pen-stack 6.4.2__tar.gz → 6.5.0__tar.gz

{pen_stack-6.4.2 → pen_stack-6.5.0}/CHANGELOG.md

@@ -3,6 +3,44 @@
 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.5.0] - 2026-06-15 - Comprehensive expression model + honest proxy-validation pass
+
+**MINOR feature release.** Two threads, one principle (no fabrication):
+
+### Added — comprehensive, literature-cited expression model (WS-EXPRESS)
+- `configs/expression/promoters.yaml` — the twin's promoter palette expands **5 → 31 promoters** (constitutive +
+  tissue-specific: liver TBG/LP1/hAAT, neuron hSyn/CaMKIIα, muscle MHCK7/MCK/CK8, astrocyte GfaABC1D, SFFV/MND/
+  MSCV/RSV, …). Each entry carries `strength` + **context** + assay + **citation** + confidence — because promoter
+  strength has **no universal scalar** (it depends on cell type × vector × readout), so a single number is encoded
+  *with* its context, never as a universal truth.
+- `configs/expression/modifiers.yaml` — a modifier layer (WPRE, intron, polyA, Kozak, codon-optimization/CAI,
+  CpG-silencing) as **literature priors/ranges**, applied as a bounded uplift RANGE (never a point multiplier —
+  the chimeric intron is ~20× for one transgene, ~3× for another). `twin/mechanistic.py` consumes both.
+
+### Added — proxy → outcome validation harness (WS-CALIB run)
+- `scripts/calibrate_immune_axes.py` + `configs/calibration/preexisting_nab_independent.yaml` — runs the existing
+  `calibrate_axis` gate (N≥6 AND bootstrap Spearman CI excludes 0) against **independent** measured data.
+
+### Honest result (the deliverable)
+- **No immune or expression axis flips to ✅.** Pre-existing NAb tested vs an independent cohort
+  (Navarro-Oliveros 2024, Basque): ρ=0.12, CI includes 0 — geography-dependent. Relative-expression tested vs an
+  independent promoter study (Damdindorj 2014): ρ=0.12, CI includes 0 — promoter strength is context-dependent
+  (Damdindorj found CMV strongest; Qin found the opposite). Genotoxicity (3 vectors), CD8 (5 capsids), anti-PEG
+  (1), innate (0 fixed) are structurally below the N≥6 gate. The labels stay 🟡 **with empirical backing** —
+  flipping them would require measured-outcome data at a statistical power the public literature does not provide.
+
+### Tests
+- `tests/unit/test_ws_express.py` — palette is comprehensive + cited; context is encoded; modifier profile is a
+  bounded range; the proxy does NOT falsely claim cross-study validation (the no-fabrication gate holds).
+
+## [6.4.3] - 2026-06-12 - Chat vehicle-parse fix (AAVS1 no longer hijacks the vehicle)
+
+**PATCH.** `web/tools.py::parse_goal` matched the delivery vehicle by substring, so the safe-harbour nickname
+**AAVS1** (which contains "aav") wrongly selected the **AAV** vehicle even when the user said *lentivirus* or
+*LNP* — producing the wrong immune profile (e.g. genotoxicity 1.0 instead of lentivirus's 0.481). Fix: strip the
+safe-harbour nicknames (AAVS1/H11/HIPP11/ROSA26) from the vehicle-search text before matching, so the user's
+stated vehicle wins. Explicit "AAV" still selects AAV. New test locks all three cases.
+
 ## [6.4.2] - 2026-06-12 - Co-Scientist chat: real writer recommendations + self-explanatory values
 
 **PATCH — fixes a stale/confusing chat experience reported from the live app.** Three problems, three fixes:

{pen_stack-6.4.2 → pen_stack-6.5.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.4.2
+version: 6.5.0
 date-released: 2026-06-12
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.4.2 → pen_stack-6.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.4.2
+Version: 6.5.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,7 +90,7 @@ 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.4.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.5.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-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)

{pen_stack-6.4.2 → pen_stack-6.5.0}/README.md

@@ -15,7 +15,7 @@ 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.4.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.5.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-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)

pen_stack-6.5.0/configs/calibration/preexisting_nab_independent.yaml

@@ -0,0 +1,25 @@
+# PEN-STACK — INDEPENDENT calibration data for the pre-existing-NAb axis (proxy → outcome validation).
+#
+# The preexisting_nab PROXY (configs/seroprevalence.yaml) is curated from Calcedo 2009 (10.1086/595830) and
+# Boutin 2010 (10.1089/hum.2009.182). To test it WITHOUT circularity, the "observed" column below is from an
+# INDEPENDENT serosurvey that did not feed the proxy:
+#
+#   Navarro-Oliveros M, et al. "Seroprevalence of adeno-associated virus types 1, 2, 3, 4, 5, 6, 8, and 9 in a
+#   Basque cohort of healthy donors." Scientific Reports 2024;14:15941.  doi:10.1038/s41598-024-66546-4  (N=100)
+#
+# Per-serotype NEUTRALIZING-antibody seroprevalence (%) as reported. eligibility = 1 − prevalence/100, to match
+# the proxy's direction (higher score = fewer patients excluded). Fed to validate.immune_calibration.calibrate_axis.
+source:
+  citation: "Navarro-Oliveros et al., Sci Rep 2024;14:15941"
+  doi: "10.1038/s41598-024-66546-4"
+  cohort: "100 healthy Basque-Country donors"
+  measure: "neutralizing-antibody seroprevalence (%)"
+  independence: "does NOT feed the proxy (proxy = Calcedo 2009 + Boutin 2010); a genuine out-of-sample test"
+observed_nab_prevalence_pct:
+  AAV1: 42
+  AAV2: 54
+  AAV5: 42
+  AAV6: 39
+  AAV8: 52
+  AAV9: 17
+# (AAV3 64%, AAV4 21% also reported but not scored by PEN-STACK → excluded from the paired test.)

pen_stack-6.5.0/configs/expression/modifiers.yaml

@@ -0,0 +1,59 @@
+# PEN-STACK — expression-MODIFIER priors (v6.5, WS-EXPRESS). Multiplicative cis-elements that shift relative
+# cassette expression. CRITICAL HONESTY: every fold-effect below is STRONGLY transgene-, cell-, and construct-
+# dependent (the canonical warning: the chimeric intron is ~20× for CAT but ~3× for luciferase in the SAME assay).
+# These are PRIORS/RANGES with citations — NOT deterministic multipliers. The model applies them with WIDE
+# uncertainty and NEVER asserts an absolute fold; the in-vivo expression MAGNITUDE stays a known-unknown.
+version: "1.0"
+
+modifiers:
+  wpre:
+    present_fold: [2.0, 5.0]        # AAV8 in vivo: ~5× mRNA liver, ~4× brain, ~2× muscle; lenti ~2–5×
+    default: 2.5
+    direction: increase
+    confidence: high
+    note: "woodchuck post-transcriptional regulatory element; most effective 3' of transgene, proximal to polyA"
+    citation: ["10.7150/ijms.14152", "Zufferey 1999 J Virol 73:2886"]
+  intron:
+    present_fold: [1.5, 5.0]        # SV40 intron ~4.39× eGFP (CHO); chimeric 3–20× (transgene-dependent)
+    default: 2.0
+    direction: increase
+    confidence: medium
+    note: "chimeric/SV40/MVM intron; STRONGLY transgene-dependent (20× CAT vs 3× luciferase); some transgenes none"
+    citation: ["10.1111/jcmm.13504", "Promega pCI bulletin"]
+  polya_strength:                   # relative, bGH as the strong reference (≈3× SV40 early polyA)
+    bgh: 1.0
+    synthetic_spa: 0.85
+    sv40: 0.6
+    default: 0.8
+    confidence: high
+    note: "bGH ≈ 3× SV40 early polyA; synthetic/SV40 give lower variance + better nuclease resistance"
+    citation: ["10.1089/dna.1986.5.115", "PMC8819543"]
+  kozak_strength:                   # translation-initiation context (GCCRCCaugG optimal)
+    optimal: 1.0
+    moderate: 0.7
+    weak: 0.4
+    default: 0.85
+    confidence: medium
+    note: "-3 purine + +4G dominant; weak context can cut expression up to ~95%; restoring optimal ~3× (RUNX3)"
+    citation: ["10.1038/s41598-018-22330-9"]
+  codon_optimization:               # CAI-driven; NON-MONOTONIC — higher CAI usually but not always higher
+    optimized_fold: [1.0, 10.0]     # typical 2–10×; documented 6–9× and ~10×; can also fail/backfire
+    default: 2.0
+    direction: increase_usually
+    confidence: medium
+    note: "CAI correlates with expression IMPERFECTLY (GC%, mRNA structure, hidden motifs also matter); not guaranteed"
+    citation: ["10.3389/fbioe.2024.1371596", "Sharp & Li 1987 NAR 15:1281"]
+  cpg_silencing:                    # high CpG density in the transcribed region -> repression/silencing
+    direction: decrease
+    magnitude: "context/locus-dependent — NO single sourced fold"
+    confidence: high_direction_low_magnitude
+    note: "high CpG promotes transcriptional repression + de-novo methylation + immunogenicity; CpG-depletion can escape silencing"
+    citation: ["10.1186/gb-2003-4-9-r53"]
+
+# composition policy (honesty): modifiers are applied as a BOUNDED relative shift with WIDE uncertainty, NOT a
+# naive product of independent folds (no source supports multiplicativity). The output stays a relative,
+# dimensionless estimate; absolute titer / % of normal remains a known-unknown.
+composition:
+  policy: "bounded_relative_shift"
+  max_total_uplift: 4.0            # cap the combined modifier uplift (avoid runaway products)
+  uncertainty: "wide — modifier effects are transgene/context-dependent priors, not measured for this construct"

pen_stack-6.5.0/configs/expression/promoters.yaml

@@ -0,0 +1,52 @@
+# PEN-STACK — comprehensive relative-promoter-strength palette (v6.5, WS-EXPRESS).
+#
+# A RELATIVE, ordinal, dimensionless strength per named promoter (0–1, EF1a/CAG ≈ 1.0 as the reference top tier).
+# CRITICAL HONESTY: promoter strength has NO universal scalar — it depends on cell type, vector backbone, and
+# readout (peak intensity vs long-term durability give DIFFERENT orderings; Qin 2010 vs Norrman 2010). So each
+# entry carries its `context`, `assay`, a `citation`, and a `confidence`. The `strength` is an ordinal PRIOR
+# anchored to the cited head-to-head studies — it is a proxy, not a measured absolute. Values marked
+# `confidence: low` had no directly-sourced number (qualitative tier only). NEVER treat these as exact.
+#
+# Anchors: Qin 2010 PLoS ONE 5(5):e10611 (SV40/CMV/UBC/EF1A/PGK/CAGG × 8 cell types, peak GFP);
+# Norrman 2010 PLoS ONE 5(8):e12413 (durability in hESC); Damdindorj 2014 PLoS ONE 9(8):e106472 (AAV context);
+# plus the per-tissue citations below.
+version: "1.0"
+reference: "EF1a (full) / CAG ≈ 1.0 (top constitutive tier, Qin 2010)"
+
+constitutive:
+  ef1a:        { strength: 1.00, context: ubiquitous,   assay: "peak GFP, 8 cell types", confidence: high,   note: "full ~1.2 kb with intron 1; top tier (Qin 2010); durable", citation: "10.1371/journal.pone.0010611" }
+  cag:         { strength: 1.00, context: ubiquitous,   assay: "peak GFP, 8 cell types", confidence: high,   note: "CMVe+chicken β-actin+rabbit β-globin; co-strongest (Qin 2010)", citation: "10.1371/journal.pone.0010611" }
+  cba:         { strength: 0.95, context: ubiquitous,   assay: "AAV/brain",              confidence: medium, note: "CAG-class, ~1.6 kb (large for AAV)", citation: "10.1089/hum.2010.245" }
+  cbh:         { strength: 0.90, context: ubiquitous,   assay: "neurons/AAV",            confidence: medium, note: "~0.8 kb hybrid; ≈CBA at half size; serotype-dependent", citation: "10.1089/hum.2010.245" }
+  cmv:         { strength: 0.90, context: "variable!",  assay: "peak GFP",               confidence: high,   note: "very strong transiently (293T) but SILENCES over time + in stem cells (6.7% eGFP+ d50 hESC)", citation: "10.1371/journal.pone.0012413" }
+  rsv:         { strength: 0.85, context: ubiquitous,   assay: "muscle/various",         confidence: medium, note: "≈CMV-class historically", citation: "10.1038/sj.mt.6300027" }
+  sffv:        { strength: 0.95, context: hematopoietic,assay: "human HSPC/blood",       confidence: medium, note: "much stronger than CAG/EF1/PGK in blood lineage; silences in stem cells", citation: "10.1089/10430340252898984" }
+  mnd:         { strength: 0.90, context: "t_cell/lenti",assay: "lentiviral CAR-T",      confidence: medium, note: "≈EF1a in T cells (MND U3 / MoMuLV)", citation: "10.1016/j.omtm.2022.05.005" }
+  mscv:        { strength: 0.80, context: "hsc/retro",  assay: "gammaretro backbone",    confidence: medium, note: "strong in gammaretro; underperforms in lentiviral backbone", citation: "PMC7380635" }
+  sv40:        { strength: 0.70, context: ubiquitous,   assay: "peak GFP",               confidence: high,   note: "mid tier; generally weaker than EF1a/CAG (Qin 2010)", citation: "10.1371/journal.pone.0010611" }
+  efs:         { strength: 0.70, context: ubiquitous,   assay: "lenti/size-limited",     confidence: low,    note: "EF1a core (intronless ~0.2 kb); weaker than full EF1a — fold not directly sourced", citation: null }
+  jet:         { strength: 0.55, context: ubiquitous,   assay: synthetic,                confidence: low,    note: "compact synthetic minimal; relative number not sourced", citation: "10.1016/S0378-1119(02)00878-8" }
+  casi:        { strength: 0.90, context: hematopoietic,assay: synthetic,                confidence: low,    note: "CAG-derived synthetic (CMVe+β-actin+UBC enh); head-to-head fold not sourced", citation: null }
+  actb:        { strength: 0.80, context: ubiquitous,   assay: "durability hESC",        confidence: high,   note: "human β-actin promoter; top long-term durability (74% eGFP+ d50 hESC, Norrman 2010)", citation: "10.1371/journal.pone.0012413" }
+  hsv_tk:      { strength: 0.30, context: ubiquitous,   assay: "AAV",                    confidence: medium, note: "HSV thymidine-kinase promoter; weak constitutive reference (Damdindorj 2014)", citation: "10.1371/journal.pone.0106472" }
+  pgk:         { strength: 0.50, context: ubiquitous,   assay: "peak GFP",               confidence: high,   note: "weak peak but DURABLE/low-silencing (74% eGFP+ d50 hESC)", citation: "10.1371/journal.pone.0010611" }
+  ubc:         { strength: 0.40, context: ubiquitous,   assay: "peak GFP",               confidence: high,   note: "weakest of the common constitutive set (Qin 2010)", citation: "10.1371/journal.pone.0010611" }
+
+tissue_specific:
+  tbg:         { strength: 1.00, context: liver,   confidence: medium, note: "top liver promoter (> LP1 > HLP); clean liver restriction; compact", citation: "10.1016/j.gene.2012.07.009" }
+  apoe_haat:   { strength: 0.85, context: liver,   confidence: medium, note: "ApoE-HCR enhancer + hAAT; first hemophilia-B FIX trials", citation: "10.1182/blood-2005-10-4035" }
+  lp1:         { strength: 0.85, context: liver,   confidence: medium, note: "HCR1 enhancer + hAAT core; clinical FIX from single AAV (2nd after TBG)", citation: "10.1182/blood-2005-10-4035" }
+  haat:        { strength: 0.80, context: liver,   confidence: medium, note: "human α1-antitrypsin; base of ApoE-hAAT/LP1 hybrids", citation: "10.1182/blood-2005-10-4035" }
+  hlp:         { strength: 0.70, context: liver,   confidence: medium, note: "HCR+hAAT+ApoE ~800 bp; below TBG/LP1; therapeutic at compact size", citation: "10.1016/j.gene.2012.07.009" }
+  camkiia:     { strength: 0.90, context: neuron,  confidence: medium, note: "excitatory neurons; greater overall expression than hSyn1", citation: "10.1016/j.neulet.2021.135889" }
+  hsyn:        { strength: 0.70, context: neuron,  confidence: medium, note: "pan-neuronal ~460 bp; robust but slower kinetics (CAG-level only by ~3 mo)", citation: "10.1016/j.neulet.2021.135889" }
+  mecp2:       { strength: 0.50, context: neuron,  confidence: low,    note: "neuron-restricted compact; weaker — relative fold not sourced", citation: null }
+  gfaabc1d:    { strength: 0.80, context: astrocyte,confidence: high,  note: "~681 bp; ~2× stronger than full gfa2; astrocyte-restricted", citation: "10.1002/glia.20622" }
+  gfap:        { strength: 0.60, context: astrocyte,confidence: medium,note: "gfa2 ~2.2 kb astrocyte-selective", citation: "10.1002/glia.20622" }
+  mhck7:       { strength: 1.00, context: muscle,  confidence: medium, note: "MCK enh + α-MHC ~770 bp; highest of muscle panel; DMD clinical", citation: "10.1038/sj.mt.6300027" }
+  mck:         { strength: 0.90, context: muscle,  confidence: medium, note: "truncated MCK; more active than CMV in muscle", citation: "10.1038/gt.2008.104" }
+  ck8:         { strength: 0.85, context: muscle,  confidence: low,    note: "compact muscle promoter; DMD clinical vectors", citation: "10.32607/actanaturae.11063" }
+  desmin:      { strength: 0.70, context: muscle,  confidence: medium, note: "mid muscle tier; ≈CMV in myotubes", citation: "10.1038/sj.mt.6300027" }
+
+# default for an unrecognised / unspecified promoter (the prior mean; honest abstention to mid-strength).
+default_strength: 0.5

{pen_stack-6.4.2 → pen_stack-6.5.0}/configs/metric_guide.yaml

@@ -82,11 +82,18 @@ metrics:
     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)."
+    means: "a RELATIVE, dimensionless expression estimate (promoter × copy number × accessibility, + a bounded
+      modifier uplift range). 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 over a COMPREHENSIVE literature-cited palette (v6.5: 31 promoters,
+      constitutive + tissue-specific, each with its context/assay/citation — configs/expression/promoters.yaml)
+      plus modifier PRIORS (WPRE, intron, polyA, Kozak, codon-opt, CpG-silencing — configs/expression/modifiers.yaml,
+      reported as a bounded uplift RANGE, never a point multiplier). Interval widens ~1.6× under OOD context."
+    validation: "richly literature-anchored PROXY, NOT outcome-validated: an INDEPENDENT promoter study
+      (Damdindorj 2014) disagrees with the anchor (Qin 2010) on CMV/CAG/EF1a ordering — promoter strength is
+      genuinely CONTEXT-dependent (cell × vector × readout), so a single context-free ordinal does not validate
+      cross-study (Spearman ~0.12 vs Damdindorj, CI includes 0). The palette now ENCODES that context rather than
+      asserting a universal number. Modifier folds are transgene-dependent priors."
     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)

{pen_stack-6.4.2 → pen_stack-6.5.0}/pen_stack/__init__.py

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

pen_stack-6.5.0/pen_stack/twin/mechanistic.py

@@ -0,0 +1,119 @@
+"""Mechanistic simulation where computable (v5.9 + v6.5 WS-EXPRESS).
+
+Computes the consequences MECHANISM allows — steady-state cassette expression in a chromatin context — and
+nothing more. Physics where computable; explicitly NOT a phenotype, NOT in-vivo behaviour, NOT durability beyond
+the steady state. Assumptions and scope flags travel with every output.
+
+v6.5: the promoter palette is now a comprehensive, literature-cited table (configs/expression/promoters.yaml,
+~25 constitutive + tissue-specific promoters) and the cassette carries an honest MODIFIER profile (WPRE, intron,
+polyA, Kozak, codon-optimization, CpG-silencing — configs/expression/modifiers.yaml). Modifier effects are
+transgene-dependent PRIORS, so they are reported as a bounded uplift RANGE with wide uncertainty, never folded
+into the [0,1] base score as a point estimate. Absolute titer / % of normal stays a known-unknown.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+# legacy default keys kept for backward compatibility (pre-v6.5 designs used these names directly).
+_LEGACY_STRENGTH = {"ef1a": 1.0, "cag": 1.0, "cmv": 0.9, "pgk": 0.6, "ubc": 0.5,
+                    "endogenous": 0.4, "minimal": 0.2}
+
+
+@lru_cache(maxsize=1)
+def _palette() -> dict:
+    """Flatten the comprehensive promoter palette (constitutive + tissue-specific) to {name: entry}."""
+    try:
+        cfg = yaml.safe_load(resource("configs/expression/promoters.yaml").read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 - config absent (shouldn't happen) -> legacy table only
+        return {}
+    out: dict = {}
+    for group in ("constitutive", "tissue_specific"):
+        for name, e in (cfg.get(group) or {}).items():
+            out[name] = e
+    out["_default"] = cfg.get("default_strength", 0.5)
+    return out
+
+
+@lru_cache(maxsize=1)
+def _modifiers() -> dict:
+    try:
+        return yaml.safe_load(resource("configs/expression/modifiers.yaml").read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return {"modifiers": {}, "composition": {"max_total_uplift": 4.0}}
+
+
+def promoter_info(name: str) -> dict:
+    """The cited palette entry for a promoter (strength + context + assay + citation), or a default."""
+    pal = _palette()
+    key = str(name or "").strip().lower()
+    if key in pal:
+        return pal[key]
+    if key in _LEGACY_STRENGTH:
+        return {"strength": _LEGACY_STRENGTH[key], "context": "ubiquitous", "confidence": "legacy"}
+    return {"strength": pal.get("_default", 0.5), "context": "unknown", "confidence": "default"}
+
+
+def _promoter_strength(design: dict) -> tuple[float, dict]:
+    p = design.get("promoter")
+    if isinstance(p, dict) and p.get("strength") is not None:
+        return float(p["strength"]), {"context": p.get("context", "supplied"), "confidence": "supplied"}
+    name = p if isinstance(p, str) else str(p or "")
+    info = promoter_info(name)
+    return float(info.get("strength", 0.5)), info
+
+
+def _modifier_profile(design: dict) -> dict:
+    """Honest, bounded modifier uplift RANGE from the cassette's cis-elements. NOT a point multiplier and NOT
+    folded into the [0,1] base — modifier effects are transgene/context-dependent priors with wide uncertainty."""
+    mods = _modifiers().get("modifiers", {})
+    cap = float(_modifiers().get("composition", {}).get("max_total_uplift", 4.0))
+    applied, hi = [], 1.0                       # lower bound stays 1.0: a modifier may do nothing for THIS transgene
+    for key, present in (("wpre", design.get("wpre")), ("intron", design.get("intron"))):
+        if present and key in mods:
+            hi *= float(mods[key].get("present_fold", [1.0, 1.0])[1])
+            applied.append(key)
+    if design.get("codon_optimized") and "codon_optimization" in mods:
+        hi *= float(mods["codon_optimization"].get("optimized_fold", [1.0, 1.0])[1])
+        applied.append("codon_optimization")
+    cpg_flag = bool(design.get("high_cpg") or (design.get("cpg_oe") is not None and float(design.get("cpg_oe")) > 0.6))
+    if cpg_flag:
+        applied.append("cpg_silencing(down)")
+    lo, hi = 1.0, round(min(hi, cap), 2)
+    return {
+        "applied": applied,
+        "estimated_uplift_range": [round(lo, 2), round(hi, 2)],
+        "direction_note": ("net uplift expected (transgene-dependent)" if hi > 1.0 else "no modifier signal"),
+        "cpg_silencing_risk": bool(cpg_flag),
+        "caveat": "modifier effects are transgene/cell/construct-dependent PRIORS (e.g. an intron is ~20x for one "
+                  "transgene, ~3x for another) — a bounded range, not a measured multiplier for THIS construct.",
+        "source": "configs/expression/modifiers.yaml (literature priors)",
+    }
+
+
+def cassette_expression(design: dict, chromatin_ctx: dict) -> dict:
+    """Computable steady-state RELATIVE expression from an integrated cassette: promoter_strength x copy_number x
+    accessibility (base, [0,1]-relative), PLUS an honest, bounded modifier uplift range. NOT a phenotype, NOT an
+    absolute titer."""
+    p, pinfo = _promoter_strength(design)
+    cn = float(design.get("copy_number", 1) or 1)
+    acc = float(chromatin_ctx.get("accessibility", 1.0) if chromatin_ctx else 1.0)
+    rel = p * cn * acc
+    flags = ["episomal_durability_unknown", "phenotype_not_modeled"]
+    # context honesty: a promoter that silences (CMV, SFFV in stem cells) is flagged, not silently trusted.
+    if str(pinfo.get("context", "")).startswith("variable") or "SILENCE" in str(pinfo.get("note", "")).upper():
+        flags.append("promoter_context_variable_or_silencing")
+    return {
+        "relative_expression": round(rel, 4),
+        "units": "relative (dimensionless)",
+        "modifier_profile": _modifier_profile(design),
+        "assumptions": ["steady-state", "no silencing dynamics modeled", "linear copy scaling",
+                        "promoter strength is an ordinal literature prior (context-dependent)"],
+        "scope_flags": flags,
+        "provenance": {"promoter_strength": p, "promoter_context": pinfo.get("context"),
+                       "promoter_citation": pinfo.get("citation"), "copy_number": cn, "accessibility": acc,
+                       "source": "twin.mechanistic (closed-form steady state + literature promoter palette v6.5)"},
+    }

{pen_stack-6.4.2 → pen_stack-6.5.0}/pen_stack/web/tools.py

@@ -28,6 +28,9 @@ _BP_RE = re.compile(r"(\d{3,6})\s*bp", re.I)
 # uppercase tokens that look like a gene but are not one (jargon / vehicle / form abbreviations)
 _GENE_STOP = {"DNA", "RNA", "MRNA", "AAV", "LNP", "HSV", "CAR", "RNP", "PCR", "WT", "KO", "KI", "ITR",
               "ORF", "UTR", "CDS", "GFP", "ID", "QC", "VG", "MOI", "HLA", "MHC", "CRISPR", "CAS", "TF"}
+# safe-harbour locus nicknames whose text collides with a vehicle keyword (AAVS1 ⊃ "aav") — stripped before
+# vehicle matching so the user's stated vehicle (e.g. lentivirus) is not overridden by the locus name.
+_SAFE_HARBOUR_RE = re.compile(r"\b(aavs1|h11|hipp11|rosa26)\b", re.I)
 
 
 def _first(text: str, table: dict, default):
@@ -59,9 +62,13 @@ def parse_goal(message: str) -> dict:
         cargo = int(m.group(1))
     genes = [g for g in _GENE_RE.findall(message) if g not in _GENE_STOP]
     gene = genes[0] if genes else "AAVS1"
+    # Vehicle matching is substring-based (so "lentivir" catches "lentiviral"); but the safe-harbour nickname
+    # "AAVS1" contains "aav", which would wrongly match the AAV vehicle even when the user said lentivirus/LNP.
+    # Strip those nicknames from the vehicle-search text first so the stated vehicle wins.
+    veh_text = _SAFE_HARBOUR_RE.sub(" ", message.lower())
     return {"write_type": "insertion", "gene": gene, "chrom": _resolve_chrom(gene) or "chr19",
             "edit_intent": _first(message, _INTENTS, "safe_harbour_insertion"),
-            "delivery_vehicle": _first(message, _VEHICLES, "AAV_single"), "cargo_bp": cargo,
+            "delivery_vehicle": _first(veh_text, _VEHICLES, "AAV_single"), "cargo_bp": cargo,
             "cell_type": _first(message, _CELLS, "k562"),
             # the user's plain-language goal IS the cargo-function description the Guardian must screen — so a
             # message like "express a ricin toxin" is biosecurity-screened, not silently passed as benign.

{pen_stack-6.4.2 → pen_stack-6.5.0}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.4.2
+Version: 6.5.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,7 +90,7 @@ 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.4.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.5.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-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)

{pen_stack-6.4.2 → pen_stack-6.5.0}/pen_stack.egg-info/SOURCES.txt

@@ -37,6 +37,9 @@ configs/target_sites.yaml
 configs/universe_crosswalk.yaml
 configs/write_types.yaml
 configs/wtkb_curated.yaml
+configs/calibration/preexisting_nab_independent.yaml
+configs/expression/modifiers.yaml
+configs/expression/promoters.yaml
 configs/oracles/execution.yaml
 configs/oracles/scope_cards.yaml
 configs/rules/delivery.yaml
@@ -435,6 +438,7 @@ prereg/ws_uq.yaml
 prereg/ws_v.yaml
 prereg/ws_vcell.yaml
 prereg/ws_wv.yaml
+scripts/calibrate_immune_axes.py
 scripts/p1_build_atlas.py
 scripts/p1_build_durability.py
 scripts/p1_export_tracks.py

{pen_stack-6.4.2 → pen_stack-6.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pen-stack"
-version = "6.4.2"
+version = "6.5.0"
 description = "Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner."
 readme = "README.md"
 requires-python = ">=3.11"

pen_stack-6.5.0/scripts/calibrate_immune_axes.py

@@ -0,0 +1,116 @@
+"""Attempt to OUTCOME-VALIDATE every immune/expression proxy against INDEPENDENT measured data.
+
+The gate (pen_stack.validate.immune_calibration.calibrate_axis) upgrades an axis to ✅ "outcome_validated"
+ONLY when N>=6 paired (proxy, independent-measured-outcome) points exist AND the bootstrap Spearman CI excludes
+zero. This script runs that gate for each axis with the best public INDEPENDENT data we could curate, and prints
+the honest status. It NEVER fabricates an outcome dataset to manufacture a positive result.
+
+Run: `python scripts/calibrate_immune_axes.py`  (CI-safe; pure-Python + scipy).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from pen_stack.validate.immune_calibration import calibrate_axis
+
+_ROOT = Path(__file__).resolve().parents[1]
+
+
+def _midpoint_score(rng: list[float]) -> float:
+    """preexisting_score = 1 − midpoint(seroprevalence %)/100 (matches seroprevalence_oracle)."""
+    return round(1 - (sum(rng) / 2) / 100, 4)
+
+
+def nab() -> dict:
+    """pre-existing NAb: 6 AAV serotypes scored. Proxy = Calcedo+Boutin midpoints; observed = INDEPENDENT
+    Basque cohort (Navarro-Oliveros 2024). The one axis that reaches N=6."""
+    sero = yaml.safe_load((_ROOT / "configs/seroprevalence.yaml").read_text(encoding="utf-8"))["serotypes"]
+    obs_cfg = yaml.safe_load((_ROOT / "configs/calibration/preexisting_nab_independent.yaml").read_text(encoding="utf-8"))
+    obs_prev = obs_cfg["observed_nab_prevalence_pct"]
+    serotypes = [s for s in obs_prev if s in sero]
+    proxy = [_midpoint_score(sero[s]["nab_seroprevalence_pct"]) for s in serotypes]
+    observed = [round(1 - obs_prev[s] / 100, 4) for s in serotypes]          # eligibility (same direction)
+    res = calibrate_axis(proxy, observed, axis="preexisting_nab")
+    res["entities"] = serotypes
+    res["independent_source"] = obs_cfg["source"]["citation"]
+    return res
+
+
+# Structural barrier: the other proxies score FEWER than the 6 entities the gate needs to even run.
+_STRUCTURAL = {
+    "genotoxicity": {"entities_scored": 3, "what": "vector classes (HIV/lentiviral, HTLV/deltaretroviral, MLV/gammaretroviral)",
+                     "outcome_needed": "measured genotoxicity per vector (IVIM mutagenic frequency / tumour-prone mouse incidence)",
+                     "barrier": "N=3 < 6 — the proxy scores only 3 vector classes; cannot run the gate."},
+    "cd8_epitope": {"entities_scored": 5, "what": "capsids (AAV2, Ad5, VSVg, +2)",
+                    "outcome_needed": "measured anti-capsid CD8 T-cell response rates per serotype",
+                    "barrier": "N≈5 < 6 — too few capsids scored; cannot run the gate."},
+    "innate": {"entities_scored": 0, "what": "no fixed entity set (per-cargo-sequence)",
+               "outcome_needed": "measured TLR9/RIG-I innate-activation per sequence",
+               "barrier": "no fixed paired set; cannot assemble ≥6 independent points."},
+    "anti_peg": {"entities_scored": 1, "what": "a single population prevalence value",
+                 "outcome_needed": "measured re-dosing-failure rate / independent anti-PEG prevalence",
+                 "barrier": "N=1 — a single population statistic; cannot run the gate."},
+    "relative_expression": {"entities_scored": 5, "what": "named promoters (ef1a, cag, cmv, pgk, ubc)",
+                            "outcome_needed": "MPRA / independent comparative promoter-strength measurements",
+                            "barrier": "N=5 < 6 — palette must be expanded to ≥6 promoters with independent strengths."},
+}
+
+
+def expression() -> dict:
+    """relative-expression promoter ordinal — INDEPENDENT validation. The palette is anchored to Qin 2010 /
+    Norrman 2010, so the honest test is whether it predicts a DIFFERENT study's measurements: Damdindorj 2014
+    (AAV context, colon/fibroblast lines). It does NOT — the two studies genuinely disagree (Damdindorj found
+    CMV strongest, CAG/EF1a much weaker; Qin found the opposite) because promoter strength is context-dependent.
+    A consistency check vs Qin alone gives rho=0.94 but is CIRCULAR (same source) — not reported as validation."""
+    from pen_stack.twin.mechanistic import promoter_info
+    proms = ["cmv", "actb", "sv40", "ef1a", "cag", "hsv_tk"]               # overlap with Damdindorj 2014
+    proxy = [float(promoter_info(p)["strength"]) for p in proms]
+    observed = [1.00, 0.80, 0.65, 0.50, 0.40, 0.20]                        # Damdindorj 2014 (independent) ranking
+    res = calibrate_axis(proxy, observed, axis="relative_expression")
+    res["entities"] = proms
+    res["note"] = ("INDEPENDENT test vs Damdindorj 2014 (10.1371/journal.pone.0106472) — palette is "
+                   "Qin/Norrman-anchored; the studies disagree (context-dependence), so it does NOT validate")
+    return res
+
+
+def main() -> None:
+    print("=" * 88)
+    print("PEN-STACK proxy → outcome validation (gate: N>=6 AND bootstrap Spearman CI excludes 0)")
+    print("=" * 88)
+
+    r = nab()
+    print(f"\n[preexisting_nab]  N={r['n']}  serotypes={r['entities']}")
+    print(f"  independent outcome: {r['independent_source']}")
+    print(f"  Spearman rho = {r['spearman']}   CI = {r['ci']}   ->  status = {r['status'].upper()}")
+    print(f"  {r['label']}")
+    if r["status"] != "outcome_validated":
+        print("  => stays 🟡 (population proxy). Note: at N=6 the bootstrap CI is ~[-1,1] — it cannot exclude 0,")
+        print("     so even a strong rho would not pass; ~15-20+ independent serotypes/points are needed.")
+
+    e = expression()
+    print(f"\n[relative_expression]  N={e['n']}  promoters={e['entities']}")
+    print(f"  {e['note']}")
+    print(f"  Spearman rho = {e['spearman']}   CI = {e['ci']}   ->  status = {e['status'].upper()}")
+    print("  => stays 🟡 — the palette is now COMPREHENSIVE (31 promoters + 6 modifiers, all literature-cited),")
+    print("     but it does NOT outcome-validate: an independent study (Damdindorj 2014) DISAGREES with the")
+    print("     anchor (Qin 2010) on CMV/CAG/EF1a ordering. Promoter strength is genuinely CONTEXT-DEPENDENT")
+    print("     (cell type × vector × readout), so a single context-free ordinal cannot be validated cross-study.")
+    print("     The model's value is that it now ENCODES that context per promoter — not a fake single number.")
+
+    for axis, info in _STRUCTURAL.items():
+        if axis == "relative_expression":
+            continue
+        print(f"\n[{axis}]  scores {info['entities_scored']} {info['what']}")
+        print(f"  would need: {info['outcome_needed']}")
+        print(f"  => stays 🟡 — {info['barrier']}")
+
+    print("\n" + "-" * 88)
+    print("CONCLUSION: no axis meets the ✅ gate with current public data. The labels are honest. Reaching ✅")
+    print("requires EXPANDING each proxy to >=~15 scored entities AND matching independent measured outcomes —")
+    print("a data-generation effort (the standing real-data-validation bottleneck), not a code change.")
+
+
+if __name__ == "__main__":
+    main()

pen_stack-6.4.2/pen_stack/twin/mechanistic.py

@@ -1,37 +0,0 @@
-"""Mechanistic simulation where computable (v5.9, WS-MECH).
-
-Computes the consequences MECHANISM allows — steady-state cassette expression in a chromatin context — and
-nothing more. Physics where computable; explicitly NOT a phenotype, NOT in-vivo behaviour, NOT durability beyond
-the steady state. Assumptions and scope flags travel with every output.
-"""
-from __future__ import annotations
-
-# documented relative promoter strengths (ordinal, dimensionless) — a curated default palette.
-_PROMOTER_STRENGTH = {"ef1a": 1.0, "cag": 1.0, "cmv": 0.9, "pgk": 0.6, "ubc": 0.5,
-                      "endogenous": 0.4, "minimal": 0.2}
-
-
-def _promoter_strength(design: dict) -> float:
-    p = design.get("promoter")
-    if isinstance(p, dict) and p.get("strength") is not None:
-        return float(p["strength"])
-    if isinstance(p, str):
-        return _PROMOTER_STRENGTH.get(p.strip().lower(), 0.5)
-    return _PROMOTER_STRENGTH.get(str(p or "").strip().lower(), 0.5)
-
-
-def cassette_expression(design: dict, chromatin_ctx: dict) -> dict:
-    """Computable steady-state relative expression from an integrated cassette:
-    promoter_strength x copy_number x accessibility. Physics where computable; NOT a phenotype."""
-    p = _promoter_strength(design)
-    cn = float(design.get("copy_number", 1) or 1)
-    acc = float(chromatin_ctx.get("accessibility", 1.0) if chromatin_ctx else 1.0)
-    rel = p * cn * acc
-    return {
-        "relative_expression": round(rel, 4),
-        "units": "relative (dimensionless)",
-        "assumptions": ["steady-state", "no silencing modeled", "linear copy scaling"],
-        "scope_flags": ["episomal_durability_unknown", "phenotype_not_modeled"],
-        "provenance": {"promoter_strength": p, "copy_number": cn, "accessibility": acc,
-                       "source": "twin.mechanistic (closed-form steady state)"},
-    }