pen-stack 6.3.1__tar.gz → 6.4.0__tar.gz

{pen_stack-6.3.1 → pen_stack-6.4.0}/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/) and the program's phase structure.
 
+## [6.4.0] - 2026-06-12 - v6.4.0: Live Oracles (the foundation models actually execute)
+
+**The oracle mesh goes live.** The foundation-model adapters that were deferred contracts now run real backends —
+without touching the no-fabrication invariant (generated outputs stay candidates, OOD inputs are flagged, a down
+backend defers). Live execution is opt-in via `PEN_STACK_ORACLE_NET=1`; with the flag unset (CI/offline) every
+oracle behaves exactly as before. MINOR feature release on the stable 6.x API. Workstream WS-LIVE.
+
+### Added — live oracles
+- **Evo2-40B (hosted)** — `oracles/genome.py::generate_dna` calls NVIDIA's hosted Evo2-40B (real generated DNA +
+  per-token probability). ~1–3 s.
+- **AlphaGenome (hosted)** — `oracles/genome.py::variant_effect` **connected to the existing v3.1
+  `wgenome.AlphaGenomeProvider`** (added `score_variant`; no duplicate client) — a real regulatory variant-effect
+  magnitude. ~2–10 s. (AlphaGenome already ran live in v3.1 for expression/tracks/contact — 416 cached predictions.)
+- **ProteinMPNN / ESM3-open / RFdiffusion (local GPU)** — `model_servers/{proteinmpnn,esm3,rfdiffusion}` small
+  FastAPI servers on the VM GPU (reuse `penstack:phase1.5` / `rfdiffusion:base`); `oracles/protein_design.py`
+  HTTP-calls them. ProteinMPNN ~1–9 s, ESM3 ~1–2 s warm, RFdiffusion ~1–2 min. `docker-compose.models.yml` starts
+  them on demand.
+- **Execution + latency surface** — `configs/oracles/execution.yaml` + `oracles/status.py` (`oracle_status`,
+  `summary`) + `GET /oracles` + the chat meta facts: per-oracle execution, **latency class**
+  (instant/seconds/slow/long_job), and live status, so the assistant states the cost before running anything.
+
+### Held / honestly deferred
+- **AlphaFold3 · Boltz-2 · Chai-1 · Protenix** — HELD: need a rented A100/H100 (24–80 GB; AF3 also ~1 TB
+  databases). Run **separately** on cloud, never on the 16 GB VM and never in the request path.
+- **Arc STATE / scGPT** — package verified installable (`pip install arc-state`; SE-600M embeds cells), but a
+  trustworthy perturbation **outcome** needs the State-Transition model + a reference scRNA pipeline, and even
+  SOTA doesn't beat naive baselines (Arc VCC) — so the magnitude stays a known-unknown, honestly deferred
+  (uniform gated hook added via `PEN_STACK_VCELL_URL` for when an ST server is stood up).
+
+### Verified on the VM (RTX A4000)
+Evo2-40B generation ~1.2 s; AlphaGenome variant score `chr22:36201698 A>C` max|effect| 3.15 over 14,652 tracks
+in 3.6 s; ProteinMPNN designed real ubiquitin-fold sequences (global_score ~0.80) in ~9 s; ESM3-open completed the
+ubiquitin sequence from a partial prompt in 1.4 s warm; RFdiffusion diffused a real 60-residue backbone in ~105 s.
+All generated outputs remain candidates (`as_claim()` raises).
+
 ## [6.3.1] - 2026-06-12 - v6.3.1: router fix — general "how does it work" no longer misrouted to the meta lane
 
 **Patch (routing correctness).** Found by a rigorous full-stack test pass (every oracle + every endpoint + the 4

{pen_stack-6.3.1 → pen_stack-6.4.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.3.1
+version: 6.4.0
 date-released: 2026-06-11
 authors:
   - family-names: "Mahaboob Ali"

{pen_stack-6.3.1 → pen_stack-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 6.3.1
+Version: 6.4.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
@@ -90,7 +90,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.3.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.4.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
@@ -148,6 +148,20 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.4 — Live Oracles (the foundation models actually execute)
+
+The foundation-model oracles now **run for real**, not just defer: **ViennaRNA** (in-process), **AlphaGenome**
+(free DeepMind API — variant effect + regulatory tracks), **Evo2-40B** (NVIDIA hosted — DNA generation),
+**ProteinMPNN** / **ESM3-open** / **RFdiffusion** (local GPU model servers). Each is opt-in via
+`PEN_STACK_ORACLE_NET=1`; with the flag off, every oracle behaves exactly as before — and the no-fabrication
+invariant is untouched (generated outputs stay **candidates**, OOD inputs are flagged, a down backend **defers**).
+
+A new **execution + latency surface** (`GET /oracles`, `configs/oracles/execution.yaml`) tells you the cost up
+front: *instant* / *seconds* / *slow* (~1–2 min, warn) / *long_job*. The cloud-A100 structure models
+(AlphaFold3 · Boltz-2 · Chai-1 · Protenix) are **held on purpose** — they run **separately** on a rented A100,
+never on the 16 GB VM and never in the request path. Arc STATE's perturbation **outcome** stays honestly
+deferred (it needs the State-Transition model + a reference scRNA pipeline). See [docs/live_oracles.md](docs/live_oracles.md).
+
 ## What is new in v6.3 — The Hybrid Co-Scientist (grounded engine + general intelligence)
 
 The chat now does three things at once without ever blurring them: it **runs the engine** for genome-writing

{pen_stack-6.3.1 → pen_stack-6.4.0}/README.md

@@ -15,7 +15,7 @@ every design against rule-grounded mechanism, reports calibrated confidence, cit
 [![codecov](https://codecov.io/gh/ahmedanees-m/pen-stack/branch/main/graph/badge.svg)](https://codecov.io/gh/ahmedanees-m/pen-stack)
 [![License: MIT](https://img.shields.io/badge/License-MIT-informational.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
-[![Version](https://img.shields.io/badge/version-6.3.1-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-6.4.0-blue.svg)](CHANGELOG.md)
 [![Status](https://img.shields.io/badge/status-1.0%20First%20Stable-success.svg)](docs/STABILITY.md)
 [![Tests](https://img.shields.io/badge/tests-378%20passing-success.svg)](tests/)
 [![Lint: ruff](https://img.shields.io/badge/lint-ruff-purple.svg)](https://github.com/astral-sh/ruff)
@@ -73,6 +73,20 @@ demonstrated (v5.12) and the benchmark went public (v5.13).
 > unknown funnel remains — made legible (scope flags, known-unknowns, honest baselines, no fabrication), not
 > hidden.
 
+## What is new in v6.4 — Live Oracles (the foundation models actually execute)
+
+The foundation-model oracles now **run for real**, not just defer: **ViennaRNA** (in-process), **AlphaGenome**
+(free DeepMind API — variant effect + regulatory tracks), **Evo2-40B** (NVIDIA hosted — DNA generation),
+**ProteinMPNN** / **ESM3-open** / **RFdiffusion** (local GPU model servers). Each is opt-in via
+`PEN_STACK_ORACLE_NET=1`; with the flag off, every oracle behaves exactly as before — and the no-fabrication
+invariant is untouched (generated outputs stay **candidates**, OOD inputs are flagged, a down backend **defers**).
+
+A new **execution + latency surface** (`GET /oracles`, `configs/oracles/execution.yaml`) tells you the cost up
+front: *instant* / *seconds* / *slow* (~1–2 min, warn) / *long_job*. The cloud-A100 structure models
+(AlphaFold3 · Boltz-2 · Chai-1 · Protenix) are **held on purpose** — they run **separately** on a rented A100,
+never on the 16 GB VM and never in the request path. Arc STATE's perturbation **outcome** stays honestly
+deferred (it needs the State-Transition model + a reference scRNA pipeline). See [docs/live_oracles.md](docs/live_oracles.md).
+
 ## What is new in v6.3 — The Hybrid Co-Scientist (grounded engine + general intelligence)
 
 The chat now does three things at once without ever blurring them: it **runs the engine** for genome-writing

pen_stack-6.4.0/configs/oracles/execution.yaml

@@ -0,0 +1,87 @@
+# How each oracle EXECUTES + its per-query latency class (PEN-STACK v6.4 "Live Oracles").
+#
+# This is the "tell the user the cost up front" table: before an oracle runs, the assistant can state how it
+# executes and how long it will take, so latency is never a surprise.
+#
+# latency_class:
+#   instant   — < 1 s          (answer inline)
+#   seconds   — ~1–10 s        (answer inline)
+#   slow      — ~10 s – 2 min  (WARN: "running <model> on the GPU, ~N…", then answer)
+#   long_job  — minutes–hours  (WARN + run SEPARATELY on cloud; never block the chat)
+#
+# execution:
+#   in_process — runs in the engine process (no extra service)
+#   hosted_api — a free cloud API (no local GPU); needs a key
+#   local_gpu  — a local model server on the VM GPU (start on demand); needs PEN_STACK_ORACLE_NET=1
+#   cloud_a100 — HELD: needs a rented A100/H100 (run separately, not active now)
+#   deferred   — honestly deferred (would require a deeper pipeline; never fabricated)
+oracles:
+  viennarna:
+    execution: in_process
+    latency_class: instant
+    live: always
+    note: "ViennaRNA MFE fold — runs in-process."
+
+  alphagenome:
+    execution: hosted_api
+    latency_class: seconds
+    live_when: "configs/alphagenome_api_key.txt (or ALPHAGENOME_API_KEY) present + PEN_STACK_ORACLE_NET=1"
+    note: "Free DeepMind AlphaGenome API (variant effect + expression/tracks/contact). ~2–10 s."
+
+  evo2:
+    execution: hosted_api
+    latency_class: seconds
+    live_when: "NVIDIA key present + PEN_STACK_ORACLE_NET=1"
+    note: "NVIDIA hosted Evo2-40B (DNA generation). ~1–3 s for short generations."
+
+  proteinmpnn:
+    execution: local_gpu
+    latency_class: seconds
+    server: "penmodel:proteinmpnn — http://localhost:9011"
+    note: "Sequence design for a backbone PDB. ~1–9 s."
+
+  esm3:
+    execution: local_gpu
+    latency_class: seconds
+    server: "penmodel:esm3 — http://localhost:9012"
+    note: "ESM3-open 1.4B protein generation/completion. ~1–2 s warm (~60 s cold weight download)."
+
+  rfdiffusion:
+    execution: local_gpu
+    latency_class: slow
+    server: "penmodel:rfdiffusion — http://localhost:9013"
+    note: "Backbone diffusion. ~1–2 min per backbone — WARN the user before running."
+
+  state:
+    execution: deferred
+    latency_class: long_job
+    live: false
+    note: "Arc STATE: `pip install arc-state` (SE-600M embeds cells). A trustworthy perturbation OUTCOME needs the
+      State-Transition model + a reference scRNA population; even SOTA doesn't beat naive baselines (Arc VCC), so
+      the magnitude stays a known-unknown — honestly deferred, never fabricated."
+  scgpt:
+    execution: deferred
+    latency_class: long_job
+    live: false
+    note: "scGPT virtual-cell — honestly deferred (same rationale as Arc STATE)."
+
+  alphafold3:
+    execution: cloud_a100
+    latency_class: long_job
+    live: false
+    note: "HELD — run SEPARATELY on a cloud A100/H100 80 GB (+ ~1 TB databases). ~10 min–hours. Not active now."
+  boltz-2:
+    execution: cloud_a100
+    latency_class: long_job
+    live: false
+    note: "HELD — run SEPARATELY on a cloud A100 (24–48 GB). ~1–10 min. Not active now."
+  chai-1:
+    execution: cloud_a100
+    latency_class: long_job
+    live: false
+    note: "HELD — run SEPARATELY on a cloud A100 (24 GB+). ~1–10 min. Not active now."
+  protenix:
+    execution: cloud_a100
+    latency_class: long_job
+    live: false
+    note: "HELD — run SEPARATELY on a cloud A100. ~1–10 min. Not active now."

pen_stack-6.4.0/docs/live_oracles.md

@@ -0,0 +1,56 @@
+# Live Oracles (v6.4)
+
+PEN-STACK's foundation-model oracles can **actually execute** — not just defer. v6.4 wires the live paths and
+adds an honest **execution + latency** surface so the assistant tells you the cost *before* it runs anything.
+
+## The no-fabrication invariant is unchanged
+
+Live or deferred, the rule holds: a generative output is a **candidate** (`as_claim()` raises), an OOD input is
+flagged `extrapolating`, and when a backend is down the adapter **defers** — it never fabricates a number.
+Turning a model "on" is opt-in via **`PEN_STACK_ORACLE_NET=1`**; with the flag unset (CI / offline) every oracle
+behaves exactly as before.
+
+## What runs where, and how long
+
+| Oracle | Execution | Latency | How to enable |
+|---|---|---|---|
+| **ViennaRNA** | in-process | **instant** (<1 s) | always on |
+| **AlphaGenome** | hosted API (free) | **seconds** (~2–10 s) | `configs/alphagenome_api_key.txt` + `PEN_STACK_ORACLE_NET=1` |
+| **Evo2-40B** | hosted API (NVIDIA) | **seconds** (~1–3 s) | `configs/nvidia_api_key.txt` + `PEN_STACK_ORACLE_NET=1` |
+| **ProteinMPNN** | local GPU server :9011 | **seconds** (~1–9 s) | start the model server + `PEN_STACK_ORACLE_NET=1` |
+| **ESM3-open 1.4B** | local GPU server :9012 | **seconds** (~1–2 s warm) | start the model server + flag |
+| **RFdiffusion** | local GPU server :9013 | **slow** (~1–2 min) | start the model server + flag *(warn the user)* |
+| Arc STATE / scGPT | deferred | long_job | perturbation **outcome** needs the State-Transition model + a reference scRNA pipeline; honestly deferred |
+| AlphaFold3 · Boltz-2 · Chai-1 · Protenix | **HELD** (cloud A100) | long_job | run **separately** on a rented A100/H100; not active now |
+
+Query the live status any time: `GET /oracles` (add `?probe=true` to ping the local servers), or
+`pen_stack.oracles.status.summary()`.
+
+## Starting the local GPU model servers (on demand)
+
+The local models run as small FastAPI services on the VM GPU — start only what you need:
+
+```bash
+# build bases once (penstack:phase1.5 already on the VM; rfdiffusion:base from the RFdiffusion repo)
+docker compose -f docker-compose.models.yml up -d proteinmpnn esm3      # the fast ones
+docker compose -f docker-compose.models.yml up -d rfdiffusion           # the slow one (~1–2 min/run)
+```
+
+Then run the engine with the live flag + keys:
+
+```bash
+PEN_STACK_ORACLE_NET=1 \
+NVIDIA_API_KEY=$(cat configs/nvidia_api_key.txt) \
+ALPHAGENOME_API_KEY=$(cat configs/alphagenome_api_key.txt) \
+uvicorn pen_stack.web.server:app --port 8000
+```
+
+## Latency policy ("tell the user up front")
+
+- **instant / seconds** → answered inline.
+- **slow** (RFdiffusion) → *"Running RFdiffusion on the GPU, ~1–2 min…"* then the result.
+- **long_job** (AF3 / Boltz / Chai / Protenix) → *"This needs a cloud A100 and takes minutes — run it separately"*;
+  never silently blocks the chat.
+
+The cloud-A100 structure models are **held on purpose** (see the v6.4 changelog): they can be run via these same
+oracle adapters by pointing them at a cloud GPU, just not on the 16 GB VM and not in the request path.

{pen_stack-6.3.1 → pen_stack-6.4.0}/pen_stack/__init__.py

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

{pen_stack-6.3.1 → pen_stack-6.4.0}/pen_stack/api/manifest.py

@@ -57,12 +57,19 @@ def capability_manifest() -> dict[str, Any]:
         "guarantees": ["rule-grounded legality", "calibrated confidence", "explicit scope / known-unknowns",
                        "biosecurity safety gate", "no fabrication"],
         "tools": _TOOLS,
-        "surfaces": {"rest": "/capabilities, /scope, /verify, /generate, /predict, /immune, /safety, /suggest, "
-                             "/session, /openapi.json", "mcp": "pen_stack.agent.mcp_server",
+        "oracles": _oracle_summary(),
+        "surfaces": {"rest": "/capabilities, /scope, /oracles, /verify, /generate, /predict, /immune, /safety, "
+                             "/suggest, /session, /openapi.json", "mcp": "pen_stack.agent.mcp_server",
                      "challenge": "benchmarks/genome_writing_challenge"},
     }
 
 
+def _oracle_summary() -> dict:
+    """Live-oracle roll-up (v6.4): which foundation models execute live, their latency class, what is held/deferred."""
+    from pen_stack.oracles.status import summary
+    return summary()
+
+
 def _known_unknowns() -> list[dict]:
     """The known-unknowns as PUBLIC data (id/title/requires/why) — internal matcher fields are not exposed."""
     from pen_stack.agent.scope import load_registry

pen_stack-6.4.0/pen_stack/oracles/genome.py

@@ -0,0 +1,167 @@
+"""Genome oracles (v4.0, WS-O1) — AlphaGenome / Evo2 / accessibility baselines, under one contract.
+
+AlphaGenome (regulatory tracks + variant effect) is **OOD-gated**: scoring a locus outside the model's
+training distribution sets `extrapolating=True` / `in_scope=False` (the model does not generalize to unseen
+loci — labelled, not hidden). Evo2 supplies a likelihood/zero-shot *claim*-scope scalar and, separately,
+*generated DNA candidates* (output_kind=candidate → cannot enter a claim path). ChromBPNet/Borzoi are kept as
+honest baselines. Heavy backends run on-demand and are cached; when absent the adapter defers (or replays a
+committed cache entry) rather than fabricating a value.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+from pen_stack.oracles import build_result, cache_get, cache_put
+from pen_stack.oracles.schema import OracleResult
+
+# ---- hosted Evo2-40B (NVIDIA) — live path, opt-in via PEN_STACK_ORACLE_NET=1 (CI stays offline by default) ----
+_EVO2_URL = "https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate"
+
+
+def _oracle_net_enabled() -> bool:
+    """Live oracle network calls are opt-in (the deployed VM sets it; CI/offline leave it unset → deferred)."""
+    return os.getenv("PEN_STACK_ORACLE_NET") == "1"
+
+
+def _nvidia_key() -> str | None:
+    key = os.getenv("NVIDIA_API_KEY")
+    if key:
+        return key.strip()
+    from pen_stack._resources import project_root
+    f = project_root() / "configs" / "nvidia_api_key.txt"
+    return f.read_text(encoding="utf-8").strip() if f.exists() else None
+
+
+def _sanitize_dna(s: str) -> str:
+    return "".join(c for c in (s or "").upper() if c in "ACGTN")
+
+
+def _call_evo2_generate(seed: str, n: int) -> dict:
+    import requests
+    key = _nvidia_key()
+    if not key:
+        raise RuntimeError("no NVIDIA_API_KEY for hosted Evo2")
+    body = {"sequence": seed, "num_tokens": int(n), "top_k": 4, "enable_sampled_probs": True}
+    r = requests.post(_EVO2_URL, headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
+                      json=body, timeout=float(os.getenv("PEN_STACK_ORACLE_TIMEOUT", "120")))
+    r.raise_for_status()
+    return r.json()
+
+
+def _deferred_or_cached(oracle: str, model: str, inputs: dict, *, extrapolating: bool = False,
+                        in_scope: bool = True, output_kind: str | None = None,
+                        backend_note: str = "backend not installed") -> OracleResult:
+    r = build_result(oracle, model, inputs=inputs, available=False, extrapolating=extrapolating,
+                     in_scope=in_scope, output_kind=output_kind, note=backend_note)
+    hit = cache_get(r.provenance.cache_key)
+    if hit is not None:
+        return build_result(oracle, model, inputs=inputs, value=hit.get("value"),
+                            native_uncertainty=hit.get("native_uncertainty"), available=True, cached=True,
+                            source="cache", extrapolating=extrapolating, in_scope=in_scope,
+                            output_kind=output_kind, note="replayed from committed oracle cache")
+    return r
+
+
+_VAR_RE = re.compile(r"(?:(chr[\w]+)[:\s]*)?(\d+)?\s*([ACGT]+)\s*>\s*([ACGT]+)", re.I)
+_LOCUS_RE = re.compile(r"(chr[\w]+)[:\s]*(\d+)?", re.I)
+
+
+def _parse_variant(variant: str, locus: str):
+    """Parse a variant ('chr1:1000 A>T' / 'chr1:1A>T' / 'A>G' + locus 'chr19:1010000') -> (chrom,pos,ref,alt)."""
+    m = _VAR_RE.search(variant or "")
+    if not m:
+        return None
+    chrom, pos, ref, alt = m.group(1), m.group(2), m.group(3), m.group(4)
+    if not chrom or not pos:
+        lm = _LOCUS_RE.search(locus or "")
+        if lm:
+            chrom = chrom or lm.group(1)
+            pos = pos or lm.group(2)
+    if not (chrom and pos and ref and alt):
+        return None
+    return chrom, int(pos), ref.upper(), alt.upper()
+
+
+def variant_effect(variant: str, locus: str, in_distribution: bool = True) -> OracleResult:
+    """AlphaGenome variant-effect prediction, OOD-gated by `in_distribution`.
+
+    LIVE via the existing `wgenome.AlphaGenomeProvider` (real `score_variant`, REF vs ALT) when
+    `PEN_STACK_ORACLE_NET=1` and the alphagenome package + key are present; otherwise deferred / cache-replay
+    (value None, OOD gate intact, never fabricated). Reuses the v3.1 provider — no duplicate client."""
+    inputs = {"variant": variant, "locus": locus}
+    parsed = _parse_variant(variant, locus)
+    if _oracle_net_enabled() and parsed:
+        from pen_stack.wgenome.providers import AlphaGenomeProvider
+        prov = AlphaGenomeProvider()
+        if prov.available():
+            chrom, pos, ref, alt = parsed
+            try:
+                rec = prov.score_variant(chrom, pos, ref, alt)
+            except Exception as e:  # noqa: BLE001 - hosted/network; defer honestly, never fabricate
+                return _deferred_or_cached("genome", "alphagenome", inputs, extrapolating=not in_distribution,
+                                           in_scope=in_distribution,
+                                           backend_note=f"AlphaGenome score_variant failed ({type(e).__name__}); deferred")
+            if rec.get("available"):
+                return build_result(
+                    "genome", "alphagenome", inputs=inputs,
+                    value={"effect_max_abs": rec["effect_max_abs"], "effect_mean_abs": rec["effect_mean_abs"],
+                           "output": rec["output"], "n_scores": rec["n_scores"],
+                           "chrom": chrom, "position": pos, "ref": ref, "alt": alt},
+                    available=True, source="hosted_api", extrapolating=not in_distribution, in_scope=in_distribution,
+                    note=("AlphaGenome score_variant (REF vs ALT, recommended RNA_SEQ scorer): max|effect| over the "
+                          "predicted regulatory tracks. A regulatory-effect magnitude, not a claim the edit works."))
+    # deferred / cache-replay — package/key/flag absent or variant unparseable (OOD gate preserved, no fabrication)
+    return _deferred_or_cached("genome", "alphagenome", inputs, extrapolating=not in_distribution,
+                               in_scope=in_distribution,
+                               backend_note="AlphaGenome deferred (set PEN_STACK_ORACLE_NET=1 + package/key to score live)")
+
+
+def sequence_likelihood(seq: str) -> OracleResult:
+    """Evo2 zero-shot sequence likelihood — a claim-scope scalar (NOT a generated sequence)."""
+    inputs = {"seq_len": len(seq), "seq": seq.upper()}
+    try:
+        import evo2  # noqa: F401
+    except Exception:  # noqa: BLE001
+        return _deferred_or_cached("genome", "evo2", inputs, output_kind="claim",
+                                   backend_note="Evo2 backend not installed (large; on-demand)")
+    return build_result("genome", "evo2", inputs=inputs, output_kind="claim", available=False,
+                        note="Evo2 present; wire likelihood scoring for the live value")
+
+
+def generate_dna(prompt: str, n: int = 20) -> OracleResult:
+    """Evo2 generative DNA — a CANDIDATE (output_kind=candidate); cannot enter a claim path unverified.
+
+    LIVE via NVIDIA's hosted Evo2-40B when `PEN_STACK_ORACLE_NET=1` and an NVIDIA key is present: Evo2 conditions
+    on a DNA context (the seed) and extends it; the per-token model probability is surfaced as native uncertainty.
+    Otherwise deferred / cache-replay (value None, never fabricated). The result is still a CANDIDATE — a generated
+    sequence is a proposal, not a claim (`as_claim()` raises)."""
+    seed = _sanitize_dna(prompt)
+    inputs = {"prompt": prompt, "seed": seed, "n": int(n)}
+    if _oracle_net_enabled() and _nvidia_key() and seed:
+        key_obj = build_result("genome", "evo2", inputs=inputs, output_kind="candidate")
+        try:
+            resp = _call_evo2_generate(seed, n)
+        except Exception as e:  # noqa: BLE001 - hosted/network; fall back to deferred honestly (no fabrication)
+            return _deferred_or_cached("genome", "evo2", inputs, output_kind="candidate",
+                                       backend_note=f"hosted Evo2 call failed ({type(e).__name__}); deferred")
+        continuation = _sanitize_dna(resp.get("sequence", ""))     # hosted endpoint returns the continuation only
+        probs = resp.get("sampled_probs") or []
+        mean_p = (sum(probs) / len(probs)) if probs else None
+        unc = round(1.0 - mean_p, 4) if mean_p is not None else None
+        val = {"generated": continuation, "full": seed + continuation, "seed": seed,
+               "per_token_prob": probs, "n_tokens": len(continuation), "elapsed_ms": resp.get("elapsed_ms")}
+        cache_put(key_obj.provenance.cache_key, {"value": val, "native_uncertainty": unc})
+        return build_result("genome", "evo2", inputs=inputs, value=val, native_uncertainty=unc,
+                            available=True, source="hosted_api", output_kind="candidate",
+                            note=("Evo2-40B (NVIDIA hosted) extended the DNA seed; per-token model probability "
+                                  "surfaced as uncertainty. CANDIDATE — verify (writer-verification) before any claim."))
+    return _deferred_or_cached("genome", "evo2", inputs, output_kind="candidate",
+                               backend_note="Evo2 generation is a CANDIDATE; verify before any claim")
+
+
+def accessibility_baseline(locus: str) -> OracleResult:
+    """ChromBPNet/Borzoi accessibility/expression — an honest BASELINE comparator to AlphaGenome."""
+    inputs = {"locus": locus}
+    return _deferred_or_cached("genome", "chrombpnet_borzoi", inputs, output_kind="baseline",
+                               backend_note="ChromBPNet/Borzoi baseline; on-demand")

pen_stack-6.4.0/pen_stack/oracles/protein_design.py

@@ -0,0 +1,136 @@
+"""Protein-design oracles (v4.0, WS-O3) — RFdiffusion / ProteinMPNN / ESM3, all CANDIDATES.
+
+Every output here is a generative **candidate** (output_kind=candidate): a backbone, a designed sequence, or
+an ESM3 design. By the contract (`OracleResult.as_claim()` raises) and a guard test, none of these can enter a
+claim path without passing writer-verification (WS-WV) scoring against measured data — the encoded
+pen-assemble lesson (0 validatable de-novo writers; we score/critique, never assert function). Heavy backends
+run on-demand; absent → deferred candidate.
+"""
+from __future__ import annotations
+
+import os
+
+from pen_stack.oracles import build_result, cache_get, cache_put
+from pen_stack.oracles.schema import OracleResult
+
+
+def _oracle_net_enabled() -> bool:
+    """Live oracle calls are opt-in (the VM sets it; CI/offline leave it unset → deferred)."""
+    return os.getenv("PEN_STACK_ORACLE_NET") == "1"
+
+
+def _model_server(env_var: str, default: str) -> str:
+    return os.getenv(env_var, default).rstrip("/")
+
+
+def _post(url: str, payload: dict, timeout_env: str = "PEN_STACK_MODEL_TIMEOUT", default_timeout: str = "600"):
+    import requests
+    r = requests.post(url, json=payload, timeout=float(os.getenv(timeout_env, default_timeout)))
+    r.raise_for_status()
+    return r.json()
+
+
+def _candidate(model: str, inputs: dict, backend: str, note: str) -> OracleResult:
+    r = build_result("protein_design", model, inputs=inputs, available=False, output_kind="candidate", note=note)
+    hit = cache_get(r.provenance.cache_key)
+    if hit is not None:
+        return build_result("protein_design", model, inputs=inputs, value=hit.get("value"), available=True,
+                            cached=True, source="cache", output_kind="candidate",
+                            note="replayed from committed oracle cache (still a CANDIDATE)")
+    try:
+        __import__(backend)
+    except Exception:  # noqa: BLE001
+        return r
+    return build_result("protein_design", model, inputs=inputs, available=False, output_kind="candidate",
+                        note=f"{model} present; wire the generator (output stays a CANDIDATE)")
+
+
+def generate_backbone(spec: dict, model: str = "rfdiffusion") -> OracleResult:
+    """RFdiffusion / RFdiffusion-AA backbone generation — a CANDIDATE.
+
+    LIVE via the local RFdiffusion model server (`PEN_STACK_RFDIFFUSION_URL`, default localhost:9013) when
+    `PEN_STACK_ORACLE_NET=1`, the spec gives a `length` or `contigs`, and the service is up: RFdiffusion
+    diffuses a real backbone PDB (still a CANDIDATE — verify before any claim). Otherwise deferred."""
+    inputs = {"spec": spec}
+    length = (spec or {}).get("length") if isinstance(spec, dict) else None
+    contigs = (spec or {}).get("contigs") if isinstance(spec, dict) else None
+    if _oracle_net_enabled() and (length or contigs):
+        key_obj = build_result("protein_design", model, inputs=inputs, output_kind="candidate")
+        url = _model_server("PEN_STACK_RFDIFFUSION_URL", "http://localhost:9013")
+        payload = {k: v for k, v in {"length": length, "contigs": contigs,
+                                     "num_designs": spec.get("num_designs", 1)}.items() if v is not None}
+        try:
+            resp = _post(f"{url}/generate", payload, default_timeout="1200")
+        except Exception:  # noqa: BLE001 - service down → defer honestly
+            return _candidate(model, inputs, "rfdiffusion",
+                              "RFdiffusion server unreachable; deferred CANDIDATE (start the model server)")
+        designs = resp.get("designs") or []
+        val = {"designs": designs, "n": len(designs), "contigs": resp.get("contigs"),
+               "n_residues": (designs[0].get("n_residues") if designs else None)}
+        cache_put(key_obj.provenance.cache_key, {"value": val})
+        return build_result("protein_design", model, inputs=inputs, value=val, available=True,
+                            source="local_gpu", output_kind="candidate",
+                            note=("RFdiffusion diffused a backbone (local GPU). CANDIDATE — design a sequence "
+                                  "(ProteinMPNN) + verify fold/activity before any claim."))
+    return _candidate(model, inputs, "rfdiffusion",
+                      "RFdiffusion backbone is a CANDIDATE; verify before any claim")
+
+
+def design_sequence(backbone: dict, model: str = "proteinmpnn") -> OracleResult:
+    """ProteinMPNN / LigandMPNN sequence design for a fixed backbone — a CANDIDATE.
+
+    LIVE via the local ProteinMPNN model server (`PEN_STACK_PROTEINMPNN_URL`, default localhost:9011) when
+    `PEN_STACK_ORACLE_NET=1`, the backbone carries a `pdb`, and the service is up; the designed sequences are a
+    real ProteinMPNN output (still a CANDIDATE — `as_claim()` raises). Otherwise deferred / cache-replay."""
+    inputs = {"backbone": backbone}
+    pdb = (backbone or {}).get("pdb") if isinstance(backbone, dict) else None
+    if _oracle_net_enabled() and isinstance(pdb, str) and "ATOM" in pdb:
+        key_obj = build_result("protein_design", model, inputs=inputs, output_kind="candidate")
+        url = _model_server("PEN_STACK_PROTEINMPNN_URL", "http://localhost:9011")
+        try:
+            resp = _post(f"{url}/design", {"pdb": pdb, "chains": backbone.get("chains"),
+                                           "num_seqs": int(backbone.get("num_seqs", 4))})
+        except Exception:  # noqa: BLE001 - service down/unreachable → defer honestly (no fabrication)
+            return _candidate(model, inputs, "proteinmpnn",
+                              "ProteinMPNN server unreachable; deferred CANDIDATE (start the model server to design)")
+        designs = resp.get("designs") or []
+        best = min((d.get("global_score") for d in designs if d.get("global_score") is not None), default=None)
+        val = {"designs": designs, "n": len(designs), "best_global_score": best}
+        cache_put(key_obj.provenance.cache_key, {"value": val})
+        return build_result("protein_design", model, inputs=inputs, value=val, available=True,
+                            source="local_gpu", output_kind="candidate",
+                            note=("ProteinMPNN designed sequences for the backbone (local GPU). CANDIDATE — score "
+                                  "against measured data (writer-verification) before any claim."))
+    return _candidate(model, inputs, "proteinmpnn",
+                      "ProteinMPNN sequence is a CANDIDATE; score against measured data before any claim")
+
+
+def esm3_design(prompt: dict, model: str = "esm3") -> OracleResult:
+    """ESM3 generative protein design / representation — a CANDIDATE.
+
+    LIVE via the local ESM3-open model server (`PEN_STACK_ESM3_URL`, default localhost:9012) when
+    `PEN_STACK_ORACLE_NET=1`, the prompt gives a masked `sequence` or a `length`, and the service is up: ESM3
+    generates a real protein (still a CANDIDATE — verify fold/activity before any claim). Otherwise deferred."""
+    inputs = {"prompt": prompt}
+    seq = (prompt or {}).get("sequence") if isinstance(prompt, dict) else None
+    length = (prompt or {}).get("length") if isinstance(prompt, dict) else None
+    if _oracle_net_enabled() and (seq or length):
+        key_obj = build_result("protein_design", model, inputs=inputs, output_kind="candidate")
+        url = _model_server("PEN_STACK_ESM3_URL", "http://localhost:9012")
+        payload = {k: v for k, v in {"sequence": seq, "length": length,
+                                     "num_steps": prompt.get("num_steps"),
+                                     "temperature": prompt.get("temperature")}.items() if v is not None}
+        try:
+            resp = _post(f"{url}/generate", payload)
+        except Exception:  # noqa: BLE001 - service down → defer honestly
+            return _candidate(model, inputs, "esm",
+                              "ESM3 server unreachable; deferred CANDIDATE (start the model server to design)")
+        val = {"sequence": resp.get("sequence"), "length": resp.get("length"),
+               "num_steps": resp.get("num_steps"), "model": resp.get("backend")}
+        cache_put(key_obj.provenance.cache_key, {"value": val})
+        return build_result("protein_design", model, inputs=inputs, value=val, available=True,
+                            source="local_gpu", output_kind="candidate",
+                            note=("ESM3-open generated a protein sequence (local GPU). CANDIDATE — verify "
+                                  "fold/activity (writer-verification) before any claim."))
+    return _candidate(model, inputs, "esm",
+                      "ESM3 design is a CANDIDATE; verify fold/activity before any claim")