pen-stack 0.1.0__py3-none-any.whl

pen_stack/planner/capsid_epitope_oracle.py

@@ -0,0 +1,135 @@
+"""Computed capsid/envelope T-cell epitope-load oracle for viral delivery vectors, using **NetMHCpan-4.1**.
+
+Refines the documented `adaptive_immune` (CD8 T-cell) tier with a DATA-COMPUTED signal for VIRAL vectors: the
+fraction of the capsid/envelope antigen presentable across a frequent HLA-I panel. **The PRIMARY
+predictor is the gold-standard licensed NetMHCpan-4.1** (eluted-ligand %Rank_EL <= 0.5, residue coverage union
+over a 12-allele frequent-HLA panel), computed on the VM and cached as derived fractions in
+`configs/mhc_epitope_oracle.yaml` (`mhc1`). The earlier MHCflurry %rank<=0.5 cache
+(`configs/capsid_epitope_oracle.yaml`) is retained as an explicit, reported **cross-check** (same residue-coverage
+metric, same panel), never silently substituted.
+
+    capsid_immune_score = 1 - epitope_fraction_strong # 1 = least presentable / least immunogenic
+
+Population-level (averaged over a frequent-allele panel) so it is NOT a patient-HLA-specific magnitude. Answers
+through the OracleResult contract (output_kind="baseline"). The vehicle -> antigen(s) mapping lives in
+`configs/capsid_epitope_oracle.yaml` (`vehicles`); the strong-binder fractions come from the NetMHCpan-4.1 cache.
+
+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).
+
+SCOPE: 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. NetMHCpan-4.1 and MHCflurry
+are different models and disagree on absolute load (both agree AAV is the least CD8-immunogenic capsid); the
+cross-check makes that disagreement visible rather than hiding it.
+"""
+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 _mhcflurry_artifact() -> dict:
+    """The MHCflurry capsid cache, used for the vehicle->antigen mapping AND as the reported cross-check."""
+    return yaml.safe_load(resource("configs/capsid_epitope_oracle.yaml").read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def _netmhcpan_mhc1() -> dict:
+    """The REAL NetMHCpan-4.1 MHC-I residue-coverage cache (configs/mhc_epitope_oracle.yaml `mhc1`), keyed by
+    antigen. Only derived fractions are shipped (the licensed binary is never distributed). {} if absent."""
+    try:
+        art = yaml.safe_load(resource("configs/mhc_epitope_oracle.yaml").read_text(encoding="utf-8")) or {}
+        return art.get("mhc1") or {}
+    except Exception: # noqa: BLE001
+        return {}
+
+
+def _netmhc_version() -> str:
+    try:
+        art = yaml.safe_load(resource("configs/mhc_epitope_oracle.yaml").read_text(encoding="utf-8")) or {}
+        return str(art.get("version", "6.9.2"))
+    except Exception: # noqa: BLE001
+        return "6.9.2"
+
+
+def _prov(**extra) -> Provenance:
+    fl = _mhcflurry_artifact()
+    return Provenance(model="netmhcpan4.1_capsid_epitope", version=_netmhc_version(), source="cache",
+                      extra={"primary_predictor": "NetMHCpan-4.1 (%Rank_EL<=0.5, residue coverage, 12-allele panel)",
+                             "cross_check_predictor": fl.get("method", {}).get("predictor"),
+                             "provenance_dois": ["10.1093/nar/gkac1029", *fl.get("provenance_dois", [])], **extra})
+
+
+def _antigens_for(vehicle_name: str) -> list[str] | None:
+    rec = (_mhcflurry_artifact().get("vehicles") or {}).get(vehicle_name)
+    return rec.get("antigens") if rec else None
+
+
+def capsid_epitope_oracle(vehicle_name: str) -> OracleResult:
+    """Computed capsid CD8 epitope load for a delivery vehicle, as an OracleResult.
+
+    - viral vehicle with committed antigen(s) -> computed `capsid_immune_score` from **NetMHCpan-4.1** x HLA
+      panel (primary), with the MHCflurry value reported as a cross-check.
+    - 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}")
+
+    antigens = _antigens_for(vehicle_name)
+    mhc1 = _netmhcpan_mhc1()
+    if antigens and all(a in mhc1 for a in antigens):
+        fracs = [mhc1[a]["epitope_fraction_strong"] for a in antigens]
+        ef = round(sum(fracs) / len(fracs), 4)
+        score = round(1.0 - ef, 4)
+        # MHCflurry cross-check (same vehicle, from its dedicated cache)
+        fl_veh = (_mhcflurry_artifact().get("vehicles") or {}).get(vehicle_name, {})
+        cross = {"predictor": "MHCflurry 2.0 (%rank<=0.5)",
+                 "epitope_fraction_strong": fl_veh.get("epitope_fraction_strong"),
+                 "capsid_immune_score": fl_veh.get("capsid_immune_score")}
+        return OracleResult(
+            oracle="protein_design",
+            value={"capsid_immune_score": score, "epitope_fraction_strong": ef, "antigens": antigens,
+                   "predictor": "NetMHCpan-4.1", "hla_panel_size": 12, "cross_check_mhcflurry": cross},
+            provenance=_prov(antigens=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(antigens)} antigen is presentable (NetMHCpan-4.1 %Rank_EL<=0.5, "
+                  f"residue coverage over a 12-allele frequent HLA-I panel); capsid_immune_score=1-epitope_fraction. "
+                  f"MHCflurry cross-check capsid_immune_score={cross['capsid_immune_score']}. 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 in the NetMHCpan-4.1 "
+                             "cache; 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/planner/cargo.py

@@ -0,0 +1,56 @@
+"""Cargo / donor design.
+
+Assemble a donor construct spec for a chosen writer + site: insulators (protect durability), promoter +
+polyA, codon optimisation flag for the host cell type, and a size check against the writer's
+deliverability/cargo class. For bridge/seek writers, attach the off-target prediction *if the
+bridge engine is available* - otherwise the field is marked pending, so the Planner runs
+end-to-end now and the off-target annotation drops in once the bridge off-target engine lands.
+
+We design at the level of construct *elements + sizes* (the payload sequence is the user's CDS/regulatory
+cassette); element lengths are nominal, documented constants.
+"""
+from __future__ import annotations
+
+# nominal element sizes (bp) for the assembled donor; documented, not hidden
+_ELEMENTS = {"insulator_5": 250, "promoter": 600, "polyA": 250, "insulator_3": 250}
+
+
+def _bridge_offtarget(writer_family: str, site: tuple) -> dict:
+    """Optional bridge off-target hook. Returns the off-target prediction if the bridge engine exists, else pending."""
+    try:
+        from pen_stack.bridge.offtarget import predict_offtargets
+    except Exception: # noqa: BLE001 - engine not built yet
+        return {"status": "pending_phase_1_5", "note": "the bridge off-target engine is not yet available"}
+    return predict_offtargets(writer_family, site)
+
+
+def design_cargo(payload_bp: int, writer_row: dict, site: tuple, ct: str,
+                 payload_seq: str | None = None) -> dict:
+    """Assemble a donor construct spec. writer_row needs: family, cargo_capacity_bp, deliv_class.
+
+    If `payload_seq` is given, attach the Cargo Polish sequence-risk scan (cargo_durability_risk +
+    actionable suggestions) - the locus model scores the site, Cargo Polish scores the insert.
+    """
+    fam = writer_row.get("family")
+    cap = writer_row.get("cargo_capacity_bp")
+    elements = dict(_ELEMENTS)
+    assembled_bp = int(payload_bp) + sum(elements.values())
+    size_ok = (cap is None) or (assembled_bp <= cap)
+
+    out = {
+        "host": ct,
+        "payload_bp": int(payload_bp),
+        "elements": elements, # insulators + promoter + polyA
+        "assembled_bp": assembled_bp,
+        "codon_optimised": True,
+        "writer_family": fam,
+        "cargo_capacity_bp": cap,
+        "size_ok": size_ok,
+        "deliverability": writer_row.get("deliv_class"),
+    }
+    if fam in {"bridge_IS110", "seek_IS1111"}:
+        out["offtargets"] = _bridge_offtarget(fam, site)
+    if payload_seq:
+        from pen_stack.planner.cargo_polish import scan_cargo
+        out["cargo_polish"] = scan_cargo(payload_seq)
+    return out

pen_stack/planner/cargo_polish.py

@@ -0,0 +1,146 @@
+"""Cargo Polish - cargo-sequence durability-risk scan.
+
+The locus model scores WHERE to write; this scores WHAT is written. It scans the insert (the user's
+cassette sequence) for known sequence triggers of transgene silencing/instability and emits a
+`cargo_durability_risk` score in [0,1] with a band and, for every flag, a concrete remedy.
+
+This is a HEURISTIC flag, not a supervised silencing predictor: it catches documented sequence triggers
+(CpG-island density -> de novo methylation; GC extremes; cryptic splice consensus; strong mRNA secondary
+structure; known silencer motifs), not all silencing causes. Thresholds are documented constants
+(configs/cargo_polish.yaml) from the silencing literature. ViennaRNA (MFE) is optional and degrades
+gracefully (the structure term is skipped, noted) so the scan runs anywhere; the other terms are pure-Python.
+
+Acceptance (prereg/ws_d.yaml): reproduces established directionality - high-CpG bacterial-style cassettes
+score above CpG-depleted / insulator-flanked constructs on a small curated set - and every flag carries a
+concrete suggestion.
+"""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+import yaml
+
+
+@lru_cache(maxsize=1)
+def _cfg() -> dict:
+    from pen_stack._resources import resource
+    return yaml.safe_load(resource("configs/cargo_polish.yaml").read_text(encoding="utf-8"))
+
+
+def _clean(seq: str) -> str:
+    return re.sub(r"[^ACGT]", "", (seq or "").upper())
+
+
+def gc_fraction(seq: str) -> float:
+    s = _clean(seq)
+    return (s.count("G") + s.count("C")) / len(s) if s else 0.0
+
+
+def cpg_islands(seq: str) -> list[dict]:
+    """Gardiner-Garden & Frommer sliding window: obs/exp CpG > threshold AND GC > threshold over the window."""
+    c = _cfg()["cpg_island"]
+    s = _clean(seq)
+    w, step = c["window_bp"], max(1, c["window_bp"] // 4)
+    out = []
+    for i in range(0, max(1, len(s) - w + 1), step):
+        win = s[i:i + w]
+        if len(win) < w:
+            break
+        nC, nG = win.count("C"), win.count("G")
+        gc = (nC + nG) / w
+        exp = (nC * nG) / w if nC and nG else 0.0
+        obs_exp = (win.count("CG") / exp) if exp else 0.0
+        if obs_exp > c["obs_exp_min"] and gc > c["gc_min"]:
+            out.append({"start": i, "obs_exp": round(obs_exp, 3), "gc": round(gc, 3)})
+    # merge overlapping windows into island count
+    merged, last_end = 0, -1
+    for isl in out:
+        if isl["start"] > last_end:
+            merged += 1
+        last_end = isl["start"] + w
+    return [{"n_islands": merged, "windows": out}] if merged else []
+
+
+def cryptic_splice_sites(seq: str) -> dict:
+    c = _cfg()["cryptic_splice"]
+    s = _clean(seq)
+    donors = len(re.findall(c["donor_motif"], s))
+    acceptors = len(re.findall(c["acceptor_motif"], s))
+    return {"donor": donors, "acceptor": acceptors, "total": donors + acceptors}
+
+
+def silencer_motifs(seq: str) -> list[dict]:
+    s = _clean(seq)
+    hits = []
+    for m in _cfg()["silencer_motifs"]["motifs"]:
+        n = len(re.findall(m["pattern"], s))
+        if n:
+            hits.append({"name": m["name"], "count": n, "note": m["note"]})
+    return hits
+
+
+def mfe_per_nt(seq: str) -> dict:
+    """ViennaRNA minimum-free-energy per nucleotide of the transcribed insert; graceful if RNA is absent."""
+    s = _clean(seq)
+    if len(s) < 10:
+        return {"available": False, "note": "sequence too short"}
+    try:
+        import RNA
+    except Exception: # noqa: BLE001 - ViennaRNA only in the bio extra / VM image
+        return {"available": False, "note": "ViennaRNA not installed (bio extra / VM image)"}
+    fc = RNA.fold_compound(s.replace("T", "U"))
+    _struct, mfe = fc.mfe()
+    return {"available": True, "mfe": round(float(mfe), 2), "mfe_per_nt": round(float(mfe) / len(s), 4)}
+
+
+def scan_cargo(seq: str) -> dict:
+    """Aggregate the cargo durability-risk scan: score in [0,1], band, and per-flag concrete suggestions."""
+    cfg = _cfg()
+    s = _clean(seq)
+    flags, risk = [], 0.0
+    sug = cfg["suggestions"]
+
+    isl = cpg_islands(s)
+    if isl:
+        n = isl[0]["n_islands"]
+        risk += min(0.5, n * cfg["cpg_island"]["risk_per_island"])
+        flags.append({"category": "cpg_island", "detail": f"{n} CpG island(s)", "suggestion": sug["cpg_island"]})
+
+    gc = gc_fraction(s)
+    if gc and (gc < cfg["gc_extremes"]["gc_low"] or gc > cfg["gc_extremes"]["gc_high"]):
+        risk += cfg["gc_extremes"]["risk"]
+        flags.append({"category": "gc_extremes", "detail": f"GC={gc:.2f}", "suggestion": sug["gc_extremes"]})
+
+    cs = cryptic_splice_sites(s)
+    if cs["total"]:
+        risk += min(cfg["cryptic_splice"]["risk_per_site_capped"], 0.05 * cs["total"])
+        flags.append({"category": "cryptic_splice", "detail": f"{cs['total']} splice consensus site(s)",
+                      "suggestion": sug["cryptic_splice"]})
+
+    sm = silencer_motifs(s)
+    if sm:
+        risk += min(cfg["silencer_motifs"]["risk_per_motif_capped"], 0.07 * sum(h["count"] for h in sm))
+        flags.append({"category": "silencer_motifs", "detail": ", ".join(h["name"] for h in sm),
+                      "suggestion": sug["silencer_motifs"]})
+
+    mfe = mfe_per_nt(s)
+    if mfe.get("available") and mfe["mfe_per_nt"] < cfg["secondary_structure"]["mfe_per_nt_warn"]:
+        risk += cfg["secondary_structure"]["risk"]
+        flags.append({"category": "secondary_structure", "detail": f"MFE/nt={mfe['mfe_per_nt']}",
+                      "suggestion": sug["secondary_structure"]})
+
+    risk = round(min(1.0, risk), 4)
+    b = cfg["bands"]
+    band = "low" if risk < b["low"] else ("moderate" if risk < b["moderate"] else "high")
+    return {"cargo_durability_risk": risk, "band": band, "length_bp": len(s),
+            "gc": round(gc, 4), "n_flags": len(flags), "flags": flags,
+            "components": {"cpg_islands": isl, "cryptic_splice": cs, "silencer_motifs": sm,
+                           "secondary_structure": mfe},
+            "scope": "heuristic sequence-trigger scan, not a supervised silencing predictor"}
+
+
+if __name__ == "__main__": # pragma: no cover
+    import json
+    demo = "CGCGCGCGGCGGCGCGCGGCGGCGCGCGGCGGCGCG" * 8
+    print(json.dumps(scan_cargo(demo), indent=2, default=str))

pen_stack/planner/chromosome.py

@@ -0,0 +1,106 @@
+"""Chromosome validation, gene/chromosome concordance, and chromosome-context advisories.
+
+The `chrom` field on a design was previously a free-text pass-through with no validation and no downstream
+effect. This module makes it meaningful WITHOUT fabricating a score: the engine's per-locus safety / durability /
+accessibility / off-target numbers are indexed by the GENE's resolved genomic coordinates via the writability
+atlas (`planner.optimize.gene_region`), not by a free-text chromosome string - a bare "chrX" with no position
+cannot index a specific locus value. So the grounded use of the field is:
+
+  * `canonical_chromosome` - validate / normalise to a standard human chromosome (chr1-chr22, chrX, chrY, chrM);
+  * `gene_chromosome` - the gene's canonical chromosome from the gene-coordinate table;
+  * `chromosome_concordance` - flag when the entered chromosome does not match the named gene's real location
+    (the "BRCA1 is on chr17, not chr1" case), making explicit that scoring uses the gene's canonical locus;
+  * `chromosome_context` - chromosome-driven advisories that ARE grounded in biology: chrM is not addressable by
+    nuclear genome-writing tools (mtDNA needs DdCBE/TALED - out of scope), chrY is male-specific with ampliconic
+    repeats, chrX is hemizygous in 46,XY vs X-inactivated in 46,XX.
+"""
+from __future__ import annotations
+
+import re
+
+STANDARD_CHROMOSOMES = [f"chr{i}" for i in range(1, 23)] + ["chrX", "chrY", "chrM"]
+
+
+def canonical_chromosome(chrom: str | None) -> str | None:
+    """Normalise a chromosome string to canonical UCSC form (chr1..chr22, chrX, chrY, chrM), or None if it is not
+    a standard human chromosome. Accepts 'chrX'/'X'/'x', 'chr1'/'1', 'chrM'/'chrMT'/'MT', '23'->X, '24'->Y."""
+    if chrom is None:
+        return None
+    c = re.sub(r"\s+", "", str(chrom)).lower()
+    if not c:
+        return None
+    if c.startswith("chr"):
+        c = c[3:]
+    c = {"mt": "m", "23": "x", "24": "y", "25": "m"}.get(c, c)
+    if c in {"x", "y", "m"}:
+        return "chr" + c.upper()
+    if c.isdigit() and 1 <= int(c) <= 22:
+        return "chr" + c
+    return None
+
+
+def gene_chromosome(gene: str | None) -> str | None:
+    """The canonical chromosome of a gene (or safe-harbour locus nickname), from the gene-coordinate table; None
+    if the gene is unknown."""
+    if not gene:
+        return None
+    try:
+        from pen_stack.planner.optimize import gene_region
+        reg = gene_region(gene)
+    except Exception:  # noqa: BLE001 - coords table absent (bare checkout) -> cannot resolve, do not fabricate
+        return None
+    return canonical_chromosome(reg[0]) if reg else None
+
+
+def chromosome_concordance(gene: str | None, chrom: str | None) -> dict:
+    """Validate the entered chromosome and check it against the named gene's canonical location.
+
+    status is one of:
+      * 'invalid'  - the entered string is not a standard human chromosome;
+      * 'mismatch' - valid, but does not match the gene's canonical chromosome (the silent-mismatch case);
+      * 'match'    - matches the gene's canonical chromosome;
+      * 'unverifiable' - valid chromosome but the gene's location is unknown (cannot confirm);
+      * 'none'     - no chromosome supplied.
+    """
+    entered = canonical_chromosome(chrom)
+    gchrom = gene_chromosome(gene)
+    out = {"entered_raw": chrom, "entered": entered, "valid": entered is not None,
+           "gene": gene, "gene_chrom": gchrom}
+    if chrom in (None, "") or str(chrom).strip() == "":
+        out["status"] = "none"
+        out["message"] = None
+    elif entered is None:
+        out["status"] = "invalid"
+        out["message"] = (f"'{chrom}' is not a standard human chromosome. Use chr1-chr22, chrX, chrY, or chrM.")
+    elif gchrom and entered != gchrom:
+        out["status"] = "mismatch"
+        out["message"] = (f"{gene} is on {gchrom}, not {entered}. Locus scoring uses {gene}'s canonical location "
+                          f"({gchrom}); the entered chromosome does not move the locus.")
+    elif gchrom and entered == gchrom:
+        out["status"] = "match"
+        out["message"] = f"{entered} matches the canonical location of {gene}."
+    else:
+        out["status"] = "unverifiable"
+        out["message"] = (f"{entered} is a valid chromosome, but {gene or 'the gene'} is not in the coordinate "
+                          "table, so the gene/chromosome match cannot be confirmed.")
+    return out
+
+
+def chromosome_context(chrom: str | None) -> dict | None:
+    """A grounded, chromosome-driven advisory (or None for an autosome). These are real biological constraints
+    the chromosome identity alone implies; magnitudes remain locus/subject-dependent (not predicted here)."""
+    c = canonical_chromosome(chrom)
+    if c == "chrM":
+        return {"chrom": "chrM", "severity": "high",
+                "note": ("the mitochondrial genome is NOT addressable by nuclear genome-writing tools "
+                         "(integrases / recombinases / nuclear-targeted Cas9); mtDNA editing requires "
+                         "mitochondrially-targeted base editors (DdCBE / TALED) - out of scope for this tool.")}
+    if c == "chrY":
+        return {"chrom": "chrY", "severity": "medium",
+                "note": ("the Y chromosome is male-specific (absent in 46,XX) and rich in ampliconic / palindromic "
+                         "repeats, so confirm the target is single-copy before trusting a unique-site assumption.")}
+    if c == "chrX":
+        return {"chrom": "chrX", "severity": "low",
+                "note": ("the X chromosome is hemizygous in 46,XY (one copy) but subject to X-inactivation in "
+                         "46,XX (mosaic expression); dosage and durability are sex- and locus-dependent.")}
+    return None

pen_stack/planner/delivery.py

@@ -0,0 +1,55 @@
+"""Delivery recommendation.
+
+Recommend a delivery modality from the total payload (writer effector + cargo) and the target cell type,
+using the documented rule table in configs/delivery_rules.yaml (no hidden constants).
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+_CFG = Path(__file__).resolve().parents[2] / "configs" / "delivery_rules.yaml"
+
+
+@lru_cache(maxsize=1)
+def _rules(path: str | Path = _CFG) -> dict:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+
+
+def _vehicle_of(delivery: str) -> str:
+    """Map a delivery-rule label to a constraint-scan vehicle key (configs/delivery_constraints.yaml)."""
+    d = (delivery or "").lower()
+    if "aav" in d:
+        return "AAV"
+    if "lenti" in d:
+        return "lentiviral"
+    if "plasmid" in d:
+        return "plasmid"
+    return d # mRNA-RNP / LNP-mRNA -> no DNA-vector packaging checks
+
+
+def recommend_delivery(effector_bp: int, cargo_bp: int, ct: str, cargo_seq: str | None = None) -> dict:
+    """Return {delivery, total_bp, rationale}. effector_bp ~= writer length_aa * 3.
+
+    When ``cargo_seq`` is supplied, attaches the delivery-vehicle sequence-constraint scan
+    (vehicle-specific soft penalties + fixes) under ``delivery_constraints``.
+    """
+    cfg = _rules()
+    total = int(effector_bp) + int(cargo_bp)
+    chosen = None
+    for rule in cfg["rules"]:
+        if total <= rule["max_total_bp"]:
+            chosen = {"delivery": rule["delivery"], "total_bp": total,
+                      "rationale": f"total payload {total} bp <= {rule['max_total_bp']} bp"}
+            break
+    if chosen is None:
+        fallback = (cfg["ex_vivo_fallback"] if ct in cfg.get("ex_vivo_cell_types", [])
+                    else cfg["in_vivo_fallback"])
+        chosen = {"delivery": fallback, "total_bp": total,
+                  "rationale": f"total payload {total} bp exceeds dual-AAV; cell type {ct}"}
+    if cargo_seq:
+        from pen_stack.planner.delivery_constraints import scan_delivery
+        chosen["delivery_constraints"] = scan_delivery(cargo_seq, _vehicle_of(chosen["delivery"]))
+    return chosen

pen_stack/planner/delivery_constraints.py

@@ -0,0 +1,110 @@
+"""Delivery-vehicle sequence constraints.
+
+Cargo Polish scans WHAT is written for silencing triggers; this scans the construct for VEHICLE-specific
+sequence problems that hurt the chosen delivery vector: lentiviral internal poly(A) signals (truncate the
+genomic RNA), AAV ITR-interfering inverted repeats / homopolymer slippage, recombinogenic direct repeats,
+and packaging-hostile GC extremes. Output is a soft ``delivery_constraint_risk`` in [0,1] with a band and a
+concrete fix per flag.
+
+These are LABELED HEURISTIC penalties (config: configs/delivery_constraints.yaml), validated only
+directionally, a construct carrying a known problematic element scores higher than a clean one, not a
+predictor of titre. Vehicles that deliver the effector as RNA/protein (mRNA-RNP, LNP-mRNA) have no DNA-vector
+packaging constraints on the cargo here.
+"""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+import yaml
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def _cfg() -> dict:
+    return yaml.safe_load(resource("configs/delivery_constraints.yaml").read_text(encoding="utf-8"))
+
+
+def _clean(seq: str) -> str:
+    return re.sub(r"[^ACGT]", "", (seq or "").upper())
+
+
+def _rc(s: str) -> str:
+    return s.translate(str.maketrans("ACGT", "TGCA"))[::-1]
+
+
+def _gc(s: str) -> float:
+    return (s.count("G") + s.count("C")) / len(s) if s else 0.0
+
+
+def _longest_homopolymer(s: str) -> int:
+    best = run = 1
+    for i in range(1, len(s)):
+        run = run + 1 if s[i] == s[i - 1] else 1
+        best = max(best, run)
+    return best if s else 0
+
+
+def _has_direct_repeat(s: str, unit: int) -> bool:
+    """A >= `unit`-nt substring that occurs at least twice (non-overlapping-ish) → recombinogenic direct repeat."""
+    seen = {}
+    for i in range(len(s) - unit + 1):
+        sub = s[i:i + unit]
+        if sub in seen and i - seen[sub] >= unit:
+            return True
+        seen.setdefault(sub, i)
+    return False
+
+
+def _has_inverted_repeat(s: str, arm: int) -> bool:
+    """A >= `arm`-nt substring whose reverse-complement also occurs → hairpin / ITR-like inverted repeat."""
+    kmers = {s[i:i + arm] for i in range(len(s) - arm + 1)}
+    for i in range(len(s) - arm + 1):
+        if _rc(s[i:i + arm]) in kmers:
+            return True
+    return False
+
+
+def scan_delivery(seq: str, vehicle: str) -> dict:
+    """Vehicle-specific construct scan → soft risk + per-flag suggestions. Unknown/RNA vehicles → no checks."""
+    cfg = _cfg()
+    s = _clean(seq)
+    checks = cfg["vehicles"].get(vehicle, [])
+    flags, risk = [], 0.0
+
+    for name in checks:
+        c = cfg["checks"][name]
+        if name == "internal_polyA":
+            n = len(re.findall(c["pattern"], s))
+            if n:
+                risk += min(c["cap"], c["risk_per_hit"] * n)
+                flags.append({"check": name, "detail": f"{n} internal poly(A) signal(s)",
+                              "suggestion": c["suggestion"]})
+        elif name == "homopolymer_run":
+            if _longest_homopolymer(s) >= c["min_len"]:
+                risk += c["risk_per_run"]
+                flags.append({"check": name, "detail": f"homopolymer run >= {c['min_len']} nt",
+                              "suggestion": c["suggestion"]})
+        elif name == "direct_repeat":
+            if _has_direct_repeat(s, c["unit_len"]):
+                risk += c["risk"]
+                flags.append({"check": name, "detail": f">= {c['unit_len']} nt direct repeat",
+                              "suggestion": c["suggestion"]})
+        elif name == "inverted_repeat":
+            if _has_inverted_repeat(s, c["arm_len"]):
+                risk += c["risk"]
+                flags.append({"check": name, "detail": f">= {c['arm_len']} nt inverted repeat (hairpin)",
+                              "suggestion": c["suggestion"]})
+        elif name == "gc_extreme":
+            gc = _gc(s)
+            if s and (gc < c["gc_low"] or gc > c["gc_high"]):
+                risk += c["risk"]
+                flags.append({"check": name, "detail": f"GC={gc:.2f}", "suggestion": c["suggestion"]})
+
+    risk = round(min(1.0, risk), 4)
+    b = cfg["bands"]
+    band = "low" if risk < b["low"] else ("moderate" if risk < b["moderate"] else "high")
+    return {"vehicle": vehicle, "delivery_constraint_risk": risk, "band": band,
+            "checks_applied": checks, "n_flags": len(flags), "flags": flags,
+            "scope": "labeled heuristic vehicle-packaging penalties (directional), not a titre predictor"}