40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
# AI Provider Contracts
|
|
|
|
AI providers are platform-managed model endpoints used by plugins through scoped platform capabilities.
|
|
|
|
## AIProviderConfig
|
|
|
|
- `id`: provider ID.
|
|
- `name`: display name.
|
|
- `kind`: provider kind.
|
|
- `baseUrl`: base URL or relay URL.
|
|
- `apiKeyRef`: secret reference.
|
|
- `models`: allowed model list.
|
|
- `defaultModel`: default model.
|
|
- `relayMode`: direct, relay, or local.
|
|
- `timeoutMs`: timeout.
|
|
- `status`: active, disabled, or error.
|
|
- `redactionPolicy`: redaction policy key.
|
|
|
|
## AIInvocationRequest
|
|
|
|
- `providerId`: selected provider.
|
|
- `purpose`: scoped purpose such as `config.suggest` or `logs.diagnose`.
|
|
- `serverInstanceId`: optional server context.
|
|
- `pluginId`: caller plugin.
|
|
- `inputRef`: artifact or bounded structured input.
|
|
- `model`: optional model override.
|
|
|
|
AI invocation responses must be bounded and must not include raw provider credentials. Config write suggestions must be presented as a diff or recommendation before dispatching run jobs.
|
|
|
|
## Management API Contracts
|
|
|
|
- `AIProviderCreateRequest`: create provider metadata with `apiKeyRef`, never raw key material.
|
|
- `AIProviderUpdateRequest`: replace editable provider metadata while preserving status through the service layer.
|
|
- `AIProviderStatusRequest`: set provider status to `active` or `disabled`.
|
|
- `AIProviderResponse`: redacted provider response with `apiKeyConfigured` only; it does not expose the stored secret reference.
|
|
- `AIProviderTestResponse`: local metadata validation result with `mode=metadata`; live external connectivity is deferred.
|
|
- `AIProviderModelsResponse`: configured model list and default model, without credentials.
|
|
|
|
Management endpoints must reject raw key-shaped values in `apiKeyRef`. Platform-mediated AI invocation is implemented through the platform service boundary; live external connectivity tests and remote model discovery are deferred to later changes.
|