pen-stack 5.2.0__tar.gz → 5.3.0__tar.gz

{pen_stack-5.2.0 → pen_stack-5.3.0}/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [5.3.0] - 2026-06-10 - v5.3 release: Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only meaningfully touches integrating vectors. v5.3 brings the **NetMHC-style
+calculation** to the **adaptive (CD8 T-cell)** axis — the fraction of a viral vector's capsid/envelope that is
+presentable across a frequent HLA-I panel (MHCflurry) — so the computed immune signal **covers all 8 vehicles**
+(5 viral computed, 3 non-viral by mechanism). Workstream WS-EPITOPE, SHA-locked.
+
+### Added
+- **WS-EPITOPE build** — `scripts/p53_build_epitope_oracle.py` (runs in a dedicated `penstack:mhcflurry` image)
+  slides 9-mers across each capsid/envelope antigen and predicts MHCflurry 2.0 affinity %rank per allele across
+  12 frequent HLA-I alleles; `epitope_fraction_strong` = residues covered by a strong binder (%rank ≤ 0.5);
+  `capsid_immune_score = 1 − epitope_fraction_strong`. Sequences UniProt-verified and committed
+  (`configs/capsid_sequences.fasta`): AAV2 VP1 P03135, Ad5 hexon P04133, VSV-G P03522, HSV-1 gD P57083 + gB
+  P06437. Emits the small committed summary `configs/capsid_epitope_oracle.yaml` (MHCflurry + raw sequences stay
+  on the VM → CI-safe).
+- **WS-EPITOPE oracle** — `pen_stack/planner/capsid_epitope_oracle.py`: `capsid_epitope_oracle(vehicle)` returns
+  an `OracleResult` (`output_kind="baseline"`, scope card `capsid_epitope`). Non-viral vehicles → 1.0 by
+  mechanism; unknown / sequence-less → **abstains**.
+- **Wired into the adaptive axis** — `safety_efficacy_profile()` folds the computed capsid score into the
+  adaptive (CD8) sub-axis **only for in-vivo vehicles**. The computed score is *intrinsic* antigen
+  presentability; for **ex-vivo** lentivirus (whose VSV-G envelope is intrinsically epitope-dense but barely
+  seen by the host ex vivo) it is **reported but not folded** (`adaptive_source = computed_ex_vivo_muted`), the
+  documented tier kept. `capsid_presentability_score` surfaces the raw computed value.
+- **Result:** AAV2 capsid is the *least* epitope-dense (0.72) and Ad5 hexon among the most (0.82); HDAd's in-vivo
+  immune score drops accordingly — the documented adaptive ordering reproduced from sequence. `prereg/ws_epitope.yaml`.
+
+### Changed
+- Version 5.2.0 -> 5.3.0 (minor — additive computed oracle); `cite.curated_dois()` ingests the epitope
+  provenance DOIs (MHCflurry 10.1016/j.cels.2020.06.010, HLA-I supertypes 10.1186/1471-2172-9-1).
+
+### Honesty invariant (unchanged)
+- Population-level, **sequence-intrinsic presentation** signal (does the capsid contain HLA binders) — **not**
+  the realized in-vivo / **patient-HLA-specific** T-cell response (a known-unknown), and **CD8/MHC-I only** (not
+  antibody / neutralizing-antibody). No magnitude predicted.
+
 ## [5.2.0] - 2026-06-10 - v5.2 release: Computed genotoxicity oracle (data, not a documented tier)
 
 The v5.1 genotoxicity axis was a documented ordinal tier; for **integrating** vectors that signal is in fact

{pen_stack-5.2.0 → pen_stack-5.3.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: 5.2.0
+version: 5.3.0
 date-released: 2026-06-10
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-5.2.0 → pen_stack-5.3.0}/MANIFEST.in

@@ -2,7 +2,7 @@
 # source build is reproducible. Large artifacts (atlases, BigWig, models) are NOT shipped - they are on
 # Zenodo (DOI) per the data policy; clone the repo + fetch Zenodo for the full pipeline.
 include README.md LICENSE CHANGELOG.md CITATION.cff pyproject.toml
-recursive-include configs *.yaml *.yml *.txt.example
+recursive-include configs *.yaml *.yml *.txt.example *.fasta
 recursive-include prereg *.yaml *.json
 recursive-include data/curated *
 recursive-include benchmarks *.yaml *.md SHA256SUMS

{pen_stack-5.2.0 → pen_stack-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.2.0
+Version: 5.3.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
@@ -91,7 +91,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-5.2.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -135,6 +135,22 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the
+**adaptive (CD8 T-cell)** axis: the fraction of a viral vector's capsid/envelope presentable across a frequent
+HLA-I panel (MHCflurry), so the computed immune signal now **covers all 8 vehicles** — 5 viral computed, 3
+non-viral by mechanism. It is a population-level, *sequence-intrinsic* presentation signal; the realized
+patient-HLA-specific T-cell response stays a known-unknown (and it is CD8/MHC-I only, not antibody).
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **EPITOPE build** | `scripts/p53_build_epitope_oracle.py` → committed `configs/capsid_epitope_oracle.yaml` | per viral capsid: `epitope_fraction_strong` over 9-mers × 12 HLA-I alleles (MHCflurry %rank ≤ 0.5), from UniProt-verified sequences (AAV2 VP1, Ad5 hexon, VSV-G, HSV gD/gB); MHCflurry stays on the VM, only the summary ships |
+| **EPITOPE oracle** | `planner/capsid_epitope_oracle.py` (`OracleResult`) | `capsid_immune_score = 1 − epitope_fraction_strong`; non-viral → 1.0 by mechanism; abstains when no sequence |
+| **wired into the adaptive axis** | folded **only for in-vivo** vehicles | AAV2 least epitope-dense (0.72), Ad5 hexon among the most (0.82) — documented adaptive ordering reproduced from sequence; **ex-vivo** lentivirus's intrinsic VSV-G load is *reported but muted* (host barely sees it ex vivo) |
+
+See `prereg/ws_epitope.yaml` and the `capsid_epitope` scope card.
+
 ## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
 
 v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for

{pen_stack-5.2.0 → pen_stack-5.3.0}/README.md

@@ -16,7 +16,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-5.2.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -60,6 +60,22 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the
+**adaptive (CD8 T-cell)** axis: the fraction of a viral vector's capsid/envelope presentable across a frequent
+HLA-I panel (MHCflurry), so the computed immune signal now **covers all 8 vehicles** — 5 viral computed, 3
+non-viral by mechanism. It is a population-level, *sequence-intrinsic* presentation signal; the realized
+patient-HLA-specific T-cell response stays a known-unknown (and it is CD8/MHC-I only, not antibody).
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **EPITOPE build** | `scripts/p53_build_epitope_oracle.py` → committed `configs/capsid_epitope_oracle.yaml` | per viral capsid: `epitope_fraction_strong` over 9-mers × 12 HLA-I alleles (MHCflurry %rank ≤ 0.5), from UniProt-verified sequences (AAV2 VP1, Ad5 hexon, VSV-G, HSV gD/gB); MHCflurry stays on the VM, only the summary ships |
+| **EPITOPE oracle** | `planner/capsid_epitope_oracle.py` (`OracleResult`) | `capsid_immune_score = 1 − epitope_fraction_strong`; non-viral → 1.0 by mechanism; abstains when no sequence |
+| **wired into the adaptive axis** | folded **only for in-vivo** vehicles | AAV2 least epitope-dense (0.72), Ad5 hexon among the most (0.82) — documented adaptive ordering reproduced from sequence; **ex-vivo** lentivirus's intrinsic VSV-G load is *reported but muted* (host barely sees it ex vivo) |
+
+See `prereg/ws_epitope.yaml` and the `capsid_epitope` scope card.
+
 ## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
 
 v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for

pen_stack-5.3.0/configs/capsid_epitope_oracle.yaml

@@ -0,0 +1,85 @@
+version: '1.0'
+built: '2026-06-10'
+description: 'computed capsid/envelope CD8 T-cell epitope-load oracle: fraction of
+  the antigen presentable (MHCflurry %rank<=0.5) across a frequent HLA-I panel. capsid_immune_score
+  = 1 - epitope_fraction_strong. Patient-HLA-specific response is NOT modelled (known-unknown);
+  this is a population-level sequence-intrinsic signal.'
+method:
+  predictor: MHCflurry 2.0 Class1AffinityPredictor (per-allele %rank)
+  peptide_len: 9
+  strong_rank: 0.5
+  binder_rank: 2.0
+  hla_panel:
+  - HLA-A*01:01
+  - HLA-A*02:01
+  - HLA-A*03:01
+  - HLA-A*11:01
+  - HLA-A*24:02
+  - HLA-A*26:01
+  - HLA-B*07:02
+  - HLA-B*08:01
+  - HLA-B*15:01
+  - HLA-B*40:01
+  - HLA-B*44:03
+  - HLA-B*58:01
+provenance_dois:
+- 10.1016/j.cels.2020.06.010
+- 10.1186/1471-2172-9-1
+proteins:
+  AAV2_VP1:
+    length: 735
+    n_9mers: 727
+    epitope_fraction_strong: 0.7197
+    epitope_fraction_binder: 0.9755
+    strong_binder_density: 0.01433
+  Ad5_hexon:
+    length: 952
+    n_9mers: 944
+    epitope_fraction_strong: 0.8204
+    epitope_fraction_binder: 0.979
+    strong_binder_density: 0.02127
+  VSVg_Indiana:
+    length: 511
+    n_9mers: 503
+    epitope_fraction_strong: 0.8356
+    epitope_fraction_binder: 0.9922
+    strong_binder_density: 0.0174
+  HSV1_gD:
+    length: 394
+    n_9mers: 386
+    epitope_fraction_strong: 0.7893
+    epitope_fraction_binder: 0.9822
+    strong_binder_density: 0.01619
+  HSV1_gB:
+    length: 904
+    n_9mers: 896
+    epitope_fraction_strong: 0.7965
+    epitope_fraction_binder: 0.979
+    strong_binder_density: 0.01851
+vehicles:
+  AAV_single:
+    antigens:
+    - AAV2_VP1
+    epitope_fraction_strong: 0.7197
+    capsid_immune_score: 0.2803
+  AAV_dual:
+    antigens:
+    - AAV2_VP1
+    epitope_fraction_strong: 0.7197
+    capsid_immune_score: 0.2803
+  lentivirus:
+    antigens:
+    - VSVg_Indiana
+    epitope_fraction_strong: 0.8356
+    capsid_immune_score: 0.1644
+  helper_dependent_adenovirus:
+    antigens:
+    - Ad5_hexon
+    epitope_fraction_strong: 0.8204
+    capsid_immune_score: 0.1796
+  hsv_amplicon:
+    antigens:
+    - HSV1_gD
+    - HSV1_gB
+    epitope_fraction_strong: 0.7929
+    capsid_immune_score: 0.2071

pen_stack-5.3.0/configs/capsid_sequences.fasta

@@ -0,0 +1,66 @@
+>AAV2_VP1|P03135 len=735
+MAADGYLPDWLEDTLSEGIRQWWKLKPGPPPPKPAERHKDDSRGLVLPGYKYLGPFNGLD
+KGEPVNEADAAALEHDKAYDRQLDSGDNPYLKYNHADAEFQERLKEDTSFGGNLGRAVFQ
+AKKRVLEPLGLVEEPVKTAPGKKRPVEHSPVEPDSSSGTGKAGQQPARKRLNFGQTGDAD
+SVPDPQPLGQPPAAPSGLGTNTMATGSGAPMADNNEGADGVGNSSGNWHCDSTWMGDRVI
+TTSTRTWALPTYNNHLYKQISSQSGASNDNHYFGYSTPWGYFDFNRFHCHFSPRDWQRLI
+NNNWGFRPKRLNFKLFNIQVKEVTQNDGTTTIANNLTSTVQVFTDSEYQLPYVLGSAHQG
+CLPPFPADVFMVPQYGYLTLNNGSQAVGRSSFYCLEYFPSQMLRTGNNFTFSYTFEDVPF
+HSSYAHSQSLDRLMNPLIDQYLYYLSRTNTPSGTTTQSRLQFSQAGASDIRDQSRNWLPG
+PCYRQQRVSKTSADNNNSEYSWTGATKYHLNGRDSLVNPGPAMASHKDDEEKFFPQSGVL
+IFGKQGSEKTNVDIEKVMITDEEEIRTTNPVATEQYGSVSTNLQRGNRQAATADVNTQGV
+LPGMVWQDRDVYLQGPIWAKIPHTDGHFHPSPLMGGFGLKHPPPQILIKNTPVPANPSTT
+FSAAKFASFITQYSTGQVSVEIEWELQKENSKRWNPEIQYTSNYNKSVNVDFTVDTNGVY
+SEPRPIGTRYLTRNL
+>Ad5_hexon|P04133 len=952
+MATPSMMPQWSYMHISGQDASEYLSPGLVQFARATETYFSLNNKFRNPTVAPTHDVTTDR
+SQRLTLRFIPVDREDTAYSYKARFTLAVGDNRVLDMASTYFDIRGVLDRGPTFKPYSGTA
+YNALAPKGAPNPCEWDEAATALEINLEEEDDDNEDEVDEQAEQQKTHVFGQAPYSGINIT
+KEGIQIGVEGQTPKYADKTFQPEPQIGESQWYETEINHAAGRVLKKTTPMKPCYGSYAKP
+TNENGGQGILVKQQNGKLESQVEMQFFSTTEATAGNGDNLTPKVVLYSEDVDIETPDTHI
+SYMPTIKEGNSRELMGQQSMPNRPNYIAFRDNFIGLMYYNSTGNMGVLAGQASQLNAVVD
+LQDRNTELSYQLLLDSIGDRTRYFSMWNQAVDSYDPDVRIIENHGTEDELPNYCFPLGGV
+INTETLTKVKPKTGQENGWEKDATEFSDKNEIRVGNNFAMEINLNANLWRNFLYSNIALY
+LPDKLKYSPSNVKISDNPNTYDYMNKRVVAPGLVDCYINLGARWSLDYMDNVNPFNHHRN
+AGLRYRSMLLGNGRYVPFHIQVPQKFFAIKNLLLLPGSYTYEWNFRKDVNMVLQSSLGND
+LRVDGASIKFDSICLYATFFPMAHNTASTLEAMLRNDTNDQSFNDYLSAANMLYPIPANA
+TNVPISIPSRNWAAFRGWAFTRLKTKETPSLGSGYDPYYTYSGSIPYLDGTFYLNHTFKK
+VAITFDSSVSWPGNDRLLTPNEFEIKRSVDGEGYNVAQCNMTKDWFLVQMLANYNIGYQG
+FYIPESYKDRMYSFFRNFQPMSRQVVDDTKYKDYQQVGILHQHNNSGFVGYLAPTMREGQ
+AYPANFPYPLIGKTAVDSITQKKFLCDRTLWRIPFSSNFMSMGALTDLGQNLLYANSAHA
+LDMTFEVDPMDEPTLLYVLFEVFDVVRVHRPHRGVIETVYLRTPFSAGNATT
+>VSVg_Indiana|P03522 len=511
+MKCLLYLAFLFIGVNCKFTIVFPHNQKGNWKNVPSNYHYCPSSSDLNWHNDLIGTAIQVK
+MPKSHKAIQADGWMCHASKWVTTCDFRWYGPKYITQSIRSFTPSVEQCKESIEQTKQGTW
+LNPGFPPQSCGYATVTDAEAVIVQVTPHHVLVDEYTGEWVDSQFINGKCSNYICPTVHNS
+TTWHSDYKVKGLCDSNLISMDITFFSEDGELSSLGKEGTGFRSNYFAYETGGKACKMQYC
+KHWGVRLPSGVWFEMADKDLFAAARFPECPEGSSISAPSQTSVDVSLIQDVERILDYSLC
+QETWSKIRAGLPISPVDLSYLAPKNPGTGPAFTIINGTLKYFETRYIRVDIAAPILSRMV
+GMISGTTTERELWDDWAPYEDVEIGPNGVLRTSSGYKFPLYMIGHGMLDSDLHLSSKAQV
+FEHPHIQDAASQLPDDESLFFGDTGLSKNPIELVEGWFSSWKSSIASFFFIIGLIIGLFL
+VLRVGIHLCIKLKHTKKRQIYTDIEMNRLGK
+>HSV1_gD|P57083 len=394
+MGGTAARLGAVILFVVIVGLHGVRGKYALADASLKMADPNRFRGKDLPVLDQLTDPPGVR
+RVYHIQAGLPDPFQPPSLPITVYYAVLERACRSVLLNAPSEAPQIVRGASEDVRKQPYNL
+TIAWFRMGGNCAIPITVMEYTECSYNKSLGACPIRTQPRWNYYDSFSAVSEDNLGFLMHA
+PAFETAGTYLRLVKINDWTEITQFILEHRAKGSCKYALPLRIPPSACLSPQAYQQGVTVD
+SIGMLPRFIPENQRTVAVYSLKIAGWHGPKAPYTSTLLPPELSETPNATQPELAPEDPED
+SALLEDPVGTVAPQIPPNWHIPSIQDAATPYHPPATPNNMGLIAGAVGGSLLAALVICGI
+VYWMHRRTRKAPKRIRLPHIREDDQPSSHQPLFY
+>HSV1_gB|P06437 len=904
+MHQGAPSWGRRWFVVWALLGLTLGVLVASAAPTSPGTPGVAAATQAANGGPATPAPPPLG
+AAPTGDPKPKKNKKPKNPTPPRPAGDNATVAAGHATLREHLRDIKAENTDANFYVCPPPT
+GATVVQFEQPRRCPTRPEGQNYTEGIAVVFKENIAPYKFKATMYYKDVTVSQVWFGHRYS
+QFMGIFEDRAPVPFEEVIDKINAKGVCRSTAKYVRNNLETTAFHRDDHETDMELKPANAA
+TRTSRGWHTTDLKYNPSRVEAFHRYGTTVNCIVEEVDARSVYPYDEFVLATGDFVYMSPF
+YGYREGSHTEHTTYAADRFKQVDGFYARDLTTKARATAPTTRNLLTTPKFTVAWDWVPKR
+PSVCTMTKWQEVDEMLRSEYGGSFRFSSDAISTTFTTNLTEYPLSRVDLGDCIGKDARDA
+MDRIFARRYNATHIKVGQPQYYQANGGFLIAYQPLLSNTLAELYVREHLREQSRKPPNPT
+PPPPGASANASVERIKTTSSIEFARLQFTYNHIQRHVNDMLGRVAIAWCELQNHELTLWN
+EARKLNPNAIASVTVGRRVSARMLGDVMAVSTCVPVAADNVIVQNSMRISSRPGACYSRP
+LVSFRYEDQGPLVEGQLGENNELRLTRDAIEPCTVGHRRYFTFGGGYVYFEEYAYSHQLS
+RADITTVSTFIDLNITMLEDHEFVPLEVYTRHEIKDSGLLDYTEVQRRNQLHDLRFADID
+TVIHADANAAMFAGLGAFFEGMGDLGRAVGKVVMGIVGGVVSAVSGVSSFMSNPFGALAV
+GLLVLAGLAAAFFAFRYVMRLQSNPMKALYPLTTKELKNPTNPDASGEGEEGGDFDEAKL
+AEAREMIRYMALVSAMERTEHKAKKKGTSALLSAKVTDMVMRKRRNTNYTQVPNKDGDAD
+EDDL

{pen_stack-5.2.0 → pen_stack-5.3.0}/configs/oracles/scope_cards.yaml

@@ -125,3 +125,16 @@ oracles:
       classes with too few catalogued sites (flagged extrapolating)"
     generalizes_to_unseen_loci: false
     license: "open (this work; VISDB 10.1093/nar/gkz867, COSMIC CGC 10.1038/s41568-018-0060-1)"
+
+  capsid_epitope:               # v5.3 WS-EPITOPE: computed capsid/envelope CD8 T-cell epitope load
+    family: protein_design
+    version: "mhcflurry2.0-2026"
+    output_kind: baseline       # sequence-intrinsic presentation comparator, not generative
+    valid_for: "RELATIVE adaptive (CD8 / MHC-I) immunogenicity ordering of VIRAL vector capsids/envelopes via
+      the fraction of the antigen presentable across a frequent HLA-I panel (MHCflurry %rank<=0.5), from
+      UniProt-sourced sequences; population-level, sequence-intrinsic"
+    not_valid_for: "the realized in-vivo / PATIENT-HLA-specific T-cell response (a known-unknown); antibody /
+      neutralizing-antibody (B-cell) immunity (this is CD8/MHC-I only); non-viral vehicles (no capsid protein);
+      a viral vehicle whose antigen sequence is not committed (abstains)"
+    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)"

{pen_stack-5.2.0 → pen_stack-5.3.0}/pen_stack/__init__.py

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

{pen_stack-5.2.0 → pen_stack-5.3.0}/pen_stack/agent/cite.py

@@ -29,12 +29,13 @@ def curated_dois() -> frozenset[str]:
     for v in veh.values():
         dois.update(v.get("dois", []) or [])
         dois.update((v.get("immune_safety") or {}).get("immune_dois", []) or [])  # v5.1 immune priors
-    # v5.2 computed-genotoxicity oracle provenance (VISDB, COSMIC CGC, integration-biology refs)
-    try:
-        gt = yaml.safe_load(resource("configs/genotoxicity_oracle.yaml").read_text(encoding="utf-8"))
-        dois.update(gt.get("provenance_dois", []) or [])
-    except FileNotFoundError:
-        pass
+    # v5.2/v5.3 computed-oracle provenance (genotoxicity: VISDB/COSMIC; capsid epitope: MHCflurry/HLA)
+    for _art in ("configs/genotoxicity_oracle.yaml", "configs/capsid_epitope_oracle.yaml"):
+        try:
+            a = yaml.safe_load(resource(_art).read_text(encoding="utf-8"))
+            dois.update(a.get("provenance_dois", []) or [])
+        except FileNotFoundError:
+            pass
     gsh = yaml.safe_load(resource("configs/gsh_validated_heldout.yaml").read_text(encoding="utf-8"))["gsh"]
     for g in gsh:
         if g.get("doi"):

pen_stack-5.3.0/pen_stack/planner/capsid_epitope_oracle.py

@@ -0,0 +1,97 @@
+"""Computed capsid/envelope T-cell epitope-load oracle for viral delivery vectors (v5.3, WS-EPITOPE).
+
+Refines the documented `adaptive_immune` (CD8 T-cell) tier with a DATA-COMPUTED signal for VIRAL vectors: the
+fraction of the capsid/envelope antigen that is presentable across a frequent HLA-I panel (MHCflurry %rank
+<= 0.5), from configs/capsid_epitope_oracle.yaml (built by scripts/p53_build_epitope_oracle.py in the dedicated
+`penstack:mhcflurry` image over UniProt-sourced sequences).
+
+    capsid_immune_score = 1 - epitope_fraction_strong      # 1 = least presentable / least immunogenic
+
+This is the NetMHC-style calculation the user asked for, made population-level (averaged over a frequent-allele
+panel) so it is NOT a patient-HLA-specific magnitude. Answers through the v4.0 OracleResult contract
+(output_kind="baseline").
+
+Coverage of the whole palette: VIRAL vectors (AAV, lentivirus[VSV-G], HDAd, HSV) get a computed score;
+NON-VIRAL vectors (LNP-mRNA, eVLP, electroporation) have no foreign capsid protein -> score 1.0 by mechanism;
+a viral vector with no committed antigen sequence -> ABSTAINS (never fabricates).
+
+HONESTY: this is a population-level, sequence-intrinsic PRESENTATION signal (does the capsid contain HLA
+binders), NOT the realized in-vivo / patient-HLA-specific T-cell response (a known-unknown); it is also CD8
+(MHC-I) only - it does not model antibody / neutralizing-antibody (B-cell) immunity.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.oracles.schema import OracleResult, Provenance
+from pen_stack.planner.delivery_vehicles import vehicle
+
+_SCOPE_CARD = "capsid_epitope"
+# non-viral vehicles have no foreign capsid/envelope protein -> no capsid CD8 epitope load (1.0 by mechanism).
+_NON_VIRAL = {"lnp_mrna", "evlp", "electroporation"}
+
+
+@lru_cache(maxsize=1)
+def _artifact() -> dict:
+    return yaml.safe_load(resource("configs/capsid_epitope_oracle.yaml").read_text(encoding="utf-8"))
+
+
+def _prov(**extra) -> Provenance:
+    art = _artifact()
+    return Provenance(model="mhcflurry_capsid_epitope", version=str(art.get("version", "1.0")), source="cache",
+                      extra={"built": art.get("built"), "predictor": art.get("method", {}).get("predictor"),
+                             "provenance_dois": art.get("provenance_dois", []), **extra})
+
+
+def capsid_epitope_oracle(vehicle_name: str) -> OracleResult:
+    """Computed capsid CD8 epitope load for a delivery vehicle, as an OracleResult (v4.0 contract).
+
+    - viral vehicle with a committed antigen -> computed `capsid_immune_score` from MHCflurry x HLA panel.
+    - non-viral vehicle -> 1.0 by mechanism (no foreign capsid protein).
+    - unknown vehicle / viral-without-sequence -> available=False (caller falls back to the documented
+      adaptive_immune tier; no number fabricated)."""
+    rec = vehicle(vehicle_name)
+    if rec is None:
+        return OracleResult(oracle="protein_design", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                            in_scope=False, available=False, output_kind="baseline",
+                            note=f"unknown vehicle {vehicle_name!r}")
+
+    vehs = _artifact().get("vehicles") or {}
+    if vehicle_name in vehs:
+        v = vehs[vehicle_name]
+        ef = v["epitope_fraction_strong"]
+        return OracleResult(
+            oracle="protein_design",
+            value={"capsid_immune_score": v["capsid_immune_score"], "epitope_fraction_strong": ef,
+                   "antigens": v.get("antigens"),
+                   "hla_panel_size": len(_artifact().get("method", {}).get("hla_panel", []))},
+            provenance=_prov(antigens=v.get("antigens")), native_uncertainty=None,
+            scope_card=_SCOPE_CARD, in_scope=True, extrapolating=False, output_kind="baseline", available=True,
+            note=(f"{ef:.1%} of the {'/'.join(v.get('antigens', []))} antigen is presentable (MHCflurry "
+                  f"%rank<=0.5) across a frequent HLA-I panel; capsid_immune_score=1-epitope_fraction. "
+                  "Patient-HLA-specific T-cell response is a known-unknown (not modelled); CD8/MHC-I only "
+                  "(not antibody/NAb)."))
+
+    if vehicle_name in _NON_VIRAL:
+        return OracleResult(
+            oracle="protein_design",
+            value={"capsid_immune_score": 1.0, "epitope_fraction_strong": 0.0, "mechanism": "non-viral"},
+            provenance=_prov(), native_uncertainty=0.0, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note="non-viral vehicle: no foreign capsid/envelope protein -> no capsid CD8 epitope load (1.0).")
+
+    return OracleResult(oracle="protein_design", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                        in_scope=False, available=False, output_kind="baseline",
+                        note=f"viral vehicle {vehicle_name!r} has no committed antigen sequence; "
+                             "fall back to the documented adaptive_immune tier.")
+
+
+def computed_capsid_immune_score(vehicle_name: str) -> tuple[float | None, OracleResult]:
+    """Convenience: (capsid_immune_score or None, full OracleResult). None when the oracle abstains (caller
+    then uses the documented adaptive_immune tier). Never fabricates."""
+    r = capsid_epitope_oracle(vehicle_name)
+    val = (r.value or {}).get("capsid_immune_score") if (r.available and r.value) else None
+    return val, r

{pen_stack-5.2.0 → pen_stack-5.3.0}/pen_stack/planner/delivery_immunology.py

@@ -58,8 +58,28 @@ def safety_efficacy_profile(name: str) -> dict | None:
     if rec is None:
         return None
     imm = rec.get("immune_safety") or {}
-    immune_present = [t for ax in _IMMUNE_AXES if (t := _tier(imm.get(ax))) is not None]
-    immune_score = (1.0 - (sum(immune_present) / len(immune_present)) / 2.0) if immune_present else None
+    # per immune axis -> a 0..1 "safety" score (1 = least immunogenic). The ADAPTIVE (CD8 T-cell) axis can be
+    # COMPUTED from the capsid epitope load (v5.3 WS-EPITOPE: MHCflurry x HLA panel over the capsid/envelope
+    # antigen). The computed signal is INTRINSIC antigen presentability; it only translates to a realized host
+    # response when the host is actually exposed to the capsid (IN-VIVO use). So it is folded into the adaptive
+    # axis only for in-vivo vehicles; for EX-VIVO-only viral vectors (e.g. lentivirus, whose VSV-G envelope is
+    # intrinsically epitope-dense but barely seen by the host ex vivo) it is surfaced but NOT folded, and the
+    # documented tier is kept. The other three axes stay documented ordinal tiers. No number is fabricated.
+    from pen_stack.planner.capsid_epitope_oracle import computed_capsid_immune_score
+    cap_score, cap_oracle = computed_capsid_immune_score(name)
+    in_vivo = bool(rec.get("in_vivo"))
+    axis_scores: dict[str, float | None] = {}
+    for ax in _IMMUNE_AXES:
+        t = _tier(imm.get(ax))
+        axis_scores[ax] = (1.0 - t / 2.0) if t is not None else None
+    adaptive_source = "documented"
+    if cap_score is not None and in_vivo:
+        axis_scores["adaptive_immune"] = cap_score          # in-vivo: host sees the capsid -> fold computed
+        adaptive_source = "computed"
+    elif cap_score is not None and not in_vivo:
+        adaptive_source = "computed_ex_vivo_muted"          # reported, but ex-vivo mutes the realized response
+    immune_present = [s for s in axis_scores.values() if s is not None]
+    immune_score = (sum(immune_present) / len(immune_present)) if immune_present else None
     # genotoxicity: prefer the COMPUTED oracle (v5.2 WS-GENOTOX: integration-site x COSMIC-oncogene
     # enrichment, from VISDB) for integrating vectors; fall back to the documented ordinal tier when the
     # oracle abstains. No number is fabricated either way.
@@ -79,6 +99,9 @@ def safety_efficacy_profile(name: str) -> dict | None:
         "vehicle": name,
         "tiers": {ax: imm.get(ax) for ax in (*_IMMUNE_AXES, _GENOTOX_AXIS)} | {"efficacy": imm.get("efficacy")},
         "immune_score": _r(immune_score),
+        "adaptive_source": adaptive_source,      # computed | computed_ex_vivo_muted | documented
+        "capsid_presentability_score": _r(cap_score),   # computed intrinsic capsid CD8 presentability (or None)
+        "adaptive_provenance": (cap_oracle.note if cap_score is not None else None),
         "genotox_score": _r(genotox_score),
         "genotox_source": genotox_source,        # "computed" (VISDBxCOSMIC oracle) | "documented" (ordinal tier)
         "genotox_provenance": (gtox_oracle.note if genotox_source == "computed" else None),

{pen_stack-5.2.0 → pen_stack-5.3.0}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 5.2.0
+Version: 5.3.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
@@ -91,7 +91,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-5.2.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-5.3.0-blue.svg)](CHANGELOG.md)
 [![Tests](https://img.shields.io/badge/tests-240%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
 [![Runtime: Docker](https://img.shields.io/badge/runtime-docker-2496ED.svg)](docker/)
@@ -135,6 +135,22 @@ Two questions gate every genome-writing project, and before PEN-STACK no resourc
 Everything is built on bulk-downloadable public data, runs on a single GPU, and is validated **blind** against
 a pre-registered, honest baseline before release.
 
+## What is new in v5.3 — Computed capsid epitope-load oracle (covers all vectors)
+
+v5.2 computed genotoxicity only touches integrating vectors. v5.3 brings the **NetMHC-style calculation** to the
+**adaptive (CD8 T-cell)** axis: the fraction of a viral vector's capsid/envelope presentable across a frequent
+HLA-I panel (MHCflurry), so the computed immune signal now **covers all 8 vehicles** — 5 viral computed, 3
+non-viral by mechanism. It is a population-level, *sequence-intrinsic* presentation signal; the realized
+patient-HLA-specific T-cell response stays a known-unknown (and it is CD8/MHC-I only, not antibody).
+
+| Workstream | What it adds | Result |
+|---|---|---|
+| **EPITOPE build** | `scripts/p53_build_epitope_oracle.py` → committed `configs/capsid_epitope_oracle.yaml` | per viral capsid: `epitope_fraction_strong` over 9-mers × 12 HLA-I alleles (MHCflurry %rank ≤ 0.5), from UniProt-verified sequences (AAV2 VP1, Ad5 hexon, VSV-G, HSV gD/gB); MHCflurry stays on the VM, only the summary ships |
+| **EPITOPE oracle** | `planner/capsid_epitope_oracle.py` (`OracleResult`) | `capsid_immune_score = 1 − epitope_fraction_strong`; non-viral → 1.0 by mechanism; abstains when no sequence |
+| **wired into the adaptive axis** | folded **only for in-vivo** vehicles | AAV2 least epitope-dense (0.72), Ad5 hexon among the most (0.82) — documented adaptive ordering reproduced from sequence; **ex-vivo** lentivirus's intrinsic VSV-G load is *reported but muted* (host barely sees it ex vivo) |
+
+See `prereg/ws_epitope.yaml` and the `capsid_epitope` scope card.
+
 ## What is new in v5.2 — Computed genotoxicity oracle (data, not a documented tier)
 
 v5.1 scored genotoxicity as a documented `low/moderate/high` tier. v5.2 makes it **computed from data** for

{pen_stack-5.2.0 → pen_stack-5.3.0}/pen_stack.egg-info/SOURCES.txt

@@ -12,6 +12,8 @@ benchmarks/genome_writing_bench/SUBMISSIONS.md
 benchmarks/genome_writing_bench/tasks.yaml
 configs/atlas_families.yaml
 configs/bridge_offtarget_profile.yaml
+configs/capsid_epitope_oracle.yaml
+configs/capsid_sequences.fasta
 configs/cargo_polish.yaml
 configs/cell_types.yaml
 configs/datasets.yaml
@@ -150,6 +152,7 @@ pen_stack/oracles/rna.py
 pen_stack/oracles/schema.py
 pen_stack/oracles/structure.py
 pen_stack/planner/__init__.py
+pen_stack/planner/capsid_epitope_oracle.py
 pen_stack/planner/cargo.py
 pen_stack/planner/cargo_polish.py
 pen_stack/planner/delivery.py
@@ -243,6 +246,7 @@ prereg/SHA256_LOCK_ws_d.json
 prereg/SHA256_LOCK_ws_e.json
 prereg/SHA256_LOCK_ws_env.json
 prereg/SHA256_LOCK_ws_ep.json
+prereg/SHA256_LOCK_ws_epitope.json
 prereg/SHA256_LOCK_ws_f.json
 prereg/SHA256_LOCK_ws_g.json
 prereg/SHA256_LOCK_ws_genotox.json
@@ -279,6 +283,7 @@ prereg/ws_d.yaml
 prereg/ws_e.yaml
 prereg/ws_env.yaml
 prereg/ws_ep.yaml
+prereg/ws_epitope.yaml
 prereg/ws_f.yaml
 prereg/ws_g.yaml
 prereg/ws_genotox.yaml
@@ -304,5 +309,6 @@ scripts/p2_build_atlas.py
 scripts/p3_benchmark_report.py
 scripts/p4_genome_scan.py
 scripts/p52_build_genotox_oracle.py
+scripts/p53_build_epitope_oracle.py
 scripts/ws_b_report.py
 scripts/ws_c_report.py

pen_stack-5.3.0/prereg/SHA256_LOCK_ws_epitope.json

@@ -0,0 +1,8 @@
+{
+  "cycle": "v5.3",
+  "workstream": "WS-EPITOPE",
+  "prepared": "2026-06-10",
+  "sha256": {
+    "prereg/ws_epitope.yaml": "d69f145f8cfe80ae2c0bccbde17dc85ccdff31f354b0db0a6a9a10910d6b31e3"
+  }
+}

pen_stack-5.3.0/prereg/ws_epitope.yaml

@@ -0,0 +1,47 @@
+# PEN-STACK v5.3 - WS-EPITOPE (computed capsid CD8 T-cell epitope-load oracle). Directional.
+cycle: "v5.3"
+workstream: "WS-EPITOPE"
+prepared: "2026-06-10"
+
+motivation: >
+  User: "continue. Also, we need to cover ALL the vectors." v5.2 computed genotoxicity only meaningfully
+  touches integrating vectors (lentivirus). The IMMUNE axis is where the rest of the palette has computable
+  signal. This adds the NetMHC-style calculation (the user's reference) for the adaptive (CD8 / MHC-I) axis,
+  covering every vehicle.
+
+deliverable: >
+  scripts/p53_build_epitope_oracle.py (VM, dedicated penstack:mhcflurry image) -> committed
+  configs/capsid_epitope_oracle.yaml; pen_stack/planner/capsid_epitope_oracle.py (OracleResult); wired into
+  delivery_immunology.safety_efficacy_profile adaptive axis; scope card `capsid_epitope`;
+  configs/capsid_sequences.fasta (UniProt-sourced, committed).
+
+method: >
+  For each VIRAL vector's capsid/envelope antigen, slide overlapping 9-mers and predict MHCflurry 2.0 affinity
+  percentile rank PER allele across a frequent HLA-I panel (12 alleles, Sidney 2008 supertypes); a 9-mer is a
+  STRONG binder for an allele at %rank <= 0.5; epitope_fraction_strong = residues covered by >=1 strong-binder
+  9-mer / length; capsid_immune_score = 1 - epitope_fraction_strong. Sequences (UniProt, verified): AAV2 VP1
+  P03135; Ad5 hexon P04133; VSV-G Indiana P03522 (lentivirus pseudotyping antigen); HSV-1 gD P57083 + gB P06437
+  (averaged). Population-level (panel-averaged), NOT patient-HLA-specific. MHCflurry [10.1016/j.cels.2020.06.010];
+  HLA-I supertypes [10.1186/1471-2172-9-1]. Committed sequences -> reproducible, no network at build. v4.0
+  OracleResult (output_kind="baseline").
+
+  INTRINSIC vs REALIZED: the computed score is INTRINSIC antigen presentability. It is folded into the adaptive
+  axis ONLY for IN-VIVO vehicles (host is exposed to the capsid). For EX-VIVO-only viral vectors (lentivirus,
+  whose VSV-G envelope is intrinsically epitope-dense but barely seen ex vivo) the score is REPORTED but NOT
+  folded (adaptive_source = computed_ex_vivo_muted); the documented tier is kept.
+
+acceptance: >
+  (1) every VIRAL vector gets a computed capsid_immune_score from MHCflurry x HLA panel; non-viral vectors are
+  1.0 by mechanism; ALL 8 vehicles covered (available). (2) the computed ordering is consistent with the
+  documented tiers (AAV2 capsid less epitope-dense than Ad5 hexon -> AAV less immunogenic than HDAd). (3) the
+  computed score folds into the adaptive axis for in-vivo vehicles and is muted (reported, not folded) for
+  ex-vivo lentivirus. (4) the oracle ABSTAINS for an unknown / sequence-less vehicle (never fabricates).
+  (5) provenance + accessions verified (UniProt) / curated (DOIs).
+
+honesty_invariant: >
+  Population-level, sequence-intrinsic PRESENTATION signal (does the capsid contain HLA binders) - NOT the
+  realized in-vivo / PATIENT-HLA-specific T-cell response (a known-unknown), and CD8 / MHC-I ONLY (not antibody
+  / neutralizing-antibody / B-cell). The immune MAGNITUDE stays `in_vivo_immunogenicity`. No magnitude predicted.
+
+gate: "all 8 vehicles covered (5 viral computed + 3 non-viral by mechanism); AAV<Ad epitope ordering; in-vivo folds / ex-vivo muted; abstains not fabricates; provenance verified; no-fabrication intact."
+locked_files: [prereg/ws_epitope.yaml]

{pen_stack-5.2.0 → pen_stack-5.3.0}/pyproject.toml

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