Skip to main content

TinyDoc 0.2.0 — local-first grounded document extraction

Extract receipt/invoice fields as schema-validated JSON with per-field evidence (quote + OCR bbox) and confidence. Runs locally with Ollama; no API key, no cloud, no telemetry.

Status (2026-11-06): the SDK and evaluation harness are measured. The first-party 256M model is retired (OCRBench 0.0%) and the SmolVLM2-2.2B SFT track is closed (no gain over base). The working product is the engine + trust layer, not the old checkpoint. Full analysis: docs/v3_plan.md.

Measured results (SROIE public-train-derived clean-100, n=100)

Engine Field F1 Address Schema Median latency Errors
Qwen2.5-VL-3B (ollama:qwen2.5vl:3b) 0.9475 0.86 1.00 14.1 s 0
Qwen3-VL-2B-Instruct (ollama:qwen3-vl:2b-instruct) 0.9200 0.84 1.00 7.0 s 0
Hybrid v2 first-party (hybrid_2p2b) 0.603 0.37 0.93 ~8 s —
PP-OCR + heuristics 0.376 0.03 — — —
Tesseract + regex 0.227 — 0.60 — —

Caveat: these are not external benchmark numbers. The 100-doc set is a duplicate-filtered split of the public SROIE train pool; Qwen may have seen it during pretraining. The original 100-doc set is 60% leaked. Use the numbers for same-document engine comparisons, not as a generalization claim. The next eval adds CORD/FUNSD/invoices and a private wild set.

Install

From PyPI (use this once 0.2.0 is published):

pip install tinydoc

From the repo:

pip install ./sdk
# editable for development:
pip install -e ./sdk

If pip install tinydoc resolves to 0.1.2, that is the legacy 256M API; use the source install above until 0.2.0 is uploaded. Core deps: pydantic, pillow, jsonschema. Optional extras:

pip install './sdk[ocr]'      # pytesseract for evidence + ocr_regex
pip install './sdk[ocr-pp]'   # RapidOCR ONNX evidence
pip install './sdk[smolvlm2]' # optional local HF SmolVLM2 engine

For the default engine, install Ollama and pull a base:

ollama pull qwen2.5vl:3b            # quality default
ollama pull qwen3-vl:2b-instruct    # fast tier (use -instruct, not the thinking tag)

System tesseract is needed for OCR-span evidence (brew install tesseract on macOS).

Quick start

from tinydoc import ReceiptPipeline

# Quality default: Qwen2.5-VL-3B
pipe = ReceiptPipeline("ollama:qwen2.5vl:3b")

# Fast tier: Qwen3-VL-2B-Instruct, ~2x faster
# pipe = ReceiptPipeline("ollama:qwen3-vl:2b-instruct")

result = pipe.extract("receipt.jpg")
print(result.fields)        # {"company": ..., "date": ..., "address": ..., "total": ...}
print(result.schema_valid)  # True/False (JSON Schema)
print(result.confidence)    # 0..1 aggregate
for field in result.field_results:
    print(field.name, field.value, field.confidence, field.evidence)

CLI:

tinydoc extract ./receipts/ --engine ollama:qwen2.5vl:3b \
    --out results.jsonl --overlay overlays/

Overlay PNGs draw OCR-span evidence boxes and field labels (tinydoc.draw_overlay).

Engines

Engine id What it does
ollama / ollama:qwen2.5vl:3b Quality default; free, local
ollama:qwen3-vl:2b-instruct Fast tier; 1.9 GB Q4, ~2x faster
auto Ollama if reachable; OCR floor if the schema would fail
ocr_regex Offline floor (Tesseract + rules)
mlx_2p2b First-party v2 edge engine (MLX SmolVLM2-2.2B 4-bit)
hybrid_2p2b v2 product path: MLX fields + frozen F3 OCR address

Do not set Ollama format: "json" — constrained decoding truncates long addresses and can drop total. The SDK uses unconstrained prompts, JSON salvage, and prompt-v1.

Environment

  • TINYDOC_OLLAMA_TIMEOUT (default 180 s) — raise to 600 for slow local runs.
  • TINYDOC_OLLAMA_NUM_CTX (default 8192) — Ollama context window. The implicit 4096 rejected 2481×3508 scans with HTTP 400; keep 8192 for full pages.

Evidence and honesty

  • Evidence kind is always ocr_span (RapidOCR word boxes), not VLM-predicted boxes. Treat it as provenance, not as model grounding. A 100-box probe measured VLM bbox hit@0.5 of 0.20 (2B) and 0.04 (3B), below the 0.70 product gate, so OCR spans remain the shipped path.
  • The schema is packaged (tinydoc/schemas/sroie_receipt.schema.json); validation uses jsonschema.
  • Confidence is a heuristic, not a probability. Evidence-off runs are constant (0.4025; field ECE 0.52–0.55). The default evidence-on path measures field ECE 0.115–0.135 raw and 0.005–0.014 after document-grouped isotonic OOF; document-level confidence is not calibrated (ECE 0.09–0.10). Use field-level scores for review routing only.
  • Every published number must recompute from evaluation/phase0/results/: python3 evaluation/phase0/recompute_scores.py must exit 0.
  • The 256M model card and the v2 decision are kept for reproducibility; neither is a current performance claim.

Layout

sdk/tinydoc/
  pipeline.py   # engines, schema, sanitize, confidence, ReceiptPipeline
  evidence.py   # OCR-span evidence
  overlay.py    # draw bboxes + labels
  cli.py        # tinydoc extract
  schemas/      # JSON Schema per doc type

License

Apache 2.0

Metadata

Release files for tinydoc 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tinydoc 0.2.0
File Size Uploaded Provenance Actions
tinydoc-0.2.0.tar.gz 25.1 kB Without provenance Details for tinydoc-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tinydoc 0.2.0
File Interpreter ABI Platform Actions
tinydoc-0.2.0-py3-none-any.whl Python 3 none any Details for tinydoc-0.2.0-py3-none-any.whl

Total release size: 49.4 kB

Release files / tinydoc-0.2.0.tar.gz

Download URL tinydoc-0.2.0.tar.gz
Size 25.1 kB
Tags Source
SHA-256 checksum
How to use checksums
afc1e7dfe523821e843863bb0e18cbef304a5d9fffca1315eeb325549fbd3586
BLAKE2b-256 checksum
How to use checksums
a3670cfddd611b2322a6cd06bc3b0d943784ee8f87444ae0a54fbf1b1dc97a96
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.7

Release files / tinydoc-0.2.0-py3-none-any.whl

Download URL tinydoc-0.2.0-py3-none-any.whl
Size 24.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b9d3c81f1af0fe3fe6a926cd080b9df9df284e194efcddc12355fffca310f5db
BLAKE2b-256 checksum
How to use checksums
2feb5152b75308c4c253e378cf34ba823ed569c649099a5fc599d06858aa1c02
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.14.7

Security for tinydoc 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page