bibr 🦫 tester guide

This guide is for colleagues testing bibr on their own computer. The recommended first test is deliberately conservative: launch the local demo, prove the pipeline with a short PDF, then add fully local inference once that works.

bibr is experimental. It works, but parts of the pipeline are still being validated. Review the extracted JSON against the source paper and report missing or incorrect fields; a completed run is not an accuracy guarantee.

Hit a bug or something confusing? Please open an issue or email me directly at jakub@jakubwerner.com.

Which setup should I use?

Setup	Best for	What runs on the laptop?
Windows hybrid (recommended first)	A Windows laptop with a 6 GB NVIDIA GPU	Local OCR and reference ML; a cloud LLM handles metadata
Windows fully local	Local inference after the hybrid test passes	Quantized OCR and LLM models, loaded one at a time; keep Crossref off (the default) for offline runs after model downloads
try.bibr.org	Trying one paper, with no installation	Only the browser; upload the paper to the hosted demo
Shared demo link	The quickest evaluation, with no installation	Only the browser; whoever runs bibr demo --share (see Gradio demo) processes the paper

Status of the 6 GB Windows path

bibr now has a native Windows path; WSL2 is not required. On Windows it uses llama.cpp for GLM-OCR and, optionally, the local LLM. For a 6 GB GPU, setup selects:

• GLM-OCR Q8 (about 950 MB downloaded) for glm-llama;
• the bibr extract 4B Q4_K_M GGUF (about 2.6 GB, which bibr downloads into the Hugging Face cache at the revision it pins) for a fully local LLM; and
• aggressive memory mode, which unloads one model before loading the next.

The code and automated tests explicitly cover the 6 GB selection, but this is a new hardware path and has not yet been field-tested on every laptop/driver combination. Start with local OCR + a cloud LLM. If fully local inference is slow or runs out of memory, that hybrid setup is still a good local installation; ask the person running the test for a demo link only if installation itself is the problem.

Allow roughly 15 GB of free disk space for Python packages, model downloads, and caches. A current NVIDIA driver and at least 16 GB of system RAM are recommended.

Windows: RTX A1000 6 GB setup

Use a normal 64-bit PowerShell terminal. Administrator rights may be requested by winget, but bibr itself does not need to run as Administrator.

1. Install the tools

Install Git if it is not already present:

winget install --id Git.Git -e

Install uv:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Now install the native llama.cpp runtime. For an NVIDIA GPU, use a CUDA build from the llama.cpp releases. bibr doctor and server startup checks warn when they detect a Vulkan build running on NVIDIA hardware.

1. From the llama.cpp releases page, download both llama-<ver>-bin-win-cuda-12.4-x64.zip and cudart-llama-bin-win-cuda-12.4-x64.zip (<ver> is the release tag).
2. Extract both zips into the same folder.
3. Add that folder to PATH — ahead of any winget-installed llama.cpp location if one exists (for example from an earlier revision of this guide), so that llama-server resolves to the CUDA build.

GTX 10-series (Pascal) cards must use the cuda-12.4 zips above — the cuda-13.x builds dropped support for that generation.

Alternatively, install the package distributed through winget, which is the command bibr setup's plan gives. It installs the Vulkan build, which works on NVIDIA but is slower than a CUDA build:

winget install llama.cpp

Update the NVIDIA driver through NVIDIA or the laptop manufacturer, then close and reopen PowerShell so the updated PATH takes effect. Check that the GPU and llama.cpp are visible:

nvidia-smi
Get-Command llama-server
llama-server --version

If Get-Command fails after reopening PowerShell, double-check that the folder containing llama-server.exe — the one you extracted the CUDA zips into, or the winget install location — was actually added to PATH. If the command works but resolves to a leftover winget (Vulkan) install, move the CUDA folder ahead of it in PATH, then re-run llama-server --version and uv run bibr doctor — the Vulkan-build warning should disappear.

2. Get bibr and install its dependencies

Clone the source repository (it is public; no GitHub account is needed):

git clone https://github.com/scienceverse/bibr.git
cd bibr

Install bibr's local-ML and demo dependencies. --extra all includes the hardware-independent extras; serving runtimes are separate. The current extras can be resolved together, but Windows does not need the Linux vLLM runtime.

uv sync --extra all

The optional ONNX GPU package can accelerate sentence splitting. It is not needed for the first run, and leaving that small stage on the CPU gives the OCR model more VRAM. Add it later with:

uv sync --extra all --extra gpu
uv pip install --reinstall-package onnxruntime-gpu "onnxruntime-gpu[cuda,cudnn]==1.26.0"

uv sync also installs the CPU onnxruntime package, and the two write the same onnxruntime folder, so either can end up loaded. The second command writes the GPU package's files last. Keep --extra gpu on every later uv sync; see GPU ONNX Runtime.

3. Configure the recommended hybrid setup

Run the wizard from the repository directory:

uv run bibr setup --advanced

For the first test:

1. Choose a cloud LLM provider, such as Anthropic (the default, with Claude Haiku 5.5), and enter its API key. This sends document text to that provider for metadata extraction.
2. Choose glm-llama for OCR on this Windows machine. Setup pins aggressive memory mode on a 6 GB GPU. Keep the default NER reference parser. Enter a Crossref email if desired; Crossref enrichment is a separate network service.
3. When the wizard offers to install extras, accept — uv sync --extra all already installed the relevant ones, and the install step uses --inexact, so accepting again won't remove anything.
4. Accept the offered smoke test on a bundled synthetic paper. It uses one page with LLM extraction and references disabled, so the complete test below is still needed to validate the cloud LLM.

The shorter uv run bibr setup flow recommends a complete configuration, which can be fully local on a 6 GB GPU. Use it when you want the automatic recommendation; the advanced steps above deliberately select the hybrid test.

The wizard writes .env in the current directory (merging with any existing one by default). Keep running the commands below from that directory. Check the resolved environment before processing a paper:

uv run bibr doctor
uv run bibr chew --dry-run .\paper.pdf

4. Open the local demo first

The easiest first run is the drag-and-drop Gradio demo:

uv run bibr demo

Upload a small paper and confirm that extraction starts. The demo uses the .env settings written by bibr setup, including PIPELINE_MEMORY_MODE and LLM_BACKEND. Stop the demo with Ctrl+C when you are done.

5. Run a command-line smoke test

Start with three pages and force the low-memory settings:

uv run bibr chew .\paper.pdf --pages 1-3 --ocr glm-llama --memory aggressive -o .\result.json -v

The first run downloads model files and will be much slower than later runs. While it is running, nvidia-smi should show llama-server.exe using the GPU. If the three-page test succeeds, process the complete paper:

uv run bibr chew .\paper.pdf --ocr glm-llama --memory aggressive -o .\result.json

6. Try fully local inference (optional)

Run setup again. If the plan preview already recommends a fully local setup for this GPU, accept it. Otherwise decline and continue into the advanced flow (or run bibr setup --advanced directly) to pick the local LLM explicitly — on this GPU it should select the llama-cpp backend and scienceverse/bibr-extract-qwen35-4b-GGUF:Q4_K_M model. Keep glm-llama for OCR. When asked about the existing .env, keep the default (merge) so earlier settings like the Crossref email carry over.

uv run bibr setup
uv run bibr doctor
uv run bibr chew .\paper.pdf --pages 1-3 --ocr glm-llama --llm local --memory aggressive -o .\result-local.json -v

OCR and the LLM run in separate llama.cpp processes and are not intended to occupy VRAM simultaneously. Close other GPU-heavy applications while testing. If this path fails or is uncomfortably slow, return to the hybrid setup; OCR and default reference parsing remain local. Crossref is off by default; if you enabled it, pass --no-crossref for a run without Crossref requests.

Other platforms

Install uv and the system prerequisites, then clone and install:

git clone https://github.com/scienceverse/bibr.git
cd bibr
uv sync --extra all
uv run bibr setup
uv run bibr doctor
uv run bibr demo

Linux, NVIDIA GPU below 10 GB (e.g. GTX 1060, RTX 4060)

Below 10 GB, bibr setup uses llama.cpp for OCR and the local LLM. From 10 GB, on Ampere or newer cards, both run through vLLM, with the 4-bit W4A16 build of bibr's fine-tuned 4B model below 20 GB and its bf16 build from 20 GB. On a 10–11 GB card, setup uses llama.cpp instead when it finds a CUDA build of llama-server of build 11282 or newer on your PATH, and says so; bibr setup --advanced still offers W4A16. Install a CUDA (or Vulkan) build of llama.cpp separately:

1. Install or build llama.cpp with CUDA support (GGML_CUDA=ON for a source build) and put llama-server on your PATH. Check the upstream build instructions for your GPU and operating system.
2. Install bibr with the compatible superset only:

uv sync --extra all
# No additional Python serving extra is needed for llama.cpp.

1. Run setup and accept its recommended local plan (GLM-OCR and the 4B GGUF build, both on llama.cpp, in the aggressive memory mode), then check the resolved configuration. Accept the extras-install offer if dependencies are missing; setup installs with --inexact to retain other installed extras. To use a cloud LLM instead, choose it in bibr setup --advanced and keep glm-llama for OCR.

uv run bibr setup
uv run bibr doctor
uv run bibr chew paper.pdf --pages 1-3 -v

About “CUDA problems” on older cards (Pascal / GTX 10-series): current PyTorch wheels no longer ship kernels for compute capability 6.x. Layout and NER then run on CPU automatically — that is expected and not fatal. GPU work for OCR/LLM goes through llama.cpp. Do not try to “fix” this by installing a different PyTorch inside the venv or enabling the gpu extra.

Cards older than Ampere (Turing, e.g. RTX 20-series, GTX 16-series; Volta; Pascal), at any memory size: bibr's vLLM models are bf16, which vLLM serves only from compute capability 8.0, so bibr setup and --llm local run the LLM and the OCR on llama.cpp there, as on a small card. This is a conservative routing rule, not a measured result: no batch on a Turing or Pascal card has been recorded, with this rule or with the vLLM routing before it. (The Pascal notes above are given with no measured run recorded.) An explicit --llm vllm or --ocr paddle-vllm still starts vLLM. Going by vLLM's source (0.31 and 0.32), it then casts the bf16 models to float16, and its 4-bit kernels (the W4A16 build) need compute capability 7.5, which rules out Pascal; none of this has been run.

While a job runs, nvidia-smi should show llama-server using the GPU. If doctor warns that llama.cpp is CPU-only, replace the binary with a CUDA build.

Optional overrides (already the managed defaults for low-VRAM) live in .env:

# Only needed if you want to change the defaults:
# LLM_LLAMA_CPP_EXTRA_ARGS=--flash-attn on --cache-type-k q8_0 --cache-type-v q8_0
# OCR_LLAMA_CPP_EXTRA_ARGS=--flash-attn on --cache-type-k q8_0 --cache-type-v q8_0

Which backend, and how fast

bibr setup writes a model and runtime to .env; --llm local without setup resolves the same model, runtime, memory mode and OCR from the platform and the detected card (a test checks that the two agree on every row). The one exception is a 10–11 GB card where setup found a qualifying llama.cpp server: setup looks on PATH, the runtime never does. The current defaults are:

Platform	OCR backend	Local LLM backend
Windows	glm-llama (llama.cpp)	llama.cpp
Linux, NVIDIA GPU ≥ 20 GB (e.g. RTX 3090)	paddle-vllm	vLLM, bibr extract 4B
Linux, NVIDIA GPU 10–<20 GB	paddle-vllm	vLLM, bibr extract 4B W4A16 (aggressive memory mode below 12 GB)
Linux, NVIDIA GPU 10–<12 GB, bibr setup with a CUDA llama-server of build 11282 or newer on PATH	glm-llama (llama.cpp)	llama.cpp, bibr extract 4B GGUF Q8_0 (aggressive memory mode); run plain bibr chew, since --llm local keeps vLLM, which cannot serve this GGUF build
Linux, NVIDIA GPU < 10 GB	glm-llama (llama.cpp)	llama.cpp, bibr extract 4B GGUF (Q8_0 from 7 GB, Q4_K_M below)
Linux, NVIDIA GPU older than Ampere (compute capability below 8.0), any size	glm-llama (llama.cpp)	llama.cpp, bibr extract 4B GGUF (untested on such cards)
Apple Silicon (M-series)	paddle-rapid-mlx (rapid-mlx)	rapid-mlx, else vllm-mlx
No suitable GPU	cloud vision OCR or an external OCR server	a cloud LLM

The setup wizard defaults to bibr's fine-tuned Qwen3.5 models for local structured extraction on Linux with an NVIDIA GPU: the 4B from 20 GB and its 4-bit W4A16 build from 10 GB. Windows, GPUs below 10 GB and GPUs older than Ampere use GGUF (llama.cpp) builds of the same models, and Apple Silicon their 8-bit MLX builds. Without a suitable GPU it recommends Claude Haiku 5.5 as a hosted model, for OCR and extraction alike. See choosing an extraction model. Of the card sizes that pick a default, 20, 12, 10, 8 and 6 GB were each run as a batch on one RTX 3090 with its memory cut to that size beside a desktop; 7 and 5 GB follow the size rule. They are not guarantees that every document fits available memory, and that page's speeds are the RTX 3090's, not those of the cards it emulated.

Throughput depends on the model, backend, hardware, and document. Scanned PDFs require more OCR than PDFs with usable embedded text. Test a representative sample before starting a large batch, and inspect both metadata and references.

If fully local inference does not run, or is too slow, walk down this ladder:

1. try the llama.cpp build (--ocr glm-llama, and --llm local on Windows or a GPU below 10 GB already selects llama.cpp; on a 10–11 GB card where bibr setup picked llama.cpp, run plain bibr chew or --llm llama-cpp);
2. set an API key for a cloud LLM (Anthropic, Google, OpenAI, …) and keep OCR local — inexpensive and reliable; or
3. self-host an open-source LLM on a GPU box and point bibr at it — OSS models run much better on a real GPU than on a laptop.

Using bibr

Process one PDF, DOCX, JATS XML, HTML, or ePub paper, or a directory of supported files. Native non-PDF formats bypass rendering, layout detection, and OCR:

uv run bibr chew paper.pdf -o result.json
uv run bibr chew papers/ -o results/

Useful options include:

• --pages 1-5 to make a quick, bounded test;
• --refs ner (default) parses references locally with no per-reference LLM cost. Segmentation defaults to geom, with region/LLM/CRF fallbacks;
• --refs llm parses reference fields with the configured LLM. --ref-seg selects segmentation independently; --refs llm-chunked is experimental;
• --refs off skips references and their Crossref enrichment while retaining title, authors, and other metadata extraction;
• --no-equations and --no-crossref disable those stages;
• --no-llm skips downstream LLM extraction and Crossref. OCR still uses the selected backend, and already structured native metadata may remain;
• --ocr paddle-http --ocr-url https://ocr.example.org uses an external Paddle OCR server; use --ocr glm-http for a GLM endpoint;
• --regions includes OCR/native-source diagnostics for inspecting a mismatch;
• --figure-images includes embedded figure images; and
• --memory aggressive for low-memory machines.

The Python API is available inside the same project environment:

import bibr

result = bibr.chew("paper.pdf")
result.title
result.references.df
result.save("result.json")

In Jupyter, use await bibr.achew(...) instead.

To load the references into a reference manager, uv run bibr references results/ -o refs.bib writes those of every export in results/ to one BibTeX file; a .ris name writes RIS and a .json name CSL-JSON. In Python, result.to_bibtex(), result.to_ris() and result.to_csl_json() return the same lists.

Gradio demo

Launch a local drag-and-drop interface with:

uv run bibr demo

The demo uses PIPELINE_MEMORY_MODE and LLM_BACKEND from the .env created by bibr setup; pass --memory aggressive or --llm llama-cpp only when you want to override that setup for this run.

Two more settings control what the demo keeps. They are process environment variables, not .env keys: set them in the shell that starts the demo, as with GRADIO_PASSWORD below. In PowerShell, for example: $env:DEMO_CACHE_TTL_SECONDS="1800".

• DEMO_MAX_FILE_SIZE_MB (default 10) limits uploads. A larger upload is refused while it arrives. A value that is not a positive whole number stops the demo at start.
• DEMO_CACHE_TTL_SECONDS (default 3600) is how long uploaded papers and JSON downloads are kept. Gradio looks for old files every five minutes, so a file is deleted at most five minutes after it reaches that age. All of them are deleted when the demo stops. 0 keeps them. Any other value that is not a whole number of seconds stops the demo at start.

While the demo deletes its files, it leaves the OCR disk cache off unless you set CACHE_OCR yourself. With DEMO_CACHE_TTL_SECONDS=0 it turns that cache on, so a paper you run again skips OCR. The cache keeps each paper's OCR text, with no expiry, in CACHE_OCR_DIR (default $XDG_CACHE_HOME/bibr/ocr, or ~/.cache/bibr/ocr when XDG_CACHE_HOME is unset). On a demo other people upload to, keep the cleanup on and do not turn CACHE_OCR on, in the shell or in .env.

For a remote demo, run it on the host that has bibr configured. Protect it with a username and a strong password before creating a temporary public share link. In PowerShell:

$env:GRADIO_USERNAME="supervisor"
$env:GRADIO_PASSWORD="replace-with-a-long-random-password"
uv run bibr demo --share --memory aggressive

Without GRADIO_PASSWORD, bibr demo refuses to start with --share or a --host other than a loopback address: anyone who reaches an open demo can process papers on your LLM quota and, with --presets, switch the configuration for everyone. Pass --allow-unauthenticated only for a network you trust.

Send the printed HTTPS link and password separately. The host downloads the models and processes uploaded papers; the supervisor only needs a browser. Treat a Gradio share link as a temporary evaluation endpoint, stop it after the session, and do not use it for confidential papers unless the hosting and data handling arrangements have been approved.

Gradio deletes the files but not the folders they were in: an empty folder for each JSON download, and one named after a hash of each uploaded paper. Its cleanup also runs as one background task that stops for good after an error. For a hosted demo on Linux, give the demo a temp folder of its own with GRADIO_TEMP_DIR and sweep it from cron as well, with an age above DEMO_CACHE_TTL_SECONDS. For the default hour, every 15 minutes:

# Before starting the demo:
export GRADIO_TEMP_DIR=/srv/bibr-demo/tmp
# crontab entry (one line):
*/15 * * * * find /srv/bibr-demo/tmp -mindepth 1 -type f -mmin +75 -delete; find /srv/bibr-demo/tmp -mindepth 1 -type d -empty -mmin +5 -delete

Updating

From the cloned repository:

git pull
uv sync --extra all   # add the hardware extras you installed, see below
uv run bibr doctor

The .env file is not touched by an update. Repeat any hardware extras you installed in the uv sync line. On Linux, bibr setup's recommended plan for an NVIDIA card installs gpu on Ampere or newer cards and vllm on cards that run vLLM, so keep both: uv sync --extra all --extra gpu --extra vllm, without any the plan did not install. A sync without --extra gpu removes onnxruntime-gpu and the files it shares with onnxruntime, and import onnxruntime then fails. With --extra gpu, run the onnxruntime-gpu reinstall from GPU ONNX Runtime again afterwards.

Reporting issues

Found a bug, or something that looks wrong? Please open an issue or email me directly at jakub@jakubwerner.com. Pick "Wrong extraction" when bibr ran but a field is missing or wrong, and "Crash or install problem" when it failed. Issues are public, so only attach papers that may be shared. To help me reproduce it, include:

1. The exact command and full error output.
2. uv run bibr doctor and uv run bibr --version output.
3. nvidia-smi output for GPU problems.
4. The input document, if it can be shared.
5. Whether the three-page hybrid test and fully local test succeeded.

Integration with Metacheck

Metacheck is the R package bibr feeds into. Follow its installation and usage guide for the current package version and use a version supporting bibr's exported schema. Compatibility depends on both projects' versions.

bibr writes export schema 12.x, whose paper fields live under metadata (schemas before 11.0 used info). Check that your Metacheck version reads schema 12 before relying on this step; a reader written for the older layout finds no title, abstract or DOI.

Extract a paper with bibr, then read the JSON in R:

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

paper <- metacheck::read("paper.json")

Use the report reference for report formats and output options supported by your installed version.

Uninstalling

Delete the cloned bibr directory. Model caches are stored separately by Hugging Face (including the bibr extract GGUF builds, which bibr downloads itself) and llama.cpp, and can be removed independently if no other local-model tools use them.