PDF ──> pdfmux router ──> best extractor per page ──> audit ──> re-extract failures ──> Markdown / JSON / chunks
 |
 ├─ PyMuPDF (digital text, 0.01s/page)
 ├─ OpenDataLoader (complex layouts, 0.05s/page)
 ├─ RapidOCR (scanned pages, CPU-only)
 ├─ Docling (tables, 97.9% TEDS)
 ├─ Surya (heavy OCR fallback)
 ├─ Marker (academic papers, neural)
 ├─ Mistral OCR ($0.002/page, 96.6% tables)
 └─ YOUR LLM (Gemini / Gemma 4 / Claude / GPT-4o / Ollama / Mistral — BYOK via YAML)

 ┌─────────────────────────────┐
 │ Segment Detector │
 │ text / tables / images / │
 │ formulas / headers per page │
 └─────────────┬───────────────┘
 │
 ┌────────────────────────────────────────┐
 │ Router Engine │
 │ │
 │ economy ── balanced ── premium │
 │ (minimize $) (default) (max quality)│
 │ budget caps: --budget 0.50 │
 └────────────────────┬───────────────────┘
 │
 ┌──────────┬──────────┬────────┴────────┬──────────┐
 │ │ │ │ │
 PyMuPDF OpenData RapidOCR Docling LLM
 digital Loader scanned tables (BYOK)
 0.01s/pg complex CPU-only 97.9% any provider
 layouts TEDS
 │ │ │ │ │
 └──────────┴──────────┴────────┬────────┴──────────┘
 │
 ┌────────────────────────────────────────┐
 │ Quality Auditor │
 │ │
 │ 4-signal dynamic confidence scoring │
 │ per-page: good / bad / empty │
 │ if bad -> re-extract with next backend│
 └────────────────────┬───────────────────┘
 │
 ┌────────────────────────────────────────┐
 │ Output Pipeline │
 │ │
 │ heading injection (font-size analysis)│
 │ table extraction + normalization │
 │ text cleanup + merge │
 │ confidence score (honest, not inflated)│
 └────────────────────────────────────────┘

pdfmux convert [options]

Options:
 -o, --output PATH Output file or directory
 -f, --format FORMAT markdown | json | csv | llm (default: markdown)
 -q, --quality QUALITY fast | standard | high (default: standard)
 -s, --schema SCHEMA JSON schema file or preset (invoice, receipt, contract, resume, paper)
 --chunk Output RAG-ready chunks
 --max-tokens N Max tokens per chunk (default: 500)
 --mode MODE economy | balanced | premium (default: balanced)
 --budget AMOUNT Max spend per document in USD
 --llm-provider PROVIDER LLM backend: gemini | claude | openai | ollama
 --confidence Include confidence score in output
 --stdout Print to stdout instead of file

pdfmux serve # stdio mode (Claude Desktop, Cursor)
pdfmux serve --http 8080 # HTTP mode

pdfmux doctor
# ┌──────────────────┬─────────────┬─────────┬──────────────────────────────────┐
# │ Extractor │ Status │ Version │ Install │
# ├──────────────────┼─────────────┼─────────┼──────────────────────────────────┤
# │ PyMuPDF │ installed │ 1.25.3 │ │
# │ OpenDataLoader │ installed │ 0.3.1 │ │
# │ RapidOCR │ installed │ 3.0.6 │ │
# │ Docling │ missing │ -- │ pip install pdfmux[tables] │
# │ Surya │ missing │ -- │ pip install pdfmux[ocr-heavy] │
# │ LLM (Gemini) │ configured │ -- │ GEMINI_API_KEY set │
# └──────────────────┴─────────────┴─────────┴──────────────────────────────────┘

pdfmux benchmark report.pdf
# ┌──────────────────┬────────┬────────────┬─────────────┬──────────────────────┐
# │ Extractor │ Time │ Confidence │ Output │ Status │
# ├──────────────────┼────────┼────────────┼─────────────┼──────────────────────┤
# │ PyMuPDF │ 0.02s │ 95% │ 3,241 chars │ all pages good │
# │ Multi-pass │ 0.03s │ 95% │ 3,241 chars │ all pages good │
# │ RapidOCR │ 4.20s │ 88% │ 2,891 chars │ ok │
# │ OpenDataLoader │ 0.12s │ 97% │ 3,310 chars │ best │
# └──────────────────┴────────┴────────────┴─────────────┴──────────────────────┘

pdfmux estimate report.pdf --quality high --llm-provider gemini
# Pages : 47
# Extractors : pymupdf4llm + gemini-2.5-flash on 9 pages
# Estimated : $0.0234
# Cache hit? : no (first run for this file)

pdfmux stream long.pdf --quality high
# {"event":"classified","page_count":312,"plan":"pymupdf+gemini-fallback"}
# {"event":"page","page_num":0,"confidence":0.97,"chars":1842}
# {"event":"page","page_num":1,"confidence":0.92,"chars":1611,"ocr":true}
# ...
# {"event":"complete","confidence":0.94,"cost_usd":0.0712}

pdfmux watch ./inbox/ -o ./output/ --profile bulk-rag

pdfmux diff a.pdf b.pdf --quality standard

pdfmux profiles list
# invoices quality=standard, schema=invoice, format=json
# receipts quality=fast, schema=receipt, format=json
# papers quality=high, chunk=true, max_tokens=500
# contracts quality=high, schema=contract
# bulk-rag quality=standard, format=llm, chunk=true

pdfmux profiles show invoices
pdfmux profiles save my-default --quality high --format llm --chunk
pdfmux profiles delete my-default

# use a profile when converting
pdfmux convert file.pdf --profile invoices

import pdfmux

text = pdfmux.extract_text("report.pdf") # -> str (markdown)
text = pdfmux.extract_text("report.pdf", quality="fast") # PyMuPDF only, instant
text = pdfmux.extract_text("report.pdf", quality="high") # LLM-assisted

data = pdfmux.extract_json("report.pdf")
# data["page_count"] -> 12
# data["confidence"] -> 0.91
# data["ocr_pages"] -> [2, 5, 8]
# data["pages"][0]["key_values"] -> [{"key": "Date", "value": "2026-02-28"}]
# data["pages"][0]["tables"] -> [{"headers": [...], "rows": [...]}]

chunks = pdfmux.chunk("report.pdf", max_tokens=500)
for c in chunks:
 print(f"{c['title']}: {c['tokens']} tokens (pages {c['page_start']}-{c['page_end']})")

data = pdfmux.extract_json("invoice.pdf", schema="invoice")
# Uses built-in invoice preset: extracts date, vendor, line items, totals
# Also accepts a path to a custom JSON Schema file

from pdfmux.extractors import get_extractor

ext = get_extractor("fast")
for page in ext.extract("large-500-pages.pdf"): # Iterator[PageResult]
 process(page.text) # constant memory, even on 500-page PDFs

from pdfmux import (
 # Enums
 Quality, # FAST, STANDARD, HIGH
 OutputFormat, # MARKDOWN, JSON, CSV, LLM
 PageQuality, # GOOD, BAD, EMPTY

 # Data objects (frozen dataclasses)
 PageResult, # page: text, page_num, confidence, quality, extractor
 DocumentResult, # document: pages, source, confidence, extractor_used
 Chunk, # chunk: title, text, page_start, page_end, tokens

 # Errors
 PdfmuxError, # base -- catch this for all pdfmux errors
 FileError, # file not found, unreadable, not a PDF
 ExtractionError, # extraction failed
 ExtractorNotAvailable,# requested backend not installed
 FormatError, # invalid output format
 AuditError, # audit could not complete
)

pip install langchain-pdfmux

from langchain_pdfmux import PDFMuxLoader

loader = PDFMuxLoader("report.pdf", quality="standard")
docs = loader.load() # -> list[Document] with confidence metadata

pip install llama-index-readers-pdfmux

from llama_index.readers.pdfmux import PDFMuxReader

reader = PDFMuxReader(quality="standard")
docs = reader.load_data("report.pdf") # -> list[Document]

{
 "mcpServers": {
 "pdfmux": {
 "command": "npx",
 "args": ["-y", "pdfmux-mcp"]
 }
 }
}

claude mcp add pdfmux -- npx -y pdfmux-mcp

# Default install — already includes python-bidi for RTL reordering
pip install pdfmux

# Recommended for Arabic-heavy docs — adds Gemma 4 vision OCR
pip install "pdfmux[arabic,llm-gemma]"

# One credential covers Gemma + Gemini (same Google endpoint)
export GEMINI_API_KEY=...

from pdfmux.arabic import (
 is_arabic_text,
 is_rtl_dominant,
 fix_bidi_order,
 normalize_arabic,
)

text = "مرحبا بالعالم"
assert is_arabic_text(text)
assert is_rtl_dominant(text)

# Fix glyph order from PyMuPDF / OCR engines
visual = fix_bidi_order(text)

# Canonicalize for indexing — strip Tatweel, unify Alef variants, drop diacritics
indexable = normalize_arabic("أَحْمَدْ") # → "احمد"

pdfmux convert big-report.pdf # first run: 14.2s
pdfmux convert big-report.pdf # cache hit: 0.05s
pdfmux convert big-report.pdf --no-cache # bypass cache (still writes back)
pdfmux convert big-report.pdf --clear-cache # purge and re-run

Page 4: 32% confidence. 0 chars extracted from image-heavy page.
 -> Install pdfmux[ocr] for RapidOCR support on 6 image-heavy pages.

git clone https://github.com/NameetP/pdfmux.git
cd pdfmux
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest # 659 tests
ruff check src/ tests/
ruff format src/ tests/

pip install pdfmux

pip install "pdfmux[ocr]" # ⭐ recommended — RapidOCR for scanned pages (~200MB, CPU)

pip install "pdfmux[tables]" # Docling — table-heavy docs (~500MB)
pip install "pdfmux[opendataloader]" # OpenDataLoader — complex layouts (Java 11+)
pip install "pdfmux[marker]" # Marker — neural extraction for academic papers
pip install "pdfmux[llm]" # Gemini fallback (default LLM)
pip install "pdfmux[llm-claude]" # Claude (Sonnet / Opus)
pip install "pdfmux[llm-openai]" # GPT-4o family
pip install "pdfmux[llm-ollama]" # Ollama (any local model)
pip install "pdfmux[llm-mistral]" # Mistral OCR API ($0.002/page)
pip install "pdfmux[llm-all]" # all LLM providers (incl. Gemma 4 via Gemini key)
pip install "pdfmux[watch]" # `pdfmux watch ` auto-convert on change
pip install "pdfmux[all]" # everything

# zero config — just works
pdfmux convert invoice.pdf
# invoice.pdf -> invoice.md (2 pages, 95% confidence, via pymupdf4llm)

# RAG-ready chunks with token limits
pdfmux convert report.pdf --chunk --max-tokens 500

# cost-aware extraction with budget cap
pdfmux convert report.pdf --mode economy --budget 0.50

# schema-guided structured extraction (5 built-in presets)
pdfmux convert invoice.pdf --schema invoice

# BYOK any LLM for hardest pages
pdfmux convert scan.pdf --llm-provider claude

# use a built-in or saved profile (invoices, receipts, papers, contracts, bulk-rag)
pdfmux convert invoice.pdf --profile invoices

# predict cost before running anything
pdfmux estimate big-report.pdf --llm-provider gemini

# stream pages as NDJSON as they finish (great for long documents)
pdfmux stream report.pdf --quality high

# auto-convert any new PDFs that land in a folder
pdfmux watch ./inbox/ -o ./output/

# diff two extractions side-by-side
pdfmux diff old.pdf new.pdf

# batch a directory — writes manifest.json with per-doc confidence
pdfmux convert ./docs/ -o ./output/

# CI mode: fail the run if any document is below 0.20 confidence
pdfmux convert ./docs/ -o ./output/ --strict --min-confidence 0.20

# pre-flight a directory: which extras do you actually need for THIS batch?
pdfmux doctor --check ./docs/

# results are cached by file hash — re-runs are instant; bypass with --no-cache
pdfmux convert report.pdf --no-cache
pdfmux convert report.pdf --clear-cache

import pdfmux
from pathlib import Path

# Batch extract — yields (path, result) tuples as each PDF completes.
pdfs = list(Path("./inbox").glob("*.pdf"))
for path, result in pdfmux.batch_extract(pdfs, quality="standard"):
 if isinstance(result, Exception):
 print(f"FAILED {path.name}: {result}")
 continue
 if result.confidence 
 **Don't wrap pdfmux with your own pypdf/pdfplumber fallback.** pdfmux already routes per page through PyMuPDF → RapidOCR → vision LLM. PyMuPDF tolerates malformed PDFs that pypdf rejects ("Stream has ended unexpectedly"), so a downstream pypdf fallback turns recoverable PDFs into failures. Trust the router; check the confidence score on the result.

## BYOK LLM Configuration

pdfmux supports any LLM via 5 lines of YAML. Bring your own keys -- nothing leaves your machine unless you configure it to.

 Supported providers:

 Provider Models Local? Cost 
 Gemini 2.5 Flash, 2.5 Pro No ~$0.01/page 
 Gemma 4 27B IT, 12B IT (great for Arabic) No (via Gemini key) ~$0.005/page 
 Claude Sonnet, Opus No ~$0.015/page 
 GPT-4o GPT-4o, GPT-4o-mini No ~$0.01/page 
 Mistral `mistral-ocr-latest` No $0.002/page 
 Ollama Any local model Yes Free 
 Custom Any OpenAI-compatible API Configurable Varies 
 

 Every provider's `extract_page()` is wrapped in `@with_retry(max_attempts=3, backoff_base=2.0)`, which honors `Retry-After` headers on 429s and skips
retries on auth failures so a bad key fails fast.