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

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

@@ -3,6 +3,74 @@
 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
+(Boltz-2), surfaces each oracle's published reliability reported verbatim from public benchmarks, and makes
+cross-oracle disagreement widen the reported interval. Every oracle output stays a candidate, never ground
+truth.
+
+### Added
+- **Binding-affinity oracle** (`pen_stack/oracles/affinity.py`). Wraps the Boltz-2 protein-ligand affinity head
+  (MIT, `10.1101/2025.06.14.659707`): a binder probability and a predicted affinity value with native
+  uncertainty taken from the model's own outputs. The head is protein-small-molecule only, so protein-protein
+  and protein-DNA pairs are returned as out-of-scope (extrapolating). The backend runs off the request path and
+  is cached; an uncached request defers (cache-or-abstain) rather than blocking or fabricating. A grounded,
+  in-domain example is committed: 4-hydroxytamoxifen binding the ERT2 ligand-binding domain (the inducible-writer
+  switch), predicted as a high-confidence binder (binder probability 0.99, complex pLDDT 0.94).
+- **Per-oracle reliability registry** (`pen_stack/oracles/reliability.py`, `configs/oracles/reliability.yaml`).
+  Each oracle's published benchmark accuracy, reported verbatim with citation: the Boltz-2 affinity head's
+  FEP+ Pearson r of about 0.62 (paper-reported) is the verified anchor. These are the wrapped models' published
+  numbers, not a claim about this stack's accuracy and not re-computed; where a verbatim score was not verified
+  the value is left null with the cited benchmark as the pointer.
+- **Disagreement to uncertainty.** Cross-oracle disagreement widens the reported interval (native uncertainty
+  plus half the cross-oracle spread); a check confirms the widening is monotonic in the spread.
+- **Held-oracle runner** (`pen_stack/oracles/structure_run.py`) for the structure oracles over writer-substrate
+  and att-site complexes: off the request path, cache-or-abstain.
+- **Oracle-Bench** (`benchmarks/oracle/`) reporting the three gates, and surfaces: `GET /api/oracles` extended
+  with reliability and the disagreement check, `POST /api/oracle/affinity`, MCP `oracle_query`, the manifest
+  `oracle_query` tool, the web Oracle Mesh page, and `docs/oracle_mesh.md`.
+
+### Notes
+- Affinity predictions are candidates with native uncertainty, not measured binding constants; reliability is
+  surfaced so a confident-looking value is not over-trusted.
+- The structure oracles over full complexes (AlphaFold3 / Boltz-2 / Chai-1 / Protenix) remain held: run
+  separately on GPU or cloud and cached, never inline on the request path.
+
 ## [6.12.0] - 2026-06-21 - Verification service: published rule spec, proof object, standards-aligned biosecurity
 
 Hardens `verify(design)` into a formal verification service. The rule base becomes a published, citable spec;
@@ -24,7 +92,8 @@ biosecurity gate is mapped to the community synthesis-screening standards.
   SecureDNA's pass/deny outcome, with a concordance report (8/8 concordant on the labelled probe set).
   References: Common Mechanism (Wheeler et al. 2024, `10.1089/apb.2023.0034`); SecureDNA (`arXiv:2403.14023`).
 - **Verify-Bench** (`benchmarks/verify/`) reporting the three gates, and surfaces: REST `POST /api/verify/proof`,
-  MCP `verify_proof`, manifest tool `verify_proof`, and `docs/verify_service.md`.
+  MCP `verify_proof`, manifest tool `verify_proof`, the web Verify page (per-axis green/amber/red with the
+  violated rule, its citation, and the suggested fix), and `docs/verify_service.md`.
 
 ### Notes
 - The verdict covers legality, feasibility and biosecurity, not efficacy (efficacy stays a downstream

{pen_stack-6.12.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.12.0
+version: 6.14.0
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.12.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/oracle/SHA256SUMS

@@ -0,0 +1,5 @@
+7b39e54eae68dbab180d3461c859cc1f1e481c8d0b694405e49b0f850029930b  benchmarks/oracle/harness.py
+573d0e5029d222dfb93d8a1db71199ff294837a44f7e7fa793b5be3f2a0a6461  benchmarks/oracle/oracle_bench_metrics.json
+d5aafb9351d5f0a93f4a3e5282fc062940a4f9ffe6b8391a4d86bdbc9e70fa29  configs/oracles/reliability.yaml
+49155d662d63ffa37e821f933a1f1b86d10f0eda0a1b038cf7dcbf5c08b54877  oracle_cache/12ce1ef95d7b45985abbc25c.json
+cfbd1588311956bfaa13cc8d8bfb88debf2d4fa7c6c11586ff14c055e5cfd864  oracle_cache/9b57c9a6a632d80ac9292ee2.json

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.12.0 → pen_stack-6.14.0}/configs/oracles/execution.yaml

@@ -85,3 +85,11 @@ oracles:
     latency_class: long_job
     live: false
     note: "HELD, run SEPARATELY on a cloud A100. ~1-10 min. Not active now."
+
+  boltz-2-affinity: # v6.13 WS-ORACLE: the Boltz-2 affinity head (protein-ligand binding affinity)
+    execution: local_gpu
+    latency_class: long_job
+    live: false
+    note: "Boltz-2 affinity head (MIT weights). Run OFF-REQUEST as a batch on the GPU (~10-30 min incl. MSA) and
+      cached; the request path is cache-or-abstain and never blocks the chat. Predicts a binder probability +
+      affinity value for a protein + small-molecule ligand."

pen_stack-6.14.0/configs/oracles/reliability.yaml

@@ -0,0 +1,92 @@
+# PEN-STACK v6.13, WS-ORACLE: per-oracle reliability registry.
+#
+# These are the WRAPPED models' PUBLISHED reliability on PUBLIC benchmarks, reported VERBATIM with citation.
+# They are NOT a claim about this stack's own accuracy, are NOT re-computed here, and do NOT make an oracle
+# output a ground-truth measurement. Every oracle output remains a candidate / hypothesis carrying its own
+# native uncertainty; reliability is surfaced so a confident-looking value is not over-trusted.
+#
+# Where a verbatim numeric score was not independently verified, `value` is null and the cited benchmark is the
+# pointer. The registry never invents a number.
+version: "1.0"
+disclaimer: >
+  Published reliability of the wrapped foundation models on public benchmarks, reported verbatim with citation.
+  Not a claim about this stack's own accuracy, not re-computed here. Each oracle output is a candidate carrying
+  its native uncertainty. Numbers tagged "paper" are author-reported; "self-report" means not independently
+  verified against the official benchmark results. Where a verbatim score is not pinned, value is null and the
+  benchmark plus citation are given as the pointer.
+
+oracles:
+  boltz-2-affinity:
+    - benchmark: "FEP+ (OpenFE) free-energy perturbation benchmark, held-out targets"
+      task: "protein-ligand binding affinity"
+      metric: "Pearson r vs experimental affinity"
+      value: 0.62
+      qualifier: "approximate; paper-reported"
+      note: "approaches physics-based FEP accuracy at ~1000x lower cost/time (a speed/cost claim, not accuracy)"
+      reported_by: "paper"
+      citation: ["10.1101/2025.06.14.659707"]
+    - benchmark: "CASP16 binding-affinity challenge (140 complexes)"
+      task: "protein-ligand binding affinity"
+      metric: "ranking among submitted methods"
+      value: null
+      qualifier: "self-reported first among submitted methods; not independently verified vs official CASP16 results"
+      reported_by: "self-report"
+      citation: ["10.1101/2025.06.14.659707"]
+    - related_public_benchmarks:
+        - "MF-PCBA multi-fidelity PubChem BioAssay (10.1021/acs.jcim.2c01569)"
+        - "Polaris / ASAP-OpenADMET antiviral challenge 2025 (10.26434/chemrxiv-2025-zd9mr)"
+        - "OpenFF protein-ligand-benchmark (github.com/openforcefield/protein-ligand-benchmark)"
+
+  alphafold3:
+    - benchmark: "CASP / CAMEO blind structure assessment; PDB held-out set"
+      task: "protein / protein-NA complex structure prediction"
+      metric: "LDDT / TM-score / DockQ by target class (see source)"
+      value: null
+      qualifier: "benchmark named; a single verbatim score is not pinned (varies strongly by target class)"
+      reported_by: "community/paper"
+      citation: ["predictioncenter.org (CASP)", "cameo3d.org (CAMEO; Haas et al. 2018, PubMed 29178137)"]
+
+  boltz-2:
+    - benchmark: "CASP / CAMEO; PDB held-out set (open-weights AF3-class predictor)"
+      task: "protein / complex structure prediction"
+      metric: "LDDT / TM-score (see source)"
+      value: null
+      qualifier: "benchmark named; verbatim score not pinned here"
+      reported_by: "paper"
+      citation: ["10.1101/2025.06.14.659707", "Boltz-1 10.1101/2024.11.19.624167"]
+
+  chai-1:
+    - benchmark: "CASP / CAMEO; PDB held-out set"
+      task: "protein / complex structure prediction"
+      metric: "LDDT / DockQ (see source)"
+      value: null
+      qualifier: "benchmark named; verbatim score not pinned here"
+      reported_by: "developer"
+      citation: ["github.com/chaidiscovery/chai-lab"]
+
+  evo2:
+    - benchmark: "ProteinGym (variant effect); zero-shot genomic likelihood"
+      task: "variant-effect / sequence likelihood"
+      metric: "Spearman / AUROC (see source)"
+      value: null
+      qualifier: "benchmark named; verbatim score not pinned here"
+      reported_by: "community"
+      citation: ["ProteinGym 10.1101/2023.12.07.570727"]
+
+  esm3:
+    - benchmark: "ProteinGym (variant effect); FLIP (fitness landscapes)"
+      task: "variant-effect / protein fitness"
+      metric: "Spearman (see source)"
+      value: null
+      qualifier: "benchmark named; verbatim score not pinned here"
+      reported_by: "community"
+      citation: ["ProteinGym 10.1101/2023.12.07.570727", "FLIP 10.1101/2021.11.09.467890"]
+
+  alphagenome:
+    - benchmark: "regulatory-track + variant-effect evaluation (in-distribution tracks/tissues)"
+      task: "regulatory genomics"
+      metric: "see source (per-track correlation)"
+      value: null
+      qualifier: "benchmark named; verbatim score not pinned here; valid only on trained tracks/tissues"
+      reported_by: "developer"
+      citation: ["Google DeepMind AlphaGenome"]

{pen_stack-6.12.0 → pen_stack-6.14.0}/configs/oracles/scope_cards.yaml

@@ -235,3 +235,16 @@ oracles:
       absolute expression"
     generalizes_to_unseen_loci: false
     license: "MIT (github.com/bowang-lab/scGPT; Nature Methods 10.1038/s41592-024-02201-0)"
+
+  boltz-2-affinity: # v6.13 WS-ORACLE: the Boltz-2 protein-ligand binding-affinity head
+    family: affinity
+    version: "2.2.1"
+    output_kind: claim # a checkable prediction (predicted, not a measured Kd); carries native uncertainty
+    valid_for: "protein + SMALL-MOLECULE ligand binding-affinity prediction (Boltz-2 affinity head): a binder
+      probability and a predicted affinity value, for ligands near the trained chemical space (e.g. a
+      small-molecule inducer that switches a writer, a capsid-binding small molecule, an effector drug)"
+    not_valid_for: "protein-protein or protein-DNA affinity (the head is protein-LIGAND only; those are
+      out-of-scope and flagged extrapolating); an absolute measured Kd/IC50; ligands far outside the trained
+      chemical space; asserting a binder WORKS in cells (every output is a hypothesis, not a measurement)"
+    generalizes_to_unseen_loci: true
+    license: "MIT (Boltz-2, 10.1101/2025.06.14.659707)"

{pen_stack-6.12.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/oracle_mesh.md

@@ -0,0 +1,64 @@
+# The oracle mesh
+
+PEN-STACK wraps the biomolecular foundation models (AlphaGenome, Evo2, AlphaFold3, Boltz-2, Chai-1, Protenix,
+ESM3, RFdiffusion, ProteinMPNN, ViennaRNA, and the bridge energetics model) behind one result contract. Every
+oracle, however different internally, answers through the same `OracleResult`: a value, its provenance
+(model + version), the model's own native uncertainty, and a scope card. Three invariants are encoded in the
+type itself:
+
+1. A generative output is a candidate, never a claim. A generated sequence, structure or backbone is a proposal
+   that must pass writer-verification before it can enter a claim path (`as_claim()` raises on a candidate).
+2. One contract for every oracle. Provenance and the oracle's native uncertainty are always carried; every call
+   is cache-keyed on inputs, model and version.
+3. Scope is explicit. Each result names its scope card and carries an `extrapolating` flag, so the evidence that
+   these models do not generalize outside their training envelope is labelled, not hidden.
+
+## Binding affinity (Boltz-2)
+
+The affinity oracle (`pen_stack.oracles.affinity`) wraps the Boltz-2 protein-ligand affinity head (Boltz-2, MIT,
+DOI 10.1101/2025.06.14.659707). For a protein and a small-molecule ligand it returns a binder probability and a
+predicted affinity value (a log(IC50), micromolar-scale number, lower = stronger), with native uncertainty taken
+from the model's own outputs. The head is protein-small-molecule only: protein-protein and protein-DNA pairs are
+returned as out-of-scope (extrapolating). Pair types in scope include the small-molecule inducer that switches a
+genome writer (for example 4-hydroxytamoxifen and the ERT2 ligand-binding domain), a capsid-binding ligand, and
+an effector drug.
+
+The affinity backend is a long GPU batch (around ten to thirty minutes including the MSA), so it runs off the
+request path and the result is cached. The request path is cache-or-abstain: a request with no cached run defers
+(`available=False`) rather than blocking the chat or fabricating a value.
+
+## Per-oracle reliability
+
+`configs/oracles/reliability.yaml` records each oracle's published reliability on public benchmarks, reported
+verbatim with citation (`pen_stack.oracles.reliability`). These numbers are the wrapped model's accuracy as
+reported by its authors or the community, not a claim about this stack's own accuracy and not re-computed here.
+The verified anchor is the Boltz-2 affinity head's FEP+ (OpenFE) Pearson r of about 0.62 (paper-reported); its
+CASP16 affinity-challenge ranking is recorded as a self-report, not independently verified. For the structure and
+sequence oracles the registry names the benchmark each is evaluated on (CASP and CAMEO for structure, ProteinGym
+and FLIP for variant effect) with citations, and leaves the numeric value null where a verbatim score was not
+independently verified rather than inventing one.
+
+Reliability is surfaced in `GET /api/oracles`, in the MCP `oracle_query` tool, and in the web Oracle Mesh page,
+so a confident-looking value is read alongside how reliable the model that produced it actually is.
+
+## Disagreement to uncertainty
+
+Where redundant numeric oracles are available (for example the structure predictors), agreement is a confidence
+signal and disagreement widens the reported interval. The consensus combines the available oracles and sets the
+reported native uncertainty to the largest member uncertainty plus half the cross-oracle spread. This widening is
+monotonic in the spread, checked by `disagreement_widens_monotonically` and reported by Oracle-Bench.
+
+## Held oracles
+
+The structure oracles (AlphaFold3 / Boltz-2 / Chai-1 / Protenix) over full writer-substrate and att-site
+complexes are held: a full complex prediction is a long GPU or cloud batch run off-request and cached
+(`pen_stack.oracles.structure_run`). The request path replays the cache or abstains; it never runs the long job
+inline.
+
+## Surfaces
+
+- `GET /api/oracles` (optional `?probe=true`): per-oracle execution, latency class, live status and published
+  reliability, plus the disagreement-to-interval check.
+- `POST /api/oracle/affinity`: a protein-ligand binding-affinity query (cache-or-abstain).
+- MCP `oracle_query`: the same, for an agent.
+- Web: the Oracle Mesh page.

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.12.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.12.0"
+__version__ = "6.14.0"

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

@@ -60,6 +60,38 @@ 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:
+    """v6.13 PEN-ORACLE: query the oracle mesh under one contract. With no arguments, returns every oracle's
+    execution + latency + live status + PUBLISHED reliability (reported verbatim from public benchmarks, with
+    citation; not a claim about this stack's accuracy) and the disagreement-to-interval check. With `oracle` set,
+    returns that oracle's status + reliability. With `protein_seq` + `ligand_smiles`, returns a CANDIDATE
+    binding-affinity prediction (Boltz-2 head): a binder probability + a predicted value with native uncertainty,
+    cache-or-abstain; protein-protein/protein-DNA pair types are flagged extrapolating (the head is
+    protein-ligand only). The long GPU job never runs on the request path."""
+    from pen_stack.oracles.status import oracle_status, summary
+    if protein_seq and ligand_smiles:
+        from pen_stack.oracles.affinity import predict_affinity
+        return predict_affinity(protein_seq, ligand_smiles, pair_type=pair_type, ligand_name=ligand_name).model_dump()
+    st = oracle_status()
+    if oracle:
+        return {"oracle": oracle, "status": st.get(oracle), "found": oracle in st}
+    return {"summary": summary(), "oracles": st}
+
+
 @mcp.tool()
 def graph_query(locus: str, cargo_form: str | None = None) -> dict:
     """v4.5 world-model graph (WS-G): a multi-hop query. Returns the writer families that REACH `locus` AND

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

@@ -67,6 +67,19 @@ _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 "
+     "(v6.13 PEN-ORACLE)",
+     "input": "oracle name, or {protein_seq, ligand_smiles, pair_type}", "output": "oracle status + reliability, "
+     "or a candidate affinity (binder probability + value) or abstain; protein-protein/protein-DNA flagged OOD",
+     "entrypoint": "pen_stack.oracles.affinity.predict_affinity", "fabricates": False},
 ]
 
 _POLICY = ("outputs outside scope are returned as `out_of_scope` (known-unknown) or `extrapolating` (OOD) and are "

pen_stack-6.14.0/pen_stack/oracles/affinity.py

@@ -0,0 +1,116 @@
+"""Binding-affinity oracle (v6.13, WS-ORACLE), the Boltz-2 protein-ligand affinity head under the contract.
+
+Boltz-2 (MIT; Passaro et al. 2025, DOI 10.1101/2025.06.14.659707) jointly predicts a complex structure and a
+binding affinity for a protein with a small-molecule ligand: a binder probability (``affinity_probability_binary``)
+and a predicted affinity value (``affinity_pred_value``, a log(IC50) micromolar-scale number, lower = stronger).
+This oracle wraps that head under the L1 ``OracleResult`` contract:
+
+* the prediction is a CANDIDATE / hypothesis, never a measured Kd;
+* the model's own outputs supply the native uncertainty (the spread between Boltz-2's two affinity heads, or a
+  binder-call entropy proxy);
+* the affinity head is protein-SMALL-MOLECULE only, so protein-protein and protein-DNA requests are flagged
+  out-of-scope (``extrapolating``);
+* the backend runs OFF the request path (a GPU batch, ~10-30 min including MSA) and is cached; when no cached run
+  is present the request path is cache-or-abstain and never blocks.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pen_stack.oracles import build_result, cache_get, cache_put
+from pen_stack.oracles.schema import OracleResult
+
+_MODEL = "boltz-2-affinity"
+
+# Pair types the affinity head COVERS (protein + small-molecule ligand), with a genome-writing-relevant gloss.
+_LIGAND_PAIRS = {
+    "inducer_switch": "a small-molecule inducer that switches a genome writer on/off (e.g. 4-OHT / ERT2)",
+    "capsid_ligand": "a small molecule binding a delivery capsid (stabiliser or targeting ligand)",
+    "effector_drug": "a drug binding a delivered effector protein",
+    "ligand": "a generic protein + small-molecule ligand pair",
+}
+# Pair types OUTSIDE the affinity head's domain (it is protein-ligand only): returned extrapolating.
+_OOD_PAIRS = {
+    "protein_protein": "protein-protein affinity is not the Boltz-2 affinity head's domain (protein-ligand only)",
+    "protein_dna": "protein-DNA affinity is not the Boltz-2 affinity head's domain (protein-ligand only)",
+}
+
+_UNITS = ("Boltz-2 affinity_pred_value: log(IC50) on a micromolar scale, lower = stronger binder "
+          "(a prediction, not a measured Kd/IC50)")
+
+
+def _inputs(protein_seq: str, ligand_smiles: str, pair_type: str) -> dict:
+    return {"protein_len": len(protein_seq), "protein": protein_seq.upper(),
+            "ligand_smiles": ligand_smiles, "pair_type": pair_type}
+
+
+def predict_affinity(protein_seq: str, ligand_smiles: str, pair_type: str = "ligand",
+                     ligand_name: str | None = None) -> OracleResult:
+    """Predict protein-ligand binding affinity with the Boltz-2 head; cache-replayed if present, else deferred.
+
+    ``pair_type`` in {inducer_switch, capsid_ligand, effector_drug, ligand} is in-scope; ``protein_protein`` /
+    ``protein_dna`` are OUT of the affinity head's domain and returned extrapolating (the head is protein-ligand).
+    The long GPU job is never run on the request path: an absent cached run yields a deferred result.
+    """
+    in_scope = pair_type in _LIGAND_PAIRS
+    extrapolating = pair_type in _OOD_PAIRS
+    if not in_scope and not extrapolating:
+        raise ValueError(f"unknown pair_type {pair_type!r}; choose from "
+                         f"{sorted(_LIGAND_PAIRS) + sorted(_OOD_PAIRS)}")
+    inputs = _inputs(protein_seq, ligand_smiles, pair_type)
+    note0 = (_OOD_PAIRS[pair_type] if extrapolating
+             else "Boltz-2 affinity head; backend runs off-request on the GPU and is cached")
+    r = build_result("affinity", _MODEL, inputs=inputs, available=False,
+                     in_scope=in_scope, extrapolating=extrapolating, note=note0 + "; cache-or-abstain")
+    hit = cache_get(r.provenance.cache_key)
+    if hit is not None:
+        note = "replayed from committed oracle cache"
+        if extrapolating:
+            note += "; OUT-OF-SCOPE pair_type for a protein-ligand head: treat as extrapolative"
+        if ligand_name:
+            note += f"; ligand={ligand_name}"
+        return build_result("affinity", _MODEL, inputs=inputs, value=hit.get("value"),
+                            native_uncertainty=hit.get("native_uncertainty"),
+                            available=True, cached=True, source="cache",
+                            in_scope=in_scope, extrapolating=extrapolating, note=note)
+    return r  # deferred: no cached run, and the long job never runs on the request path
+
+
+def value_from_boltz_output(out_dir: str | Path) -> dict:
+    """Parse a Boltz-2 affinity prediction directory into the cached {value, native_uncertainty} payload.
+
+    Native uncertainty is taken from the model's own outputs: half the spread between Boltz-2's two affinity
+    heads when both are present, else a binder-call entropy proxy (``1 - |2p - 1|``, 0 at p in {0,1}, 1 at 0.5).
+    """
+    out = Path(out_dir)
+    js = sorted(p for p in out.rglob("affinity*.json"))
+    if not js:
+        raise FileNotFoundError(f"no affinity*.json under {out}")
+    d = json.loads(js[0].read_text(encoding="utf-8"))
+    val = d.get("affinity_pred_value")
+    prob = d.get("affinity_probability_binary")
+    v1, v2 = d.get("affinity_pred_value1"), d.get("affinity_pred_value2")
+    if v1 is not None and v2 is not None:
+        unc = round(abs(float(v1) - float(v2)) / 2.0, 4)
+        unc_src = "half the spread between the two Boltz-2 affinity heads"
+    elif prob is not None:
+        unc = round(1.0 - abs(2.0 * float(prob) - 1.0), 4)
+        unc_src = "binder-call entropy proxy (1 - |2p - 1|)"
+    else:
+        unc, unc_src = None, "unavailable"
+    value = {"affinity_pred_value": val, "binder_probability": prob, "units": _UNITS,
+             "heads": {"affinity_pred_value1": v1, "affinity_pred_value2": v2},
+             "native_uncertainty_source": unc_src, "source_file": js[0].name}
+    return {"value": value, "native_uncertainty": unc}
+
+
+def cache_affinity_run(protein_seq: str, ligand_smiles: str, pair_type: str, out_dir: str | Path) -> str:
+    """Ingest an OFF-REQUEST Boltz-2 affinity run into the oracle cache, so the request path can replay it.
+
+    Returns the cache key. Called after a separate GPU batch completes; never on the request path.
+    """
+    payload = value_from_boltz_output(out_dir)
+    r = build_result("affinity", _MODEL, inputs=_inputs(protein_seq, ligand_smiles, pair_type), available=False)
+    cache_put(r.provenance.cache_key, payload)
+    return r.provenance.cache_key