ai-foundation

Enterprise Part of the commercial Kumiko Enterprise offering — not in the open framework.

Plugin host and connection store that wires an LLM (and optionally a transcription and a speech) provider to your app without coupling it to a specific vendor SDK. A tenant keeps its AI connections here (anthropic, openai, openai-compatible; the API key is a write-only, encrypted field) and assigns them to jobs in the standard models (text, images, dictation, read-aloud). Add it when you want features like ai-patch, ai-generate, ai-triage, or ai-draft — each of those calls createLLMProviderForTenant(ctx, tenantId) from this package to resolve the provider at request time; transcription uses createTranscribeProviderForTenant, read-aloud createSpeechProviderForTenant. A SystemAdmin can provide platform connections (one key per vendor) that every tenant may pick. Adapters (ai-provider-anthropic, ai-provider-openai-compat) only build the provider; credentials and endpoints are resolved here.

Build it yourself

This Enterprise implementation is optional. If you need a narrower or domain-specific version, you can build an app-owned feature, handler, or job with Kumiko’s public extension points.

Use this package when you want the maintained implementation, its existing contracts, and the surrounding operational behavior. A custom implementation is not drop-in compatible automatically: your app owns its authorization, validation, integrations, tests, security review, and production operations.

Start with Features and composition and Custom write handlers.

How it fits

What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).

flowchart TB
  n_ai_foundation["ai-foundation"]
  subgraph how_reqs["Requires"]
    n_config["config"]
  end
  subgraph how_provides["Provides"]
    n_cmd_ai_foundation_write_ai_connection_create(["create"])
    n_cmd_ai_foundation_write_ai_connection_delete(["delete"])
    n_cmd_ai_foundation_write_ai_connection_update(["update"])
    n_cmd_ai_foundation_write_refresh_models(["refresh-models"])
  end
  n_config --> n_ai_foundation
  n_ai_foundation --> n_cmd_ai_foundation_write_ai_connection_create
  n_ai_foundation --> n_cmd_ai_foundation_write_ai_connection_delete
  n_ai_foundation --> n_cmd_ai_foundation_write_ai_connection_update
  n_ai_foundation --> n_cmd_ai_foundation_write_refresh_models

Provides — write commands this feature registers (dispatch them through the command bus):

ai-foundation:write:ai-connection:create
ai-foundation:write:ai-connection:delete
ai-foundation:write:ai-connection:update
ai-foundation:write:refresh-models

Dependencies

Requires: config
Activation: always on (not toggleable)

Configuration

Per-tenant config keys, set via the tenant-admin UI or a seed. 🔒 = encrypted at rest.

Key	Type	Default	Scope	Who can write	Who can read
`default-effort`	select (low \| medium \| high \| xhigh \| max)	`high`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`all`
`default-max-tokens`	number (256–200000)	`16000`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`all`
`image-connection`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`image-model`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`migrated-legacy-connections`	text	`""`	tenant	`system`, `SystemAdmin`	`system`, `SystemAdmin`
`monthly-transcription-seconds`	number (≥ 1)	—	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`all`
`platform-anthropic-api-key`	text	—	system 🔒	`system`, `SystemAdmin`	`SystemAdmin`
`platform-anthropic-endpoint`	text	`""`	system	`system`, `SystemAdmin`	`SystemAdmin`
`platform-openai-compat-api-key`	text	—	system 🔒	`system`, `SystemAdmin`	`SystemAdmin`
`platform-openai-compat-endpoint`	text	`""`	system	`system`, `SystemAdmin`	`SystemAdmin`
`platform-openrouter-api-key`	text	—	system 🔒	`system`, `SystemAdmin`	`SystemAdmin`
`platform-openrouter-endpoint`	text	`""`	system	`system`, `SystemAdmin`	`SystemAdmin`
`speech-connection`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`speech-model`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`speech-voice`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`text-connection`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`text-model`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`transcription-connection`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`
`transcription-model`	text	`""`	tenant	`system`, `TenantAdmin`, `SystemAdmin`	`TenantAdmin`, `SystemAdmin`, `User`