Deploy Sensorflow Studio

.gitattributes

@@ -33,3 +33,9 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+docs/retro/screenshots/01-hardware-compat-card.png filter=lfs diff=lfs merge=lfs -text
+docs/retro/screenshots/02-evidence-chain-observed.png filter=lfs diff=lfs merge=lfs -text
+docs/retro/screenshots/03-evidence-chain-policy-gate.png filter=lfs diff=lfs merge=lfs -text
+docs/retro/screenshots/04-scorecard.png filter=lfs diff=lfs merge=lfs -text
+docs/retro/screenshots/05-retrieved-standards.png filter=lfs diff=lfs merge=lfs -text
+docs/retro/screenshots/06-audit-trail.png filter=lfs diff=lfs merge=lfs -text

app_backend.py

@@ -1488,6 +1488,11 @@ app.include_router(rca_router)
 from sensorflow.hillclimb.api import router as hillclimb_router
 app.include_router(hillclimb_router)
 
+# Agentic Retrospective Safety Analyzer (evidence-tiered failure retrospectives,
+# safety-case RAG, deterministic severity + launch policy gate).
+from sensorflow.retro.api import router as retro_router
+app.include_router(retro_router)
+
 # Multimodal rare-event mining & perception QA (costumed-pedestrian miner).
 from sensorflow.raremine.api import router as raremine_router
 app.include_router(raremine_router)

docs/retro/compatibility-matrix.md

@@ -0,0 +1,80 @@
+# CUDA vs ROCm compatibility matrix for the retro inference layer
+
+Scope: running the vLLM server (`sensorflow/retro/inference/vllm_server/`)
+that backs the Retrospective Analyzer's `vllm` backend.
+
+**Honesty statement.** This matrix was written on a macOS (Apple Silicon)
+machine where **none of the GPU rows below can be executed or verified**. It
+is compiled from general knowledge of the CUDA/ROCm/vLLM ecosystems as of the
+author's knowledge cutoff. vLLM moves fast: **verify every row against the
+release notes of the vLLM version you actually install.** Rows marked
+UNCERTAIN are flagged rather than guessed.
+
+## Platform support at a glance
+
+| Platform | vLLM | Notes |
+|---|---|---|
+| Linux + NVIDIA (CUDA 12.x) | Supported | Primary, best-tested target |
+| Linux + AMD (ROCm 6.x, MI200/MI300 class) | Supported | Official ROCm builds; narrower feature set |
+| Linux + AMD consumer (RDNA) | UNCERTAIN | Community/experimental; verify per release |
+| macOS (Apple Silicon or Intel) | **NOT SUPPORTED** | No CUDA, no ROCm; this dev machine. Use Ollama (Metal) locally |
+| Windows native | NOT SUPPORTED | WSL2 + CUDA is the workaround |
+| CPU-only Linux | Limited/experimental | A CPU backend exists but is not a serving-grade path; verify |
+
+## Package installation
+
+| Aspect | CUDA (NVIDIA) | ROCm (AMD) |
+|---|---|---|
+| Install | `pip install vllm` (prebuilt wheels, CUDA 12.x) | No universal PyPI wheel historically; use AMD's ROCm docker images or build from source with ROCm 6.x. Verify current release — ROCm wheels have been appearing |
+| Driver floor | Driver >= 535-series for CUDA 12.x wheels (verify) | ROCm >= 6.0 for current vLLM; MI300 needs recent ROCm |
+| Attention kernels | FlashAttention-2 / FlashInfer prebuilt | ROCm FlashAttention port (Composable Kernel / Triton based); fewer head-dim/feature combos supported |
+
+## PyTorch builds
+
+| Aspect | CUDA | ROCm |
+|---|---|---|
+| Wheel source | `pip install torch` (cu12x wheels on PyPI) | `pip install torch --index-url https://download.pytorch.org/whl/rocm6.x` |
+| Detection | `torch.version.cuda` set, `torch.cuda.is_available()` | `torch.version.hip` set; ROCm *masquerades as* `torch.cuda` (HIP) — `torch.cuda.is_available()` is True on ROCm builds |
+| Pitfall | CPU-only wheel silently installed if index not pinned | Mixing a CUDA wheel onto a ROCm host fails at runtime, not install time |
+
+## Quantization support (verify against your vLLM release)
+
+| Method | CUDA | ROCm |
+|---|---|---|
+| AWQ | Supported (Ampere+; kernels tuned for 4-bit) | UNCERTAIN/limited — AWQ kernels historically CUDA-only; do not assume |
+| GPTQ | Supported (incl. Marlin kernels on newer GPUs) | Partial — basic GPTQ paths have worked via Triton; Marlin is CUDA-specific |
+| FP8 (W8A8) | Supported on Hopper/Ada (H100, L40S); emulated/absent on older | Supported on MI300 (native FP8); not on older CDNA |
+| INT8 (SmoothQuant-style) | Supported | UNCERTAIN — verify |
+| bitsandbytes | Supported (load-time) | NOT SUPPORTED historically |
+
+`compat.py` encodes a conservative subset of this table
+(`CUDA_QUANTIZATIONS` / `ROCM_QUANTIZATIONS`) and says "verify against the
+installed vLLM release" in its PASS messages.
+
+## Memory management
+
+| Aspect | CUDA | ROCm |
+|---|---|---|
+| PagedAttention KV cache | Core feature, mature | Same architecture, HIP-compiled kernels |
+| `GPU_MEMORY_UTILIZATION` | Fraction of VRAM pre-allocated (default 0.9) | Same flag; MI300's 192 GB HBM changes sizing math |
+| Unified/managed memory | Not used by vLLM | Not used by vLLM |
+| Multi-GPU (TENSOR_PARALLEL_SIZE) | NCCL | RCCL (NCCL API-compatible); verify topology support (xGMI vs NVLink) |
+
+## Kernel compatibility
+
+| Aspect | CUDA | ROCm |
+|---|---|---|
+| Core kernels | CUDA C++/CUTLASS + Triton | HIPified C++ + Composable Kernel + Triton-on-ROCm |
+| Triton | Mature | Works on ROCm but kernel autotuning/coverage lags; some fused ops fall back to slower paths |
+| CUDA Graphs | Used for decode speedups | HIP graph support has lagged; verify (`--enforce-eager` is the fallback) |
+| Custom all-reduce | CUDA-specific fast path | Typically disabled on ROCm; RCCL path used |
+
+## What this repo can and cannot claim
+
+- CAN claim (verified here): vLLM is unsupported on this macOS machine —
+  `env_detect.py` + `compat.py` prove it at runtime, and the test suite
+  asserts it.
+- CANNOT claim: any vLLM latency/throughput number. `benchmark.py` produces
+  them only when pointed at a real CUDA/ROCm host; no such run happened here.
+- Local real-inference numbers, if any appear in reports, come from an
+  **Ollama server on Apple CPU/Metal** and are labeled as such.

docs/retro/final-report.md

@@ -0,0 +1,205 @@
+# Agentic Retrospective Safety Analyzer — Final Report
+
+Delivered in one run, structured phase-by-phase per the source spec. All numbers
+below are real measurements taken on this machine; anything not measurable here
+is explicitly labeled as such.
+
+**Verification totals: 74/74 retro tests green; full repo suite 598/598 green;
+tsc clean; production build green; browser walkthrough completed (screenshots
+in `docs/retro/screenshots/`).**
+
+---
+
+## Hardware findings on THIS machine (real, measured)
+
+| Property | Value |
+|---|---|
+| OS | macOS 26.6.1 (Darwin), arm64 — Apple Silicon |
+| GPU | Apple M4 (unified memory, Metal/MPS only) |
+| Python | 3.11.9 (`.venv`) |
+| CUDA / ROCm | **None — vLLM UNSUPPORTED on this machine** |
+| Ollama | **Not reachable** at `localhost:11434` at verification time (connection refused) |
+| Compat chain | `gpu` = FAIL (clear message); `driver/torch/vllm/model/quantization` = SKIPPED (blocked by failed `gpu` link) |
+
+Measured latencies (labeled honestly):
+
+- **Mock backend, end-to-end analysis via HTTP API**: 0.26–0.30 s per analysis
+  (3 runs: 0.298 s, 0.261 s, 0.275 s) on the warm server. This is deterministic
+  scripted analysis — no LLM.
+- **Ollama**: no numbers reported because no server was running. The client
+  supports real inference + latency measurement and labels results
+  "Ollama-on-CPU/Metal" when a server is present.
+- **vLLM**: NO benchmark numbers exist anywhere in this delivery. The benchmark
+  script (`sensorflow/retro/inference/vllm_server/benchmark.py`) is runnable
+  only on CUDA/ROCm hosts and says so; it was not executed here.
+
+## Dependency outcomes
+
+| Dependency | Outcome |
+|---|---|
+| `chromadb` | **Installed cleanly, used live.** The RAG index reports `store_backend: chromadb` at runtime. Deterministic hashed-TF + numpy cosine store remains as the always-available fallback (same interface), and tests force the fallback path so they never depend on chroma. |
+| `mcp` | **Installed cleanly.** Bonus MCP server wrapper (`sensorflow/retro/tools/mcp_server.py`) adapts the tool registry; the installed package exposes `MCPServer` (not `FastMCP`), handled dynamically. The registry itself remains the MCP-style boundary. |
+| `pydantic-ai-slim` | **Installed**, but orchestration deliberately uses the internal typed loop (typed pydantic contracts + explicit tool loop) for full determinism and auditability; PydanticAI adds no value on the mock path and would obscure the audit trail. |
+
+## Reuse map (read-only imports)
+
+- `sensorflow/safety/ssam_ext.py` → `projected_ttc` math for TTC (with validity flags added on top).
+- `sensorflow/megaeval` stats → `DistributionAnalysisTool` delegates distribution-shift summaries.
+- `sensorflow/seqeval/paired.py` → `PairedSequentialTest` for statistical significance in the scorecard.
+- `sensorflow/evaluation/copilot.py` pattern → Ollama backend client shape (endpoint, model discovery, timeouts).
+
+## Test counts
+
+74 retro tests (all passing), plus full-repo suite 598/598:
+
+| File | Tests | Covers |
+|---|---|---|
+| `test_inference.py` | 8 | env detection on this machine, vLLM-unsupported honesty, compat chain clarity, mock client contract |
+| `test_rag.py` | 9 | chunking, retrieval eval precision, synthetic labels always present, no-citation-without-retrieval |
+| `test_tools.py` | 8 | read-only default, write authorization, audit completeness, path allowlist, schemas |
+| `test_metrics.py` | 14 | stopping-distance parameterization, TTC validity flags, SCR, behavioral impact |
+| `test_policy.py` | 13 | asymmetric costs (benign-FN < phantom-FP), gate determinism, AI-severity override flow, INSUFFICIENT_EVIDENCE never PASS |
+| `test_agent.py` | 10 | both canonical fixtures, fact/inference separation, stripped telemetry → UNKNOWN, persistence |
+| `test_api.py` | 9 | full API lifecycle via TestClient, vLLM local-unavailability |
+| `test_optional_deps.py` | 3 | chromadb store, MCP server bonus (skip if not installed) |
+
+---
+
+## Phase 1 — Inference foundation (`sensorflow/retro/inference/`)
+
+**What was built**: `env_detect.py` (real OS/Python/Torch/GPU/CUDA/ROCm/MPS
+detection; detected Apple M4 on this machine), `compat.py` (validation chain
+GPU→driver→torch→vLLM→model→quantization; failed links block downstream checks
+with clear reasons), `client.py` (pluggable mock/ollama/vllm client with health
+check, deterministic test-prompt validation, token counts, latency),
+`vllm_server/` (config split into `server.env` / `model.env` / `runtime.env`,
+`start_vllm.sh` that refuses to run on macOS, `benchmark.py` with TTFT
+P50/P95/P99, tokens/sec, warm-vs-cold), `requirements-retro.txt`, package README.
+
+**How to run**:
+
+```bash
+.venv/bin/python -m sensorflow.retro.inference.env_detect     # env report
+.venv/bin/python -m sensorflow.retro.inference.compat          # compat chain
+# vLLM host (CUDA/ROCm only): edit *.env, then ./start_vllm.sh; benchmark.py
+```
+
+**Validation checklist**: env detection real on this machine PASS · vLLM
+honestly reported unsupported PASS · mock client contract PASS · vLLM
+configs/scripts provided-but-not-executed, stated explicitly PASS.
+
+**Known limitations**: vLLM artifacts unverified here by definition; Ollama
+path exercised only via health-check code (no server running); compatibility
+matrix is general-knowledge with "verify against current vLLM release" caveats.
+
+## Phase 2 — Safety-case RAG (`sensorflow/retro/rag/`)
+
+**What was built**: parser + configurable chunking, embedder (chromadb default
+embedder when installed; deterministic hashed-TF fallback with documented
+tradeoff), store (`ChromaStore` / `NumpyCosineStore` behind one protocol),
+retriever that ALWAYS returns `{source, document, version, section,
+retrieved_text, relevance_score}` + full metadata, seed corpus of 7 SYNTHETIC
+documents (safety requirements, launch criteria, perception requirements, ODD,
+historical retrospectives, evaluation policy, SOTIF concept paraphrase — every
+one tagged `SYNTHETIC_EXAMPLE / NOT_A_REAL_STANDARD` in content AND metadata),
+retrieval eval harness.
+
+**Real numbers**: precision@4 = **1.0** over 14 expected-source queries,
+`store_backend: chromadb` (live server) — fallback path separately tested.
+
+**Hard rule (tested)**: no safety-requirement citation is ever emitted without
+a retrieval hit backing it; every scorecard `retrieved_standards` entry maps to
+an audited `safety_standard_rag` call.
+
+**How to run**: `GET /api/retro/rag/search?q=...&k=4`, `GET /api/retro/rag/eval`.
+
+**Known limitations**: corpus is small and synthetic by design; lexical
+fallback scores are not comparable to chroma's embedding distances (documented).
+
+## Phase 3 — Agent + MCP-style tools (`sensorflow/retro/agent/`, `tools/`)
+
+**What was built**: `ToolRegistry` (input/output schema, `read_only` default
+true, timeout, error behavior, audit log with args/result-hash/timestamp for
+every call including denials); tools: `LogReaderTool` (allowlisted to `runs/`
++ fixtures dir), `SafetyStandardRAGTool`, `MetricCalculatorTool` (stopping
+distance with reaction/velocity/grade/friction/decel/system latency reusing
+ssam_ext math; TTC with validity flags; SCR vs policy criticality; behavioral
+impact observed-vs-corrected), `HistoricalFailureSearchTool`,
+`DistributionAnalysisTool` (megaeval delegation), `CreateEvaluationCaseTool`
+(the ONE write tool, requires explicit authorization, audited). Bonus: real MCP
+server wrapper since `mcp` installed. Orchestrator: internal typed loop
+(Log Agent → Evidence Analyzer → RAG Agent → Safety Synthesizer); mock backend
+= deterministic scripted analysis, Ollama backend = real LLM synthesis with
+follow-up RAG queries. Five fixtures including both canonical examples and the
+missing-telemetry / benign-FP / non-critical-FN variants.
+
+**Tested guarantees**: stripped telemetry → UNKNOWN, never guessed; fact and
+inference never mixed (hypotheses are Tier 4 only); write tool denied without
+authorization; every tool call audited.
+
+**How to run**: `POST /api/retro/analyze?fixture_id=missed_pedestrian_rain&backend=mock`
+(or upload a JSON log; `backend=ollama` when a server is running).
+
+**Known limitations**: Ollama synthesis path implemented and unit-tested at the
+prompt/parsing level but not exercised end-to-end here (no server); MCP server
+wrapper is smoke-tested, not exercised by a real MCP client.
+
+## Phase 4 — Scorecard + policy gate (`scorecard.py`, `policy.py`)
+
+**What was built**: evidence hierarchy enforced in types (Tier1 OBSERVED /
+Tier2 DERIVED / Tier3 RETRIEVED / Tier4 AI_HYPOTHESIS); strictly-typed
+`RetrospectiveScorecard` with every spec field + markdown renderer showing the
+FACT / DERIVED FACT / RETRIEVED REQUIREMENT / AI HYPOTHESIS / SAFETY
+DETERMINATION distinction; deterministic severity BENIGN/DISRUPTIVE/CRITICAL/
+FATAL from contextual evidence with the asymmetric FN/FP cost model (VRU ×
+distance-vs-stopping × relative motion × remaining reaction time for FN;
+intervention magnitude × disruption for FP) — tested that a benign distant FN
+ranks BELOW a hard-braking phantom FP; LLM severity proposal adjudicated by the
+policy engine with divergence recorded + flagged for human review; policy-
+versioned launch gate (`retro-policy/1.0.0`) where INSUFFICIENT_EVIDENCE can
+never become PASS.
+
+**Fixture B verified result** (mock, end-to-end): FALSE_NEGATIVE, severity
+CRITICAL (AI proposal agreed, no divergence), launch FAIL (GATE-01), human
+review required, 38 evidence items, 7 retrieved standards, 2 hypotheses,
+stopping distance 26.18 m vs 26.0 m range, TTC 1.7 s with validity flags.
+
+**Known limitations**: severity weights are demonstration policy values
+(versioned, documented), not calibrated to a real fleet's risk model.
+
+## API + persistence
+
+All endpoints live under `/api/retro` (env, compat, backends, rag/search,
+rag/eval, fixtures, analyze, analyses, analyses/{id}, analyses/{id}/audit,
+tools) — all verified 200 via curl sweep and the pytest TestClient suite.
+Artifacts persist under `runs/retro/{analyses,audit,uploads}`.
+
+## Frontend
+
+"Retrospective Analyzer" page under SAFETY & COMPLIANCE. All new files
+(`src/pages/retro/`, `src/components/retro/`, `src/services/retro.ts`,
+`src/types/retro.ts`) + minimal additive insertions (App.tsx nav/import/render,
+LabelEvalContext page id, HelpMenu page name, pageHelp + glossary entries —
+required because those maps are typed `Record<PageId, …>`). Delivers: fixture
+picker + backend selector with honest availability badges, vertical evidence-
+chain view color-coded by tier with legend, scorecard with severity/launch
+banner + human-review flag, retrieved-standards panel with SYNTHETIC_EXAMPLE
+badges, audit-trail tab, hardware/compat card. `tsc` clean; `vite build` green.
+
+## Verification & servers
+
+- Full pytest: **598 passed, 0 failed** (includes 74 retro tests).
+- Browser walkthrough of fixture B end-to-end on `http://localhost:5199/#/retro`
+  (screenshots 01–06 in `docs/retro/screenshots/`).
+- The pre-existing servers on :8000 and :5173 were left untouched; because the
+  :8000 backend predates this router (started without `--reload`), verification
+  runs on a fresh backend at :8100 paired with `vite.retro-verify.config.ts` on
+  :5199 — both left running. Nothing was committed.
+
+## Honest gaps
+
+1. No vLLM execution or benchmark numbers — impossible on macOS; scripts ship unverified-by-design.
+2. No real-LLM end-to-end run — Ollama was not running at verification time; the mock path is the verified path.
+3. The safety-case corpus is synthetic; SOTIF content is concept paraphrase only.
+4. The long-running :8000/:5173 servers won't show the retro API/page until restarted (concurrent-work constraint, not a defect).
+5. PydanticAI installed but intentionally unused for orchestration (typed internal loop chosen for auditability).

sensorflow/retro/README.md

@@ -0,0 +1,94 @@
+# Retro — Agentic Retrospective Safety Analyzer
+
+Local-first, evidence-driven analysis of perception failures. Traceable chain:
+
+```
+RAW FAILURE -> OBSERVED EVIDENCE -> DERIVED METRICS -> RETRIEVED ENGINEERING
+EVIDENCE -> AGENT HYPOTHESIS -> BEHAVIORAL ANALYSIS -> SAFETY POLICY ->
+RETROSPECTIVE SCORECARD -> HUMAN DECISION
+```
+
+Core rule: the LLM interprets/correlates/hypothesizes; deterministic code
+computes metrics and owns the safety boundary. Launch determinations only
+pass through the deterministic policy gate (`policy.py`).
+
+## Backends and reproducible startup
+
+### mock (default — no model, fully deterministic)
+Nothing to start. All tests run against this backend.
+
+```bash
+.venv/bin/python -c "
+from sensorflow.retro.inference.client import get_backend
+b = get_backend('mock'); print(b.health()); print(b.validate())"
+```
+
+### ollama (real local inference on this macOS machine — CPU/Metal)
+```bash
+# 1. Install & start Ollama (https://ollama.com), then pull a model:
+ollama pull gemma3:latest        # or any chat model
+# 2. Optionally pin the model:
+export RETRO_OLLAMA_MODEL=gemma3:latest
+# 3. Validate:
+.venv/bin/python -c "
+from sensorflow.retro.inference.client import get_backend
+b = get_backend('ollama'); print(b.health()); print(b.validate())"
+```
+Numbers from this backend are **Ollama-on-CPU/Metal**, never vLLM numbers.
+
+### vllm (CUDA/ROCm Linux hosts ONLY — not runnable on this machine)
+```bash
+# On the GPU host:
+pip install vllm
+cd sensorflow/retro/inference/vllm_server
+MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct PORT=8001 ./start_vllm.sh
+# Benchmark (TTFT p50/p95/p99, tokens/sec, warm-vs-cold):
+python benchmark.py --base-url http://localhost:8001/v1 --label "vLLM <GPU model>"
+
+# Back on this machine, point the client at the host:
+export RETRO_VLLM_URL=http://gpu-host:8001/v1
+```
+`start_vllm.sh` refuses to run on macOS with a clear error. `env_detect.py`
+and `compat.py` report this machine as unsupported for vLLM (verified by
+tests). See `docs/retro/compatibility-matrix.md` for CUDA vs ROCm.
+
+## Quick tour
+
+```bash
+# Environment + compat report
+.venv/bin/python -m sensorflow.retro.inference.compat
+
+# Analyze a canonical fixture end to end (mock backend)
+.venv/bin/python -c "
+from sensorflow.retro.agent.orchestrator import analyze_fixture
+sc = analyze_fixture('missed_pedestrian_rain', backend='mock')
+print(sc.render_markdown())"
+
+# API (mounted on the studio backend at :8000)
+curl -s localhost:8000/api/retro/env | python -m json.tool
+curl -s -X POST 'localhost:8000/api/retro/analyze?fixture_id=phantom_brake_plastic_bag&backend=mock'
+```
+
+## Layout
+
+- `inference/` — env detection, vLLM compat chain, pluggable client,
+  vLLM server configs + startup + benchmark (GPU hosts only).
+- `rag/` — safety-case retrieval. Seed corpus is **SYNTHETIC** demonstration
+  material; every synthetic rule is tagged `SYNTHETIC_EXAMPLE` /
+  `NOT_A_REAL_STANDARD` in content and metadata. SOTIF/ISO 21448 entries are
+  paraphrase-level concept summaries, not standard text.
+- `tools/` — MCP-style audited tool registry (read-only default, path
+  allowlists, audit trail with args/result-hash/timestamp).
+- `agent/` — orchestrator: Log Agent -> Evidence Analyzer -> RAG Agent ->
+  Safety Synthesizer. Mock backend = deterministic scripted analysis.
+- `scorecard.py` — tiered evidence (OBSERVED/DERIVED/RETRIEVED/AI_HYPOTHESIS)
+  and the strictly-typed `RetrospectiveScorecard`.
+- `policy.py` — deterministic severity framework (asymmetric FN/FP cost) and
+  the versioned launch-recommendation gate.
+- `api.py` — FastAPI router at `/api/retro`; artifacts under `runs/retro/`.
+
+## Tests
+
+```bash
+.venv/bin/python -m pytest tests/test_retro -q
+```

sensorflow/retro/__init__.py

@@ -0,0 +1,24 @@
+"""Agentic Retrospective Safety Analyzer (retro).
+
+Evidence-driven analysis of perception failures with a traceable chain:
+
+    RAW FAILURE -> OBSERVED EVIDENCE -> DERIVED METRICS -> RETRIEVED
+    ENGINEERING EVIDENCE -> AGENT HYPOTHESIS -> BEHAVIORAL ANALYSIS ->
+    SAFETY POLICY -> RETROSPECTIVE SCORECARD -> HUMAN DECISION
+
+Core rule: the LLM interprets, correlates, and hypothesizes; deterministic
+code computes every metric and owns the safety boundary. Launch
+determinations only ever pass through the deterministic policy gate
+(sensorflow.retro.policy); INSUFFICIENT_EVIDENCE never becomes PASS.
+
+Package layout:
+    inference/   pluggable LLM backends (vllm | ollama | mock) + env/compat
+    rag/         safety-case retrieval (synthetic, clearly-labeled corpus)
+    tools/       MCP-style audited tool registry
+    agent/       retrospective orchestrator (Log -> Evidence -> RAG -> Synth)
+    scorecard.py tier-tagged evidence + RetrospectiveScorecard model
+    policy.py    deterministic severity framework + launch gate
+    api.py       FastAPI router mounted at /api/retro
+"""
+
+AGENT_VERSION = "retro-agent/1.0.0"

sensorflow/retro/agent/__init__.py

@@ -0,0 +1,11 @@
+"""Retrospective agent: Log Agent -> Evidence Analyzer -> RAG Agent ->
+Safety Synthesizer, with ReAct-style audited tool use.
+
+Orchestration note: pydantic-ai installed cleanly in this environment, but
+the orchestrator deliberately uses the internal typed loop (typed pydantic
+stage contracts + the audited ToolRegistry) as the execution engine for BOTH
+backends, because the deterministic mock path and the per-call audit
+requirements must hold with no model present. The LLM (Ollama, when
+reachable) contributes hypotheses, severity proposals, and follow-up
+retrieval queries — never metrics or determinations.
+"""

sensorflow/retro/agent/orchestrator.py

@@ -0,0 +1,642 @@
+"""Retrospective orchestrator: the typed four-stage agent pipeline.
+
+    Log Agent          reads the artifact through the audited registry,
+                       derives the failure type, extracts TIER1 facts,
+                       and explicitly lists missing fields (UNKNOWN).
+    Evidence Analyzer  drives the deterministic MetricCalculatorTool
+                       (stopping distance, TTC, SCR impact, behavioral
+                       impact) -> TIER2 derived facts.
+    RAG Agent          builds failure-conditioned queries, retrieves
+                       safety-case requirements (TIER3), historical
+                       matches, and distribution findings.
+    Safety Synthesizer LLM (Ollama) or deterministic scripted analysis
+                       (mock) -> TIER4 hypotheses + severity PROPOSAL.
+
+The deterministic policy engine then validates/overrides the proposal and
+produces the launch determination; the assembled RetrospectiveScorecard is
+persisted with its full audit trail.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+from pydantic import BaseModel, Field
+
+from sensorflow.retro import AGENT_VERSION, store
+from sensorflow.retro.inference.client import InferenceBackend, get_backend
+from sensorflow.retro.agent.prompts import SYSTEM_PROMPT, synthesis_prompt
+from sensorflow.retro.agent.scripted import (scripted_hypotheses,
+                                             scripted_severity_proposal)
+from sensorflow.retro.policy import (POLICY_VERSION, SeverityContext,
+                                     adjudicate_severity, compute_severity,
+                                     launch_gate)
+from sensorflow.retro.scorecard import (EvidenceItem, EvidenceTier,
+                                        RetrievedStandard,
+                                        RetrospectiveScorecard,
+                                        RootCauseHypothesis, Severity,
+                                        StatSignificance, UNKNOWN,
+                                        UncertaintyReport)
+from sensorflow.retro.tools.builtin import build_registry
+from sensorflow.retro.tools.registry import ToolRegistry
+
+NON_HAZARD_CLASSES = {"plastic_bag", "debris", "cardboard", "balloon",
+                      "traffic_sign", "vegetation", "steam", "shadow"}
+DEFAULT_REACTION_TIME_S = 0.25
+
+
+# --------------------------------------------------------- stage contracts
+
+class LogExtract(BaseModel):
+    log: Dict[str, Any]
+    source_path: str
+    present_fields: List[str]
+    missing_fields: List[str]
+    failure_type: str
+    failure_type_rationale: str
+    observed_evidence: List[EvidenceItem]
+
+
+class EvidenceAnalysis(BaseModel):
+    stopping: Dict[str, Any]
+    ttc: Dict[str, Any]
+    scr: Dict[str, Any]
+    behavioral: Dict[str, Any]
+    derived_evidence: List[EvidenceItem]
+    unknown_metrics: List[str]
+
+
+class RAGFindings(BaseModel):
+    standards: List[RetrievedStandard]
+    retrieved_evidence: List[EvidenceItem]
+    historical_matches: List[Dict[str, Any]] = Field(default_factory=list)
+    distribution_findings: List[str] = Field(default_factory=list)
+    distribution_shift: Optional[Dict[str, Any]] = None
+    queries: List[str] = Field(default_factory=list)
+
+
+class Synthesis(BaseModel):
+    hypotheses: List[RootCauseHypothesis]
+    ai_proposed_severity: Optional[Severity]
+    behavioral_consequence: str
+    provider: str
+
+
+# ----------------------------------------------------------- 1. Log Agent
+
+def _derive_failure_type(log: Dict[str, Any]) -> Tuple[str, str]:
+    gt = log.get("ground_truth") or {}
+    pred = log.get("prediction")
+    planner = log.get("planner_response") or {}
+    if gt and pred is None:
+        return "FALSE_NEGATIVE", ("ground truth object present with no "
+                                  "corresponding prediction/track")
+    if pred and (pred.get("detection_delay_s") or 0.0) > 0.5:
+        return "FALSE_NEGATIVE", (f"detection arrived "
+                                  f"{pred.get('detection_delay_s')}s late — the "
+                                  "object was effectively missed during the "
+                                  "safety-relevant window (late detection)")
+    gt_class = (gt.get("class") or "").lower()
+    pred_class = (pred.get("class") or "").lower() if pred else ""
+    if (gt_class in NON_HAZARD_CLASSES and pred_class
+            and pred_class not in NON_HAZARD_CLASSES):
+        if (planner.get("decel_mps2") or 0.0) > 0.5:
+            return "FALSE_POSITIVE", (f"non-hazard '{gt_class}' predicted as "
+                                      f"'{pred_class}' and the planner "
+                                      "intervened: phantom intervention")
+        return "FALSE_POSITIVE", (f"non-hazard '{gt_class}' predicted as "
+                                  f"hazard '{pred_class}' (no intervention)")
+    if pred and gt_class and pred_class and gt_class != pred_class:
+        return "MISCLASSIFICATION", (f"ground truth '{gt_class}' predicted as "
+                                     f"'{pred_class}'")
+    return "UNKNOWN_FAILURE", "no deterministic rule matched this artifact"
+
+
+def _obs(key: str, value: Any, statement: str, provenance: str) -> EvidenceItem:
+    return EvidenceItem(tier=EvidenceTier.OBSERVED, key=key,
+                        value=UNKNOWN if value is None else str(value),
+                        statement=statement, provenance=provenance)
+
+
+def run_log_agent(registry: ToolRegistry, fixture_id: Optional[str] = None,
+                  path: Optional[str] = None) -> LogExtract:
+    res = registry.call("log_reader",
+                        {"fixture_id": fixture_id, "path": path})
+    out = res.result or {}
+    log = out["log"]
+    failure_type, rationale = _derive_failure_type(log)
+
+    gt = log.get("ground_truth") or {}
+    pred = log.get("prediction") or {}
+    ego = log.get("ego") or {}
+    scenario = log.get("scenario") or {}
+    planner = log.get("planner_response") or {}
+    sensors = log.get("sensor_metadata") or {}
+    traffic = (log.get("traffic_context") or {}).get("following_vehicle") or {}
+    dis = log.get("disengagement") or {}
+    col = log.get("collision") or {}
+    models = log.get("models") or {}
+    tracks = log.get("tracks") or []
+
+    src = "eval log field"
+    ev: List[EvidenceItem] = [
+        _obs("ego_speed_mps", ego.get("speed_mps"),
+             "ego speed at event time", f"{src} ego.speed_mps"),
+        _obs("gt_class", gt.get("class"),
+             "human-verified ground-truth object class", f"{src} ground_truth.class"),
+        _obs("gt_distance", gt.get("distance_m"),
+             "ground-truth object range from ego", f"{src} ground_truth.distance_m"),
+        _obs("gt_relative_velocity", gt.get("relative_velocity_mps"),
+             "ground-truth closing velocity (positive = closing)",
+             f"{src} ground_truth.relative_velocity_mps"),
+        _obs("pred_class", pred.get("class") if pred else None,
+             "predicted object class", f"{src} prediction.class"),
+        _obs("pred_confidence", pred.get("confidence") if pred else None,
+             "detector confidence", f"{src} prediction.confidence"),
+        _obs("pred_detection_delay", pred.get("detection_delay_s") if pred else None,
+             "detection delay versus ground-truth appearance",
+             f"{src} prediction.detection_delay_s"),
+        _obs("pred_relative_velocity", pred.get("relative_velocity_mps") if pred else None,
+             "predicted closing velocity", f"{src} prediction.relative_velocity_mps"),
+        _obs("planner_action", planner.get("action"),
+             "observed planner action", f"{src} planner_response.action"),
+        _obs("planner_decel", planner.get("decel_mps2"),
+             "observed planner deceleration (m/s^2)", f"{src} planner_response.decel_mps2"),
+        _obs("planner_response_time", planner.get("response_time_s"),
+             "planner response time after object appearance",
+             f"{src} planner_response.response_time_s"),
+        _obs("weather", scenario.get("weather"),
+             "scenario weather", f"{src} scenario.weather"),
+        _obs("odd_status", scenario.get("odd_status"),
+             "inside/outside operational design domain", f"{src} scenario.odd_status"),
+        _obs("following_gap", traffic.get("time_gap_s"),
+             "rear traffic time gap", f"{src} traffic_context.following_vehicle.time_gap_s"),
+        _obs("disengagement_occurred", dis.get("occurred"),
+             "safety-driver disengagement", f"{src} disengagement.occurred"),
+        _obs("collision_near_miss", col.get("near_miss"),
+             "near-miss recorded", f"{src} collision.near_miss"),
+        _obs("models", f"{models.get('baseline')} -> {models.get('candidate')}",
+             "baseline and candidate model versions", f"{src} models"),
+    ]
+    if tracks:
+        ev.append(_obs("track_class_flicker", tracks[0].get("class_flicker"),
+                       "track-level class flicker observed", f"{src} tracks[0].class_flicker"))
+        ev.append(_obs("track_velocity_variance", tracks[0].get("velocity_variance"),
+                       "track velocity variance level", f"{src} tracks[0].velocity_variance"))
+    if sensors:
+        for name in ("camera", "lidar"):
+            status = (sensors.get(name) or {}).get("status")
+            if status is not None:
+                ev.append(_obs(f"sensor_{name}_status", status,
+                               f"{name} health/degradation state",
+                               f"{src} sensor_metadata.{name}.status"))
+    for f in out["missing_fields"]:
+        ev.append(EvidenceItem(
+            tier=EvidenceTier.OBSERVED, key=f"missing:{f}", value=UNKNOWN,
+            statement=f"required field '{f}' is absent from the artifact — "
+                      "treated as UNKNOWN, never guessed",
+            provenance="field absent from artifact"))
+
+    return LogExtract(log=log, source_path=out["source_path"],
+                      present_fields=out["present_fields"],
+                      missing_fields=out["missing_fields"],
+                      failure_type=failure_type,
+                      failure_type_rationale=rationale,
+                      observed_evidence=ev)
+
+
+# --------------------------------------------------- 2. Evidence Analyzer
+
+def _drv(key: str, value: Any, statement: str, provenance: str) -> EvidenceItem:
+    return EvidenceItem(tier=EvidenceTier.DERIVED, key=key,
+                        value=UNKNOWN if value is None else str(value),
+                        statement=statement, provenance=provenance)
+
+
+def run_evidence_analyzer(registry: ToolRegistry,
+                          extract: LogExtract) -> EvidenceAnalysis:
+    log = extract.log
+    ego = log.get("ego") or {}
+    gt = log.get("ground_truth") or {}
+    timing = log.get("timing") or {}
+
+    sd_params = {
+        "velocity_mps": ego.get("speed_mps"),
+        "reaction_time_s": DEFAULT_REACTION_TIME_S,
+        "system_latency_s": (timing.get("detection_latency_ms") or 0) / 1000.0,
+        "planner_latency_s": (timing.get("planner_latency_ms") or 0) / 1000.0,
+        "friction": ego.get("road_friction_estimate", 0.7),
+        "grade": ego.get("grade", 0.0),
+    }
+    stopping = registry.call("metric_calculator", {
+        "operation": "stopping_distance", "params": sd_params}).result["result"]
+
+    obj_dims = gt.get("dimensions_m") or [0.6, 0.6]
+    ttc = registry.call("metric_calculator", {
+        "operation": "ttc",
+        "params": {"distance_m": gt.get("distance_m"),
+                   "closing_velocity_mps": gt.get("relative_velocity_mps"),
+                   "obj_length_m": obj_dims[0], "obj_width_m": obj_dims[1]},
+    }).result["result"]
+
+    scr = registry.call("metric_calculator", {
+        "operation": "scr_impact",
+        "params": {"evaluation_context": log.get("evaluation_context")},
+    }).result["result"]
+
+    behavioral = registry.call("metric_calculator", {
+        "operation": "behavioral_impact",
+        "params": {"observed": log.get("planner_response"),
+                   "counterfactual": log.get("counterfactual_planner_response")},
+    }).result["result"]
+
+    prov = "MetricCalculatorTool (deterministic)"
+    ev: List[EvidenceItem] = []
+    unknown: List[str] = []
+
+    if stopping.get("stopping_distance_m") is not None:
+        ev.append(_drv("stopping_distance", stopping["stopping_distance_m"],
+                       f"stopping distance {stopping['stopping_distance_m']} m "
+                       f"(reaction {stopping['reaction_distance_m']} m + braking "
+                       f"{stopping['braking_distance_m']} m at "
+                       f"{stopping['effective_decel_mps2']} m/s^2 effective decel; "
+                       f"total reaction budget {stopping['total_reaction_time_s']} s "
+                       "incl. perception+planner latency)",
+                       f"{prov} stopping_distance"))
+        if gt.get("distance_m") is not None:
+            ratio = gt["distance_m"] / stopping["stopping_distance_m"]
+            ev.append(_drv("distance_vs_stopping", round(ratio, 3),
+                           f"object range {gt['distance_m']} m is {ratio:.2f}x "
+                           "the stopping distance -> "
+                           + ("INSIDE the stopping envelope"
+                              if ratio <= 1.0 else
+                              ("inside 1.5x criticality envelope" if ratio <= 1.5
+                               else "outside the criticality envelope")),
+                           f"{prov} stopping_distance + observed range"))
+    else:
+        unknown.append("stopping_distance")
+        ev.append(_drv("stopping_distance", None,
+                       f"stopping distance UNKNOWN: {stopping.get('unknown_reason')}",
+                       f"{prov} stopping_distance"))
+
+    if ttc.get("ttc_s") is not None:
+        ev.append(_drv("ttc", ttc["ttc_s"],
+                       f"projected TTC {ttc['ttc_s']} s (SSAM rectangle "
+                       f"projection; closed-form cross-check "
+                       f"{ttc.get('closed_form_ttc_s')} s); validity: "
+                       + "; ".join(ttc.get("validity_flags", [])),
+                       f"{prov} ttc"))
+    else:
+        if ttc.get("unknown_reason"):
+            unknown.append("ttc")
+            ev.append(_drv("ttc", None,
+                           f"TTC UNKNOWN: {ttc['unknown_reason']}", f"{prov} ttc"))
+        else:
+            ev.append(_drv("ttc", "no_predicted_collision",
+                           "no projected collision path (object not closing or "
+                           "beyond look-ahead); validity: "
+                           + "; ".join(ttc.get("validity_flags", [])),
+                           f"{prov} ttc"))
+
+    if scr.get("scr_impact") is not None:
+        ev.append(_drv("scr_impact", scr["scr_impact"],
+                       f"safety-critical recall {scr['scr_baseline']:.4f} -> "
+                       f"{scr['scr_candidate']:.4f} (delta {scr['scr_impact']:+.4f} "
+                       f"over {scr['denominator']} critical objects; criticality: "
+                       f"{scr['criticality_policy']})",
+                       f"{prov} scr_impact"))
+    else:
+        unknown.append("safety_critical_recall_impact")
+        ev.append(_drv("scr_impact", None,
+                       f"SCR impact UNKNOWN: {scr.get('unknown_reason')}",
+                       f"{prov} scr_impact"))
+
+    if behavioral.get("consequence") not in (None, "UNKNOWN"):
+        ev.append(_drv("behavioral_impact", behavioral.get("decel_delta_mps2"),
+                       f"behavioral impact: {behavioral['consequence']}",
+                       f"{prov} behavioral_impact (observed vs corrected-"
+                       "perception counterfactual)"))
+    else:
+        unknown.append("behavioral_impact")
+        ev.append(_drv("behavioral_impact", None,
+                       f"behavioral impact UNKNOWN: {behavioral.get('unknown_reason')}",
+                       f"{prov} behavioral_impact"))
+
+    return EvidenceAnalysis(stopping=stopping, ttc=ttc, scr=scr,
+                            behavioral=behavioral, derived_evidence=ev,
+                            unknown_metrics=unknown)
+
+
+# ---------------------------------------------------------- 3. RAG Agent
+
+def _build_queries(extract: LogExtract) -> List[str]:
+    log = extract.log
+    gt_class = ((log.get("ground_truth") or {}).get("class") or "object").lower()
+    weather = ((log.get("scenario") or {}).get("weather") or "").lower()
+    queries: List[str] = []
+    if extract.failure_type == "FALSE_NEGATIVE":
+        queries.append(f"{gt_class} missed detection inside stopping distance "
+                       "recall requirement")
+        if weather in ("rain", "snow", "fog"):
+            queries.append(f"{weather} degradation detection recall confidence "
+                           "threshold fusion")
+    elif extract.failure_type == "FALSE_POSITIVE":
+        queries.append(f"phantom braking false positive {gt_class} road debris "
+                       "misclassification limits")
+        queries.append("asymmetric false negative false positive cost context")
+    else:
+        queries.append(f"{gt_class} misclassification requirements "
+                       "class stability")
+    queries.append("launch criteria severity gate insufficient evidence")
+    return queries
+
+
+def run_rag_agent(registry: ToolRegistry, extract: LogExtract,
+                  extra_queries: Optional[List[str]] = None,
+                  k: int = 3) -> RAGFindings:
+    queries = _build_queries(extract) + list(extra_queries or [])
+    seen: Dict[str, RetrievedStandard] = {}
+    for q in queries:
+        res = registry.call("safety_standard_rag", {"query": q, "k": k})
+        for hit in (res.result or {}).get("hits", []):
+            std = RetrievedStandard(**hit)
+            if std.chunk_id not in seen or std.relevance_score > seen[std.chunk_id].relevance_score:
+                seen[std.chunk_id] = std
+    standards = sorted(seen.values(), key=lambda s: -s.relevance_score)[:8]
+
+    retrieved_ev = [EvidenceItem(
+        tier=EvidenceTier.RETRIEVED, key=f"standard:{s.doc_id}:{s.chunk_id}",
+        value=f"relevance {s.relevance_score:.2f}",
+        statement=f"[{s.label}] {s.document} v{s.version} §{s.section}: "
+                  f"{s.retrieved_text[:180]}…",
+        provenance=f"SafetyStandardRAGTool hit {s.chunk_id} "
+                   f"(source {s.source})") for s in standards]
+
+    hist = registry.call("historical_failure_search", {
+        "query_text": f"{extract.failure_type} "
+                      f"{json.dumps((extract.log.get('scenario') or {}))[:300]}",
+        "k": 3, "exclude_evaluation_id": extract.log.get("evaluation_id"),
+    }).result or {}
+
+    dist = registry.call("distribution_analysis", {
+        "distribution_shift": (extract.log.get("evaluation_context") or {})
+        .get("distribution_shift"),
+    }).result or {}
+    for m in hist.get("matches", []):
+        retrieved_ev.append(EvidenceItem(
+            tier=EvidenceTier.RETRIEVED, key=f"historical:{m['evaluation_id']}",
+            value=f"similarity {m['similarity']:.2f}",
+            statement=f"prior analyzed failure {m['evaluation_id']} "
+                      f"({m.get('failure_type')}, {m.get('severity')}) is similar",
+            provenance="HistoricalFailureSearchTool"))
+    for f in dist.get("findings", []):
+        retrieved_ev.append(EvidenceItem(
+            tier=EvidenceTier.RETRIEVED, key="distribution_finding",
+            value=None, statement=f,
+            provenance=f"DistributionAnalysisTool ({dist.get('source')})"))
+
+    return RAGFindings(standards=standards, retrieved_evidence=retrieved_ev,
+                       historical_matches=hist.get("matches", []),
+                       distribution_findings=dist.get("findings", []),
+                       distribution_shift=dist.get("shift"),
+                       queries=queries)
+
+
+# -------------------------------------------------- 4. Safety Synthesizer
+
+def _extract_json(text: str) -> Optional[Dict[str, Any]]:
+    m = re.search(r"\{.*\}", text, re.DOTALL)
+    if not m:
+        return None
+    try:
+        return json.loads(m.group(0))
+    except json.JSONDecodeError:
+        return None
+
+
+def run_synthesizer(backend: InferenceBackend, registry: ToolRegistry,
+                    extract: LogExtract, analysis: EvidenceAnalysis,
+                    rag: RAGFindings) -> Tuple[Synthesis, RAGFindings]:
+    """Returns the synthesis plus a possibly-augmented RAGFindings (the LLM
+    may request up to two follow-up retrieval queries, ReAct-style)."""
+    scripted = Synthesis(
+        hypotheses=scripted_hypotheses(extract.failure_type, extract.log,
+                                       extract.missing_fields),
+        ai_proposed_severity=scripted_severity_proposal(extract.log,
+                                                        extract.failure_type),
+        behavioral_consequence=analysis.behavioral.get("consequence", UNKNOWN),
+        provider="scripted-deterministic")
+
+    if backend.name == "mock":
+        return scripted, rag
+
+    prompt = synthesis_prompt(
+        extract.failure_type,
+        [e.model_dump() for e in extract.observed_evidence],
+        [e.model_dump() for e in analysis.derived_evidence],
+        [s.model_dump() for s in rag.standards],
+        extract.missing_fields)
+    try:
+        res = backend.generate(prompt, system=SYSTEM_PROMPT, max_tokens=1400)
+        parsed = _extract_json(res.text)
+    except Exception:
+        parsed = None
+    if not parsed or not parsed.get("hypotheses"):
+        # Honest fallback: model unreachable/unparseable -> scripted analysis,
+        # provider label says so.
+        scripted.provider = f"{backend.name}-fallback-scripted"
+        return scripted, rag
+
+    hyps: List[RootCauseHypothesis] = []
+    for h in parsed["hypotheses"][:4]:
+        try:
+            hyps.append(RootCauseHypothesis(
+                hypothesis=str(h.get("hypothesis", ""))[:600],
+                confidence=max(0.0, min(1.0, float(h.get("confidence", 0.5)))),
+                supporting_evidence_keys=[str(k) for k in
+                                          h.get("supporting_evidence_keys", [])][:8],
+                missing_evidence=[str(k) for k in
+                                  h.get("missing_evidence", [])][:8]))
+        except (TypeError, ValueError):
+            continue
+    sev = None
+    try:
+        sev = Severity(str(parsed.get("proposed_severity", "")).upper())
+    except ValueError:
+        pass
+
+    extra_q = [str(q) for q in parsed.get("additional_queries", [])][:2]
+    if extra_q:
+        rag = run_rag_agent(registry, extract, extra_queries=extra_q)
+
+    model_label = getattr(backend, "model", None) or backend.name
+    return Synthesis(
+        hypotheses=hyps or scripted.hypotheses,
+        ai_proposed_severity=sev or scripted.ai_proposed_severity,
+        behavioral_consequence=str(
+            parsed.get("behavioral_consequence")
+            or analysis.behavioral.get("consequence", UNKNOWN))[:500],
+        provider=f"{backend.name}:{model_label}"), rag
+
+
+# ------------------------------------------------------------- assembly
+
+def _assemble_scorecard(extract: LogExtract, analysis: EvidenceAnalysis,
+                        rag: RAGFindings, synth: Synthesis,
+                        backend_name: str) -> RetrospectiveScorecard:
+    log = extract.log
+    ego = log.get("ego") or {}
+    gt = log.get("ground_truth") or {}
+    pred = log.get("prediction")
+    ec = log.get("evaluation_context") or {}
+    dis = log.get("disengagement") or {}
+    traffic = ((log.get("traffic_context") or {}).get("following_vehicle") or {})
+
+    sev_ctx = SeverityContext(
+        failure_type=extract.failure_type,
+        object_class=gt.get("class"),
+        distance_m=gt.get("distance_m"),
+        stopping_distance_m=analysis.stopping.get("stopping_distance_m"),
+        closing_velocity_mps=gt.get("relative_velocity_mps"),
+        ttc_s=analysis.ttc.get("ttc_s"),
+        total_reaction_time_s=analysis.stopping.get("total_reaction_time_s"),
+        collision_occurred=bool((log.get("collision") or {}).get("occurred")),
+        near_miss=bool((log.get("collision") or {}).get("near_miss")),
+        intervention_decel_mps2=(log.get("planner_response") or {}).get("decel_mps2"),
+        following_gap_s=traffic.get("time_gap_s"),
+        ego_speed_mps=ego.get("speed_mps"))
+    sev_result = compute_severity(sev_ctx)
+    adjudication = adjudicate_severity(sev_result, synth.ai_proposed_severity)
+
+    uncertainty = UncertaintyReport(
+        missing_fields=extract.missing_fields,
+        unknown_metrics=analysis.unknown_metrics,
+        notes=([f"severity adjudication: {adjudication.divergence_note}"]
+               if adjudication.divergence else []))
+
+    sig_raw = ec.get("significance")
+    significance = (StatSignificance(**sig_raw) if sig_raw else
+                    StatSignificance(method="seqeval.PairedSequentialTest",
+                                     significant=None,
+                                     detail="no paired-run significance artifact "
+                                            "attached — not evaluable here"))
+
+    decision = launch_gate(
+        severity=adjudication.final_severity,
+        has_evidence_gaps=uncertainty.has_gaps,
+        scr_impact=analysis.scr.get("scr_impact"),
+        scr_significant=significance.significant)
+
+    policy_ev = [EvidenceItem(
+        tier=EvidenceTier.DERIVED, key="policy_severity",
+        value=adjudication.final_severity.value,
+        statement="deterministic severity: " + " | ".join(sev_result.rule_trace),
+        provenance=f"policy engine {POLICY_VERSION} (compute_severity)")]
+    if adjudication.divergence:
+        policy_ev.append(EvidenceItem(
+            tier=EvidenceTier.DERIVED, key="severity_divergence",
+            value=f"AI={adjudication.ai_proposed_severity.value} "
+                  f"policy={adjudication.final_severity.value}",
+            statement=adjudication.divergence_note,
+            provenance=f"policy engine {POLICY_VERSION} (adjudicate_severity)"))
+
+    hypothesis_ev = [EvidenceItem(
+        tier=EvidenceTier.AI_HYPOTHESIS, key=f"hypothesis_{i + 1}",
+        value=f"confidence {h.confidence:.0%}",
+        statement=h.hypothesis,
+        provenance=f"Safety Synthesizer ({synth.provider}) — inference, not fact")
+        for i, h in enumerate(synth.hypotheses)]
+
+    review_reasons: List[str] = []
+    if adjudication.final_severity in (Severity.CRITICAL, Severity.FATAL):
+        review_reasons.append(f"severity {adjudication.final_severity.value}")
+    if adjudication.divergence:
+        review_reasons.append("AI severity proposal diverged from policy")
+    if uncertainty.has_gaps:
+        review_reasons.append("required evidence UNKNOWN")
+    if len(rag.standards) < 2:
+        review_reasons.append("fewer than two independent retrieved sources")
+
+    return RetrospectiveScorecard(
+        evaluation_id=log.get("evaluation_id", "UNKNOWN-EVAL"),
+        policy_version=POLICY_VERSION,
+        agent_version=AGENT_VERSION,
+        backend_used=synth.provider if backend_name != "mock" else "mock",
+        failure_type=extract.failure_type,
+        severity=adjudication.final_severity,
+        ai_proposed_severity=adjudication.ai_proposed_severity,
+        severity_divergence=adjudication.divergence,
+        safety_critical_recall_impact=analysis.scr.get("scr_impact"),
+        scr_impact_detail=analysis.scr.get("unknown_reason")
+                          or analysis.scr.get("criticality_policy", ""),
+        behavioral_consequence=synth.behavioral_consequence,
+        launch_recommendation=decision.recommendation,
+        launch_rationale=decision.rationale,
+        baseline_model=(log.get("models") or {}).get("baseline"),
+        candidate_model=(log.get("models") or {}).get("candidate"),
+        scenario=log.get("scenario") or {},
+        object_class=gt.get("class"),
+        ground_truth=gt or None,
+        prediction=pred,
+        confidence=(pred or {}).get("confidence") if pred else None,
+        ego_speed_mps=ego.get("speed_mps"),
+        distance_to_object_m=gt.get("distance_m"),
+        relative_velocity_mps=gt.get("relative_velocity_mps"),
+        stopping_distance_m=analysis.stopping.get("stopping_distance_m"),
+        ttc_s=analysis.ttc.get("ttc_s"),
+        ttc_validity=analysis.ttc.get("validity_flags", []),
+        planner_response=log.get("planner_response"),
+        disengagement_probability=dis.get("probability_model"),
+        metric_delta=ec.get("metric_delta"),
+        statistical_significance=significance,
+        distribution_shift=rag.distribution_shift,
+        root_cause_hypotheses=synth.hypotheses,
+        evidence=(extract.observed_evidence + analysis.derived_evidence
+                  + rag.retrieved_evidence + policy_ev + hypothesis_ev),
+        retrieved_standards=rag.standards,
+        uncertainty=uncertainty,
+        human_review_required=bool(review_reasons),
+        human_review_reasons=review_reasons)
+
+
+# ------------------------------------------------------------ entrypoints
+
+def analyze(fixture_id: Optional[str] = None, path: Optional[str] = None,
+            backend: str = "mock", persist: bool = True,
+            registry: Optional[ToolRegistry] = None) -> RetrospectiveScorecard:
+    """Full pipeline on a fixture id or an allowlisted artifact path."""
+    be = get_backend(backend)
+    if be.name != "mock":
+        status = be.health()
+        if not status.available:
+            raise RuntimeError(f"backend '{backend}' unavailable: {status.detail}")
+
+    analysis_key = fixture_id or (path or "adhoc").rsplit("/", 1)[-1].replace(".json", "")
+    reg = registry or build_registry(analysis_id=analysis_key,
+                                     persist_audit=persist)
+
+    extract = run_log_agent(reg, fixture_id=fixture_id, path=path)
+    analysis = run_evidence_analyzer(reg, extract)
+    rag = run_rag_agent(reg, extract)
+    synth, rag = run_synthesizer(be, reg, extract, analysis, rag)
+    scorecard = _assemble_scorecard(extract, analysis, rag, synth, be.name)
+
+    if persist:
+        store.save_analysis(scorecard.evaluation_id, {
+            "scorecard": json.loads(scorecard.model_dump_json()),
+            "markdown": scorecard.render_markdown(),
+            "audit_analysis_id": reg.analysis_id,
+            "stage_summary": {
+                "failure_type_rationale": extract.failure_type_rationale,
+                "rag_queries": rag.queries,
+                "synthesis_provider": synth.provider,
+            },
+        })
+    return scorecard
+
+
+def analyze_fixture(fixture_id: str, backend: str = "mock",
+                    persist: bool = True) -> RetrospectiveScorecard:
+    return analyze(fixture_id=fixture_id, backend=backend, persist=persist)

sensorflow/retro/agent/prompts.py

@@ -0,0 +1,48 @@
+"""Prompts for the LLM-backed synthesis stage (Ollama backend)."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+SYSTEM_PROMPT = (
+    "You are the Safety Synthesizer stage of a retrospective analyzer for an "
+    "autonomous-vehicle perception platform. You interpret evidence and form "
+    "hypotheses. You NEVER compute metrics, NEVER invent telemetry, and NEVER "
+    "make launch determinations — deterministic code owns those. Separate "
+    "fact from inference rigorously: anything not present in the supplied "
+    "evidence must be listed as missing_evidence, not asserted."
+)
+
+
+def synthesis_prompt(failure_type: str, observed: List[Dict[str, Any]],
+                     derived: List[Dict[str, Any]],
+                     retrieved: List[Dict[str, Any]],
+                     missing_fields: List[str]) -> str:
+    return f"""FAILURE TYPE (deterministically derived): {failure_type}
+
+TIER1 OBSERVED FACTS (from the artifact):
+{json.dumps(observed, indent=1)[:3000]}
+
+TIER2 DERIVED METRICS (deterministic calculators):
+{json.dumps(derived, indent=1)[:2500]}
+
+TIER3 RETRIEVED REQUIREMENTS (safety-case retrieval; synthetic-labeled corpus):
+{json.dumps([{k: r[k] for k in ('doc_id', 'section', 'retrieved_text')}
+             for r in retrieved], indent=1)[:2500]}
+
+MISSING ARTIFACT FIELDS (must stay UNKNOWN): {missing_fields}
+
+Respond with ONLY a JSON object:
+{{
+  "hypotheses": [
+    {{"hypothesis": "<causal hypothesis, clearly inference>",
+      "confidence": <0..1>,
+      "supporting_evidence_keys": ["<keys from the observed/derived items>"],
+      "missing_evidence": ["<what you would need to confirm>"]}}
+  ],
+  "proposed_severity": "BENIGN|DISRUPTIVE|CRITICAL|FATAL",
+  "behavioral_consequence": "<one sentence, grounded in the derived metrics>",
+  "additional_queries": ["<up to 2 follow-up safety-case retrieval queries>"]
+}}
+Base every claim on the supplied evidence. 2-4 hypotheses."""

sensorflow/retro/agent/scripted.py

@@ -0,0 +1,133 @@
+"""Deterministic scripted synthesis (mock backend path).
+
+Rule-driven hypothesis generation assembled from the ACTUAL evidence in the
+artifact — the same pattern as the platform's offline MITL copilot
+(sensorflow/evaluation/copilot.py). Never invents telemetry: hypotheses cite
+supporting evidence keys and explicitly list the evidence that is missing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from sensorflow.retro.scorecard import RootCauseHypothesis, Severity
+
+
+def scripted_hypotheses(failure_type: str, log: Dict[str, Any],
+                        missing_fields: List[str]) -> List[RootCauseHypothesis]:
+    gt = log.get("ground_truth") or {}
+    pred = log.get("prediction") or {}
+    scenario = log.get("scenario") or {}
+    sensors = log.get("sensor_metadata") or {}
+    tracks = log.get("tracks") or []
+    hyps: List[RootCauseHypothesis] = []
+
+    gt_class = (gt.get("class") or "").lower()
+    weather = (scenario.get("weather") or "").lower()
+    flicker = any(t.get("class_flicker") for t in tracks)
+
+    if failure_type == "FALSE_POSITIVE" and gt_class in (
+            "plastic_bag", "debris", "cardboard", "balloon"):
+        hyps.append(RootCauseHypothesis(
+            hypothesis="Training-distribution gap for wind-blown deformable "
+                       "low-mass objects: the detector assigned a hazardous "
+                       "class with high confidence to a non-hazard object, "
+                       "consistent with the historical phantom-braking cluster "
+                       "(RETRO-2025-014 [SYNTHETIC]).",
+            confidence=0.65,
+            supporting_evidence_keys=["gt_class", "pred_class", "pred_confidence"]
+                                     + (["track_class_flicker"] if flicker else []),
+            missing_evidence=["camera embeddings for the misclassified frames",
+                              "training-set frequency of deformable clutter"]))
+        if "velocity_note" in pred or any(
+                t.get("velocity_variance") == "high" for t in tracks):
+            hyps.append(RootCauseHypothesis(
+                hypothesis="Tracker velocity latch: bag flutter was integrated "
+                           "into a spurious closing velocity, converting a "
+                           "static-clutter FP into a phantom emergency brake.",
+                confidence=0.55,
+                supporting_evidence_keys=["pred_relative_velocity",
+                                          "gt_relative_velocity",
+                                          "track_velocity_variance"],
+                missing_evidence=["raw radar doppler track for the object"]))
+
+    elif failure_type == "FALSE_NEGATIVE" and gt_class in (
+            "pedestrian", "cyclist", "motorcycle", "wheelchair"):
+        if weather in ("rain", "snow", "fog"):
+            cam = (sensors.get("camera") or {}).get("status", "")
+            lid = (sensors.get("lidar") or {}).get("status", "")
+            hyps.append(RootCauseHypothesis(
+                hypothesis=f"Fusion confidence starvation under {weather}: "
+                           f"camera '{cam}' and LiDAR '{lid}' each degraded, "
+                           "and the fusion confidence stayed below the tracking "
+                           "threshold instead of applying weather-conditioned "
+                           "weighting (pattern matches RETRO-2025-021 "
+                           "[SYNTHETIC]).",
+                confidence=0.6,
+                supporting_evidence_keys=["sensor_camera_status",
+                                          "sensor_lidar_status",
+                                          "pred_confidence",
+                                          "pred_detection_delay"],
+                missing_evidence=["per-frame fusion confidence trace",
+                                  "confidence threshold config for this release"]))
+        hyps.append(RootCauseHypothesis(
+            hypothesis="Training-data coverage gap for this VRU appearance/"
+                       "condition slice; the distribution-shift slice data "
+                       "shows the regression concentrated rather than uniform.",
+            confidence=0.5,
+            supporting_evidence_keys=["distribution_shift", "metric_delta"],
+            missing_evidence=["slice-level training data counts"]))
+
+    elif failure_type == "FALSE_POSITIVE":
+        hyps.append(RootCauseHypothesis(
+            hypothesis="Static-scene classification ambiguity: a fixed roadside "
+                       "asset was transiently classified as a dynamic hazard; "
+                       "map-prior fusion did not veto the detection.",
+            confidence=0.5,
+            supporting_evidence_keys=["gt_class", "pred_class",
+                                      "pred_confidence"],
+            missing_evidence=["map-prior veto decision log"]))
+
+    elif failure_type == "FALSE_NEGATIVE":
+        hyps.append(RootCauseHypothesis(
+            hypothesis="Detection miss on a low-salience static object; range "
+                       "sparsity is the most consistent factor given nominal "
+                       "sensor status.",
+            confidence=0.45,
+            supporting_evidence_keys=["gt_distance", "sensor_lidar_status"],
+            missing_evidence=["point count inside the ground-truth box"]))
+
+    if not hyps:
+        hyps.append(RootCauseHypothesis(
+            hypothesis="Insufficient patterns matched for a specific causal "
+                       "hypothesis; requires human investigation.",
+            confidence=0.3, supporting_evidence_keys=[],
+            missing_evidence=["additional telemetry"]))
+
+    if missing_fields:
+        for h in hyps:
+            for f in missing_fields:
+                marker = f"artifact field {f}"
+                if marker not in h.missing_evidence:
+                    h.missing_evidence.append(marker)
+    return hyps
+
+
+def scripted_severity_proposal(log: Dict[str, Any],
+                               failure_type: str) -> Optional[Severity]:
+    """The mock 'LLM proposal' — a deliberately simpler heuristic than the
+    policy engine, so the policy-validate/override flow is real."""
+    collision = (log.get("collision") or {})
+    planner = (log.get("planner_response") or {})
+    traffic = ((log.get("traffic_context") or {}).get("following_vehicle") or {})
+    if collision.get("occurred"):
+        return Severity.FATAL
+    if collision.get("near_miss"):
+        return Severity.CRITICAL
+    decel = planner.get("decel_mps2") or 0.0
+    gap = traffic.get("time_gap_s")
+    if decel >= 3.4 and gap is not None and gap < 1.5:
+        return Severity.CRITICAL
+    if decel >= 3.0:
+        return Severity.DISRUPTIVE
+    return Severity.BENIGN

sensorflow/retro/api.py

@@ -0,0 +1,135 @@
+"""FastAPI router for the Agentic Retrospective Safety Analyzer.
+
+Mounted at /api/retro by app_backend.py. Artifacts persist under runs/retro/.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from fastapi import APIRouter, Body, HTTPException, Query
+
+from sensorflow.retro import store
+from sensorflow.retro.agent.orchestrator import analyze
+from sensorflow.retro.inference.client import all_backend_statuses
+from sensorflow.retro.inference.compat import check_vllm_compatibility, format_report
+from sensorflow.retro.inference.env_detect import detect_environment
+from sensorflow.retro.rag.evalharness import run_retrieval_eval
+from sensorflow.retro.rag.retriever import get_index
+from sensorflow.retro.tools.builtin import FIXTURES_DIR, build_registry
+
+router = APIRouter(prefix="/api/retro", tags=["retro"])
+
+
+@router.get("/env")
+def env_report():
+    env = detect_environment()
+    return {"status": "ok", "environment": env.model_dump()}
+
+
+@router.get("/compat")
+def compat_report(model_name: str = "meta-llama/Llama-3.1-8B-Instruct",
+                  quantization: str = "none"):
+    env = detect_environment(probe_ollama=False)
+    report = check_vllm_compatibility(env, model_name=model_name,
+                                      quantization=quantization)
+    return {"status": "ok", "report": report.model_dump(),
+            "formatted": format_report(report)}
+
+
+@router.get("/backends")
+def backends_status():
+    return {"status": "ok",
+            "backends": [s.model_dump() for s in all_backend_statuses()]}
+
+
+@router.get("/rag/search")
+def rag_search(q: str = Query(min_length=3), k: int = Query(4, ge=1, le=10)):
+    index = get_index()
+    hits = index.search(q, k=k)
+    return {"status": "ok", "store_backend": index.backend_name,
+            "hits": [h.model_dump() for h in hits]}
+
+
+@router.get("/rag/eval")
+def rag_eval(k: int = Query(4, ge=1, le=10)):
+    return {"status": "ok", "report": run_retrieval_eval(k=k).model_dump()}
+
+
+@router.get("/fixtures")
+def list_fixtures():
+    out = []
+    for p in sorted(Path(FIXTURES_DIR).glob("*.json")):
+        try:
+            data = json.loads(p.read_text())
+            out.append({
+                "fixture_id": p.stem,
+                "evaluation_id": data.get("evaluation_id"),
+                "description": (data.get("scenario") or {}).get("description", ""),
+                "weather": (data.get("scenario") or {}).get("weather"),
+            })
+        except (json.JSONDecodeError, OSError):
+            continue
+    return {"status": "ok", "fixtures": out}
+
+
+@router.post("/analyze")
+def analyze_failure(fixture_id: Optional[str] = None,
+                    backend: str = Query("mock", pattern="^(mock|ollama|vllm)$"),
+                    log: Optional[Dict[str, Any]] = Body(None)):
+    """Analyze a fixture by id, or an uploaded JSON eval log in the body."""
+    if not fixture_id and not log:
+        raise HTTPException(status_code=400,
+                            detail="provide ?fixture_id= or a JSON log body")
+    try:
+        if fixture_id:
+            scorecard = analyze(fixture_id=fixture_id, backend=backend)
+        else:
+            eval_id = log.get("evaluation_id", "uploaded")
+            safe = "".join(c for c in eval_id if c.isalnum() or c in "-_")[:64]
+            upload_path = store.uploads_dir() / f"{safe or 'uploaded'}.json"
+            upload_path.write_text(json.dumps(log, indent=2))
+            scorecard = analyze(path=str(upload_path), backend=backend)
+    except FileNotFoundError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except RuntimeError as exc:  # backend unavailable
+        raise HTTPException(status_code=503, detail=str(exc))
+    return {"status": "ok",
+            "scorecard": json.loads(scorecard.model_dump_json()),
+            "markdown": scorecard.render_markdown()}
+
+
+@router.get("/analyses")
+def list_analyses():
+    return {"status": "ok", "analyses": store.list_analyses()}
+
+
+@router.get("/analyses/{evaluation_id}")
+def get_analysis(evaluation_id: str):
+    data = store.load_analysis(evaluation_id)
+    if data is None:
+        raise HTTPException(status_code=404,
+                            detail=f"no analysis for {evaluation_id}")
+    return {"status": "ok", **data}
+
+
+@router.get("/analyses/{evaluation_id}/audit")
+def get_audit(evaluation_id: str):
+    data = store.load_analysis(evaluation_id)
+    if data is None:
+        raise HTTPException(status_code=404,
+                            detail=f"no analysis for {evaluation_id}")
+    audit_id = data.get("audit_analysis_id", evaluation_id)
+    return {"status": "ok", "audit_analysis_id": audit_id,
+            "records": store.read_audit(audit_id)}
+
+
+@router.get("/tools")
+def tool_registry_listing():
+    reg = build_registry(persist_audit=False)
+    return {"status": "ok",
+            "tools": [s.model_dump() for s in reg.specs()],
+            "note": "write tools require policy_authorization=true per call; "
+                    "all calls are audited"}

sensorflow/retro/fixtures/benign_fp_static_sign.json

@@ -0,0 +1,85 @@
+{
+  "evaluation_id": "EVAL-2026-0805-BF01",
+  "artifact_kind": "perception_failure_eval_log",
+  "scenario": {
+    "scenario_id": "SCN-SUB-207-A",
+    "description": "Suburban street, clear day. A roadside sign at 55 m is briefly detected as a stopped vehicle in the shoulder; planner applies a gentle precautionary slowdown; no following traffic. Benign false positive.",
+    "road_type": "suburban_street",
+    "weather": "clear",
+    "rain_rate_mmh": 0.0,
+    "time_of_day": "day",
+    "odd_status": "inside",
+    "posted_speed_mps": 13.4
+  },
+  "models": {
+    "baseline": "percept-bev-v41.2",
+    "candidate": "percept-bev-v42.0"
+  },
+  "sensor_metadata": {
+    "camera": {"status": "nominal", "fps": 30},
+    "lidar": {"status": "nominal", "returns_density": "normal", "fps": 10},
+    "radar": {"status": "nominal", "note": "static return, zero doppler"}
+  },
+  "ego": {
+    "speed_mps": 12.0,
+    "heading_deg": 0.0,
+    "grade": 0.0,
+    "road_friction_estimate": 0.8,
+    "lane": 1
+  },
+  "ground_truth": {
+    "object_id": "gt-1180",
+    "class": "traffic_sign",
+    "distance_m": 55.0,
+    "lateral_offset_m": 3.2,
+    "relative_velocity_mps": 0.0,
+    "dimensions_m": [0.1, 0.8, 2.2],
+    "source": "map-verified static asset"
+  },
+  "prediction": {
+    "object_id": "det-45520",
+    "class": "vehicle",
+    "confidence": 0.58,
+    "distance_m": 54.6,
+    "relative_velocity_mps": 0.0,
+    "track_id": "trk-902",
+    "class_history": ["vehicle", "vehicle", "traffic_sign"],
+    "detection_delay_s": 0.0,
+    "note": "resolved to traffic_sign after 3 frames"
+  },
+  "tracks": [
+    {"track_id": "trk-902", "frames": 3, "class_flicker": true,
+     "velocity_variance": "none", "id_switches": 0}
+  ],
+  "timing": {
+    "detection_latency_ms": 110,
+    "planner_latency_ms": 70
+  },
+  "planner_response": {
+    "action": "precautionary_slowdown",
+    "decel_mps2": 1.2,
+    "response_time_s": 0.6
+  },
+  "counterfactual_planner_response": {
+    "action": "maintain_speed",
+    "decel_mps2": 0.0,
+    "response_time_s": 0.6,
+    "source": "resim replay with corrected static-sign classification"
+  },
+  "traffic_context": {
+    "following_vehicle": {"present": true, "time_gap_s": 4.2, "speed_mps": 11.8}
+  },
+  "disengagement": {"occurred": false, "probability_model": 0.03},
+  "collision": {"occurred": false, "near_miss": false},
+  "evaluation_context": {
+    "critical_object_count": 1240,
+    "baseline_missed_critical": 3,
+    "candidate_missed_critical": 3,
+    "metric_delta": {"vehicle_precision": -0.004},
+    "significance": {
+      "method": "seqeval.PairedSequentialTest",
+      "significant": false,
+      "detail": "precision delta CS includes 0 at alpha=0.05 (from run artifact)"
+    }
+  }
+}

sensorflow/retro/fixtures/missed_pedestrian_rain.json

@@ -0,0 +1,99 @@
+{
+  "evaluation_id": "EVAL-2026-0802-MP01",
+  "artifact_kind": "perception_failure_eval_log",
+  "scenario": {
+    "scenario_id": "SCN-URB-042-R",
+    "description": "Urban arterial, moderate rain at night. Pedestrian in dark clothing crosses mid-block. Detection is 1.9 s late; the pedestrian is inside ego stopping distance when finally tracked; planner executes a delayed hard brake; near-miss with safety-driver disengagement.",
+    "road_type": "urban_arterial",
+    "weather": "rain",
+    "rain_rate_mmh": 18.0,
+    "time_of_day": "night",
+    "odd_status": "inside",
+    "posted_speed_mps": 15.6
+  },
+  "models": {
+    "baseline": "percept-bev-v41.2",
+    "candidate": "percept-bev-v42.0"
+  },
+  "sensor_metadata": {
+    "camera": {"status": "degraded_contrast", "exposure": "night_mode", "fps": 30,
+               "note": "wet-road glare and low pedestrian contrast"},
+    "lidar": {"status": "attenuated", "returns_density": "reduced_by_spray", "fps": 10},
+    "radar": {"status": "nominal", "note": "weak return, pedestrian RCS at range"}
+  },
+  "ego": {
+    "speed_mps": 13.4,
+    "heading_deg": 0.0,
+    "grade": -0.02,
+    "road_friction_estimate": 0.5,
+    "lane": 1
+  },
+  "ground_truth": {
+    "object_id": "gt-7742",
+    "class": "pedestrian",
+    "distance_m": 26.0,
+    "lateral_offset_m": 1.1,
+    "relative_velocity_mps": 13.9,
+    "dimensions_m": [0.6, 0.6, 1.7],
+    "crossing": true,
+    "source": "human-verified replay label"
+  },
+  "prediction": {
+    "object_id": "det-91027",
+    "class": "pedestrian",
+    "confidence": 0.34,
+    "distance_m": 14.8,
+    "relative_velocity_mps": 13.1,
+    "track_id": "trk-551",
+    "class_history": ["unknown", "unknown", "pedestrian"],
+    "detection_delay_s": 1.9,
+    "note": "fusion confidence below tracking threshold for 6 consecutive frames before track confirmation"
+  },
+  "tracks": [
+    {"track_id": "trk-551", "frames": 4, "class_flicker": true,
+     "velocity_variance": "moderate", "id_switches": 0,
+     "confirmation_delay_frames": 6}
+  ],
+  "timing": {
+    "detection_latency_ms": 180,
+    "planner_latency_ms": 100
+  },
+  "planner_response": {
+    "action": "emergency_brake",
+    "decel_mps2": 8.0,
+    "response_time_s": 2.4,
+    "lateral_action": "partial_swerve_left"
+  },
+  "counterfactual_planner_response": {
+    "action": "controlled_brake",
+    "decel_mps2": 3.5,
+    "response_time_s": 0.5,
+    "source": "resim replay with on-time pedestrian detection"
+  },
+  "traffic_context": {
+    "following_vehicle": {"present": false, "time_gap_s": null, "speed_mps": null}
+  },
+  "disengagement": {
+    "occurred": true,
+    "probability_model": 0.87,
+    "note": "safety driver braked simultaneously with the late system response"
+  },
+  "collision": {"occurred": false, "near_miss": true, "min_gap_m": 1.6},
+  "evaluation_context": {
+    "critical_object_count": 1240,
+    "baseline_missed_critical": 3,
+    "candidate_missed_critical": 6,
+    "metric_delta": {"recall_pedestrian_rain": -0.021, "recall_pedestrian_overall": -0.006},
+    "significance": {
+      "method": "seqeval.PairedSequentialTest",
+      "significant": true,
+      "detail": "pedestrian-rain recall regression CS excludes 0 at alpha=0.05 (from run artifact)"
+    },
+    "distribution_shift": {
+      "slice": "pedestrian_rain_night",
+      "candidate_fn_rate": 0.048,
+      "baseline_fn_rate": 0.021,
+      "relative_change": 1.29
+    }
+  }
+}

sensorflow/retro/fixtures/missing_telemetry_variant.json

@@ -0,0 +1,70 @@
+{
+  "evaluation_id": "EVAL-2026-0802-MT01",
+  "artifact_kind": "perception_failure_eval_log",
+  "scenario": {
+    "scenario_id": "SCN-URB-042-R-degraded",
+    "description": "Same missed-pedestrian-in-rain event as EVAL-2026-0802-MP01, but the telemetry pipeline dropped the CAN segment: ego speed, relative velocity, and the resim counterfactual are absent. The analyzer must mark the derived safety metrics UNKNOWN, never guess them.",
+    "road_type": "urban_arterial",
+    "weather": "rain",
+    "rain_rate_mmh": 18.0,
+    "time_of_day": "night",
+    "odd_status": "inside",
+    "posted_speed_mps": 15.6
+  },
+  "models": {
+    "baseline": "percept-bev-v41.2",
+    "candidate": "percept-bev-v42.0"
+  },
+  "sensor_metadata": {
+    "camera": {"status": "degraded_contrast", "exposure": "night_mode", "fps": 30},
+    "lidar": {"status": "attenuated", "returns_density": "reduced_by_spray", "fps": 10},
+    "radar": {"status": "telemetry_dropout"}
+  },
+  "ego": {
+    "heading_deg": 0.0,
+    "grade": -0.02,
+    "road_friction_estimate": 0.5,
+    "lane": 1,
+    "telemetry_note": "speed_mps absent: CAN log segment lost in upload"
+  },
+  "ground_truth": {
+    "object_id": "gt-7742",
+    "class": "pedestrian",
+    "distance_m": 26.0,
+    "lateral_offset_m": 1.1,
+    "dimensions_m": [0.6, 0.6, 1.7],
+    "crossing": true,
+    "source": "human-verified replay label"
+  },
+  "prediction": {
+    "object_id": "det-91027",
+    "class": "pedestrian",
+    "confidence": 0.34,
+    "distance_m": 14.8,
+    "track_id": "trk-551",
+    "class_history": ["unknown", "unknown", "pedestrian"],
+    "detection_delay_s": 1.9
+  },
+  "tracks": [
+    {"track_id": "trk-551", "frames": 4, "class_flicker": true,
+     "velocity_variance": "moderate", "id_switches": 0}
+  ],
+  "timing": {
+    "detection_latency_ms": 180,
+    "planner_latency_ms": 100
+  },
+  "planner_response": {
+    "action": "emergency_brake",
+    "decel_mps2": 8.0,
+    "response_time_s": 2.4
+  },
+  "traffic_context": {},
+  "disengagement": {
+    "occurred": true,
+    "probability_model": 0.87
+  },
+  "collision": {"occurred": false, "near_miss": true},
+  "evaluation_context": {
+    "metric_delta": {"recall_pedestrian_rain": -0.021}
+  }
+}

sensorflow/retro/fixtures/noncritical_fn_parked_vehicle.json

@@ -0,0 +1,73 @@
+{
+  "evaluation_id": "EVAL-2026-0806-NF01",
+  "artifact_kind": "perception_failure_eval_log",
+  "scenario": {
+    "scenario_id": "SCN-RES-330-B",
+    "description": "Residential street, low speed. A parked vehicle 87 m ahead on the shoulder is missed for several frames. Ego is slow, the object is static and far outside stopping distance, and no maneuver was required. Benign, non-critical false negative.",
+    "road_type": "residential",
+    "weather": "clear",
+    "rain_rate_mmh": 0.0,
+    "time_of_day": "day",
+    "odd_status": "inside",
+    "posted_speed_mps": 11.2
+  },
+  "models": {
+    "baseline": "percept-bev-v41.2",
+    "candidate": "percept-bev-v42.0"
+  },
+  "sensor_metadata": {
+    "camera": {"status": "nominal", "fps": 30},
+    "lidar": {"status": "nominal", "returns_density": "sparse_at_range", "fps": 10},
+    "radar": {"status": "nominal"}
+  },
+  "ego": {
+    "speed_mps": 8.3,
+    "heading_deg": 0.0,
+    "grade": 0.0,
+    "road_friction_estimate": 0.75,
+    "lane": 1
+  },
+  "ground_truth": {
+    "object_id": "gt-5521",
+    "class": "vehicle",
+    "distance_m": 87.0,
+    "lateral_offset_m": 2.8,
+    "relative_velocity_mps": -0.2,
+    "dimensions_m": [4.4, 1.8, 1.5],
+    "parked": true,
+    "source": "human-verified replay label"
+  },
+  "prediction": null,
+  "tracks": [],
+  "timing": {
+    "detection_latency_ms": 130,
+    "planner_latency_ms": 75
+  },
+  "planner_response": {
+    "action": "maintain_speed",
+    "decel_mps2": 0.0,
+    "response_time_s": 0.0
+  },
+  "counterfactual_planner_response": {
+    "action": "maintain_speed",
+    "decel_mps2": 0.0,
+    "response_time_s": 0.0,
+    "source": "resim replay with the parked vehicle detected: identical plan"
+  },
+  "traffic_context": {
+    "following_vehicle": {"present": false, "time_gap_s": null, "speed_mps": null}
+  },
+  "disengagement": {"occurred": false, "probability_model": 0.01},
+  "collision": {"occurred": false, "near_miss": false},
+  "evaluation_context": {
+    "critical_object_count": 1240,
+    "baseline_missed_critical": 3,
+    "candidate_missed_critical": 3,
+    "metric_delta": {"vehicle_recall_static_far": -0.008},
+    "significance": {
+      "method": "seqeval.PairedSequentialTest",
+      "significant": false,
+      "detail": "far-static recall delta CS includes 0 at alpha=0.05 (from run artifact)"
+    }
+  }
+}

sensorflow/retro/fixtures/phantom_brake_plastic_bag.json

@@ -0,0 +1,97 @@
+{
+  "evaluation_id": "EVAL-2026-0731-PB01",
+  "artifact_kind": "perception_failure_eval_log",
+  "scenario": {
+    "scenario_id": "SCN-HWY-118-C",
+    "description": "Divided highway, light traffic. Wind-blown plastic bag crosses lanes ahead of ego; perception classifies it as a vehicle with spurious closing velocity; planner executes an unwarranted emergency brake with a close follower behind.",
+    "road_type": "divided_highway",
+    "weather": "clear",
+    "rain_rate_mmh": 0.0,
+    "time_of_day": "day",
+    "odd_status": "inside",
+    "posted_speed_mps": 29.1
+  },
+  "models": {
+    "baseline": "percept-bev-v41.2",
+    "candidate": "percept-bev-v42.0"
+  },
+  "sensor_metadata": {
+    "camera": {"status": "nominal", "exposure": "auto", "fps": 30},
+    "lidar": {"status": "nominal", "returns_density": "normal", "fps": 10},
+    "radar": {"status": "nominal", "note": "low RCS return consistent with low-mass object"}
+  },
+  "ego": {
+    "speed_mps": 24.6,
+    "heading_deg": 0.0,
+    "grade": 0.0,
+    "road_friction_estimate": 0.85,
+    "lane": 2
+  },
+  "ground_truth": {
+    "object_id": "gt-3312",
+    "class": "plastic_bag",
+    "distance_m": 38.2,
+    "lateral_offset_m": 0.4,
+    "relative_velocity_mps": 1.2,
+    "dimensions_m": [0.5, 0.4, 0.3],
+    "mass_plausibility": "low_mass_deformable",
+    "source": "human-verified replay label"
+  },
+  "prediction": {
+    "object_id": "det-88410",
+    "class": "vehicle",
+    "confidence": 0.91,
+    "distance_m": 37.9,
+    "relative_velocity_mps": 9.8,
+    "track_id": "trk-204",
+    "class_history": ["unknown", "vehicle", "vehicle", "vehicle"],
+    "detection_delay_s": 0.0,
+    "velocity_note": "tracker latched bag flutter as closing velocity toward ego"
+  },
+  "tracks": [
+    {"track_id": "trk-204", "frames": 11, "class_flicker": true,
+     "velocity_variance": "high", "id_switches": 0}
+  ],
+  "timing": {
+    "detection_latency_ms": 120,
+    "planner_latency_ms": 80
+  },
+  "planner_response": {
+    "action": "emergency_brake",
+    "decel_mps2": 6.2,
+    "response_time_s": 0.4,
+    "lateral_action": null
+  },
+  "counterfactual_planner_response": {
+    "action": "maintain_speed",
+    "decel_mps2": 0.0,
+    "response_time_s": 0.4,
+    "source": "resim replay with corrected perception (bag labeled low-mass debris)"
+  },
+  "traffic_context": {
+    "following_vehicle": {"present": true, "time_gap_s": 0.9, "speed_mps": 25.1}
+  },
+  "disengagement": {
+    "occurred": false,
+    "probability_model": 0.41,
+    "note": "safety driver hands hovered; no takeover"
+  },
+  "collision": {"occurred": false, "near_miss": false, "induced_rear_risk": true},
+  "evaluation_context": {
+    "critical_object_count": 1240,
+    "baseline_missed_critical": 3,
+    "candidate_missed_critical": 3,
+    "metric_delta": {"phantom_brake_rate_per_1k_km": 0.8, "vehicle_precision": -0.011},
+    "significance": {
+      "method": "seqeval.PairedSequentialTest",
+      "significant": false,
+      "detail": "phantom-brake rate delta CS still includes 0 at alpha=0.05 (from run artifact)"
+    },
+    "distribution_shift": {
+      "slice": "highway_debris_windblown",
+      "candidate_fp_rate": 0.034,
+      "baseline_fp_rate": 0.012,
+      "relative_change": 1.83
+    }
+  }
+}

sensorflow/retro/inference/__init__.py

@@ -0,0 +1,2 @@
+"""Inference foundation: environment detection, vLLM compatibility chain,
+and the pluggable backend client (vllm | ollama | mock)."""

sensorflow/retro/inference/client.py

@@ -0,0 +1,272 @@
+"""Pluggable inference client: vllm | ollama | mock backends.
+
+All backends implement the same contract:
+    health()  -> BackendStatus (never raises)
+    generate(prompt, system, max_tokens) -> InferenceResult with token counts
+                                            and wall-clock latency
+    validate() -> deterministic test-prompt round trip
+
+The mock backend is the default for tests: fully deterministic, no network.
+The ollama backend follows the platform's existing local pattern
+(sensorflow/evaluation/copilot.py). The vllm backend targets any
+OpenAI-compatible endpoint and is only exercisable on CUDA/ROCm hosts —
+see sensorflow/retro/inference/vllm_server/.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import time
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+import httpx
+from pydantic import BaseModel, Field
+
+VALIDATION_PROMPT = "Respond with exactly the token RETRO-OK and nothing else."
+VALIDATION_EXPECT = "RETRO-OK"
+
+DEFAULT_OLLAMA_URL = os.environ.get("RETRO_OLLAMA_URL", "http://localhost:11434")
+DEFAULT_VLLM_URL = os.environ.get("RETRO_VLLM_URL", "http://localhost:8001/v1")
+
+
+class InferenceResult(BaseModel):
+    backend: str
+    model: str
+    text: str
+    prompt_tokens: int
+    completion_tokens: int
+    latency_ms: float
+    notes: str = ""
+
+
+class BackendStatus(BaseModel):
+    backend: str
+    available: bool
+    endpoint: Optional[str] = None
+    model: Optional[str] = None
+    detail: str = ""
+    health_latency_ms: Optional[float] = None
+
+
+class ValidationResult(BaseModel):
+    backend: str
+    passed: bool
+    expected: str
+    got: str
+    latency_ms: float
+    prompt_tokens: int
+    completion_tokens: int
+    detail: str = ""
+
+
+class InferenceBackend(ABC):
+    name: str = "abstract"
+
+    @abstractmethod
+    def health(self) -> BackendStatus: ...
+
+    @abstractmethod
+    def generate(self, prompt: str, system: Optional[str] = None,
+                 max_tokens: int = 1024) -> InferenceResult: ...
+
+    def validate(self) -> ValidationResult:
+        """Deterministic test-prompt inference validation with latency."""
+        t0 = time.perf_counter()
+        try:
+            res = self.generate(VALIDATION_PROMPT, max_tokens=16)
+        except Exception as exc:
+            return ValidationResult(backend=self.name, passed=False,
+                                    expected=VALIDATION_EXPECT, got="",
+                                    latency_ms=(time.perf_counter() - t0) * 1000,
+                                    prompt_tokens=0, completion_tokens=0,
+                                    detail=f"generate failed: {exc}")
+        passed = VALIDATION_EXPECT in res.text
+        return ValidationResult(backend=self.name, passed=passed,
+                                expected=VALIDATION_EXPECT, got=res.text.strip()[:200],
+                                latency_ms=res.latency_ms,
+                                prompt_tokens=res.prompt_tokens,
+                                completion_tokens=res.completion_tokens,
+                                detail="" if passed else
+                                "model reply did not contain the expected token")
+
+
+def _approx_tokens(text: str) -> int:
+    """Deterministic whitespace-ish token approximation (mock backend only)."""
+    return max(1, len(text.split())) if text else 0
+
+
+class MockBackend(InferenceBackend):
+    """Deterministic, offline. Replies are pure functions of the prompt.
+
+    The retrospective agent does NOT parse mock replies for analysis content —
+    in mock mode the analysis itself is produced by the deterministic scripted
+    path (sensorflow/retro/agent). The mock backend exists to satisfy the
+    client contract (health/generate/validate) without any model.
+    """
+
+    name = "mock"
+
+    def health(self) -> BackendStatus:
+        return BackendStatus(backend="mock", available=True, endpoint=None,
+                             model="deterministic-mock",
+                             detail="always available; replies are deterministic "
+                                    "functions of the prompt", health_latency_ms=0.0)
+
+    def generate(self, prompt: str, system: Optional[str] = None,
+                 max_tokens: int = 1024) -> InferenceResult:
+        t0 = time.perf_counter()
+        if VALIDATION_EXPECT in prompt or "RETRO-OK" in prompt:
+            text = VALIDATION_EXPECT
+        else:
+            digest = hashlib.sha256(((system or "") + "\n" + prompt).encode()).hexdigest()[:12]
+            text = f"[mock-response {digest}] Deterministic placeholder reply."
+        return InferenceResult(
+            backend="mock", model="deterministic-mock", text=text,
+            prompt_tokens=_approx_tokens((system or "") + " " + prompt),
+            completion_tokens=_approx_tokens(text),
+            latency_ms=(time.perf_counter() - t0) * 1000,
+            notes="deterministic mock; token counts are whitespace approximations")
+
+
+class OllamaBackend(InferenceBackend):
+    """Local Ollama server (Metal/CPU on this machine — NOT vLLM numbers)."""
+
+    name = "ollama"
+
+    def __init__(self, base_url: str = DEFAULT_OLLAMA_URL,
+                 model: Optional[str] = None, timeout: float = 120.0):
+        self.base_url = base_url.rstrip("/")
+        self.model = model or os.environ.get("RETRO_OLLAMA_MODEL", "")
+        self.timeout = timeout
+
+    def _pick_model(self) -> Optional[str]:
+        if self.model:
+            return self.model
+        try:
+            res = httpx.get(f"{self.base_url}/api/tags", timeout=3.0)
+            models = [m.get("name") for m in res.json().get("models", [])]
+            self.model = models[0] if models else None
+        except Exception:
+            self.model = None
+        return self.model
+
+    def health(self) -> BackendStatus:
+        t0 = time.perf_counter()
+        try:
+            res = httpx.get(f"{self.base_url}/api/tags", timeout=3.0)
+            ms = (time.perf_counter() - t0) * 1000
+            if res.status_code == 200:
+                models = [m.get("name") for m in res.json().get("models", [])]
+                return BackendStatus(backend="ollama", available=True,
+                                     endpoint=self.base_url,
+                                     model=self.model or (models[0] if models else None),
+                                     detail=f"{len(models)} model(s) installed",
+                                     health_latency_ms=round(ms, 1))
+            return BackendStatus(backend="ollama", available=False,
+                                 endpoint=self.base_url,
+                                 detail=f"HTTP {res.status_code} from /api/tags")
+        except Exception as exc:
+            return BackendStatus(backend="ollama", available=False,
+                                 endpoint=self.base_url,
+                                 detail=f"unreachable: {exc.__class__.__name__}: {exc}")
+
+    def generate(self, prompt: str, system: Optional[str] = None,
+                 max_tokens: int = 1024) -> InferenceResult:
+        model = self._pick_model()
+        if not model:
+            raise RuntimeError(f"no Ollama model available at {self.base_url}")
+        messages = ([{"role": "system", "content": system}] if system else []) + [
+            {"role": "user", "content": prompt}]
+        t0 = time.perf_counter()
+        res = httpx.post(f"{self.base_url}/api/chat",
+                         json={"model": model, "messages": messages, "stream": False,
+                               "options": {"num_predict": max_tokens}},
+                         timeout=self.timeout)
+        latency_ms = (time.perf_counter() - t0) * 1000
+        res.raise_for_status()
+        body = res.json()
+        return InferenceResult(
+            backend="ollama", model=model,
+            text=body.get("message", {}).get("content", ""),
+            prompt_tokens=int(body.get("prompt_eval_count", 0)),
+            completion_tokens=int(body.get("eval_count", 0)),
+            latency_ms=round(latency_ms, 1),
+            notes="Ollama on local CPU/Metal — these are NOT vLLM/GPU numbers")
+
+
+class VLLMBackend(InferenceBackend):
+    """OpenAI-compatible vLLM endpoint. Only runnable against a CUDA/ROCm host
+    (see vllm_server/); on this macOS machine health() honestly reports it
+    unavailable unless a remote endpoint is configured."""
+
+    name = "vllm"
+
+    def __init__(self, base_url: str = DEFAULT_VLLM_URL,
+                 model: Optional[str] = None, timeout: float = 120.0):
+        self.base_url = base_url.rstrip("/")
+        self.model = model or os.environ.get("RETRO_VLLM_MODEL", "")
+        self.timeout = timeout
+
+    def health(self) -> BackendStatus:
+        t0 = time.perf_counter()
+        try:
+            res = httpx.get(f"{self.base_url}/models", timeout=3.0)
+            ms = (time.perf_counter() - t0) * 1000
+            if res.status_code == 200:
+                models = [m.get("id") for m in res.json().get("data", [])]
+                return BackendStatus(backend="vllm", available=True,
+                                     endpoint=self.base_url,
+                                     model=self.model or (models[0] if models else None),
+                                     detail=f"OpenAI-compatible server, models: {models}",
+                                     health_latency_ms=round(ms, 1))
+            return BackendStatus(backend="vllm", available=False,
+                                 endpoint=self.base_url,
+                                 detail=f"HTTP {res.status_code} from /models")
+        except Exception as exc:
+            return BackendStatus(backend="vllm", available=False,
+                                 endpoint=self.base_url,
+                                 detail=f"unreachable ({exc.__class__.__name__}); vLLM "
+                                        "cannot run on this macOS machine — point "
+                                        "RETRO_VLLM_URL at a CUDA/ROCm host")
+
+    def generate(self, prompt: str, system: Optional[str] = None,
+                 max_tokens: int = 1024) -> InferenceResult:
+        model = self.model
+        if not model:
+            res = httpx.get(f"{self.base_url}/models", timeout=5.0)
+            data = res.json().get("data", [])
+            if not data:
+                raise RuntimeError(f"no models served at {self.base_url}")
+            model = data[0]["id"]
+        messages = ([{"role": "system", "content": system}] if system else []) + [
+            {"role": "user", "content": prompt}]
+        t0 = time.perf_counter()
+        res = httpx.post(f"{self.base_url}/chat/completions",
+                         json={"model": model, "messages": messages,
+                               "max_tokens": max_tokens, "temperature": 0.0},
+                         timeout=self.timeout)
+        latency_ms = (time.perf_counter() - t0) * 1000
+        res.raise_for_status()
+        body = res.json()
+        usage = body.get("usage", {})
+        return InferenceResult(
+            backend="vllm", model=model,
+            text=body["choices"][0]["message"]["content"],
+            prompt_tokens=int(usage.get("prompt_tokens", 0)),
+            completion_tokens=int(usage.get("completion_tokens", 0)),
+            latency_ms=round(latency_ms, 1))
+
+
+BACKENDS = {"mock": MockBackend, "ollama": OllamaBackend, "vllm": VLLMBackend}
+
+
+def get_backend(name: str = "mock", **kwargs) -> InferenceBackend:
+    if name not in BACKENDS:
+        raise ValueError(f"unknown backend {name!r}; expected one of {sorted(BACKENDS)}")
+    return BACKENDS[name](**kwargs)
+
+
+def all_backend_statuses() -> List[BackendStatus]:
+    return [get_backend(n).health() for n in ("mock", "ollama", "vllm")]

sensorflow/retro/inference/compat.py

@@ -0,0 +1,241 @@
+"""vLLM compatibility validation chain.
+
+Chain order (each link depends on the previous):
+    GPU -> driver -> torch -> vLLM -> model -> quantization
+
+Every link produces a CompatCheck with PASS / FAIL / SKIPPED (blocked by an
+earlier failure) plus a human-readable reason and remediation. On this
+project's development machine (macOS, no CUDA/ROCm) the chain fails honestly
+at the GPU link and reports vLLM as unsupported.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from sensorflow.retro.inference.env_detect import EnvironmentReport, detect_environment
+
+PASS = "PASS"
+FAIL = "FAIL"
+SKIPPED = "SKIPPED"
+
+# Quantization methods vLLM supports on CUDA; ROCm support is narrower.
+# See docs/retro/compatibility-matrix.md for the substantiated matrix.
+CUDA_QUANTIZATIONS = {"awq", "gptq", "fp8", "int8", "none"}
+ROCM_QUANTIZATIONS = {"fp8", "gptq", "none"}  # verify against current vLLM release
+
+# Very rough VRAM floor (GB) per model family for a usable context window.
+MODEL_VRAM_FLOOR_GB = {
+    "7b": 16, "8b": 18, "13b": 28, "14b": 30, "32b": 68, "70b": 140,
+}
+
+
+class CompatCheck(BaseModel):
+    link: str            # gpu | driver | torch | vllm | model | quantization
+    status: str          # PASS | FAIL | SKIPPED
+    reason: str
+    remediation: Optional[str] = None
+
+
+class CompatReport(BaseModel):
+    vllm_supported: bool
+    platform_summary: str
+    checks: List[CompatCheck]
+    failed_link: Optional[str] = None
+    notes: List[str] = Field(default_factory=list)
+
+
+def _estimate_vram_floor(model_name: str) -> Optional[int]:
+    lname = model_name.lower()
+    for size, gb in MODEL_VRAM_FLOOR_GB.items():
+        if size in lname:
+            return gb
+    return None
+
+
+def check_vllm_compatibility(env: Optional[EnvironmentReport] = None,
+                             model_name: str = "meta-llama/Llama-3.1-8B-Instruct",
+                             quantization: str = "none") -> CompatReport:
+    """Run the full GPU->driver->torch->vLLM->model->quantization chain."""
+    env = env or detect_environment(probe_ollama=False)
+    checks: List[CompatCheck] = []
+    failed: Optional[str] = None
+
+    def blocked(link: str, by: str) -> None:
+        checks.append(CompatCheck(
+            link=link, status=SKIPPED,
+            reason=f"not evaluated: blocked by failed '{by}' check"))
+
+    # --- 1. GPU -------------------------------------------------------------
+    cuda_gpus = [g for g in env.gpus if g.vendor == "nvidia"]
+    rocm_gpus = [g for g in env.gpus if g.vendor == "amd"]
+    gpu_vendor = "nvidia" if cuda_gpus else ("amd" if rocm_gpus else None)
+
+    if gpu_vendor:
+        gpu = (cuda_gpus or rocm_gpus)[0]
+        checks.append(CompatCheck(
+            link="gpu", status=PASS,
+            reason=f"{gpu.vendor.upper()} GPU detected: {gpu.model}"
+                   + (f" ({gpu.memory_mb} MB VRAM)" if gpu.memory_mb else "")))
+    else:
+        failed = "gpu"
+        apple = next((g for g in env.gpus if g.vendor == "apple"), None)
+        if env.is_macos:
+            reason = (f"No CUDA or ROCm capable GPU. This is macOS "
+                      f"({env.machine_arch})"
+                      + (f" with an Apple GPU ({apple.model}), which exposes "
+                         f"Metal/MPS only" if apple else "")
+                      + ". vLLM requires NVIDIA CUDA or AMD ROCm and does not "
+                        "run on macOS.")
+            remediation = ("Run the vLLM server on a Linux host with an NVIDIA "
+                           "or AMD data-center/consumer GPU; use the 'ollama' "
+                           "backend for local inference on this machine.")
+        else:
+            reason = "No NVIDIA or AMD GPU detected (nvidia-smi / rocm-smi absent or empty)."
+            remediation = "Install GPU drivers or move to a GPU host."
+        checks.append(CompatCheck(link="gpu", status=FAIL, reason=reason,
+                                  remediation=remediation))
+
+    # --- 2. Driver ----------------------------------------------------------
+    if failed:
+        blocked("driver", failed)
+    elif gpu_vendor == "nvidia":
+        drv = cuda_gpus[0].driver_version
+        if drv:
+            checks.append(CompatCheck(link="driver", status=PASS,
+                                      reason=f"NVIDIA driver {drv} reported by nvidia-smi"))
+        else:
+            failed = "driver"
+            checks.append(CompatCheck(
+                link="driver", status=FAIL,
+                reason="nvidia-smi present but did not report a driver version",
+                remediation="Reinstall the NVIDIA driver (>=535 recommended for "
+                            "current vLLM/CUDA 12 wheels)."))
+    else:  # amd
+        if env.rocm_smi_present:
+            checks.append(CompatCheck(link="driver", status=PASS,
+                                      reason="ROCm stack present (rocm-smi responds)"))
+        else:
+            failed = "driver"
+            checks.append(CompatCheck(link="driver", status=FAIL,
+                                      reason="AMD GPU without a working ROCm install",
+                                      remediation="Install ROCm >= 6.x for the target GPU."))
+
+    # --- 3. torch -----------------------------------------------------------
+    if failed:
+        blocked("torch", failed)
+    elif not env.torch.installed:
+        failed = "torch"
+        checks.append(CompatCheck(
+            link="torch", status=FAIL,
+            reason=f"PyTorch is not installed in this environment ({env.torch.detail})",
+            remediation="pip install a torch build matching the GPU stack "
+                        "(cu12x wheels for CUDA; rocm wheels for AMD)."))
+    elif gpu_vendor == "nvidia" and not env.torch.cuda_available:
+        failed = "torch"
+        checks.append(CompatCheck(
+            link="torch", status=FAIL,
+            reason=f"torch {env.torch.version} installed but torch.cuda.is_available() "
+                   "is False (CPU-only build or driver mismatch)",
+            remediation="Install a CUDA-enabled torch wheel matching the driver."))
+    elif gpu_vendor == "amd" and not env.torch.rocm_version:
+        failed = "torch"
+        checks.append(CompatCheck(
+            link="torch", status=FAIL,
+            reason=f"torch {env.torch.version} is not a ROCm build",
+            remediation="Install the ROCm torch wheel (torch.version.hip must be set)."))
+    else:
+        checks.append(CompatCheck(
+            link="torch", status=PASS,
+            reason=f"torch {env.torch.version} with a matching accelerator build"))
+
+    # --- 4. vLLM ------------------------------------------------------------
+    if failed:
+        blocked("vllm", failed)
+    elif not env.vllm_installed:
+        failed = "vllm"
+        checks.append(CompatCheck(
+            link="vllm", status=FAIL,
+            reason="vllm package is not installed",
+            remediation="pip install vllm (CUDA) or build the ROCm image; see "
+                        "docs/retro/compatibility-matrix.md."))
+    else:
+        checks.append(CompatCheck(link="vllm", status=PASS,
+                                  reason=f"vllm {env.vllm_version} importable"))
+
+    # --- 5. Model fits ------------------------------------------------------
+    if failed:
+        blocked("model", failed)
+    else:
+        floor = _estimate_vram_floor(model_name)
+        vram_mb = (cuda_gpus or rocm_gpus)[0].memory_mb
+        if floor is None or vram_mb is None:
+            checks.append(CompatCheck(
+                link="model", status=PASS,
+                reason=f"cannot pre-validate VRAM for '{model_name}' "
+                       "(unknown size class or unreported VRAM); vLLM will "
+                       "validate at load time"))
+        elif vram_mb / 1024 < floor:
+            failed = "model"
+            checks.append(CompatCheck(
+                link="model", status=FAIL,
+                reason=f"'{model_name}' needs roughly >={floor} GB VRAM unquantized; "
+                       f"GPU reports {vram_mb / 1024:.0f} GB",
+                remediation="Use quantization (AWQ/GPTQ/FP8), a smaller model, or "
+                            "tensor parallelism across more GPUs."))
+        else:
+            checks.append(CompatCheck(
+                link="model", status=PASS,
+                reason=f"'{model_name}' plausibly fits in {vram_mb / 1024:.0f} GB VRAM"))
+
+    # --- 6. Quantization ----------------------------------------------------
+    q = (quantization or "none").lower()
+    if failed:
+        blocked("quantization", failed)
+    else:
+        supported = CUDA_QUANTIZATIONS if gpu_vendor == "nvidia" else ROCM_QUANTIZATIONS
+        if q in supported:
+            checks.append(CompatCheck(
+                link="quantization", status=PASS,
+                reason=f"quantization '{q}' is supported on {gpu_vendor} "
+                       "(verify against the installed vLLM release)"))
+        else:
+            failed = "quantization"
+            checks.append(CompatCheck(
+                link="quantization", status=FAIL,
+                reason=f"quantization '{q}' is not supported on {gpu_vendor} "
+                       f"(supported: {sorted(supported)})",
+                remediation="Pick a supported method or run unquantized."))
+
+    if env.is_macos:
+        summary = (f"macOS {env.os_version} ({env.machine_arch}): vLLM UNSUPPORTED "
+                   "on this machine. Use the ollama or mock backend locally; run "
+                   "vLLM on a CUDA/ROCm Linux host.")
+    elif failed:
+        summary = f"vLLM unsupported here: chain failed at '{failed}'."
+    else:
+        summary = "All compatibility checks passed; vLLM should run on this host."
+
+    return CompatReport(
+        vllm_supported=failed is None,
+        platform_summary=summary,
+        checks=checks,
+        failed_link=failed,
+        notes=list(env.notes),
+    )
+
+
+def format_report(report: CompatReport) -> str:
+    lines = [report.platform_summary, ""]
+    for c in report.checks:
+        mark = {"PASS": "[PASS]", "FAIL": "[FAIL]", "SKIPPED": "[SKIP]"}[c.status]
+        lines.append(f"{mark} {c.link:<13} {c.reason}")
+        if c.remediation:
+            lines.append(f"       remediation: {c.remediation}")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":
+    print(format_report(check_vllm_compatibility()))

sensorflow/retro/inference/env_detect.py

@@ -0,0 +1,228 @@
+"""Real hardware/software environment detection for the inference layer.
+
+Every field is probed from the actual machine (platform module, subprocess
+calls to nvidia-smi / rocm-smi / system_profiler, and import probes for
+torch / vllm). Nothing is assumed or fabricated: absent components are
+reported as absent, and probe failures carry the failure detail.
+"""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import subprocess
+import sys
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class GPUInfo(BaseModel):
+    vendor: str                      # nvidia | amd | apple | intel | unknown
+    model: str
+    memory_mb: Optional[int] = None  # dedicated VRAM if known; None for unified
+    unified_memory: bool = False     # Apple Silicon shares system RAM
+    driver_version: Optional[str] = None
+    compute_capability: Optional[str] = None
+    detail: str = ""
+
+
+class TorchInfo(BaseModel):
+    installed: bool
+    version: Optional[str] = None
+    cuda_available: bool = False
+    cuda_version: Optional[str] = None
+    rocm_version: Optional[str] = None
+    mps_available: bool = False
+    detail: str = ""
+
+
+class EnvironmentReport(BaseModel):
+    os_name: str
+    os_version: str
+    machine_arch: str
+    is_macos: bool
+    is_apple_silicon: bool
+    python_version: str
+    torch: TorchInfo
+    gpus: List[GPUInfo] = Field(default_factory=list)
+    cuda_toolkit_version: Optional[str] = None   # from nvcc, if present
+    rocm_installed: bool = False
+    nvidia_smi_present: bool = False
+    rocm_smi_present: bool = False
+    vllm_installed: bool = False
+    vllm_version: Optional[str] = None
+    ollama_endpoint: Optional[str] = None        # reachable Ollama server, if any
+    ollama_models: List[str] = Field(default_factory=list)
+    notes: List[str] = Field(default_factory=list)
+
+
+def _run(cmd: List[str], timeout: float = 5.0) -> Optional[str]:
+    try:
+        out = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        if out.returncode == 0:
+            return out.stdout
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return None
+
+
+def _detect_nvidia() -> List[GPUInfo]:
+    if not shutil.which("nvidia-smi"):
+        return []
+    out = _run(["nvidia-smi", "--query-gpu=name,memory.total,driver_version,compute_cap",
+                "--format=csv,noheader,nounits"])
+    gpus: List[GPUInfo] = []
+    for line in (out or "").strip().splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) >= 2:
+            gpus.append(GPUInfo(
+                vendor="nvidia", model=parts[0],
+                memory_mb=int(float(parts[1])) if parts[1].replace(".", "").isdigit() else None,
+                driver_version=parts[2] if len(parts) > 2 else None,
+                compute_capability=parts[3] if len(parts) > 3 else None,
+                detail="detected via nvidia-smi"))
+    return gpus
+
+
+def _detect_amd() -> List[GPUInfo]:
+    if not shutil.which("rocm-smi"):
+        return []
+    out = _run(["rocm-smi", "--showproductname", "--json"])
+    gpus: List[GPUInfo] = []
+    if out:
+        try:
+            data = json.loads(out)
+            for card, fields in data.items():
+                name = (fields.get("Card series") or fields.get("Card SKU")
+                        or fields.get("Card model") or card)
+                gpus.append(GPUInfo(vendor="amd", model=str(name),
+                                    detail="detected via rocm-smi"))
+        except (json.JSONDecodeError, AttributeError):
+            gpus.append(GPUInfo(vendor="amd", model="unknown AMD GPU",
+                                detail="rocm-smi present but output unparseable"))
+    return gpus
+
+
+def _detect_apple() -> List[GPUInfo]:
+    if platform.system() != "Darwin":
+        return []
+    out = _run(["system_profiler", "SPDisplaysDataType", "-json"], timeout=15.0)
+    gpus: List[GPUInfo] = []
+    if out:
+        try:
+            data = json.loads(out)
+            for item in data.get("SPDisplaysDataType", []):
+                model = item.get("sppci_model", "Apple GPU")
+                cores = item.get("sppci_cores")
+                detail = "detected via system_profiler"
+                if cores:
+                    detail += f"; {cores} GPU cores"
+                gpus.append(GPUInfo(vendor="apple", model=model, unified_memory=True,
+                                    detail=detail))
+        except json.JSONDecodeError:
+            pass
+    if not gpus:
+        # Apple Silicon always has an integrated GPU even if profiling failed.
+        gpus.append(GPUInfo(vendor="apple", model=f"Apple GPU ({platform.machine()})",
+                            unified_memory=True,
+                            detail="system_profiler unavailable; inferred from platform"))
+    return gpus
+
+
+def _detect_torch() -> TorchInfo:
+    try:
+        import torch  # type: ignore
+    except ImportError as exc:
+        return TorchInfo(installed=False, detail=f"torch not importable: {exc}")
+    info = TorchInfo(installed=True, version=getattr(torch, "__version__", None))
+    try:
+        info.cuda_available = bool(torch.cuda.is_available())
+        info.cuda_version = getattr(torch.version, "cuda", None)
+        info.rocm_version = getattr(torch.version, "hip", None)
+        mps = getattr(torch.backends, "mps", None)
+        info.mps_available = bool(mps and mps.is_available())
+        info.detail = "torch probed successfully"
+    except Exception as exc:  # torch runtime probing should never crash detection
+        info.detail = f"torch installed but probing failed: {exc}"
+    return info
+
+
+def _detect_nvcc() -> Optional[str]:
+    out = _run(["nvcc", "--version"]) if shutil.which("nvcc") else None
+    if out:
+        for line in out.splitlines():
+            if "release" in line:
+                return line.strip()
+    return None
+
+
+def _detect_ollama(endpoints: Optional[List[str]] = None) -> tuple[Optional[str], List[str]]:
+    import httpx
+    for base in endpoints or ["http://localhost:11434"]:
+        try:
+            res = httpx.get(f"{base}/api/tags", timeout=2.0)
+            if res.status_code == 200:
+                models = [m.get("name", "?") for m in res.json().get("models", [])]
+                return base, models
+        except Exception:
+            continue
+    return None, []
+
+
+def detect_environment(probe_ollama: bool = True) -> EnvironmentReport:
+    """Probe the actual machine. Safe to call anywhere; never raises."""
+    system = platform.system()
+    arch = platform.machine()
+    is_macos = system == "Darwin"
+    is_apple_silicon = is_macos and arch == "arm64"
+
+    gpus = _detect_nvidia() + _detect_amd()
+    if not gpus and is_macos:
+        gpus = _detect_apple()
+
+    try:
+        import vllm  # type: ignore
+        vllm_installed, vllm_version = True, getattr(vllm, "__version__", "unknown")
+    except ImportError:
+        vllm_installed, vllm_version = False, None
+
+    ollama_ep, ollama_models = (None, [])
+    if probe_ollama:
+        ollama_ep, ollama_models = _detect_ollama()
+
+    notes: List[str] = []
+    if is_macos:
+        notes.append("macOS detected: vLLM does not run on macOS (no CUDA, no ROCm); "
+                     "Apple GPU acceleration is Metal/MPS which vLLM does not target.")
+    if is_apple_silicon:
+        notes.append("Apple Silicon (arm64) with unified memory; local LLM inference "
+                     "is possible via Ollama (Metal), not vLLM.")
+    if not shutil.which("nvidia-smi") and not shutil.which("rocm-smi"):
+        notes.append("Neither nvidia-smi nor rocm-smi found on PATH: no CUDA or "
+                     "ROCm capable GPU stack is installed on this machine.")
+
+    return EnvironmentReport(
+        os_name=system,
+        os_version=platform.mac_ver()[0] if is_macos else platform.release(),
+        machine_arch=arch,
+        is_macos=is_macos,
+        is_apple_silicon=is_apple_silicon,
+        python_version=".".join(map(str, sys.version_info[:3])),
+        torch=_detect_torch(),
+        gpus=gpus,
+        cuda_toolkit_version=_detect_nvcc(),
+        rocm_installed=shutil.which("rocm-smi") is not None,
+        nvidia_smi_present=shutil.which("nvidia-smi") is not None,
+        rocm_smi_present=shutil.which("rocm-smi") is not None,
+        vllm_installed=vllm_installed,
+        vllm_version=vllm_version,
+        ollama_endpoint=ollama_ep,
+        ollama_models=ollama_models,
+        notes=notes,
+    )
+
+
+if __name__ == "__main__":
+    print(detect_environment().model_dump_json(indent=2))

sensorflow/retro/inference/vllm_server/benchmark.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Latency/throughput benchmark for an OpenAI-compatible LLM endpoint.
+
+Measures, over N requests against a live endpoint:
+  * TTFT (time to first streamed token): P50 / P95 / P99
+  * end-to-end latency percentiles
+  * completion tokens/sec (per request and aggregate)
+  * warm vs cold: the first request after startup is reported separately
+
+HONESTY NOTE: this script was written on a macOS machine where vLLM cannot
+run. It has NOT been executed against a vLLM server here and this repository
+contains NO vLLM benchmark numbers. Run it yourself on a CUDA/ROCm host:
+
+    python benchmark.py --base-url http://gpu-host:8001/v1 --n 32
+
+It also works against Ollama's OpenAI-compatible endpoint
+(http://localhost:11434/v1) — numbers from that path are Ollama-on-CPU/Metal
+numbers and must be labeled as such, never as vLLM results.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+import time
+from typing import Dict, List, Optional
+
+import httpx
+
+PROMPTS = [
+    "Summarize why time-to-collision alone is an insufficient safety metric.",
+    "List three causes of phantom braking in camera-based perception stacks.",
+    "Explain the difference between a false negative and a missed detection track.",
+    "Describe how rain degrades LiDAR point cloud density at range.",
+]
+
+
+def percentile(values: List[float], p: float) -> float:
+    if not values:
+        return float("nan")
+    s = sorted(values)
+    idx = min(len(s) - 1, max(0, round(p / 100 * (len(s) - 1))))
+    return s[idx]
+
+
+def stream_once(client: httpx.Client, base_url: str, model: str, prompt: str,
+                max_tokens: int) -> Dict:
+    """One streaming chat completion; returns ttft/e2e/token counts."""
+    t0 = time.perf_counter()
+    ttft: Optional[float] = None
+    completion_tokens = 0
+    with client.stream(
+        "POST", f"{base_url}/chat/completions",
+        json={"model": model, "messages": [{"role": "user", "content": prompt}],
+              "max_tokens": max_tokens, "temperature": 0.0, "stream": True},
+        timeout=180.0,
+    ) as res:
+        res.raise_for_status()
+        for line in res.iter_lines():
+            if not line or not line.startswith("data:"):
+                continue
+            payload = line[len("data:"):].strip()
+            if payload == "[DONE]":
+                break
+            try:
+                chunk = json.loads(payload)
+            except json.JSONDecodeError:
+                continue
+            delta = chunk.get("choices", [{}])[0].get("delta", {})
+            if delta.get("content"):
+                if ttft is None:
+                    ttft = time.perf_counter() - t0
+                completion_tokens += 1  # one content delta ~= one token for vLLM/Ollama
+    e2e = time.perf_counter() - t0
+    return {"ttft_s": ttft if ttft is not None else e2e, "e2e_s": e2e,
+            "completion_tokens": completion_tokens,
+            "tokens_per_s": completion_tokens / e2e if e2e > 0 else 0.0}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--base-url", default="http://localhost:8001/v1")
+    ap.add_argument("--model", default=None, help="default: first served model")
+    ap.add_argument("--n", type=int, default=16, help="number of measured (warm) requests")
+    ap.add_argument("--max-tokens", type=int, default=128)
+    ap.add_argument("--label", default=None,
+                    help="required honesty label for the report, e.g. "
+                         "'vLLM A100-80GB' or 'Ollama on Apple M-series (Metal)'")
+    args = ap.parse_args()
+
+    client = httpx.Client()
+    try:
+        res = client.get(f"{args.base_url}/models", timeout=5.0)
+        res.raise_for_status()
+        served = [m["id"] for m in res.json().get("data", [])]
+    except Exception as exc:
+        print(f"ERROR: endpoint {args.base_url} unreachable: {exc}", file=sys.stderr)
+        print("No benchmark numbers produced. (This is expected on the macOS "
+              "dev machine: vLLM cannot run here.)", file=sys.stderr)
+        return 2
+
+    model = args.model or (served[0] if served else None)
+    if not model:
+        print("ERROR: endpoint serves no models", file=sys.stderr)
+        return 2
+
+    label = args.label or f"UNLABELED endpoint at {args.base_url}"
+    print(f"# Benchmark: {model} @ {args.base_url}")
+    print(f"# Hardware label: {label}")
+
+    print("## Cold request (first after client startup)")
+    cold = stream_once(client, args.base_url, model, PROMPTS[0], args.max_tokens)
+    print(f"  ttft={cold['ttft_s'] * 1000:.0f}ms e2e={cold['e2e_s']:.2f}s "
+          f"tokens/s={cold['tokens_per_s']:.1f}")
+
+    print(f"## Warm requests (n={args.n})")
+    rows = []
+    for i in range(args.n):
+        r = stream_once(client, args.base_url, model,
+                        PROMPTS[i % len(PROMPTS)], args.max_tokens)
+        rows.append(r)
+        print(f"  [{i + 1:>3}/{args.n}] ttft={r['ttft_s'] * 1000:.0f}ms "
+              f"e2e={r['e2e_s']:.2f}s tok/s={r['tokens_per_s']:.1f}")
+
+    ttfts = [r["ttft_s"] * 1000 for r in rows]
+    e2es = [r["e2e_s"] for r in rows]
+    tps = [r["tokens_per_s"] for r in rows]
+    report = {
+        "hardware_label": label,
+        "model": model,
+        "base_url": args.base_url,
+        "n_warm": args.n,
+        "cold": {k: round(v, 4) for k, v in cold.items()},
+        "ttft_ms": {"p50": round(percentile(ttfts, 50), 1),
+                    "p95": round(percentile(ttfts, 95), 1),
+                    "p99": round(percentile(ttfts, 99), 1)},
+        "e2e_s": {"p50": round(percentile(e2es, 50), 3),
+                  "p95": round(percentile(e2es, 95), 3),
+                  "p99": round(percentile(e2es, 99), 3)},
+        "tokens_per_s": {"mean": round(statistics.mean(tps), 2),
+                         "min": round(min(tps), 2), "max": round(max(tps), 2)},
+        "warm_vs_cold_ttft_ratio": round(
+            cold["ttft_s"] * 1000 / max(percentile(ttfts, 50), 1e-9), 2),
+    }
+    print("\n## Summary (JSON)")
+    print(json.dumps(report, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sensorflow/retro/inference/vllm_server/model.env

@@ -0,0 +1,6 @@
+# vLLM model config.
+MODEL_NAME=${MODEL_NAME:-meta-llama/Llama-3.1-8B-Instruct}
+MAX_MODEL_LEN=${MAX_MODEL_LEN:-8192}
+# QUANTIZATION: none | awq | gptq | fp8  (support differs by GPU vendor;
+# see docs/retro/compatibility-matrix.md)
+QUANTIZATION=${QUANTIZATION:-none}

sensorflow/retro/inference/vllm_server/runtime.env

@@ -0,0 +1,4 @@
+# vLLM runtime/resource config.
+GPU_MEMORY_UTILIZATION=${GPU_MEMORY_UTILIZATION:-0.90}
+TENSOR_PARALLEL_SIZE=${TENSOR_PARALLEL_SIZE:-1}
+DTYPE=${DTYPE:-auto}

sensorflow/retro/inference/vllm_server/server.env

@@ -0,0 +1,5 @@
+# vLLM server config — network/serving parameters.
+# Every value can be overridden by exporting the variable before start_vllm.sh.
+HOST=${HOST:-0.0.0.0}
+PORT=${PORT:-8001}
+API_KEY=${API_KEY:-}            # optional --api-key

sensorflow/retro/inference/vllm_server/start_vllm.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# Start an OpenAI-compatible vLLM server.
+#
+# RUNNABLE ONLY ON CUDA/ROCm LINUX HOSTS. This script was authored on a macOS
+# development machine where vLLM cannot run; it refuses to start on Darwin
+# with an honest error instead of failing cryptically.
+#
+# Config is separated into three env files (server/model/runtime); every
+# variable can be overridden from the environment:
+#   MODEL_NAME=Qwen/Qwen2.5-7B-Instruct PORT=8010 ./start_vllm.sh
+set -euo pipefail
+cd "$(dirname "$0")"
+
+if [ "$(uname -s)" = "Darwin" ]; then
+  echo "ERROR: vLLM does not run on macOS (no CUDA, no ROCm)." >&2
+  echo "Run this script on a Linux host with an NVIDIA or AMD GPU." >&2
+  echo "On this machine use the 'ollama' or 'mock' backend instead." >&2
+  exit 2
+fi
+
+if ! command -v nvidia-smi >/dev/null 2>&1 && ! command -v rocm-smi >/dev/null 2>&1; then
+  echo "ERROR: neither nvidia-smi nor rocm-smi found — no supported GPU stack." >&2
+  exit 2
+fi
+
+# shellcheck disable=SC1091
+source ./server.env
+source ./model.env
+source ./runtime.env
+
+echo "Starting vLLM: model=${MODEL_NAME} host=${HOST}:${PORT}" \
+     "tp=${TENSOR_PARALLEL_SIZE} gpu_mem=${GPU_MEMORY_UTILIZATION}" \
+     "max_len=${MAX_MODEL_LEN} quant=${QUANTIZATION}"
+
+ARGS=(
+  --model "${MODEL_NAME}"
+  --host "${HOST}"
+  --port "${PORT}"
+  --gpu-memory-utilization "${GPU_MEMORY_UTILIZATION}"
+  --max-model-len "${MAX_MODEL_LEN}"
+  --tensor-parallel-size "${TENSOR_PARALLEL_SIZE}"
+  --dtype "${DTYPE}"
+)
+[ "${QUANTIZATION}" != "none" ] && ARGS+=(--quantization "${QUANTIZATION}")
+[ -n "${API_KEY}" ] && ARGS+=(--api-key "${API_KEY}")
+
+exec python -m vllm.entrypoints.openai.api_server "${ARGS[@]}"

sensorflow/retro/metrics.py

@@ -0,0 +1,239 @@
+"""Deterministic safety metric calculators (the safety boundary).
+
+Everything here is pure, parameterized computation — no LLM involvement.
+TTC reuses the platform's SSAM rectangle conflict-point projection
+(sensorflow/safety/ssam_ext.py) and cross-checks with the closed-form
+distance/closing-speed ratio. Every result carries explicit
+assumption/validity flags; inputs that are absent produce UNKNOWN results,
+never guesses.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from sensorflow.safety.ssam_ext import projected_ttc
+
+G = 9.80665  # m/s^2
+
+
+class StoppingDistanceResult(BaseModel):
+    stopping_distance_m: Optional[float]
+    reaction_distance_m: Optional[float]
+    braking_distance_m: Optional[float]
+    effective_decel_mps2: Optional[float]
+    total_reaction_time_s: Optional[float]
+    params: Dict[str, Any]
+    assumptions: List[str]
+    unknown_reason: Optional[str] = None
+
+
+def stopping_distance(velocity_mps: Optional[float],
+                      reaction_time_s: float = 0.25,
+                      system_latency_s: float = 0.0,
+                      planner_latency_s: float = 0.0,
+                      friction: float = 0.7,
+                      grade: float = 0.0,
+                      decel_mps2: Optional[float] = None) -> StoppingDistanceResult:
+    """Stopping distance = v * t_react_total + v^2 / (2 * a_eff).
+
+    a_eff comes from an explicit decel limit if provided, otherwise from
+    friction and road grade: a = g * (friction * cos(theta) + sin(theta)),
+    with theta = atan(grade); a downhill (negative) grade reduces available
+    deceleration. t_react_total charges perception system latency and
+    planner latency against the reaction budget.
+    """
+    params = {"velocity_mps": velocity_mps, "reaction_time_s": reaction_time_s,
+              "system_latency_s": system_latency_s,
+              "planner_latency_s": planner_latency_s, "friction": friction,
+              "grade": grade, "decel_mps2": decel_mps2}
+    if velocity_mps is None:
+        return StoppingDistanceResult(
+            stopping_distance_m=None, reaction_distance_m=None,
+            braking_distance_m=None, effective_decel_mps2=None,
+            total_reaction_time_s=None, params=params, assumptions=[],
+            unknown_reason="ego velocity missing from telemetry -> UNKNOWN")
+
+    assumptions = ["point-mass braking model on uniform surface",
+                   "constant deceleration during braking phase",
+                   "reaction budget includes perception system latency "
+                   "and planner latency"]
+    theta = math.atan(grade)
+    if decel_mps2 is not None:
+        a_eff = float(decel_mps2) + G * math.sin(theta)
+        assumptions.append("deceleration limit supplied explicitly; grade "
+                           "component added (downhill reduces)")
+    else:
+        a_eff = G * (friction * math.cos(theta) + math.sin(theta))
+        assumptions.append(f"deceleration derived from friction={friction} "
+                           f"and grade={grade}")
+    if a_eff <= 0.05:
+        return StoppingDistanceResult(
+            stopping_distance_m=None, reaction_distance_m=None,
+            braking_distance_m=None, effective_decel_mps2=round(a_eff, 4),
+            total_reaction_time_s=None, params=params, assumptions=assumptions,
+            unknown_reason="effective deceleration <= 0 (grade exceeds "
+                           "friction) -> stopping distance undefined")
+
+    t_react = reaction_time_s + system_latency_s + planner_latency_s
+    reaction_d = velocity_mps * t_react
+    braking_d = velocity_mps ** 2 / (2 * a_eff)
+    return StoppingDistanceResult(
+        stopping_distance_m=round(reaction_d + braking_d, 2),
+        reaction_distance_m=round(reaction_d, 2),
+        braking_distance_m=round(braking_d, 2),
+        effective_decel_mps2=round(a_eff, 3),
+        total_reaction_time_s=round(t_react, 3),
+        params=params, assumptions=assumptions)
+
+
+class TTCResult(BaseModel):
+    ttc_s: Optional[float]
+    method: str
+    validity_flags: List[str]
+    closed_form_ttc_s: Optional[float] = None
+    unknown_reason: Optional[str] = None
+
+
+def time_to_collision(distance_m: Optional[float],
+                      closing_velocity_mps: Optional[float],
+                      ego_length_m: float = 4.5, ego_width_m: float = 1.9,
+                      obj_length_m: float = 0.6, obj_width_m: float = 0.6,
+                      look_ahead_s: float = 12.0) -> TTCResult:
+    """TTC via the SSAM rectangle conflict-point projection (ssam_ext),
+    cross-checked against the closed-form gap/closing ratio.
+
+    closing_velocity_mps > 0 means the range is decreasing.
+    """
+    flags = ["constant-velocity extrapolation (no acceleration model)",
+             "straight-line relative motion assumed",
+             "rectangle footprint projection (ssam_ext.projected_ttc)"]
+    if distance_m is None or closing_velocity_mps is None:
+        return TTCResult(ttc_s=None, method="ssam_ext.projected_ttc",
+                         validity_flags=flags,
+                         unknown_reason="distance or relative velocity missing "
+                                        "from telemetry -> UNKNOWN")
+    if closing_velocity_mps <= 0:
+        flags.append("object not closing: TTC undefined (no predicted collision)")
+        return TTCResult(ttc_s=None, method="ssam_ext.projected_ttc",
+                         validity_flags=flags)
+
+    ego_state = {"x": 0.0, "y": 0.0, "speed": float(closing_velocity_mps),
+                 "heading": 0.0}
+    obj_state = {"x": float(distance_m), "y": 0.0, "speed": 0.0, "heading": 0.0}
+    ttc = projected_ttc(ego_state, (ego_length_m, ego_width_m),
+                        obj_state, (obj_length_m, obj_width_m),
+                        look_ahead=look_ahead_s, dt=0.02)
+    gap = max(distance_m - (ego_length_m + obj_length_m) / 2, 0.0)
+    closed_form = gap / closing_velocity_mps
+    if ttc is None:
+        flags.append(f"no projected collision within {look_ahead_s}s look-ahead")
+    return TTCResult(ttc_s=None if ttc is None else round(ttc, 3),
+                     method="ssam_ext.projected_ttc",
+                     validity_flags=flags,
+                     closed_form_ttc_s=round(closed_form, 3))
+
+
+class SCRImpactResult(BaseModel):
+    scr_baseline: Optional[float]
+    scr_candidate: Optional[float]
+    scr_impact: Optional[float]           # candidate - baseline
+    criticality_policy: str
+    denominator: Optional[int]
+    unknown_reason: Optional[str] = None
+
+
+def scr_impact(evaluation_context: Optional[Dict[str, Any]]) -> SCRImpactResult:
+    """Safety-critical recall delta against the policy-defined criticality
+    population (objects inside 1.5x stopping distance, closing, VRU or
+    collision-relevant mass — see SFS-EVAL-005 EVAL-SCR-01 [SYNTHETIC])."""
+    policy = ("critical = inside 1.5x stopping distance AND closing AND "
+              "(VRU class OR collision-relevant mass)")
+    ctx = evaluation_context or {}
+    n = ctx.get("critical_object_count")
+    mb = ctx.get("baseline_missed_critical")
+    mc = ctx.get("candidate_missed_critical")
+    if n is None or mb is None or mc is None or n <= 0:
+        return SCRImpactResult(scr_baseline=None, scr_candidate=None,
+                               scr_impact=None, criticality_policy=policy,
+                               denominator=None,
+                               unknown_reason="criticality-context counts absent "
+                                              "-> SCR impact UNKNOWN (inadmissible "
+                                              "as launch evidence)")
+    scr_b = 1.0 - mb / n
+    scr_c = 1.0 - mc / n
+    return SCRImpactResult(scr_baseline=round(scr_b, 6),
+                           scr_candidate=round(scr_c, 6),
+                           scr_impact=round(scr_c - scr_b, 6),
+                           criticality_policy=policy, denominator=int(n))
+
+
+class BehavioralImpactResult(BaseModel):
+    observed_action: Optional[str]
+    observed_decel_mps2: Optional[float]
+    corrected_action: Optional[str]
+    corrected_decel_mps2: Optional[float]
+    action_changed: Optional[bool]
+    decel_delta_mps2: Optional[float]
+    response_delay_s: Optional[float]
+    consequence: str
+    unknown_reason: Optional[str] = None
+
+
+def behavioral_impact(observed: Optional[Dict[str, Any]],
+                      counterfactual: Optional[Dict[str, Any]]) -> BehavioralImpactResult:
+    """Observed planner response vs the corrected-perception counterfactual.
+
+    The counterfactual must be supplied by the evaluation artifact (replay or
+    simulation output); this function only compares — it never invents one.
+    """
+    if not observed:
+        return BehavioralImpactResult(
+            observed_action=None, observed_decel_mps2=None,
+            corrected_action=None, corrected_decel_mps2=None,
+            action_changed=None, decel_delta_mps2=None, response_delay_s=None,
+            consequence="UNKNOWN",
+            unknown_reason="planner response missing from artifact")
+    if not counterfactual:
+        return BehavioralImpactResult(
+            observed_action=observed.get("action"),
+            observed_decel_mps2=observed.get("decel_mps2"),
+            corrected_action=None, corrected_decel_mps2=None,
+            action_changed=None, decel_delta_mps2=None, response_delay_s=None,
+            consequence="UNKNOWN",
+            unknown_reason="corrected-perception counterfactual not provided "
+                           "in artifact -> behavioral delta UNKNOWN")
+    obs_a, cf_a = observed.get("action"), counterfactual.get("action")
+    obs_d = float(observed.get("decel_mps2") or 0.0)
+    cf_d = float(counterfactual.get("decel_mps2") or 0.0)
+    obs_t = observed.get("response_time_s")
+    cf_t = counterfactual.get("response_time_s")
+    delay = (round(float(obs_t) - float(cf_t), 3)
+             if obs_t is not None and cf_t is not None else None)
+    changed = obs_a != cf_a
+    delta = round(obs_d - cf_d, 3)
+    if delay is not None and delay > 0.5:
+        consequence = (f"perception error DELAYED the planner response by "
+                       f"{delay:.2f} s ('{cf_a}' at t={cf_t}s became '{obs_a}' "
+                       f"at t={obs_t}s) -> reaction-time budget consumed, "
+                       "residual collision risk")
+    elif changed and delta > 3.0:
+        consequence = (f"perception error converted '{cf_a}' into '{obs_a}' with "
+                       f"{delta:+.1f} m/s^2 excess deceleration (unwarranted "
+                       "intervention)")
+    elif changed and delta < -3.0:
+        consequence = (f"perception error suppressed '{cf_a}' "
+                       f"({delta:+.1f} m/s^2 missing deceleration -> residual "
+                       "collision risk)")
+    elif changed:
+        consequence = f"planner action changed ('{cf_a}' -> '{obs_a}'), moderate magnitude"
+    else:
+        consequence = "no behavioral change attributable to the perception error"
+    return BehavioralImpactResult(
+        observed_action=obs_a, observed_decel_mps2=obs_d,
+        corrected_action=cf_a, corrected_decel_mps2=cf_d,
+        action_changed=changed, decel_delta_mps2=delta, response_delay_s=delay,
+        consequence=consequence)

sensorflow/retro/policy.py

@@ -0,0 +1,288 @@
+"""Deterministic severity framework and launch-recommendation gate.
+
+This module OWNS the safety boundary. The LLM may propose a severity with
+evidence; this engine validates or overrides it, records divergence, and is
+the ONLY producer of launch determinations.
+
+Severity model (asymmetric FN/FP costs, context-dependent — deliberately NOT
+"every FN outranks every FP"):
+  FALSE NEGATIVE cost ~ VRU weight x safety-relevant-distance factor x
+      relative-motion factor x remaining-reaction-time factor
+  FALSE POSITIVE cost ~ intervention magnitude x traffic disruption exposure
+A benign distant non-closing FN scores below a hard-braking phantom FP with
+a tailgater; the test suite pins this ordering.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Tuple
+
+from pydantic import BaseModel, Field
+
+from sensorflow.retro.scorecard import LaunchRecommendation, Severity
+
+POLICY_VERSION = "retro-policy/1.0.0"
+
+# Versioned policy configuration: all thresholds live here, not in code paths.
+POLICY_CONFIG: Dict[str, Any] = {
+    "version": POLICY_VERSION,
+    "vru_weights": {
+        "pedestrian": 1.0, "cyclist": 0.95, "motorcycle": 0.9,
+        "wheelchair": 1.0, "vehicle": 0.6, "truck": 0.65, "bus": 0.65,
+        "unknown": 0.5, "debris": 0.15, "plastic_bag": 0.05, "static": 0.2,
+    },
+    "fn_severity_cutoffs": {"critical": 0.45, "disruptive": 0.18},
+    "fp_severity_cutoffs": {"critical": 0.55, "disruptive": 0.28},
+    "hard_brake_g": 0.35,               # from SFS-SAFE-001 REQ-FP-02 [SYNTHETIC]
+    "tailgater_gap_s": 1.5,
+    "scr_regression_tolerance": 0.002,  # 0.2 pp, SFS-LAUNCH-004 GATE-02 [SYNTHETIC]
+    "collision_risk_ttc_s": 1.5,
+}
+
+
+class SeverityContext(BaseModel):
+    """Deterministic inputs to the severity computation (facts + derived)."""
+    failure_type: str                       # FALSE_NEGATIVE | FALSE_POSITIVE | ...
+    object_class: Optional[str] = None      # ground-truth class
+    distance_m: Optional[float] = None
+    stopping_distance_m: Optional[float] = None
+    closing_velocity_mps: Optional[float] = None
+    ttc_s: Optional[float] = None
+    total_reaction_time_s: Optional[float] = None
+    collision_occurred: bool = False
+    near_miss: bool = False
+    intervention_decel_mps2: Optional[float] = None   # observed planner decel
+    following_gap_s: Optional[float] = None            # rear traffic time gap
+    ego_speed_mps: Optional[float] = None
+
+
+class SeverityResult(BaseModel):
+    severity: Severity
+    score: float
+    rule_trace: List[str] = Field(default_factory=list)
+    computable: bool = True
+
+
+def _fn_severity(ctx: SeverityContext, cfg: Dict[str, Any],
+                 trace: List[str]) -> Tuple[Severity, float]:
+    w = cfg["vru_weights"].get((ctx.object_class or "unknown").lower(), 0.5)
+    trace.append(f"FN branch: class '{ctx.object_class}' weight={w}")
+
+    if ctx.distance_m is not None and ctx.stopping_distance_m:
+        ratio = ctx.distance_m / ctx.stopping_distance_m
+        if ratio <= 1.0:
+            dist_f = 1.0
+        elif ratio <= 1.5:
+            dist_f = 0.6
+        elif ratio <= 3.0:
+            dist_f = 0.25
+        else:
+            dist_f = 0.05
+        trace.append(f"distance {ctx.distance_m:.1f} m = {ratio:.2f}x stopping "
+                     f"distance -> factor {dist_f}")
+    else:
+        dist_f = 0.5
+        trace.append("distance vs stopping distance not computable -> neutral 0.5")
+
+    closing = ctx.closing_velocity_mps or 0.0
+    if closing > 0:
+        motion_f = min(1.0, 0.3 + closing / 15.0)
+        trace.append(f"closing at {closing:.1f} m/s -> motion factor {motion_f:.2f}")
+    else:
+        motion_f = 0.1
+        trace.append("not closing -> motion factor 0.1")
+
+    if ctx.ttc_s is not None and ctx.total_reaction_time_s is not None:
+        remaining = ctx.ttc_s - ctx.total_reaction_time_s
+        if remaining <= 0:
+            rrt_f = 1.0
+        elif remaining < 1.0:
+            rrt_f = 0.8
+        elif remaining < 2.5:
+            rrt_f = 0.5
+        else:
+            rrt_f = 0.2
+        trace.append(f"remaining reaction time {remaining:.2f} s -> factor {rrt_f}")
+    elif closing > 0:
+        rrt_f = 0.6
+        trace.append("TTC/reaction budget unknown while closing -> conservative 0.6")
+    else:
+        rrt_f = 0.1
+        trace.append("no predicted collision path -> reaction factor 0.1")
+
+    score = w * dist_f * (0.5 * motion_f + 0.5 * rrt_f)
+    cuts = cfg["fn_severity_cutoffs"]
+    if ctx.collision_occurred:
+        trace.append("collision occurred -> FATAL override")
+        return Severity.FATAL, max(score, 1.0)
+    if score >= cuts["critical"] or (ctx.near_miss and score >= cuts["disruptive"]):
+        return Severity.CRITICAL, score
+    if score >= cuts["disruptive"]:
+        return Severity.DISRUPTIVE, score
+    if ctx.near_miss:
+        trace.append("near-miss recorded despite low computed score -> "
+                     "DISRUPTIVE floor")
+        return Severity.DISRUPTIVE, score
+    return Severity.BENIGN, score
+
+
+def _fp_severity(ctx: SeverityContext, cfg: Dict[str, Any],
+                 trace: List[str]) -> Tuple[Severity, float]:
+    decel = ctx.intervention_decel_mps2 or 0.0
+    intervention_f = min(1.0, decel / 9.0)
+    trace.append(f"FP branch: intervention decel {decel:.1f} m/s^2 "
+                 f"({decel / 9.80665:.2f} g) -> factor {intervention_f:.2f}")
+
+    if ctx.following_gap_s is not None:
+        if ctx.following_gap_s < 1.0:
+            disruption_f = 1.0
+        elif ctx.following_gap_s < cfg["tailgater_gap_s"]:
+            disruption_f = 0.8
+        elif ctx.following_gap_s < 3.0:
+            disruption_f = 0.5
+        else:
+            disruption_f = 0.3
+        trace.append(f"following gap {ctx.following_gap_s:.1f} s -> "
+                     f"disruption factor {disruption_f}")
+    else:
+        disruption_f = 0.4
+        trace.append("following traffic unknown -> disruption factor 0.4 (assumed)")
+
+    speed_f = min(1.0, (ctx.ego_speed_mps or 0.0) / 30.0)
+    trace.append(f"ego speed factor {speed_f:.2f}")
+
+    score = intervention_f * (0.55 + 0.45 * disruption_f) * (0.6 + 0.4 * speed_f)
+    cuts = cfg["fp_severity_cutoffs"]
+    hard_brake = decel >= cfg["hard_brake_g"] * 9.80665
+    tailgated = (ctx.following_gap_s is not None
+                 and ctx.following_gap_s < cfg["tailgater_gap_s"])
+    if ctx.collision_occurred:
+        trace.append("collision occurred (induced) -> FATAL override")
+        return Severity.FATAL, max(score, 1.0)
+    if hard_brake and tailgated:
+        trace.append(f"hard brake (>= {cfg['hard_brake_g']} g) with rear gap "
+                     f"< {cfg['tailgater_gap_s']} s -> CRITICAL rule "
+                     "(REQ-FP-02 [SYNTHETIC])")
+        return Severity.CRITICAL, max(score, cuts["critical"])
+    if score >= cuts["critical"]:
+        return Severity.CRITICAL, score
+    if score >= cuts["disruptive"]:
+        return Severity.DISRUPTIVE, score
+    return Severity.BENIGN, score
+
+
+def compute_severity(ctx: SeverityContext,
+                     config: Optional[Dict[str, Any]] = None) -> SeverityResult:
+    """Deterministic severity from contextual evidence. Pure function."""
+    cfg = config or POLICY_CONFIG
+    trace: List[str] = [f"policy {cfg['version']}"]
+    ft = ctx.failure_type.upper()
+    if ft in ("FALSE_NEGATIVE", "MISSED_DETECTION", "LATE_DETECTION"):
+        sev, score = _fn_severity(ctx, cfg, trace)
+    elif ft in ("FALSE_POSITIVE", "PHANTOM_OBJECT", "MISCLASSIFICATION_FP"):
+        sev, score = _fp_severity(ctx, cfg, trace)
+    elif ft == "MISCLASSIFICATION":
+        # Consequence-dominant: score both directions, take the worse.
+        t1: List[str] = []
+        t2: List[str] = []
+        s1 = _fn_severity(ctx, cfg, t1)
+        s2 = _fp_severity(ctx, cfg, t2)
+        order = [Severity.BENIGN, Severity.DISRUPTIVE, Severity.CRITICAL, Severity.FATAL]
+        if order.index(s1[0]) >= order.index(s2[0]):
+            sev, score = s1
+            trace += ["misclassification scored on FN consequence branch"] + t1
+        else:
+            sev, score = s2
+            trace += ["misclassification scored on FP consequence branch"] + t2
+    else:
+        trace.append(f"failure type '{ctx.failure_type}' has no severity model "
+                     "-> not computable, conservative DISRUPTIVE floor")
+        return SeverityResult(severity=Severity.DISRUPTIVE, score=0.0,
+                              rule_trace=trace, computable=False)
+    return SeverityResult(severity=sev, score=round(score, 4), rule_trace=trace)
+
+
+SEVERITY_ORDER = [Severity.BENIGN, Severity.DISRUPTIVE, Severity.CRITICAL,
+                  Severity.FATAL]
+
+
+class SeverityAdjudication(BaseModel):
+    policy_severity: Severity
+    ai_proposed_severity: Optional[Severity]
+    final_severity: Severity            # always the policy severity
+    divergence: bool
+    divergence_note: str = ""
+
+
+def adjudicate_severity(policy: SeverityResult,
+                        ai_proposed: Optional[Severity]) -> SeverityAdjudication:
+    """Policy validates/overrides the LLM proposal; divergence is recorded
+    and (by the caller) flagged for human review."""
+    divergence = ai_proposed is not None and ai_proposed != policy.severity
+    note = ""
+    if divergence:
+        direction = ("understated" if SEVERITY_ORDER.index(ai_proposed)
+                     < SEVERITY_ORDER.index(policy.severity) else "overstated")
+        note = (f"AI proposed {ai_proposed.value} but deterministic policy "
+                f"computed {policy.severity.value} (AI {direction} severity); "
+                "policy severity is authoritative and the divergence requires "
+                "human review")
+    return SeverityAdjudication(policy_severity=policy.severity,
+                                ai_proposed_severity=ai_proposed,
+                                final_severity=policy.severity,
+                                divergence=divergence, divergence_note=note)
+
+
+class LaunchDecision(BaseModel):
+    recommendation: LaunchRecommendation
+    rationale: List[str]
+    policy_version: str = POLICY_VERSION
+
+
+def launch_gate(severity: Severity,
+                has_evidence_gaps: bool,
+                scr_impact: Optional[float],
+                scr_significant: Optional[bool],
+                config: Optional[Dict[str, Any]] = None) -> LaunchDecision:
+    """Deterministic launch recommendation. INSUFFICIENT_EVIDENCE never
+    becomes PASS (SFS-LAUNCH-004 GATE-03 [SYNTHETIC], enforced here)."""
+    cfg = config or POLICY_CONFIG
+    rationale: List[str] = [f"policy {cfg['version']}"]
+
+    if has_evidence_gaps:
+        rationale.append("required evidence fields are UNKNOWN -> "
+                         "INSUFFICIENT_EVIDENCE (can never be converted to PASS; "
+                         "resolve evidence gaps and re-run)")
+        return LaunchDecision(recommendation=LaunchRecommendation.INSUFFICIENT_EVIDENCE,
+                              rationale=rationale)
+
+    if severity in (Severity.CRITICAL, Severity.FATAL):
+        rationale.append(f"unresolved {severity.value} severity -> FAIL (GATE-01)")
+        return LaunchDecision(recommendation=LaunchRecommendation.FAIL,
+                              rationale=rationale)
+
+    tol = cfg["scr_regression_tolerance"]
+    if scr_impact is not None and scr_impact < -tol and scr_significant:
+        rationale.append(f"safety-critical recall regressed {scr_impact:+.4f} "
+                         f"beyond tolerance {tol} with statistical significance "
+                         "-> FAIL (GATE-02)")
+        return LaunchDecision(recommendation=LaunchRecommendation.FAIL,
+                              rationale=rationale)
+
+    if severity == Severity.DISRUPTIVE:
+        rationale.append("DISRUPTIVE severity -> CONDITIONAL_PASS pending "
+                         "mitigation tracking")
+        return LaunchDecision(recommendation=LaunchRecommendation.CONDITIONAL_PASS,
+                              rationale=rationale)
+
+    if scr_impact is not None and scr_impact < -tol and scr_significant is None:
+        rationale.append(f"SCR delta {scr_impact:+.4f} beyond tolerance but "
+                         "significance not established -> CONDITIONAL_PASS "
+                         "pending seqeval confirmation")
+        return LaunchDecision(recommendation=LaunchRecommendation.CONDITIONAL_PASS,
+                              rationale=rationale)
+
+    rationale.append("BENIGN severity, no significant safety-critical recall "
+                     "regression -> PASS")
+    return LaunchDecision(recommendation=LaunchRecommendation.PASS,
+                          rationale=rationale)

sensorflow/retro/rag/__init__.py

@@ -0,0 +1,8 @@
+"""Safety-case RAG: parser -> chunking -> embeddings -> store -> retriever.
+
+The seed corpus is SYNTHETIC demonstration material. Every synthetic rule is
+tagged SYNTHETIC_EXAMPLE / NOT_A_REAL_STANDARD in both content and metadata;
+SOTIF (ISO 21448) entries are honest concept paraphrases labeled
+PARAPHRASE_NOT_STANDARD_TEXT. The retriever ALWAYS returns
+{source, document, version, section, retrieved_text, relevance_score}.
+"""

sensorflow/retro/rag/chunking.py

@@ -0,0 +1,74 @@
+"""Document parsing and configurable chunking.
+
+Documents are markdown-ish text with `## section` headings. The parser splits
+into sections (keeping section titles as metadata), and the chunker splits
+long sections into overlapping windows measured in words.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List
+
+from pydantic import BaseModel
+
+
+class Chunk(BaseModel):
+    chunk_id: str
+    text: str
+    metadata: Dict[str, str]
+
+
+def parse_sections(text: str) -> List[Dict[str, str]]:
+    """Split a document into {section, text} blocks on '## ' headings."""
+    sections: List[Dict[str, str]] = []
+    current_title = "preamble"
+    current_lines: List[str] = []
+    for line in text.splitlines():
+        m = re.match(r"^##\s+(.*)", line)
+        if m:
+            if current_lines and "".join(current_lines).strip():
+                sections.append({"section": current_title,
+                                 "text": "\n".join(current_lines).strip()})
+            current_title = m.group(1).strip()
+            current_lines = []
+        else:
+            current_lines.append(line)
+    if current_lines and "".join(current_lines).strip():
+        sections.append({"section": current_title,
+                         "text": "\n".join(current_lines).strip()})
+    return sections
+
+
+def chunk_words(text: str, chunk_size: int = 160, overlap: int = 40) -> List[str]:
+    """Overlapping word-window chunking. chunk_size/overlap are in words."""
+    if chunk_size <= 0:
+        raise ValueError("chunk_size must be positive")
+    if overlap >= chunk_size:
+        raise ValueError("overlap must be smaller than chunk_size")
+    words = text.split()
+    if len(words) <= chunk_size:
+        return [text.strip()] if text.strip() else []
+    step = chunk_size - overlap
+    chunks = []
+    for start in range(0, len(words), step):
+        window = words[start:start + chunk_size]
+        if not window:
+            break
+        chunks.append(" ".join(window))
+        if start + chunk_size >= len(words):
+            break
+    return chunks
+
+
+def chunk_document(doc_id: str, text: str, base_metadata: Dict[str, str],
+                   chunk_size: int = 160, overlap: int = 40) -> List[Chunk]:
+    """Parse into sections then chunk each section, propagating metadata."""
+    chunks: List[Chunk] = []
+    for si, sec in enumerate(parse_sections(text)):
+        for ci, piece in enumerate(chunk_words(sec["text"], chunk_size, overlap)):
+            meta = dict(base_metadata)
+            meta["section"] = sec["section"]
+            chunks.append(Chunk(chunk_id=f"{doc_id}:s{si}:c{ci}", text=piece,
+                                metadata=meta))
+    return chunks

sensorflow/retro/rag/corpus.py

@@ -0,0 +1,281 @@
+"""Seed safety-case corpus.
+
+EVERYTHING HERE IS SYNTHETIC DEMONSTRATION MATERIAL. Every synthetic rule is
+tagged SYNTHETIC_EXAMPLE / NOT_A_REAL_STANDARD in the text itself AND in the
+chunk metadata, so no rendering path can strip the label. The SOTIF document
+is an honest concept-level paraphrase of ISO 21448 ideas, explicitly labeled
+PARAPHRASE_NOT_STANDARD_TEXT — it contains no standard text and no clause
+numbers, and must never be cited as the standard.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+SYNTH = "SYNTHETIC_EXAMPLE / NOT_A_REAL_STANDARD"
+
+SEED_DOCUMENTS: List[Dict] = [
+    {
+        "doc_id": "SFS-SAFE-001",
+        "document": "Internal Perception Safety Requirements",
+        "source": "sensorflow-internal",
+        "version": "2.1",
+        "jurisdiction": "internal",
+        "doc_type": "safety_requirement",
+        "effective_date": "2026-01-15",
+        "synthetic": "true",
+        "label": SYNTH,
+        "text": f"""[{SYNTH}] Internal Perception Safety Requirements v2.1.
+
+## VRU detection within stopping distance
+[{SYNTH}] REQ-VRU-01: A vulnerable road user (pedestrian, cyclist,
+motorcyclist) that is inside the ego vehicle's current stopping distance
+envelope MUST be detected and tracked with safety-critical recall of at
+least 0.999 per exposure hour. A false negative (missed detection) of a
+pedestrian within stopping distance is classified at minimum CRITICAL and
+requires a retrospective before any launch decision. Degraded weather (rain,
+fog, spray) does not relax this requirement; it tightens the sensor fusion
+redundancy obligations in REQ-VRU-03.
+
+## False positive braking limits
+[{SYNTH}] REQ-FP-02: Phantom braking caused by misclassified static or
+low-mass clutter (plastic bag, cardboard, tire shred, road debris) MUST NOT
+produce a hard brake exceeding 0.35 g when no collision-relevant object is
+present. A phantom hard brake above this magnitude with following traffic
+present is classified at minimum DISRUPTIVE, and CRITICAL when rear
+time-gap is under 1.5 seconds, because induced rear-end collision risk
+transfers harm to other road users.
+
+## Detection latency budget
+[{SYNTH}] REQ-LAT-04: End-to-end perception-to-planner reaction latency
+(sensor timestamp to planner action) MUST NOT exceed 300 ms at P99 for
+objects inside the safety-critical zone. Latency consumed by perception
+reduces the remaining human or system reaction time budget and is charged
+against stopping distance in the safety case.
+
+## Sensor fusion disagreement
+[{SYNTH}] REQ-VRU-03: When camera and LiDAR disagree on the existence of a
+VRU-class object inside 2x stopping distance, the stack MUST treat the
+object as present (existence-favoring fusion) until disproven by two
+consecutive frames of agreement.""",
+    },
+    {
+        "doc_id": "SFS-LAUNCH-004",
+        "document": "Launch Criteria and Release Gate Policy",
+        "source": "sensorflow-internal",
+        "version": "3.0",
+        "jurisdiction": "internal",
+        "doc_type": "launch_criteria",
+        "effective_date": "2026-03-01",
+        "synthetic": "true",
+        "label": SYNTH,
+        "text": f"""[{SYNTH}] Launch Criteria and Release Gate Policy v3.0.
+
+## Launch gate conditions
+[{SYNTH}] GATE-01: A candidate model MUST NOT receive a PASS launch
+recommendation while any retrospective scorecard carries an unresolved
+severity of CRITICAL or FATAL. GATE-02: Safety-critical recall (SCR) on the
+criticality-weighted evaluation population must not regress versus baseline
+beyond the policy tolerance of 0.2 percentage points with statistical
+significance. GATE-03: A determination of INSUFFICIENT_EVIDENCE can never be
+converted into PASS by any agent, human or automated; the only allowed
+transitions are to CONDITIONAL_PASS after new evidence or to FAIL.
+
+## Human review triggers
+[{SYNTH}] GATE-05: Human review is mandatory when (a) severity is CRITICAL
+or FATAL, (b) the AI-proposed severity diverges from the deterministic
+policy severity, (c) any evidence field required by the scorecard is
+UNKNOWN, or (d) the analysis relied on fewer than two independent evidence
+sources.
+
+## Disengagement and collision-risk events
+[{SYNTH}] GATE-07: Any event with a collision-risk trajectory (predicted
+time-to-collision below 1.5 s against a VRU) or an actual disengagement
+attributed to perception MUST be retrospectively analyzed before the next
+release train, with the scorecard archived and auditable.""",
+    },
+    {
+        "doc_id": "SFS-PERC-002",
+        "document": "Perception Requirements in Degraded Conditions",
+        "source": "sensorflow-internal",
+        "version": "1.4",
+        "jurisdiction": "internal",
+        "doc_type": "perception_requirement",
+        "effective_date": "2025-11-20",
+        "synthetic": "true",
+        "label": SYNTH,
+        "text": f"""[{SYNTH}] Perception Requirements in Degraded Conditions v1.4.
+
+## Rain and spray degradation
+[{SYNTH}] REQ-WX-01: In measured rain rates up to 25 mm/h, pedestrian
+detection recall inside the safety-critical zone must degrade by no more
+than 0.5 percentage points versus clear-weather baseline. LiDAR point
+density loss and camera contrast loss must be compensated by fusion
+weighting, not by raising confidence thresholds, because threshold raising
+silently trades false positives for missed VRUs.
+
+## Confidence calibration
+[{SYNTH}] REQ-CAL-02: Detection confidence must be calibrated such that a
+reported confidence of 0.5 corresponds to an empirical precision between
+0.45 and 0.55 on the rolling evaluation window. Systematic underconfidence
+in rain is a known failure mode and must be tracked as a calibration defect,
+not compensated with global threshold changes.
+
+## Object class stability
+[{SYNTH}] REQ-CLS-03: Class flicker (an object toggling between classes such
+as vehicle and unknown or debris across consecutive frames) inside 2x
+stopping distance must trigger existence-favoring handling and is reportable
+evidence in any retrospective involving misclassification.""",
+    },
+    {
+        "doc_id": "SFS-ODD-003",
+        "document": "Operational Design Domain Definitions",
+        "source": "sensorflow-internal",
+        "version": "2.0",
+        "jurisdiction": "internal",
+        "doc_type": "odd_definition",
+        "effective_date": "2025-09-01",
+        "synthetic": "true",
+        "label": SYNTH,
+        "text": f"""[{SYNTH}] Operational Design Domain Definitions v2.0.
+
+## Urban ODD envelope
+[{SYNTH}] ODD-URB-01: The urban ODD covers divided and undivided surface
+streets with posted speeds up to 45 mph (20.1 m/s), signalized and
+unsignalized intersections, and marked crosswalks. Ego speed above the
+posted limit voids the ODD envelope for analysis purposes.
+
+## Weather boundaries
+[{SYNTH}] ODD-WX-02: Operation is inside ODD in light-to-moderate rain
+(under 25 mm/h) with functional wipers and defog. Heavy rain above 25 mm/h,
+standing water, and night-plus-heavy-rain combinations are OUTSIDE the
+current ODD; events occurring there are ODD-exit events, and the correct
+system response is a minimal-risk maneuver, not continued operation.
+
+## Analysis obligations
+[{SYNTH}] ODD-AN-03: Every retrospective must state whether the event was
+inside or outside ODD, because requirements applicability, severity
+weighting, and launch gating differ. Outside-ODD events still require
+analysis of whether the ODD-exit detection itself functioned.""",
+    },
+    {
+        "doc_id": "SFS-RETRO-HIST-01",
+        "document": "Historical Retrospectives Digest",
+        "source": "sensorflow-internal",
+        "version": "1.0",
+        "jurisdiction": "internal",
+        "doc_type": "historical_retrospective",
+        "effective_date": "2025-12-10",
+        "synthetic": "true",
+        "label": SYNTH,
+        "text": f"""[{SYNTH}] Historical Retrospectives Digest v1.0.
+
+## RETRO-2025-014 phantom braking cluster
+[{SYNTH}] Twelve phantom hard-brake events in one quarter were traced to
+low-mass road debris (plastic bags, mylar balloons) being classified as
+vehicle or unknown-obstacle with high confidence at 30-60 m range. Root
+cause hypothesis confirmed: training distribution lacked wind-blown
+deformable objects; the tracker latched a spurious velocity toward ego from
+bag motion, producing a false closing-velocity estimate and an unwarranted
+emergency braking response. Fix: hard-negative mining of deformable clutter
+plus track-consistency gating on mass-plausibility. Post-fix phantom brake
+rate fell 87 percent.
+
+## RETRO-2025-021 missed pedestrian in rain
+[{SYNTH}] A pedestrian in dark clothing crossing mid-block in moderate rain
+at night was detected 1.9 s later than required, inside stopping distance.
+Camera contrast was degraded and LiDAR returns were attenuated by spray;
+fusion confidence stayed below the tracking threshold for 6 consecutive
+frames. The planner received the object late and executed a hard brake with
+residual collision risk. Contributing factors: confidence threshold raised
+globally two releases earlier to suppress rain clutter false positives —
+exactly the trade REQ-WX-01 prohibits. Fix: rain-conditioned fusion
+weighting and restoration of threshold, plus targeted rain-night pedestrian
+data collection.""",
+    },
+    {
+        "doc_id": "SFS-EVAL-005",
+        "document": "Evaluation Policies for Safety-Relevant Metrics",
+        "source": "sensorflow-internal",
+        "version": "1.2",
+        "jurisdiction": "internal",
+        "doc_type": "evaluation_policy",
+        "effective_date": "2026-02-05",
+        "synthetic": "true",
+        "label": SYNTH,
+        "text": f"""[{SYNTH}] Evaluation Policies for Safety-Relevant Metrics v1.2.
+
+## Safety-critical recall definition
+[{SYNTH}] EVAL-SCR-01: Safety-critical recall (SCR) is recall computed only
+over ground-truth objects whose criticality context meets the policy
+criteria: object inside 1.5x stopping distance, closing relative velocity,
+and VRU class or collision-relevant mass. SCR is reported with its
+denominator; an SCR delta without a criticality-context denominator is not
+admissible launch evidence.
+
+## Asymmetric error costs
+[{SYNTH}] EVAL-COST-02: False negatives and false positives carry
+asymmetric, CONTEXT-DEPENDENT costs. A missed distant non-closing object can
+be BENIGN while a phantom hard brake with a tailgater can be CRITICAL. Cost
+is computed from context (class, distance versus stopping distance, relative
+motion, remaining reaction time, intervention magnitude), never from the
+error type alone.
+
+## Statistical significance
+[{SYNTH}] EVAL-SIG-03: Metric deltas feeding launch decisions must carry
+anytime-valid confidence sequences (the platform's seqeval machinery) or an
+explicit NOT_SIGNIFICANT marker. Point deltas without uncertainty are
+inadmissible.""",
+    },
+    {
+        "doc_id": "SOTIF-CONCEPTS-21448",
+        "document": "SOTIF (ISO 21448) Concept Summary",
+        "source": "public-standard-paraphrase",
+        "version": "concept-summary-1.0",
+        "jurisdiction": "international",
+        "doc_type": "standard_concept_paraphrase",
+        "effective_date": "2022-06-01",
+        "synthetic": "false",
+        "label": "PARAPHRASE_NOT_STANDARD_TEXT",
+        "text": """[PARAPHRASE_NOT_STANDARD_TEXT] This is an honest concept-level
+paraphrase of ideas associated with ISO 21448 (Safety of the Intended
+Functionality, SOTIF). It contains NO standard text and NO clause numbers
+and must never be cited as the standard itself.
+
+## Functional insufficiency
+[PARAPHRASE_NOT_STANDARD_TEXT] SOTIF addresses hazards that arise not from
+component faults but from performance limitations of the intended
+functionality — for example a perception stack whose sensor physics or
+training distribution is insufficient for a scenario (heavy rain, unusual
+object appearance). A missed pedestrian in rain with no hardware fault is a
+canonical SOTIF-style functional insufficiency, not a malfunction.
+
+## Triggering conditions and scenario space
+[PARAPHRASE_NOT_STANDARD_TEXT] The concept framework partitions scenarios
+into known-safe, known-hazardous, and unknown-hazardous. Engineering effort
+aims to discover unknown-hazardous scenarios (triggering conditions such as
+specific weather, lighting, or object configurations) and move them into the
+known space, then reduce their residual risk through requirements, data,
+or ODD restriction.
+
+## Verification and validation implication
+[PARAPHRASE_NOT_STANDARD_TEXT] Retrospective analysis of field failures is
+one of the accepted mechanisms for discovering triggering conditions.
+Evidence from such analysis feeds requirement updates and validation
+targets; residual risk acceptance must be argued, not assumed.""",
+    },
+]
+
+
+def corpus_metadata(doc: Dict) -> Dict[str, str]:
+    return {
+        "doc_id": doc["doc_id"],
+        "document": doc["document"],
+        "source": doc["source"],
+        "version": doc["version"],
+        "jurisdiction": doc["jurisdiction"],
+        "doc_type": doc["doc_type"],
+        "effective_date": doc["effective_date"],
+        "synthetic": doc["synthetic"],
+        "label": doc["label"],
+    }

sensorflow/retro/rag/embedder.py

@@ -0,0 +1,64 @@
+"""Embedding layer with an honest, documented tradeoff.
+
+Preferred path: chromadb's bundled embedder (all-MiniLM-L6-v2 via ONNX) when
+chromadb is installed — real semantic embeddings.
+
+Fallback path (always available): a deterministic hashed TF vector embedder.
+Tradeoff: the hashing embedder is purely LEXICAL — it captures word overlap
+(with sublinear term-frequency weighting and stable feature hashing) but has
+zero semantic generalization ("pedestrian" and "person on foot" do not
+match). For this package's seed corpus, which uses consistent engineering
+vocabulary, lexical retrieval is adequate and — critically — fully
+deterministic and dependency-free, which the test suite relies on.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import List
+
+import numpy as np
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+# Common words that would otherwise dominate hashed-TF cosine similarity.
+_STOPWORDS = frozenset(
+    "a an and are as at be by for from has have in is it its of on or that the "
+    "this to was were will with within must shall should not no".split())
+
+
+class HashedTfEmbedder:
+    """Deterministic hashed term-frequency embedder (numpy only)."""
+
+    name = "hashed-tf-fallback"
+
+    def __init__(self, dim: int = 1024):
+        self.dim = dim
+
+    def _bucket(self, token: str) -> int:
+        return int.from_bytes(hashlib.md5(token.encode()).digest()[:4], "little") % self.dim
+
+    def embed(self, texts: List[str]) -> np.ndarray:
+        out = np.zeros((len(texts), self.dim), dtype=np.float64)
+        for i, text in enumerate(texts):
+            for tok in _TOKEN_RE.findall(text.lower()):
+                if tok in _STOPWORDS:
+                    continue
+                out[i, self._bucket(tok)] += 1.0
+            # sublinear tf then L2 normalize
+            nz = out[i] > 0
+            out[i, nz] = 1.0 + np.log(out[i, nz])
+            norm = math.sqrt(float(np.dot(out[i], out[i])))
+            if norm > 0:
+                out[i] /= norm
+        return out
+
+
+def chromadb_available() -> bool:
+    try:
+        import chromadb  # noqa: F401
+        return True
+    except ImportError:
+        return False

sensorflow/retro/rag/evalharness.py

@@ -0,0 +1,83 @@
+"""Retrieval evaluation harness: query set with expected-source assertions.
+
+precision@k here means: fraction of queries whose expected doc_id appears in
+the top-k results (a.k.a. hit-rate@k / recall@k over one relevant document
+per query — reported explicitly so nobody mistakes it for a graded metric).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel
+
+from sensorflow.retro.rag.retriever import SafetyCaseIndex, get_index
+
+# Each query names the doc that a correct retriever must surface.
+EVAL_QUERIES: List[Dict[str, str]] = [
+    {"query": "pedestrian missed inside stopping distance recall requirement",
+     "expected_doc_id": "SFS-SAFE-001"},
+    {"query": "phantom braking limits for plastic bag road debris misclassification",
+     "expected_doc_id": "SFS-SAFE-001"},
+    {"query": "launch gate CRITICAL severity unresolved scorecard PASS blocked",
+     "expected_doc_id": "SFS-LAUNCH-004"},
+    {"query": "INSUFFICIENT_EVIDENCE can never become PASS",
+     "expected_doc_id": "SFS-LAUNCH-004"},
+    {"query": "rain degradation pedestrian recall confidence threshold raising prohibited",
+     "expected_doc_id": "SFS-PERC-002"},
+    {"query": "confidence calibration empirical precision rolling window",
+     "expected_doc_id": "SFS-PERC-002"},
+    {"query": "urban ODD posted speed crosswalk envelope",
+     "expected_doc_id": "SFS-ODD-003"},
+    {"query": "heavy rain outside ODD minimal-risk maneuver",
+     "expected_doc_id": "SFS-ODD-003"},
+    {"query": "historical retrospective phantom brake mylar balloon deformable clutter",
+     "expected_doc_id": "SFS-RETRO-HIST-01"},
+    {"query": "pedestrian dark clothing rain night fusion confidence below tracking threshold",
+     "expected_doc_id": "SFS-RETRO-HIST-01"},
+    {"query": "safety-critical recall SCR denominator criticality context",
+     "expected_doc_id": "SFS-EVAL-005"},
+    {"query": "asymmetric false negative false positive cost context dependent",
+     "expected_doc_id": "SFS-EVAL-005"},
+    {"query": "SOTIF functional insufficiency performance limitation intended functionality",
+     "expected_doc_id": "SOTIF-CONCEPTS-21448"},
+    {"query": "unknown hazardous scenarios triggering conditions discovery",
+     "expected_doc_id": "SOTIF-CONCEPTS-21448"},
+]
+
+
+class QueryResult(BaseModel):
+    query: str
+    expected_doc_id: str
+    hit_at_k: bool
+    top_doc_ids: List[str]
+    top_score: float
+
+
+class RetrievalEvalReport(BaseModel):
+    k: int
+    num_queries: int
+    num_hits: int
+    precision_at_k: float  # hit-rate@k with one relevant doc per query
+    store_backend: str
+    results: List[QueryResult]
+
+
+def run_retrieval_eval(index: Optional[SafetyCaseIndex] = None,
+                       k: int = 4) -> RetrievalEvalReport:
+    index = index or get_index()
+    results: List[QueryResult] = []
+    hits = 0
+    for item in EVAL_QUERIES:
+        found = index.search(item["query"], k=k)
+        doc_ids = [f.doc_id for f in found]
+        hit = item["expected_doc_id"] in doc_ids
+        hits += int(hit)
+        results.append(QueryResult(
+            query=item["query"], expected_doc_id=item["expected_doc_id"],
+            hit_at_k=hit, top_doc_ids=doc_ids,
+            top_score=found[0].relevance_score if found else 0.0))
+    return RetrievalEvalReport(
+        k=k, num_queries=len(EVAL_QUERIES), num_hits=hits,
+        precision_at_k=round(hits / len(EVAL_QUERIES), 4),
+        store_backend=index.backend_name, results=results)

sensorflow/retro/rag/retriever.py

@@ -0,0 +1,81 @@
+"""Retriever over the safety-case index.
+
+Every hit is returned as a RetrievedStandard carrying
+{source, document, version, section, retrieved_text, relevance_score} —
+ALWAYS, with no optional escape hatch. The scorecard layer refuses citations
+that are not instances of this model (the no-citation-without-retrieval
+rule, enforced and tested).
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import List, Optional
+
+from sensorflow.retro.rag.chunking import chunk_document
+from sensorflow.retro.rag.corpus import SEED_DOCUMENTS, corpus_metadata
+from sensorflow.retro.rag.store import VectorStore, build_store
+from sensorflow.retro.scorecard import RetrievedStandard
+
+
+class SafetyCaseIndex:
+    def __init__(self, store: Optional[VectorStore] = None,
+                 chunk_size: int = 160, overlap: int = 40):
+        self.store = store or build_store()
+        self.chunk_size = chunk_size
+        self.overlap = overlap
+        self._loaded_docs = 0
+        self._load_seed_corpus()
+
+    @property
+    def backend_name(self) -> str:
+        return self.store.backend_name
+
+    def _load_seed_corpus(self) -> None:
+        ids: List[str] = []
+        texts: List[str] = []
+        metas: List[dict] = []
+        for doc in SEED_DOCUMENTS:
+            base_meta = corpus_metadata(doc)
+            for chunk in chunk_document(doc["doc_id"], doc["text"], base_meta,
+                                        self.chunk_size, self.overlap):
+                ids.append(chunk.chunk_id)
+                texts.append(chunk.text)
+                metas.append(chunk.metadata)
+        self.store.add(ids, texts, metas)
+        self._loaded_docs = len(SEED_DOCUMENTS)
+
+    def search(self, query: str, k: int = 4) -> List[RetrievedStandard]:
+        hits = self.store.query(query, k=k)
+        out: List[RetrievedStandard] = []
+        for h in hits:
+            meta = h.metadata
+            out.append(RetrievedStandard(
+                source=meta.get("source", "unknown"),
+                document=meta.get("document", meta.get("doc_id", "unknown")),
+                version=meta.get("version", "unknown"),
+                section=meta.get("section", "unknown"),
+                retrieved_text=h.text,
+                relevance_score=round(h.relevance_score, 4),
+                doc_id=meta.get("doc_id", "unknown"),
+                doc_type=meta.get("doc_type", "unknown"),
+                jurisdiction=meta.get("jurisdiction", "unknown"),
+                effective_date=meta.get("effective_date", "unknown"),
+                synthetic=meta.get("synthetic", "true") == "true",
+                label=meta.get("label", ""),
+                chunk_id=h.chunk_id,
+            ))
+        return out
+
+
+_INDEX: Optional[SafetyCaseIndex] = None
+_INDEX_LOCK = threading.Lock()
+
+
+def get_index() -> SafetyCaseIndex:
+    """Process-wide lazily-built index (seed corpus is static)."""
+    global _INDEX
+    with _INDEX_LOCK:
+        if _INDEX is None:
+            _INDEX = SafetyCaseIndex()
+        return _INDEX

sensorflow/retro/rag/store.py

@@ -0,0 +1,112 @@
+"""Vector store with two interchangeable implementations.
+
+- ChromaStore: chromadb (its bundled embedder), when installed.
+- NumpyCosineStore: deterministic hashed-TF embeddings + cosine similarity.
+
+Both expose the exact same interface: add(ids, texts, metadatas) and
+query(text, k) -> List[StoreHit]. build_store() picks chroma when available
+unless RETRO_FORCE_FALLBACK_STORE=1.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, List, Optional, Protocol
+
+import numpy as np
+from pydantic import BaseModel
+
+from sensorflow.retro.rag.embedder import HashedTfEmbedder, chromadb_available
+
+
+class StoreHit(BaseModel):
+    chunk_id: str
+    text: str
+    metadata: Dict[str, str]
+    relevance_score: float  # cosine similarity in [0, 1] (clipped)
+
+
+class VectorStore(Protocol):
+    backend_name: str
+
+    def add(self, ids: List[str], texts: List[str],
+            metadatas: List[Dict[str, str]]) -> None: ...
+
+    def query(self, text: str, k: int = 5) -> List[StoreHit]: ...
+
+
+class NumpyCosineStore:
+    """Deterministic fallback store: hashed-TF embeddings, cosine ranking."""
+
+    backend_name = "numpy-cosine-fallback"
+
+    def __init__(self, embedder: Optional[HashedTfEmbedder] = None):
+        self.embedder = embedder or HashedTfEmbedder()
+        self._ids: List[str] = []
+        self._texts: List[str] = []
+        self._metas: List[Dict[str, str]] = []
+        self._matrix: Optional[np.ndarray] = None
+
+    def add(self, ids: List[str], texts: List[str],
+            metadatas: List[Dict[str, str]]) -> None:
+        if not (len(ids) == len(texts) == len(metadatas)):
+            raise ValueError("ids/texts/metadatas length mismatch")
+        self._ids.extend(ids)
+        self._texts.extend(texts)
+        self._metas.extend(metadatas)
+        embs = self.embedder.embed(texts)
+        self._matrix = embs if self._matrix is None else np.vstack([self._matrix, embs])
+
+    def query(self, text: str, k: int = 5) -> List[StoreHit]:
+        if self._matrix is None or not self._ids:
+            return []
+        q = self.embedder.embed([text])[0]
+        sims = self._matrix @ q  # rows are L2-normalized -> dot = cosine
+        order = np.argsort(-sims)[:k]
+        return [StoreHit(chunk_id=self._ids[i], text=self._texts[i],
+                         metadata=self._metas[i],
+                         relevance_score=float(np.clip(sims[i], 0.0, 1.0)))
+                for i in order]
+
+
+class ChromaStore:
+    """chromadb-backed store using its default bundled embedder."""
+
+    backend_name = "chromadb"
+
+    def __init__(self, collection_name: str = "retro_safety_case"):
+        import chromadb
+        self._client = chromadb.EphemeralClient()
+        try:
+            self._client.delete_collection(collection_name)
+        except Exception:
+            pass
+        self._collection = self._client.create_collection(
+            collection_name, metadata={"hnsw:space": "cosine"})
+
+    def add(self, ids: List[str], texts: List[str],
+            metadatas: List[Dict[str, str]]) -> None:
+        self._collection.add(ids=ids, documents=texts, metadatas=metadatas)
+
+    def query(self, text: str, k: int = 5) -> List[StoreHit]:
+        res = self._collection.query(query_texts=[text], n_results=k)
+        hits: List[StoreHit] = []
+        for i, cid in enumerate(res["ids"][0]):
+            distance = float(res["distances"][0][i])  # cosine distance
+            hits.append(StoreHit(
+                chunk_id=cid,
+                text=res["documents"][0][i],
+                metadata={k2: str(v) for k2, v in (res["metadatas"][0][i] or {}).items()},
+                relevance_score=float(np.clip(1.0 - distance, 0.0, 1.0))))
+        return hits
+
+
+def build_store() -> VectorStore:
+    if chromadb_available() and os.environ.get("RETRO_FORCE_FALLBACK_STORE") != "1":
+        try:
+            return ChromaStore()
+        except Exception:
+            # chromadb installed but not functional (e.g. onnxruntime issue):
+            # fall back rather than fail — the interface is identical.
+            pass
+    return NumpyCosineStore()

sensorflow/retro/requirements-retro.txt

@@ -0,0 +1,27 @@
+# Retro (Agentic Retrospective Safety Analyzer) dependencies.
+#
+# Hard requirements — already part of the platform environment:
+pydantic>=2.6
+httpx>=0.27
+numpy>=1.26
+fastapi>=0.110
+
+# Optional — the package degrades gracefully when these are absent:
+#   chromadb        vector store + embedder for the safety-case RAG.
+#                   Fallback: deterministic hashed TF-IDF embedder + numpy
+#                   cosine store with the same interface (rag/embedder.py,
+#                   rag/store.py).
+# chromadb>=0.5
+#
+#   pydantic-ai     agent orchestration. Fallback: internal typed tool loop
+#                   (agent/orchestrator.py) with the same contracts.
+# pydantic-ai-slim>=0.0.30
+#
+#   mcp             exposes the tool registry as a real MCP server (bonus).
+#                   Fallback: the audited registry itself is the MCP-style
+#                   boundary (tools/registry.py).
+# mcp>=1.0
+
+# GPU-host only (NOT installable/runnable on this macOS dev machine):
+#   vllm>=0.6       # CUDA/ROCm Linux hosts; see inference/vllm_server/
+#   torch           # install the wheel matching your GPU stack

sensorflow/retro/scorecard.py

@@ -0,0 +1,240 @@
+"""Evidence hierarchy and the strictly-typed RetrospectiveScorecard.
+
+Tier semantics (enforced in types, rendered distinctly):
+    TIER1_OBSERVED      FACT — read directly from the failure artifact.
+    TIER2_DERIVED       DERIVED FACT — deterministically computed from facts.
+    TIER3_RETRIEVED     RETRIEVED REQUIREMENT — backed by a retrieval hit.
+    TIER4_AI_HYPOTHESIS AI HYPOTHESIS — inference, never presented as fact.
+The SAFETY DETERMINATION (severity + launch recommendation) is produced only
+by the deterministic policy engine (sensorflow.retro.policy).
+
+The no-citation-without-retrieval rule lives here: RetrievedStandard has NO
+optional escape hatch — a citation cannot be constructed without the actual
+retrieved text, its relevance score, and its source metadata.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+UNKNOWN = "UNKNOWN"
+INSUFFICIENT_EVIDENCE = "INSUFFICIENT_EVIDENCE"
+
+
+class EvidenceTier(str, Enum):
+    OBSERVED = "TIER1_OBSERVED"
+    DERIVED = "TIER2_DERIVED"
+    RETRIEVED = "TIER3_RETRIEVED"
+    AI_HYPOTHESIS = "TIER4_AI_HYPOTHESIS"
+
+
+TIER_RENDER_NAMES = {
+    EvidenceTier.OBSERVED: "FACT",
+    EvidenceTier.DERIVED: "DERIVED FACT",
+    EvidenceTier.RETRIEVED: "RETRIEVED REQUIREMENT",
+    EvidenceTier.AI_HYPOTHESIS: "AI HYPOTHESIS",
+}
+
+
+class Severity(str, Enum):
+    BENIGN = "BENIGN"
+    DISRUPTIVE = "DISRUPTIVE"
+    CRITICAL = "CRITICAL"
+    FATAL = "FATAL"
+
+
+class LaunchRecommendation(str, Enum):
+    PASS = "PASS"
+    CONDITIONAL_PASS = "CONDITIONAL_PASS"
+    FAIL = "FAIL"
+    INSUFFICIENT_EVIDENCE = "INSUFFICIENT_EVIDENCE"
+
+
+class EvidenceItem(BaseModel):
+    tier: EvidenceTier
+    key: str                        # machine key, e.g. "ego_speed_mps"
+    statement: str                  # human-readable statement
+    value: Optional[str] = None     # string form; UNKNOWN if absent
+    provenance: str                 # where this came from (field/tool/doc/agent)
+
+    @field_validator("statement")
+    @classmethod
+    def _nonempty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("evidence statement must be non-empty")
+        return v
+
+
+class RetrievedStandard(BaseModel):
+    """A citation. Constructible ONLY with real retrieval output."""
+    source: str
+    document: str
+    version: str
+    section: str
+    retrieved_text: str = Field(min_length=20)
+    relevance_score: float = Field(ge=0.0, le=1.0)
+    doc_id: str
+    doc_type: str
+    jurisdiction: str
+    effective_date: str
+    synthetic: bool
+    label: str                      # SYNTHETIC_EXAMPLE... or PARAPHRASE...
+    chunk_id: str
+
+
+class RootCauseHypothesis(BaseModel):
+    hypothesis: str
+    confidence: float = Field(ge=0.0, le=1.0)
+    supporting_evidence_keys: List[str] = Field(default_factory=list)
+    missing_evidence: List[str] = Field(default_factory=list)
+    tier: EvidenceTier = EvidenceTier.AI_HYPOTHESIS
+
+    @field_validator("tier")
+    @classmethod
+    def _hypothesis_is_never_fact(cls, v: EvidenceTier) -> EvidenceTier:
+        if v != EvidenceTier.AI_HYPOTHESIS:
+            raise ValueError("root-cause hypotheses are always TIER4_AI_HYPOTHESIS")
+        return v
+
+
+class StatSignificance(BaseModel):
+    method: str                      # e.g. "seqeval.PairedSequentialTest"
+    significant: Optional[bool]      # None => not evaluable from this artifact
+    detail: str
+
+
+class UncertaintyReport(BaseModel):
+    missing_fields: List[str] = Field(default_factory=list)
+    unknown_metrics: List[str] = Field(default_factory=list)
+    notes: List[str] = Field(default_factory=list)
+
+    @property
+    def has_gaps(self) -> bool:
+        return bool(self.missing_fields or self.unknown_metrics)
+
+
+class RetrospectiveScorecard(BaseModel):
+    # identity / provenance
+    evaluation_id: str
+    created_at: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    policy_version: str
+    agent_version: str
+    backend_used: str
+
+    # classification
+    failure_type: str               # FALSE_POSITIVE | FALSE_NEGATIVE | ...
+    severity: Severity              # POLICY-decided severity (authoritative)
+    ai_proposed_severity: Optional[Severity] = None
+    severity_divergence: bool = False
+    safety_critical_recall_impact: Optional[float] = None
+    scr_impact_detail: str = ""
+    behavioral_consequence: str
+    launch_recommendation: LaunchRecommendation
+    launch_rationale: List[str] = Field(default_factory=list)
+
+    # context
+    baseline_model: Optional[str] = None
+    candidate_model: Optional[str] = None
+    scenario: Dict[str, Any] = Field(default_factory=dict)
+    object_class: Optional[str] = None
+    ground_truth: Optional[Dict[str, Any]] = None
+    prediction: Optional[Dict[str, Any]] = None
+    confidence: Optional[float] = None
+
+    # kinematics / behavior (None => UNKNOWN, listed in uncertainty)
+    ego_speed_mps: Optional[float] = None
+    distance_to_object_m: Optional[float] = None
+    relative_velocity_mps: Optional[float] = None
+    stopping_distance_m: Optional[float] = None
+    ttc_s: Optional[float] = None
+    ttc_validity: List[str] = Field(default_factory=list)
+    planner_response: Optional[Dict[str, Any]] = None
+    disengagement_probability: Optional[float] = None
+
+    # statistics
+    metric_delta: Optional[Dict[str, float]] = None
+    statistical_significance: Optional[StatSignificance] = None
+    distribution_shift: Optional[Dict[str, Any]] = None
+
+    # evidence chain
+    root_cause_hypotheses: List[RootCauseHypothesis] = Field(default_factory=list)
+    evidence: List[EvidenceItem] = Field(min_length=1)
+    retrieved_standards: List[RetrievedStandard] = Field(default_factory=list)
+    uncertainty: UncertaintyReport
+    human_review_required: bool
+    human_review_reasons: List[str] = Field(default_factory=list)
+
+    def evidence_by_tier(self, tier: EvidenceTier) -> List[EvidenceItem]:
+        return [e for e in self.evidence if e.tier == tier]
+
+    # ------------------------------------------------------------- rendering
+
+    def render_markdown(self) -> str:
+        lines: List[str] = [
+            f"# Retrospective Scorecard — {self.evaluation_id}",
+            "",
+            f"- **Failure type:** {self.failure_type}",
+            f"- **Severity (policy determination):** {self.severity.value}"
+            + (f"  _(AI proposed {self.ai_proposed_severity.value}; divergence "
+               f"flagged for human review)_" if self.severity_divergence
+               and self.ai_proposed_severity else ""),
+            f"- **Launch recommendation:** {self.launch_recommendation.value}",
+            f"- **Human review required:** "
+            f"{'YES — ' + '; '.join(self.human_review_reasons) if self.human_review_required else 'no'}",
+            f"- **Models:** baseline={self.baseline_model or UNKNOWN} "
+            f"candidate={self.candidate_model or UNKNOWN}",
+            f"- **Policy/agent:** {self.policy_version} / {self.agent_version} "
+            f"(backend: {self.backend_used})",
+            "",
+            "## Evidence chain (tiered)",
+        ]
+        for tier in EvidenceTier:
+            items = self.evidence_by_tier(tier)
+            if not items:
+                continue
+            lines.append(f"### {TIER_RENDER_NAMES[tier]} ({tier.value})")
+            for e in items:
+                val = f" = `{e.value}`" if e.value is not None else ""
+                lines.append(f"- **{e.key}**{val}: {e.statement}  \n"
+                             f"  _provenance: {e.provenance}_")
+            lines.append("")
+
+        lines.append("## RETRIEVED REQUIREMENTS (citations)")
+        if not self.retrieved_standards:
+            lines.append("_none retrieved — no requirement is cited_")
+        for s in self.retrieved_standards:
+            lines.append(
+                f"- **[{s.label}]** {s.document} v{s.version} — §{s.section} "
+                f"(source: {s.source}, relevance {s.relevance_score:.2f})  \n"
+                f"  > {s.retrieved_text[:280]}{'…' if len(s.retrieved_text) > 280 else ''}")
+        lines.append("")
+
+        lines.append("## AI HYPOTHESES (inference — never fact)")
+        for h in self.root_cause_hypotheses:
+            lines.append(f"- ({h.confidence:.0%} confidence) {h.hypothesis}  \n"
+                         f"  _supported by: {', '.join(h.supporting_evidence_keys) or 'n/a'};"
+                         f" missing: {', '.join(h.missing_evidence) or 'none'}_")
+        lines.append("")
+
+        lines.append("## SAFETY DETERMINATION (deterministic policy)")
+        lines.append(f"- Severity: **{self.severity.value}**")
+        lines.append(f"- Launch: **{self.launch_recommendation.value}**")
+        for r in self.launch_rationale:
+            lines.append(f"  - {r}")
+        lines.append("")
+
+        if self.uncertainty.has_gaps:
+            lines.append("## UNCERTAINTY / MISSING EVIDENCE")
+            for f in self.uncertainty.missing_fields:
+                lines.append(f"- missing field: `{f}` -> {UNKNOWN}")
+            for m in self.uncertainty.unknown_metrics:
+                lines.append(f"- metric not computable: `{m}` -> {UNKNOWN}")
+            for n in self.uncertainty.notes:
+                lines.append(f"- {n}")
+
+        return "\n".join(lines)

sensorflow/retro/store.py

@@ -0,0 +1,86 @@
+"""Persistence for retro artifacts under runs/retro/.
+
+    runs/retro/analyses/<evaluation_id>.json   scorecard + metadata
+    runs/retro/audit/<analysis_id>.jsonl       tool-call audit trail
+    runs/retro/eval_cases/<case_id>.json       cases created by the write tool
+    runs/retro/uploads/<name>.json             uploaded logs (allowlisted reads)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, List, Optional
+
+def root() -> Path:
+    """Resolved per call so tests can isolate via RETRO_RUNS_DIR."""
+    return Path(os.environ.get("RETRO_RUNS_DIR", "runs/retro"))
+
+
+def _dir(name: str) -> Path:
+    d = root() / name
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def analyses_dir() -> Path:
+    return _dir("analyses")
+
+
+def audit_dir() -> Path:
+    return _dir("audit")
+
+
+def eval_cases_dir() -> Path:
+    return _dir("eval_cases")
+
+
+def uploads_dir() -> Path:
+    return _dir("uploads")
+
+
+def save_analysis(evaluation_id: str, payload: Dict) -> Path:
+    path = analyses_dir() / f"{evaluation_id}.json"
+    path.write_text(json.dumps(payload, indent=2))
+    return path
+
+
+def load_analysis(evaluation_id: str) -> Optional[Dict]:
+    path = analyses_dir() / f"{evaluation_id}.json"
+    if not path.exists():
+        return None
+    return json.loads(path.read_text())
+
+
+def list_analyses() -> List[Dict]:
+    out = []
+    for p in sorted(analyses_dir().glob("*.json")):
+        try:
+            data = json.loads(p.read_text())
+            sc = data.get("scorecard", {})
+            out.append({
+                "evaluation_id": sc.get("evaluation_id", p.stem),
+                "created_at": sc.get("created_at"),
+                "failure_type": sc.get("failure_type"),
+                "severity": sc.get("severity"),
+                "launch_recommendation": sc.get("launch_recommendation"),
+                "backend_used": sc.get("backend_used"),
+                "human_review_required": sc.get("human_review_required"),
+            })
+        except (json.JSONDecodeError, OSError):
+            continue
+    return out
+
+
+def append_audit(analysis_id: str, record: Dict) -> None:
+    path = audit_dir() / f"{analysis_id}.jsonl"
+    with path.open("a") as f:
+        f.write(json.dumps(record) + "\n")
+
+
+def read_audit(analysis_id: str) -> List[Dict]:
+    path = audit_dir() / f"{analysis_id}.jsonl"
+    if not path.exists():
+        return []
+    return [json.loads(line) for line in path.read_text().splitlines() if line.strip()]

sensorflow/retro/tools/__init__.py

@@ -0,0 +1 @@
+"""MCP-style audited tool registry and the built-in analysis tools."""

sensorflow/retro/tools/builtin.py

@@ -0,0 +1,308 @@
+"""Built-in analysis tools registered on the audited registry.
+
+All tools are read-only except CreateEvaluationCaseTool, which requires an
+explicit policy_authorization flag per call (enforced by the registry).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import numpy as np
+from pydantic import BaseModel, Field
+
+from sensorflow.retro import metrics, store
+from sensorflow.retro.rag.embedder import HashedTfEmbedder
+from sensorflow.retro.rag.retriever import get_index
+from sensorflow.retro.tools.registry import ToolRegistry
+
+FIXTURES_DIR = Path(__file__).resolve().parent.parent / "fixtures"
+
+# Dotted paths the analyzer needs; absent ones become UNKNOWN, never guessed.
+REQUIRED_FIELDS = [
+    "ego.speed_mps",
+    "ground_truth.class",
+    "ground_truth.distance_m",
+    "ground_truth.relative_velocity_mps",
+    "planner_response",
+    "counterfactual_planner_response",
+    "timing.detection_latency_ms",
+    "timing.planner_latency_ms",
+    "scenario.weather",
+    "models.baseline",
+    "models.candidate",
+    "collision",
+    "traffic_context.following_vehicle",
+]
+
+
+def _dotted_get(obj: Dict[str, Any], path: str) -> Any:
+    cur: Any = obj
+    for part in path.split("."):
+        if not isinstance(cur, dict) or part not in cur or cur[part] is None:
+            return None
+        cur = cur[part]
+    return cur
+
+
+# ------------------------------------------------------------- LogReaderTool
+
+class LogReaderInput(BaseModel):
+    fixture_id: Optional[str] = Field(
+        None, description="fixture name (stem) under sensorflow/retro/fixtures")
+    path: Optional[str] = Field(
+        None, description="path under the approved allowlist "
+                          "(runs/retro/uploads or the fixtures dir)")
+
+
+class LogReaderOutput(BaseModel):
+    source_path: str
+    log: Dict[str, Any]
+    present_fields: List[str]
+    missing_fields: List[str]
+
+
+def _allowed_roots() -> List[Path]:
+    return [FIXTURES_DIR.resolve(), store.uploads_dir().resolve()]
+
+
+def log_reader(inp: LogReaderInput) -> LogReaderOutput:
+    if not inp.fixture_id and not inp.path:
+        raise ValueError("provide fixture_id or path")
+    if inp.fixture_id:
+        if not re.fullmatch(r"[A-Za-z0-9_\-]+", inp.fixture_id):
+            raise PermissionError(f"invalid fixture id {inp.fixture_id!r}")
+        target = (FIXTURES_DIR / f"{inp.fixture_id}.json").resolve()
+    else:
+        target = Path(inp.path).resolve()
+    if not any(str(target).startswith(str(root) + "/") or target.parent == root
+               for root in _allowed_roots()):
+        raise PermissionError(
+            f"path {target} is outside the approved artifact allowlist "
+            f"({[str(r) for r in _allowed_roots()]})")
+    if not target.exists():
+        raise FileNotFoundError(f"artifact not found: {target}")
+    log = json.loads(target.read_text())
+    present, missing = [], []
+    for fieldpath in REQUIRED_FIELDS:
+        (present if _dotted_get(log, fieldpath) is not None else missing).append(fieldpath)
+    return LogReaderOutput(source_path=str(target), log=log,
+                           present_fields=present, missing_fields=missing)
+
+
+# ------------------------------------------------------ SafetyStandardRAGTool
+
+class RAGSearchInput(BaseModel):
+    query: str = Field(min_length=3)
+    k: int = Field(4, ge=1, le=10)
+
+
+class RAGSearchOutput(BaseModel):
+    store_backend: str
+    hits: List[Dict[str, Any]]
+
+
+def rag_search(inp: RAGSearchInput) -> RAGSearchOutput:
+    index = get_index()
+    hits = index.search(inp.query, k=inp.k)
+    return RAGSearchOutput(store_backend=index.backend_name,
+                           hits=[h.model_dump() for h in hits])
+
+
+# ------------------------------------------------------- MetricCalculatorTool
+
+class MetricCalcInput(BaseModel):
+    operation: str = Field(description="stopping_distance | ttc | scr_impact | "
+                                       "behavioral_impact")
+    params: Dict[str, Any] = Field(default_factory=dict)
+
+
+class MetricCalcOutput(BaseModel):
+    operation: str
+    result: Dict[str, Any]
+
+
+def metric_calculator(inp: MetricCalcInput) -> MetricCalcOutput:
+    ops = {
+        "stopping_distance": lambda p: metrics.stopping_distance(**p),
+        "ttc": lambda p: metrics.time_to_collision(**p),
+        "scr_impact": lambda p: metrics.scr_impact(p.get("evaluation_context")),
+        "behavioral_impact": lambda p: metrics.behavioral_impact(
+            p.get("observed"), p.get("counterfactual")),
+    }
+    if inp.operation not in ops:
+        raise ValueError(f"unknown operation {inp.operation!r}; "
+                         f"expected one of {sorted(ops)}")
+    result = ops[inp.operation](inp.params)
+    return MetricCalcOutput(operation=inp.operation, result=result.model_dump())
+
+
+# ------------------------------------------------ HistoricalFailureSearchTool
+
+class HistoricalSearchInput(BaseModel):
+    query_text: str = Field(min_length=3)
+    k: int = Field(3, ge=1, le=10)
+    exclude_evaluation_id: Optional[str] = None
+
+
+class HistoricalSearchOutput(BaseModel):
+    matches: List[Dict[str, Any]]
+    corpus_size: int
+
+
+def historical_search(inp: HistoricalSearchInput) -> HistoricalSearchOutput:
+    """Similarity over previously analyzed failures (persisted scorecards)."""
+    embedder = HashedTfEmbedder()
+    docs, meta = [], []
+    for entry in store.list_analyses():
+        eid = entry.get("evaluation_id")
+        if not eid or eid == inp.exclude_evaluation_id:
+            continue
+        full = store.load_analysis(eid) or {}
+        sc = full.get("scorecard", {})
+        text = " ".join([
+            str(sc.get("failure_type", "")),
+            str(sc.get("behavioral_consequence", "")),
+            json.dumps(sc.get("scenario", {})),
+            " ".join(h.get("hypothesis", "") for h in sc.get("root_cause_hypotheses", [])),
+        ])
+        docs.append(text)
+        meta.append(entry)
+    if not docs:
+        return HistoricalSearchOutput(matches=[], corpus_size=0)
+    mat = embedder.embed(docs)
+    q = embedder.embed([inp.query_text])[0]
+    sims = mat @ q
+    order = np.argsort(-sims)[:inp.k]
+    matches = [{**meta[i], "similarity": round(float(np.clip(sims[i], 0, 1)), 4)}
+               for i in order]
+    return HistoricalSearchOutput(matches=matches, corpus_size=len(docs))
+
+
+# -------------------------------------------------- DistributionAnalysisTool
+
+class DistributionInput(BaseModel):
+    distribution_shift: Optional[Dict[str, Any]] = Field(
+        None, description="slice-level shift data from the eval artifact")
+    run_id: Optional[str] = Field(
+        None, description="megaeval run id — when provided and resolvable, the "
+                          "analysis delegates to sensorflow.megaeval.analysis")
+
+
+class DistributionOutput(BaseModel):
+    source: str
+    findings: List[str]
+    shift: Optional[Dict[str, Any]] = None
+
+
+def distribution_analysis(inp: DistributionInput) -> DistributionOutput:
+    if inp.run_id:
+        # Delegate to the platform's megaeval statistics when a real run exists.
+        try:
+            from sensorflow.megaeval.analysis import distribution_shift
+            from sensorflow.megaeval.runs import get_run, get_store
+            run = get_run(get_store(), inp.run_id)
+            res = distribution_shift(get_store(), run)
+            return DistributionOutput(
+                source="sensorflow.megaeval.analysis.distribution_shift",
+                findings=[f"megaeval shift analysis for run {inp.run_id}"],
+                shift=res)
+        except Exception as exc:
+            return DistributionOutput(
+                source="megaeval-delegation-failed",
+                findings=[f"could not delegate to megaeval ({exc}); no "
+                          "distribution claim is made"], shift=None)
+    ds = inp.distribution_shift
+    if not ds:
+        return DistributionOutput(
+            source="none",
+            findings=["no distribution data in artifact -> distribution shift "
+                      "UNKNOWN"], shift=None)
+    findings = []
+    cand, base = ds.get("candidate_fn_rate", ds.get("candidate_fp_rate")), \
+        ds.get("baseline_fn_rate", ds.get("baseline_fp_rate"))
+    if cand is not None and base is not None and base > 0:
+        ratio = cand / base
+        findings.append(
+            f"slice '{ds.get('slice', 'unknown')}': error rate {base:.3f} -> "
+            f"{cand:.3f} ({ratio:.2f}x) per the evaluation artifact")
+        if ratio > 1.3:
+            findings.append("relative increase exceeds 1.3x: concentrated "
+                            "regression in this slice rather than uniform noise")
+    else:
+        findings.append("artifact shift block lacks comparable rates -> UNKNOWN")
+    return DistributionOutput(source="artifact-provided slice rates",
+                              findings=findings, shift=ds)
+
+
+# ------------------------------------------------- CreateEvaluationCaseTool
+
+class CreateCaseInput(BaseModel):
+    title: str = Field(min_length=5)
+    description: str = Field(min_length=10)
+    scenario_tags: List[str] = Field(default_factory=list)
+    source_evaluation_id: str
+
+
+class CreateCaseOutput(BaseModel):
+    case_id: str
+    path: str
+    created_at: str
+
+
+def create_evaluation_case(inp: CreateCaseInput) -> CreateCaseOutput:
+    """THE write tool. The registry refuses this call without an explicit
+    policy_authorization=True flag; every call is audited."""
+    case_id = f"case-{uuid.uuid4().hex[:10]}"
+    created = datetime.now(timezone.utc).isoformat()
+    payload = {"case_id": case_id, "created_at": created, **inp.model_dump()}
+    path = store.eval_cases_dir() / f"{case_id}.json"
+    path.write_text(json.dumps(payload, indent=2))
+    return CreateCaseOutput(case_id=case_id, path=str(path), created_at=created)
+
+
+# --------------------------------------------------------------- registration
+
+def build_registry(analysis_id: Optional[str] = None,
+                   persist_audit: bool = True) -> ToolRegistry:
+    reg = ToolRegistry(analysis_id=analysis_id, persist_audit=persist_audit)
+    reg.register("log_reader", log_reader, LogReaderInput, LogReaderOutput,
+                 "Read an approved local failure artifact (allowlisted to the "
+                 "fixtures dir and runs/retro/uploads); returns the parsed log "
+                 "plus present/missing required fields.",
+                 read_only=True, timeout_s=5.0)
+    reg.register("safety_standard_rag", rag_search, RAGSearchInput, RAGSearchOutput,
+                 "Retrieve safety-case requirements from the (synthetic, "
+                 "clearly-labeled) corpus with source/version/section/"
+                 "relevance-score metadata.",
+                 read_only=True, timeout_s=20.0)
+    reg.register("metric_calculator", metric_calculator, MetricCalcInput,
+                 MetricCalcOutput,
+                 "Deterministic safety metrics: stopping_distance (reaction/"
+                 "latency/friction/grade/decel parameterized), ttc (SSAM "
+                 "rectangle projection with validity flags), scr_impact "
+                 "(policy-defined criticality), behavioral_impact (observed vs "
+                 "corrected-perception planner response).",
+                 read_only=True, timeout_s=10.0)
+    reg.register("historical_failure_search", historical_search,
+                 HistoricalSearchInput, HistoricalSearchOutput,
+                 "Similarity search over previously analyzed failures "
+                 "(persisted retro scorecards).",
+                 read_only=True, timeout_s=10.0)
+    reg.register("distribution_analysis", distribution_analysis,
+                 DistributionInput, DistributionOutput,
+                 "Distribution-shift findings: delegates to megaeval stats for "
+                 "real run ids, else analyzes artifact-provided slice rates.",
+                 read_only=True, timeout_s=15.0)
+    reg.register("create_evaluation_case", create_evaluation_case,
+                 CreateCaseInput, CreateCaseOutput,
+                 "WRITE TOOL: persist a new evaluation case candidate derived "
+                 "from this retrospective. Requires explicit policy "
+                 "authorization on every call; fully audited.",
+                 read_only=False, timeout_s=5.0)
+    return reg

sensorflow/retro/tools/mcp_server.py

@@ -0,0 +1,70 @@
+"""Bonus: expose the audited tool registry as a real MCP server.
+
+The `mcp` python package installed cleanly in this environment, so the
+registry can be served over stdio to any MCP client:
+
+    .venv/bin/python -m sensorflow.retro.tools.mcp_server
+
+Design notes:
+- Every MCP tool call still flows through ToolRegistry.call(), so the audit
+  trail, schema validation, timeouts, and write-authorization gate apply
+  identically to MCP clients and in-process callers.
+- The write tool (create_evaluation_case) is exposed but the registry will
+  deny it unless the client passes policy_authorization=true in arguments —
+  the MCP layer cannot bypass the boundary.
+- If `mcp` is not installed this module raises a clear ImportError; the
+  registry itself remains the MCP-style boundary (documented in registry.py).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from sensorflow.retro.tools.builtin import build_registry
+
+
+def _import_server_class():
+    """Support both the modern (MCPServer) and older (FastMCP) APIs."""
+    try:
+        from mcp.server.mcpserver import MCPServer
+        return MCPServer
+    except ImportError:
+        pass
+    try:
+        from mcp.server.fastmcp import FastMCP
+        return FastMCP
+    except ImportError as exc:  # honest failure; registry remains the boundary
+        raise ImportError(
+            "the 'mcp' package is not installed (or has an unknown server "
+            "API); the ToolRegistry remains the MCP-style boundary "
+            "(pip install mcp to enable this server)") from exc
+
+
+def build_mcp_server():
+    """Construct (but do not run) the MCP server wrapping the registry."""
+    server_cls = _import_server_class()
+    registry = build_registry(analysis_id="mcp-session")
+    server = server_cls(name="sensorflow-retro")
+
+    def make_handler(tool_name: str):
+        def handler(arguments: Dict[str, Any] | None = None) -> Dict[str, Any]:
+            args = dict(arguments or {})
+            authorized = bool(args.pop("policy_authorization", False))
+            res = registry.call(tool_name, args, policy_authorization=authorized)
+            return res.model_dump()
+        return handler
+
+    for spec in registry.specs():
+        server.add_tool(
+            make_handler(spec.name),
+            name=spec.name,
+            description=(f"{spec.description} "
+                         f"[read_only={spec.read_only}, timeout={spec.timeout_s}s; "
+                         f"args: single 'arguments' object matching the input "
+                         f"schema; write tools need policy_authorization=true]"))
+    return server, registry
+
+
+if __name__ == "__main__":
+    srv, _ = build_mcp_server()
+    srv.run()  # stdio transport

sensorflow/retro/tools/registry.py

@@ -0,0 +1,184 @@
+"""Tool registry: the MCP-style boundary between the agent and the world.
+
+Every tool declares an input schema, an output schema, permissions
+(read_only, default True), a timeout, and error behavior. Every call —
+success or failure — is appended to an audit trail with the arguments, a
+SHA-256 hash of the result, and a UTC timestamp. Write tools additionally
+require an explicit policy-authorization flag per call.
+
+If the `mcp` package is installed, tools/mcp_server.py exposes this same
+registry as a real MCP server; otherwise this registry itself is the
+MCP-style boundary.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import hashlib
+import json
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, List, Optional, Type
+
+from pydantic import BaseModel, Field, ValidationError
+
+from sensorflow.retro import store
+
+
+class ToolPermissionError(PermissionError):
+    pass
+
+
+class ToolSpec(BaseModel):
+    name: str
+    description: str
+    input_schema: Dict[str, Any]
+    output_schema: Dict[str, Any]
+    read_only: bool = True
+    timeout_s: float = 10.0
+    error_behavior: str = "raise"  # raise | return_error
+
+
+class AuditRecord(BaseModel):
+    call_id: str
+    analysis_id: str
+    tool: str
+    timestamp: str
+    args: Dict[str, Any]
+    status: str                    # ok | error | timeout | denied
+    result_hash: Optional[str]     # sha256 of canonical result JSON
+    elapsed_ms: float
+    error: Optional[str] = None
+    authorized_write: bool = False
+
+
+class _RegisteredTool(BaseModel):
+    spec: ToolSpec
+    fn: Callable[..., BaseModel]
+    input_model: Type[BaseModel]
+    output_model: Type[BaseModel]
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+def _hash_result(result: Any) -> str:
+    blob = json.dumps(result, sort_keys=True, default=str)
+    return hashlib.sha256(blob.encode()).hexdigest()
+
+
+class ToolCallResult(BaseModel):
+    ok: bool
+    tool: str
+    call_id: str
+    result: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    elapsed_ms: float = 0.0
+
+
+class ToolRegistry:
+    """Audited, permissioned, schema-validated tool dispatch."""
+
+    def __init__(self, analysis_id: Optional[str] = None,
+                 persist_audit: bool = True):
+        self._tools: Dict[str, _RegisteredTool] = {}
+        self.analysis_id = analysis_id or f"adhoc-{uuid.uuid4().hex[:8]}"
+        self.persist_audit = persist_audit
+        self.audit_log: List[AuditRecord] = []
+
+    # ------------------------------------------------------------ registration
+
+    def register(self, name: str, fn: Callable[..., BaseModel],
+                 input_model: Type[BaseModel], output_model: Type[BaseModel],
+                 description: str, read_only: bool = True,
+                 timeout_s: float = 10.0, error_behavior: str = "raise") -> None:
+        if name in self._tools:
+            raise ValueError(f"tool {name!r} already registered")
+        if error_behavior not in ("raise", "return_error"):
+            raise ValueError("error_behavior must be 'raise' or 'return_error'")
+        spec = ToolSpec(name=name, description=description,
+                        input_schema=input_model.model_json_schema(),
+                        output_schema=output_model.model_json_schema(),
+                        read_only=read_only, timeout_s=timeout_s,
+                        error_behavior=error_behavior)
+        self._tools[name] = _RegisteredTool(spec=spec, fn=fn,
+                                            input_model=input_model,
+                                            output_model=output_model)
+
+    def specs(self) -> List[ToolSpec]:
+        return [t.spec for t in self._tools.values()]
+
+    def get_spec(self, name: str) -> ToolSpec:
+        return self._tools[name].spec
+
+    # ------------------------------------------------------------------ audit
+
+    def _audit(self, record: AuditRecord) -> None:
+        self.audit_log.append(record)
+        if self.persist_audit:
+            store.append_audit(self.analysis_id, record.model_dump())
+
+    # ------------------------------------------------------------------- call
+
+    def call(self, name: str, args: Dict[str, Any],
+             policy_authorization: bool = False) -> ToolCallResult:
+        call_id = uuid.uuid4().hex[:12]
+        t0 = time.perf_counter()
+        ts = datetime.now(timezone.utc).isoformat()
+
+        def audit(status: str, result_hash: Optional[str] = None,
+                  error: Optional[str] = None) -> None:
+            self._audit(AuditRecord(
+                call_id=call_id, analysis_id=self.analysis_id, tool=name,
+                timestamp=ts, args=args, status=status, result_hash=result_hash,
+                elapsed_ms=round((time.perf_counter() - t0) * 1000, 2),
+                error=error, authorized_write=policy_authorization))
+
+        if name not in self._tools:
+            audit("error", error="unknown tool")
+            raise KeyError(f"unknown tool {name!r}")
+        tool = self._tools[name]
+
+        if not tool.spec.read_only and not policy_authorization:
+            audit("denied", error="write tool requires policy_authorization=True")
+            raise ToolPermissionError(
+                f"tool {name!r} is a WRITE tool and requires an explicit "
+                "policy_authorization=True flag on the call")
+
+        try:
+            validated = tool.input_model(**args)
+        except ValidationError as exc:
+            audit("error", error=f"input validation failed: {exc}")
+            if tool.spec.error_behavior == "return_error":
+                return ToolCallResult(ok=False, tool=name, call_id=call_id,
+                                      error=f"input validation failed: {exc}",
+                                      elapsed_ms=(time.perf_counter() - t0) * 1000)
+            raise
+
+        try:
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(tool.fn, validated)
+                output = future.result(timeout=tool.spec.timeout_s)
+        except concurrent.futures.TimeoutError:
+            audit("timeout", error=f"timed out after {tool.spec.timeout_s}s")
+            if tool.spec.error_behavior == "return_error":
+                return ToolCallResult(ok=False, tool=name, call_id=call_id,
+                                      error=f"timeout after {tool.spec.timeout_s}s",
+                                      elapsed_ms=(time.perf_counter() - t0) * 1000)
+            raise TimeoutError(f"tool {name!r} timed out after {tool.spec.timeout_s}s")
+        except Exception as exc:
+            audit("error", error=f"{exc.__class__.__name__}: {exc}")
+            if tool.spec.error_behavior == "return_error":
+                return ToolCallResult(ok=False, tool=name, call_id=call_id,
+                                      error=f"{exc.__class__.__name__}: {exc}",
+                                      elapsed_ms=(time.perf_counter() - t0) * 1000)
+            raise
+
+        if not isinstance(output, tool.output_model):
+            output = tool.output_model(**(output if isinstance(output, dict)
+                                          else output.model_dump()))
+        result_dict = output.model_dump()
+        audit("ok", result_hash=_hash_result(result_dict))
+        return ToolCallResult(ok=True, tool=name, call_id=call_id,
+                              result=result_dict,
+                              elapsed_ms=round((time.perf_counter() - t0) * 1000, 2))

src/App.tsx

@@ -30,6 +30,7 @@ import {
   Map as MapIcon,
   AppWindow,
   Mountain,
+  Undo2,
   CircuitBoard,
 } from 'lucide-react';
 import { LabelEvalContext, type PageId, ALL_PAGE_IDS } from './context/LabelEvalContext';
@@ -54,6 +55,7 @@ import RootCauseLabPage from './pages/rca/RootCauseLabPage';
 import RareMinePage from './pages/raremine/RareMinePage';
 import VitisPage from './pages/vitis/VitisPage';
 import HillClimbSection from './pages/hillclimb/HillClimbSection';
+import RetroAnalyzerPage from './pages/retro/RetroAnalyzerPage';
 import PageIntro from './components/help/PageIntro';
 import HelpMenu from './components/help/HelpMenu';
 
@@ -83,6 +85,7 @@ const PLATFORM_NAV: NavItem[] = [
   { id: 'audit', label: 'Audit', icon: <ScrollText size={18} /> },
   { id: 'pipeline', label: 'Pipeline Architecture', icon: <Workflow size={18} /> },
   { id: 'hillclimb', label: 'Hill Climbing EM', icon: <Mountain size={18} /> },
+  { id: 'retro', label: 'Retrospective Analyzer', icon: <Undo2 size={18} /> },
   { id: 'vitis', label: 'Hardware Acceleration', icon: <CircuitBoard size={18} /> },
 ];
 
@@ -109,6 +112,7 @@ const PAGE_TITLES: Record<PageId, string> = {
   audit: 'Audit & Process Units',
   pipeline: 'Pipeline Architecture',
   hillclimb: 'Hill Climbing EM',
+  retro: 'Retrospective Safety Analyzer',
   vitis: 'Hardware Acceleration (Vitis Vision)',
   ssam: 'SSAM Safety Dashboard',
   legacy: 'Legacy Studio',
@@ -317,6 +321,7 @@ export default function App() {
               {page === 'audit' ? <AuditPage /> : null}
               {page === 'pipeline' ? <PipelineArchitecturePage /> : null}
               {page === 'hillclimb' ? <HillClimbSection initialView={entityId} /> : null}
+              {page === 'retro' ? <RetroAnalyzerPage /> : null}
               {page === 'vitis' ? <VitisPage /> : null}
             </Box>
           )}

src/components/help/HelpMenu.tsx

@@ -185,6 +185,7 @@ const PAGE_ORDER: PageId[] = [
   'audit',
   'pipeline',
   'hillclimb',
+  'retro',
   'vitis',
   'ssam',
   'legacy',
@@ -208,6 +209,7 @@ const PAGE_NAMES: Record<PageId, string> = {
   audit: 'Audit',
   pipeline: 'Pipeline Architecture',
   hillclimb: 'Hill Climbing EM',
+  retro: 'Retrospective Analyzer',
   vitis: 'Hardware Acceleration',
   ssam: 'SSAM Safety',
   legacy: 'Legacy Studio',