pen-stack 6.4.1__tar.gz → 6.4.3__tar.gz

{pen_stack-6.4.1 → pen_stack-6.4.3}/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [6.4.3] - 2026-06-12 - Chat vehicle-parse fix (AAVS1 no longer hijacks the vehicle)
+
+**PATCH.** `web/tools.py::parse_goal` matched the delivery vehicle by substring, so the safe-harbour nickname
+**AAVS1** (which contains "aav") wrongly selected the **AAV** vehicle even when the user said *lentivirus* or
+*LNP* — producing the wrong immune profile (e.g. genotoxicity 1.0 instead of lentivirus's 0.481). Fix: strip the
+safe-harbour nicknames (AAVS1/H11/HIPP11/ROSA26) from the vehicle-search text before matching, so the user's
+stated vehicle wins. Explicit "AAV" still selects AAV. New test locks all three cases.
+
+## [6.4.2] - 2026-06-12 - Co-Scientist chat: real writer recommendations + self-explanatory values
+
+**PATCH — fixes a stale/confusing chat experience reported from the live app.** Three problems, three fixes:
+
+1. **The chat dossier was generic and barely changed per query.** `web/tools.py::parse_goal` hardcoded
+   `chrom="chr19"` (so a goal about ITGB2 — chr21 — was mis-located) and `run_tools` never called the planner,
+   so a "which writer can integrate N kb in GENE" question got a vehicle-keyed immune profile but **no named
+   writer**. Fix: `parse_goal` now resolves the gene's REAL chromosome (`planner.gene_region`, atlas-gated,
+   falls back offline), and `run_tools` runs the planner and attaches a `plan` block — the recommended writer
+   family, top site, safety/durability/score, cargo-capacity fit, and delivery — all engine-computed. Honest
+   when the gene isn't in the atlas ("not found — check the HGNC symbol"); never fabricated.
+2. **The LLM narration produced `[unverified]` spam.** With no writer in the tool results, the model invented
+   one (`AAV9-CRISPR` + made-up numbers) and the grounding guard struck them all. Fix: the system prompt now
+   forbids inventing a writer/vehicle/table/number, and if the guard still strikes ≥2 numbers the reply falls
+   back to the fully-grounded deterministic narration — so the spam never reaches the user.
+3. **Values + the "⚠ extrapolating" badge weren't self-explanatory.** Each immune axis now carries a
+   plain-language `meaning` ("0.55 on a 0–1 scale — moderate; higher = fewer patients excluded …; this is a
+   proxy, not validated against a measured outcome"), the deterministic narration uses it, and
+   `ImmuneProfileCard` renders it plus a one-line legend explaining that "extrapolating" = a proxy estimate.
+
+### Added
+- `tests/unit/test_ws_chat.py` — chrom resolution, axis-meaning, real writer plan, and the no-`[unverified]`-spam
+  fallback are locked by new tests.
+
+## [6.4.1] - 2026-06-12 - Defence-in-depth: pre-route safety screen
+
+**PATCH.** The grounded co-scientist chat ran the Guardian (biosecurity gate) only in the *design* lane (via
+`run_tools`); a hazardous request with no design signal (no vehicle/locus) routed to `general`/`explain`/`meta`
+and was never screened. Fix: `pen_stack/web/llm.py::_pre_route_safety` runs the Guardian — framing-stripped, the
+authority on the decision — at the **top** of `grounded_reply()`, before lane routing. A `refuse`/`escalate`
+verdict short-circuits to a clear decline (`mode="safety"`, with the decision in `tool_results`). Benign
+hazard-adjacent biology (vaccines, generic pathogen questions) is **not** blocked — the Guardian clears it and
+routing continues. A broad regex only decides *whether* to invoke the Guardian; a false trigger is harmless.
+
+### Added
+- `tests/unit/test_ws_chat.py` — `test_pre_route_safety_screens_a_hazardous_general_query` and
+  `test_pre_route_safety_does_not_over_refuse_benign_questions` lock both sides of the screen.
+
 ## [6.4.0] - 2026-06-12 - v6.4.0: Live Oracles (the foundation models actually execute)
 
 **The oracle mesh goes live.** The foundation-model adapters that were deferred contracts now run real backends —

{pen_stack-6.4.1 → pen_stack-6.4.3}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 6.4.0
-date-released: 2026-06-11
+version: 6.4.3
+date-released: 2026-06-12
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-6.4.1 → pen_stack-6.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.4.1
+Version: 6.4.3
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -90,7 +90,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.4.3-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)

{pen_stack-6.4.1 → pen_stack-6.4.3}/README.md

@@ -15,7 +15,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.4.3-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)

{pen_stack-6.4.1 → pen_stack-6.4.3}/pen_stack/__init__.py

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

{pen_stack-6.4.1 → pen_stack-6.4.3}/pen_stack/web/llm.py

@@ -28,11 +28,13 @@ from pen_stack.web.tools import extract_grounded_numbers, run_tools
 # -------------------------------------------------------------------------------------- system prompts
 SYSTEM_GROUNDED = (
     "You are PEN-STACK's co-scientist for genome writing. The PEN-STACK ENGINE computed the TOOL RESULTS; you "
-    "explain and route, but you MUST NOT state any number, score, or probability that is not present in the TOOL "
-    "RESULTS or the METRIC GUIDE provided. For every key number, also explain what it MEANS using the metric "
-    "guide — its scale, whether higher is better, the reference band, and how it was computed — so the user "
-    "understands the value, not just sees it. Surface uncertainty and the scope ledger ('what I can't tell you'). "
-    "Be concise, friendly, honest. Decision-support, not a clinical directive."
+    "explain and route, but you MUST NOT state any number, score, probability, writer/enzyme name, or delivery "
+    "vehicle that is not present in the TOOL RESULTS or the METRIC GUIDE provided. NEVER invent a recommendation, "
+    "a markdown table of made-up values, or a 'hypothetical' result — if the engine did not compute something, "
+    "say so plainly. For every key number, explain what it MEANS in plain words — its scale, whether higher is "
+    "better, the reference band, how it was computed — so the user understands the value, not just sees it. "
+    "Surface uncertainty and the scope ledger ('what I can't tell you'). Be concise, friendly, honest. "
+    "Decision-support, not a clinical directive."
 )
 SYSTEM_META = (
     "You are PEN-STACK's co-scientist explaining the SYSTEM ITSELF (coverage, methods, accuracy). Answer using "
@@ -84,12 +86,46 @@ def _fmt(x):
     return str(x)
 
 
+def _narrate_plan(p: dict) -> str | None:
+    """The actual writer/site recommendation as a self-explanatory line (or an honest 'not found' note)."""
+    if not p or not p.get("available"):
+        return None
+    if not p.get("found"):
+        return f"**Recommended writer.** {p.get('why', 'no writable plan for this target.')}"
+    bits = [f"the top writer family is **{p['recommended_writer']}**"]
+    site = p.get("site") or {}
+    if site.get("chrom"):
+        bits.append(f"at **{site['chrom']}:bin{site.get('bin')}**")
+    nums = []
+    if p.get("safety") is not None:
+        nums.append(f"safety {_fmt(p['safety'])}")
+    if p.get("durability") is not None:
+        nums.append(f"durability {_fmt(p['durability'])}")
+    if p.get("score") is not None:
+        nums.append(f"plan score {_fmt(p['score'])}")
+    cap = p.get("cargo_capacity_bp")
+    fit = p.get("cargo_fits_single_vector")
+    cargo_note = ""
+    if cap is not None:
+        cargo_note = (f" Cargo capacity is **{cap} bp**; the assembled cassette "
+                      f"({p.get('assembled_bp', '?')} bp) "
+                      + ("fits a single vector" if fit else f"exceeds it → delivered as **{p.get('delivery', 'split/dual')}**")
+                      + ".")
+    alts = p.get("alternative_writers") or []
+    alt_note = f" Alternatives: {', '.join(alts)}." if alts else ""
+    return (f"**Recommended writer.** For this target {', '.join(bits)} "
+            f"({'; '.join(nums)}).{cargo_note}{alt_note} (0–1 scores, higher = better.)")
+
+
 def _deterministic_narrate(tr: dict) -> str:
     d = tr["parsed_design"]
     v = tr["verdict"]
     lines = [f"I read your goal as a **{d['edit_intent'].replace('_', ' ')}** of **{d['gene']}** "
-             f"(~{d['cargo_bp']} bp) by **{d['delivery_vehicle'].replace('_', ' ')}** in **{d['cell_type']}**. "
-             f"Every number below is engine-computed."]
+             f"({d['chrom']}, ~{d['cargo_bp']} bp) by **{d['delivery_vehicle'].replace('_', ' ')}** "
+             f"in **{d['cell_type']}**. Every number below is engine-computed."]
+    plan_line = _narrate_plan(tr.get("plan") or {})
+    if plan_line:
+        lines.append(plan_line)
     legal = "legal" if v["legal"] else ("deferred" if v["legal"] is None else "ILLEGAL")
     line = f"**Verification.** The design is **{legal}** ({v['epistemic_status']})."
     if v["violations"]:
@@ -107,13 +143,14 @@ def _deterministic_narrate(tr: dict) -> str:
         lines.append(f"**Safety (Guardian).** **{s['decision']}** — {s.get('reason', '')}. {sd}")
     axes = (tr["immune_profile"].get("axes") or {})
     if axes:
-        lines.append("**Immune-risk profile** (per-axis — never collapsed). Each is 0–1, higher = safer:")
+        lines.append("**Immune-risk profile** (per-axis — never collapsed; each is 0–1, higher = safer):")
         for name, a in axes.items():
             gd = guide_for(name) or {}
             val = _fmt(a["value"]) if a.get("value") is not None else "n/a"
             unc = f" ±{_fmt(a['uncertainty'])}" if a.get("uncertainty") is not None else ""
-            meaning = (gd.get("means", "").split(".")[0]) if gd else ""
-            lines.append(f"  • **{gd.get('label', name)}: {val}{unc}** — {meaning}. _{a.get('validation', '')}_")
+            # prefer the self-explanatory engine 'meaning' (says what the value means + the proxy caveat in words)
+            meaning = a.get("meaning") or ((gd.get("means", "").split(".")[0]) if gd else "")
+            lines.append(f"  • **{gd.get('label', name)}: {val}{unc}** — {meaning}")
     ku = tr["immune_profile"].get("known_unknowns") or []
     if ku:
         lines.append("**What I can't tell you** (measured, never predicted): " + ", ".join(str(x) for x in ku) + ".")
@@ -353,14 +390,24 @@ def grounded_reply(message: str, history: list | None = None, *, allow_llm: bool
     base = {"mode": mode, "provenance": "pen-stack", "grounded": True, "tool_results": tr,
             "angles": None, "facts": None}
     if allow_llm:
-        prompt = (f"TOOL RESULTS (the only source of THIS design's numbers):\n{json.dumps(tr, default=str)}\n\n"
+        prompt = (f"TOOL RESULTS (the only source of THIS design's numbers — including the recommended writer in "
+                  f"`plan`):\n{json.dumps(tr, default=str)}\n\n"
                   f"METRIC GUIDE (use to EXPLAIN what each number means — scale, direction, reference band; you "
                   f"may cite band thresholds):\n{json.dumps(guides, default=str)}\n"
                   f"SAFETY DECISIONS:\n{json.dumps(bands)}\n\n{hist}USER: {message}\n\n"
-                  f"Reply with: (1) the engine's findings WITH the numbers, (2) what each key number MEANS using "
-                  f"the metric guide (scale, what's good/bad, reference range), (3) the uncertainty + scope ledger. "
-                  f"Use ONLY numbers in the tool results or the metric guide.")
+                  f"Reply with: (1) the engine's findings WITH the numbers — if the user asked which writer, lead "
+                  f"with `plan.recommended_writer` and its site/scores (do NOT name any other writer or vehicle), "
+                  f"(2) what each key number MEANS in plain words (scale, what's good/bad, reference range), "
+                  f"(3) the uncertainty + scope ledger. STRICT: use ONLY numbers present in the tool results or the "
+                  f"metric guide; do NOT invent a writer name, a vehicle, a table, or any number. If something "
+                  f"isn't in the tool results, say it is not computed.")
         text, backend = _run_llm(prompt, SYSTEM_GROUNDED)
         if text:
-            return {**base, "reply": _enforce_grounding(text, allow), "backend": backend}
+            cleaned = _enforce_grounding(text, allow)
+            # Defence against fabrication-spam: if the model invented a lot of numbers (the guard struck many),
+            # the narrated reply is unreadable ([unverified] everywhere) — fall back to the deterministic,
+            # fully-grounded narration so the user always gets a clean, traceable answer.
+            if cleaned.count(_UNVERIFIED) >= 2:
+                return {**base, "reply": _deterministic_narrate(tr), "backend": f"deterministic (guard:{backend})"}
+            return {**base, "reply": cleaned, "backend": backend}
     return {**base, "reply": _deterministic_narrate(tr), "backend": "deterministic"}

pen_stack-6.4.3/pen_stack/web/tools.py

@@ -0,0 +1,197 @@
+"""Engine tool-runner for the grounded co-scientist (PEN-STACK v6.2, WS-CHAT support).
+
+The chat NEVER sources a number. This module is where the ENGINE computes everything: it parses a plain-language
+goal, runs the validated tools (verify -> legality + safety + calibrated confidence + immune profile; the scope
+matcher for known-unknowns), and returns a structured "dossier" of grounded facts. `extract_grounded_numbers`
+returns the allow-list of values the LLM is permitted to cite — anything else it emits is stripped by the
+grounding guard. No LLM is involved here; this is deterministic.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+# tiny, transparent keyword maps (the engine grounds everything; this only routes a plain-language goal).
+_VEHICLES = {"aav": "AAV_single", "aav single": "AAV_single", "aav dual": "AAV_dual", "dual aav": "AAV_dual",
+             "lentivir": "lentivirus", "lnp": "lnp_mrna", "mrna": "lnp_mrna", "adenovir": "helper_dependent_adenovirus",
+             "hsv": "hsv_amplicon", "electroporat": "electroporation"}
+_INTENTS = {"safe harbour": "safe_harbour_insertion", "safe harbor": "safe_harbour_insertion",
+            "knock-in": "knock_in_with_disruption", "knock in": "knock_in_with_disruption",
+            "knockin": "knock_in_with_disruption", "durab": "high_durability_insertion",
+            "excis": "regulatory_element_excision", "regulator": "regulatory_element_excision",
+            "landing pad": "landing_pad_insertion", "repeat": "repeat_excision"}
+_CELLS = {"liver": "hepg2", "hepato": "hepg2", "hepg2": "hepg2", "hspc": "hspc", "stem cell": "h1_hesc",
+          "ipsc": "ipsc", "k562": "k562", "t cell": "cd8_t", "t-cell": "cd8_t", "car-t": "cd8_t", "pbmc": "pbmc"}
+_GENE_RE = re.compile(r"\b([A-Z][A-Z0-9]{1,7})\b")             # crude gene-symbol token (AAVS1, TRAC, FIX, ...)
+_KB_RE = re.compile(r"(\d+(?:\.\d+)?)\s*kb", re.I)
+_BP_RE = re.compile(r"(\d{3,6})\s*bp", re.I)
+# uppercase tokens that look like a gene but are not one (jargon / vehicle / form abbreviations)
+_GENE_STOP = {"DNA", "RNA", "MRNA", "AAV", "LNP", "HSV", "CAR", "RNP", "PCR", "WT", "KO", "KI", "ITR",
+              "ORF", "UTR", "CDS", "GFP", "ID", "QC", "VG", "MOI", "HLA", "MHC", "CRISPR", "CAS", "TF"}
+# safe-harbour locus nicknames whose text collides with a vehicle keyword (AAVS1 ⊃ "aav") — stripped before
+# vehicle matching so the user's stated vehicle (e.g. lentivirus) is not overridden by the locus name.
+_SAFE_HARBOUR_RE = re.compile(r"\b(aavs1|h11|hipp11|rosa26)\b", re.I)
+
+
+def _first(text: str, table: dict, default):
+    low = text.lower()
+    for key, val in table.items():
+        if key in low:
+            return val
+    return default
+
+
+def _resolve_chrom(gene: str) -> str | None:
+    """The real chromosome for a gene symbol (or a safe-harbour nickname like AAVS1); None if not resolvable
+    offline. So a chat goal about ITGB2 carries chr21, not a hardcoded default. Atlas-gated — never fabricates."""
+    try:
+        from pen_stack.planner.optimize import gene_region, resolve_gene
+        reg = gene_region(resolve_gene(gene))
+        return reg[0] if reg else None
+    except Exception:  # noqa: BLE001 - data/atlas absent (CI/offline) -> caller falls back to the default
+        return None
+
+
+def parse_goal(message: str) -> dict:
+    """Best-effort parse of a plain-language goal into a Design/Goal dict. The engine grounds everything; this
+    just picks a starting point (with sensible defaults) so the tools can run."""
+    cargo = 3000
+    if (m := _KB_RE.search(message)):
+        cargo = int(float(m.group(1)) * 1000)
+    elif (m := _BP_RE.search(message)):
+        cargo = int(m.group(1))
+    genes = [g for g in _GENE_RE.findall(message) if g not in _GENE_STOP]
+    gene = genes[0] if genes else "AAVS1"
+    # Vehicle matching is substring-based (so "lentivir" catches "lentiviral"); but the safe-harbour nickname
+    # "AAVS1" contains "aav", which would wrongly match the AAV vehicle even when the user said lentivirus/LNP.
+    # Strip those nicknames from the vehicle-search text first so the stated vehicle wins.
+    veh_text = _SAFE_HARBOUR_RE.sub(" ", message.lower())
+    return {"write_type": "insertion", "gene": gene, "chrom": _resolve_chrom(gene) or "chr19",
+            "edit_intent": _first(message, _INTENTS, "safe_harbour_insertion"),
+            "delivery_vehicle": _first(veh_text, _VEHICLES, "AAV_single"), "cargo_bp": cargo,
+            "cell_type": _first(message, _CELLS, "k562"),
+            # the user's plain-language goal IS the cargo-function description the Guardian must screen — so a
+            # message like "express a ricin toxin" is biosecurity-screened, not silently passed as benign.
+            "cargo_function": message.strip()}
+
+
+# the chat's free-text intents map onto the planner's EditIntent enum (landing-pad/regulatory have nearest valid).
+_INTENT_TO_ENUM = {"safe_harbour_insertion": "safe_harbour_insertion",
+                   "high_durability_insertion": "high_durability_insertion",
+                   "knock_in_with_disruption": "knock_in_with_disruption",
+                   "regulatory_element_excision": "regulatory_excision",
+                   "repeat_excision": "repeat_excision",
+                   "landing_pad_insertion": "safe_harbour_insertion"}
+
+# plain-language reading of each immune axis (0–1, higher = safer) — so a value is self-explanatory in the reply.
+_AXIS_DIRECTION = {
+    "genotoxicity": "higher = safer (less integration-site oncogene risk; 1.0 = episomal / non-integrating)",
+    "cd8_epitope": "higher = fewer strong CD8/MHC-I capsid epitopes (1.0 = non-viral / none)",
+    "innate": "higher = less innate (CpG/TLR9, RIG-I) sensing of the delivered cargo",
+    "preexisting_nab": "higher = fewer patients excluded by pre-existing neutralizing antibodies to the vector",
+    "anti_peg": "higher = lower pre-existing anti-PEG barrier to re-dosing (PEGylated vehicles only)",
+}
+
+
+def _band_word(v: float) -> str:
+    return "favourable" if v >= 0.7 else ("moderate" if v >= 0.4 else "a concern")
+
+
+def axis_meaning(name: str, value, validation: str | None) -> str:
+    """A self-explanatory, plain-language reading of one immune axis: what the number means + the proxy caveat."""
+    if value is None:
+        return "out of scope for this design — not predicted (no applicable mechanism)."
+    direction = _AXIS_DIRECTION.get(name, "0–1, higher = safer")
+    s = f"{float(value):.2f} on a 0–1 scale — {_band_word(float(value))}; {direction}."
+    if validation and ("proxy" in validation.lower() or "not outcome-validated" in validation.lower()):
+        s += (" This is a mechanistically/population-computed PROXY — it is not validated against a measured "
+              "clinical outcome, so read it as a directional estimate, not a guaranteed result.")
+    return s
+
+
+def _run_planner(design: dict) -> dict[str, Any]:
+    """The ACTUAL writer/site recommendation for the goal (atlas-gated). This is what makes a 'which writer can
+    integrate N kb in GENE' question real: a named writer family, the top site, cargo-capacity fit, delivery —
+    all engine-computed. Honest when the gene isn't in the atlas or the atlas isn't mounted; NEVER fabricates."""
+    try:
+        from pen_stack.planner.optimize import EditIntent
+        from pen_stack.planner.pipeline import plan_write
+    except Exception:  # noqa: BLE001
+        return {"available": False, "why": "planner unavailable in this environment"}
+    intent = _INTENT_TO_ENUM.get(design.get("edit_intent"), "safe_harbour_insertion")
+    try:
+        plans = plan_write(design["gene"], EditIntent(intent), int(design["cargo_bp"]),
+                           design.get("cell_type", "k562"), k=3)
+    except FileNotFoundError:
+        return {"available": False, "why": "writability atlas not mounted (planner runs on the live app only)"}
+    except Exception as e:  # noqa: BLE001 - never let a planner error break the chat dossier
+        return {"available": False, "why": f"planner error: {type(e).__name__}"}
+    if not plans:
+        return {"available": True, "found": False, "gene": design["gene"],
+                "why": (f"no writable plan for '{design['gene']}' — it is not in the writability atlas. Check it "
+                        "is an HGNC gene symbol or a known safe-harbour nickname (AAVS1, H11/HIPP11).")}
+    top = plans[0]
+    cargo = top.get("cargo") or {}
+    return {"available": True, "found": True, "n_plans": len(plans),
+            "recommended_writer": top.get("writer"), "site": top.get("site"),
+            "safety": top.get("safety"), "durability": top.get("durability"), "score": top.get("score"),
+            "writer_activity": top.get("writer_activity"), "reachability_tier": top.get("reachability_tier"),
+            "cargo_capacity_bp": cargo.get("cargo_capacity_bp"), "assembled_bp": cargo.get("assembled_bp"),
+            "cargo_fits_single_vector": cargo.get("size_ok"),
+            "delivery": (top.get("delivery") or {}).get("delivery"),
+            # distinct OTHER writer families (the top-k can repeat one family across sites — don't list it twice)
+            "alternative_writers": sorted({p.get("writer") for p in plans[1:]
+                                           if p.get("writer") and p.get("writer") != top.get("writer")})}
+
+
+def run_tools(message: str, history: list | None = None) -> dict[str, Any]:
+    """Run the validated engine over a plain-language message and return a grounded dossier. EVERY number here
+    is computed by the engine (verify / planner / scope) — no fabrication, no LLM."""
+    from pen_stack.agent.scope import match_scope
+    from pen_stack.verify import verify
+
+    design = parse_goal(message)
+    v = verify(dict(design), question=message)
+    imm = v.immune_profile or {}
+    axes = {k: {"value": a.get("value"), "uncertainty": a.get("uncertainty"),
+                "validation": a.get("validation"), "in_scope": a.get("in_scope"),
+                "meaning": axis_meaning(k, a.get("value"), a.get("validation"))}
+            for k, a in (imm.get("axes") or {}).items()}
+    oos = match_scope(message)                                # is the QUESTION out of scope (a known-unknown)?
+    return {
+        "parsed_design": design,
+        "plan": _run_planner(design),                         # the actual writer/site recommendation (atlas-gated)
+        "verdict": {"legal": v.legal, "confidence": v.confidence, "interval": v.interval,
+                    "epistemic_status": v.epistemic_status,
+                    "violations": [x.get("rule_id") for x in v.violations]},
+        "safety": {"decision": (v.safety.decision if v.safety else None),
+                   "reason": (v.safety.reason if v.safety else None)},
+        "immune_profile": {"axes": axes, "collapsed_score": imm.get("collapsed_score"),
+                           "known_unknowns": imm.get("known_unknowns")},
+        "scope": ({"out_of_scope": True, "id": oos["id"], "title": oos["title"], "why": oos.get("deferral")}
+                  if oos else {"out_of_scope": False}),
+        "disclaimer": "Decision-support only; not a clinical directive. Every number is tool-sourced.",
+    }
+
+
+_NUM_RE = re.compile(r"-?\d+(?:\.\d+)?")
+
+
+def extract_grounded_numbers(tool_results: dict) -> set[str]:
+    """The allow-list: every numeric string that appears in the engine's tool results. The grounding guard
+    permits the LLM to cite ONLY these; any other number it emits is stripped."""
+    import json
+    text = json.dumps(tool_results, default=str)
+    grounded = set(_NUM_RE.findall(text))
+    # also allow the common normalised forms (e.g. 0.5 / .5 / 50%) of each grounded value
+    extra = set()
+    for n in list(grounded):
+        try:
+            f = float(n)
+        except ValueError:
+            continue
+        extra.add(str(int(f)) if f.is_integer() else str(f))
+        extra.add(f"{f:.2f}")
+        if 0 <= f <= 1:
+            extra.add(str(round(f * 100)))                    # percent form of a [0,1] score
+    return grounded | extra

{pen_stack-6.4.1 → pen_stack-6.4.3}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.4.1
+Version: 6.4.3
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT
@@ -90,7 +90,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.4.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.4.3-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)

{pen_stack-6.4.1 → pen_stack-6.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pen-stack"
-version = "6.4.1"
+version = "6.4.3"
 description = "Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner."
 readme = "README.md"
 requires-python = ">=3.11"

pen_stack-6.4.1/pen_stack/web/tools.py

@@ -1,105 +0,0 @@
-"""Engine tool-runner for the grounded co-scientist (PEN-STACK v6.2, WS-CHAT support).
-
-The chat NEVER sources a number. This module is where the ENGINE computes everything: it parses a plain-language
-goal, runs the validated tools (verify -> legality + safety + calibrated confidence + immune profile; the scope
-matcher for known-unknowns), and returns a structured "dossier" of grounded facts. `extract_grounded_numbers`
-returns the allow-list of values the LLM is permitted to cite — anything else it emits is stripped by the
-grounding guard. No LLM is involved here; this is deterministic.
-"""
-from __future__ import annotations
-
-import re
-from typing import Any
-
-# tiny, transparent keyword maps (the engine grounds everything; this only routes a plain-language goal).
-_VEHICLES = {"aav": "AAV_single", "aav single": "AAV_single", "aav dual": "AAV_dual", "dual aav": "AAV_dual",
-             "lentivir": "lentivirus", "lnp": "lnp_mrna", "mrna": "lnp_mrna", "adenovir": "helper_dependent_adenovirus",
-             "hsv": "hsv_amplicon", "electroporat": "electroporation"}
-_INTENTS = {"safe harbour": "safe_harbour_insertion", "safe harbor": "safe_harbour_insertion",
-            "knock-in": "knock_in_with_disruption", "knock in": "knock_in_with_disruption",
-            "knockin": "knock_in_with_disruption", "durab": "high_durability_insertion",
-            "excis": "regulatory_element_excision", "regulator": "regulatory_element_excision",
-            "landing pad": "landing_pad_insertion", "repeat": "repeat_excision"}
-_CELLS = {"liver": "hepg2", "hepato": "hepg2", "hepg2": "hepg2", "hspc": "hspc", "stem cell": "h1_hesc",
-          "ipsc": "ipsc", "k562": "k562", "t cell": "cd8_t", "t-cell": "cd8_t", "car-t": "cd8_t", "pbmc": "pbmc"}
-_GENE_RE = re.compile(r"\b([A-Z][A-Z0-9]{1,7})\b")             # crude gene-symbol token (AAVS1, TRAC, FIX, ...)
-_KB_RE = re.compile(r"(\d+(?:\.\d+)?)\s*kb", re.I)
-_BP_RE = re.compile(r"(\d{3,6})\s*bp", re.I)
-
-
-def _first(text: str, table: dict, default):
-    low = text.lower()
-    for key, val in table.items():
-        if key in low:
-            return val
-    return default
-
-
-def parse_goal(message: str) -> dict:
-    """Best-effort parse of a plain-language goal into a Design/Goal dict. The engine grounds everything; this
-    just picks a starting point (with sensible defaults) so the tools can run."""
-    cargo = 3000
-    if (m := _KB_RE.search(message)):
-        cargo = int(float(m.group(1)) * 1000)
-    elif (m := _BP_RE.search(message)):
-        cargo = int(m.group(1))
-    genes = [g for g in _GENE_RE.findall(message) if g not in {"DNA", "RNA", "AAV", "LNP", "HSV", "CAR"}]
-    gene = genes[0] if genes else "AAVS1"
-    return {"write_type": "insertion", "gene": gene, "chrom": "chr19",
-            "edit_intent": _first(message, _INTENTS, "safe_harbour_insertion"),
-            "delivery_vehicle": _first(message, _VEHICLES, "AAV_single"), "cargo_bp": cargo,
-            "cell_type": _first(message, _CELLS, "k562"),
-            # the user's plain-language goal IS the cargo-function description the Guardian must screen — so a
-            # message like "express a ricin toxin" is biosecurity-screened, not silently passed as benign.
-            "cargo_function": message.strip()}
-
-
-def run_tools(message: str, history: list | None = None) -> dict[str, Any]:
-    """Run the validated engine over a plain-language message and return a grounded dossier. EVERY number here
-    is computed by the engine (verify / scope) — no fabrication, no LLM."""
-    from pen_stack.agent.scope import match_scope
-    from pen_stack.verify import verify
-
-    design = parse_goal(message)
-    v = verify(dict(design), question=message)
-    imm = v.immune_profile or {}
-    axes = {k: {"value": a.get("value"), "uncertainty": a.get("uncertainty"),
-                "validation": a.get("validation"), "in_scope": a.get("in_scope")}
-            for k, a in (imm.get("axes") or {}).items()}
-    oos = match_scope(message)                                # is the QUESTION out of scope (a known-unknown)?
-    return {
-        "parsed_design": design,
-        "verdict": {"legal": v.legal, "confidence": v.confidence, "interval": v.interval,
-                    "epistemic_status": v.epistemic_status,
-                    "violations": [x.get("rule_id") for x in v.violations]},
-        "safety": {"decision": (v.safety.decision if v.safety else None),
-                   "reason": (v.safety.reason if v.safety else None)},
-        "immune_profile": {"axes": axes, "collapsed_score": imm.get("collapsed_score"),
-                           "known_unknowns": imm.get("known_unknowns")},
-        "scope": ({"out_of_scope": True, "id": oos["id"], "title": oos["title"], "why": oos.get("deferral")}
-                  if oos else {"out_of_scope": False}),
-        "disclaimer": "Decision-support only; not a clinical directive. Every number is tool-sourced.",
-    }
-
-
-_NUM_RE = re.compile(r"-?\d+(?:\.\d+)?")
-
-
-def extract_grounded_numbers(tool_results: dict) -> set[str]:
-    """The allow-list: every numeric string that appears in the engine's tool results. The grounding guard
-    permits the LLM to cite ONLY these; any other number it emits is stripped."""
-    import json
-    text = json.dumps(tool_results, default=str)
-    grounded = set(_NUM_RE.findall(text))
-    # also allow the common normalised forms (e.g. 0.5 / .5 / 50%) of each grounded value
-    extra = set()
-    for n in list(grounded):
-        try:
-            f = float(n)
-        except ValueError:
-            continue
-        extra.add(str(int(f)) if f.is_integer() else str(f))
-        extra.add(f"{f:.2f}")
-        if 0 <= f <= 1:
-            extra.add(str(round(f * 100)))                    # percent form of a [0,1] score
-    return grounded | extra