docket — local document AI, invoice & receipt OCR parser with LLMs

Turn scanned invoices, receipts, and contracts into structured, validated JSON using local OCR and vision-language models — and export them as EU e-invoices (XRechnung, ZUGFeRD / Factur-X, Peppol UBL, Facturae).

Apache-2.0 licensed: use it in your own products, commercial or not. Embed it as a Python library, run it as an HTTP service, or call the CLI.

Runs locally with Ollama or on any OpenAI-compatible API (Mistral, OpenAI, Azure, vLLM) · Pydantic schemas · Grounded citations · Zero hallucinations

Quick start: local invoice & receipt parsing

You need Tesseract on PATH (brew install tesseract, apt install tesseract-ocr) and an LLM: either Ollama with a text and a vision model pulled, or an OpenAI-compatible API key (see Configuration).

pip install docket-idp
docket invoice.pdf

Classification, OCR extraction, and validation all run against whichever models your environment or .env names.

{
  "doc_type": "invoice",
  "invoice_number": "FAC-2026-0042",
  "issue_date": "2026-03-15",
  "vendor_name": "Talleres Montjuïc S.A.",
  "subtotal": 1234.56,
  "tax_amount": 259.26,
  "total_amount": 1493.82,
  "currency": "EUR"
}

The process exits non-zero when validation fails, so it drops into a shell pipeline as-is.

Use it in your application

As a Python library

from docket import Invoice, export_document, process

result = process("invoice.pdf", enqueue_review=False)  # your app owns the review flow
if result.is_valid and isinstance(result.document, Invoice):
    print(result.document.vendor_name, result.document.total_amount)
    xml = export_document(result.document, "xrechnung")
else:
    print(result.review_reasons, result.validation_issues)

result.document is the typed schema (Invoice, Receipt, Contract, …); result.field_sources says where on the page each value was read.

As an HTTP service (any language)

docker run -p 8000:8000 -e DOCKET_API_KEY=secret ghcr.io/kazkozdev/docket
# or: pip install "docket-idp[api]" && docket-api --port 8000
curl -H "Authorization: Bearer secret" -F file=@invoice.pdf localhost:8000/process

The OpenAPI spec is in docs/openapi.json — generate a typed client for TypeScript, Java, C#, Go, etc. from it.

As a CLI

docket invoice.pdf                       # JSON on stdout, exit code 2 if invalid
docket invoice.pdf --export xrechnung    # e-invoice XML on stdout
docket --list-formats

Runnable versions of all three, a TypeScript client, a Mistral-backed docker-compose.yml and an exporter plugin are in examples/.

EU e-invoicing and ERP export

Need a format that isn't here? Register one in a few lines (register_exporter("my-erp", func, accepts=(Invoice,))), or ship it as its own pip package through the docket.exporters entry point — see examples/exporter_plugin. Always validate generated XML against your recipient's official validator (e.g. KoSIT for XRechnung) before going live.

Structured data extraction with Pydantic schemas

Each document type has a strict Pydantic schema, and the model fills it under a JSON Schema contract rather than being asked nicely for JSON. A result that fails validation is sent back to the model with the error attached.

docket invoice.pdf
python tui.py invoice.pdf        # same pipeline, live per-stage progress
streamlit run app.py             # browser UI with a document preview

European and American number conventions are both parsed, so 1.234,56 and 1,234.56 read as the same amount. Keyword rules cover English and Spanish.

Commercial contracts & CLM analysis

docket eval/golden_dataset/contract_services.txt

{
  "doc_type": "contract",
  "contract_title": "SERVICES AGREEMENT",
  "parties_a": ["Vertex Consulting LLC"],
  "parties_b": ["Meridian Retail Inc."],
  "effective_date": "2026-03-01",
  "expiration_date": "2027-03-01",
  "governing_law": "State of New York",
  "payment_terms": "within 30 days of invoice",
  "auto_renewal": false,
  "key_obligations": [
    "Party A shall deliver monthly infrastructure audits.",
    "Party A shall provide a dedicated support engineer during business hours.",
    "Party B shall pay Party A within 30 days of invoice."
  ]
}

Contracts undergo specialized legal validation: counterparty cross-checking (parties cannot contract with themselves), grounding checks (parties, governing law, payment terms, signatories, and liability caps must appear in the raw document), and automated risk assessment (unlimited liability, auto-renewal traps, notice and cure period bounds).

Human-in-the-loop (HITL) review queue for flagged documents

Low classification confidence, a failed extraction or an error-severity validation issue routes the document to a review queue instead of a database. Each entry gets a stable id, a status, the preserved original, and an audit history of who changed what.

docket eval/golden_dataset/invoice_bad_total.txt

doc_9479a6b321e02ab6de25  pending  invoice
    validation error: total_amount — subtotal + tax + shipping - discount = 270.60,
    total_amount says 500.00

That document prints Amount Due: 500.00 while its own subtotal and tax add up to 270.60. Nothing silently reconciles it.

Embedding docket in an app with its own review UI? Pass process(..., enqueue_review=False) (or set DOCKET_REVIEW_QUEUE_ENABLED=false) and act on result.needs_review / result.review_reasons yourself.

Document AI REST API with FastAPI and async worker

DOCKET_API_KEY=secret docket-api
curl -H "Authorization: Bearer secret" -F file=@invoice.pdf localhost:8000/process

POST /process runs synchronously; POST /jobs queues and returns 202 with a job id for GET /jobs/{id}. GET /review-queue lists what is waiting for a person, and /review-queue/{id}/original returns the document that produced it. Interactive OpenAPI docs at /docs.

Pipeline architecture: hybrid OCR, classification, and validation

Text comes from the cheapest source that works: a PDF text layer if there is one, Tesseract for scans, and a Vision-Language Model (VLM) only when OCR confidence is low or a cheap text model judges the scan unusable. Classification tries keyword rules, then a TF-IDF model, then an LLM — each tier runs only because the last was not confident. Extraction fills a Pydantic schema and cites, for every number, the verbatim line it was read from.

Validation is completely deterministic and never calls a model: it checks arithmetic, date ranges, IBAN mod-97 (ISO 7064 across Europe & Brazil), VAT check digits (all 27 EU member states, UK, Switzerland, Norway), national tax IDs (US EIN, Canadian BN, Brazilian CNPJ/CPF), and asserts that each cited line exists and contains the number claimed. Detailed flow in ARCHITECTURE.md.

document → text layer / OCR / VLM → classify → extract + cite → validate → JSON or review

Configuration

Full list in src/docket/config.py; LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY enable optional tracing.

Requirements

• Python 3.10+
• macOS or Linux
• Tesseract OCR on PATH
• An LLM: a running Ollama with one text and one vision model pulled, or an OpenAI-compatible API (Mistral La Plateforme keeps data in the EU)

Limitations

• Four document types: invoice, receipt, contract, boarding pass.
• Keyword rules and the TF-IDF corpus cover English and Spanish only.
• The vision model has been observed altering digits to make a page reconcile — a printed 450.00 read three times out of three as 480.00. No fix for that is in this repo.
• Line items carry no source citations, so the cited-source check does not cover them.
• The review queue is one file: durable on one node, not across hosts.
• Windows is untested; CI runs Linux only. 3.6–9.5 s per document, more when a page needs the vision model.

pip install docket-idp            # library + CLI
pip install "docket-idp[api]"     # + HTTP service (docket-api)
pip install "docket-idp[all]"     # + Streamlit UI, terminal UI, Langfuse tracing

git clone https://github.com/KazKozDev/docket.git
cd docket && python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

docker run -p 8000:8000 -v docket-data:/app/data ghcr.io/kazkozdev/docket
# or build it yourself: docker build -t docket .

pytest                                # none need a running LLM
python eval/run_eval.py               # accuracy, P/R/F1, latency on the golden set
python eval/benchmark_methods.py      # the rules vs TF-IDF vs LLM comparison