debugerai 0.2.0__py3-none-any.whl

debugai/analyze.py

@@ -0,0 +1,142 @@
+"""Level 1 API — the single-call entry point (Architecture §3.2).
+
+    from debugai import analyze
+    result = analyze(
+        prompt="What is the refund policy?",
+        output="Refunds are issued within 90 days...",
+        chunks=[...],
+        similarity_scores=[...],
+    )
+    print(result["primary"]["failure"], result["primary"]["confidence"])
+
+Returns the structured JSON contract from §7.3:
+    { "healthy": bool,
+      "primary":   {failure, confidence, severity, root_cause, fix, evidence},
+      "secondary": [ ... ],
+      "signals":   { ...8 metrics... },
+      "explanation": "human-readable text" }
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from debugai.diagnosis import diagnose
+from debugai.explainer import explain
+from debugai.judge import INSTRUCTION_VIOLATION, judge_instructions
+from debugai.schema import CaptureRecord
+from debugai.signals import compute_signals, measure_variance
+from debugai.thresholds import DEFAULT_THRESHOLDS, Thresholds
+
+_IV_FIX = (
+    "Strengthen the system prompt to enforce the violated rules: reveal at most "
+    "one small hint per turn (never the full solution early), ask exactly one NEW "
+    "leading question that advances beyond what was already said (never restate a "
+    "prior question), and don't open by paraphrasing the student."
+)
+
+
+def _merge_instruction(result: dict, jd) -> dict:
+    """Fold an instruction-adherence verdict into the diagnosis, re-ranking by
+    confidence so the most severe failure becomes primary."""
+    severity = "critical" if any(v.severity == "critical" for v in jd.violations) else "warning"
+    rules = "; ".join(v.rule for v in jd.violations[:3])
+    iv = {
+        "failure": INSTRUCTION_VIOLATION,
+        "confidence": jd.confidence,
+        "severity": severity,
+        "root_cause": f"The response violates {len(jd.violations)} system-prompt "
+                      f"rule(s): {rules}",
+        "fix": _IV_FIX,
+        "evidence": {"violations": [v.to_dict() for v in jd.violations],
+                     "judge_model": jd.model},
+    }
+    fired = ([result["primary"]] if result.get("primary") else []) + result.get("secondary", []) + [iv]
+    fired.sort(key=lambda r: r["confidence"], reverse=True)
+    result["healthy"] = False
+    result["primary"] = fired[0]
+    result["secondary"] = fired[1:]
+    return result
+
+
+def analyze(
+    prompt: str,
+    output: str,
+    *,
+    system_prompt: str = "",
+    chunks: list[str] | None = None,
+    similarity_scores: list[float] | None = None,
+    retrieval_query: str | None = None,
+    expected_output: str | None = None,
+    model_name: str | None = None,
+    temperature: float | None = None,
+    max_tokens: int | None = None,
+    context_window: int | None = None,
+    latency_ms: int | None = None,
+    token_usage: dict[str, int] | None = None,
+    thresholds: Thresholds = DEFAULT_THRESHOLDS,
+    explain_with_llm: bool = True,
+    lazy: bool = False,
+    judge: bool = False,
+    judge_model: str | None = None,
+    variance_rerun: Any = None,
+    variance_runs: int = 3,
+) -> dict[str, Any]:
+    """Diagnose why an LLM output failed and return a structured fix.
+
+    Only ``prompt`` and ``output`` are required (Core IO). Supplying retrieval
+    and runtime fields unlocks the RAG and capacity signals.
+    """
+    rec = CaptureRecord(
+        user_prompt=prompt,
+        llm_output=output,
+        system_prompt=system_prompt,
+        expected_output=expected_output,
+        retrieved_chunks=chunks or [],
+        similarity_scores=similarity_scores or [],
+        retrieval_query=retrieval_query,
+        model_name=model_name,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        context_window=context_window,
+        latency_ms=latency_ms,
+        token_usage=token_usage or {},
+    )
+
+    signals = compute_signals(rec, lazy=lazy)
+    # Deep mode (§7.5 Tier 2): replace the variance proxy with a measured value
+    # from actually re-running the model, before classifying.
+    if variance_rerun is not None:
+        signals.variance = measure_variance(
+            variance_rerun, rec.system_prompt, rec.user_prompt,
+            rec.retrieved_chunks, rec.temperature, variance_runs)
+        signals.variance_method = "measured"
+    diag = diagnose(signals, rec, thresholds)
+    result = diag.to_dict()
+
+    # Optional behavioural / instruction-following check (LLM-as-judge) — catches
+    # failures the grounding signals can't see (e.g. a tutor revealing the answer).
+    if judge and rec.system_prompt:
+        jd = judge_instructions(rec.system_prompt, rec.user_prompt, rec.llm_output,
+                                model=judge_model)
+        if not jd.healthy:
+            result = _merge_instruction(result, jd)
+
+    if explain_with_llm:
+        explanation = explain(diag)
+        result["explainer_model"] = explanation["model"]
+        # Prefer the deterministic primary's own root_cause when the judge changed
+        # the primary; otherwise use the LLM explanation.
+        if (result.get("primary") or {}).get("failure") == INSTRUCTION_VIOLATION:
+            result["explanation"] = result["primary"]["root_cause"]
+        else:
+            result["explanation"] = explanation["explanation"]
+            if diag.primary is not None and explanation.get("fix"):
+                result["primary"]["fix"] = explanation["fix"]
+    else:
+        result["explanation"] = (
+            result["primary"]["root_cause"] if result.get("primary") else "No failure detected."
+        )
+        result["explainer_model"] = "none"
+
+    return result

debugai/calibration.py

@@ -0,0 +1,198 @@
+"""Adaptive threshold calibration (Architecture §7.2).
+
+Static thresholds break across embedding models, domains, and chunk sizes. The
+``ThresholdStore`` learns a per-user "known good" baseline from the signals of
+healthy requests and tightens the gating thresholds to *that user's* norms:
+
+    cold  (<50 requests)   sensible defaults — not enough data yet
+    warm  (50-500)         percentile-based (5th / 95th of healthy baseline)
+    hot   (>500)           rolling-window z-score (mean ± 2 std), last `window`
+
+A signal is only adapted once it has ``MIN_SAMPLES`` healthy observations;
+otherwise its default is kept. Every calibrated value is clamped to a sane band
+so pathological data can't produce a runaway threshold.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+from debugai.thresholds import DEFAULT_THRESHOLDS, Thresholds
+
+COLD_MAX = 50
+WARM_MAX = 500
+MIN_SAMPLES = 15
+Z = 2.0  # z-score: anomaly = 2 std beyond the healthy baseline
+
+# Thresholds field -> (signal key, direction). "low" = anomaly below threshold,
+# "high" = anomaly above threshold. Fields not listed stay fixed (semantic).
+CALIBRATION_SPEC: dict[str, tuple[str, str]] = {
+    "similarity_min": ("similarity", "low"),
+    "overlap_low": ("overlap", "low"),
+    "entity_coverage_min": ("entity_coverage", "low"),
+    "contradiction_min": ("contradiction", "high"),
+    "variance_min": ("variance", "high"),
+    "context_length_ratio_max": ("context_ratio", "high"),
+    "token_usage_high": ("token_ratio", "high"),
+    "latency_high_ms": ("latency_ms", "high"),
+}
+
+# Clamp bands keep calibrated thresholds reasonable regardless of the data.
+CLAMP: dict[str, tuple[float, float]] = {
+    "similarity_min": (0.10, 0.90),
+    "overlap_low": (0.10, 0.85),
+    "entity_coverage_min": (0.10, 0.85),
+    "contradiction_min": (0.10, 0.60),
+    "variance_min": (0.15, 0.80),
+    "context_length_ratio_max": (0.50, 0.95),
+    "token_usage_high": (0.50, 0.95),
+    "latency_high_ms": (500.0, 30000.0),
+}
+
+_SIGNAL_KEYS = sorted({k for k, _ in CALIBRATION_SPEC.values()})
+
+
+def _mean(xs: list[float]) -> float:
+    return sum(xs) / len(xs)
+
+
+def _std(xs: list[float], mu: float) -> float:
+    if len(xs) < 2:
+        return 0.0
+    return (sum((x - mu) ** 2 for x in xs) / (len(xs) - 1)) ** 0.5
+
+
+def _percentile(xs: list[float], p: float) -> float:
+    s = sorted(xs)
+    if not s:
+        return 0.0
+    idx = (len(s) - 1) * (p / 100.0)
+    lo, hi = int(idx), min(int(idx) + 1, len(s) - 1)
+    frac = idx - lo
+    return s[lo] * (1 - frac) + s[hi] * frac
+
+
+@dataclass
+class SignalCalibration:
+    signal: str
+    direction: str
+    field: str
+    n: int
+    baseline_mean: float
+    baseline_std: float
+    default: float
+    value: float
+    adapted: bool
+
+
+class ThresholdStore:
+    """Per-user adaptive threshold store. Thread-safe; optionally persisted."""
+
+    def __init__(self, path: Path | None = None, window: int = WARM_MAX):
+        self._path = path
+        self._window = window
+        self._lock = threading.Lock()
+        self._total = 0
+        self._healthy: list[dict[str, float]] = []  # baseline signal rows
+        if path is not None:
+            self._load()
+
+    # --- persistence -------------------------------------------------------
+    def _load(self) -> None:
+        try:
+            data = json.loads(self._path.read_text())
+            if isinstance(data, dict):
+                self._total = int(data.get("total", 0) or 0)
+                healthy = data.get("healthy", [])
+                self._healthy = healthy[-self._window:] if isinstance(healthy, list) else []
+        except Exception:  # missing / corrupt / unreadable → cold start
+            pass
+
+    def _persist(self) -> None:
+        if self._path is None:
+            return
+        self._path.write_text(json.dumps(
+            {"total": self._total, "healthy": self._healthy[-self._window:]}
+        ))
+
+    # --- ingest ------------------------------------------------------------
+    def record(self, signals: dict, healthy: bool) -> None:
+        with self._lock:
+            self._total += 1
+            if healthy:
+                row = {k: float(signals.get(k, 0.0)) for k in _SIGNAL_KEYS}
+                self._healthy.append(row)
+                del self._healthy[:-self._window]
+            self._persist()
+
+    # --- regime ------------------------------------------------------------
+    def regime(self) -> str:
+        if self._total < COLD_MAX:
+            return "cold"
+        return "warm" if self._total <= WARM_MAX else "hot"
+
+    # --- calibration -------------------------------------------------------
+    def _calibrate_field(self, field: str, regime: str) -> SignalCalibration:
+        signal, direction = CALIBRATION_SPEC[field]
+        default = getattr(DEFAULT_THRESHOLDS, field)
+        values = [r[signal] for r in self._healthy if signal in r]
+        mu = _mean(values) if values else default
+        sd = _std(values, mu) if values else 0.0
+
+        # A baseline that is entirely zero means the signal was never exercised
+        # (e.g. no context_window supplied → context_ratio always 0). Don't adapt
+        # it — keep the default rather than collapsing to a clamp floor.
+        degenerate = mu == 0.0 and sd == 0.0
+        adapted = regime != "cold" and len(values) >= MIN_SAMPLES and not degenerate
+        value = default
+        if adapted:
+            if regime == "warm":  # percentile of the healthy baseline
+                value = _percentile(values, 5.0 if direction == "low" else 95.0)
+            else:  # hot: rolling-window z-score
+                value = mu - Z * sd if direction == "low" else mu + Z * sd
+            lo, hi = CLAMP[field]
+            value = max(lo, min(value, hi))
+
+        return SignalCalibration(
+            signal=signal, direction=direction, field=field, n=len(values),
+            baseline_mean=round(mu, 4), baseline_std=round(sd, 4),
+            default=default, value=round(value, 4), adapted=adapted,
+        )
+
+    def current(self) -> Thresholds:
+        """The active, calibrated thresholds for this user."""
+        with self._lock:
+            regime = self.regime()
+            if regime == "cold":
+                return DEFAULT_THRESHOLDS
+            overrides = {
+                field: self._calibrate_field(field, regime).value
+                for field in CALIBRATION_SPEC
+            }
+        return dataclasses.replace(DEFAULT_THRESHOLDS, **overrides)
+
+    def details(self) -> dict:
+        """Full calibration report for the dashboard."""
+        with self._lock:
+            regime = self.regime()
+            cals = [self._calibrate_field(f, regime) for f in CALIBRATION_SPEC]
+            return {
+                "regime": regime,
+                "total_requests": self._total,
+                "healthy_baseline": len(self._healthy),
+                "window": self._window,
+                "next_regime_at": COLD_MAX if regime == "cold" else (
+                    WARM_MAX if regime == "warm" else None
+                ),
+                "signals": [dataclasses.asdict(c) for c in cals],
+            }
+
+    def reset(self) -> None:
+        with self._lock:
+            self._total = 0
+            self._healthy = []
+            self._persist()

debugai/cli.py

@@ -0,0 +1,171 @@
+"""DebugAI command-line interface.
+
+    debugai analyze --prompt "..." --output "..." --chunk "..." --score 0.4
+    debugai diagnose cases.json
+    debugai fix cases.json --simulate
+    debugai serve --port 8000
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from debugai import analyze
+from debugai.agents import propose_fix
+from debugai.schema import CaptureRecord
+
+_ANSI = {"red": "\033[31m", "green": "\033[32m", "yellow": "\033[33m",
+         "dim": "\033[2m", "bold": "\033[1m", "reset": "\033[0m"}
+
+
+def _c(text: str, color: str) -> str:
+    if not sys.stdout.isatty():
+        return text
+    return f"{_ANSI[color]}{text}{_ANSI['reset']}"
+
+
+def _grounded_stub(system_prompt, user_prompt, chunks, temperature):
+    ctx = " ".join(chunks)
+    return ("Per the provided context: " + ctx) if ctx else "I don't have that information."
+
+
+def _case_kwargs(case: dict) -> dict:
+    keys = ("prompt", "output", "system_prompt", "chunks", "similarity_scores",
+            "retrieval_query", "temperature", "max_tokens", "context_window",
+            "latency_ms", "model_name")
+    return {k: case[k] for k in keys if k in case}
+
+
+def _print_diagnosis(diag: dict, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(diag, indent=2))
+        return
+    if diag.get("healthy"):
+        print(_c("✓ healthy", "green") + " — no failure detected")
+        return
+    p = diag["primary"]
+    color = "red" if p["severity"] == "critical" else "yellow"
+    print(_c(f"✗ {p['failure']}", color) + f"  conf {p['confidence']}  ({p['severity']})")
+    print("  " + p["root_cause"])
+    print(_c("  fix: ", "dim") + p["fix"])
+    if diag.get("secondary"):
+        print(_c("  secondary: ", "dim") + ", ".join(s["failure"] for s in diag["secondary"]))
+
+
+def _load_cases(path: Path) -> list[dict]:
+    data = json.loads(path.read_text())
+    if isinstance(data, dict) and "cases" in data:
+        return [{k: v for k, v in c.items() if k not in ("id", "expected", "_comment")}
+                for c in data["cases"]]
+    if isinstance(data, list):
+        return data
+    return [data]
+
+
+# --------------------------------------------------------------------------- #
+def cmd_analyze(args) -> int:
+    diag = analyze(
+        prompt=args.prompt, output=args.output, system_prompt=args.system or "",
+        chunks=args.chunk or None, similarity_scores=args.score or None,
+        temperature=args.temperature, context_window=args.context_window,
+        explain_with_llm=args.explain,
+    )
+    _print_diagnosis(diag, args.json)
+    return 0
+
+
+def cmd_diagnose(args) -> int:
+    cases = _load_cases(Path(args.file))
+    results = []
+    for c in cases:
+        diag = analyze(explain_with_llm=False, **_case_kwargs(c))
+        results.append(diag)
+        if not args.json:
+            label = c.get("label") or (c.get("prompt", "")[:48])
+            print(_c(label, "bold"))
+            _print_diagnosis(diag, False)
+            print()
+    if args.json:
+        print(json.dumps(results, indent=2))
+    else:
+        failing = sum(0 if r["healthy"] else 1 for r in results)
+        print(_c(f"{failing}/{len(results)} failing", "dim"))
+    return 0
+
+
+def cmd_fix(args) -> int:
+    cases = _load_cases(Path(args.file))
+    rerun = _grounded_stub if args.simulate else None
+    for c in cases:
+        kw = _case_kwargs(c)
+        diag = analyze(explain_with_llm=False, **kw)
+        rec = CaptureRecord(
+            user_prompt=kw.get("prompt", ""), llm_output=kw.get("output", ""),
+            system_prompt=kw.get("system_prompt", ""),
+            retrieved_chunks=kw.get("chunks") or [],
+            similarity_scores=kw.get("similarity_scores") or [],
+            temperature=kw.get("temperature"), context_window=kw.get("context_window"),
+        )
+        report = propose_fix(diag, rec, rerun=rerun)
+        label = c.get("label") or kw.get("prompt", "")[:48]
+        print(_c(label, "bold"))
+        if report is None:
+            print("  healthy / no agent\n")
+            continue
+        vcolor = {"verified": "green", "mitigated": "yellow", "escalated": "yellow",
+                  "failed": "red", "pending_rerun": "dim"}.get(report.verdict, "dim")
+        print(f"  {report.agent} → " + _c(report.verdict, vcolor) +
+              f"  tests {report.tests_passed}/{report.tests_total}")
+        if report.diff:
+            print(_c("  " + report.diff.replace("\n", "\n  "), "dim"))
+        print()
+    return 0
+
+
+def cmd_serve(args) -> int:
+    import uvicorn
+    uvicorn.run("server.app:app", host=args.host, port=args.port, reload=args.reload)
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="debugai", description="Diagnose & fix LLM failures.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    a = sub.add_parser("analyze", help="diagnose a single prompt/output")
+    a.add_argument("--prompt", required=True)
+    a.add_argument("--output", required=True)
+    a.add_argument("--system", default="")
+    a.add_argument("--chunk", action="append", help="a retrieved chunk (repeatable)")
+    a.add_argument("--score", action="append", type=float, help="similarity score (repeatable)")
+    a.add_argument("--temperature", type=float)
+    a.add_argument("--context-window", type=int, dest="context_window")
+    a.add_argument("--explain", action="store_true", help="use the LLM explainer")
+    a.add_argument("--json", action="store_true")
+    a.set_defaults(func=cmd_analyze)
+
+    d = sub.add_parser("diagnose", help="diagnose a JSON file of cases")
+    d.add_argument("file")
+    d.add_argument("--json", action="store_true")
+    d.set_defaults(func=cmd_diagnose)
+
+    fx = sub.add_parser("fix", help="diagnose + propose/verify a fix for each case")
+    fx.add_argument("file")
+    fx.add_argument("--simulate", action="store_true", help="run the verify loop with a grounded stub model")
+    fx.set_defaults(func=cmd_fix)
+
+    sv = sub.add_parser("serve", help="launch the web app")
+    sv.add_argument("--host", default="127.0.0.1")
+    sv.add_argument("--port", type=int, default=8000)
+    sv.add_argument("--reload", action="store_true")
+    sv.set_defaults(func=cmd_serve)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

debugai/config.py

@@ -0,0 +1,134 @@
+"""DebugAI SDK configuration — a single object controls everything that runs
+per request, replacing the scattered wrap_llm() keyword arguments.
+
+    from debugai import DebugAIConfig
+    config = DebugAIConfig(
+        enable_judge=True,      # LLM-as-judge for system-prompt adherence
+        sample_rate=0.1,        # diagnose 10% of requests
+        on_diagnosis=lambda d: print(d["primary"]),
+        sink_url="http://my-debugai/api/traces",
+        sink_token="dbg_...",
+    )
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+from debugai.thresholds import DEFAULT_THRESHOLDS, Thresholds
+
+
+@dataclass
+class DebugAIConfig:
+    # ── Background workers ──────────────────────────────────────────────────
+    enable_diagnosis: bool = True
+    """Run the 8-signal engine + 5 detectors on every (sampled) request."""
+
+    enable_traces: bool = True
+    """Emit an observability Trace (spans, scores, cost) per request."""
+
+    enable_judge: bool = False
+    """LLM-as-judge: check system-prompt rule adherence (costs an LLM call)."""
+
+    enable_explain: bool = False
+    """LLM explainer: generate a human-readable explanation (costs an LLM call)."""
+
+    lazy: bool = True
+    """Skip expensive signals (embeddings/NER/NLI) when cheap signals are healthy."""
+
+    sample_rate: float = 1.0
+    """Fraction of requests to diagnose (0.0–1.0). Deterministic count-based."""
+
+    max_queue_depth: int = 10_000
+    """Maximum pending jobs in the background worker queue. Excess jobs are
+    dropped (backpressure) so diagnosis never slows the real request."""
+
+    # ── Metrics ─────────────────────────────────────────────────────────────
+    track_tokens: bool = True
+    """Accumulate prompt + completion token counts per model in MetricsLedger."""
+
+    track_cost: bool = True
+    """Estimate cost per request and accumulate in MetricsLedger."""
+
+    track_latency: bool = True
+    """Record per-request latency for p50/p95 in MetricsLedger."""
+
+    # ── Sinks ───────────────────────────────────────────────────────────────
+    on_diagnosis: Callable[[dict], None] | None = None
+    """Called with each diagnosis dict after background analysis completes."""
+
+    on_trace: Callable[[Any], None] | None = None
+    """Called with each Trace object after background analysis completes."""
+
+    on_metrics: Callable[[dict], None] | None = None
+    """Called after each request with a snapshot of per-request metrics."""
+
+    sink_url: str | None = None
+    """POST traces to a DebugAI server endpoint (e.g. http://…/api/traces).
+    Requires sink_token if the server has auth enabled."""
+
+    sink_token: str | None = None
+    """X-API-Key token for sink_url authentication."""
+
+    # ── Conversation ────────────────────────────────────────────────────────
+    session_id: str | None = None
+    """Default session ID for all traces; overridden by the session() ctx manager."""
+
+    tags: dict[str, str] = field(default_factory=dict)
+    """Key-value tags attached to every trace and diagnosis record."""
+
+    # ── Thresholds ──────────────────────────────────────────────────────────
+    thresholds: Thresholds = field(default_factory=lambda: DEFAULT_THRESHOLDS)
+    """Detection thresholds. Per-user adaptive calibration overrides these at
+    the server level; SDK callers can override them explicitly here."""
+
+    # ── Provider config ──────────────────────────────────────────────────────
+    ollama_base_url: str = "http://localhost:11434/v1"
+    """Ollama server URL for local models (Qwen, Llama, Phi, DeepSeek…).
+    Overridden by the OLLAMA_BASE_URL env var."""
+
+    model_prices: dict | None = None
+    """Custom per-model pricing overrides: {"my-model": (input_$/1M, output_$/1M)}.
+    Merged with the built-in table; your entries take precedence."""
+
+    # ── LiteLLM-parity features (B1+) ───────────────────────────────────────
+    fallbacks: list = field(default_factory=list)
+    """Model names to try if the primary call fails (rate limit / error / timeout).
+    e.g. fallbacks=['claude-haiku-4-5', 'ollama/qwen2.5']"""
+
+    response_schema: dict | None = None
+    """JSON Schema to validate structured outputs. Violations are surfaced as
+    an instruction_violation in the diagnosis."""
+
+    on_schema_violation: Callable | None = None
+    """Called when a schema violation is detected: fn(output_text, violations_list)."""
+
+    # ── B4: Budget manager ───────────────────────────────────────────────────
+    budget_usd: float | None = None
+    """Soft spend cap across the MetricsLedger. Raises BudgetExceededError (or calls
+    on_budget_exceeded) before each call once this threshold is crossed."""
+
+    on_budget_exceeded: Callable | None = None
+    """Called instead of raising when the budget is exhausted: fn(spent_usd).
+    If set, the call is NOT made and this callback fires instead."""
+
+    # ── B5: Request caching ──────────────────────────────────────────────────
+    cache_ttl_seconds: int | None = None
+    """Cache identical (model, messages) calls for this many seconds.
+    Cache hits skip the provider call and return a CompletionResponse(from_cache=True)."""
+
+    # ── B6: Retry tracing ────────────────────────────────────────────────────
+    max_retries: int = 2
+    """Retry attempts on rate-limit (429) or transient server errors (500/502/503).
+    Each attempt is recorded in CompletionResponse.retry_count and trace metadata."""
+
+    retry_backoff_seconds: float = 1.0
+    """Base back-off between retries (doubled each attempt)."""
+
+    # ── B8: Latency SLA ──────────────────────────────────────────────────────
+    latency_sla_ms: float | None = None
+    """Alert when a request exceeds this latency threshold."""
+
+    on_sla_breach: Callable | None = None
+    """Called when latency_sla_ms is breached: fn({"model", "latency_ms", "threshold_ms"})."""