fastdocparse 0.1.0__py3-none-any.whl

docextract/__init__.py

@@ -0,0 +1,48 @@
+"""docextract — extract structured data from semi-structured documents using any
+OpenAI-compatible LLM, with per-field grounding and confidence.
+
+    from docextract import Schema, Field, LLMClient, DocumentParser
+
+    schema = Schema(name="Invoice", fields=[Field(name="total", description="Grand total", type="number")])
+    client = LLMClient(model="gpt-4o-mini", api_key="sk-...")
+    result = DocumentParser(client).extract(document_bytes, schema)
+"""
+
+from .cache import Cache, InMemoryCache
+from .config import ExtractionConfig
+from .grounding import Issue, check_substring, cross_check, date_parseable_rule, numeric_sum_rule, validate_field_constraints
+from .llm_client import LLMClient, LLMClientError
+from .parser import DocumentParser, EmptyDocumentError, UnknownIngestionKindError, register_default_ingestion_handler
+from .result import ExtractionMeta, ExtractionResult, FieldResult
+from .schema import Field, Schema
+from .schema_compiler import compile_schema_from_description
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("docextract")
+except Exception:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "Schema",
+    "Field",
+    "LLMClient",
+    "LLMClientError",
+    "DocumentParser",
+    "EmptyDocumentError",
+    "UnknownIngestionKindError",
+    "register_default_ingestion_handler",
+    "ExtractionConfig",
+    "Cache",
+    "InMemoryCache",
+    "ExtractionResult",
+    "FieldResult",
+    "ExtractionMeta",
+    "Issue",
+    "check_substring",
+    "cross_check",
+    "validate_field_constraints",
+    "numeric_sum_rule",
+    "date_parseable_rule",
+    "compile_schema_from_description",
+]

docextract/cache.py

@@ -0,0 +1,72 @@
+"""Pluggable caching for DocumentParser.extract(). Off by default — pass a cache instance to opt in.
+
+Caching is skipped whenever custom `rules` are passed to extract(), since a rule is an
+arbitrary callable that can't be safely fingerprinted — caching would risk returning a
+result validated under a different rule than the one just requested.
+"""
+
+import hashlib
+import json
+from collections import OrderedDict
+from typing import Any, Callable, Dict, Optional, Protocol
+
+from .config import ExtractionConfig
+from .schema import Schema
+
+
+class Cache(Protocol):
+    def get(self, key: str) -> Optional[Dict[str, Any]]: ...
+    def set(self, key: str, value: Dict[str, Any]) -> None: ...
+
+
+class InMemoryCache:
+    """Process-local cache. Good for a long-running batch job or server process; lost on restart.
+
+    Pass max_size to cap memory use — oldest-accessed entries are evicted once the cap is
+    hit (LRU). Leave it None (default) only for short-lived scripts/batch jobs where the
+    process exits before the cache could grow unbounded.
+    """
+
+    def __init__(self, max_size: Optional[int] = None):
+        if max_size is not None and max_size <= 0:
+            raise ValueError(f"max_size must be positive, got {max_size}")
+        self._max_size = max_size
+        self._store: "OrderedDict[str, Dict[str, Any]]" = OrderedDict()
+
+    def get(self, key: str) -> Optional[Dict[str, Any]]:
+        if key not in self._store:
+            return None
+        self._store.move_to_end(key)
+        return self._store[key]
+
+    def set(self, key: str, value: Dict[str, Any]) -> None:
+        self._store[key] = value
+        self._store.move_to_end(key)
+        if self._max_size is not None:
+            while len(self._store) > self._max_size:
+                self._store.popitem(last=False)
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+
+def make_cache_key(
+    document_bytes: bytes,
+    schema: Schema,
+    kind: str,
+    config: ExtractionConfig,
+    handler: Callable[..., str],
+) -> str:
+    """Fingerprint a (document, schema, ingestion kind, config, handler) combination.
+
+    handler is included, not just kind, because handlers are registered per
+    DocumentParser instance — two instances can register different handlers under the
+    same kind name, and a cache shared between them must not conflate the two.
+    Identity is process-local (qualified name + id()), which matches InMemoryCache's own
+    process-local lifetime — it isn't meant to survive a restart anyway.
+    """
+    document_digest = hashlib.sha256(document_bytes).hexdigest()
+    schema_digest = hashlib.sha256(schema.model_dump_json().encode()).hexdigest()
+    config_digest = hashlib.sha256(json.dumps(config.__dict__, sort_keys=True).encode()).hexdigest()
+    handler_identity = f"{getattr(handler, '__module__', '?')}.{getattr(handler, '__qualname__', repr(handler))}:{id(handler)}"
+    return hashlib.sha256(f"{document_digest}:{schema_digest}:{kind}:{config_digest}:{handler_identity}".encode()).hexdigest()

docextract/cli.py

@@ -0,0 +1,140 @@
+"""Command-line entrypoint: extract fields from a document without writing code.
+
+Usage:
+    docextract extract document.pdf invoice_schema.json
+    docextract extract receipt.jpg shipment_schema.json --model llama3 --base-url http://localhost:11434/v1
+"""
+
+import importlib
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+from pydantic import ValidationError
+
+from .llm_client import LLMClient, LLMClientError
+from .parser import DocumentParser, EmptyDocumentError, UnknownIngestionKindError
+from .schema import Schema
+from .schema_compiler import compile_schema_from_description
+
+
+def _load_plugins() -> None:
+    """Import modules listed in DOCEXTRACT_PLUGINS (comma-separated) so they can call
+    parser.register_default_ingestion_handler() on import — the only way a custom
+    ingestion kind (DOCX, XLSX, ...) becomes reachable from this CLI, since a fresh CLI
+    process otherwise only knows the built-in "pdf"/"image" handlers.
+
+    Security note: this imports and runs arbitrary Python from wherever DOCEXTRACT_PLUGINS
+    points, at CLI startup, with no sandboxing — the same trust model as PYTHONSTARTUP or
+    DJANGO_SETTINGS_MODULE. That's fine for a user pointing it at their own plugin on their
+    own machine, which is the only supported use. Never let this env var be set from an
+    untrusted source (e.g. a request parameter in a hosted service built on this CLI).
+    """
+    plugin_spec = os.environ.get("DOCEXTRACT_PLUGINS", "")
+    for module_name in filter(None, (p.strip() for p in plugin_spec.split(","))):
+        importlib.import_module(module_name)
+
+
+_load_plugins()
+
+app = typer.Typer(
+    add_completion=False,
+    help="Extract structured data from a PDF/PNG/JPG using a schema file you define — no coding required.",
+)
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg"}
+SUPPORTED_EXTENSIONS = IMAGE_EXTENSIONS | {".pdf"}
+
+
+@app.command()
+def extract(
+    file: Path = typer.Argument(..., exists=True, readable=True, help="Path to the PDF/PNG/JPG document."),
+    schema: Path = typer.Argument(..., exists=True, readable=True, help="Path to a .json or .yaml schema file listing the fields to extract."),
+    model: str = typer.Option("gpt-4o-mini", "--model", "-m", help="Model name, e.g. gpt-4o-mini, llama3."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="OpenAI-compatible API base URL. Omit for OpenAI; use e.g. http://localhost:11434/v1 for Ollama."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="LLM_API_KEY", help="API key. Not needed for local Ollama."),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Write the JSON result to this file instead of printing it."),
+    kind: Optional[str] = typer.Option(None, "--kind", help="Override ingestion routing (e.g. 'docx' for a custom handler loaded via DOCEXTRACT_PLUGINS). Defaults to auto-detecting pdf/image from the file extension."),
+):
+    """Extract the fields defined in SCHEMA from FILE and print the result as JSON."""
+    if kind is None and file.suffix.lower() not in SUPPORTED_EXTENSIONS:
+        typer.echo(f"Unsupported file type {file.suffix!r}. Supported: .pdf, .png, .jpg, .jpeg (or pass --kind).", err=True)
+        raise typer.Exit(code=1)
+
+    try:
+        doc_schema = Schema.from_file(schema)
+    except (ValidationError, ValueError, OSError) as e:
+        typer.echo(f"Could not load schema from {schema}: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    client = LLMClient(base_url=base_url, api_key=api_key, model=model)
+    document_parser = DocumentParser(client=client)
+
+    is_image = file.suffix.lower() in IMAGE_EXTENSIONS
+    document_bytes = file.read_bytes()
+
+    try:
+        result = document_parser.extract(document_bytes, doc_schema, is_image=is_image, kind=kind)
+    except EmptyDocumentError as e:
+        typer.echo(f"Extraction failed: {e}", err=True)
+        raise typer.Exit(code=1)
+    except LLMClientError as e:
+        typer.echo(f"Could not complete extraction: {e}", err=True)
+        raise typer.Exit(code=1)
+    except UnknownIngestionKindError as e:
+        typer.echo(f"{e} (check --kind is spelled correctly and its plugin is loaded via DOCEXTRACT_PLUGINS)", err=True)
+        raise typer.Exit(code=1)
+    except ValueError as e:
+        typer.echo(f"Extraction failed: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    result_json = json.dumps(result, indent=2, default=str)
+
+    if output:
+        try:
+            output.parent.mkdir(parents=True, exist_ok=True)
+            output.write_text(result_json)
+        except OSError as e:
+            typer.echo(f"Could not write output to {output}: {e}", err=True)
+            raise typer.Exit(code=1)
+        typer.echo(f"Wrote result to {output}")
+    else:
+        typer.echo(result_json)
+
+
+@app.command(name="schema-from-text")
+def schema_from_text(
+    description: str = typer.Argument(..., help="Plain-English description of the fields you want extracted, e.g. \"invoice number, total price, and a list of line items with product name and quantity\"."),
+    output: Path = typer.Option(..., "--output", "-o", help="Where to save the generated schema (.json)."),
+    model: str = typer.Option("gpt-4o-mini", "--model", "-m", help="Model name, e.g. gpt-4o-mini, llama3."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="OpenAI-compatible API base URL. Omit for OpenAI; use e.g. http://localhost:11434/v1 for Ollama."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", envvar="LLM_API_KEY", help="API key. Not needed for local Ollama."),
+):
+    """Turn a plain-English description of the fields you want into a schema file.
+
+    Review the generated file before using it with `extract` — the LLM proposes field
+    names and types from your description, and a wrong guess here affects every
+    document you later run against this schema.
+    """
+    client = LLMClient(base_url=base_url, api_key=api_key, model=model)
+    try:
+        doc_schema = compile_schema_from_description(description, client)
+    except (ValueError, LLMClientError) as e:
+        typer.echo(f"Could not generate a schema: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    try:
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(doc_schema.model_dump(), indent=2))
+    except OSError as e:
+        typer.echo(f"Could not write schema to {output}: {e}", err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo(f"Saved schema '{doc_schema.name}' with {len(doc_schema.fields)} field(s) to {output}")
+    typer.echo("Review it, then run: docextract extract <your_document> " + str(output))
+
+
+if __name__ == "__main__":
+    app()

docextract/config.py

@@ -0,0 +1,38 @@
+"""Tunable extraction parameters, previously hardcoded inline in parser.py."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ExtractionConfig:
+    """Knobs for a DocumentParser run. Override per-instance instead of editing source."""
+
+    # The single page cap: ingestion reads (and chunks/merges across) up to this
+    # many pages. A document with more pages than this is flagged truncated —
+    # there used to be two separate, disconnected limits here (a smaller one
+    # actually used for ingestion, a larger one only used for the truncation
+    # flag), which meant a document could silently lose pages while still being
+    # reported as "not truncated." One limit now, so the flag is honest.
+    max_pages: int = 15
+    chunk_max_tokens: int = 3000
+    pdf_render_dpi: int = 150
+    max_image_dim: int = 1536
+    ocr_min_confidence: float = 0.3
+    # Chunks are processed sequentially by default (1) — safe, deterministic order.
+    # Raise this to fan LLM calls for independent chunks out over threads; chunks are
+    # I/O-bound network calls, so a plain ThreadPoolExecutor is enough (no asyncio needed).
+    max_concurrent_chunks: int = 1
+
+    def __post_init__(self):
+        if self.max_pages <= 0:
+            raise ValueError(f"max_pages must be positive, got {self.max_pages}")
+        if self.chunk_max_tokens <= 0:
+            raise ValueError(f"chunk_max_tokens must be positive, got {self.chunk_max_tokens}")
+        if self.pdf_render_dpi <= 0:
+            raise ValueError(f"pdf_render_dpi must be positive, got {self.pdf_render_dpi}")
+        if self.max_image_dim <= 0:
+            raise ValueError(f"max_image_dim must be positive, got {self.max_image_dim}")
+        if not 0.0 <= self.ocr_min_confidence <= 1.0:
+            raise ValueError(f"ocr_min_confidence must be between 0 and 1, got {self.ocr_min_confidence}")
+        if self.max_concurrent_chunks <= 0:
+            raise ValueError(f"max_concurrent_chunks must be positive, got {self.max_concurrent_chunks}")

docextract/example_schemas.py

@@ -0,0 +1,13 @@
+"""Pre-built schemas with few-shot examples for common document types.
+
+Loaded from schemas/*.json rather than declared twice — schemas/invoice.json is the
+single source of truth; editing it updates both the CLI template and this import.
+"""
+
+from pathlib import Path
+
+from .schema import Schema
+
+_SCHEMAS_DIR = Path(__file__).parent / "schemas"
+
+INVOICE_SCHEMA = Schema.from_file(_SCHEMAS_DIR / "invoice.json")

docextract/grounding.py

@@ -0,0 +1,306 @@
+"""Grounding and validation checks for extracted data."""
+
+import logging
+import re
+import signal
+import threading
+from datetime import datetime
+from typing import Any, Dict, List, Callable, Optional
+from dataclasses import dataclass
+from .schema import Schema
+
+logger = logging.getLogger(__name__)
+
+
+def _is_present(value: Any) -> bool:
+    """False for None and for empty/whitespace-only strings — both mean "nothing was
+    really extracted here," which a bare `value is None` check misses. A required field
+    that comes back "" must not silently pass as present (and must not be trivially
+    "grounded" either, since an empty string is a substring of anything)."""
+    if value is None:
+        return False
+    if isinstance(value, str) and not value.strip():
+        return False
+    return True
+
+
+class _PatternTimeout(Exception):
+    pass
+
+
+def _regex_matches_with_timeout(pattern: str, value: str, timeout: float = 1.0) -> Optional[bool]:
+    """Guard re.fullmatch against a catastrophically backtracking pattern (e.g.
+    "^(a+)+$" against a long near-miss string), since `pattern` is arbitrary user- or
+    LLM-supplied regex that can otherwise hang indefinitely.
+
+    Two approaches were tried and rejected before this one:
+    - A background *thread* with join(timeout): doesn't work. CPython's `re` engine
+      holds the GIL for the whole backtracking search, so a hung regex thread starves
+      the main thread too and the timeout never fires (confirmed by testing).
+    - A separate *process* with a hard kill: works in isolation, but this application
+      loads a native ML runtime at import time (RapidOCR/onnxruntime, for local OCR).
+      Spawning a subprocess alongside that runtime crashed the whole process with a
+      native SIGABRT on exit ("recursive_mutex lock failed") — confirmed by running it
+      through the real CLI, not just a unit test. Not safe here.
+
+    SIGALRM actually interrupts a mid-backtrack regex call in CPython (confirmed by
+    testing) and needs no subprocess — but signal handlers only work on the main thread.
+    On a non-main thread (e.g. inside aextract()'s background-thread wrapper) or on a
+    platform without SIGALRM (Windows), this runs the match with no timeout at all —
+    a narrower, documented gap rather than a mechanism that looked safe but wasn't.
+    """
+    can_use_signal = hasattr(signal, "SIGALRM") and threading.current_thread() is threading.main_thread()
+
+    if not can_use_signal:
+        try:
+            return re.fullmatch(pattern, value) is not None
+        except re.error:
+            return None
+
+    def _on_alarm(signum, frame):
+        raise _PatternTimeout()
+
+    previous_handler = signal.signal(signal.SIGALRM, _on_alarm)
+    signal.setitimer(signal.ITIMER_REAL, timeout)
+    try:
+        return re.fullmatch(pattern, value) is not None
+    except _PatternTimeout:
+        logger.warning(
+            "Pattern check timed out after %.1fs (pattern=%r) — possible catastrophic "
+            "backtracking; skipping this field's format check.", timeout, pattern
+        )
+        return None
+    except re.error:
+        return None
+    finally:
+        signal.setitimer(signal.ITIMER_REAL, 0)
+        signal.signal(signal.SIGALRM, previous_handler)
+
+@dataclass
+class Issue:
+    field: str
+    message: str
+    severity: str = "warning"
+    kind: str = "cross_check"  # "cross_check" | "missing_required" | "invalid_format"
+
+
+_NUMBER_RE = re.compile(r'-?\d[\d,]*\.?\d*')
+
+
+def _as_number(value: Any) -> Optional[float]:
+    """Parse an int/float or a numeric-looking string (currency symbols, thousands separators) into a float."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        cleaned = re.sub(r'^[^\d\-]*', '', value.strip()).replace(',', '')
+        try:
+            return float(cleaned)
+        except ValueError:
+            return None
+    return None
+
+
+def _extract_numbers(text: str) -> List[float]:
+    numbers = []
+    for match in _NUMBER_RE.findall(text):
+        try:
+            numbers.append(float(match.replace(',', '')))
+        except ValueError:
+            continue
+    return numbers
+
+
+_DATE_CANDIDATE_RE = re.compile(
+    r'\d{4}[/-]\d{1,2}[/-]\d{1,2}'           # 2021-04-22, 2021/04/22
+    r'|\d{1,2}[/-]\d{1,2}[/-]\d{2,4}'         # 22/04/2021, 04-22-2021
+    r'|\d{1,2}\s?[A-Za-z]{3,9}\s?\d{2,4}'     # 22Apr2021, 22 April 2021
+    r'|[A-Za-z]{3,9}\s\d{1,2},?\s\d{2,4}'     # April 22, 2021
+)
+
+_DATE_FORMATS = [
+    "%Y-%m-%d", "%Y/%m/%d",
+    "%m/%d/%Y", "%d/%m/%Y", "%m-%d-%Y", "%d-%m-%Y",
+    "%d%b%Y", "%d %b %Y", "%d%B%Y", "%d %B %Y",
+    "%b %d, %Y", "%B %d, %Y", "%b %d %Y", "%B %d %Y",
+]
+
+
+def _parse_date_any(text: str):
+    """Try each known date format in turn; return a date object or None."""
+    text = text.strip()
+    for fmt in _DATE_FORMATS:
+        try:
+            return datetime.strptime(text, fmt).date()
+        except ValueError:
+            continue
+    return None
+
+
+def check_substring(value: Any, source_text: str, numeric: bool = False, date: bool = False) -> bool:
+    """
+    Check if the value is grounded (found) in the source text using fuzzy substring matching.
+    Returns True if grounded, False otherwise.
+
+    numeric: opt in for fields declared type "number"/"currency" — compares by parsed
+    numeric value (tolerant of formatting like "1,234.50" vs 1234.5). Leave False for
+    text/ID fields (invoice numbers, container numbers, etc.) where an all-digit value
+    is still a string identity, not a number, and "0100" must not be treated as
+    equal to "100".
+
+    date: opt in for fields declared type "date" — compares by parsed calendar date, so
+    a source document's "22Apr2021" still grounds a normalized "2021-04-22" even though
+    the strings don't match at all. Without this, every reformatted-but-correct date gets
+    flagged ungrounded, which is a false alarm, not a real hallucination.
+    """
+    if value is None:
+        return True
+
+    if isinstance(value, list):
+        if not value:
+            return True
+        return all(check_substring(item, source_text) for item in value)
+
+    if isinstance(value, dict):
+        if not value:
+            return True
+        return all(check_substring(v, source_text) for v in value.values())
+
+    val_str = str(value).lower()
+    source_lower = source_text.lower()
+
+    # Exact lowercase match
+    if val_str in source_lower:
+        return True
+
+    # Numeric comparison: catches formatting differences (1,234.50 vs 1234.5)
+    # that the naive digit-concatenation fallback below gets wrong or right by luck.
+    # Opt-in only (see docstring) so digit-string IDs aren't coerced into numbers.
+    if numeric:
+        num_val = _as_number(value)
+        if num_val is not None:
+            return any(abs(n - num_val) < 0.01 for n in _extract_numbers(source_text))
+
+    # Date comparison: catches reformatting (22Apr2021 -> 2021-04-22) that no string-based
+    # match, fuzzy or otherwise, can see past. Opt-in for the same reason numeric is.
+    if date:
+        target_date = _parse_date_any(str(value))
+        if target_date is not None:
+            for candidate in _DATE_CANDIDATE_RE.findall(source_text):
+                if _parse_date_any(candidate) == target_date:
+                    return True
+
+    # Fuzzy match ignoring non-alphanumeric chars
+    val_clean = re.sub(r'\W+', '', val_str)
+    source_clean = re.sub(r'\W+', '', source_lower)
+    
+    if val_clean and val_clean in source_clean:
+        return True
+        
+    return False
+
+
+def validate_field_constraints(schema: Schema, extracted: Dict[str, Any]) -> List[Issue]:
+    """Check schema-declared constraints (required, pattern, enum) against extracted values.
+
+    Runs automatically for every schema, independent of any user-supplied cross_check rules —
+    these constraints are properties of the schema itself (any domain), not custom business logic.
+    """
+    issues: List[Issue] = []
+    for f in schema.fields:
+        value = extracted.get(f.name)
+        is_missing = not _is_present(value) or (f.type == "list" and not value)
+
+        if is_missing:
+            if f.required:
+                issues.append(Issue(
+                    field=f.name,
+                    message=f"'{f.name}' is required but was not found in the document",
+                    severity="error",
+                    kind="missing_required",
+                ))
+            continue
+
+        if f.type == "list":
+            continue  # pattern/enum constraints apply to sub_fields on their own, not implemented here
+
+        if f.pattern and isinstance(value, str) and _regex_matches_with_timeout(f.pattern, value) is False:
+            issues.append(Issue(
+                field=f.name,
+                message=f"'{value}' does not match required pattern {f.pattern!r} for '{f.name}'",
+                kind="invalid_format",
+            ))
+
+        if f.enum and value not in f.enum:
+            issues.append(Issue(
+                field=f.name,
+                message=f"'{value}' is not one of the allowed values for '{f.name}': {f.enum}",
+                kind="invalid_format",
+            ))
+
+    return issues
+
+
+def numeric_sum_rule(list_field: str, total_field: str, item_key: str = "amount", tolerance: float = 0.01) -> Callable[[Dict[str, Any]], Optional[List[Issue]]]:
+    """Build a rule flagging total_field when it doesn't match the sum of item_key across list_field."""
+
+    def _rule(extracted: Dict[str, Any]) -> Optional[List[Issue]]:
+        total = extracted.get(total_field)
+        items = extracted.get(list_field)
+        if total is None or not items:
+            return None
+        try:
+            total_val = float(total)
+            calc_val = sum(float(item.get(item_key, 0) or 0) for item in items)
+        except (TypeError, ValueError):
+            return None
+        if abs(calc_val - total_val) > tolerance:
+            return [
+                Issue(field=total_field, message=f"{total_field} ({total_val}) does not match sum of {list_field}.{item_key} ({calc_val})"),
+                Issue(field=list_field, message=f"Sum of {item_key} ({calc_val}) does not match {total_field} ({total_val})"),
+            ]
+        return None
+
+    return _rule
+
+
+def date_parseable_rule(field_name: str, formats: Optional[List[str]] = None) -> Callable[[Dict[str, Any]], Optional[List[Issue]]]:
+    """Build a rule flagging field_name when its value doesn't parse as a date in any given format."""
+    from datetime import datetime
+
+    candidates = formats or ["%Y-%m-%d", "%m/%d/%Y", "%d/%m/%Y", "%Y/%m/%d"]
+
+    def _rule(extracted: Dict[str, Any]) -> Optional[List[Issue]]:
+        val = extracted.get(field_name)
+        if val is None:
+            return None
+        for fmt in candidates:
+            try:
+                datetime.strptime(str(val), fmt)
+                return None
+            except ValueError:
+                continue
+        return [Issue(field=field_name, message=f"'{val}' is not a parseable date")]
+
+    return _rule
+
+
+def cross_check(schema: Schema, extracted: Dict[str, Any], rules: List[Callable[[Dict[str, Any]], Optional[List[Issue]]]]) -> List[Issue]:
+    """
+    Run custom cross-check rules on the extracted data.
+    Each rule is a callable taking the extracted dict and returning a list of Issues (or None).
+    """
+    issues = []
+    if not rules:
+        return issues
+        
+    for rule in rules:
+        try:
+            result = rule(extracted)
+            if result:
+                issues.extend(result)
+        except Exception:
+            logger.exception("Cross-check rule %r raised an exception", getattr(rule, "__name__", rule))
+            
+    return issues