pen-stack 3.1.0__py3-none-any.whl

pen_stack/rag/qa.py

@@ -0,0 +1,105 @@
+"""Grounded, cited Q&A over the PEN-STACK platform (Phase 2, Step 2.8).
+
+The front door for non-expert users. Contract (enforced by pen_stack.agent.guardrails):
+  * clinical-directive questions are refused;
+  * every *quantitative* claim is produced by a validated tool call (writability / atlas / cross-link),
+    never guessed by the LLM - the answer's ``provenance`` block names the tool;
+  * every factual claim carries a citation (DOIs from the curated atlas/WT-KB).
+
+An optional LLM (Ollama/Qwen via litellm) only *phrases* the grounded facts; it is never the source of a
+number or a citation. With no LLM available the deterministic tool+retrieval path still satisfies the
+contract - that is the whole point.
+"""
+from __future__ import annotations
+
+import re
+
+from pen_stack.agent.guardrails import DISCLAIMER, enforce_grounded, out_of_scope
+from pen_stack.rag.index import build_cards, retrieve
+
+_GENE_RE = re.compile(r"\b([A-Z][A-Z0-9]{2,9})\b")          # crude gene-symbol cue (TRAC, CCR5, ...)
+_FAMILY_HINTS = {
+    "bridge": "bridge_IS110", "is110": "bridge_IS110", "iscro4": "bridge_IS110",
+    "seek": "seek_IS1111", "is1111": "seek_IS1111", "cast": "CAST_VK",
+    "integrase": "serine_integrase", "bxb1": "serine_integrase", "paste": "PE_integrase",
+    "prime": "PE_integrase", "cas9": "Cas9", "cas12a": "Cas12a", "tnpb": "TnpB_Fanzor",
+    "fanzor": "TnpB_Fanzor",
+}
+_WRITABLE_CUES = ("where", "writable", "safe harbour", "safe harbor", "insert", "insertion site", "locus")
+# Standing citation for tool-derived writability claims: the Phase-1 Writable Genome atlas
+# (TRIP durability supervision + clinical-CIS safety supervision).
+_WRITABILITY_CITATIONS = ["10.1016/j.cell.2013.07.018"]   # Akhtar 2013 (TRIP) - durability supervision
+
+
+def _family_in(question: str) -> str | None:
+    q = question.lower()
+    for cue, fam in _FAMILY_HINTS.items():
+        if cue in q:
+            return fam
+    return None
+
+
+def answer(question: str, ct: str = "k562", use_llm: bool = False) -> dict:
+    refusal = out_of_scope(question)
+    if refusal:
+        return {"refused": True, "answer": refusal, "citations": [], "provenance": [],
+                "disclaimer": DISCLAIMER}
+
+    cards = build_cards()
+    retrieved = retrieve(question, cards, k=3)
+    citations = sorted({d for c in retrieved for d in c.citations})
+    provenance: list[dict] = []
+    parts: list[str] = []
+
+    # --- numeric route 1: "where can I write / writable loci for GENE" -> writability tool ---
+    if any(cue in question.lower() for cue in _WRITABLE_CUES):
+        genes = [g for g in _GENE_RE.findall(question) if g not in {"PEN", "STACK", "DNA", "RNA"}]
+        if genes:
+            try:
+                from pen_stack.atlas.crosslink import loci_for_gene
+                g = loci_for_gene(genes[0], ct)
+                if not g.empty:
+                    w = float(g["writability"].max())
+                    provenance.append({"tool": "crosslink.loci_for_gene",
+                                       "args": {"gene": genes[0], "ct": ct},
+                                       "result": {"max_writability": round(w, 3), "n_bins": int(len(g))}})
+                    parts.append(f"For {genes[0]} in {ct}, the most writable bin scores "
+                                 f"{w:.3f} (writability = safety x durability), across {len(g)} bins.")
+                    citations = sorted(set(citations) | set(_WRITABILITY_CITATIONS))
+            except FileNotFoundError:
+                parts.append("(Writable-genome atlas not loaded; numeric writability unavailable.)")
+
+    # --- numeric route 2: "which writer / tell me about FAMILY" -> atlas tool ---
+    fam = _family_in(question)
+    if fam:
+        import pandas as pd
+
+        from pen_stack.rag.index import _ATLAS
+        adf = pd.read_parquet(_ATLAS)
+        sub = adf[adf["family"] == fam]
+        rep = sub[sub["entry_kind"] == "curated_core"]
+        rep = rep.iloc[0] if len(rep) else sub.iloc[0]
+        provenance.append({"tool": "atlas.query", "args": {"family": fam},
+                           "result": {"n_systems": int(len(sub)),
+                                      "reachability_tier": rep.get("reachability_tier"),
+                                      "deliv_class": rep.get("deliv_class")}})
+        parts.append(f"{fam}: {len(sub):,} catalogued systems; reachability {rep.get('reachability_tier')}; "
+                     f"deliverability {rep.get('deliv_class')}; representative {rep['representative_system']}.")
+
+    # --- factual route: retrieval-grounded summary (always cited) ---
+    if retrieved:
+        parts.append("Relevant atlas facts: " + " | ".join(c.text for c in retrieved[:2]))
+
+    if not parts:
+        parts.append("No grounded match in the atlas. Try naming a writer family or a target gene.")
+
+    out = {"refused": False, "answer": " ".join(parts), "citations": citations,
+           "provenance": provenance, "disclaimer": DISCLAIMER}
+    out = enforce_grounded(out)
+    # optional LLM phrasing - presentation only; numbers/citations stay tool-derived (additive field)
+    if use_llm:
+        from pen_stack.rag.llm import phrase
+        phrased = phrase(out["answer"])
+        if phrased:
+            out["answer_phrased"] = phrased
+    return out

pen_stack/score/__init__.py

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

pen_stack/score/recalibrate.py

@@ -0,0 +1,77 @@
+"""Re-ground the scoring axes (Phase 0, Step 0.3).
+
+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 (Phase 2, Step 2.3).
+
+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 Phase-0
+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 PEN-STACK v3.0 program doc."""

pen_stack/server/api.py

@@ -0,0 +1,142 @@
+"""PEN-STACK REST API (Phase 2, Step 2.6) - atlas + cross-link endpoints over FastAPI.
+
+Extends the Phase-1 atlas with the Writer Atlas and the writer<->locus cross-link. Every quantitative
+result is computed by the validated library functions (never guessed); the ``/ask`` route defers numeric
+claims to those tools (Step 2.8). Heavy data is loaded lazily so the app boots without the Phase-1 atlas.
+
+Run: ``uvicorn pen_stack.server.api:app --host 0.0.0.0 --port 8000`` (needs the ``server`` extra).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+try:
+    from fastapi import FastAPI, HTTPException, Query
+except ImportError as e:  # pragma: no cover - server extra optional
+    raise ImportError("FastAPI not installed: pip install 'pen-stack[server]'") from e
+
+from pen_stack import __version__
+
+_ATLAS = Path(__file__).resolve().parents[1] / "atlas" / "atlas.parquet"
+
+app = FastAPI(title="PEN-STACK API", version=__version__,
+              description="Open infrastructure for genome writing: Writer Atlas + Writable Genome cross-link.")
+
+_DISCLAIMER = ("Decision-support only - predictions are calibrated risk/durability estimates, not "
+               "clinical directives. Tier-2/3 reachability is candidate and requires experimental validation.")
+
+
+def _atlas_df() -> pd.DataFrame:
+    if not _ATLAS.exists():
+        raise HTTPException(503, "atlas.parquet not built")
+    return pd.read_parquet(_ATLAS)
+
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "version": __version__, "atlas_present": _ATLAS.exists()}
+
+
+@app.get("/atlas/coverage")
+def atlas_coverage():
+    df = _atlas_df()
+    cov = (df.groupby("family")
+             .agg(n=("representative_system", "size"),
+                  measured=("confidence", lambda s: int((s == "measured").sum())),
+                  reachability_tier=("reachability_tier", "first"),
+                  mechanism=("mechanism_bucket", "first"))
+             .reset_index())
+    return {"families": int(df["family"].nunique()), "systems": int(len(df)),
+            "coverage": cov.to_dict("records"), "disclaimer": _DISCLAIMER}
+
+
+@app.get("/atlas")
+def atlas(family: str | None = None, limit: int = Query(50, le=500)):
+    df = _atlas_df()
+    if family:
+        df = df[df["family"] == family]
+    cols = [c for c in ["representative_system", "family", "confidence", "mechanism_bucket",
+                        "deliv_class", "readiness", "cargo_capacity_bp", "reachability_tier",
+                        "human_cell_activity"] if c in df.columns]
+    return {"n": int(len(df)), "rows": df[cols].head(limit).to_dict("records"), "disclaimer": _DISCLAIMER}
+
+
+@app.get("/crosslink/writers")
+def crosslink_writers(chrom: str, bin: int, ct: str = "k562"):
+    from pen_stack.atlas import crosslink as cl
+    try:
+        w = cl.writers_for_locus(chrom, bin, ct)
+    except FileNotFoundError as e:
+        raise HTTPException(503, str(e)) from e
+    if w.empty:
+        return {"locus": f"{chrom}:bin{bin}", "writers": [], "disclaimer": _DISCLAIMER}
+    fams = w.groupby("family").size().to_dict()
+    return {"locus": f"{chrom}:bin{bin}", "ct": ct,
+            "locus_writability": float(w["locus_writability"].iloc[0]),
+            "families": {k: int(v) for k, v in fams.items()},
+            "n_systems": int(len(w)), "disclaimer": _DISCLAIMER}
+
+
+@app.get("/crosslink/loci")
+def crosslink_loci(family: str, ct: str = "k562", top: int = Query(20, le=200)):
+    from pen_stack.atlas import crosslink as cl
+    try:
+        loci = cl.loci_for_writer(family, ct, top=top)
+    except FileNotFoundError as e:
+        raise HTTPException(503, str(e)) from e
+    return {"family": family, "ct": ct, "loci": loci.to_dict("records"), "disclaimer": _DISCLAIMER}
+
+
+@app.get("/writable")
+def writable(gene: str, ct: str = "k562", top: int = Query(20, le=200)):
+    from pen_stack.atlas.crosslink import loci_for_gene
+    try:
+        g = loci_for_gene(gene, ct)
+    except FileNotFoundError as e:
+        raise HTTPException(503, str(e)) from e
+    if g.empty:
+        return {"gene": gene, "ct": ct, "loci": [], "disclaimer": _DISCLAIMER}
+    cols = ["chrom", "bin", "safety", "p_durable", "writability"]
+    return {"gene": gene, "ct": ct, "loci": g[cols].head(top).to_dict("records"), "disclaimer": _DISCLAIMER}
+
+
+@app.get("/bridge/design")
+def bridge_design(target: str, donor: str, scaffold: str = "ISCro4_enhanced",
+                  ct: str | None = None, scan: bool = False):
+    """Bridge-recombinase design + off-target/QC (Phase 1.5). scan=false by default (genome scan is heavy)."""
+    from pen_stack.bridge.pipeline import design_and_assess
+    res = design_and_assess(target, donor, scaffold, ct=ct, scan=scan)
+    off = res["offtargets"]
+    if off.get("scanned") and "table" in off:
+        t = off["table"]
+        off = {"scanned": True, "n_candidates": off["n_candidates"], "n_exact": off["n_exact"],
+               "top": t.head(20).to_dict("records")}
+    return {"brna": {k: v for k, v in res["brna"].items() if k != "bridge_sequence"} |
+            ({"bridge_sequence_len": len(res["brna"]["bridge_sequence"])} if res["brna"].get("available") else {}),
+            "qc": res["qc"], "offtargets": off, "disclaimer": res["disclaimer"]}
+
+
+@app.get("/ask")
+def ask(q: str):
+    """Grounded, cited Q&A (Step 2.8). Numeric claims are resolved by tool calls, never guessed."""
+    from pen_stack.rag.qa import answer
+    return answer(q)
+
+
+@app.get("/plan")
+def plan(gene: str, intent: str, cargo_bp: int = 2000, ct: str = "k562", k: int = Query(5, le=20)):
+    """Write Planner (Step 3.4): goal + edit_intent -> ranked, traceable plans."""
+    from pen_stack.planner.optimize import EditIntent
+    from pen_stack.planner.pipeline import plan_write
+    try:
+        intent_e = EditIntent(intent)
+    except ValueError as e:
+        raise HTTPException(422, f"unknown edit_intent: {intent}") from e
+    try:
+        plans = plan_write(gene, intent_e, cargo_bp, ct, k=k)
+    except FileNotFoundError as e:
+        raise HTTPException(503, str(e)) from e
+    return {"gene": gene, "intent": intent, "ct": ct, "n": len(plans), "plans": plans,
+            "disclaimer": _DISCLAIMER}

pen_stack/ui/__init__.py

@@ -0,0 +1 @@
+"""pen_stack.ui - see PEN-STACK v3.0 program doc."""