Affinage

LLM-powered, literature-grounded gene function annotator. For each human protein-coding gene, Affinage retrieves the primary mechanistic literature, extracts dated experimental findings, and synthesizes a declarative, citation-anchored function narrative — at genome scale.

The full release covers 19,293 / 19,296 HGNC protein-coding genes (99.98%) at ~$0.13/gene (≈ $2,491 total at batch rates) and is served as a live REST API and MCP endpoint at https://affinage.wi.mit.edu.

---

Why it's different

• Single-pass, two-stage. A reading pass extracts only direct experimental evidence as dated, PMID-supported findings; a synthesis pass reasons over those findings alone — it never sees external databases (UniProt, DepMap, …), so the narrative is a synthesis of the primary literature, not a paraphrase of a curated source.
• Index-based citation. Stage 2 cites each claim by the integer index of the finding it rests on; a deterministic post-step resolves indices to the recorded PMIDs. The model never emits a citation token along this path, so confabulation is rare by construction — residual raw-PMID slips are caught by the audit layer (R7; 0.34% genome-wide).
• Deterministic audit (R1–R10). A pure regex/SQL tripwire layer (no LLM in the evidentiary chain) flags identity, grounding, and behavior anomalies on every released record — reproducible directly from the database.

Validation

• Faithfulness (100-gene failure-enriched gold-standard cohort, manually adjudicated per claim): 95.6% of claims supported, 0.26% genuine-error rate.
• Pairwise vs UniProt (cross-family Prometheus-8x7b judge):
  • cohort: 52/7/1 win/tie/loss over decided genes;
  • genome: 13,158 / 1,234 / 117 over the 14,509 genes with both a narrative and a UniProt function field — a 99.1% win rate over decided pairs.
• Genome audit: 289 / 19,293 records (1.50%) raise ≥1 R1–R10 flag.

---

Pipeline

Every gene set — the 100-gene cohort, ablation variants, and the full genome — flows through the same path:

 annotate ──► detect_audit_flags (R1–R10) ──► Prometheus eval ──► figures / web
                                              (faithfulness + pairwise)

 Stage 0  retrieve papers (PubMed + Europe PMC), rank by iCite citations,
          F1–F4 precision filter            [affinage/fetch, pubmed, citations, corpus_filter]
 Stage 1  read corpus → dated Timeline of findings   (Sonnet 4.6)  [affinage/annotate]
 Stage 2  Timeline → declarative Narrative, index-cited  (Opus 4.8) [affinage/synthesize]
 audit    R1–R10 concordance tripwires on the output   [affinage/audit_rules, audit_detect]

Prefetched reference data (UniProt, DepMap, OpenCell, HPA, OMIM, HGNC, AlphaFold) is attached to each record for display and the web projections, but is never an input to Stage 1 or Stage 2.

Layout

affinage/          core library
  fetch, pubmed, citations, _ncbi   Stage 0 retrieval + NCBI throttle
  corpus_filter, alias_filter        F1–F4 retrieval-precision layer
  prefetch                           disk-cached reference metadata (viewer bundle)
  annotate, synthesize               Stage 1 / Stage 2
  batch                              Batch-API wrapper (50% cost, parallel prefetch)
  audit_rules, audit_detect          R1–R10 deterministic audit
  eval_faithfulness, eval_pairwise   LLM-judge evaluation primitives
  bucket_manifest, cohort_report     cohort evaluation source-of-truth + aggregator
  db, schemas, uniprot_text          SQLite layer, Pydantic models, shared UniProt reader
scripts/           runnable entry points (see "Running" below)
tests/             pytest suite (run: `python -m pytest`)
paper/             ICML 2026 manuscript + figures
web/               live REST API + MCP service (FastAPI; reads a built DB)

---

Setup

conda create -n affinage -c conda-forge python=3.11 uv pip -y
conda activate affinage
uv pip install -e ".[dev]"
cp .env.example .env          # add ANTHROPIC_API_KEY (and NCBI_API_KEY for 10 req/s)

One-time data builds:

python scripts/build_gene_universe.py     # refresh HGNC cache (.cache/); data/genes.txt is the tracked ~20k seed list
python scripts/build_depmap_summary.py    # DepMap essentiality summary
python scripts/build_vocabularies.py      # controlled-vocabulary seed for Stage 2

The GPU evaluation stack (Prometheus-8x7b judge) is a separate environment — see scripts/setup_eval_env.sh and the [eval] extra in pyproject.toml.

Running

# Single gene (sync, full price) — for debugging
python scripts/annotate_gene.py TP53

# A batch of genes (Batch API, 50% cost)
python scripts/run_batch.py CDCA3 CKAP2L
python scripts/run_batch.py --file data/genes.txt

# Genome-wide (chunked, resumable orchestrator)
python scripts/run_genome_wide.py

# 100-gene cohort + ablations + evaluation (the paper pipeline)
python scripts/run_cohort_paper.py

# Deterministic audit (R1–R10) over a built DB
python scripts/detect_audit_flags.py --db results/affinage.db

# Prometheus evaluation (GPU; faithfulness + pairwise vs UniProt)
sbatch scripts/eval_prometheus_all.sbatch          # cohort
sbatch scripts/eval_prometheus_genome.sbatch       # genome pairwise (chunked/resumable)

# Web-service projection tables + paper figures
python scripts/build_web_projections.py --db results/affinage.db
python scripts/make_paper_figs.py

Outputs accumulate in a single SQLite database (results/affinage.db); per-gene prefetch is disk-cached under results/.prep/, so reruns reuse prior retrieval work.

Web service

web/ is a FastAPI app exposing a read-only HTML viewer, a JSON API, and ten MCP tools over a built database. It reads flat projection tables (gene_uniprot, gene_hgnc_alias, gene_omim) materialized from the pipeline DB by affinage.db.materialize_web_projections (run automatically at the end of a genome build, or via scripts/build_web_projections.py for cohort/ablation DBs).

AFFINAGE_DB_PATH=$PWD/results/affinage.db python -m affinage_web.server --http --port 8000

Figures

Paper figures are all regenerated by a single entry point, scripts/make_paper_figs.py (the pipeline schematic is the pipeline target; data-driven figures read CSVs from scripts/export_fig_data.py). The ICML 2026 manuscript source itself is kept out of the tracked tree.

Citation

Di Bernardo M, Cheeseman IM. Affinage: genome-scale mechanistic gene annotation from the published literature. arXiv:2607.02217 (2026). Accepted to the Workshop on Generative and Agentic AI for Biology at ICML 2026. https://arxiv.org/abs/2607.02217

@article{dibernardo2026affinage,
  title  = {Affinage: genome-scale mechanistic gene annotation from the published literature},
  author = {Di Bernardo, Matteo and Cheeseman, Iain M.},
  journal = {arXiv preprint arXiv:2607.02217},
  year   = {2026},
  doi    = {10.48550/arXiv.2607.02217},
  note   = {Accepted to the Workshop on Generative and Agentic AI for Biology at ICML 2026}
}

License

See LICENSE.