pen-stack 0.1.0__py3-none-any.whl

pen_stack/planner/delivery_immune.py

@@ -0,0 +1,61 @@
+"""Immune-coupled delivery selection.
+
+Fuses the cross-modality deliverability recommendation with the per-axis immune-risk profile and
+surfaces the **dose <-> immunogenicity tradeoff** as a VECTOR, never collapsed into one number. The point: a vehicle
+that is most deliverable may carry the highest immune liability (e.g. AAV: efficient in vivo, but pre-existing NAbs +
+capsid CD8 + dose-dependent innate sensing), and that tension must be visible, not hidden.
+
+the immune axes are population-level proxies; the realized in-vivo magnitude / patient titer is a
+declared known-unknown. The dose<->immune tradeoff is informative, NOT a clinical dosing directive.
+"""
+from __future__ import annotations
+
+
+def _highest_risk_axis(design: dict) -> dict | None:
+    """The in-scope immune axis with the LOWEST score (= highest risk) from the immune-risk profile, with its value."""
+    from pen_stack.planner.immune_profile import immune_profile
+    axes = immune_profile(dict(design)).get("axes", {})
+    in_scope = {k: a for k, a in axes.items() if a.get("in_scope") and a.get("value") is not None}
+    if not in_scope:
+        return None
+    k = min(in_scope, key=lambda x: in_scope[x]["value"])
+    return {"axis": k, "score": in_scope[k]["value"], "note": in_scope[k].get("note")}
+
+
+def delivery_immune_tradeoff(cargo_form: str, cargo_bp: int | None = None, target_tissue: str | None = None,
+                             *, writer_family: str | None = None, serotype: str | None = None,
+                             safety_weight: float = 0.5, in_vivo: bool | None = None) -> dict:
+    """Rank deliverability AND attach each vehicle's immune profile, surfacing the dose<->immune tradeoff per
+    vehicle as a vector. Never collapses deliverability and immunogenicity into one score."""
+    from pen_stack.planner.delivery_predict import recommend_delivery_plus
+    rec = recommend_delivery_plus(cargo_form, cargo_bp, target_tissue, safety_weight=safety_weight,
+                                  in_vivo=in_vivo, serotype=serotype)
+    coupled = []
+    for prof in rec.get("ranked", []) or rec.get("eligible", []) or []:
+        veh = prof.get("vehicle") or prof.get("name")
+        if not veh:
+            continue
+        design = {"delivery_vehicle": veh, "serotype": serotype, "writer_family": writer_family}
+        risk = _highest_risk_axis(design)
+        coupled.append({
+            "vehicle": veh,
+            "deliverability_balance": prof.get("balance"),
+            "efficacy_score": prof.get("efficacy_score"),
+            "immune_highest_risk_axis": risk, # the dominant immune liability
+            "tradeoff": (f"deliverability {prof.get('balance')} vs dominant immune liability "
+                         f"'{risk['axis']}' (score {risk['score']})" if risk else
+                         "deliverability ranked; immune axes abstain for this vehicle"),
+        })
+    return {
+        "cargo_form": cargo_form, "cargo_bp": cargo_bp, "target_tissue": target_tissue,
+        "serotype_tropism_prior": rec.get("serotype_tropism_prior"),
+        "coupled": coupled,
+        "collapsed_score": None, # deliberately None, dose<->immune is a vector, NEVER fused
+        "dose_immune_note": ("AAV/viral vehicles are efficient in vivo but carry the highest immune liability "
+                             "(pre-existing NAbs, capsid CD8, dose-dependent innate sensing); higher dose raises both "
+                             "transduction AND immunogenicity. The tradeoff is surfaced per vehicle, never collapsed."),
+        "known_unknowns": ["in_vivo_immunogenicity_magnitude", "patient_specific_titer", "realized_dose_response"],
+        "honesty": "immune axes are population-level proxies; realized magnitude/titer is a known-unknown; "
+                   "this is decision-support, NOT a clinical dosing directive. No collapsed score.",
+        "no_fabrication": True,
+    }

pen_stack/planner/delivery_immunology.py

@@ -0,0 +1,222 @@
+"""Delivery safety<->efficacy balance over DOCUMENTED immune priors.
+
+Motivation (user): "we should be able to give a good balance between safety and efficacy. AAV is
+safe but neutralizing antibodies / pre-existing immunity will be there; lentivirus is highly efficacious at
+integrating but its safety is bad." This module turns the per-vehicle ``immune_safety`` block in
+configs/delivery_vehicles.yaml into a transparent, user-weightable ranking of the delivery palette.
+
+SCOPE NOTE (unchanged across the program): the immune MAGNITUDE, how strongly a given patient or
+construct will react in vivo, is a declared known-unknown (configs/known_unknowns.yaml: ``in_vivo_immunogenicity``)
+and is NEVER predicted here. What this module exposes is strictly:
+
+  * the DOCUMENTED, CITED, ORDINAL (low/moderate/high) literature priors per vehicle, and
+  * a transparent ranking that combines those ordinal tiers under a USER-SUPPLIED safety<->efficacy weight.
+
+The composite scores are an explicit, reproducible function of the documented tiers and the user's weight, not
+a learned or predicted immunogenicity. Every profile carries the scope flag that the magnitude is out of scope,
+plus the curated DOIs so the prior is auditable.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack.planner.delivery_vehicles import load_vehicles, names, vehicle
+
+# Ordinal map for the documented qualitative tiers. Higher = more of the named property.
+# For the BURDEN axes (immunity / NAb / innate / adaptive / genotoxicity) higher = worse (less safe);
+# for the EFFICACY axis higher = better.
+_TIER = {"low": 0.0, "moderate": 1.0, "high": 2.0}
+# Two DISTINCT safety sub-axes are kept separate, never collapsed into one mean, because they are different
+# KINDS of risk: immunogenicity is (largely) reversible and bears on eligibility/re-dosing, whereas
+# genotoxicity (insertional mutagenesis) is a permanent, potentially oncogenic risk. This is exactly the
+# tradeoff the request is about ("AAV is safe but NAbs; LV is highly efficacious at integrating but its
+# safety is bad"), so genotoxicity must be a first-class, separately-visible axis, not 1/5 of an average.
+_IMMUNE_AXES = ("preexisting_immunity", "neutralizing_antibody", "innate_immune", "adaptive_immune")
+_GENOTOX_AXIS = "genotoxicity"
+# magnitude is NEVER predicted; this is the known-unknown the profile points back to.
+_MAGNITUDE_SCOPE_ID = "in_vivo_immunogenicity"
+
+
+def _tier(val) -> float | None:
+    if val is None:
+        return None
+    return _TIER.get(str(val).strip().lower())
+
+
+def safety_efficacy_profile(name: str) -> dict | None:
+    """Documented safety<->efficacy profile for one vehicle, derived ONLY from its ``immune_safety`` block.
+
+    Reports the ordinal tiers verbatim and THREE normalised sub-scores (1 = best):
+      * ``immune_score`` = 1 - mean(immune-burden axes)/2 (1 = least immunogenic)
+      * ``genotox_score`` = 1 - genotoxicity/2 (1 = least insertional/oncogenic risk)
+      * ``efficacy_score`` = efficacy/2 (1 = most efficacious)
+    plus a headline ``safety_score = min(immune_score, genotox_score)``, a precautionary worst-axis aggregation
+    so a vehicle is only as "safe" as its WORST safety dimension (a non-immunogenic but genotoxic vector is not
+    called safe). Also returns the documented tradeoff sentence, curated DOIs, and the standing scope flag that
+    the immune MAGNITUDE is not predicted. Returns ``None`` for an unknown vehicle; invents no number."""
+    rec = vehicle(name)
+    if rec is None:
+        return None
+    imm = rec.get("immune_safety") or {}
+    # 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 (primary = NetMHCpan-4.1 over the
+    # capsid/envelope antigen, MHCflurry cross-check). 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
+    # PRE-EXISTING immunity (B-cell / NAb): grounded in published serosurvey data. Folded
+    # only for IN-VIVO vehicles (serum NAb neutralises the vector in vivo; ex-vivo transduction in a dish is
+    # not reached by host antibody, so for ex-vivo vehicles it is reported but muted).
+    from pen_stack.planner.seroprevalence_oracle import computed_preexisting_score
+    pre_score, pre_oracle = computed_preexisting_score(name)
+    preexisting_source = "documented"
+    if pre_score is not None and in_vivo:
+        axis_scores["preexisting_immunity"] = pre_score
+        preexisting_source = "computed"
+    elif pre_score is not None and not in_vivo:
+        preexisting_source = "computed_ex_vivo_muted"
+    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 (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.
+    from pen_stack.planner.genotoxicity_oracle import computed_genotox_score
+    computed, gtox_oracle = computed_genotox_score(name)
+    gtox_tier = _tier(imm.get(_GENOTOX_AXIS))
+    documented_genotox = (1.0 - gtox_tier / 2.0) if gtox_tier is not None else None
+    genotox_score = computed if computed is not None else documented_genotox
+    genotox_source = "computed" if computed is not None else ("documented" if documented_genotox is not None
+                                                              else None)
+    sub = [s for s in (immune_score, genotox_score) if s is not None]
+    safety_score = min(sub) if sub else None # worst-axis; abstain if neither documented
+    eff = _tier(imm.get("efficacy"))
+    efficacy_score = (eff / 2.0) if eff is not None else None
+    _r = lambda x: None if x is None else round(x, 3) # noqa: E731
+    return {
+        "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),
+        "preexisting_source": preexisting_source, # computed | computed_ex_vivo_muted | documented
+        "seroprevalence_score": _r(pre_score), # computed pre-existing-NAb score (or None)
+        "preexisting_provenance": (pre_oracle.note if pre_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),
+        "safety_score": _r(safety_score),
+        "efficacy_score": _r(efficacy_score),
+        "re_dosable": imm.get("re_dosable", rec.get("re_dosable")),
+        "integrating": rec.get("integrating"),
+        "tradeoff": imm.get("tradeoff"),
+        "immune_dois": list(imm.get("immune_dois", []) or []),
+        "magnitude_scope_flag": {
+            "kind": "known_unknown", "id": _MAGNITUDE_SCOPE_ID,
+            "reason": "the in-vivo immune MAGNITUDE (patient/construct-specific response) is a known-unknown; "
+                      "only documented ordinal priors are surfaced, never a predicted magnitude"},
+        "note": "safety_score = min(immune_score, genotox_score) over DOCUMENTED ordinal tiers, a precautionary "
+                "worst-axis aggregation, not a predicted immunogenicity.",
+    }
+
+
+@lru_cache(maxsize=1)
+def all_profiles() -> tuple:
+    """All vehicle profiles (tuple so it is hashable/cacheable)."""
+    return tuple(p for n in names() if (p := safety_efficacy_profile(n)) is not None)
+
+
+def _balance(profile: dict, safety_weight: float) -> float | None:
+    """Composite = safety_weight * safety_score + (1 - safety_weight) * efficacy_score. None if either axis is
+    undocumented (abstain rather than impute)."""
+    s, e = profile["safety_score"], profile["efficacy_score"]
+    if s is None or e is None:
+        return None
+    w = min(max(float(safety_weight), 0.0), 1.0)
+    return round(w * s + (1.0 - w) * e, 4)
+
+
+def recommend_delivery(cargo_form: str, cargo_bp: int | None = None, *, safety_weight: float = 0.5,
+                       in_vivo: bool | None = None) -> dict:
+    """Rank the delivery palette for a cargo by a USER-WEIGHTED safety<->efficacy balance over documented priors.
+
+    Args:
+        cargo_form: required cargo form (DNA / mRNA / RNP), only vehicles compatible with it are considered.
+        cargo_bp: if given, vehicles whose ``cargo_capacity_bp`` is smaller are excluded (hard packaging limit).
+        safety_weight: in [0, 1]. 1.0 = rank purely on documented safety; 0.0 = purely on efficacy; 0.5 = balance.
+        in_vivo: if True, exclude ex-vivo-only vehicles (and vice-versa) when the field is documented.
+
+    Returns a dict with the eligible vehicles ranked best-first by the composite, each carrying its documented
+    tiers, tradeoff, and curated DOIs, plus the standing magnitude scope flag. No magnitude is predicted; the
+    composite is an explicit function of the documented ordinal tiers and the caller's weight."""
+    form = (cargo_form or "").strip()
+    veh = load_vehicles()
+    # Input validation, surfaced rather than silently absorbed: an unrecognized cargo form matches no vehicle and
+    # would otherwise return an unexplained empty ranking, and a non-physical cargo length can never exceed a
+    # capacity so it would otherwise pass every packaging check unnoticed.
+    known_forms = sorted({f for rec in veh.values() for f in (rec.get("compatible_cargo_form") or [])})
+    input_flags: list[dict] = []
+    if form and form not in known_forms:
+        input_flags.append({"field": "cargo_form", "value": cargo_form, "issue": "unrecognized",
+                            "detail": f"no vehicle declares compatibility with cargo form {cargo_form!r}; "
+                                      f"known forms: {', '.join(known_forms)}. No vehicle is eligible."})
+    if cargo_bp is not None and int(cargo_bp) <= 0:
+        input_flags.append({"field": "cargo_bp", "value": cargo_bp, "issue": "not_physical",
+                            "detail": "cargo length must be a positive number of base pairs; the packaging-capacity "
+                                      "filter cannot be applied to it."})
+    eligible: list[dict] = []
+    excluded: list[dict] = []
+    for n, rec in veh.items():
+        forms = rec.get("compatible_cargo_form", []) or []
+        if form and form not in forms:
+            continue
+        if cargo_bp is not None and rec.get("cargo_capacity_bp") is not None \
+                and int(cargo_bp) > int(rec["cargo_capacity_bp"]):
+            excluded.append({"vehicle": n, "reason": f"cargo {cargo_bp} bp exceeds capacity "
+                                                     f"{rec['cargo_capacity_bp']} bp"})
+            continue
+        if in_vivo is True and rec.get("ex_vivo") and not rec.get("in_vivo"):
+            excluded.append({"vehicle": n, "reason": "ex-vivo-only; an in-vivo route was required"})
+            continue
+        if in_vivo is False and rec.get("in_vivo") and not rec.get("ex_vivo"):
+            excluded.append({"vehicle": n, "reason": "in-vivo-only; an ex-vivo route was required"})
+            continue
+        prof = safety_efficacy_profile(n)
+        if prof is None:
+            continue
+        prof = dict(prof)
+        prof["balance"] = _balance(prof, safety_weight)
+        eligible.append(prof)
+
+    # rank: documented balance first (None last); tie-break by efficacy then safety.
+    eligible.sort(key=lambda p: (p["balance"] is None, -(p["balance"] or 0.0),
+                                 -(p["efficacy_score"] or 0.0), -(p["safety_score"] or 0.0)))
+    return {
+        "cargo_form": form, "cargo_bp": cargo_bp, "safety_weight": min(max(float(safety_weight), 0.0), 1.0),
+        "in_vivo": in_vivo,
+        "ranked": eligible,
+        "recommended": eligible[0]["vehicle"] if eligible else None,
+        "excluded": excluded,
+        "input_flags": input_flags,
+        "scope_flags": [{"kind": "known_unknown", "id": _MAGNITUDE_SCOPE_ID,
+                         "reason": "ranking is over DOCUMENTED ordinal immune priors; the patient/construct-"
+                                   "specific immune MAGNITUDE is a known-unknown and is not predicted"}],
+        "no_fabrication": True,
+        "note": "balance = safety_weight*safety + (1-safety_weight)*efficacy over documented low/moderate/high "
+                "tiers; change safety_weight to move along the safety<->efficacy frontier.",
+    }

pen_stack/planner/delivery_predict.py

@@ -0,0 +1,196 @@
+"""Cross-modality deliverability + learned AAV capsid-fitness.
+
+Extends the rule-level `recommend_delivery` (documented safety<->efficacy balance) with two grounded layers:
+
+  * **serotype -> tissue tropism PRIOR** (`configs/aav_serotype_tropism.yaml`), real serotype<->tissue mappings
+    evidenced by APPROVED AAV gene therapies (AAV9->CNS, AAVrh74->skeletal muscle, AAV5->liver, AAV2->retina/putamen
+    via LOCAL injection). A grounded prior for an approved serotype; a known-unknown (abstain) for a novel capsid.
+  * **learned capsid-fitness**, a model trained on the FLIP-AAV benchmark (Bryant 2021 packaging fitness; Dallago
+    2021 splits) that scores an AAV capsid VP1 sequence. The Delivery-Bench shows it beats a mutation-burden baseline
+    on held-out splits; the licensed datasets stay on the VM, and the derived metrics + reproducible build script are
+    committed. The ~3 MB model itself is gitignored (regenerated via ``scripts/build_capsid_fitness.py`` and mounted
+    into the deployed app, like ``position_effect.pkl``); the axis abstains gracefully when it is absent. Predicted
+    fitness is a CANDIDATE for the MEASURED axis (packaging viability) and extrapolative for in-vivo human tropism.
+
+no fabricated tropism; predicted fitness is a candidate; abstains without inputs / without the model.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import project_root, resource
+
+# Delivery-Bench headline (REAL FLIP-AAV result; learned vs mutation-burden baseline, Spearman, bootstrap CI).
+# Filled from benchmarks/delivery/capsid_fitness_metrics.json (computed on the VM); kept in-code so the axis is
+# available everywhere (CI / bare wheel / live app) without the licensed data tree.
+CAPSID_FITNESS_BENCH = {
+    "benchmark": "FLIP-AAV (Dallago 2021; Bryant 2021 packaging fitness, 10.1038/s41587-020-00793-4)",
+    "model": "windowed one-hot (VP1 555-595) gradient boosting",
+    "baseline": "mutation burden (Hamming from the train consensus)",
+    "splits": {}, # populated below from the committed metrics
+}
+
+
+@lru_cache(maxsize=1)
+def _bench_metrics() -> dict:
+    """The committed Delivery-Bench metrics (capsid-fitness learned-vs-baseline), or {} if the data tree is absent."""
+    try:
+        import json
+        return json.loads(resource("benchmarks/delivery/capsid_fitness_metrics.json").read_text(encoding="utf-8"))
+    except Exception: # noqa: BLE001
+        return {}
+
+
+@lru_cache(maxsize=1)
+def _tropism() -> dict:
+    try:
+        return yaml.safe_load(resource("configs/aav_serotype_tropism.yaml").read_text(encoding="utf-8")) or {}
+    except Exception: # noqa: BLE001
+        return {}
+
+
+def serotype_tropism(serotype: str) -> dict:
+    """The grounded tissue prior for an AAV serotype (from approved therapies), or a known-unknown."""
+    rec = (_tropism().get("serotypes") or {}).get(serotype)
+    if rec:
+        return {"serotype": serotype, "tissue": rec["tissue"], "route": rec.get("route"),
+                "evidence": rec.get("example_product"), "indication": rec.get("indication"),
+                "approval": rec.get("approval"), "doi": rec.get("doi"),
+                "confidence": "grounded (approved therapy)", "output_kind": "prior"}
+    return {"serotype": serotype, "tissue": None, "confidence": "known-unknown",
+            "note": "no approved-therapy precedent for this serotype/capsid -> in-vivo human tropism is a "
+                    "known-unknown; not fabricated", "output_kind": "abstain"}
+
+
+def serotypes_for_tissue(target_tissue: str) -> dict:
+    """Which approved AAV serotypes are GROUNDED priors for a target tissue (e.g. liver -> AAV5/AAVRh74var). Abstains
+    (empty) when no approved serotype targets the tissue, never invents one."""
+    t = (target_tissue or "").strip().lower()
+    hits = []
+    for s, rec in (_tropism().get("serotypes") or {}).items():
+        tissues = [str(x).lower() for x in (rec.get("tissue") or [])]
+        if any(t in x or x in t for x in tissues):
+            hits.append({"serotype": s, "tissue": rec["tissue"], "route": rec.get("route"),
+                         "evidence": rec.get("example_product")})
+    return {"target_tissue": target_tissue, "grounded_serotypes": hits,
+            "note": ("grounded serotype->tissue priors from approved therapies" if hits else
+                     f"no approved AAV serotype has a grounded prior for {target_tissue!r} -> known-unknown (abstain)")}
+
+
+@lru_cache(maxsize=1)
+def _fitness_model():
+    """Load the FLIP-AAV-trained capsid-fitness model (gitignored .pkl, regenerated on the VM; mounted into the live
+    container like position_effect.pkl). None when absent -> the fitness call abstains. The committed bench metrics
+    document the model's measured performance even when the .pkl is not present."""
+    import pickle
+    for base in (project_root() / "models", project_root() / "data" / "delivery_models"):
+        p = base / "capsid_fitness.pkl"
+        if p.exists():
+            try:
+                return pickle.load(open(p, "rb"))
+            except Exception: # noqa: BLE001
+                return None
+    return None
+
+
+def capsid_fitness(vp1_sequence: str, vector: str = "AAV") -> dict:
+    """Predicted AAV capsid packaging-fitness for a VP1 sequence (FLIP-AAV-trained), or an abstention when the
+    model is not present (CI / bare wheel). The learned model is AAV-capsid-specific: for other vectors (LV,
+    adenovirus, HSV) there is NO packaging/assembly-fitness model, so it abstains with that stated rather than
+    fabricate a score. Predicted fitness is a CANDIDATE for the measured packaging axis, NOT an in-vivo tropism claim."""
+    import numpy as np
+    vec = (vector or "AAV").strip()
+    if vec.upper() != "AAV":
+        return {"available": False, "abstain": True, "vector": vec, "predicted_fitness": None, "output_kind": "n/a",
+                "note": f"no learned packaging/assembly-fitness model for {vec}: the FLIP-AAV model is AAV-capsid-"
+                        "specific. Non-AAV vectors get vehicle-level checks (capacity, immune risk), not a "
+                        "capsid-fitness score -- not fabricated.", "bench": None}
+    m = _fitness_model()
+    bench = _bench_metrics()
+    if m is None:
+        return {"available": False, "abstain": True, "vector": "AAV", "predicted_fitness": None,
+                "output_kind": "candidate",
+                "note": "capsid_fitness.pkl not present (VM-only/regenerated); the committed Delivery-Bench documents "
+                        "its measured performance.", "bench": bench}
+    w0, w1 = m["window"]
+    aas = m["aas"]
+    ai = {a: i for i, a in enumerate(aas)}
+    wl = w1 - w0
+    # clean the input: drop FASTA header lines, strip whitespace, upper-case (a pasted VP1 usually has newlines).
+    seq = "".join(ln for ln in str(vp1_sequence).splitlines() if not ln.lstrip().startswith(">"))
+    seq = "".join(seq.split()).upper()
+    # INPUT GUARD: the model reads AAV VP1 residues w0-w1 ONLY. A sequence that never reaches that window, or a
+    # nucleotide sequence pasted by mistake, would collapse to a degenerate constant -> abstain, never fake a score.
+    nuc_only = bool(seq) and set(seq) <= set("ACGTUN")
+    if len(seq) <= w0 or nuc_only:
+        why = ("this looks like a nucleotide (DNA/RNA) sequence; the model needs the VP1 capsid PROTEIN (amino acids)"
+               if nuc_only else
+               f"the input is only {len(seq)} aa and never reaches VP1 residues {w0}-{w1} -- the region the model reads")
+        return {"available": False, "abstain": True, "vector": "AAV", "predicted_fitness": None,
+                "output_kind": "candidate", "input_issue": why,
+                "note": f"no meaningful score: {why}. Paste a full-length AAV VP1 capsid protein (>= {w1} aa, AAV2 "
+                        f"numbering) so the model can read residues {w0}-{w1}.", "bench": bench}
+    win = (seq[w0:w1] + "-" * wl)[:wl]
+    x = np.zeros(wl * 20, dtype="float32")
+    for i, a in enumerate(win):
+        if a in ai:
+            x[i * 20 + ai[a]] = 1.0
+    val = float(m["model"].predict(x.reshape(1, -1))[0])
+    # Readable verdict: the PERCENTILE of this prediction within the model's own predicted-fitness distribution on
+    # the held-out FLIP-AAV test set (a grounded, unambiguous "top X% of measured variants" instead of a bare float).
+    pcts = m.get("pred_percentiles")
+    percentile = None
+    if pcts:
+        percentile = max(0, min(100, int(np.searchsorted(np.asarray(pcts, dtype="float64"), val))))
+    if percentile is None:
+        bucket, verdict = "unknown", f"Predicted packaging fitness {round(val, 3)} (no reference distribution in this model build)."
+    else:
+        bucket = "better" if percentile >= 67 else ("similar" if percentile >= 33 else "worse")
+        verdict = {"better": "High packaging fitness", "similar": "Mid-range packaging fitness",
+                   "worse": "Low packaging fitness"}[bucket]  # the percentile carries the "better than X%" detail
+    # a compact 24-bin histogram of the reference distribution (for a UI sparkline). Binning the equally-spaced
+    # percentiles reconstructs the density shape (dense near the mode, sparse at the tails); cached on the model.
+    dist = m.get("_ref_hist")
+    if dist is None and pcts:
+        arr = np.asarray(pcts, dtype="float64")
+        lo, hi = float(arr[0]), float(arr[-1])
+        counts, _ = np.histogram(arr, bins=24, range=(lo, hi))
+        dist = {"lo": round(lo, 4), "hi": round(hi, 4), "counts": [int(x) for x in counts]}
+        m["_ref_hist"] = dist
+    input_warning = None
+    if len(seq) < w1:  # partial window: the tail is padded, so only part of the 555-595 window informs the score
+        input_warning = (f"sequence is {len(seq)} aa (< {w1}); residues {len(seq)}-{w1} are padded, so only part of "
+                         f"the {w0}-{w1} window informs the score -- treat with extra caution.")
+    return {"available": True, "abstain": False, "vector": "AAV", "predicted_fitness": round(val, 4),
+            "percentile": percentile, "verdict": verdict, "verdict_bucket": bucket, "distribution": dist,
+            "scale": "FLIP-AAV packaging fitness (log-enrichment; higher = more fit)", "output_kind": "candidate",
+            "window": [w0, w1], "sequence_len": len(seq), "input_warning": input_warning,
+            "status": f"CANDIDATE for the measured packaging axis; NOT an in-vivo human-tropism claim (known-unknown). "
+                      f"The model reads VP1 residues {w0}-{w1} only; the percentile is vs the model's held-out "
+                      f"FLIP-AAV test predictions.",
+            "bench": bench}
+
+
+def recommend_delivery_plus(cargo_form: str, cargo_bp: int | None = None, target_tissue: str | None = None,
+                            *, safety_weight: float = 0.5, in_vivo: bool | None = None,
+                            serotype: str | None = None) -> dict:
+    """The extended recommender: the rule-level safety<->efficacy ranking (recommend_delivery) PLUS a grounded
+    serotype->tissue tropism prior and the learned capsid-fitness capability. The tropism prior answers whichever
+    direction the caller asked: a specific ``serotype`` -> its approved-therapy tissue (e.g. AAV9 -> CNS/Zolgensma);
+    otherwise a ``target_tissue`` -> the approved serotypes that reach it. Grounded for approved serotypes, a
+    known-unknown otherwise. Never fabricates."""
+    from pen_stack.planner.delivery_immunology import recommend_delivery
+    base = recommend_delivery(cargo_form, cargo_bp, safety_weight=safety_weight, in_vivo=in_vivo)
+    if serotype:
+        tropism = serotype_tropism(serotype)          # serotype -> tissue (matches the field name; report path)
+    elif target_tissue:
+        tropism = serotypes_for_tissue(target_tissue)  # tissue -> approved serotypes
+    else:
+        tropism = None
+    return {**base, "serotype": serotype, "target_tissue": target_tissue, "serotype_tropism_prior": tropism,
+            "capsid_fitness": {"capability": "learned FLIP-AAV capsid-fitness (call capsid_fitness(vp1_seq))",
+                               "bench": _bench_metrics().get("mut_des") or CAPSID_FITNESS_BENCH},
+            "honesty": "tropism is a grounded prior for approved serotypes, a known-unknown otherwise; predicted "
+                       "capsid-fitness is a candidate for the measured packaging axis; no fabricated tropism."}

pen_stack/planner/delivery_vehicles.py

@@ -0,0 +1,37 @@
+"""Delivery-vehicle palette loader. Reads configs/delivery_vehicles.yaml (>=6 vehicles:
+AAV single/dual, lentivirus, helper-dependent adenovirus, HSV amplicon, LNP-mRNA, eVLP, electroporation).
+Replaces the single dual-AAV assumption with a queryable palette the rule engine constrains."""
+from __future__ import annotations
+
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def load_vehicles(path=None) -> dict:
+    p = resource("configs/delivery_vehicles.yaml") if path is None else path
+    return yaml.safe_load(open(p, encoding="utf-8").read())["vehicles"]
+
+
+def vehicle(name: str) -> dict | None:
+    """Vehicle record by name (case-insensitive; tolerant of aliases like 'aav'->AAV_single, 'lvv')."""
+    if not name:
+        return None
+    veh = load_vehicles()
+    if name in veh:
+        return veh[name]
+    low = name.lower()
+    alias = {"aav": "AAV_single", "aav_single": "AAV_single", "dual_aav": "AAV_dual",
+             "aav_dual": "AAV_dual", "lvv": "lentivirus", "lenti": "lentivirus",
+             "hdad": "helper_dependent_adenovirus", "hsv": "hsv_amplicon",
+             "lnp": "lnp_mrna", "mrna": "lnp_mrna", "vlp": "evlp", "ep": "electroporation",
+             "nucleofection": "electroporation"}
+    key = alias.get(low) or next((k for k in veh if k.lower() == low), None)
+    return veh.get(key) if key else None
+
+
+def names() -> list[str]:
+    return list(load_vehicles().keys())

pen_stack/planner/genotoxicity_oracle.py

@@ -0,0 +1,112 @@
+"""Computed genotoxicity oracle for integrating delivery vectors.
+
+Replaces the hard-coded `genotoxicity` ordinal tier (documented prior) with a DATA-COMPUTED signal for
+INTEGRATING vehicles: the observed enrichment of a vector class's integration sites near CancerMine (CC0)
+oncogenes, from VISDB integration catalogues x the oncogene annotation (configs/genotoxicity_oracle.yaml,
+built by scripts/p52_build_genotox_oracle.py on the VM where the data lives).
+
+    genotox_score = min(1, 1 / enrichment) # 1 = safest; episomal/non-targeting ~ 1.0
+
+This reproduces the lentivirus-safer-than-gammaretrovirus ordering FROM DATA (lentiviral ~2x oncogene-proximity
+enrichment vs gammaretroviral ~5-6x, the LMO2 / SCID-X1 pattern), instead of asserting it. It answers through
+the OracleResult contract (value + provenance + native_uncertainty + scope_card + output_kind) and is an
+`output_kind="baseline"` observed-data comparator, NOT a generative claim.
+
+SCOPE: this is a RELATIVE, integration-PREFERENCE signal. The in-vivo clonal-expansion / leukemogenesis
+OUTCOME in a patient is NOT modelled and stays a known-unknown; a class with too few catalogued sites is
+flagged `extrapolating`; non-integrating vehicles have no insertional mechanism (score 1.0 by mechanism).
+"""
+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 = "delivery_genotoxicity"
+
+
+@lru_cache(maxsize=1)
+def _artifact() -> dict:
+    return yaml.safe_load(resource("configs/genotoxicity_oracle.yaml").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def _vehicle_to_class() -> dict:
+    art = _artifact()
+    out: dict[str, str] = {}
+    for cls, vehs in (art.get("vehicle_class") or {}).items():
+        for v in vehs or []:
+            out[v] = cls
+    return out
+
+
+def _prov(source: str, **extra) -> Provenance:
+    art = _artifact()
+    return Provenance(model="visdb_integration_x_cancermine", version=str(art.get("version", "1.0")),
+                      source=source, extra={"built": art.get("built"),
+                                            "provenance_dois": art.get("provenance_dois", []), **extra})
+
+
+def genotoxicity_oracle(vehicle_name: str) -> OracleResult:
+    """Computed genotoxicity for a delivery vehicle, as an OracleResult.
+
+    - non-integrating vehicle -> genotox_score 1.0 by mechanism (episomal/transient; no insertional risk).
+    - integrating + computed class -> data-derived score from VISDB x CancerMine; small-n class -> extrapolating.
+    - integrating but no computed class / unknown vehicle -> available=False (caller falls back to the
+      documented `immune_safety.genotoxicity` tier; no number is fabricated)."""
+    rec = vehicle(vehicle_name)
+    if rec is None:
+        return OracleResult(oracle="genome", value=None, provenance=_prov("cache"),
+                            scope_card=_SCOPE_CARD, in_scope=False, available=False, output_kind="baseline",
+                            note=f"unknown vehicle {vehicle_name!r}")
+
+    if not rec.get("integrating"):
+        return OracleResult(
+            oracle="genome",
+            value={"genotox_score": 1.0, "enrichment": None, "mechanism": "non-integrating"},
+            provenance=_prov("cache"), native_uncertainty=0.0, scope_card=_SCOPE_CARD, in_scope=True,
+            extrapolating=False, output_kind="baseline", available=True,
+            note="episomal/transient vector: no integration -> no insertional-mutagenesis mechanism (score 1.0).")
+
+    cls = _vehicle_to_class().get(vehicle_name)
+    classes = _artifact().get("classes") or {}
+    if not cls or cls not in classes:
+        return OracleResult(oracle="genome", value=None, provenance=_prov("cache"),
+                            scope_card=_SCOPE_CARD, in_scope=False, available=False, output_kind="baseline",
+                            note=f"integrating vehicle {vehicle_name!r} has no computed class; "
+                                 "fall back to the documented genotoxicity tier.")
+
+    rc = classes[cls]
+    enrich = rc.get("enrichment")
+    frac, ci95, n = rc.get("frac_oncogene_50kb"), rc.get("ci95"), rc.get("n_sites")
+    score = min(1.0, 1.0 / enrich) if enrich else None
+    robust = bool(rc.get("robust"))
+    # native uncertainty = relative CI on the observed oncogene-proximity fraction (coefficient of variation)
+    nu = round(ci95 / frac, 4) if (ci95 and frac) else None
+    return OracleResult(
+        oracle="genome",
+        value={"genotox_score": round(score, 3) if score is not None else None,
+               "enrichment": enrich, "frac_oncogene_50kb": frac, "ci95": ci95, "n_sites": n,
+               "frac_genotoxic_cis": rc.get("frac_genotoxic_cis"), "vector_class": cls,
+               "background_frac": _artifact().get("genome_background_frac_oncogene_50kb")},
+        provenance=_prov("cache", virus=rc.get("virus"), vector_class=cls),
+        native_uncertainty=nu, scope_card=_SCOPE_CARD, in_scope=True,
+        extrapolating=not robust, output_kind="baseline", available=True,
+        note=(f"{cls} integration is {enrich}x enriched within "
+              f"{_artifact().get('window_bp')} bp of a CancerMine oncogene vs background "
+              f"({frac:.3%}, n={n}); genotox_score=min(1,1/enrichment)."
+              + ("" if robust else " SMALL-N class: directional only (extrapolating).")
+              + " In-vivo clonal outcome is a known-unknown (not modelled).")
+    )
+
+
+def computed_genotox_score(vehicle_name: str) -> tuple[float | None, OracleResult]:
+    """Convenience: (genotox_score or None, full OracleResult). None when the oracle abstains (caller then
+    uses the documented tier). Never fabricates a number."""
+    r = genotoxicity_oracle(vehicle_name)
+    val = (r.value or {}).get("genotox_score") if (r.available and r.value) else None
+    return val, r