Download src/validator.py from Zayeemk/DocuPurse: direct link, hf CLI and curl.
- Browser
- Download file 9.86 kB
-
https://huggingface.co/spaces/Zayeemk/DocuPurse/resolve/main/src/validator.py
- Command line
-
hf download hf://spaces/Zayeemk/DocuPurse/src/validator.py
-
curl -L -o validator.py https://huggingface.co/spaces/Zayeemk/DocuPurse/resolve/main/src/validator.py
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, | |
| ) | |