pen-stack 0.1.0__py3-none-any.whl

pen_stack/mech/classify_atlas.py

@@ -0,0 +1,71 @@
+"""Mechanism-aware classification at scale.
+
+Run the audited Pfam-whitelist classifier over the expanded Writer Atlas. For every system, derive a
+``mech_pred`` bucket + ``mech_conf`` *independently* from its Pfam domain architecture (homology), then
+compare against the inherited/audited ``mechanism_bucket`` - keeping homology and mechanism distinct, as
+the program requires. Low-confidence / conflicting / disagreeing calls are written to a review queue and
+flagged, never hidden.
+
+Inputs : pen_stack/atlas/atlas.parquet, the 18-family whitelist.
+Outputs: atlas.parquet updated with mech_pred / mech_conf / mech_basis / mech_agrees,
+         out/mech_review_queue.csv.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from pen_stack.mech.whitelist import PfamWhitelist
+
+_ROOT = Path(__file__).resolve().parents[2]
+_ATLAS = _ROOT / "pen_stack" / "atlas" / "atlas.parquet"
+_QUEUE = _ROOT / "out" / "mech_review_queue.csv"
+
+
+def classify_atlas(atlas_parquet: str | Path = _ATLAS, out: str | Path = _ATLAS,
+                   queue: str | Path = _QUEUE) -> pd.DataFrame:
+    atlas = pd.read_parquet(atlas_parquet)
+    wl = PfamWhitelist()
+
+    calls = atlas["pfam_signature"].apply(lambda s: wl.classify(list(s) if s is not None else []))
+    atlas["mech_pred"] = [c.bucket for c in calls]
+    atlas["mech_conf"] = [c.confidence for c in calls]
+    atlas["mech_basis"] = [c.basis for c in calls]
+    # agreement with the inherited/audited mechanism label (None where one side is missing)
+    atlas["mech_agrees"] = [
+        (mp == mb) if (mp is not None and pd.notna(mb)) else None
+        for mp, mb in zip(atlas["mech_pred"], atlas["mechanism_bucket"])
+    ]
+    atlas["mech_class_version"] = wl.version
+
+    # review queue: no domain evidence, conflicting evidence, or disagreement with the audited label
+    flag = (
+        atlas["mech_conf"].isin(["none", "conflicting"])
+        | atlas["mech_agrees"].eq(False) # explicit False (disagreement), not NaN
+    )
+    q = atlas.loc[flag, ["representative_system", "family", "pfam_signature",
+                         "mechanism_bucket", "mech_pred", "mech_conf", "mech_basis",
+                         "mech_agrees", "confidence"]]
+    Path(queue).parent.mkdir(parents=True, exist_ok=True)
+    q.to_csv(queue, index=False)
+
+    atlas.to_parquet(out, index=False)
+    return atlas
+
+
+def core_agreement(atlas: pd.DataFrame) -> dict:
+    """Agreement on the curated 8-family core against the audited 18-family labels."""
+    core = atlas[atlas["entry_kind"] == "curated_core"]
+    scored = core[core["mech_pred"].notna()]
+    agree = int((scored["mech_pred"] == scored["mechanism_bucket"]).sum())
+    return {"n_core": len(core), "n_scored": len(scored), "n_agree": agree,
+            "agreement": round(agree / len(scored), 4) if len(scored) else None}
+
+
+if __name__ == "__main__": # pragma: no cover
+    a = classify_atlas()
+    print("mech_conf distribution:\n", a["mech_conf"].value_counts())
+    print("\ncore agreement:", core_agreement(a))
+    n_flag = int((a["mech_conf"].isin(["none", "conflicting"]) | (a["mech_agrees"].eq(False))).sum())
+    print("\nreview queue rows:", n_flag)

pen_stack/mech/pfam_whitelist.yaml

@@ -0,0 +1,247 @@
+# Pfam whitelist v1.2.2 - PEN-STACK genome-writing enzyme families
+# AUDIT STATUS:
+# * Pfam ACCESSIONS (the entry criteria): independently verified against the InterPro/EBI API
+# (all 26 resolve with the correct domain name) on 2026-04-22 and re-confirmed 2026-06-09.
+# * example_uniprot proteins (illustrative metadata only, NOT entry criteria): on 2026-06-09 each was
+# checked against its UniProt Pfam cross-references; 13 of 22 did NOT actually contain the claimed
+# domain (e.g. a marine-worm Histone H3, a mouse mannosyltransferase, I-AniI [a LAGLIDADG enzyme]
+# mislabelled HNH, an obsolete 404 accession). ALL corrected in v1.2.2 to reviewed/curated proteins
+# whose UniProt entry genuinely carries the domain (membership re-verified).
+#
+# Verification discipline:
+# 1. InterPro API name-match against stored interpro_name (accessions)
+# 2. UniProt Pfam-xref MEMBERSHIP check for every example_uniprot (the claimed domain must be in the
+# protein's UniProt Pfam cross-references) - not just "the accession exists"
+# 3. Literature cross-check for biological relevance
+
+# Mechanism buckets (Tier A of MECH-CLASS):
+# DSB_NUCLEASE | DSB_FREE_TRANSEST_RECOMBINASE | TRANSPOSASE
+
+domains:
+  # === CRISPR-Cas Class 2 - Cas9 (multi-domain; >=2 of 3 co-occurring define Cas9) ===
+  - accession: PF13395
+    name: HNH_4
+    interpro_name: "HNH endonuclease"
+    mechanism_bucket: DSB_NUCLEASE
+    example_systems: [SpCas9, SaCas9]
+    example_uniprot: [Q99ZW2]
+    reference: "Jinek 2012 Science"
+    doi: "10.1126/science.1225829"
+    co_occurs_with: [PF18541, PF16595]
+    notes: "HNH nuclease domain found in CRISPR-related proteins (including Cas9). Not exclusively Cas9-specific - also found in other HNH endonucleases. Cleaves target DNA strand in Cas9."
+
+  - accession: PF18541
+    name: RuvC_III
+    interpro_name: "RuvC endonuclease subdomain 3"
+    mechanism_bucket: DSB_NUCLEASE
+    example_systems: [SpCas9]
+    example_uniprot: [Q99ZW2]
+    reference: "Jinek 2012 Science"
+    doi: "10.1126/science.1225829"
+    co_occurs_with: [PF13395, PF16595]
+    notes: "Cas9 RuvC subdomain 3; cleaves non-target strand. Part of composite Cas9 set. NOT the same as Cas12a RuvC (PF18516). example_uniprot Q99ZW2 IS SpCas9 (the correct biological example); UniProt annotates its RuvC under the merged Cas9 set, so the PF18541 sub-accession is not individually cross-referenced - kept because the protein genuinely bears this subdomain."
+
+  - accession: PF16595
+    name: Cas9_PI
+    interpro_name: "PAM-interacting domain of CRISPR-associated endonuclease Cas9"
+    mechanism_bucket: DSB_NUCLEASE
+    example_systems: [SpCas9]
+    example_uniprot: [Q99ZW2]
+    reference: "Nishimasu 2014 Cell"
+    doi: "10.1016/j.cell.2014.02.001"
+    co_occurs_with: [PF13395, PF18541]
+    notes: "PAM-interacting domain; recognises NGG PAM in SpCas9. Part of composite Cas9 set."
+
+  # === CRISPR-Cas Class 2 - Cas12a (RuvC-only single lobe) ===
+  - accession: PF18516
+    name: RuvC_1
+    interpro_name: "RuvC nuclease domain"
+    mechanism_bucket: DSB_NUCLEASE
+    example_systems: [AsCas12a, LbCas12a, FnCas12a]
+    example_uniprot: [U2UMQ6]
+    reference: "Zetsche 2015 Cell; Yamano 2016 Cell"
+    doi: "10.1016/j.cell.2015.09.038"
+    notes: "Cas12a RuvC nuclease domain. Single-lobe architecture; produces staggered cuts. Distinct from Cas9 RuvC (PF18541)."
+
+  # === IS110 / Bridge Recombinase composite (both domains required) ===
+  - accession: PF01548
+    name: DEDD_Tnp_IS110
+    interpro_name: "Transposase"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [ISCro4, IS621, IS110]
+    example_uniprot: [D2TGM5] # ISCro4 transposase (carries PF01548 + PF02371) - the bridge recombinase
+    reference: "Durrant 2024 Nature; Hiraizumi 2024 Nature"
+    doi: "10.1038/s41586-024-07552-4"
+    co_occurs_with: [PF02371]
+    notes: "N-terminal RuvC-fold DEDD catalytic domain of IS110/IS1111 transposases. Paired with PF02371 CTD. Uses bridge/seeker RNA for targeting."
+
+  - accession: PF02371
+    name: Transposase_20
+    interpro_name: "Transposase IS116/IS110/IS902 family"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [ISCro4, IS621, IS110, IS1111]
+    example_uniprot: [D2TGM5] # ISCro4 transposase (carries PF01548 + PF02371)
+    reference: "InterPro: Transposase IS116/IS110/IS902 family (PF01548 + PF02371)"
+    doi: null # the previously-listed Prudhomme 2002 J Bacteriol DOI did not resolve; classification rests on the Pfam domains
+    co_occurs_with: [PF01548]
+    notes: "C-terminal CTD of IS110 transposase. Contains HHH motif. DEDD chemistry (not serine recombinase). DNA binding + complex assembly."
+
+  # === TnpB / IscB / Fanzor ancestor family ===
+  - accession: PF07282
+    name: Cas12f1-like_TNB
+    interpro_name: "Cas12f1-like, TNB domain"
+    mechanism_bucket: DSB_NUCLEASE
+    example_systems: [ISDra2_TnpB, IscB, Fanzor1, Fanzor2]
+    example_uniprot: [Q7DF80]
+    reference: "Altae-Tran 2021 Science; Saito 2023 Nature"
+    doi: "10.1126/science.abj6856"
+    notes: "C-terminal zinc-ribbon / TNB domain of TnpB/IscB/Fanzor/Cas12f umbrella. Formerly called OrfB_Zn_ribbon. Broad ancestral marker; specific Fanzor/Cas12f ID needs structural features (Paper 2)."
+
+  # === Classical DDE transposases ===
+  - accession: PF00665
+    name: rve
+    interpro_name: "Integrase core domain"
+    mechanism_bucket: TRANSPOSASE
+    example_systems: [HIV_integrase, TnsB]
+    example_uniprot: [P03366] # HIV-1 Gag-Pol (integrase, rve core); Tn3 P03008 removed (it is PF01526, not rve)
+    reference: "Rice & Mizuuchi 1995 Cell"
+    doi: "10.1016/0092-8674(95)90308-9"
+    notes: "RNase H / integrase core fold (rve superfamily). Shared by retroviral integrases and TnsB of Tn7. TnsB specificity comes from co-occurrence with TnsA (PF08721)."
+
+  - accession: PF01609
+    name: DDE_Tnp_1
+    interpro_name: "Transposase DDE domain"
+    mechanism_bucket: TRANSPOSASE
+    example_systems: [Tn5, IS3_family, IS4_family]
+    example_uniprot: [Q46731] # Tn5 transposase (carries PF01609); was P03008 (Tn3, PF01526 - wrong fold)
+    reference: "Reznikoff 2008 Annu Rev Genet"
+    doi: "10.1146/annurev.genet.42.110807.091656"
+    notes: "Canonical DDE transposase catalytic domain. Found in Tn5 and many insertion sequences."
+
+  - accession: PF13586
+    name: DDE_Tnp
+    interpro_name: "Transposase DDE domain"
+    mechanism_bucket: TRANSPOSASE
+    example_systems: [DDE_transposases_diverse]
+    example_uniprot: [A0A009P861] # Transposase DDE-domain protein (carries PF13586); was Q9U6K4 (Histone H3 - wrong)
+    reference: "Chandler 2013 Nat Rev Microbiol"
+    doi: "10.1038/nrmicro3067"
+    notes: "Additional DDE transposase domain family. Generic DDE-fold diversity - not exclusively hAT or Mariner. Complements PF01609 coverage."
+
+  # === Tn7 and CAST (I-F and V-K) system components ===
+  - accession: PF08721
+    name: Tn7_Tnp_TnsA_C
+    interpro_name: "TnsA endonuclease C terminal"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [Tn7, CAST-I-F]
+    example_uniprot: [P13988] # Tn7 TnsA (carries PF08721); was P13990 (obsolete/404)
+    reference: "Hickman 2000 Mol Cell"
+    doi: "10.1016/S1097-2765(00)80267-1"
+    notes: "TnsA endonuclease C-terminal domain. Cleaves 5' transposon end. CAST V-K lacks TnsA; detect via TnsB+TnsC co-occurrence instead."
+
+  - accession: PF11426
+    name: TnsC
+    interpro_name: "Tn7 transposition regulator TnsC"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [Tn7, CAST-I-F, CAST-V-K]
+    example_uniprot: [P05846]
+    reference: "Hoffmann 2022 Nature; Peters 2017 PNAS"
+    doi: "10.1038/s41586-022-05059-4"
+    notes: "AAA+ ATPase regulator of Tn7 transposition. Bridges target selection (TniQ/Cascade) and transposase (TnsB). Core to all CAST systems. CORRECTED from PF03400 (was IS1 transposase - completely unrelated)."
+
+  - accession: PF05621
+    name: TniB
+    interpro_name: "Bacterial TniB protein"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [Tn5053, Tn7-related_targeting]
+    example_uniprot: [A0A059KVU2] # AAA+ ATPase / TniB (carries PF05621); was P0CW70 (mouse mannosyltransferase - wrong)
+    reference: "Kholodii 1993 J Mol Biol (Tn5053)"
+    doi: "10.1006/jmbi.1993.1228"
+    notes: "TniB P-loop NTPase. Related to TnsC-family regulators but distinct protein. Found in Tn5053 and related Tn7-like elements."
+
+  # === Site-specific recombinases ===
+  - accession: PF00589
+    name: Phage_integrase
+    interpro_name: "Phage integrase family"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [Cre, Flp, lambda-Int, XerC, XerD]
+    example_uniprot: [P06956, P03700]
+    reference: "Grainge 2002 J Mol Biol"
+    doi: "10.1016/S0022-2836(02)00517-X"
+    notes: "Tyrosine recombinase family. 5'-phosphotyrosine covalent intermediate."
+
+  - accession: PF00239
+    name: Resolvase
+    interpro_name: "Resolvase, N terminal domain"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [gamma-delta_resolvase, Sin, Tn3_resolvase]
+    example_uniprot: [P03012, P20384] # gamma-delta (Tn3) resolvase + Tn552 invertase; was P03016 (no Pfam xref)
+    reference: "Smith 2004 Mol Microbiol"
+    doi: "10.1111/j.1365-2958.2003.03927.x"
+    notes: "Small serine recombinase family. 5'-phosphoserine covalent intermediate."
+
+  - accession: PF07508
+    name: Recombinase
+    interpro_name: "Recombinase"
+    mechanism_bucket: DSB_FREE_TRANSEST_RECOMBINASE
+    example_systems: [Bxb1, phiC31, TP901-1, R4]
+    example_uniprot: [Q9B086] # Bxb1 serine integrase (carries PF07508); was O25753/Q9T1S6 (no Pfam xref - wrong)
+    reference: "Stark 2014 Microbiol Spectr"
+    doi: "10.1128/microbiolspec.MDNA3-0046-2014"
+    notes: "Large serine integrase family. Used in eePASSIGE and landing-pad strategies."
+
+  # === Other DNA-cleaving enzymes relevant to genome writing ===
+  - accession: PF01844
+    name: HNH
+    interpro_name: "HNH endonuclease"
+    mechanism_bucket: DSB_NUCLEASE
+    example_systems: [McrA, HNH_endonucleases]
+    example_uniprot: [P24200] # E. coli McrA, an HNH endonuclease (carries PF01844); was P03880 (I-AniI, a LAGLIDADG enzyme - wrong fold)
+    reference: "Stoddard 2011 Structure"
+    doi: "10.1016/j.str.2010.12.005"
+    notes: "Standalone HNH endonuclease family. Distinct from HNH_4 (PF13395). Appears in IscB and homing endonucleases."
+
+  - accession: PF02486
+    name: Rep_3
+    interpro_name: "Replication initiation factor"
+    mechanism_bucket: TRANSPOSASE
+    example_systems: [IS91, ISCR, helitrons, rolling-circle_initiators]
+    example_uniprot: [P03064] # Staph rolling-circle Rep initiator (carries PF02486); was P03856 (PF01051, not PF02486)
+    reference: "Chandler 2013 Nat Rev Microbiol"
+    doi: "10.1038/nrmicro3067"
+    notes: "HUH-domain rolling-circle replication initiator. 5'-phosphotyrosine intermediate. Covers IS91 / ISCR / helitron families."
+
+# === Auxiliary domains (NOT entry criteria - recorded if co-occurring with primary) ===
+auxiliary:
+  - accession: PF18061
+    name: WED
+    interpro_name: "CRISPR-Cas9 WED domain"
+    notes: "Wedge domain between REC and NUC lobes in Cas9."
+  - accession: PF16592
+    name: REC_lobe
+    interpro_name: "REC lobe of CRISPR-associated endonuclease Cas9"
+    notes: "Alpha-helical recognition lobe of Cas9. CORRECTED from PF18543 (was unrelated intracellular delivery domain)."
+  - accession: PF16593
+    name: Bridge_helix
+    interpro_name: "Bridge helix of CRISPR-associated endonuclease Cas9"
+    notes: "Arginine-rich helix connecting REC and NUC lobes in Cas9."
+  - accession: PF13639
+    name: ZnF_RING
+    interpro_name: "Ring finger domain"
+    notes: "RING/zinc-finger; sometimes appears in engineered fusions."
+  - accession: PF03377
+    name: TAL_effector
+    interpro_name: "TAL effector repeat"
+    notes: "TALE repeat - outgroup comparison for programmable DNA binding. CORRECTED from PF03374 (was KilAC phage antirepressor)."
+
+# === Version metadata ===
+version: "1.2.2"
+created: "2026-04-22"
+previous_version: "1.2.1"
+curator: "Anees Ahmed"
+audit_status: "Pfam accessions verified vs InterPro API; example_uniprot membership re-verified vs UniProt Pfam cross-references on 2026-06-09 (13 wrong example proteins corrected)"
+change_log:
+  - "2026-06-09 v1.2.2: example_uniprot MEMBERSHIP audit (UniProt Pfam xrefs). 13/22 example proteins did not contain their claimed domain despite the v1.2.1 header claiming a spot-check; all corrected to proteins whose UniProt entry carries the domain: PF01548/PF02371 Q8X7L4->D2TGM5 (ISCro4); PF00665 dropped P03008 (Tn3, not rve), kept P03366; PF01609 P03008->Q46731 (Tn5); PF13586 Q9U6K4 (Histone H3!)->A0A009P861; PF08721 P13990 (404)->P13988 (Tn7 TnsA); PF05621 P0CW70 (mouse mannosyltransferase)->A0A059KVU2; PF00239 P03016->P03012 (gamma-delta resolvase); PF07508 O25753/Q9T1S6->Q9B086 (Bxb1 integrase); PF01844 P03880 (I-AniI, LAGLIDADG)->P24200 (McrA HNH); PF02486 P03856->P03064. PF18541 kept Q99ZW2 (SpCas9; merged-xref granularity, documented). Pfam accessions themselves all re-confirmed correct."
+  - "2026-04-22 v1.2.0: Comprehensive audit. Replaced 13 incorrect/mismatched accessions from v1.1.0."
+  - "2026-04-22 v1.1.0: Added DOIs; fixed 3 reference mismatches."
+  - "2026-04-22 v1.0.0: Initial release."

pen_stack/mech/whitelist.py

@@ -0,0 +1,66 @@
+"""The InterPro-audited 18-family Pfam whitelist (imported from genome-atlas v1.2.1).
+
+Tier-A of MECH-CLASS: maps a Pfam domain architecture to a mechanism bucket
+(``DSB_NUCLEASE`` / ``DSB_FREE_TRANSEST_RECOMBINASE`` / ``TRANSPOSASE``) using domain presence plus
+*composite co-occurrence rules* (e.g. Cas9 requires >=2 of its 3 signature domains; IS110 requires
+both PF01548 and PF02371). This is the audited backbone the program carries forward (Section 9); the retired
+ESM-2 discovery head is not used - domain evidence is the load-bearing mechanism signal.
+
+The source YAML ``pfam_whitelist.yaml`` is the genome-atlas asset, accessions verified against InterPro
+on 2026-04-22 (v1.2.1 corrected three v1.2.0 accession errors).
+"""
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+_WL_PATH = Path(__file__).resolve().parent / "pfam_whitelist.yaml"
+
+# Composite architectures: a call is only "composite-grade" (highest confidence) when the required
+# co-occurring domains are all present. Derived from the whitelist co_occurs_with fields.
+_COMPOSITES = {
+    "Cas9": {"min": 2, "of": {"PF13395", "PF18541", "PF16595"}, "bucket": "DSB_NUCLEASE"},
+    "IS110_bridge": {"min": 2, "of": {"PF01548", "PF02371"}, "bucket": "DSB_FREE_TRANSEST_RECOMBINASE"},
+}
+
+
+@dataclass(frozen=True)
+class MechCall:
+    bucket: str | None # mechanism bucket, or None if no whitelisted domain present
+    confidence: str # composite | single | conflicting | none
+    basis: str # human-readable evidence trail
+    matched: tuple[str, ...] # whitelisted accessions that fired
+
+
+class PfamWhitelist:
+    def __init__(self, path: str | Path = _WL_PATH):
+        doms = yaml.safe_load(Path(path).read_text(encoding="utf-8"))["domains"]
+        self.bucket_of: dict[str, str] = {d["accession"]: d["mechanism_bucket"] for d in doms}
+        self.name_of: dict[str, str] = {d["accession"]: d.get("name", "") for d in doms}
+        self.version = "1.2.1"
+
+    def classify(self, pfam_signature) -> MechCall:
+        """Mechanism from a Pfam domain set - independent of any inherited/family label."""
+        sig = {str(a).strip() for a in (pfam_signature or []) if str(a).strip()}
+        hits = sorted(sig & set(self.bucket_of))
+        if not hits:
+            return MechCall(None, "none", "no whitelisted Pfam domain present", ())
+
+        # composite rule wins (most specific, highest confidence)
+        for name, rule in _COMPOSITES.items():
+            present = sig & rule["of"]
+            if len(present) >= rule["min"]:
+                return MechCall(rule["bucket"], "composite",
+                                f"{name}: {len(present)}/{len(rule['of'])} signature domains "
+                                f"({','.join(sorted(present))})", tuple(hits))
+
+        buckets = Counter(self.bucket_of[a] for a in hits)
+        top, n = buckets.most_common(1)[0]
+        if len(buckets) > 1:
+            return MechCall(top, "conflicting",
+                            f"mixed domain evidence: {dict(buckets)}", tuple(hits))
+        return MechCall(top, "single",
+                        f"single-bucket domain evidence: {','.join(hits)}", tuple(hits))

pen_stack/monitor/__init__.py

@@ -0,0 +1 @@
+"""pen_stack.monitor - see the PEN-STACK program doc."""

pen_stack/monitor/europepmc.py

@@ -0,0 +1,32 @@
+"""Europe PMC client for the living-literature monitor.
+
+Europe PMC is the right primary source: open REST API, full-text + preprints, no licence friction.
+This module only *fetches* - triage + queueing live in triage.py / run.py.
+"""
+from __future__ import annotations
+
+import time
+import urllib.parse
+import urllib.request
+from io import BytesIO
+import json
+
+EPMC = "https://www.ebi.ac.uk/europepmc/webservices/rest/search"
+
+
+def search(query: str, since_date: str | None = None, page_size: int = 100,
+           timeout: int = 30, retries: int = 3) -> list[dict]:
+    """Search Europe PMC. ``since_date`` (YYYY-MM-DD) filters on first publication date."""
+    q = query if not since_date else f"{query} AND FIRST_PDATE:[{since_date} TO *]"
+    params = {"query": q, "format": "json", "pageSize": page_size, "resultType": "core"}
+    url = EPMC + "?" + urllib.parse.urlencode(params)
+    last = None
+    for attempt in range(retries):
+        try:
+            with urllib.request.urlopen(url, timeout=timeout) as r:
+                data = json.load(BytesIO(r.read()))
+            return data.get("resultList", {}).get("result", [])
+        except Exception as e: # noqa: BLE001 - network best-effort
+            last = e
+            time.sleep(2 * (attempt + 1))
+    raise RuntimeError(f"Europe PMC search failed for {query!r}: {last}")

pen_stack/monitor/run.py

@@ -0,0 +1,57 @@
+"""The living-literature monitor orchestrator - the Europe PMC living-database engine.
+
+Poll Europe PMC for every writer-family query, triage each hit into a candidate row (always cited),
+de-duplicate, and write a human-reviewed curation queue. The atlas is **never** auto-edited; accepted
+entries flow into the WT-KB/atlas with confidence=inferred only after a human accepts them.
+
+Back-test: with ``back_test=True`` and a date window covering March 2026, the engine must surface the
+known recent writer ISPpu10 (Europe PMC PPR1218813) into the queue - the pre-registered success check.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from pen_stack.monitor.europepmc import search
+from pen_stack.monitor.triage import _load_cues, triage_hit
+
+_OUT = Path(__file__).resolve().parents[2] / "out" / "monitor_queue.csv"
+
+
+def run_monitor(since: str = "2026-01-01", page_size: int = 50, back_test: bool = False,
+                out: str | Path = _OUT, cfg_path: str | Path | None = None) -> dict:
+    cfg = _load_cues(cfg_path) if cfg_path else _load_cues()
+    rows, n_hits = [], 0
+    for q in cfg["queries"]:
+        try:
+            hits = search(q["terms"], since_date=since, page_size=page_size)
+        except RuntimeError:
+            continue
+        n_hits += len(hits)
+        for h in hits:
+            rows.append(triage_hit(h, default_family=q.get("family"), cfg=cfg))
+
+    queue = pd.DataFrame(rows)
+    if not queue.empty:
+        queue = queue.drop_duplicates(subset=["source_id"]).reset_index(drop=True)
+        # every queued candidate must carry a citation (source_id or doi)
+        queue = queue[queue["source_id"].notna() | queue["doi"].notna()]
+
+    Path(out).parent.mkdir(parents=True, exist_ok=True)
+    queue.to_csv(out, index=False)
+
+    res = {"since": since, "n_hits": n_hits, "n_candidates": int(len(queue)), "queue": str(out)}
+    if back_test:
+        found = False
+        if not queue.empty:
+            blob = (queue["title"].fillna("") + " " + queue["source_id"].fillna("")).str.lower()
+            found = bool(blob.str.contains("isppu10").any() or
+                         (queue["source_id"] == "PPR1218813").any())
+        res["isppu10_found"] = found
+    return res
+
+
+if __name__ == "__main__": # pragma: no cover
+    r = run_monitor(since="2026-01-01", back_test=True)
+    print(r)

pen_stack/monitor/triage.py

@@ -0,0 +1,63 @@
+"""Triage Europe PMC hits into candidate writer-system rows.
+
+Grounded extraction: pull candidate fields (family, organism cue, human-cell evidence) from a hit's
+title/abstract using documented keyword cues, **always** carrying the source citation (Europe PMC id +
+DOI). An optional LLM pass (Ollama/Qwen via litellm) can enrich the abstract extraction, but it never
+invents a citation and never auto-edits the atlas - its output is just another candidate for the queue.
+
+The rule-based path is the reliable default (works offline, fully reproducible, satisfies the back-test).
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import yaml
+
+_CFG = Path(__file__).resolve().parents[2] / "configs" / "monitor_queries.yaml"
+
+
+def _load_cues(path: str | Path = _CFG) -> dict:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+
+
+def classify_family(text: str, cfg: dict) -> tuple[str | None, list[str]]:
+    """Best-guess writer family from keyword cues; returns (family, matched_cues)."""
+    t = text.lower()
+    best, best_hits = None, []
+    for fam, cues in cfg.get("family_cues", {}).items():
+        hits = [c for c in cues if c in t]
+        if len(hits) > len(best_hits):
+            best, best_hits = fam, hits
+    return best, best_hits
+
+
+def has_human_cell_evidence(text: str, cfg: dict) -> bool:
+    t = text.lower()
+    return any(cue in t for cue in cfg.get("human_cell_cues", []))
+
+
+_ORG_RE = re.compile(r"\b([A-Z][a-z]+ [a-z]{3,})\b") # coarse "Genus species" cue
+
+
+def triage_hit(hit: dict, default_family: str | None = None, cfg: dict | None = None) -> dict:
+    """Return a candidate row for the curation queue. Always carries a citation; never auto-edits."""
+    cfg = cfg or _load_cues()
+    title = hit.get("title", "") or ""
+    abstract = hit.get("abstractText", "") or ""
+    text = f"{title}. {abstract}"
+    fam, cues = classify_family(text, cfg)
+    org = _ORG_RE.search(abstract)
+    return {
+        "candidate_family": fam or default_family,
+        "matched_cues": ";".join(cues),
+        "organism_cue": org.group(1) if org else None,
+        "human_cell_evidence": has_human_cell_evidence(text, cfg),
+        "title": title[:300],
+        "source_id": hit.get("id"),
+        "source_db": hit.get("source"),
+        "doi": hit.get("doi"),
+        "pub_date": hit.get("firstPublicationDate"),
+        "confidence": "inferred", # candidate - stays inferred until a human reviews/measures
+        "status": "pending_review", # NEVER auto-accepted into the atlas
+    }

pen_stack/oracles/__init__.py

@@ -0,0 +1,65 @@
+"""The L1 oracle mesh, one contract over the biomolecular foundation models.
+
+`pen_stack.oracles` wraps AlphaGenome / Evo2 / structure predictors (AF3, Boltz-2, Chai-1, Protenix) /
+protein-design models (ESM3, RFdiffusion, ProteinMPNN) / ViennaRNA / the bridge energetics model under a
+single `OracleResult` contract (value + provenance + native uncertainty + scope card). Heavy backends run
+on-demand (hosted API / local GPU) and are cached + version-pinned; when a backend is absent the adapter
+returns a *deferred* result (available=False), the core stays runnable offline from cache.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pen_stack.oracles.cache import cache_get, cache_key, cache_put, scope_card
+from pen_stack.oracles.schema import OracleResult, Provenance
+
+__all__ = ["OracleResult", "Provenance", "build_result", "consensus", "assert_claimable",
+           "cache_get", "cache_key", "cache_put", "scope_card"]
+
+
+def build_result(oracle: str, model: str, *, value: Any = None, inputs: dict | None = None,
+                 native_uncertainty: float | None = None, available: bool = True, cached: bool = False,
+                 source: str = "adapter", extrapolating: bool = False, in_scope: bool = True,
+                 output_kind: str | None = None, note: str | None = None) -> OracleResult:
+    """Assemble an `OracleResult`, filling version / output_kind / scope from the model's scope card.
+
+    `output_kind` defaults to the scope card's, but may be overridden per call (e.g. an Evo2 *likelihood*
+    score is a claim-scope scalar, while an Evo2 *generated sequence* is a candidate)."""
+    card = scope_card(model) or {}
+    key = cache_key(oracle, model, card.get("version", "0"), inputs or {})
+    return OracleResult(
+        oracle=oracle, value=value,
+        provenance=Provenance(model=model, version=card.get("version", "0"), source=source, cache_key=key),
+        native_uncertainty=native_uncertainty,
+        scope_card=model, in_scope=in_scope, extrapolating=extrapolating,
+        output_kind=output_kind or card.get("output_kind", "claim"),
+        available=available, cached=cached, note=note)
+
+
+def assert_claimable(result: OracleResult) -> OracleResult:
+    """Guard: a generative candidate cannot enter a claim path without writer-verification (Principle 1)."""
+    return result.as_claim()
+
+
+def consensus(results: list[OracleResult], oracle: str = "structure") -> OracleResult:
+    """Cross-oracle self-consistency (Principle 3): agreement is a confidence signal, **divergence
+    widens the interval**. Combines redundant numeric oracles (e.g. AF3 / Boltz-2 / Chai-1 / Protenix); the
+    reported native_uncertainty is increased by the spread across the available oracles."""
+    avail = [r for r in results if r.available and isinstance(r.value, (int, float))]
+    if not avail:
+        return build_result(oracle, "consensus", available=False,
+                            note="no available numeric oracle to combine")
+    vals = [float(r.value) for r in avail]
+    mean = sum(vals) / len(vals)
+    spread = (max(vals) - min(vals)) if len(vals) > 1 else 0.0
+    base_unc = max((r.native_uncertainty or 0.0) for r in avail)
+    card = scope_card("boltz-2") or {}
+    return OracleResult(
+        oracle=oracle, value=round(mean, 4),
+        provenance=Provenance(model="consensus", version=card.get("version", "0"), source="adapter",
+                              extra={"members": [r.provenance.model for r in avail], "spread": round(spread, 4)}),
+        # disagreement widens the interval: native uncertainty + half the cross-oracle spread
+        native_uncertainty=round(base_unc + 0.5 * spread, 4),
+        scope_card="boltz-2", in_scope=all(r.in_scope for r in avail),
+        extrapolating=any(r.extrapolating for r in avail), output_kind="claim",
+        available=True, note=f"consensus of {len(avail)} oracles; spread {round(spread, 4)} widens the interval")