pdfmux

pdfmux

Self-healing PDF extraction that flags the pages it can't read instead of dropping them — and now certifies any extractor's output for silent drops. Open-source LlamaParse alternative for RAG pipelines, MCP server for Claude Desktop, LangChain + LlamaIndex loaders.

pdfmux extracts PDFs and checks its own work — and now certifies any extractor's, telling you which pages it silently dropped. Free, MIT. Patent-pending method. pip install pdfmux.

Two jobs, one tool:

• Self-healing extraction. The only PDF extractor that audits its own output. Catches blank pages, scrambled columns, broken tables — re-extracts them with a stronger backend, and flags what it still can't read instead of silently dropping it. So your LLM gets clean data, not silent garbage. Routes each page to the best of 7 built-in extraction backends + BYOK LLM fallback (Gemini / Claude / GPT-4o / Ollama). One CLI. One API. Zero config.
• [Certify Anything](#certify-anything) — new in v1.8.1. pdfmux verify audits *any* extraction engine's output against the source PDF — Reducto, Mistral OCR, LlamaParse, Docling, your in-house parser — and tells you which pages it silently dropped. Free, MIT, patent-clean.

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 3 / Claude / GPT-4o / Ollama / Mistral — BYOK via YAML)

Install

pip install pdfmux

That handles digital PDFs. For any real-world batch, install `pdfmux[ocr]` too — almost every directory of PDFs has at least one scan, and without OCR those pages return empty text:

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

Other backends, by document type:

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 via Gemini key) pip install "pdfmux[watch]" # pdfmux watch auto-convert on change pip install "pdfmux[all]" # everything

Requires Python 3.11+.

Quick Start

CLI

# 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

Python

For batch processing, use batch_extract() — not a subprocess.run(['pdfmux', ...]) loop. Same pipeline, no per-file process spawn, handles non-ASCII filenames:

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 < 0.50: print(f"REVIEW {path.name} ({result.confidence:.2f})") else: print(f"OK {path.name} ({result.confidence:.2f})")

Single-file helpers.

text = pdfmux.extract_text("report.pdf") # markdown string data = pdfmux.extract_json("report.pdf") # locked schema dict chunks = pdfmux.chunk("report.pdf", max_tokens=500) # RAG-ready chunks

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.

Certify Anything

pdfmux verify audits any extraction engine's output against the source PDF and tells you which pages it silently dropped — not just pdfmux's own extraction. Point it at the output of Reducto, Mistral OCR, LlamaParse, Docling, or your in-house parser and it re-derives the source text with pdfmux's own audit pass, aligns the extraction to it, and scores every page.

The failure it catches: a page where the source has real text but the engine returned nothing — while reporting success. That "silent drop" is the exact failure that poisons a RAG index without a single error in the logs.

# Certify pdfmux's own extraction of a document

pdfmux verify --source report.pdf --engine pdfmux

Certify ANOTHER engine's output (JSON / Markdown / text)

pdfmux verify --source report.pdf --extracted reducto.json --engine-name reducto

Batch a whole directory — the "M pages silently dropped across N docs" report

pdfmux verify --source ./pdfs/ --extracted ./engine-outputs/ -o certification.json

CI gate: exit non-zero unless the overall verdict is PASS

pdfmux verify --source report.pdf --extracted out.json --strict

Every run prints a PASS / REVIEW / FAIL verdict, overall confidence and coverage, and — when it finds them — the silently dropped pages by number:

pdfmux verify — report.pdf · engine: reducto

FAIL confidence 71% · coverage 68% reducto: FAIL; 3 page(s) SILENTLY DROPPED (pages 7, 12, 31); overall confidence 71%, coverage 68% across 40 page(s).

❌ 3 page(s) SILENTLY DROPPED: 7, 12, 31

Per page you get a verdict (pass / review / fail), confidence, coverage, alignment, hallucination-risk, and table/heading integrity. Batch mode rolls that up into a single "N pages silently dropped across M documents" line — the report you run on 100 of your own PDFs to find the silent failures already in your pipeline.

It works on any engine's output

--extracted accepts JSON, Markdown, or plain text (--extracted-format auto | json | markdown | text). When the extraction exposes real per-page structure, pdfmux compares page-by-page; when it's a single blob, it falls back to content-presence checks so it never fabricates a "silent drop" from a pagination mismatch.

Python API

from pdfmux import verify_extraction, verify_batch

Single document → a CertificationManifest

manifest = verify_extraction("report.pdf", "reducto.json", engine="reducto") print(manifest.verdict) # "PASS" | "REVIEW" | "FAIL" print(manifest.silent_drops) # e.g. (7, 12, 31) — 1-indexed page numbers print(manifest.coverage) # 0.0–1.0

Many documents → a BatchCertification ("M pages dropped across N docs")

batch = verify_batch([("a.pdf", "a.json"), ("b.pdf", "b.json")], engine="llamaparse") print(batch.total_silent_drops, "pages dropped across", batch.doc_count, "docs")

Each manifest carries a tamper-evident SHA-256 content signature over its canonical body and an embedded, honest limitations list: the certifier is lexical, not linguistic — it detects missing and garbled content, not faithful paraphrase or translation.

MCP

verify_extraction is exposed as an MCP tool (the 7th — see MCP Server), so an agent can certify an engine's output in the same session it extracts.

Free, MIT, patent-clean

Certify Anything reuses only pdfmux's shipped MIT audit layer. It does not include, and does not require, the patent-pending decision-trace method — that stays in pdfmux Cloud/Pro. pip install pdfmux gives you the full verify command at no cost.

Full reference: [docs/CERTIFY-ANYTHING.md](docs/CERTIFY-ANYTHING.md).

When you need to prove it to someone else

A local install can audit an extraction, but it cannot *attest* to one — anything it signs, anyone could forge. pdfmux Cloud returns an Ed25519-signed manifest over the extraction: your auditor verifies it offline, against a published public key, without an account and without trusting pdfmux.

pdfmux verify-manifest manifest.json      # free, MIT, offline — no account

Verification is free and open forever; only *generation* is paid ($49/mo). That asymmetry is deliberate — you should never need our permission to check our work.

Free tool, no signup: [app.pdfmux.com/audit](https://app.pdfmux.com/audit) — upload a PDF and see which pages your current extractor silently dropped. Measured accuracy (and its blind spots) published in pdfmux-bench.

Architecture

                           ┌─────────────────────────────┐

│ Segment Detector │ │ text / tables / images / │ │ formulas / headers per page │ └─────────────┬───────────────┘ │ ┌────────────────────────────────────────┐ │ Router Engine │ │ │ │ economy ── balanced ── premium │ │ (minimize $) (default) (max quality)│ │ budget caps: --budget 0.50 │ └────────────────────┬───────────────────┘ │ ┌──────────┬──────