DocuPurse / docs /validation_logic.md
Zayeemk's picture
Initial commit: DocuParse AI complete implementation
26b8deb
|
Raw History Blame Contribute Delete
3.21 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade

ο»Ώ# DocuParse AI β€” Validation Logic

Overview

All validation in DocuParse AI is deterministic Python β€” no LLM calls, no probability. The system uses decimal.Decimal for all monetary arithmetic to avoid binary floating-point rounding errors.

Tolerance

TOLERANCE = Decimal("0.01")

A difference of up to Rs. 0.01 (or equivalent) is considered acceptable, accounting for legitimate rounding in document presentation.

1. Line Item Calculation Check

For each extracted line item:

expected_line_total = quantity * unit_price
difference = abs(expected_line_total - extracted_line_total)
passed = difference <= TOLERANCE

Example (PASS):

Laptop Stand: 2 x Rs. 1,500 = Rs. 3,000
expected = 3000.00, actual = 3000.00, diff = 0.00 β†’ PASS

Example (FAIL):

Keyboard: 3 x Rs. 2,000 = Rs. 6,000
expected = 6000.00, actual = 7000.00, diff = 1000.00 β†’ FAIL

Severity: ERROR

Items are skipped (INFO) if quantity or unit_price was not extracted.

2. Subtotal Reconciliation

calculated_subtotal = sum(line_item.line_total for all line items)
difference = abs(calculated_subtotal - document_subtotal)
passed = difference <= TOLERANCE

Example (PASS):

Items: 3000 + 6000 + 2500 = 11500
Document subtotal: 11500.00 β†’ PASS

Severity: WARNING (non-critical since documents sometimes include non-itemised charges)

3. Total Reconciliation

expected_total = subtotal + tax + shipping - discount
difference = abs(expected_total - document_total)
passed = difference <= TOLERANCE

Example (PASS β€” Sample Invoice A):

subtotal = 11500.00
tax = 2070.00
shipping = 0.00
discount = 0.00
expected = 13570.00
document_total = 13570.00 β†’ PASS

Example (FAIL β€” Validation Failure Demo):

subtotal = 11500.00
tax = 2070.00
expected = 13570.00
document_total = 14000.00
difference = 430.00 β†’ FAIL (ERROR)

Severity: ERROR β€” critical failure.

4. Date Validation

normalised_date = normalise_date(raw_date)
if normalised_date is None: WARNING
if due_date < document_date: WARNING

Date normalisation handles:

  • ISO: 2026-08-18 β†’ 2026-08-18
  • Indian: 18/08/2026 β†’ 2026-08-18
  • Textual: 18 August 2026 β†’ 2026-08-18

Severity: WARNING

5. Required Field Validation

Document Type Required (ERROR) Recommended (WARNING)
invoice document_id, vendor, document_date, total line_items, subtotal, tax
receipt vendor, document_date, total payment_method
purchase_order document_id, vendor, document_date line_items, total
unknown β€” β€”

Overall Status Determination

if any ERROR check fails:
    overall_status = "INVALID"
    is_valid = False
elif any WARNING check fails:
    overall_status = "WARNING"
    is_valid = True
else:
    overall_status = "VALID"
    is_valid = True

Why Decimal?

Python floats use binary representation:

>>> 11500 + 2070 == 13570
True
>>> 0.1 + 0.2
0.30000000000000004  # Not 0.3!

For financial documents even small rounding errors matter. Decimal("11500") + Decimal("2070") == Decimal("13570") is always exact.