merge: feat/phase1-knowledge-specialist-s2 — the five knowledge endpoints (drugs_for_targets, trials_for_genes, annotate_genes, pathways_for_genes, targets_for_disease), gradio_ui with the machine gate, frozen descriptor; 11 cassettes recorded live (Phase 0 Q1-Q9 replay), 8 pinned schemas, loaded set 12 -> 8; D5-A pillow acceptance until 2026-11-20; 238 passed; scan clean

.gitleaksignore

@@ -0,0 +1,3 @@
+# Exact-fingerprint acceptances of verified gitleaks false positives (security/ACCEPTED-FINDINGS.md §1).
+# One finding per line; never a path or rule wildcard.
+97e7d80cbcef56eaa6e8deec780a1b7b27532a30:security/ACCEPTED-FINDINGS.md:generic-api-key:13

README.md

@@ -19,18 +19,18 @@ analysis**: it reads no dataset and computes no statistic. Built per
 [ADR-0001](docs/adr/ADR-0001-knowledge-specialist-contract.md) on a pinned, allow-listed subset
 of [ToolUniverse](https://github.com/mims-harvard/ToolUniverse) (Apache-2.0).
 
-> **Status: Phase 1, slice s1 — the governed core only.** The endpoints, the Gradio app and the
-> deploy descriptor arrive in s2; there is no Space yet. See
-> [the plan](docs/plans/PLAN-phase1-knowledge-specialist.md).
+> **Status: Phase 1, slice s2 — the five endpoints, the Gradio app and the frozen deploy
+> descriptor, replayed against the Phase 0 lookups recorded live.** There is no Space yet (s3).
+> See [the plan](docs/plans/PLAN-phase1-knowledge-specialist.md).
 
-## What it will answer (s2)
+## What it answers
 
 | Endpoint | What | Sources |
 |---|---|---|
-| `drugs_for_targets` | Drugs and clinical candidates per target, with mechanism and maximum clinical stage | HGNC → Open Targets; ChEMBL |
-| `trials_for_genes` | ClinicalTrials.gov studies whose intervention matches the gene | ClinicalTrials.gov |
-| `annotate_genes` | Approved name, UniProt accession, protein name, function, subcellular location | HGNC, UniProt |
-| `pathways_for_genes` | Reactome pathways each gene belongs to (membership, not enrichment) | UniProt → Reactome |
+| `drugs_for_targets` | Drugs and clinical candidates per target, with maximum clinical stage; ChEMBL mechanisms for the 30 most advanced | HGNC → Open Targets; ChEMBL |
+| `trials_for_genes` | ClinicalTrials.gov studies whose intervention name matches the gene, with the exact query run | ClinicalTrials.gov |
+| `annotate_genes` | Approved name, locus type, UniProt accession, protein name, function, subcellular location | HGNC, UniProt |
+| `pathways_for_genes` | Reactome lowest-level pathways each gene belongs to, and those all share (membership, not enrichment) | HGNC → Reactome |
 | `targets_for_disease` | Top associated targets, with Open Targets' own association score | Open Targets |
 
 Which TFs or pathways are active, which genes are differentially expressed and which gene sets
@@ -62,7 +62,8 @@ are enriched in a dataset are DecoupleRpy's questions; the literature corpus is
 
 ```bash
 uv venv --python 3.12 .venv && uv pip install -r requirements-dev.txt
-python -m pytest                 # hermetic: outbound sockets are blocked
+python -m pytest                 # hermetic: outbound sockets are blocked; recorded cassettes
+python scripts/record_fixtures.py   # the ONLY live step: re-record cassettes (review the diff)
 make security-scan               # ADR-0014: pip-audit, bandit, gitleaks (trivy N/A)
 make install-hooks               # the pre-push security gate, once per clone
 ```

config/tools_allowlist.yaml

@@ -12,8 +12,10 @@
 # and why. Never add an agentic/LLM-backed tool, the tool finder, a remote MCP server, a
 # web-search backend or a key-gated tool — tests/test_allowlist.py refuses each of those.
 #
-# The five endpoints are built in s2; their tool sets are fixed here so the loaded surface is
-# reviewable before any endpoint code exists.
+# s2 (2026-10-20) narrowed the loaded set from 12 to 8 once the real responses were seen: HGNC
+# returns each gene's Ensembl id and UniProt accession, one batched UniProt_search returns name,
+# function and location for up to 100 accessions, and Reactome's UniProt mapping already returns
+# the lowest-level pathways. The four tools no longer used stay approved (`endpoints: []`).
 
 tooluniverse_version: "1.5.6"
 
@@ -65,20 +67,20 @@ tools:
   # --- UniProt (4) ---
   - name: UniProt_search
     source: uniprot
-    endpoints: [annotate_genes, pathways_for_genes]
+    endpoints: [annotate_genes]
     review: "memo 2026-10-12, approved 2026-10-13 — symbol to reviewed human accession (Phase 0 Q4)"
   - name: UniProt_get_function_by_accession
     source: uniprot
-    endpoints: [annotate_genes]
-    review: "memo 2026-10-12, approved 2026-10-13 — function (Phase 0 Q3)"
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — function (Phase 0 Q3); s2 2026-10-20: not loaded, one batched UniProt_search returns this field for every gene"
   - name: UniProt_get_recommended_name_by_accession
     source: uniprot
-    endpoints: [annotate_genes]
-    review: "memo 2026-10-12, approved 2026-10-13 — recommended protein name"
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — recommended protein name; s2 2026-10-20: not loaded, one batched UniProt_search returns this field for every gene"
   - name: UniProt_get_subcellular_location_by_accession
     source: uniprot
-    endpoints: [annotate_genes]
-    review: "memo 2026-10-12, approved 2026-10-13 — subcellular location"
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — subcellular location; s2 2026-10-20: not loaded, one batched UniProt_search returns this field for every gene"
 
   # --- ClinicalTrials.gov (3) ---
   - name: ClinicalTrials_search_studies
@@ -119,8 +121,8 @@ tools:
     review: "memo 2026-10-12, approved 2026-10-13 — one pathway"
   - name: Reactome_get_pathways_low_entity
     source: reactome
-    endpoints: [pathways_for_genes]
-    review: "memo 2026-10-12, approved 2026-10-13 — lowest-level pathways for an entity (ADR-0001 §4)"
+    endpoints: []
+    review: "memo 2026-10-12, approved 2026-10-13 — lowest-level pathways for an entity (ADR-0001 §4); s2 2026-10-20: not loaded, Reactome_map_uniprot_to_pathways already returns the lowest-level pathways"
 
   # --- DGIdb (3) ---
   - name: DGIdb_get_drug_gene_interactions
@@ -139,7 +141,7 @@ tools:
   # --- HGNC (2) ---
   - name: HGNC_fetch_gene_by_symbol
     source: hgnc
-    endpoints: [drugs_for_targets, annotate_genes]
+    endpoints: [drugs_for_targets, annotate_genes, pathways_for_genes]
     review: "memo 2026-10-12, approved 2026-10-13 — approved symbol, name and Ensembl id"
   - name: HGNC_search_genes
     source: hgnc

deploy/orchestrator_registration.yaml

@@ -0,0 +1,83 @@
+# Registration descriptor for pdac-analysis-orchestrator's agents.yaml.
+# Endpoint names and parameter order are FROZEN (ADR-0001 §4) — tests/test_deploy_surface.py
+# cross-checks them against the gr.api surface and src/endpoints.ENDPOINTS. The dev twin is NOT
+# a registration target; dev routing is the orchestrator's HF_SPACE_PDAC_KNOWLEDGE_AGENT override.
+
+id: pdac_knowledge_agent
+name: "PDAC Knowledge Agent"
+dispatch_kind: tool_server
+space: "anne-voigt/pdac-knowledge-agent"
+space_dev: "anne-voigt/pdac-knowledge-agent-dev"
+# The boundary sentence, verbatim from ADR-0001 §3 (also the routing prompt's).
+description: >
+  Looks up what public knowledge bases say about named genes, drugs, diseases and trials
+  (Open Targets, ChEMBL, UniProt, ClinicalTrials.gov, Reactome, HGNC). It returns annotation,
+  never analysis: it reads no dataset and computes no statistic. Which genes are differentially
+  expressed, which TFs or pathways are active, and which gene sets are enriched in a dataset are
+  DecoupleRpy's questions. The literature corpus belongs to lit-agent.
+
+# Payload contract: JSON string; status ∈ {ok, refused, error, denied} + reason/message on non-ok;
+# run_id on ok/refused/error (denials mint none). Every ok payload has kind: "annotation" and NO
+# hierarchy or n_for_inference — a row count is never a sample size. Every row carries a
+# provenance block {source, source_tool, tooluniverse_version, query, source_ref, source_url,
+# retrieved_at, cache, licence, licence_url}; nested blocks (mechanisms, protein, disease) carry
+# their own. Also on every ok payload: unresolved[], source_errors[] (reason ∈
+# source_unavailable | rate_limited | upstream_schema_drift), coverage_notes[], attribution[],
+# a deterministic narrative ("According to <source> (queried <date>) …") and a disclaimer.
+# RELAY the narrative and coverage notes; never add a drug, trial or gene the rows do not hold.
+# Inputs are identifiers only (ADR-0001 §6): free text, sample ids and numbers are refused as
+# invalid_identifier, more than 100 identifiers as too_many_identifiers.
+# Machine auth: x-orchestrator-token header.
+tools:
+  - name: drugs_for_targets
+    api_name: "/drugs_for_targets"
+    params: [genes]
+    description: >
+      Drugs and clinical candidates per target, from Open Targets, each with its maximum clinical
+      stage and indications, plus ChEMBL's mechanisms of action for the 30 most advanced drugs in
+      the call. `genes` is a comma-separated list of HGNC symbols or Ensembl gene ids (at most
+      100). Open Targets lists drugs with trial or approval evidence; an investigational compound
+      with no trial record (for example MRTX1133 against KRAS G12D) can be absent — the
+      coverage note says so, relay it rather than filling the gap from memory.
+  - name: trials_for_genes
+    api_name: "/trials_for_genes"
+    params: [genes, condition, status]
+    description: >
+      ClinicalTrials.gov studies whose INTERVENTION NAME matches each gene symbol, for a
+      condition (default 'pancreatic cancer') and recruitment status (default RECRUITING; also
+      NOT_YET_RECRUITING, ACTIVE_NOT_RECRUITING, ENROLLING_BY_INVITATION, COMPLETED, ANY). The
+      payload's query_semantics and executed_queries state exactly what was searched: a name
+      match is not evidence that the intervention acts on the gene's product, and studies that
+      mention the gene elsewhere are not listed. For the weekly digest's trials, lit-agent keeps
+      its own harvester.
+  - name: annotate_genes
+    api_name: "/annotate_genes"
+    params: [genes]
+    timeout_seconds: 300  # 55 genes: one HGNC call each at 3/s, then one batched UniProt call
+    description: >
+      What HGNC and UniProt say each gene and its protein are: approved name, locus type,
+      Ensembl id, and from the reviewed (Swiss-Prot) human UniProt entry the recommended protein
+      name, function text and subcellular location. `genes` is a comma-separated list of HGNC
+      symbols (at most 100). A gene with no reviewed entry (a pseudogene such as SORD2P) keeps
+      its HGNC row with protein null and is listed in unresolved — never describe it from
+      anything else.
+  - name: pathways_for_genes
+    api_name: "/pathways_for_genes"
+    params: [genes]
+    description: >
+      Reactome lowest-level pathways each gene's protein belongs to, plus shared_by_all (the
+      pathways every resolved gene belongs to). MEMBERSHIP, NOT ENRICHMENT: no statistic is
+      computed over the list, so never call a pathway enriched, overrepresented or significant
+      from this payload — that question is DecoupleRpy's. `genes` is a comma-separated list of
+      HGNC symbols or UniProt accessions (at most 100).
+  - name: targets_for_disease
+    api_name: "/targets_for_disease"
+    params: [disease, size]
+    description: >
+      The targets Open Targets most associates with a disease, ranked by Open Targets' own
+      association score (relayed as its score; this agent ranks nothing). `disease` is a name or
+      a MONDO/EFO/Orphanet id — Open Targets has moved most ids to MONDO (pancreatic ductal
+      adenocarcinoma is MONDO_0005184; the legacy EFO_0002618 no longer resolves and is refused
+      with Open Targets' message). A name resolves to an exact match if there is one, else
+      Open Targets' first hit, and the payload's disease block names the id chosen and the
+      alternatives. `size` is 1-50 (default 25).

docs/plans/PLAN-phase1-knowledge-specialist.md

@@ -133,6 +133,27 @@ The memo settled the approach. The only real choice left is where the endpoints
 - **Blocks:** s1 (and through it every slice).
 - **Status:** DECIDED 2026-10-20 (project lead): A — start s1 now.
 
+### Decision D5: what to do about the pillow 12.3.0 CVEs that block the security gate (raised by s2)
+- **Door:** one-way. Accepting a known CVE, or moving gradio, is a security posture call, and it is
+  fleet-wide: gradio 6.28.0 requires `pillow<13`, every fleet repo's `dev` pins `pillow==12.3.0`, and
+  8 advisories published 2026-10-20/21 are fixed only in 13.0.0. Every pre-push gate in the fleet
+  now fails on them.
+- **Exposure here:** all eight concern parsing attacker-supplied image files (PDF append, GIF,
+  PPM/PGM, TIFF, EPS). This Space accepts identifiers only and has no image or file input.
+- **Options:**
+  - A) a justified acceptance in this repo's `security/ACCEPTED-FINDINGS.md`, scoped to these eight
+    ids and expiring when a gradio release allows `pillow>=13` (or on 2026-11-20, whichever is
+    first), with the fleet-wide question triaged separately;
+  - B) no acceptance: s3 (the first push) waits for a gradio release that allows pillow 13 and a
+    fleet-wide bump;
+  - C) force `pillow==13.0.0` against gradio's declared constraint (unsupported).
+- **Recommend:** A, for this repo.
+- **Blocks:** the s2 merge gate ("security scan green") and s3's first push. Everything else in s2
+  is done and green.
+- **Status:** DECIDED 2026-10-20 (project lead): A — accepted in this repo only, expiring 2026-11-20 or
+  when gradio allows pillow 13 (`security/accepted-vulns.txt`, `tests/test_accepted_vulns.py`). The
+  fleet-wide question stays open outside this plan.
+
 **Two-way defaults** (DECIDED by default; overrule in one line):
 - The plan and ADR-0001 stay here until s1 moves them into the new repo.
 - **No orchestrator ADR number is claimed in Phase 1.** The knowledge-join ADR (annotation inside chains, the recipe

gradio_ui.py

@@ -0,0 +1,317 @@
+"""PDAC Knowledge Agent — Gradio app: UI + machine endpoints (tool_server contract).
+
+Three surfaces over the five endpoint functions in ``src.endpoints`` (the pdac-spatial-agent shape):
+
+- **Machine endpoints** — ``gr.api(fn, api_name=...)``, plain-string in / JSON-string out.
+  Endpoint FUNCTION names equal the contract names (the gradio MCP bridge names tools after the
+  Python function while ``gradio_client`` dispatches on ``api_name`` — keep them identical).
+  Names and parameter order are frozen by ``deploy/orchestrator_registration.yaml``.
+- **MCP** — ``demo.launch(mcp_server=True)``.
+- **UI handlers** — ``_ui_*`` with ``api_name=False``. NOTE: ``api_name=False`` is NOT a
+  security boundary; every handler, UI and machine alike, runs the access gate itself.
+
+Every payload has ``status`` in {ok, refused, error, denied} + ``reason`` on non-ok. Gate first,
+then argument validation: an unauthenticated caller learns nothing about our inputs.
+
+The allow-listed ToolUniverse is built when this module is imported (ADR-0001 §7), so a Space
+with a model-provider key, a drifted version or a widened tool set does not start at all.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+
+import gradio as gr
+
+from access import check_access
+from audit import record_run
+from src.endpoints import ENDPOINTS, _common
+from src.tu_client import ToolClient, build_tooluniverse
+
+_common.set_client(ToolClient(tooluniverse=build_tooluniverse()))
+
+# --------------------------------------------------------------------------- #
+# Machine-caller identity (x-orchestrator-token → whoami), copied from pdac-spatial-agent.
+# --------------------------------------------------------------------------- #
+# HF edge infra strips the reserved "x-hf-*" namespace, so only the custom header survives in
+# a deployed Space; both are accepted for local/dev callers.
+_MACHINE_TOKEN_HEADERS = ("x-orchestrator-token", "x-hf-authorization")
+
+_WHOAMI_TTL_S = 15 * 60
+_WHOAMI_NEG_TTL_S = 60
+_WHOAMI_STALE_OK_S = 24 * 60 * 60
+_WHOAMI_CACHE: dict[str, tuple[str | None, float]] = {}
+
+_MACHINE_DENIAL_REASONS = {
+    "no_token_header": (
+        "🔒 No machine credential presented: neither 'x-orchestrator-token' nor "
+        "'x-hf-authorization' reached this Space. The caller is misconfigured — the "
+        "orchestrator attaches that header only when its own HF_TOKEN is set, so "
+        "check that secret on the CALLING Space."
+    ),
+    "token_unresolved": (
+        "🔒 A machine credential was presented but could not be resolved to a "
+        "HuggingFace identity — invalid/expired token, or an upstream lookup "
+        "failure. Fail-closed by design; retry once before treating as a rejection."
+    ),
+    "not_allowlisted": None,  # check_access already says who was refused and why
+}
+
+
+def _header_value(headers, name: str) -> str | None:
+    if not headers:
+        return None
+    getter = getattr(headers, "get", None)
+    return getter(name) if getter else None
+
+
+def _resolve_token_identity(token: str) -> str | None:
+    """HF token → username via whoami; TTL-cached, stale-if-error."""
+    now = time.monotonic()
+    entry = _WHOAMI_CACHE.get(token)
+    if entry is not None:
+        identity, stamp = entry
+        ttl = _WHOAMI_TTL_S if identity is not None else _WHOAMI_NEG_TTL_S
+        if now - stamp < ttl:
+            return identity
+    try:
+        from huggingface_hub import HfApi
+        from huggingface_hub.utils import HfHubHTTPError
+
+        try:
+            identity = HfApi().whoami(token=token).get("name")
+        except HfHubHTTPError:
+            _WHOAMI_CACHE[token] = (None, now)  # definitive: the token is bad
+            return None
+    except Exception:  # noqa: BLE001 — transient failure: stale-if-error, else deny
+        if entry is not None:
+            identity, stamp = entry
+            if identity is not None and now - stamp < _WHOAMI_STALE_OK_S:
+                return identity
+        return None
+    _WHOAMI_CACHE[token] = (identity, now)
+    return identity
+
+
+def _machine_caller_identity(request) -> tuple[str | None, str]:
+    headers = getattr(request, "headers", None) if request else None
+    presented = False
+    for header in _MACHINE_TOKEN_HEADERS:
+        raw = _header_value(headers, header)
+        if not raw:
+            continue
+        token = raw[7:].strip() if raw.lower().startswith("bearer ") else raw.strip()
+        if token:
+            presented = True
+            identity = _resolve_token_identity(token)
+            if identity:
+                return identity, "resolved"
+    return None, ("token_unresolved" if presented else "no_token_header")
+
+
+def _machine_gate(tool: str, request) -> tuple[str | None, str | None]:
+    """(identity, denial_json). A non-None denial is returned to the caller verbatim."""
+    username, diagnosis = _machine_caller_identity(request)
+    allowed, denial = check_access(username)
+    if not allowed:
+        if username:
+            diagnosis = "not_allowlisted"
+        record_run(tool, username=username, n_identifiers=None, status="denied")
+        return username, json.dumps(
+            {
+                "status": "denied",
+                "reason": _MACHINE_DENIAL_REASONS.get(diagnosis) or denial,
+                "machine_auth": diagnosis,
+            },
+            indent=2,
+        )
+    return username, None
+
+
+def _machine_input_errors(**fields) -> dict | None:
+    """Typed error for a non-string machine argument. Deliberately no coercion — the published
+    schema declares `str`, and quietly accepting a second shape means the published contract and
+    the real one disagree."""
+    for field, value in fields.items():
+        if value is None or isinstance(value, str):
+            continue
+        got = type(value).__name__
+        return {
+            "status": "error",
+            "machine_input": f"{field}_not_a_string",
+            "reason": (
+                f"Machine endpoints take plain strings; `{field}` arrived as a {got}. "
+                "Pass a comma-separated string instead. This is a caller-side argument "
+                "error — the call was not run."
+            ),
+        }
+    return None
+
+
+def _safe_result(fn):
+    """Any escaped exception becomes an error dict — the contract never raises."""
+    try:
+        return fn()
+    except Exception as exc:  # noqa: BLE001
+        return {"status": "error", "reason": f"{type(exc).__name__}: {exc}"}
+
+
+def _as_json(result) -> str:
+    return json.dumps(result, indent=2, default=str, ensure_ascii=False)
+
+
+def _n_identifiers(result: dict) -> int | None:
+    query = result.get("query") or {}
+    genes = query.get("genes")
+    if isinstance(genes, list):
+        return len(genes)
+    return 1 if query.get("disease") else None
+
+
+def _run(tool_name: str, request, **string_fields) -> str:
+    """The shared machine-endpoint shape: gate → typed inputs → endpoint → audit → JSON."""
+    username, denial = _machine_gate(tool_name, request)
+    if denial is not None:
+        return denial
+    bad = _machine_input_errors(**string_fields)
+    if bad is not None:
+        record_run(tool_name, username=username, n_identifiers=None, status="error")
+        return _as_json(bad)
+    fn, params = ENDPOINTS[tool_name]
+    result = _safe_result(lambda: fn(*[string_fields[p] or "" for p in params]))
+    record_run(
+        tool_name,
+        username=username,
+        n_identifiers=_n_identifiers(result),
+        status=str(result.get("status", "error")),
+        run_id=result.get("run_id"),
+    )
+    return _as_json(result)
+
+
+# --------------------------------------------------------------------------- #
+# Machine endpoints (string in / JSON string out). Names are FROZEN (ADR-0001 §4).
+# --------------------------------------------------------------------------- #
+def drugs_for_targets(genes: str = "", request: gr.Request | None = None) -> str:
+    """Drugs and clinical candidates per target (Open Targets), with ChEMBL mechanisms."""
+    return _run("drugs_for_targets", request, genes=genes)
+
+
+def trials_for_genes(
+    genes: str = "", condition: str = "", status: str = "", request: gr.Request | None = None
+) -> str:
+    """ClinicalTrials.gov studies whose intervention name matches each gene."""
+    return _run("trials_for_genes", request, genes=genes, condition=condition, status=status)
+
+
+def annotate_genes(genes: str = "", request: gr.Request | None = None) -> str:
+    """HGNC and reviewed UniProt annotation per gene: name, function, location."""
+    return _run("annotate_genes", request, genes=genes)
+
+
+def pathways_for_genes(genes: str = "", request: gr.Request | None = None) -> str:
+    """Reactome lowest-level pathway membership per gene (membership, not enrichment)."""
+    return _run("pathways_for_genes", request, genes=genes)
+
+
+def targets_for_disease(
+    disease: str = "", size: str = "", request: gr.Request | None = None
+) -> str:
+    """Top targets Open Targets associates with a disease, by its own association score."""
+    return _run("targets_for_disease", request, disease=disease, size=size)
+
+
+# --------------------------------------------------------------------------- #
+# UI — modest by design; the orchestrator is the primary caller.
+# --------------------------------------------------------------------------- #
+def _username(profile) -> str | None:
+    return getattr(profile, "username", None) if profile else None
+
+
+def _ui_call(tool_name: str):
+    def handler(*args, profile: gr.OAuthProfile | None = None):
+        allowed, denial = check_access(_username(profile))
+        if not allowed:
+            return f"⛔ **Access denied.** {denial}", _as_json(
+                {"status": "denied", "reason": denial}
+            )
+        fn, params = ENDPOINTS[tool_name]
+        values = [a if isinstance(a, str) else "" for a in args][: len(params)]
+        result = _safe_result(lambda: fn(*values))
+        record_run(
+            f"{tool_name}:ui",
+            username=_username(profile),
+            n_identifiers=_n_identifiers(result),
+            status=str(result.get("status", "error")),
+            run_id=result.get("run_id"),
+        )
+        status = result.get("status", "error")
+        summary = (
+            result.get("narrative", "")
+            if status == "ok"
+            else f"⚠️ **{status}.** {result.get('message') or result.get('reason', '')}"
+        )
+        return summary, _as_json(result)
+
+    return handler
+
+
+with gr.Blocks(title="PDAC Knowledge Agent") as demo:
+    gr.Markdown(
+        "# PDAC Knowledge Agent\n"
+        "What public knowledge bases say about named genes, drugs, diseases and trials: "
+        "Open Targets, ChEMBL, UniProt, ClinicalTrials.gov, Reactome and HGNC. **Annotation, "
+        "never analysis**: nothing here reads a dataset or computes a statistic, and every row "
+        "names its source, query date and licence."
+    )
+    gr.LoginButton()
+
+    gr.api(drugs_for_targets, api_name="drugs_for_targets")
+    gr.api(trials_for_genes, api_name="trials_for_genes")
+    gr.api(annotate_genes, api_name="annotate_genes")
+    gr.api(pathways_for_genes, api_name="pathways_for_genes")
+    gr.api(targets_for_disease, api_name="targets_for_disease")
+
+    def _tab(label: str, tool_name: str, inputs: list):
+        button = gr.Button(f"Look up: {label}", variant="primary")
+        summary = gr.Markdown()
+        raw = gr.Code(language="json", label="Result (JSON, with provenance on every row)")
+        button.click(_ui_call(tool_name), inputs=inputs, outputs=[summary, raw], api_name=False)
+
+    with gr.Tab("Drugs for targets"):
+        _tab(
+            "drugs", "drugs_for_targets", [gr.Textbox(label="Genes (HGNC symbols or Ensembl ids)")]
+        )
+    with gr.Tab("Trials for genes"):
+        _tab(
+            "trials",
+            "trials_for_genes",
+            [
+                gr.Textbox(label="Genes (HGNC symbols)"),
+                gr.Textbox(label="Condition", value="pancreatic cancer"),
+                gr.Textbox(label="Status (RECRUITING, COMPLETED, ANY, …)", value="RECRUITING"),
+            ],
+        )
+    with gr.Tab("Annotate genes"):
+        _tab("annotation", "annotate_genes", [gr.Textbox(label="Genes (HGNC symbols)")])
+    with gr.Tab("Pathways for genes"):
+        _tab(
+            "pathways",
+            "pathways_for_genes",
+            [gr.Textbox(label="Genes (HGNC symbols or UniProt accessions)")],
+        )
+    with gr.Tab("Targets for a disease"):
+        _tab(
+            "targets",
+            "targets_for_disease",
+            [
+                gr.Textbox(
+                    label="Disease (name or MONDO/EFO id)", value="pancreatic ductal adenocarcinoma"
+                ),
+                gr.Textbox(label="How many targets (1-50)", value="25"),
+            ],
+        )
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

scripts/record_fixtures.py

@@ -0,0 +1,195 @@
+"""Record the Phase 0 lookups as replay cassettes — the ONLY live-network step in this repo.
+
+Run by hand from the repo root, keyless, when fixtures are first made or after a reviewed
+ToolUniverse bump (ADR-0001 §7). It runs each scenario through the real endpoint code and the
+real, allow-listed ToolUniverse, and stores every raw response the endpoint received, keyed by
+tool and arguments, in ``tests/fixtures/cassettes/<scenario>.json``. The test suite replays
+those responses with sockets blocked, so what the tests check is exactly what the sources said
+on the recording day. Re-recording is a reviewed change: diff the cassettes before committing.
+
+Schema validation is switched off while recording (the schemas are written FROM these
+responses); replay validates every response against the pinned schemas.
+
+    python scripts/record_fixtures.py            # every scenario
+    python scripts/record_fixtures.py q5_trials_cd40
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT))
+
+from src import config, schemas
+from src.cache import ResponseCache
+from src.endpoints import ENDPOINTS, _common
+from src.tu_client import (
+    ToolClient,
+    build_tooluniverse,
+    installed_tooluniverse_version,
+)
+
+CASSETTES = ROOT / "tests" / "fixtures" / "cassettes"
+# The 55 pORG genes, as pdac-subtype-agent ships them (src/resources/signatures/pORG.tsv,
+# commit 2451c18) — the same list Phase 0's Q4 annotated.
+PORG_SOURCE = "pdac-subtype-agent src/resources/signatures/pORG.tsv @ 2451c18"
+PORG = [
+    "TNFSF18",
+    "CST2",
+    "RPRD1B",
+    "BARD1",
+    "SORD2P",
+    "ZNF217",
+    "CHMP4B",
+    "SLFN13",
+    "MMEL1",
+    "SPATA24",
+    "OSER1",
+    "PHACTR3",
+    "PKIB",
+    "ARHGAP12",
+    "RBM41",
+    "MPZL3",
+    "GDE1",
+    "FGD6",
+    "PLAAT2",
+    "STAU1",
+    "ZG16B",
+    "RIOK3",
+    "ALOX5",
+    "CDS1",
+    "PIK3CB",
+    "HPGD",
+    "HIST1H1T",
+    "GID8",
+    "NUDT21",
+    "PAK1",
+    "CYP4F3",
+    "ARL17A",
+    "PLAAT3",
+    "SRP9",
+    "ANKRD18B",
+    "CCL20",
+    "CFB",
+    "SPOPL",
+    "CTNNBL1",
+    "NFE2L3",
+    "ACSL5",
+    "CIAO2A",
+    "SCOC",
+    "SAA4",
+    "PPP1R3C",
+    "WFDC13",
+    "FUNDC1",
+    "ADNP",
+    "DLEU7",
+    "NME7",
+    "EFNB2",
+    "LRRIQ1",
+    "MAP3K2",
+    "LNPK",
+    "ZDHHC13",
+]
+
+SCENARIOS = {
+    "q1_q2_drugs_kras": ("drugs_for_targets", ["KRAS"], "Phase 0 Q1 (KRAS G12D) and Q2 (G12C)"),
+    "q3_annotate_elavl1": ("annotate_genes", ["ELAVL1"], "Phase 0 Q3 (HuR function)"),
+    "q4_annotate_porg": ("annotate_genes", [",".join(PORG)], "Phase 0 Q4 (the 55 pORG genes)"),
+    "q5_trials_cd40": ("trials_for_genes", ["CD40", "", ""], "Phase 0 Q5 (recruiting CD40 trials)"),
+    "q6_drugs_jak_stat": ("drugs_for_targets", ["JAK1,JAK2,STAT1"], "Phase 0 Q6 (JAK1/JAK2/STAT1)"),
+    "q7_drugs_tnfrsf10b": ("drugs_for_targets", ["TNFRSF10B"], "Phase 0 Q7 (DR5)"),
+    "q8_targets_pdac": (
+        "targets_for_disease",
+        ["pancreatic ductal adenocarcinoma", ""],
+        "Phase 0 Q8 (top PDAC targets)",
+    ),
+    "q9_pathways_isg15_rsad2_oas1": (
+        "pathways_for_genes",
+        ["ISG15,RSAD2,OAS1"],
+        "Phase 0 Q9 (Interferon alpha/beta signaling)",
+    ),
+    "c1_annotate_kras_tp53_sord2p": (
+        "annotate_genes",
+        ["KRAS,TP53,SORD2P"],
+        "plan C1(c): SORD2P listed as unresolved, not guessed",
+    ),
+    "edge_unknown_symbol": ("drugs_for_targets", ["NOTAGENE1"], "a symbol HGNC does not know"),
+    "edge_legacy_efo": (
+        "targets_for_disease",
+        ["EFO_0002618", "5"],
+        "a legacy EFO id Open Targets dropped",
+    ),
+}
+
+
+class Recorder:
+    def __init__(self):
+        self.tu = build_tooluniverse()
+        self.calls: list[dict] = []
+
+    def __call__(self, tool: str, args: dict):
+        response = self.tu.run_one_function({"name": tool, "arguments": args}, use_cache=False)
+        self.calls.append({"tool": tool, "args": dict(args), "response": response})
+        return response
+
+
+def record(name: str) -> Path:
+    endpoint, arguments, why = SCENARIOS[name]
+    recorder = Recorder()
+    client = ToolClient(runner=recorder, cache=ResponseCache(":memory:"))
+    _common.set_client(client)
+    started = time.time()
+    payload = ENDPOINTS[endpoint][0](*arguments)
+    used = sorted({config.source_of(c["tool"]) for c in recorder.calls})
+    cassette = {
+        "_recorded": {
+            "scenario": name,
+            "why": why,
+            "endpoint": endpoint,
+            "arguments": arguments,
+            "tooluniverse_version": installed_tooluniverse_version(),
+            "recorded_on": datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "recorded_at_epoch": round(started, 3),
+            "recorded_with": "scripts/record_fixtures.py",
+            "payload_status_when_recorded": payload.get("status"),
+            "licences": {s: config.source(s)["licence"] for s in used},
+            **({"porg_source": PORG_SOURCE} if name == "q4_annotate_porg" else {}),
+        },
+        "calls": recorder.calls,
+    }
+    path = CASSETTES / f"{name}.json"
+    path.write_text(json.dumps(cassette, indent=1, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(
+        f"{name}: {len(recorder.calls)} calls, payload {payload.get('status')}, "
+        f"{len(payload.get('rows') or [])} rows, {time.time() - started:.1f} s -> {path.name}"
+    )
+    return path
+
+
+def _check_porg_against_the_subtype_agent() -> None:
+    """The list above was once typed from memory and was wrong; compare it to the source file."""
+    relative = Path("pdac-subtype-agent/src/resources/signatures/pORG.tsv")
+    for candidate in (ROOT.parent / relative, Path.home() / "Documents/GitHub" / relative):
+        if candidate.is_file():
+            listed = candidate.read_text().split()[1:]
+            assert listed == PORG, "PORG differs from pdac-subtype-agent's pORG.tsv"
+            return
+    raise SystemExit("pdac-subtype-agent is not checked out beside this repo; cannot check PORG")
+
+
+def main(names: list[str]) -> None:
+    assert len(PORG) == 55, len(PORG)
+    _check_porg_against_the_subtype_agent()
+    CASSETTES.mkdir(parents=True, exist_ok=True)
+    schemas.validate = lambda tool, data: None  # recording only: schemas are written from this
+    for name in names or list(SCENARIOS):
+        record(name)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

scripts/security_scan.sh

@@ -115,8 +115,25 @@ else
     echo "    setting up audit venv ($PYBIN)"
     "$PYBIN" -m venv "$VENV" && "$VENV/bin/python" -m pip install -q --upgrade pip pip-audit
   fi
+  # Recorded, expiring acceptances (security/accepted-vulns.txt; justified in
+  # security/ACCEPTED-FINDINGS.md). An EXPIRED entry fails the scan: re-triage, never extend quietly.
+  IGNORES=()
+  if [[ -f security/accepted-vulns.txt ]]; then
+    TODAY="$(date -u +%Y-%m-%d)"
+    while read -r vid expires _rest; do
+      [[ -z "${vid:-}" || "$vid" == \#* ]] && continue
+      exp="${expires#expires=}"
+      if [[ "$exp" < "$TODAY" ]]; then
+        fail "accepted finding $vid expired on $exp — re-triage it (security/ACCEPTED-FINDINGS.md)"
+        continue
+      fi
+      IGNORES+=(--ignore-vuln "$vid")
+    done < security/accepted-vulns.txt
+    [[ ${#IGNORES[@]} -gt 0 ]] && echo "    accepting $(( ${#IGNORES[@]} / 2 )) recorded finding(s) until their expiry (security/accepted-vulns.txt)"
+  fi
+  # `${IGNORES[@]+…}`: macOS ships bash 3.2, where an empty array under `set -u` is unbound.
   "$VENV/bin/python" -m pip_audit --requirement "$TMP/audit.txt" --no-deps --disable-pip \
-    --format columns 2>/dev/null | tee "$OUT/pip-audit-$STAMP.txt"
+    ${IGNORES[@]+"${IGNORES[@]}"} --format columns 2>/dev/null | tee "$OUT/pip-audit-$STAMP.txt"
   AUDIT_RC=${PIPESTATUS[0]}
   if [[ "$AUDIT_RC" -eq 0 ]]; then
     ok "pip-audit — no known vulnerabilities in the resolved tree"

security/ACCEPTED-FINDINGS.md

@@ -10,7 +10,7 @@ There are none.
 |-------|--------|
 | **pip-audit** (compiled lock vs OSV/PyPI advisories) | **clean** — `requirements.txt` is a uv lock of `requirements.in` for python 3.12 / linux: 119 pinned packages, including gradio 6.28.0 from `sdk_version` and ToolUniverse 1.5.6 with every transitive dependency. The memo accepted that footprint under this scan (2026-10-13). |
 | **bandit** (static, medium+, `src/` + `access.py`, `audit.py`, `logging_sink.py`) | **clean** — 0 findings, so there is no baseline file. |
-| **gitleaks** (working tree + full git history) | **clean**. The first run flagged `src/identifiers.py:4` under `generic-api-key`: the docstring phrase "UniProt accessions, EFO/MONDO/Orphanet" matched the rule's keyword-plus-token shape. Not a secret; fixed by rewording the docstring and amending the unpushed commit, **not** by an allowlist entry. |
+| **gitleaks** (working tree + full git history) | **clean**. The first run flagged `src/identifiers.py:4` under `generic-api-key`: a docstring listing identifier kinds matched the rule's keyword-plus-token shape. Not a secret; fixed by rewording the docstring and amending the unpushed commit, **not** by an allowlist entry. (See §1: this record then quoted the phrase and tripped the same rule.) |
 | **trivy** (sandbox image) | **N/A** — no sandboxed-exec Dockerfile in this repo; the stage skips. |
 | **SBOM** (CycloneDX, of the lock) | written to `security/sbom.json` (not tracked — regenerable, as in pdac-spatial-agent). |
 
@@ -20,3 +20,10 @@ A version bump is its own lane (ADR-0001 §7): `tooluniverse-doctor`, re-recorde
 the schema tests, and this scan on the recompiled lock. `tests/test_no_llm_keys.py` also fails if the lock ever
 gains an LLM client library (openai, anthropic, google-genai, smolagents, litellm, langchain, vllm), so a new
 transitive of that kind is a reviewed change, not a silent one.
+
+## §1 — s2 run (2026-10-21 UTC)
+
+| Stage | Result |
+|-------|--------|
+| **gitleaks** | One finding, **accepted as a false positive by fingerprint** (`.gitleaksignore`): commit `97e7d80`, `security/ACCEPTED-FINDINGS.md:13`, `generic-api-key`. That line of §0 quoted, verbatim, the docstring phrase §0 describes as a false positive, so it tripped the same rule. The text is reworded here; the old commit is local history on `dev` that has never been pushed, and is ignored by its exact fingerprint rather than rewritten. Not a secret: it is a list of identifier kinds. |
+| **pip-audit** | **8 findings, ACCEPTED until 2026-11-20 (plan D5-A, the project lead, 2026-10-20)** — `pillow 12.3.0` (via gradio 6.28.0, which requires `pillow<13`): CVE-2026-112895 / -112400 / -112397 / -112896 / -112897 / -112395 / -112404 / -112899, all fixed in 13.0.0. **Why acceptable here:** all eight are in parsing attacker-supplied image files (PDF append, GIF, PPM/PGM, TIFF, EPS); this Space's inputs are identifiers only (ADR-0001 §6), it has no image or file input, and it never opens an image a caller supplies. **Why not fixed:** an anchored pin bump cannot move pillow without breaking gradio's constraint; every fleet repo's `dev` pins the same version, so the fix is a fleet-wide gradio move, tracked separately. **Ends** when a gradio release allowing `pillow>=13` is pinned (tests/test_accepted_vulns.py then fails until the entries are removed) or on 2026-11-20, when the scan fails on the expired entries. Mechanism: `security/accepted-vulns.txt` → `pip-audit --ignore-vuln`. |

security/accepted-vulns.txt

@@ -0,0 +1,13 @@
+# Accepted pip-audit findings — each line: <advisory id> expires=<YYYY-MM-DD> <package> <affected version>
+# scripts/security_scan.sh passes every unexpired id to `pip-audit --ignore-vuln` and FAILS on an
+# expired one, so an acceptance cannot outlive its date. tests/test_accepted_vulns.py fails once the
+# lock moves the package off the affected version, so a fixed finding cannot stay accepted.
+# Justification: security/ACCEPTED-FINDINGS.md §1 (plan D5-A, decided 2026-10-20 by the project lead).
+CVE-2026-112895 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112400 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112397 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112896 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112897 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112395 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112404 expires=2026-11-20 pillow 12.3.0
+CVE-2026-112899 expires=2026-11-20 pillow 12.3.0

src/endpoints/__init__.py

@@ -0,0 +1,30 @@
+"""The five BCC endpoints (ADR-0001 §4). Names and parameter order are frozen by the descriptor.
+
+Each is ``fn(*strings) -> payload dict``; ``ENDPOINTS`` maps the contract name to the function
+and its parameter names, in the order ``gradio_ui`` exposes them and the descriptor records.
+"""
+
+from __future__ import annotations
+
+from src.endpoints.annotate import annotate_genes
+from src.endpoints.drugs import drugs_for_targets
+from src.endpoints.pathways import pathways_for_genes
+from src.endpoints.targets import targets_for_disease
+from src.endpoints.trials import trials_for_genes
+
+ENDPOINTS = {
+    "drugs_for_targets": (drugs_for_targets, ("genes",)),
+    "trials_for_genes": (trials_for_genes, ("genes", "condition", "status")),
+    "annotate_genes": (annotate_genes, ("genes",)),
+    "pathways_for_genes": (pathways_for_genes, ("genes",)),
+    "targets_for_disease": (targets_for_disease, ("disease", "size")),
+}
+
+__all__ = [
+    "ENDPOINTS",
+    "annotate_genes",
+    "drugs_for_targets",
+    "pathways_for_genes",
+    "targets_for_disease",
+    "trials_for_genes",
+]

src/endpoints/_common.py

@@ -0,0 +1,247 @@
+"""What every endpoint shares: the client, the call budget, dates, stages and HGNC resolution.
+
+Endpoints are plain functions — strings in, payload dicts out — and no exception escapes one
+(the family tool_server contract). A failure inside one source call is a ``source_errors`` entry,
+an input that a source does not know is an ``unresolved`` entry, and only an endpoint where
+nothing could be looked up at all is an ``error`` payload.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any
+
+from src import config
+from src.provenance import stamp
+from src.tu_client import SourceError, SourceResult, ToolClient
+
+# One endpoint call may spend at most this long across all its source calls; the orchestrator's
+# own call limit is above it (300 s for annotate_genes, its default for the others).
+ENDPOINT_BUDGET_SECONDS = 240
+
+_client: ToolClient | None = None
+_client_lock = threading.Lock()
+
+
+def get_client() -> ToolClient:
+    """The process-wide client (one cache, one set of rate limits for every endpoint)."""
+    global _client
+    with _client_lock:
+        if _client is None:
+            _client = ToolClient()
+        return _client
+
+
+def set_client(client: ToolClient | None) -> None:
+    """Tests replay recorded responses through a client of their own."""
+    global _client
+    with _client_lock:
+        _client = client
+
+
+class Budget:
+    """The endpoint's wall-clock budget. Past it, remaining inputs are reported, not looked up."""
+
+    def __init__(self, seconds: float = ENDPOINT_BUDGET_SECONDS, clock=time.monotonic):
+        self._clock = clock
+        self._deadline = clock() + seconds
+
+    @property
+    def remaining(self) -> float:
+        return max(0.0, self._deadline - self._clock())
+
+    @property
+    def spent(self) -> bool:
+        return self.remaining <= 0
+
+
+@dataclass
+class Collector:
+    """Accumulates what an endpoint found, failed on and could not resolve."""
+
+    rows: list[dict[str, Any]] = field(default_factory=list)
+    unresolved: list[dict[str, str]] = field(default_factory=list)
+    source_errors: list[dict[str, str]] = field(default_factory=list)
+    sources_used: set[str] = field(default_factory=set)
+    retrieved: list[float] = field(default_factory=list)
+    calls: int = 0
+
+    def call(
+        self,
+        client: ToolClient,
+        budget: Budget,
+        tool: str,
+        args: dict[str, Any],
+        *,
+        unknown: tuple[str, str] | None = None,
+    ) -> SourceResult | None:
+        """One source call. None (with the reason recorded) if it failed or the budget ran out.
+
+        ``unknown=(marker, input)``: a source error whose detail contains ``marker`` means the
+        source does not know ``input`` (Reactome's 404, Open Targets' "no disease for ID"). That
+        is an unresolved input, not a source failure.
+        """
+        if budget.spent:
+            return None
+        self.calls += 1
+        try:
+            result = client.call(tool, args, max_wait=min(10.0, budget.remaining))
+        except SourceError as err:
+            if (
+                unknown is not None
+                and err.reason == "source_unavailable"
+                and unknown[0] in err.detail
+            ):
+                self.unresolved_input(unknown[1], f"unknown to {err.source}: {err.detail}")
+            else:
+                self.source_errors.append(err.as_payload())
+            return None
+        self.sources_used.add(result.source)
+        self.retrieved.append(result.retrieved_at)
+        return result
+
+    def unresolved_input(self, value: str, reason: str) -> None:
+        self.unresolved.append({"input": value, "reason": reason})
+
+    def out_of_budget(self, values: Iterable[str]) -> None:
+        for value in values:
+            self.unresolved_input(
+                value, f"not looked up: the {ENDPOINT_BUDGET_SECONDS} s call budget ran out"
+            )
+
+
+def stamped(row: dict[str, Any], result: SourceResult, *, ref: str, url: str) -> dict[str, Any]:
+    return stamp(
+        row,
+        source=result.source,
+        source_tool=result.tool,
+        tooluniverse_version=result.tooluniverse_version,
+        query=result.args,
+        source_ref=ref,
+        source_url=url,
+        retrieved_at=result.retrieved_at,
+        cache=result.cache,
+    )
+
+
+def query_dates(retrieved: Iterable[float]) -> str:
+    """'2026-10-20', or '2026-10-14 to 2026-10-20' when cached answers span days."""
+    from src.provenance import iso_utc
+
+    days = sorted({iso_utc(t)[:10] for t in retrieved})
+    if not days:
+        return "today"
+    return days[0] if len(days) == 1 else f"{days[0]} to {days[-1]}"
+
+
+def according_to(source_ids: Iterable[str], retrieved: Iterable[float]) -> str:
+    names = [config.source(s)["name"] for s in sorted(set(source_ids))]
+    joined = names[0] if len(names) == 1 else ", ".join(names[:-1]) + " and " + names[-1]
+    return f"According to {joined} (queried {query_dates(retrieved)})"
+
+
+def humanise_list(items: list[str], limit: int = 5) -> str:
+    shown = items[:limit]
+    more = len(items) - len(shown)
+    text = ", ".join(shown)
+    return f"{text} and {more} more" if more > 0 else text
+
+
+# Open Targets' clinical-stage vocabulary, highest first. Anything unknown sorts last and is
+# shown as Open Targets wrote it.
+_STAGE_ORDER = (
+    "APPROVAL",
+    "APPROVED",
+    "PHASE_4",
+    "PHASE_3",
+    "PHASE_2_3",
+    "PHASE_2",
+    "PHASE_1_2",
+    "PHASE_1",
+    "EARLY_PHASE_1",
+    "PHASE_0",
+    "PRECLINICAL",
+)
+
+
+def stage_rank(stage: str | None) -> int:
+    try:
+        return _STAGE_ORDER.index((stage or "").upper())
+    except ValueError:
+        return len(_STAGE_ORDER)
+
+
+def stage_label(stage: str | None) -> str:
+    if not stage:
+        return "stage not stated"
+    text = stage.upper()
+    if text in ("APPROVAL", "APPROVED"):
+        return "approved"
+    return (
+        text.replace("_", " ")
+        .lower()
+        .replace("phase 1 2", "phase 1/2")
+        .replace("phase 2 3", "phase 2/3")
+    )
+
+
+@dataclass(frozen=True)
+class Gene:
+    """An input resolved through HGNC."""
+
+    input: str
+    symbol: str
+    hgnc_id: str
+    name: str
+    locus_type: str
+    ensembl_gene_id: str | None
+    uniprot_ids: tuple[str, ...]
+    provenance_row: dict[str, Any]
+
+
+HGNC = "HGNC_fetch_gene_by_symbol"
+
+
+def resolve_symbols(
+    symbols: list[str], client: ToolClient, budget: Budget, out: Collector
+) -> list[Gene]:
+    """HGNC symbol → approved record. Unknown symbols go to ``unresolved``."""
+    genes: list[Gene] = []
+    for i, symbol in enumerate(symbols):
+        if budget.spent:
+            out.out_of_budget(symbols[i:])
+            break
+        result = out.call(client, budget, HGNC, {"symbol": symbol})
+        if result is None:
+            continue
+        data = result.data or {}
+        if not data.get("symbol"):
+            out.unresolved_input(symbol, "not a current, previous or alias symbol in HGNC")
+            continue
+        row = stamped(
+            {"input": symbol, "symbol": data["symbol"], "hgnc_id": data["hgnc_id"]},
+            result,
+            ref=data["hgnc_id"],
+            url=f"https://www.genenames.org/data/gene-symbol-report/#!/hgnc_id/{data['hgnc_id']}",
+        )
+        genes.append(
+            Gene(
+                input=symbol,
+                symbol=data["symbol"],
+                hgnc_id=data["hgnc_id"],
+                name=data.get("name") or "",
+                locus_type=data.get("locus_type") or "",
+                ensembl_gene_id=data.get("ensembl_gene_id"),
+                uniprot_ids=tuple(data.get("uniprot_ids") or ()),
+                provenance_row=row,
+            )
+        )
+    return genes
+
+
+def resolution_rows(genes: list[Gene]) -> list[dict[str, Any]]:
+    """The identifier mapping each answer rests on, with HGNC's provenance."""
+    return [g.provenance_row for g in genes]

src/endpoints/annotate.py

@@ -0,0 +1,179 @@
+"""annotate_genes — what HGNC and UniProt say each gene and its protein are.
+
+HGNC is the authority for the symbol (approved name, locus type, Ensembl id) and for the
+gene → UniProt accession link. UniProt is then asked once per batch of up to 100 accessions,
+reviewed (Swiss-Prot) human entries only, for the recommended name, function and subcellular
+location. A gene with no reviewed entry — a pseudogene such as SORD2P — keeps its HGNC row with
+``protein: null`` and is listed in ``unresolved``; it is never filled in from anything else.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src import payloads
+from src.endpoints._common import (
+    Budget,
+    Collector,
+    according_to,
+    get_client,
+    humanise_list,
+    resolve_symbols,
+    stamped,
+)
+from src.identifiers import parse_gene_list
+
+ENDPOINT = "annotate_genes"
+UNIPROT_SEARCH = "UniProt_search"
+UNIPROT_BATCH = 100
+UNIPROT_FIELDS = [
+    "accession",
+    "gene_primary",
+    "protein_name",
+    "cc_function",
+    "cc_subcellular_location",
+]
+MAX_FUNCTION_CHARS = 600
+
+
+def annotate_genes(genes: str = "") -> dict[str, Any]:
+    parsed = parse_gene_list(genes, allow_ensembl=False)
+    if not parsed.ok:
+        return payloads.refused(ENDPOINT, parsed.reason, parsed.message)
+    client, budget, out = get_client(), Budget(), Collector()
+    symbols = [i.value for i in parsed.identifiers]
+    resolved = resolve_symbols(symbols, client, budget, out)
+
+    accessions = sorted({acc for g in resolved for acc in g.uniprot_ids})
+    entries = fetch_reviewed_entries(accessions, client, budget, out)
+
+    with_protein = 0
+    for gene in resolved:
+        protein = None
+        for acc in gene.uniprot_ids:
+            if acc in entries:
+                entry, result = entries[acc]
+                protein = stamped(entry_fields(entry), result, ref=acc, url=uniprot_url(acc))
+                break
+        if protein is not None:
+            with_protein += 1
+            status = "reviewed UniProt entry"
+        elif not gene.uniprot_ids:
+            status = f"HGNC links no UniProt entry (locus type: {gene.locus_type or 'not stated'})"
+            out.unresolved_input(gene.input, f"no reviewed UniProt entry: {status}")
+        else:
+            status = "no reviewed (Swiss-Prot) human entry for " + ", ".join(gene.uniprot_ids)
+            out.unresolved_input(gene.input, status)
+        out.rows.append(
+            {
+                "input": gene.input,
+                "symbol": gene.symbol,
+                "hgnc_id": gene.hgnc_id,
+                "name": gene.name,
+                "locus_type": gene.locus_type,
+                "ensembl_gene_id": gene.ensembl_gene_id,
+                "protein": protein,
+                "protein_status": status,
+                "provenance": gene.provenance_row["provenance"],
+            }
+        )
+
+    if not out.rows and out.source_errors:
+        return payloads.error(
+            ENDPOINT,
+            "all_sources_failed",
+            "HGNC did not answer; nothing was looked up.",
+            source_errors=out.source_errors,
+        )
+    lead = according_to(out.sources_used or {"hgnc"}, out.retrieved)
+    approved = "an approved HGNC gene" if len(symbols) == 1 else "approved HGNC genes"
+    sentences = [
+        (
+            f"{lead}, {len(resolved)} of {len(symbols)} input{'s' if len(symbols) != 1 else ''} "
+            f"{'is' if len(symbols) == 1 else 'are'} {approved}, and {with_protein} "
+            f"{'has' if with_protein == 1 else 'have'} a reviewed human UniProt entry."
+        )
+    ]
+    if out.unresolved:
+        sentences.append(
+            "Not resolved: "
+            + humanise_list([f"{u['input']} ({u['reason']})" for u in out.unresolved], limit=8)
+            + "."
+        )
+    if out.source_errors:
+        sentences.append(
+            "Source problems: "
+            + "; ".join(f"{e['source']} {e['reason']}" for e in out.source_errors)
+            + "."
+        )
+    return payloads.ok(
+        ENDPOINT,
+        query={"genes": symbols},
+        rows=out.rows,
+        sources_used=out.sources_used or {"hgnc"},
+        narrative=" ".join(sentences),
+        unresolved=out.unresolved,
+        source_errors=out.source_errors,
+    )
+
+
+def uniprot_url(accession: str) -> str:
+    return f"https://www.uniprot.org/uniprotkb/{accession}/entry"
+
+
+def fetch_reviewed_entries(
+    accessions: list[str], client, budget: Budget, out: Collector
+) -> dict[str, tuple[dict[str, Any], Any]]:
+    """Reviewed human UniProt entries by accession, in batches of ``UNIPROT_BATCH``."""
+    found: dict[str, tuple[dict[str, Any], Any]] = {}
+    for start in range(0, len(accessions), UNIPROT_BATCH):
+        batch = accessions[start : start + UNIPROT_BATCH]
+        query = (
+            "("
+            + " OR ".join(f"accession:{a}" for a in batch)
+            + ") AND reviewed:true AND organism_id:9606"
+        )
+        result = out.call(
+            client,
+            budget,
+            UNIPROT_SEARCH,
+            {"query": query, "limit": len(batch), "fields": UNIPROT_FIELDS},
+        )
+        if result is None:
+            continue
+        for entry in result.data.get("results") or []:
+            acc = entry.get("primaryAccession")
+            if acc in batch:
+                found[acc] = (entry, result)
+    return found
+
+
+def entry_fields(entry: dict[str, Any]) -> dict[str, Any]:
+    comments = entry.get("comments") or []
+    function = " ".join(
+        t.get("value", "")
+        for c in comments
+        if c.get("commentType") == "FUNCTION"
+        for t in c.get("texts") or []
+    ).strip()
+    locations = []
+    for c in comments:
+        if c.get("commentType") != "SUBCELLULAR LOCATION":
+            continue
+        for loc in c.get("subcellularLocations") or []:
+            value = (loc.get("location") or {}).get("value")
+            if value and value not in locations:
+                locations.append(value)
+    recommended = ((entry.get("proteinDescription") or {}).get("recommendedName") or {}).get(
+        "fullName"
+    ) or {}
+    genes = entry.get("genes") or []
+    return {
+        "accession": entry.get("primaryAccession"),
+        "gene": ((genes[0].get("geneName") or {}).get("value") if genes else None),
+        "protein_name": recommended.get("value"),
+        "function": function[:MAX_FUNCTION_CHARS]
+        + ("…" if len(function) > MAX_FUNCTION_CHARS else ""),
+        "function_truncated": len(function) > MAX_FUNCTION_CHARS,
+        "subcellular_location": locations,
+    }

src/endpoints/drugs.py

@@ -0,0 +1,185 @@
+"""drugs_for_targets — drugs and clinical candidates per target (ADR-0001 §4).
+
+HGNC resolves each symbol to its Ensembl id, Open Targets lists the drugs and clinical candidates
+for that target with their maximum clinical stage, and ChEMBL gives each drug's mechanisms. The
+mechanism lookup is one call per drug, so it is capped at the ``MAX_MECHANISM_LOOKUPS`` most
+advanced drugs in the call (stage first, then name); the payload says how many were looked up.
+Open Targets' coverage note travels with every payload: an investigational compound with no
+trial record can be absent (Phase 0: MRTX1133 against KRAS G12D).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src import payloads
+from src.endpoints._common import (
+    Budget,
+    Collector,
+    according_to,
+    get_client,
+    humanise_list,
+    resolution_rows,
+    resolve_symbols,
+    stage_label,
+    stage_rank,
+    stamped,
+)
+from src.identifiers import parse_gene_list
+
+ENDPOINT = "drugs_for_targets"
+OT_DRUGS = "OpenTargets_get_associated_drugs_by_target_ensemblID"
+CHEMBL_MECHANISMS = "ChEMBL_get_drug_mechanisms"
+MAX_MECHANISM_LOOKUPS = 30
+MAX_INDICATIONS = 10
+
+
+def drugs_for_targets(genes: str = "") -> dict[str, Any]:
+    parsed = parse_gene_list(genes)
+    if not parsed.ok:
+        return payloads.refused(ENDPOINT, parsed.reason, parsed.message)
+    client, budget, out = get_client(), Budget(), Collector()
+
+    symbols = [i.value for i in parsed.identifiers if i.kind == "symbol"]
+    resolved = resolve_symbols(symbols, client, budget, out)
+    targets: list[tuple[str, str]] = []  # (label for messages, Ensembl id)
+    for gene in resolved:
+        if gene.ensembl_gene_id:
+            targets.append((gene.symbol, gene.ensembl_gene_id))
+        else:
+            out.unresolved_input(gene.input, "HGNC records no Ensembl gene id for it")
+    targets += [(i.value, i.value) for i in parsed.identifiers if i.kind == "ensembl"]
+
+    per_target: list[tuple[str, int]] = []
+    for label, ensembl_id in targets:
+        result = out.call(client, budget, OT_DRUGS, {"ensemblId": ensembl_id})
+        if result is None:
+            continue
+        target = result.data.get("target")
+        if target is None:
+            out.unresolved_input(label, "unknown to Open Targets")
+            continue
+        block = target["drugAndClinicalCandidates"]
+        # ToolUniverse omits `rows` when the count is 0 (STAT1, recorded 2026-10-20) and sets
+        # `truncated` when it returned fewer rows than Open Targets holds.
+        candidates = block.get("rows") or []
+        if block.get("truncated"):
+            out.unresolved_input(
+                label,
+                f"Open Targets holds {block.get('count')} records; ToolUniverse returned "
+                f"{len(candidates)} (listed)",
+            )
+        rows = []
+        for cand in candidates:
+            drug = cand["drug"]
+            indications = [
+                d["disease"]["name"]
+                for d in cand.get("diseases") or []
+                if (d.get("disease") or {}).get("name")
+            ]
+            rows.append(
+                stamped(
+                    {
+                        "target": target["approvedSymbol"],
+                        "target_ensembl_id": target["id"],
+                        "drug": drug["name"],
+                        "drug_chembl_id": drug["id"],
+                        "max_clinical_stage": cand["maxClinicalStage"],
+                        "stage": stage_label(cand["maxClinicalStage"]),
+                        "indications": indications[:MAX_INDICATIONS],
+                        "indications_total": len(indications),
+                    },
+                    result,
+                    ref=drug["id"],
+                    url=f"https://platform.opentargets.org/drug/{drug['id']}",
+                )
+            )
+        rows.sort(key=lambda r: (stage_rank(r["max_clinical_stage"]), r["drug"]))
+        out.rows.extend(rows)
+        per_target.append((target["approvedSymbol"], len(rows)))
+
+    looked_up = _attach_mechanisms(out, client, budget)
+
+    if not out.rows and out.source_errors and not per_target:
+        return payloads.error(
+            ENDPOINT,
+            "all_sources_failed",
+            "Open Targets did not answer for any target; no drugs could be looked up.",
+            source_errors=out.source_errors,
+        )
+    return payloads.ok(
+        ENDPOINT,
+        query={"genes": [i.value for i in parsed.identifiers]},
+        rows=out.rows,
+        sources_used=out.sources_used,
+        narrative=_narrative(out, per_target, looked_up),
+        unresolved=out.unresolved,
+        source_errors=out.source_errors,
+        resolved_identifiers=resolution_rows(resolved),
+        mechanism_lookups={"looked_up": looked_up, "cap": MAX_MECHANISM_LOOKUPS},
+    )
+
+
+def _attach_mechanisms(out: Collector, client, budget: Budget) -> int:
+    """ChEMBL mechanisms for the most advanced drugs; every row says whether it was looked up."""
+    best: dict[str, tuple[int, str]] = {}
+    for row in out.rows:
+        key = (stage_rank(row["max_clinical_stage"]), row["drug"])
+        best[row["drug_chembl_id"]] = min(best.get(row["drug_chembl_id"], key), key)
+    order = sorted(best, key=lambda chembl_id: (best[chembl_id], chembl_id))
+    mechanisms: dict[str, dict[str, Any]] = {}
+    for chembl_id in order[:MAX_MECHANISM_LOOKUPS]:
+        result = out.call(client, budget, CHEMBL_MECHANISMS, {"drug_chembl_id": chembl_id})
+        if result is None:
+            continue
+        records = result.data.get("mechanisms") or []
+        moa = sorted({m["mechanism_of_action"] for m in records if m.get("mechanism_of_action")})
+        actions = sorted({m["action_type"] for m in records if m.get("action_type")})
+        mechanisms[chembl_id] = stamped(
+            {"mechanism_of_action": moa, "action_types": actions},
+            result,
+            ref=chembl_id,
+            url=f"https://www.ebi.ac.uk/chembl/compound_report_card/{chembl_id}/",
+        )
+    for row in out.rows:
+        found = mechanisms.get(row["drug_chembl_id"])
+        row["mechanisms"] = found if found is not None else {"looked_up": False}
+    return len(mechanisms)
+
+
+def _narrative(out: Collector, per_target: list[tuple[str, int]], looked_up: int) -> str:
+    sentences = []
+    clauses = []
+    for symbol, n in per_target:
+        rows = [r for r in out.rows if r["target"] == symbol]
+        if not rows:
+            clauses.append(f"{symbol} has no listed drugs or clinical candidates")
+            continue
+        top = rows[0]["stage"]
+        names = [r["drug"] for r in rows if r["stage"] == top]
+        clauses.append(
+            f"{symbol} has {n} drug or clinical-candidate record{'s' if n != 1 else ''}, "
+            f"the most advanced ({top}): {humanise_list(names)}"
+        )
+    if clauses:
+        sentences.append(
+            f"{according_to(['opentargets'], out.retrieved)}: " + "; ".join(clauses) + "."
+        )
+    if looked_up:
+        sentences.append(
+            f"Mechanisms are ChEMBL's for the {looked_up} most advanced drug"
+            f"{'s' if looked_up != 1 else ''} (at most {MAX_MECHANISM_LOOKUPS} per call)."
+        )
+    if out.unresolved:
+        sentences.append(
+            "Not resolved: "
+            + "; ".join(f"{u['input']} ({u['reason']})" for u in out.unresolved)
+            + "."
+        )
+    if out.source_errors:
+        sentences.append(
+            "Source problems: "
+            + "; ".join(f"{e['source']} {e['reason']}" for e in out.source_errors)
+            + "."
+        )
+    return " ".join(sentences) or "Nothing was looked up."

src/endpoints/pathways.py

@@ -0,0 +1,124 @@
+"""pathways_for_genes — which Reactome pathways each gene's protein belongs to.
+
+Membership, never enrichment: a row says "Reactome annotates this protein to this pathway", and
+nothing is computed over the gene list. ``shared_by_all`` lists the pathways every resolved gene
+belongs to — a set intersection over Reactome's own annotation, with no statistic attached.
+Which pathways are *enriched* in a gene list is DecoupleRpy's question.
+
+Symbols resolve through HGNC to UniProt accessions; accessions may also be given directly.
+Reactome's UniProt mapping returns the lowest-level pathways (Phase 0 Q9: ISG15, RSAD2 and OAS1
+in "Interferon alpha/beta signaling").
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src import payloads
+from src.endpoints._common import (
+    Budget,
+    Collector,
+    according_to,
+    get_client,
+    resolution_rows,
+    resolve_symbols,
+    stamped,
+)
+from src.identifiers import parse_gene_list
+
+ENDPOINT = "pathways_for_genes"
+REACTOME_MAP = "Reactome_map_uniprot_to_pathways"
+
+
+def pathways_for_genes(genes: str = "") -> dict[str, Any]:
+    parsed = parse_gene_list(genes, allow_uniprot=True, allow_ensembl=False)
+    if not parsed.ok:
+        return payloads.refused(ENDPOINT, parsed.reason, parsed.message)
+    client, budget, out = get_client(), Budget(), Collector()
+
+    symbols = [i.value for i in parsed.identifiers if i.kind == "symbol"]
+    resolved = resolve_symbols(symbols, client, budget, out)
+    proteins: list[tuple[str, str]] = []  # (gene label, UniProt accession)
+    for gene in resolved:
+        if not gene.uniprot_ids:
+            out.unresolved_input(
+                gene.input,
+                f"HGNC links no UniProt entry (locus type: {gene.locus_type or 'not stated'})",
+            )
+        proteins += [(gene.symbol, acc) for acc in gene.uniprot_ids]
+    proteins += [(i.value, i.value) for i in parsed.identifiers if i.kind == "uniprot"]
+
+    by_gene: dict[str, set[str]] = {}
+    names: dict[str, str] = {}
+    for label, acc in proteins:
+        result = out.call(client, budget, REACTOME_MAP, {"uniprot_id": acc}, unknown=("404", label))
+        if result is None:
+            continue
+        pathways = result.data or []
+        by_gene.setdefault(label, set())
+        for pw in pathways:
+            st_id = pw["stId"]
+            names[st_id] = pw["displayName"]
+            if st_id in by_gene[label]:
+                continue
+            by_gene[label].add(st_id)
+            out.rows.append(
+                stamped(
+                    {
+                        "gene": label,
+                        "uniprot_accession": acc,
+                        "pathway_id": st_id,
+                        "pathway_name": pw["displayName"],
+                        "is_in_disease": bool(pw.get("isInDisease")),
+                        "species": pw.get("speciesName"),
+                    },
+                    result,
+                    ref=st_id,
+                    url=f"https://reactome.org/content/detail/{st_id}",
+                )
+            )
+
+    if not out.rows and out.source_errors and not by_gene:
+        return payloads.error(
+            ENDPOINT,
+            "all_sources_failed",
+            "No source answered; nothing was looked up.",
+            source_errors=out.source_errors,
+        )
+    shared = sorted(set.intersection(*by_gene.values())) if len(by_gene) > 1 else []
+    lead = according_to(["reactome"], out.retrieved)
+    sentences = [
+        f"{lead}, {label} is annotated to {len(ids)} lowest-level pathway"
+        f"{'s' if len(ids) != 1 else ''}."
+        for label, ids in by_gene.items()
+    ]
+    if len(by_gene) > 1:
+        sentences.append(
+            f"Pathways all {len(by_gene)} genes belong to: "
+            + (", ".join(f"{names[s]} ({s})" for s in shared) if shared else "none")
+            + "."
+        )
+    sentences.append("This is membership, not enrichment: no statistic was computed.")
+    if out.unresolved:
+        sentences.append(
+            "Not resolved: "
+            + "; ".join(f"{u['input']} ({u['reason']})" for u in out.unresolved)
+            + "."
+        )
+    if out.source_errors:
+        sentences.append(
+            "Source problems: "
+            + "; ".join(f"{e['source']} {e['reason']}" for e in out.source_errors)
+            + "."
+        )
+    return payloads.ok(
+        ENDPOINT,
+        query={"genes": [i.value for i in parsed.identifiers]},
+        rows=out.rows,
+        sources_used=out.sources_used or {"reactome"},
+        narrative=" ".join(sentences),
+        unresolved=out.unresolved,
+        source_errors=out.source_errors,
+        resolved_identifiers=resolution_rows(resolved),
+        shared_by_all=[{"pathway_id": s, "pathway_name": names[s]} for s in shared],
+    )

src/endpoints/targets.py

@@ -0,0 +1,136 @@
+"""targets_for_disease — the targets Open Targets most associates with a disease.
+
+A disease name is resolved by Open Targets' own search: an exact (case-insensitive) name match
+wins, else the first hit, and the payload names the id chosen and the alternatives it passed
+over. The ranking and the score are Open Targets' association score, relayed as its score; this
+endpoint ranks nothing itself. Open Targets moved most disease ids from EFO to MONDO
+(pancreatic ductal adenocarcinoma is ``MONDO_0005184``; the legacy ``EFO_0002618`` no longer
+resolves), so an unknown id is reported as unresolved with Open Targets' own message.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src import payloads
+from src.endpoints._common import (
+    Budget,
+    Collector,
+    according_to,
+    get_client,
+    humanise_list,
+    stamped,
+)
+from src.identifiers import parse_disease
+
+ENDPOINT = "targets_for_disease"
+OT_SEARCH = "OpenTargets_get_disease_id_description_by_name"
+OT_TARGETS = "OpenTargets_get_associated_targets_by_disease_efoId"
+DEFAULT_SIZE = 25
+MAX_SIZE = 50
+MAX_ALTERNATIVES = 4
+
+
+def targets_for_disease(disease: str = "", size: str = "") -> dict[str, Any]:
+    parsed = parse_disease(disease)
+    if not parsed.ok:
+        return payloads.refused(ENDPOINT, parsed.reason, parsed.message)
+    try:
+        n = int((size or str(DEFAULT_SIZE)).strip())
+    except ValueError:
+        n = 0
+    if not 1 <= n <= MAX_SIZE:
+        return payloads.refused(
+            ENDPOINT, "invalid_argument", f"size must be a whole number from 1 to {MAX_SIZE}."
+        )
+    client, budget, out = get_client(), Budget(), Collector()
+    given = parsed.identifiers[0]
+    resolution: dict[str, Any] = {"input": given.value}
+
+    if given.kind == "disease_id":
+        disease_id, disease_name = given.value, None
+    else:
+        result = out.call(client, budget, OT_SEARCH, {"diseaseName": given.value})
+        if result is None:
+            return payloads.error(
+                ENDPOINT,
+                "all_sources_failed",
+                "Open Targets did not answer.",
+                source_errors=out.source_errors,
+            )
+        hits = ((result.data.get("search") or {}).get("hits")) or []
+        if not hits:
+            return payloads.refused(
+                ENDPOINT, "unknown_disease", f"Open Targets finds no disease named {given.value!r}."
+            )
+        exact = [h for h in hits if (h.get("name") or "").casefold() == given.value.casefold()]
+        chosen = (exact or hits)[0]
+        disease_id, disease_name = chosen["id"], chosen.get("name")
+        resolution = stamped(
+            {
+                "input": given.value,
+                "id": disease_id,
+                "name": disease_name,
+                "matched": "exact name" if exact else "first search hit",
+                "alternatives": [
+                    {"id": h["id"], "name": h.get("name")} for h in hits if h["id"] != disease_id
+                ][:MAX_ALTERNATIVES],
+            },
+            result,
+            ref=disease_id,
+            url=f"https://platform.opentargets.org/disease/{disease_id}",
+        )
+
+    result = out.call(
+        client,
+        budget,
+        OT_TARGETS,
+        {"efoId": disease_id, "size": n},
+        unknown=("no disease for ID", disease_id),
+    )
+    if result is None:
+        if out.unresolved:
+            return payloads.refused(ENDPOINT, "unknown_disease", out.unresolved[0]["reason"])
+        return payloads.error(
+            ENDPOINT,
+            "all_sources_failed",
+            "Open Targets did not answer.",
+            source_errors=out.source_errors,
+        )
+    data = result.data.get("disease") or {}
+    disease_name = disease_name or data.get("name")
+    assoc = data.get("associatedTargets") or {}
+    for rank, row in enumerate(assoc.get("rows") or [], start=1):
+        target = row["target"]
+        out.rows.append(
+            stamped(
+                {
+                    "rank": rank,
+                    "target": target["approvedSymbol"],
+                    "target_ensembl_id": target["id"],
+                    "association_score": round(float(row["score"]), 4),
+                },
+                result,
+                ref=target["id"],
+                url=f"https://platform.opentargets.org/evidence/{target['id']}/{disease_id}",
+            )
+        )
+    lead = according_to(["opentargets"], out.retrieved)
+    symbols = [r["target"] for r in out.rows]
+    narrative = (
+        f"{lead}, the top {len(symbols)} of {assoc.get('count', len(symbols))} targets associated "
+        f"with {disease_name or disease_id} ({disease_id}), ranked by Open Targets' own "
+        f"association score: {humanise_list(symbols, limit=10)}."
+    )
+    if resolution.get("matched") == "first search hit":
+        narrative += f" No exact name match for {given.value!r}; Open Targets' first hit was used."
+    return payloads.ok(
+        ENDPOINT,
+        query={"disease": given.value, "size": n},
+        rows=out.rows,
+        sources_used=out.sources_used,
+        narrative=narrative,
+        unresolved=out.unresolved,
+        source_errors=out.source_errors,
+        disease=resolution,
+    )

src/endpoints/trials.py

@@ -0,0 +1,149 @@
+"""trials_for_genes — ClinicalTrials.gov studies whose intervention matches the gene.
+
+Memo decision 3: ToolUniverse for interactive lookups; lit-agent's own harvester keeps the
+weekly digest. ToolUniverse narrows an intervention search to the intervention's name and other
+name (Phase 0 finding 5: "CD40" gives the one pancreas-specific mitazalimab trial, where a broad
+API query also returns two solid-tumour basket trials). That rewrite is helpful but silent, so
+every payload states it: ``query_semantics`` in words, and ``executed_queries`` with the exact
+query ClinicalTrials.gov ran, taken from the response itself and pinned by a recorded fixture.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from src import payloads
+from src.endpoints._common import Budget, Collector, according_to, get_client, stamped
+from src.identifiers import parse_disease, parse_gene_list
+
+ENDPOINT = "trials_for_genes"
+CT_SEARCH = "ClinicalTrials_search_studies"
+DEFAULT_CONDITION = "pancreatic cancer"
+DEFAULT_STATUS = "RECRUITING"
+STATUSES = (
+    "RECRUITING",
+    "NOT_YET_RECRUITING",
+    "ACTIVE_NOT_RECRUITING",
+    "ENROLLING_BY_INVITATION",
+    "COMPLETED",
+    "ANY",
+)
+PAGE_SIZE = 100
+QUERY_SEMANTICS = (
+    "A study is listed when its intervention name or intervention other-name matches the gene "
+    "symbol (ToolUniverse's rewrite of the ClinicalTrials.gov query). Studies that mention the "
+    "gene only in their title, outcomes or eligibility are not listed, and a match on the name is "
+    "not evidence that the intervention acts on the gene's product."
+)
+
+
+def trials_for_genes(genes: str = "", condition: str = "", status: str = "") -> dict[str, Any]:
+    parsed = parse_gene_list(genes, allow_ensembl=False)
+    if not parsed.ok:
+        return payloads.refused(ENDPOINT, parsed.reason, parsed.message)
+    cond = parse_disease(condition or DEFAULT_CONDITION)
+    if not cond.ok:
+        return payloads.refused(ENDPOINT, cond.reason, cond.message)
+    if cond.identifiers[0].kind != "disease_name":
+        return payloads.refused(
+            ENDPOINT,
+            "invalid_identifier",
+            "Give the condition as a name, e.g. 'pancreatic cancer'.",
+        )
+    wanted = (status or DEFAULT_STATUS).strip().upper()
+    if wanted not in STATUSES:
+        return payloads.refused(
+            ENDPOINT,
+            "invalid_argument",
+            f"status must be one of {', '.join(STATUSES)}; got {wanted[:24]!r}.",
+        )
+    condition_name = cond.identifiers[0].value
+    client, budget, out = get_client(), Budget(), Collector()
+    executed: list[dict[str, Any]] = []
+    per_gene: list[tuple[str, int, int]] = []
+    symbols = [i.value for i in parsed.identifiers]
+    for idx, gene in enumerate(symbols):
+        if budget.spent:
+            out.out_of_budget(symbols[idx:])
+            break
+        args: dict[str, Any] = {
+            "query_cond": condition_name,
+            "query_intr": gene,
+            "page_size": PAGE_SIZE,
+        }
+        if wanted != "ANY":
+            args["filter_status"] = wanted
+        result = out.call(client, budget, CT_SEARCH, args)
+        if result is None:
+            continue
+        data = result.data
+        executed.append({"gene": gene, "executed_query": data.get("executed_query")})
+        studies = data.get("studies") or []
+        for study in studies:
+            nct = study["nct_id"]
+            out.rows.append(
+                stamped(
+                    {
+                        "gene": gene,
+                        "nct_id": nct,
+                        "title": study.get("brief_title"),
+                        "status": study.get("status"),
+                        "phases": study.get("phases") or [],
+                        "study_type": study.get("study_type"),
+                        "conditions": study.get("conditions") or [],
+                        "interventions": study.get("interventions") or [],
+                        "sponsor": study.get("sponsor"),
+                        "start_date": study.get("start_date"),
+                        "completion_date": study.get("completion_date"),
+                    },
+                    result,
+                    ref=nct,
+                    url=f"https://clinicaltrials.gov/study/{nct}",
+                )
+            )
+        per_gene.append((gene, len(studies), int(data.get("total_count") or len(studies))))
+
+    if not out.rows and out.source_errors and not per_gene:
+        return payloads.error(
+            ENDPOINT,
+            "all_sources_failed",
+            "ClinicalTrials.gov did not answer; nothing was looked up.",
+            source_errors=out.source_errors,
+        )
+    lead = according_to(["clinicaltrials"], out.retrieved)
+    kind = "of any status" if wanted == "ANY" else wanted
+    clauses = []
+    for gene, shown, total in per_gene:
+        ids = [r["nct_id"] for r in out.rows if r["gene"] == gene]
+        listed = f" ({', '.join(ids[:10])}" + (
+            f" and {len(ids) - 10} more" if len(ids) > 10 else ""
+        )
+        listed += ")" if ids else ""
+        more = f", showing the first {shown}" if total > shown else ""
+        noun = "study" if total == 1 else "studies"
+        clauses.append(f"{gene}: {total} {kind} {noun}{listed}{more}")
+    sentences = []
+    if clauses:
+        sentences.append(
+            f"{lead}, studies for '{condition_name}' with an intervention matching each gene — "
+            + "; ".join(clauses)
+            + "."
+        )
+    sentences.append("Matching is by intervention name only; see query_semantics.")
+    if out.source_errors:
+        sentences.append(
+            "Source problems: "
+            + "; ".join(f"{e['source']} {e['reason']}" for e in out.source_errors)
+            + "."
+        )
+    return payloads.ok(
+        ENDPOINT,
+        query={"genes": symbols, "condition": condition_name, "status": wanted},
+        rows=out.rows,
+        sources_used=out.sources_used or {"clinicaltrials"},
+        narrative=" ".join(sentences),
+        unresolved=out.unresolved,
+        source_errors=out.source_errors,
+        query_semantics=QUERY_SEMANTICS,
+        executed_queries=executed,
+    )

src/identifiers.py

@@ -75,12 +75,14 @@ def _dedupe_key(token: str) -> str:
     return token if token.startswith("ENSG") else token.upper()
 
 
-def classify_gene_token(token: str, *, allow_uniprot: bool = False) -> str | None:
+def classify_gene_token(
+    token: str, *, allow_uniprot: bool = False, allow_ensembl: bool = True
+) -> str | None:
     """The identifier kind for one gene/protein token, or None if it is not one."""
     if _SAMPLE_ID.match(token):
         return None
     if ENSEMBL_GENE.match(token):
-        return "ensembl"
+        return "ensembl" if allow_ensembl else None
     if allow_uniprot and UNIPROT.match(token):
         return "uniprot"
     if len(token) <= 25 and SYMBOL.match(token):
@@ -88,8 +90,14 @@ def classify_gene_token(token: str, *, allow_uniprot: bool = False) -> str | Non
     return None
 
 
-def parse_gene_list(raw: str | list[str] | None, *, allow_uniprot: bool = False) -> Parsed:
-    """Split, de-duplicate (order kept) and validate a gene list."""
+def parse_gene_list(
+    raw: str | list[str] | None, *, allow_uniprot: bool = False, allow_ensembl: bool = True
+) -> Parsed:
+    """Split, de-duplicate (order kept) and validate a gene list.
+
+    ``allow_ensembl=False`` is for the endpoints that resolve through HGNC symbols
+    (annotate_genes, pathways_for_genes); drugs_for_targets accepts Ensembl ids directly.
+    """
     if isinstance(raw, list):
         tokens = [str(t).strip() for t in raw]
     else:
@@ -103,12 +111,15 @@ def parse_gene_list(raw: str | list[str] | None, *, allow_uniprot: bool = False)
             "too_many_identifiers",
             f"{len(unique)} identifiers given; at most {MAX_IDENTIFIERS} per call.",
         )
-    bad = [t for t in tokens if classify_gene_token(t, allow_uniprot=allow_uniprot) is None]
+    kinds = {"allow_uniprot": allow_uniprot, "allow_ensembl": allow_ensembl}
+    bad = [t for t in tokens if classify_gene_token(t, **kinds) is None]
     if bad:
         shown = ", ".join(_echo(t) for t in bad[:5])
         more = f" and {len(bad) - 5} more" if len(bad) > 5 else ""
-        accepted = "HGNC symbols or Ensembl gene ids" + (
-            " or UniProt accessions" if allow_uniprot else ""
+        accepted = (
+            "HGNC symbols"
+            + (" or Ensembl gene ids" if allow_ensembl else "")
+            + (" or UniProt accessions" if allow_uniprot else "")
         )
         return _refuse(
             "invalid_identifier",
@@ -122,7 +133,7 @@ def parse_gene_list(raw: str | list[str] | None, *, allow_uniprot: bool = False)
         if key in emitted:
             continue
         emitted.add(key)
-        out.append(Identifier(t, classify_gene_token(t, allow_uniprot=allow_uniprot) or "symbol"))
+        out.append(Identifier(t, classify_gene_token(t, **kinds) or "symbol"))
     return Parsed(identifiers=tuple(out), duplicates_dropped=len(tokens) - len(out))
 
 

src/schemas/ChEMBL_get_drug_mechanisms.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass.",
+  "type": "object",
+  "required": [
+    "mechanisms"
+  ],
+  "properties": {
+    "mechanisms": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "mechanism_of_action": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "action_type": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

src/schemas/ClinicalTrials_search_studies.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass. executed_query is required: it is how a payload states the query ClinicalTrials.gov actually ran (memo finding 5).",
+  "type": "object",
+  "required": [
+    "studies",
+    "total_count",
+    "executed_query"
+  ],
+  "properties": {
+    "total_count": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "executed_query": {
+      "type": "object",
+      "required": [
+        "query.intr"
+      ]
+    },
+    "studies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "nct_id"
+        ],
+        "properties": {
+          "nct_id": {
+            "type": "string",
+            "pattern": "^NCT\\d{8}$"
+          },
+          "brief_title": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "status": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "phases": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            }
+          },
+          "interventions": {
+            "type": [
+              "array",
+              "null"
+            ],
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/schemas/HGNC_fetch_gene_by_symbol.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass. An unknown symbol comes back as an empty object, which is an unresolved input, not drift.",
+  "type": "object",
+  "dependentRequired": {
+    "symbol": [
+      "hgnc_id"
+    ]
+  },
+  "properties": {
+    "symbol": {
+      "type": "string",
+      "minLength": 1
+    },
+    "hgnc_id": {
+      "type": "string",
+      "pattern": "^HGNC:\\d+$"
+    },
+    "name": {
+      "type": "string"
+    },
+    "locus_type": {
+      "type": "string"
+    },
+    "ensembl_gene_id": {
+      "type": "string",
+      "pattern": "^ENSG\\d{11}$"
+    },
+    "uniprot_ids": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 6
+      }
+    }
+  }
+}

src/schemas/OpenTargets_get_associated_drugs_by_target_ensemblID.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$comment": "Pinned 2026-10-20 (s1) from the Phase 0 response recorded through ToolUniverse 1.5.6 on 2026-10-12 (TNFRSF10B). Only the fields drugs_for_targets reads are required. A null target means the id is unknown to Open Targets: an unresolved input, not drift. `target` is object-or-null in one schema rather than a oneOf, so a drift error names the field that moved instead of 'not valid under any of the given schemas' (JSON Schema's required/properties only apply to objects).",
+  "$comment": "Pinned 2026-10-20 (s1) from the Phase 0 response recorded through ToolUniverse 1.5.6 on 2026-10-12 (TNFRSF10B). Only the fields drugs_for_targets reads are required. A null target means the id is unknown to Open Targets: an unresolved input, not drift. `target` is object-or-null in one schema rather than a oneOf, so a drift error names the field that moved instead of 'not valid under any of the given schemas' (JSON Schema's required/properties only apply to objects). s2: `rows` is optional because ToolUniverse omits it when the count is 0 (STAT1, recorded 2026-10-20); `truncated` says it returned fewer rows than Open Targets holds.",
   "type": "object",
   "required": [
     "target"
@@ -28,8 +28,7 @@
         "drugAndClinicalCandidates": {
           "type": "object",
           "required": [
-            "count",
-            "rows"
+            "count"
           ],
           "properties": {
             "count": {
@@ -70,6 +69,9 @@
                   }
                 }
               }
+            },
+            "truncated": {
+              "type": "boolean"
             }
           }
         }

src/schemas/OpenTargets_get_associated_targets_by_disease_efoId.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass. Scores are Open Targets' association scores, relayed as such.",
+  "type": "object",
+  "required": [
+    "disease"
+  ],
+  "properties": {
+    "disease": {
+      "type": [
+        "object",
+        "null"
+      ],
+      "required": [
+        "id",
+        "associatedTargets"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "associatedTargets": {
+          "type": "object",
+          "required": [
+            "count",
+            "rows"
+          ],
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "rows": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "target",
+                  "score"
+                ],
+                "properties": {
+                  "target": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "approvedSymbol"
+                    ],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "pattern": "^ENSG\\d{11}$"
+                      },
+                      "approvedSymbol": {
+                        "type": "string",
+                        "minLength": 1
+                      }
+                    }
+                  },
+                  "score": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 1
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/schemas/OpenTargets_get_disease_id_description_by_name.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass.",
+  "type": "object",
+  "required": [
+    "search"
+  ],
+  "properties": {
+    "search": {
+      "type": "object",
+      "required": [
+        "hits"
+      ],
+      "properties": {
+        "hits": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "name"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "name": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/schemas/Reactome_map_uniprot_to_pathways.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass. Reactome's UniProt mapping returns the lowest-level pathways for the protein.",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": [
+      "stId",
+      "displayName"
+    ],
+    "properties": {
+      "stId": {
+        "type": "string",
+        "pattern": "^R-[A-Z]{3}-\\d+$"
+      },
+      "displayName": {
+        "type": "string",
+        "minLength": 1
+      },
+      "isInDisease": {
+        "type": "boolean"
+      }
+    }
+  }
+}

src/schemas/UniProt_search.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$comment": "Pinned 2026-10-20 (s2) from the responses recorded in tests/fixtures/cassettes/ through ToolUniverse 1.5.6. Only the fields the row builder reads are required; added upstream fields pass.",
+  "type": "object",
+  "required": [
+    "results"
+  ],
+  "properties": {
+    "results": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "primaryAccession"
+        ],
+        "properties": {
+          "primaryAccession": {
+            "type": "string",
+            "minLength": 6
+          },
+          "proteinDescription": {
+            "type": "object"
+          },
+          "genes": {
+            "type": "array"
+          },
+          "comments": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "commentType"
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+}

src/tu_client.py

@@ -264,9 +264,12 @@ class ToolClient:
         limiters: RateLimiters | None = None,
         clock: Callable[[], float] = time.time,
         tooluniverse_version: str | None = None,
+        tooluniverse: Any = None,
     ):
         self._runner = runner
-        self._tu = None
+        # gradio_ui passes an instance built at import, so a Space that must not start (a model
+        # key, a version drift, a widened tool set) fails at startup, not on its first call.
+        self._tu = tooluniverse
         self.cache = cache if cache is not None else ResponseCache()
         self.limiters = limiters if limiters is not None else RateLimiters()
         self._clock = clock
@@ -308,18 +311,22 @@ class ToolClient:
 
         runner = self._runner or self._default_runner
         future = self._pool.submit(runner, tool, dict(args))
-        try:
-            raw = future.result(timeout=cfg["timeout_seconds"])
-        except concurrent.futures.TimeoutError:
+        # `wait`, not `result(timeout=…)`: since Python 3.11 concurrent.futures.TimeoutError IS the
+        # builtin TimeoutError, so a source's own read timeout raised inside the call would be
+        # indistinguishable from our deadline passing (caught by a test on 2026-10-20).
+        done, _ = concurrent.futures.wait([future], timeout=cfg["timeout_seconds"])
+        if not done:
             future.cancel()
             raise SourceError(
                 source,
                 "source_unavailable",
                 f"{cfg['name']} did not answer within {cfg['timeout_seconds']} s",
-            ) from None
+            )
+        try:
+            raw = future.result()
         except SourceError:
             raise
-        except Exception as e:
+        except Exception as e:  # any failure inside a source call is structured, never raised
             raise SourceError(source, "source_unavailable", f"{tool}: {type(e).__name__}") from e
         retrieved_at = self._clock()
 

tests/conftest.py

@@ -43,6 +43,34 @@ def _blocked_connect(self, address):
 
 socket.socket.connect = _blocked_connect  # type: ignore[method-assign]
 
+# gradio's local LoginButton mock reaches for a HuggingFace identity while the app graph builds at
+# `import gradio_ui`. Stub `_get_mocked_oauth_info` (NOT `whoami`, which gradio calls through its
+# own reference) — the pdac-spatial-agent lesson of 2026-09-28. A gradio upgrade can rename this
+# private, and `setattr` on a missing name succeeds silently, so fail here if it is gone.
+import gradio.oauth as _gr_oauth
+
+_GRADIO_OAUTH_MOCK_HOOK = "_get_mocked_oauth_info"
+if not hasattr(_gr_oauth, _GRADIO_OAUTH_MOCK_HOOK):
+    raise RuntimeError(
+        f"gradio.oauth.{_GRADIO_OAUTH_MOCK_HOOK} no longer exists; re-point the offline OAuth "
+        "stub in tests/conftest.py (a stale stub, not a network problem)."
+    )
+_gr_oauth._get_mocked_oauth_info = lambda: {  # type: ignore[assignment]
+    "access_token": "test-token",
+    "token_type": "bearer",
+    "expires_at": 0,
+    "expires_in": 28800,
+    "scope": "openid profile",
+    "userinfo": {
+        "sub": "test-user-id",
+        "name": "Test User",
+        "preferred_username": "test-user",
+        "profile": "https://huggingface.co/test-user",
+        "picture": None,
+        "email": None,
+    },
+}
+
 FIXTURES = Path(__file__).resolve().parent / "fixtures"
 
 
@@ -101,3 +129,71 @@ def memory_cache(clock):
 def tnfrsf10b_response() -> dict:
     """The real Open Targets response for DR5, recorded through ToolUniverse 1.5.6 in Phase 0."""
     return load_fixture("phase0/opentargets_drugs_TNFRSF10B.json")["response"]
+
+
+# --------------------------------------------------------------------------- #
+# Cassette replay: what the sources said on the recording day, with sockets blocked.
+# --------------------------------------------------------------------------- #
+CASSETTES = FIXTURES / "cassettes"
+SCENARIOS = sorted(p.stem for p in CASSETTES.glob("*.json"))
+
+
+class CassetteRunner:
+    """Answers each (tool, arguments) with the response recorded for it, or fails loudly."""
+
+    def __init__(self, name: str):
+        from src.cache import cache_key
+
+        self.name = name
+        self.cassette = json.loads((CASSETTES / f"{name}.json").read_text(encoding="utf-8"))
+        self._key = cache_key
+        self.responses = {
+            cache_key(c["tool"], c["args"]): c["response"] for c in self.cassette["calls"]
+        }
+        self.calls: list[tuple[str, dict]] = []
+
+    def __call__(self, tool: str, args: dict):
+        self.calls.append((tool, dict(args)))
+        try:
+            return self.responses[self._key(tool, args)]
+        except KeyError:
+            raise AssertionError(
+                f"{tool} {args} is not in cassette {self.name!r}: the endpoint now makes a call "
+                "that was not recorded. Re-record with scripts/record_fixtures.py and review the diff."
+            ) from None
+
+
+def replay_client(name: str):
+    """(client, runner) replaying cassette ``name`` at its recording time, rate limits on a fake clock."""
+    from src.cache import ResponseCache
+    from src.ratelimit import RateLimiters
+    from src.tu_client import ToolClient
+
+    runner = CassetteRunner(name)
+    clock = FakeClock(start=runner.cassette["_recorded"]["recorded_at_epoch"])
+    client = ToolClient(
+        runner=runner,
+        cache=ResponseCache(":memory:", clock=clock),
+        limiters=RateLimiters(clock=clock, sleep=clock.sleep),
+        clock=clock,
+        tooluniverse_version=runner.cassette["_recorded"]["tooluniverse_version"],
+    )
+    return client, runner
+
+
+@pytest.fixture()
+def replay():
+    """``replay(name)`` → the endpoint's payload for that recorded scenario."""
+    from src.endpoints import ENDPOINTS, _common
+
+    runners = []
+
+    def run(name: str) -> dict:
+        client, runner = replay_client(name)
+        runners.append(runner)
+        _common.set_client(client)
+        meta = runner.cassette["_recorded"]
+        return ENDPOINTS[meta["endpoint"]][0](*meta["arguments"])
+
+    yield run
+    _common.set_client(None)

tests/fixtures/cassettes/c1_annotate_kras_tp53_sord2p.json

@@ -0,0 +1,1025 @@
+{
+ "_recorded": {
+  "scenario": "c1_annotate_kras_tp53_sord2p",
+  "why": "plan C1(c): SORD2P listed as unresolved, not guessed",
+  "endpoint": "annotate_genes",
+  "arguments": [
+   "KRAS,TP53,SORD2P"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:43:45Z",
+  "recorded_at_epoch": 1792557823.37,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "hgnc": "No restrictions on access or use (HGNC data release policy); citation requested",
+   "uniprot": "CC BY 4.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "KRAS"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "hgnc_id": "HGNC:6407",
+     "gencc": "HGNC:6407",
+     "alias_symbol": [
+      "KRAS1",
+      "K-Ras4B"
+     ],
+     "rgd_id": [
+      "RGD:2981"
+     ],
+     "ucsc_id": "uc001rgp.3",
+     "cosmic": "KRAS",
+     "location": "12p12.1",
+     "uniprot_ids": [
+      "P01116"
+     ],
+     "prev_name": [
+      "KRAS proto-oncogene, GTPase",
+      "v-Ki-ras2 Kirsten rat sarcoma 2 viral oncogene homolog",
+      "v-Ki-ras2 Kirsten rat sarcoma viral oncogene homolog",
+      "Kirsten rat sarcoma viral oncogene homolog"
+     ],
+     "omim_id": [
+      "190070"
+     ],
+     "uuid": "4e5a8988-4945-4b5b-9182-a394193ae050",
+     "lsdb": [
+      "LRG_344|http://ftp.ebi.ac.uk/pub/databases/lrgex/LRG_344.xml"
+     ],
+     "name": "KRas proto-oncogene, GTPase",
+     "status": "Approved",
+     "iuphar": "HGNC:6407",
+     "mane_select": [
+      "ENST00000311936.8",
+      "NM_004985.5"
+     ],
+     "refseq_accession": [
+      "NM_033360"
+     ],
+     "agr": "HGNC:6407",
+     "date_modified": "2026-06-10T00:00:00Z",
+     "locus_type": "gene with protein product",
+     "date_approved_reserved": "1988-06-02T00:00:00Z",
+     "date_name_changed": "2026-06-10T00:00:00Z",
+     "entrez_id": "3845",
+     "prev_symbol": [
+      "KRAS2"
+     ],
+     "gene_group": [
+      "RAS type GTPase family"
+     ],
+     "ena": [
+      "BC010502"
+     ],
+     "mgd_id": [
+      "MGI:96680"
+     ],
+     "ccds_id": [
+      "CCDS8702",
+      "CCDS8703"
+     ],
+     "ensembl_gene_id": "ENSG00000133703",
+     "vega_id": "OTTHUMG00000171193",
+     "locus_group": "protein-coding gene",
+     "orphanet": 122879,
+     "date_symbol_changed": "2005-01-24T00:00:00Z",
+     "gene_group_id": [
+      389
+     ],
+     "symbol": "KRAS"
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "KRAS",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "TP53"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "symbol": "TP53",
+     "locus_group": "protein-coding gene",
+     "orphanet": 120204,
+     "gene_group_id": [
+      4068
+     ],
+     "vega_id": "OTTHUMG00000162125",
+     "ensembl_gene_id": "ENSG00000141510",
+     "ccds_id": [
+      "CCDS11118",
+      "CCDS45605",
+      "CCDS45606",
+      "CCDS73963",
+      "CCDS73964",
+      "CCDS73965",
+      "CCDS73966",
+      "CCDS73967",
+      "CCDS73968",
+      "CCDS73969",
+      "CCDS73970",
+      "CCDS73971"
+     ],
+     "gene_group": [
+      "p53 transcription factor family"
+     ],
+     "ena": [
+      "AF307851"
+     ],
+     "mgd_id": [
+      "MGI:98834"
+     ],
+     "date_approved_reserved": "1986-01-01T00:00:00Z",
+     "date_name_changed": "2008-01-16T00:00:00Z",
+     "entrez_id": "7157",
+     "date_modified": "2023-01-20T00:00:00Z",
+     "alias_name": [
+      "Li-Fraumeni syndrome"
+     ],
+     "locus_type": "gene with protein product",
+     "pubmed_id": [
+      6396087,
+      3456488,
+      2047879
+     ],
+     "refseq_accession": [
+      "NM_000546"
+     ],
+     "mane_select": [
+      "ENST00000269305.9",
+      "NM_000546.6"
+     ],
+     "agr": "HGNC:11998",
+     "status": "Approved",
+     "omim_id": [
+      "191170"
+     ],
+     "uuid": "22e519f0-ad02-4326-b78b-d972b5873187",
+     "lsdb": [
+      "IARC TP53 Mutation Database|http://www-p53.iarc.fr/",
+      "p53 UMD TP53 mutation database|http://p53.fr/",
+      "Database of Germline p53 Mutations|http://www.lf2.cuni.cz/projects/germline_mut_p53.htm",
+      "MUTP53LOAD, Mutant p53 Loss Of Activity Database|http://www.umd.be:2072/",
+      "LRG_321|http://ftp.ebi.ac.uk/pub/databases/lrgex/LRG_321.xml"
+     ],
+     "name": "tumor protein p53",
+     "rgd_id": [
+      "RGD:3889"
+     ],
+     "ucsc_id": "uc060aur.1",
+     "location": "17p13.1",
+     "cosmic": "TP53",
+     "uniprot_ids": [
+      "P04637"
+     ],
+     "hgnc_id": "HGNC:11998",
+     "gencc": "HGNC:11998",
+     "alias_symbol": [
+      "p53",
+      "LFS1"
+     ]
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "TP53",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "SORD2P"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "date_approved_reserved": "2014-03-21T00:00:00Z",
+     "hgnc_id": "HGNC:49919",
+     "entrez_id": "653381",
+     "location": "15q21.1",
+     "uuid": "002482ab-9cb8-42cd-b314-14153e1dfe38",
+     "name": "sorbitol dehydrogenase 2, pseudogene",
+     "status": "Approved",
+     "ensembl_gene_id": "ENSG00000259479",
+     "pubmed_id": [
+      9880675
+     ],
+     "agr": "HGNC:49919",
+     "refseq_accession": [
+      "NR_146393"
+     ],
+     "vega_id": "OTTHUMG00000171966",
+     "pseudogene.org": "PGOHUM00000246773",
+     "locus_group": "pseudogene",
+     "date_modified": "2014-03-21T00:00:00Z",
+     "symbol": "SORD2P",
+     "locus_type": "pseudogene"
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "SORD2P",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "UniProt_search",
+   "args": {
+    "query": "(accession:P01116 OR accession:P04637) AND reviewed:true AND organism_id:9606",
+    "limit": 2,
+    "fields": [
+     "accession",
+     "gene_primary",
+     "protein_name",
+     "cc_function",
+     "cc_subcellular_location"
+    ]
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "total_results": 2,
+     "returned": 2,
+     "results": [
+      {
+       "entryType": "UniProtKB reviewed (Swiss-Prot)",
+       "primaryAccession": "P01116",
+       "proteinDescription": {
+        "recommendedName": {
+         "fullName": {
+          "value": "GTPase KRas"
+         },
+         "ecNumbers": [
+          {
+           "evidences": [
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "20949621"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "39809765"
+            }
+           ],
+           "value": "3.6.5.2"
+          }
+         ]
+        },
+        "alternativeNames": [
+         {
+          "fullName": {
+           "value": "K-Ras 2"
+          }
+         },
+         {
+          "fullName": {
+           "value": "Ki-Ras"
+          }
+         },
+         {
+          "fullName": {
+           "value": "c-K-ras"
+          }
+         },
+         {
+          "fullName": {
+           "value": "c-Ki-ras"
+          }
+         }
+        ],
+        "contains": [
+         {
+          "recommendedName": {
+           "fullName": {
+            "value": "GTPase KRas, N-terminally processed"
+           }
+          }
+         }
+        ],
+        "flag": "Precursor"
+       },
+       "genes": [
+        {
+         "geneName": {
+          "value": "KRAS"
+         }
+        }
+       ],
+       "comments": [
+        {
+         "texts": [
+          {
+           "evidences": [
+            {
+             "evidenceCode": "ECO:0000250",
+             "source": "UniProtKB",
+             "id": "P08644"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "20949621"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "22711838"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "23698361"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "24623306"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "39809765"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "40934300"
+            }
+           ],
+           "value": "Signal transducer in the Ras-MAPK signaling pathway that regulates cell proliferation and survival (PubMed:22711838, PubMed:23698361). Ras proteins bind GDP/GTP and possess intrinsic GTPase activity (PubMed:20949621, PubMed:39809765). Activates MAPK1/MAPK3 resulting in phosphorylation and ultimately degradation of GJA1 (By similarity). Plays a role in promoting oncogenic events by inducing transcriptional silencing of tumor suppressor genes (TSGs) in colorectal cancer (CRC) cells in a ZNF304-dependent manner (PubMed:24623306). Recognized by LZTR1 that mediates its ubiquitination by a BCR (BTB-CUL3-RBX1) E3 ubiquitin-protein ligase complex (PubMed:40934300)"
+          }
+         ],
+         "commentType": "FUNCTION"
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "subcellularLocations": [
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "22431598"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "23524970"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "23698361"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "29239724"
+             }
+            ],
+            "value": "Cell membrane",
+            "id": "SL-0039"
+           },
+           "topology": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "29239724"
+             },
+             {
+              "evidenceCode": "ECO:0000305",
+              "source": "PubMed",
+              "id": "23698361"
+             }
+            ],
+            "value": "Lipid-anchor",
+            "id": "SL-9901"
+           },
+           "orientation": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000305",
+              "source": "PubMed",
+              "id": "23698361"
+             }
+            ],
+            "value": "Cytoplasmic side",
+            "id": "SL-9910"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "29239724"
+             }
+            ],
+            "value": "Endomembrane system",
+            "id": "SL-0147"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "23524970"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "23698361"
+             }
+            ],
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 2B",
+         "subcellularLocations": [
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "28619714"
+             }
+            ],
+            "value": "Cell membrane",
+            "id": "SL-0039"
+           },
+           "topology": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000305",
+              "source": "PubMed",
+              "id": "28619714"
+             }
+            ],
+            "value": "Lipid-anchor",
+            "id": "SL-9901"
+           }
+          }
+         ]
+        }
+       ],
+       "extraAttributes": {
+        "uniParcId": "UPI0000133132"
+       }
+      },
+      {
+       "entryType": "UniProtKB reviewed (Swiss-Prot)",
+       "primaryAccession": "P04637",
+       "proteinDescription": {
+        "recommendedName": {
+         "fullName": {
+          "value": "Cellular tumor antigen p53"
+         }
+        },
+        "alternativeNames": [
+         {
+          "fullName": {
+           "value": "Antigen NY-CO-13"
+          }
+         },
+         {
+          "fullName": {
+           "value": "Phosphoprotein p53"
+          }
+         },
+         {
+          "fullName": {
+           "value": "Tumor suppressor p53"
+          }
+         }
+        ]
+       },
+       "genes": [
+        {
+         "geneName": {
+          "value": "TP53"
+         }
+        }
+       ],
+       "comments": [
+        {
+         "texts": [
+          {
+           "evidences": [
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "11025664"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "12524540"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "12810724"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "15186775"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "15340061"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "17189187"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "17317671"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "17349958"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "19556538"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "20673990"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "20959462"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "22726440"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "24051492"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "24652652"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "35618207"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "36634798"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "38653238"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "9840937"
+            }
+           ],
+           "value": "Multifunctional transcription factor that induces cell cycle arrest, DNA repair or apoptosis upon binding to its target DNA sequence (PubMed:11025664, PubMed:12524540, PubMed:12810724, PubMed:15186775, PubMed:15340061, PubMed:17317671, PubMed:17349958, PubMed:19556538, PubMed:20673990, PubMed:20959462, PubMed:22726440, PubMed:24051492, PubMed:24652652, PubMed:35618207, PubMed:36634798, PubMed:38653238, PubMed:9840937). Acts as a tumor suppressor in many tumor types; induces growth arrest or apoptosis depending on the physiological circumstances and cell type (PubMed:11025664, PubMed:12524540, PubMed:12810724, PubMed:15186775, PubMed:15340061, PubMed:17189187, PubMed:17317671, PubMed:17349958, PubMed:19556538, PubMed:20673990, PubMed:20959462, PubMed:22726440, PubMed:24051492, PubMed:24652652, PubMed:38653238, PubMed:9840937). Negatively regulates cell division by controlling expression of a set of genes required for this process (PubMed:11025664, PubMed:12524540, PubMed:12810724, PubMed:15186775, PubMed:15340061, PubMed:17317671, PubMed:17349958, PubMed:19556538, PubMed:20673990, PubMed:20959462, PubMed:22726440, PubMed:24051492, PubMed:24652652, PubMed:9840937). One of the activated genes is an inhibitor of cyclin-dependent kinases. Apoptosis induction seems to be mediated either by stimulation of BAX and FAS antigen expression, or by repression of Bcl-2 expression (PubMed:12524540, PubMed:17189187). Its pro-apoptotic activity is activated via its interaction with PPP1R13B/ASPP1 or TP53BP2/ASPP2 (PubMed:12524540). However, this activity is inhibited when the interaction with PPP1R13B/ASPP1 or TP53BP2/ASPP2 is displaced by PPP1R13L/iASPP (PubMed:12524540). In cooperation with mitochondrial PPIF is involved in activating oxidative stress-induced necrosis; the function is largely independent of transcription. Induces the transcription of long intergenic non-coding RNA p21 (lincRNA-p21) and lincRNA-Mkln1. LincRNA-p21 participates in TP53-dependent transcriptional repression leading to apoptosis and seems to have an effect on cell-cycle regulation. Implicated in Notch signaling cross-over. Prevents CDK7 kinase activity when associated to CAK complex in response to DNA damage, thus stopping cell cycle progression. Isoform 2 enhances the transactivation activity of isoform 1 from some but not all TP53-inducible promoters. Isoform 4 suppresses transactivation activity and impairs growth suppression mediated by isoform 1. Isoform 7 inhibits isoform 1-mediated apoptosis. Regulates the circadian clock by repressing CLOCK-BMAL1-mediated transcriptional activation of PER2 (PubMed:24051492)"
+          }
+         ],
+         "commentType": "FUNCTION"
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "note": {
+          "texts": [
+           {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "12810724"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "22726440"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "24625977"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "27323408"
+             }
+            ],
+            "value": "Recruited into PML bodies together with CHEK2 (PubMed:12810724). Translocates to mitochondria upon oxidative stress (PubMed:22726440). Translocates to mitochondria in response to mitomycin C treatment (PubMed:27323408). Competitive inhibition of TP53 interaction with HSPA9/MOT-2 by UBXN2A results in increased protein abundance and subsequent translocation of TP53 to the nucleus (PubMed:24625977)"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "15340061"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "17170702"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "19011621"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "19033443"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "21597459"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "22726440"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "22914926"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "24625977"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "26634371"
+             }
+            ],
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "15340061"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "17170702"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "17591690"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "18206965"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "19011621"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "21597459"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "22914926"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "24625977"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "26634371"
+             }
+            ],
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "11025664"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "12810724"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "36108750"
+             }
+            ],
+            "value": "Nucleus, PML body",
+            "id": "SL-0465"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "17170702"
+             }
+            ],
+            "value": "Endoplasmic reticulum",
+            "id": "SL-0095"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "22726440"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "25168243"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "27323408"
+             }
+            ],
+            "value": "Mitochondrion matrix",
+            "id": "SL-0170"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "28842590"
+             }
+            ],
+            "value": "Cytoplasm, cytoskeleton, microtubule organizing center, centrosome",
+            "id": "SL-0048"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 1",
+         "note": {
+          "texts": [
+           {
+            "value": "Predominantly nuclear but localizes to the cytoplasm when expressed with isoform 4"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "23752197"
+             }
+            ],
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 2",
+         "note": {
+          "texts": [
+           {
+            "value": "Localized mainly in the nucleus with minor staining in the cytoplasm"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 3",
+         "note": {
+          "texts": [
+           {
+            "value": "Localized in the nucleus in most cells but found in the cytoplasm in some cells"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 4",
+         "note": {
+          "texts": [
+           {
+            "value": "Predominantly nuclear but translocates to the cytoplasm following cell stress"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 7",
+         "note": {
+          "texts": [
+           {
+            "value": "Localized mainly in the nucleus with minor staining in the cytoplasm"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 8",
+         "note": {
+          "texts": [
+           {
+            "value": "Localized in both nucleus and cytoplasm in most cells. In some cells, forms foci in the nucleus that are different from nucleoli"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "molecule": "Isoform 9",
+         "subcellularLocations": [
+          {
+           "location": {
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          }
+         ]
+        }
+       ],
+       "extraAttributes": {
+        "uniParcId": "UPI000002ED67"
+       }
+      }
+     ],
+     "normalization_note": "Query scope widened: 'organism_id:<taxid>' was rewritten to 'taxonomy_id:<taxid>'. UniProt's organism_id field (labelled 'Organism [OS]') matches only an entry's own organism node, while taxonomy_id ('Taxonomy [OC]') matches anywhere in the entry's lineage. Most bacterial entries are annotated at strain level, so a species-level organism_id silently returns 0 or an undercount (e.g. 'gene:gyrA AND organism_id:1423 AND reviewed:true' -> 0 hits vs 1 for taxonomy_id; gene:recA + E. coli 562 -> 9 vs 30). Results therefore include descendant strains of the taxid you supplied. To match the exact organism node only, write 'organism_id:<taxid>' yourself against the UniProt REST API, or use organism_name with the exact strain name."
+    }
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/edge_legacy_efo.json

@@ -0,0 +1,32 @@
+{
+ "_recorded": {
+  "scenario": "edge_legacy_efo",
+  "why": "a legacy EFO id Open Targets dropped",
+  "endpoint": "targets_for_disease",
+  "arguments": [
+   "EFO_0002618",
+   "5"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:43:47Z",
+  "recorded_at_epoch": 1792557827.393,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "refused",
+  "licences": {
+   "opentargets": "CC0 1.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "OpenTargets_get_associated_targets_by_disease_efoId",
+   "args": {
+    "efoId": "EFO_0002618",
+    "size": 5
+   },
+   "response": {
+    "status": "error",
+    "error": "OpenTargets returned no disease for ID 'EFO_0002618'. OpenTargets migrated most disease IDs from EFO to MONDO, so many legacy EFO disease IDs now resolve to null. Pass a current MONDO ID (e.g. MONDO_0005011 for Crohn disease); look up a disease's current ID by name with OpenTargets_multi_entity_search_by_query_string."
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/edge_unknown_symbol.json

@@ -0,0 +1,37 @@
+{
+ "_recorded": {
+  "scenario": "edge_unknown_symbol",
+  "why": "a symbol HGNC does not know",
+  "endpoint": "drugs_for_targets",
+  "arguments": [
+   "NOTAGENE1"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:43:47Z",
+  "recorded_at_epoch": 1792557825.747,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "hgnc": "No restrictions on access or use (HGNC data release policy); citation requested"
+  }
+ },
+ "calls": [
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "NOTAGENE1"
+   },
+   "response": {
+    "status": "success",
+    "data": {},
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "NOTAGENE1",
+     "num_found": 0,
+     "no_results_note": "'NOTAGENE1' is not known to HGNC as a current symbol, a previous symbol, or an alias symbol. Check the spelling, or use HGNC_search_genes (which supports wildcards and free-text search) to find the gene."
+    }
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/q1_q2_drugs_kras.json

@@ -0,0 +1,605 @@
+{
+ "_recorded": {
+  "scenario": "q1_q2_drugs_kras",
+  "why": "Phase 0 Q1 (KRAS G12D) and Q2 (G12C)",
+  "endpoint": "drugs_for_targets",
+  "arguments": [
+   "KRAS"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:42:22Z",
+  "recorded_at_epoch": 1792557740.022,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "chembl": "CC BY-SA 3.0",
+   "hgnc": "No restrictions on access or use (HGNC data release policy); citation requested",
+   "opentargets": "CC0 1.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "KRAS"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "hgnc_id": "HGNC:6407",
+     "gencc": "HGNC:6407",
+     "alias_symbol": [
+      "KRAS1",
+      "K-Ras4B"
+     ],
+     "rgd_id": [
+      "RGD:2981"
+     ],
+     "ucsc_id": "uc001rgp.3",
+     "cosmic": "KRAS",
+     "location": "12p12.1",
+     "uniprot_ids": [
+      "P01116"
+     ],
+     "prev_name": [
+      "KRAS proto-oncogene, GTPase",
+      "v-Ki-ras2 Kirsten rat sarcoma 2 viral oncogene homolog",
+      "v-Ki-ras2 Kirsten rat sarcoma viral oncogene homolog",
+      "Kirsten rat sarcoma viral oncogene homolog"
+     ],
+     "omim_id": [
+      "190070"
+     ],
+     "uuid": "4e5a8988-4945-4b5b-9182-a394193ae050",
+     "lsdb": [
+      "LRG_344|http://ftp.ebi.ac.uk/pub/databases/lrgex/LRG_344.xml"
+     ],
+     "name": "KRas proto-oncogene, GTPase",
+     "status": "Approved",
+     "iuphar": "HGNC:6407",
+     "mane_select": [
+      "ENST00000311936.8",
+      "NM_004985.5"
+     ],
+     "refseq_accession": [
+      "NM_033360"
+     ],
+     "agr": "HGNC:6407",
+     "date_modified": "2026-06-10T00:00:00Z",
+     "locus_type": "gene with protein product",
+     "date_approved_reserved": "1988-06-02T00:00:00Z",
+     "date_name_changed": "2026-06-10T00:00:00Z",
+     "entrez_id": "3845",
+     "prev_symbol": [
+      "KRAS2"
+     ],
+     "gene_group": [
+      "RAS type GTPase family"
+     ],
+     "ena": [
+      "BC010502"
+     ],
+     "mgd_id": [
+      "MGI:96680"
+     ],
+     "ccds_id": [
+      "CCDS8702",
+      "CCDS8703"
+     ],
+     "ensembl_gene_id": "ENSG00000133703",
+     "vega_id": "OTTHUMG00000171193",
+     "locus_group": "protein-coding gene",
+     "orphanet": 122879,
+     "date_symbol_changed": "2005-01-24T00:00:00Z",
+     "gene_group_id": [
+      389
+     ],
+     "symbol": "KRAS"
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "KRAS",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "OpenTargets_get_associated_drugs_by_target_ensemblID",
+   "args": {
+    "ensemblId": "ENSG00000133703"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "target": {
+      "id": "ENSG00000133703",
+      "approvedSymbol": "KRAS",
+      "drugAndClinicalCandidates": {
+       "count": 3,
+       "rows": [
+        {
+         "drug": {
+          "id": "CHEMBL4535757",
+          "name": "SOTORASIB",
+          "maximumClinicalStage": "APPROVAL"
+         },
+         "maxClinicalStage": "APPROVAL",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005070",
+            "name": "neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0008903",
+            "name": "lung cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0056806",
+            "name": "non-small cell squamous lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0007254",
+            "name": "breast cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0021040",
+            "name": "pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0011962",
+            "name": "endometrial cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0009831",
+            "name": "malignant pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0008170",
+            "name": "ovarian cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0003060",
+            "name": "biliary tract cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005008",
+            "name": "colorectal adenocarcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0004992",
+            "name": "cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005070",
+            "name": "neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005192",
+            "name": "exocrine pancreatic carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0021350",
+            "name": "neoplasm of thorax"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0021211",
+            "name": "brain neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0006047",
+            "name": "pancreatic adenocarcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL4594350",
+          "name": "ADAGRASIB",
+          "maximumClinicalStage": "APPROVAL"
+         },
+         "maxClinicalStage": "APPROVAL",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005070",
+            "name": "neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0007254",
+            "name": "breast cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0008903",
+            "name": "lung cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005184",
+            "name": "pancreatic ductal adenocarcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0003060",
+            "name": "biliary tract cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0021040",
+            "name": "pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0009831",
+            "name": "malignant pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005070",
+            "name": "neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0004992",
+            "name": "cancer"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL23293",
+          "name": "SALIRASIB",
+          "maximumClinicalStage": "PHASE_2"
+         },
+         "maxClinicalStage": "PHASE_2",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0008903",
+            "name": "lung cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0021040",
+            "name": "pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0009831",
+            "name": "malignant pancreatic neoplasm"
+           }
+          }
+         ]
+        }
+       ],
+       "returned": 3,
+       "truncated": false
+      }
+     }
+    }
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL4594350"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "INHIBITOR",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 4,
+       "mec_id": 8840,
+       "mechanism_comment": null,
+       "mechanism_of_action": "GTPase KRas inhibitor",
+       "mechanism_refs": [
+        {
+         "ref_id": "31658955",
+         "ref_type": "PubMed",
+         "ref_url": "https://pubmed.ncbi.nlm.nih.gov/31658955/"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL4594350",
+       "parent_molecule_chembl_id": "CHEMBL4594350",
+       "record_id": 3461020,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL2189121",
+       "variant_sequence": {
+        "accession": "P01116",
+        "isoform": 1,
+        "mutation": "G12C",
+        "organism": "Homo sapiens",
+        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQRVEDAFYTLVREIRQYRLKKISKEEKTPGCVKIKKCIIM",
+        "tax_id": 9606,
+        "version": 1
+       }
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL4594350",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL4535757"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "INHIBITOR",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 4,
+       "mec_id": 8492,
+       "mechanism_comment": "Covalent inhibitor",
+       "mechanism_of_action": "GTPase KRas inhibitor",
+       "mechanism_refs": [
+        {
+         "ref_id": "31189530",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/31189530"
+        },
+        {
+         "ref_id": "31666701",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/31666701"
+        },
+        {
+         "ref_id": "31820981",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/31820981"
+        },
+        {
+         "ref_id": "32568546",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/32568546"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL4535757",
+       "parent_molecule_chembl_id": "CHEMBL4535757",
+       "record_id": 3489912,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL2189121",
+       "variant_sequence": {
+        "accession": "P01116",
+        "isoform": 1,
+        "mutation": "G12C",
+        "organism": "Homo sapiens",
+        "sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQEEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHHYREQIKRVKDSEDVPMVLVGNKCDLPSRTVDTKQAQDLARSYGIPFIETSAKTRQRVEDAFYTLVREIRQYRLKKISKEEKTPGCVKIKKCIIM",
+        "tax_id": 9606,
+        "version": 1
+       }
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL4535757",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL23293"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "INHIBITOR",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 8727,
+       "mechanism_comment": null,
+       "mechanism_of_action": "RAS inhibitor",
+       "mechanism_refs": [
+        {
+         "ref_id": "22547163",
+         "ref_type": "PubMed",
+         "ref_url": "https://pubmed.ncbi.nlm.nih.gov/22547163/"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL23293",
+       "parent_molecule_chembl_id": "CHEMBL23293",
+       "record_id": 1705113,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL4524006",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL23293",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/q3_annotate_elavl1.json

@@ -0,0 +1,345 @@
+{
+ "_recorded": {
+  "scenario": "q3_annotate_elavl1",
+  "why": "Phase 0 Q3 (HuR function)",
+  "endpoint": "annotate_genes",
+  "arguments": [
+   "ELAVL1"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:42:24Z",
+  "recorded_at_epoch": 1792557742.938,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "hgnc": "No restrictions on access or use (HGNC data release policy); citation requested",
+   "uniprot": "CC BY 4.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "ELAVL1"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "vega_id": "OTTHUMG00000182470",
+     "symbol": "ELAVL1",
+     "gene_group_id": [
+      725,
+      2291
+     ],
+     "locus_group": "protein-coding gene",
+     "prev_symbol": [
+      "HUR"
+     ],
+     "date_name_changed": "2013-10-03T00:00:00Z",
+     "entrez_id": "1994",
+     "date_approved_reserved": "1996-08-12T00:00:00Z",
+     "ensembl_gene_id": "ENSG00000066044",
+     "ccds_id": [
+      "CCDS12193"
+     ],
+     "mgd_id": [
+      "MGI:1100851"
+     ],
+     "gene_group": [
+      "RNA binding motif containing",
+      "ELAV like RNA binding protein family"
+     ],
+     "ena": [
+      "U38175"
+     ],
+     "refseq_accession": [
+      "NM_001419"
+     ],
+     "mane_select": [
+      "ENST00000407627.7",
+      "NM_001419.3"
+     ],
+     "agr": "HGNC:3312",
+     "pubmed_id": [
+      8626503,
+      9003489,
+      35973378
+     ],
+     "locus_type": "gene with protein product",
+     "date_modified": "2023-11-02T00:00:00Z",
+     "alias_name": [
+      "embryonic lethal, abnormal vision, drosophila, homolog-like 1",
+      "Hu antigen R",
+      "Human antigen R"
+     ],
+     "location": "19p13.2",
+     "uniprot_ids": [
+      "Q15717"
+     ],
+     "prev_name": [
+      "ELAV (embryonic lethal, abnormal vision, Drosophila)-like 1 (Hu antigen R)"
+     ],
+     "rgd_id": [
+      "RGD:1308649"
+     ],
+     "ucsc_id": "uc060ssp.1",
+     "alias_symbol": [
+      "HuR",
+      "Hua",
+      "MelG"
+     ],
+     "hgnc_id": "HGNC:3312",
+     "status": "Approved",
+     "name": "ELAV like RNA binding protein 1",
+     "omim_id": [
+      "603466"
+     ],
+     "uuid": "4139f3ba-b203-4497-b00a-0952766090b5"
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "ELAVL1",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "UniProt_search",
+   "args": {
+    "query": "(accession:Q15717) AND reviewed:true AND organism_id:9606",
+    "limit": 1,
+    "fields": [
+     "accession",
+     "gene_primary",
+     "protein_name",
+     "cc_function",
+     "cc_subcellular_location"
+    ]
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "total_results": 1,
+     "returned": 1,
+     "results": [
+      {
+       "entryType": "UniProtKB reviewed (Swiss-Prot)",
+       "primaryAccession": "Q15717",
+       "proteinDescription": {
+        "recommendedName": {
+         "fullName": {
+          "value": "ELAV-like protein 1"
+         }
+        },
+        "alternativeNames": [
+         {
+          "fullName": {
+           "value": "Hu-antigen R"
+          },
+          "shortNames": [
+           {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000303",
+              "source": "PubMed",
+              "id": "8626503"
+             }
+            ],
+            "value": "HuR"
+           }
+          ]
+         }
+        ]
+       },
+       "genes": [
+        {
+         "geneName": {
+          "value": "ELAVL1"
+         }
+        }
+       ],
+       "comments": [
+        {
+         "texts": [
+          {
+           "evidences": [
+            {
+             "evidenceCode": "ECO:0000250",
+             "source": "UniProtKB",
+             "id": "P70372"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "14517288"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "14731398"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "17632515"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "18285462"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "19029303"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "23519412"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "29180010"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "31358969"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "32245947"
+            },
+            {
+             "evidenceCode": "ECO:0000269",
+             "source": "PubMed",
+             "id": "8626503"
+            }
+           ],
+           "value": "RNA-binding protein that binds to the 3'-UTR region of mRNAs and increases their stability (PubMed:14517288, PubMed:18285462, PubMed:31358969). Involved in embryonic stem cell (ESC) differentiation: preferentially binds mRNAs that are not methylated by N6-methyladenosine (m6A), stabilizing them, promoting ESC differentiation (By similarity). Has also been shown to be capable of binding to m6A-containing mRNAs and contributes to MYC stability by binding to m6A-containing MYC mRNAs (PubMed:32245947). Binds to poly-U elements and AU-rich elements (AREs) in the 3'-UTR of target mRNAs (PubMed:14731398, PubMed:17632515, PubMed:18285462, PubMed:23519412, PubMed:8626503). Binds avidly to the AU-rich element in FOS and IL3/interleukin-3 mRNAs. In the case of the FOS AU-rich element, binds to a core element of 27 nucleotides that contain AUUUA, AUUUUA, and AUUUUUA motifs. Binds preferentially to the 5'-UUUU[AG]UUU-3' motif in vitro (PubMed:8626503). With ZNF385A, binds the 3'-UTR of p53/TP53 mRNA to control their nuclear export induced by CDKN2A. Hence, may regulate p53/TP53 expression and mediate in part the CDKN2A anti-proliferative activity. May also bind with ZNF385A the CCNB1 mRNA (By similarity). Increases the stability of the leptin mRNA harboring an AU-rich element (ARE) in its 3' UTR (PubMed:29180010)"
+          }
+         ],
+         "commentType": "FUNCTION"
+        },
+        {
+         "commentType": "SUBCELLULAR LOCATION",
+         "note": {
+          "texts": [
+           {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000250",
+              "source": "UniProtKB",
+              "id": "P70372"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "14517288"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "18285462"
+             }
+            ],
+            "value": "Translocates into the cytoplasm following phosphorylation by MAPKAPK2 (PubMed:14517288). Likewise, phosphorylation by PRKCD promotes translocation from the nucleus into the cytoplasm, where it is associated with free and cytoskeleton-bound polysomes (PubMed:18285462). Localizes to the stress granules in the presence of PLEKHN1 (By similarity)"
+           }
+          ]
+         },
+         "subcellularLocations": [
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "14517288"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "17632515"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "18285462"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "19029303"
+             }
+            ],
+            "value": "Cytoplasm",
+            "id": "SL-0086"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "14517288"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "17632515"
+             },
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "18285462"
+             }
+            ],
+            "value": "Nucleus",
+            "id": "SL-0191"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000250",
+              "source": "UniProtKB",
+              "id": "P70372"
+             }
+            ],
+            "value": "Cytoplasm, Stress granule",
+            "id": "SL-0496"
+           }
+          },
+          {
+           "location": {
+            "evidences": [
+             {
+              "evidenceCode": "ECO:0000269",
+              "source": "PubMed",
+              "id": "29476152"
+             }
+            ],
+            "value": "Cytoplasm, P-body",
+            "id": "SL-0230"
+           }
+          }
+         ]
+        }
+       ],
+       "extraAttributes": {
+        "uniParcId": "UPI0000129E74"
+       }
+      }
+     ],
+     "normalization_note": "Query scope widened: 'organism_id:<taxid>' was rewritten to 'taxonomy_id:<taxid>'. UniProt's organism_id field (labelled 'Organism [OS]') matches only an entry's own organism node, while taxonomy_id ('Taxonomy [OC]') matches anywhere in the entry's lineage. Most bacterial entries are annotated at strain level, so a species-level organism_id silently returns 0 or an undercount (e.g. 'gene:gyrA AND organism_id:1423 AND reviewed:true' -> 0 hits vs 1 for taxonomy_id; gene:recA + E. coli 562 -> 9 vs 30). Results therefore include descendant strains of the taxid you supplied. To match the exact organism node only, write 'organism_id:<taxid>' yourself against the UniProt REST API, or use organism_name with the exact strain name."
+    }
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/q5_trials_cd40.json

@@ -0,0 +1,90 @@
+{
+ "_recorded": {
+  "scenario": "q5_trials_cd40",
+  "why": "Phase 0 Q5 (recruiting CD40 trials)",
+  "endpoint": "trials_for_genes",
+  "arguments": [
+   "CD40",
+   "",
+   ""
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:42:55Z",
+  "recorded_at_epoch": 1792557775.678,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "clinicaltrials": "Public (U.S. National Library of Medicine); NLM terms and conditions apply"
+  }
+ },
+ "calls": [
+  {
+   "tool": "ClinicalTrials_search_studies",
+   "args": {
+    "query_cond": "pancreatic cancer",
+    "query_intr": "CD40",
+    "page_size": 100,
+    "filter_status": "RECRUITING"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "studies": [
+      {
+       "nct_id": "NCT06205849",
+       "brief_title": "Intra-tumoral Mitazalimab (CD40 Antibody) With Irreversible Electroporation (IRE) in Locally Advanced Pancreas Cancer",
+       "status": "RECRUITING",
+       "study_type": "INTERVENTIONAL",
+       "phases": [
+        "PHASE1"
+       ],
+       "enrollment": 18,
+       "conditions": [
+        "Pancreatic Cancer"
+       ],
+       "interventions": [
+        "IRE + intratumoral mitazalimab (CD40 antibody) injection",
+        "NanoKnife"
+       ],
+       "intervention_count": 2,
+       "interventions_truncated": false,
+       "sponsor": "University of California, San Diego",
+       "start_date": "2024-07-17",
+       "completion_date": "2030-08"
+      }
+     ],
+     "total_count": 1,
+     "next_page_token": null,
+     "executed_query": {
+      "query.cond": "\"pancreatic cancer\"",
+      "query.intr": "(AREA[InterventionName]CD40 OR AREA[InterventionOtherName]CD40)",
+      "filter.overallStatus": "RECRUITING"
+     },
+     "query_rewrites": [
+      {
+       "parameter": "query_cond",
+       "api_field": "query.cond",
+       "submitted": "pancreatic cancer",
+       "executed": "\"pancreatic cancer\"",
+       "restricted_to_fields": []
+      },
+      {
+       "parameter": "query_intr",
+       "api_field": "query.intr",
+       "submitted": "CD40",
+       "executed": "(AREA[InterventionName]CD40 OR AREA[InterventionOtherName]CD40)",
+       "restricted_to_fields": [
+        "InterventionName",
+        "InterventionOtherName"
+       ]
+      }
+     ]
+    },
+    "metadata": {
+     "source": "ClinicalTrials.gov API v2",
+     "operation": "search"
+    }
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/q7_drugs_tnfrsf10b.json

@@ -0,0 +1,865 @@
+{
+ "_recorded": {
+  "scenario": "q7_drugs_tnfrsf10b",
+  "why": "Phase 0 Q7 (DR5)",
+  "endpoint": "drugs_for_targets",
+  "arguments": [
+   "TNFRSF10B"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:43:37Z",
+  "recorded_at_epoch": 1792557814.828,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "chembl": "CC BY-SA 3.0",
+   "hgnc": "No restrictions on access or use (HGNC data release policy); citation requested",
+   "opentargets": "CC0 1.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "TNFRSF10B"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "entrez_id": "8795",
+     "date_name_changed": "2016-06-28T00:00:00Z",
+     "date_approved_reserved": "1998-12-04T00:00:00Z",
+     "ensembl_gene_id": "ENSG00000120889",
+     "ccds_id": [
+      "CCDS6035",
+      "CCDS6036"
+     ],
+     "mgd_id": [
+      "MGI:1341090"
+     ],
+     "cd": "CD262",
+     "ena": [
+      "AF012628"
+     ],
+     "gene_group": [
+      "CD molecules",
+      "Tumor necrosis factor receptor superfamily"
+     ],
+     "vega_id": "OTTHUMG00000097826",
+     "symbol": "TNFRSF10B",
+     "gene_group_id": [
+      471,
+      782
+     ],
+     "locus_group": "protein-coding gene",
+     "prev_name": [
+      "tumor necrosis factor receptor superfamily, member 10b"
+     ],
+     "uniprot_ids": [
+      "O14763"
+     ],
+     "location": "8p21.3",
+     "ucsc_id": "uc003xcu.4",
+     "alias_symbol": [
+      "DR5",
+      "KILLER",
+      "TRICK2A",
+      "TRAIL-R2",
+      "TRICKB",
+      "CD262",
+      "TRAILR2"
+     ],
+     "gencc": "HGNC:11905",
+     "hgnc_id": "HGNC:11905",
+     "iuphar": "HGNC:11905",
+     "status": "Approved",
+     "name": "TNF receptor superfamily member 10b",
+     "uuid": "4b2390b4-2ff2-4ba8-9fcf-b6e65ad656f9",
+     "omim_id": [
+      "603612"
+     ],
+     "agr": "HGNC:11905",
+     "refseq_accession": [
+      "NM_147187"
+     ],
+     "mane_select": [
+      "ENST00000276431.9",
+      "NM_003842.5"
+     ],
+     "pubmed_id": [
+      9285725,
+      9311998
+     ],
+     "locus_type": "gene with protein product",
+     "date_modified": "2023-01-20T00:00:00Z"
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "TNFRSF10B",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "OpenTargets_get_associated_drugs_by_target_ensemblID",
+   "args": {
+    "ensemblId": "ENSG00000120889"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "target": {
+      "id": "ENSG00000120889",
+      "approvedSymbol": "TNFRSF10B",
+      "drugAndClinicalCandidates": {
+       "count": 7,
+       "rows": [
+        {
+         "drug": {
+          "id": "CHEMBL2109247",
+          "name": "LBY-135",
+          "maximumClinicalStage": "PHASE_1"
+         },
+         "maxClinicalStage": "PHASE_1",
+         "diseases": []
+        },
+        {
+         "drug": {
+          "id": "CHEMBL2107846",
+          "name": "DULANERMIN",
+          "maximumClinicalStage": "PHASE_2"
+         },
+         "maxClinicalStage": "PHASE_2",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0056806",
+            "name": "non-small cell squamous lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0018908",
+            "name": "non-Hodgkin lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0018906",
+            "name": "follicular lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "EFO_1001480",
+            "name": "metastatic colorectal cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL1743008",
+          "name": "DROZITUMAB",
+          "maximumClinicalStage": "PHASE_2"
+         },
+         "maxClinicalStage": "PHASE_2",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0018906",
+            "name": "follicular lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0008977",
+            "name": "chondrosarcoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL1743080",
+          "name": "TIGATUZUMAB",
+          "maximumClinicalStage": "PHASE_2"
+         },
+         "maxClinicalStage": "PHASE_2",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0007254",
+            "name": "breast cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0002691",
+            "name": "liver cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0008170",
+            "name": "ovarian cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0021040",
+            "name": "pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0009831",
+            "name": "malignant pancreatic neoplasm"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005192",
+            "name": "exocrine pancreatic carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0007256",
+            "name": "hepatocellular carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0007254",
+            "name": "breast cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005062",
+            "name": "lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0024331",
+            "name": "colorectal carcinoma"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL2109248",
+          "name": "APOMAB",
+          "maximumClinicalStage": "PHASE_1"
+         },
+         "maxClinicalStage": "PHASE_1",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL1743036",
+          "name": "LEXATUMUMAB",
+          "maximumClinicalStage": "PHASE_2"
+         },
+         "maxClinicalStage": "PHASE_2",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0005072",
+            "name": "neuroblastoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0012817",
+            "name": "Ewing sarcoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0009807",
+            "name": "osteosarcoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005212",
+            "name": "rhabdomyosarcoma"
+           }
+          }
+         ]
+        },
+        {
+         "drug": {
+          "id": "CHEMBL1743003",
+          "name": "CONATUMUMAB",
+          "maximumClinicalStage": "PHASE_2"
+         },
+         "maxClinicalStage": "PHASE_2",
+         "diseases": [
+          {
+           "disease": {
+            "id": "MONDO_0005575",
+            "name": "colorectal cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "HP_0012531",
+            "name": "Pain"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0024331",
+            "name": "colorectal carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005233",
+            "name": "non-small cell lung carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0018078",
+            "name": "soft tissue sarcoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005192",
+            "name": "exocrine pancreatic carcinoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0008170",
+            "name": "ovarian cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005089",
+            "name": "sarcoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0004952",
+            "name": "Hodgkins lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0018876",
+            "name": "mantle cell lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0005062",
+            "name": "lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0018905",
+            "name": "diffuse large B-cell lymphoma"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0002158",
+            "name": "fallopian tube cancer"
+           }
+          },
+          {
+           "disease": {
+            "id": "MONDO_0015686",
+            "name": "primary peritoneal carcinoma"
+           }
+          }
+         ]
+        }
+       ],
+       "returned": 7,
+       "truncated": false
+      }
+     }
+    }
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL1743003"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 5991,
+       "mechanism_comment": "It binds to TNFRSF10B, activating intracellular caspases in vitro in the presence of a cross-linker.",
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "20150762",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/20150762"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL1743003",
+       "parent_molecule_chembl_id": "CHEMBL1743003",
+       "record_id": 1392887,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL1743003",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL1743008"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": "Binds at the junction between CRD2 and CRD3, interacting with residues in both CRD2 and CRD3.",
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 5995,
+       "mechanism_comment": "Induces TNFRSF10B clustering at the cell surface and stimulates a death-inducing signaling complex containing the adaptor molecule Fas-associated death domain and the apoptosis-initiating protease caspase-8. Fc crosslinking further augmented Drozitumab's proapoptotic activity.",
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "18219321",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/18219321"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL1743008",
+       "parent_molecule_chembl_id": "CHEMBL1743008",
+       "record_id": 1392892,
+       "selectivity_comment": "Binds to TNFRSF10B, but shows no detectable binding to any of the other Apo2L/TRAIL receptors.",
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL1743008",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL2107846"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 5540,
+       "mechanism_comment": "Binds to and activates TRAIL receptors 1 and 2 (TRAIL-R1/R2), which may activate caspases and induce p53-independent apoptosis.",
+       "mechanism_of_action": "TRAIL receptor-1 agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "10411544",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/10411544"
+        },
+        {
+         "ref_id": "22914439",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/22914439"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL2107846",
+       "parent_molecule_chembl_id": "CHEMBL2107846",
+       "record_id": 1695906,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL3551",
+       "variant_sequence": null
+      },
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 5868,
+       "mechanism_comment": "Binds to and activates TRAIL receptors 1 and 2 (TRAIL-R1/R2), which may activate caspases and induce p53-independent apoptosis.",
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "10411544",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/10411544"
+        },
+        {
+         "ref_id": "22914439",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/22914439"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL2107846",
+       "parent_molecule_chembl_id": "CHEMBL2107846",
+       "record_id": 1695906,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 2
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL2107846",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 2
+    },
+    "count": 2
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL1743036"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 7082,
+       "mechanism_comment": null,
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "https://www.cancer.gov/publications/dictionaries/cancer-drug?cdrid=528015",
+         "ref_type": "Other",
+         "ref_url": "https://www.cancer.gov/publications/dictionaries/cancer-drug?cdrid=528015"
+        },
+        {
+         "ref_id": "PMC3494837",
+         "ref_type": "PMC",
+         "ref_url": "http://europepmc.org/articles/PMC3494837"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL1743036",
+       "parent_molecule_chembl_id": "CHEMBL1743036",
+       "record_id": 1392920,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL1743036",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL1743080"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 3,
+       "mec_id": 5468,
+       "mechanism_comment": "Mimics the natural receptor ligand TRAIL and binds to TRAIL-R2 (without crosslinking), activating signal transduction pathways that may result in tumor cell apoptosis and a reduction in tumor growth.",
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "18304965",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/18304965"
+        },
+        {
+         "ref_id": "20187792",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/20187792"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL1743080",
+       "parent_molecule_chembl_id": "CHEMBL1743080",
+       "record_id": 1392964,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL1743080",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL2109248"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 2,
+       "mec_id": 6327,
+       "mechanism_comment": null,
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "18219321",
+         "ref_type": "PubMed",
+         "ref_url": "http://europepmc.org/abstract/MED/18219321"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL2109248",
+       "parent_molecule_chembl_id": "CHEMBL2109248",
+       "record_id": 1706662,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL2109248",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  },
+  {
+   "tool": "ChEMBL_get_drug_mechanisms",
+   "args": {
+    "drug_chembl_id": "CHEMBL2109247"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "mechanisms": [
+      {
+       "action_type": "AGONIST",
+       "binding_site_comment": null,
+       "direct_interaction": 1,
+       "disease_efficacy": 1,
+       "max_phase": 1,
+       "mec_id": 7083,
+       "mechanism_comment": null,
+       "mechanism_of_action": "Tumor necrosis factor receptor superfamily member 10B agonist",
+       "mechanism_refs": [
+        {
+         "ref_id": "10.1002/ddr.20229/abstract",
+         "ref_type": "DOI",
+         "ref_url": "http://onlinelibrary.wiley.com/doi/10.1002/ddr.20229/abstract"
+        }
+       ],
+       "molecular_mechanism": 1,
+       "molecule_chembl_id": "CHEMBL2109247",
+       "parent_molecule_chembl_id": "CHEMBL2109247",
+       "record_id": 1706661,
+       "selectivity_comment": null,
+       "site_id": null,
+       "target_chembl_id": "CHEMBL1075153",
+       "variant_sequence": null
+      }
+     ],
+     "page_meta": {
+      "limit": 20,
+      "next": null,
+      "offset": 0,
+      "previous": null,
+      "total_count": 1
+     }
+    },
+    "url": "https://www.ebi.ac.uk/chembl/api/data/mechanism.json?format=json&parent_molecule_chembl_id=CHEMBL2109247",
+    "page_meta": {
+     "limit": 20,
+     "next": null,
+     "offset": 0,
+     "previous": null,
+     "total_count": 1
+    },
+    "count": 1
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/q8_targets_pdac.json

@@ -0,0 +1,262 @@
+{
+ "_recorded": {
+  "scenario": "q8_targets_pdac",
+  "why": "Phase 0 Q8 (top PDAC targets)",
+  "endpoint": "targets_for_disease",
+  "arguments": [
+   "pancreatic ductal adenocarcinoma",
+   ""
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:43:38Z",
+  "recorded_at_epoch": 1792557817.888,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "opentargets": "CC0 1.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "OpenTargets_get_disease_id_description_by_name",
+   "args": {
+    "diseaseName": "pancreatic ductal adenocarcinoma"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "search": {
+      "hits": [
+       {
+        "id": "MONDO_0005184",
+        "name": "pancreatic ductal adenocarcinoma",
+        "description": "An infiltrating adenocarcinoma that arises from the epithelial cells of the pancreas. It affects males more often than females and the patients are usually over 50 years of age. Microscopically it is characterized by the presence of glandular (ductal) differentiation and desmoplastic stroma formation. Signs and symptoms include pain, loss of weight, and jaundice. It grows rapidly and is usually detected after it has metastasized to other anatomic sites. The prognosis is usually poor."
+       },
+       {
+        "id": "MONDO_0002666",
+        "name": "pancreatic signet ring cell adenocarcinoma",
+        "description": "A rare pancreatic ductal adenocarcinoma with poor prognosis. It is characterized by the presence of malignant signet ring cells infiltrating the pancreatic parenchyma in an individual cell pattern."
+       },
+       {
+        "id": "MONDO_0005614",
+        "name": "pancreatic adenosquamous carcinoma",
+        "description": "A carcinoma that arises from the pancreas showing both ductal and squamous differentiation. The squamous component should represent at least 30% of the malignant cellular infiltrate. The prognosis is usually worse than that of ductal adenocarcinoma."
+       },
+       {
+        "id": "MONDO_0006270",
+        "name": "lobular breast carcinoma in situ",
+        "description": "A non-invasive adenocarcinoma of the breast characterized by a proliferation of monomorphic cells completely filling the lumina. The overall lobular architecture is preserved. It is frequently multifocal (90% in some series) and bilateral. It seldom becomes invasive; however there is an increased risk of infiltrating ductal adenocarcinoma."
+       },
+       {
+        "id": "OBA_2050353",
+        "name": "age of onset of pancreatic ductal adenocarcinoma",
+        "description": "The age at which pancreatic ductal adenocarcinoma manifestations first appear."
+       }
+      ]
+     }
+    }
+   }
+  },
+  {
+   "tool": "OpenTargets_get_associated_targets_by_disease_efoId",
+   "args": {
+    "efoId": "MONDO_0005184",
+    "size": 25
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "disease": {
+      "id": "MONDO_0005184",
+      "name": "pancreatic ductal adenocarcinoma",
+      "associatedTargets": {
+       "count": 7656,
+       "rows": [
+        {
+         "target": {
+          "id": "ENSG00000133703",
+          "approvedSymbol": "KRAS"
+         },
+         "score": 0.5291977040592586
+        },
+        {
+         "target": {
+          "id": "ENSG00000141510",
+          "approvedSymbol": "TP53"
+         },
+         "score": 0.49944194194971064
+        },
+        {
+         "target": {
+          "id": "ENSG00000147889",
+          "approvedSymbol": "CDKN2A"
+         },
+         "score": 0.49599448524186573
+        },
+        {
+         "target": {
+          "id": "ENSG00000177084",
+          "approvedSymbol": "POLE"
+         },
+         "score": 0.4868680592918723
+        },
+        {
+         "target": {
+          "id": "ENSG00000062822",
+          "approvedSymbol": "POLD1"
+         },
+         "score": 0.48593032024807303
+        },
+        {
+         "target": {
+          "id": "ENSG00000198900",
+          "approvedSymbol": "TOP1"
+         },
+         "score": 0.4618463053159949
+        },
+        {
+         "target": {
+          "id": "ENSG00000141646",
+          "approvedSymbol": "SMAD4"
+         },
+         "score": 0.44565744688506587
+        },
+        {
+         "target": {
+          "id": "ENSG00000115170",
+          "approvedSymbol": "ACVR1"
+         },
+         "score": 0.44390531781927567
+        },
+        {
+         "target": {
+          "id": "ENSG00000140937",
+          "approvedSymbol": "CDH11"
+         },
+         "score": 0.43912921188656784
+        },
+        {
+         "target": {
+          "id": "ENSG00000167553",
+          "approvedSymbol": "TUBA1C"
+         },
+         "score": 0.4335269722906423
+        },
+        {
+         "target": {
+          "id": "ENSG00000178568",
+          "approvedSymbol": "ERBB4"
+         },
+         "score": 0.43245181660076104
+        },
+        {
+         "target": {
+          "id": "ENSG00000120217",
+          "approvedSymbol": "CD274"
+         },
+         "score": 0.4311901321308853
+        },
+        {
+         "target": {
+          "id": "ENSG00000167325",
+          "approvedSymbol": "RRM1"
+         },
+         "score": 0.4269595666656111
+        },
+        {
+         "target": {
+          "id": "ENSG00000171848",
+          "approvedSymbol": "RRM2"
+         },
+         "score": 0.4254344546577324
+        },
+        {
+         "target": {
+          "id": "ENSG00000146143",
+          "approvedSymbol": "PRIM2"
+         },
+         "score": 0.42386371823232
+        },
+        {
+         "target": {
+          "id": "ENSG00000101162",
+          "approvedSymbol": "TUBB1"
+         },
+         "score": 0.422448089960708
+        },
+        {
+         "target": {
+          "id": "ENSG00000176890",
+          "approvedSymbol": "TYMS"
+         },
+         "score": 0.4197400685336987
+        },
+        {
+         "target": {
+          "id": "ENSG00000100479",
+          "approvedSymbol": "POLE2"
+         },
+         "score": 0.41912077676386633
+        },
+        {
+         "target": {
+          "id": "ENSG00000101868",
+          "approvedSymbol": "POLA1"
+         },
+         "score": 0.4183816170544969
+        },
+        {
+         "target": {
+          "id": "ENSG00000258947",
+          "approvedSymbol": "TUBB3"
+         },
+         "score": 0.41803837591047344
+        },
+        {
+         "target": {
+          "id": "ENSG00000014138",
+          "approvedSymbol": "POLA2"
+         },
+         "score": 0.41801203719981217
+        },
+        {
+         "target": {
+          "id": "ENSG00000175482",
+          "approvedSymbol": "POLD4"
+         },
+         "score": 0.41708808756310045
+        },
+        {
+         "target": {
+          "id": "ENSG00000048392",
+          "approvedSymbol": "RRM2B"
+         },
+         "score": 0.41708808756310045
+        },
+        {
+         "target": {
+          "id": "ENSG00000106628",
+          "approvedSymbol": "POLD2"
+         },
+         "score": 0.4161641379263887
+        },
+        {
+         "target": {
+          "id": "ENSG00000198056",
+          "approvedSymbol": "PRIM1"
+         },
+         "score": 0.4161641379263887
+        }
+       ],
+       "returned": 25,
+       "truncated": true
+      }
+     }
+    },
+    "metadata": {
+     "truncation_note": "PARTIAL RESULT: 'associatedTargets' returned 25 of 7656 rows -- 'rows' is one page of the collection, not all of it. Open Targets defaults to a page size of 25 when no page size is given. The 7631 rows not shown are missing from this response only; their absence here is NOT evidence they are absent from Open Targets. Re-query with size: 3000 and index: 0 to get the first 3000 rows (Open Targets rejects a page size above 3000), then step the page index to reach the rest."
+    }
+   }
+  }
+ ]
+}

tests/fixtures/cassettes/q9_pathways_isg15_rsad2_oas1.json

@@ -0,0 +1,578 @@
+{
+ "_recorded": {
+  "scenario": "q9_pathways_isg15_rsad2_oas1",
+  "why": "Phase 0 Q9 (Interferon alpha/beta signaling)",
+  "endpoint": "pathways_for_genes",
+  "arguments": [
+   "ISG15,RSAD2,OAS1"
+  ],
+  "tooluniverse_version": "1.5.6",
+  "recorded_on": "2026-10-21T04:43:43Z",
+  "recorded_at_epoch": 1792557818.642,
+  "recorded_with": "scripts/record_fixtures.py",
+  "payload_status_when_recorded": "ok",
+  "licences": {
+   "hgnc": "No restrictions on access or use (HGNC data release policy); citation requested",
+   "reactome": "CC0 1.0"
+  }
+ },
+ "calls": [
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "ISG15"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "vega_id": "OTTHUMG00000040777",
+     "symbol": "ISG15",
+     "orphanet": 315470,
+     "date_symbol_changed": "2006-04-28T00:00:00Z",
+     "locus_group": "protein-coding gene",
+     "prev_symbol": [
+      "G1P2"
+     ],
+     "date_name_changed": "2019-02-18T00:00:00Z",
+     "entrez_id": "9636",
+     "date_approved_reserved": "1990-10-16T00:00:00Z",
+     "ccds_id": [
+      "CCDS6"
+     ],
+     "ensembl_gene_id": "ENSG00000187608",
+     "mgd_id": [
+      "MGI:1855694"
+     ],
+     "ena": [
+      "BC009507"
+     ],
+     "refseq_accession": [
+      "NM_005101"
+     ],
+     "mane_select": [
+      "ENST00000649529.1",
+      "NM_005101.4"
+     ],
+     "agr": "HGNC:4053",
+     "pubmed_id": [
+      3087979
+     ],
+     "locus_type": "gene with protein product",
+     "date_modified": "2023-01-20T00:00:00Z",
+     "location": "1p36.33",
+     "prev_name": [
+      "interferon, alpha-inducible protein (clone IFI-15K)"
+     ],
+     "uniprot_ids": [
+      "P05161"
+     ],
+     "ucsc_id": "uc001acj.5",
+     "rgd_id": [
+      "RGD:1310312"
+     ],
+     "alias_symbol": [
+      "IFI15",
+      "UCRP"
+     ],
+     "hgnc_id": "HGNC:4053",
+     "gencc": "HGNC:4053",
+     "status": "Approved",
+     "name": "ISG15 ubiquitin like modifier",
+     "omim_id": [
+      "147571"
+     ],
+     "uuid": "3cc085a6-ff20-4251-a3c2-68a68d18210f",
+     "lsdb": [
+      "LRG_1231|http://ftp.ebi.ac.uk/pub/databases/lrgex/LRG_1231.xml"
+     ]
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "ISG15",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "RSAD2"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "symbol": "RSAD2",
+     "gene_group_id": [
+      2036,
+      3925
+     ],
+     "locus_group": "protein-coding gene",
+     "vega_id": "OTTHUMG00000090352",
+     "ensembl_gene_id": "ENSG00000134321",
+     "ccds_id": [
+      "CCDS1656",
+      "CCDS92710"
+     ],
+     "mgd_id": [
+      "MGI:1929628"
+     ],
+     "gene_group": [
+      "Radical S-adenosylmethionine domain containing",
+      "Carbon-oxygen lyases"
+     ],
+     "ena": [
+      "AF442151"
+     ],
+     "entrez_id": "91543",
+     "date_approved_reserved": "2004-11-08T00:00:00Z",
+     "locus_type": "gene with protein product",
+     "date_modified": "2023-01-20T00:00:00Z",
+     "alias_name": [
+      "virus-inhibitory protein, endoplasmic reticulum–associated, interferon-inducible"
+     ],
+     "refseq_accession": [
+      "NM_080657"
+     ],
+     "mane_select": [
+      "ENST00000382040.4",
+      "NM_080657.5"
+     ],
+     "agr": "HGNC:30908",
+     "pubmed_id": [
+      11752458
+     ],
+     "status": "Approved",
+     "name": "radical S-adenosyl methionine domain containing 2",
+     "omim_id": [
+      "607810"
+     ],
+     "uuid": "d9641307-6faf-41ec-a6de-7f4bc9f68905",
+     "location": "2p25.2",
+     "uniprot_ids": [
+      "Q8WXG1"
+     ],
+     "rgd_id": [
+      "RGD:620495"
+     ],
+     "ucsc_id": "uc002qyp.2",
+     "alias_symbol": [
+      "cig5",
+      "vig1",
+      "Viperin"
+     ],
+     "hgnc_id": "HGNC:30908"
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "RSAD2",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "HGNC_fetch_gene_by_symbol",
+   "args": {
+    "symbol": "OAS1"
+   },
+   "response": {
+    "status": "success",
+    "data": {
+     "symbol": "OAS1",
+     "locus_group": "protein-coding gene",
+     "gene_group_id": [
+      2093
+     ],
+     "vega_id": "OTTHUMG00000169792",
+     "enzyme_id": [
+      "2.7.7.-"
+     ],
+     "ensembl_gene_id": "ENSG00000089127",
+     "ccds_id": [
+      "CCDS31905",
+      "CCDS41838",
+      "CCDS44980",
+      "CCDS81742",
+      "CCDS91752",
+      "CCDS91755"
+     ],
+     "ena": [
+      "X04371"
+     ],
+     "gene_group": [
+      "2'-5'-oligoadenylate synthetase family"
+     ],
+     "mgd_id": [
+      "MGI:2180860",
+      "MGI:97430",
+      "MGI:2149633",
+      "MGI:2140770",
+      "MGI:2180856",
+      "MGI:2180855",
+      "MGI:97429",
+      "MGI:2180853"
+     ],
+     "prev_symbol": [
+      "OIAS"
+     ],
+     "date_approved_reserved": "2001-06-22T00:00:00Z",
+     "entrez_id": "4938",
+     "date_name_changed": "2025-10-10T00:00:00Z",
+     "alias_name": [
+      "2'-5' oligoadenylate synthase 1"
+     ],
+     "date_modified": "2025-10-10T00:00:00Z",
+     "locus_type": "gene with protein product",
+     "pubmed_id": [
+      9344649,
+      9325053
+     ],
+     "agr": "HGNC:8086",
+     "refseq_accession": [
+      "NM_001032409"
+     ],
+     "mane_select": [
+      "ENST00000202917.10",
+      "NM_016816.4"
+     ],
+     "status": "Approved",
+     "uuid": "99e53375-4117-4b2d-bc59-4996fc779ad6",
+     "omim_id": [
+      "164350"
+     ],
+     "name": "2'-5'-oligoadenylate synthetase 1",
+     "rgd_id": [
+      "RGD:621760"
+     ],
+     "ucsc_id": "uc001tuc.4",
+     "uniprot_ids": [
+      "P00973"
+     ],
+     "prev_name": [
+      "2',5'-oligoadenylate synthetase 1 (40-46 kD)",
+      "2'-5'-oligoadenylate synthetase 1, 40/46kDa"
+     ],
+     "location": "12q24.13",
+     "gencc": "HGNC:8086",
+     "hgnc_id": "HGNC:8086",
+     "alias_symbol": [
+      "OIASI",
+      "IFI-4"
+     ]
+    },
+    "metadata": {
+     "source": "HGNC",
+     "query_field": "symbol",
+     "query_value": "OAS1",
+     "num_found": 1
+    }
+   }
+  },
+  {
+   "tool": "Reactome_map_uniprot_to_pathways",
+   "args": {
+    "uniprot_id": "P05161"
+   },
+   "response": {
+    "status": "success",
+    "data": [
+     {
+      "dbId": 1169408,
+      "displayName": "ISG15 antiviral mechanism",
+      "stId": "R-HSA-1169408",
+      "stIdVersion": "R-HSA-1169408.4",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "ISG15 antiviral mechanism"
+      ],
+      "releaseDate": "2011-12-06",
+      "speciesName": "Homo sapiens",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2021-09-15",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 168276,
+      "displayName": "NS1 Mediated Effects on Host Pathways",
+      "stId": "R-HSA-168276",
+      "stIdVersion": "R-HSA-168276.11",
+      "isInDisease": true,
+      "isInferred": false,
+      "maxDepth": 4,
+      "name": [
+       "NS1 Mediated Effects on Host Pathways"
+      ],
+      "releaseDate": "2005-06-13",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-168276.9",
+      "hasDiagram": false,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-09-13",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 168928,
+      "displayName": "DDX58/IFIH1-mediated induction of interferon-alpha/beta",
+      "stId": "R-HSA-168928",
+      "stIdVersion": "R-HSA-168928.12",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 3,
+      "name": [
+       "DDX58/IFIH1-mediated induction of interferon-alpha/beta",
+       "RIG-I/MDA5 mediated induction of IFN-alpha/beta pathways"
+      ],
+      "releaseDate": "2010-12-14",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-168928.9",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-09-13",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 5656169,
+      "displayName": "Termination of translesion DNA synthesis",
+      "stId": "R-HSA-5656169",
+      "stIdVersion": "R-HSA-5656169.2",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "Termination of translesion DNA synthesis"
+      ],
+      "releaseDate": "2015-03-19",
+      "speciesName": "Homo sapiens",
+      "hasDiagram": false,
+      "hasEHLD": false,
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 909733,
+      "displayName": "Interferon alpha/beta signaling",
+      "stId": "R-HSA-909733",
+      "stIdVersion": "R-HSA-909733.9",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 3,
+      "name": [
+       "Interferon alpha/beta signaling"
+      ],
+      "releaseDate": "2010-12-14",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-909733.6",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-06-07",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 936440,
+      "displayName": "Negative regulators of DDX58/IFIH1 signaling",
+      "stId": "R-HSA-936440",
+      "stIdVersion": "R-HSA-936440.6",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "Negative regulators of DDX58/IFIH1 signaling",
+       "Negative regulators of RIG-I/MDA5 signaling"
+      ],
+      "releaseDate": "2010-12-14",
+      "speciesName": "Homo sapiens",
+      "hasDiagram": false,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2022-04-07",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 9705671,
+      "displayName": "SARS-CoV-2 activates/modulates innate and adaptive immune responses",
+      "stId": "R-HSA-9705671",
+      "stIdVersion": "R-HSA-9705671.5",
+      "isInDisease": true,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "SARS-CoV-2 activates/modulates innate and adaptive immune responses"
+      ],
+      "releaseDate": "2022-03-23",
+      "speciesName": "Homo sapiens",
+      "hasDiagram": false,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-03-29",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 9833110,
+      "displayName": "RSV-host interactions",
+      "stId": "R-HSA-9833110",
+      "stIdVersion": "R-HSA-9833110.2",
+      "isInDisease": true,
+      "isInferred": false,
+      "maxDepth": 3,
+      "name": [
+       "RSV-host interactions"
+      ],
+      "releaseDate": "2023-12-06",
+      "speciesName": "Homo sapiens",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 9833482,
+      "displayName": "PKR-mediated signaling",
+      "stId": "R-HSA-9833482",
+      "stIdVersion": "R-HSA-9833482.3",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "PKR-mediated signaling"
+      ],
+      "releaseDate": "2023-09-13",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-9833482.1",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 9909505,
+      "displayName": "Modulation of host responses by IFN-stimulated genes",
+      "stId": "R-HSA-9909505",
+      "stIdVersion": "R-HSA-9909505.2",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "Modulation of host responses by IFN-stimulated genes"
+      ],
+      "releaseDate": "2024-12-04",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-9909505.1",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     }
+    ]
+   }
+  },
+  {
+   "tool": "Reactome_map_uniprot_to_pathways",
+   "args": {
+    "uniprot_id": "Q8WXG1"
+   },
+   "response": {
+    "status": "success",
+    "data": [
+     {
+      "dbId": 909733,
+      "displayName": "Interferon alpha/beta signaling",
+      "stId": "R-HSA-909733",
+      "stIdVersion": "R-HSA-909733.9",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 3,
+      "name": [
+       "Interferon alpha/beta signaling"
+      ],
+      "releaseDate": "2010-12-14",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-909733.6",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-06-07",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     }
+    ]
+   }
+  },
+  {
+   "tool": "Reactome_map_uniprot_to_pathways",
+   "args": {
+    "uniprot_id": "P00973"
+   },
+   "response": {
+    "status": "success",
+    "data": [
+     {
+      "dbId": 877300,
+      "displayName": "Interferon gamma signaling",
+      "stId": "R-HSA-877300",
+      "stIdVersion": "R-HSA-877300.9",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 3,
+      "name": [
+       "Interferon gamma signaling"
+      ],
+      "releaseDate": "2010-12-14",
+      "speciesName": "Homo sapiens",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-06-07",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 8983711,
+      "displayName": "OAS antiviral response",
+      "stId": "R-HSA-8983711",
+      "stIdVersion": "R-HSA-8983711.5",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 2,
+      "name": [
+       "OAS antiviral response"
+      ],
+      "releaseDate": "2018-09-12",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-8983711.1",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2020-06-17",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     },
+     {
+      "dbId": 909733,
+      "displayName": "Interferon alpha/beta signaling",
+      "stId": "R-HSA-909733",
+      "stIdVersion": "R-HSA-909733.9",
+      "isInDisease": false,
+      "isInferred": false,
+      "maxDepth": 3,
+      "name": [
+       "Interferon alpha/beta signaling"
+      ],
+      "releaseDate": "2010-12-14",
+      "speciesName": "Homo sapiens",
+      "doi": "10.3180/R-HSA-909733.6",
+      "hasDiagram": true,
+      "hasEHLD": false,
+      "lastUpdatedDate": "2023-06-07",
+      "schemaClass": "Pathway",
+      "className": "Pathway"
+     }
+    ]
+   }
+  }
+ ]
+}

tests/test_accepted_vulns.py

@@ -0,0 +1,51 @@
+"""Accepted pip-audit findings stay narrow, documented, dated, and die when they are fixed."""
+
+from __future__ import annotations
+
+import datetime
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+LINE = re.compile(r"^(?P<id>\S+) expires=(?P<date>\d{4}-\d{2}-\d{2}) (?P<pkg>\S+) (?P<ver>\S+)$")
+
+
+def _entries():
+    out = []
+    for raw in (ROOT / "security/accepted-vulns.txt").read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        m = LINE.match(line)
+        assert m, f"malformed acceptance line: {line!r}"
+        out.append(m.groupdict())
+    return out
+
+
+def _locked(package: str) -> str | None:
+    lock = (ROOT / "requirements.txt").read_text()
+    m = re.search(rf"^{re.escape(package)}==(\S+)$", lock, re.MULTILINE | re.IGNORECASE)
+    return m.group(1) if m else None
+
+
+def test_every_acceptance_is_well_formed_dated_and_short_lived():
+    for e in _entries():
+        expires = datetime.date.fromisoformat(e["date"])
+        # D5-A: no acceptance runs past 2026-11-20 without a new decision.
+        assert expires <= datetime.date(2026, 11, 20), e
+
+
+def test_every_acceptance_is_justified_in_the_findings_record():
+    record = (ROOT / "security/ACCEPTED-FINDINGS.md").read_text()
+    for e in _entries():
+        suffix = e["id"].split("-")[-1]
+        assert e["id"] in record or f"-{suffix}" in record, e["id"]
+
+
+def test_an_acceptance_dies_when_its_package_moves_off_the_affected_version():
+    """When the lock moves pillow to a fixed version, remove the entries; this fails until then."""
+    for e in _entries():
+        assert _locked(e["pkg"]) == e["ver"], (
+            f"{e['pkg']} is now {_locked(e['pkg'])} in requirements.txt; {e['id']} was accepted "
+            f"for {e['ver']} only — remove it from security/accepted-vulns.txt"
+        )

tests/test_access_gate.py

@@ -0,0 +1,74 @@
+"""C7 — the gate runs first, in every handler, machine and UI alike (family contract)."""
+
+from __future__ import annotations
+
+import json
+import types
+
+import pytest
+
+import gradio_ui
+from src.endpoints import ENDPOINTS
+
+
+@pytest.fixture()
+def enforced(monkeypatch):
+    monkeypatch.setenv("ACCESS_CONTROL", "enforce")
+    monkeypatch.setenv("ALLOWED_IDS", "someone-else")
+    monkeypatch.setenv("ADMIN_IDS", "an-admin")
+
+
+@pytest.mark.parametrize("name", list(ENDPOINTS))
+def test_no_token_is_denied_with_no_run_id(enforced, name):
+    payload = json.loads(getattr(gradio_ui, name)(request=None))
+    assert payload["status"] == "denied"
+    assert payload["machine_auth"] == "no_token_header"
+    assert "run_id" not in payload
+
+
+@pytest.mark.parametrize("name", list(ENDPOINTS))
+def test_the_gate_runs_before_validation(enforced, name):
+    """Bad input from an unauthenticated caller is denied, never refused: it learns nothing."""
+    payload = json.loads(getattr(gradio_ui, name)("what drugs target KRAS?", request=None))
+    assert payload["status"] == "denied"
+
+
+def test_an_unresolvable_token_is_denied(enforced, monkeypatch):
+    monkeypatch.setattr(gradio_ui, "_resolve_token_identity", lambda token: None)
+    request = types.SimpleNamespace(headers={"x-orchestrator-token": "Bearer not-a-real-token"})
+    payload = json.loads(gradio_ui.annotate_genes("KRAS", request=request))
+    assert payload["status"] == "denied" and payload["machine_auth"] == "token_unresolved"
+
+
+def test_a_resolved_but_unlisted_caller_is_denied(enforced, monkeypatch):
+    monkeypatch.setattr(gradio_ui, "_resolve_token_identity", lambda token: "a-stranger")
+    request = types.SimpleNamespace(headers={"x-orchestrator-token": "hf_test"})
+    payload = json.loads(gradio_ui.annotate_genes("KRAS", request=request))
+    assert payload["status"] == "denied" and payload["machine_auth"] == "not_allowlisted"
+
+
+def test_an_allowlisted_caller_gets_through_to_validation(enforced, monkeypatch):
+    monkeypatch.setattr(gradio_ui, "_resolve_token_identity", lambda token: "someone-else")
+    request = types.SimpleNamespace(headers={"x-orchestrator-token": "hf_test"})
+    payload = json.loads(gradio_ui.annotate_genes("what drugs target KRAS?", request=request))
+    assert payload["status"] == "refused" and payload["reason"] == "invalid_identifier"
+
+
+def test_a_non_string_argument_is_a_typed_error(monkeypatch):
+    monkeypatch.delenv("ACCESS_CONTROL", raising=False)
+    payload = json.loads(gradio_ui.drugs_for_targets(["KRAS"], request=None))
+    assert payload["status"] == "error"
+    assert payload["machine_input"] == "genes_not_a_string"
+
+
+def test_the_ui_handler_runs_the_gate_too(enforced):
+    summary, raw = gradio_ui._ui_call("annotate_genes")("KRAS", profile=None)
+    assert "Access denied" in summary
+    assert json.loads(raw)["status"] == "denied"
+
+
+def test_gate_off_lets_a_call_through(monkeypatch, replay):
+    monkeypatch.delenv("ACCESS_CONTROL", raising=False)
+    replay("q3_annotate_elavl1")  # installs the replay client; the machine call below reuses it
+    payload = json.loads(gradio_ui.annotate_genes("ELAVL1", request=None))
+    assert payload["status"] == "ok" and payload["rows"][0]["symbol"] == "ELAVL1"

tests/test_allowlist.py

@@ -4,7 +4,7 @@ What these tests pin, against the INSTALLED ToolUniverse (offline: loading reads
 own JSON configs and opens no socket, which the conftest block would turn into a failure):
 
 - the config is the memo's 28 tools across 8 sources, and every name exists in 1.5.6;
-- the Space loads exactly the five endpoints' set (12 tools), nothing more;
+- the Space loads exactly the five endpoints' set (8 tools since s2), nothing more;
 - no agentic, tool-finder, remote-MCP, web-search or key-gated tool is or can be loaded;
 - the installed version is the pinned one, and a mismatch refuses startup;
 - ToolUniverse's own result cache is off.
@@ -51,7 +51,7 @@ def test_every_allowlisted_name_exists_in_the_installed_version():
 def test_the_space_loads_exactly_the_endpoints_set(loaded_tu):
     loaded = frozenset(loaded_tu.all_tool_dict)
     assert loaded == config.endpoint_tool_names()
-    assert len(loaded) == 12
+    assert len(loaded) == 8
     assert loaded <= config.allowed_tool_names()
 
 

tests/test_deploy_surface.py

@@ -0,0 +1,88 @@
+"""The deploy descriptor, the endpoint table and the gr.api surface must agree (names are frozen)."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from pathlib import Path
+
+import yaml
+
+_EXPECTED = [
+    "drugs_for_targets",
+    "trials_for_genes",
+    "annotate_genes",
+    "pathways_for_genes",
+    "targets_for_disease",
+]
+_REPO = Path(__file__).resolve().parent.parent
+
+
+def _descriptor() -> dict:
+    return yaml.safe_load((_REPO / "deploy" / "orchestrator_registration.yaml").read_text())
+
+
+def test_descriptor_names_and_params_match_the_endpoint_table():
+    from src import config
+    from src.endpoints import ENDPOINTS
+
+    descriptor = _descriptor()
+    assert descriptor["id"] == "pdac_knowledge_agent"
+    assert descriptor["dispatch_kind"] == "tool_server"
+    assert descriptor["space"] == "anne-voigt/pdac-knowledge-agent"
+    assert descriptor["space_dev"] == "anne-voigt/pdac-knowledge-agent-dev"
+    names = [t["name"] for t in descriptor["tools"]]
+    assert names == _EXPECTED == list(ENDPOINTS) == list(config.ENDPOINTS)
+    for tool in descriptor["tools"]:
+        assert tool["api_name"] == f"/{tool['name']}"
+        assert tuple(tool["params"]) == ENDPOINTS[tool["name"]][1]
+
+
+def test_gradio_functions_exist_with_string_defaults_and_trailing_request():
+    import gradio_ui
+    from src.endpoints import ENDPOINTS
+
+    for name in _EXPECTED:
+        params = list(inspect.signature(getattr(gradio_ui, name)).parameters.values())
+        assert params[-1].name == "request"
+        assert [p.name for p in params[:-1]] == list(ENDPOINTS[name][1])
+        assert all(p.default == "" for p in params[:-1])
+
+
+def test_every_endpoint_is_registered_with_gr_api():
+    import gradio_ui
+
+    registered = {getattr(fn, "api_name", None) for fn in gradio_ui.demo.fns.values()}
+    assert set(_EXPECTED) <= registered
+
+
+def test_the_boundary_sentence_is_the_adrs_verbatim():
+    adr = (_REPO / "docs/adr/ADR-0001-knowledge-specialist-contract.md").read_text()
+    quoted = re.search(
+        r'reused verbatim in the descriptor and the routing prompt: \*"(.+?)"\*', adr, re.DOTALL
+    )
+    sentence = " ".join(quoted.group(1).split())
+    assert " ".join(_descriptor()["description"].split()) == sentence
+
+
+def test_descriptor_states_the_caps_the_code_enforces():
+    from src.endpoints import drugs, targets
+    from src.identifiers import MAX_IDENTIFIERS
+
+    described = {t["name"]: " ".join(t["description"].split()) for t in _descriptor()["tools"]}
+    assert (
+        f"for the {drugs.MAX_MECHANISM_LOOKUPS} most advanced drugs"
+        in described["drugs_for_targets"]
+    )
+    assert (
+        f"`size` is 1-{targets.MAX_SIZE} (default {targets.DEFAULT_SIZE})"
+        in described["targets_for_disease"]
+    )
+    for name in ("drugs_for_targets", "annotate_genes", "pathways_for_genes"):
+        assert f"at most {MAX_IDENTIFIERS}" in described[name], name
+    assert "MEMBERSHIP, NOT ENRICHMENT" in described["pathways_for_genes"]
+
+
+def test_annotate_genes_carries_its_longer_timeout():
+    [annotate] = [t for t in _descriptor()["tools"] if t["name"] == "annotate_genes"]
+    assert annotate["timeout_seconds"] == 300

tests/test_endpoint_provenance.py

@@ -0,0 +1,75 @@
+"""C3 — provenance on every row of every endpoint, over every recorded scenario.
+
+Rows carry a ``provenance`` block; so does each nested block that comes from a second source
+(drugs' ChEMBL ``mechanisms``, annotation's UniProt ``protein``, the disease resolution and the
+HGNC identifier mapping). Every ok payload is ``kind: "annotation"`` with no sample size.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from src.provenance import missing_fields
+from tests.conftest import SCENARIOS
+
+
+def _nested_blocks(payload):
+    for row in payload["rows"]:
+        mech = row.get("mechanisms")
+        if isinstance(mech, dict) and mech.get("looked_up") is not False:
+            yield "mechanisms", mech
+        if row.get("protein"):
+            yield "protein", row["protein"]
+    for res in payload.get("resolved_identifiers") or []:
+        yield "resolved_identifiers", res
+    disease = payload.get("disease")
+    if isinstance(disease, dict) and "provenance" in disease:
+        yield "disease", disease
+
+
+@pytest.mark.parametrize("scenario", SCENARIOS)
+def test_every_row_and_nested_block_is_fully_stamped(replay, scenario):
+    payload = replay(scenario)
+    if payload["status"] != "ok":
+        assert payload["status"] == "refused" and payload["run_id"]
+        return
+    assert payload["kind"] == "annotation"
+    assert "n_for_inference" not in payload and "hierarchy" not in payload
+    for i, row in enumerate(payload["rows"]):
+        assert missing_fields(row) == [], (scenario, i)
+    for where, block in _nested_blocks(payload):
+        assert missing_fields(block) == [], (scenario, where)
+    used = {a["source"] for a in payload["attribution"]}
+    stamped_sources = {r["provenance"]["source"] for r in payload["rows"]} | {
+        b["provenance"]["source"] for _, b in _nested_blocks(payload)
+    }
+    assert stamped_sources <= used, scenario  # every licence a row carries is attributed
+
+
+@pytest.mark.parametrize("scenario", SCENARIOS)
+def test_the_narrative_names_its_source_and_query_date(replay, scenario):
+    payload = replay(scenario)
+    if payload["status"] != "ok" or not payload["rows"]:
+        return
+    assert payload["narrative"].startswith("According to ")
+    assert "(queried 20" in payload["narrative"]
+
+
+def test_licences_on_rows_come_from_config(replay):
+    payload = replay("q6_drugs_jak_stat")
+    rows = payload["rows"]
+    assert {r["provenance"]["licence"] for r in rows} == {"CC0 1.0"}
+    mechs = [r["mechanisms"] for r in rows if r["mechanisms"].get("looked_up") is not False]
+    assert mechs and {m["provenance"]["licence"] for m in mechs} == {"CC BY-SA 3.0"}
+    not_looked_up = [r for r in rows if r["mechanisms"].get("looked_up") is False]
+    assert len(not_looked_up) == len(rows) - sum(
+        1 for r in rows if r["mechanisms"].get("looked_up") is not False
+    )
+
+
+def test_a_cached_replay_keeps_the_recorded_retrieved_at(replay):
+    first = replay("q7_drugs_tnfrsf10b")
+    again = replay("q7_drugs_tnfrsf10b")
+    assert [r["provenance"]["retrieved_at"] for r in first["rows"]] == [
+        r["provenance"]["retrieved_at"] for r in again["rows"]
+    ]

tests/test_output_schemas.py

@@ -14,7 +14,7 @@ import pytest
 
 from src import config, schemas
 from src.tu_client import SourceError, ToolClient
-from tests.conftest import FakeRunner
+from tests.conftest import SCENARIOS, FakeRunner
 
 OT_DRUGS = "OpenTargets_get_associated_drugs_by_target_ensemblID"
 ARGS = {"ensemblId": "ENSG00000120889", "size": 100}
@@ -88,27 +88,31 @@ def test_an_added_field_upstream_is_not_drift(memory_cache, clock, tnfrsf10b_res
     assert result.cache == "miss"
 
 
-def test_a_tool_with_no_pinned_schema_builds_no_rows(memory_cache, clock):
-    client = ToolClient(
-        runner=FakeRunner({"UniProt_search": {"status": "success", "data": {"results": []}}}),
-        cache=memory_cache,
-        clock=clock,
-        tooluniverse_version="1.5.6",
-    )
-    with pytest.raises(SourceError) as excinfo:
-        client.call("UniProt_search", {"query": "gene_exact:KRAS"})
-    assert excinfo.value.reason == "upstream_schema_drift"
-    assert "no pinned schema" in excinfo.value.detail
+def test_a_tool_with_no_pinned_schema_builds_no_rows():
+    """Fail-closed: an approved tool that gains an endpoint without a schema cannot answer."""
+    with pytest.raises(schemas.SchemaDrift, match="no pinned schema"):
+        schemas.validate("PubChem_get_CID_by_compound_name", {"IdentifierList": {"CID": [60750]}})
+
+
+@pytest.mark.parametrize("scenario", SCENARIOS)
+def test_every_recorded_response_validates(scenario):
+    """C4: what the sources said on the recording day matches every pinned schema."""
+    import json
+
+    from src.tu_client import _unwrap
+    from tests.conftest import CASSETTES
+
+    for call in json.loads((CASSETTES / f"{scenario}.json").read_text())["calls"]:
+        try:
+            data = _unwrap(call["tool"], config.source_of(call["tool"]), call["response"])
+        except SourceError:
+            continue  # a recorded error envelope (the legacy EFO id): no data to validate
+        schemas.validate(call["tool"], data)
 
 
 def test_every_pinned_schema_belongs_to_an_endpoint_tool():
     assert schemas.pinned_tools() <= config.endpoint_tool_names()
 
 
-@pytest.mark.xfail(
-    strict=True,
-    reason="s2 records the Phase 0 fixtures and pins the remaining 11 schemas; when it does, "
-    "this XPASSes and strict mode fails the suite until the marker is removed",
-)
 def test_every_endpoint_tool_has_a_pinned_schema():
     assert schemas.pinned_tools() == config.endpoint_tool_names()

tests/test_phase0_replay.py

@@ -0,0 +1,135 @@
+"""C6 — the ten Phase 0 lookups, recorded once, replay to their expected entities.
+
+Each scenario is a cassette in tests/fixtures/cassettes/ recorded live through the real
+endpoints and ToolUniverse 1.5.6 (scripts/record_fixtures.py). Q10 (gemcitabine identifiers,
+PubChem) has no Phase 1 endpoint and is not replayed.
+"""
+
+from __future__ import annotations
+
+from src.identifiers import NCT
+
+
+def _drugs(payload, target=None):
+    return {r["drug"] for r in payload["rows"] if target is None or r["target"] == target}
+
+
+def test_q1_kras_g12d_mrtx1133_absent_from_open_targets_and_the_note_says_so(replay):
+    payload = replay("q1_q2_drugs_kras")
+    assert payload["status"] == "ok"
+    assert not any("MRTX" in d for d in _drugs(payload))
+    notes = " ".join(n["note"] for n in payload["coverage_notes"])
+    assert "MRTX1133" in notes
+
+
+def test_q2_kras_g12c_sotorasib_and_adagrasib_approved(replay):
+    payload = replay("q1_q2_drugs_kras")
+    approved = {r["drug"] for r in payload["rows"] if r["stage"] == "approved"}
+    assert {"SOTORASIB", "ADAGRASIB"} <= approved
+    assert "SOTORASIB" in payload["narrative"] and "ADAGRASIB" in payload["narrative"]
+
+
+def test_q3_elavl1_is_an_rna_binding_stabiliser(replay):
+    payload = replay("q3_annotate_elavl1")
+    [row] = payload["rows"]
+    assert row["symbol"] == "ELAVL1"
+    assert row["protein"]["accession"] == "Q15717"
+    function = row["protein"]["function"].lower()
+    assert "rna" in function and "stabil" in function
+
+
+def test_q4_porg_54_of_55_with_sord2p_unresolved(replay):
+    payload = replay("q4_annotate_porg")
+    assert len(payload["rows"]) == 55
+    with_protein = [r for r in payload["rows"] if r["protein"]]
+    assert len(with_protein) == 54
+    assert [u["input"] for u in payload["unresolved"]] == ["SORD2P"]
+    sord2p = next(r for r in payload["rows"] if r["symbol"] == "SORD2P")
+    assert sord2p["protein"] is None and sord2p["locus_type"] == "pseudogene"
+    assert "54 have a reviewed human UniProt entry" in payload["narrative"]
+
+
+def test_q5_cd40_trial_semantics_are_pinned(replay):
+    payload = replay("q5_trials_cd40")
+    assert [r["nct_id"] for r in payload["rows"]] == ["NCT06205849"]
+    assert all(NCT.match(r["nct_id"]) for r in payload["rows"])
+    [executed] = payload["executed_queries"]
+    assert executed["executed_query"]["query.intr"] == (
+        "(AREA[InterventionName]CD40 OR AREA[InterventionOtherName]CD40)"
+    )
+    assert executed["executed_query"]["filter.overallStatus"] == "RECRUITING"
+    assert "intervention name" in payload["query_semantics"]
+
+
+def test_q6_ruxolitinib_targets_jak1_and_jak2_and_stat1_has_none(replay):
+    payload = replay("q6_drugs_jak_stat")
+    for target in ("JAK1", "JAK2"):
+        assert any(d.startswith("RUXOLITINIB") for d in _drugs(payload, target)), target
+    assert _drugs(payload, "STAT1") == set()
+    assert "STAT1 has no listed drugs or clinical candidates" in payload["narrative"]
+    assert payload["mechanism_lookups"] == {"looked_up": 30, "cap": 30}
+
+
+def test_q7_dr5_all_seven_agents(replay):
+    payload = replay("q7_drugs_tnfrsf10b")
+    assert _drugs(payload) == {
+        "CONATUMUMAB",
+        "LEXATUMUMAB",
+        "TIGATUZUMAB",
+        "DROZITUMAB",
+        "DULANERMIN",
+        "APOMAB",
+        "LBY-135",
+    }
+
+
+def test_q8_pdac_top_targets(replay):
+    payload = replay("q8_targets_pdac")
+    assert payload["disease"]["id"] == "MONDO_0005184"
+    assert payload["disease"]["matched"] == "exact name"
+    top = [r["target"] for r in payload["rows"]]
+    assert {"KRAS", "TP53", "CDKN2A", "SMAD4"} <= set(top)
+    assert top[0] == "KRAS"
+    assert [r["rank"] for r in payload["rows"]] == list(range(1, len(top) + 1))
+    assert "Open Targets' own association score" in payload["narrative"]
+
+
+def test_q9_isg15_rsad2_oas1_share_interferon_alpha_beta_signaling(replay):
+    payload = replay("q9_pathways_isg15_rsad2_oas1")
+    assert {"pathway_id": "R-HSA-909733", "pathway_name": "Interferon alpha/beta signaling"} in (
+        payload["shared_by_all"]
+    )
+    assert "membership, not enrichment" in payload["narrative"]
+    assert "enriched" not in payload["narrative"].lower()
+
+
+def test_c1_sord2p_listed_as_unresolved_not_guessed(replay):
+    payload = replay("c1_annotate_kras_tp53_sord2p")
+    assert [r["symbol"] for r in payload["rows"]] == ["KRAS", "TP53", "SORD2P"]
+    assert [u["input"] for u in payload["unresolved"]] == ["SORD2P"]
+    assert "SORD2P" in payload["narrative"]
+
+
+def test_an_unknown_symbol_is_unresolved_and_no_target_is_queried(replay):
+    payload = replay("edge_unknown_symbol")
+    assert payload["status"] == "ok" and payload["rows"] == []
+    assert payload["unresolved"][0]["input"] == "NOTAGENE1"
+
+
+def test_a_legacy_efo_id_is_refused_with_open_targets_message(replay):
+    payload = replay("edge_legacy_efo")
+    assert payload["status"] == "refused"
+    assert payload["reason"] == "unknown_disease"
+    assert "MONDO" in payload["message"]
+
+
+def test_every_scenario_was_recorded_through_the_pinned_version():
+    import json
+
+    from tests.conftest import CASSETTES, SCENARIOS
+
+    assert len(SCENARIOS) == 11
+    for name in SCENARIOS:
+        meta = json.loads((CASSETTES / f"{name}.json").read_text())["_recorded"]
+        assert meta["tooluniverse_version"] == "1.5.6", name
+        assert meta["recorded_with"] == "scripts/record_fixtures.py", name

tests/test_refusals_and_payloads.py

@@ -0,0 +1,220 @@
+"""C7 — refusals are data, and they happen before any outbound call (ADR-0001 §5, §6).
+
+Every endpoint here runs against a client whose runner fails the test if it is ever called, so
+"refused before any call" is enforced, not assumed.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from src.endpoints import ENDPOINTS, _common
+from src.tu_client import ToolClient
+from tests.conftest import FakeRunner
+
+
+class NoCalls:
+    def __call__(self, tool, args):
+        raise AssertionError(f"an outbound call was attempted: {tool} {args}")
+
+
+@pytest.fixture()
+def no_calls(memory_cache, clock):
+    _common.set_client(
+        ToolClient(runner=NoCalls(), cache=memory_cache, clock=clock, tooluniverse_version="1.5.6")
+    )
+    yield
+    _common.set_client(None)
+
+
+GENE_ENDPOINTS = ["drugs_for_targets", "trials_for_genes", "annotate_genes", "pathways_for_genes"]
+
+
+@pytest.mark.parametrize("endpoint", GENE_ENDPOINTS)
+@pytest.mark.parametrize(
+    "genes",
+    [
+        "what drugs target KRAS?",
+        "TCGA-2J-AAB1-01A",
+        "GSM1234567",
+        "KRAS 2.5",
+        "",
+        "SELECT * FROM genes",
+    ],
+)
+def test_bad_gene_input_is_refused_before_any_call(no_calls, endpoint, genes):
+    payload = ENDPOINTS[endpoint][0](genes)
+    assert payload["status"] == "refused"
+    assert payload["reason"] == "invalid_identifier"
+    assert payload["run_id"] and payload["message"]
+
+
+@pytest.mark.parametrize("endpoint", GENE_ENDPOINTS)
+def test_more_than_100_identifiers_is_refused(no_calls, endpoint):
+    genes = ",".join(f"GENE{i}" for i in range(101))
+    payload = ENDPOINTS[endpoint][0](genes)
+    assert payload["reason"] == "too_many_identifiers"
+
+
+@pytest.mark.parametrize("endpoint", ["trials_for_genes", "annotate_genes", "pathways_for_genes"])
+def test_ensembl_ids_are_refused_where_hgnc_symbols_are_needed(no_calls, endpoint):
+    payload = ENDPOINTS[endpoint][0]("ENSG00000133703")
+    assert payload["reason"] == "invalid_identifier"
+
+
+@pytest.mark.parametrize(
+    "args,reason",
+    [
+        (("CD40", "", "SOMETIMES"), "invalid_argument"),
+        (("CD40", "MONDO_0005184", ""), "invalid_identifier"),
+        (("CD40", "x" * 90, ""), "invalid_identifier"),
+    ],
+)
+def test_trials_arguments_are_checked(no_calls, args, reason):
+    from src.endpoints import trials_for_genes
+
+    assert trials_for_genes(*args)["reason"] == reason
+
+
+@pytest.mark.parametrize("size", ["0", "51", "ten", "-3"])
+def test_targets_size_is_bounded(no_calls, size):
+    from src.endpoints import targets_for_disease
+
+    payload = targets_for_disease("pancreatic ductal adenocarcinoma", size)
+    assert payload["reason"] == "invalid_argument"
+
+
+@pytest.mark.parametrize("disease", ["", "patient 12; DOB 1950-01-01?", "TCGA-2J-AAB1", "1234"])
+def test_bad_disease_is_refused(no_calls, disease):
+    from src.endpoints import targets_for_disease
+
+    assert targets_for_disease(disease)["reason"] == "invalid_identifier"
+
+
+HGNC_KRAS = {
+    "status": "success",
+    "data": {
+        "symbol": "KRAS",
+        "hgnc_id": "HGNC:6407",
+        "name": "KRAS proto-oncogene, GTPase",
+        "locus_type": "gene with protein product",
+        "ensembl_gene_id": "ENSG00000133703",
+        "uniprot_ids": ["P01116"],
+    },
+}
+
+
+def _with(responses, memory_cache, clock):
+    _common.set_client(
+        ToolClient(
+            runner=FakeRunner(responses),
+            cache=memory_cache,
+            clock=clock,
+            tooluniverse_version="1.5.6",
+        )
+    )
+
+
+def _hgnc(args):
+    symbol = args["symbol"]
+    ensembl = {"KRAS": "ENSG00000133703", "TNFRSF10B": "ENSG00000120889"}[symbol]
+    data = {**HGNC_KRAS["data"], "symbol": symbol, "ensembl_gene_id": ensembl}
+    return {"status": "success", "data": data}
+
+
+def test_a_failing_source_is_a_source_error_not_a_guess(memory_cache, clock, tnfrsf10b_response):
+    """One target's Open Targets call fails: the other's rows stand, the failure is named."""
+    from src.endpoints import drugs_for_targets
+
+    def ot(args):
+        if args["ensemblId"] == "ENSG00000133703":
+            raise TimeoutError("read timed out")
+        return tnfrsf10b_response
+
+    _with(
+        {
+            "HGNC_fetch_gene_by_symbol": _hgnc,
+            "OpenTargets_get_associated_drugs_by_target_ensemblID": ot,
+            "ChEMBL_get_drug_mechanisms": {"status": "success", "data": {"mechanisms": []}},
+        },
+        memory_cache,
+        clock,
+    )
+    try:
+        payload = drugs_for_targets("KRAS,TNFRSF10B")
+    finally:
+        _common.set_client(None)
+    assert payload["status"] == "ok"
+    assert {r["target"] for r in payload["rows"]} == {"TNFRSF10B"}
+    assert payload["source_errors"] == [
+        {
+            "source": "opentargets",
+            "reason": "source_unavailable",
+            "detail": "OpenTargets_get_associated_drugs_by_target_ensemblID: TimeoutError",
+        }
+    ]
+    assert "Source problems: opentargets source_unavailable" in payload["narrative"]
+
+
+def test_when_the_drug_source_fails_for_every_target_it_is_an_error(memory_cache, clock):
+    from src.endpoints import drugs_for_targets
+
+    _with(
+        {
+            "HGNC_fetch_gene_by_symbol": HGNC_KRAS,
+            "OpenTargets_get_associated_drugs_by_target_ensemblID": TimeoutError("read timed out"),
+        },
+        memory_cache,
+        clock,
+    )
+    try:
+        payload = drugs_for_targets("KRAS")
+    finally:
+        _common.set_client(None)
+    assert payload["status"] == "error" and payload["reason"] == "all_sources_failed"
+    assert payload["source_errors"][0]["source"] == "opentargets"
+
+
+def test_when_nothing_answers_the_payload_is_an_error(memory_cache, clock):
+    from src.endpoints import annotate_genes
+
+    _with({"HGNC_fetch_gene_by_symbol": ConnectionError("reset")}, memory_cache, clock)
+    try:
+        payload = annotate_genes("KRAS,TP53")
+    finally:
+        _common.set_client(None)
+    assert payload["status"] == "error"
+    assert payload["reason"] == "all_sources_failed"
+    assert {e["source"] for e in payload["source_errors"]} == {"hgnc"}
+
+
+def test_a_drifted_response_builds_no_rows(memory_cache, clock):
+    from src.endpoints import drugs_for_targets
+
+    drifted = {
+        "status": "success",
+        "data": {"target": {"id": "ENSG00000133703", "approvedSymbol": "KRAS"}},
+    }
+    _with(
+        {
+            "HGNC_fetch_gene_by_symbol": HGNC_KRAS,
+            "OpenTargets_get_associated_drugs_by_target_ensemblID": drifted,
+        },
+        memory_cache,
+        clock,
+    )
+    try:
+        payload = drugs_for_targets("KRAS")
+    finally:
+        _common.set_client(None)
+    assert payload["status"] == "error"
+    assert "rows" not in payload
+    assert payload["source_errors"][0]["reason"] == "upstream_schema_drift"
+
+
+def test_source_errors_carry_only_the_three_reasons():
+    from src.payloads import SOURCE_ERROR_REASONS, source_error
+
+    assert SOURCE_ERROR_REASONS == ("source_unavailable", "rate_limited", "upstream_schema_drift")
+    with pytest.raises(ValueError):
+        source_error("opentargets", "made_up", "z")