pen-stack 0.1.0__py3-none-any.whl

pen_stack/oracles/affinity.py

@@ -0,0 +1,116 @@
+"""Binding-affinity 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/oracles/cache.py

@@ -0,0 +1,53 @@
+"""Deterministic, version-pinned oracle cache + scope-card loader.
+
+Every oracle call is keyed on (oracle family, model, version, canonicalised inputs) so a cached round-trip
+reproduces committed values offline, the substrate's *core stays runnable from cache* even when a heavy
+oracle backend (AF3, Evo2, ESM3) is not installed (the compute policy). Cache entries are plain JSON
+under `oracle_cache/` (committed for offline CI).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from pen_stack._resources import project_root
+
+_CACHE_DIR = project_root() / "oracle_cache"
+
+
+def scope_cards_path() -> Path:
+    from pen_stack._resources import resource
+    return resource("configs/oracles/scope_cards.yaml")
+
+
+@lru_cache(maxsize=1)
+def load_scope_cards() -> dict:
+    return yaml.safe_load(scope_cards_path().read_text(encoding="utf-8"))["oracles"]
+
+
+def scope_card(model: str) -> dict | None:
+    return load_scope_cards().get(model)
+
+
+def cache_key(oracle: str, model: str, version: str, inputs: dict[str, Any]) -> str:
+    """A stable key over the oracle family, the pinned model+version, and canonicalised inputs."""
+    payload = json.dumps({"oracle": oracle, "model": model, "version": version, "inputs": inputs},
+                         sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode()).hexdigest()[:24]
+
+
+def cache_get(key: str) -> dict | None:
+    p = _CACHE_DIR / f"{key}.json"
+    if p.exists():
+        return json.loads(p.read_text(encoding="utf-8"))
+    return None
+
+
+def cache_put(key: str, value: dict) -> None:
+    _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    (_CACHE_DIR / f"{key}.json").write_text(json.dumps(value, indent=2, default=str), encoding="utf-8")

pen_stack/oracles/energetics.py

@@ -0,0 +1,33 @@
+"""Energetics oracle, bridge off-target relative-risk, under the oracle contract.
+
+Generalises the MC3 off-target energetics model into the mesh. The HARD GATE is unchanged: the
+energetics model ships only if its held-out AUROC beats BOTH the position-weight model on the same split AND
+the published 0.77 baseline (the eval lives in `validate.offtarget_energetics_eval`); off the VM (Perry data
+absent) the adapter returns a deferred result rather than a fabricated number.
+"""
+from __future__ import annotations
+
+from pen_stack.oracles import build_result
+from pen_stack.oracles.schema import OracleResult
+
+GATE_AUROC = 0.77
+
+
+def gate() -> OracleResult:
+    """Run the MC3 held-out discrimination eval and report whether energetics still earns its place."""
+    inputs = {"eval": "offtarget_energetics_eval", "gate": GATE_AUROC}
+    try:
+        from pen_stack.validate.offtarget_energetics_eval import run
+        rep = run()
+    except Exception as e: # noqa: BLE001 - Perry tables absent off the VM
+        return build_result("energetics", "bridge_energetics", inputs=inputs, available=False,
+                            note=f"off-target energetics eval unavailable: {type(e).__name__}: {e}")
+    if not rep.get("available", True):
+        return build_result("energetics", "bridge_energetics", inputs=inputs, available=False,
+                            note=rep.get("note", "Perry off-target tables absent (runs on the VM)"))
+    auroc = rep.get("energetics_auroc") or rep.get("model_auroc")
+    ships = bool(rep.get("ships", auroc is not None and auroc > GATE_AUROC))
+    return build_result("energetics", "bridge_energetics", inputs=inputs, value={"held_out_auroc": auroc,
+                        "beats_0_77": ships, "report": rep},
+                        native_uncertainty=None if auroc is None else round(max(0.0, 1.0 - auroc), 3),
+                        note=f"MC3 gate: ships only if held-out AUROC>{GATE_AUROC} AND > position-weight model")

pen_stack/oracles/genome.py

@@ -0,0 +1,167 @@
+"""Genome oracles, 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
+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 existing 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, 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 (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 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/oracles/protein_design.py

@@ -0,0 +1,136 @@
+"""Protein-design oracles, 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 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
+            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 (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
+            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")

pen_stack/oracles/reliability.py

@@ -0,0 +1,64 @@
+"""Per-oracle reliability registry + 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 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/oracles/rna.py

@@ -0,0 +1,28 @@
+"""RNA oracle, ViennaRNA secondary-structure fold, under the oracle contract.
+
+A thin contract wrapper over the EXISTING `bridge.fold_qc` (the ViennaRNA QC that already feeds the
+hard fold-legality rule). ViennaRNA is real and runs in the VM image; when absent the adapter returns a
+deferred `OracleResult` (available=False) rather than a fabricated structure. Fold legality remains a HARD
+rule input (it does not become a soft signal here).
+"""
+from __future__ import annotations
+
+from pen_stack.oracles import build_result
+from pen_stack.oracles.schema import OracleResult
+
+
+def fold(scaffold_seq: str) -> OracleResult:
+    """MFE fold of a bridge-RNA scaffold via ViennaRNA, wrapped in the oracle contract."""
+    from pen_stack.bridge.fold_qc import fold as _fold
+    r = _fold(scaffold_seq)
+    inputs = {"scaffold_len": len(scaffold_seq), "scaffold_seq": scaffold_seq.upper()}
+    if not r.get("available"):
+        return build_result("rna", "viennarna", inputs=inputs, available=False,
+                            note=r.get("note", "ViennaRNA not installed (runs in the VM image)"))
+    # native uncertainty proxy: a less-negative MFE per nt = a weaker, less-certain fold
+    mfe, n = float(r["mfe"]), max(1, int(r["length"]))
+    unc = max(0.0, min(1.0, 1.0 + (mfe / n) / 0.5)) # ~0 for strong folds, ->1 as MFE/nt -> 0
+    return build_result("rna", "viennarna", inputs=inputs,
+                        value={"structure": r["structure"], "mfe": r["mfe"], "length": r["length"]},
+                        native_uncertainty=round(unc, 3),
+                        note="ViennaRNA MFE fold; a hard legality input for bridge-RNA QC")