42 lines
2.5 KiB
Markdown
42 lines
2.5 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` and `baseUrlConfigured` only; it does not expose the stored secret reference or provider endpoint.
|
|
- `AIProviderTestResponse`: local metadata validation result with `mode=metadata`; live external connectivity is deferred.
|
|
- `AIProviderModelsResponse`: configured model list and default model, without credentials.
|
|
|
|
Management endpoints reject raw key-shaped values in `apiKeyRef`. In `live` mode Platform resolves `env://NAME` or `secret://providers/<id>` inside the service boundary and invokes OpenAI-compatible, OpenAI, Claude, Gemini, Ollama, or custom HTTP providers with bounded requests. Local debug uses explicit `mock` mode.
|
|
|
|
Provider failures return a stable safe error without URL, header, key, request-body secret, or stack details. A config suggestion response includes the proposed content plus `configExecution` metadata for the bounded `config.write` job that Platform dispatches immediately after the current config version/checksum, permissions, runtime binding, and content-safety checks pass. The response contains the job ID and target key so the caller can follow execution logs without receiving provider credentials.
|