pen-stack 6.9.2__tar.gz → 6.10.0__tar.gz

{pen_stack-6.9.2 → pen_stack-6.10.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.10.0] - 2026-06-20 - WS-OFFTARGET (PEN-OFFTGT: cross-writer-family off-target nomination)
+
+**Series III, Stage E.** Off-target moves from a single-family bridge pseudosite scan to a **cross-writer-family,
+chromatin-aware NOMINATION engine** grounded in unbiased genome-wide assays — completing the safety triad
+(site B + writer C + off-target E). Nomination is scrupulously framed as **not a clearance**: every candidate
+ships with the empirical assay that would confirm it.
+
+### Added
+- **Off-Target-Bench** (`benchmarks/offtarget/`) — a real, leakage-controlled nomination benchmark over canonical
+  Cas9 guides (EMX1/VEGFA1-3/FANCF/HEK293) with **experimentally validated off-targets** from GUIDE-seq
+  (Tsai 2015, `10.1038/nbt.3117`) and CIRCLE-seq (Tsai 2017, `10.1038/nmeth.4278`). Held-out-guide split, per-assay
+  provenance, SHA256SUMS. **Gate E-G2 PASSES on real data + real tool:** the licensed **CRISOT-Score** predictor
+  (Chen et al., Nat Commun 2023, `10.1038/s41467-023-42695-4`; XGBoost RNA-DNA fingerprint) BEATS the sequence-
+  homology baseline — GUIDE-seq AUPRC **0.646 vs 0.467** (gap +0.179, CI [0.015, 0.340]); CIRCLE-seq **0.520 vs
+  0.266** (gap +0.253, CI [0.140, 0.361]); per-guide bootstrap CI excludes 0 on both assays.
+- `pen_stack/wgenome/offtarget_data.py` — validated assay/predictor provenance, a GROUNDED mismatch→active-fraction
+  risk calibration (real-data: GUIDE-seq 0-1mm→100% active, 2mm→76%, 3mm→23%, 4mm→3.3%), the bench fixture loader.
+- `pen_stack/wgenome/offtarget_predict.py` — `nominate_offtargets(writer_family, ...)`: **nuclease** (mismatch-
+  calibrated risk band + the real cached CRISOT score + a documented chromatin modifier, Lazzarotto 2020);
+  **serine integrase** (cryptic **pseudo-attB** scan on the real documented Bxb1 attB core GCGGTCTC/GT);
+  **bridge** (delegates to the existing Perry-DMS pseudosite engine). Abstains without inputs; never fabricates sites.
+- `pen_stack/wgenome/offtarget_assay.py` — validation-assay recommender (GUIDE/CHANGE/CIRCLE-seq for nucleases;
+  Cryptic-seq/HIDE-seq for integrases; **honest gap** for bridge recombinases — NO published genome-wide unbiased
+  off-target assay or predictor exists, verified).
+- **Surfaces:** REST `POST /offtarget` + `GET /offtarget/assay`, MCP `offtarget_scan`, manifest `nominate_offtargets`
+  (fabricates=False), an `offtarget_nomination` scope card, and a web **Off-Target** page.
+
+### Honest limits
+- Nomination is NOT a clearance; genome-wide candidate ENUMERATION needs the on-VM Cas-OFFinder/genome scan (this
+  engine SCORES + RANKS + risk-bands supplied candidates). The CRISOT predictor is CC-BY-NC — it runs only on the
+  VM and its weights are NEVER redistributed; only derived scores are cached (CI-safe). Bridge/integrase off-target
+  is data-thin/unmodeled and is flagged extrapolative; IntQuery (Tome Biosciences) is a paper-only reference.
+
 ## [6.9.2] - 2026-06-19 - WS-IMMUNE2 real-tool rigor pass (no proxies / no heuristics across the immune + writer axes)
 
 **PATCH — a top-to-bottom audit replacing every remaining proxy/heuristic in the immune & writer-design stack with

{pen_stack-6.9.2 → pen_stack-6.10.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.9.2
+version: 6.10.0
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.9.2 → pen_stack-6.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.9.2
+Version: 6.10.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.9.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.10.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)
@@ -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.10 — PEN-OFFTGT (cross-writer-family off-target nomination)
+
+Off-target prediction was a single-family bridge pseudosite scan that abstained for nucleases and integrases.
+v6.10 makes it a **cross-writer-family, chromatin-aware NOMINATION engine** — completing the safety triad
+(site + writer + off-target). It is scrupulously honest that **nomination is not a clearance**: every candidate
+ships with the empirical assay that would confirm it.
+
+- **A real, validated benchmark** (`benchmarks/offtarget/`) over canonical Cas9 guides with **experimentally
+  validated off-targets** from GUIDE-seq (Tsai 2015) and CIRCLE-seq (Tsai 2017). The licensed **CRISOT** predictor
+  (Chen et al. *Nat Commun* 2023) **beats the sequence-homology baseline** on held-out guides — GUIDE-seq AUPRC
+  **0.65 vs 0.47**, CIRCLE-seq **0.52 vs 0.27**; per-guide bootstrap CI excludes 0 on both. CRISOT is CC-BY-NC and
+  runs only on the VM — only derived scores are cached (like the licensed MHC tools).
+- **Grounded, calibrated risk** — the risk band IS the real-data fraction of candidates at *k* mismatches that were
+  experimentally validated-active (GUIDE-seq: 0–1 mm → 100%, 2 mm → 76%, 3 mm → 23%, 4 mm → 3.3%), not a guessed curve.
+- **Cross-family** — nucleases (mismatch-calibrated risk + the real CRISOT score), serine integrases (cryptic
+  **pseudo-attB** scan on the real documented Bxb1 attB core), bridge recombinases (the existing Perry-DMS engine).
+  Bridge/integrase off-target is **honestly flagged data-thin** — there is no published genome-wide unbiased assay
+  or predictor for bridge recombinases (verified).
+- **Surfaces** — REST `POST /offtarget`, MCP `offtarget_scan`, manifest `nominate_offtargets`, and an Off-Target
+  web page. Abstains without inputs; never fabricates sites.
+
 ## What is new in v6.9 — PEN-IMMUNE (MHC-II/CD4 + ADA + the writer enzyme as a distinct antigen)
 
 The immune profile did **CD8/MHC-I only** (capsid epitope load via MHCflurry) — but the **dominant** immunogenicity

{pen_stack-6.9.2 → pen_stack-6.10.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.9.2-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.10.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)
@@ -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.10 — PEN-OFFTGT (cross-writer-family off-target nomination)
+
+Off-target prediction was a single-family bridge pseudosite scan that abstained for nucleases and integrases.
+v6.10 makes it a **cross-writer-family, chromatin-aware NOMINATION engine** — completing the safety triad
+(site + writer + off-target). It is scrupulously honest that **nomination is not a clearance**: every candidate
+ships with the empirical assay that would confirm it.
+
+- **A real, validated benchmark** (`benchmarks/offtarget/`) over canonical Cas9 guides with **experimentally
+  validated off-targets** from GUIDE-seq (Tsai 2015) and CIRCLE-seq (Tsai 2017). The licensed **CRISOT** predictor
+  (Chen et al. *Nat Commun* 2023) **beats the sequence-homology baseline** on held-out guides — GUIDE-seq AUPRC
+  **0.65 vs 0.47**, CIRCLE-seq **0.52 vs 0.27**; per-guide bootstrap CI excludes 0 on both. CRISOT is CC-BY-NC and
+  runs only on the VM — only derived scores are cached (like the licensed MHC tools).
+- **Grounded, calibrated risk** — the risk band IS the real-data fraction of candidates at *k* mismatches that were
+  experimentally validated-active (GUIDE-seq: 0–1 mm → 100%, 2 mm → 76%, 3 mm → 23%, 4 mm → 3.3%), not a guessed curve.
+- **Cross-family** — nucleases (mismatch-calibrated risk + the real CRISOT score), serine integrases (cryptic
+  **pseudo-attB** scan on the real documented Bxb1 attB core), bridge recombinases (the existing Perry-DMS engine).
+  Bridge/integrase off-target is **honestly flagged data-thin** — there is no published genome-wide unbiased assay
+  or predictor for bridge recombinases (verified).
+- **Surfaces** — REST `POST /offtarget`, MCP `offtarget_scan`, manifest `nominate_offtargets`, and an Off-Target
+  web page. Abstains without inputs; never fabricates sites.
+
 ## What is new in v6.9 — PEN-IMMUNE (MHC-II/CD4 + ADA + the writer enzyme as a distinct antigen)
 
 The immune profile did **CD8/MHC-I only** (capsid epitope load via MHCflurry) — but the **dominant** immunogenicity

pen_stack-6.10.0/benchmarks/offtarget/SHA256SUMS

@@ -0,0 +1,4 @@
+9a02d9fc0fb4fe305fc87510114df892027ac85f24a495bddccaf1c29e8decf7  split.json
+006642247dbb3dfe5ebefd0a9f0144e9e9d26b682e7b9173d13e2c4e1252bec8  offtarget_bench_fixture.csv
+6ec099c0d30f83bd09f7182c4f365ee7b1106e45f4ca80db46f4fdb0df2941ba  offtarget_bench_metrics.json
+626d383ab3a494d6899c1620fa7cb2e6626c055410c1fd57e6b7d57d308523f4  offtarget_calibration.json

{pen_stack-6.9.2 → pen_stack-6.10.0}/configs/oracles/scope_cards.yaml

@@ -139,6 +139,23 @@ oracles:
     generalizes_to_unseen_loci: false
     license: "open (this work; MHCflurry 10.1016/j.cels.2020.06.010, HLA-I supertypes 10.1186/1471-2172-9-1)"
 
+  offtarget_nomination:         # v6.10 WS-OFFTARGET: cross-family off-target NOMINATION (not clearance)
+    family: genome
+    version: "crisot+homology-2026"
+    output_kind: baseline       # ranks/risk-bands CANDIDATE sites, not generative
+    valid_for: "RELATIVE off-target NOMINATION for a writer: rank candidate sites so validated off-targets
+      surface first, with a mismatch-CALIBRATED empirical risk band (real GUIDE-seq/CIRCLE-seq active fractions).
+      Nucleases use the real CRISOT-Score (beats a homology baseline on held-out guides, CI excludes 0); serine
+      integrases use a documented pseudo-attB cryptic scan; bridge recombinases delegate to the Perry-DMS engine"
+    not_valid_for: "a safety CLEARANCE (nomination != validation; every result ships with the empirical assay
+      that would confirm it); genome-wide candidate ENUMERATION (needs the on-VM Cas-OFFinder/genome scan; this
+      engine SCORES supplied candidates); a per-site cleavage/recombination PROBABILITY; bridge-recombinase
+      off-target magnitude (NO published genome-wide unbiased assay/predictor exists -> extrapolative/abstains);
+      structural variants/translocations beyond nominated sites"
+    generalizes_to_unseen_loci: false
+    license: "open (this work; GUIDE-seq 10.1038/nbt.3117, CIRCLE-seq 10.1038/nmeth.4278, CHANGE-seq
+      10.1038/s41587-020-0555-7, CRISOT 10.1038/s41467-023-42695-4 CC-BY-NC run on the VM only)"
+
   innate_sensing:               # v5.4 WS-INNATE: computed nucleic-acid innate-sensing motif load
     family: genome
     version: "cpg-oe+dsrna-2026"

pen_stack-6.10.0/docs/cards/offtarget_data.md

@@ -0,0 +1,52 @@
+# Data card — Off-Target-Bench (v6.10 PEN-OFFTGT)
+
+## Summary
+A real, leakage-controlled benchmark for cross-writer-family off-target **nomination**: given a guide and its
+candidate sites, rank the candidates so the experimentally validated off-targets surface first. Labels are the
+wet-lab assay calls (NON-circular — the label is the experiment, not a predictor).
+
+## Ground truth (independently verified 2026-06-19)
+| Assay | Setting | Citation | DOI |
+|---|---|---|---|
+| GUIDE-seq | cell-based, unbiased, genome-wide | Tsai et al., *Nat Biotechnol* 2015 | `10.1038/nbt.3117` |
+| CIRCLE-seq | in vitro (cell-free), unbiased | Tsai et al., *Nat Methods* 2017 | `10.1038/nmeth.4278` |
+
+Canonical Cas9 guides: **EMX1, VEGFA site 1/2/3, FANCF, HEK293 site 2/3/4**. The harmonized candidate/label tables
+are sourced from the CRISOT data release (Zenodo `10.5281/zenodo.8420032`), which redistributes the public assay
+supplements; PEN-STACK cites the **original assay papers** as the ground-truth provenance.
+
+## Learned predictor (real tool, VM-only)
+**CRISOT-Score** — Chen et al., *Nat Commun* 2023, `10.1038/s41467-023-42695-4`; an XGBoost RNA-DNA interaction
+fingerprint. **License: CC-BY-NC** → it runs only on the VM (`crisot:tools` Docker, `xgboost`/`pandas`/`numpy`);
+its weights are NEVER redistributed. Only DERIVED scores are cached/committed (CI-safe), exactly like the licensed
+NetMHC tools.
+
+## Baseline (pre-registered)
+Sequence-homology nomination = ascending **mismatch count** (Hamming over the 20-nt protospacer).
+
+## Result (E-G2, full real data, on the VM)
+| Assay | CRISOT AUPRC | homology AUPRC | gap | 95% CI (held-out-guide bootstrap) | beats homology |
+|---|---|---|---|---|---|
+| GUIDE-seq | 0.646 | 0.467 | +0.179 | [0.015, 0.340] | ✅ |
+| CIRCLE-seq | 0.520 | 0.266 | +0.253 | [0.140, 0.361] | ✅ |
+
+The learned predictor beats the homology baseline on both assays (per-guide bootstrap CI excludes 0).
+
+## Risk calibration (grounded)
+The nomination risk band IS the empirical fraction of candidates at *k* mismatches that were validated-active
+(full real data): GUIDE-seq 0–1 mm → 1.00, 2 mm → 0.765, 3 mm → 0.231, 4 mm → 0.033, 5 mm → 0.0028, 6 mm → 0.00014.
+Mismatch counts outside the calibrated range abstain rather than extrapolate.
+
+## Files
+- `benchmarks/offtarget/offtarget_bench_fixture.csv` — real validated off-targets + cached CRISOT scores (CI-safe;
+  inactives downsampled with a fixed seed for a small committed file).
+- `benchmarks/offtarget/offtarget_bench_metrics.json` — the AUTHORITATIVE full-data metrics.
+- `benchmarks/offtarget/offtarget_calibration.json` — the full-data mismatch / CRISOT-decile calibration.
+- `benchmarks/offtarget/split.json`, `SHA256SUMS` — split definition + checksums.
+
+## Honest limits
+Nomination is **not** a clearance — every result ships with the empirical assay that would confirm it. Genome-wide
+candidate ENUMERATION needs the on-VM Cas-OFFinder/genome scan; this benchmark covers SCORING + RANKING of supplied
+candidates. Bridge/integrase off-target is data-thin: there is **no published genome-wide unbiased off-target assay
+or predictor for bridge recombinases** (verified), and the large-serine-integrase assays (Cryptic-seq/HIDE-seq) and
+predictor (IntQuery) are recent single-company preprints with no public weights.

pen_stack-6.10.0/docs/offtarget.md

@@ -0,0 +1,45 @@
+# Stage E — the off-target nomination engine (v6.10 PEN-OFFTGT)
+
+Stage E completes the **safety triad** — site (Stage B) + writer (Stage C) + **off-target** (Stage E) — by turning
+off-target from a single-family bridge pseudosite scan into a **cross-writer-family, chromatin-aware NOMINATION
+engine** with a real-data-calibrated risk band. The cardinal honesty invariant: **nomination is not a clearance.**
+A nominated off-target is a candidate, and every result ships with the empirical assay that would confirm it.
+
+## The engine (`pen_stack/wgenome/offtarget_predict.py`)
+
+`nominate_offtargets(writer_family, ...)` dispatches by writer family:
+
+- **Nuclease (Cas9):** given a guide + candidate sites (e.g. from a Cas-OFFinder scan), each candidate gets a
+  **mismatch-calibrated empirical risk** (the real GUIDE-seq/CIRCLE-seq active fraction at *k* mismatches — not a
+  guessed curve), the **real CRISOT-Score** when the (guide, site) is in the cached bench, and a documented
+  **chromatin modifier** (open chromatin raises realized off-target activity; Lazzarotto 2020, CHANGE-seq).
+- **Serine integrase (Bxb1):** a cryptic **pseudo-attB** scan that seeds on the *real documented* Bxb1 attB core
+  (`GCGGTCTC`, central GT; FlyBase FBto0000359, Ghosh 2003) and reports candidate cryptic sites by arm mismatches.
+- **Bridge recombinase:** delegates to the existing Perry-DMS pseudosite engine (`pen_stack.bridge.offtarget`).
+
+The engine **abstains without inputs** (no candidate sites → no fabricated sites) and is explicit that genome-wide
+candidate ENUMERATION needs the on-VM scan; this engine SCORES + RANKS + risk-bands supplied candidates.
+
+## The benchmark (E-G2, real data + real tool)
+
+`benchmarks/offtarget/` is a held-out-guide nomination benchmark over canonical Cas9 guides with **experimentally
+validated off-targets** (GUIDE-seq, CIRCLE-seq). The licensed **CRISOT** predictor (CC-BY-NC, run on the VM) beats
+the sequence-homology baseline on both assays — GUIDE-seq AUPRC **0.65 vs 0.47**, CIRCLE-seq **0.52 vs 0.27**, with
+the per-guide bootstrap CI on the gap excluding 0. Only derived CRISOT scores are cached/committed; the weights are
+never redistributed. See `docs/cards/offtarget_data.md` for full provenance.
+
+## Validation-assay recommendation (`pen_stack/wgenome/offtarget_assay.py`)
+
+`recommend_assay(writer_family)` maps a writer to the empirical assay(s) that would confirm a nomination —
+GUIDE/CHANGE/CIRCLE-seq for nucleases, Cryptic-seq/HIDE-seq for serine integrases — and is **honest about the gap**
+for bridge recombinases: there is no published genome-wide unbiased off-target assay or predictor for them, so their
+nominations are flagged extrapolative and routed to targeted confirmation, never read as a clearance.
+
+## Surfaces
+REST `POST /offtarget` + `GET /offtarget/assay`, MCP `offtarget_scan`, manifest tool `nominate_offtargets`
+(`fabricates: false`), the `offtarget_nomination` scope card, and the **Off-Target** web page.
+
+## Honest limits
+Nomination ≠ validation. Bridge/integrase off-target is data-thin/unmodeled (verified) and flagged extrapolative.
+Chromatin-awareness depends on target-cell-type data. Translocations/structural variants beyond nominated sites are
+out of scope. The CRISOT learned predictor is CC-BY-NC and runs only on the VM; PEN-STACK ships only derived scores.

{pen_stack-6.9.2 → pen_stack-6.10.0}/pen_stack/__init__.py

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

{pen_stack-6.9.2 → pen_stack-6.10.0}/pen_stack/agent/cite.py

@@ -39,6 +39,19 @@ def curated_dois() -> frozenset[str]:
     # v5.4 computed innate-sensing provenance (CpG-TLR9 / AAV CpG-depletion / RNA modification)
     from pen_stack.planner.innate_sensing import PROVENANCE_DOIS as _innate_dois
     dois.update(_innate_dois)
+    # v6.10 off-target nomination provenance (GUIDE/CIRCLE/CHANGE/SITE-seq assays + CRISOT predictor + LSI assays)
+    try:
+        from pen_stack.wgenome.offtarget_data import (
+            ASSAY_PROVENANCE,
+            INTEGRASE_ASSAY_PROVENANCE,
+            PREDICTOR_PROVENANCE,
+        )
+        for _src in (ASSAY_PROVENANCE, PREDICTOR_PROVENANCE, INTEGRASE_ASSAY_PROVENANCE):
+            for _rec in _src.values():
+                if _rec.get("doi"):
+                    dois.add(_rec["doi"])
+    except Exception:  # noqa: BLE001
+        pass
     # v5.5 anti-vector seroprevalence provenance (serosurveys)
     try:
         sp = yaml.safe_load(resource("configs/seroprevalence.yaml").read_text(encoding="utf-8"))

{pen_stack-6.9.2 → pen_stack-6.10.0}/pen_stack/agent/mcp_server.py

@@ -91,6 +91,18 @@ def immune_profile(design: dict) -> dict:
     return _ip(design)
 
 
+@mcp.tool()
+def offtarget_scan(writer_family: str, guide: str | None = None, candidate_sites: list | None = None,
+                   sequence: str | None = None, assay: str = "guideseq") -> dict:
+    """v6.10 PEN-OFFTGT cross-family off-target NOMINATION (NOT a clearance). Ranks candidate sites with a
+    real-data mismatch-calibrated risk band + the real CRISOT learned score (nuclease), a pseudo-attB scan
+    (integrase), or the Perry-DMS pseudosite engine (bridge); ships the validation assay that would confirm
+    each candidate. Abstains without inputs; never fabricates sites."""
+    from pen_stack.wgenome.offtarget_predict import nominate_offtargets
+    return nominate_offtargets(writer_family, guide=guide, candidate_sites=candidate_sites,
+                               sequence=sequence, assay=assay)
+
+
 @mcp.tool()
 def generate_designs(goal: dict | None = None, candidates: list | None = None, keep: int = 25) -> dict:
     """v5.8 generative designer (verifier-as-discriminator): hazardous/illegal candidates are DISCARDED;

{pen_stack-6.9.2 → pen_stack-6.10.0}/pen_stack/api/manifest.py

@@ -46,6 +46,12 @@ _TOOLS = [
      "efficiency w/ conformal interval + auto-designed guide/att (v6.8 PEN-WRITER)",
      "input": "write request (write-type, cargo, cell type, optional target/donor seq)", "output": "WriterRanking",
      "entrypoint": "pen_stack.atlas.writer_recommend.recommend_writers", "fabricates": False},
+    {"name": "nominate_offtargets", "summary": "cross-writer-family off-target NOMINATION: rank candidate sites "
+     "with a real-data mismatch-calibrated risk band + the real CRISOT learned score (nuclease), pseudo-attB "
+     "scan (integrase), Perry-DMS pseudosite engine (bridge); nomination is NOT a clearance (v6.10 PEN-OFFTGT)",
+     "input": "writer family + guide/candidate sites (nuclease) or locus sequence (integrase)",
+     "output": "ranked off-target candidates + calibrated risk + recommended validation assay",
+     "entrypoint": "pen_stack.wgenome.offtarget_predict.nominate_offtargets", "fabricates": False},
 ]
 
 _POLICY = ("outputs outside scope are returned as `out_of_scope` (known-unknown) or `extrapolating` (OOD) and are "

{pen_stack-6.9.2 → pen_stack-6.10.0}/pen_stack/server/api.py

@@ -208,6 +208,26 @@ def immune_endpoint(design: dict):
     return immune_profile(design)
 
 
+@app.post("/offtarget", tags=["v6.10 off-target"])
+def offtarget_endpoint(req: dict):
+    """v6.10 PEN-OFFTGT cross-family off-target NOMINATION (NOT a clearance). Body:
+    {writer_family, guide?, candidate_sites?, sequence?, accessibility?, assay?}. Returns ranked candidate
+    off-targets with a real-data mismatch-calibrated risk band + the recommended validation assay; abstains
+    without inputs and never fabricates sites."""
+    from pen_stack.wgenome.offtarget_predict import nominate_offtargets
+    return nominate_offtargets(
+        req.get("writer_family", ""), guide=req.get("guide"), candidate_sites=req.get("candidate_sites"),
+        sequence=req.get("sequence"), accessibility=req.get("accessibility"),
+        target_core=req.get("target_core"), assay=req.get("assay", "guideseq"))
+
+
+@app.get("/offtarget/assay", tags=["v6.10 off-target"])
+def offtarget_assay_endpoint(writer_family: str):
+    """v6.10 validation-assay recommendation for a writer family (the assay that would confirm a nomination)."""
+    from pen_stack.wgenome.offtarget_assay import recommend_assay
+    return recommend_assay(writer_family)
+
+
 @app.post("/generate", tags=["v6.1 AI surface"])
 def generate_endpoint(req: dict):
     """v5.8 generative designer: verifier-as-discriminator. Body: {goal?, candidates?, keep?}. Hazardous/illegal

pen_stack-6.10.0/pen_stack/wgenome/offtarget_assay.py

@@ -0,0 +1,55 @@
+"""Validation-assay recommender for off-target nomination (v6.10 PEN-OFFTGT, E-WS3).
+
+Nomination is NOT a clearance — it ships with the empirical assay that would CONFIRM the candidates. This maps a
+writer family to the appropriate unbiased genome-wide assay(s) + their documented applicability, grounded in the
+validated assay literature. For families with no published genome-wide off-target assay (bridge recombinases) it
+says so honestly and recommends targeted confirmation, never implying a clearance exists.
+"""
+from __future__ import annotations
+
+# assay applicability by writer family (validated citations in offtarget_data.ASSAY_PROVENANCE)
+_NUCLEASE_ASSAYS = [
+    {"assay": "GUIDE-seq", "setting": "cell-based (in cellulo)", "doi": "10.1038/nbt.3117",
+     "use": "captures off-targets in the actual chromatin/cell context (dsODN tag at DSBs)"},
+    {"assay": "CHANGE-seq", "setting": "in vitro, high-throughput", "doi": "10.1038/s41587-020-0555-7",
+     "use": "most sensitive genome-wide nomination; pair with a cell-based assay to filter chromatin-masked sites"},
+    {"assay": "CIRCLE-seq", "setting": "in vitro (cell-free)", "doi": "10.1038/nmeth.4278",
+     "use": "highly sensitive in vitro confirmation; over-nominates vs cell context"},
+]
+
+
+def recommend_assay(writer_family: str) -> dict:
+    """Recommend the empirical validation assay(s) for a writer family + the documented expected sensitivity, or
+    an honest 'no genome-wide assay exists' for data-thin families. Always frames nomination as not a clearance."""
+    fam = (writer_family or "").lower()
+    if "cas9" in fam or "nuclease" in fam or fam in {"spcas9", "sacas9", "cas12a", "ascas12a", "nickase"}:
+        return {"family": writer_family, "writer_class": "RNA-guided nuclease (DSB)",
+                "recommended": _NUCLEASE_ASSAYS,
+                "strategy": "nominate in vitro (CHANGE-/CIRCLE-seq, high sensitivity) THEN confirm the survivors "
+                            "in the target cell type (GUIDE-seq) — chromatin masks a fraction of in vitro sites",
+                "available": True,
+                "note": "nomination ranks CANDIDATES; an empirical assay is required for clearance."}
+    if "integrase" in fam or "paste" in fam or "passige" in fam or "bxb1" in fam or "phic31" in fam:
+        return {"family": writer_family, "writer_class": "large serine integrase",
+                "recommended": [{"assay": "Cryptic-seq / HIDE-seq", "setting": "unbiased LSI off-target discovery",
+                                 "doi": "10.1101/2024.08.23.609471",
+                                 "use": "the genome-wide unbiased assay for serine-integrase cryptic attB sites "
+                                        "(Tome Biosciences, 2024 preprint)"}],
+                "strategy": "scan cryptic pseudo-attB (this engine) THEN confirm by Cryptic-seq/HIDE-seq; "
+                            "quantitative prediction (IntQuery) is paper-only (no public weights)",
+                "available": True,
+                "note": "LSI off-target assays are recent preprints; coverage is single-company / largely Bxb1."}
+    if "bridge" in fam or "is110" in fam or "is621" in fam or "seek" in fam or "iscro4" in fam:
+        return {"family": writer_family, "writer_class": "bridge recombinase (IS110/IS621 RNA-guided)",
+                "recommended": [{"assay": "targeted amplicon / capture sequencing at nominated pseudosites",
+                                 "setting": "targeted", "doi": None,
+                                 "use": "confirm individual nominated pseudosites (no genome-wide unbiased "
+                                        "off-target assay exists for bridge recombinases yet)"}],
+                "strategy": "nominate pseudosites with the Perry-DMS engine THEN confirm by targeted sequencing; "
+                            "an unbiased genome-wide bridge off-target assay is an open need",
+                "available": True,
+                "note": "HONEST GAP: bridge-recombinase off-target is essentially unmodeled — there is NO "
+                        "published genome-wide unbiased assay or predictor (verified). Treat nominations as "
+                        "high-uncertainty / extrapolative; do not read as clearance."}
+    return {"family": writer_family, "available": False,
+            "note": f"no off-target assay applicability rule for family {writer_family!r}"}

pen_stack-6.10.0/pen_stack/wgenome/offtarget_data.py

@@ -0,0 +1,100 @@
+"""Off-target ground-truth + provenance for the cross-family nomination engine (v6.10 PEN-OFFTGT, E-WS1).
+
+The ground truth is harmonized, PUBLISHED, unbiased genome-wide off-target assays over canonical Cas9 guides;
+the derived risk calibration and the Off-Target-Bench headline (the REAL CRISOT predictor vs the homology
+baseline) are embedded in-code so the axis is available everywhere (CI / bare install / live app), while the
+full sealed fixture + per-guide metrics live under ``benchmarks/offtarget/`` for the bench harness.
+
+LICENSING / HONESTY: the CRISOT predictor (Chen et al., Nat Commun 2023) is CC-BY-NC and runs ONLY on the VM —
+its binaries/weights are NEVER redistributed; only DERIVED scores are cached (exactly like the licensed MHC
+tools). Off-target SITE sequences are facts from the public assay supplements (cited below). A nominated
+off-target is a CANDIDATE, never a claim.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+# ---- validated assay provenance (independently verified 2026-06-19) -----------------------------
+ASSAY_PROVENANCE = {
+    "guideseq": {"name": "GUIDE-seq", "kind": "cell-based, unbiased, genome-wide",
+                 "citation": "Tsai et al., Nat Biotechnol 2015", "doi": "10.1038/nbt.3117"},
+    "circleseq": {"name": "CIRCLE-seq", "kind": "in vitro (cell-free), unbiased, genome-wide",
+                  "citation": "Tsai et al., Nat Methods 2017", "doi": "10.1038/nmeth.4278"},
+    "changeseq": {"name": "CHANGE-seq", "kind": "in vitro, unbiased, high-throughput (110 sgRNAs)",
+                  "citation": "Lazzarotto et al., Nat Biotechnol 2020", "doi": "10.1038/s41587-020-0555-7"},
+    "siteseq": {"name": "SITE-seq", "kind": "in vitro biochemical, unbiased",
+                "citation": "Cameron et al., Nat Methods 2017", "doi": "10.1038/nmeth.4284"},
+}
+PREDICTOR_PROVENANCE = {
+    "crisot": {"name": "CRISOT-Score", "approach": "XGBoost RNA-DNA interaction fingerprint",
+               "citation": "Chen et al., Nat Commun 2023", "doi": "10.1038/s41467-023-42695-4",
+               "license": "CC-BY-NC (run on the VM; only derived scores cached, weights never redistributed)"},
+}
+# integrase off-target assays (large serine integrases) — for the assay recommender; data-thin, preprints
+INTEGRASE_ASSAY_PROVENANCE = {
+    "cryptic_seq": {"name": "Cryptic-seq / HIDE-seq", "kind": "unbiased LSI off-target discovery",
+                    "citation": "Hazelbaker et al. (Tome Biosciences), bioRxiv 2024",
+                    "doi": "10.1101/2024.08.23.609471"},
+    "intquery": {"name": "IntQuery", "kind": "LSI off-target deep-learning predictor (paper-only, no public weights)",
+                 "citation": "Bakalar et al. (Tome Biosciences), bioRxiv 2024", "doi": "10.1101/2024.10.10.617699"},
+}
+
+# canonical Cas9 guides present in the bench (20-nt protospacers; Tsai 2015/2017)
+CANONICAL_GUIDES = {
+    "EMX1": "GAGTCCGAGCAGAAGAAGAA", "VEGFA_site1": "GGGTGGGGGGAGTTTGCTCC",
+    "VEGFA_site2": "GACCCCCTCCACCCCGCCTC", "VEGFA_site3": "GGTGAGTGAGTGTGTGCGTG",
+    "FANCF": "GGAATCCCTTCTGCAGCACC", "HEK293_site2": "GAACACAAAGCATAGACTGC",
+    "HEK293_site3": "GGCCCAGACTGAGCACGTGA", "HEK293_site4": "GGCACTGCGGCTGGAGGTGG",
+}
+
+# ---- DERIVED, real-data risk calibration: empirical active fraction by mismatch count -----------
+# (computed on the VM over ALL canonical-guide candidates; the off-target nomination risk band is grounded
+# in how often a candidate at k mismatches was actually validated-active, not a guessed curve.)
+MISMATCH_ACTIVE_FRACTION = {
+    "guideseq": {0: 1.0, 1: 1.0, 2: 0.76471, 3: 0.23129, 4: 0.033, 5: 0.00276, 6: 0.00014},
+    "circleseq": {0: 1.0, 1: 1.0, 2: 1.0, 3: 0.67146, 4: 0.26566, 5: 0.05924, 6: 0.00985},
+}
+
+# ---- Off-Target-Bench headline (REAL full-data result; per-guide AUPRC, held-out-guide bootstrap CI) -----
+BENCH_SUMMARY = {
+    "guideseq": {"n_guides": 8, "crisot_auprc": 0.6458, "homology_auprc": 0.4668,
+                 "auprc_gap": 0.179, "gap_ci95": [0.0154, 0.3396], "crisot_beats_homology": True},
+    "circleseq": {"n_guides": 8, "crisot_auprc": 0.5197, "homology_auprc": 0.2664,
+                  "auprc_gap": 0.2533, "gap_ci95": [0.1404, 0.3608], "crisot_beats_homology": True},
+    "metric": "per-guide AUPRC; baseline = ascending mismatch count; learned = real CRISOT-Score (VM, cached)",
+}
+
+
+def assay_provenance() -> dict:
+    """Validated provenance for every assay + predictor the off-target engine is grounded on."""
+    return {"nuclease_assays": ASSAY_PROVENANCE, "nuclease_predictor": PREDICTOR_PROVENANCE,
+            "integrase_assays": INTEGRASE_ASSAY_PROVENANCE}
+
+
+@lru_cache(maxsize=1)
+def bench_records() -> list[dict]:
+    """The committed Off-Target-Bench fixture (real validated off-targets + cached CRISOT scores) as a list of
+    dicts, or [] when the data tree is absent (bare wheel). Columns: assay, guide, On, Off, mismatch, active,
+    crisot_score."""
+    try:
+        import csv
+
+        from pen_stack._resources import resource
+        path = resource("benchmarks/offtarget/offtarget_bench_fixture.csv")
+        with open(path, encoding="utf-8") as fh:
+            rows = list(csv.DictReader(fh))
+        for r in rows:
+            r["mismatch"] = int(r["mismatch"])
+            r["active"] = int(r["active"])
+            r["crisot_score"] = float(r["crisot_score"])
+        return rows
+    except Exception:  # noqa: BLE001  (bare wheel / no data tree -> the bench harness is checkout-only)
+        return []
+
+
+def calibrated_active_fraction(n_mismatch: int, assay: str = "guideseq") -> float | None:
+    """The empirical fraction of candidate sites at ``n_mismatch`` mismatches that were validated-active in the
+    named assay (grounded risk). None if the mismatch count is outside the calibrated range (then the axis
+    abstains rather than extrapolating)."""
+    table = MISMATCH_ACTIVE_FRACTION.get(assay, MISMATCH_ACTIVE_FRACTION["guideseq"])
+    return table.get(int(n_mismatch))