dwara_core/config/

ai.rs

//! 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.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

/// Serde skip helper: elide `audit` when false (the default).
fn is_false(b: &bool) -> bool {
    !*b
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiConfig {
    /// The provider pool. Each entry names an upstream that carries the
    /// transport and the adapter `kind` that carries the wire translation.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub providers: Vec<AiProvider>,
    /// Model alias table: the `model` value a client puts in its request
    /// body maps to the provider that serves it and the provider's own
    /// model identifier. The alias is echoed back to the client; the
    /// `provider_model` never leaves the gateway.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub models: BTreeMap<String, AiModel>,
    /// Per-model pricing table (DW-079): the key is the PROVIDER MODEL
    /// identifier (the actual model the provider charges for, e.g.
    /// `gpt-4o-mini`), NOT the client-facing alias. Costs are integer
    /// micro-USD per 1 000 tokens (1 000 000 micro-USD = $1.00 — no
    /// floating-point money). Spend = usage x price, aggregated per
    /// key/team/model (DW-079). Absent (the default): no pricing, so
    /// cost attribution records zero cost (the budget cost window and
    /// the spend store stay live but inert until prices are declared).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub pricing: BTreeMap<String, AiPricing>,
    /// Model governance (DW-084): per-team (policy) model allowlists
    /// and the shadow-audit switch. Absent (the default): no
    /// governance — every consumer may call every configured alias,
    /// and no governance audit events are recorded.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub governance: Option<AiGovernance>,
    /// Prompt/response logging (DW-081): opt-in capture of the
    /// canonical prompt and response with PII redaction, sampling,
    /// and retention. Absent (the default): no capture — privacy-first
    /// (no prompt or response text is ever stored). When present and
    /// `enabled: true`, 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 (see [`crate::config::Consumer::ai_logging`]).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub logging: Option<AiLogging>,
    /// Guardrails (DW-082): prompt-injection heuristics, PII
    /// detection, banned-content filters, and output schema
    /// enforcement as a middleware chain on the AI proxy action.
    /// Absent (the default): no guardrails — every prompt and
    /// response passes through uninspected. When present, each rule
    /// inspects the prompt (before the provider call) and/or the
    /// response (after), and blocks, redacts, or logs per its
    /// `action`. Policy-scoped rules apply only to consumers
    /// attaching a listed policy; an empty `policies` list applies
    /// to all. Schema enforcement uses the unconditional `jsonschema`
    /// dependency and works in every build.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub guardrails: Option<AiGuardrails>,
    /// Semantic cache (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) and a pure-Rust HNSW ANN index
    /// (`hnsw_rs`). Feature-gated behind the `semantic_cache` cargo
    /// feature; without it the config is accepted but the cache is a
    /// no-op. Absent (the default): no semantic cache.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub semantic_cache: Option<SemanticCacheConfig>,
    /// Routing policies (DW-085 `ai.routing_policies`): named
    /// within-request escalation or latency-vs-cost selection plans,
    /// keyed by name. A model alias declares `routing_policy: <name>`
    /// to be served by one; the policy is evaluated per request (a
    /// FallbackChain policy may call an external classifier service;
    /// a LatencyCost policy picks deterministically at compile time).
    /// Absent (the default): no routing policies.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub routing_policies: BTreeMap<String, AiRoutingPolicy>,
    /// Prompt experimentation (DW-086 `ai.experiments`): prompt
    /// versioning, A/B model comparison, regression evals, and
    /// feedback ingestion. Absent (the default): no experiments.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub experiments: Option<AiExperiments>,
    /// MCP gateway (DW-087 `ai.mcp`): turns dwara into an MCP
    /// (Model Context Protocol) server/router. Configured tools are
    /// exposed over JSON-RPC 2.0 on a reserved HTTP path (default
    /// `/mcp`); the gateway proxies tool calls to upstream HTTP
    /// endpoints with authN/authZ, manages agent sessions in the
    /// state store, and correlates tool calls in analytics. Absent
    /// (the default): no MCP surface (the `/mcp` path returns 404).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mcp: Option<AiMcpConfig>,
    /// A2A (agent-to-agent) protocol support (DW-114 `ai.a2a`):
    /// configures remote A2A agents that the gateway can route chat
    /// requests to. Each agent names an upstream (the transport) and
    /// an Agent Card (discovery doc, file path or inline JSON). The
    /// adapter translates a canonical chat request into an A2A
    /// task-submit body; the task lifecycle is STUBBED pending spec
    /// freeze. Compiled into every build (no cargo feature). Absent
    /// (the default): no A2A surface.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub a2a: Option<A2aConfig>,
    /// Unknown-model pricing policy (DW-AI-03
    /// `ai.unknown_model_policy`): what to do when a provider model
    /// has no entry in `ai.pricing`. Absent (the default): `allow`
    /// (cost 0, fail-open — the original behavior). `fail_closed`
    /// rejects the response with 403 `ai_unknown_model_pricing`;
    /// `alert` proceeds with cost 0 but logs a WARN and increments
    /// the `dwara_ai_unknown_pricing_total{model}` metric.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub unknown_model_policy: Option<UnknownModelPolicy>,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiGovernance {
    /// Per-policy (team) model allowlists. The key is the POLICY name
    /// (the team), the value is the list of allowed client-facing
    /// model aliases. A consumer attaching a policy listed here may
    /// only call the aliases in its allowlist; a consumer attaching
    /// no listed policy is unrestricted. Validation rejects an
    /// allowlist entry that names an alias absent from `ai.models`
    /// (an authoring error, not a runtime 404).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub team_allowlists: BTreeMap<String, Vec<String>>,
    /// When true, record model usage for shadow audit: BOTH allowed
    /// calls and denied attempts land in the `ai_governance_events`
    /// analytics table (the admin `/analytics/governance-audit`
    /// endpoint reads it). When false (the default), only the
    /// denial metric fires — no per-event audit rows are written.
    #[serde(default, skip_serializing_if = "is_false")]
    pub audit: bool,
    /// SEC-14 / CFG-14: dry-run mode. When true, the governance engine
    /// evaluates the team allowlist and records would-be denials
    /// (`dwara_policy_dry_run_total{phase="ai_governance"}` + a
    /// structured log) but does NOT reject the request — the call
    /// proceeds to the model. Useful for rolling out a new allowlist
    /// without breaking existing callers. Default false (reject on
    /// mismatch).
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
}

/// One AI provider (DW-075 `ai.providers[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiProvider {
    /// Provider name; unique within the `ai:` block. Referenced by
    /// `ai.models[].provider`.
    pub name: String,
    /// Wire-protocol adapter kind. Selects the request/response
    /// translation applied to every call routed to this provider.
    pub kind: AiProviderKind,
    /// Name of the `upstreams:` entry that carries this provider's
    /// transport (endpoints, TLS trust, pooling, timeouts, breaker).
    /// The adapter builds provider-specific paths; the endpoint's
    /// authority becomes the dialed host, exactly like a proxy route.
    pub upstream: String,
    /// Authentication attached to every call to this provider: a
    /// verbatim header. Optional — a provider behind an internal network
    /// (a self-hosted gateway fronting an Ollama-style endpoint, for
    /// example) may need none.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub auth: Option<AiProviderAuth>,
    /// Full request path override for this provider. When set, the
    /// transport uses this path verbatim instead of the adapter's
    /// built-in path. This bridges providers whose API path differs
    /// from the adapter's default (e.g. z.ai's coding-plan endpoint
    /// `/api/coding/paas/v4/chat/completions` vs the OpenAI adapter's
    /// `/v1/chat/completions`) without an external reverse proxy.
    /// When unset, the adapter's per-kind default path is used.
    /// Applies to both adapter-translated and passthrough requests.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// DW-080 (Ent): a credential pool for this provider. When set,
    /// the gateway rotates across multiple API keys to aggregate
    /// rate-limit headroom (the LiteLLM pattern). Each entry is an
    /// `AiProviderAuth` (same shape as `auth`); the pool is used
    /// INSTEAD of `auth` — validation rejects a provider that sets
    /// both. At request time the pool picks one credential per
    /// request (round-robin by default); when a key returns 429, it
    /// is temporarily quarantined and subsequent requests rotate to
    /// the next. Pool exhaustion (all keys quarantined) degrades
    /// gracefully with a 429 + Retry-After, not a panic. Ent-only:
    /// rejected at validation when the `ent` cargo feature is off.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub credential_pool: Option<AiCredentialPool>,
}

/// The wire protocol an adapter speaks (DW-075).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiProviderKind {
    /// OpenAI chat-completions API (`POST /v1/chat/completions`). Also
    /// the dialect spoken by OpenAI-compatible servers (vLLM, Ollama's
    /// compatibility endpoint, Groq, DeepSeek, Mistral, Cohere, and
    /// others) — point the upstream at one of those and this adapter
    /// speaks to it unchanged (AI-01).
    Openai,
    /// Anthropic messages API (`POST /v1/messages`).
    Anthropic,
    /// Google Gemini `generateContent` API
    /// (`POST /v1beta/models/{model}:generateContent`).
    Gemini,
    /// DW-114: A2A (agent-to-agent) protocol. An A2A provider is a
    /// configured `ai.a2a.agents[]` entry: the adapter translates a
    /// canonical chat request into an A2A task-submit body and parses
    /// the task response back. The task lifecycle state machine is
    /// implemented against the A2A Protocol Specification draft (legal
    /// and illegal transitions are enforced). Compiled into every
    /// build (no cargo feature).
    A2a,
    /// AI-01: Azure OpenAI. Uses the Azure deployment URL format
    /// (`/openai/deployments/{deployment}/chat/completions?api-version=...`)
    /// and `api-key` header authentication. The request/response body
    /// is OpenAI-compatible (the adapter reuses the OpenAI body
    /// translation and overrides the path + headers).
    AzureOpenai,
    /// AI-01: AWS Bedrock. Uses the Bedrock invoke API
    /// (`/model/{model_id}/invoke`) with AWS SigV4 request signing.
    /// The request/response body follows the Anthropic messages format
    /// for Claude models on Bedrock (the adapter reuses the Anthropic
    /// body translation and overrides the path + headers). SigV4
    /// signing is applied by the transport layer using the provider's
    /// configured AWS credentials.
    Bedrock,
}

impl AiProviderKind {
    /// The OTel GenAI semantic-convention `gen_ai.system` value
    /// (AI-07): the lowercase provider kind token. Used as the
    /// `gen_ai.system` span attribute and never a metric label by
    /// itself (the config-bounded provider NAME is the label).
    pub fn gen_ai_system(&self) -> &'static str {
        match self {
            AiProviderKind::Openai => "openai",
            AiProviderKind::Anthropic => "anthropic",
            AiProviderKind::Gemini => "gemini",
            AiProviderKind::A2a => "a2a",
            AiProviderKind::AzureOpenai => "azure_openai",
            AiProviderKind::Bedrock => "aws_bedrock",
        }
    }
}

/// 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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiProviderAuth {
    /// Header name (e.g. `Authorization`, `x-api-key`,
    /// `x-goog-api-key`). Must be a valid HTTP header name.
    pub header: String,
    /// Header value, verbatim (e.g. `Bearer ${OPENAI_API_KEY}` —
    /// reference resolution covers the whole value, so the `Bearer `
    /// prefix belongs INSIDE the referenced variable or the literal).
    /// Inline values are redacted in config echoes; never logged.
    pub value: String,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiCredentialPool {
    /// One or more credential entries. Each entry has the same shape
    /// as `ai.providers[].auth` (a header name + secret-bearing value).
    /// At least two entries are required (a single-entry pool is
    /// equivalent to `auth` — validation rejects it).
    pub credentials: Vec<AiProviderAuth>,
    /// Rotation strategy (DW-080). `round_robin` (the default) cycles
    /// through credentials in config order; `weighted` picks
    /// proportionally to each entry's `weight` (deterministic per
    /// request id, same as canary splits). When a credential is
    /// quarantined (429 from the provider), the pool skips it and
    /// picks the next available one.
    #[serde(default, skip_serializing_if = "is_default_pool_strategy")]
    pub strategy: AiPoolStrategy,
    /// Quarantine duration in seconds for a credential that received a
    /// 429 from the provider. During quarantine, the pool skips the
    /// credential; after the window expires, it re-enters rotation.
    /// Default: 60 seconds. A provider's `Retry-After` header, when
    /// present, overrides this per-429 (capped at 600 seconds to
    /// prevent a hostile provider from pinning a key out indefinitely).
    #[serde(
        default = "default_quarantine_secs",
        skip_serializing_if = "is_default_quarantine_secs"
    )]
    pub quarantine_secs: u64,
}

/// Credential pool rotation strategy (DW-080).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "snake_case")]
pub enum AiPoolStrategy {
    /// Cycle through credentials in config order (default).
    #[default]
    RoundRobin,
    /// Pick proportionally to each entry's weight (deterministic per
    /// request id, same hash as canary splits). Weights are implicit
    /// in the entry order (equal weight); a future extension may add
    /// an explicit `weight` field per entry.
    Weighted,
}

fn is_default_pool_strategy(s: &AiPoolStrategy) -> bool {
    *s == AiPoolStrategy::RoundRobin
}

fn default_quarantine_secs() -> u64 {
    60
}

fn is_default_quarantine_secs(v: &u64) -> bool {
    *v == 60
}

/// One model alias mapping (DW-075 `ai.models{alias}`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiModel {
    /// Name of the `ai.providers[]` entry that serves this alias.
    pub provider: String,
    /// The provider's own model identifier (e.g. `gpt-4o-mini`,
    /// `claude-sonnet-4-5`, `gemini-2.5-flash`), sent to the provider
    /// in place of the alias.
    pub provider_model: String,
    /// Ordered failover chain (DW-076): when the primary target
    /// answers 429 or a 5xx, or its transport errors, the gateway
    /// retries the next entry — a DIFFERENT provider/model pair, never
    /// a re-send to the provider that just failed (its upstream's
    /// breaker owns same-provider retries). The client sees one
    /// response. Absent (the default): no failover, the primary's
    /// answer is final. Cannot be combined with `canary` on the same
    /// alias (validation rejects the pairing): failover is an
    /// availability chain for a single logical model; a canary split
    /// is deliberately serving multiple versions at once — mixing the
    /// two would retry a canary request onto the stable version and
    /// silently undo the experiment.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub failover: Vec<AiModelTarget>,
    /// Weighted canary split (DW-076): traffic for this alias
    /// distributes across the listed versions by a deterministic
    /// weighted hash of the request id (the same slot semantics as
    /// traffic splitting: ratios hold per request, and re-sending a
    /// request with the same id lands on the same version). Each
    /// version names exactly one provider/model pair and carries no
    /// failover of its own. Absent (the default): no split. Cannot be
    /// combined with `failover` on the same alias.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub canary: Vec<AiCanaryVersion>,
    /// A routing policy name (DW-085): when set, this alias is served
    /// by the named entry in `ai.routing_policies` instead of a plain
    /// failover chain or canary split. The policy is evaluated per
    /// request (a FallbackChain policy may call an external classifier
    /// service to decide cheap-vs-expensive; a LatencyCost policy
    /// picks deterministically). Cannot be combined with `failover`
    /// or `canary` on the same alias (validation enforces mutual
    /// exclusivity): a policy alias composes over OTHER aliases'
    /// routing plans, so it has no primary provider/model pair of its
    /// own.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub routing_policy: Option<String>,
    /// An A/B test name (DW-086): when set, this alias is served by
    /// the named entry in `ai.experiments.ab_tests` instead of a
    /// plain failover chain, canary split, or routing policy. The
    /// experiment is evaluated per request (a deterministic weighted
    /// pick by request id selects a variant). Cannot be combined
    /// with `failover`, `canary`, or `routing_policy` on the same
    /// alias (validation enforces mutual exclusivity): an experiment
    /// alias composes over OTHER aliases' routing plans, so it has
    /// no primary provider/model pair of its own.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ab_test: Option<String>,
    /// Auto-canary analysis (DW-091): when set, a background
    /// controller compares the canary (second version) vs the
    /// baseline (first version) on error rate or latency and adjusts
    /// the canary split weights automatically. Only valid when the
    /// canary has exactly 2 versions (baseline + canary). Weight
    /// changes are transient (Generation swap) and revert on config
    /// reload.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub canary_analysis: Option<crate::config::CanaryAnalysis>,
}

/// One provider/model pair an alias can route to (DW-076): the primary
/// shape reused by failover entries and canary versions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiModelTarget {
    /// Name of the `ai.providers[]` entry.
    pub provider: String,
    /// The provider's own model identifier.
    pub provider_model: String,
}

/// One weighted version of a canary split (DW-076
/// `ai.models.<alias>.canary[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiCanaryVersion {
    /// Version name — the analytics/metrics attribution label for
    /// requests this version served. Unique within the alias; bounded
    /// label (config entity).
    pub version: String,
    /// Relative weight (>= 1). A weight of 0 is not allowed here (the
    /// split machinery parks traffic by RE-BALANCING weights, and a
    /// zero-weight canary entry that still exists would read as
    /// coverage it does not have) — remove the entry to park it.
    pub weight: u32,
    /// Name of the `ai.providers[]` entry serving this version.
    pub provider: String,
    /// The provider's own model identifier for this version.
    pub provider_model: String,
}

/// 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).
///
/// The optional cached-token and batch-rate fields (DW-AI-03) extend
/// the table for prompt-caching and batch-API discounts. When absent,
/// the standard input/output rates apply (the fallback). Cached tokens
/// are priced at `cached_input_per_1k_micros` when present (the
/// discounted rate providers charge for prompt-cache hits); the
/// non-cached portion of the prompt is priced at the standard
/// `input_per_1k_micros`. Batch rates apply when the request is a
/// batch-API call (`batch: true` on the cost computation).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiPricing {
    /// Micro-USD per 1 000 input (prompt) tokens.
    pub input_per_1k_micros: u64,
    /// Micro-USD per 1 000 output (completion) tokens.
    pub output_per_1k_micros: u64,
    /// Micro-USD per 1 000 CACHED input (prompt-cached) tokens. When
    /// present, the `cached_tokens` portion of the prompt is priced at
    /// this discounted rate instead of `input_per_1k_micros`. Absent
    /// (the default): cached tokens are priced at the standard input
    /// rate (no separate cached tier).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cached_input_per_1k_micros: Option<u64>,
    /// Micro-USD per 1 000 input tokens under the batch API. When
    /// present and the request is a batch call, this rate replaces
    /// `input_per_1k_micros`. Absent (the default): batch calls fall
    /// back to the standard input rate.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub batch_input_per_1k_micros: Option<u64>,
    /// Micro-USD per 1 000 output tokens under the batch API. When
    /// present and the request is a batch call, this rate replaces
    /// `output_per_1k_micros`. Absent (the default): batch calls fall
    /// back to the standard output rate.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub batch_output_per_1k_micros: Option<u64>,
}

/// 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.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "snake_case")]
pub enum UnknownModelPolicy {
    /// Proceed with cost 0 (the original fail-open behavior). A
    /// misconfigured price table must not 500 a request.
    #[default]
    Allow,
    /// Reject the response with 403 `ai_unknown_model_pricing` when the
    /// model has no pricing entry. The provider call has already been
    /// made (cost is computed from the response usage), but the
    /// response is not returned to the client — the unpriced model
    /// cannot serve traffic silently.
    FailClosed,
    /// Proceed with cost 0 but log a WARN and increment the
    /// `dwara_ai_unknown_pricing_total{model}` metric. The call
    /// succeeds; the metric and log surface the gap for operators.
    Alert,
}

/// Default sampling rate: capture all when enabled (1.0).
fn default_sample_rate() -> f64 {
    1.0
}

/// Default retention: 7 days in seconds (604800).
fn default_retention_secs() -> u64 {
    604_800
}

/// Default redaction replacement string.
fn default_replacement() -> String {
    "[REDACTED]".to_string()
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiLogging {
    /// Master switch. Default false (privacy-first): no prompt or
    /// response text is stored unless this is explicitly true.
    #[serde(default)]
    pub enabled: bool,
    /// Sampling rate 0.0..=1.0. Default 1.0 (capture all when
    /// enabled). The sample decision is deterministic per request
    /// (a hash of the request id), so a re-send with the same id
    /// lands on the same decision.
    #[serde(default = "default_sample_rate")]
    pub sample_rate: f64,
    /// Retention in seconds. Records older than this are deleted by
    /// the analytics maintenance tick. Default 7 days (604800).
    #[serde(default = "default_retention_secs")]
    pub retention_secs: u64,
    /// PII redaction patterns. Built-in defaults (emails, phone
    /// numbers, API keys, credit card numbers) are always active
    /// when redaction is on; custom patterns are added to the set.
    #[serde(default)]
    pub redaction: RedactionConfig,
    /// SCALE-12 (#190): external sink for prompt/response logs. When
    /// configured, the analytics maintenance tick invokes the
    /// specified command to sync exported prompt log files to an
    /// external storage system (S3, GCS, etc.). The command receives
    /// the export directory as its first argument. This is a
    /// lean-dependency alternative to embedding S3/GCS SDKs — the
    /// operator provides the sync tool (e.g., `aws s3 sync`, `gsutil
    /// rsync`). The sink has its own retention (`retention_secs`
    /// above); the local store prunes on its schedule, the external
    /// sink prunes on the operator's policy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub external_sink: Option<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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiLoggingExternalSink {
    /// The command to invoke for syncing prompt log files to external
    /// storage. The export directory path is passed as the first
    /// argument. Example: `aws s3 sync` or `gsutil rsync -r`.
    pub sync_command: String,
    /// Optional additional arguments to pass to the sync command
    /// (after the export directory path).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub extra_args: Vec<String>,
    /// How often to invoke the sync command, in seconds. Default
    /// 3600 (1 hour). Minimum 60.
    #[serde(default = "default_sync_interval_secs")]
    pub sync_interval_secs: u64,
}

fn default_sync_interval_secs() -> u64 {
    3600
}

/// 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.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RedactionConfig {
    /// Additional regex patterns to scrub (beyond the built-in
    /// defaults). Each is a Rust `regex` crate pattern; invalid
    /// patterns fail validation at publish time.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub patterns: Vec<String>,
    /// Replacement string for redacted content. Default
    /// `"[REDACTED]"`.
    #[serde(default = "default_replacement")]
    pub replacement: String,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiGuardrails {
    /// Guardrail rules. Each rule is one check applied to prompts
    /// and/or responses, in declaration order. Rule names must be
    /// unique (validation rejects duplicates).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub rules: Vec<AiGuardrailRule>,
    /// SEC-14 / CFG-14: dry-run mode. When true, guardrail rules are
    /// evaluated and would-be blocks are recorded
    /// (`dwara_policy_dry_run_total{phase="ai_guardrails"}` + a
    /// structured log) but the request/response is NOT blocked — the
    /// call proceeds. Useful for tuning guardrail patterns before
    /// enforcing. Default false (block on match).
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiGuardrailRule {
    /// Rule name (for logging/metrics attribution). Must be unique
    /// within the guardrails block (validation rejects duplicates).
    pub name: String,
    /// Guardrail kind: what the rule checks.
    pub kind: AiGuardrailKind,
    /// Action on match: `block` (return an error to the client),
    /// `redact` (scrub the match and continue — prompt phase only),
    /// or `log` (observe only, dry-run — the request proceeds).
    pub action: AiGuardrailAction,
    /// When to apply: `prompt` (before the provider call), `response`
    /// (after), or `both`. Default `both`.
    #[serde(default = "default_guardrail_phase")]
    pub phase: AiGuardrailPhase,
    /// Patterns for injection/pii/banned kinds (regex strings). Each
    /// is a Rust `regex` crate pattern; invalid patterns fail
    /// validation at publish time. For `pii` kind, the built-in PII
    /// patterns (email, phone, API key, credit card) are always
    /// active alongside any custom patterns declared here.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub patterns: Vec<String>,
    /// JSON schema for output schema enforcement (`schema` kind
    /// only). The response content (parsed as JSON) is validated
    /// against this schema; a violation blocks the response. Uses the
    /// unconditional `jsonschema` dependency; works in every build.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub schema: Option<serde_json::Value>,
    /// Policy names this rule attaches to. Empty (the default) means
    /// the rule applies to ALL consumers. When non-empty, the rule
    /// applies only to consumers whose attached policies (the
    /// consumer > route > service > listener > global chain) include
    /// at least one listed name.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<String>,
}

/// The default guardrail phase: `both`.
fn default_guardrail_phase() -> AiGuardrailPhase {
    AiGuardrailPhase::Both
}

/// Guardrail kind (DW-082 `ai.guardrails.rules[].kind`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiGuardrailKind {
    /// Prompt-injection heuristics: pattern matching for common
    /// injection attempts ("ignore previous instructions", role
    /// injection, instruction override). Applied at the prompt
    /// phase.
    Injection,
    /// PII detection: the built-in PII patterns (email, phone, API
    /// key, credit card) plus any custom patterns. Applied at the
    /// prompt phase; `redact` action scrubs the PII before the
    /// provider call.
    Pii,
    /// Banned-content filter: pattern matching against a banned
    /// content list. Applied at the prompt and/or response phase per
    /// the rule's `phase`.
    Banned,
    /// Output schema enforcement: the response content is validated
    /// against the declared JSON schema. Applied at the response
    /// phase (non-streaming only — streaming cannot validate a
    /// schema on partial content). Works in every build.
    Schema,
}

/// Guardrail action (DW-082 `ai.guardrails.rules[].action`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiGuardrailAction {
    /// Block the request/response: return a 400 error to the client
    /// with code `guardrail_blocked` (prompt) or
    /// `response_schema_violation` / `guardrail_blocked` (response).
    Block,
    /// Redact the match and continue: scrub the PII/banned content
    /// from the prompt before the provider call. Prompt phase only.
    Redact,
    /// Log only (dry-run): record the match but allow the request
    /// through. Use to tune thresholds before switching to `block`.
    Log,
}

/// Guardrail phase (DW-082 `ai.guardrails.rules[].phase`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiGuardrailPhase {
    /// Apply at the prompt phase (before the provider call).
    Prompt,
    /// Apply at the response phase (after the provider call, before
    /// the response is returned to the client).
    Response,
    /// Apply at both phases.
    Both,
}

/// Default semantic-cache cosine-similarity threshold: 0.85.
fn default_semantic_cache_threshold() -> f64 {
    0.85
}

/// Default semantic-cache TTL: 1 hour (3600 s).
fn default_semantic_cache_ttl() -> u64 {
    3600
}

/// Default semantic-cache max entries: 10 000.
fn default_semantic_cache_max_entries() -> usize {
    10_000
}

/// Default semantic-cache embedding-service timeout: 5 s (5000 ms).
fn default_semantic_cache_embedding_timeout_ms() -> u64 {
    5000
}

/// 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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SemanticCacheConfig {
    /// Whether the semantic cache is enabled. Default false: an
    /// `ai.semantic_cache` block without `enabled: true` caches
    /// nothing (the engine compiles but stays inert).
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The URL of the external embedding service (OpenAI-compatible
    /// /v1/embeddings API). Required when enabled. Validation
    /// rejects an empty or non-http(s) URL.
    pub embedding_url: String,
    /// The model name passed to the embedding service in the
    /// `model` field of the POST body.
    pub embedding_model: String,
    /// The dimension of the embedding vectors. Must match what the
    /// embedding service returns for the configured model;
    /// validation rejects 0.
    pub embedding_dim: usize,
    /// Cosine similarity threshold (0.0 to 1.0, inclusive). A cached
    /// entry is returned only if its cosine similarity to the query
    /// embedding is >= this threshold. Higher = stricter matching
    /// (fewer hits, more accurate). Default 0.85.
    #[serde(default = "default_semantic_cache_threshold")]
    pub threshold: f64,
    /// TTL for cached entries in seconds. Entries older than this are
    /// considered stale and not returned. Default 3600 (1 hour).
    #[serde(default = "default_semantic_cache_ttl")]
    pub ttl_secs: u64,
    /// Maximum number of entries to cache. When the cache is full,
    /// it is reset (all entries evicted, the HNSW index rebuilt).
    /// Default 10 000.
    #[serde(default = "default_semantic_cache_max_entries")]
    pub max_entries: usize,
    /// Timeout for the embedding service HTTP call in milliseconds.
    /// Default 5000 (5 seconds).
    #[serde(default = "default_semantic_cache_embedding_timeout_ms")]
    pub embedding_timeout_ms: u64,
    /// Optional API key for the embedding service (sent as
    /// `Authorization: Bearer <key>`). Can be a `${...}` secret
    /// reference (resolved at config-compile time). Inline values
    /// are redacted in config echoes; never logged.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub embedding_api_key: Option<String>,
}

// -------------------------------------------------------------------------
// DW-085: routing policies (fallback chains + latency-cost selection).
// -------------------------------------------------------------------------

/// Default classifier complexity threshold: 0.5.
fn default_classifier_threshold() -> f64 {
    0.5
}

/// Default classifier HTTP timeout: 1000 ms.
fn default_classifier_timeout_ms() -> u64 {
    1000
}

/// 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:
///
/// ```yaml
/// routing_policies:
///   my-policy:
///     kind: fallback_chain
///     cheap: cheap-model
///     escalate_to: expensive-model
///     classifier_url: http://...
///     classifier_model: complexity
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields, tag = "kind", rename_all = "snake_case")]
pub enum AiRoutingPolicy {
    /// Cheap-model-first with complexity-signal escalation (DW-085).
    /// Calls an external classifier service to estimate prompt
    /// complexity; simple prompts (score < threshold) use the cheap
    /// model, complex prompts (score >= threshold) escalate to the
    /// costlier model. On classifier error, fails open to the cheap
    /// model (the safe default).
    FallbackChain(AiFallbackChainPolicy),
    /// Latency-vs-cost routing (DW-085): static config-based
    /// selection. The operator declares cost/latency scores per
    /// candidate and a preference; the policy picks deterministically
    /// at compile time (no runtime metrics needed).
    LatencyCost(AiLatencyCostPolicy),
}

/// 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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiFallbackChainPolicy {
    /// The model alias to use for simple prompts (the cheap model).
    /// Must reference an existing alias in `ai.models` (validation
    /// rejects a typo at publish time).
    pub cheap: String,
    /// The model alias to escalate to for complex prompts. Must
    /// reference an existing alias in `ai.models`.
    pub escalate_to: String,
    /// The URL of the external classifier service. The service must
    /// accept a POST with `{"model": "...", "input": "..."}` and
    /// return `{"data": [{"score": 0.0-1.0}]}` (the OpenAI-compatible
    /// embeddings response shape, with `score` in place of
    /// `embedding`). Validation rejects an empty or non-http(s) URL.
    pub classifier_url: String,
    /// The model name to pass to the classifier service in the
    /// `model` field of the POST body.
    pub classifier_model: String,
    /// Complexity score threshold (0.0 to 1.0, inclusive). A score
    /// at or above the threshold triggers escalation to the costlier
    /// model; a score below the threshold uses the cheap model.
    /// Default 0.5.
    #[serde(default = "default_classifier_threshold")]
    pub threshold: f64,
    /// Timeout for the classifier HTTP call in milliseconds. Default
    /// 1000 (1 second). Validation rejects 0.
    #[serde(default = "default_classifier_timeout_ms")]
    pub timeout_ms: u64,
    /// Optional API key for the classifier service (sent as
    /// `Authorization: Bearer <key>`). Can be a `${...}` secret
    /// reference (resolved at config-compile time). Inline values
    /// are redacted in config echoes; never logged.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub api_key: Option<String>,
}

/// 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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiLatencyCostPolicy {
    /// The candidate models with their cost/latency scores. Each
    /// `model` must reference an existing alias in `ai.models`.
    /// Validation rejects an empty list.
    pub candidates: Vec<AiLatencyCostCandidate>,
    /// The selection preference: `cost` (cheapest), `latency`
    /// (fastest), or `balanced` (best cost/latency sum).
    pub preference: AiLatencyPreference,
    /// AI-15 (#203): when true, the policy uses live latency
    /// observations to dynamically adjust candidate ordering. The
    /// static `latency` scores are used as priors; observed latencies
    /// from recent requests refine the selection. Default false
    /// (static selection, the DW-085 behavior).
    #[serde(default, skip_serializing_if = "is_false")]
    pub live: bool,
    /// AI-15 (#203): the window size for live latency tracking
    /// (number of recent observations to average). Default 10. Only
    /// used when `live` is true.
    #[serde(
        default = "default_live_window",
        skip_serializing_if = "Option::is_none"
    )]
    pub live_window: Option<usize>,
}

/// AI-15 (#203): default live latency window size.
fn default_live_window() -> Option<usize> {
    Some(10)
}

/// One candidate in a latency-vs-cost policy (DW-085
/// `ai.routing_policies.<name>.candidates[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiLatencyCostCandidate {
    /// The model alias to route to. Must reference an existing alias
    /// in `ai.models`.
    pub model: String,
    /// Relative cost score (1-10, where 1 = cheapest). Validation
    /// rejects values outside 1-10.
    pub cost: u32,
    /// Relative latency score (1-10, where 1 = fastest). Validation
    /// rejects values outside 1-10.
    pub latency: u32,
}

/// The latency-vs-cost selection preference (DW-085
/// `ai.routing_policies.<name>.preference`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiLatencyPreference {
    /// Pick the cheapest candidate (lowest `cost` score).
    Cost,
    /// Pick the fastest candidate (lowest `latency` score).
    Latency,
    /// Pick the best cost/latency ratio (lowest `cost + latency`
    /// sum).
    Balanced,
}

// -------------------------------------------------------------------------
// DW-086: prompt experimentation (versioning, A/B tests, evals,
// feedback).
// -------------------------------------------------------------------------

/// Default feedback enabled flag: true.
fn default_feedback_enabled() -> bool {
    true
}

/// Prompt experimentation (DW-086 `ai.experiments`): prompt
/// versioning, A/B model comparison, regression evals, and feedback
/// ingestion. Absent (the default): no experiments surface.
#[derive(Debug, Clone, PartialEq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiExperiments {
    /// Named prompt version sets (DW-086). Each entry declares one
    /// or more versions (each with a system message) and an active
    /// version. The active version can be overridden at runtime via
    /// the admin API (stored in the state store). Absent (the
    /// default): no prompt versioning.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub prompts: BTreeMap<String, AiPromptVersions>,
    /// Named A/B tests (DW-086). Each test declares 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). Absent (the default): no A/B tests.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub ab_tests: BTreeMap<String, AiAbTest>,
    /// Named regression evals (DW-086). Each eval declares a golden
    /// set of input/expected cases and an optional prompt version;
    /// the admin API runs it against a model alias (or an A/B test's
    /// variants) and stores the results. Absent (the default): no
    /// evals.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub evals: BTreeMap<String, AiEval>,
    /// Feedback ingestion config (DW-086). When enabled, the admin
    /// API accepts feedback records (request id, label, comment)
    /// and stores them in analytics. Absent (the default): feedback
    /// is enabled (the default is `enabled: true`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub feedback: Option<AiFeedbackConfig>,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiPromptVersions {
    /// The named versions, each carrying a system message. Version
    /// names must be non-empty (validation rejects empty strings).
    pub versions: BTreeMap<String, AiPromptVersion>,
    /// The active version name. Must exist in `versions` (validation
    /// rejects a name not in the map). Can be overridden at runtime
    /// via the admin API (the override is stored in the state store).
    pub active: String,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiPromptVersion {
    /// The system message prepended to the request's messages. If
    /// the request already has a system message, the template's
    /// system message is prepended BEFORE it.
    pub system: String,
}

/// 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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiAbTest {
    /// The variants. Validation requires at least 2 (one variant is
    /// not a test). Each variant's `model` must reference an existing
    /// alias in `ai.models` that is NOT itself an experiment alias
    /// (no nested experiments).
    pub variants: Vec<AiAbVariant>,
}

/// One variant of an A/B test (DW-086
/// `ai.experiments.ab_tests.<name>.variants[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiAbVariant {
    /// The variant name (for analytics/metrics attribution). Must be
    /// non-empty.
    pub name: String,
    /// The model alias this variant routes to. Must reference an
    /// existing alias in `ai.models` that is NOT itself an experiment
    /// alias (no nested experiments — validation rejects it).
    pub model: String,
    /// An optional prompt version reference in
    /// `"prompt_name/version_name"` format. When set, the named
    /// version's system message is prepended to the request's
    /// messages for this variant. Validation rejects a reference
    /// whose prompt or version does not exist.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prompt: Option<String>,
    /// Relative weight (>= 1). The deterministic weighted pick uses
    /// the same slot semantics as canary splits (ratios hold per
    /// request, and re-sending a request with the same id lands on
    /// the same variant). Validation rejects 0.
    pub weight: u32,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiEval {
    /// An optional prompt version reference in
    /// `"prompt_name/version_name"` format. When set, the named
    /// version's system message is prepended to each eval case's
    /// input. Validation rejects a reference whose prompt or version
    /// does not exist.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub prompt: Option<String>,
    /// The golden set: input/expected pairs with a scorer. Validation
    /// requires at least one case and non-empty `input`/`expected`.
    pub golden_set: Vec<AiEvalCase>,
}

/// One eval case (DW-086
/// `ai.experiments.evals.<name>.golden_set[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiEvalCase {
    /// The input prompt (sent as the user message to the provider).
    /// Must be non-empty (validation rejects empty strings).
    pub input: String,
    /// The expected output. The scorer compares the provider's output
    /// against this value. For `exact_match`, an exact string match;
    /// for `contains`, the output must contain this string; for
    /// `regex`, this is the regex pattern the output must match.
    pub expected: String,
    /// The scorer name. One of: `exact_match` (default), `contains`,
    /// `regex`. When `regex`, `expected` must be a valid regex
    /// pattern (validation compiles it at publish time).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub scorer: Option<String>,
}

/// Feedback ingestion config (DW-086
/// `ai.experiments.feedback`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiFeedbackConfig {
    /// Whether the feedback admin endpoint accepts records. Default
    /// true (an `ai.experiments.feedback` block without `enabled:
    /// false` accepts feedback). When false, the endpoint returns
    /// 403.
    #[serde(default = "default_feedback_enabled", skip_serializing_if = "is_false")]
    pub enabled: bool,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiMcpConfig {
    /// The tool table, keyed by tool name. Each tool names an
    /// upstream that carries the transport and a path on that
    /// upstream. Tool names must be non-empty and unique (validation
    /// rejects duplicates and empty names).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub tools: BTreeMap<String, AiMcpTool>,
    /// AI-11 (#200): Static resources exposed via `resources/list`
    /// and `resources/read`. Each resource has a URI, a name, a
    /// description, and an optional MIME type. The resource content
    /// is served inline (no upstream proxy).
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub resources: BTreeMap<String, AiMcpResource>,
    /// AI-11 (#200): Static prompt templates exposed via
    /// `prompts/list` and `prompts/get`. Each prompt has a name, a
    /// description, and a template body with optional arguments.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub prompts: BTreeMap<String, AiMcpPrompt>,
    /// Session policy. Absent (the default): the built-in defaults
    /// (TTL 3600s, max 1000 concurrent sessions).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sessions: Option<AiMcpSessions>,
    /// The reserved HTTP path for the MCP JSON-RPC endpoint. Default
    /// `/mcp`. Must start with `/` if specified. The path is reserved
    /// like `/healthz`, `/readyz`, `/metrics` — it shadows any
    /// configured route and is handled before route resolution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiMcpTool {
    /// Human-readable description of the tool (returned to the client
    /// in `tools/list`).
    pub description: String,
    /// Name of the `upstreams[]` entry that carries this tool's
    /// transport. The gateway resolves the upstream's first endpoint
    /// to build the tool's URL. Validation rejects a reference to an
    /// unknown upstream.
    pub upstream: String,
    /// The path on the upstream (appended to the endpoint's
    /// `address:port`). Default `/`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// The HTTP method for the upstream call. Default `POST`. Must be
    /// a valid HTTP method (GET, POST, PUT, PATCH, DELETE) if
    /// specified.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub method: Option<String>,
    /// The JSON Schema for the tool's arguments (returned to the
    /// client in `tools/list` as `inputSchema`). Must be a valid JSON
    /// object.
    pub input_schema: serde_json::Value,
    /// Optional per-tool authorization. When present, the tool is
    /// only callable by consumers satisfying the authz rules. When
    /// absent, any authenticated consumer may call the tool.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authz: Option<crate::config::Authz>,
    /// Upstream call timeout in milliseconds. Default 30000.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_ms: Option<u64>,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiMcpResource {
    /// The resource URI (e.g., `config://routes`, `data://users`). Must
    /// be non-empty (validation rejects empty strings).
    pub uri: String,
    /// Human-readable name (returned in `resources/list`).
    pub name: String,
    /// Human-readable description (returned in `resources/list`).
    pub description: String,
    /// The MIME type of the content (e.g., `text/plain`,
    /// `application/json`). Default `text/plain`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mime_type: Option<String>,
    /// The resource content (returned verbatim in `resources/read`).
    pub content: String,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiMcpPrompt {
    /// Human-readable description (returned in `prompts/list`).
    pub description: String,
    /// The prompt template body. May contain `{{argument_name}}`
    /// placeholders that are substituted from the `arguments` field
    /// of a `prompts/get` request.
    pub template: String,
    /// The argument definitions for this prompt. Each argument has a
    /// name, a description, and a required flag.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub arguments: Vec<AiMcpPromptArgument>,
}

/// AI-11 (#200): One prompt argument definition.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiMcpPromptArgument {
    /// The argument name (used as the `{{name}}` placeholder in the
    /// template).
    pub name: String,
    /// Human-readable description of the argument.
    pub description: String,
    /// Whether the argument is required (default false).
    #[serde(default, skip_serializing_if = "is_false")]
    pub required: bool,
}

/// MCP session policy (DW-087 `ai.mcp.sessions`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AiMcpSessions {
    /// Session TTL in seconds. Default 3600. Expired sessions are
    /// cleaned up periodically and rejected on use.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ttl_secs: Option<u64>,
    /// Maximum number of concurrent active sessions. Default 1000.
    /// New `initialize` requests beyond this limit are rejected.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_concurrent: Option<usize>,
}

/// 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).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct A2aConfig {
    /// Master switch. Off by default: even when the `a2a` feature is
    /// enabled, the block is inert until `enabled: true`. This lets
    /// operators stage the config ahead of activating the surface.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The A2A agent pool. Each entry names an upstream (the
    /// transport) and an Agent Card (discovery doc). Agent names
    /// must be non-empty and unique (validation rejects duplicates
    /// and empty names). Each agent appears as a provider in the
    /// model alias table (its `kind` is `a2a`), so a model alias
    /// can route to it by name.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub agents: Vec<A2aAgent>,
    /// Session policy. Absent (the default): the built-in defaults
    /// (TTL 3600s, max 1000 concurrent sessions), mirroring MCP.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sessions: Option<A2aSessions>,
}

/// 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.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct A2aAgent {
    /// Agent name; unique within the `ai.a2a.agents` list. Referenced
    /// by `ai.models[].provider` (the agent appears as a provider of
    /// kind `a2a`). Validation rejects empty and duplicate names.
    pub name: String,
    /// The agent's base URL (the A2A endpoint). Must be an `http` or
    /// `https` URL. The adapter builds the task-submit path under
    /// this URL.
    pub url: String,
    /// The Agent Card: a discovery doc declaring the agent's name,
    /// description, version, capabilities, and authentication.
    /// Either a filesystem path to a JSON document (`/path/to/card.json`)
    /// or an inline JSON object. Validation rejects an inline card
    /// that is not a JSON object. The card is parsed at compile time
    /// (see `ai::a2a::AgentCardParser`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub card: Option<A2aAgentCard>,
    /// Name of the `upstreams[]` entry that carries this agent's
    /// transport (endpoints, TLS trust, pooling, timeouts, breaker).
    /// Validation rejects a reference to an unknown upstream.
    pub upstream: String,
}

/// The Agent Card source (DW-114): a file path or an inline JSON
/// object. One of the two is required when `card` is present.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct A2aAgentCard {
    /// Filesystem path to an Agent Card JSON document. Read at
    /// compile time; an unreadable or malformed file fails the
    /// generation closed (the same DW-045 contract as secret refs).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub path: Option<String>,
    /// Inline Agent Card JSON object. When present, takes precedence
    /// over `path`. Must be a JSON object.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub inline: Option<serde_json::Value>,
}

/// A2A session policy (DW-114 `ai.a2a.sessions`), mirroring MCP.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct A2aSessions {
    /// Session TTL in seconds. Default 3600. Expired sessions are
    /// cleaned up periodically and rejected on use.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ttl_secs: Option<u64>,
    /// Maximum number of concurrent active sessions. Default 1000.
    /// New task sessions beyond this limit are rejected.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_concurrent: Option<usize>,
}