pen-stack 6.8.0__tar.gz → 6.9.0__tar.gz

{pen_stack-6.8.0 → pen_stack-6.9.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.9.0] - 2026-06-20 - PEN-IMMUNE: MHC-II/CD4 + ADA + writer-as-antigen
+
+**MINOR feature release.** Extends the immune profile from CD8/MHC-I-only to a full T-cell profile — MHC-I +
+**MHC-II/CD4 + ADA risk with self-tolerance filtering** — scored over the **writer enzyme as a distinct antigen**,
+still population-level, OOD-gated, and **never collapsed**. Wraps the v5.6 unified profile. No fabrication: real
+UniProt sequences, grounded documented method, honest 🟡 labels.
+
+### Added — the MHC-II + ADA axes (WS-IMMUNE2: G-WS1, G-WS2)
+- `pen_stack/planner/immune_mhc2.py` — grounded, dependency-free **promiscuous MHC-II binder density** (documented
+  P1 hydrophobic anchor, Stern & Wiley 1994; secondary pockets, Southwood 1998) over capsid AND writer sequences +
+  the bundled real writer/control FASTA. `configs/writer_sequences.fasta` — real UniProt: SpCas9 (Q99ZW2), ISCro4
+  bridge recombinase (D2TGM5), Bxb1 integrase (Q9B086), human albumin self control (P02768).
+- `pen_stack/planner/ada_risk.py` — **ADA-risk = MHC-II epitope density × foreignness** with a JanusMatrix-style
+  **self-tolerance filter** (origin authoritative; human-proteome k-mer filter otherwise). Recovers
+  immunogenic-vs-tolerated: foreign writers score above the human self control (clean separation).
+
+### Changed — the unified profile (G-WS3)
+- `pen_stack/planner/immune_profile.py` — adds `mhc2_writer` + `ada_writer` axes and a `writer_as_antigen` card
+  with `dominant_antigen` + `writer_dominant_risk` (fires for a foreign writer, especially non-viral delivery
+  where there is no capsid antigen). `collapsed_score` stays `None` (asserted). `immune_calibration.AXIS_STATUS`
+  registers the two new axes as mechanistic/population proxies.
+
+### Added — Immuno-Bench + honest calibration (G-WS4)
+- `benchmarks/immuno/harness.py` — the immunogenic-vs-tolerated recovery track (non-circular: label = protein
+  origin) + an honest `calibrate_axis` ADA pass that **stays 🟡** at public-data power (no manufactured ✅).
+- `tests/unit/test_ws_immune2.py` (CI-safe; pure-Python method + committed sequences). `prereg/ws_immune2.yaml`.
+
+### Honesty
+- Every axis is a population-level proxy, never a patient-specific ADA titer / realized CD4 magnitude (known-
+  unknowns). The MHC-II method is sequence-intrinsic presentation potential, not a trained allele-specific predictor.
+  The self-tolerance k-mer filter is seeded by the bundled human reference (full human proteome substitutable on the
+  VM); the authoritative foreignness signal is the protein origin. Axes are a vector, never fused.
+
 ## [6.8.0] - 2026-06-20 - PEN-WRITER: cross-family writer-efficiency engine + Writer-Efficiency Bench
 
 **MINOR feature release.** Upgrades Stage C (pick the writer) from a curated-KB **ranking** to a prediction +

{pen_stack-6.8.0 → pen_stack-6.9.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.8.0
+version: 6.9.0
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.8.0 → pen_stack-6.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.8.0
+Version: 6.9.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.8.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.9.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,29 @@ 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.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
+driver is **MHC-II / CD4 help → anti-drug antibodies (ADA)**, and the **writer enzyme itself is immunogenic**
+(Cas9 elicits MHC-II-presented CD4 responses, Simhadri *Nat Commun* 2021; bridge recombinases / serine integrases
+are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that gap, **never collapsing** the axes:
+
+- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — a grounded, dependency-free **promiscuous MHC-II
+  binder density** over the documented P1 hydrophobic anchor (Stern & Wiley 1994) + secondary pockets, scored over
+  **capsid AND writer** sequences. Population-level proxy (🟡), never a patient-HLA magnitude.
+- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, with a
+  **self-tolerance filter** (JanusMatrix-style: self epitopes are tolerated; foreign drive ADA). It **recovers
+  immunogenic-vs-tolerated**: the foreign writers (real UniProt SpCas9 / ISCro4 / Bxb1) score **above** the human
+  self control (albumin), even without the origin label (the k-mer self-match tolerates the human protein).
+- **The writer as a distinct antigen** — the profile now carries a `writer_as_antigen` card and a
+  `writer_dominant_risk` flag: for **non-viral delivery of a bacterial writer there is no capsid antigen, so the
+  WRITER is the dominant immunogen** — the insight the capsid-only profile missed.
+- **Immuno-Bench** (`benchmarks/immuno/`) — the immunogenic-vs-tolerated recovery track + an honest `calibrate_axis`
+  ADA pass (it stays 🟡 at public-data power — no manufactured ✅, the standing wet-lab bottleneck).
+
+Real UniProt sequences only (no fabricated sequence); the axes are reported as a vector with `collapsed_score: None`;
+the realized CD4 response / ADA titer stay known-unknowns. See [docs/immune_profiler.md](docs/immune_profiler.md).
+
 ## What is new in v6.8 — PEN-WRITER (a cross-family writer-efficiency engine + the first writer-efficiency benchmark)
 
 Stage C (pick the writer) was **retrieval** — the curated Writer Atlas ranks 8 families but predicts no

{pen_stack-6.8.0 → pen_stack-6.9.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.8.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.9.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,29 @@ 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.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
+driver is **MHC-II / CD4 help → anti-drug antibodies (ADA)**, and the **writer enzyme itself is immunogenic**
+(Cas9 elicits MHC-II-presented CD4 responses, Simhadri *Nat Commun* 2021; bridge recombinases / serine integrases
+are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that gap, **never collapsing** the axes:
+
+- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — a grounded, dependency-free **promiscuous MHC-II
+  binder density** over the documented P1 hydrophobic anchor (Stern & Wiley 1994) + secondary pockets, scored over
+  **capsid AND writer** sequences. Population-level proxy (🟡), never a patient-HLA magnitude.
+- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, with a
+  **self-tolerance filter** (JanusMatrix-style: self epitopes are tolerated; foreign drive ADA). It **recovers
+  immunogenic-vs-tolerated**: the foreign writers (real UniProt SpCas9 / ISCro4 / Bxb1) score **above** the human
+  self control (albumin), even without the origin label (the k-mer self-match tolerates the human protein).
+- **The writer as a distinct antigen** — the profile now carries a `writer_as_antigen` card and a
+  `writer_dominant_risk` flag: for **non-viral delivery of a bacterial writer there is no capsid antigen, so the
+  WRITER is the dominant immunogen** — the insight the capsid-only profile missed.
+- **Immuno-Bench** (`benchmarks/immuno/`) — the immunogenic-vs-tolerated recovery track + an honest `calibrate_axis`
+  ADA pass (it stays 🟡 at public-data power — no manufactured ✅, the standing wet-lab bottleneck).
+
+Real UniProt sequences only (no fabricated sequence); the axes are reported as a vector with `collapsed_score: None`;
+the realized CD4 response / ADA titer stay known-unknowns. See [docs/immune_profiler.md](docs/immune_profiler.md).
+
 ## What is new in v6.8 — PEN-WRITER (a cross-family writer-efficiency engine + the first writer-efficiency benchmark)
 
 Stage C (pick the writer) was **retrieval** — the curated Writer Atlas ranks 8 families but predicts no

pen_stack-6.9.0/configs/writer_sequences.fasta

@@ -0,0 +1,12 @@
+# Writer-enzyme + control protein sequences for the v6.9 writer-as-antigen immunogenicity profiler (Stage G).
+# Real UniProt sequences, verbatim, each with its accession + ORIGIN (foreign | self). The writer enzymes are
+# bacterial/phage proteins (FOREIGN -> non-self -> ADA-driving); human albumin is the SELF/tolerated control.
+# Header convention: >NAME|ACCESSION origin=foreign|self family=... (DOIs/provenance in configs/immune_sequences.yaml)
+>SpCas9|Q99ZW2 origin=foreign family=Cas9 organism=S.pyogenes
+MDKKYSIGLDIGTNSVGWAVITDEYKVPSKKFKVLGNTDRHSIKKNLIGALLFDSGETAEATRLKRTARRRYTRRKNRICYLQEIFSNEMAKVDDSFFHRLEESFLVEEDKKHERHPIFGNIVDEVAYHEKYPTIYHLRKKLVDSTDKADLRLIYLALAHMIKFRGHFLIEGDLNPDNSDVDKLFIQLVQTYNQLFEENPINASGVDAKAILSARLSKSRRLENLIAQLPGEKKNGLFGNLIALSLGLTPNFKSNFDLAEDAKLQLSKDTYDDDLDNLLAQIGDQYADLFLAAKNLSDAILLSDILRVNTEITKAPLSASMIKRYDEHHQDLTLLKALVRQQLPEKYKEIFFDQSKNGYAGYIDGGASQEEFYKFIKPILEKMDGTEELLVKLNREDLLRKQRTFDNGSIPHQIHLGELHAILRRQEDFYPFLKDNREKIEKILTFRIPYYVGPLARGNSRFAWMTRKSEETITPWNFEEVVDKGASAQSFIERMTNFDKNLPNEKVLPKHSLLYEYFTVYNELTKVKYVTEGMRKPAFLSGEQKKAIVDLLFKTNRKVTVKQLKEDYFKKIECFDSVEISGVEDRFNASLGTYHDLLKIIKDKDFLDNEENEDILEDIVLTLTLFEDREMIEERLKTYAHLFDDKVMKQLKRRRYTGWGRLSRKLINGIRDKQSGKTILDFLKSDGFANRNFMQLIHDDSLTFKEDIQKAQVSGQGDSLHEHIANLAGSPAIKKGILQTVKVVDELVKVMGRHKPENIVIEMARENQTTQKGQKNSRERMKRIEEGIKELGSQILKEHPVENTQLQNEKLYLYYLQNGRDMYVDQELDINRLSDYDVDHIVPQSFLKDDSIDNKVLTRSDKNRGKSDNVPSEEVVKKMKNYWRQLLNAKLITQRKFDNLTKAERGGLSELDKAGFIKRQLVETRQITKHVAQILDSRMNTKYDENDKLIREVKVITLKSKLVSDFRKDFQFYKVREINNYHHAHDAYLNAVVGTALIKKYPKLESEFVYGDYKVYDVRKMIAKSEQEIGKATAKYFFYSNIMNFFKTEITLANGEIRKRPLIETNGETGEIVWDKGRDFATVRKVLSMPQVNIVKKTEVQTGGFSKESILPKRNSDKLIARKKDWDPKKYGGFDSPTVAYSVLVVAKVEKGKSKKLKSVKELLGITIMERSSFEKNPIDFLEAKGYKEVKKDLIIKLPKYSLFELENGRKRMLASAGELQKGNELALPSKYVNFLYLASHYEKLKGSPEDNEQKQLFVEQHKHYLDEIIEQISEFSKRVILADANLDKVLSAYNKHRDKPIREQAENIIHLFTLTNLGAPAAFKYFDTTIDRKRYTSTKEVLDATLIHQSITGLYETRIDLSQLGGD
+>ISCro4|D2TGM5 origin=foreign family=bridge_IS110 organism=C.rodentium
+MEQELHFIGIDVSKAKLDVDVLRPDGRHRSKKFANTPKGHDELLRWLSGHRVAPAHICMEATSTYMEDVAAHLSDAGYTVSVINPALGKAFAQSEGLRSKTDAVDARMLAEFCRQKRPPAWEAPHPVERALRALVLRHQSLTDMHTQELNRLETAREVQRPSIDAHLLWLHAELKRIEKQIKDLTDDDPDMKHRRKLLESIPGIGEKTSAVLLAYTGLKERFTHARQFAAFAGLTPRRYESGSSVNRASRMSKAGHASLRRALYMPAMVAVSKTEWGRAFRDRLAGNGKKGKVIIGAMMRKLAQVAYGVLKSGVPFDASRHNPVAA
+>Bxb1|Q9B086 origin=foreign family=serine_integrase organism=phage_Bxb1
+MRALVVIRLSRVTDATTSPERQLESCQQLCAQRGWDVVGVAEDLDVSGAVDPFDRKRRPNLARWLAFEEQPFDVIVAYRVDRLTRSIRHLQQLVHWAEDHKKLVVSATEAHFDTTTPFAAVVIALMGTVAQMELEAIKERNRSAAHFNIRAGKYRGSLPPWGYLPTRVDGEWRLVPDPVQRERILEVYHRVVDNHEPLHLVAHDLNRRGVLSPKDYFAQLQGREPQGREWSATALKRSMISEAMLGYATLNGKTVRDDDGAPLVRAEPILTREQLEALRAELVKTSRAKPAVSTPSLLLRVLFCAVCGEPAYKFAGGGRKHPRYRCRSMGFPKHCGNGTVAMAEWDAFCEEQVLDLLGDAAERLEKVWVAGSDSAVELAEVNAELVDLTSLIGSPAYRAGSPQREALDARIAALAARQEELEGLEARPSGWEWRETGQRFGDWWREQDTAAKNTWLRSMNVRLTFDVRGGLTRTIDFGDLQEYEQHLRLGSVVERLHTGMS
+>HumanAlbumin|P02768 origin=self family=human_control organism=H.sapiens
+MKWVTFISLLFLFSSAYSRGVFRRDAHKSEVAHRFKDLGEENFKALVLIAFAQYLQQCPFEDHVKLVNEVTEFAKTCVADESAENCDKSLHTLFGDKLCTVATLRETYGEMADCCAKQEPERNECFLQHKDDNPNLPRLVRPEVDVMCTAFHDNEETFLKKYLYEIARRHPYFYAPELLFFAKRYKAAFTECCQAADKAACLLPKLDELRDEGKASSAKQRLKCASLQKFGERAFKAWAVARLSQRFPKAEFAEVSKLVTDLTKVHTECCHGDLLECADDRADLAKYICENQDSISSKLKECCEKPLLEKSHCIAEVENDEMPADLPSLAADFVESKDVCKNYAEAKDVFLGMFLYEYARRHPDYSVVLLLRLAKTYETTLEKCCAAADPHECYAKVFDEFKPLVEEPQNLIKQNCELFEQLGEYKFQNALLVRYTKKVPQVSTPTLVEVSRNLGKVGSKCCKHPEAKRMPCAEDYLSVVLNQLCVLHEKTPVSDRVTKCCTESLVNRRPCFSALEVDETYVPKEFNAETFTFHADICTLSEKERQIKKQTALVELVKHKPKATKEQLKAVMDDFAAFVEKCCKADDKETCFAEEGKKLVAASQAALGL

pen_stack-6.9.0/docs/immune_profiler.md

@@ -0,0 +1,53 @@
+# Stage G — the immune profiler (v6.9 PEN-IMMUNE)
+
+Stage G profiles a design's immunogenicity/toxicity across **separate, never-collapsed axes**. Through v6.8 the
+adaptive axis was **CD8/MHC-I only** (capsid epitope load via MHCflurry). v6.9 adds the **dominant** driver —
+**MHC-II/CD4 → ADA** — and scores the **writer enzyme as a distinct antigen**.
+
+## The MHC-II/CD4 axis (`planner/immune_mhc2.py`)
+
+A grounded, dependency-free **promiscuous MHC-II binder density**: MHC-II presents a 9-mer core in an open groove
+whose **P1 pocket is deep and hydrophobic** — the single dominant anchor (M/F/Y/W/L/I/V; Stern & Wiley, *Nature*
+1994), with secondary pockets at P4/P6/P9. A *promiscuous* epitope (binds many HLA-DR) has a strong P1 anchor +
+favorable secondaries (Southwood 1998). We count promiscuous-binder cores → an epitope-density proxy, computed over
+**capsid AND writer** sequences. It is a **population-level, sequence-intrinsic proxy (🟡)** — not a trained
+allele-specific predictor, not a patient-HLA magnitude (a known-unknown).
+
+## The ADA-risk axis + self-tolerance (`planner/ada_risk.py`)
+
+Epitope load is necessary but not sufficient — **self** proteins carry MHC-II epitopes yet are tolerated. So:
+
+```
+ADA-risk = MHC-II epitope density × foreignness
+```
+
+with a **self-tolerance filter** (JanusMatrix-style: an epitope whose core matches the human proteome is
+tolerated). `foreignness` uses the **authoritative protein origin** (self vs bacterial/viral/phage) when known,
+else `1 − self_match_fraction` from a human-proteome k-mer filter. This **recovers immunogenic-vs-tolerated**:
+
+| Protein (real UniProt) | origin | ADA-risk |
+|---|---|---|
+| Bxb1 integrase (Q9B086) | foreign | **0.095** |
+| SpCas9 (Q99ZW2) | foreign | **0.093** |
+| ISCro4 bridge recombinase (D2TGM5) | foreign | **0.082** |
+| Human albumin (P02768) | self | **0.0** (tolerated) |
+
+The human self control scores 0 **even without the origin label** — the k-mer self-match tolerates it. The foreign
+writers separate cleanly above it.
+
+## The writer as a distinct antigen
+
+`immune_profile` now carries a `writer_as_antigen` card and a `writer_dominant_risk` flag. The insight the
+capsid-only profile missed: **for non-viral delivery (LNP/mRNA, eVLP) of a bacterial writer there is no capsid
+antigen — so the WRITER is the dominant immunogen.** The flag fires accordingly; the axes are reported as a vector
+with `collapsed_score: None` (never fused).
+
+## Honest limits
+- Population-level proxies (🟡), never a patient-specific ADA titer / realized CD4 magnitude (known-unknowns).
+- The MHC-II method is presentation potential, not a trained allele-specific predictor.
+- The self-tolerance k-mer filter is seeded by the bundled human reference; the **full human proteome** is
+  substitutable on the VM (the authoritative foreignness signal is the protein origin).
+- The ADA axis's `calibrate_axis` pass **stays 🟡** — no public observed-incidence set at N≥6 power (the standing
+  wet-lab/clinical-data bottleneck), reported, never manufactured.
+
+See `benchmarks/immuno/` (Immuno-Bench) and `prereg/ws_immune2.yaml`.

{pen_stack-6.8.0 → pen_stack-6.9.0}/pen_stack/__init__.py

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

pen_stack-6.9.0/pen_stack/planner/ada_risk.py

@@ -0,0 +1,84 @@
+"""ADA-risk + self-tolerance filter (v6.9 PEN-IMMUNE, G-WS2).
+
+A protein's MHC-II epitope load (presentation potential) is necessary but not sufficient for anti-drug antibodies
+(ADA): **self** proteins carry MHC-II epitopes too, yet are tolerated (central tolerance deletes self-reactive T
+cells). What drives ADA is **non-self** (foreign) presentable epitopes. So:
+
+    ADA-risk  =  MHC-II epitope density  x  foreignness
+
+with a **self-tolerance filter** (JanusMatrix-style: an epitope whose core matches the human proteome is
+tolerated; EpiVax JanusMatrix, De Groot et al.). `foreignness` uses the AUTHORITATIVE protein origin (self vs
+bacterial/viral/phage) when known; otherwise it is `1 - self_match_fraction` from a human-proteome k-mer filter
+(seeded here by the bundled human self-reference; the FULL human proteome is substitutable on the VM via the build
+script). This recovers immunogenic (Cas9, bridge recombinase, serine integrase — all foreign) above tolerated
+(human self) — the immunogenic-vs-tolerated benchmark.
+
+Honest: a **population-level proxy (🟡)**, never a patient-specific ADA titer (a known-unknown). The calibration
+attempt against a public ADA set runs through the EXISTING `calibrate_axis` gate; it flips to ✅ only if the gate
+passes (it does not, at the public-data power available — reported, not manufactured).
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack.planner.immune_mhc2 import _clean, mhc2_binder_cores, mhc2_epitope_load, writer_sequences
+
+ADA_DOIS = ["10.1038/s41467-021-25414-9"]   # Cas9 MHC-II CD4 immunogenicity (Simhadri 2021)
+
+
+@lru_cache(maxsize=1)
+def human_self_kmers(k: int = 9) -> frozenset:
+    """9-mer set of the bundled human SELF reference proteins (the self-tolerance reference). On the VM the full
+    human proteome is substitutable (scripts/p1_build_immuno.py --human-proteome); here the bundled human
+    control(s) seed it, so the AUTHORITATIVE foreignness signal is the protein `origin`."""
+    refs = [v["seq"] for v in writer_sequences().values() if v.get("origin") == "self"]
+    ks: set = set()
+    for s in refs:
+        s = _clean(s)
+        for i in range(len(s) - k + 1):
+            ks.add(s[i:i + k])
+    return frozenset(ks)
+
+
+def self_tolerance(seq: str, human_kmers: frozenset | None = None) -> dict:
+    """Fraction of a protein's MHC-II binder cores that match the human self reference (tolerated)."""
+    human = human_kmers if human_kmers is not None else human_self_kmers()
+    cores = [c for _, c, _ in mhc2_binder_cores(seq)]
+    if not cores:
+        return {"self_match_fraction": None, "n_binder_cores": 0, "n_self_matched": 0}
+    matched = sum(1 for c in cores if c in human)
+    return {"self_match_fraction": round(matched / len(cores), 4), "n_binder_cores": len(cores),
+            "n_self_matched": matched,
+            "reference": "bundled human self proteins (full human proteome substitutable on VM)"}
+
+
+def ada_risk(seq: str, origin: str | None = None, human_kmers: frozenset | None = None) -> dict:
+    """ADA-risk = MHC-II epitope density x foreignness, with the self-tolerance filter. Higher ada_risk_score =
+    MORE anti-drug-antibody risk; `ada_immune_score = 1 - ada_risk_score` (higher = safer) for profile parity."""
+    el = mhc2_epitope_load(seq)
+    st = self_tolerance(seq, human_kmers)
+    sm = st["self_match_fraction"] or 0.0
+    if origin == "self":
+        foreign = 0.0
+    else:                                                # foreign or unknown -> use the self-match filter
+        foreign = round(1.0 - sm, 4)
+    risk = round(el["epitope_density"] * foreign, 4)
+    return {
+        "ada_risk_score": risk, "ada_immune_score": round(1.0 - risk, 4),
+        "epitope_density": el["epitope_density"], "foreignness": foreign, "origin": origin,
+        "self_tolerance": st,
+        "direction": "ada_risk_score: higher = MORE ADA risk; ada_immune_score: higher = safer",
+        "filter": "JanusMatrix-style self-tolerance: foreign non-self MHC-II epitopes drive ADA; self epitopes are "
+                  "tolerated (central tolerance). Origin is authoritative when known; else the human-proteome "
+                  "k-mer filter.",
+        "status": "population-level proxy (🟡); patient ADA titer / magnitude is a known-unknown",
+        "dois": ADA_DOIS,
+    }
+
+
+def ada_risk_named(name: str) -> dict:
+    """ADA-risk for a bundled writer/control protein by name (uses its declared origin)."""
+    rec = writer_sequences().get(name)
+    if not rec:
+        return {"available": False, "note": f"no bundled sequence {name!r}"}
+    return {"available": True, "name": name, "family": rec.get("family"), **ada_risk(rec["seq"], rec.get("origin"))}

pen_stack-6.9.0/pen_stack/planner/immune_mhc2.py

@@ -0,0 +1,114 @@
+"""CD4 / MHC-II epitope-load axis for the writer enzyme AND the capsid (v6.9 PEN-IMMUNE, G-WS1).
+
+The dominant immunogenicity driver for a protein therapeutic is **MHC-II / CD4 help -> anti-drug antibodies
+(ADA)** — exactly what the v5.x immune profile omitted (it did CD8/MHC-I via MHCflurry only). And the **editor
+protein itself is immunogenic** (Cas9 elicits MHC-II-presented CD4 responses, Simhadri et al., Nat Commun 2021,
+10.1038/s41467-021-25414-9; bridge recombinases / serine integrases are bacterial/phage) — yet Stage G scored
+only the capsid. v6.9 adds an MHC-II epitope-load axis over the **writer** as a distinct antigen.
+
+Method (grounded, dependency-free, allele-agnostic PROMISCUOUS-binder density): MHC-II presents a 9-mer core in an
+open groove; the **P1 pocket is deep and hydrophobic**, the single dominant anchor (M/F/Y/W/L/I/V) (Stern & Wiley,
+Nature 1994; Jardetzky 1996), with secondary pockets at P4/P6/P9. A *promiscuous* epitope (binds many HLA-DR) is
+exactly one with a strong P1 anchor + favorable secondaries (Southwood et al., J Immunol 1998). We count
+promiscuous-binder cores -> an epitope-density proxy. This is a **population-level, sequence-intrinsic PROXY (🟡)**,
+NOT a trained allele-specific predictor and NOT a patient-HLA-specific magnitude (a known-unknown). Whether those
+epitopes drive ADA depends on self-tolerance (foreign vs self) — handled in `ada_risk`.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack._resources import resource
+
+_AA = set("ACDEFGHIKLMNPQRSTVWY")
+P1_ANCHOR = set("MFYWLIV")          # large hydrophobic — the dominant MHC-II P1 anchor (Stern & Wiley 1994)
+_FAVORABLE = set("AVLIMFYWSTNQGC")  # favorable at secondary pockets (hydrophobic / small / polar-uncharged)
+_DISFAVORED = set("DEKRP")          # charged / proline disfavored at anchor positions
+MHC2_DOIS = ["10.1038/35030019", "10.1038/s41467-021-25414-9"]   # Stern&Wiley groove; Cas9 MHC-II (Simhadri 2021)
+
+
+def _clean(seq: str) -> str:
+    return "".join(c for c in str(seq).upper() if c in _AA)
+
+
+def _core_is_binder(core: str) -> tuple[bool, float]:
+    """A 9-mer core is a promiscuous-binder candidate iff P1 (pos0) is a strong hydrophobic anchor AND >=2 of the
+    secondary pockets P4/P6/P9 are favorable with no disfavored residue at an anchor position."""
+    if core[0] not in P1_ANCHOR:
+        return False, 0.0
+    sec = sum(1 for p in (3, 5, 8) if core[p] in _FAVORABLE)
+    pen = sum(1 for p in (0, 3, 5, 8) if core[p] in _DISFAVORED)
+    score = 1.0 + 0.5 * sec - 0.5 * pen
+    return (sec >= 2 and pen == 0), round(score, 3)
+
+
+def mhc2_binder_cores(seq: str) -> list[tuple[int, str, float]]:
+    """All promiscuous-binder 9-mer cores in the sequence: (start_index, core, score)."""
+    s = _clean(seq)
+    out = []
+    for i in range(len(s) - 8):
+        ok, sc = _core_is_binder(s[i:i + 9])
+        if ok:
+            out.append((i, s[i:i + 9], sc))
+    return out
+
+
+def mhc2_epitope_load(seq: str) -> dict:
+    """Sequence-intrinsic MHC-II promiscuous-binder density + an immune score (1 = least presentable), 🟡 proxy."""
+    s = _clean(seq)
+    n_cores = max(0, len(s) - 8)
+    binders = mhc2_binder_cores(s)
+    density = (len(binders) / n_cores) if n_cores else 0.0
+    return {
+        "n_residues": len(s), "n_cores": n_cores, "n_promiscuous_binders": len(binders),
+        "epitope_density": round(density, 4),
+        "mhc2_immune_score": round(1.0 - min(density, 1.0), 4),       # 1 = least presentable (MHC-I convention)
+        "method": "promiscuous MHC-II binder density (P1 hydrophobic anchor + P4/P6/P9 secondary pockets; "
+                  "Stern & Wiley 1994; Southwood 1998)",
+        "status": "population-level sequence-intrinsic proxy (🟡); NOT a trained allele-specific predictor, NOT a "
+                  "patient-HLA-specific magnitude (known-unknown)",
+        "binder_cores": [c for _, c, _ in binders[:50]],
+    }
+
+
+# ---- bundled writer / control sequences (real UniProt, configs/writer_sequences.fasta) --------
+@lru_cache(maxsize=1)
+def writer_sequences() -> dict:
+    """Parse the bundled writer/control FASTA -> {name: {seq, origin, family, accession}}."""
+    txt = resource("configs/writer_sequences.fasta").read_text(encoding="utf-8")
+    out: dict = {}
+    name = seq = origin = family = acc = None
+
+    def _flush():
+        if name:
+            out[name] = {"seq": seq, "origin": origin, "family": family, "accession": acc}
+    for line in txt.splitlines():
+        if line.startswith("#"):
+            continue
+        if line.startswith(">"):
+            _flush()
+            head = line[1:].strip()
+            tok = head.split()
+            name, acc = (tok[0].split("|") + [None])[:2]
+            kv = dict(p.split("=", 1) for p in tok[1:] if "=" in p)
+            origin, family, seq = kv.get("origin"), kv.get("family"), ""
+        else:
+            seq = (seq or "") + line.strip()
+    _flush()
+    return out
+
+
+def writer_family_to_sequence(writer_family: str) -> dict | None:
+    """Map a design's writer family (e.g. 'bridge_IS110', 'serine_integrase', 'Cas9') to a bundled writer
+    sequence record, or None when no representative sequence is bundled (then the axis abstains)."""
+    fam = (writer_family or "").lower()
+    seqs = writer_sequences()
+    for name, rec in seqs.items():
+        f = (rec.get("family") or "").lower()
+        if rec.get("origin") == "self":
+            continue
+        if fam and (fam in f or f in fam or fam in name.lower()):
+            return {"name": name, **rec}
+    if "cas9" in fam or "nuclease" in fam:
+        return {"name": "SpCas9", **seqs.get("SpCas9", {})} if "SpCas9" in seqs else None
+    return None

{pen_stack-6.8.0 → pen_stack-6.9.0}/pen_stack/planner/immune_profile.py

@@ -12,8 +12,10 @@ not a patient-level prediction.
 from __future__ import annotations
 
 from pen_stack.planner.antipeg_oracle import antipeg_oracle
+from pen_stack.planner.ada_risk import ada_risk
 from pen_stack.planner.capsid_epitope_oracle import capsid_epitope_oracle
 from pen_stack.planner.genotoxicity_oracle import genotoxicity_oracle
+from pen_stack.planner.immune_mhc2 import mhc2_epitope_load, writer_family_to_sequence
 from pen_stack.planner.innate_sensing import innate_sensing
 from pen_stack.planner.seroprevalence_oracle import seroprevalence_oracle
 from pen_stack.validate.immune_calibration import axis_label
@@ -67,6 +69,32 @@ def _axis(result, axis: str) -> dict:
             "note": result.note}
 
 
+def _proxy_axis(value, note: str, axis: str = "mhc2_writer") -> dict:
+    """An axis record for the v6.9 sequence-intrinsic proxies (MHC-II / ADA). Value None = abstained (no writer
+    sequence). Population-level proxy until WS-CALIB validates — never a patient magnitude."""
+    return {"value": value, "uncertainty": None, "in_scope": value is not None, "available": value is not None,
+            "validation": axis_label(axis), "scope_card": axis, "note": note}
+
+
+def _writer_antigen_card(design: dict) -> dict | None:
+    """The WRITER enzyme as a distinct antigen (v6.9 G-WS3): MHC-II epitope load + ADA-risk over the writer's real
+    sequence. Returns None when no representative writer sequence is bundled (axis then abstains)."""
+    wf = design.get("writer_family") or design.get("writer")
+    rec = writer_family_to_sequence(wf) if wf else None
+    if not rec or not rec.get("seq"):
+        return None
+    el = mhc2_epitope_load(rec["seq"])
+    ad = ada_risk(rec["seq"], rec.get("origin"))
+    return {"writer_family": wf, "representative": rec.get("name"), "accession": rec.get("accession"),
+            "origin": rec.get("origin"), "is_foreign": rec.get("origin") == "foreign",
+            "mhc2_immune_score": el["mhc2_immune_score"], "epitope_density": el["epitope_density"],
+            "ada_risk_score": ad["ada_risk_score"], "ada_immune_score": ad["ada_immune_score"],
+            "self_tolerance": ad["self_tolerance"],
+            "note": "the WRITER enzyme scored as a distinct antigen (MHC-II/CD4 + ADA, self-tolerance filtered); "
+                    "bacterial/phage writers are foreign -> ADA-driving (Cas9 MHC-II: Simhadri 2021). "
+                    "Population-level proxy (🟡); realized CD4 response / ADA titer is a known-unknown."}
+
+
 def immune_profile(design: dict) -> dict:
     """Per-design immune-risk profile across all axes. ``design`` keys: ``delivery_vehicle`` (or ``vehicle``),
     ``serotype``, ``cargo_seq``, ``writer_output_form`` (or ``cargo_form``), ``pegylated``.
@@ -79,20 +107,46 @@ def immune_profile(design: dict) -> dict:
     form = design.get("writer_output_form") or design.get("cargo_form") or ""
     peg = design.get("pegylated")
 
+    capsid_cd8 = capsid_epitope_oracle(veh)
+    writer_card = _writer_antigen_card(design)            # v6.9 — the writer enzyme as a distinct antigen
+
     axes = {
         "genotoxicity": _axis(genotoxicity_oracle(veh), "genotoxicity"),
-        "cd8_epitope": _axis(capsid_epitope_oracle(veh), "cd8_epitope"),
+        "cd8_epitope": _axis(capsid_cd8, "cd8_epitope"),  # capsid CD8/MHC-I (v5.3)
         "innate": _axis(innate_sensing(cargo_seq, form), "innate"),
         "preexisting_nab": _axis(seroprevalence_oracle(veh, sero), "preexisting_nab"),
         "anti_peg": _axis(antipeg_oracle(veh, peg), "anti_peg"),
+        # v6.9 — CD4/MHC-II + ADA over the WRITER enzyme (the dominant immunogenicity driver, previously omitted)
+        "mhc2_writer": _proxy_axis(writer_card["mhc2_immune_score"] if writer_card else None,
+                                   (writer_card or {}).get("note", "no bundled writer sequence -> abstains"),
+                                   "mhc2_writer"),
+        "ada_writer": _proxy_axis(writer_card["ada_immune_score"] if writer_card else None,
+                                  "ADA-risk (higher ada_immune_score = safer) over the writer enzyme, self-"
+                                  "tolerance filtered; population proxy" if writer_card else
+                                  "no bundled writer sequence -> abstains", "ada_writer"),
     }
+
+    # writer-as-antigen comparison: for non-viral delivery (no foreign capsid) or a foreign writer outscoring the
+    # capsid, the WRITER is the dominant antigen — the v6.9 insight, never collapsed into the other axes.
+    dominant = None
+    writer_dominant_risk = False
+    if writer_card:
+        capsid_present = bool(capsid_cd8.available and capsid_cd8.value
+                              and (capsid_cd8.value.get("capsid_immune_score") or 1.0) < 1.0)
+        writer_risk = writer_card["ada_risk_score"]
+        capsid_risk = (1.0 - (capsid_cd8.value or {}).get("capsid_immune_score", 1.0)) if capsid_present else 0.0
+        writer_dominant_risk = bool(writer_card["is_foreign"] and (not capsid_present or writer_risk >= capsid_risk))
+        dominant = "writer" if writer_dominant_risk else ("capsid" if capsid_present else "writer")
+
     return {
         "axes": axes,
         "collapsed_score": None,            # deliberately None — a profile, never a fused number
+        "writer_as_antigen": ({**writer_card, "dominant_antigen": dominant,
+                               "writer_dominant_risk": writer_dominant_risk} if writer_card else None),
         "route_modifier": _route_modifier(design.get("route")),   # v5.6 WS-EXT documented route modifier (or None)
         "known_unknowns": KNOWN_UNKNOWNS,
         "no_fabrication": True,
-        "note": ("relative immune-risk SCREEN across axes; each axis keeps its own value + uncertainty + scope "
-                 "+ validation label; NOT a patient-level prediction. The in-vivo response magnitude and the "
-                 "patient-specific titer are declared known-unknowns."),
+        "note": ("relative immune-risk SCREEN across axes (now incl. CD4/MHC-II + ADA over the writer enzyme); each "
+                 "axis keeps its own value + uncertainty + scope + validation label; NEVER fused. NOT a patient-"
+                 "level prediction. The realized CD4 response / ADA titer / in-vivo magnitude are known-unknowns."),
     }

{pen_stack-6.8.0 → pen_stack-6.9.0}/pen_stack/validate/immune_calibration.py

@@ -94,6 +94,16 @@ AXIS_STATUS: dict[str, dict] = {
         "label": "anti_peg: population proxy — gates re-dosing, not calibrated to re-dosing failure",
         "reason": "anti-PEG seroprevalence gates re-dosing; not calibrated against observed re-dosing-failure "
                   "rates (and induced post-dose-1 anti-PEG is a separate dynamic)."},
+    "mhc2_writer": {        # v6.9 G-WS1 — CD4/MHC-II epitope load over the writer enzyme
+        "status": "mechanistic_proxy",
+        "label": "mhc2_writer: mechanistic/population proxy — NOT outcome-validated",
+        "reason": "sequence-intrinsic promiscuous MHC-II binder density (P1-anchor; Stern & Wiley 1994) is a "
+                  "presentation potential, NOT a trained allele-specific predictor or a patient-HLA magnitude."},
+    "ada_writer": {        # v6.9 G-WS2 — ADA-risk (MHC-II x foreignness, self-tolerance filtered)
+        "status": "mechanistic_proxy",
+        "label": "ada_writer: mechanistic/population proxy — NOT outcome-validated",
+        "reason": "ADA-risk = MHC-II epitope density x foreignness (self-tolerance filtered) recovers immunogenic-"
+                  "vs-tolerated, but is not calibrated against observed ADA incidence at public-data power."},
 }
 
 

{pen_stack-6.8.0 → pen_stack-6.9.0}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.8.0
+Version: 6.9.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.8.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.9.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,29 @@ 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.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
+driver is **MHC-II / CD4 help → anti-drug antibodies (ADA)**, and the **writer enzyme itself is immunogenic**
+(Cas9 elicits MHC-II-presented CD4 responses, Simhadri *Nat Commun* 2021; bridge recombinases / serine integrases
+are bacterial/phage) — yet Stage G scored only the capsid. v6.9 closes that gap, **never collapsing** the axes:
+
+- **A CD4/MHC-II epitope-load axis** (`planner/immune_mhc2.py`) — a grounded, dependency-free **promiscuous MHC-II
+  binder density** over the documented P1 hydrophobic anchor (Stern & Wiley 1994) + secondary pockets, scored over
+  **capsid AND writer** sequences. Population-level proxy (🟡), never a patient-HLA magnitude.
+- **An ADA-risk axis** (`planner/ada_risk.py`) — **ADA-risk = MHC-II epitope density × foreignness**, with a
+  **self-tolerance filter** (JanusMatrix-style: self epitopes are tolerated; foreign drive ADA). It **recovers
+  immunogenic-vs-tolerated**: the foreign writers (real UniProt SpCas9 / ISCro4 / Bxb1) score **above** the human
+  self control (albumin), even without the origin label (the k-mer self-match tolerates the human protein).
+- **The writer as a distinct antigen** — the profile now carries a `writer_as_antigen` card and a
+  `writer_dominant_risk` flag: for **non-viral delivery of a bacterial writer there is no capsid antigen, so the
+  WRITER is the dominant immunogen** — the insight the capsid-only profile missed.
+- **Immuno-Bench** (`benchmarks/immuno/`) — the immunogenic-vs-tolerated recovery track + an honest `calibrate_axis`
+  ADA pass (it stays 🟡 at public-data power — no manufactured ✅, the standing wet-lab bottleneck).
+
+Real UniProt sequences only (no fabricated sequence); the axes are reported as a vector with `collapsed_score: None`;
+the realized CD4 response / ADA titer stay known-unknowns. See [docs/immune_profiler.md](docs/immune_profiler.md).
+
 ## What is new in v6.8 — PEN-WRITER (a cross-family writer-efficiency engine + the first writer-efficiency benchmark)
 
 Stage C (pick the writer) was **retrieval** — the curated Writer Atlas ranks 8 families but predicts no

{pen_stack-6.8.0 → pen_stack-6.9.0}/pen_stack.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ configs/seroprevalence.yaml
 configs/target_sites.yaml
 configs/universe_crosswalk.yaml
 configs/write_types.yaml
+configs/writer_sequences.fasta
 configs/wtkb_curated.yaml
 configs/calibration/preexisting_nab_independent.yaml
 configs/expression/modifiers.yaml
@@ -82,6 +83,7 @@ docs/dissemination.md
 docs/environment.md
 docs/experiment_design.md
 docs/generative_design.md
+docs/immune_profiler.md
 docs/index.md
 docs/integrations.md
 docs/live_oracles.md
@@ -213,6 +215,7 @@ pen_stack/oracles/status.py
 pen_stack/oracles/structure.py
 pen_stack/oracles/vcell.py
 pen_stack/planner/__init__.py
+pen_stack/planner/ada_risk.py
 pen_stack/planner/antipeg_oracle.py
 pen_stack/planner/capsid_epitope_oracle.py
 pen_stack/planner/cargo.py
@@ -222,6 +225,7 @@ pen_stack/planner/delivery_constraints.py
 pen_stack/planner/delivery_immunology.py
 pen_stack/planner/delivery_vehicles.py
 pen_stack/planner/genotoxicity_oracle.py
+pen_stack/planner/immune_mhc2.py
 pen_stack/planner/immune_profile.py
 pen_stack/planner/innate_sensing.py
 pen_stack/planner/multiplex.py
@@ -361,6 +365,7 @@ prereg/SHA256_LOCK_ws_graph.json
 prereg/SHA256_LOCK_ws_h.json
 prereg/SHA256_LOCK_ws_hybrid.json
 prereg/SHA256_LOCK_ws_immune.json
+prereg/SHA256_LOCK_ws_immune2.json
 prereg/SHA256_LOCK_ws_ingest.json
 prereg/SHA256_LOCK_ws_innate.json
 prereg/SHA256_LOCK_ws_loop.json
@@ -432,6 +437,7 @@ prereg/ws_graph.yaml
 prereg/ws_h.yaml
 prereg/ws_hybrid.yaml
 prereg/ws_immune.yaml
+prereg/ws_immune2.yaml
 prereg/ws_ingest.yaml
 prereg/ws_innate.yaml
 prereg/ws_loop.yaml

pen_stack-6.9.0/prereg/SHA256_LOCK_ws_immune2.json

@@ -0,0 +1,8 @@
+{
+  "cycle": "v6.9",
+  "workstream": "WS-IMMUNE2",
+  "prepared": "2026-06-20",
+  "sha256": {
+    "prereg/ws_immune2.yaml": "241c052bbd908664b98371a34f319ea08f7ab317693b550874dc28801ee5a5d2"
+  }
+}