InvoiceGuard AI

Agentic accounts-payable automation for German e-invoicing — built on LangGraph, with human-in-the-loop approval, fraud detection, an MCP server and an eval suite that gates CI.

InvoiceGuard takes supplier invoices from any channel — scanned PDFs, e-mails with attachments, or native XRechnung / ZUGFeRD e-invoices — and runs them through a stateful agent that extracts the data, checks it the way an experienced AP clerk would, matches it against purchase orders and goods receipts, scores fraud risk, and then either posts it automatically, pauses for a human decision, or rejects it — with a tamper-evident audit trail for every step and an EN 16931 XRechnung file as output.

Why this problem

Germany is moving all domestic B2B invoicing to structured e-invoices: businesses have had to be able to receive EN 16931 e-invoices since 1 Jan 2025, companies above €800k turnover must issue them from 1 Jan 2027, and everyone from 1 Jan 2028 (Wachstumschancengesetz, §14 UStG). Most SMEs still receive a mix of PDFs, scans and e-mails — and accounts payable is also the #1 target for business-email-compromise fraud ("our bank details have changed").

InvoiceGuard is a reference implementation of how an AI agent should handle that safely:

• The LLM extracts, deterministic code decides. The model never approves a payment; routing is an explicit, testable policy.

• Humans stay in control of anything risky, through a durable LangGraph interrupt() that can wait hours and survive restarts.

• Every decision is explainable — named validation rules and weighted risk signals, not a black box.

• It's measurable — a golden-set eval runs in CI and blocks merges on regressions, including a hard gate of zero unsafe auto-approvals.

Related MCP server: Payment-Risk-Exception-AI-Agent-MCP

What it does

Architecture

flowchart LR
    subgraph Intake
      A[PDF / scan] --> I
      B[E-mail .eml] --> I
      C[XRechnung UBL<br/>ZUGFeRD CII] --> I
      I[ingest]
    end
    I --> G[guard<br/>prompt-injection scan]
    G --> K{classify}
    K -- delivery note / reminder / other --> R[reject]
    K -- invoice --> E[extract<br/>LLM structured output<br/>or native XML]
    E --> V[validate<br/>§14 UStG · EN 16931 · IBAN]
    V -- misread? feed errors back --> E
    V --> M[3-way match<br/>PO · goods receipt]
    M --> S[risk score<br/>BEC / duplicate / outlier]
    S --> D{decide<br/>deterministic policy}
    D -- clean, low risk, < limit --> P[post to ERP<br/>+ XRechnung export]
    D -- anything else --> H[[human review<br/>interrupt]]
    D -- duplicate / wrong addressee --> R
    H -- approve --> P
    H -- reject --> R
    P & R --> L[(hash-chained<br/>audit log)]

Each box is a LangGraph node; state is checkpointed per case (thread_id), so a case waiting for a reviewer is just a paused graph that any process — the API, the UI, the MCP server or a fresh worker — can resume with Command(resume=...).

src/invoiceguard/
├── graph.py         # LangGraph state machine + approval policy
├── extraction.py    # LLM extractor (init_chat_model + structured output) & offline extractor
├── validation.py    # deterministic checks: UStG, EN 16931, IBAN, VAT
├── matching.py      # 3-way match
├── risk.py          # explainable fraud scoring
├── guardrails.py    # prompt-injection detection, spotlighting, PII masking
├── xrechnung.py     # UBL export, UBL + CII parsing
├── ingest.py        # PDF / XML / e-mail intake
├── erp.py           # ERP adapter (SQLite stand-in for SAP / DATEV / Odoo)
├── audit.py         # tamper-evident audit trail
├── service.py       # facade used by API, MCP, CLI and evals
├── api.py           # FastAPI + review UI
└── mcp_server.py    # FastMCP server
evals/               # golden set + eval harness (CI gate)
data/samples/        # 10 synthetic documents covering every path

Quick start

git clone https://github.com/JoshilFernandes/invoiceguard-ai.git
cd invoiceguard-ai
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

python -m invoiceguard demo          # runs all 10 sample documents, no API key needed
python -m invoiceguard serve         # → http://localhost:8000  (click "Load 10 demo documents")

Or with Docker (API on :8000, MCP server on :8765):

docker compose up --build

Use a real LLM

pip install -e ".[groq]"                         # or [openai] / [anthropic] / [ollama]
cp .env.example .env
# set INVOICEGUARD_LLM=groq:llama-3.3-70b-versatile and GROQ_API_KEY=...
python evals/run_evals.py                        # same eval suite, now against the LLM

Connect it to Claude Desktop (MCP)

{
  "mcpServers": {
    "invoiceguard": {
      "command": "python",
      "args": ["-m", "invoiceguard.mcp_server"],
      "cwd": "/path/to/invoiceguard-ai"
    }
  }
}

Then ask: "What's waiting for my approval?" → "Show me the risk signals on the Havelland invoice" → "Reject it — the bank change wasn't confirmed." The decision resumes the paused graph and lands in the same audit trail as UI decisions.

Tools: process_invoice, list_pending_reviews, get_invoice_case, decide_invoice, vendor_master_data (IBANs masked), ap_dashboard.

Demo corpus & results

Ten synthetic documents, each built to exercise one path (all companies, VAT IDs and IBANs are fictitious):

Eval gate (runs on every push — see evals/report.md):

API

Interactive docs at /docs.

Design decisions

• Deterministic policy over LLM judgement. The approval decision is a ~30-line pure function (graph.decide). That makes it auditable, unit-testable and immune to prompt injection: a manipulated document can at worst produce wrong fields, which the validators and matcher then catch.

• Two extractors, one interface. The offline extractor makes CI reproducible and gives a baseline to benchmark LLMs against with the same eval harness.

• Native e-invoices skip the LLM. Structured XRechnung/ZUGFeRD is parsed directly — cheaper, exact, and the direction the German market is heading.

• Self-repair only for "extraction" errors. Arithmetic that doesn't add up might be a misread, so the model gets one more look with the validator's feedback; if the error persists, it's treated as a real problem with the invoice.

• Durable HITL. interrupt() + a SQLite checkpointer (swap for Postgres in production) means approvals can take days without holding compute.

• Explainable risk. Every point of the risk score is a named rule with a human-readable reason, so a reviewer knows what to verify (e.g. "call the vendor on a known number").

Production notes / roadmap

• Swap erp.py for a real adapter (SAP S/4HANA, DATEV, Odoo, lexoffice) and the SQLite checkpointer for langgraph-checkpoint-postgres

• OCR for image-only scans (Azure Document Intelligence / Tesseract) before extraction

• Run the official KoSIT validator on generated XRechnung files

• Peppol access-point integration for sending/receiving

• LangSmith / OpenTelemetry tracing and per-vendor extraction accuracy dashboards

• Vendor-specific few-shot examples learned from reviewer corrections

Development

make test     # 23 unit/integration tests (graph, HITL resume, self-repair, API, MCP, audit tampering)
make eval     # golden-set evaluation, writes evals/report.md
make lint     # ruff
make samples  # regenerate the synthetic corpus and ERP seed data

Author

Joshil Fernandes — AI Automation Engineer, Berlin · LinkedIn · GitHub

MIT licensed. Synthetic data only; not tax or legal advice.