How to Build an AI Invoice Processing Agent That Extracts and Validates Financial Data

ai-invoice-agent/
├── app/
│   ├── __init__.py
│   ├── invoice_validator.py
│   └── dedupe_store.py
├── tests/
│   └── test_invoice_agent.py
└── requirements.txt

import re
from decimal import Decimal, ROUND_HALF_UP
from typing import List, Optional
from pydantic import BaseModel, Field, model_validator

GSTIN_REGEX = re.compile(r"^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z]{1}[1-9A-Z]{1}Z[0-9A-Z]{1}$")

def q2(val: Decimal) -> Decimal:
    return val.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)

class InvoiceLineItem(BaseModel):
    description: str
    quantity: Decimal = Field(..., gt=Decimal("0"))
    unit_price: Decimal = Field(..., ge=Decimal("0"))
    line_total: Decimal

    @model_validator(mode="after")
    def check_line_math(self) -> "InvoiceLineItem":
        expected = q2(self.quantity * self.unit_price)
        actual = q2(self.line_total)
        if abs(expected - actual) > Decimal("0.02"):
            raise ValueError(
                f"Line item math error for '{self.description}': "
                f"{self.quantity} * {self.unit_price} = {expected}, but extracted line_total is {actual}"
            )
        return self

class ExtractedInvoice(BaseModel):
    vendor_name: str
    vendor_tax_id: str = Field(..., description="Vendor GSTIN, VAT, or EIN")
    invoice_number: str
    invoice_date_iso: str
    currency: str = "INR"
    line_items: List[InvoiceLineItem] = Field(..., min_length=1)
    subtotal: Decimal
    cgst_amount: Decimal = Decimal("0.00")
    sgst_amount: Decimal = Decimal("0.00")
    igst_amount: Decimal = Decimal("0.00")
    total_tax_amount: Decimal
    grand_total: Decimal

    @model_validator(mode="after")
    def verify_invoice_arithmetic_and_tax(self) -> "ExtractedInvoice":
        if self.currency == "INR" and not GSTIN_REGEX.match(self.vendor_tax_id.strip().upper()):
            raise ValueError(f"Invalid Indian GSTIN format: {self.vendor_tax_id}")

        sum_lines = q2(sum((item.line_total for item in self.line_items), Decimal("0.00")))
        if abs(sum_lines - q2(self.subtotal)) > Decimal("0.05"):
            raise ValueError(f"Subtotal mismatch: sum of lines ({sum_lines}) != subtotal ({self.subtotal})")

        component_tax = q2(self.cgst_amount + self.sgst_amount + self.igst_amount)
        if component_tax > Decimal("0.00") and abs(component_tax - q2(self.total_tax_amount)) > Decimal("0.05"):
            raise ValueError(f"GST component sum ({component_tax}) != total_tax_amount ({self.total_tax_amount})")

        expected_grand = q2(self.subtotal + self.total_tax_amount)
        if abs(expected_grand - q2(self.grand_total)) > Decimal("0.05"):
            raise ValueError(
                f"Grand total mismatch: subtotal ({self.subtotal}) + tax ({self.total_tax_amount}) "
                f"= {expected_grand} != grand_total ({self.grand_total})"
            )
        return self

def normalize_invoice_key(vendor_tax_id: str, invoice_number: str) -> str:
    """Normalizes invoice number to catch 'INV-0042' vs 'INV42' duplicates."""
    clean_tax = re.sub(r"[^A-Z0-9]", "", vendor_tax_id.upper())
    clean_inv = re.sub(r"[^A-Z0-9]", "", invoice_number.upper()).lstrip("0")
    return f"{clean_tax}::{clean_inv or '0'}"

from decimal import Decimal
import pytest
from app.invoice_validator import InvoiceLineItem, ExtractedInvoice, normalize_invoice_key

def test_valid_gst_invoice_passes_decimal_checks():
    inv = ExtractedInvoice(
        vendor_name="Cloud Infra Pvt Ltd",
        vendor_tax_id="07AABCU9603R1ZP",
        invoice_number="INV-00984",
        invoice_date_iso="2026-10-15",
        currency="INR",
        line_items=[
            InvoiceLineItem(description="GPU Node Rental", quantity=Decimal("2"), unit_price=Decimal("15000.00"), line_total=Decimal("30000.00")),
            InvoiceLineItem(description="Block Storage", quantity=Decimal("1"), unit_price=Decimal("5000.00"), line_total=Decimal("5000.00")),
        ],
        subtotal=Decimal("35000.00"),
        cgst_amount=Decimal("3150.00"),
        sgst_amount=Decimal("3150.00"),
        total_tax_amount=Decimal("6300.00"),
        grand_total=Decimal("41300.00"),
    )
    assert inv.grand_total == Decimal("41300.00")

def test_tampered_or_misread_line_item_raises_error():
    with pytest.raises(ValueError, match="Line item math error"):
        InvoiceLineItem(
            description="Server Rack",
            quantity=Decimal("3"),
            unit_price=Decimal("1000.00"),
            line_total=Decimal("3800.00"),  # OCR misread 3000 as 3800
        )

def test_duplicate_invoice_key_normalization():
    k1 = normalize_invoice_key("07AABCU9603R1ZP", "INV-00042")
    k2 = normalize_invoice_key("07aabcu9603r1zp", "inv/42")
    assert k1 == k2