Client ──► API Gateway (auth, idempotency, quota)
              │
              ▼
        [1] Decision Contract (JSON Schema / Pydantic / Zod)
              │
              ▼
        [2] Context Assembler (policy pack + record + retrieval)
              │
              ▼
        [3] Gemini Inference (structured output + bounded tools)
              │
              ▼
        [4] Deterministic Policy Gate (confidence, missing fields, rules)
              │
              ▼
        [5] Persistence, Trace, Eval Sampling ──► Audit Store / OTel

# decisions/schema.py
from __future__ import annotations

from typing import Literal

from pydantic import BaseModel, Field, model_validator


class Evidence(BaseModel):
    source_id: str = Field(description="Stable ID of a policy clause or source record.")
    quote: str = Field(max_length=280, description="Verbatim span from that source.")
    polarity: Literal["supports", "contradicts"]


class Decision(BaseModel):
    """Wire contract for POST /v1/decisions (schema v3)."""

    outcome: Literal["approve", "escalate", "deny"]
    confidence: float = Field(ge=0.0, le=1.0)
    rationale: str = Field(min_length=20, max_length=1200)
    evidence: list[Evidence] = Field(min_length=1, max_length=8)
    missing_fields: list[str] = Field(default_factory=list)
    requires_human: bool = False

    @model_validator(mode="after")
    def _policy_gate(self) -> "Decision":
        # Deterministic post-processing. The model proposes; the service disposes.
        if self.confidence < 0.72 or self.missing_fields:
            self.requires_human = True
        if self.outcome == "deny" and not any(
            e.polarity == "supports" for e in self.evidence
        ):
            self.outcome = "escalate"
            self.requires_human = True
        return self

# decisions/engine.py
import json
import logging

from google import genai
from google.genai import errors as genai_errors
from google.genai import types
from tenacity import (
    retry, retry_if_exception_type, stop_after_attempt, wait_exponential_jitter,
)

from .schema import Decision

log = logging.getLogger("decisions")
client = genai.Client()
MODEL = "gemini-2.5-flash"  # pin explicitly; never use a floating alias in prod

SYSTEM = """You are a credit-limit review engine.
Rules:
1. Every assertion in `rationale` must map to an item in `evidence`.
2. `source_id` must come from the supplied policy pack. Never invent IDs.
3. If a required field is absent, add it to `missing_fields` and set outcome='escalate'.
4. Prefer 'escalate' over guessing. A wrong 'approve' costs 40x a manual review.
"""

RETRYABLE = {429, 500, 502, 503, 504}


class RetryableUpstream(Exception):
    """Normalized transient error from the inference provider."""


@retry(
    retry=retry_if_exception_type(RetryableUpstream),
    wait=wait_exponential_jitter(initial=0.4, max=8.0),
    stop=stop_after_attempt(4),
    reraise=True,
)
def decide(payload: dict, request_id: str) -> Decision:
    try:
        resp = client.models.generate_content(
            model=MODEL,
            contents=render(payload),
            config=types.GenerateContentConfig(
                system_instruction=SYSTEM,
                response_mime_type="application/json",
                response_schema=Decision,
                temperature=0.0,
                seed=1337,
                max_output_tokens=2048,
                thinking_config=types.ThinkingConfig(thinking_budget=0),
            ),
        )
    except genai_errors.APIError as exc:
        if exc.code in RETRYABLE:
            raise RetryableUpstream(f"upstream {exc.code}") from exc
        log.error("non_retryable_upstream", extra={"request_id": request_id,
                                                   "code": exc.code})
        raise

    decision = resp.parsed  # already a validated Decision instance
    if decision is None:
        raise RetryableUpstream(f"unparseable decision for {request_id}")
    log.info("decision_emitted", extra={
        "request_id": request_id,
        "outcome": decision.outcome,
        "confidence": decision.confidence,
        "input_tokens": resp.usage_metadata.prompt_token_count,
        "output_tokens": resp.usage_metadata.candidates_token_count,
    })
    return decision

HANDLERS = {"lookup_policy": lookup_policy, "fetch_account": fetch_account}


def decide_with_tools(payload: dict, max_turns: int = 4) -> Decision:
    config = types.GenerateContentConfig(
        system_instruction=SYSTEM,
        tools=[lookup_policy, fetch_account],
        response_mime_type="application/json",
        response_schema=Decision,
        temperature=0.0,
    )
    contents = [types.Content(role="user", parts=[types.Part(text=render(payload))])]

    for _ in range(max_turns):
        resp = client.models.generate_content(
            model=MODEL, contents=contents, config=config
        )
        calls = resp.function_calls or []
        if not calls:
            if resp.parsed is None:
                raise RetryableUpstream("final turn was not a valid Decision")
            return resp.parsed

        contents.append(resp.candidates[0].content)
        parts = []
        for call in calls:
            handler = HANDLERS.get(call.name or "")
            try:
                if handler is None:
                    raise KeyError(f"unknown_tool:{call.name}")
                result = {"result": handler(**(call.args or {}))}
            except Exception as exc:  # tool errors are data, not crashes
                result = {"error": f"{type(exc).__name__}: {exc}"}
            parts.append(types.Part.from_function_response(
                name=call.name, response=result))
        # Gemini expects function responses delivered in a user-role turn.
        contents.append(types.Content(role="user", parts=parts))

    raise TimeoutError("tool loop exhausted")

// decisions/client.ts — typed consumer side
import { z } from "zod";

const Evidence = z.object({
  sourceId: z.string(),
  quote: z.string().max(280),
  polarity: z.enum(["supports", "contradicts"]),
});

export const Decision = z.object({
  outcome: z.enum(["approve", "escalate", "deny"]),
  confidence: z.number().min(0).max(1),
  rationale: z.string().min(20).max(1200),
  evidence: z.array(Evidence).min(1).max(8),
  missingFields: z.array(z.string()),
  requiresHuman: z.boolean(),
});
export type Decision = z.infer<typeof Decision>;

export async function requestDecision(
  input: unknown,
  signal: AbortSignal,
): Promise<Decision> {
  const res = await fetch(`${BASE}/v1/decisions`, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${token}`,
      "idempotency-key": crypto.randomUUID(),
    },
    body: JSON.stringify(input),
    signal,
  });

  if (!res.ok) {
    // RFC 9457 problem+json from the gateway
    const problem = await res.json().catch(() => ({}));
    throw new Error(`decision_failed:${res.status}:${problem.title ?? "unknown"}`);
  }

  const parsed = Decision.safeParse(await res.json());
  if (!parsed.success) {
    throw new Error(`contract_violation: ${parsed.error.message}`);
  }
  return parsed.data;
}

cost_per_1k = 1000 * (
    uncached_in / 1e6 * P_in
  + cached_in   / 1e6 * P_cached
  + output_tok  / 1e6 * P_out
)