Module ai 

The ai: configuration block (DW-075): AI provider adapters.

This is the source shape only — the runtime translation lives in the AI domain one level up (see the ai module’s AiRuntime), which consumes these types at compile time. The block is ADDITIVE to the gateway schema: absent (the default), the gateway has no AI surface at all; present, it declares the provider pool (providers:) and the model alias table (models:) that map an OpenAI-shaped client request onto a concrete provider call.

Design notes (DW-075):

• A provider names an UPSTREAM (upstreams: entry), not a raw base URL: the provider’s transport — endpoint set, TLS trust, connection pooling, timeouts, breaker, passive health — is the SAME machinery every other upstream gets, and the adapter layer stays pure request/response translation with no HTTP client of its own. A multi-region provider pool is then just an upstream with several endpoints.
• Authentication is a verbatim header (auth.header + auth.value) rather than a per-provider auth enum: providers disagree on the convention (OpenAI wants Authorization: Bearer ..., Anthropic x-api-key: ..., Gemini x-goog-api-key: ...), and a verbatim pair expresses all of them without the schema growing a variant per provider. value is secret-bearing: inline values are redacted in every config echo (DW-045) and ${...} references resolve at config-compile time, failing the generation closed when unresolvable.
• models: is a map from the MODEL ALIAS the client names in the request body to the provider that serves it plus the provider’s own model identifier. The alias is what the gateway echoes back in the response; the provider model never leaks to the client.

Structs

A2aAgent

One A2A agent (DW-114 ai.a2a.agents[]). The gateway routes a chat request to the agent by translating it into an A2A task-submit body and placing the call through the named upstream. The Agent Card (discovery doc) declares the agent’s capabilities and authentication; it is parsed at compile time.

A2aAgentCard

The Agent Card source (DW-114): a file path or an inline JSON object. One of the two is required when card is present.

A2aConfig

A2A (agent-to-agent) protocol config (DW-114 ai.a2a). Declares the remote A2A agents the gateway can route chat requests to and the session policy for agent-to-agent task sessions. The block is ADDITIVE: absent (the default), the gateway has no A2A surface. Compiled into every build (no cargo feature).

A2aSessions

A2A session policy (DW-114 ai.a2a.sessions), mirroring MCP.

AiAbTest

One A/B test (DW-086 ai.experiments.ab_tests.<name>): two or more variants, each naming a model alias, an optional prompt version, and a weight. A model alias declares ab_test: <name> to be served by one; the test is evaluated per request (a deterministic weighted pick by request id selects a variant).

AiAbVariant

One variant of an A/B test (DW-086 ai.experiments.ab_tests.<name>.variants[]).

AiCanaryVersion

One weighted version of a canary split (DW-076 ai.models.<alias>.canary[]).

AiConfig

The ai: top-level block (DW-075). Absent: no AI surface. Present: validation requires at least one provider and at least one model — an ai: block that can never serve a model is an authoring error, not a silently inert config.

AiCredentialPool

DW-080 (Ent): a credential pool for a provider — multiple API keys rotated across to aggregate rate-limit headroom. Each entry is an AiProviderAuth (same header+value shape as the singular auth field). The pool is used INSTEAD of auth; validation rejects a provider that sets both.

AiEval

One regression eval (DW-086 ai.experiments.evals.<name>): a golden set of input/expected cases plus an optional prompt version. The admin API runs it against a model alias (or an A/B test’s variants) and stores the results in analytics.

AiEvalCase

One eval case (DW-086 ai.experiments.evals.<name>.golden_set[]).

AiExperiments

Prompt experimentation (DW-086 ai.experiments): prompt versioning, A/B model comparison, regression evals, and feedback ingestion. Absent (the default): no experiments surface.

AiFallbackChainPolicy

A fallback-chain routing policy (DW-085 kind: fallback_chain): cheap-model-first with complexity-signal escalation. The cheap and escalate_to fields name OTHER model aliases (plain chain/canary aliases — a policy composes over DW-076 routing, so it has no provider/model pair of its own).

AiFeedbackConfig

Feedback ingestion config (DW-086 ai.experiments.feedback).

AiGovernance

Model governance (DW-084 ai.governance): per-team model allowlists plus a shadow-audit switch. A team is a POLICY name (the same vocabulary the token budgets use for scope: policy): every consumer attaching a policy with an allowlist entry is restricted to that allowlist’s aliases. The check runs BEFORE routing, against the client-facing alias (the model value in the request body), so a typo or a renamed alias is blocked at the edge rather than surfacing as a provider 404. Multiple policies with allowlists that bind one request intersect (deny-wins): the model must be in EVERY binding allowlist, matching the authz deny-anywhere-wins principle. Consumers with no binding allowlist policy are unrestricted (fail-open, the DW-017 default posture). audit: true records BOTH allowed and denied attempts into the ai_governance_events analytics table for shadow review.

AiGuardrailRule

One guardrail rule (DW-082 ai.guardrails.rules[]). A rule declares a kind (what to check), an action (what to do on a match), a phase (prompt, response, or both), the patterns or schema to check against, and the policies it attaches to.

AiGuardrails

Guardrails (DW-082 ai.guardrails): a list of rules that inspect prompts and responses for prompt-injection, PII, banned content, and output schema conformance. Each rule is one check applied at the prompt phase (before the provider call) and/or the response phase (after). Policy-scoped rules apply only to consumers attaching a listed policy; an empty policies list applies to all. See AiGuardrailRule for the per-rule shape.

AiLatencyCostCandidate

One candidate in a latency-vs-cost policy (DW-085 ai.routing_policies.<name>.candidates[]).

AiLatencyCostPolicy

A latency-vs-cost routing policy (DW-085 kind: latency_cost): static config-based selection. The operator declares cost/latency scores per candidate and a preference; the policy sorts candidates at compile time and picks the best one deterministically (no runtime metrics needed).

AiLogging

Prompt/response logging (DW-081 ai.logging): opt-in capture of the canonical prompt and response with PII redaction, sampling, and retention. Capture is OFF by default (privacy-first): the enabled field defaults to false, so an ai.logging block without enabled: true captures nothing. When on, a redaction pass scrubs PII/secrets before storage, sample_rate controls volume, and retention_secs ages records out. Per-consumer ai_logging overrides respect tenant preference.

AiLoggingExternalSink

SCALE-12 (#190): external sink configuration for prompt/response logs. The sync command is invoked by the analytics maintenance tick with the export directory as its first argument. Failures are logged and silently ignored (best-effort sync).

AiMcpConfig

MCP gateway config (DW-087 ai.mcp): the tool table, session policy, and reserved path. Tools are configured with upstream references; the gateway proxies tool calls to upstream HTTP endpoints (POST JSON body, get JSON response). The gateway is a router, not a tool executor.

AiMcpPrompt

AI-11 (#200): One MCP static prompt template (ai.mcp.prompts.<name>). Prompts are served inline. The template body is returned in prompts/get responses, with optional argument substitution.

AiMcpPromptArgument

AI-11 (#200): One prompt argument definition.

AiMcpResource

AI-11 (#200): One MCP static resource (ai.mcp.resources.<name>). Resources are served inline (no upstream proxy). The content is returned verbatim in resources/read responses.

AiMcpSessions

MCP session policy (DW-087 ai.mcp.sessions).

AiMcpTool

One MCP tool (DW-087 ai.mcp.tools.<name>). The gateway proxies tool calls to the named upstream’s HTTP endpoint: the tool’s arguments are sent as the JSON request body, and the upstream’s response body becomes the tool’s output.

AiModel

One model alias mapping (DW-075 ai.models{alias}).

AiModelTarget

One provider/model pair an alias can route to (DW-076): the primary shape reused by failover entries and canary versions.

AiPricing

Per-model token pricing (DW-079 ai.pricing.<provider_model>). Costs are integer MICRO-USD per 1 000 tokens (1 000 000 micro-USD = $1.00 — no floating-point money). The key in the parent map is the PROVIDER MODEL identifier (the actual model the provider charges for), not the client-facing alias. Spend is computed as input_tokens * input_per_1k_micros / 1000 + output_tokens * output_per_1k_micros / 1000 (integer micro-USD, saturating).

AiPromptVersion

One prompt version (DW-086 ai.experiments.prompts.<name>.versions.<version>): a system message prepended to the request’s messages when this version is active.

AiPromptVersions

One prompt’s version set (DW-086 ai.experiments.prompts.<name>): a map of version names to system messages plus the active version. The active version can be overridden at runtime via the admin API.

AiProvider

One AI provider (DW-075 ai.providers[]).

AiProviderAuth

Verbatim authentication header for a provider (DW-075 ai.providers[].auth). value is SECRET-BEARING: an inline value is replaced by the redaction placeholder in every config echo, and a ${...} reference is resolved at config-compile time (DW-045).

RedactionConfig

PII redaction configuration (DW-081 ai.logging.redaction). Built-in patterns scrub common PII/secrets; custom patterns add deployment-specific scrubbing. All patterns are compiled into a single regex::RegexSet for one-pass efficiency.

SemanticCacheConfig

Semantic cache config (DW-083 ai.semantic_cache): an embedding-similarity cache for AI prompts. A paraphrased prompt within the cosine-similarity threshold returns the cached response with no provider call and no token spend. Uses an external embedding service (OpenAI-compatible /v1/embeddings API) to vectorize prompts and hnsw_rs (pure Rust HNSW) for approximate nearest neighbor search. Compiled into every build (hnsw_rs is an unconditional dependency).

Enums

AiGuardrailAction

Guardrail action (DW-082 ai.guardrails.rules[].action).

AiGuardrailKind

Guardrail kind (DW-082 ai.guardrails.rules[].kind).

AiGuardrailPhase

Guardrail phase (DW-082 ai.guardrails.rules[].phase).

AiLatencyPreference

The latency-vs-cost selection preference (DW-085 ai.routing_policies.<name>.preference).

AiPoolStrategy

Credential pool rotation strategy (DW-080).

AiProviderKind

The wire protocol an adapter speaks (DW-075).

AiRoutingPolicy

A routing policy (DW-085 ai.routing_policies.<name>): within-request escalation or latency-vs-cost selection. Keyed by name in ai.routing_policies. An alias declares routing_policy: <name> to be served by one; the policy is evaluated per request and composes over DW-076 routing (the candidate aliases it names are themselves plain chain/canary aliases). Internally tagged by kind so the YAML shape is:

UnknownModelPolicy

The unknown-model pricing policy (DW-AI-03 ai.unknown_model_policy): what the gateway does when a provider model has no entry in the ai.pricing table. The default (allow) preserves the original fail-open behavior (cost 0, never a crash); fail_closed rejects the response with 403 ai_unknown_model_pricing so an unpriced model cannot serve traffic silently; alert proceeds with cost 0 but logs a WARN and increments dwara_ai_unknown_pricing_total{model} for observability without blocking the call.