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

{pen_stack-6.8.0 → pen_stack-6.9.1}/CHANGELOG.md

@@ -3,6 +3,65 @@
 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.1] - 2026-06-20 - Real NetMHCIIpan-4.0 / NetMHCpan-4.1 MHC epitope load (replaces the v6.9.0 proxy)
+
+**PATCH — rigour upgrade.** v6.9.0's MHC-II axis was a documented *heuristic proxy* (P1-anchor density). The
+gold-standard licensed predictors were already on the VM — so v6.9.1 computes the MHC-II epitope load with **real
+NetMHCIIpan-4.0** (and MHC-I with **NetMHCpan-4.1**) over a frequent HLA panel, and re-grounds the axis on the real
+values. Honest: the licensed binaries are **never committed/distributed** — only the **derived fractions** are
+cached (`configs/mhc_epitope_oracle.yaml`), exactly like the v5.3 MHCflurry cache.
+
+### Changed
+- `pen_stack/planner/immune_mhc2.py` — `mhc2_epitope_load(seq, name)` now uses the **real NetMHCIIpan-4.0 EL
+  %Rank≤2** cache (over 7 frequent HLA-II alleles) when the antigen is cached; the documented promiscuous-binder
+  proxy remains only as the **offline/CI fallback** for uncached sequences. `real_mhc2_load(name)` exposes the cache.
+- `ada_risk` + `immune_profile` (writer-as-antigen) + `benchmarks/immuno` thread the antigen name → real values.
+- `configs/mhc_epitope_oracle.yaml` (committed) — derived epitope fractions for the writer + capsid antigens.
+
+### Result (real tool is more discriminating than the proxy)
+- Real NetMHCIIpan-4.0 strong-binder fraction: SpCas9 **0.153**, Bxb1 **0.152**, ISCro4 **0.112**, AAV2 0.114 vs
+  **human albumin (self) 0.066 — the lowest**. The gold-standard tool shows the self protein has a genuinely lower
+  MHC-II load and the foreign writers higher — a signal the heuristic proxy flattened (~0.08–0.10 for all). The
+  immunogenic-vs-tolerated recovery is unchanged (foreign ≫ self) but now on real predictions.
+
+### How it ran (no host install; per the VM Docker rule)
+- `penmhc:tools` (debian + tcsh + gawk + perl) with `~/netmhc` (the licensed tools) **mounted**, NMHOME fixed at
+  runtime; `scratch/v691_mhc_compute.py` runs both predictors and writes the derived cache. The axis stays a 🟡
+  population-level proxy (frequent-HLA panel, not a patient-HLA magnitude — a known-unknown).
+
+## [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.1}/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.1
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.8.0
+Version: 6.9.1
 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.1-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,32 @@ 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`) — **v6.9.1 computes it with the real, licensed
+  NetMHCIIpan-4.0** (EL %Rank≤2 over a frequent HLA-II panel; MHC-I via NetMHCpan-4.1), scored over **capsid AND
+  writer** sequences; only the derived fractions are cached (`configs/mhc_epitope_oracle.yaml`, the binaries are
+  never distributed), with a documented promiscuous-binder proxy as the offline/CI fallback. Population-level proxy
+  (🟡), never a patient-HLA magnitude. *(v6.9.0 used the heuristic proxy; the real tool is more discriminating —
+  human-self albumin 0.066 vs foreign writers 0.11–0.15.)*
+- **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.1}/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.1-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,32 @@ 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`) — **v6.9.1 computes it with the real, licensed
+  NetMHCIIpan-4.0** (EL %Rank≤2 over a frequent HLA-II panel; MHC-I via NetMHCpan-4.1), scored over **capsid AND
+  writer** sequences; only the derived fractions are cached (`configs/mhc_epitope_oracle.yaml`, the binaries are
+  never distributed), with a documented promiscuous-binder proxy as the offline/CI fallback. Population-level proxy
+  (🟡), never a patient-HLA magnitude. *(v6.9.0 used the heuristic proxy; the real tool is more discriminating —
+  human-self albumin 0.066 vs foreign writers 0.11–0.15.)*
+- **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.1/configs/mhc_epitope_oracle.yaml

@@ -0,0 +1,239 @@
+version: 6.9.1
+method:
+  mhc2: NetMHCIIpan-4.0 EL %Rank<=2
+  mhc1: NetMHCpan-4.1 %Rank<=0.5
+  hla2_panel:
+  - DRB1_0101
+  - DRB1_0301
+  - DRB1_0401
+  - DRB1_0701
+  - DRB1_1101
+  - DRB1_1301
+  - DRB1_1501
+  hla1_panel:
+  - HLA-A01:01
+  - HLA-A02:01
+  - HLA-A03:01
+  - HLA-A11:01
+  - HLA-A24:02
+  - HLA-A26:01
+  - HLA-B07:02
+  - HLA-B08:01
+  - HLA-B15:01
+  - HLA-B27:05
+  - HLA-B40:01
+  - HLA-B58:01
+provenance_dois:
+- 10.1093/nar/gkac1029
+- 10.1093/nar/gkaa379
+note: population-level epitope load over a frequent HLA panel (NOT patient-HLA-specific);
+  licensed NetMHC binaries run locally, only derived fractions cached.
+mhc2:
+  SpCas9:
+    epitope_fraction_strong: 0.1529
+    immune_score: 0.8471
+    n_windows: 1354
+    n_strong: 207
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  ISCro4:
+    epitope_fraction_strong: 0.1122
+    immune_score: 0.8878
+    n_windows: 312
+    n_strong: 35
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  Bxb1:
+    epitope_fraction_strong: 0.152
+    immune_score: 0.848
+    n_windows: 487
+    n_strong: 74
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  HumanAlbumin:
+    epitope_fraction_strong: 0.0655
+    immune_score: 0.9345
+    n_windows: 595
+    n_strong: 39
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  AAV2_VP1:
+    epitope_fraction_strong: 0.1137
+    immune_score: 0.8863
+    n_windows: 721
+    n_strong: 82
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  Ad5_hexon:
+    epitope_fraction_strong: 0.1471
+    immune_score: 0.8529
+    n_windows: 938
+    n_strong: 138
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  VSVg_Indiana:
+    epitope_fraction_strong: 0.0684
+    immune_score: 0.9316
+    n_windows: 497
+    n_strong: 34
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  HSV1_gD:
+    epitope_fraction_strong: 0.1184
+    immune_score: 0.8816
+    n_windows: 380
+    n_strong: 45
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+  HSV1_gB:
+    epitope_fraction_strong: 0.1067
+    immune_score: 0.8933
+    n_windows: 890
+    n_strong: 95
+    alleles_used:
+    - DRB1_0101
+    - DRB1_0301
+    - DRB1_0401
+    - DRB1_0701
+    - DRB1_1101
+    - DRB1_1301
+    - DRB1_1501
+mhc1:
+  AAV2_VP1:
+    epitope_fraction_strong: 0.0935
+    immune_score: 0.9065
+    n_windows: 727
+    n_strong: 68
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B27:05
+    - HLA-B40:01
+    - HLA-B58:01
+  Ad5_hexon:
+    epitope_fraction_strong: 0.1367
+    immune_score: 0.8633
+    n_windows: 944
+    n_strong: 129
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B27:05
+    - HLA-B40:01
+    - HLA-B58:01
+  VSVg_Indiana:
+    epitope_fraction_strong: 0.1074
+    immune_score: 0.8926
+    n_windows: 503
+    n_strong: 54
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B27:05
+    - HLA-B40:01
+    - HLA-B58:01
+  HSV1_gD:
+    epitope_fraction_strong: 0.1218
+    immune_score: 0.8782
+    n_windows: 386
+    n_strong: 47
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B27:05
+    - HLA-B40:01
+    - HLA-B58:01
+  HSV1_gB:
+    epitope_fraction_strong: 0.115
+    immune_score: 0.885
+    n_windows: 896
+    n_strong: 103
+    alleles_used:
+    - HLA-A01:01
+    - HLA-A02:01
+    - HLA-A03:01
+    - HLA-A11:01
+    - HLA-A24:02
+    - HLA-A26:01
+    - HLA-B07:02
+    - HLA-B08:01
+    - HLA-B15:01
+    - HLA-B27:05
+    - HLA-B40:01
+    - HLA-B58:01

pen_stack-6.9.1/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.1/docs/immune_profiler.md

@@ -0,0 +1,61 @@
+# 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`)
+
+> **v6.9.1 — real predictor.** The MHC-II epitope load is computed with the **licensed NetMHCIIpan-4.0** (EL
+> %Rank≤2 over a frequent HLA-II panel; MHC-I via **NetMHCpan-4.1**), run inside `penmhc:tools` Docker on the VM
+> with the licensed tools **mounted** (never committed). Only the **derived fractions** are cached
+> (`configs/mhc_epitope_oracle.yaml`), exactly like the v5.3 MHCflurry cache. The documented proxy below remains as
+> the offline/CI fallback for sequences not in the cache. Real result: human-self albumin **0.066** vs foreign
+> writers **0.11–0.15** (the gold-standard tool discriminates self from foreign — the v6.9.0 proxy gave ~0.08–0.10
+> for all). Still a 🟡 population-level proxy (frequent-HLA panel, not a patient-HLA magnitude).
+
+A grounded, dependency-free **promiscuous MHC-II binder density** (the offline/CI fallback): 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.1}/pen_stack/__init__.py

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

pen_stack-6.9.1/pen_stack/planner/ada_risk.py

@@ -0,0 +1,87 @@
+"""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,
+             name: str | None = None) -> dict:
+    """ADA-risk = MHC-II epitope density x foreignness, with the self-tolerance filter. Uses the REAL NetMHCIIpan-4.0
+    epitope density when the antigen `name` is cached (else the documented proxy). 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, name)
+    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"), name=name)}