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

{pen_stack-6.12.0 → pen_stack-6.13.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.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 +58,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.13.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.13.0
 date-released: 2026-06-20
 authors:
   - family-names: "Mahaboob Ali"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.12.0
+Version: 6.13.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

pen_stack-6.13.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.12.0 → pen_stack-6.13.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.13.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.13.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.13.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.12.0 → pen_stack-6.13.0}/pen_stack/__init__.py

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

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

@@ -60,6 +60,26 @@ def verify_proof(design: dict) -> dict:
     return _vp(design).model_dump()
 
 
+@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.13.0}/pen_stack/api/manifest.py

@@ -67,6 +67,13 @@ _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": "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.13.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

pen_stack-6.13.0/pen_stack/oracles/reliability.py

@@ -0,0 +1,64 @@
+"""Per-oracle reliability registry (v6.13, WS-ORACLE) + the disagreement-to-interval monotonicity check.
+
+Reliability here is the wrapped model's PUBLISHED accuracy on PUBLIC benchmarks, reported VERBATIM with citation
+(``configs/oracles/reliability.yaml``). It is NOT recomputed here and NOT a claim about this stack's own accuracy.
+Each oracle output remains a candidate carrying its own native uncertainty; reliability is surfaced precisely so a
+confident-looking value is not over-trusted. Where a verbatim number was not independently verified the registry
+records ``null`` plus the cited benchmark (the pointer), never a guess.
+
+The module also exposes :func:`disagreement_widens_monotonically`, which confirms the cross-oracle consensus
+mechanism (:func:`pen_stack.oracles.consensus`, native uncertainty + half the cross-oracle spread) widens the
+reported interval MONOTONICALLY as the spread grows. That is the v6.13 acceptance check for the
+disagreement-to-uncertainty rule.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack._resources import resource
+
+
+@lru_cache(maxsize=1)
+def _doc() -> dict:
+    import yaml
+    return yaml.safe_load(resource("configs/oracles/reliability.yaml").read_text(encoding="utf-8"))
+
+
+def reliability(oracle: str) -> list | None:
+    """The published-reliability records for one oracle (or None if the oracle is not in the registry)."""
+    return _doc()["oracles"].get(oracle)
+
+
+def all_reliability() -> dict:
+    """The full per-oracle reliability registry."""
+    return _doc()["oracles"]
+
+
+def disclaimer() -> str:
+    """The standing disclaimer: published numbers, reported verbatim, not a claim about this stack."""
+    return _doc()["disclaimer"].strip()
+
+
+def _num_result(value: float, unc: float):
+    from pen_stack.oracles import build_result
+    return build_result("structure", "boltz-2", value=value, native_uncertainty=unc, available=True)
+
+
+def disagreement_widens_monotonically(spreads: list[float] | None = None) -> dict:
+    """Confirm :func:`consensus` widens the reported interval monotonically with the cross-oracle spread.
+
+    For each spread ``s`` two numeric oracles are placed symmetrically about a common centre, each with the same
+    small native uncertainty; the consensus native uncertainty must be non-decreasing in ``s``. Returns the
+    measured sequence and the monotonicity verdict (the gate reports the mechanism as working or broken).
+    """
+    from pen_stack.oracles import consensus
+    spreads = spreads if spreads is not None else [0.0, 0.05, 0.1, 0.2, 0.4]
+    centre, member_unc = 0.5, 0.05
+    uncs: list[float] = []
+    for s in spreads:
+        members = [_num_result(centre - s / 2, member_unc), _num_result(centre + s / 2, member_unc)]
+        uncs.append(consensus(members, oracle="structure").native_uncertainty)
+    monotone = all(uncs[i + 1] >= uncs[i] - 1e-9 for i in range(len(uncs) - 1))
+    return {"spreads": spreads, "native_uncertainty": uncs, "monotone_nondecreasing": monotone,
+            "rule": "native_uncertainty = max(member native uncertainty) + 0.5 * (max - min) over the "
+                    "available numeric oracles"}

{pen_stack-6.12.0 → pen_stack-6.13.0}/pen_stack/oracles/status.py

@@ -87,14 +87,20 @@ def _is_live(model: str, card: dict, probe: bool) -> tuple[bool, str]:
 
 
 def oracle_status(probe: bool = False) -> dict:
-    """Per-oracle execution + latency_class + live status. `probe=True` pings the local model servers (adds a
-    short network check); default is config-level only. The assistant uses this to warn the user about cost."""
+    """Per-oracle execution + latency_class + live status + published reliability. `probe=True` pings the local
+    model servers (adds a short network check); default is config-level only. Reliability is the wrapped model's
+    PUBLISHED benchmark accuracy, reported verbatim with citation, never a claim about this stack's accuracy."""
+    try:
+        from pen_stack.oracles.reliability import all_reliability
+        rel = all_reliability()
+    except Exception: # noqa: BLE001
+        rel = {}
     out = {}
     for model, card in execution_map().items():
         live, why = _is_live(model, card, probe)
         out[model] = {"execution": card.get("execution"), "latency_class": card.get("latency_class"),
                       "live": live, "status": why, "note": card.get("note", ""),
-                      "server": card.get("server")}
+                      "server": card.get("server"), "reliability": rel.get(model)}
     return out
 
 
@@ -104,7 +110,14 @@ def summary() -> dict:
     live = sorted(m for m, s in st.items() if s["live"])
     held = sorted(m for m, s in st.items() if s["execution"] == "cloud_a100")
     deferred = sorted(m for m, s in st.items() if s["execution"] == "deferred")
-    return {"live": live, "held_cloud": held, "deferred": deferred,
-            "latency_classes": {m: s["latency_class"] for m, s in st.items()},
-            "note": ("Live oracles answer in seconds, ~2 min; held cloud jobs (AF3/Boltz/Chai/Protenix) are run "
-                     "separately and never block; deferred outcomes are known-unknowns, never fabricated.")}
+    out = {"live": live, "held_cloud": held, "deferred": deferred,
+           "latency_classes": {m: s["latency_class"] for m, s in st.items()},
+           "note": ("Live oracles answer in seconds, ~2 min; held cloud jobs (AF3/Boltz/Chai/Protenix) are run "
+                    "separately and never block; deferred outcomes are known-unknowns, never fabricated.")}
+    try:
+        from pen_stack.oracles.reliability import disagreement_widens_monotonically, disclaimer
+        out["reliability_note"] = disclaimer()
+        out["disagreement_to_interval"] = disagreement_widens_monotonically()
+    except Exception: # noqa: BLE001
+        pass
+    return out

pen_stack-6.13.0/pen_stack/oracles/structure_run.py

@@ -0,0 +1,76 @@
+"""Off-request structure-oracle runner (v6.13, WS-ORACLE) over named genome-writing complexes.
+
+The structure oracles (AlphaFold3 / Boltz-2 / Chai-1 / Protenix) are held: a full complex prediction is a long
+GPU / cloud batch, so it runs OFF the request path and the result is cached; the request path only ever replays
+the cache or abstains (:func:`pen_stack.oracles.structure.consistency`). This module names the writer-substrate /
+att-site complexes the substrate cares about, exposes a cache-or-abstain :func:`get` over the cross-oracle
+consistency, and an :func:`ingest_boltz_confidence` hook that folds a completed off-request Boltz run's confidence
+(pLDDT / pTM) into the cache so the request path can replay it.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pen_stack.oracles import build_result, cache_put
+from pen_stack.oracles.schema import OracleResult
+from pen_stack.oracles.structure import consistency, predict_structure
+
+# Named complexes relevant to genome writing. Sequences are supplied at call time; these entries describe what a
+# held off-request run would target. `kind` records why a structure oracle is or is not the right tool.
+_COMPLEXES = {
+    "ert2_4oht": {
+        "description": "ERT2 ligand-binding domain (human ESR1, UniProt P03372 res 305-554) with "
+                       "4-hydroxytamoxifen, the inducible-writer chemical switch",
+        "kind": "protein_ligand"},
+    "bxb1_attb": {
+        "description": "Bxb1 serine integrase engaging its attB DNA target",
+        "kind": "protein_dna"},
+    "prime_editor_target": {
+        "description": "Prime editor (Cas9 nickase-RT fusion) engaging its primed genomic target",
+        "kind": "protein_dna"},
+}
+
+
+def complexes() -> dict:
+    """The registry of named writer-substrate / att-site complexes a held structure run would target."""
+    return dict(_COMPLEXES)
+
+
+def get(protein_seq: str, models: list[str] | None = None) -> OracleResult:
+    """Cross-oracle structure consistency for a complex's protein, cache-or-abstain (never runs the long job).
+
+    Replays committed structure-oracle caches and combines them; divergence widens the interval. When no backend
+    has been run off-request and cached, the consensus is unavailable (a deferred result), never fabricated.
+    """
+    return consistency(protein_seq, models)
+
+
+def single(protein_seq: str, model: str = "boltz-2") -> OracleResult:
+    """One structure oracle's confidence for a sequence (cache-replayed if present, else deferred)."""
+    return predict_structure(protein_seq, model)
+
+
+def ingest_boltz_confidence(protein_seq: str, out_dir: str | Path, model: str = "boltz-2") -> str:
+    """Fold a completed OFF-REQUEST Boltz run's confidence into the structure cache, keyed as ``predict_structure``.
+
+    Reads Boltz's ``confidence_*.json`` (``complex_plddt`` on a 0-1 scale) and caches a pLDDT-like value with
+    native uncertainty ``1 - pLDDT``, so :func:`predict_structure` (and thus :func:`get`) replays it. Returns the
+    cache key. Called after a separate GPU batch completes; never on the request path.
+    """
+    out = Path(out_dir)
+    cj = sorted(p for p in out.rglob("confidence*.json"))
+    if not cj:
+        raise FileNotFoundError(f"no confidence*.json under {out}")
+    d = json.loads(cj[0].read_text(encoding="utf-8"))
+    plddt = d.get("complex_plddt")
+    if plddt is None:
+        raise KeyError(f"complex_plddt absent in {cj[0].name}")
+    plddt = float(plddt)
+    if plddt > 1.0:  # some writers report 0-100; normalise to 0-1
+        plddt = plddt / 100.0
+    inputs = {"seq_len": len(protein_seq), "seq": protein_seq.upper(), "model": model}
+    key = build_result("structure", model, inputs=inputs, available=False).provenance.cache_key
+    cache_put(key, {"value": round(plddt, 4), "native_uncertainty": round(1.0 - plddt, 4),
+                    "ptm": d.get("ptm"), "iptm": d.get("iptm"), "source_file": cj[0].name})
+    return key

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

@@ -238,6 +238,18 @@ def offtarget_assay_endpoint(writer_family: str):
     return recommend_assay(writer_family)
 
 
+@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:
+    {protein_seq, ligand_smiles, pair_type?, ligand_name?}. Returns a CANDIDATE affinity (binder probability +
+    predicted value) with native uncertainty, cache-or-abstain; protein-protein/protein-DNA pair types are
+    flagged extrapolating (the head is protein-ligand only). Never runs the long job on the request path."""
+    from pen_stack.oracles.affinity import predict_affinity
+    r = predict_affinity(req.get("protein_seq", ""), req.get("ligand_smiles", ""),
+                         pair_type=req.get("pair_type", "ligand"), ligand_name=req.get("ligand_name"))
+    return r.model_dump()
+
+
 @app.post("/delivery", tags=["v6.11 delivery"])
 def delivery_endpoint(req: dict):
     """v6.11 PEN-DELIVER cross-modality delivery recommender. Body: {cargo_form, cargo_bp?, target_tissue?,