pen-stack 6.2.1__tar.gz → 6.2.3__tar.gz

{pen_stack-6.2.1 → pen_stack-6.2.3}/CHANGELOG.md

@@ -3,6 +3,42 @@
 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.2.3] - 2026-06-12 - v6.2.3: scope matcher covers functional titer + durability (patch)
+
+**Honesty-coverage fix (from the 20-query acceptance suite, `phase_6.2/PEN-STACK_ACCEPTANCE_TESTS.md`).** The
+known-unknowns matcher (`configs/known_unknowns.yaml`) had no entry for *functional titer / absolute in-vivo
+expression magnitude* and its *durability* terms were too narrow ("how long will it last **in a patient**"), so
+common measured-endpoint questions ("what functional titer (% of normal)?", "how long will episomal AAV
+expression last?") were not explicitly deferred. The no-fabrication spine already held (no titer/half-life was
+ever emitted, and the immune profile lists `patient_specific_titer`), but the matcher should flag these
+proactively.
+
+### Added / Fixed
+- `configs/known_unknowns.yaml`: new known-unknown `in_vivo_expression_magnitude` (functional titer / % of normal
+  / absolute expression — a measured clinical endpoint, never predicted; PEN-STACK gives the relative mechanistic
+  proxy + immune context); broadened `long_term_clinical_durability` match-terms/patterns to catch "how long will
+  … last/persist", "durability", "half-life". Regression test
+  `tests/unit/test_ws_api.py::test_scope_defers_titer_and_durability_questions`.
+
+### Acceptance suite result
+- 20/20 behave as specified at the engine level: grounded where earned, refusing where unsafe (ricin/botulinum),
+  abstaining/deferring where honest (titer, durability, phenotype), no fabricated number. T10 (RNP↔AAV) and T12
+  (multiplex translocation) are enforced via `delivery.cargo_form_compatible` and `multiplex.translocation_risk`
+  on the structured design fields (`writer_output_form`, `edits`).
+
+## [6.2.2] - 2026-06-12 - v6.2.2: safe-harbour locus-nickname resolution (patch)
+
+**Usability fix.** Site Finder / `/plan` / `/writable` returned 0 plans for `AAVS1` because it is a genomic
+safe-harbour *locus nickname*, not an HGNC gene symbol, so the gene→coordinate lookup (`gene_coords`, 60,888
+symbols) could not resolve it — honest empty, but unhelpful for the most-typed safe harbour. (The cell-type
+atlases are complete; real symbols like `PCSK9`/`HBB`/`CCR5`/`CLYBL` resolved fine.)
+
+### Fixed
+- `pen_stack/planner/optimize.py`: `resolve_gene()` maps well-documented safe-harbour nicknames to their host
+  gene (`AAVS1`→`PPP1R12C` 19q13.42; `H11`/`Hipp11`→`EIF4ENIF1` 22q12) at every gene→coordinate lookup
+  (`gene_region`, `plan`, `crosslink.loci_for_gene`); real symbols pass through unchanged. Regression test
+  `tests/unit/test_ws_api.py::test_safe_harbour_nickname_resolves_to_host_gene`.
+
 ## [6.2.1] - 2026-06-12 - v6.2.1: JSON-safe atlas/crosslink endpoints (patch)
 
 **Bug fix.** The `/atlas`, `/writable`, and `/crosslink/loci` endpoints returned raw DataFrame records, which

{pen_stack-6.2.1 → pen_stack-6.2.3}/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.1
+version: 6.2.3
 date-released: 2026-06-11
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.2.1 → pen_stack-6.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.2.1
+Version: 6.2.3
 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.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.2.3-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-369%20passing-success.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-371%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/)

{pen_stack-6.2.1 → pen_stack-6.2.3}/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.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.2.3-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-369%20passing-success.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-371%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/)

{pen_stack-6.2.1 → pen_stack-6.2.3}/configs/known_unknowns.yaml

@@ -36,8 +36,24 @@ known_unknowns:
       cassette in a given epigenome) — it does NOT predict multi-year in-vivo persistence, immune clearance,
       or clonal dynamics in a patient"
     match_terms: ["long-term in-vivo", "long term in vivo", "years of expression", "clinical durability",
-                  "persist in the patient", "how long will it last in", "in-vivo persistence", "clonal"]
-    patterns: ["\\bhow long (will|would) (it|the cassette|expression) (last|persist) (in|in a)\\b"]
+                  "persist in the patient", "how long will it last in", "in-vivo persistence", "clonal",
+                  "how long will expression last", "how long will it last", "how long will the cassette",
+                  "expression duration", "half-life", "half life", "will it persist", "how durable",
+                  "durability magnitude", "how long does"]
+    patterns: ["\\bhow long\\b[^?]{0,60}\\b(last|persist|express|stay expressed|remain)\\b",
+               "\\bduration of (expression|the cassette|the transgene)\\b"]
+
+  - id: in_vivo_expression_magnitude
+    title: "absolute in-vivo expression magnitude / functional titer"
+    requires: "an in-vivo expression / pharmacokinetic measurement (functional titer, % of normal, ng/mL) in a
+      living organism"
+    why: "PEN-STACK computes a RELATIVE, dimensionless mechanistic expression proxy (promoter × copy ×
+      accessibility) and the immune context — it does NOT predict an absolute in-vivo functional titer, a
+      percent-of-normal level, or a protein concentration; that is a measured clinical endpoint, never predicted"
+    match_terms: ["titer", "titre", "percent of normal", "% of normal", "percent normal", "iu/ml", "ng/ml",
+                  "absolute expression", "expression level in vivo", "how much protein", "how much will it express",
+                  "what level of expression", "protein concentration", "serum level", "plasma level"]
+    patterns: ["\\bwhat (functional )?titer\\b", "\\b\\d+\\s*% of normal\\b"]
 
   - id: higher_order_epistasis
     title: "higher-order epistasis / multi-edit interaction beyond the translocation screen"

{pen_stack-6.2.1 → pen_stack-6.2.3}/pen_stack/__init__.py

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

{pen_stack-6.2.1 → pen_stack-6.2.3}/pen_stack/atlas/crosslink.py

@@ -99,13 +99,10 @@ def writers_for_locus(chrom: str, bin_idx: int, ct: str = "k562") -> pd.DataFram
 
 def loci_for_gene(gene: str, ct: str = "k562", gene_coords: str | Path | None = None) -> pd.DataFrame:
     """Writable bins overlapping a gene body (forward query helper)."""
-    if gene_coords:
-        gc_path = Path(gene_coords)
-    else:
-        from pen_stack.planner.optimize import gene_coords_path
-        gc_path = gene_coords_path()
+    from pen_stack.planner.optimize import gene_coords_path, resolve_gene
+    gc_path = Path(gene_coords) if gene_coords else gene_coords_path()
     gc = pd.read_parquet(gc_path)
-    g = gc[gc["gene"] == gene]
+    g = gc[gc["gene"] == resolve_gene(gene)]      # resolve safe-harbour nicknames (AAVS1 -> PPP1R12C)
     if g.empty:
         return pd.DataFrame()
     r = g.iloc[0]

{pen_stack-6.2.1 → pen_stack-6.2.3}/pen_stack/planner/optimize.py

@@ -209,9 +209,20 @@ def _gene_coords(path: str | None = None) -> pd.DataFrame:
     return pd.read_parquet(Path(path) if path else gene_coords_path())
 
 
+# Genomic safe-harbour *locus nicknames* are not HGNC gene symbols, so they are absent from gene_coords; map the
+# well-documented ones to their host gene so a user who types the common name still gets a plan. AAVS1 = intron 1
+# of PPP1R12C (19q13.42); H11/Hipp11 = an intron of EIF4ENIF1 (22q12). (CCR5, CLYBL, HPRT1 are real symbols.)
+_GSH_ALIASES = {"AAVS1": "PPP1R12C", "H11": "EIF4ENIF1", "HIPP11": "EIF4ENIF1"}
+
+
+def resolve_gene(gene: str) -> str:
+    """Map a safe-harbour locus nickname (e.g. AAVS1) to its HGNC host gene; pass real symbols through unchanged."""
+    return _GSH_ALIASES.get(str(gene).strip().upper(), gene)
+
+
 def gene_region(gene: str, flank_kb: int = 50) -> tuple[str, int, int] | None:
     gc = _gene_coords()
-    g = gc[gc["gene"] == gene]
+    g = gc[gc["gene"] == resolve_gene(gene)]
     if g.empty:
         return None
     r = g.iloc[0]
@@ -232,7 +243,7 @@ def plan(gene: str, intent: EditIntent | str, cargo_bp: int, writable_df: pd.Dat
         return pd.DataFrame()
     # on_target = bin overlaps the gene body (not just the flank)
     g = _gene_coords()
-    gr = g[g["gene"] == gene].iloc[0]
+    gr = g[g["gene"] == resolve_gene(gene)].iloc[0]
     sub["on_target"] = sub["bin"].between(int(gr["start"]) // BIN_BP, int(gr["end"]) // BIN_BP)
     scored = score_candidates(sub, intent, cargo_bp)
     cols = ["chrom", "bin", "writer", "safety", "p_durable", "writer_activity",

{pen_stack-6.2.1 → pen_stack-6.2.3}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.2.1
+Version: 6.2.3
 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.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.2.3-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-369%20passing-success.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-371%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/)

{pen_stack-6.2.1 → pen_stack-6.2.3}/pyproject.toml

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