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

Turn scanned invoices, receipts, and contracts into structured, validated JSON using OCR and LLMs, then export them as EU e-invoices (XRechnung, Factur-X / ZUGFeRD, Peppol BIS, UBL, Facturae) and check them with the official EN 16931, Peppol, XRechnung and Factur-X rules. Use it as a Python library, an HTTP service, or a CLI. Apache-2.0, so commercial use is fine.

Ollama or any OpenAI-compatible API (Mistral, OpenAI, Azure, vLLM) · Pydantic schemas · Every value cited to its source line · Deterministic validation

Quick start

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

pip install docket-idp
docket process invoice.pdf                       # JSON result on stdout, exit code 2 if validation fails
docket process invoice.pdf --export xrechnung-ubl --validate-export   # e-invoice XML, checked with the official rules
docket validate-einvoice invoice.xml              # XSD + Schematron report for any UBL/CII XML or Factur-X PDF
docket schemas list                              # every document type, with its version

{
  "status": "succeeded",
  "document_type": "invoice",
  "schema_id": "invoice",
  "schema_version": "2.0",
  "extracted": {
    "invoice_number": "FAC-2026-0042",
    "issue_date": "2026-03-15",
    "seller": {"name": "Talleres Montjuïc S.A.", "tax_ids": [{"value": "A28015865", "scheme": "vat"}]},
    "buyer": {"name": "Aerolíneas del Sur S.L."},
    "subtotal": 1234.56,
    "tax_amount": 259.26,
    "total_amount": 1493.82,
    "currency": "EUR"
  },
  "field_sources": {"total_amount": {"page": 1, "quote": "Total factura: 1.493,82 €", "bbox": {"x0": 0.62, "y0": 0.71, "x1": 0.89, "y1": 0.73}}}
}

Use it in your application

Python library

from docket import ExportError, OcrOptions, ProcessOptions, ReviewOptions, export_document, process_document

options = ProcessOptions(
    document_type="invoice",                      # skip classification (or schema_model=YourModel)
    ocr=OcrOptions(backend="tesseract", fallbacks=["vlm"]),
    review=ReviewOptions(enqueue=False),          # your app owns the review flow
)
result = process_document("invoice.pdf", options)
try:
    xml = export_document(result, "xrechnung-ubl").content   # refuses invalid or unreviewed results
except ExportError:
    print(result.status, result.review_reasons)

result.document is the typed schema (Invoice, Receipt, Contract, …) and result.status is succeeded, needs_review or failed (with a structured error); unset options fall back to the DOCKET_* environment. result.field_sources gives the page, quote and bounding box each value was read from, and result.layout holds every page's words, lines, columns and tables with normalized coordinates.

Batches

from docket import BatchOptions, process_batch

batch = process_batch("scans/", options, BatchOptions(recursive=True, workers=4, checkpoint="run.jsonl"))
print(batch.succeeded, batch.needs_review, batch.failed, batch.metrics.document_seconds_median)

docket batch scans/ --recursive --format csv --output results.csv   # + results.line_items.csv

Results keep input order, one failing document never stops the rest (unless --fail-fast), and rerunning after an interruption skips documents already in the checkpoint. CSV columns are the same for every document type (document_number, document_date, issuer, recipient, currency, subtotal, tax_amount, total_amount plus status and review columns); line items go to a second CSV linked by document_id. Exit codes: 0 all succeeded, 1 partial (some failed or need review), 2 all failed, 3 configuration error.

HTTP service (any language)

docker run -p 8000:8000 -e DOCKET_API_KEY=secret ghcr.io/kazkozdev/docket
curl -H "Authorization: Bearer secret" -F file=@invoice.pdf localhost:8000/process
curl -H "Authorization: Bearer secret" -F files=@a.pdf -F files=@b.jpg localhost:8000/jobs

POST /process is synchronous. POST /jobs takes one or more files and returns 202 with a job to poll at GET /jobs/{id}; results come from /jobs/{id}/results/{index}, results.jsonl, results.csv and line-items.csv. Form fields choose a registered schema (document_type), the OCR chain and include_layout; an Idempotency-Key header makes retries safe; errors are {"error": {"code", "message"}}. /schemas, /ocr-backends and /export-formats describe the deployment, /review-queue serves flagged documents. Generate a typed client from docs/openapi.json; interactive docs are at /docs. Without Docker: pip install "docket-idp[api]" && docket-api.

examples/ has runnable scripts, a TypeScript client, a Mistral-backed docker-compose.yml and plugin packages.

Document types

A versioned catalog of 14 schemas (docket schemas list, GET /schemas):

Invoice-family schemas share Party, Address, TaxIdentifier, DocumentReference and BankAccount; results saved under an older schema version are migrated when read (docket.catalog.migrate). docket schemas show invoice prints a schema's metadata, cited fields and export formats; docket schemas json-schema invoice its JSON Schema.

To add your own, write a Pydantic model and register it:

from datetime import date
from docket import CitedDocument, Party, SchemaSpec, keywords, register_schema

class ParkingTicket(CitedDocument):      # CitedDocument adds page/quote citations
    ticket_number: str
    issuing_authority: Party
    issue_date: date
    fine: float

register_schema(SchemaSpec(
    schema_id="parking_ticket", version="1.0", model=ParkingTicket,
    description="Parking ticket / Strafzettel for a parking offence",   # read by the LLM classifier
    keywords=keywords("parking ticket", "strafzettel"),                  # free rules tier
    cited_fields=("ticket_number", "issuing_authority.name", "fine"),
))

Registered schemas are classified, extracted, citation-checked and exported like the built-in ones; give examples= sentences and the TF-IDF tier learns them too. A model can also be used without registering it: ProcessOptions(schema_model=ParkingTicket) or docket process file.pdf --schema mypkg.models:ParkingTicket. add_validator("invoice", fn) adds rules to any schema, and the docket.schemas entry point lets a separate package ship schemas. See examples/custom_document_type.py and examples/schema_plugin/.

Export formats

The EN 16931 exporters take an Invoice, TaxInvoice or CreditNote (a credit note becomes a UBL CreditNote or CII type 381). They refuse a document they can't represent faithfully instead of guessing: no line items (BR-16), a tax rate that can't be determined, tax that doesn't match the lines, or a discount spread over several rates. Only standard-rated (S) and zero-rated (Z) VAT is written. Recipients still check routing data the extraction can't know, e.g. a Peppol endpoint (seller.electronic_address with an EAS electronic_address_scheme) or the XRechnung Leitweg-ID (buyer_reference).

Add your own with register_exporter("my-erp", func, accepts=(Invoice,)) or the docket.exporters entry point. docket formats shows everything available.

E-invoice validation

pip install "docket-idp[einvoice]" adds offline validation with the official artifacts, vendored with their versions, licenses and SHA-256 checksums in src/docket/einvoice/resources/manifest.json: the UBL 2.1 and CII D16B XML Schemas, the CEN EN 16931 Schematron 1.3.16, KoSIT XRechnung Schematron 2.6.0 (XRechnung 3.0.2), OpenPeppol BIS Billing 3.0.20 and the Factur-X 1.09 profile schemas and Schematron. XSD runs in lxml, Schematron (XSLT 2.0) in SaxonC-HE; no Java, no network.

docket validate-einvoice invoice.xml                     # exit 0 valid, 2 invalid, 3 extra missing
docket validate-einvoice invoice.pdf --profile factur-x-en16931 --format json
curl -F file=@invoice.xml -F profile=xrechnung localhost:8000/validate/einvoice

from docket import EInvoiceValidationOptions, validate_einvoice

report = validate_einvoice("invoice.xml", EInvoiceValidationOptions(profile="peppol"))
report.valid, report.detected_format, report.profile, report.validation_resource_version
for issue in report.issues:        # code (BR-CO-15, PEPPOL-EN16931-R001, BR-DE-15, XSD), severity,
    print(issue.code, issue.layer, issue.location, issue.message)   # layer xsd/schematron, rule source

The profile comes from the document's specification identifier (BT-24) unless you pass one; when you do and the document declares another, the report carries DOCKET-PROFILE-MISMATCH. Schematron only runs on XML that passed the XML Schema. Factur-X / ZUGFeRD PDFs are validated from their embedded factur-x.xml / zugferd-invoice.xml; the PDF/A-3 container itself is not checked. export_document(..., ExportOptions(validate_einvoice=True)) validates right after export, and docket process --export FORMAT --validate-export does the same on the command line. python scripts/update_einvoice_resources.py rebuilds the artifacts from their pinned official downloads (--check verifies the vendored copy). See examples/validate_xrechnung.py and examples/validate_peppol.py.

How it works

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

• Text comes from the cheapest source that works, page by page: the PDF text layer, then the OCR backend (Tesseract by default; pluggable), then a vision model, which is used only when OCR confidence is low or a cheap text model judges the scan unusable. Every backend returns the same layout model — words with boxes, lines, columns, tables.
• Classification tries keyword rules, then TF-IDF, then an LLM. Each tier runs only when the one before it was unsure. Rules and TF-IDF cover English, Spanish, German, French, Italian, Dutch and Portuguese; any other language falls through to the LLM.
• Extraction fills a Pydantic schema under a JSON Schema contract and cites the verbatim line for every value. Output that fails the schema goes back to the model with the error attached.
• Validation never calls a model. It checks arithmetic (to the cent: an absolute 0.01 tolerance), dates, IBAN mod-97, VAT check digits (all 27 EU states, UK, CH, NO), national tax IDs, and that every cited line exists and contains the claimed value. Contracts also get counterparty, grounding and risk checks (unlimited liability, auto-renewal, notice periods).
• Review: low confidence, failed extraction or a validation error sends the document to a review queue that keeps the original and an audit history. Nothing is silently reconciled. An invoice whose Amount Due: 500.00 disagrees with its own 270.60 subtotal and tax is flagged, not fixed.

Also included: cross-document matching (invoice ↔ PO, three-way PO/waybill/invoice, invoice ↔ contract, receipt ↔ bank transactions) and a heuristic stamp, signature and alteration check (docket forensics file.pdf). Details are in ARCHITECTURE.md.

Configuration

Settings come from, in rising priority: built-in defaults, a TOML config file, the environment (or .env), and explicit arguments (ProcessOptions, CLI flags, HTTP form fields). The config file is --config PATH (docket and docket-api), else DOCKET_CONFIG, else ./docket.toml:

[ocr]
backend = "paddle"
fallbacks = ["tesseract", "vlm"]
languages = ["en", "de"]

[batch]
workers = 8

Every setting and its environment variable is in docket.example.toml; docket config show prints the effective values and where each came from, docket config check validates them. An invalid value, an unknown key or a missing config file stops the CLI (exit 3), docket-api and process_document() before any document is read, with every problem listed at once.

Limitations

• The TF-IDF tier is trained on a small embedded corpus (about 20 phrases per type), so it only answers when confident and leaves the rest to the LLM.
• --forensics is a pixel heuristic, not a trained vision model. It finds colored stamps and seals and handwriting in colored or black ink, but never reports black stamps, which it can't tell apart from logos or table graphics. Its confidence scores come from geometry and aren't calibrated probabilities.
• The vision model has been observed changing digits so that a page reconciles (a printed 450.00 read as 480.00 three times out of three). There is no fix for that in this repo.
• Line items carry no source citations, so the citation check doesn't cover them.
• The review queue is a single file: durable on one node, not across hosts.
• Windows is untested. A document takes a median of 6.4–22.7 s depending on the OCR backend (measured over 33 scans), longer 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]"     # + Langfuse tracing and e-invoice validation
pip install "docket-idp[paddle]"  # + PaddleOCR backend (--ocr-backend paddle)
pip install "docket-idp[einvoice]" # + official EN 16931 / Peppol / XRechnung / Factur-X validation

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
streamlit run examples/streamlit_demo.py   # demo UI: document preview + per-stage results

pytest                                # no test needs a running LLM
python eval/run_eval.py               # accuracy, P/R/F1, latency on the golden set
python eval/benchmark_methods.py      # rules vs TF-IDF vs LLM comparison (incl. confidence)
python eval/benchmark_ocr.py         # Tesseract vs Paddle (OCR-only + full pipeline) on the scans
python eval/benchmark_variance.py     # extraction stability: same document 10 times