> ## Documentation Index
> Fetch the complete documentation index at: https://docs.findmydata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR 0005 ai provider gateway

# ADR-0005: AI provider gateway — deterministic mock first-class

**Status:** Accepted · 2026-07-14

## Decision

All model calls go through `AiGateway` with typed task-level requests
(`generateTaxonomyDraft`, `classifyCandidate`, `planAnalystQuery`, …), never raw
prompt passthrough from callers. Providers:

* **MockProvider (default):** deterministic, seeded by request content hash;
  produces schema-valid outputs from fixture templates. The only provider used by
  tests; requires no credentials.
* **AzureOpenAIProvider:** first-class adapter (endpoint/deployment/api-version from
  config; key or managed-identity reference). Config-gated.
* **AnthropicProvider:** adapter implementing the same contract via the Messages
  API. Config-gated.

Gateway responsibilities (provider-independent): prompt/template registry with
versions, Zod validation of structured outputs with bounded retry, token/cost/latency
budgets, redaction policy before egress, untrusted-content delimiting, per-tenant
provider allowlist, and audit metadata (task, template version, provider, model,
duration, token counts — never raw prompt bodies in default logs).

**No silent cross-provider fallback:** if a configured provider fails, the task
degrades to an explicit `provider_unavailable` state, never to a differently
governed provider.

## Consequences

* Every AI answer records `(provider, model, templateVersion)` for provenance.
* Adding a provider is one adapter file + registry entry + contract tests.