Install and configure

This page gets you from a clean Python environment to a working CLI in under 10 minutes. After this you can run the first-paper walkthrough.

Prerequisites

Python 3.10 or later. Check with python3 --version.
A pip-installable repository. This guide uses the haak-side source at home/collabs/elife/claim-trees/extract/. The package is also intended for publication to the eLife corpus repo as a sibling to the existing scripts/ and verification/ directories.
One of: Vertex AI access OR direct Anthropic API access. This pipeline runs Anthropic’s Claude models. Vertex is the canonical configuration; direct API works as a fallback.
A few hundred dollars of API budget if you plan to run multiple papers. ~$7 per paper with the external reviewer enabled.

Install the package

git clone <repo-url-when-published>
cd elife-claim-trees/extract     # or home/collabs/elife/claim-trees/extract in the haak repo
pip install -e .

This installs the elife-extract console script along with its dependencies: anthropic[vertex], httpx, pdfplumber, pyyaml, pydantic. All transitively pulled.

Verify the install:

elife-extract --version
elife-extract --help

You should see the version string and the five subcommands listed: extract, write, verify-refs, run, evaluate.

Configure Vertex AI credentials (recommended)

The CLI defaults to Vertex AI as the model backend — the canonical HAAK configuration on cr-mainen / europe-west1. To use your own GCP project:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your-service-account.json
export VERTEX_PROJECT_ID=your-gcp-project-id
export VERTEX_REGION=us-central1   # or wherever Anthropic models are enabled

Anthropic’s models on Vertex must be enabled in your GCP project’s Anthropic Model Garden subscription for the regions you target. The models the CLI uses by default:

claude-sonnet-4-6 — for the three extraction agents
claude-opus-4-6 — for reconciliation and external review

If you see 404 Publisher Model not found errors, the model isn’t enabled in your project/region. Enable it via the Vertex AI console, or override via --vertex-region us-east5 (or wherever it is).

If you don’t set GOOGLE_APPLICATION_CREDENTIALS, the SDK falls back to Application Default Credentials (ADC). Run gcloud auth application-default login to set those up.

Configure direct Anthropic API (alternative)

If you’d rather hit Anthropic directly:

export ANTHROPIC_API_KEY=sk-ant-...
unset CLAUDE_CODE_USE_VERTEX

The Anthropic Python SDK auto-routes to direct API when ANTHROPIC_API_KEY is set and Vertex env vars aren’t. Costs are the same; latency may be different depending on your geography.

Environment variable contract

The CLI reads configuration in this priority order: CLI args → environment variables → defaults. The full contract:

Variable	CLI flag	Required?	Purpose
`ELIFE_CORPUS_DIR`	`--corpus-dir`	yes (for `write`, `run`, `verify-refs`)	Where claim files are read/written
`VERTEX_PROJECT_ID`	`--vertex-project`	uses default	GCP project for Vertex AI Claude (default: `cr-mainen`)
`VERTEX_REGION`	`--vertex-region`	uses default	Vertex region (default: `europe-west1`)
`GOOGLE_APPLICATION_CREDENTIALS`	n/a	yes (for Vertex)	Service account JSON for Vertex auth
`ANTHROPIC_API_KEY`	n/a	yes (for direct API)	Direct Anthropic SDK auth
`ELIFE_EXTRACT_MODEL_RESULTS`	`--model-results`	optional	Override Results-reader model (default: `claude-sonnet-4-6`)
`ELIFE_EXTRACT_MODEL_CAPTION`	`--model-caption`	optional	Override Caption-reader model
`ELIFE_EXTRACT_MODEL_STRUCTURE`	`--model-structure`	optional	Override Structure-reader model
`ELIFE_EXTRACT_MODEL_RECONCILE`	`--model-reconcile`	optional	Override reconciliation + reviewer model (default: `claude-opus-4-6`)
`ELIFE_EXTRACT_OUTPUT`	`--output-dir`	optional	Where draft tables and intermediates land (default: `./out`)

CLI args win when both are set. Set the env vars in your shell profile for convenience; pass --corpus-dir etc. on the command line for one-offs.

Verify with a smoke test

Once installed and configured, the simplest verification is to run extract on a test paper and check it produces a draft:

mkdir -p /tmp/elife-smoke-test/{out,corpus}
elife-extract extract \
  --doi 10.7554/eLife.95562 \
  --corpus-dir /tmp/elife-smoke-test/corpus \
  --output-dir /tmp/elife-smoke-test/out

Expect ~5 minutes wall time, ~$5 in API. If this prints a step-by-step extraction trace and ends with “draft saved” and a JSON file at /tmp/elife-smoke-test/out/draft-headley-2024-spatially-targeted-inhibitory.json, your installation works.

If it fails:

Symptom	Likely cause	Fix
`404 Publisher Model not found`	Anthropic model not enabled in your Vertex region	Enable in GCP console or change `--vertex-region`
`Errno 8 nodename nor servname`	DNS / network failure	Check connectivity to `cdn.elifesciences.org` and `*-aiplatform.googleapis.com`
`corpus_dir not set` error	Missing required arg/env	Set `--corpus-dir` or `ELIFE_CORPUS_DIR`
`pdfplumber import error`	Dependency missing	`pip install -e .` again; check no stale env

What’s next

First paper walkthrough — concrete steps from DOI to corpus
The five subcommands — extract, write, verify-refs, run, evaluate
Configuration reference — every env var and CLI flag in detail