pen-stack 6.13.0__tar.gz → 6.14.0__tar.gz

{pen_stack-6.13.0 → pen_stack-6.14.0}/CHANGELOG.md

@@ -3,6 +3,40 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [6.14.0] - 2026-06-22 - WriteSpec: a typed, ontology-backed intent layer with a grounded extractor and a feasibility check
+
+Replaces the keyword parser with a typed, machine-checkable genome-writing request (an SBOL3 profile), a grounded
+prose-to-spec extractor that labels every inference and never fabricates intent, and a feasibility check. This is
+the agentic front-end: one contract the whole stack consumes. A WriteSpec is a request, not a claim.
+
+### Added
+- **The WriteRequest type** (`pen_stack/spec/writespec.py`, `schemas/writespec.json`). A typed model carrying the
+  write semantics (write-type, cargo with Sequence-Ontology roles, target gene/locus/att-site/phenotype, cell
+  type, constraints) plus a per-field provenance map (explicit / inferred / user / unresolved). Lossless JSON
+  round-trip; SBOL3 round-trip via the real `sbol3` library (the `[spec]` extra; native Components + SO roles for
+  interoperability); GenBank export for a cargo with a sequence; and `to_legacy_design`, the adapter that lets
+  every existing stage consume a WriteRequest without a rewrite.
+- **Vocabulary resolvers** (`pen_stack/spec/resolvers/`). Free text to canonical id: HGNC genes (atlas-grounded),
+  Cellosaurus / Cell Ontology cell types, Sequence Ontology feature roles, MONDO phenotypes, ChEBI molecules,
+  GRCh38 coordinates. Every curated id was verified against the live ontology services before commit; an
+  unresolved term stays null, never invented.
+- **Grounded extractor + clarifying-question planner** (`pen_stack/spec/extract.py`, `clarify.py`). A
+  deterministic backbone (so the benchmark is reproducible) that labels every inferred field, asks a clarifying
+  question for anything underspecified or ambiguous, and keeps unresolved terms null.
+- **Feasibility check** (`pen_stack/spec/satisfy.py`). Wraps reachability (the atlas), deliverability (the
+  delivery recommender), and legality (the verification proof object) into feasible / infeasible plus named
+  blocking constraints and repair hints; feasibility is necessary, not sufficient (not efficacy).
+- **WriteSpec-Bench** (`benchmarks/writespec/`). The first prose-to-write-spec corpus, grounded in real
+  experiments, with an ambiguity subset and a sealed held-out. Reported verbatim: sealed-test structural fidelity
+  1.0 and value accuracy 0.96 versus a 0.46 keyword-dict baseline; inferred-field labelling recall 1.0.
+- **Surfaces**: REST `POST /api/writespec`, MCP `writespec_parse`, the manifest tool, the web "Describe a Write"
+  builder page, and `docs/writespec_profile.md` + `docs/writespec_bench.md`.
+
+### Notes
+- Feasibility rules out unreachable / undeliverable / illegal, not whether the write will work.
+- The extractor backbone is deterministic; an LLM pass is optional and adds no ground truth (it may only propose
+  values that still pass the resolvers).
+
 ## [6.13.0] - 2026-06-22 - Oracle mesh: binding-affinity dimension, per-oracle reliability, disagreement-to-uncertainty
 
 Hardens the foundation-model oracle mesh under one result contract. Adds a binding-affinity dimension

{pen_stack-6.13.0 → pen_stack-6.14.0}/CITATION.cff

@@ -1,7 +1,7 @@
 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.13.0
+version: 6.14.0
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.13.0 → pen_stack-6.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.13.0
+Version: 6.14.0
 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
@@ -67,6 +67,8 @@ Requires-Dist: mkdocs>=1.6; extra == "docs"
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
 Provides-Extra: env
 Requires-Dist: gymnasium>=0.29; extra == "env"
+Provides-Extra: spec
+Requires-Dist: sbol3>=1.1; extra == "spec"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"

pen_stack-6.14.0/benchmarks/writespec/SHA256SUMS

@@ -0,0 +1,4 @@
+5bbfd8b7d73c0828a72d84d68b12155f7047e45d0d227e8c9654cc15687991f5  benchmarks/writespec/corpus.json
+d3133084f098a6eeed46ab49555731057c9b106c787f090331df6b019cd249f2  benchmarks/writespec/harness.py
+bc6126634628e92baedf68404636889f07c77c53d59ca057b18b7f54511a11fe  benchmarks/writespec/writespec_bench_metrics.json
+051ddbaccca5faab72d66f2737e634b5b7170aa919323aab73f98e53fd042b36  benchmarks/writespec/splits.json

{pen_stack-6.13.0 → pen_stack-6.14.0}/docs/offtarget.md

@@ -20,8 +20,10 @@ A nominated off-target is a candidate, and every result ships with the empirical
   controls) found that with a **cell-type-matched** track (ENCODE HEK293T DNase, v6.10.3) accessibility predicts
   WT-Cas9 cell-based off-target activity: **GUIDE-seq AUROC 0.58 (cross-cell K562) → 0.671 (matched), CI
   [0.642, 0.701]**, in-vitro control null. **VALIDATED (moderate, cell-type-matched)**; it is surfaced as an
-  annotation and does **not yet change the numeric risk score** (sequence/CRISOT dominates; TTISS, a Cas9-variant
-  assay, is the expected outlier). Full result: `benchmarks/offtarget/chromatin_validation.json`.
+  annotation and is **intentionally not folded into the numeric risk score** (the v6.10.4 incremental analysis
+  found no held-out ranking improvement over CRISOT, so the score stays sequence/CRISOT-driven; TTISS, a
+  Cas9-variant assay, is the expected outlier). Full results:
+  `benchmarks/offtarget/chromatin_{validation,incremental}.json`.
 - **Serine integrase (Bxb1):** a cryptic **pseudo-attB** scan that seeds on the *real documented* Bxb1 attB core
   (`GCGGTCTC`, central GT; FlyBase FBto0000359, Ghosh 2003) and reports candidate cryptic sites by arm mismatches.
 - **Bridge recombinase:** delegates to the existing Perry-DMS pseudosite engine (`pen_stack.bridge.offtarget`).

pen_stack-6.14.0/docs/writespec_bench.md

@@ -0,0 +1,44 @@
+# WriteSpec-Bench (Stage A)
+
+WriteSpec-Bench is the first prose-to-write-spec benchmark for genome writing: paired
+`(plain-language request -> gold WriteSpec)`, grounded in real, well-documented genome-writing experiments
+(cited per row). It is `benchmarks/writespec/` (corpus, splits, harness, metrics).
+
+## Construction
+
+- Each gold WriteSpec is the structured value a careful curator extracts: write-type, target kind, the gene
+  (HGNC) or phenotype (MONDO) id, the cell (Cellosaurus / Cell Ontology) id, the cargo Sequence-Ontology role
+  set, and the key constraints. Every ontology id was verified against the live services before commit.
+- The **standard** subset is fully specified. The **ambiguity** subset is deliberately underspecified or
+  ambiguous, to test that the extractor surfaces assumptions and asks clarifying questions rather than guessing.
+- **Leakage control**: the test split is sealed and disjoint from train (`splits.json`); paraphrases do not
+  co-occur across splits.
+
+## Scoring (SO-Bench-style)
+
+- **schema adherence**: the output validates as a typed `WriteRequest`.
+- **structural fidelity**: write_type and target_kind match the gold.
+- **value accuracy**: canonical-id match for gene / phenotype / cell, the cargo role set, and the listed
+  constraints.
+- **grounding**: on the ambiguity subset, clarifying questions fire and the inferred write_type is labelled;
+  inferred-field labelling recall must be 100% (no field is set without provenance).
+
+The baseline is the legacy keyword dictionary (`web.tools.parse_goal`), which emits raw tokens, not canonical
+ids.
+
+## Results (reported verbatim, deterministic extractor, not tuned to the sealed test)
+
+- Sealed test: schema adherence 1.0, structural fidelity 1.0, value accuracy 0.964; baseline value accuracy
+  0.464.
+- Train: structural fidelity 1.0, value accuracy 0.988; baseline 0.407.
+- Ambiguity subset: clarifying questions fire, inferred write_type labelled.
+- Inferred-field labelling recall: 1.0.
+
+The extractor beats the keyword-dict baseline because it resolves terms to verified ontology ids; the baseline
+keeps raw tokens. The corpus is small and curated, grounded in real experiments; its value is bounded by curation
+quality, reported verbatim. Two structural mismatches found during development were genuine extractor bugs (a
+cell-line token mis-read as a gene; a disease prioritized over a named gene target), fixed in the extractor, not
+papered over in the gold.
+
+The full per-run metrics are in `benchmarks/writespec/writespec_bench_metrics.json`; re-run with
+`python -m benchmarks.writespec.harness`.

pen_stack-6.14.0/docs/writespec_profile.md

@@ -0,0 +1,58 @@
+# The WriteSpec profile (Stage A)
+
+WriteSpec is a typed, ontology-backed, machine-checkable representation of a genome-writing request. It replaces
+the keyword parser with one contract every downstream stage consumes, and it is an SBOL3 profile, so it is
+interoperable with the genetic-design-automation ecosystem and GenBank from day one. A WriteSpec is a request,
+not a claim.
+
+## The type
+
+`WriteRequest` (`pen_stack/spec/writespec.py`) carries:
+
+- **write_type**: one of insertion, excision, inversion, replacement, regulatory_rewrite, landing_pad_install,
+  multiplex.
+- **cargo**: a list of components, each with a Sequence-Ontology role (promoter `SO:0000167`, CDS `SO:0000316`,
+  polyA signal `SO:0000551`, insulator `SO:0000627`, ...) and an optional sequence and length.
+- **target**: the edit site, as a gene (HGNC), a locus (GRCh38 coordinate), an att/landing site, or, when only a
+  disease goal is given, a phenotype (MONDO). A named gene or att site is the target; a disease is attached as the
+  goal.
+- **cell_type**: a Cellosaurus cell line (HEK293T `CVCL_0063`) or a Cell-Ontology cell type (T cell `CL:0000084`),
+  carrying the irreducible subline / karyotype-drift caveat.
+- **constraints**: efficiency floor, scarless, safety-switch-required, copy number, germline guardrail, max cargo
+  bp, delivery limit / vehicle, and a ChEBI small-molecule inducer.
+
+## The grounding discipline
+
+Every field records its provenance in the `provenance` map: `explicit` (stated in the prose), `inferred`
+(defaulted, with the rationale in `assumptions`), `user` (supplied through a structured override), or
+`unresolved`. A required field that is unspecified or ambiguous yields a `clarifications` question rather than a
+guess. A term that cannot be resolved is listed in `unresolved` and its field stays null. Nothing is invented.
+
+All curated ontology ids were verified against the live services (Cellosaurus, EBI OLS for SO / MONDO / CL /
+ChEBI) before they were committed; a resolver degrades to `unresolved`, never a fabricated id.
+
+## Round-trips and the downstream adapter
+
+- **JSON**: always available (`to_json` / `from_json`), lossless.
+- **SBOL3**: `to_sbol3` / `from_sbol3` via the real `sbol3` library (the `[spec]` extra). The export emits native
+  Components with Sequence-Ontology roles for interoperability and carries the full typed spec losslessly in a
+  PROV-O-namespaced annotation.
+- **GenBank**: `to_genbank` exports the cargo as a GenBank record when it carries a DNA sequence (intent-only
+  specs return None).
+- **`to_legacy_design`**: the adapter that emits the dict the existing stages (verify / plan / safety / delivery)
+  already consume, so the whole stack reads one contract without a per-stage rewrite.
+
+## Feasibility
+
+`pen_stack/spec/satisfy.py` tests the necessary conditions a write must meet by wrapping the existing stages:
+reachability (the writable-genome atlas), deliverability (the Stage D recommender), and legality (the Stage F
+rule set, via the repair-oriented proof object). It returns feasible or infeasible plus the named blocking
+constraint(s) and repair hints, so an agent can repair the spec and re-check. Feasibility is necessary, not
+sufficient: it rules out unreachable / undeliverable / illegal, not whether the write will work (that is the
+downstream stages' calibrated prediction).
+
+## Surfaces
+
+- REST `POST /api/writespec` (body `{prose, overrides?, check_feasibility?}`).
+- MCP `writespec_parse`.
+- The web "Describe a Write" builder page.

{pen_stack-6.13.0 → pen_stack-6.14.0}/pen_stack/__init__.py

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

{pen_stack-6.13.0 → pen_stack-6.14.0}/pen_stack/agent/mcp_server.py

@@ -60,6 +60,18 @@ def verify_proof(design: dict) -> dict:
     return _vp(design).model_dump()
 
 
+@mcp.tool()
+def writespec_parse(prose: str, check_feasibility: bool = True) -> dict:
+    """v6.14 Stage A: parse a plain-language genome-writing request into a typed, ontology-backed WriteSpec (an
+    SBOL3 profile). Returns the typed spec with per-field provenance (explicit / inferred / user / unresolved),
+    the assumptions behind every inferred field, clarifying questions for anything underspecified or ambiguous,
+    the unresolved terms (kept null, never invented), the downstream design adapter, and a feasibility verdict
+    (reachability + deliverability + legality, with named blocking constraints + repair hints). A WriteSpec is a
+    REQUEST, not a claim; the extractor never fabricates intent."""
+    from pen_stack.spec.service import parse_request
+    return parse_request(prose, check_feasibility=check_feasibility)
+
+
 @mcp.tool()
 def oracle_query(oracle: str | None = None, protein_seq: str | None = None, ligand_smiles: str | None = None,
                  pair_type: str = "ligand", ligand_name: str | None = None) -> dict:

{pen_stack-6.13.0 → pen_stack-6.14.0}/pen_stack/api/manifest.py

@@ -67,6 +67,12 @@ _TOOLS = [
      "NOT an in-vivo tropism claim (v6.11 PEN-DELIVER)",
      "input": "AAV VP1 capsid amino-acid sequence", "output": "predicted packaging-fitness (candidate) or abstain",
      "entrypoint": "pen_stack.planner.delivery_predict.capsid_fitness", "fabricates": False},
+    {"name": "writespec_parse", "summary": "parse a plain-language genome-writing request into a typed, "
+     "ontology-backed WriteSpec (an SBOL3 profile): per-field provenance (explicit/inferred/user/unresolved), "
+     "assumptions, clarifying questions on underspecification, and a feasibility verdict (reachability + "
+     "deliverability + legality); a REQUEST not a claim, never fabricates intent (v6.14 Stage A WriteSpec)",
+     "input": "prose request (+ optional structured overrides)", "output": "typed WriteSpec + clarifications + "
+     "feasibility; unresolved stays null", "entrypoint": "pen_stack.spec.service.parse_request", "fabricates": False},
     {"name": "oracle_query", "summary": "query the oracle mesh under one contract: per-oracle execution + latency "
      "+ live status + PUBLISHED reliability (verbatim from public benchmarks, cited) + disagreement-to-interval; "
      "or a CANDIDATE protein-ligand binding affinity (Boltz-2 head) with native uncertainty, cache-or-abstain "

{pen_stack-6.13.0 → pen_stack-6.14.0}/pen_stack/server/api.py

@@ -238,6 +238,18 @@ def offtarget_assay_endpoint(writer_family: str):
     return recommend_assay(writer_family)
 
 
+@app.post("/writespec", tags=["v6.14 writespec"])
+def writespec_endpoint(req: dict):
+    """v6.14 Stage A: parse a plain-language genome-writing request into a typed, ontology-backed WriteSpec.
+    Body: {prose, overrides?, check_feasibility?}. Returns the typed spec (with per-field provenance), the
+    assumptions behind every inferred field, clarifying questions for anything underspecified, the unresolved
+    terms (kept null, never invented), the downstream design adapter, and the feasibility verdict. A WriteSpec is
+    a REQUEST, not a claim; the extractor never fabricates intent."""
+    from pen_stack.spec.service import parse_request
+    return parse_request(req.get("prose", ""), overrides=req.get("overrides"),
+                         check_feasibility=bool(req.get("check_feasibility", True)))
+
+
 @app.post("/oracle/affinity", tags=["v6.13 oracle"])
 def oracle_affinity_endpoint(req: dict):
     """v6.13 PEN-ORACLE protein-ligand binding-affinity (Boltz-2 head) under the oracle contract. Body:

pen_stack-6.14.0/pen_stack/spec/__init__.py

@@ -0,0 +1,18 @@
+"""The WriteSpec intent layer (v6.14, Stage A).
+
+A typed, ontology-backed, machine-checkable representation of a genome-writing request (``WriteRequest``, an
+SBOL3 profile), a grounded prose-to-spec extractor that labels every inference and never fabricates intent, and a
+feasibility (satisfiability) check. This is the agentic front-end: one contract every downstream stage consumes.
+"""
+from __future__ import annotations
+
+from pen_stack.spec.writespec import (
+    CargoComponent,
+    Constraints,
+    Resolved,
+    Target,
+    WriteRequest,
+    WRITE_TYPES,
+)
+
+__all__ = ["WriteRequest", "CargoComponent", "Target", "Constraints", "Resolved", "WRITE_TYPES"]

pen_stack-6.14.0/pen_stack/spec/clarify.py

@@ -0,0 +1,42 @@
+"""Clarifying-question planner (v6.14, Stage A, A-WS3).
+
+Given a :class:`WriteRequest`, return the minimal set of questions needed to make it actionable: the required
+fields that are unspecified or ambiguous. The extractor already populates ``clarifications`` during parsing;
+this module is the standalone planner an agent calls to decide whether to ask before composing a write, and to
+get a clean, de-duplicated question list. It never guesses a value: a missing required field becomes a question.
+"""
+from __future__ import annotations
+
+from pen_stack.spec.writespec import WriteRequest
+
+# fields that must be present for a write to be composable (by write-type)
+_REQUIRED_TARGET = {"insertion", "excision", "inversion", "replacement", "regulatory_rewrite",
+                    "landing_pad_install", "multiplex"}
+
+
+def clarifying_questions(spec: WriteRequest) -> list[str]:
+    """The minimal de-duplicated question list for the underspecified / ambiguous required fields."""
+    qs: list[str] = list(spec.clarifications)  # carry the extractor's questions
+    if spec.write_type in _REQUIRED_TARGET and spec.target.kind == "unspecified":
+        q = "Which gene, locus, att/landing site, or disease phenotype should the write target?"
+        if q not in qs:
+            qs.append(q)
+    # an insertion with no cargo at all is underspecified
+    if spec.write_type == "insertion" and not spec.cargo:
+        qs.append("What cargo should be inserted (size in bp/kb, and any features such as promoter / CDS / polyA)?")
+    # an unresolved term needs disambiguation, not a guess
+    for term in spec.unresolved:
+        qs.append(f"The term '{term}' could not be resolved to a gene / locus / cell / phenotype; please clarify it.")
+    # de-duplicate, preserve order
+    seen: set[str] = set()
+    out: list[str] = []
+    for q in qs:
+        if q not in seen:
+            seen.add(q)
+            out.append(q)
+    return out
+
+
+def is_actionable(spec: WriteRequest) -> bool:
+    """True when no clarifying question remains (the spec is complete enough to compose a write)."""
+    return not clarifying_questions(spec)

pen_stack-6.14.0/pen_stack/spec/extract.py

@@ -0,0 +1,232 @@
+"""Grounded prose-to-WriteSpec extractor (v6.14, Stage A, A-WS3).
+
+Maps a plain-language genome-writing request to a typed :class:`WriteRequest`. The backbone is DETERMINISTIC (so
+the benchmark is reproducible and CI-safe); an LLM pass is optional and never required. Three grounding
+safeguards are mandatory and encoded here:
+
+  1. assumption surfacing  - every field not explicit in the prose is recorded in ``provenance`` as ``inferred``
+     with the rationale in ``assumptions`` (never a silent default);
+  2. clarifying questions   - a required field that is unspecified or ambiguous yields a ``clarifications``
+     question rather than a guess;
+  3. no fabrication         - a term that cannot be resolved is listed in ``unresolved`` and its field stays null.
+"""
+from __future__ import annotations
+
+import re
+
+from pen_stack.spec.resolvers import (
+    resolve_cell,
+    resolve_chem,
+    resolve_feature,
+    resolve_gene,
+    resolve_locus,
+    resolve_phenotype,
+)
+from pen_stack.spec.resolvers.phenotype import _PHENO
+from pen_stack.spec.writespec import (
+    CargoComponent,
+    Constraints,
+    Target,
+    WriteRequest,
+)
+
+_GENE_RE = re.compile(r"\b([A-Z][A-Z0-9]{1,7})\b")
+_WRITE_TYPE_KW = [
+    ("excision", ["excise", "delete", "knock out", "knockout", "remove ", "disrupt"]),
+    ("inversion", ["invert", "inversion", "flip "]),
+    ("replacement", ["replace", "correct the", "correct a", "swap", "base edit", "prime edit", "repair the"]),
+    ("regulatory_rewrite", ["regulatory", "promoter swap", "rewrite the promoter", "tune expression", "upregulate", "knock down"]),
+    ("landing_pad_install", ["landing pad", "landing-pad", "install an att", "install a landing", "attp", "bxb1 site"]),
+    ("multiplex", ["multiplex", "multiple loci", "simultaneously edit"]),
+    ("insertion", ["insert", "integrate", "knock in", "knock-in", "knockin", "add a", "deliver a transgene", "place a"]),
+]
+_ROLE_KW = {"promoter": "promoter", "cds": "CDS", "coding": "CDS", "transgene": "CDS", "gfp": "CDS",
+            "polya": "polyA", "poly-a": "polyA", "insulator": "insulator", "enhancer": "enhancer",
+            "terminator": "terminator", "ires": "IRES"}
+
+
+def _detect_write_type(low: str) -> tuple[str, bool]:
+    for wt, kws in _WRITE_TYPE_KW:
+        if any(k in low for k in kws):
+            return wt, True
+    return "insertion", False  # default, labelled inferred by the caller
+
+
+def _gene_tokens(prose: str) -> list[str]:
+    """Gene-symbol tokens, excluding jargon and any token that resolves as a cell line / type (e.g. HEK293T)."""
+    from pen_stack.spec.resolvers.cell import _CELLS
+    from pen_stack.spec.resolvers.gene import _STOP
+    cell_keys = {k.upper() for k in _CELLS}
+    return [g for g in _GENE_RE.findall(prose) if g not in _STOP and g.upper() not in cell_keys]
+
+
+def _detect_bp(low: str) -> int | None:
+    m = re.search(r"(\d+(?:\.\d+)?)\s*kb", low)
+    if m:
+        return int(float(m.group(1)) * 1000)
+    m = re.search(r"(\d{2,6})\s*(?:bp|base pairs)", low)
+    if m:
+        return int(m.group(1))
+    return None
+
+
+def _detect_phenotype(prose: str):
+    low = prose.lower()
+    for phrase in sorted(_PHENO, key=len, reverse=True):
+        if phrase in low:
+            return resolve_phenotype(phrase)
+    return None
+
+
+def _detect_cell(prose: str):
+    from pen_stack.spec.resolvers.cell import _CELLS
+    low = prose.lower()
+    for phrase in sorted(_CELLS, key=len, reverse=True):
+        if phrase in low:
+            return resolve_cell(phrase)
+    return None
+
+
+def _detect_inducer(prose: str):
+    from pen_stack.spec.resolvers.chem import _CHEM
+    low = prose.lower()
+    for phrase in sorted(_CHEM, key=len, reverse=True):
+        if phrase in low:
+            return resolve_chem(phrase)
+    return None
+
+
+def extract_writespec(prose: str, *, overrides: dict | None = None, allow_llm: bool = False) -> WriteRequest:
+    """Extract a typed WriteRequest from prose, deterministically, with grounding safeguards.
+
+    ``overrides`` lets a caller (or the web builder) supply a field directly; those are marked provenance ``user``.
+    ``allow_llm`` is accepted for surface parity but the deterministic backbone is what runs and is benchmarked;
+    an LLM pass, when wired, may only PROPOSE values that still pass the resolvers (it can never set an
+    unresolved id).
+    """
+    prose = prose or ""
+    low = prose.lower()
+    prov: dict[str, str] = {}
+    assumptions: list[str] = []
+    unresolved: list[str] = []
+    clarifications: list[str] = []
+    overrides = overrides or {}
+
+    # --- write type ---
+    if "write_type" in overrides:
+        wt = overrides["write_type"]
+        prov["write_type"] = "user"
+    else:
+        wt, explicit = _detect_write_type(low)
+        prov["write_type"] = "explicit" if explicit else "inferred"
+        if not explicit:
+            assumptions.append("write_type inferred as 'insertion' (no explicit write verb; the default for a "
+                               "cargo-placement request)")
+
+    # --- target: a named gene/locus or att site is the EDIT SITE (target_kind); a disease is the GOAL ---
+    target = Target()
+    pheno = _detect_phenotype(prose)
+    gene_toks = _gene_tokens(prose)
+    att = None
+    for k in ("attb", "attp", "landing pad", "landing-pad", "landing site"):
+        if k in low:
+            att = k.replace(" ", "_").replace("-", "_")
+            break
+    gene_resolved = None
+    if gene_toks:
+        g = resolve_gene(gene_toks[0])
+        if g.resolved:
+            gene_resolved = g
+        else:
+            unresolved.append(gene_toks[0])
+    if gene_resolved is not None:
+        loc = resolve_locus(gene_toks[0])
+        target = Target(kind="gene", gene=gene_resolved, locus=loc if loc.resolved else None)
+        prov["target.gene"] = "explicit"
+        if pheno is not None and pheno.resolved:  # the disease is the goal, attached to the gene target
+            target.phenotype = pheno
+            prov["target.phenotype"] = "explicit"
+    elif att:
+        target = Target(kind="att_site", att_site=att)
+        prov["target.att_site"] = "explicit"
+        if pheno is not None and pheno.resolved:
+            target.phenotype = pheno
+            prov["target.phenotype"] = "explicit"
+    elif pheno is not None and pheno.resolved:
+        target = Target(kind="phenotype", phenotype=pheno)
+        prov["target.phenotype"] = "explicit"
+    if target.kind == "unspecified":
+        clarifications.append("Which gene, locus, att/landing site, or disease phenotype should the write target?")
+
+    # --- cell type (optional but recommended) ---
+    cell = None
+    ct = _detect_cell(prose)
+    if ct is not None and ct.resolved:
+        cell = ct
+        prov["cell_type"] = "explicit"
+    elif ct is not None and ct.candidates:
+        cell = ct
+        prov["cell_type"] = "explicit"
+        clarifications.append(f"Cell term '{ct.text}' is ambiguous: did you mean "
+                              f"{', '.join(c['label'] for c in ct.candidates)}?")
+    else:
+        clarifications.append("Which cell type or cell line is the target (e.g. HEK293T, primary T cells, HSPCs)?")
+
+    # --- cargo (size + feature roles) ---
+    cargo: list[CargoComponent] = []
+    bp = _detect_bp(low)
+    seen_roles: set[str] = set()
+    for kw, label in _ROLE_KW.items():
+        if kw in low and label not in seen_roles:
+            seen_roles.add(label)
+            role = resolve_feature(label)
+            cargo.append(CargoComponent(name=kw, role=role if role.resolved else None))
+            prov[f"cargo[{len(cargo) - 1}].role"] = "explicit"
+    if bp is not None and cargo:
+        cargo[0].length_bp = bp
+    elif bp is not None:
+        cargo.append(CargoComponent(name="cargo", length_bp=bp))
+
+    # --- constraints ---
+    cons = Constraints()
+    if "scarless" in low or "seamless" in low:
+        cons.scarless = True
+        prov["constraints.scarless"] = "explicit"
+    if "safety switch" in low or "kill switch" in low or "icasp9" in low or "suicide gene" in low:
+        cons.safety_switch_required = True
+        prov["constraints.safety_switch_required"] = "explicit"
+    # named delivery vehicle (so the legality / capacity check can run) - most specific first
+    _VEH = [("dual aav", "AAV_dual"), ("aav", "AAV_single"), ("lentivir", "lentivirus"), ("lnp", "LNP"),
+            ("electroporat", "electroporation"), ("rnp", "electroporation"), ("adenovir", "adenovirus")]
+    for kw, veh in _VEH:
+        if kw in low:
+            cons.delivery_limit = veh
+            prov["constraints.delivery_limit"] = "explicit"
+            break
+    if cons.delivery_limit is None and ("non-integrating" in low or "nonintegrating" in low
+                                        or "episomal" in low or "transient" in low):
+        cons.delivery_limit = "non_integrating"
+        prov["constraints.delivery_limit"] = "explicit"
+    if "germline" in low or "embryo" in low or "heritable" in low:
+        cons.germline = True
+        prov["constraints.germline"] = "explicit"
+    m = re.search(r"(?:at least|>=|over|above)\s*(\d{1,3})\s*%\s*(?:efficien|edit|integrat)", low)
+    if m:
+        cons.efficiency_floor = float(m.group(1)) / 100.0
+        prov["constraints.efficiency_floor"] = "explicit"
+    inducer = _detect_inducer(prose)
+    if inducer is not None and inducer.resolved:
+        cons.inducer = inducer
+        prov["constraints.inducer"] = "explicit"
+    if bp is not None:
+        cons.max_cargo_bp = bp
+        prov["constraints.max_cargo_bp"] = "explicit"
+
+    # apply structured overrides (provenance=user) last
+    for k, v in overrides.items():
+        if k != "write_type":
+            prov[k] = "user"
+
+    return WriteRequest(write_type=wt, cargo=cargo, target=target, cell_type=cell, constraints=cons,
+                        provenance=prov, assumptions=assumptions, clarifications=clarifications,
+                        unresolved=unresolved, free_text_note=prose.strip() or None)

pen_stack-6.14.0/pen_stack/spec/resolvers/__init__.py

@@ -0,0 +1,17 @@
+"""Vocabulary resolvers (v6.14, Stage A, A-WS2): free text -> canonical ontology id.
+
+Each resolver returns a :class:`pen_stack.spec.writespec.Resolved` with a canonical id + confidence + (when
+ambiguous) a ranked candidate set, or a result with ``id=None`` for an unresolved term. Unresolved stays null:
+a resolver never invents an id. All curated ids were verified against the live ontology services (Cellosaurus,
+EBI OLS for SO / MONDO / CL / ChEBI) before they were committed.
+"""
+from __future__ import annotations
+
+from pen_stack.spec.resolvers.cell import resolve_cell
+from pen_stack.spec.resolvers.chem import resolve_chem
+from pen_stack.spec.resolvers.feature import resolve_feature
+from pen_stack.spec.resolvers.gene import resolve_gene
+from pen_stack.spec.resolvers.locus import resolve_locus
+from pen_stack.spec.resolvers.phenotype import resolve_phenotype
+
+__all__ = ["resolve_gene", "resolve_cell", "resolve_feature", "resolve_phenotype", "resolve_chem", "resolve_locus"]

pen_stack-6.14.0/pen_stack/spec/resolvers/cell.py

@@ -0,0 +1,51 @@
+"""Cell-line / cell-type resolver (A-WS2): free text -> Cellosaurus (cell lines) or Cell Ontology (cell types).
+
+Curated offline cache (ids verified against the Cellosaurus API and EBI OLS). Cell lines carry the irreducible
+subline / karyotype-drift caveat as a note. An unrecognized term stays unresolved (id=None), never invented.
+"""
+from __future__ import annotations
+
+from pen_stack.spec.writespec import Resolved
+
+# (id, canonical label, ontology) - all ids verified live before commit
+_CELLS: dict[str, tuple[str, str, str]] = {
+    # cell lines (Cellosaurus)
+    "hek293t": ("CVCL_0063", "HEK293T", "Cellosaurus"), "293t": ("CVCL_0063", "HEK293T", "Cellosaurus"),
+    "k562": ("CVCL_0004", "K-562", "Cellosaurus"), "k-562": ("CVCL_0004", "K-562", "Cellosaurus"),
+    "hepg2": ("CVCL_0027", "Hep-G2", "Cellosaurus"), "hep-g2": ("CVCL_0027", "Hep-G2", "Cellosaurus"),
+    "jurkat": ("CVCL_0065", "Jurkat", "Cellosaurus"),
+    "hela": ("CVCL_0030", "HeLa", "Cellosaurus"),
+    # cell types (Cell Ontology)
+    "t cell": ("CL:0000084", "T cell", "CL"), "t-cell": ("CL:0000084", "T cell", "CL"),
+    "cd8 t cell": ("CL:0000084", "T cell", "CL"), "car-t": ("CL:0000084", "T cell", "CL"),
+    "primary t cell": ("CL:0000084", "T cell", "CL"),
+    "hspc": ("CL:0000037", "hematopoietic stem cell", "CL"), "hsc": ("CL:0000037", "hematopoietic stem cell", "CL"),
+    "cd34+": ("CL:0000037", "hematopoietic stem cell", "CL"), "cd34": ("CL:0000037", "hematopoietic stem cell", "CL"),
+    "neuron": ("CL:0000540", "neuron", "CL"),
+}
+_LINE_CAVEAT = ("cell-line identity carries irreducible subline / karyotype drift (e.g. HEK293T); the canonical "
+                "id does not resolve that away")
+
+
+def resolve_cell(text: str) -> Resolved:
+    """Resolve a cell line / type to Cellosaurus or Cell Ontology; unrecognized stays null."""
+    if not text:
+        return Resolved(text=text, note="empty")
+    key = text.strip().lower()
+    hit = _CELLS.get(key)
+    if hit is None:
+        # try a loose contains-match for a ranked candidate set (never a silent pick)
+        cands = [{"id": v[0], "label": v[1], "ontology": v[2]}
+                 for k, v in _CELLS.items() if k in key or key in k]
+        uniq = {c["id"]: c for c in cands}
+        if len(uniq) == 1:
+            v = next(iter(uniq.values()))
+            hit = (v["id"], v["label"], v["ontology"])
+        elif len(uniq) > 1:
+            return Resolved(text=text, ontology=None, confidence=0.3, candidates=list(uniq.values()),
+                            note="ambiguous cell term; resolve to one of the candidates")
+        else:
+            return Resolved(text=text, confidence=None, note="unresolved cell term")
+    cid, label, onto = hit
+    note = _LINE_CAVEAT if onto == "Cellosaurus" else None
+    return Resolved(text=text, id=cid, label=label, ontology=onto, confidence=0.95, note=note)