DocuPurse / src /validator.py
Zayeemk's picture
Initial commit: DocuParse AI complete implementation
26b8deb
Raw History Blame Contribute Delete
9.86 kB
"""Deterministic validation logic for DocuParse AI.
This module performs all arithmetic, date, and structural validation.
No LLM calls are made here - all logic is pure Python with Decimal arithmetic.
"""
from __future__ import annotations
from decimal import Decimal
from typing import List, Optional
from .schemas import DocumentExtraction, LineItem, ValidationCheck, ValidationResult
from .normalizer import normalise_date
TOLERANCE = Decimal("0.01")
REQUIRED_FIELDS: dict = {
"invoice": {
"errors": ["document_id", "vendor", "document_date", "total"],
"warnings": ["line_items", "subtotal", "tax"],
},
"receipt": {
"errors": ["vendor", "document_date", "total"],
"warnings": ["payment_method"],
},
"purchase_order": {
"errors": ["document_id", "vendor", "document_date"],
"warnings": ["line_items", "total"],
},
"unknown": {
"errors": [],
"warnings": [],
},
}
def validate_line_items(line_items: List[LineItem]) -> List[ValidationCheck]:
"""Validate each line item: quantity * unit_price should equal line_total."""
checks = []
for i, item in enumerate(line_items):
label = item.description or f"Item {i + 1}"
if item.quantity_decimal is None or item.unit_price_decimal is None:
checks.append(ValidationCheck(
name=f"line_item_{i + 1}_calculation",
passed=True,
severity="INFO",
message=f"[{label}] Skipped - quantity or unit_price not available.",
))
continue
expected = item.quantity_decimal * item.unit_price_decimal
if item.line_total_decimal is None:
checks.append(ValidationCheck(
name=f"line_item_{i + 1}_calculation",
passed=True,
severity="INFO",
expected=str(expected),
actual=None,
message=f"[{label}] line_total not extracted; expected {expected}.",
))
continue
diff = abs(expected - item.line_total_decimal)
passed = diff <= TOLERANCE
checks.append(ValidationCheck(
name=f"line_item_{i + 1}_calculation",
passed=passed,
severity="ERROR" if not passed else "INFO",
expected=f"{expected:.2f}",
actual=f"{item.line_total_decimal:.2f}",
difference=f"{diff:.2f}",
message=(
f"[{label}] {item.quantity_decimal} x {item.unit_price_decimal} = "
f"{expected:.2f}; extracted line_total = {item.line_total_decimal:.2f}. "
+ ("PASS" if passed else f"MISMATCH - difference {diff:.2f}")
),
))
return checks
def validate_subtotal(extraction: DocumentExtraction) -> Optional[ValidationCheck]:
"""Validate sum of line item totals against document subtotal."""
valid_totals = [
item.line_total_decimal
for item in extraction.line_items
if item.line_total_decimal is not None
]
if not valid_totals:
return None
calculated = sum(valid_totals, Decimal("0"))
if extraction.subtotal_decimal is None:
return ValidationCheck(
name="subtotal_reconciliation",
passed=True,
severity="INFO",
expected=f"{calculated:.2f}",
actual=None,
message=f"Calculated subtotal from line items: {calculated:.2f}. Document subtotal not extracted.",
)
diff = abs(calculated - extraction.subtotal_decimal)
passed = diff <= TOLERANCE
return ValidationCheck(
name="subtotal_reconciliation",
passed=passed,
severity="WARNING" if not passed else "INFO",
expected=f"{calculated:.2f}",
actual=f"{extraction.subtotal_decimal:.2f}",
difference=f"{diff:.2f}",
message=(
f"Sum of line items: {calculated:.2f}; Document subtotal: {extraction.subtotal_decimal:.2f}. "
+ ("PASS" if passed else f"MISMATCH - difference {diff:.2f}")
),
)
def validate_total(extraction: DocumentExtraction) -> Optional[ValidationCheck]:
"""Validate: subtotal + tax + shipping - discount = total."""
if extraction.subtotal_decimal is None or extraction.total_decimal is None:
return ValidationCheck(
name="total_reconciliation",
passed=True,
severity="INFO",
message="Total reconciliation skipped - subtotal or total not available.",
)
tax = extraction.tax_decimal or Decimal("0")
shipping = extraction.shipping_decimal or Decimal("0")
discount = extraction.discount_decimal or Decimal("0")
expected = extraction.subtotal_decimal + tax + shipping - discount
diff = abs(expected - extraction.total_decimal)
passed = diff <= TOLERANCE
return ValidationCheck(
name="total_reconciliation",
passed=passed,
severity="ERROR" if not passed else "INFO",
expected=f"{expected:.2f}",
actual=f"{extraction.total_decimal:.2f}",
difference=f"{diff:.2f}",
message=(
f"Calculated total ({extraction.subtotal_decimal:.2f} + {tax:.2f} tax "
f"+ {shipping:.2f} shipping - {discount:.2f} discount = {expected:.2f}); "
f"Document total: {extraction.total_decimal:.2f}. "
+ ("PASS" if passed else f"MISMATCH - difference {diff:.2f}")
),
)
def validate_dates(extraction: DocumentExtraction) -> List[ValidationCheck]:
"""Validate document_date and due_date."""
checks = []
if extraction.document_date is None:
checks.append(ValidationCheck(
name="date_validation",
passed=True,
severity="INFO",
message="document_date not extracted.",
))
else:
normalised = normalise_date(extraction.document_date)
if normalised is None:
checks.append(ValidationCheck(
name="date_validation",
passed=False,
severity="WARNING",
actual=extraction.document_date,
message=f"document_date '{extraction.document_date}' could not be parsed to a valid calendar date.",
))
else:
checks.append(ValidationCheck(
name="date_validation",
passed=True,
severity="INFO",
actual=normalised,
message=f"document_date is valid: {normalised}.",
))
if extraction.due_date is not None and extraction.document_date is not None:
norm_due = normalise_date(extraction.due_date)
norm_doc = normalise_date(extraction.document_date)
if norm_due and norm_doc:
if norm_due < norm_doc:
checks.append(ValidationCheck(
name="due_date_validation",
passed=False,
severity="WARNING",
expected=f">= {norm_doc}",
actual=norm_due,
message=f"due_date ({norm_due}) is earlier than document_date ({norm_doc}).",
))
else:
checks.append(ValidationCheck(
name="due_date_validation",
passed=True,
severity="INFO",
message=f"due_date ({norm_due}) is on or after document_date ({norm_doc}). PASS",
))
return checks
def validate_required_fields(extraction: DocumentExtraction) -> List[ValidationCheck]:
"""Validate required fields for the document type."""
checks = []
doc_type = extraction.document_type
required = REQUIRED_FIELDS.get(doc_type, REQUIRED_FIELDS["unknown"])
def check_field(field_name: str, severity: str) -> ValidationCheck:
value = getattr(extraction, field_name, None)
if field_name == "line_items":
present = isinstance(value, list) and len(value) > 0
else:
present = value is not None and str(value).strip() != ""
return ValidationCheck(
name=f"required_field_{field_name}",
passed=present,
severity=severity if not present else "INFO",
actual=str(value) if present else None,
message=(
f"Field '{field_name}' is present." if present
else f"Required field '{field_name}' is missing for document type '{doc_type}'."
),
)
for field in required.get("errors", []):
checks.append(check_field(field, "ERROR"))
for field in required.get("warnings", []):
checks.append(check_field(field, "WARNING"))
return checks
def run_all_validations(extraction: DocumentExtraction) -> ValidationResult:
"""Run all deterministic validations and return aggregated result."""
all_checks = []
all_checks.extend(validate_line_items(extraction.line_items))
sub_check = validate_subtotal(extraction)
if sub_check:
all_checks.append(sub_check)
total_check = validate_total(extraction)
if total_check:
all_checks.append(total_check)
all_checks.extend(validate_dates(extraction))
all_checks.extend(validate_required_fields(extraction))
errors = [c.message for c in all_checks if not c.passed and c.severity == "ERROR"]
warnings = [c.message for c in all_checks if not c.passed and c.severity == "WARNING"]
if errors:
status = "INVALID"
is_valid = False
elif warnings:
status = "WARNING"
is_valid = True
else:
status = "VALID"
is_valid = True
return ValidationResult(
is_valid=is_valid,
overall_status=status,
checks=all_checks,
warnings=warnings,
errors=errors,
)