pen-stack 0.1.0__py3-none-any.whl

pen_stack/safety/registry.py

@@ -0,0 +1,255 @@
+"""Hazard registry, the curated, version-pinned signature source for the Guardian.
+
+A *defensive* biosecurity screen. The registry holds, at the FUNCTION / FAMILY / TAXON level only (public
+Pfam accessions + public control-list references), the controlled-hazard categories a genome-writing design
+is screened against. It deliberately contains no hazard sequences and no operational/synthesis detail, it
+is a safeguard, not a guarantee, and not a substitute for institutional biosafety review.
+
+The matcher is intentionally EXPLICIT (keyword/Pfam/alias tokens from the curated config), not a heuristic:
+a safety control should be auditable. Flags come ONLY from the registry (or, when enabled, a wrapped external
+screener), never fabricated. The function screen is what catches an AI-designed homolog: a low-identity
+sequence still carries a hazardous FUNCTION annotation, and function, not homology, is the load-bearing axis.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any, Callable
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.safety.screen import ScreenHit
+
+_REGISTRY_REL = "configs/safety/hazard_registry.yaml"
+
+
+@lru_cache(maxsize=1)
+def _default_registry() -> "HazardRegistry":
+    from pen_stack.safety.pfam_scan import pfam_domain_screen
+    return HazardRegistry.load(external_hook=pfam_domain_screen)
+
+
+def _norm(s: Any) -> str:
+    return str(s or "").strip().lower()
+
+
+def _sep_norm(s: Any) -> str:
+    """Lowercase and collapse separator runs (whitespace / hyphen / underscore) to a single space, so
+    "furin-cleavage", "furin_cleavage" and "furin cleavage" are one token. Keeps the matcher robust to the
+    hyphen/space/underscore variation that is ubiquitous in free-text function descriptions."""
+    return re.sub(r"[\s_\-]+", " ", _norm(s)).strip()
+
+
+def _kw_match(kw: str, text: str) -> bool:
+    """Separator-insensitive, word-boundary keyword match. Two failure modes of a plain substring test:
+    (1) over-broad - the short ricin keyword "rip" matches inside "transc-RIP-tion", a word in almost every
+    genome-editing design, so a benign promoter cassette would false-refuse as ricin; (2) too-narrow - a
+    hyphenated "furin-cleavage" would slip past the space-form keyword "furin cleavage". Normalising separators
+    then matching on alphanumeric boundaries fixes both: "rip" matches "RIP" standalone but not inside a longer
+    word, and "furin cleavage" / "furin-cleavage" / "furin_cleavage" all match."""
+    k = _sep_norm(kw)
+    if not k:
+        return False
+    return re.search(r"(?<![a-z0-9])" + re.escape(k) + r"(?![a-z0-9])", _sep_norm(text)) is not None
+
+
+def _design_function_tokens(design: dict) -> set[str]:
+    """Normalised function annotations declared on a design (NOT free-text justification)."""
+    toks: set[str] = set()
+    for k in ("cargo_function", "function_annotation", "goal_function"):
+        v = design.get(k)
+        if v:
+            toks.add(_norm(v))
+    for k in ("function_tags", "pfam_domains", "annotations"):
+        for v in design.get(k) or []:
+            toks.add(_norm(v))
+    return {t for t in toks if t}
+
+
+def _design_pfam(design: dict) -> set[str]:
+    return {_norm(p) for p in (design.get("pfam_domains") or []) if p}
+
+
+def _design_taxon_text(design: dict) -> str:
+    return " ".join(_norm(design.get(k)) for k in ("source_taxon", "organism", "host_taxon") if design.get(k))
+
+
+@dataclass
+class HazardRegistry:
+    """Loaded, version-pinned hazard signatures + the screen methods that consume them."""
+
+    version: str
+    toxin_functions: list[dict] = field(default_factory=list)
+    regulated_taxa: list[dict] = field(default_factory=list)
+    controlled_functions: list[dict] = field(default_factory=list)
+    chimera_rules: list[dict] = field(default_factory=list)
+    oncogenic_manipulation: dict = field(default_factory=dict)
+    external_enabled: bool = False
+    external_hook: Callable[[str], list[ScreenHit]] | None = None
+
+    # ---- loading -----------------------------------------------------------
+    @classmethod
+    def load(cls, path: str | None = None, *, external_hook: Callable[[str], list[ScreenHit]] | None = None
+             ) -> "HazardRegistry":
+        raw = yaml.safe_load(resource(path or _REGISTRY_REL).read_text(encoding="utf-8"))
+        return cls(
+            version=raw.get("registry_version", "unknown"),
+            toxin_functions=raw.get("toxin_functions", []),
+            regulated_taxa=raw.get("regulated_taxa", []),
+            controlled_functions=raw.get("controlled_functions", []),
+            chimera_rules=raw.get("chimera_rules", []),
+            oncogenic_manipulation=raw.get("oncogenic_manipulation", {}),
+            external_enabled=external_hook is not None,
+            external_hook=external_hook,
+        )
+
+    @staticmethod
+    def default() -> "HazardRegistry":
+        """The registry `screen_design()` uses when no explicit registry is passed: the curated
+        function/taxon signatures PLUS the local Pfam/HMMER sequence-domain screen wired in as
+        the `external_hook`, so a raw cargo sequence for one of the curated toxin families (the SAME
+        accessions in `toxin_functions` above) is caught even with no declared cargo_function. Cached: the
+        HMM profiles parse once, not per request. `HazardRegistry.load()` itself is unchanged (still
+        hookless by default) for callers who want the bare registry or their own hook."""
+        return _default_registry()
+
+    def _prov(self, entry: dict) -> dict:
+        return {"registry_version": self.version, "signature_id": entry.get("id"),
+                "control_ref": entry.get("control_ref"), "source": "hazard_registry (function/family-level)"}
+
+    # ---- screens (each returns typed, provenanced hits) --------------------
+    def function_flags(self, design: dict) -> list[ScreenHit]:
+        """Toxin / controlled-FUNCTION screen. Matches declared Pfam domains OR function keywords.
+        Catches AI-homologs: a low-identity sequence with a hazardous function annotation still flags."""
+        hits: list[ScreenHit] = []
+        toks = _design_function_tokens(design)
+        pfam = _design_pfam(design)
+        for entry in self.toxin_functions + self.controlled_functions:
+            by_pfam = pfam & {_norm(p) for p in entry.get("pfam", [])}
+            by_kw = {kw for kw in (entry.get("keywords") or []) if any(_kw_match(kw, t) for t in toks)}
+            if by_pfam or by_kw:
+                ev = {}
+                if by_pfam:
+                    ev["matched_pfam"] = sorted(by_pfam)
+                if by_kw:
+                    ev["matched_keywords"] = sorted(by_kw)
+                hits.append(ScreenHit(kind="function_flag", detail=entry["name"],
+                                      severity=entry.get("severity", "medium"),
+                                      provenance=self._prov(entry), evidence=ev))
+        return hits
+
+    def oncogenic_flags(self, design: dict) -> list[ScreenHit]:
+        """Oncogenic-manipulation PATTERN screen. Flags the COMBINATION that a flat keyword list misses:
+        a tumor-suppressor gene with a disruptive verb, an oncogene with an activating signature, or an
+        immortalization signature. The asymmetry spares therapy without an allow-list (restoring a suppressor /
+        silencing an oncogene matches neither). Escalates to human review (dual-use, legitimate cancer-model path)."""
+        cfg = self.oncogenic_manipulation
+        if not cfg:
+            return []
+        # screen the declared function annotations only (the artifact, not any free-text justification)
+        text = " " + " | ".join(sorted(_design_function_tokens(design))) + " "
+        if not text.strip(" |"):
+            return []
+
+        def has(keys: list[str]) -> list[str]:
+            return [k for k in (keys or []) if _norm(k) in text]
+
+        supp = has(cfg.get("tumor_suppressors"))
+        onco = has(cfg.get("oncogenes"))
+        disrupt = has(cfg.get("disrupt_verbs"))
+        activate = has(cfg.get("activate_signatures"))
+        immortal = has(cfg.get("immortalization"))
+        therapy = has(cfg.get("therapy_context"))
+
+        reasons = []
+        if supp and disrupt:
+            reasons.append(f"tumor-suppressor disruption ({supp[0]} + {disrupt[0]})")
+        if onco and activate:
+            reasons.append(f"oncogene activation ({onco[0]} + {activate[0]})")
+        if immortal:
+            reasons.append(f"immortalization signature ({immortal[0]})")
+        if not reasons:
+            return []
+        # therapeutic restoration / supplementation with NO disruptive/activating/immortalization signal -> clear.
+        if therapy and not (disrupt or activate or immortal):
+            return []
+        return [ScreenHit(kind="oncogenic_flag", detail=cfg.get("name", "oncogenic manipulation"),
+                          severity=cfg.get("severity", "medium"), provenance=self._prov(cfg),
+                          evidence={"patterns": reasons,
+                                    "suppressor": supp[:2], "oncogene": onco[:2], "disrupt": disrupt[:2],
+                                    "activate": activate[:2], "immortalization": immortal[:2]})]
+
+    def taxon_flags(self, design: dict) -> list[ScreenHit]:
+        """Regulated-pathogen-TAXON screen (Select Agent / Australia Group membership by declared source)."""
+        hits: list[ScreenHit] = []
+        text = _design_taxon_text(design)
+        if not text:
+            return hits
+        for entry in self.regulated_taxa:
+            aliases = [_norm(a) for a in ([entry.get("name")] + (entry.get("aliases") or [])) if a]
+            matched = [a for a in aliases if a and a in text]
+            if matched:
+                hits.append(ScreenHit(kind="taxon_flag", detail=entry["name"],
+                                      severity=entry.get("severity", "medium"),
+                                      provenance=self._prov(entry), evidence={"matched_alias": matched[0]}))
+        return hits
+
+    def chimera_context(self, design: dict) -> list[ScreenHit]:
+        """Hazardous ASSEMBLY of individually-benign parts (toxin+broad delivery; virulence+replication;
+        split-hazard across sub-designs). Operates on declared structure, never invents a part."""
+        hits: list[ScreenHit] = []
+        rules = {r["id"]: r for r in self.chimera_rules}
+
+        cf = _norm(design.get("cargo_function"))
+        has_toxin = bool(self.function_flags(design)) or bool(cf) and any(
+            _kw_match(kw, cf) for e in self.toxin_functions for kw in (e.get("keywords") or []))
+        broad = _norm(design.get("delivery_tropism")) in {"broad", "broad_systemic", "systemic"} or \
+            _norm(design.get("delivery_vehicle")) in {"aav9", "aavrh10"}
+        replicating = bool(design.get("replication_competent"))
+        patho = any(_norm(kw) in _design_function_tokens(design)
+                    for e in self.controlled_functions if e["id"] == "FUNC-PATHO-ESSENTIAL"
+                    for kw in (e.get("keywords") or [])) or "pathogen_essential" in _design_function_tokens(design)
+
+        if has_toxin and broad and "CHIM-TOXIN-PAYLOAD" in rules:
+            r = rules["CHIM-TOXIN-PAYLOAD"]
+            hits.append(ScreenHit(kind="chimera_context", detail=r["detail"], severity=r["severity"],
+                                  provenance=self._prov(r), evidence={"toxin_payload": True, "broad_delivery": True}))
+        if (patho or replicating and self.taxon_flags(design)) and replicating and "CHIM-PATHO-REPLICATION" in rules:
+            r = rules["CHIM-PATHO-REPLICATION"]
+            hits.append(ScreenHit(kind="chimera_context", detail=r["detail"], severity=r["severity"],
+                                  provenance=self._prov(r), evidence={"virulence_or_taxon": True, "replication_competent": True}))
+
+        # split-hazard: scan sub-designs / multi-edit plan; if the assembled plan carries a hazardous
+        # function/taxon that no single sub-design fully declares, flag the assembly. Type-guarded so an
+        # unexpected field shape can never crash the gate (the safety gate must never break verify()).
+        subs: list[dict] = []
+        for key in ("sub_designs", "multiplex", "edits"):
+            v = design.get(key)
+            if isinstance(v, list):
+                subs += [s for s in v if isinstance(s, dict)]
+        if subs and "CHIM-SPLIT-HAZARD" in rules:
+            sub_hits = [h for s in subs for h in (self.function_flags(s) + self.taxon_flags(s))]
+            if sub_hits or self.taxon_flags(design) or patho:
+                r = rules["CHIM-SPLIT-HAZARD"]
+                worst = "high" if any(h.severity == "high" for h in sub_hits) or \
+                    any(h.severity == "high" for h in self.taxon_flags(design)) else r["severity"]
+                hits.append(ScreenHit(kind="chimera_context", detail=r["detail"], severity=worst,
+                                      provenance=self._prov(r),
+                                      evidence={"n_sub_designs": len(subs), "split_hazard": True}))
+        return hits
+
+    def sequence_homology(self, seq: str | None) -> list[ScreenHit]:
+        """Baseline sequence-homology screen. The transparent baseline does NOT embed hazard sequences;
+        real homology screening is delegated to a wrapped external screener (IBBIS Common Mechanism /
+        SecureDNA-style) via `external_screen`. Returns [] here (a safeguard, not a guarantee)."""
+        if self.external_enabled and seq:
+            return self.external_screen(seq)
+        return []
+
+    def external_screen(self, seq: str | None) -> list[ScreenHit]:
+        """Wrapped external sequence screener (disabled unless an `external_hook` was supplied at load)."""
+        if not (self.external_enabled and self.external_hook and seq):
+            return []
+        return list(self.external_hook(seq))

pen_stack/safety/screen.py

@@ -0,0 +1,59 @@
+"""Sequence + function screening, the Guardian linchpin.
+
+Runs the hazard screens over a design and returns typed, provenanced hits. Three+ screens:
+  * function_flag, toxin / controlled-function domains (the screen that catches AI-homologs),
+  * taxon_flag, regulated-pathogen taxon membership (Select Agent / Australia Group),
+  * chimera_context, hazardous assembly of individually-benign parts,
+  * sequence_homology, delegated to a wrapped external screener when enabled (baseline: no-op + a note).
+
+Flags come ONLY from the registry / wrapped screeners, never fabricated. Screening reduces, not eliminates,
+risk; it is a documented, audited safeguard, not a guarantee.
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+ScreenKind = Literal["sequence_homology", "function_flag", "taxon_flag", "chimera_context", "oncogenic_flag"]
+Severity = Literal["low", "medium", "high"]
+
+
+class ScreenHit(BaseModel):
+    """Frozen: a hazard hit's severity cannot be downgraded after screening (a mutable `severity` could be
+    lowered to change the policy decision). Screens construct fresh hits, so immutability has no cost."""
+    model_config = ConfigDict(frozen=True)
+
+    kind: ScreenKind
+    detail: str
+    severity: Severity
+    provenance: dict = Field(default_factory=dict)
+    evidence: dict = Field(default_factory=dict)
+
+
+def _assemble_cargo(design: dict) -> str | None:
+    """Best-effort cargo sequence for the (optional) external homology screen. The baseline does not
+    require it, function/taxon/chimera screens read declared annotations, not raw sequence."""
+    return design.get("cargo_sequence") or design.get("cargo_seq")
+
+
+def screen_design(design: dict, registry=None) -> list[ScreenHit]:
+    """Run all hazard screens over a design. `design` is the structured proposal (declared function tags /
+    Pfam domains / source taxon / delivery / sub-designs), NOT any free-text justification (the artifact
+    decides, not the framing). Returns the list of typed hits (empty == no hazard signal)."""
+    from pen_stack.safety.registry import HazardRegistry # lazy: registry imports ScreenHit from here
+    # the default registry (no explicit override) wires the local Pfam/HMMER sequence screen as its
+    # external_hook, so a raw cargo sequence is checked against the curated toxin families too, not just a
+    # declared cargo_function. A caller wanting the bare, hookless registry still gets it via HazardRegistry.load().
+    reg = registry or HazardRegistry.default()
+    if not isinstance(design, dict):
+        design = dict(design)
+    hits: list[ScreenHit] = []
+    hits += reg.function_flags(design) # toxin / pathogen-essential function domains
+    hits += reg.oncogenic_flags(design) # oncogenic-manipulation pattern (mechanism/synonym-robust)
+    hits += reg.taxon_flags(design) # regulated pathogen taxa
+    hits += reg.chimera_context(design) # hazardous assembly of benign parts
+    seq = _assemble_cargo(design)
+    if seq:
+        hits += reg.sequence_homology(seq) # local Pfam/HMMER screen (default) or a wrapped external screener
+    return hits

pen_stack/safety/standards.py

@@ -0,0 +1,141 @@
+"""Alignment of the Guardian biosecurity screen to community synthesis-screening standards.
+
+The Guardian is an IN-DESIGN, function/family/taxon-level screen. The community synthesis-screening standards
+(the IBBIS Common Mechanism, SecureDNA) screen synthesis orders at the sequence level. This module maps the
+Guardian's four screen kinds and its four decisions onto the Common Mechanism's reported categories and
+ScreenStatus values, and reports the concordance on a labelled set, so the two interoperate. It is a
+concordance, not a certification: the full sequence-screening pipeline is BioFirewall, and the
+authoritative screen is the standard's own tool. The mapping never changes a Guardian decision; it only
+expresses it in the standard's vocabulary.
+
+References (verified):
+  IBBIS Common Mechanism for DNA Synthesis Screening (CLI: commec), IBBIS, MIT-licensed,
+    https://github.com/ibbis-bio/common-mechanism ; Wheeler et al. 2024, Applied Biosafety 29(2):71-78,
+    DOI 10.1089/apb.2023.0034.
+  SecureDNA, SecureDNA Foundation, privacy-preserving cryptographic screening; Baum et al.,
+    arXiv:2403.14023 (DOI 10.48550/arXiv.2403.14023).
+  US Federal Select Agents Program: 42 CFR 73, 7 CFR 331, 9 CFR 121 (selectagents.gov).
+  Australia Group control lists for human/animal pathogens and toxins and for plant pathogens
+    (australiagroup.net).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pen_stack.safety.policy import SafetyVerdict, decide
+from pen_stack.safety.screen import screen_design
+
+COMMON_MECHANISM = {
+    "name": "The Common Mechanism for DNA Synthesis Screening (commec)",
+    "run_by": "IBBIS (International Biosecurity and Biosafety Initiative for Science)",
+    "license": "MIT",
+    "repo": "https://github.com/ibbis-bio/common-mechanism",
+    "citation_doi": "10.1089/apb.2023.0034",
+    # ScreenStatus values reported by the Common Mechanism (commec/config/result.py).
+    "screen_status": ["Pass", "Warning", "Flag", "Warning (Cleared)", "Flag (Cleared)"],
+    "screen_steps": ["Biorisk Search", "Nucleotide Taxonomy Search", "Protein Taxonomy Search",
+                     "Low Concern Search"],
+    # the three user-facing output categories (IBBIS FAQ).
+    "categories": [
+        "flagged sequences of concern (virulence factors and toxins)",
+        "areas of similarity to regulated pathogens",
+        "matches to genes with a known benign function",
+    ],
+}
+
+SECUREDNA = {
+    "name": "SecureDNA",
+    "run_by": "SecureDNA Foundation",
+    "mechanism": "privacy-preserving cryptographic exact-match window screening (>= 30 nt)",
+    "citation_arxiv": "2403.14023",
+    "output": "binary match to deny (exemption-token override); no public per-category taxonomy, so the "
+              "Guardian aligns to it only at the pass/deny level.",
+}
+
+CONTROL_LISTS = {
+    "us_select_agents": {"refs": ["42 CFR 73", "7 CFR 331", "9 CFR 121"], "url": "https://www.selectagents.gov/"},
+    "australia_group": {
+        "lists": ["List of Human and Animal Pathogens and Toxins for Export Control",
+                  "List of Plant Pathogens for Export Control"],
+        "url": "https://www.australiagroup.net/",
+    },
+}
+
+# Guardian screen kind -> Common Mechanism step + reported category.
+SCREEN_KIND_TO_CM = {
+    "function_flag": {"cm_step": "Biorisk Search",
+                      "cm_category": "flagged sequences of concern (virulence factors and toxins)"},
+    "taxon_flag": {"cm_step": "Nucleotide/Protein Taxonomy Search",
+                   "cm_category": "areas of similarity to regulated pathogens"},
+    "sequence_homology": {"cm_step": "Biorisk/Taxonomy homology",
+                          "cm_category": "homology to a regulated toxin, virus or non-viral pathogen"},
+    # the Common Mechanism screens per-window sequences, not declared assemblies; chimera-context has no direct
+    # CM step and is reported as an in-design signal the per-window standard does not cover.
+    "chimera_context": {"cm_step": "(none: assembly-level, not per-window)",
+                        "cm_category": "assembly-level hazard not screened by the per-window standard"},
+}
+
+# Guardian decision -> Common Mechanism ScreenStatus (escalate maps to Warning, the CM "equally-good matches"
+# ambiguous tie; refuse maps to Flag, the CM higher-concern hit).
+DECISION_TO_CM_STATUS = {"clear": "Pass", "flag": "Warning", "escalate": "Warning", "refuse": "Flag"}
+# Guardian decision -> SecureDNA order-level outcome (binary, with review for the ambiguous middle).
+DECISION_TO_SECUREDNA = {"clear": "pass", "flag": "review", "escalate": "review", "refuse": "deny"}
+
+
+def align_to_common_mechanism(safety: SafetyVerdict) -> dict[str, Any]:
+    """Express a Guardian SafetyVerdict in the standards' vocabulary: the order-level Common Mechanism
+    ScreenStatus, the SecureDNA pass/deny outcome, and the per-hit category mapping. No decision is changed."""
+    hits = [{"guardian_kind": h.kind, "detail": h.detail, "severity": h.severity,
+             **SCREEN_KIND_TO_CM.get(h.kind, {"cm_step": "(unmapped)", "cm_category": "(unmapped)"})}
+            for h in (safety.hits or [])]
+    return {
+        "guardian_decision": safety.decision,
+        "common_mechanism_status": DECISION_TO_CM_STATUS.get(safety.decision, "Warning"),
+        "securedna_outcome": DECISION_TO_SECUREDNA.get(safety.decision, "review"),
+        "hits": hits,
+        "note": "in-design concordance, not certification; BioFirewall is the downstream "
+                "sequence-screening gate, and the standard's own tool is authoritative.",
+    }
+
+
+def _decision_for(design: dict) -> SafetyVerdict:
+    """Screen a design and decide, without the audit side-effect of the full gate (this is a report path)."""
+    hits = screen_design(design)
+    decision, reason = decide(hits)
+    return SafetyVerdict(decision=decision, hits=hits, reason=reason,
+                         provenance={"source": "standards.concordance"})
+
+
+def concordance_report(probes: list[dict] | None = None) -> dict[str, Any]:
+    """Run the Guardian over a labelled set and report, verbatim, the concordance between its decisions
+    (expressed as Common Mechanism ScreenStatus) and the expected status (Pass for benign, Flag/Warning for a
+    hazard). Loads the committed safety probes when none are supplied."""
+    if probes is None:
+        import yaml
+
+        from pen_stack._resources import resource
+        raw = yaml.safe_load(resource("configs/safety/probes.yaml").read_text(encoding="utf-8"))
+        probes = [{"name": e.get("name"), "design": e["design"], "label": "benign"}
+                  for e in raw.get("benign_controls", [])]
+        probes += [{"name": e.get("name"), "design": e["design"], "label": "hazard"}
+                   for e in raw.get("hazard_probes", [])]
+    rows = []
+    for p in probes:
+        sv = _decision_for(p["design"])
+        cm = DECISION_TO_CM_STATUS.get(sv.decision, "Warning")
+        # benign should map to Pass; a hazard should map to a non-Pass status (Warning/Flag).
+        expected_nonpass = p["label"] == "hazard"
+        concordant = (cm != "Pass") == expected_nonpass
+        rows.append({"name": p["name"], "label": p["label"], "guardian_decision": sv.decision,
+                     "common_mechanism_status": cm, "concordant": concordant})
+    n = len(rows)
+    n_conc = sum(r["concordant"] for r in rows)
+    return {
+        "n": n, "n_concordant": n_conc, "concordance": round(n_conc / n, 4) if n else None,
+        "discordances": [r for r in rows if not r["concordant"]],
+        "rows": rows,
+        "standard": COMMON_MECHANISM["name"], "standard_doi": COMMON_MECHANISM["citation_doi"],
+        "note": "Reported verbatim. A concordance between the in-design Guardian and the Common Mechanism's "
+                "reported status, not a certification; the standard's own tool remains authoritative and "
+                "BioFirewall is the downstream sequence-screening gate.",
+    }

pen_stack/score/__init__.py

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

pen_stack/score/recalibrate.py

@@ -0,0 +1,77 @@
+"""Re-ground the scoring axes.
+
+The prior `prog`/`cargo` axes were effectively hand-set flags (`s_prog=1.0` for everything) that
+required per-enzyme overrides to pass any gate. Here each axis is a documented, continuous function
+of a *measured* input read from ``configs/score_axes.yaml``. There are NO per-enzyme override
+constants in this module - that invariant is checked by ``tests/unit/test_no_overrides.py``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import yaml
+
+_CFG_PATH = Path(__file__).resolve().parents[2] / "configs" / "score_axes.yaml"
+
+
+def load_axes_config(path: str | Path = _CFG_PATH) -> dict:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+
+
+def recalibrate_cargo(df: pd.DataFrame, cfg: dict) -> pd.DataFrame:
+    """S_Cargo from measured cargo bp (monotone); fall back to upstream s_cargo if bp unknown."""
+    cap = float(cfg["cargo"]["cap_bp"])
+    out = df.copy()
+    if "cargo_capacity_bp" in out.columns:
+        bp = out["cargo_capacity_bp"].astype("float64").clip(0, cap)
+        recal = np.log1p(bp) / np.log1p(cap)
+        # only override where we actually have a measured bp; otherwise keep upstream s_cargo
+        out["S_Cargo"] = np.where(bp.notna() & (bp > 0), recal, out.get("s_cargo"))
+    else:
+        out["S_Cargo"] = out.get("s_cargo")
+    return out
+
+
+def recalibrate_prog(df: pd.DataFrame, cfg: dict) -> pd.DataFrame:
+    """S_Prog from MEASURED targeting modality (documented anchors), not a 0/1 flag."""
+    p = cfg["programmability"]
+    anchor = p["modality_anchor"]
+    bip_fams = set(p.get("bipartite_reprogrammable_families", []))
+    bonus = float(p.get("bipartite_bonus_to", 1.0))
+
+    def _prog(row) -> float:
+        fam = row.get("family")
+        if fam in bip_fams:
+            return bonus
+        modality = row.get("targeting_modality")
+        if modality in anchor:
+            return float(anchor[modality])
+        # fall back to upstream s_prog if no modality info (documented degradation, not an override)
+        return float(row["s_prog"]) if pd.notna(row.get("s_prog")) else np.nan
+
+    out = df.copy()
+    out["S_Prog"] = out.apply(_prog, axis=1)
+    return out
+
+
+def backfill_length(df: pd.DataFrame, cfg: dict) -> pd.DataFrame:
+    """Backfill length_aa from independently-verified UniProt lengths (upstream has all None)."""
+    table = cfg["length_aa_backfill"]
+    out = df.copy()
+    key = "entity_id" if "entity_id" in out.columns else "representative_system"
+    filled = out["length_aa"] if "length_aa" in out.columns else pd.Series([None] * len(out))
+    out["length_aa"] = [
+        (table.get(k) if (pd.isna(v) or v is None) else v)
+        for k, v in zip(out[key], filled)
+    ]
+    return out
+
+
+def recalibrate_all(df: pd.DataFrame, cfg: dict | None = None) -> pd.DataFrame:
+    cfg = cfg or load_axes_config()
+    out = backfill_length(df, cfg)
+    out = recalibrate_cargo(out, cfg)
+    out = recalibrate_prog(out, cfg)
+    return out

pen_stack/score/therapeutic.py

@@ -0,0 +1,85 @@
+"""Therapeutic-readiness scoring across families.
+
+The motto's "therapeutic-ready" axis, realised and *measured*: score every Writer-Atlas system for
+deliverability, cargo capacity, immunogenicity proxy, and human-cell compatibility - using the
+re-grounded axes (configs/score_axes.yaml is the single source of thresholds; no per-enzyme overrides).
+All components are retained on the row (a transparent profile, never collapsed to one opaque number).
+
+Inputs : pen_stack/atlas/atlas.parquet, configs/score_axes.yaml.
+Outputs: atlas.parquet updated with deliv_class / S_Deliv / S_Cargo / S_HumanCell / readiness.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from pen_stack.score.recalibrate import load_axes_config
+
+_ROOT = Path(__file__).resolve().parents[2]
+_ATLAS = _ROOT / "pen_stack" / "atlas" / "atlas.parquet"
+
+
+def deliverability_class(length_aa: float | None, cfg: dict) -> str:
+    """AAV single (<=~730 aa effector) / split-AAV (<=1500) / mRNA-RNP, from effector size."""
+    d = cfg["deliverability"]
+    if length_aa is None or (isinstance(length_aa, float) and np.isnan(length_aa)):
+        return "unknown"
+    L = float(length_aa)
+    if L <= d["aav_single_max_aa"]:
+        return "AAV"
+    if L <= d["split_aav_max_aa"]:
+        return "split-AAV"
+    return "mRNA-RNP"
+
+
+def _s_cargo(bp, cfg) -> float:
+    cap = float(cfg["cargo"]["cap_bp"])
+    if bp is None or (isinstance(bp, float) and np.isnan(bp)) or bp <= 0:
+        return np.nan
+    return float(np.log1p(min(float(bp), cap)) / np.log1p(cap))
+
+
+def _s_humancell(hca: str | None) -> float:
+    """Coarse human-cell compatibility from the curated activity string (measured > demonstrated > none)."""
+    t = (hca or "").lower()
+    if "not measured" in t or "bacterial" in t:
+        return 0.0
+    if "low in human" in t or "modest" in t:
+        return 0.4
+    if "human cell" in t or "human cells" in t or "primary t cell" in t or "hepatocyte" in t or "clinical" in t:
+        return 1.0
+    return np.nan
+
+
+def therapeutic_profile(atlas_df: pd.DataFrame, cfg: dict | None = None) -> pd.DataFrame:
+    cfg = cfg or load_axes_config()
+    df = atlas_df.copy()
+    classes = cfg["deliverability"]["classes"]
+
+    df["deliv_class"] = df["length_aa"].apply(lambda L: deliverability_class(L, cfg))
+    df["S_Deliv"] = df["deliv_class"].map(classes) # unknown -> NaN
+    df["S_Cargo"] = df["cargo_capacity_bp"].apply(lambda bp: _s_cargo(bp, cfg))
+    df["S_HumanCell"] = df["human_cell_activity"].apply(_s_humancell)
+    df["S_DSBfree"] = df["dsb_free"].apply(lambda b: 1.0 if b is True else (0.0 if b is False else np.nan))
+
+    # transparent composite (mean of available components); components remain on the row
+    comp = df[["S_Deliv", "S_Cargo", "S_HumanCell", "S_DSBfree"]]
+    df["readiness"] = comp.mean(axis=1, skipna=True)
+    return df
+
+
+def apply_to_atlas(atlas_parquet: str | Path = _ATLAS, out: str | Path = _ATLAS) -> pd.DataFrame:
+    atlas = pd.read_parquet(atlas_parquet)
+    out_df = therapeutic_profile(atlas)
+    out_df.to_parquet(out, index=False)
+    return out_df
+
+
+if __name__ == "__main__": # pragma: no cover
+    a = apply_to_atlas()
+    cores = a[a.entry_kind == "curated_core"]
+    print(cores[["representative_system", "length_aa", "deliv_class", "S_Deliv",
+                 "S_Cargo", "S_HumanCell", "readiness"]].to_string(index=False))
+    print("\ndeliv_class distribution:\n", a["deliv_class"].value_counts(dropna=False))

pen_stack/server/__init__.py

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