PuffinParse

import puffinparse
doc = puffinparse.parse("invoice.pdf", model="reducto/standard")
print(doc.markdown, doc.cost_usd)

One API for every document parser: parse, OCR and extract. Rust core, Python and TypeScript SDKs, a CLI, a self-hosted gateway, and an open benchmark that ranks providers on accuracy, latency and cost.

import puffinparse

doc = puffinparse.parse("invoice.pdf", model="reducto/standard")     # or "extend/parse_performance", "llamaparse/agentic", ...
print(doc.markdown)                                              # unified markdown, every provider
print(doc.pages[0].blocks[0].bbox, doc.usage.pages, doc.cost_usd)

text = puffinparse.ocr("scan.png", model="llamaparse/fast")          # plain text + line/word boxes
print(text.text, text.pages[0].lines[0].bbox)

Switch providers by changing one string. Same request, same response shape, same errors.

Why#

Every document-parsing vendor has its own upload flow, polling loop, JSON layout, block vocabulary, coordinate system and billing unit. PuffinParse hides all of that behind one call, tracks cost per call, retries and falls back across providers, and ships a reproducible benchmark so you can pick a provider on evidence instead of marketing.

Two things make switching real rather than aspirational. Modes: every call names parse, ocr or extract, models declare the modes they serve, and a model that cannot serve the one you asked for fails before any network call — so a provider swap can never quietly change the shape of your answer. Native-format compatibility: if you are already integrated with Reducto, Extend or LlamaParse, output_format="reducto" (and friends) renders any provider's result into that vendor's own JSON, so you can re-point a request without touching your parsing code — see below.

Install#

pip install puffinparse              # Python SDK (abi3 wheels: Linux, macOS, Windows)
npm install puffinparse              # Node.js SDK (prebuilt for Linux x64/arm64 glibc, macOS, Windows x64)
cargo install puffinparse-cli        # CLI + gateway; or grab an archive from GitHub Releases
docker pull ghcr.io/ajinkyashejul/puffinparse   # gateway image

Set the keys for the providers you use:

export REDUCTO_API_KEY=...
export EXTEND_API_KEY=...
export LLAMA_API_KEY=llx-...      # LlamaCloud / LlamaParse

No key yet? The self-hosted engines work out of the box once installed:

sudo apt-get install tesseract-ocr poppler-utils     # or: brew install tesseract poppler
puffinparse ocr scan.png -m tesseract                    # free, local, word boxes + confidences

Every provider reads its own variable: .env.example lists all of them, the model tables say which belongs to which provider, and puffinparse providers shows which ones are set in your shell.

From source (Rust stable + Python 3.9+):

git clone https://github.com/ajinkyashejul/puffinparse && cd puffinparse
python -m venv .venv && . .venv/bin/activate
pip install maturin && maturin develop --release     # builds the extension into the venv
cargo build --release -p puffinparse-cli                 # ./target/release/puffinparse

Modes#

Document AI vendors sell three different products, and they are not interchangeable: layout parsing, plain-text OCR, and schema-driven extraction. A call picks one mode, and the mode decides the response type:

Providers are swappable only within a mode. Every model declares the modes it serves, so a model that cannot do what you asked raises UnsupportedModelError before any network call instead of silently returning the wrong shape. puffinparse.list_models("ocr") lists the candidates for a mode; puffinparse providers --mode ocr does the same on the command line. Providers without a native OCR endpoint serve ocr from their parse output, flagged as resp.metadata["puffinparse_derived_from"] == "parse".

Which models serve which mode is a registry fact, not a guess — ask puffinparse.list_models("extract") or puffinparse providers --mode extract. Most providers serve parse and ocr; extract needs a model built for it (reducto/extract, extend/extraction_light, azure/invoice, the vision-LLM models, ...), and calling it with a parse-only model raises UnsupportedModelError naming the mode.

Usage#

One call, any provider#

import puffinparse

# path, URL, or bytes (+ filename)
doc = puffinparse.parse("contract.pdf", model="extend/parse_performance")
doc = puffinparse.parse("https://cdn.reducto.ai/samples/fidelity-example.pdf", model="reducto/r-1", pages="1-2")
doc = puffinparse.parse(open("scan.png", "rb").read(), filename="scan.png", model="llamaparse/agentic")

doc.markdown            # whole document
doc.text                # plain text
doc.pages[0].markdown   # per page
for block in doc.pages[0].blocks:
    block.type           # text | title | section_header | list | table | figure | header | footer | ...
    block.content        # markdown
    block.bbox           # BBox(x0, y0, x1, y1) normalised 0..1, origin top-left (or None)
    block.confidence     # 0..1 when the provider reports one
doc.usage.pages, doc.usage.credits, doc.cost_usd, doc.latency_ms

Plain text and boxes (ocr)#

text = puffinparse.ocr("scan.png", model="reducto/standard")

text.text                     # whole document, pages joined by a blank line
page = text.pages[0]
page.text                     # plain text in reading order
for line in page.lines:       # Line(text, bbox, confidence)
    x0, y0, x1, y1 = line.bbox.to_pixels(page.width, page.height)
for word in page.words:       # Word(text, bbox, confidence)
    ...

Structured extraction (extract)#

schema = {
    "type": "object",
    "properties": {"invoice_number": {"type": "string"}, "total": {"type": "number"}},
    "required": ["invoice_number", "total"],
}
result = puffinparse.extract("invoice.pdf", schema, model="...", citations=True)

result.data                          # {"invoice_number": "INV-42", "total": 1280.5}
result.fields["/total"].confidence   # per-field confidence, keyed by JSON pointer
result.citations("/total")           # [Citation(page_number=2, bbox=..., text="Total due 1,280.50")]

Async#

doc = await puffinparse.aparse("contract.pdf", model="llamaparse/cost_effective")
text = await puffinparse.aocr("scan.png", model="llamaparse/fast")

Runs on the Rust runtime; the event loop is never blocked.

Long documents: jobs and webhooks#

parse waits for the provider. For long documents, batches or webhook-driven pipelines, split it:

job = puffinparse.submit("annual-report.pdf", model="reducto/standard",
                     webhook_url="https://example.com/hooks/puffinparse")   # optional
store(job)                                  # a Job is plain data: serialisable, holds no key

result = puffinparse.retrieve(job)              # Job (still pending) or ParseResponse
# ...or, in your web handler, turn the provider's webhook body into a result:
result = puffinparse.handle_webhook(request.json(), model="reducto")  # verify the signature first

Reducto, Extend and LlamaParse support jobs; webhook_url maps to each provider's per-job webhook where one exists (Extend only has workspace-level webhooks, so it is rejected there). See docs/SPEC.md §15.

TypeScript / Node.js#

The same core as a napi-rs addon, with camelCase typed responses:

import { parse, Router } from "puffinparse";

const doc = await parse("invoice.pdf", { model: "reducto/standard", fallbacks: ["llamaparse/agentic"] });
console.log(doc.markdown, doc.usage.pages, doc.costUsd);

npm install puffinparse ships prebuilt binaries for Linux x64/arm64 (glibc), macOS and Windows x64; other platforms build from source (cd js && npm ci && npm run build), see js/README.md.

Model names#

"<provider>/<model>", like LiteLLM. A bare provider name picks that provider's default model for the mode you called — marked * below. puffinparse providers and puffinparse.list_models(mode) print the live list; the tables here are the built-in registry (crates/puffinparse-core/src/model.rs and pricing.json).

Prices are public pay-as-you-go list prices, per page, per mode, shown as parse · ocr · extract with — where a model does not serve that mode. Override one mode at a time with puffinparse.set_pricing({"reducto/standard": 0.012}, "parse"), and estimate with puffinparse.estimate_cost("reducto/standard", pages=1000, mode="ocr"). The vision-LLM providers (Gemini, OpenAI, Anthropic) bill tokens rather than pages, so their per-page numbers are estimates — see the source lines in pricing.json.

Each provider carries one of three verification labels:

• live-verified: the live tests pass against the real API with a key, and the fixtures include redacted live responses (Reducto, Extend, LlamaParse).
• verified locally: a self-hosted engine whose live tests pass against a local install (Tesseract, Docling).
• docs-only: implemented from the provider's API documentation and tested against fixture payloads built from it, but not yet run against the live API. Expect wire-format differences until it is verified; issue #10 tracks this, and a run with your own key is a welcome contribution.

docs/providers/README.md tracks the state and links one reference page per provider.

Reducto · REDUCTO_API_KEY · live-verified — Layout parsing plus a schema extractor with citations; the default parse target.

Extend · EXTEND_API_KEY · live-verified — Parse engines that trade accuracy for cost per page, and two extraction processors.

LlamaParse (LlamaCloud) · LLAMA_API_KEY · live-verified — Credit-priced tiers from plain text extraction to agentic parsing; extract from cost_effective up.

Mistral Document AI · MISTRAL_API_KEY · docs-only — One OCR model with pinned versions; annotations give it an extract mode.

Azure AI Document Intelligence · AZURE_DOCUMENT_INTELLIGENCE_KEY (+ AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT) · docs-only — Prebuilt Document Intelligence models: read for OCR, layout for structure, fixed schemas for extraction.

AWS Textract · AWS_ACCESS_KEY_ID (+ AWS_SECRET_ACCESS_KEY, AWS_REGION) · docs-only — One AWS API, four feature sets; SigV4-signed, no SDK.

Google Gemini · GEMINI_API_KEY · docs-only — Vision-LLM transcription. Prices are per-page estimates (~1500 in + ~800 out tokens); cost_usd uses them until the response reports real usage.

OpenAI · OPENAI_API_KEY · docs-only — Vision transcription through the Responses API. Per-page prices are estimates, as for Gemini.

Anthropic (Claude) · ANTHROPIC_API_KEY · docs-only — Vision transcription through the Messages API. Per-page prices are estimates.

Mathpix · MATHPIX_APP_KEY (+ MATHPIX_APP_ID) · docs-only — Maths-first OCR: Mathpix Markdown with LaTeX, line and word polygons.

Datalab (Marker) · DATALAB_API_KEY · docs-only — Marker's hosted API: three quality modes at two price points.

Unstructured · UNSTRUCTURED_API_KEY · docs-only — The partitioner behind many RAG pipelines; flat per-page price across strategies.

Upstage Document Parse · UPSTAGE_API_KEY · docs-only — Korean/English layout parsing to HTML or markdown.

Landing AI (Agentic Document Extraction) · LANDINGAI_API_KEY · docs-only — Agentic Document Extraction (DPT-2): parse, then extract against your schema.

Google Cloud Document AI · GOOGLE_DOCUMENTAI_ACCESS_TOKEN (+ GOOGLE_DOCUMENTAI_PROJECT, _LOCATION, _PROCESSOR_ID) · docs-only — Processor-based: pick the processor id in provider_options; OCR, layout, forms and prebuilt extractors.

Self-hosted engines · no key · $0/page — out-of-process: a local binary or a server you run. Tesseract and Docling are verified locally; PaddleOCR is docs-only.

Keep your Reducto / Extend / LlamaParse code#

Already integrated with a vendor? Ask for its shape and PuffinParse renders the response into that vendor's own JSON, whatever provider actually ran the call — switch the model string, keep your parser:

doc = puffinparse.parse("invoice.pdf", model="extend/parse_light", output_format="reducto")
block = doc["result"]["chunks"][0]["blocks"][0]            # Reducto's shape, Extend's engine
draw(block["bbox"]["left"], block["bbox"]["top"], block["type"])

output_format accepts reducto, extend, llamaparse, or puffinparse (the unified shape, and the default). It returns a plain dict instead of a dataclass, and works on parse, extract, their async variants, the Router, and the CLI (--output-format <vendor> with --format json). An unknown name raises BadRequestError before any network call.

What is guaranteed is structural fidelity — key set and nesting, one chunk/page per page, the content strings, the vendor's own block vocabulary and coordinate units, the billed page count — not byte equality with what the vendor would have returned. Fields PuffinParse does not model (presigned URLs, studio links, billing breakdowns, OCR word layers) are null or empty, and a few block types are lossy. docs/COMPAT.md enumerates all of it, per format; examples/switch_provider_keep_format.py is a runnable version of the above.

Provider-specific options#

Anything the common request doesn't cover is passed through verbatim:

puffinparse.parse("doc.pdf", model="reducto/standard",
              provider_options={"settings": {"return_ocr_data": True}, "async": True})
puffinparse.parse("doc.pdf", model="extend/parse_performance",
              provider_options={"blockOptions": {"figures": {"enabled": False}}})
puffinparse.ocr("doc.pdf", model="llamaparse/agentic",
            provider_options={"take_screenshot": True, "version": "2026-08-19"})

include_raw=True attaches the provider's original payload as resp.raw.

Router: fallbacks and load balancing#

router = puffinparse.Router(
    ["reducto/standard", "llamaparse/agentic", "extend/parse_light"],
    mode="parse",                # the mode every model must serve; "ocr" and "extract" too
    strategy="ordered",          # or "round_robin"
)
resp = router.parse("doc.pdf")   # falls back on provider / rate-limit / timeout / network errors
router.stats()                   # per-model successes, failures, latency, cost, pages

A router is bound to one mode: Router([...], mode="parse").ocr(...) raises InputError rather than quietly changing the answer's shape, and every model is validated against the mode when the router is built. Auth, bad-request and input errors never trigger a fallback.

Errors#

All errors derive from puffinparse.PuffinParseError and carry provider, status_code, job_id and retryable:

AuthenticationError, RateLimitError, BadRequestError, ProviderError, TimeoutError, UnsupportedModelError, InputError, NetworkError.

UnsupportedModelError also covers a model asked to do a mode it does not serve; the message names the mode and the models that do serve it.

Callbacks and logging#

Callbacks fire for every mode, with that mode's response object:

puffinparse.success_callback.append(lambda r: print(r.model, r.usage.pages, r.cost_usd))
puffinparse.failure_callback.append(lambda e: print("failed:", e))
puffinparse.init_logging("debug")    # Rust core tracing on stderr (or PUFFINPARSE_LOG=debug for the CLI)

CLI#

puffinparse providers                                             # models, modes, prices, key status
puffinparse providers --mode ocr                                  # only models that serve a mode
puffinparse parse invoice.pdf -m extend/parse_light               # markdown to stdout
puffinparse parse scan.png -m llamaparse/agentic -f json --raw    # full unified JSON (+ provider payload)
puffinparse parse doc.pdf -m extend/parse_light -f json \
    --output-format reducto                                   # ... in Reducto's response shape
puffinparse parse doc.pdf -m reducto/r-1 --pages 1-3 -f text
puffinparse ocr scan.png -m reducto/standard                      # plain text to stdout
puffinparse ocr scan.png -f json                                  # TextResponse: text + lines + words
puffinparse extract invoice.pdf -s schema.json --citations        # JSON object from a schema
puffinparse extract invoice.pdf -s '{"type":"object"}'            # inline schema also works
puffinparse extract invoice.pdf -s schema.json --output-format extend   # Extend's extract_run shape
puffinparse providers --json | jq '.output_formats'               # the vendor shapes this build renders

Gateway server#

Run PuffinParse as one HTTP endpoint so applications never hold provider keys:

puffinparse serve --config puffinparse.toml       # or: docker run ghcr.io/ajinkyashejul/puffinparse (docs/SERVER.md)
curl -H "Authorization: Bearer $TEAM_KEY" -F file=@invoice.pdf -F model=invoices \
     http://localhost:4000/v1/parse

puffinparse.toml defines aliases (invoices = [reducto/standard, extend/parse_performance] with ordered or round-robin fallback), provider keys as env: references, and virtual keys with model allow-lists, monthly USD budgets and per-minute limits. /v1/models, /v1/usage, /health and Prometheus /metrics are built in; request logs are JSON lines that never contain document content or secrets. Reference: docs/SERVER.md, sample: examples/server/puffinparse.toml.

Rust#

use puffinparse_core::{extract, ocr, parse, DocumentRequest, ExtractRequest};

let doc = parse(DocumentRequest::from_path("invoice.pdf").model("reducto/standard")).await?;
println!("{} pages, ${:.4}\n{}", doc.usage.pages, doc.cost_usd.unwrap_or(0.0), doc.markdown);

let text = ocr(DocumentRequest::from_path("scan.png").model("llamaparse/fast")).await?;
println!("{} lines on page 1", text.pages[0].lines.len());

let req = ExtractRequest::new(DocumentRequest::from_path("invoice.pdf").model("..."), schema);
let data = extract(req.citations(true)).await?.data;

Benchmark#

PuffinParse ships an open, reproducible benchmark. Ground truth is exact by construction (the documents are rendered from the same source as the truth files), metrics are deterministic text comparisons, and every run records the dataset hash, model, latency and cost.

python benchmark/generate_synthetic.py                       # regenerate the dataset (byte-reproducible)
puffinparse bench run --dataset benchmark/datasets/synthetic-v1 \
    --models reducto/standard extend/parse_performance llamaparse/cost_effective
puffinparse bench report benchmark/results/*.json > benchmark/LEADERBOARD.md
puffinparse bench score prediction.md truth.md                   # metrics for one pair, no network

Metrics (after NFKC + markdown stripping + whitespace collapsing, case-insensitive by default):

• Overall = 100 × mean(char_similarity), where char_similarity = 1 − levenshtein / max(len)
• CER, WER, word F1 (bag-of-words precision / recall)
• Order: Kendall-τ-style agreement of shared line order (reading order)
• Table: character similarity restricted to markdown table rows
• Latency p50 / p95 and ms per page; $/1k pages from the price table

The current leaderboard is in benchmark/LEADERBOARD.md, and every document, output, diff and rule check is browsable at puffinparse.com/benchmark-results. Datasets: synthetic-v1 (exact truth by construction) and the headline combined-v3, which adds subsets of ParseBench, olmOCR-bench, OmniDocBench and DP-Bench converted by benchmark/adapters/ at pinned revisions. Older combined-v1 and combined-v2 runs are kept for comparison. Long runs are safe: --dry-run and --max-cost show and cap the spend before any call, and --resume continues an interrupted run.

How it maps providers#

Full details, including the exact wire formats verified against live responses, are in docs/SPEC.md.

Project layout#

crates/puffinparse-core     Rust library: types, providers, router, pricing, benchmark metrics
crates/puffinparse-cli      `puffinparse` binary
crates/puffinparse-python   PyO3 extension (puffinparse._core)
crates/puffinparse-node     napi-rs addon for the Node.js SDK
crates/puffinparse-server   HTTP gateway behind `puffinparse serve`
python/puffinparse          Python package (typed public API)
js/                     Node.js / TypeScript package
benchmark/              dataset generator, adapters, datasets, results, leaderboard, viewer
docs/SPEC.md            specification

Roadmap#

Planned work is tracked in GitHub Issues. Open items:

• Packaging: publish 0.1.0 to PyPI, npm and crates.io with prebuilt wheels, addons and CLI binaries (#9).
• Providers: live-verify the docs-only providers (#10), including PaddleOCR against a real server (#17).
• Benchmark: add tesseract/default (#11) and docling/default with a hardware note (#12) to combined-v3; regenerate the leaderboard in one command (#13); score table-cell neighbour relations exactly (#15); a READoc long-document track (#16).
• SDK: output_format="mistral" for code written against Mistral OCR responses (#14).
• Playground: upload a document and compare up to three models side by side (#18).

Support#

PuffinParse is built in the open by one person. If it saved you time, a star on GitHub helps other developers find it. Reports of a wrong score, a missing provider or a confusing doc help even more: open an issue.

Contributing#

See CONTRIBUTING.md. Adding a provider is one Rust file plus a fixture test; the checklist is in the new provider issue template. Issues labelled good first issue are a good place to start, and AGENTS.md summarises the build commands and conventions for coding agents.

License#

MIT. See LICENSE.