pen-stack 6.2.4__tar.gz → 6.3.0__tar.gz

{pen_stack-6.2.4 → pen_stack-6.3.0}/CHANGELOG.md

@@ -3,6 +3,39 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [6.3.0] - 2026-06-12 - v6.3.0: The Hybrid Co-Scientist (grounded engine + general intelligence)
+
+**The chat gains general + biological intelligence WITHOUT loosening the no-fabrication core.** A 4-lane router
+keeps grounded engine output and general trained-knowledge in separate, explicitly-labelled lanes, so a
+general-knowledge fact can never be mistaken for a PEN-STACK result. Numbers now come with their meaning,
+reference range, and how they were computed; the conversation has memory. MINOR feature release on the stable
+6.x API. Workstream WS-HYBRID, SHA-locked.
+
+### Added
+- **WS-HYBRID** — `pen_stack/web/router.py` (deterministic 4-lane classifier: `design` / `explain` / `meta` /
+  `general`, biased to the engine whenever a design signal is present) + `pen_stack/web/guide.py`
+  (`metric_guide()` interpretation cards + `pen_stack_facts()` assembled from LIVE engine data) + a rewritten
+  `pen_stack/web/llm.py::grounded_reply` that dispatches per lane and returns `{mode, provenance, grounded, …}`.
+- **`configs/metric_guide.yaml`** — grounded interpretation for every engine number (genotoxicity, CD8 epitope,
+  innate, pre-existing NAb, anti-PEG, confidence, relative expression + the safety decisions): what it means, the
+  scale + direction, reference bands, how it is computed, and its validation status. The chat now EXPLAINS a value
+  (scale / what's good-or-bad / reference range / method), not just prints it.
+- **Lanes & provenance:** `design`/`explain`/`meta` are engine-grounded (the grounding guard runs over the tool
+  results, the metric guide, or the live facts); `general` answers from the LLM's trained knowledge, is **labelled
+  "General knowledge — not PEN-STACK-verified"**, attributes no number to PEN-STACK, and **points to the engine**
+  wherever PEN-STACK could compute a concrete answer (`pen_stack_angles`).
+- **Conversation memory** — the last turns are passed to every lane so follow-ups ("what does that 0.55 mean?")
+  resolve against the prior dossier; the frontend keeps history in-session until refresh and renders a per-message
+  provenance badge (🔬 grounded vs 🧠 general) + the "PEN-STACK can compute this →" pointers.
+- Tests: `tests/unit/test_ws_chat.py` — the 4-lane router, the general lane labelled+unattributed+pointered, the
+  meta lane grounded in live facts, the explain lane interpreting prior values without a fresh design, the metric
+  guide complete. prereg `ws_hybrid` + SHA lock; deposit `phase_6.3/`.
+
+### Notes
+- **The core is untouched.** The guard still runs on every PEN-STACK-attributed number; we ADDED a general lane,
+  we did not loosen the grounded lane. The honest cost is that general-lane answers carry the LLM's fallibility —
+  made safe by the explicit label and by redirecting to the engine for anything computable.
+
 ## [6.2.4] - 2026-06-12 - v6.2.4: faster grounded narration (LLM backends) (patch)
 
 **Performance + a real fix, from benchmarking the narration backends on the deployment GPU (RTX A4000).** The

{pen_stack-6.2.4 → pen_stack-6.3.0}/CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 6.2.4
+version: 6.3.0
 date-released: 2026-06-11
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.2.4 → pen_stack-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.2.4
+Version: 6.3.0
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -90,9 +90,9 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.2.4-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
-[![Tests](https://img.shields.io/badge/tests-371%20passing-success.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
@@ -148,6 +148,27 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.3 — The Hybrid Co-Scientist (grounded engine + general intelligence)
+
+The chat now does three things at once without ever blurring them: it **runs the engine** for genome-writing
+requests, **explains what the numbers mean**, and answers **general biology** questions — each in its own lane with
+its own provenance, so a general-knowledge fact can never be mistaken for a PEN-STACK result.
+
+| Lane | Trigger | Source | Provenance |
+|---|---|---|---|
+| 🔬 **Design** | "insert FIX at AAVS1 with AAV in hepatocytes" | the engine (verify/safety/immune/twin) — guard ON | "PEN-STACK · grounded" |
+| 📖 **Explain** | "what does that 0.55 mean?" | the **metric guide** (scale, direction, reference range, how computed) + the prior dossier | "PEN-STACK · metric guide" |
+| ⚙️ **Meta** | "how many enzymes? how is immunogenicity computed? how accurate?" | the **live capability facts** (33,370 systems / 8 families / 5 immune axes …) — guard ON | "PEN-STACK · about the engine" |
+| 🧠 **General** | "hi", "what is AAV", "how does AAV work" | the LLM's trained knowledge | **"General knowledge — not PEN-STACK-verified"**, + a pointer to what PEN-STACK can compute |
+
+- **The one rule that keeps the core intact:** a number presented as a PEN-STACK result is engine-grounded (the
+  guard runs on the first three lanes); a number from general knowledge is **visibly labelled** and, wherever
+  PEN-STACK could compute it, **redirected to the engine**. We added a lane; we did not loosen the grounded one.
+- **Numbers now come with meaning** — every value is explained with its scale, what's good/bad, its reference
+  range, and how it was computed (`configs/metric_guide.yaml`).
+- **Conversation memory** — follow-ups resolve against the prior answer (in-session until you refresh).
+- Workstream **WS-HYBRID** (`pen_stack/web/{router,guide}.py` + the rewritten `llm.py`); `prereg/ws_hybrid.yaml`.
+
 ## What is new in v6.2 — The Web Platform (the human surface)
 
 Post-1.0, the adoption surface for **bench scientists**: a complete, friendly **web application** — a grounded
@@ -800,7 +821,7 @@ pen-stack/
 │   │                                   v5.12 closed_loop (loop-integrity hard-gate: gated end-to-end run · Level-3 human-in-control · drift detection · versioned/reversible continual learning)
 │   ├── data/                         ingestion (genome, chromatin, integration, TRIP, safety annotations)
 │   ├── api/                          v6.1 AI integration surface: manifest (capability_manifest + scope_manifest = machine-readable known-unknowns + oracle scope cards)
-│   ├── web/                          v6.2 Web Platform backend: tools (deterministic engine dossier) / llm (grounded co-scientist: Ollama→Nemotron→deterministic + grounding-guard hard gate) / server (FastAPI gateway mounting the v6.1 surface + /chat + SSE + static frontend)
+│   ├── web/                          v6.2 Web Platform backend: tools (deterministic engine dossier) / llm (grounded co-scientist + grounding-guard) / server (FastAPI gateway + /chat + SSE) + v6.3 hybrid: router (4-lane design/explain/meta/general classifier) / guide (metric-interpretation cards + live capability facts)
 │   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask; v3.3 verify; v6.1 /capabilities /scope /safety /immune /generate /predict /suggest /session + openapi.json 3.1; v5.13 /challenge/{tasks,leaderboard})
 │   ├── ui/app.py                     Streamlit web app (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
@@ -821,7 +842,7 @@ pen-stack/
 │                                       genotox,epitope,innate,seroprev,peg,calib,profile,screen,policy,redteam,
 │                                       gen,pareto,orch,vcell,mech,outcome,twincal,acq,aldesign,alvalidate,
 │                                       proto,ingest,simlab,loop,continual,drift,challenge,cosci2,
-│                                       manifest,openapi,mcp,chat,frontend} + SHA256 locks)
+│                                       manifest,openapi,mcp,chat,frontend,hybrid} + SHA256 locks)
 ├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile,
 │                                       v3.2 bridge_offtarget_energetics.json)
 ├── data/llm_bench_cache/             28 cached ungrounded-LLM transcripts (T7, offline/CI replay)

{pen_stack-6.2.4 → pen_stack-6.3.0}/README.md

@@ -15,9 +15,9 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.2.4-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
-[![Tests](https://img.shields.io/badge/tests-371%20passing-success.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
 [![Validation: pre-registered](https://img.shields.io/badge/validation-pre--registered-critical.svg)](prereg/)
@@ -73,6 +73,27 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.3 — The Hybrid Co-Scientist (grounded engine + general intelligence)
+
+The chat now does three things at once without ever blurring them: it **runs the engine** for genome-writing
+requests, **explains what the numbers mean**, and answers **general biology** questions — each in its own lane with
+its own provenance, so a general-knowledge fact can never be mistaken for a PEN-STACK result.
+
+| Lane | Trigger | Source | Provenance |
+|---|---|---|---|
+| 🔬 **Design** | "insert FIX at AAVS1 with AAV in hepatocytes" | the engine (verify/safety/immune/twin) — guard ON | "PEN-STACK · grounded" |
+| 📖 **Explain** | "what does that 0.55 mean?" | the **metric guide** (scale, direction, reference range, how computed) + the prior dossier | "PEN-STACK · metric guide" |
+| ⚙️ **Meta** | "how many enzymes? how is immunogenicity computed? how accurate?" | the **live capability facts** (33,370 systems / 8 families / 5 immune axes …) — guard ON | "PEN-STACK · about the engine" |
+| 🧠 **General** | "hi", "what is AAV", "how does AAV work" | the LLM's trained knowledge | **"General knowledge — not PEN-STACK-verified"**, + a pointer to what PEN-STACK can compute |
+
+- **The one rule that keeps the core intact:** a number presented as a PEN-STACK result is engine-grounded (the
+  guard runs on the first three lanes); a number from general knowledge is **visibly labelled** and, wherever
+  PEN-STACK could compute it, **redirected to the engine**. We added a lane; we did not loosen the grounded one.
+- **Numbers now come with meaning** — every value is explained with its scale, what's good/bad, its reference
+  range, and how it was computed (`configs/metric_guide.yaml`).
+- **Conversation memory** — follow-ups resolve against the prior answer (in-session until you refresh).
+- Workstream **WS-HYBRID** (`pen_stack/web/{router,guide}.py` + the rewritten `llm.py`); `prereg/ws_hybrid.yaml`.
+
 ## What is new in v6.2 — The Web Platform (the human surface)
 
 Post-1.0, the adoption surface for **bench scientists**: a complete, friendly **web application** — a grounded
@@ -725,7 +746,7 @@ pen-stack/
 │   │                                   v5.12 closed_loop (loop-integrity hard-gate: gated end-to-end run · Level-3 human-in-control · drift detection · versioned/reversible continual learning)
 │   ├── data/                         ingestion (genome, chromatin, integration, TRIP, safety annotations)
 │   ├── api/                          v6.1 AI integration surface: manifest (capability_manifest + scope_manifest = machine-readable known-unknowns + oracle scope cards)
-│   ├── web/                          v6.2 Web Platform backend: tools (deterministic engine dossier) / llm (grounded co-scientist: Ollama→Nemotron→deterministic + grounding-guard hard gate) / server (FastAPI gateway mounting the v6.1 surface + /chat + SSE + static frontend)
+│   ├── web/                          v6.2 Web Platform backend: tools (deterministic engine dossier) / llm (grounded co-scientist + grounding-guard) / server (FastAPI gateway + /chat + SSE) + v6.3 hybrid: router (4-lane design/explain/meta/general classifier) / guide (metric-interpretation cards + live capability facts)
 │   ├── server/api.py                 FastAPI REST (atlas, crosslink, writable, plan, bridge, ask; v3.3 verify; v6.1 /capabilities /scope /safety /immune /generate /predict /suggest /session + openapi.json 3.1; v5.13 /challenge/{tasks,leaderboard})
 │   ├── ui/app.py                     Streamlit web app (16 pages; v3.2 PEN-Agent shows confidence + epistemic status)
 │   └── cli.py                        unified CLI
@@ -746,7 +767,7 @@ pen-stack/
 │                                       genotox,epitope,innate,seroprev,peg,calib,profile,screen,policy,redteam,
 │                                       gen,pareto,orch,vcell,mech,outcome,twincal,acq,aldesign,alvalidate,
 │                                       proto,ingest,simlab,loop,continual,drift,challenge,cosci2,
-│                                       manifest,openapi,mcp,chat,frontend} + SHA256 locks)
+│                                       manifest,openapi,mcp,chat,frontend,hybrid} + SHA256 locks)
 ├── data/curated/                     small committed tables (universe, gene coords, measured bridge profile,
 │                                       v3.2 bridge_offtarget_energetics.json)
 ├── data/llm_bench_cache/             28 cached ungrounded-LLM transcripts (T7, offline/CI replay)

pen_stack-6.3.0/configs/metric_guide.yaml

@@ -0,0 +1,102 @@
+# PEN-STACK v6.3 — Metric Interpretation Guide (the "what does this number mean" layer).
+# For every quantity the engine returns, a GROUNDED interpretation card: what it is, the scale + direction,
+# reference bands, how it is computed (the oracle + data source), its validation status, and the caveat. These
+# are curated facts ABOUT the metrics (not predictions), so the chat can explain a number without fabricating —
+# the value is still the engine's; this only adds the textbook reading of it. Bands are interpretive aids, not
+# thresholds for a decision.
+
+metrics:
+  genotoxicity:
+    label: "Genotoxicity safety score"
+    scale: "0–1 (dimensionless)"
+    direction: "higher = safer (1.0 = no insertional-mutagenesis mechanism)"
+    bands: { favorable: ">=0.7", moderate: "0.4–0.7", concern: "<0.4" }
+    means: "relative insertional-oncogenesis safety of the delivery/integration strategy. 1.0 = episomal/
+      non-integrating (no integration → no insertional mutagenesis); lower = an integrating vector whose insertion
+      sites fall nearer known proto-oncogenes."
+    computed: "for integrating vectors, from VISDB integration-site maps × COSMIC Cancer-Gene-Census oncogene
+      proximity (per-vector enrichment of integrations within 50 kb of an oncogene vs background)."
+    validation: "mechanistic proxy — NOT outcome-validated (the actual clonal-transformation rate is measured, not predicted)."
+    reference: "e.g. lentiviral ~0.48 (2.08× oncogene-proximity enrichment) vs episomal AAV 1.0."
+
+  cd8_epitope:
+    label: "CD8 T-cell capsid epitope-load score"
+    scale: "0–1 (dimensionless)"
+    direction: "higher = fewer strong CD8 epitopes presented (1.0 = none / non-viral)"
+    bands: { favorable: ">=0.6", moderate: "0.3–0.6", concern: "<0.3" }
+    means: "sequence-derived load of strong MHC-I (CD8) epitopes on the viral capsid/envelope across a common
+      HLA-I panel. Lower = more of the capsid is presentable to cytotoxic T cells."
+    computed: "MHCflurry binding prediction over the capsid/envelope sequence × a 12-allele HLA-I panel →
+      fraction of strong binders; score = 1 − strong-epitope-fraction."
+    validation: "mechanistic proxy — NOT outcome-validated; covers CD8/MHC-I only (CD4/MHC-II help is a known-unknown)."
+    reference: "e.g. AAV2 capsid ~0.28 (≈72% of windows are strong binders across the panel)."
+
+  innate:
+    label: "Innate-sensing safety score"
+    scale: "0–1 (dimensionless)"
+    direction: "higher = less innate-immune sensing of the cargo"
+    bands: { favorable: ">=0.7", moderate: "0.4–0.7", concern: "<0.4" }
+    means: "how strongly the cargo nucleic acid triggers innate pattern-recognition (DNA: CpG/TLR9; mRNA:
+      dsRNA/RIG-I). Higher = fewer immunostimulatory motifs."
+    computed: "CpG observed/expected for DNA cargo (TLR9), and U-content + ViennaRNA dsRNA structure for mRNA
+      (RIG-I/MDA5); RNP minimal. mRNA is partial (nucleoside modification is not sequence-derivable)."
+    validation: "mechanistic proxy (partial for mRNA) — the realized in-vivo magnitude is a known-unknown."
+    reference: "often 'n/a' when no cargo sequence is supplied (the engine abstains rather than guess)."
+
+  preexisting_nab:
+    label: "Pre-existing neutralizing-antibody eligibility score"
+    scale: "0–1 (dimensionless)"
+    direction: "higher = fewer patients excluded by pre-existing antibodies"
+    bands: { favorable: ">=0.7", moderate: "0.4–0.7", concern: "<0.4" }
+    means: "the fraction of the population NOT excluded by pre-existing neutralizing antibodies to the vector.
+      It predicts ELIGIBILITY (who can be dosed), NOT the response magnitude in an eligible patient."
+    computed: "1 − midpoint of published anti-vector NAb seroprevalence ranges (serosurveys, per serotype)."
+    validation: "population proxy — predicts eligibility, not response magnitude. The individual patient's titer is a known-unknown (a clinical test)."
+    reference: "e.g. AAV ~0.55 (≈30–60% seroprevalence), Ad5 ~0.35 (40–90%), VSV ~0.975 (0–5%)."
+
+  anti_peg:
+    label: "Anti-PEG (re-dosing) eligibility score"
+    scale: "0–1 (dimensionless)"
+    direction: "higher = lower pre-existing anti-PEG barrier to re-dosing"
+    bands: { favorable: ">=0.7", moderate: "0.4–0.7", concern: "<0.4" }
+    means: "pre-existing anti-PEG immunity that gates RE-DOSING of a PEGylated delivery (e.g. LNP). Activates
+      only for PEGylated vehicles; abstains for non-PEG vehicles."
+    computed: "1 − midpoint of published anti-PEG seroprevalence ranges (population serosurveys)."
+    validation: "population proxy — gates re-dosing eligibility, not calibrated to a re-dosing-failure rate. Patient-specific and post-dose-1 induced anti-PEG are known-unknowns."
+    reference: "e.g. PEGylated LNP ~0.515 (≈25–72% population anti-PEG prevalence); 'n/a' for non-PEG vehicles."
+
+  confidence:
+    label: "Calibrated confidence (soft components)"
+    scale: "0–1, with an interval [low–high]"
+    direction: "higher = more confident on the SOFT (scored) components — a SEPARATE axis from legality"
+    bands: { high: ">=0.7", moderate: "0.4–0.7", low: "<0.4" }
+    means: "calibrated confidence on the design's soft/scored components (durability, writer activity, etc.),
+      reported with an uncertainty interval. It is NOT legality (a legal design can still be low-confidence), and
+      it is NOT a success probability. 'None' = the engine ABSTAINED (no calibrated score for this design)."
+    computed: "L4 trust layer over the planner scores, calibrated with held-out conformal intervals."
+    validation: "calibrated where data supports it; abstains (None) rather than emit an uncalibrated number."
+    reference: "interval widens / status flips to 'extrapolating' for out-of-distribution contexts."
+
+  relative_expression:
+    label: "Relative expression estimate (digital twin)"
+    scale: "0–1 (relative, dimensionless), with an interval"
+    direction: "higher = stronger relative cassette expression — NOT an absolute titer"
+    bands: { strong: ">=0.6", moderate: "0.3–0.6", weak: "<0.3" }
+    means: "a RELATIVE, dimensionless expression estimate (promoter × copy number × accessibility). It is NOT a
+      phenotype, NOT a functional titer, and NOT a percent-of-normal — those are measured clinical endpoints."
+    computed: "closed-form mechanistic twin (steady-state; no silencing modeled; linear copy scaling), fused with
+      the immune context; interval is a heuristic band that WIDENS ~1.6× under out-of-distribution context."
+    validation: "honest heuristic band — NOT a trained conformal interval (no public perturbation-outcome calibration set)."
+    reference: "absolute titer / % of normal is explicitly out of scope (known-unknown in_vivo_expression_magnitude)."
+
+# how to read the safety decision (categorical, not a number)
+safety_decision:
+  clear: "no dual-use hazard signal — the design proceeds to scoring."
+  flag: "a low/medium dual-use signal — surfaced for human review."
+  escalate: "an ambiguous dual-use (e.g. gain-of-function) case — routed to oversight (P3CO/DURC)."
+  refuse: "a high-severity controlled-hazard match — the design is REFUSED and not scored further (reframing cannot flip it)."
+
+# the global caveat that rides every quantitative answer
+disclaimer: "Decision-support, not a clinical directive. Every number is a tool-computed proxy with a stated
+  scope; proxies are not outcome-validated, and patient-specific magnitudes (titer, response, durability) are
+  explicit known-unknowns — measured, never predicted."

{pen_stack-6.2.4 → pen_stack-6.3.0}/pen_stack/__init__.py

@@ -1,2 +1,2 @@
 """PEN-STACK v3.0 - open infrastructure for genome writing."""
-__version__ = "6.2.4"
+__version__ = "6.3.0"

pen_stack-6.3.0/pen_stack/web/guide.py

@@ -0,0 +1,103 @@
+"""Metric interpretation + PEN-STACK capability facts (v6.3, the explain/meta lanes).
+
+Two grounded sources the hybrid co-scientist narrates over WITHOUT fabricating:
+  * `metric_guide()` — curated interpretation cards (configs/metric_guide.yaml): what each engine number means,
+    its scale/direction, reference bands, how it is computed, validation status. Used to EXPLAIN a value.
+  * `pen_stack_facts()` — capability facts assembled from LIVE engine data (writer atlas coverage, the delivery
+    palette, the immune axes, the known-unknowns) — so "how many enzymes / vectors / axes, how accurate" is
+    answered from the system itself, not invented.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def metric_guide() -> dict:
+    return yaml.safe_load(resource("configs/metric_guide.yaml").read_text(encoding="utf-8"))
+
+
+def guide_for(metric: str) -> dict | None:
+    """The interpretation card for a metric name (immune axis / verdict field)."""
+    return (metric_guide().get("metrics") or {}).get(metric)
+
+
+def enrich_axes(axes: dict) -> dict:
+    """Attach the interpretation card (meaning/scale/bands/computed/validation/reference) to each immune axis."""
+    out = {}
+    for name, a in (axes or {}).items():
+        g = guide_for(name)
+        out[name] = {**a, "guide": g} if g else a
+    return out
+
+
+@lru_cache(maxsize=1)
+def pen_stack_facts() -> dict:
+    """GROUNDED facts about what PEN-STACK covers + how it computes — assembled from live engine data, never
+    hand-typed counts. Answers the 'meta' lane ('how many enzymes/vectors/axes, how is X computed, how accurate')."""
+    facts: dict = {"disclaimer": (metric_guide() or {}).get("disclaimer")}
+
+    # writer atlas coverage (enzymes / families) — from the committed atlas
+    try:
+        import pandas as pd
+
+        from pen_stack import __file__ as _pkg
+        from pathlib import Path
+        atlas = pd.read_parquet(Path(_pkg).resolve().parents[0] / "atlas" / "atlas.parquet")
+        facts["writers"] = {
+            "systems": int(len(atlas)),
+            "families": sorted(atlas["family"].astype(str).unique().tolist()),
+            "n_families": int(atlas["family"].nunique()),
+            "measured": int((atlas["confidence"] == "measured").sum()) if "confidence" in atlas.columns else None,
+            "note": "writer = genome-writing enzyme system (integrases, recombinases, nucleases, transposases) on "
+                    "common measured axes (cargo capacity, programmability, DSB-freeness, human-cell activity, "
+                    "deliverability).",
+        }
+    except Exception:
+        facts["writers"] = {"note": "writer atlas requires the committed atlas.parquet"}
+
+    # delivery palette (vectors)
+    try:
+        from pen_stack.planner.delivery_vehicles import names as _vnames
+        from pen_stack.planner.delivery_vehicles import vehicle as _veh
+        vs = _vnames()
+        viral = [v for v in vs if (_veh(v) or {}).get("class", "").lower().startswith("vir")
+                 or any(k in v.lower() for k in ("aav", "lenti", "adeno", "hsv", "virus"))]
+        facts["delivery"] = {
+            "n_vehicles": len(vs), "vehicles": list(vs),
+            "viral_like": viral, "nonviral_like": [v for v in vs if v not in viral],
+            "note": "each vehicle carries documented cargo capacity, integration status, cargo-form compatibility "
+                    "(DNA/mRNA/RNP) and an ordinal immune/safety prior; the planner picks compatible vehicles.",
+        }
+    except Exception:
+        facts["delivery"] = {"note": "delivery palette in configs/delivery_vehicles.yaml"}
+
+    # immune-risk axes (how immunogenicity is computed) + their guides
+    axes = ["genotoxicity", "cd8_epitope", "innate", "preexisting_nab", "anti_peg"]
+    facts["immunogenicity"] = {
+        "n_axes": len(axes), "axes": axes,
+        "never_collapsed": "the per-axis profile is never fused into one score (collapsed_score is None) — the "
+                           "axes measure different mechanisms on different evidence.",
+        "how": {a: (guide_for(a) or {}).get("computed") for a in axes},
+        "validation": {a: (guide_for(a) or {}).get("validation") for a in axes},
+    }
+
+    # accuracy / honesty posture + the known-unknowns
+    try:
+        from pen_stack.agent.scope import load_registry
+        kus = [{"id": e["id"], "title": e["title"]} for e in load_registry()]
+    except Exception:
+        kus = []
+    facts["accuracy"] = {
+        "posture": "every number is a tool-computed proxy with a stated scope; proxies are labelled "
+                   "'mechanistic/population proxy — NOT outcome-validated'; the engine ABSTAINS or flags "
+                   "out-of-scope rather than guess; nothing is fabricated.",
+        "known_unknowns": kus,
+        "what_is_NOT_predicted": "functional titer / % of normal, in-vivo response magnitude, long-term clinical "
+                                 "durability, phenotype — these are measured clinical endpoints, never predicted.",
+    }
+    return facts