Skip to main content

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