Skip to content

v0.10.0 - Adaptive Template Fingerprinting, LRU Config Cache and Guardrailed Auto-Tuner

Choose a tag to compare

View all tags
@Edge-Explorer Edge-Explorer released this 08 Sep 05:22
· 67 commits to main since this release
v0.10.0
0128646

Overview

v0.10.0 introduces the Adaptive Template Intelligence Layer to Universal Parser. This enables the engine to generate content-agnostic structural layout fingerprints, recognize recurring document templates via fuzzy similarity matching, cache per-template parsing configurations, and auto-tune parsing hyperparameters using feedback error signals with strict mathematical guardrails.

What's New in v0.10.0

1. Content-Agnostic Structural Layout Fingerprinting

  • 2D Spatial Histogram Discretization: Quantizes element bounding boxes $(x_0, y_0, x_1, y_1)$ normalized to $[0.0, 1.0] \times [0.0, 1.0]$ into a fixed $10 \times 10$ occupancy and density matrix.
  • Categorical Element Type Distribution: Computes normalized proportions of document element types (headings, paragraphs, tables, figures, code blocks).
  • Deterministic SHA-256 Digest: Generates content-independent layout hashes that remain identical even when document text values change (e.g. across monthly invoices or templated filings).

2. Multi-Modal Layout Similarity Engine

  • Weighted Cosine-Jaccard Metric: Combines 2D spatial layout alignment ($70%$ weight) and element type categorical distribution ($30%$ weight) into a normalized similarity score $\in [0.0, 1.0]$.
  • Enables robust fuzzy template matching for layout variations with minor coordinate shifts or added table rows.

3. Thread-Safe LRU Template Config Cache

  • Dual Retrieval: Provides $O(1)$ exact hash lookups with automatic fallback to fuzzy similarity matching ($\ge 0.85$ threshold).
  • Least Recently Used (LRU) Eviction: Bounded in-memory capacity management.
  • Atomic Disk Persistence: Safe serialization and deserialization to JSON (.save() and .load()).

4. Error Gradient Auto-Tuning with Mathematical Guardrails

  • Coordinate Descent Tuning: Adjusts parser hyperparameters based on explicit or automated feedback signals (missed_heading, false_heading, missed_table, false_table, merged_columns, split_columns, ocr_quality).
  • Mathematical Guardrails: Parameter clipping constraints that prevent hyperparameters from drifting into degenerate or unstable regimes:
    • column_gap_threshold: $[10.0, 120.0]\text{ pt}$
    • heading_p95_ratio: $[1.05, 3.00]$
    • heading_p85_ratio: $[1.01, 2.50]$
    • min_table_confidence: $[0.30, 0.95]$
    • ocr_dpi: $[100, 300]$

Test Suite & Quality Verification

  • Total Unit Tests: 58 passed (100% pass rate across all 15 formats and adaptive modules).
  • Ruff Lint & Format: 0 errors, all checks passing.
  • Memory RSS: Zero memory leaks, strictly within the 250MB RAM budget.

Verification Commands

uv run pytest
uv run ruff check .
Assets 2
Loading