First steps

1. Configure secrets

cp .env.example .env

Edit .env. Keys are loaded automatically and must not be placed in YAML.

Variable	Needed for
OPENALEX_API_KEY and/or OPENALEX_EMAIL	Literature search
UNPAYWALL_EMAIL	Open-access PDF download
ANTHROPIC_API_KEY	Claude stages (if configured)
OPENAI_API_KEY	Ollama / OpenAI-compatible APIs

Full list: Environment variables.

2. Choose a config

configs/config.yaml is the shipped generic template. It uses the example extraction schema and prompt documented in Schemas & prompts:

• schemas/example/record.json
• prompts/example/prompt.md

The complete file is documented in Configuration.

export CONFIG=configs/config.yaml

Edit user_goal, filters, and extraction.schemas as needed. See Configuration.

3. Set the PDF converter device

conversion:
  engine: marker
  device: cpu       # cuda:0 on NVIDIA, mps on Apple Silicon

4. Create a run

export CONFIG=configs/config.yaml
litcurate run-stage query_generation --config $CONFIG

Copy the printed run id:

RUN_ID=<your_run_id>

Tip

List recent runs anytime with litcurate list-runs.

5. Continue stage by stage

Use the same RUN_ID for later stages. Full sequence: Running a pipeline.

litcurate run-stage openalex_search --run-id $RUN_ID
litcurate status $RUN_ID

Pass --config $CONFIG on LLM stages so provider settings apply.

6. Export

When extraction is done:

litcurate run-stage export --run-id $RUN_ID

Output:

runs/<RUN_ID>/artifacts/output/database.json