puffinparse 0.1.2__tar.gz → 0.1.3__tar.gz

{puffinparse-0.1.2 → puffinparse-0.1.3}/Cargo.lock

@@ -1395,7 +1395,7 @@ dependencies = [
 
 [[package]]
 name = "puffinparse-cli"
-version = "0.1.2"
+version = "0.1.3"
 dependencies = [
  "anyhow",
  "chrono",
@@ -1415,7 +1415,7 @@ dependencies = [
 
 [[package]]
 name = "puffinparse-core"
-version = "0.1.2"
+version = "0.1.3"
 dependencies = [
  "async-trait",
  "bytes",
@@ -1439,7 +1439,7 @@ dependencies = [
 
 [[package]]
 name = "puffinparse-node"
-version = "0.1.2"
+version = "0.1.3"
 dependencies = [
  "bytes",
  "napi",
@@ -1453,7 +1453,7 @@ dependencies = [
 
 [[package]]
 name = "puffinparse-python"
-version = "0.1.2"
+version = "0.1.3"
 dependencies = [
  "bytes",
  "puffinparse-core",
@@ -1468,7 +1468,7 @@ dependencies = [
 
 [[package]]
 name = "puffinparse-server"
-version = "0.1.2"
+version = "0.1.3"
 dependencies = [
  "axum",
  "bytes",

{puffinparse-0.1.2 → puffinparse-0.1.3}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/puffinparse-core", "crates/puffinparse-python"]
 
 [workspace.package]
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 rust-version = "1.80"
 license = "MIT"
@@ -15,7 +15,7 @@ keywords = ["ocr", "document-parsing", "pdf", "api", "benchmark"]
 categories = ["api-bindings", "text-processing"]
 
 [workspace.dependencies]
-puffinparse-core = { path = "crates/puffinparse-core", version = "0.1.2" }
+puffinparse-core = { path = "crates/puffinparse-core", version = "0.1.3" }
 reqwest = { version = "0.13", default-features = false, features = ["json", "multipart", "rustls", "stream", "gzip"] }
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "fs", "time", "sync"] }
 serde = { version = "1", features = ["derive"] }

{puffinparse-0.1.2 → puffinparse-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: puffinparse
-Version: 0.1.2
+Version: 0.1.3
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -36,7 +36,7 @@ Project-URL: Repository, https://github.com/ajinkyashejul/puffinparse
 
 # PuffinParse
 
-[![PyPI](https://img.shields.io/pypi/v/puffinparse?color=E95C20)](https://pypi.org/project/puffinparse/) [![GitHub stars](https://img.shields.io/github/stars/ajinkyashejul/puffinparse?style=flat&color=E95C20)](https://github.com/ajinkyashejul/puffinparse/stargazers) [![CI](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml/badge.svg)](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-puffinparse.com-E95C20)](https://puffinparse.com/docs/) [![Benchmark](https://img.shields.io/badge/benchmark-results-E95C20)](https://puffinparse.com/benchmark-results/) [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![PyPI](https://img.shields.io/pypi/v/puffinparse?color=E95C20)](https://pypi.org/project/puffinparse/) [![GitHub stars](https://img.shields.io/github/stars/ajinkyashejul/puffinparse?style=flat&color=E95C20)](https://github.com/ajinkyashejul/puffinparse/stargazers) [![CI](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml/badge.svg)](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-puffinparse.com-E95C20)](https://puffinparse.com/docs/) [![Benchmark](https://img.shields.io/badge/benchmark-results-E95C20)](https://puffinparse.com/benchmark-results/) [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://github.com/ajinkyashejul/puffinparse/blob/main/pyproject.toml)
 
 **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.
 
@@ -64,24 +64,28 @@ Two things make switching real rather than aspirational. **Modes**: every call n
 | **Providers (v0.1)** | 18 providers · 60 models · 3 modes. **Live-verified** against the real APIs: [Reducto](https://reducto.ai), [Extend](https://extend.ai), [LlamaParse](https://cloud.llamaindex.ai). **Verified locally**: the self-hosted Tesseract and Docling. **Docs-only** (implemented from the provider's API documentation and tested against fixture payloads, not yet run live): Mistral, Azure, Textract, Gemini, OpenAI, Anthropic, Mathpix, Datalab, Unstructured, Upstage, Landing AI, Google Document AI and the self-hosted PaddleOCR ([help verify them](https://github.com/ajinkyashejul/puffinparse/issues/10)). [Full table](#model-names) |
 | **Modes** | `parse` (markdown + blocks), `ocr` (plain text + boxes), `extract` (JSON from a schema) |
 | **Core** | Rust (`puffinparse-core`): `reqwest` + `tokio`, no vendor SDKs, `#![forbid(unsafe_code)]` |
-| **SDKs** | Python 3.9+ (sync + async, fully typed) and Node.js / TypeScript ([`js/`](js/README.md)), both on the same Rust core |
-| **Gateway** | `puffinparse serve`: one HTTP endpoint with aliases, fallbacks, virtual keys, budgets, rate limits, JSON logs and Prometheus metrics ([`docs/SERVER.md`](docs/SERVER.md)) |
+| **SDKs** | Python 3.9+ (sync + async, fully typed) and Node.js / TypeScript ([`js/`](https://github.com/ajinkyashejul/puffinparse/blob/main/js/README.md)), both on the same Rust core |
+| **Gateway** | `puffinparse serve`: one HTTP endpoint with aliases, fallbacks, virtual keys, budgets, rate limits, JSON logs and Prometheus metrics ([`docs/SERVER.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SERVER.md)) |
 | **Long documents** | `submit` / `retrieve` jobs and provider webhooks instead of a blocking call ([below](#long-documents-jobs-and-webhooks)) |
 | **CLI** | `puffinparse parse`, `puffinparse ocr`, `puffinparse extract`, `puffinparse providers`, `puffinparse bench` |
 | **Reliability** | Retries with jittered backoff, whole-call deadlines, `Router` with ordered fallbacks / round-robin |
-| **Compatibility** | `output_format` renders any provider's result in Reducto's, Extend's or LlamaParse's own JSON, so an existing integration keeps its parser ([`docs/COMPAT.md`](docs/COMPAT.md)) |
+| **Compatibility** | `output_format` renders any provider's result in Reducto's, Extend's or LlamaParse's own JSON, so an existing integration keeps its parser ([`docs/COMPAT.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/COMPAT.md)) |
 | **Cost** | Embedded, overridable price table → `cost_usd` on every response |
 | **Benchmark** | One harness over synthetic data and public benchmarks (ParseBench, olmOCR-bench, OmniDocBench, DP-Bench); deterministic metrics and rule checks, latency, $/1k pages; every output inspectable at [puffinparse.com/benchmark-results](https://puffinparse.com/benchmark-results/) |
 
 ## Install
 
 ```bash
-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
+pip install puffinparse              # Python SDK (abi3 wheels: Linux glibc 2.28+, macOS, Windows)
+docker pull --platform linux/amd64 ghcr.io/ajinkyashejul/puffinparse   # gateway image (amd64 only for now)
 ```
 
+The CLI (which also runs the gateway) is a single binary: download the archive for your platform
+from [GitHub Releases](https://github.com/ajinkyashejul/puffinparse/releases/latest), or build it
+with `cargo install --git https://github.com/ajinkyashejul/puffinparse puffinparse-cli`. On macOS, a
+binary downloaded with a browser needs `xattr -d com.apple.quarantine ./puffinparse` once (it is not
+notarized yet). The Node.js SDK is not on npm yet: build it from [`js/`](https://github.com/ajinkyashejul/puffinparse/blob/main/js/README.md).
+
 Set the keys for the providers you use:
 
 ```bash
@@ -94,10 +98,11 @@ No key yet? The self-hosted engines work out of the box once installed:
 
 ```bash
 sudo apt-get install tesseract-ocr poppler-utils     # or: brew install tesseract poppler
-puffinparse ocr scan.png -m tesseract                    # free, local, word boxes + confidences
+python -c 'import puffinparse; print(puffinparse.ocr("scan.png", model="tesseract").text)'
+puffinparse ocr scan.png -m tesseract                # same with the CLI binary: word boxes + confidences
 ```
 
-Every provider reads its own variable: [`.env.example`](.env.example) lists all of them, the
+Every provider reads its own variable: [`.env.example`](https://github.com/ajinkyashejul/puffinparse/blob/main/.env.example) lists all of them, the
 [model tables](#model-names) say which belongs to which provider, and `puffinparse providers` shows
 which ones are set in your shell.
 
@@ -167,7 +172,8 @@ 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)
+    if line.bbox and page.width and page.height:   # normalised 0-1 box -> pixels
+        x0, y0, x1, y1 = line.bbox.to_pixels(page.width, page.height)
 for word in page.words:       # Word(text, bbox, confidence)
     ...
 ```
@@ -180,7 +186,7 @@ schema = {
     "properties": {"invoice_number": {"type": "string"}, "total": {"type": "number"}},
     "required": ["invoice_number", "total"],
 }
-result = puffinparse.extract("invoice.pdf", schema, model="...", citations=True)
+result = puffinparse.extract("invoice.pdf", schema, model="reducto/extract", citations=True)
 
 result.data                          # {"invoice_number": "INV-42", "total": 1280.5}
 result.fields["/total"].confidence   # per-field confidence, keyed by JSON pointer
@@ -212,7 +218,7 @@ result = puffinparse.handle_webhook(request.json(), model="reducto")  # verify t
 
 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`](docs/SPEC.md) §15.
+[`docs/SPEC.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SPEC.md) §15.
 
 ### TypeScript / Node.js
 
@@ -225,8 +231,9 @@ const doc = await parse("invoice.pdf", { model: "reducto/standard", fallbacks: [
 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`](js/README.md).
+The npm package is not published yet; build it from a clone (`cd js && npm ci && npm run build`), see
+[`js/README.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/js/README.md). Prebuilt binaries for Linux x64/arm64 (glibc), macOS and Windows x64
+will ship with the npm release.
 
 ### Model names
 
@@ -253,7 +260,7 @@ Each provider carries one of three verification labels:
   until it is verified; [issue #10](https://github.com/ajinkyashejul/puffinparse/issues/10) tracks this, and a run with your own key is a welcome
   contribution.
 
-[`docs/providers/README.md`](docs/providers/README.md) tracks the state and links one reference
+[`docs/providers/README.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/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.
@@ -417,7 +424,7 @@ What is guaranteed is **structural fidelity** — key set and nesting, one chunk
 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`](docs/COMPAT.md) enumerates all of it, per format;
+block types are lossy. [`docs/COMPAT.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/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
@@ -502,8 +509,8 @@ curl -H "Authorization: Bearer $TEAM_KEY" -F file=@invoice.pdf -F model=invoices
 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`](docs/SERVER.md), sample:
-[`examples/server/puffinparse.toml`](examples/server/puffinparse.toml).
+or secrets. Reference: [`docs/SERVER.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SERVER.md), sample:
+[`examples/server/puffinparse.toml`](https://github.com/ajinkyashejul/puffinparse/blob/main/examples/server/puffinparse.toml).
 
 ### Rust
 
@@ -516,38 +523,39 @@ println!("{} pages, ${:.4}\n{}", doc.usage.pages, doc.cost_usd.unwrap_or(0.0), d
 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 schema = serde_json::json!({"type": "object", "properties": {"total": {"type": "number"}}});
+let req = ExtractRequest::new(DocumentRequest::from_path("invoice.pdf").model("reducto/extract"), 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.
+PuffinParse ships an open, reproducible benchmark. Pages from public benchmarks are scored against their own published truth or rules, the synthetic set's truth is exact by construction (its documents are rendered from the same source as the truth files), metrics are deterministic text comparisons with no LLM judge, and every run records the dataset hash, model, latency and cost.
 
 ```bash
 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 report benchmark/results/2026-09-25-combined-v3.json   # one dataset's leaderboard section
 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)`
+- **Overall** = `100 ×` the mean of each document's headline metric: `char_similarity` (`1 − levenshtein / max(len)`) for transcripts, the table score for table-only pages, the rule pass rate for rule-checked pages; a failed call scores 0 (details in [`benchmark/README.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/benchmark/README.md))
 - **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`](benchmark/LEADERBOARD.md), and every
+The current leaderboard is in [`benchmark/LEADERBOARD.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/benchmark/LEADERBOARD.md), and every
 document, output, diff and rule check is browsable at
 [puffinparse.com/benchmark-results](https://puffinparse.com/benchmark-results/). Datasets:
 `synthetic-v1` (exact truth by construction) and the headline `combined-v3`, which adds subsets of
 [ParseBench](https://github.com/run-llama/ParseBench), [olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench),
 [OmniDocBench](https://github.com/opendatalab/OmniDocBench) and
 [DP-Bench](https://huggingface.co/datasets/upstage/dp-bench) converted by
-[`benchmark/adapters/`](docs/benchmarks/adapters.md) at pinned revisions. Older `combined-v1` and
+[`benchmark/adapters/`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/benchmarks/adapters.md) 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.
@@ -562,7 +570,7 @@ interrupted run.
 | Boxes | already normalised | divided by `metadata.page.width/height` | `bBox` divided by page `width/height` |
 | Usage | `usage.num_pages`, `usage.credits` | `metrics.pageCount`, `usage.credits` | `job_metadata.job_pages` |
 
-Full details, including the exact wire formats verified against live responses, are in [`docs/SPEC.md`](docs/SPEC.md).
+Full details, including the exact wire formats verified against live responses, are in [`docs/SPEC.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SPEC.md).
 
 ## Project layout
 
@@ -583,12 +591,12 @@ docs/SPEC.md            specification
 Planned work is tracked in [GitHub Issues](https://github.com/ajinkyashejul/puffinparse/issues).
 Open items:
 
-- **Packaging**: publish 0.1.0 to PyPI, npm and crates.io with prebuilt wheels, addons and CLI
-  binaries ([#9](https://github.com/ajinkyashejul/puffinparse/issues/9)).
+- **Packaging**: PyPI wheels and CLI binaries ship today; npm and crates.io are next, plus a
+  multi-arch gateway image and a notarized macOS binary ([#9](https://github.com/ajinkyashejul/puffinparse/issues/9)).
 - **Providers**: live-verify the docs-only providers ([#10](https://github.com/ajinkyashejul/puffinparse/issues/10)), including PaddleOCR
   against a real server ([#17](https://github.com/ajinkyashejul/puffinparse/issues/17)).
-- **Benchmark**: add `tesseract/default` ([#11](https://github.com/ajinkyashejul/puffinparse/issues/11)) and `docling/default` with a hardware note
-  ([#12](https://github.com/ajinkyashejul/puffinparse/issues/12)) to `combined-v3`; regenerate the leaderboard in one command
+- **Benchmark**: add `docling/default` with a hardware note
+  ([#12](https://github.com/ajinkyashejul/puffinparse/issues/12)) to `combined-v3` (`tesseract/default` is already in it); regenerate the leaderboard in one command
   ([#13](https://github.com/ajinkyashejul/puffinparse/issues/13)); score table-cell neighbour relations exactly ([#15](https://github.com/ajinkyashejul/puffinparse/issues/15)); a READoc
   long-document track ([#16](https://github.com/ajinkyashejul/puffinparse/issues/16)).
 - **SDK**: `output_format="mistral"` for code written against Mistral OCR responses
@@ -604,9 +612,45 @@ developers find it. Reports of a wrong score, a missing provider or a confusing
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Adding a provider is one Rust file plus a fixture test; the checklist is in the [new provider issue template](.github/ISSUE_TEMPLATE/new_provider.md). Issues labelled [`good first issue`](https://github.com/ajinkyashejul/puffinparse/labels/good%20first%20issue) are a good place to start, and [AGENTS.md](AGENTS.md) summarises the build commands and conventions for coding agents.
+See [CONTRIBUTING.md](https://github.com/ajinkyashejul/puffinparse/blob/main/CONTRIBUTING.md). Adding a provider is one Rust file plus a fixture test; the checklist is in the [new provider issue template](https://github.com/ajinkyashejul/puffinparse/blob/main/github/ISSUE_TEMPLATE/new_provider.md). Issues labelled [`good first issue`](https://github.com/ajinkyashejul/puffinparse/labels/good%20first%20issue) are a good place to start, and [AGENTS.md](https://github.com/ajinkyashejul/puffinparse/blob/main/AGENTS.md) summarises the build commands and conventions for coding agents.
+
+## Acknowledgements
+
+PuffinParse stands on other people's work:
+
+- **Benchmarks and datasets.** The combined benchmark is built on
+  [ParseBench](https://github.com/run-llama/ParseBench) (LlamaIndex; Zhang et al., 2026,
+  arXiv:2604.08538; Apache-2.0),
+  [olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench) (Allen Institute for AI;
+  Poznanski et al., 2025, arXiv:2502.18443; ODC-BY-1.0),
+  [OmniDocBench](https://github.com/opendatalab/OmniDocBench) (OpenDataLab / Shanghai AI
+  Laboratory; Ouyang et al., 2024, arXiv:2412.07626; research-only, so only an index is committed)
+  and [DP-Bench](https://huggingface.co/datasets/upstage/dp-bench) (Upstage AI; MIT). Each
+  `benchmark/datasets/<name>/README.md` gives the pinned revision, the licence, what we changed and
+  the citation the authors ask for. If you use these numbers, please cite those benchmarks too.
+- **Metrics.** The rule checks re-implement the test semantics of olmOCR-bench and ParseBench, and
+  table structure is scored with TEDS (Zhong, ShafieiBavani and Jimeno Yepes, 2020, "Image-based
+  table recognition: data, model, and evaluation"). The scorer is our own Rust code; the source
+  comments say whose behaviour each part mirrors.
+- **API design.** The `"<provider>/<model>"` model strings and the gateway server follow
+  [LiteLLM](https://github.com/BerriAI/litellm), which did this first for LLM APIs.
+- **Providers and engines.** The compatibility shapes mirror the public response formats of
+  Reducto, Extend and LlamaParse so existing code can switch, and the open baselines are
+  [Tesseract](https://github.com/tesseract-ocr/tesseract) and
+  [Docling](https://github.com/docling-project/docling). Provider names are trademarks of their
+  owners. PuffinParse is not affiliated with or endorsed by any of them.
+- **Libraries.** [tokio](https://tokio.rs), [reqwest](https://github.com/seanmonstar/reqwest),
+  [serde](https://serde.rs), [axum](https://github.com/tokio-rs/axum),
+  [clap](https://github.com/clap-rs/clap), [PyO3](https://pyo3.rs),
+  [maturin](https://github.com/PyO3/maturin), [napi-rs](https://napi.rs) and the other crates in
+  [THIRD_PARTY_NOTICES.md](https://github.com/ajinkyashejul/puffinparse/blob/main/THIRD_PARTY_NOTICES.md).
+  The site uses GitHub's [Octicons](https://github.com/primer/octicons) GitHub mark (MIT), and the
+  results viewer uses [pdf.js](https://github.com/mozilla/pdf.js) (Apache-2.0).
 
 ## License
 
-MIT. See [LICENSE](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE).
+MIT. See [LICENSE](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE). The third-party
+crates compiled into the binaries are listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/ajinkyashejul/puffinparse/blob/main/THIRD_PARTY_NOTICES.md),
+and the benchmark data keeps its own licence, stated per dataset.
 

{puffinparse-0.1.2 → puffinparse-0.1.3}/README.md

@@ -2,7 +2,7 @@
 
 # PuffinParse
 
-[![PyPI](https://img.shields.io/pypi/v/puffinparse?color=E95C20)](https://pypi.org/project/puffinparse/) [![GitHub stars](https://img.shields.io/github/stars/ajinkyashejul/puffinparse?style=flat&color=E95C20)](https://github.com/ajinkyashejul/puffinparse/stargazers) [![CI](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml/badge.svg)](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-puffinparse.com-E95C20)](https://puffinparse.com/docs/) [![Benchmark](https://img.shields.io/badge/benchmark-results-E95C20)](https://puffinparse.com/benchmark-results/) [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![PyPI](https://img.shields.io/pypi/v/puffinparse?color=E95C20)](https://pypi.org/project/puffinparse/) [![GitHub stars](https://img.shields.io/github/stars/ajinkyashejul/puffinparse?style=flat&color=E95C20)](https://github.com/ajinkyashejul/puffinparse/stargazers) [![CI](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml/badge.svg)](https://github.com/ajinkyashejul/puffinparse/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-puffinparse.com-E95C20)](https://puffinparse.com/docs/) [![Benchmark](https://img.shields.io/badge/benchmark-results-E95C20)](https://puffinparse.com/benchmark-results/) [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://github.com/ajinkyashejul/puffinparse/blob/main/pyproject.toml)
 
 **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.
 
@@ -30,24 +30,28 @@ Two things make switching real rather than aspirational. **Modes**: every call n
 | **Providers (v0.1)** | 18 providers · 60 models · 3 modes. **Live-verified** against the real APIs: [Reducto](https://reducto.ai), [Extend](https://extend.ai), [LlamaParse](https://cloud.llamaindex.ai). **Verified locally**: the self-hosted Tesseract and Docling. **Docs-only** (implemented from the provider's API documentation and tested against fixture payloads, not yet run live): Mistral, Azure, Textract, Gemini, OpenAI, Anthropic, Mathpix, Datalab, Unstructured, Upstage, Landing AI, Google Document AI and the self-hosted PaddleOCR ([help verify them](https://github.com/ajinkyashejul/puffinparse/issues/10)). [Full table](#model-names) |
 | **Modes** | `parse` (markdown + blocks), `ocr` (plain text + boxes), `extract` (JSON from a schema) |
 | **Core** | Rust (`puffinparse-core`): `reqwest` + `tokio`, no vendor SDKs, `#![forbid(unsafe_code)]` |
-| **SDKs** | Python 3.9+ (sync + async, fully typed) and Node.js / TypeScript ([`js/`](js/README.md)), both on the same Rust core |
-| **Gateway** | `puffinparse serve`: one HTTP endpoint with aliases, fallbacks, virtual keys, budgets, rate limits, JSON logs and Prometheus metrics ([`docs/SERVER.md`](docs/SERVER.md)) |
+| **SDKs** | Python 3.9+ (sync + async, fully typed) and Node.js / TypeScript ([`js/`](https://github.com/ajinkyashejul/puffinparse/blob/main/js/README.md)), both on the same Rust core |
+| **Gateway** | `puffinparse serve`: one HTTP endpoint with aliases, fallbacks, virtual keys, budgets, rate limits, JSON logs and Prometheus metrics ([`docs/SERVER.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SERVER.md)) |
 | **Long documents** | `submit` / `retrieve` jobs and provider webhooks instead of a blocking call ([below](#long-documents-jobs-and-webhooks)) |
 | **CLI** | `puffinparse parse`, `puffinparse ocr`, `puffinparse extract`, `puffinparse providers`, `puffinparse bench` |
 | **Reliability** | Retries with jittered backoff, whole-call deadlines, `Router` with ordered fallbacks / round-robin |
-| **Compatibility** | `output_format` renders any provider's result in Reducto's, Extend's or LlamaParse's own JSON, so an existing integration keeps its parser ([`docs/COMPAT.md`](docs/COMPAT.md)) |
+| **Compatibility** | `output_format` renders any provider's result in Reducto's, Extend's or LlamaParse's own JSON, so an existing integration keeps its parser ([`docs/COMPAT.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/COMPAT.md)) |
 | **Cost** | Embedded, overridable price table → `cost_usd` on every response |
 | **Benchmark** | One harness over synthetic data and public benchmarks (ParseBench, olmOCR-bench, OmniDocBench, DP-Bench); deterministic metrics and rule checks, latency, $/1k pages; every output inspectable at [puffinparse.com/benchmark-results](https://puffinparse.com/benchmark-results/) |
 
 ## Install
 
 ```bash
-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
+pip install puffinparse              # Python SDK (abi3 wheels: Linux glibc 2.28+, macOS, Windows)
+docker pull --platform linux/amd64 ghcr.io/ajinkyashejul/puffinparse   # gateway image (amd64 only for now)
 ```
 
+The CLI (which also runs the gateway) is a single binary: download the archive for your platform
+from [GitHub Releases](https://github.com/ajinkyashejul/puffinparse/releases/latest), or build it
+with `cargo install --git https://github.com/ajinkyashejul/puffinparse puffinparse-cli`. On macOS, a
+binary downloaded with a browser needs `xattr -d com.apple.quarantine ./puffinparse` once (it is not
+notarized yet). The Node.js SDK is not on npm yet: build it from [`js/`](https://github.com/ajinkyashejul/puffinparse/blob/main/js/README.md).
+
 Set the keys for the providers you use:
 
 ```bash
@@ -60,10 +64,11 @@ No key yet? The self-hosted engines work out of the box once installed:
 
 ```bash
 sudo apt-get install tesseract-ocr poppler-utils     # or: brew install tesseract poppler
-puffinparse ocr scan.png -m tesseract                    # free, local, word boxes + confidences
+python -c 'import puffinparse; print(puffinparse.ocr("scan.png", model="tesseract").text)'
+puffinparse ocr scan.png -m tesseract                # same with the CLI binary: word boxes + confidences
 ```
 
-Every provider reads its own variable: [`.env.example`](.env.example) lists all of them, the
+Every provider reads its own variable: [`.env.example`](https://github.com/ajinkyashejul/puffinparse/blob/main/.env.example) lists all of them, the
 [model tables](#model-names) say which belongs to which provider, and `puffinparse providers` shows
 which ones are set in your shell.
 
@@ -133,7 +138,8 @@ 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)
+    if line.bbox and page.width and page.height:   # normalised 0-1 box -> pixels
+        x0, y0, x1, y1 = line.bbox.to_pixels(page.width, page.height)
 for word in page.words:       # Word(text, bbox, confidence)
     ...
 ```
@@ -146,7 +152,7 @@ schema = {
     "properties": {"invoice_number": {"type": "string"}, "total": {"type": "number"}},
     "required": ["invoice_number", "total"],
 }
-result = puffinparse.extract("invoice.pdf", schema, model="...", citations=True)
+result = puffinparse.extract("invoice.pdf", schema, model="reducto/extract", citations=True)
 
 result.data                          # {"invoice_number": "INV-42", "total": 1280.5}
 result.fields["/total"].confidence   # per-field confidence, keyed by JSON pointer
@@ -178,7 +184,7 @@ result = puffinparse.handle_webhook(request.json(), model="reducto")  # verify t
 
 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`](docs/SPEC.md) §15.
+[`docs/SPEC.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SPEC.md) §15.
 
 ### TypeScript / Node.js
 
@@ -191,8 +197,9 @@ const doc = await parse("invoice.pdf", { model: "reducto/standard", fallbacks: [
 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`](js/README.md).
+The npm package is not published yet; build it from a clone (`cd js && npm ci && npm run build`), see
+[`js/README.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/js/README.md). Prebuilt binaries for Linux x64/arm64 (glibc), macOS and Windows x64
+will ship with the npm release.
 
 ### Model names
 
@@ -219,7 +226,7 @@ Each provider carries one of three verification labels:
   until it is verified; [issue #10](https://github.com/ajinkyashejul/puffinparse/issues/10) tracks this, and a run with your own key is a welcome
   contribution.
 
-[`docs/providers/README.md`](docs/providers/README.md) tracks the state and links one reference
+[`docs/providers/README.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/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.
@@ -383,7 +390,7 @@ What is guaranteed is **structural fidelity** — key set and nesting, one chunk
 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`](docs/COMPAT.md) enumerates all of it, per format;
+block types are lossy. [`docs/COMPAT.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/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
@@ -468,8 +475,8 @@ curl -H "Authorization: Bearer $TEAM_KEY" -F file=@invoice.pdf -F model=invoices
 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`](docs/SERVER.md), sample:
-[`examples/server/puffinparse.toml`](examples/server/puffinparse.toml).
+or secrets. Reference: [`docs/SERVER.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SERVER.md), sample:
+[`examples/server/puffinparse.toml`](https://github.com/ajinkyashejul/puffinparse/blob/main/examples/server/puffinparse.toml).
 
 ### Rust
 
@@ -482,38 +489,39 @@ println!("{} pages, ${:.4}\n{}", doc.usage.pages, doc.cost_usd.unwrap_or(0.0), d
 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 schema = serde_json::json!({"type": "object", "properties": {"total": {"type": "number"}}});
+let req = ExtractRequest::new(DocumentRequest::from_path("invoice.pdf").model("reducto/extract"), 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.
+PuffinParse ships an open, reproducible benchmark. Pages from public benchmarks are scored against their own published truth or rules, the synthetic set's truth is exact by construction (its documents are rendered from the same source as the truth files), metrics are deterministic text comparisons with no LLM judge, and every run records the dataset hash, model, latency and cost.
 
 ```bash
 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 report benchmark/results/2026-09-25-combined-v3.json   # one dataset's leaderboard section
 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)`
+- **Overall** = `100 ×` the mean of each document's headline metric: `char_similarity` (`1 − levenshtein / max(len)`) for transcripts, the table score for table-only pages, the rule pass rate for rule-checked pages; a failed call scores 0 (details in [`benchmark/README.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/benchmark/README.md))
 - **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`](benchmark/LEADERBOARD.md), and every
+The current leaderboard is in [`benchmark/LEADERBOARD.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/benchmark/LEADERBOARD.md), and every
 document, output, diff and rule check is browsable at
 [puffinparse.com/benchmark-results](https://puffinparse.com/benchmark-results/). Datasets:
 `synthetic-v1` (exact truth by construction) and the headline `combined-v3`, which adds subsets of
 [ParseBench](https://github.com/run-llama/ParseBench), [olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench),
 [OmniDocBench](https://github.com/opendatalab/OmniDocBench) and
 [DP-Bench](https://huggingface.co/datasets/upstage/dp-bench) converted by
-[`benchmark/adapters/`](docs/benchmarks/adapters.md) at pinned revisions. Older `combined-v1` and
+[`benchmark/adapters/`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/benchmarks/adapters.md) 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.
@@ -528,7 +536,7 @@ interrupted run.
 | Boxes | already normalised | divided by `metadata.page.width/height` | `bBox` divided by page `width/height` |
 | Usage | `usage.num_pages`, `usage.credits` | `metrics.pageCount`, `usage.credits` | `job_metadata.job_pages` |
 
-Full details, including the exact wire formats verified against live responses, are in [`docs/SPEC.md`](docs/SPEC.md).
+Full details, including the exact wire formats verified against live responses, are in [`docs/SPEC.md`](https://github.com/ajinkyashejul/puffinparse/blob/main/docs/SPEC.md).
 
 ## Project layout
 
@@ -549,12 +557,12 @@ docs/SPEC.md            specification
 Planned work is tracked in [GitHub Issues](https://github.com/ajinkyashejul/puffinparse/issues).
 Open items:
 
-- **Packaging**: publish 0.1.0 to PyPI, npm and crates.io with prebuilt wheels, addons and CLI
-  binaries ([#9](https://github.com/ajinkyashejul/puffinparse/issues/9)).
+- **Packaging**: PyPI wheels and CLI binaries ship today; npm and crates.io are next, plus a
+  multi-arch gateway image and a notarized macOS binary ([#9](https://github.com/ajinkyashejul/puffinparse/issues/9)).
 - **Providers**: live-verify the docs-only providers ([#10](https://github.com/ajinkyashejul/puffinparse/issues/10)), including PaddleOCR
   against a real server ([#17](https://github.com/ajinkyashejul/puffinparse/issues/17)).
-- **Benchmark**: add `tesseract/default` ([#11](https://github.com/ajinkyashejul/puffinparse/issues/11)) and `docling/default` with a hardware note
-  ([#12](https://github.com/ajinkyashejul/puffinparse/issues/12)) to `combined-v3`; regenerate the leaderboard in one command
+- **Benchmark**: add `docling/default` with a hardware note
+  ([#12](https://github.com/ajinkyashejul/puffinparse/issues/12)) to `combined-v3` (`tesseract/default` is already in it); regenerate the leaderboard in one command
   ([#13](https://github.com/ajinkyashejul/puffinparse/issues/13)); score table-cell neighbour relations exactly ([#15](https://github.com/ajinkyashejul/puffinparse/issues/15)); a READoc
   long-document track ([#16](https://github.com/ajinkyashejul/puffinparse/issues/16)).
 - **SDK**: `output_format="mistral"` for code written against Mistral OCR responses
@@ -570,8 +578,44 @@ developers find it. Reports of a wrong score, a missing provider or a confusing
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Adding a provider is one Rust file plus a fixture test; the checklist is in the [new provider issue template](.github/ISSUE_TEMPLATE/new_provider.md). Issues labelled [`good first issue`](https://github.com/ajinkyashejul/puffinparse/labels/good%20first%20issue) are a good place to start, and [AGENTS.md](AGENTS.md) summarises the build commands and conventions for coding agents.
+See [CONTRIBUTING.md](https://github.com/ajinkyashejul/puffinparse/blob/main/CONTRIBUTING.md). Adding a provider is one Rust file plus a fixture test; the checklist is in the [new provider issue template](https://github.com/ajinkyashejul/puffinparse/blob/main/github/ISSUE_TEMPLATE/new_provider.md). Issues labelled [`good first issue`](https://github.com/ajinkyashejul/puffinparse/labels/good%20first%20issue) are a good place to start, and [AGENTS.md](https://github.com/ajinkyashejul/puffinparse/blob/main/AGENTS.md) summarises the build commands and conventions for coding agents.
+
+## Acknowledgements
+
+PuffinParse stands on other people's work:
+
+- **Benchmarks and datasets.** The combined benchmark is built on
+  [ParseBench](https://github.com/run-llama/ParseBench) (LlamaIndex; Zhang et al., 2026,
+  arXiv:2604.08538; Apache-2.0),
+  [olmOCR-bench](https://huggingface.co/datasets/allenai/olmOCR-bench) (Allen Institute for AI;
+  Poznanski et al., 2025, arXiv:2502.18443; ODC-BY-1.0),
+  [OmniDocBench](https://github.com/opendatalab/OmniDocBench) (OpenDataLab / Shanghai AI
+  Laboratory; Ouyang et al., 2024, arXiv:2412.07626; research-only, so only an index is committed)
+  and [DP-Bench](https://huggingface.co/datasets/upstage/dp-bench) (Upstage AI; MIT). Each
+  `benchmark/datasets/<name>/README.md` gives the pinned revision, the licence, what we changed and
+  the citation the authors ask for. If you use these numbers, please cite those benchmarks too.
+- **Metrics.** The rule checks re-implement the test semantics of olmOCR-bench and ParseBench, and
+  table structure is scored with TEDS (Zhong, ShafieiBavani and Jimeno Yepes, 2020, "Image-based
+  table recognition: data, model, and evaluation"). The scorer is our own Rust code; the source
+  comments say whose behaviour each part mirrors.
+- **API design.** The `"<provider>/<model>"` model strings and the gateway server follow
+  [LiteLLM](https://github.com/BerriAI/litellm), which did this first for LLM APIs.
+- **Providers and engines.** The compatibility shapes mirror the public response formats of
+  Reducto, Extend and LlamaParse so existing code can switch, and the open baselines are
+  [Tesseract](https://github.com/tesseract-ocr/tesseract) and
+  [Docling](https://github.com/docling-project/docling). Provider names are trademarks of their
+  owners. PuffinParse is not affiliated with or endorsed by any of them.
+- **Libraries.** [tokio](https://tokio.rs), [reqwest](https://github.com/seanmonstar/reqwest),
+  [serde](https://serde.rs), [axum](https://github.com/tokio-rs/axum),
+  [clap](https://github.com/clap-rs/clap), [PyO3](https://pyo3.rs),
+  [maturin](https://github.com/PyO3/maturin), [napi-rs](https://napi.rs) and the other crates in
+  [THIRD_PARTY_NOTICES.md](https://github.com/ajinkyashejul/puffinparse/blob/main/THIRD_PARTY_NOTICES.md).
+  The site uses GitHub's [Octicons](https://github.com/primer/octicons) GitHub mark (MIT), and the
+  results viewer uses [pdf.js](https://github.com/mozilla/pdf.js) (Apache-2.0).
 
 ## License
 
-MIT. See [LICENSE](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE).
+MIT. See [LICENSE](https://github.com/ajinkyashejul/puffinparse/blob/main/LICENSE). The third-party
+crates compiled into the binaries are listed in
+[THIRD_PARTY_NOTICES.md](https://github.com/ajinkyashejul/puffinparse/blob/main/THIRD_PARTY_NOTICES.md),
+and the benchmark data keeps its own licence, stated per dataset.

puffinparse-0.1.3/crates/puffinparse-core/README.md

@@ -0,0 +1,18 @@
+# puffinparse-core
+
+Rust core of [PuffinParse](https://github.com/ajinkyashejul/puffinparse): one API for every
+OCR / document-parsing provider (Reducto, Extend, LlamaParse, Mistral, Azure, Textract, …).
+
+```rust
+use puffinparse_core::{parse, DocumentRequest};
+
+#[tokio::main]
+async fn main() -> Result<(), puffinparse_core::Error> {
+    let doc = parse(DocumentRequest::from_path("invoice.pdf").model("reducto/standard")).await?;
+    println!("{} pages, ${:.4}: {}", doc.usage.pages, doc.cost_usd.unwrap_or(0.0), doc.markdown);
+    Ok(())
+}
+```
+
+`ocr` returns plain text with line and word boxes, and `extract` fills a JSON Schema; see the
+repository README for the Python and TypeScript SDKs, the CLI, the gateway and the benchmark.

{puffinparse-0.1.2 → puffinparse-0.1.3}/crates/puffinparse-core/src/bench/tables.rs

@@ -390,6 +390,11 @@ pub fn decode_entities(s: &str) -> String {
 // grids — the same formula, costs and Zhang–Shasha edit distance, just without `thead`/`tbody` and
 // span attributes. It still punishes missing, extra, split or merged rows and cells, which the
 // flat `table_score` string similarity does not see.
+//
+// Credit: the metric is from the paper above; its reference implementation is IBM's PubTabNet
+// `src/metric.py` (github.com/ibm-aur-nlp/PubTabNet, Apache-2.0), which uses APTED. This file is an
+// independent Rust implementation (Zhang & Shasha, 1989, "Simple fast algorithms for the editing
+// distance between trees and related problems"); no PubTabNet code is copied.
 
 /// Node budget above which [`teds_grid`] declines (`None`): Zhang–Shasha is O(n·m) memory.
 const TEDS_MAX_PAIRS: usize = 16_000_000;

{puffinparse-0.1.2 → puffinparse-0.1.3}/crates/puffinparse-core/src/bench.rs

@@ -444,6 +444,13 @@ pub fn summarize_with(metrics: &[Option<Metrics>], table_only: &[bool]) -> Summa
 // of a reference transcript: `kind: "rules"` documents in `docs/benchmarks/adapters.md`. A document
 // scores `passed / total`, which has the same shape as an accuracy in `0..=1` and therefore slots
 // into [`Metrics`] via [`metrics_from_rules`].
+//
+// Credit: the rule types and their semantics come from the benchmarks that define them and are
+// re-implemented here from their published descriptions and code, without copying any of it:
+// olmOCR-bench (`olmocr/bench/tests.py` in github.com/allenai/olmocr, Apache-2.0: `present`,
+// `absent`, `order`, `table`, and `max_diffs` fuzzy matching) and ParseBench
+// (github.com/run-llama/ParseBench, Apache-2.0: `missing_sentence_percent` → `bag_of_sentences`).
+// The fuzzy substring search is Sellers' algorithm (1980), see [`approx_contains`].
 
 /// What a [`Rule`] asserts about the parsed markdown.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]

{puffinparse-0.1.2 → puffinparse-0.1.3}/crates/puffinparse-core/src/providers/tesseract.rs

@@ -245,6 +245,7 @@ async fn run(request: &DocumentRequest) -> Result<Run> {
                 &deadline,
                 "pdftoppm",
                 "install poppler-utils (apt install poppler-utils / brew install poppler) or set PDFTOPPM_CMD",
+                PDFTOPPM_INPUT_EXITS,
             )
             .await?;
             for (n, path) in rendered_pages(scratch.path()).await? {
@@ -285,6 +286,7 @@ async fn run(request: &DocumentRequest) -> Result<Run> {
             &deadline,
             "tesseract",
             "install Tesseract (apt install tesseract-ocr / brew install tesseract) or set TESSERACT_CMD",
+            &[],
         )
         .await?;
         let tsv = String::from_utf8_lossy(&stdout).into_owned();
@@ -319,8 +321,34 @@ async fn rendered_pages(dir: &Path) -> Result<Vec<(u32, PathBuf)>> {
     Ok(out)
 }
 
-/// Run a local binary with the call's deadline; non-zero exits carry the tool's stderr verbatim.
-async fn exec(cmd: &str, args: &[String], deadline: &Deadline, tool: &str, install_hint: &str) -> Result<Vec<u8>> {
+/// `pdftoppm` exit codes that mean the input is at fault: 1 cannot open/read the PDF (corrupt or not
+/// a PDF), 3 PDF permissions, 99 anything else, which in practice is a page range past the end.
+/// These are input errors, not retryable: another model would fail on the same file.
+const PDFTOPPM_INPUT_EXITS: &[i32] = &[1, 3, 99];
+
+/// Lines of a tool's stderr kept in an error message; a corrupt PDF can produce hundreds.
+const STDERR_LINES: usize = 5;
+
+/// The first [`STDERR_LINES`] lines of a tool's stderr, noting how many were dropped.
+fn stderr_excerpt(stderr: &str) -> String {
+    let lines: Vec<&str> = stderr.trim().lines().collect();
+    if lines.len() <= STDERR_LINES {
+        return lines.join("\n");
+    }
+    format!("{}\n... ({} more lines)", lines[..STDERR_LINES].join("\n"), lines.len() - STDERR_LINES)
+}
+
+/// Run a local binary with the call's deadline. A non-zero exit carries the start of the tool's
+/// stderr; exit codes in `input_exits` are reported as input errors, and 127 (the shell's "command
+/// not found", as seen in minimal containers) as a missing binary.
+async fn exec(
+    cmd: &str,
+    args: &[String],
+    deadline: &Deadline,
+    tool: &str,
+    install_hint: &str,
+    input_exits: &[i32],
+) -> Result<Vec<u8>> {
     let mut command = tokio::process::Command::new(cmd);
     // Tesseract's OpenMP threads oversubscribe the CPU when several pages run concurrently (a
     // small PNG took 70 s instead of 0.7 s on 4 cores); one thread per process is the documented
@@ -348,10 +376,16 @@ async fn exec(cmd: &str, args: &[String], deadline: &Deadline, tool: &str, insta
         Err(_) => return Err(Error::timeout(format!("deadline exceeded while running {tool}")).with_provider(NAME)),
     };
     if !output.status.success() {
-        let stderr = String::from_utf8_lossy(&output.stderr);
-        return Err(
-            Error::provider(format!("{tool} exited with {}: {}", output.status, stderr.trim())).with_provider(NAME)
-        );
+        let stderr = stderr_excerpt(&String::from_utf8_lossy(&output.stderr));
+        let code = output.status.code();
+        let err = match code {
+            Some(127) => Error::provider(format!("{tool} binary '{cmd}' could not be run (exit 127): {install_hint}")),
+            Some(c) if input_exits.contains(&c) => {
+                Error::input(format!("{tool} could not read the input (exit {c}): {stderr}"))
+            }
+            _ => Error::provider(format!("{tool} exited with {}: {stderr}", output.status)),
+        };
+        return Err(err.with_provider(NAME));
     }
     Ok(output.stdout)
 }
@@ -622,6 +656,40 @@ mod tests {
         assert!(e.message.contains("pdftoppm binary") && e.message.contains("poppler"), "{e}");
     }
 
+    #[test]
+    fn stderr_is_trimmed_to_a_few_lines() {
+        assert_eq!(stderr_excerpt("  one\ntwo\n"), "one\ntwo");
+        let long: String = (1..=300).map(|i| format!("Syntax Error ({i}): Illegal character\n")).collect();
+        let short = stderr_excerpt(&long);
+        assert_eq!(short.lines().count(), STDERR_LINES + 1);
+        assert!(short.ends_with("... (295 more lines)"), "{short}");
+    }
+
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn exit_codes_are_classified() {
+        let deadline = Deadline::new(10.0);
+        let sh = |script: &str| vec!["-c".to_string(), script.to_string()];
+        let e = exec(
+            "sh",
+            &sh("echo 'Wrong page range' >&2; exit 99"),
+            &deadline,
+            "pdftoppm",
+            "hint",
+            PDFTOPPM_INPUT_EXITS,
+        )
+        .await
+        .unwrap_err();
+        assert_eq!(e.kind, crate::error::ErrorKind::Input);
+        assert!(!e.retryable && e.message.contains("Wrong page range"), "{e}");
+        let e = exec("sh", &sh("exit 127"), &deadline, "tesseract", "install it", &[]).await.unwrap_err();
+        assert_eq!(e.kind, crate::error::ErrorKind::Provider);
+        assert!(e.message.contains("could not be run") && e.message.contains("install it"), "{e}");
+        let e = exec("sh", &sh("exit 2"), &deadline, "pdftoppm", "hint", PDFTOPPM_INPUT_EXITS).await.unwrap_err();
+        assert_eq!(e.kind, crate::error::ErrorKind::Provider);
+        assert!(e.retryable, "{e}");
+    }
+
     #[tokio::test]
     async fn rejects_non_image_input() {
         let req = DocumentRequest::from_bytes(&b"PK\x03\x04"[..], "a.docx");

puffinparse-0.1.3/crates/puffinparse-core/tests/fixtures/README.md

@@ -0,0 +1,14 @@
+# Test fixtures: where each payload comes from
+
+Every provider parse path is tested against a payload in this directory. They come from three
+places, matching the **Status** column in [`docs/providers/README.md`](../../../../docs/providers/README.md):
+
+| Fixtures | Provider status | Origin |
+|---|---|---|
+| `reducto_*.json`, `extend_*.json`, `llamaparse_*.json` | live-verified | Trimmed responses captured from our own calls to the live APIs, on documents we made (`benchmark/datasets/synthetic-v1`, the "Hello LiteOCR" / "Cedar Ridge Supply" sample invoices). Job ids, signed URLs, project ids and similar values are redacted or replaced. The provider pages say which file is which. |
+| `docling_*.json`, `tesseract_headings.tsv` | verified locally | Real output of a locally installed docling-serve / Tesseract on `synthetic-v1` documents. |
+| `anthropic_*`, `azure_*`, `datalab_*`, `gemini_*`, `google_documentai_*`, `landingai_*`, `mathpix_*`, `mistral_*`, `openai_*`, `paddleocr_*`, `textract_*`, `unstructured_*`, `upstage_*` | docs-only | Hand-built to the response *schema* each provider documents, filled with our own sample content. They are not copies of the providers' documentation examples. |
+| `rules_text_sparse_note.json` | n/a | A verbatim copy of `benchmark/datasets/parsebench/rules/text_sparse_note.json`, derived from [ParseBench](https://huggingface.co/datasets/llamaindex/ParseBench) (LlamaIndex, Apache-2.0); see that dataset's README for attribution. |
+
+When you replace a hand-built fixture with a real response, redact every credential, signed URL,
+account or project id and any personal data before committing, and update this table.

{puffinparse-0.1.2 → puffinparse-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "puffinparse"
-version = "0.1.2"
+version = "0.1.3"
 description = "One API for every OCR / document-parsing provider (Reducto, Extend, LlamaParse, ...). Rust core, Python SDK, open benchmark."
 readme = "README.md"
 license = { text = "MIT" }

puffinparse-0.1.2/crates/puffinparse-core/README.md

@@ -1,17 +0,0 @@
-# puffinparse-core
-
-Rust core of [PuffinParse](https://github.com/ajinkyashejul/puffinparse): a single API
-for every OCR / document-parsing provider (Reducto, Extend, LlamaParse, …).
-
-```rust
-use puffinparse_core::{ocr, OcrRequest};
-
-#[tokio::main]
-async fn main() -> Result<(), puffinparse_core::Error> {
-    let resp = ocr(OcrRequest::from_path("invoice.pdf").model("reducto/standard")).await?;
-    println!("{} pages, ${:.4}: {}", resp.usage.pages, resp.cost_usd.unwrap_or(0.0), resp.markdown);
-    Ok(())
-}
-```
-
-See the repository README for the Python SDK, CLI and benchmark.