step 1 / 6 · input
Pipeline architecture

Gene Program Interpreter

A tissue-agnostic pipeline that turns weighted gene programs into biological interpretation — where every claim links to a real, verified citation, never a fabricated one.

Walkthrough grounded in a real run: mouse hepatocyte Perturb-seq Program 10 press Follow Program 10 to trace one program end-to-end.
input · executor ④ Highlight

Context & regulator injection

gene_loading.csv · research/bundle.py · gpi/context_profile.py

One weighted gene list per program — from cNMF / NMF / Perturb-seq — is packaged into a self-contained research brief: its marker genes framed with a structured ContextProfile, the high-leverage context_terms that define normal cell function, and its activating / repressing perturbation regulators. Capturing biological context for real data; this brief is the only thing each research agent sees.

weighted program · top genes (of 300)
program_bundles/P10.jsonresearch brief
ContextProfile
organism mouse tissue liver cell type hepatocyte conditions aging · MASLD
context_terms — normal cell-type function
metabolic zonation xenobiotic & drug metabolism bile-acid metabolism gluconeogenesis & glycogen nitrogen & urea metabolism oxidative / mitochondrial membrane transport & SLCs lipid metabolism
perturbation regulators (Perturb-seq)
↑ activating
Insig1Fgfr4Trib1
↓ repressing
Dgat2ScapMlxipl
context_terms reach the agent verbatim & fold into the PubMed keyword query
P10
A 300-gene program led by Rhbg, Glul, Cyp2e1, Axin2 — raw loadings, now framed as a mouse hepatocyte program an agent can actually research.
executor ④ · deterministic

STRING evidence collection

gpi/enrichment.py · gpi/string_api.py

Before any model sees the program, the pipeline gathers conventional STRING evidence: GO & KEGG functional enrichment over the marker genes, and the protein–protein interaction network that links each perturbation regulator to its confidence-scored targets. Bundled into the brief, this evidence anchors the literature search and the final annotation.

STRING functional enrichment — GO process & KEGG pathways
GOfatty-acid metabolic process GOxenobiotic metabolic process KEGGdrug metabolism — CYP450 KEGGretinol metabolism GOsteroid metabolic process
STRING interaction network — regulator → target, confidence-scored
activating repressing regulator target gene edge width ∝ STRING confidence (0–1000)
P10
STRING ties P10's lipid-metabolism regulators to a shared Ppara / cholesterol-synthesis hub — real associations (scores 413–941), not guesses.
executor ② · Agent SDK Highlight

Parallel literature research

research/research_parallel.py · research/literature.py

One isolated Claude Agent-SDK session per program, fanned out under a Python asyncio Semaphore — there is no manager agent. Each session is sandboxed to see only its own brief and queries PubMed, OpenAlex & Crossref through an in-process literature server. The agent decides every search; deterministic code never researches on its own.

Python controls fan-out · asyncio.Semaphore(k) · k = 3–5
Claude Agent SDK in-process MCP: PubMed · OpenAlex · Crossref sandboxed · Read-only Claude.ai subscription
P10
P10's agent ran 31 turns, searched zonation / ammonia-transport / xenobiotic literature, and submitted 3 candidate mechanisms with 30 attached papers — for $0.46.
executor ④ · deterministic

Deterministic verification

research/verify.py

Before anything is shown, every PMID and DOI the agents returned is resolved against CrossRef and NCBI, checked for retraction, and de-duplicated. Identifiers that don't resolve are dropped and the run degrades honestly — the pipeline never invents an identifier to fill a gap.

PMID 29059455 PMID 26655896 DOI 10.1016/j.stem.2021.05.013 PMID 39052834 PMID 31866224 · contradicts Tbx3 · no paper
CrossRef + NCBI resolvability · retraction · dedup
P10
30 / 30 identifiers resolved · 0 retracted. One paper is kept precisely because it disagrees; six genes are logged as gaps, not glossed over.
executor ③ · Anthropic Batch Highlight

Batch annotation & synthesis

gpi/evidence_context.py · gpi/anthropic_batch.py

Verified evidence is folded back into a per-program prompt and synthesized through the Anthropic Batch API — functional modules, a lead sentence, and a cross-program label. Research bills the subscription; batch synthesis bills API credit — a clean auth split by executor.

P10 · brief + evidence
P22 · brief + evidence
… per program
Anthropic Batch
one request · many programs
② research → subscription
Agent-SDK CLI on Claude.ai; API key withheld.
③ batch → API credit
Batch synthesis on ANTHROPIC_API_KEY.
P10
Synthesis names the program: "Pericentral Hepatocyte Zonation & Detoxification" — a label chosen across programs, not by P10's agent alone.
executor ④ · deterministic Highlight

One-click evidence report

gpi/html_report.py → report.html

A single interactive HTML report. Each functional module carries an evidence-status colour, and every supporting claim is one click from the resolvable paper — PMID, DOI, out to PubMed. Disagreement and gaps are shown, not hidden. Click any citation below.

Program 10 STRING top pathway · drug metabolism (CYP450)

Pericentral Hepatocyte Zonation & Detoxification

The pericentral (zone 3) compartment — Wnt/β-catenin zonation, ammonia detoxification via glutamine synthesis, and pericentral xenobiotic metabolism.

supported Pericentral zonation via Wnt/β-catenin
GlulAxin2Cyp2e1Cyp1a2Tbx3
supported Pericentral ammonia detoxification & nitrogen metabolism
GlulRhbgOatSlc1a2
supported Xenobiotic & drug metabolism + hepatic uptake transport
Cyp2e1Gstm2Slc22a1Slco1b2
contradictory

An AXIN2⁺ lineage-tracing study argues pericentral hepatocytes contribute little to homeostatic turnover — challenging the pericentral stem-cell hypothesis. Surfaced, not suppressed.

evidence gap

No hepatocyte-specific functional papers were retrieved for Tbx3, Lhpp, Gulo, Lect2 — recorded as open questions.

report.html every claim → resolvable PMID / DOI · supported · partial · contradictory · missing
P10
From 300 anonymous genes to a named, colour-graded interpretation where a collaborator reaches the primary literature in one click. That is the whole point.

Executors — who runs each step

Research agents. Claude Agent SDK, one isolated session per program, real-time, MCP tool-using.
Anthropic Batch. Batched per-program LLM synthesis — annotation, labels, themes.
Deterministic. Parsing, bundling, citation verification, HTML render — no model.

Evidence status

Supported — mechanism backed by resolvable papers.
Partial — some support, some gaps.
Contradictory — literature disagrees; shown deliberately.
Missing — no paper found; logged as a gap.

Regulators

↑ Activating perturbation regulators.
↓ Repressing perturbation regulators.
context_terms — normal cell-type function vocabulary.
Worked example: runs/hepatocyte_p10_p22 claude-sonnet 30 / 30 citations resolved 0 retracted · 0 fabricated