Skip to content

Quickstart

This page takes you from nothing to a processed invoice in a few minutes. You don't need an API key or network access after the install.

Install

pip install "invoice-agent[api,synth]"

Get the sample data

Write the 50 synthetic invoices, purchase orders, and receipts to dataset/:

invoice-agent generate-dataset

Process invoices

invoice-agent process dataset/invoices/016_b04.pdf dataset/invoices/005_q05.pdf \
  --pos dataset/purchase_orders.json --receipts dataset/receipts.json
016_b04.pdf: NEEDS REVIEW
  vendor  Brightforge Maschinenteile GmbH
  invoice BF-2026/0404
  date    2026-03-17
  total   EUR 409.05
  po      PO-2026-0114 (3-way)
  lines   2/2 matched to PO lines
  [!] PRICE_VARIANCE: Line 1 ('Zahnriemen HTD 8M / Timing belt HTD 8M', PO line 1): unit price 61.56 is 8.0% above the PO price 57.00 (tolerance 2.0% or 0.05).
005_q05.pdf: NEEDS REVIEW
  ...

Add --json for one JSON result per line, and --ledger ledger.json to keep duplicate and billed-quantity history across runs.

Score the pipeline

invoice-agent eval

eval runs all 50 invoices through the pipeline in submission order and prints field accuracy, decision accuracy, exception precision and recall, and a confusion matrix.

Run the web page and API

invoice-agent serve --pos dataset/purchase_orders.json --receipts dataset/receipts.json

Open http://localhost:8000, upload a PDF from dataset/invoices/, and see the extracted fields, the line matches, and the decision.

Use your own data

Pass your own POs and receipts as JSON, CSV, or SQLite. The formats are in Data loading. To change tolerances, pass --policy policy.json; see Concepts.