DocuPurse / docs /validation_logic.md
Zayeemk's picture
Initial commit: DocuParse AI complete implementation
26b8deb
|
Raw History Blame Contribute Delete
3.21 kB
ο»Ώ# 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
```python
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:
```python
>>> 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.