pen-stack 0.1.0__py3-none-any.whl

pen_stack/agent/orchestrator.py

@@ -0,0 +1,112 @@
+"""The PEN-STACK agent: tool-use orchestration.
+
+Given a natural-language goal ("durably express factor IX in hepatocytes"), the agent plans the whole
+write by calling validated tools (writability -> reachable writers -> writer axes -> plan_write -> cited
+literature) in a tool-calling loop driven by the configured LLM (hybrid: NVIDIA Nemotron with Ollama
+fallback, via ``pen_stack.rag.llm.chat``). Guardrails: it obtains numbers ONLY from tool calls (no
+free-text predictions), refuses clinical-directive prompts, and logs an auditable trace.
+
+Graceful: if no LLM provider is reachable, ``run_agent`` returns a refusal-free deterministic fallback
+that calls plan_write directly - so the platform degrades to the validated pipeline rather than failing.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pen_stack.agent.guardrails import DISCLAIMER, out_of_scope
+from pen_stack.agent.tools import SCHEMAS, dispatch
+from pen_stack.rag.llm import chat as llm_chat
+
+_TRACES = Path(__file__).resolve().parents[2] / "out" / "agent_traces"
+
+_SYSTEM = (
+    "You are the PEN-STACK genome-writing planning agent. You MUST obtain every fact and number by "
+    "calling the provided tools - never invent a number, gene, score, or citation. Plan a write by "
+    "calling: writability, reachable_writers, writer_axes, plan_write, ask_literature. When you have "
+    "enough tool results, write a short plan that cites which tool produced each number. Decision-support "
+    "only - never give clinical directives.")
+
+
+def _tool_response(style: str, call_id: str | None, content: str) -> dict:
+    """Format a tool-result message for the provider's API style."""
+    if style == "anthropic": # Anthropic returns tool results as a user-turn tool_result content block
+        block = {"type": "tool_result", "content": content}
+        if call_id is not None:
+            block["tool_use_id"] = call_id
+        return {"role": "user", "content": [block]}
+    m = {"role": "tool", "content": content}
+    if style == "openai" and call_id is not None:
+        m["tool_call_id"] = call_id
+    return m
+
+
+def run_agent(goal: str, max_steps: int = 12, cfg: dict | None = None) -> dict:
+    """Turn a goal into a cited, auditable plan. Numbers come only from tool calls."""
+    refusal = out_of_scope(goal)
+    if refusal:
+        return {"refused": True, "plan": refusal, "trace": [], "disclaimer": DISCLAIMER}
+
+    from pen_stack.rag.llm import load_llm_config
+    step_timeout = int((cfg or load_llm_config()).get("agent_call_timeout", 60))
+    msgs = [{"role": "system", "content": _SYSTEM}, {"role": "user", "content": goal}]
+    trace: list[dict] = []
+    seen: set = set()
+
+    for _ in range(max_steps):
+        resp = llm_chat(msgs, tools=SCHEMAS, cfg=cfg, timeout=step_timeout)
+        if resp is None:
+            return _fallback(goal, trace)
+        provider, style = resp.get("provider"), resp.get("style", "openai")
+        calls = resp.get("tool_calls") or []
+        if not calls:
+            return {"refused": False, "plan": resp.get("content", "").strip(),
+                    "trace": trace, "disclaimer": DISCLAIMER, "llm": True, "provider": provider}
+        msgs.append(resp["raw"]) # append the assistant turn verbatim
+        raw_calls = resp["raw"].get("tool_calls") or []
+        for i, c in enumerate(calls):
+            name = c["function"]["name"]
+            args = c["function"]["arguments"]
+            # anthropic carries the id on the normalised call; openai carries it on the raw tool_call
+            call_id = c.get("id") or (raw_calls[i].get("id") if i < len(raw_calls) else None)
+            key = f"{name}:{json.dumps(args, sort_keys=True, default=str)}"
+            if key in seen:
+                msgs.append(_tool_response(style, call_id, json.dumps(
+                    {"note": "already called with these args; use prior result and finalise the plan"})))
+                continue
+            seen.add(key)
+            try:
+                result = dispatch(name, args) # VALIDATED tool only
+            except Exception as e: # noqa: BLE001
+                result = {"error": str(e)}
+            trace.append({"tool": name, "args": args, "result": result})
+            msgs.append(_tool_response(style, call_id, json.dumps(result, default=str)))
+    return {"refused": False, "plan": "(max steps reached)", "trace": trace,
+            "disclaimer": DISCLAIMER, "llm": True}
+
+
+def _fallback(goal: str, trace: list[dict]) -> dict:
+    """Deterministic fallback when no LLM is reachable: call plan_write on a best-effort parse."""
+    from pen_stack.planner.optimize import EditIntent
+    gene = next((w for w in goal.replace(",", " ").split() if w.isupper() and len(w) >= 2), None)
+    intent = EditIntent.SAFE_HARBOUR.value
+    for kw, it in [("disrupt", "knock_in_with_disruption"), ("knock", "knock_in_with_disruption"),
+                   ("durab", "high_durability_insertion"), ("enhancer", "regulatory_excision"),
+                   ("repeat", "repeat_excision")]:
+        if kw in goal.lower():
+            intent = it
+            break
+    if not gene:
+        return {"refused": False, "plan": "No target gene detected; LLM unavailable.",
+                "trace": trace, "disclaimer": DISCLAIMER, "llm": False}
+    res = dispatch("plan_write", {"gene": gene, "intent": intent})
+    trace.append({"tool": "plan_write", "args": {"gene": gene, "intent": intent}, "result": res})
+    return {"refused": False, "plan": f"[deterministic fallback] plan for {gene} ({intent})",
+            "trace": trace, "disclaimer": DISCLAIMER, "llm": False}
+
+
+def save_trace(result: dict, name: str) -> Path:
+    _TRACES.mkdir(parents=True, exist_ok=True)
+    p = _TRACES / f"{name}.json"
+    p.write_text(json.dumps(result, indent=2, default=str), encoding="utf-8")
+    return p

pen_stack/agent/orchestrator_live.py

@@ -0,0 +1,56 @@
+"""Live foundation-model orchestration.
+
+A reasoning loop that GENERATES grounded candidates, calls oracles (cache-first / replayable) for a critique
+signal, and disposes via `verify()` (safety + legality + immune). The agent picks WHICH oracle to call; the
+NUMBER always comes from the oracle/tool, never invented. Live calls are cache-keyed and version-pinned, so a
+seed-locked replay reproduces a run from the committed cache (replay is the CI default).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def _oracle_critique(design: dict, *, seed: int = 0) -> dict:
+    """A grounded critique number for the top candidate, sourced from an oracle adapter (cache-first). When the
+    candidate carries a writer sequence, use the structure-consistency oracle; otherwise abstain (no fabricated
+    value). The returned value/uncertainty come from the OracleResult, never the agent."""
+    seq = design.get("writer_candidate_seq") or design.get("writer_seq")
+    if not seq:
+        return {"oracle": None, "value": None, "available": False, "note": "no sequence supplied; abstaining"}
+    from pen_stack.oracles.structure import consistency
+    r = consistency(seq)
+    return {"oracle": "structure.consistency", "value": (r.value or {}),
+            "available": bool(r.available), "cached": bool(getattr(r, "cached", False)),
+            "source": getattr(r, "source", None), "output_kind": r.output_kind}
+
+
+def orchestrate(goal: dict, *, candidates: list[dict] | None = None, max_rounds: int = 4,
+                seed: int = 0) -> dict[str, Any]:
+    """Plan -> generate grounded candidates -> call an oracle (cache-first) -> critique via verify() -> refine.
+    Returns the chosen design + a trace in which every number is tool-sourced. Deterministic given the inputs +
+    seed (replayable from cache). No stage fabricates a value."""
+    from pen_stack.design.generate import generate_designs
+    from pen_stack.verify import verify
+
+    state: dict[str, Any] = {"goal": goal, "design": None, "candidates": []}
+    trace: list[dict] = []
+    for r in range(max_rounds):
+        cands = generate_designs(goal, candidates=candidates, keep=5, actor="orchestrator")
+        if not cands:
+            trace.append({"round": r, "action": "generate", "n": 0,
+                          "note": "no surviving candidates (atlas absent or all discarded by the discriminator)"})
+            break
+        top = cands[0]
+        oracle = _oracle_critique(top, seed=seed)
+        v = verify(dict(top), actor="orchestrator")
+        trace.append({"round": r, "action": "generate+oracle+verify", "n": len(cands),
+                      "oracle": oracle, "verdict": v.summary(), "legal": v.legal,
+                      "safety": (v.safety.decision if v.safety is not None else None),
+                      "confidence": v.confidence})
+        state["design"], state["candidates"] = top, cands
+        if v.legal is True and v.safety is not None and v.safety.decision in ("clear", "flag"):
+            break
+        # refine: on a non-passing round, narrow the pool to the survivors for the next iteration
+        candidates = cands
+    return {"goal": goal, "design": state["design"], "trace": trace,
+            "no_fabrication": True, "replayable": True}

pen_stack/agent/pen_agent.py

@@ -0,0 +1,242 @@
+"""PEN-Agent - grounded write-planning state machine.
+
+A deterministic task-state machine over the VALIDATED tools. It sequences a genome-write plan:
+
+    goal intake -> site selection (writability) -> writer selection (reachability) ->
+    cargo design (+ Cargo Polish) -> off-target -> 3D structural risk -> report
+
+Core property (the contribution): NO FABRICATION. Every number in the output is copied verbatim from a
+tool-result dict and tagged with that tool's provenance; a step whose tool cannot ground a value is marked
+`degraded`/`refused`, never invented. The agent therefore runs end-to-end even when AlphaGenome or the
+bridge engine is unavailable - those steps degrade with a reason instead of guessing.
+
+The LLM (agent/orchestrator.py) is an optional conversational front-end over this same machine; the plan
+itself is deterministic, so the result is reproducible and the no-fabrication guarantee holds with or
+without an LLM. Modes: "automatic" (run all steps), "guided" (stop after each step), "qa" (single tool).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pen_stack.agent import tools as T
+
+
+@dataclass
+class Step:
+    name: str
+    tool: str | None
+    status: str # ok | degraded | refused
+    provenance: str | None = None
+    result: dict = field(default_factory=dict)
+    reason: str | None = None
+
+
+def _site_selection(gene: str, ct: str) -> Step:
+    try:
+        r = T.writability(gene, ct)
+    except Exception as e: # noqa: BLE001 - missing atlas -> refuse, never fabricate
+        return Step("site_selection", "wgenome.writability", "refused", reason=f"{type(e).__name__}: {e}")
+    if not r.get("found"):
+        return Step("site_selection", r.get("tool"), "refused", reason=f"no writable locus for {gene}")
+    return Step("site_selection", r["tool"], "ok", provenance=r["tool"],
+                result={"max_writability": r["max_writability"], "safety": r["safety"],
+                        "p_durable": r["p_durable"], "n_bins": r["n_bins"]})
+
+
+def _writer_selection(gene: str, intent: str, cargo_bp: int, ct: str) -> tuple[Step, dict]:
+    try:
+        plan = T.plan_write(gene, intent, cargo_bp, ct)
+    except Exception as e: # noqa: BLE001 - missing atlas -> refuse, never fabricate
+        return Step("writer_selection", "planner.pipeline", "refused",
+                    reason=f"{type(e).__name__}: {e}"), {}
+    if not plan or plan.get("found") is False:
+        return Step("writer_selection", "planner.pipeline", "refused",
+                    reason="planner returned no plan"), {}
+    fam = plan.get("writer") or plan.get("writer_family") or plan.get("family")
+    return (Step("writer_selection", "planner.pipeline", "ok", provenance="planner.pipeline",
+                 result={"writer_family": fam, "score": plan.get("score"),
+                         "site": {k: plan.get(k) for k in ("chrom", "bin") if k in plan}}),
+            plan)
+
+
+def _cargo_design(plan: dict, cargo_bp: int, ct: str, payload_seq: str | None) -> Step:
+    from pen_stack.planner.cargo import design_cargo
+    fam = plan.get("writer") or plan.get("writer_family") or plan.get("family")
+    wr = {"family": fam, "cargo_capacity_bp": plan.get("cargo_capacity_bp"),
+          "deliv_class": plan.get("deliv_class")}
+    site = (plan.get("chrom"), plan.get("bin"))
+    cargo = design_cargo(cargo_bp, wr, site, ct, payload_seq=payload_seq)
+    res = {"assembled_bp": cargo["assembled_bp"], "size_ok": cargo["size_ok"]}
+    if "cargo_polish" in cargo:
+        res["cargo_durability_risk"] = cargo["cargo_polish"]["cargo_durability_risk"]
+        res["cargo_band"] = cargo["cargo_polish"]["band"]
+        res["cargo_suggestions"] = [f["suggestion"] for f in cargo["cargo_polish"]["flags"]]
+    return Step("cargo_design", "planner.cargo", "ok", provenance="planner.cargo+cargo_polish", result=res)
+
+
+def _offtarget(plan: dict) -> Step:
+    fam = plan.get("writer") or plan.get("writer_family") or plan.get("family") or ""
+    if "bridge" not in str(fam).lower() and "seek" not in str(fam).lower():
+        return Step("offtarget", None, "degraded", reason=f"off-target engine applies to bridge/seek writers, not {fam}")
+    try:
+        from pen_stack.bridge.offtarget import predict_offtargets
+        r = predict_offtargets(fam, (plan.get("chrom"), plan.get("bin")))
+    except Exception as e: # noqa: BLE001
+        return Step("offtarget", "bridge.offtarget", "degraded", reason=f"{type(e).__name__}: {e}")
+    if isinstance(r, dict) and r.get("status", "").startswith("pending"):
+        return Step("offtarget", "bridge.offtarget", "degraded", reason=r.get("note"))
+    return Step("offtarget", "bridge.offtarget", "ok", provenance="bridge.offtarget",
+                result=r if isinstance(r, dict) else {"offtargets": r})
+
+
+def _structural_risk(plan: dict) -> Step:
+    chrom, b = plan.get("chrom"), plan.get("bin")
+    if chrom is None or b is None:
+        return Step("structural_risk", None, "degraded", reason="no concrete site coordinates")
+    try:
+        from pen_stack.wgenome.structure3d import structural_risk
+        r = structural_risk(chrom, int(b) * 1000, int(b) * 1000 + 135_000, offline=True)
+    except Exception as e: # noqa: BLE001
+        return Step("structural_risk", "wgenome.structure3d", "degraded", reason=f"{type(e).__name__}: {e}")
+    if not r.get("available"):
+        return Step("structural_risk", "wgenome.structure3d", "degraded",
+                    reason="AlphaGenome contact map not cached (offline); flag with confidence")
+    return Step("structural_risk", "wgenome.structure3d", "ok", provenance="wgenome.structure3d", result=r)
+
+
+def _plan_confidence(s_site: Step, ood_factor: float = 1.0) -> dict:
+    """Plan-level confidence from the grounded site step's safety + durability, widened by OOD.
+
+    Reuses the uncertainty-quantification Monte-Carlo propagation; abstention is confidence below the threshold. Returns a
+    neutral 'no grounded site' verdict when the site step refused (then the session is not-computable anyway).
+    """
+    from pen_stack.agent.epistemic import ABSTAIN_CONFIDENCE
+    from pen_stack.validate.selective_prediction import propagate_plan_confidence
+    if s_site.status != "ok":
+        return {"confidence": None, "abstained": False, "ood_factor": ood_factor}
+    safety = float(s_site.result.get("safety", 0.5))
+    p_dur = float(s_site.result.get("p_durable", 0.5))
+    hw = 0.10 * ood_factor
+    axes = {"safety": {"point": safety, "lo": max(0.0, safety - hw), "hi": min(1.0, safety + hw)},
+            "durability": {"point": p_dur, "lo": max(0.0, p_dur - 1.5 * hw), "hi": min(1.0, p_dur + 1.5 * hw)}}
+    prop = propagate_plan_confidence(axes, {"safety": 0.5, "durability": 0.5}, threshold=0.5)
+    return {"confidence": round(prop["confidence"], 4), "interval": [prop["lo"], prop["hi"]],
+            "abstained": bool(prop["confidence"] < ABSTAIN_CONFIDENCE), "ood_factor": ood_factor}
+
+
+def plan_write_session(gene: str, intent: str, cargo_bp: int = 2000, ct: str = "k562",
+                       payload_seq: str | None = None, mode: str = "automatic",
+                       question: str | None = None, ood_factor: float = 1.0) -> dict:
+    """Run the grounded write-planning state machine. Returns steps with provenance, a no-fabrication audit,
+    and a per-step + session-level epistemic status with abstention.
+
+    If ``question`` is supplied and matches a known-unknown (configs/known_unknowns.yaml), the session defers
+    immediately (status not-computable, zero fabrication) instead of planning, the out-of-scope arm of trust.
+    """
+    from pen_stack.agent.epistemic import classify_step, summarize
+    from pen_stack.agent.guardrails import DISCLAIMER
+
+    # out-of-scope deferral (a known-unknown is never planned, never guessed)
+    if question is not None:
+        from pen_stack.agent.scope import match_scope
+        oos = match_scope(question)
+        if oos:
+            verdict = classify_step("refused", out_of_scope=True)
+            return {"goal": {"gene": gene, "intent": intent, "cargo_bp": cargo_bp, "ct": ct, "mode": mode},
+                    "steps": [], "provenance": {}, "degraded_modes": [], "refusals": [],
+                    "no_fabrication": True, "completed": False, "out_of_scope": oos,
+                    "epistemic_summary": summarize([verdict]), "abstained": True,
+                    "disclaimer": DISCLAIMER}
+
+    steps: list[Step] = []
+    s_site = _site_selection(gene, ct)
+    steps.append(s_site)
+    plan: dict = {}
+    if s_site.status == "ok":
+        s_writer, plan = _writer_selection(gene, intent, cargo_bp, ct)
+        steps.append(s_writer)
+        if s_writer.status == "ok":
+            steps.append(_cargo_design(plan, cargo_bp, ct, payload_seq))
+            steps.append(_offtarget(plan))
+            steps.append(_structural_risk(plan))
+        if mode == "guided":
+            steps = steps[:2] # guided mode pauses after writer selection
+
+    grounded = [s for s in steps if s.status == "ok"]
+    degraded = [{"step": s.name, "reason": s.reason} for s in steps if s.status == "degraded"]
+    refused = [{"step": s.name, "reason": s.reason} for s in steps if s.status == "refused"]
+    # no-fabrication audit: every 'ok' step carries provenance for its numbers; nothing is free-text generated
+    no_fabrication = all(s.provenance for s in grounded)
+
+    # The agent submits its own plan to the rule-grounded verifier before returning it.
+    # An illegal plan is surfaced with the named rule reason (the agent revises/refuses; it never fabricates).
+    verification = None
+    if plan.get("writer") or plan.get("writer_family") or plan.get("family"):
+        try:
+            from pen_stack.verify import verify
+            fam = plan.get("writer") or plan.get("writer_family") or plan.get("family")
+            v = verify({"write_type": "insertion", "writer_family": fam, "cargo_bp": cargo_bp,
+                        "cell_type": ct, "edit_intent": intent,
+                        "delivery_vehicle": plan.get("delivery") or plan.get("delivery_vehicle")})
+            verification = {"legal": v.legal, "violations": v.violations,
+                            "epistemic_status": v.epistemic_status, "no_fabrication": v.no_fabrication}
+        except Exception as e: # noqa: BLE001 - verifier unavailable -> no verdict, never fabricate
+            verification = {"legal": None, "reason": f"verifier unavailable: {type(e).__name__}"}
+
+    # tag every step with an epistemic verdict driven by grounding + OOD; plan-level abstention
+    pc = _plan_confidence(s_site, ood_factor=ood_factor)
+    step_dicts = []
+    for s in steps:
+        d = vars(s)
+        conf = pc["confidence"] if s.name == "site_selection" else None
+        d["epistemic"] = classify_step(s.status, confidence=conf, ood_factor=ood_factor)
+        step_dicts.append(d)
+    return {
+        "goal": {"gene": gene, "intent": intent, "cargo_bp": cargo_bp, "ct": ct, "mode": mode},
+        "steps": step_dicts,
+        "provenance": {s.name: s.provenance for s in grounded},
+        "degraded_modes": degraded,
+        "refusals": refused,
+        "no_fabrication": no_fabrication,
+        "completed": bool(grounded) and not refused,
+        "plan_confidence": pc["confidence"],
+        "abstained": pc["abstained"],
+        "epistemic_summary": summarize([d["epistemic"] for d in step_dicts]),
+        "verification": verification,
+        "disclaimer": DISCLAIMER,
+    }
+
+
+_AUDIT_GOALS = [("TRAC", "knock_in_with_disruption"),
+                ("HBB", "high_durability_insertion"),
+                ("AAVS1", "safe_harbour_insertion"),
+                ("CCR5", "safe_harbour_insertion"),
+                ("HBG1", "regulatory_excision"),
+                ("PDCD1", "knock_in_with_disruption"),
+                ("FXN", "repeat_excision"),
+                ("CLYBL", "high_durability_insertion")]
+
+
+def no_fabrication_audit(goals: list[tuple[str, str]] | None = None) -> dict:
+    """Deterministic no-fabrication HARD GATE for the bench (T6) - NO LLM, so it never hangs and is always
+    available. The state machine copies every number from a tool-result dict, so fabrication is impossible by
+    construction; the audit confirms that every grounded ('ok') step carries provenance and that no step
+    emits an ungrounded value. Without the atlas the steps refuse (still no fabrication = pass)."""
+    goals = goals or _AUDIT_GOALS
+    runs = [plan_write_session(g, i) for g, i in goals]
+    per_goal = []
+    for (g, i), r in zip(goals, runs):
+        ok_steps = [s for s in r["steps"] if s["status"] == "ok"]
+        clean = r["no_fabrication"] and all(s["provenance"] for s in ok_steps)
+        per_goal.append({"gene": g, "intent": i, "no_fabrication": bool(clean),
+                         "grounded_steps": len(ok_steps), "completed": r["completed"]})
+    n_fab = sum(0 if p["no_fabrication"] else 1 for p in per_goal)
+    return {"available": True, "n_goals": len(goals), "n_fabricated": n_fab,
+            "all_no_fabrication_pass": n_fab == 0,
+            "n_grounded": sum(p["completed"] for p in per_goal), "per_goal": per_goal,
+            "method": "deterministic pen_agent state machine (no LLM); fabrication impossible by construction"}
+
+
+if __name__ == "__main__": # pragma: no cover
+    import json
+    print(json.dumps(no_fabrication_audit(), indent=2, default=str))

pen_stack/agent/scope.py

@@ -0,0 +1,60 @@
+"""Scope matcher over the known-unknowns registry.
+
+Matches an incoming question against `configs/known_unknowns.yaml` and, on a hit, returns a structured
+deferral ("this requires X, which PEN-STACK does not model") instead of letting the agent guess. This is the
+*out-of-scope* arm of trustworthiness, distinct from the clinical-directive refusal in `agent/guardrails.py`
+(which this complements): guardrails refuse *clinical advice*; the scope matcher defers *biology beyond any
+tool here* (the unknown funnel: structure→phenotype, in-vivo immunogenicity, long-term durability, epistasis,
+polygenic, germline).
+
+Deterministic substring + regex matching (no LLM) so the deferral is reproducible and testable. The result
+feeds `agent.epistemic.classify(out_of_scope=True)` → status `not-computable` with zero fabrication.
+"""
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from pathlib import Path
+
+import yaml
+
+from pen_stack._resources import resource
+
+_CFG = "configs/known_unknowns.yaml"
+
+
+@lru_cache(maxsize=1)
+def load_registry(path: str | Path | None = None) -> list[dict]:
+    p = Path(path) if path else resource(_CFG)
+    data = yaml.safe_load(Path(p).read_text(encoding="utf-8"))
+    return data.get("known_unknowns", [])
+
+
+def match_scope(question: str, registry: list[dict] | None = None) -> dict | None:
+    """Return a structured deferral if the question hits a known-unknown, else None (in scope).
+
+    A hit = any `match_terms` substring (lowercased) OR any `patterns` regex matches. Returns the matched
+    entry's id/title/requires/why + a ready-to-surface deferral message.
+    """
+    reg = registry if registry is not None else load_registry()
+    q = question.lower()
+    for entry in reg:
+        hit_term = next((t for t in entry.get("match_terms", []) if t in q), None)
+        hit_pat = None
+        if not hit_term:
+            for pat in entry.get("patterns", []):
+                if re.search(pat, q, re.IGNORECASE):
+                    hit_pat = pat
+                    break
+        if hit_term or hit_pat:
+            return {"out_of_scope": True, "id": entry["id"], "title": entry["title"],
+                    "requires": entry["requires"], "why": entry["why"],
+                    "matched_on": hit_term or f"pattern:{hit_pat}",
+                    "deferral": (f"This question is out of scope for PEN-STACK: it concerns "
+                                 f"{entry['title']}, which requires {entry['requires']}. "
+                                 f"{entry['why']}. PEN-STACK does not model this and will not guess a value.")}
+    return None
+
+
+def is_out_of_scope(question: str) -> bool:
+    return match_scope(question) is not None

pen_stack/agent/tools.py

@@ -0,0 +1,130 @@
+"""PEN-STACK agent tools: the validated capabilities the agent may call.
+
+Each tool wraps a *validated* module function and returns a JSON-serialisable, provenance-tagged result.
+The agent may obtain numbers ONLY by calling these - never by free-text generation (the no-fabrication
+guarantee, enforced by the eval harness). Schemas are the Ollama/OpenAI tool-calling format.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def writability(gene: str, ct: str = "k562") -> dict:
+    """Most-writable locus near a gene (safety x durability)."""
+    from pen_stack.atlas.crosslink import loci_for_gene
+    g = loci_for_gene(gene, ct)
+    if g.empty:
+        return {"gene": gene, "ct": ct, "found": False, "tool": "wgenome.writability"}
+    top = g.sort_values("writability", ascending=False).iloc[0]
+    return {"gene": gene, "ct": ct, "found": True,
+            "max_writability": round(float(top["writability"]), 4),
+            "safety": round(float(top["safety"]), 4),
+            "p_durable": round(float(top["p_durable"]), 4),
+            "n_bins": int(len(g)), "tool": "wgenome.writability"}
+
+
+def reachable_writers(gene: str, ct: str = "k562") -> dict:
+    """Writer families that can reach a gene's most-writable locus."""
+    from pen_stack.atlas.crosslink import loci_for_gene, writers_for_locus
+    g = loci_for_gene(gene, ct)
+    if g.empty:
+        return {"gene": gene, "found": False, "tool": "atlas.crosslink"}
+    top = g.sort_values("writability", ascending=False).iloc[0]
+    w = writers_for_locus(top["chrom"], int(top["bin"]), ct)
+    return {"gene": gene, "ct": ct, "found": True,
+            "families": sorted(set(w["family"])) if not w.empty else [],
+            "tool": "atlas.crosslink"}
+
+
+def writer_axes(family: str) -> dict:
+    """Measured axes for a writer family (cargo, deliverability, reachability, readiness)."""
+    import pandas as pd
+
+    from pen_stack.rag.index import _ATLAS
+    atlas = pd.read_parquet(_ATLAS)
+    sub = atlas[atlas["family"] == family]
+    if sub.empty:
+        return {"family": family, "found": False, "tool": "atlas.score"}
+    core = sub[sub["entry_kind"] == "curated_core"]
+    r = core.iloc[0] if len(core) else sub.iloc[0]
+    return {"family": family, "found": True, "n_systems": int(len(sub)),
+            "reachability_tier": r.get("reachability_tier"),
+            "cargo_capacity_bp": (int(r["cargo_capacity_bp"]) if pd.notna(r.get("cargo_capacity_bp")) else None),
+            "deliv_class": r.get("deliv_class"), "tool": "atlas.score"}
+
+
+def plan_write(gene: str, intent: str, cargo_bp: int = 2000, ct: str = "k562") -> dict:
+    """Full Write Planner: goal + edit_intent -> top ranked, traceable plan."""
+    from pen_stack.planner.optimize import EditIntent
+    from pen_stack.planner.pipeline import plan_write as _pw
+    plans = _pw(gene, EditIntent(intent), cargo_bp, ct, k=1)
+    return (plans[0] if plans else {"gene": gene, "found": False}) | {"tool": "planner.pipeline"}
+
+
+def ask_literature(q: str) -> dict:
+    """Grounded, cited literature answer (numbers still from tools)."""
+    from pen_stack.rag.qa import answer
+    a = answer(q)
+    return {"answer": a["answer"], "citations": a["citations"], "tool": "rag.qa"}
+
+
+def multiplex_translocation_risk(edits: list[dict]) -> dict:
+    """Translocation-risk SCREEN for a multi-edit (2-5) plan: pairwise DSB-join risk across edits.
+
+    Each edit: {name, family, chrom, pos, optional offtargets:[{chrom,pos,risk}]}. DSB-free recombinase
+    writers contribute zero risk. A screen, not a calibrated predictor."""
+    from pen_stack.planner.multiplex import translocation_risk
+    return {**translocation_risk(edits), "tool": "planner.multiplex"}
+
+
+REGISTRY = {
+    "writability": writability,
+    "reachable_writers": reachable_writers,
+    "writer_axes": writer_axes,
+    "plan_write": plan_write,
+    "ask_literature": ask_literature,
+    "multiplex_translocation_risk": multiplex_translocation_risk,
+}
+
+# Ollama/OpenAI tool-calling schemas
+SCHEMAS = [
+    {"type": "function", "function": {
+        "name": "writability", "description": "Most-writable locus near a gene (safety x durability).",
+        "parameters": {"type": "object", "properties": {
+            "gene": {"type": "string"}, "ct": {"type": "string", "enum": ["k562", "hepg2", "hspc"]}},
+            "required": ["gene"]}}},
+    {"type": "function", "function": {
+        "name": "reachable_writers", "description": "Writer families that can reach a gene's best locus.",
+        "parameters": {"type": "object", "properties": {
+            "gene": {"type": "string"}, "ct": {"type": "string"}}, "required": ["gene"]}}},
+    {"type": "function", "function": {
+        "name": "writer_axes", "description": "Measured axes for a writer family.",
+        "parameters": {"type": "object", "properties": {"family": {"type": "string"}},
+                       "required": ["family"]}}},
+    {"type": "function", "function": {
+        "name": "plan_write", "description": "Full Write Planner: gene + edit_intent -> ranked plan.",
+        "parameters": {"type": "object", "properties": {
+            "gene": {"type": "string"},
+            "intent": {"type": "string", "enum": ["safe_harbour_insertion", "knock_in_with_disruption",
+                       "high_durability_insertion", "regulatory_excision", "repeat_excision"]},
+            "cargo_bp": {"type": "integer"}, "ct": {"type": "string"}},
+            "required": ["gene", "intent"]}}},
+    {"type": "function", "function": {
+        "name": "ask_literature", "description": "Grounded, cited literature answer.",
+        "parameters": {"type": "object", "properties": {"q": {"type": "string"}}, "required": ["q"]}}},
+    {"type": "function", "function": {
+        "name": "multiplex_translocation_risk",
+        "description": "Translocation-risk screen for a multi-edit plan (pairwise DSB-join risk).",
+        "parameters": {"type": "object", "properties": {
+            "edits": {"type": "array", "items": {"type": "object", "properties": {
+                "name": {"type": "string"}, "family": {"type": "string"},
+                "chrom": {"type": "string"}, "pos": {"type": "integer"}}}}},
+            "required": ["edits"]}}},
+]
+
+
+def dispatch(name: str, args: dict) -> Any:
+    """Execute a validated tool by name. Raises KeyError for unknown tools (never fabricates)."""
+    if name not in REGISTRY:
+        raise KeyError(f"unknown tool: {name}")
+    return REGISTRY[name](**args)

pen_stack/api/__init__.py

@@ -0,0 +1,12 @@
+"""pen_stack.api, the self-describing AI integration surface.
+
+A machine-readable capability manifest (what PEN-STACK can do) and, the differentiator, a machine-readable
+scope manifest (what it refuses to answer: the known-unknowns + the oracle scope cards). An external agent can
+ask "what can you do, and what do you refuse to answer?" and get a typed, valid answer it can route on. The
+grounding machinery becomes an API, versioned under the public API stability commitment.
+"""
+from __future__ import annotations
+
+from pen_stack.api.manifest import capability_manifest, scope_manifest
+
+__all__ = ["capability_manifest", "scope_manifest"]