Skip to content

Quickstart

Install bibr from PyPI, configure your backends, and extract a first paper. The first run may download several GB of models.

1. Install

uv init --python 3.12 paper-extraction
cd paper-extraction
uv add bibr

On macOS and Linux, install the system libmagic library first (see Installation).

This installs core bibr, including the ONNX runtime for its trained models. The setup wizard offers any additional runtime extras your hardware needs; see Installation for prerequisites, the optional demo, and source installs.

2. Configure once

uv run bibr setup

The wizard detects your hardware, then shows a plan — OCR backend, LLM, extras, memory mode, privacy, and expected speed — for one confirmation. Decline it and the wizard offers to switch into bibr setup --advanced for exact provider/backend control instead. Two common outcomes:

  • Capable hardware (Apple Silicon, or an NVIDIA GPU with at least 5 GB of VRAM): the plan uses local OCR and a managed local LLM: bibr's fine-tuned Qwen3.5-4B, as its 4-bit W4A16 build on a Linux NVIDIA GPU with 10-19 GB of VRAM, except on a 10-11 GB card where setup finds a CUDA llama-server of build 11282 or newer and runs the GGUF build and GLM-OCR on it (see choosing an extraction model). On Apple Silicon, the OCR selector tries Paddle Rapid-MLX before Paddle MLX-VLM, with GLM startup fallbacks. On Windows and on NVIDIA GPUs below 10 GB, OCR (GLM-OCR) and the LLM run through llama.cpp, which you install separately; on Windows the plan gives the winget install llama.cpp command. The preview shows the requested backends, model, and memory mode. Crossref enrichment, a network service, stays off unless you enable it (--crossref or CROSSREF_ENRICH=true).
  • Weaker hardware: the wizard asks whether you have a private OCR/LLM server; if not, it offers cloud processing with Claude Haiku 5.5 (Anthropic) for both OCR and metadata, with a consent question that defaults to No (document content leaves your machine) and an Anthropic API key prompt. PDFs always need an OCR backend, even with --no-llm, so on such a machine they need that server or cloud, or a separately installed llama.cpp, which is slow on a CPU (see Installation). DOCX, JATS, HTML and ePub need no OCR.

It writes .env, saves a preset, and offers to install the extras the plan needs. Validation includes an optional connection/server check and a one-page smoke test on a bundled synthetic paper. That smoke test disables downstream LLM extraction and references; process your own paper next to check metadata.

The recommended local setup writes the Paddle-first automatic selector; cloud and private-server plans write their chosen backend instead:

OCR_BACKEND=paddle

It intentionally leaves OCR_MODEL and OCR_PROFILE unset so the selected Linux or Apple-Silicon candidate can retain its own model/profile. For an explicit external Paddle endpoint, use OCR_BACKEND=paddle-http with OCR_MODEL=paddle-ocr-vl-1.6 and OCR_PROFILE=paddle; custom aliases also require OCR_PROFILE.

Use --ocr paddle-vllm for explicit Paddle OCR on Linux/CUDA. Use --ocr glm-rapid-mlx (Apple Silicon), --ocr glm-llama, or --ocr glm-http when you deliberately want GLM-OCR. (The older glm-mlx backend is disabled: vllm-mlx produced corrupted OCR text.) On Linux the automatic selector only tries paddle-vllm on an NVIDIA GPU with at least 8 GB of VRAM; smaller GPUs and CPU-only machines go straight to llama.cpp (glm-llama), which needs llama-server on your PATH. The automatic paddle selector falls back only while starting an OCR runtime; it does not retry failed individual regions with GLM.

3. Chew a paper

uv run bibr chew paper.pdf -o paper.json

You get schema-versioned JSON (currently v12.3) with title, authors, affiliations, DOI, sections, sentences, tables, figure metadata, and parsed references. Add --figure-images to embed figure images.

-o also writes two files next to the result: paper.core.json, the core extraction before any enrichment (it matches paper.json when Crossref is off, the default), and paper.json.receipt.json, the run's status. With --crossref, paper.json.enrichment.json holds the enrichment as well.

An export that is not promotable goes to _quarantine/<disposition>/ beside the requested path instead. For example, a blocking validation error such as VAL_METADATA_MULTI_ITEM writes _quarantine/blocked/paper.json (and its paper.core.json). The receipt stays next to the requested path and records the "disposition", the console prints where the export went, and the command still exits 0.

The same command accepts DOCX, JATS XML (.xml), HTML (.html/.htm), and ePub files. These formats are parsed natively without OCR. PDF text layers also supply usable text directly; regions needing recognition still use the OCR backend. Point the command at a directory to process supported files in that directory:

uv run bibr chew papers/ -o out/

A directory, a glob or several inputs always write one out/<name>.json per paper, even when they hold a single paper; -o names a file only for one input file named directly.

Common variations

Goal Command
Keep metadata, skip references and their enrichment uv run bibr chew paper.pdf --refs off
Skip downstream LLM extraction and Crossref uv run bibr chew paper.pdf --no-llm
Parse reference fields with the configured LLM uv run bibr chew paper.pdf --refs llm
Try only the first three PDF pages uv run bibr chew paper.pdf --pages 1-3
Preview resolved settings without processing uv run bibr chew paper.pdf --dry-run
Write the references of out/ for a reference manager (.bib, .ris, or CSL-JSON .json) uv run bibr references out/ -o refs.bib
Check your setup uv run bibr doctor

--no-llm leaves the configured OCR route active, including cloud vision OCR if selected. For PDFs and DOCX it primarily produces document structure; structured metadata and references already parsed from native formats can still be retained. It is different from --refs off, which preserves normal metadata extraction.

Every flag is documented in the generated CLI reference.

Next steps