Invoice OCR Extractor

Convert invoice PDFs, JPGs, PNGs, and scans into a reviewable Excel workbook. The application runs locally on the bookkeeper's computer. Documents are sent only to the AI provider and model selected during installation.

It produces one row per uploaded document in Invoices, plus a normalized Line Items sheet when line items are found. It supports batches of up to 50 documents while preserving the upload order.

What it solves

Bookkeepers often receive invoices in mixed layouts and formats, then need to retype or reconcile them one document at a time. This project turns a batch of invoice PDFs, images, and scans into a single, reviewable workbook: one document per row in Invoices, with a separate normalized Line Items sheet when present.

It is designed to be installed once on a bookkeeper's computer, then opened by double-clicking a Desktop launcher. The application is a local browser interface; it is not a hosted service and does not require a developer workflow after setup.

What this project adds around LangExtract

LangExtract is the final structured, grounded extraction layer. This repository adds the invoice-specific application around it:

• visual ingestion for PDF, JPG, PNG, and scanned documents;
• a bookkeeping schema for invoice headers and line items;
• document routing, conservative normalization, and review flags;
• batch processing with upload order preserved in a two-sheet Excel workbook;
• a simple local frontend and a Desktop launcher for macOS and Windows;
• provider setup, a tiny public PDF-and-image validation, and an optional live stress test.

This project is independent and is not affiliated with or endorsed by Google or the LangExtract project.

Start here: install with Codex, Claude Code, or another coding agent

Give the agent this repository URL and this instruction:

Read AGENTS.md completely. Install Invoice OCR Extractor on this computer for a bookkeeper. Ask which AI provider and vision-capable model they want to use, then request only the minimum credential required by that provider. Run the required synthetic PDF-and-image validation. Leave the working Invoice OCR Extractor launcher on the Desktop. Do not run the optional stress test unless I explicitly request it.

The agent will install Python 3.12 through uv, install the small runtime dependency set, configure the selected provider/model, validate the full pipeline, and create the Desktop launcher.

Provider and model choice

There is no automatic provider or model default. Installation explicitly asks for both. These are recommended starting profiles, not requirements:

Provider route	Suggested vision and extraction model
OpenRouter	google/gemini-2.5-flash
Google AI Studio	gemini-2.5-flash

Any model is acceptable only if it can reliably read the required PDF/JPG/PNG input and complete the LangExtract step. openrouter, gemini, and a best-effort openai_compatible route are included. A different provider, including AWS, may need a small adapter and provider-specific credentials such as region/profile settings. The coding agent must follow docs/PROVIDERS.md and make the synthetic validation pass before leaving the installation in place.

What the bookkeeper uses

After a successful setup, double-click Invoice OCR Extractor on the Desktop. It starts the local server only if needed and opens http://127.0.0.1:8099 in the default browser. The visible launcher is intentionally simple; do not open frontend/index.html directly because it needs the local backend.

Manual installation

If no coding agent is available, run one of these commands from the repository:

# macOS
./setup.sh

# Windows PowerShell
.\setup.ps1

The installer asks for provider, model, and the credential required for that choice. It makes two small real provider calls using the public synthetic fixtures: one PDF and one PNG. This confirms credential, vision, LangExtract, extraction, and Excel output before the Desktop launcher is created. See docs/INSTALL.md.

Architecture

PDF / JPG / PNG
  -> selected vision-capable model: faithful transcript + route
  -> LangExtract: grounded bookkeeping fields and line items
  -> conservative normalization
  -> Excel: Invoices + optional Line Items

Every document follows this order. LangExtract is always the final financial-field extractor. If a file contains multiple invoices, the app flags it for review rather than inventing one merged invoice.

The canonical schema is in backend/schema.py. Default output does not include full addresses, email, banking instructions, barcode payloads, or medical information.

Optional evaluation and stress testing

Normal installation runs only the tiny validation described above. The optional evals/ suite contains public fictional fixtures, expected output, and a separate live stress-test command. It is not part of installation or CI.

Sources and acknowledgements

The application builds on public open-source projects. See THIRD_PARTY_NOTICES.md for the upstream sources, their roles in this repository, and links to their licenses.

Privacy and local limits

• The app binds only to 127.0.0.1.
• Uploads remain in memory for the request. Excel exports expire after 24 hours.
• Defaults are 20 MB per file, 50 files per batch, 100 MB per batch, and three simultaneous documents.
• Do not process a document unless its selected AI provider's terms and data policy are acceptable for that document.

Development

uv sync --group dev
uv run pytest -m "not live"
uv run ruff check .

Live evaluation is opt-in. It requires a configured provider and must use only the public synthetic fixtures.

Public-repository rules

This repository intentionally excludes secrets, real invoices, exports, transcripts, logs, Cloudflare/R2 configuration, and the private legacy OCR project. The project is released under the MIT License.

Author

Built and maintained by Carlos Altamirano.