vaxtract

Schema-validated extraction of neoantigen cancer-vaccine immunogenicity data from primary papers. The default runtime is the Claude Agent SDK; --profile grok (and other OpenAI-compatible endpoints) is experimental. Point it at a folder of paper files (PDF / XLSX / DOCX) and it returns a schema-validated, provenance-tracked JSON extraction (per-peptide / per-epitope immunogenicity, HLA restriction, evidence, survival outcomes, …) for human sign-off.

Bring your own key (BYOK). You run the agent and pay for your own model usage (~$3/paper, varies). Your files never leave your machine unless you choose a hosted runner. There is no public upload service.

Output is silver, not gold. Every record carries provenance and is meant for a curator to review before use, not to be treated as ground truth.

This is the open-source extraction engine behind the NeoVax Atlas — a curated database of neoantigen cancer-vaccine trials. The agent's design and validation are described in the accompanying paper (see Citation).

Install

pip install vaxtract                    # core: the schema/vocab data contract only (pydantic)
pip install "vaxtract[agent]"           # + the extraction agent (Claude Agent SDK + readers)
pip install "vaxtract[agent,figures]"   # + figure/image reading (PyMuPDF + Pillow)
pip install "vaxtract[compat]"          # + OpenAI-compatible runtime (Grok / GPT / vLLM)

pip install vaxtract pulls only pydantic, so you can import vaxtract.schema to validate records without the Claude Agent SDK. Running the agent (the vaxtract console script or vaxtract.extract_paper) needs the [agent] extra.

Running the agent also requires Python ≥ 3.10 and the Claude Code CLI on your PATH (the Agent SDK shells out to the claude binary):

npm install -g @anthropic-ai/claude-code

(The Docker image below bundles this for you.)

Authenticate (pick one)

export ANTHROPIC_API_KEY=sk-ant-...     # A) API key — pay-per-token
# B) Claude subscription — pass --subscription to use a logged-in plan via the `claude` CLI

Run

vaxtract ./my_paper_dir out.json
vaxtract --subscription ./my_paper_dir out.json   # Claude plan quota
vaxtract --profile grok ./my_paper_dir out.json   # XAI_API_KEY; experimental

--subscription is Claude-only. Non-Claude profiles (grok, gpt, inkling, nemotron, qwen) are experimental — see docs/MODEL_AGNOSTIC_RUNTIME.md.

my_paper_dir is a folder containing the paper's .pdf and any supplementary .xlsx / .docx. The agent reads the tables/text/figures, builds the record, self-validates against the schema, and writes out.json.

As a library

import asyncio
from vaxtract import extract_paper
asyncio.run(extract_paper("./my_paper_dir", "out.json"))

The data contract is importable without the SDK:

from vaxtract.schema import ExtractedPaper, SCHEMA_VERSION

Run with Docker

Multi-arch images on GHCR. latest includes the Claude CLI; compat is the slim Grok/GPT image (no Node).

docker pull ghcr.io/mskgreenbaumlab/vaxtract:latest
docker run --rm -e ANTHROPIC_API_KEY \
    -v "$PWD/my_paper_dir:/work/my_paper_dir" \
    ghcr.io/mskgreenbaumlab/vaxtract:latest \
    /work/my_paper_dir /work/my_paper_dir/out.json

docker pull ghcr.io/mskgreenbaumlab/vaxtract:compat
docker run --rm -e XAI_API_KEY \
    -v "$PWD/my_paper_dir:/work/my_paper_dir" \
    ghcr.io/mskgreenbaumlab/vaxtract:compat \
    --profile grok /work/my_paper_dir /work/my_paper_dir/out.json

What it extracts

Per paper: studies, patients, immunizing peptides, minimal epitopes, pools, immunogenicity evidence (assay / outcome / magnitude), neoantigen mutations, survival outcomes, clinical-benefit signals, safety, and vaccine-delivery covariates — all validated against a versioned Pydantic schema (SCHEMA_VERSION).

How it works

The model is given tools and a loop: it reads tables/text/figures itself, drafts candidate JSON, calls validate(), reads the schema's errors, and fixes its own output until the record passes or an outer guard quarantines it for review. Pure logic (agent_core.py, prompt_render.py) is SDK-free and unit-tested; the SDK shell wraps it as in-process tools.

flowchart LR
    A["Paper dir<br/>PDF · XLSX · DOCX · figures"] --> B[Read sources]
    B --> C[Draft / amend record]
    C --> D{"validate()"}
    D -- errors --> C
    D -- passes --> E["finalize:<br/>faithfulness guards"]
    E -- clean --> F[("Schema-valid JSON")]
    E -- flagged --> G[["needs_review"]]

See docs/ARCHITECTURE.md for the full design.

Reproducibility

The agent calls a proprietary, versioned, non-deterministic model, and the validation corpus is copyright-restricted — so the gold reference_records/ (audited extractions) are the reproducibility anchor, not byte-identical re-runs. See REPRODUCIBILITY.md.

Repository layout

Citation

If you use vaxtract, please cite it — see CITATION.cff (a DOI is minted on release via Zenodo). A .bib entry will be added with the published paper.

License

MIT © 2026 Samuel Ahuno