pen-stack 3.1.0__py3-none-any.whl

pen_stack/__init__.py

@@ -0,0 +1,2 @@
+"""PEN-STACK v3.0 - open infrastructure for genome writing."""
+__version__ = "3.1.0"

pen_stack/_resources.py

@@ -0,0 +1,34 @@
+"""Resolve repo-relative resource files (configs, prereg, curated data) in both layouts.
+
+PEN-STACK is a research pipeline: the pip wheel ships the importable library + CLI + the pure-logic tools,
+while the full data pipeline (3 M-row atlases, curated configs, BigWig tracks) lives in the cloned repo and
+on Zenodo, per the data policy in the README. This helper finds resource files when running from a source
+checkout/sdist, and gives installed users a single escape hatch (`PEN_STACK_HOME`) to point at a checkout.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_PKG = Path(__file__).resolve().parent          # .../pen_stack
+_ENV = "PEN_STACK_HOME"
+
+
+def project_root() -> Path:
+    """Best guess at the project root holding configs/, prereg/, data/. `PEN_STACK_HOME` overrides."""
+    env = os.environ.get(_ENV)
+    if env:
+        return Path(env).expanduser()
+    return _PKG.parent                          # repo root in a source checkout / sdist
+
+
+def resource(rel: str) -> Path:
+    """Absolute path to a repo-relative resource (e.g. 'configs/cargo_polish.yaml'). Raises a clear,
+    actionable error if it is not present (e.g. a bare `pip install` without `PEN_STACK_HOME` or a checkout)."""
+    p = project_root() / rel
+    if not p.exists():
+        raise FileNotFoundError(
+            f"resource {rel!r} not found at {p}. The pip wheel ships the library, not the full data/config "
+            f"tree. Clone the repo for the full pipeline, or set {_ENV} to a checkout: "
+            f"export {_ENV}=/path/to/pen-stack")
+    return p

pen_stack/adapt/__init__.py

@@ -0,0 +1,14 @@
+"""Local recalibration / private-data adaptation (v3.1, WS-F).
+
+Released PEN-STACK models can be recalibrated (or lightly fine-tuned) on a user's own assays - inside
+Docker, on private data that never leaves the machine - behind a VALIDATION GATE so quality cannot silently
+regress. The adapted artifact activates only if it beats the released model on the user's held-out split;
+the released model is never overwritten (separate versioning under models/local_<id>/).
+"""
+from __future__ import annotations
+
+from pen_stack.adapt.pipeline import adapt
+from pen_stack.adapt.recalibrate import IsotonicCalibrator, recalibrate
+from pen_stack.adapt.report import evaluate, gate, model_card
+
+__all__ = ["adapt", "IsotonicCalibrator", "recalibrate", "evaluate", "gate", "model_card"]

pen_stack/adapt/finetune.py

@@ -0,0 +1,33 @@
+"""WS-F2(b) - OPTIONAL light fine-tuning: a LightGBM head on the user's features.
+
+This is the heavier, opt-in path (the default WS-F adaptation is isotonic recalibration, which is far more
+robust on small private datasets). It trains a small LightGBM classifier on the user's features+labels - or
+continues training from a released booster via `init_model` - and is subject to the SAME validation gate:
+it activates only if it beats the released model on the held-out split. Small-data overfitting is mitigated
+(not eliminated) by the gate, shallow trees, and strong regularization.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+
+def finetune_head(X, y, init_model=None, seed: int = 0, n_estimators: int = 100):
+    """Train (or continue-train) a small, regularized LightGBM head. Returns the fitted model."""
+    import lightgbm as lgb
+    X, y = np.asarray(X, float), np.asarray(y, float)
+    if X.ndim == 1:
+        X = X.reshape(-1, 1)
+    model = lgb.LGBMClassifier(
+        n_estimators=n_estimators, num_leaves=15, max_depth=4, learning_rate=0.05,
+        min_child_samples=20, reg_lambda=1.0, subsample=0.8, colsample_bytree=0.8,
+        random_state=seed, verbose=-1)
+    model.fit(X, y.astype(int), init_model=init_model)
+    return model
+
+
+def predict_proba(model, X):
+    import numpy as np
+    X = np.asarray(X, float)
+    if X.ndim == 1:
+        X = X.reshape(-1, 1)
+    return model.predict_proba(X)[:, 1]

pen_stack/adapt/ingest.py

@@ -0,0 +1,86 @@
+"""WS-F1 - ingest a user's private assay into per-site labels matching the model's feature schema.
+
+The runnable in-code path is TABULAR: a CSV/TSV/Parquet of sites + an outcome label (and, optionally, the
+released-model score column or the per-bin features to attach). The upstream FASTQ/BAM -> per-site label
+derivation (integration-site sequencing, GUIDE-seq, expression-stability profiling) is documented in
+docs/private_data_formats.md and runs in the Docker image with the usual aligners; it produces exactly the
+tabular schema this module validates, so the two halves compose.
+
+Schema (standardized output): chrom, bin, ct, label, [score], [features...]
+  * label: 0/1 (discrimination) or a real value in [0,1] (calibration target).
+  * score: the released model's output for that site (safety / p_durable / writability) - the thing we
+    recalibrate. If absent, attach_features() joins it from the writability atlas.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+BIN_BP = 1000
+REQUIRED = ("chrom", "label")            # plus one of {bin, pos}
+
+
+def load_user_labels(path: str | Path) -> pd.DataFrame:
+    """Load + validate a user label table (.csv/.tsv/.parquet). Returns a frame with chrom, bin, ct, label."""
+    p = Path(path)
+    if p.suffix in (".parquet", ".pq"):
+        df = pd.read_parquet(p)
+    else:
+        df = pd.read_csv(p, sep="\t" if p.suffix in (".tsv", ".txt") else ",")
+    return normalize(df)
+
+
+def normalize(df: pd.DataFrame) -> pd.DataFrame:
+    """Validate columns and standardize: derive `bin` from `pos` if needed; coerce label; default ct."""
+    df = df.copy()
+    missing = [c for c in REQUIRED if c not in df.columns]
+    if missing:
+        raise ValueError(f"user table missing required columns: {missing} (have {list(df.columns)})")
+    if "bin" not in df.columns:
+        if "pos" not in df.columns:
+            raise ValueError("user table needs a 'bin' or a 'pos' column to locate each site")
+        df["bin"] = (df["pos"].astype(int) // BIN_BP).astype(int)
+    if "ct" not in df.columns:
+        df["ct"] = "user"
+    lab = pd.to_numeric(df["label"], errors="coerce")
+    if lab.isna().any():
+        raise ValueError("label column has non-numeric / missing values")
+    if not (((lab == 0) | (lab == 1)).all() or ((lab >= 0) & (lab <= 1)).all()):
+        raise ValueError("label must be binary {0,1} or a probability in [0,1]")
+    df["label"] = lab.astype(float)
+    keep = ["chrom", "bin", "ct", "label"] + [c for c in df.columns
+                                              if c not in ("chrom", "bin", "ct", "label", "pos")]
+    return df[keep].reset_index(drop=True)
+
+
+def attach_features(df: pd.DataFrame, target: str = "safety", ct: str = "k562") -> pd.DataFrame:
+    """Join the released model's score for `target` (safety|p_durable|writability) from the Phase-1 atlas.
+
+    No-op if the score column is already present (user supplied it). Raises if the atlas is unavailable and
+    no score column exists - the caller then supplies scores directly.
+    """
+    col = {"safety": "safety", "durability": "p_durable", "p_durable": "p_durable",
+           "writability": "writability"}.get(target, target)
+    if col in df.columns and df[col].notna().any():
+        return df.rename(columns={col: "score"}) if col != "score" else df
+    if "score" in df.columns:
+        return df
+    atlas = Path(__file__).resolve().parents[2].parent / "phase_1" / "out" / f"atlas_{ct}.parquet"
+    if not atlas.exists():
+        raise FileNotFoundError(
+            f"no '{col}'/'score' column and Phase-1 atlas absent ({atlas}); supply the released-model score "
+            "column in the user table, or run inside the image where the atlas is mounted.")
+    a = pd.read_parquet(atlas, columns=["chrom", "bin", col])
+    out = df.merge(a, on=["chrom", "bin"], how="left").rename(columns={col: "score"})
+    if out["score"].isna().any():
+        out = out.dropna(subset=["score"]).reset_index(drop=True)
+    return out
+
+
+def schema_summary(df: pd.DataFrame) -> dict:
+    return {"n_sites": int(len(df)), "n_chroms": int(df["chrom"].nunique()),
+            "label_kind": "binary" if set(np.unique(df["label"])) <= {0.0, 1.0} else "continuous",
+            "positive_rate": round(float(df["label"].mean()), 4),
+            "has_score": "score" in df.columns}

pen_stack/adapt/pipeline.py

@@ -0,0 +1,101 @@
+"""WS-F2 - the adaptation pipeline (ingest -> split -> recalibrate/finetune -> held-out gate -> version).
+
+`adapt()` is the one entry point. It splits the user's sites into train/held-out (chromosome-grouped when
+possible), fits the adaptation on train, scores the released vs adapted model on the SAME held-out split,
+and applies the validation gate. The adapted artifact is written under models/local_<id>/ ONLY - the
+released model is never overwritten, and its fingerprint is checked before/after to prove it (acceptance).
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from pen_stack.adapt import report as R
+from pen_stack.adapt.recalibrate import recalibrate
+
+_ROOT = Path(__file__).resolve().parents[2]
+_MODELS = _ROOT / "models"
+# released score-producing modules - the "released model" we must prove is unchanged by adaptation.
+_RELEASED = [_ROOT / "pen_stack" / "wgenome" / m for m in ("safety.py", "durability.py", "writability.py")]
+
+
+def _split(df: pd.DataFrame, seed: int, holdout_frac: float = 0.3):
+    """Chromosome-grouped holdout when >=2 chromosomes (no leakage); else a seeded random split."""
+    rng = np.random.default_rng(seed)
+    chroms = df["chrom"].unique()
+    if len(chroms) >= 2:
+        n_ho = max(1, int(round(len(chroms) * holdout_frac)))
+        ho_chroms = set(rng.choice(chroms, size=n_ho, replace=False))
+        mask = df["chrom"].isin(ho_chroms)
+    else:
+        mask = pd.Series(rng.random(len(df)) < holdout_frac, index=df.index)
+    return df[~mask].reset_index(drop=True), df[mask].reset_index(drop=True)
+
+
+def adapt(df: pd.DataFrame, target: str = "safety", method: str = "isotonic", local_id: str = "local",
+          seed: int = 20260604, primary: str = "brier", margin: float = 0.0,
+          feature_cols: list[str] | None = None, models_dir: str | Path = _MODELS) -> dict:
+    """Recalibrate (or fine-tune) the released `target` score on the user frame (needs 'score' + 'label').
+
+    Returns the held-out before/after report + the gate decision + the artifact paths. The adapted model is
+    activated (written + flagged) only if it beats the released model on the held-out split.
+    """
+    if "score" not in df.columns or "label" not in df.columns:
+        raise ValueError("adapt() needs standardized columns 'score' and 'label' (see adapt.ingest)")
+    fp_before = R.released_fingerprint(*_RELEASED)
+
+    train, holdout = _split(df, seed)
+    if len(train) < 5 or len(holdout) < 3:
+        raise ValueError(f"not enough data after split (train={len(train)}, holdout={len(holdout)})")
+
+    base_holdout = np.clip(holdout["score"].to_numpy(float), 0, 1)   # released score as a probability
+    if method == "isotonic":
+        cal = recalibrate(train["score"], train["label"])
+        adapted_holdout = cal.transform(holdout["score"])
+        artifact = "calibrator.json"
+    elif method == "finetune":
+        from pen_stack.adapt.finetune import finetune_head, predict_proba
+        cols = feature_cols or ["score"]
+        model = finetune_head(train[cols].to_numpy(float), train["label"], seed=seed)
+        adapted_holdout = predict_proba(model, holdout[cols].to_numpy(float))
+        cal, artifact = None, "head.txt"
+    else:
+        raise ValueError(f"unknown method: {method!r} (use 'isotonic' or 'finetune')")
+
+    # no-skill constant predictor: the TRAIN base rate applied to every held-out site (no leakage). The
+    # adapted model must beat this too, else its 'improvement' is just regression to climatology.
+    base_rate = float(np.clip(train["label"].mean(), 1e-6, 1 - 1e-6))
+    no_skill = R.evaluate(np.full(len(holdout), base_rate), holdout["label"])
+
+    base = R.evaluate(base_holdout, holdout["label"])
+    adapted = R.evaluate(adapted_holdout, holdout["label"])
+    gate = R.gate(base, adapted, primary=primary, margin=margin, no_skill=no_skill)
+
+    out_dir = Path(models_dir) / f"local_{local_id}"
+    fp_after = R.released_fingerprint(*_RELEASED)
+    released_unchanged = fp_before == fp_after
+    report = {"local_id": local_id, "target": target, "method": method,
+              "n_train": int(len(train)), "n_holdout": int(len(holdout)),
+              "held_out_before": base, "held_out_after": adapted, "held_out_no_skill": no_skill, "gate": gate,
+              "released_model_unchanged": released_unchanged,
+              "released_fingerprint": fp_after, "activated": gate["activate"]}
+    card = R.model_card(f"local_{local_id}", target, method, base, adapted, gate,
+                        len(train), len(holdout), fp_after)
+    paths = R.write_report(out_dir, report, card)
+    # persist the adapted artifact ONLY when the gate passes; otherwise remove any stale artifact so a
+    # previously-activated adaptation that now fails the gate is not left active (released model stays in force).
+    artifact_path = out_dir / artifact
+    if gate["activate"]:
+        if method == "isotonic":
+            cal.save(artifact_path)
+        else:
+            model.booster_.save_model(str(artifact_path))
+        paths["artifact"] = str(artifact_path)
+    else:
+        for stale in (out_dir / "calibrator.json", out_dir / "head.txt"):
+            if stale.exists():
+                stale.unlink()
+    report["paths"] = paths
+    return report

pen_stack/adapt/recalibrate.py

@@ -0,0 +1,58 @@
+"""WS-F2(a) - isotonic recalibration of a released score on user labels (private, in-container).
+
+Isotonic regression learns a monotonic map released_score -> calibrated probability. Being monotonic it
+NEVER changes the ranking (AUROC is preserved); it only fixes calibration (Brier / ECE). Small and robust on
+the small datasets users typically have. The calibrator is saved as plain JSON under models/local_<id>/ -
+the released model is untouched.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+
+
+class IsotonicCalibrator:
+    """Thin, serializable wrapper around sklearn's IsotonicRegression (saved as JSON, no pickle)."""
+
+    def __init__(self):
+        self._iso = None
+        self.fitted = False
+
+    def fit(self, scores, labels) -> "IsotonicCalibrator":
+        from sklearn.isotonic import IsotonicRegression
+        s, y = np.asarray(scores, float), np.asarray(labels, float)
+        self._iso = IsotonicRegression(out_of_bounds="clip", y_min=0.0, y_max=1.0)
+        self._iso.fit(s, y)
+        self.fitted = True
+        return self
+
+    def transform(self, scores):
+        if not self.fitted:
+            raise RuntimeError("calibrator not fitted")
+        return self._iso.predict(np.asarray(scores, float))
+
+    def to_dict(self) -> dict:
+        return {"kind": "isotonic", "x": list(map(float, self._iso.X_thresholds_)),
+                "y": list(map(float, self._iso.y_thresholds_))}
+
+    def save(self, path: str | Path) -> Path:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        Path(path).write_text(json.dumps(self.to_dict(), indent=2), encoding="utf-8")
+        return Path(path)
+
+    @classmethod
+    def load(cls, path: str | Path) -> "IsotonicCalibrator":
+        d = json.loads(Path(path).read_text(encoding="utf-8"))
+        obj = cls()
+        from sklearn.isotonic import IsotonicRegression
+        iso = IsotonicRegression(out_of_bounds="clip", y_min=0.0, y_max=1.0)
+        iso.fit(np.asarray(d["x"], float), np.asarray(d["y"], float))   # re-fit on the stored knots
+        obj._iso, obj.fitted = iso, True
+        return obj
+
+
+def recalibrate(scores, labels) -> IsotonicCalibrator:
+    """Fit an isotonic calibrator mapping a released score to a calibrated probability on user labels."""
+    return IsotonicCalibrator().fit(scores, labels)

pen_stack/adapt/report.py

@@ -0,0 +1,130 @@
+"""WS-F2(c,d) - held-out evaluation, the validation GATE, and the model card.
+
+The adapted artifact ACTIVATES only if it beats the released model on the user's held-out split (the gate).
+Calibration is judged by Brier score + expected calibration error (ECE, lower is better); discrimination by
+AUROC (higher is better). The released model is provably unchanged (its artifact hash is recorded and
+re-checked); a before/after report and a model card are always written.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import numpy as np
+
+
+def _auroc(scores, labels) -> float:
+    pos = [s for s, y in zip(scores, labels) if y == 1]
+    neg = [s for s, y in zip(scores, labels) if y == 0]
+    if not pos or not neg:
+        return float("nan")
+    return sum((p > n) + 0.5 * (p == n) for p in pos for n in neg) / (len(pos) * len(neg))
+
+
+def _ece(probs, labels, n_bins: int = 10) -> float:
+    probs, labels = np.asarray(probs, float), np.asarray(labels, float)
+    edges = np.linspace(0, 1, n_bins + 1)
+    ece, n = 0.0, len(probs)
+    for i in range(n_bins):
+        m = (probs >= edges[i]) & (probs < edges[i + 1] if i < n_bins - 1 else probs <= edges[i + 1])
+        if m.sum():
+            ece += (m.sum() / n) * abs(probs[m].mean() - labels[m].mean())
+    return float(ece)
+
+
+def evaluate(probs, labels) -> dict:
+    """Calibration + discrimination metrics for a set of probabilities against binary labels."""
+    probs, labels = np.asarray(probs, float), np.asarray(labels, float)
+    brier = float(np.mean((probs - labels) ** 2))
+    biny = labels if set(np.unique(labels)) <= {0.0, 1.0} else (labels >= 0.5).astype(float)
+    return {"n": int(len(probs)), "brier": round(brier, 5), "ece": round(_ece(probs, biny), 5),
+            "auroc": round(_auroc(list(probs), list(biny)), 4)}
+
+
+def gate(base: dict, adapted: dict, primary: str = "brier", margin: float = 0.0,
+         no_skill: dict | None = None) -> dict:
+    """Activate the adapted model only if it BEATS the released model AND the no-skill constant predictor on
+    the held-out primary metric.
+
+    primary='brier'|'ece' -> lower is better; primary='auroc' -> higher is better. `margin` is the minimum
+    improvement required (guards against noise on small holdouts). The `no_skill` guard is essential:
+    recalibration can trivially lower Brier by regressing to the base rate, so we require the adapted model
+    to beat the constant base-rate predictor too - otherwise the 'improvement' is no skill, just climatology.
+    """
+    lower_better = primary in ("brier", "ece")
+
+    def better(x, ref):
+        return (ref - x) if lower_better else (x - ref)
+
+    b, a = base[primary], adapted[primary]
+    imp_released = better(a, b)
+    beats_released = imp_released > margin
+    beats_no_skill = True
+    ns = None
+    if no_skill is not None:
+        ns = no_skill[primary]
+        beats_no_skill = better(a, ns) > margin
+    activate = bool(beats_released and beats_no_skill)
+    if activate:
+        decision = "ADAPTED ACTIVATED (beats released AND the no-skill constant on held-out)"
+    elif not beats_no_skill:
+        decision = "ADAPTED REJECTED (improvement is no skill - does not beat the constant base rate)"
+    else:
+        decision = "ADAPTED REJECTED (does not beat released; released model kept)"
+    return {"primary_metric": primary, "lower_is_better": lower_better,
+            "released": b, "adapted": a, "no_skill_constant": ns,
+            "improvement_vs_released": round(imp_released, 5), "margin": margin,
+            "beats_released": bool(beats_released), "beats_no_skill": bool(beats_no_skill),
+            "activate": activate, "decision": decision}
+
+
+def released_fingerprint(*paths: str | Path) -> dict:
+    """Hash designated released-model artifacts so we can prove they are unchanged by adaptation."""
+    import hashlib
+    fp = {}
+    for p in paths:
+        p = Path(p)
+        if p.exists():
+            fp[str(p.name)] = hashlib.sha256(p.read_bytes()).hexdigest()[:16]
+    return fp
+
+
+def model_card(local_id: str, target: str, method: str, base: dict, adapted: dict, gate_res: dict,
+               n_train: int, n_holdout: int, released_fp: dict) -> str:
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    return "\n".join([
+        f"# PEN-STACK local adaptation - {local_id}",
+        "",
+        f"- **Date:** {ts}",
+        f"- **Target score:** {target}    **Method:** {method}",
+        f"- **Data:** {n_train} train / {n_holdout} held-out sites (private, in-container)",
+        f"- **Released-model fingerprint (unchanged):** {released_fp}",
+        "",
+        "## Held-out before/after",
+        "| metric | released | adapted |",
+        "|---|---|---|",
+        f"| Brier (lower better) | {base['brier']} | {adapted['brier']} |",
+        f"| ECE (lower better) | {base['ece']} | {adapted['ece']} |",
+        f"| AUROC (higher better) | {base['auroc']} | {adapted['auroc']} |",
+        "",
+        f"## Gate: **{gate_res['decision']}**",
+        f"- primary metric `{gate_res['primary_metric']}`: released {gate_res['released']} -> adapted "
+        f"{gate_res['adapted']} (improvement vs released {gate_res['improvement_vs_released']}, "
+        f"no-skill constant {gate_res.get('no_skill_constant')}, margin {gate_res['margin']}; "
+        f"beats released={gate_res['beats_released']}, beats no-skill={gate_res['beats_no_skill']}).",
+        "",
+        "## Scope",
+        "Recalibration / light fine-tuning on a small private dataset; overfitting is mitigated (not "
+        "eliminated) by the held-out gate. Not unsupervised learning from raw reads. The released model is "
+        "never overwritten - this artifact lives under `models/local_<id>/` and activates only if the gate "
+        "passed.",
+    ])
+
+
+def write_report(out_dir: str | Path, report: dict, card: str) -> dict:
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "report.json").write_text(json.dumps(report, indent=2, default=str), encoding="utf-8")
+    (out / "model_card.md").write_text(card, encoding="utf-8")
+    return {"report": str(out / "report.json"), "model_card": str(out / "model_card.md")}

pen_stack/agent/__init__.py

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

pen_stack/agent/guardrails.py

@@ -0,0 +1,49 @@
+"""LLM guardrails for PEN-STACK platform services (Phase 2, Section 2B).
+
+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 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,42 @@
+"""PEN-STACK MCP server (Phase 3, Step 3.10; v3.1 WS-E2) - 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)            # WS-G1: 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)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    mcp.run()