"""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, )