AI provider matrix
Kumiko resolves the AI provider per tenant. The application features use the provider contract; they do not need to know which vendor handles a request.
Provider choices
Section titled “Provider choices”| Provider | Capabilities | Best fit | Network and key behavior |
|---|---|---|---|
| Anthropic | Text | Claude production workloads | Anthropic API with a tenant-scoped API key |
| OpenAI-compatible | Text, transcription, read-aloud | OpenAI, OpenRouter, Azure, Groq, Ollama, vLLM, llama.cpp, or another compatible endpoint | A connection of kind openai or openai-compatible with its own address (including /v1) and API key; local endpoints can run without a hosted API key |
| Mock | Text | Tests, demos, and deterministic integration coverage | Scripted responses; not a production model |
A tenant keeps its providers as connections (AI providers screen, entity
ai-connection). Each connection has a kind (anthropic, openai or
openai-compatible), an address for compatible servers and its own write-only API
key. OpenRouter is an openai-compatible connection; there is no separate
OpenRouter package. The Standard models screen assigns a connection and a model
to each job: text, images, transcription and read-aloud. A tenant can therefore run
text on an Anthropic connection and voice on an OpenAI-compatible one.
The address must be a full http or https URL without a query string, a
fragment or credentials. Tenant users can see the address, so an address like
https://user:pass@host would leak a secret. Saving such an address fails
with ai_foundation.connection_endpoint_invalid, both on a tenant connection
and on the platform endpoint in the system config. A platform endpoint that
still holds such an address, for example from a boot seed, is checked again on
every read: the platform connection then counts as not configured and the
server logs a warning. Put the key in the connection’s API key field.
Choosing a deployment shape
Section titled “Choosing a deployment shape”- Use a hosted provider when you want the shortest path to production.
- Use OpenAI-compatible routing when you need to switch vendors or point at a local model without changing application features.
- Use a local endpoint when prompts and inputs must stay inside your network.
- Use the mock provider in every integration test that does not need a real vendor response.
Provider selection does not replace data classification. Decide which tenants may send which fields to which endpoint, then enforce that choice in tenant configuration, secrets, and application policy.
EU only and zero data retention
Section titled “EU only and zero data retention”For OpenRouter connections, ai-foundation can pin the data-handling policy.
providerRoutingon a connection holds OpenRouter’sproviderobject (zdr,data_collection,allow_fallbacks,order,only). It is sent with chat requests, and only toopenrouter.aiand its subdomains over https.- A connection marked
requireEuZdr(“EU only, zero data retention”) must beopenai-compatibleand sit on an allowed EU origin, by defaulthttps://eu.openrouter.ai. It always sendszdr: trueanddata_collection: "deny", whateverproviderRoutingsays. createAiFoundationFeature({ enforceEuZdr: true })applies the same policy to every connection of the installation, platform and BYOK connections included.euZdrEndpointsreplaces the list of allowed origins.
The policy fails closed. A connection outside the allowed endpoints is refused on
save and on every resolve. A request path that cannot carry the routing is refused
with ai_foundation.connection_eu_zdr_request_not_routable. The query
ai-foundation:query:connection-data-policy returns a connection’s effective routing
for feature gates. The edit form does not expose providerRouting; set it through the
connection write handlers.
Build your own provider
Section titled “Build your own provider”The provider packages are adapters. An application can build its own adapter
against the public ai-foundation extension point for another vendor, an
internal gateway, or a rules engine. The custom adapter owns request mapping,
timeouts, retries, error classification, secret handling, and tests.