pen-stack 0.1.0__py3-none-any.whl

pen_stack/oracles/schema.py

@@ -0,0 +1,77 @@
+"""The oracle contract, one uniform result type for every foundation model.
+
+PEN-STACK is the composition + verification layer *on top of* the biomolecular foundation models
+(AlphaGenome, Evo2, AlphaFold3, Boltz-2, Chai-1, Protenix, ESM3, RFdiffusion, ProteinMPNN, ViennaRNA, ...).
+Every oracle, however different internally, answers through ONE contract:
+
+    predict(...) -> OracleResult{value, provenance(model+version), native_uncertainty, scope}
+
+Three invariants are encoded in the type itself:
+  1. **A generative output is a candidate, never a claim**, `candidate=True` outputs cannot enter a claim
+     path without passing writer-verification (`as_claim()` raises; a guard test asserts it).
+  2. **One contract for every oracle**, provenance (model+version) and the oracle's *native* uncertainty are
+     always carried, never discarded; every call is cache-keyed on inputs+model+version.
+  3. **Scope is explicit**, each result carries the id of its oracle's scope card and an `extrapolating`
+     flag; the field's evidence that these models do not generalize to unseen loci is *labelled*, not hidden.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+OutputKind = Literal["claim", "candidate", "baseline"]
+
+
+class Provenance(BaseModel):
+    """Immutable (frozen): once an oracle stamps a result with its model, version, and source, that record
+    cannot be edited after the fact. Frozen here as well as on OracleResult, since a frozen OracleResult with
+    a mutable Provenance would still let a caller rewrite `model`/`version`/`source` on the nested object."""
+    model_config = ConfigDict(frozen=True)
+
+    model: str # e.g. "boltz-2", "alphagenome", "evo2"
+    version: str # pinned model/version string
+    source: str = "adapter" # adapter | cache | hosted_api | local_gpu
+    cache_key: str | None = None
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class OracleResult(BaseModel):
+    """The single result type returned by every oracle adapter.
+
+    Frozen (immutable) so the scope, provenance, and availability an oracle reports cannot be edited after the
+    fact: once an adapter returns a result, no downstream caller (or agent step) can flip `available`,
+    `in_scope`, `output_kind`, or `extrapolating` to launder a candidate into a claim or hide extrapolation.
+    `as_claim()` therefore *filters* (returns self or raises), it never mutates. Build a changed copy with
+    `model_copy(update=...)` if a transform genuinely needs one; that yields a new, separately-provenanced
+    result rather than silently rewriting an existing one."""
+    model_config = ConfigDict(frozen=True)
+
+    oracle: str # family: genome | structure | protein_design | rna | energetics
+    value: Any | None # the prediction (kind depends on the oracle)
+    provenance: Provenance
+    native_uncertainty: float | None = None # the oracle's OWN uncertainty (e.g. 1 - pLDDT), surfaced not hidden
+    scope_card: str | None = None # id of the scope card stating what this oracle is valid for
+    in_scope: bool = True # input falls within the scope card
+    extrapolating: bool = False # OOD relative to the oracle's training/validity envelope
+    output_kind: OutputKind = "claim" # claim | candidate (generative) | baseline (comparator)
+    available: bool = True # backend present + ran (False -> deferred, value may be cached/None)
+    cached: bool = False
+    note: str | None = None
+
+    @property
+    def is_candidate(self) -> bool:
+        return self.output_kind == "candidate"
+
+    def as_claim(self) -> "OracleResult":
+        """Return self for use in a claim path, or RAISE if this is a generative candidate (Principle 1).
+
+        A generated sequence/structure/backbone (Evo2/ESM3/RFdiffusion/ProteinMPNN) is a *proposal*; it must be
+        scored against measured data through writer-verification before any claim. This guard makes the
+        pen-assemble lesson (0 validatable de-novo writers) un-bypassable in code."""
+        if self.is_candidate:
+            raise ValueError(
+                f"oracle '{self.provenance.model}' returned a CANDIDATE ({self.oracle}); it cannot enter a "
+                "claim path without writer-verification scoring (Principle 1). Call "
+                "pen_stack.atlas.writer_verify on it first.")
+        return self

pen_stack/oracles/status.py

@@ -0,0 +1,123 @@
+"""Live-oracle status + latency surface (PEN-STACK).
+
+Reports, for every foundation-model oracle, HOW it executes, its per-query LATENCY CLASS, and whether it is
+currently LIVE (or why not), so the assistant can tell the user the cost up front ("this runs on the GPU,
+~1 min" / "this is a long cloud job, run it separately") and never silently blocks. The static map lives in
+`configs/oracles/execution.yaml`; this module adds the runtime liveness check (key present? server up?).
+"""
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def execution_map() -> dict:
+    import yaml
+    return yaml.safe_load(resource("configs/oracles/execution.yaml").read_text(encoding="utf-8"))["oracles"]
+
+
+def _net_on() -> bool:
+    return os.getenv("PEN_STACK_ORACLE_NET") == "1"
+
+
+def _alphagenome_key() -> bool:
+    if os.getenv("ALPHAGENOME_API_KEY"):
+        return True
+    try:
+        return resource("configs/alphagenome_api_key.txt").exists()
+    except Exception: # noqa: BLE001
+        return False
+
+
+def _nvidia_key() -> bool:
+    if os.getenv("NVIDIA_API_KEY"):
+        return True
+    try:
+        return resource("configs/nvidia_api_key.txt").exists()
+    except Exception: # noqa: BLE001
+        return False
+
+
+_SERVER_ENV = {"proteinmpnn": ("PEN_STACK_PROTEINMPNN_URL", "http://localhost:9011"),
+               "esm3": ("PEN_STACK_ESM3_URL", "http://localhost:9012"),
+               "rfdiffusion": ("PEN_STACK_RFDIFFUSION_URL", "http://localhost:9013")}
+
+
+def _server_up(model: str) -> bool:
+    env, default = _SERVER_ENV[model]
+    url = os.getenv(env, default).rstrip("/")
+    try:
+        import requests
+        return requests.get(f"{url}/health", timeout=2).status_code == 200
+    except Exception: # noqa: BLE001
+        return False
+
+
+def _is_live(model: str, card: dict, probe: bool) -> tuple[bool, str]:
+    ex = card.get("execution")
+    if ex == "in_process":
+        return True, "runs in-process"
+    if card.get("live") is False or ex in {"deferred", "cloud_a100"}:
+        return False, card.get("note", "not active")
+    if ex == "hosted_api":
+        if not _net_on():
+            return False, "set PEN_STACK_ORACLE_NET=1 to enable live calls"
+        if model == "alphagenome":
+            if not _alphagenome_key():
+                return False, "add configs/alphagenome_api_key.txt"
+            try:
+                from pen_stack.wgenome.providers import package_available
+                if not package_available():
+                    return False, "pip install alphagenome"
+            except Exception: # noqa: BLE001
+                return False, "alphagenome package unavailable"
+        if model == "evo2" and not _nvidia_key():
+            return False, "add configs/nvidia_api_key.txt"
+        return True, "hosted API ready"
+    if ex == "local_gpu":
+        if not _net_on():
+            return False, "set PEN_STACK_ORACLE_NET=1"
+        if probe:
+            return (_server_up(model), "server up" if _server_up(model) else "model server not running (start it on demand)")
+        return True, "enabled (start the model server on demand)"
+    return False, "unknown execution"
+
+
+def oracle_status(probe: bool = False) -> dict:
+    """Per-oracle execution + latency_class + live status + published reliability. `probe=True` pings the local
+    model servers (adds a short network check); default is config-level only. Reliability is the wrapped model's
+    PUBLISHED benchmark accuracy, reported verbatim with citation, never a claim about this stack's accuracy."""
+    try:
+        from pen_stack.oracles.reliability import all_reliability
+        rel = all_reliability()
+    except Exception: # noqa: BLE001
+        rel = {}
+    out = {}
+    for model, card in execution_map().items():
+        live, why = _is_live(model, card, probe)
+        out[model] = {"execution": card.get("execution"), "latency_class": card.get("latency_class"),
+                      "live": live, "status": why, "note": card.get("note", ""),
+                      "server": card.get("server"), "reliability": rel.get(model)}
+    return out
+
+
+def summary() -> dict:
+    """Compact roll-up for the capability manifest + the chat meta facts."""
+    st = oracle_status(probe=False)
+    live = sorted(m for m, s in st.items() if s["live"])
+    held = sorted(m for m, s in st.items() if s["execution"] == "cloud_a100")
+    deferred = sorted(m for m, s in st.items() if s["execution"] == "deferred")
+    out = {"live": live, "held_cloud": held, "deferred": deferred,
+           "latency_classes": {m: s["latency_class"] for m, s in st.items()},
+           "note": ("Live oracles answer in seconds, ~2 min; held cloud jobs (AF3/Boltz/Chai/Protenix) are run "
+                    "separately and never block; deferred outcomes are known-unknowns, never fabricated.")}
+    try:
+        from pen_stack.oracles.reliability import disagreement_widens_monotonically, disclaimer
+        out["reliability_note"] = disclaimer()
+        out["disagreement_to_interval"] = disagreement_widens_monotonically()
+    except Exception: # noqa: BLE001
+        pass
+    return out

pen_stack/oracles/structure.py

@@ -0,0 +1,42 @@
+"""Structure oracles, AlphaFold3 / Boltz-2 / Chai-1 / Protenix, with cross-oracle consistency.
+
+Each predictor returns structure confidence (pLDDT-like) under the oracle contract, with the model's native
+uncertainty surfaced (1 − pLDDT). Where redundant oracles are available, `consistency()` combines them: their
+agreement is a confidence signal and **their disagreement widens the reported interval** (Principle 3).
+Heavy backends run on-demand (hosted/local GPU) and are cached; absent → deferred / cache replay.
+"""
+from __future__ import annotations
+
+from pen_stack.oracles import build_result, cache_get, consensus
+from pen_stack.oracles.schema import OracleResult
+
+_STRUCT_MODELS = ["alphafold3", "boltz-2", "chai-1", "protenix"]
+_BACKEND = {"alphafold3": "alphafold3", "boltz-2": "boltz", "chai-1": "chai_lab", "protenix": "protenix"}
+
+
+def predict_structure(sequence: str, model: str = "boltz-2") -> OracleResult:
+    """Predict a structure's confidence with one model (pLDDT-like). Deferred / cache-replayed if absent."""
+    if model not in _STRUCT_MODELS:
+        raise ValueError(f"unknown structure model {model!r}; choose from {_STRUCT_MODELS}")
+    inputs = {"seq_len": len(sequence), "seq": sequence.upper(), "model": model}
+    r = build_result("structure", model, inputs=inputs, available=False,
+                     note=f"{model} backend not installed (on-demand hosted/local GPU)")
+    hit = cache_get(r.provenance.cache_key)
+    if hit is not None:
+        return build_result("structure", model, inputs=inputs, value=hit.get("value"),
+                            native_uncertainty=hit.get("native_uncertainty"), available=True, cached=True,
+                            source="cache", note="replayed from committed oracle cache")
+    try:
+        __import__(_BACKEND[model])
+    except Exception: # noqa: BLE001
+        return r
+    return build_result("structure", model, inputs=inputs, available=False,
+                        note=f"{model} present; wire the predictor for the live pLDDT/PAE value")
+
+
+def consistency(sequence: str, models: list[str] | None = None) -> OracleResult:
+    """Cross-oracle self-consistency over the available structure predictors; divergence widens the interval."""
+    models = models or _STRUCT_MODELS
+    results = [predict_structure(sequence, m) for m in models]
+    out = consensus(results, oracle="structure")
+    return out.model_copy(update={"note": (out.note or "") + f" | members tried: {models}"})

pen_stack/oracles/structure_run.py

@@ -0,0 +1,76 @@
+"""Off-request structure-oracle runner over named genome-writing complexes.
+
+The structure oracles (AlphaFold3 / Boltz-2 / Chai-1 / Protenix) are held: a full complex prediction is a long
+GPU / cloud batch, so it runs OFF the request path and the result is cached; the request path only ever replays
+the cache or abstains (:func:`pen_stack.oracles.structure.consistency`). This module names the writer-substrate /
+att-site complexes the substrate cares about, exposes a cache-or-abstain :func:`get` over the cross-oracle
+consistency, and an :func:`ingest_boltz_confidence` hook that folds a completed off-request Boltz run's confidence
+(pLDDT / pTM) into the cache so the request path can replay it.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pen_stack.oracles import build_result, cache_put
+from pen_stack.oracles.schema import OracleResult
+from pen_stack.oracles.structure import consistency, predict_structure
+
+# Named complexes relevant to genome writing. Sequences are supplied at call time; these entries describe what a
+# held off-request run would target. `kind` records why a structure oracle is or is not the right tool.
+_COMPLEXES = {
+    "ert2_4oht": {
+        "description": "ERT2 ligand-binding domain (human ESR1, UniProt P03372 res 305-554) with "
+                       "4-hydroxytamoxifen, the inducible-writer chemical switch",
+        "kind": "protein_ligand"},
+    "bxb1_attb": {
+        "description": "Bxb1 serine integrase engaging its attB DNA target",
+        "kind": "protein_dna"},
+    "prime_editor_target": {
+        "description": "Prime editor (Cas9 nickase-RT fusion) engaging its primed genomic target",
+        "kind": "protein_dna"},
+}
+
+
+def complexes() -> dict:
+    """The registry of named writer-substrate / att-site complexes a held structure run would target."""
+    return dict(_COMPLEXES)
+
+
+def get(protein_seq: str, models: list[str] | None = None) -> OracleResult:
+    """Cross-oracle structure consistency for a complex's protein, cache-or-abstain (never runs the long job).
+
+    Replays committed structure-oracle caches and combines them; divergence widens the interval. When no backend
+    has been run off-request and cached, the consensus is unavailable (a deferred result), never fabricated.
+    """
+    return consistency(protein_seq, models)
+
+
+def single(protein_seq: str, model: str = "boltz-2") -> OracleResult:
+    """One structure oracle's confidence for a sequence (cache-replayed if present, else deferred)."""
+    return predict_structure(protein_seq, model)
+
+
+def ingest_boltz_confidence(protein_seq: str, out_dir: str | Path, model: str = "boltz-2") -> str:
+    """Fold a completed OFF-REQUEST Boltz run's confidence into the structure cache, keyed as ``predict_structure``.
+
+    Reads Boltz's ``confidence_*.json`` (``complex_plddt`` on a 0-1 scale) and caches a pLDDT-like value with
+    native uncertainty ``1 - pLDDT``, so :func:`predict_structure` (and thus :func:`get`) replays it. Returns the
+    cache key. Called after a separate GPU batch completes; never on the request path.
+    """
+    out = Path(out_dir)
+    cj = sorted(p for p in out.rglob("confidence*.json"))
+    if not cj:
+        raise FileNotFoundError(f"no confidence*.json under {out}")
+    d = json.loads(cj[0].read_text(encoding="utf-8"))
+    plddt = d.get("complex_plddt")
+    if plddt is None:
+        raise KeyError(f"complex_plddt absent in {cj[0].name}")
+    plddt = float(plddt)
+    if plddt > 1.0:  # some writers report 0-100; normalise to 0-1
+        plddt = plddt / 100.0
+    inputs = {"seq_len": len(protein_seq), "seq": protein_seq.upper(), "model": model}
+    key = build_result("structure", model, inputs=inputs, available=False).provenance.cache_key
+    cache_put(key, {"value": round(plddt, 4), "native_uncertainty": round(1.0 - plddt, 4),
+                    "ptm": d.get("ptm"), "iptm": d.get("iptm"), "source_file": cj[0].name})
+    return key

pen_stack/oracles/vcell.py

@@ -0,0 +1,74 @@
+"""Virtual-cell outcome oracles, Arc STATE / scGPT under the OracleResult contract.
+
+A perturbation-response prediction is a CANDIDATE (a hypothesis), never a claim. It is OOD-gated: a cell context
+or perturbation outside the model's documented validity envelope sets `extrapolating=True` / `in_scope=False`,
+because the field's own evidence (Arc's Virtual Cell Challenge) is that perturbation models do not yet
+consistently beat naive baselines and do not generalize to unseen contexts. Heavy backends run on-demand and are
+cached; absent → deferred / cache replay (the value may be None, never fabricated).
+"""
+from __future__ import annotations
+
+import os
+
+from pen_stack.oracles import build_result, cache_get, cache_put
+from pen_stack.oracles.schema import OracleResult
+
+# documented in-distribution envelope (representative trained human cell contexts + perturbation kinds).
+_IN_DISTRIBUTION_CONTEXTS = {
+    "k562", "hepg2", "jurkat", "hek293", "hek293t", "h1_hesc", "h1", "a549", "thp1", "raw264",
+    "hela", "mcf7", "ipsc", "pbmc", "cd4_t", "cd8_t", "hspc",
+}
+_VALID_PERTURBATION_KINDS = {"genetic", "crispr", "knockout", "knockdown", "overexpression",
+                             "chemical", "drug", "cytokine"}
+
+
+def _normalize(s) -> str:
+    return str(s or "").strip().lower().replace("-", "").replace(" ", "")
+
+
+def in_distribution(cell_state: str, perturbation: dict) -> bool:
+    """True iff the cell context is a documented trained context AND the perturbation kind is supported."""
+    ctx_ok = _normalize(cell_state) in {_normalize(c) for c in _IN_DISTRIBUTION_CONTEXTS}
+    kind = _normalize(perturbation.get("kind") or perturbation.get("type"))
+    kind_ok = (not kind) or kind in {_normalize(k) for k in _VALID_PERTURBATION_KINDS}
+    return bool(ctx_ok and kind_ok)
+
+
+def predict_response(cell_state: str, perturbation: dict, *, model: str = "state",
+                     live: bool = False) -> OracleResult:
+    """Virtual-cell outcome oracle (Arc STATE / scGPT). OOD-gated: a context outside the scope card ->
+    `extrapolating`, never a confident claim. Cached/deferred when the backend is absent (replay is CI default)."""
+    extrap = not in_distribution(cell_state, perturbation)
+    inputs = {"cell_state": cell_state, "perturbation": perturbation, "live": bool(live)}
+    key_obj = build_result("vcell", model, inputs=inputs)
+    hit = cache_get(key_obj.provenance.cache_key)
+    if hit is not None:
+        return build_result("vcell", model, inputs=inputs, value=hit.get("value"),
+                            native_uncertainty=hit.get("native_uncertainty"), available=True, cached=True,
+                            source="cache", extrapolating=extrap, in_scope=not extrap,
+                            note="replayed from committed oracle cache")
+    # Live hook (uniform with the other oracles): a State *Transition* server can be stood up to predict a
+    # perturbation response; if PEN_STACK_VCELL_URL is set + up, use it. No such server ships by default,
+    # Arc STATE's SE-600M only EMBEDS cells (needs an scRNA AnnData), while a real perturbation OUTCOME needs
+    # the ST model + a reference cell population. So this path normally defers, and we DO NOT fabricate a number.
+    url = os.getenv("PEN_STACK_VCELL_URL")
+    if os.getenv("PEN_STACK_ORACLE_NET") == "1" and url:
+        try:
+            import requests
+            resp = requests.post(f"{url.rstrip('/')}/predict",
+                                 json={"cell_state": cell_state, "perturbation": perturbation},
+                                 timeout=float(os.getenv("PEN_STACK_MODEL_TIMEOUT", "300"))).json()
+            cache_put(key_obj.provenance.cache_key, {"value": resp})
+            return build_result("vcell", model, inputs=inputs, value=resp, available=True, source="local_gpu",
+                                extrapolating=extrap, in_scope=not extrap,
+                                note="Arc STATE transition server prediction (OOD-gated). Still a candidate hypothesis.")
+        except Exception: # noqa: BLE001 - server absent/down → defer
+            pass
+    # default: deferred (value None), the contract + OOD gate are real; the OUTCOME is a known-unknown
+    return build_result("vcell", model, inputs=inputs, value=None, available=False,
+                        extrapolating=extrap, in_scope=not extrap,
+                        note=(f"{model} perturbation-OUTCOME deferred; OOD={extrap}. The Arc STATE model is "
+                              "installable (`pip install arc-state`; SE-600M embeds cells), but a trustworthy "
+                              "perturbation response needs the State-Transition model + a reference scRNA "
+                              "population, and even SOTA does not yet consistently beat naive baselines (Arc VCC), "
+                              "so the magnitude stays a known-unknown rather than a fabricated number."))

pen_stack/planner/__init__.py

@@ -0,0 +1 @@
+"""pen_stack.planner - see the PEN-STACK program doc."""

pen_stack/planner/ada_risk.py

@@ -0,0 +1,64 @@
+"""ADA-risk.
+
+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 (real, NetMHCIIpan-4.0) x foreignness
+
+where **foreignness is the protein ORIGIN** (self vs bacterial/viral/phage), the authoritative, definitive
+self/non-self signal (central tolerance), not a heuristic. The **real human-proteome 9-mer self-match** (computed
+on the VM against the full UniProt human reference proteome) is reported as a cross-check. NO heuristic fallback:
+when the MHC-II density is not cached (NetMHCIIpan not run) OR the origin is unknown, ADA-risk **abstains** (an
+known-unknown) rather than guessing.
+
+a population-level proxy, never a patient-specific ADA titer (a known-unknown). The calibration
+against a public ADA-incidence set runs through the EXISTING calibrate_axis gate and stays at public-data power.
+"""
+from __future__ import annotations
+
+from pen_stack.planner.immune_mhc2 import _real_cache, mhc2_epitope_load, writer_sequences
+
+ADA_DOIS = ["10.1038/s41467-021-25414-9"] # Cas9 MHC-II CD4 immunogenicity (Simhadri 2021)
+_FOREIGN = {"self": 0.0, "foreign": 1.0}
+
+
+def real_self_match(name: str) -> dict | None:
+    """The REAL human-proteome 9-mer self-match for a bundled antigen (cross-check; computed on the VM against the
+    full UniProt human reference proteome). Foreign proteins ~0, human ~1. None if not in the cache."""
+    rec = (_real_cache().get("self_match") or {}).get(name)
+    if rec is None:
+        return None
+    return {"human_9mer_match_fraction": rec.get("fraction"), "n_9mers": rec.get("n"),
+            "reference": (_real_cache().get("self_match_meta") or {}).get("reference",
+                          "UniProt human reference proteome (full)")}
+
+
+def ada_risk(seq: str, origin: str | None = None, name: str | None = None) -> dict:
+    """ADA-risk = real MHC-II epitope density x foreignness(origin). Abstains (no proxy/heuristic) when the MHC-II
+    density is uncached or the origin is unknown. Higher ada_risk_score = MORE ADA risk; ada_immune_score = 1 - it."""
+    el = mhc2_epitope_load(seq, name)
+    density = el.get("epitope_density")
+    foreign = _FOREIGN.get(str(origin)) if origin is not None else None
+    sm = real_self_match(name) if name else None
+    base = {"epitope_density": density, "foreignness": foreign, "origin": origin,
+            "self_match_human_proteome": sm, "dois": ADA_DOIS,
+            "filter": "central tolerance: foreign (non-self) MHC-II epitopes drive ADA; self tolerated. Foreignness "
+                      "= protein origin (authoritative); MHC-II density = NetMHCIIpan-4.0; real human-proteome "
+                      "self-match reported as cross-check (no heuristic).",
+            "status": "population-level; patient ADA titer / magnitude is a known-unknown"}
+    if density is None or foreign is None:
+        return {**base, "ada_risk_score": None, "ada_immune_score": None, "backend": "abstain",
+                "note": ("abstains (no proxy): " + ("NetMHCIIpan-4.0 not run for this sequence" if density is None
+                         else "protein origin unknown, foreignness is not guessed"))}
+    risk = round(density * foreign, 4)
+    return {**base, "ada_risk_score": risk, "ada_immune_score": round(1.0 - risk, 4), "backend": "real"}
+
+
+def ada_risk_named(name: str) -> dict:
+    """ADA-risk for a bundled writer/control protein by name (uses its declared origin + the real MHC-II cache)."""
+    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)}

pen_stack/planner/antipeg_oracle.py

@@ -0,0 +1,75 @@
+"""Anti-PEG immunity axis for PEGylated LNP.
+
+Covers pre-existing / induced anti-PEG antibodies, which
+gate RE-DOSING of PEGylated LNP. Anti-PEG is a property of the PEGylation chemistry, not of any encoded
+sequence, so, exactly like the anti-vector seroprevalence oracle, it is grounded in published serosurvey
+DATA (configs/antipeg.yaml, a population prevalence range with DOIs):
+
+    preexisting_antipeg_score = 1 - midpoint(anti_PEG_prevalence_pct) / 100 # 1 = fewest excluded
+
+Answers through the OracleResult contract (output_kind="baseline"). ABSTAINS for non-PEGylated vehicles.
+SCOPE: a POPULATION prevalence (a range, region/age/assay-dependent), NOT a given patient's anti-PEG titer
+(a clinical test, patient-specific -> a known-unknown); induced anti-PEG after dose 1 is a separate, larger
+dynamic (noted, not modelled).
+"""
+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
+
+_SCOPE_CARD = "antipeg"
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict:
+    return yaml.safe_load(resource("configs/antipeg.yaml").read_text(encoding="utf-8"))
+
+
+def _all_dois() -> list[str]:
+    return list((_table().get("prevalence") or {}).get("dois", []) or [])
+
+
+def _prov(**extra) -> Provenance:
+    return Provenance(model="anti_peg_seroprevalence", version=str(_table().get("version", "1.0")),
+                      source="cache", extra=extra)
+
+
+def antipeg_oracle(vehicle_name: str, pegylated: bool | None = None) -> OracleResult:
+    """Anti-PEG pre-existing immunity for a vehicle, as an OracleResult.
+
+    - PEGylated vehicle -> preexisting_antipeg_score = 1 - midpoint(prevalence)/100 (gates RE-DOSING).
+    - non-PEGylated vehicle -> ABSTAINS (available=False, value=None): the anti-PEG axis is not applicable.
+    `pegylated` overrides the config's vehicle list when given. Never fabricates a patient titer."""
+    t = _table()
+    is_peg = pegylated if pegylated is not None else (vehicle_name in (t.get("pegylated_vehicles") or []))
+    if not is_peg:
+        return OracleResult(oracle="genome", value=None, provenance=_prov(), scope_card=_SCOPE_CARD,
+                            in_scope=False, available=False, output_kind="baseline",
+                            note=f"non-PEGylated vehicle {vehicle_name!r}: anti-PEG axis not applicable (abstains).")
+
+    rec = t["prevalence"]
+    lo, hi = rec["anti_peg_prevalence_pct"]
+    mid = (lo + hi) / 2.0
+    score = max(0.0, min(1.0, 1.0 - mid / 100.0))
+    return OracleResult(
+        oracle="genome",
+        value={"preexisting_antipeg_score": round(score, 3), "anti_peg_prevalence_pct": [lo, hi],
+               "midpoint_pct": mid, "gates": "re-dosing", "dois": rec.get("dois", [])},
+        provenance=_prov(dois=rec.get("dois", [])), native_uncertainty=round((hi - lo) / 200.0, 4),
+        scope_card=_SCOPE_CARD, in_scope=True, extrapolating=False, output_kind="baseline", available=True,
+        note=(f"population anti-PEG prevalence {lo}-{hi}% -> preexisting_antipeg_score={score:.3f}; gates "
+              "RE-DOSING of PEGylated LNP. A POPULATION range (region/age/assay-dependent) - NOT a patient's "
+              "anti-PEG titer (a known-unknown); induced anti-PEG after dose 1 is a separate, larger dynamic "
+              "(not modelled)."))
+
+
+def computed_antipeg_score(vehicle_name: str, pegylated: bool | None = None) -> tuple[float | None, OracleResult]:
+    """Convenience: (anti-PEG score or None, full OracleResult). None when the oracle abstains (non-PEG).
+    Never fabricates."""
+    r = antipeg_oracle(vehicle_name, pegylated)
+    val = (r.value or {}).get("preexisting_antipeg_score") if (r.available and r.value) else None
+    return val, r