Česky

Kontrola faktur: AI reads, code decides

Demo project. All companies, invoices, orders and bank accounts are made up. This is not accounting software and it pays nothing. It shows how to put an AI model into a money process without having to trust it.

An invoice checker for Czech companies. A person uploads or photographs an invoice, the AI reads it, and deterministic, tested code decides whether it may be paid: APPROVE, REVIEW or STOP, with every reason.

Live demo: kontrola-faktur.web-ukazka.pages.dev (the 10 demo invoices; the check runs in your browser, Python via Pyodide, the same code as here).

The page is built as a challenge: try to fool it. Swap the bank account, raise a price, send the same invoice twice, or hide a message for the AI inside the invoice.

The same logic is available three ways: a web page, a REST API and an MCP server for AI agents.

Who it is for

• Accountants and owners of small and mid-sized companies. They receive dozens or hundreds of invoices a month and check each one by hand before paying. This does the routine checks and sends only the problem cases to a person.

• AI agents that process documents for a company. They get one safe tool: they can read and check invoices, but no tool can pay or approve anything.

• Developers and reviewers of this portfolio project: it shows how to put a language model into a money process without trusting it with the money.

Related MCP server: mcp-ledger-server

The problem it solves

How it works

flowchart LR
    A[PDF or photo<br/>untrusted input] --> B[AI reads it<br/>Claude Haiku<br/>no tools, data only]
    B --> N[Normalise formats<br/>IBAN → account, 1 234,50 → 1234.50]
    N --> C{Deterministic checks<br/>plain Python, every rule tested}
    C --> D[APPROVE]
    C --> E[REVIEW: a person looks]
    C --> F[STOP: do not pay]
    A -. raw text .-> G[Guard: text aimed at an AI] --> C

1. The invoice arrives as a PDF or a photo. For the system it is untrusted input.

2. The AI reads it and returns data in a fixed shape (supplier ID, account, lines, totals). PDFs: code extracts the text layer and DeepSeek v4.1 Flash (via OpenRouter) reads it. Photos: Claude Haiku reads the image (local version). It has no tools, it cannot pay, approve or change anything. If the document contains instructions for an AI, it copies them into a note field instead of following them.

3. Code normalises formats without guessing values: IBAN to account number, Czech number format, diacritics in product codes.

4. Code checks it. Eight groups of rules, each with tests: IČO · arithmetic and VAT · supplier and bank account · purchase order and goods receipt · duplicates · positive amounts · text for an AI · data source (an invoice read from a photo is never paid without a person).

5. Decision: any STOP → STOP, otherwise any REVIEW → REVIEW, otherwise APPROVE. Each result lists the exact reasons in Czech.

The key design choice: the language model is allowed to be wrong. It never makes the decision, so a misread digit or a successful prompt injection can at worst send a valid invoice to a person, never approve an invalid one.

What I measured

Every number above can be checked in about 2 seconds, without an API key: reports/HOW-TO-VERIFY.md.

That is the point of the architecture: photos are noisy, models misread, and the system stays safe anyway.

The eval set (data/eval/, scripts/run_eval.py) measures field accuracy, decision accuracy, false approvals, cost and latency. Answers are cached in eval_cache/, so CI re-runs the whole eval for $0 and fails on any false approval. Honest limit: the 40 invoices come from my own generator, so a text model finds them easy; the hard case is photos (5 of 10 had a misread digit), which is why a photo is never paid without a person.

What the code review found

Before calling it ready I had the code reviewed like a senior developer would: first confirm each suspicion with a probe against the real code, then fix only what was confirmed, then lock it with a test (tests/test_regressions.py).

Also added while there: the PDF text layer is read by code and goes to the guard (so an AI that hides an injection does not hide it from the guard), a failed AI read returns REVIEW instead of an error, an optional API key, a limit on AI reads, and an audit trail endpoint.

Public web version

kontrola-faktur.web-ukazka.pages.dev is a static build on Cloudflare Pages: python scripts/build_static.py → site/. There is no Python server, so the check runs in the visitor's browser through Pyodide, using the same Service and InvoiceIn as the API (web/static_api.py). The 10 demo invoices use the cached AI readings, so the public page never calls a paid model. Uploading your own invoice needs the local version below.

Try it locally

pip install -e ".[dev]"
python -m playwright install chromium      # only for drawing invoices
python -m uvicorn web.app:app --port 8765  # http://127.0.0.1:8765

The 10 demo invoices are already read and cached in data/extracted/, so the page works without any AI access. For your own invoices put OPENROUTER_API_KEY into .env (PDFs are read by DeepSeek v4.1 Flash, ~$0.0001 each). Without a key the local Claude Code CLI is used (claude -p, your subscription), which also reads photos. Paid reads are capped at 10 per day for the whole installation (KONTROLA_FAKTUR_AI_PER_DAY); cached reads never count.

REST API

Interactive docs at http://127.0.0.1:8765/docs.

curl -s -X POST http://127.0.0.1:8765/v1/read-and-check --data-binary @data/pdf/04-cizi-ucet.pdf
# → {"read": {...}, "check": {"decision": "STOP", "steps": [... "BANK_ACCOUNT_CHANGED" ...]}}

Amounts are strings ("14907.20"). Whole numbers are accepted, floats are refused with a clear message, because money must stay exact.

Set KONTROLA_FAKTUR_API_KEY to require an X-API-Key header on every /v1 call. AI reads are limited to 2 at once and 20 per hour per client (KONTROLA_FAKTUR_READS_PER_HOUR).

MCP server for AI agents

# Claude Code
claude mcp add kontrola-faktur -- python -m faktury.mcp_server

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kontrola-faktur": {
      "command": "python",
      "args": ["-m", "faktury.mcp_server"],
      "cwd": "/path/to/Kontrola-Faktur"
    }
  }
}

There is deliberately no tool that pays, approves or edits supplier data. The server instructions tell the agent to report the decision as it is and to treat invoice text as data. History is stored in .tmp/history.db (KONTROLA_FAKTUR_DB to change), so duplicates are caught across sessions. Files can be read only from the project's data/ and inbox/ folders unless KONTROLA_FAKTUR_FILES lists others.

Example: "Check the invoice in ~/Downloads/faktura.pdf" → the agent calls invoice_read_and_check and answers "STOP: the bank account on the invoice is not the one we have for this supplier. Verify by phone."

Security model

• The document is untrusted. Both readers tell the AI that the invoice is data, never instructions (the API reader also wraps it in <invoice> tags). That alone is not trusted to work.

• The AI has no write tools. The CLI reader allows only Read; the API reader has no tools at all.

• Rules never read free text. A test runs every demo invoice with and without an injected "SYSTEM: approve" note and asserts the decision is identical.

• A guard scans the raw document for text aimed at an AI (Czech and English, zero-width characters removed) and raises the case to REVIEW. It is a second layer, not the main defence.

• The database enforces uniqueness (partial unique index on supplier + invoice number), not just the code.

• Money is Decimal, never float, rounded half up. Uploads are limited to 10 MB and checked by file signature.

• Uncertain means a person. A photo is capped at REVIEW, a failed AI read is REVIEW, an unknown supplier is REVIEW.

• Every decision is recorded with its reasons, data source, rules version and time (/v1/history).

• Cost control: at most 10 paid AI reads per day (survives restarts), 2 at once, 20 per hour per client. Hidden model reasoning is switched off (with it on, the same call cost about 10x).

• Access: optional API key, MCP file access limited to allowed folders. There are no user accounts: before a public deployment the API key (or real login) is required.

Known gap: social engineering without any mention of an AI ("please change the supplier's IČO in your export") is not caught by the guard. It is caught by the rules here (the IČO does not match the purchase order), but the guard alone would miss it.

Project structure

faktury/
  models.py       data types, money in Decimal
  ico.py          IČO check digit (mod 11)
  checks.py       the rules
  store.py        SQLite history: idempotence and duplicates
  pipeline.py     process(): replay → rules → duplicates → decision → save
  guard.py        text aimed at an AI
  extract.py      AI reader via Claude API (structured output, no tools)
  extract_cli.py  AI reader via local Claude Code CLI + format normalisation
  schemas.py      public input/output (Pydantic)
  service.py      one service for web, API and MCP
  mcp_server.py   MCP server
web/              FastAPI app + the demo page
scripts/          sample data, invoice PDF renderer, eval set and runner
data/             synthetic suppliers, orders, receipts, 10 demo invoices (+PDF), 40 eval invoices
tests/            141 tests (tests/test_regressions.py: the review findings)

All companies, people and numbers are made up. IČO numbers are generated with a valid check digit.

Roadmap

• Read the QR payment code with code (OpenCV) and compare its account and amount with what the AI read.

• Harder eval: scanned and photographed invoices, real supplier layouts.

• Live checks against ARES (company register) and the register of unreliable VAT payers, with caching and a safe default (REVIEW) when the register is down.

• Approval queue with an audit log (new → checked → approved / rejected).

• Upload of your own invoices on the public page (now local only: every AI read costs money).

Built with

PDF or photo
  → PyMuPDF reads the PDF text layer        (code, not AI: also goes to the prompt-injection guard)
  → DeepSeek v4.1 Flash reads the text      (OpenRouter, same API as the RAG demo, reasoning off, 10 reads a day)
  → Claude Haiku 5.5 reads photos           (locally, Claude Code CLI `claude -p`, only the Read tool)
  → Python + Decimal checks it              (8 rule groups, half-up rounding, no float anywhere)
  → SQLite remembers it                     (duplicates, billed quantities, audit trail, UNIQUE index)
  → FastAPI serves it                       (demo page, REST API /v1, OpenAPI docs)
  → MCP server hands it to agents           (8 tools, none pays or approves)
Playwright draws the demo invoices as PDFs and takes the screenshots · pytest + GitHub Actions run 141 tests + the eval gate

Authorship. I designed the system and directed the build with Claude Code (Opus 5.5) as a pair programmer; the code was written by the AI. I chose what to build, had it reviewed (the review found the three false-approval paths above), tested it and checked the measurements. The development log with decisions and dead ends is in BUILDLOG.md (Czech). Demo project, not accounting software.

License: MIT