Settings reference

Configuration loads ~/.bibr/.env, then the working directory's .env; environment variables override both. BIBR_ENV_FILE replaces this file chain (use : between paths on Unix, ; on Windows, or an empty value to disable dotenv loading). Per-run options can override these defaults. Sections are namespaced by prefix; there is no global BIBR_ prefix. The tables below show shipped defaults, not the build machine's settings. Use bibr config show --sources to see the live values and where each one comes from, and bibr config path to locate your .env file. See the configuration guide for presets and examples.

LLM (LLM_*)

Variable	Type	Default	Description
LLM_PROVIDER	enum	"google"	LLM provider: "google" (default), "openai", "anthropic", "groq", or "ollama". Custom adapters added through bibr.clients.providers.register cannot be named here; set them on the settings object in code instead.
LLM_MODEL	str	"gemini-3.5-flash-lite"	Model name for the selected provider. Unset, it follows LLM_PROVIDER: google uses gemini-3.5-flash-lite, openai uses gpt-5-nano, anthropic uses claude-haiku-5-5, groq uses llama-3.3-70b-versatile, ollama uses gpt-oss:20b. An openai provider with LLM_BASE_URL keeps this default, so name the served model there.
LLM_MODEL_REVISION	str | None	None	Exact model revision/commit deployed (surfaced in qualification_provenance; null falls back to the expected revision only when LLM_MODEL is numind/NuExtract3-FP8).
LLM_JINJA_SHA256	str | None	None	sha256 of the deployed chat template (surfaced in qualification_provenance; null falls back to the expected template sha only when LLM_MODEL is numind/NuExtract3-FP8).
LLM_API_KEY	str | None	None	Generic API key, used by the openai provider and OpenAI-compatible endpoints. Google/Anthropic/Groq use their provider-specific keys.
LLM_BASE_URL	str | None	None	Base URL override for custom OpenAI-compatible endpoints.
LLM_ALLOW_INSECURE_HTTP	bool	False	Send the LLM API key over plain http:// to a public LLM_BASE_URL or OCR_VISION_BASE_URL host. Loopback and private-network hosts (RFC 1918 or tailnet addresses, single-label names, .local/.internal/.lan/.ts.net) never need it; public hosts default to HTTPS-only.
LLM_CHAT_TEMPLATE_KWARGS	dict	{}	Chat-template options for custom OpenAI-compatible endpoints, e.g. LLM_CHAT_TEMPLATE_KWARGS='{"enable_thinking": false}'. Ignored for real OpenAI.
LLM_OLLAMA_BASE_URL	str	"http://localhost:11434"	Ollama server URL (LLM_PROVIDER=ollama).
LLM_REASONING_EFFORT	str | None	"minimal"	Reasoning effort for reasoning models (minimal/low/medium/high; null disables the parameter for models that reject it).
LLM_REASONING_EFFORT_AUTHORS	str | None	"low"	Per-call reasoning effort override for the authors extraction call (benefits from more reasoning due to spatial/cross-reference logic).
LLM_REASONING_EFFORT_CITATIONS	str | None	"low"	Per-call reasoning effort override for the citation-linking call (benefits from more reasoning due to spatial/cross-reference logic).
LLM_RATE_LIMIT_RPM	int	60	LLM rate limit in requests per minute. Guards a cloud provider's quota, so it is auto-lowered to 10 for the ollama provider and auto-raised to 600 for a managed local server or an LLM_BASE_URL on loopback, a private network or a tailnet (which have no external quota) — all unless set explicitly.
LLM_MAX_CONCURRENCY	int	0	Max in-flight LLM requests (0 = unlimited). Set 1 to serialize against a local single-device server; cloud providers are fine at the default.
LLM_TEMPERATURE	float	0.0	Sampling temperature for OpenAI-compatible LLM responses.
LLM_MAX_TOKENS	int	65536	Max completion tokens for LLM responses.
LLM_TITLE_MAX_TOKENS	int | None	4096	Max completion tokens for title/abstract/keywords extraction; 0 disables the task cap.
LLM_AUTHORS_MAX_TOKENS	int | None	8192	Max completion tokens for author extraction; 0 disables the task cap.
LLM_PAPER_CLASSIFICATION_MAX_TOKENS	int | None	1024	Max completion tokens for broad paper classification; 0 disables the task cap.
LLM_PAPER_TYPE_MAX_TOKENS	int | None	512	Max completion tokens for narrow paper-type labeling; 0 disables the task cap.
LLM_SECTION_MAX_TOKENS	int | None	4096	Max completion tokens for section classification/detection; 0 disables the task cap.
LLM_INTEGRITY_MAX_TOKENS	int | None	4096	Max completion tokens for research-integrity extraction; 0 disables the task cap.
LLM_EQUATION_MAX_TOKENS	int | None	4096	Max completion tokens for equation extraction; 0 disables the task cap.
LLM_CITATION_MAX_TOKENS	int | None	8192	Max completion tokens for citation resolution; 0 disables the task cap.
LLM_MAX_INPUT_CHARS	int	300000	Max input characters sent to the LLM.
LLM_CONTEXT_TOKENS	int | None	None	The LLM server's context window in tokens. When set, long inputs are cut so prompt plus completion fits it, and an Ollama or llama.cpp server gets input and completion caps sized to it. bibr fills it in for the servers it starts and asks an Ollama or llama.cpp server for it. Otherwise it learns it from a context-length rejection, or from the server's /v1/models listing when an answer stops at the window.
LLM_REF_SEG_WINDOW_CHARS	int	16000	Max input characters per LLM reference-segmentation window (~50 refs/window).
LLM_CLASSIFICATION_MAX_CHARS	int	20000	Max input characters sent to the LLM section-classification call.
LLM_CORE_CUTOFF_MAX_SENTENCES	int	250	Upper bound (in sentences) on the core-metadata front-matter slice. Caps late cutoffs caused by misclassified early section headers; also the fallback slice when no IMRaD header is found. 0 disables the cap (fallback then stays 250).
LLM_PER_TASK_CONTEXT	bool	True	Send task-specific context slices to the core-metadata LLM calls: page-1 + ORCID/correspondence rows to the authors call and front matter through the end of the abstract to the classification call, instead of the full front-matter blob. The title/keywords call always receives the full blob.
LLM_MERGED_CORE_METADATA	bool	False	Experimental: merge title/abstract/keywords + authors + classification into one LLM call instead of three, saving repeated front-matter tokens. Off until quality-gated.
LLM_POINTER_OUTPUTS	bool	False	Experimental: the title/keywords call names the abstract's first and last words and bibr copies the abstract from the front matter, and the authors call lists each affiliation once and numbers it. Cuts the output tokens the slower of the two calls writes by about a third. Falls back to the verbatim call when the abstract cannot be placed. Not used by the merged call or the NuExtract native backend. Off until quality-gated.
LLM_VALIDATION_ATTEMPTS	int | None	None	Instructor schema-validation attempts. None auto-selects 1 for deterministic custom OpenAI-compatible endpoints and 3 for cloud providers.
LLM_TIMEOUT_SECONDS	int	30	Per-request LLM timeout in seconds.
LLM_TRACK_USAGE	bool	True	Track LLM token usage.
LLM_CAPTURE_TRACE	bool	False	Opt-in: capture each LLM call's rendered prompt and raw response into extraction.trace (see LlmTraceExport). Off by default — a default-config export has no trace key. Prompts/completions are scrubbed of credential-shaped tokens before capture; callers choose storage and retention for trace-bearing exports. Captures Instructor backend calls only — the NuExtract-native structured backend is not yet instrumented, so enabling this on a nuextract-native deployment (a common local/self-hosted setup) silently produces no trace rows; a warning is logged in that case.
LLM_THINKING_BUDGET	int	0	Thinking budget for extended-thinking models (0 = disabled).
LLM_BACKEND	enum	"cloud"	Default LLM backend for chew when --llm is not passed: "cloud" or a managed local server ("local", "vllm", "vllm-mlx", "rapid-mlx", "llama-cpp", "llmster"). Written by bibr setup.
LLM_LOCAL_MODEL	str | None	None	Model id served by the managed local LLM backends. Unset picks the build bibr setup would write for the selected backend and the detected memory (the NVIDIA card's, or system RAM on Apple Silicon; the tier table in docs/guides/extraction-models.md): bibr's fine-tuned Qwen3.5-4B (scienceverse/bibr-extract-qwen35-4b) as bf16 on vLLM from 20 GB and its W4A16 build below; on llama.cpp its GGUF Q8_0 build from 7 GB and Q4_K_M below; on Apple Silicon its 8-bit MLX build. The 2B student only when a 2B build fits and no 4B build does; when nothing fits, the build with the smallest minimum. Unknown memory gets the backend's first build (4B bf16 on vLLM, Q8_0 on llama.cpp). bibr setup writes it explicitly. The registry's 4B builds are pinned to a Hub commit; on llama.cpp this may also be the path of a local .gguf file.
LLM_LOCAL_MEM_FRACTION	float	0.85	Share of GPU memory (0.0-1.0) for the managed vLLM LLM server. Left unset, it is the most the server takes: bibr sizes the share from the GPU memory free when the server starts. Set it to start the server at exactly this share.
LLM_LOCAL_MIN_VRAM_GB	float | None	None	Minimum budget (GiB) of a managed vLLM LLM server's model: when bibr sizes the server's share at a start, a share below it is refused before vLLM is launched. It sets the minimum of a model that bibr's registry does not list, such as a local path (6.0 for a local copy of the 4B student's W4A16 build served with --max-num-seqs 64 on vLLM 0.32, 7.25 with an MTP --speculative-config of your own). For a model the registry lists it can raise the registry's minimum but not lower it: a lower value is ignored with a warning.
LLM_VLLM_MLX_PORT	int	8767	Port for the managed vllm-mlx LLM server.
LLM_VLLM_MLX_EXTRA_ARGS	str	""	Extra CLI args (shlex-split) appended to the managed vllm-mlx LLM server command.
LLM_VLLM_MLX_CONTINUOUS_BATCHING	bool	True	Launch the managed vllm-mlx LLM server with --continuous-batching (BatchedEngine) instead of the serial SimpleEngine. Default ON: bibr launches the server via bibr.local._vllm_mlx_server, a stable wrapper around the validated vllm-mlx 0.4.x entrypoint with conservative hybrid-cache handling for Qwen3.5/Qwen3-Next. Managed local LLM calls are still serialized by default through LLM_MAX_CONCURRENCY=1 unless the operator explicitly raises that cap after validating their runtime/model combo.
LLM_VLLM_PORT	int	8769	Port for the managed vLLM LLM server (Linux/CUDA; --llm local).
LLM_VLLM_STARTUP_TIMEOUT	int	600	Startup timeout in seconds for the managed vLLM LLM server.
LLM_VLLM_EXTRA_ARGS	str	""	Extra CLI args appended to the managed vLLM LLM server command (overrides registry defaults on repeated flags).
LLM_VLLM_SPEC_DECODE	enum	"auto"	Speculative decoding for the managed vLLM LLM server: 'auto' (MTP when bibr's model registry lists an MTP config for the model, the server stays up for the whole run, and its budget meets MTP's minimum; none when it restarts every chunk to take turns with a managed PaddleOCR-VL server, as by default on cards up to 64 GB), 'none', or 'mtp' / 'dflash' at every start when the registry lists that config for the model (DFlash: the 4B student's bf16 build only); the start then needs that config's larger minimum. A --speculative-config in LLM_VLLM_EXTRA_ARGS wins.
LLM_RAPID_MLX_MODEL	str	"qwen3.5-4b-4bit"	Model id or Rapid-MLX alias for the managed Rapid-MLX LLM server. Default is Qwen3.5 4B 4-bit, served with no-thinking defaults.
LLM_RAPID_MLX_PORT	int	8773	Port for the managed Rapid-MLX LLM server.
LLM_RAPID_MLX_EXTRA_ARGS	str	""	Extra CLI args appended to the managed Rapid-MLX LLM server command.
LLM_LLMSTER_MODEL	str	""	LM Studio model key already present in lms ls --json.
LLM_LLMSTER_MODEL_ID	str	"bibr-local"	Stable loaded-model identifier exposed through the local API.
LLM_LLMSTER_PORT	int	1234	LM Studio OpenAI-compatible server port.
LLM_LLMSTER_CONTEXT_LENGTH	int	32768	Context length requested when bibr loads the llmster model.
LLM_LLMSTER_LOAD_ARGS	str	""	Additional expert arguments appended to lms load.
LLM_LLAMA_CPP_PORT	int	8770	Port for the managed llama.cpp LLM server (native Windows / low-VRAM GGUF).
LLM_LLAMA_CPP_CONTEXT_SIZE	int	16384	Context size (tokens) for the managed llama.cpp LLM server. Qwen3.5's hybrid attention (mostly linear-attention layers) makes KV cheap, so 16384 fits the 24,000-char input cap plus the 4,096-token completion cap with headroom on 6 GB cards.
LLM_LLAMA_CPP_STARTUP_TIMEOUT	int	600	Startup timeout in seconds for the managed llama.cpp LLM server.
LLM_LLAMA_CPP_EXTRA_ARGS	str	""	Extra CLI args appended to the managed llama.cpp LLM server command. Overrides bibr defaults for the same flags. Pass each flag and its value as separate tokens (--flag value, not --flag=value). Role-based LLM defaults include --flash-attn on, --cache-type-k/v q8_0, --n-gpu-layers 999, plus probe-gated --parallel 2 --kv-unified, --spec-type ngram-mod, and --no-mmproj when supported (else --parallel 1).
LLM_INSTRUCTOR_MODE	enum	""	Instructor structured-output mode for custom-base_url (local) servers: "" (default, strict JSON_SCHEMA), "json" (json_object, looser but more complete on small models), or the explicit "md_json"/"markdown_json"/"json_schema"/"tools" spellings. "json_object" is accepted as "json". Ignored for real OpenAI.
LLM_STRUCTURED_BACKEND	enum	"auto"	Structured-output backend: "auto" (default), "instructor", or "nuextract-native". Auto uses Instructor; native NuExtract templates are experimental, require explicit runtime-specific qualification and need pip install 'bibr[nuextract]'.
LLM_BATCH_MODEL	str	"claude-haiku-4-5"	Model name for the offline batch LLM layer.
LLM_BATCH_POLL_INTERVAL_S	int	60	Poll interval in seconds for the offline batch LLM layer's job status checks.

OCR (OCR_*)

Variable	Type	Default	Description
OCR_API_KEY	str | None	None	OCR server API key, if authentication is required.
OCR_ALLOW_INSECURE_HTTP	bool	False	Allow plain HTTP to a non-loopback OCR server. Enable only on a trusted private network; remote OCR defaults to HTTPS-only.
OCR_REQUEST_TIMEOUT	int	90	OCR request timeout in seconds.
OCR_BACKEND	str	"paddle"	OCR server backend: "paddle" (default), "paddle-vllm" (GPU/vLLM), "paddle-rapid-mlx" (Apple Silicon/Rapid-MLX), "paddle-mlx-vlm" (Apple Silicon/MLX-VLM), or "paddle-http" (external Paddle server); "glm-mlx" (disabled — use glm-rapid-mlx), "glm-rapid-mlx" (Apple Silicon/Rapid-MLX), "glm-llama" (Windows default; llama.cpp), or "glm-http" (external GLM server) — plus the cloud vision-LLM providers "gemini", "openai", and "anthropic".
OCR_MODEL	str | None	None	OCR model name override.
OCR_PROFILE	enum, optional	None	OCR model profile override. Null infers Paddle or GLM from the backend/model name.
OCR_GENERATION_MAX_TOKENS	int | None	None	OCR generation max-token override for every task in the resolved model profile.
OCR_GENERATION_TEMPERATURE	float | None	None	OCR generation temperature override for the resolved model profile.
OCR_PADDLE_MODEL	str	"PaddlePaddle/PaddleOCR-VL-1.6"	PaddleOCR-VL HuggingFace model id.
OCR_PADDLE_REVISION	str	"66317acc4c9fc17bd154591ce650735cd2855f3e"	Pinned revision for the PaddleOCR-VL HuggingFace model.
OCR_PADDLE_SERVED_MODEL	str	"paddle-ocr-vl-1.6"	Served model name expected from Paddle OCR HTTP servers.
OCR_PADDLE_VLLM_PORT	int	8774	Port for the managed Paddle vLLM OCR server.
OCR_PADDLE_VLLM_STARTUP_TIMEOUT	int	900	Startup timeout in seconds for the managed Paddle vLLM OCR server.
OCR_PADDLE_VLLM_EXTRA_ARGS	str	""	Extra CLI args appended to the managed Paddle vLLM OCR server command.
OCR_PADDLE_MLX_MODEL	str	"olragon/PaddleOCR-VL-1.6-8bit"	Model id for the managed Paddle MLX OCR server.
OCR_PADDLE_MLX_PORT	int	8775	Port for the managed Paddle MLX OCR server (shared with the paddle-rapid-mlx fallback candidate, which runs in sequence, never alongside).
OCR_PADDLE_MLX_STARTUP_TIMEOUT	int	600	Startup timeout in seconds for the managed Paddle MLX OCR server.
OCR_PADDLE_MLX_EXTRA_ARGS	str	""	Extra CLI args for the managed Paddle MLX-VLM OCR server (paddle-mlx-vlm only). It shares OCR_PADDLE_MLX_PORT with paddle-rapid-mlx because the paddle chain never runs them at the same time.
OCR_PADDLE_RAPID_MLX_MODEL	str	"olragon/PaddleOCR-VL-1.6-8bit"	Model id for the managed Paddle Rapid-MLX OCR server.
OCR_PADDLE_RAPID_MLX_EXTRA_ARGS	str	""	Extra CLI args for the managed Paddle Rapid-MLX OCR server (paddle-rapid-mlx only). It shares OCR_PADDLE_MLX_PORT with paddle-mlx-vlm because the paddle chain never runs them at the same time.
OCR_LLAMA_CPP_MODEL	str	"ggml-org/GLM-OCR-GGUF:Q8_0"	Model id for the managed llama.cpp OCR server.
OCR_LLAMA_CPP_PORT	int	8771	Port for the managed llama.cpp OCR server.
OCR_LLAMA_CPP_CONTEXT_SIZE	int	8192	Context size (tokens) for the managed llama.cpp OCR server.
OCR_LLAMA_CPP_STARTUP_TIMEOUT	int	600	Startup timeout in seconds for the managed llama.cpp OCR server.
OCR_LLAMA_CPP_EXTRA_ARGS	str	""	Extra CLI args appended to the managed llama.cpp OCR server command. Overrides bibr defaults for the same flags. Pass each flag and its value as separate tokens (--flag value, not --flag=value). Role-based OCR defaults include --flash-attn on, --cache-type-k/v q8_0, --n-gpu-layers 999, --parallel 1 (OCR image encode serializes across slots, so it stays single-slot).
OCR_NATIVE_TEXT_ENABLED	bool	True	Native text extraction — skip OCR for text-layer PDFs.
OCR_NATIVE_TEXT_MIN_CHARS	int	20	Minimum character count for a native-text extraction to be accepted.
OCR_NATIVE_TEXT_MIN_PRINTABLE_RATIO	float	0.85	Minimum fraction of printable characters a native-text extraction must have to be trusted; below this the page falls back to OCR.
OCR_NATIVE_TEXT_HEADER_FOOTER	bool	True	Read header/footer regions from the PDF text layer instead of OCR on born-digital PDFs, under the same printable-ratio gate as body text. Short running heads use the short-text allowance. A header or footer stays with OCR in a right-to-left script, as a first-page masthead the text layer barely covers, and on scanned pages. On by default: in the 2026-10-26 evaluation it changed no scored field on born-digital PDFs or scans and sent about 42% fewer OCR requests per born-digital paper. Set false to OCR them.
OCR_NATIVE_TEXT_FORMULA_NUMBER	bool	False	Read equation-number regions (formula_number, e.g. "(3)") from the PDF text layer instead of OCR on born-digital PDFs, under the same printable-ratio gate. They are 1-16 characters, so they get their own short-text allowance; longer text (the box caught part of the formula) falls back to OCR. Off by default; enable to A/B.
OCR_NATIVE_TEXT_REJECT_INVISIBLE_LAYER	bool	True	Read a scanned page with OCR even when it carries a text layer, if the page is a page-sized image under invisible text (the searchable layer an OCR engine adds to a scan). The legacy layer is often worse than OCR; disable to trust it as before.
OCR_CONSENSUS_BACKEND	enum, optional	None	OCR backend that re-reads scanned regions for two-recognizer consensus (glm-http or paddle-http against a running server, or a cloud vision provider). Null (default) disables consensus.
OCR_CONSENSUS_URL	str | None	None	Base URL of the consensus recognizer's OpenAI-compatible server.
OCR_CONSENSUS_MODEL	str | None	None	Served model name of the consensus recognizer (backend default if null).
OCR_CONSENSUS_PROFILE	enum, optional	None	Prompt/output profile of the consensus recognizer; inferred from its backend and model when null.
OCR_CONSENSUS_THRESHOLD	float	0.15	Normalized edit distance between the two readings of a region at or above which the recognizers disagree.
OCR_CONSENSUS_ESCALATE_SHARE	float	0.07	Largest share of a paper's compared regions that is escalated, worst disagreement first (at least one region when any disagrees).
OCR_CONSENSUS_PAGE_KINDS	list	['scan']	Page classes whose OCR'd text regions are compared (comma-separated).
OCR_ESCALATION_BACKEND	enum, optional	None	OCR backend that re-reads the escalated regions; the reading closest to the other two is kept. Null keeps the primary reading and only flags the region.
OCR_ESCALATION_URL	str | None	None	Base URL of the escalation recognizer's OpenAI-compatible server.
OCR_ESCALATION_MODEL	str | None	None	Served model name of the escalation recognizer.
OCR_ESCALATION_PROFILE	enum, optional	None	Prompt/output profile of the escalation recognizer.
OCR_LOCAL_GPUS	int	1	Number of GPUs dedicated to the local OCR server (tensor parallelism). Also sets ocr.max_concurrent_regions = 16 x this value. (aliases: OCR_SGLANG_GPUS)
OCR_MAX_CONCURRENT_FILES	int	4	Max concurrent files being OCR'd simultaneously.
OCR_MAX_CONCURRENT_REGIONS	int	16	Max concurrent OCR region requests server-wide (default 16 x OCR_LOCAL_GPUS; keep <= 16 per server instance to avoid detokenizer stalls). Binds every OCR path, and is the cap used on its own when files run one at a time against a managed batching server (paddle-vllm).
OCR_CONCURRENT_REGIONS_PER_FILE	int	6	Max concurrent OCR region requests per file (prevents one file starving others when files overlap). Never exceeds OCR_MAX_CONCURRENT_REGIONS.
OCR_LOCAL_MODEL	str	"THUDM/GLM-OCR"	HuggingFace model id for the local GLM OCR backends.
OCR_RAPID_MLX_MODEL	str	"mlx-community/GLM-OCR-8bit"	Model id for the managed Rapid-MLX OCR server. Defaults to GLM-OCR 8-bit.
OCR_RAPID_MLX_PORT	int	8772	Port for the managed Rapid-MLX OCR server.
OCR_RAPID_MLX_EXTRA_ARGS	str	""	Extra CLI args appended to the managed Rapid-MLX OCR server command.
OCR_RAPID_MLX_RECYCLE_AFTER	int	80	Restart the managed Rapid-MLX OCR subprocess after this many regions. Mitigates a vendored rapid-mlx bug (vllm_mlx MLLMBatchGenerator's VisionEmbeddingCache pixel cache is bounded by entry count, not bytes — 100 entries, no eviction by size) that never gets useful reuse on bibr's unique-crop-per-region workload, so it fills with ~100 dead ~34-72MB float32 tensors (~3.4GB) and OCR then fails silently while /health stays green. 80 leaves headroom below the ~100-entry saturation point. 0 disables recycling.
OCR_MIN_SUCCESS_RATE	float	0.5	Mark a file failed (code ocr_mostly_failed) when fewer than this fraction of OCR-needed regions return content. Set to 0 to disable.
OCR_UNLOAD_BETWEEN_CHUNKS	enum	"auto"	When to tear down a local in-process OCR engine between batch chunks: "auto" (default, keep resident in balanced mode unless a local LLM shares the GPU), "always" (legacy per-chunk teardown), or "never".

OCR vision (OCR_VISION_*)

Variable	Type	Default	Description
OCR_VISION_PROVIDER	str	"google"	Vision LLM provider for OCR: "google" (default), "openai", "anthropic".
OCR_VISION_MODEL	str	"gemini-3-flash-preview"	Vision LLM model for OCR.
OCR_VISION_BASE_URL	str | None	None	Vision LLM base URL override.
OCR_VISION_RATE_LIMIT_RPM	int	30	Vision LLM rate limit in requests per minute.
OCR_VISION_MAX_TOKENS	int	16384	Vision LLM max completion tokens. With anthropic each region asks for one token per 32 crop pixels at 200 DPI (scaled with LAYOUT_DPI), at least 2048, never more than this.
OCR_VISION_TIMEOUT_SECONDS	int	60	Vision LLM request timeout in seconds.

Figure extraction (FIG_*)

Variable	Type	Default	Description
FIG_EXTRACT	enum	"off"	Reserved figure-analysis tier: "off" (default) or "meta". Not yet implemented: meta logs a warning and does not add figure analysis. All FIG_* settings are inactive until the analysis stage is implemented.
FIG_PROVIDER	str	"google"	Vision LLM provider: "google" (default), "openai", "anthropic".
FIG_MODEL	str	"gemini-3-flash-preview"	Vision LLM model.
FIG_BASE_URL	str | None	None	Vision LLM base URL override.
FIG_RATE_LIMIT_RPM	int	30	Rate limit in requests per minute.
FIG_MAX_TOKENS	int	8192	Max completion tokens per figure call.
FIG_TIMEOUT_SECONDS	int	90	Per-figure request timeout in seconds.
FIG_MAX_FIGURES	int	15	Max figures analyzed per paper; the rest are skipped with a warning.
FIG_MAX_CONCURRENCY	int	4	Concurrent figure calls per paper.
FIG_MIN_CROP_PX	int	120	Skip crops whose width or height is below this many pixels.

Layout detection (LAYOUT_*)

Variable	Type	Default	Description
LAYOUT_MODEL_ID	str	"PaddlePaddle/PP-DocLayoutV3_safetensors"	HF Hub repo id (or local directory) of the PP-DocLayout torch checkpoint (PP-DocLayoutV3 or PP-DocLayoutV4) used when layout runs on torch.
LAYOUT_MODEL_REVISION	str	"97d101e6db2642e162a1d05392d1b0231c91033e"	HF Hub revision (commit SHA or branch) of LAYOUT_MODEL_ID to load. Pinned so a hub push cannot change layout output; 'main' tracks the repo head.
LAYOUT_ONNX_MODEL_ID	str | None	"scienceverse/bibr-layout-onnx"	HF Hub repo id (or local bundle directory) holding the ONNX export of the layout model under onnx/. Null disables the ONNX runtime for layout.
LAYOUT_ONNX_REVISION	str	"2bcb16a65f5128fd9e61ac6c503204721cf01ce0"	HF Hub revision (commit SHA or branch) of LAYOUT_ONNX_MODEL_ID to load. Pinned to the export whose regions match the torch model exactly; 'main' tracks the head.
LAYOUT_DPI	int	200	Page rasterization DPI for layout detection.
LAYOUT_MAX_RENDER_PIXELS	int	25000000	Maximum rasterized pixels for one PDF page. A page over it at LAYOUT_DPI renders at the largest DPI that fits, down to 24; below that it is rejected.
LAYOUT_MAX_RENDER_DIMENSION	int	10000	Maximum rasterized width or height for one PDF page, handled like LAYOUT_MAX_RENDER_PIXELS.
LAYOUT_DETECTION_THRESHOLD	float	0.3	Minimum confidence score for a layout detection to be kept.
LAYOUT_NMS_IOU_SAME	float	0.6	Non-max-suppression IoU threshold for boxes of the same class.
LAYOUT_NMS_IOU_DIFF	float	0.98	Non-max-suppression IoU threshold for boxes of different classes.
LAYOUT_LARGE_IMAGE_AREA_LANDSCAPE	float	0.82	Page-area fraction above which a landscape image region is treated as a large/full-page figure.
LAYOUT_LARGE_IMAGE_AREA_PORTRAIT	float	0.93	Page-area fraction above which a portrait image region is treated as a large/full-page figure.
LAYOUT_SECTION_CLASSIFICATION_SCORE	float	0.85	Minimum confidence score for a detected section heading region.
LAYOUT_CONTAINMENT_THRESHOLD	float	0.5	Minimum overlap fraction for one detected region to be treated as contained in another.
LAYOUT_BATCH_SIZE	int	8	Page batch size for layout model inference. The configured value is the non-CPU batch; on CPU the local and serve detectors run one page at a time unless this was set explicitly (a CPU batch of 8 grows the ORT CPU arena to several GB with no throughput gain).
LAYOUT_BATCH_TIMEOUT_MS	int	5	Coalescing window in milliseconds for the serve layout GpuBatcher (0 = flush immediately, admission-gate only).
LAYOUT_OVERLAP_RESOLVER	enum	"legacy"	Overlap-resolution pass for layout regions: "legacy" (pairwise containment filter) or "rulebook" (union-find keep-best-absorb-union resolver). Rulebook ships dark pending an eval gate.
LAYOUT_READ_ORDER_FALLBACK	enum	"xy"	Reading-order fallback when the layout model emits no order_seq: "xy" (lexsort by box centers) or "rb" (column-aware horizontal-dilation adjacency ordering).
LAYOUT_TORCH_COMPILE	bool	False	Enable torch.compile for the layout model.
LAYOUT_USE_GPU	bool | None	None	Run the serve layout model on GPU. Null = auto-detect (cuda->mps->cpu). Force CPU only on VRAM-tight boxes that co-locate OCR.

Crossref enrichment (CROSSREF_*)

Variable	Type	Default	Description
CROSSREF_API_EMAIL	str | None	None	Contact email for the Crossref polite API pool (strongly recommended).
CROSSREF_API_KEY	str | None	None	Crossref API key, for Plus/Metadata Plus access.
CROSSREF_RATE_LIMIT_RPM	int	200	Crossref rate limit in requests per minute (raise to 600 if you set an email or have an API key).
CROSSREF_ENRICH	bool	False	Enable Crossref/resolver reference enrichment (off by default). Per-run overrides: bibr chew --crossref/--no-crossref, chew(crossref=...), or the serve API's crossref form field.
CROSSREF_BULK_DOI_LOOKUP	bool	True	Prefetch all DOI-bearing references in one Crossref filter query before the per-reference fan-out. Set false to restore one request per DOI.
CROSSREF_ENRICH_CONCURRENCY	int	12	Pipeline-fill parallelism for Crossref reference lookups.
CROSSREF_ENRICH_TIMEOUT	float	120.0	Per-paper wall-clock budget in seconds for the whole enrichment stage.
CROSSREF_REQUEST_TIMEOUT	float	15.0	Per-HTTP-request timeout in seconds for Crossref calls.
CROSSREF_CACHE_SIZE	int	1024	In-process LRU cache size for Crossref works/search responses. 0 disables.
CROSSREF_REDIS_CACHE	bool	False	Enable the shared (tier-2) Redis response cache for Crossref works/search responses. Off by default (in-process LRU only).
CROSSREF_CACHE_REDIS_URL	str | None	None	Redis URL for the shared Crossref response cache. Falls back to REDIS_URL when unset; REDIS_PASSWORD is added when it names the same Redis host and port.
CROSSREF_CACHE_TTL_SECONDS	int	2592000	TTL for shared Crossref cache entries, in seconds (default 30 days).
CROSSREF_NOT_FOUND_TTL_SECONDS	int	86400	How long a Crossref 404 for a DOI (no record) is remembered in the response caches, in seconds (default 1 day), so repeat lookups skip the request. 0 disables.
CROSSREF_CONSOLIDATE	enum	"off"	Merge accepted bib_match data into bib rows at export: "off" (default), "fill" (fill empty fields only), or "replace" (also overwrite printed values, only from a match carrying the reference's printed DOI).
CROSSREF_VERIFY	bool	True	Check parsed reference volume, issue and pages against the matched record at export: report disagreements, and fill or correct a value only when the record's value is printed in the reference string. Needs enrichment; off leaves bib[] as parsed.

bibr-resolver (BIBR_RESOLVER_*)

Variable	Type	Default	Description
BIBR_RESOLVER_URL	str | None	None	Base URL of the bibr-resolver service, e.g. http://resolver-host:2010. Unset = disabled.
BIBR_RESOLVER_ENRICH	bool	True	Master gate for the resolver; when false the resolver is skipped even if url is set.
BIBR_RESOLVER_TIMEOUT	float	30.0	Per-request timeout in seconds for resolver calls (/search, /works, /health).
BIBR_RESOLVER_RETRIES	int	3	Times a resolver call is tried again after a busy answer (429/502/503/504), a timeout (once at most) or a dropped connection. 0 disables retries.
BIBR_RESOLVER_RETRY_BACKOFF	float	1.0	First wait in seconds before retrying a resolver call; it doubles on each retry (with jitter, capped at 30 s) and is never shorter than the resolver's Retry-After.
BIBR_RESOLVER_MAX_CONCURRENCY	int	8	Max resolver requests in flight across all papers in this process (per resolver URL). 0 = no cap.
BIBR_RESOLVER_LIMIT	int	20	Max candidates to request from the resolver /search endpoint.
BIBR_RESOLVER_SEARCH_CONCURRENCY	int	4	Max concurrent /search calls when prefetching a reference list's title searches.
BIBR_RESOLVER_AUTHORITATIVE	bool	False	Treat a clean resolver miss (queried OK, no accepted match) as final, skipping the redundant CrossRef fallback. A resolver error still falls through to CrossRef.
BIBR_RESOLVER_SOURCES	list	['crossref']	Resolver corpora to query on /search (comma-separated in env, e.g. "crossref,openalex"). CrossRef only by default — OpenAlex is ~8x slower per search, so route it through fallback_sources instead. Empty = the resolver's own default tier.
BIBR_RESOLVER_FALLBACK_SOURCES	list	[]	Resolver corpora queried only for references left unmatched by the primary pass.
BIBR_RESOLVER_FALLBACK_SEARCH_CONCURRENCY	int	4	Max concurrent resolver searches in the unmatched-reference fallback pass.
BIBR_RESOLVER_FALLBACK_TIMEOUT	float	30.0	Whole-paper wall-clock deadline in seconds for the resolver fallback pass.
BIBR_RESOLVER_RAW_SEARCH	bool	True	Search the resolver with the whole reference string for references the title passes left unmatched; a candidate is accepted only when its title, year and first author (or volume and first page) are printed in that string.

ROR organization matching (ROR_*)

Variable	Type	Default	Description
ROR_ENRICH	bool	True	Match affiliation strings and funder names to ROR IDs when enrichment runs (--crossref). Set false to skip ROR.
ROR_CLIENT_ID	str | None	None	ROR API client ID, sent as the Client-Id header. It raises the default request budget from 1000 to 2000 requests per 5 minutes. ROR client IDs are free, but ROR has paused new registrations.
ROR_URL	str	"https://api.ror.org/v2"	ROR API base URL.
ROR_REQUESTS_PER_5MIN	int | None	None	Client-side ROR request budget per 5 minutes, per process. Default: 1000 without a client ID (half ROR's limit of 2000 per IP address, so two processes on one address stay under it) and 2000 with one. Every bibr process and other ROR client behind one outgoing IP address shares ROR's 2000, so with N processes set at most 2000/N. A 429 from ROR halves the budget in that process (not below 50, or this value if lower); the first lookup after an hour without one doubles it back, and the next doubling needs another such hour.
ROR_REQUEST_TIMEOUT	float	10.0	Per-HTTP-request timeout in seconds for ROR calls.
ROR_ENRICH_TIMEOUT	float	60.0	Per-paper wall-clock budget in seconds for ROR matching. Strings not matched in time are left without a match.
ROR_CACHE_SIZE	int	4096	In-process cache size for ROR answers (hits and misses). 0 disables.

Cache (CACHE_*)

Variable	Type	Default	Description
CACHE_ENABLED	bool	True	Enable the result cache.
CACHE_VERSION	str	(computed)	Cache version namespace; invalidates stored entries on change. Defaults to a hash of the code — override only to pin or force-invalidate manually.
CACHE_TTL_SECONDS	int	86400	Result cache entry TTL in seconds. 0 or a negative value means no expiry.
CACHE_DISTRIBUTED_SINGLEFLIGHT	bool	True	Coalesce identical Redis-backed cache misses across workers. Fail-open.
CACHE_SINGLEFLIGHT_WAIT_SECONDS	float	10.0	Maximum time a distributed waiter polls for the owner's result. Unset (left at its default without explicitly setting it) follows PIPELINE_TIMEOUT; an explicitly set value is the wait budget.
CACHE_SINGLEFLIGHT_LEASE_TTL_SECONDS	int	120	TTL for a distributed extraction ownership lease.
CACHE_SINGLEFLIGHT_RENEW_INTERVAL_SECONDS	float	30.0	Interval between token-safe ownership renewals.
CACHE_SINGLEFLIGHT_POLL_INTERVAL_MS	int	100	Base cache polling interval for distributed waiters.
CACHE_OPERATION_TIMEOUT_SECONDS	float	5.0	Upper bound in seconds for one response-cache operation (get, set, lease) in bibr serve. A slower Redis counts as a cache miss instead of stalling the request.
CACHE_OCR	bool	False	Opt-in disk cache for OCR stage output — reuses cached OCR regions for the same PDF instead of re-running the OCR backend. A complete entry also skips page rendering, layout detection and native-text analysis, so leave it off when timing runs. Entries are keyed on the settings, model pins and bibr version, not on source changes between releases; use a fresh CACHE_OCR_DIR per source revision when comparing revisions that touch those stages. Off by default.
CACHE_OCR_DIR	str | None	None	Directory for the OCR disk cache. Null = $XDG_CACHE_HOME/bibr/ocr (else ~/.cache/bibr/ocr).
CACHE_LLM	bool	False	Opt-in disk cache for structured LLM responses, keyed on model, schema, system prompt and user text. Not written by the offline batch layer. Off by default.
CACHE_LLM_DIR	str | None	None	Directory for the LLM response cache. Null = $XDG_CACHE_HOME/bibr/llm (else ~/.cache/bibr/llm).

Circuit breaker (CB_*)

Variable	Type	Default	Description
CB_FAILURE_THRESHOLD	int	5	Consecutive failures before the circuit breaker opens for an upstream service.
CB_RESET_TIMEOUT_SECONDS	float	30.0	Seconds the circuit breaker stays open before allowing a retry probe.
CB_FAILURE_DEDUP_WINDOW	float	2.0	Seconds within which repeated failures are deduplicated as a single event.

CORS (CORS_*)

Variable	Type	Default	Description
CORS_ORIGINS	list	[]	Comma-separated list of allowed CORS origins for production.
CORS_ALLOW_CREDENTIALS	bool	False	Allow credentials (cookies/auth headers) in CORS requests.
CORS_ALLOW_METHODS	list	['*']	Allowed HTTP methods for CORS requests.
CORS_ALLOW_HEADERS	list	['*']	Allowed HTTP headers for CORS requests.

Redis (REDIS_*)

Variable	Type	Default	Description
REDIS_PASSWORD	str | None	None	Redis password. Required in production; injected into redis.url if unset there.
REDIS_URL	str | None	None	Redis connection URL. Defaults work with docker-compose; auto-built from password if unset.
REDIS_CONNECT_TIMEOUT_SECONDS	float	2.0	Seconds to wait for a Redis TCP connection before treating Redis as down.
REDIS_SOCKET_TIMEOUT_SECONDS	float	5.0	Seconds to wait for a single Redis command reply. A Redis that accepts connections but never answers fails the command instead of hanging the request.

ML models (ML_*)

Variable	Type	Default	Description
ML_RUNTIME	enum	"auto"	Inference runtime for the local models: 'auto' (ONNX bundle when published or configured, else torch when installed), 'onnx' (require the ONNX bundle), or 'torch' (require the torch extra).
ML_SECTION_CLASSIFIER_MODEL_ID	str | None	"scienceverse/bibr-section-classifier"	HF Hub repo id for the trained section classifier. Null falls back to the LLM classification path.
ML_SECTION_CLASSIFIER_REVISION	str	"cf7c2d8530f8b596ccb0a4c67c1db82537121100"	HF Hub revision (commit SHA or branch) for the section classifier. Pinned to the audited commit (plus the additive ONNX bundle) so a hub push cannot change output; 'main' tracks the repo head.
ML_SECTION_CLASSIFIER_MIN_CONFIDENCE	float	0.5	Type-head softmax probability below which a section-classifier prediction collapses to UNKNOWN. Set to 0.0 to disable.
ML_SECTION_CLASSIFIER_LLM_ESCALATION	bool	True	Escalate section headers the trained classifier leaves UNKNOWN (below-confidence collapses and confident unknown predictions) to the batched LLM classifier instead of discarding them.
ML_SECTION_CLASSIFIER_DEVICE	str | None	None	Device the section classifier runs on. Null = auto (CUDA -> CPU); MPS is opt-in (benchmarked slower than CPU on this model).
ML_PAPER_CLASSIFIER_MODEL_ID	str | None	"scienceverse/bibr-paper-classifier"	HF Hub repo id for the trained OECD/paper_type multitask classifier. Set to null to fall back to the existing LLM classification path. Defaults to the published multitask classifier (all-MiniLM-L6-v2 encoder; OECD L1/L2 + paper_type).
ML_PAPER_CLASSIFIER_REVISION	str	"6046171b3198a255acb1f07f81a586a32f399ac4"	HF Hub revision (commit SHA or branch) for the paper classifier. Pinned to the audited commit (plus the additive ONNX bundle) so a hub push cannot change output; 'main' tracks the repo head.
ML_PAPER_CLASSIFIER_MIN_CONFIDENCE	float	0.5	paper_type-head softmax probability below which a paper-classifier prediction is escalated to the LLM fallback (label_paper_type).
ML_PAPER_CLASSIFIER_LLM_ESCALATION	bool	True	Escalate low-confidence paper_type predictions to the LLM paper_type labeler instead of keeping them as-is.
ML_PAPER_CLASSIFIER_L2_MIN_CONFIDENCE	float	0.5	OECD L2 (subdomain) head softmax probability below which the subdomain is emitted as null instead of a low-confidence label. 0.0 = always emit.
ML_PAPER_CLASSIFIER_DEVICE	str | None	None	Device the paper classifier runs on. Null = auto (CUDA -> CPU).
ML_FRONT_ROLE_MODEL_ID	str | None	"scienceverse/bibr-front-role-v1"	HF Hub repo id (or local path) of the first-page region-role classifier bundle. Null disables the model and rests front matter on the lexical heuristics alone. TRUST BOUNDARY: deserialized with joblib via the gadget-restricted loader; only point it at a checkpoint you control.
ML_FRONT_ROLE_REVISION	str	"7f01b57e1999d93cb5f17895ed10fdfa27cf6e0b"	Pinned revision for the front-role classifier bundle. Pinned so a hub push cannot change front-matter output; 'main' tracks the repo head.
ML_FRONT_ROLE_ENABLED	bool	True	Consult the front-role classifier when a model id is configured. False keeps the model unloaded even when ML_FRONT_ROLE_MODEL_ID is set.
ML_FRONT_ROLE_MIN_CONFIDENCE	float	0.5	Minimum front-role probability for a model role to count as evidence.
ML_FRONT_ROLE_MASTHEAD_CONFIDENCE	float	0.8	Front-role masthead probability above which a row cannot be a title seed.
ML_FRONT_ROLE_RECORD_ROOT_CONFIDENCE	float	0.9	Front-role probability of a non-title role above which a title seed cannot root a second front-matter record. 1.0 disables the veto.
ML_CLASSIFIERS_REQUIRED	bool	False	Fail readiness when a configured local classifier cannot be loaded. False keeps the existing LLM fallback and reports degraded readiness.
ML_PAPER_CLASSIFIER_BATCH_SIZE	int	64	Maximum paper-classifier micro-batch size.
ML_PAPER_CLASSIFIER_BATCH_TIMEOUT_MS	float	5.0	Paper-classifier cross-request coalescing window in milliseconds.
ML_SECTION_CLASSIFIER_BATCH_SIZE	int	64	Maximum section-classifier micro-batch size.
ML_SECTION_CLASSIFIER_BATCH_TIMEOUT_MS	float	5.0	Section-classifier cross-request coalescing window in milliseconds.
ML_CLASSIFIER_VRAM_SAFETY_RESERVE_MB	int	2048	VRAM kept free after managed vLLM and classifier placement.
ML_PAPER_CLASSIFIER_ESTIMATED_PEAK_MB	int	1536	Conservative paper-classifier weights plus forward-workspace estimate.
ML_SECTION_CLASSIFIER_ESTIMATED_PEAK_MB	int	512	Conservative section-classifier weights plus forward-workspace estimate.

vLLM-MLX (VLLM_MLX_*)

Variable	Type	Default	Description
VLLM_MLX_STARTUP_TIMEOUT	int	180	Startup timeout in seconds for the managed vllm-mlx subprocess.
VLLM_MLX_WARMUP_TIMEOUT	int	300	Warmup timeout in seconds for the managed vllm-mlx subprocess's first inference (first-inference paging on a 2 GB+ model can take 30-60s).

Rapid-MLX (RAPID_MLX_*)

Variable	Type	Default	Description
RAPID_MLX_EXECUTABLE	str	"rapid-mlx"	rapid-mlx executable path or command name for managed Rapid-MLX servers.
RAPID_MLX_STARTUP_TIMEOUT	int	600	Startup timeout in seconds for the managed Rapid-MLX subprocess.
RAPID_MLX_WARMUP_TIMEOUT	int	300	Warmup timeout in seconds for the managed Rapid-MLX subprocess.
RAPID_MLX_PREFILL_STEP_SIZE	int	8192	Chunk size passed as --prefill-step-size to managed Rapid-MLX servers.
RAPID_MLX_MAX_NUM_SEQS	int	4	Max concurrent sequences for managed Rapid-MLX servers. Apple Silicon decode is bandwidth-bound, so batched sequences amortize weight reads and raise aggregate throughput; Rapid-MLX continuous batching is on by default.
RAPID_MLX_MAX_CONCURRENT_REQUESTS	int	4	Admission cap for managed Rapid-MLX servers.
RAPID_MLX_SPEC_DECODE	enum	"auto"	Speculative decoding for the managed Rapid-MLX LLM server: 'auto' (attempt native MTP for Qwen3.5/3.6 models, relaunching without it when the checkpoint lacks MTP layers), 'mtp' (fail hard if unsupported), or 'none'. The multimodal OCR server is never launched with speculative decoding.
RAPID_MLX_PIN_SYSTEM_PROMPT	bool	True	Pass --pin-system-prompt so the shared system prompt stays in the Rapid-MLX prefix cache under memory pressure.
RAPID_MLX_FORCE_DISK_CHECK	bool	True	Pass --force-disk-check so external HF caches are not rejected by the current filesystem's free-space check.
RAPID_MLX_HF_HOME	str | None	None	HF_HOME override for managed Rapid-MLX subprocesses, useful for external model-cache drives.
RAPID_MLX_HF_HUB_CACHE	str | None	None	HF_HUB_CACHE override for managed Rapid-MLX subprocesses.
RAPID_MLX_HOME	str | None	None	HOME override for managed Rapid-MLX subprocesses; Rapid-MLX stores some runtime files under the home directory.

Pipeline (PIPELINE_*)

Variable	Type	Default	Description
PIPELINE_TIMEOUT	int	300	Pipeline timeout in seconds.
PIPELINE_BIBR_SHA	str | None	None	Deployed bibr commit SHA surfaced in qualification_provenance (falls back to BIBR_BUILD_SHA when unset).
PIPELINE_PLATFORM_SHA	str | None	None	Deployed serving-platform commit SHA surfaced in qualification_provenance.
PIPELINE_MEMORY_MODE	enum, optional	None	Default memory mode when no --memory flag / LocalPipeline arg is given: "aggressive", "balanced", or "keep_all". Null selects aggressive on systems with <=8 GB RAM or CUDA GPUs below 12 GB of VRAM; otherwise balanced.
PIPELINE_INTEGRITY_STATEMENT_MODE	enum	"shadow"	Research-integrity statement resolver rollout mode. Shadow exports the compatibility statements and logs the comparison with the bounded selection at debug level.
PIPELINE_TITLE_PREFER_BYLINE_ADJACENT	bool	False	Prefer the printed title row directly above the byline over a disagreeing model title (multilingual front matter). Experimental; validate on representative inputs.
PIPELINE_DEPLOYMENT_READY_TIMEOUT	int	120	Deployment ready timeout in seconds.
PIPELINE_MAX_FILE_SIZE	int	52428800	Max upload file size in bytes.
PIPELINE_MULTIPART_OVERHEAD_BYTES	int	1048576	Bytes reserved above max_file_size for multipart boundaries and headers.
PIPELINE_RESTART_WORKERS	bool	False	Opt in to LitServe worker replacement after a critical worker-loop failure. The safe default is fail-stop because LitServe 0.2.x cannot reliably notify an API process whose in-flight request belonged to the dead worker.
PIPELINE_UPLOAD_SPOOL_MEMORY_BYTES	int	1048576	Upload bytes retained in memory before the bounded spool rolls to disk.
PIPELINE_MAX_PAGES	int	200	Hard maximum pages processed per file. Requests beyond this range are capped to prevent compact many-page PDFs from exhausting render memory.
PIPELINE_MAX_CONCURRENT_POST_PARSE	int	4	Max concurrent post-parse tasks per request.
PIPELINE_STREAM_BACKHALF	bool	True	Overlap each OCR window's back half (parse/extract/enrich/export) with subsequent windows' OCR. Only applies to the cloud-LLM path (LLM_BACKEND=cloud, memory mode not aggressive); managed local LLM backends keep the stage barrier. Escape hatch for debugging.
PIPELINE_HEAP_TRIM	enum	"chunk"	When a batch hands freed heap back to the OS (glibc malloc_trim): "chunk" after each chunk, "window" also between the render/OCR windows inside a chunk (lower footprint in large chunks, some throughput cost), "off" never. Single-paper calls and serve requests never trim; no effect off glibc.
PIPELINE_MAX_INFLIGHT_REQUESTS	int	8	Max requests running the pipeline concurrently per worker (0 = unlimited). Bounds peak host RAM under an upload flood.
PIPELINE_MAX_ACTIVE_UPLOADS	int	8	Maximum concurrent upload requests admitted by the API server before multipart parsing (excess requests receive HTTP 429).
PIPELINE_TEXT_QUALITY_REPORT	bool	True	Compute and export a per-paper text-quality score (report-only; 10th-percentile aggregation of per-region garbage/fragmentation ratings).
PIPELINE_TEXT_QUALITY_WARN_THRESHOLD	float	0.5	Text-quality score below which a processing warning is attached to the paper.
PIPELINE_OUTLINE_HEADINGS	bool	False	Use the PDF outline (bookmarks) as a heading-level signal for section hierarchy. Ships dark pending an eval gate.
PIPELINE_SCAN_ARTICLE_SPLIT	bool	False	On scanned pages, drop the regions of neighbouring articles (the previous article's tail and references before the paper's title, the next article after its references) before parsing. Off by default pending an eval on scans.
PIPELINE_DOCUMENT_LAYER	bool	False	Build the internal document layer (glyph fonts, sizes, spans, lines, superscripts, furniture) from the PDF text layer. Internal only; changes no output.
PIPELINE_NON_IMRAD_BODY_AS_DISCUSSION	bool	True	Type the model/LLM-typed body headings of reviews and commentaries with no Methods or Results heading as discussion.

HTTP auth (AUTH_*)

Variable	Type	Default	Description
AUTH_API_KEY	str | None	None	When set, bibr serve enforces bearer-token auth on every request. Required in production (ENVIRONMENT=production refuses to start without it).

Serve jobs (JOBS_*)

Variable	Type	Default	Description
JOBS_ENABLED	bool	True	Enable the async job API (serve).
JOBS_STORE	enum	"memory"	Where job status and results live: 'memory' (one replica; lost on restart) or 'redis' (shared by every replica pointed at the same Redis, so the active-job cap is global and any replica can answer status/result polls). Uploads and execution always stay on the replica that received the upload.
JOBS_REDIS_URL	str | None	None	Redis URL for JOBS_STORE=redis. Falls back to REDIS_URL (the cache's Redis) when unset; startup fails if neither is set. REDIS_PASSWORD is added when it names the same Redis host and port.
JOBS_KEY_PREFIX	str	"bibr:jobs"	Key prefix for the Redis job store. Every replica sharing one job namespace must use the same prefix; change it to isolate deployments that share a Redis.
JOBS_REPLICA_ID	str | None	None	Identifier of this bibr serve replica, recorded on each job it executes and reported as replica in job status. Defaults to <hostname>:<pid>.
JOBS_TTL_SECONDS	int	3600	TTL in seconds for completed job records.
JOBS_MAX_ACTIVE	int	32	Max admitted queued plus running jobs.
JOBS_MAX_RUNNING	int	2	Max job inference descriptors dispatched concurrently.
JOBS_MAX_RETAINED	int	128	Max completed job results retained (in the process, or in Redis across every replica); oldest results are evicted.
JOBS_MAX_RETAINED_BYTES	int	268435456	Byte budget for retained job results (their encoded JSON bodies; the Redis store charges the same encoded size while holding the body compressed). Oldest results are evicted until the rest fit; the newest result is always kept so that an export larger than the budget can still be fetched once. 0 disables the budget (count-only retention).
JOBS_DEDUPE_INFLIGHT	bool	False	Answer a job upload whose file (sha256), filename and options match a job this replica still has queued or running with that job, instead of running the paper twice. bibr serve has a single principal (the shared API key), so enable it only when every caller may share jobs; a multi-user front end should deduplicate per user itself.

Metering (METER_*)

Variable	Type	Default	Description
METER_ENABLED	bool	True	Enable per-request usage metering (serve).
METER_LOG_PATH	str | None	None	Path to write metering records as JSONL (request records; the worker writes extraction records to the sibling '.worker' file, so read both files for token usage).
METER_LOG_MAX_BYTES	int	104857600	Rotate the metering JSONL at this size (bytes). The metering middleware sits outside the auth gate, so unauthenticated request spam would otherwise grow the log without bound and exhaust disk. 0 disables rotation (unbounded).
METER_LOG_BACKUP_COUNT	int	3	Number of rotated metering-log backups to keep.

MCP endpoint (serve) (MCP_*)

Variable	Type	Default	Description
MCP_ENABLED	bool	False	Mount the MCP endpoint at /mcp on bibr serve (requires the mcp extra).
MCP_MAX_PAPERS_PER_SESSION	int	16	Chewed papers retained in memory per MCP client session; the oldest is evicted beyond this.
MCP_SESSION_IDLE_TIMEOUT_SECONDS	float	1800.0	Seconds an MCP client session may sit idle before the server closes it and drops its papers. A client that disconnects without DELETE would otherwise pin its session — and up to max_papers_per_session full exports — for the process lifetime. 0 disables the timeout.
MCP_CHEW_URL_ENABLED	bool	True	Expose the chew_url tool on the MCP servers (bibr mcp and the serve endpoint): a server-side, SSRF-guarded download of a public https:// URL routed into extraction. Disable to keep them free of outbound fetches an agent could use to send data out.
MCP_URL_ALLOWED_HOSTS	list	[]	Restrict chew_url downloads to these hosts (subdomains included, e.g. 'arxiv.org' admits 'export.arxiv.org'). Empty = any public host.

Top-level

Variable	Type	Default	Description
ENVIRONMENT	str	"development"	Runtime environment: "development" or "production". In production mode, redis.password and auth.api_key are required.
BIBR_BUILD_SHA	str | None	None	Exact lowercase Git commit deployed by the serving environment.
SERVE_LOG_LEVEL	str	"info"	Log level for bibr serve's own loggers (bibr.*), also handed to uvicorn and LitServe: debug, info, warning or error. Metering records (METER_ENABLED) are emitted regardless of this level.
WTPSPLIT_MODEL	str	"sat-6l-sm"	WtP-split sentence segmentation model.
WTPSPLIT_MODEL_REVISION	str | None	None	HF Hub revision for a Hub-hosted wtpsplit model. Unset pins the default sat-6l-sm to its audited commit and loads other Hub models from main; local bundles carry their own manifest revision.
WTPSPLIT_THRESHOLD	float | None	None	Optional explicit wtpsplit sentence-boundary threshold.
WTPSPLIT_BLOCK_SIZE	int | None	None	Optional explicit wtpsplit inference block size.
WTPSPLIT_STRIDE	int | None	None	Optional explicit wtpsplit inference stride.
EQUATION_EXTRACTION	bool	True	Extract equations from OCR output.
EQUATION_EXTRACTION_TIMEOUT_SECONDS	int	90	Timeout in seconds for equation extraction.
EQUATION_LLM_FALLBACK_MIN_REGEX_STATS	int	0	Opt-in cost gate for the LLM equation fallback. When > 0, the fallback runs only on papers whose regex pass already found at least this many non-LaTeX statistical components — a paper-level proxy for 'this paper reports statistics'. 0 (default) always runs the fallback. Measured on a 149-paper run: threshold 1 cut ~20% of fallback calls at ~95% recall of LLM-only stat components.
IMPLICIT_SECTION_DETECTION	bool	True	Infer implicit sections from body text when headers are absent.
FIGURE_IMAGES	bool	False	Extract figure images from PDFs.
REF_SEG_STRATEGY	enum, optional	"geom"	Reference-segmentation strategy: "geom" (default; local geometry GBM, cascades region anchors -> LLM -> CRF), "region" (zero-cost layout-region anchors as primary tier), "llm" (force the LLM segmenter), or "crf" (ModernBERT+CRF segmenter).
REF_PARSE_STRATEGY	enum, optional	"ner"	Reference-parsing strategy: "ner" (default; local encoder-CRF parser, no per-reference LLM cost), "ref-llm" (dedicated fine-tuned reference model), "llm" (batched LLM), "llm-chunked" (chunk-tolerant LLM parse over region-aligned chunks), or "off" (disable reference extraction entirely).
REF_NER_LLM_FALLBACK	bool	True	Review flagged NER reference parses with the configured fine-tuned endpoint; retain NER on failed or weaker reviews.
REF_NER_LLM_MIN_COVERAGE	float	0.8	Route references below this source-word coverage to fine-tuned review; this is a routing check, not confidence.
REF_NER_LLM_LONG_CHARS	int	1200	Route longer reference strings to fine-tuned review to check NER input-window loss.
REF_NER_LLM_MAX_REVIEWS	int	32	Maximum fine-tuned NER reviews per reference list; unrevised entries retain their NER parse.
REF_LLM_BASE_URL	str | None	None	OpenAI-compatible /v1 endpoint for the dedicated fine-tuned reference parser.
REF_LLM_MODEL	str | None	None	Served fine-tuned model or LoRA alias implementing ref-llm-sft@1; not the base model.
REF_LLM_API_KEY	str | None	None	Bearer credential for the dedicated reference parser endpoint.
REF_LLM_MAX_CONCURRENCY	int	4	Concurrent reference-parser requests per paper.
REF_LLM_TIMEOUT_SECONDS	float	30	Deadline for one reference-parser request.
REF_LLM_TOTAL_TIMEOUT_SECONDS	float	120	Total reference-parser request budget per paper; unfinished entries use NER.
REF_LLM_MAX_TOKENS	int	512	Output-token cap for one fine-tuned reference parse.
REF_LLM_MAX_INPUT_CHARS	int	4000	Maximum reference input size; longer entries use NER without silent truncation.
REF_PARSE_BATCH_SIZE	int	15	References per LLM parse call. Larger batches cut per-paper token cost near-proportionally (each call carries ~1.7k fixed schema/instruction tokens).
REF_PARSE_MAX_TOKENS	int	8192	Output-token cap for a single LLM ref-parse batch, overriding LLM_MAX_TOKENS for this call. Bounds degenerate generations to a fast, detectable truncation.
REF_GEOM_SEG_MODEL_ID	str	"scienceverse/bibr-geom-segmenter-v1"	HF Hub repo id for the local geometry reference segmenter (REF_SEG_STRATEGY=geom). Needs the ml extra. TRUST BOUNDARY: this is deserialized with joblib (executes code on load); a local path here is loaded via the gadget-restricted loader but must still be a checkpoint you control — never point it at an untrusted file.
REF_GEOM_SEG_REVISION	str	"4d1702e2c766d96c8887bd4b30ef56637aa9b32c"	Pinned commit revision for the geometry reference segmenter bundle.
REF_GEOM_SEG_CASCADE_THRESHOLD	float	0.9	Per-paper geometry confidence below which reference segmentation cascades to the LLM.
REF_GEOM_MIN_ALIGN_YIELD	float	0.5	Alignment-yield (aligned/labeled boundaries) below which the geometry segmenter declines regardless of confidence, cascading to the next tier.
REF_SPLIT_MERGED_REFS	bool	True	Split a reference string containing a second author-date onset before parsing (segmenter-agnostic, post-segmentation merged-reference splitter).
REF_FOOTNOTE_CITATIONS	bool	True	Read the reference list from the citations in the paper's footnotes and endnotes when no reference list is found, or one that parses to at most two references, and at least five notes cite works in full.
REF_SEG_REGION_ANCHORS	bool	True	Enable layout-region anchor segmentation, the zero-cost fallback tier between geom/LLM segmentation and the CRF last resort.
REF_SEG_LLM_FALLBACK	bool	True	Allow the token-costly LLM tier in the reference-segmentation fallback chain (geom decline -> region anchors -> LLM -> CRF). Off skips straight to CRF/marker-split.
REF_SEG_MIN_SOURCE_RECALL	float	0.6	Fraction of reference-section source records the region tier must recover as segments; below it, escalate to the LLM tier instead of accepting the segmentation. 0 disables the backstop.
REF_TRAINING_DATA_DIR	str | None	None	Directory to save raw bibliography text + LLM extracts as JSON pairs for reference-extraction model training. Unset disables capture.
NER_SEG_CKPT	str	"scienceverse/bibr-segmenter-v1"	Local path or HF Hub repo id for the NER reference-segmenter checkpoint (optionally suffixed :filename.pt).
NER_PARSER_CKPT	str	"scienceverse/bibr-parser-v5-1-ultrabert"	Local path or HF Hub repo id for the NER reference-parser checkpoint (optionally suffixed :filename.pt). Requires a v4-format checkpoint.
NER_SEG_REVISION	str	"344f27d851ffb901b2659629ac879f10b6eba234"	Pinned commit revision for the NER segmenter checkpoint. Set to "main" to track the latest revision instead.
NER_PARSER_REVISION	str	"97b06cc7dd6511bdd53f8855c93a29020231d215"	Pinned commit revision for the NER parser checkpoint. Set to "main" to track the latest revision instead; a parser repo that ships its own encoder code (v5) loads only from a commit SHA or a local directory.
NER_PARSER_ENCODER	str | None	None	Encoder (HF Hub repo id or local directory) whose config, modeling code and tokenizer the torch NER parser loads. Unset: the checkpoint's own (a parser repo with a config.json, at NER_PARSER_REVISION), else answerdotai/ModernBERT-base.
NER_PARSER_ENCODER_REVISION	str | None	None	Revision of NER_PARSER_ENCODER. An encoder with its own modeling code runs it only from a local directory or a commit SHA revision.
NER_DEVICE	str | None	None	Device for NER checkpoints: cpu, cuda, or mps (auto-detected if unset).
OCR_BASE_URL	str	"http://localhost:8080"	OCR server base URL (Docker Compose overrides this with its private bibr-ocr host).
SEGMENTER_SUB_BATCH_SIZE	int	32	Sub-batch size for sentence segmentation.
SEGMENTER_GPU_MEM_LIMIT_MB	int	0	GPU memory limit in MB for the sentence segmenter (0 = unlimited).
SEGMENTER_BATCH_TIMEOUT_MS	int	5	Coalescing window in milliseconds for the serve segmenter's GpuBatcher (0 = no coalescing wait, admission-gate only).
SEGMENTER_USE_GPU	bool | None	None	Run the serve sentence segmenter on GPU. Null = auto-detect (CUDA when onnxruntime exposes it). Force CPU only on VRAM-tight boxes that co-locate OCR.
GOOGLE_API_KEY	str | None	None	Google AI API key, for LLM_PROVIDER=google. Legacy aliases GEMINI_API_KEY and LANGEXTRACT_API_KEY also accepted. (aliases: GEMINI_API_KEY, LANGEXTRACT_API_KEY)
ANTHROPIC_API_KEY	str | None	None	Anthropic API key, for LLM_PROVIDER=anthropic. Alias CLAUDE_API_KEY also accepted. (aliases: CLAUDE_API_KEY)
GROQ_API_KEY	str | None	None	Groq API key, for LLM_PROVIDER=groq.