# 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.