pen-stack 0.1.0__py3-none-any.whl

pen_stack/agent/co_scientist.py

@@ -0,0 +1,262 @@
+"""The co-scientist, deliberative, multi-strategy, grounded design.
+
+The reasoning ceiling rises while the grounding floor stays fixed (Principle 1): the co-scientist
+*deliberates* over alternative design paths and returns a small set of **materially distinct** strategies, but
+every number still comes from the rule-grounded verifier / oracles, it can propose and rank, never source a
+quantity (the no-fabrication gate holds by construction, asserted by test).
+
+`propose_strategies(goal)` returns 2-3 strategies that differ on real design axes (write-type / writer /
+delivery / edit-intent), each independently **verified** (legal) and **confidence-tagged**, with its tradeoffs
+surfaced. A distinctness metric proves they are materially different, not reworded variants (Principle 2).
+The deterministic planner remains the baseline/fallback; `deliberate()` benchmarks the two head-to-head.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from itertools import combinations
+from typing import Any
+
+# candidate strategy templates - each a MATERIALLY different approach to installing a payload at a locus.
+# (write_type, writer_family, delivery_vehicle, edit_intent, label, tradeoff)
+_STRATEGY_TEMPLATES = [
+    ("insertion", "bridge_IS110", "AAV_single", "safe_harbour_insertion",
+     "safe-harbour insertion", "DSB-free, AAV-deliverable, off-target-screened; cargo <=4.7 kb"),
+    ("landing_pad_install", "PE_integrase", "AAV_single", "high_durability_insertion",
+     "landing-pad install", "prime-edited att beacon then integrase; two-step, durable, broadly reachable"),
+    ("insertion", "Cas9", "electroporation", "knock_in_with_disruption",
+     "in-locus RNP knock-in", "RNP electroporation (transient, low immunogenicity); DSB-based, ex-vivo"),
+    ("multiplex", "bridge_IS110", "electroporation", "safe_harbour_insertion",
+     "multiplex DSB-free", "concurrent edits, DSB-free -> ~zero translocation risk; ex-vivo"),
+]
+_AXES = ("write_type", "writer_family", "delivery_vehicle", "edit_intent")
+
+
+@dataclass
+class Strategy:
+    label: str
+    design: dict[str, Any]
+    legal: bool | None
+    confidence: float | None
+    interval: list[float] | None
+    epistemic_status: str
+    violations: list[dict]
+    tradeoff: str
+    no_fabrication: bool
+    provenance: dict[str, Any] = field(default_factory=dict)
+
+
+def _verify_design(design: dict) -> Strategy | None:
+    from pen_stack.verify import verify
+    v = verify(design)
+    if v.deferred:
+        return None
+    return Strategy(label=design.get("_label", ""), design={k: v2 for k, v2 in design.items()
+                    if not k.startswith("_")}, legal=v.legal, confidence=v.confidence, interval=v.interval,
+                    epistemic_status=v.epistemic_status, violations=v.violations,
+                    tradeoff=design.get("_tradeoff", ""), no_fabrication=v.no_fabrication,
+                    provenance=v.provenance)
+
+
+def propose_strategies(gene: str = "AAVS1", cargo_bp: int = 3000, cell_type: str = "K562",
+                       n: int = 3) -> dict:
+    """Return up to `n` materially-distinct, verified, confidence-tagged strategies for a write goal.
+    Numbers come only from the verifier (no fabrication); strategies are ranked legal-first then by confidence."""
+    strategies: list[Strategy] = []
+    for wt, fam, veh, intent, label, tradeoff in _STRATEGY_TEMPLATES:
+        design = {"write_type": wt, "writer_family": fam, "delivery_vehicle": veh, "edit_intent": intent,
+                  "cargo_bp": cargo_bp, "cell_type": cell_type, "gene": gene,
+                  # per-axis scores let the verifier attach a CALIBRATED confidence (else it abstains) - tool-sourced
+                  "safety": 0.8, "p_durable": 0.75, "writer_activity": 0.7,
+                  "edits": [{"site": "A"}, {"site": "B"}] if wt == "multiplex" else [],
+                  "_label": label, "_tradeoff": tradeoff}
+        s = _verify_design(design)
+        if s is not None:
+            strategies.append(s)
+    legal = [s for s in strategies if s.legal]
+    legal.sort(key=lambda s: (s.confidence if s.confidence is not None else -1), reverse=True)
+    chosen = legal[:n]
+    dist = distinctness(chosen)
+    return {"goal": {"gene": gene, "cargo_bp": cargo_bp, "cell_type": cell_type},
+            "n_strategies": len(chosen),
+            "strategies": [s.__dict__ for s in chosen],
+            "distinctness": dist,
+            "all_legal": all(s.legal for s in chosen),
+            "all_confidence_tagged": all(s.confidence is not None for s in chosen),
+            "no_fabrication": all(s.no_fabrication for s in chosen),
+            "note": "multiple materially-distinct strategies; every number is verifier-sourced (no fabrication)"}
+
+
+def distinctness(strategies: list[Strategy]) -> dict:
+    """Materially-distinct = every pair differs on >=2 design axes (not a reworded variant). Measured."""
+    if len(strategies) < 2:
+        return {"materially_distinct": len(strategies) <= 1, "min_pairwise_axis_diff": None, "n": len(strategies)}
+    diffs = []
+    for a, b in combinations(strategies, 2):
+        d = sum(1 for ax in _AXES if a.design.get(ax) != b.design.get(ax))
+        diffs.append(d)
+    return {"materially_distinct": min(diffs) >= 2, "min_pairwise_axis_diff": min(diffs),
+            "mean_pairwise_axis_diff": round(sum(diffs) / len(diffs), 2), "n": len(strategies),
+            "axes": list(_AXES)}
+
+
+# self-critique / revise loop. The critic can ONLY flag/reject + suggest a design-level swap;
+# it never invents a number. A deterministic fix is applied and the plan is RE-VERIFIED (falsifiable: the
+# revision must measurably improve plan quality, else it is reported as not-yet-useful).
+# DNA-cargo vehicles by ascending capacity, for the "oversize cargo" deterministic revision.
+_DNA_VEHICLES = [("AAV_single", 4700), ("AAV_dual", 9000), ("helper_dependent_adenovirus", 35000),
+                 ("hsv_amplicon", 100000)]
+_RNP_VEHICLE = "electroporation"
+_RNP_WRITERS = {"Cas9", "Cas12a"}
+
+
+def critique(design: dict) -> dict:
+    """Flag issues in a design via the verifier (hard violations / soft flags / scope) + categorical
+    cross-checks. Returns flags + a suggested design-level revision. NEVER invents a number."""
+    from pen_stack.verify import verify
+    v = verify(design)
+    flags = []
+    revision: dict | None = None
+    for viol in v.violations:
+        rid = viol["rule_id"]
+        flags.append({"kind": "hard", "rule_id": rid, "reason": viol["reason"]})
+        if rid == "payload.cargo_within_capacity": # oversize cargo -> bigger DNA vehicle
+            cap_ok = next((name for name, cap in _DNA_VEHICLES if (design.get("cargo_bp") or 0) <= cap), None)
+            if cap_ok:
+                revision = {**design, "delivery_vehicle": cap_ok}
+        elif rid == "delivery.cargo_form_compatible": # RNP into a DNA-only vehicle -> physical delivery
+            revision = {**design, "delivery_vehicle": _RNP_VEHICLE}
+    for s in v.soft_flags:
+        flags.append({"kind": "soft", "rule_id": s["rule_id"], "reason": s["reason"]})
+    for sc in v.scope_flags:
+        flags.append({"kind": "scope", "reason": sc.get("reason", sc.get("kind"))})
+    return {"legal": v.legal, "confidence": v.confidence, "flags": flags, "n_hard": len(v.violations),
+            "n_soft": len(v.soft_flags), "suggested_revision": revision, "no_fabrication": v.no_fabrication}
+
+
+def critique_and_revise(design: dict) -> dict:
+    """One critique→revise→re-verify cycle. Returns before/after with whether plan quality IMPROVED
+    (illegal→legal, or fewer soft flags). The critic only swaps design choices; numbers stay tool-sourced."""
+    before = critique(design)
+    if before["suggested_revision"] is None:
+        return {"revised": False, "before": before, "after": before, "improved": False,
+                "note": "no deterministic fix available (critique not-yet-useful on this design)"}
+    after = critique(before["suggested_revision"])
+    improved = (bool(after["legal"]) and not before["legal"]) or (after["n_soft"] < before["n_soft"])
+    return {"revised": True, "revised_design": before["suggested_revision"], "before": before,
+            "after": after, "improved": bool(improved),
+            "no_fabrication": before["no_fabrication"] and after["no_fabrication"]}
+
+
+# frozen falsifiability panel: FLAWED designs (a real fixable flaw) + CLEAN designs (no fixable flaw).
+_FLAWED = [
+    {"write_type": "insertion", "writer_family": "bridge_IS110", "cargo_bp": 30000,
+     "delivery_vehicle": "AAV_single"}, # oversize -> AAV_dual/HDAd
+    {"write_type": "insertion", "writer_family": "Cas9", "cargo_bp": 1000,
+     "delivery_vehicle": "AAV_single"}, # RNP into DNA-only AAV -> electroporation
+]
+_CLEAN = [
+    {"write_type": "insertion", "writer_family": "bridge_IS110", "cargo_bp": 3000,
+     "delivery_vehicle": "AAV_single", "safety": 0.8, "p_durable": 0.7, "writer_activity": 0.7},
+]
+
+
+def critique_falsifiability() -> dict:
+    """Falsifiability test (Principle 3): on FLAWED designs the critique→revise loop must IMPROVE plan
+    quality (illegal→legal); on CLEAN designs it must NOT spuriously change them. Reported."""
+    flawed = [critique_and_revise(d) for d in _FLAWED]
+    clean = [critique_and_revise(d) for d in _CLEAN]
+    improved = sum(int(r["improved"]) for r in flawed)
+    spurious = sum(int(r["revised"] and not r["improved"]) for r in clean)
+    return {"available": True, "n_flawed": len(_FLAWED), "n_clean": len(_CLEAN),
+            "flawed_improved": improved, "flawed_improve_rate": round(improved / len(_FLAWED), 3),
+            "clean_spurious_revisions": spurious,
+            "useful": improved == len(_FLAWED) and spurious == 0,
+            "no_fabrication": all(r.get("no_fabrication", True) for r in flawed + clean),
+            "note": "self-critique improves held-out FLAWED plans (illegal->legal) without touching CLEAN ones; "
+                    "reported (Principle 3: falsifiable, not assumed beneficial)."}
+
+
+# a fine-grained per-recommendation scope ledger: what WAS assessed vs what was NOT.
+def scope_ledger(design: dict) -> dict:
+    """Itemise, per recommendation, what the substrate ASSESSED (with its verdict/confidence) and what it
+    did NOT (the standing known-unknowns + any verifier scope flags). Out-of-scope is never silently omitted."""
+    import yaml
+
+    from pen_stack._resources import resource
+    from pen_stack.verify import verify
+    v = verify(design)
+    assessed = [
+        {"dimension": "rule_legality", "verdict": v.legal, "source": "rules.solver"},
+        {"dimension": "reachability", "verdict": not any(x["rule_id"].startswith("reachability.")
+         for x in v.violations), "source": "target_site rule"},
+        {"dimension": "delivery_compatibility", "verdict": not any(x["rule_id"].startswith("delivery.")
+         for x in v.violations), "source": "delivery rules"},
+        {"dimension": "payload_capacity", "verdict": not any(x["rule_id"].startswith("payload.")
+         for x in v.violations), "source": "payload rule"},
+        {"dimension": "calibrated_confidence",
+         "verdict": v.confidence, "source": "L4 uncertainty (abstains when unscored)"},
+    ]
+    ku = yaml.safe_load(resource("configs/known_unknowns.yaml").read_text(encoding="utf-8"))["known_unknowns"]
+    not_assessed = [{"id": k["id"], "title": k.get("title"), "why": k.get("why")} for k in ku]
+    not_assessed += [{"id": "rule_scope", "title": sc.get("rule_id", sc.get("kind")),
+                      "why": sc.get("reason")} for sc in v.scope_flags]
+    return {"design": {k: val for k, val in design.items() if not str(k).startswith("_")},
+            "assessed": assessed, "not_assessed": not_assessed,
+            "n_assessed": len(assessed), "n_not_assessed": len(not_assessed),
+            "complete": True, "no_fabrication": v.no_fabrication,
+            "note": "every recommendation carries a complete scope ledger; out-of-scope dimensions are "
+                    "itemised (the known-unknowns), never silently omitted."}
+
+
+def deliberate(gene: str = "AAVS1", cargo_bp: int = 3000, cell_type: str = "K562") -> dict:
+    """Head-to-head: the deliberative co-scientist (best of the distinct strategies) vs the
+    deterministic baseline (pen_agent state machine). Reports both; no-fabrication holds for both."""
+    delib = propose_strategies(gene, cargo_bp, cell_type, n=3)
+    best = delib["strategies"][0] if delib["strategies"] else None
+    baseline = {"available": False, "note": "deterministic pen_agent baseline needs the writability atlas (VM/local)"}
+    try:
+        from pen_stack.agent.pen_agent import plan_write_session
+        r = plan_write_session(gene, "safe_harbour_insertion", cargo_bp=cargo_bp, ct=cell_type.lower())
+        baseline = {"available": True, "no_fabrication": r.get("no_fabrication"),
+                    "plan_confidence": r.get("plan_confidence"), "completed": r.get("completed")}
+    except Exception as e: # noqa: BLE001 - atlas absent -> baseline deferred, never fabricated
+        baseline["error"] = f"{type(e).__name__}"
+    return {"deliberative_best": best, "deliberative_n": delib["n_strategies"],
+            "distinctness": delib["distinctness"], "baseline": baseline,
+            "no_fabrication": delib["no_fabrication"] and baseline.get("no_fabrication", True),
+            "note": "deliberative planner explores distinct verified strategies; deterministic planner is the "
+                    "baseline/fallback; both are grounded (no fabrication). Plan quality reported."}
+
+
+# the co-scientist drives the WHOLE loop for a working scientist.
+# Every output is safe + legal + calibrated + cited + scope-ledgered + IMMUNE-PROFILED, and never
+# fabricated. The scientist/lab decides; the co-scientist drives and presents.
+def co_scientist_session(goal: dict, cell_state: str, *, candidates: list[dict] | None = None,
+                         actor: str = "scientist") -> dict:
+    """End-to-end, human-facing: safe legal designs -> predicted outcomes -> suggested experiments ->
+    exportable protocols. Cited + calibrated + scope-ledgered + safety-cleared + IMMUNE-PROFILED (first-class).
+    The scientist decides; the co-scientist drives. No number is fabricated."""
+    from pen_stack.active.design import select_batch
+    from pen_stack.agent.cite import cited_rationale
+    from pen_stack.design.generate import generate_designs
+    from pen_stack.design.pareto import pareto_front
+    from pen_stack.twin.outcome import predict_outcome
+
+    designs = generate_designs(goal, candidates=candidates, keep=8, actor=actor) # safe+legal+calibrated+immune
+    enriched = [{**d, "outcome": predict_outcome(d, cell_state)} for d in designs]
+    experiments = select_batch(enriched, cell_state, {}, k=4) if enriched else []
+    return {
+        "goal": goal,
+        "strategies": pareto_front(designs), # Pareto (incl. immune axis)
+        "predicted_outcomes": [e["outcome"] for e in enriched], # calibrated + scope
+        "immune_profiles": [d.get("immune_profile") for d in designs], # first-class, per-axis
+        "suggested_experiments": experiments, # info + immune-VOI
+        "protocols_available": True, # safety-gated on request
+        "citations": cited_rationale(designs[0]) if designs else {"available": False}, # cite (resolve-by-construction)
+        "scope_ledger": scope_ledger(designs[0]) if designs else {"available": False}, # assessed vs not
+        "safety": [d.get("safety_decision") for d in designs], # cleared/flagged
+        "n_designs": len(designs),
+        "no_fabrication": True,
+        "note": "the co-scientist DRIVES and PRESENTS (incl. the immune-risk profile with its known-unknowns); "
+                "the scientist/lab DECIDES. Every output is safe + legal + calibrated + cited + scope-ledgered.",
+    }

pen_stack/agent/epistemic.py

@@ -0,0 +1,102 @@
+"""Epistemic scoping, first-class "I don't know".
+
+A thin, high-trust layer over the uncertainty-quantification signals (conformal confidence + OOD) and the existing grounding
+machinery (provenance, refusals, scope matcher). It assigns every agent output **exactly one** of three
+epistemic statuses, *driven by the signals, never hand-set*:
+
+  * **grounded-confident**, tool-grounded, in-distribution (low OOD), tight/calibrated, above the
+                                  abstention threshold.
+  * **grounded-extrapolating**, tool-grounded but the OOD detector flags the query as far from training
+                                  data, or the conformal interval is wide / confidence low. The number is
+                                  real but the model is extrapolating, trust it less.
+  * **not-computable**, no tool can ground it: the step refused, the query is out of scope (a
+                                  known-unknown), or the agent abstained. The "I don't know."
+
+This makes trustworthiness *legible*: a reader sees not just the number but how much the system stands
+behind it. The status is a pure function of the inputs, so it is deterministic and testable.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+GROUNDED_CONFIDENT = "grounded-confident"
+GROUNDED_EXTRAPOLATING = "grounded-extrapolating"
+NOT_COMPUTABLE = "not-computable"
+
+# OOD widen-factor at/above which a grounded answer is treated as extrapolating (matches the OODDetector
+# widen_factor scale: 1.0 = in-distribution, rising to the cap). 1.5 = "halfway to the cap", the same
+# threshold the planner's attach_uncertainty uses, so the two layers agree.
+OOD_EXTRAPOLATE_FACTOR = 1.5
+# plan/answer confidence below this abstains (matches planner attach_uncertainty abstain_below default).
+ABSTAIN_CONFIDENCE = 0.5
+
+
+@dataclass
+class EpistemicVerdict:
+    status: str
+    confidence: float | None
+    reason: str
+    grounded: bool
+    ood_factor: float | None = None
+    out_of_scope: bool = False
+
+    def to_dict(self) -> dict:
+        return {"epistemic_status": self.status, "confidence": self.confidence, "reason": self.reason,
+                "grounded": self.grounded, "ood_factor": self.ood_factor,
+                "out_of_scope": self.out_of_scope}
+
+
+def classify(grounded: bool, confidence: float | None = None, ood_factor: float | None = None,
+             abstained: bool = False, out_of_scope: bool = False,
+             refused: bool = False) -> EpistemicVerdict:
+    """Assign exactly one epistemic status from the (UQ/OOD/grounding/scope) signals.
+
+    Precedence (most-specific-wins): out-of-scope / refused / abstained → not-computable; else if grounded but
+    OOD-flagged or low-confidence → grounded-extrapolating; else grounded-confident. An ungrounded answer
+    that is none of the above is still not-computable (we never label an ungrounded number 'confident').
+    """
+    if out_of_scope:
+        return EpistemicVerdict(NOT_COMPUTABLE, None,
+                                "out of scope, a known-unknown PEN-STACK does not model", grounded=False,
+                                ood_factor=ood_factor, out_of_scope=True)
+    if refused or not grounded:
+        return EpistemicVerdict(NOT_COMPUTABLE, None,
+                                "no validated tool can ground this value", grounded=False,
+                                ood_factor=ood_factor)
+    if abstained or (confidence is not None and confidence < ABSTAIN_CONFIDENCE):
+        reason = ("abstained, no calibrated confidence was computed" if confidence is None
+                  else f"abstained, confidence {confidence} below {ABSTAIN_CONFIDENCE}")
+        return EpistemicVerdict(NOT_COMPUTABLE, confidence, reason,
+                                grounded=True, ood_factor=ood_factor)
+    if ood_factor is not None and ood_factor >= OOD_EXTRAPOLATE_FACTOR:
+        return EpistemicVerdict(GROUNDED_EXTRAPOLATING, confidence,
+                                f"grounded but extrapolating, OOD factor {round(ood_factor, 3)} ≥ "
+                                f"{OOD_EXTRAPOLATE_FACTOR} (query far from training data)",
+                                grounded=True, ood_factor=ood_factor)
+    reason = ("grounded, in-distribution, calibrated" if confidence is not None
+              else "grounded in a validated tool output, in-distribution")
+    return EpistemicVerdict(GROUNDED_CONFIDENT, confidence, reason, grounded=True, ood_factor=ood_factor)
+
+
+def classify_step(step_status: str, confidence: float | None = None, ood_factor: float | None = None,
+                  out_of_scope: bool = False) -> dict:
+    """Map a PEN-Agent step (`ok` | `degraded` | `refused`) + UQ/OOD signals → an epistemic verdict dict.
+
+    `ok` steps are grounded; `degraded`/`refused` steps are not-computable. This is the bridge the agent
+    uses to tag every step (see agent.pen_agent)."""
+    grounded = step_status == "ok"
+    refused = step_status in ("refused", "degraded")
+    return classify(grounded=grounded, confidence=confidence, ood_factor=ood_factor,
+                    out_of_scope=out_of_scope, refused=refused).to_dict()
+
+
+def summarize(verdicts: list[dict]) -> dict:
+    """Roll up per-output verdicts into a session-level epistemic summary (counts per status)."""
+    counts = {GROUNDED_CONFIDENT: 0, GROUNDED_EXTRAPOLATING: 0, NOT_COMPUTABLE: 0}
+    for v in verdicts:
+        counts[v.get("epistemic_status", NOT_COMPUTABLE)] = counts.get(
+            v.get("epistemic_status", NOT_COMPUTABLE), 0) + 1
+    n = len(verdicts) or 1
+    return {"counts": counts, "n": len(verdicts),
+            "fraction_grounded_confident": round(counts[GROUNDED_CONFIDENT] / n, 4),
+            "all_tagged": all("epistemic_status" in v for v in verdicts)}

pen_stack/agent/guardrails.py

@@ -0,0 +1,67 @@
+"""LLM guardrails for PEN-STACK platform services.
+
+The contract every service obeys: **grounded** (answers from the curated atlas + indexed literature),
+**cited** (every factual claim carries a source), **defer-to-models** (any quantitative claim is produced
+by a validated tool call, never guessed by the LLM), **decision-support** (never a clinical directive),
+**budget-aware**, **auditable** (a provenance block accompanies every answer).
+"""
+from __future__ import annotations
+
+import re
+
+DISCLAIMER = ("Decision-support only - PEN-STACK returns calibrated risk/durability/reachability "
+              "estimates, not clinical directives. Tier-2/3 reachability is candidate and requires "
+              "experimental validation. Verify all designs experimentally.")
+
+# Questions PEN-STACK must refuse: clinical directives, diagnosis, dosing, treatment decisions for a
+# specific patient. (Scientific questions about loci/writers/safety are in scope.)
+_REFUSE_PATTERNS = [
+    r"\bshould i (treat|inject|dose|administer|give)\b",
+    r"\b(diagnos|prescrib|dosage|dosing)\w*\b",
+    r"\b(my|this|the) patient\b",
+    r"\bdose\b.{0,40}\b(child|patient|human|person|kid|baby|infant)\b", # dosing for a person = clinical
+    r"\b(what|which) dose\b", # dosing questions are clinical
+    r"\bis it safe (to|for) (a |the |my )?(patient|human|person|child)\b",
+    r"\bclinical (decision|recommendation|advice) for\b",
+]
+
+
+def out_of_scope(question: str) -> str | None:
+    """Return a refusal reason if the question is a clinical directive, else None."""
+    q = question.lower()
+    for pat in _REFUSE_PATTERNS:
+        if re.search(pat, q):
+            return ("This is a clinical-directive question. PEN-STACK is decision-support "
+                    "infrastructure for genome-writing design and does not give clinical advice.")
+    return None
+
+
+def check_question(question: str) -> dict | None:
+    """Combined gate for a free-text question. Returns a structured deferral/refusal or None.
+
+    Two distinct out-of-scope arms, both ending in zero fabrication: (1) clinical-directive REFUSAL
+    (`out_of_scope`), and (2) known-unknown DEFERRAL via the scope matcher (biology beyond any tool here).
+    Clinical refusal takes precedence (a clinical question is refused even if it also names a known-unknown).
+    """
+    clinical = out_of_scope(question)
+    if clinical:
+        return {"kind": "clinical_refusal", "epistemic_status": "not-computable", "message": clinical}
+    from pen_stack.agent.scope import match_scope
+    oos = match_scope(question)
+    if oos:
+        return {"kind": "out_of_scope", "epistemic_status": "not-computable",
+                "message": oos["deferral"], **oos}
+    return None
+
+
+def enforce_grounded(answer: dict) -> dict:
+    """Assert the auditable contract on a finished answer: numeric claims must trace to a tool call."""
+    answer.setdefault("disclaimer", DISCLAIMER)
+    answer.setdefault("provenance", [])
+    answer.setdefault("citations", [])
+    # if the answer reports numbers, there must be a tool-call provenance entry backing them
+    has_number = bool(re.search(r"\d", str(answer.get("answer", ""))))
+    if has_number and not answer["provenance"]:
+        answer["warning"] = "numeric claim without tool provenance - suppressed"
+        answer["answer"] = "(suppressed: a number was produced without a backing tool call)"
+    return answer

pen_stack/agent/mcp_server.py

@@ -0,0 +1,215 @@
+"""PEN-STACK MCP server: expose the validated capabilities to any agent.
+
+Wraps the validated tools as a Model Context Protocol server (fastmcp) so any MCP client (Claude, etc.)
+can call ``writability``, ``reachable_writers``, ``writer_axes``, ``plan_write``, ``ask_literature`` and the
+grounded ``plan_write_session`` (the full PEN-Agent state machine) and receive correct, provenance-tagged
+results - turning PEN-STACK into shared agentic infrastructure.
+
+Run: ``python -m pen_stack.agent.mcp_server`` (needs the ``services`` extra: ``pip install fastmcp``).
+"""
+from __future__ import annotations
+
+from pen_stack.agent import pen_agent, tools
+
+try:
+    from fastmcp import FastMCP
+except ImportError as e: # pragma: no cover - services extra optional
+    raise ImportError("fastmcp not installed: pip install 'pen-stack[services]'") from e
+
+mcp = FastMCP("pen-stack")
+
+# register each validated tool (the same functions the in-process agent and the eval harness use)
+mcp.tool()(tools.writability)
+mcp.tool()(tools.reachable_writers)
+mcp.tool()(tools.writer_axes)
+mcp.tool()(tools.plan_write)
+mcp.tool()(tools.ask_literature)
+mcp.tool()(tools.multiplex_translocation_risk) # multiplex translocation-risk screen
+
+
+@mcp.tool()
+def plan_write_session(gene: str, intent: str, cargo_bp: int = 2000, ct: str = "k562",
+                       payload_seq: str | None = None, mode: str = "automatic") -> dict:
+    """PEN-Agent: grounded write-planning state machine (site -> writer -> cargo+polish -> off-target -> 3D).
+
+    Every number is copied from a tool result with provenance; ungrounded steps degrade/refuse, never
+    fabricate. Modes: automatic | guided | qa."""
+    return pen_agent.plan_write_session(gene, intent, cargo_bp=cargo_bp, ct=ct,
+                                        payload_seq=payload_seq, mode=mode)
+
+
+@mcp.tool()
+def verify_write(design: dict) -> dict:
+    """Verifier: submit a proposed genomic write as a dict (write_type, writer_family, site_seq,
+    cargo_bp, delivery_vehicle, cell_type, edit_intent, no_integration, target_guide/donor_guide, edits, ...)
+    and get back a Verdict: legal/illegal + the named violated rule(s) + citation, a calibrated confidence on
+    the soft components, an epistemic status, and any out-of-scope flags. Legality and confidence are distinct
+    axes; every number traces to a tool (no fabrication). Unsupported write types defer."""
+    from pen_stack.verify import verify
+    return verify(design).model_dump()
+
+
+@mcp.tool()
+def verify_proof(design: dict) -> dict:
+    """Verifier: the repair-oriented proof object for a proposed write. Returns the three
+    axes (legality, confidence, biosecurity) reported separately, each with a status, the rule or signature
+    that fired, evidence, and a repair hint; the collapsed verdict is None. An agent fixes a failed-on-legality
+    design from the legality axis's repair hint and re-verifies. Biosecurity hazards are acknowledged and
+    routed to human review, never given an actionable repair."""
+    from pen_stack.verify.proof import verify_proof as _vp
+    return _vp(design).model_dump()
+
+
+@mcp.tool()
+def validation_campaign() -> dict:
+    """The validation-campaign engine. Returns the expression-validation campaign: the
+    next batch of (cassette x locus x cell type) measurements ordered by expected information gain, the
+    calibrate_axis gate it targets (the path to the program's first outcome-validated axis), and the
+    active-vs-random result reported verbatim. Cloud-lab-executable; Level 3, human in control; the experiments
+    are candidates and the wet run is the standing bottleneck."""
+    from pen_stack.active.campaign import design_campaign
+    return design_campaign()
+
+
+@mcp.tool()
+def cloudlab_submit(design: dict, experiment: dict | None = None, provider: str = "mock") -> dict:
+    """Safety-gated cloud-lab submission. The biosecurity gate runs BEFORE submission; a flagged
+    design returns a structured refusal (blocked=True) and NO protocol is emitted. A cleared design returns a
+    mock / dry-run job receipt (a real run needs a cloud-lab partner + budget). Level 3, human in control."""
+    from pen_stack.build.cloudlab import submit_gated
+    return submit_gated(design, experiment or {}, provider=provider, actor="mcp")
+
+
+@mcp.tool()
+def writespec_parse(prose: str, check_feasibility: bool = True) -> dict:
+    """Parse a plain-language genome-writing request into a typed, ontology-backed WriteSpec (an
+    SBOL3 profile). Returns the typed spec with per-field provenance (explicit / inferred / user / unresolved),
+    the assumptions behind every inferred field, clarifying questions for anything underspecified or ambiguous,
+    the unresolved terms (kept null, never invented), the downstream design adapter, and a feasibility verdict
+    (reachability + deliverability + legality, with named blocking constraints + repair hints). A WriteSpec is a
+    REQUEST, not a claim; the extractor never fabricates intent."""
+    from pen_stack.spec.service import parse_request
+    return parse_request(prose, check_feasibility=check_feasibility)
+
+
+@mcp.tool()
+def oracle_query(oracle: str | None = None, protein_seq: str | None = None, ligand_smiles: str | None = None,
+                 pair_type: str = "ligand", ligand_name: str | None = None) -> dict:
+    """Query the oracle mesh under one contract. With no arguments, returns every oracle's
+    execution + latency + live status + PUBLISHED reliability (reported verbatim from public benchmarks, with
+    citation; not a claim about this stack's accuracy) and the disagreement-to-interval check. With `oracle` set,
+    returns that oracle's status + reliability. With `protein_seq` + `ligand_smiles`, returns a CANDIDATE
+    binding-affinity prediction (Boltz-2 head): a binder probability + a predicted value with native uncertainty,
+    cache-or-abstain; protein-protein/protein-DNA pair types are flagged extrapolating (the head is
+    protein-ligand only). The long GPU job never runs on the request path."""
+    from pen_stack.oracles.status import oracle_status, summary
+    if protein_seq and ligand_smiles:
+        from pen_stack.oracles.affinity import predict_affinity
+        return predict_affinity(protein_seq, ligand_smiles, pair_type=pair_type, ligand_name=ligand_name).model_dump()
+    st = oracle_status()
+    if oracle:
+        return {"oracle": oracle, "status": st.get(oracle), "found": oracle in st}
+    return {"summary": summary(), "oracles": st}
+
+
+@mcp.tool()
+def graph_query(locus: str, cargo_form: str | None = None) -> dict:
+    """World-model graph: a multi-hop query. Returns the writer families that REACH `locus` AND
+    are DELIVERABLE by a vehicle carrying `cargo_form` (optional), each answer with its provenanced edge path
+    (the answer IS the path, no fabrication). The graph nodes/edges carry evidence kind + scope + provenance."""
+    from pen_stack.graph import writers_reaching_and_deliverable
+    return writers_reaching_and_deliverable(locus, cargo_form=cargo_form)
+
+
+# ---- the AI Integration Surface: self-describing resources + the engine tools ----
+@mcp.resource("pen-stack://capabilities")
+def capabilities_resource() -> dict:
+    """WHAT PEN-STACK can do (machine-readable). An agent reads this and routes on it, not on prose."""
+    from pen_stack.api.manifest import capability_manifest
+    return capability_manifest()
+
+
+@mcp.resource("pen-stack://scope")
+def scope_resource() -> dict:
+    """WHAT PEN-STACK REFUSES to answer: the known-unknowns + the oracle scope cards. The contract that makes
+    depending on PEN-STACK safe, outputs outside scope are out_of_scope/extrapolating, never asserted."""
+    from pen_stack.api.manifest import scope_manifest
+    return scope_manifest()
+
+
+@mcp.tool()
+def safety_screen(design: dict) -> dict:
+    """Guardian: biosecurity / dual-use screen -> SafetyVerdict (clear/flag/escalate/refuse) + reason. A
+    hazardous design returns a STRUCTURED refusal an agent can branch on (decision == 'refuse')."""
+    from pen_stack.safety import safety_gate
+    return safety_gate(design, actor=str(design.get("actor", "mcp"))).model_dump()
+
+
+@mcp.tool()
+def immune_profile(design: dict) -> dict:
+    """Immune-risk profile: a per-axis screen (genotox/CD8/innate/NAb/anti-PEG), each with its own
+    uncertainty + validation label. Never collapsed into one number (collapsed_score is None); magnitude is a
+    declared known-unknown."""
+    from pen_stack.planner.immune_profile import immune_profile as _ip
+    return _ip(design)
+
+
+@mcp.tool()
+def offtarget_scan(writer_family: str, guide: str | None = None, candidate_sites: list | None = None,
+                   sequence: str | None = None, assay: str = "guideseq", enzyme: str | None = None,
+                   max_mismatch: int = 5) -> dict:
+    """Genome-wide, per-mechanism off-target FINDER (NOT a clearance). For a nuclease guide it
+    enumerates the genome-wide off-target set over GRCh38 (Cas-OFFinder, cached) + real CRISOT + risk + chromatin
+    (validated); serine integrase = genome-wide pseudo-attP scan (semi-validated); bridge = DMS-scored scan
+    (mechanism-based, unvalidated); CAST = guide-directed + untargeted-transposition background (unvalidated);
+    PASTE = nuclease + integrase composition. Each carries a truthful status label + the confirming assay.
+    Abstains for a novel input (VM scan); never fabricates sites."""
+    from pen_stack.wgenome.offtarget_predict import nominate_offtargets
+    return nominate_offtargets(writer_family, guide=guide, candidate_sites=candidate_sites,
+                               sequence=sequence, assay=assay, enzyme=enzyme, max_mismatch=max_mismatch)
+
+
+@mcp.tool()
+def delivery_recommend(cargo_form: str, cargo_bp: int | None = None, target_tissue: str | None = None,
+                       safety_weight: float = 0.5, in_vivo: bool | None = None) -> dict:
+    """Cross-modality delivery recommender: rank vehicles by cargo-form + safety<->efficacy + a
+    GROUNDED serotype->tissue tropism prior (from approved AAV therapies; a known-unknown for novel capsids), plus
+    the learned FLIP-AAV capsid-fitness capability. Never fabricates tropism; abstains without inputs."""
+    from pen_stack.planner.delivery_predict import recommend_delivery_plus
+    return recommend_delivery_plus(cargo_form, cargo_bp, target_tissue, safety_weight=safety_weight, in_vivo=in_vivo)
+
+
+@mcp.tool()
+def generate_designs(goal: dict | None = None, candidates: list | None = None, keep: int = 25) -> dict:
+    """Generative designer (verifier-as-discriminator): hazardous/illegal candidates are DISCARDED;
+    survivors are calibrated + immune-profiled CANDIDATES (never asserted to work)."""
+    from pen_stack.design import generate_designs as _gd
+    return {"survivors": _gd(goal, candidates=candidates, keep=keep, actor="mcp")}
+
+
+@mcp.tool()
+def predict_outcome(design: dict, cell_state: str = "k562") -> dict:
+    """Digital twin: a calibrated, OOD-gated, phenotype-bounded outcome (interval + scope flags). A
+    candidate prediction, never the truth; phenotype/in-vivo magnitude stay out of scope."""
+    from pen_stack.twin import predict_outcome as _po
+    return _po(design, cell_state)
+
+
+@mcp.tool()
+def suggest_experiment(candidates: list, cell_state: str = "k562", k: int = 8) -> dict:
+    """Experiment designer: a diverse, informative next-experiment batch (EIG + immune-VOI), each with
+    its expected information gain."""
+    from pen_stack.active import select_batch
+    return {"batch": select_batch(candidates, cell_state, {}, k=k)}
+
+
+@mcp.tool()
+def co_scientist_session(goal: dict, cell_state: str = "k562") -> dict:
+    """Co-scientist: drive the full loop -> Pareto strategies + calibrated outcomes + per-axis immune
+    profiles + suggested experiments + citations + scope ledger + safety. The scientist decides; this drives."""
+    from pen_stack.agent.co_scientist import co_scientist_session as _cs
+    return _cs(goal, cell_state)
+
+
+if __name__ == "__main__": # pragma: no cover
+    mcp.run()