universal-doc-parser 1.0.0__py3-none-any.whl

universal_doc_parser-1.0.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+universal_parser/__init__.py,sha256=aXTv6p_QoWsK5yyuRATxtnPkoTL3M_ju7AetSDRhbSY,1337
+universal_parser/adaptive/__init__.py,sha256=-y0YQaC-GrsGJejduofpE4Cm7lzcZeogpk-THo49RAc,476
+universal_parser/adaptive/config_cache.py,sha256=U4MQkO7SrNESpiR7UWw5dSulRqtUd7TEUj0we8ytmF4,4698
+universal_parser/adaptive/fingerprint.py,sha256=hwnk85msBHCtRW4wekH5bFH2pEaqLxH1v1FJEJJ1eEQ,4720
+universal_parser/adaptive/tuner.py,sha256=zT50xD2fs5nkYppI9DgzK5hzCzCwrU17P6Cx09uPdpY,3791
+universal_parser/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/core/engine.py,sha256=ZLDVP03MMxCEhUfUVBNf4CSIvHq4fwVi2p9pXhZjvEg,1725
+universal_parser/core/router.py,sha256=jJOE4qT3s9J-KlHjhuYZjT6bRKyHgeSLnM2QWYW1lk8,1387
+universal_parser/core/schema.py,sha256=vyB5MKwrFrRxAuIH7g4BAq3X3PavJ2fAr1gthkLqvJI,1787
+universal_parser/core/sniffer.py,sha256=GqUHRTJt-Fc8cXr-zm5ZwsGuUXFyf2oLCYwipCea2SE,3700
+universal_parser/enrichment/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/enrichment/vlm_enricher.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/exports/__init__.py,sha256=-1b3-EAbnEgjgglQVPG0jPrzrAwabmMxzXIHBG62YrY,17
+universal_parser/exports/to_chunks.py,sha256=wnEh0jD5YPrUeB9bwY-8ac1G1lc0wD8teHUDLjzSMak,3687
+universal_parser/exports/to_graph.py,sha256=AuqrtDkd270VL_leWWIJ9_Y22IUGWnW5GlZbUMHH6lw,3262
+universal_parser/exports/to_markdown.py,sha256=1_rgNL2GD3SQNdZXBtUI98w7ZxnMcYojiZ0gH0pLaig,985
+universal_parser/extractors/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/base.py,sha256=Vslbmb0fdd2e2a5j-e8GZX7pZBXMFq4yogQLhW0kf2c,1400
+universal_parser/extractors/images/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/images/scan_extractor.py,sha256=ftD2uitFlrAL7YmK8xyhJHeuMI0UWhwLfb2jUV3fZ8Y,2601
+universal_parser/extractors/mail/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/mail/mail_extractor.py,sha256=dpeDkdLERWFdjCCU4tkglO26iLdXbVDyLzPXuDr04R0,7530
+universal_parser/extractors/office/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/office/docx_extractor.py,sha256=pRfQjTd4P-W3iy5SNwf8HeECsQTthTf4_mbJQk4hHaI,4458
+universal_parser/extractors/office/legacy_extractor.py,sha256=Dq0c0oCZMoENie2qND1QoI_Qv1yUzijbcRTxYCa7rZY,3843
+universal_parser/extractors/office/pptx_extractor.py,sha256=7WxDmpQAxK8uYPe1Hwpkjhbun40nYiW4ehHaSOuNw6c,4074
+universal_parser/extractors/office/xlsx_extractor.py,sha256=Z06ayb0Z37lJVlgglanhmiadCogwwpKEBCN_5bewd7c,3438
+universal_parser/extractors/pdf/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/pdf/native.py,sha256=B36CvFYA22MYCQa9xmdnKsxsu43gxOTh2lLjxbgT28c,13352
+universal_parser/extractors/pdf/tables.py,sha256=Xqhcfq1uA1Q3sV2oXzVmUwDBxsStdtPbmMIRJfBBBTM,5501
+universal_parser/extractors/pdf/visual_onnx.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/structured/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/extractors/structured/csv_extractor.py,sha256=YKZgjyfOJdl-x8W5Q4lKam82QtwFRCu92XxSSBTnXUs,2999
+universal_parser/extractors/structured/json_xml_extractor.py,sha256=MNVOnJxLoWuf4s20PPRzi4aPOC6bar-EONsQX32xFb4,3835
+universal_parser/extractors/structured/parquet_extractor.py,sha256=RT6WUi1aMmtGYusV5F7yd7b4Y3vxGduykVrKvLN-YCw,1912
+universal_parser/extractors/web/__init__.py,sha256=qgz0BE4177sP3FVQqDifYgNKejYD-D1Dbq-YTY0we4w,17
+universal_parser/extractors/web/epub_extractor.py,sha256=9H5CI_Y7k046_ho38PojRi-iqxEr3b4XQ-w1Ii3_Dd8,2836
+universal_parser/extractors/web/html_extractor.py,sha256=7Erx1oncwCLmKx3Iz1gb2X8zh7mx5IqpQN5d_rMllHM,3977
+universal_parser/mcp/__init__.py,sha256=IjzqjjmYctuyTAGB4hZpd93bNmu0EMlHLTimYnIm42M,14
+universal_parser/mcp/server.py,sha256=ccyr3Sd2F2GLf7_lKwygZsR0HICQoesALt4sZGXqpq4,1848
+universal_parser/observability/__init__.py,sha256=6LpvpSKaK_W-UtEIfKIYF3VMWyjSlhByBIMW4WM-i3w,312
+universal_parser/observability/dashboard.py,sha256=vNpTAhDfaQf_tk3-5i81dMJggzh9IH-OrCho6InoRMU,7393
+universal_parser/observability/logger.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+universal_parser/observability/metrics.py,sha256=NQEFOXDKVH2QkHV4lrhebu7qLRQgQK9dgah7PHIvJn4,3084
+universal_doc_parser-1.0.0.dist-info/METADATA,sha256=Q5dxXh6tz_XdGPkmbCLl6NP-X_U6iv3AFJmaQ1C7giw,26771
+universal_doc_parser-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+universal_doc_parser-1.0.0.dist-info/licenses/LICENSE,sha256=TBBq_QxVzFx6N4MBDqm1ipgIA_nmeP0DJlLugIUK1ws,1069
+universal_doc_parser-1.0.0.dist-info/RECORD,,

universal_doc_parser-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

universal_doc_parser-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karan Shelar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

universal_parser/__init__.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+import universal_parser.extractors.images.scan_extractor
+import universal_parser.extractors.mail.mail_extractor
+import universal_parser.extractors.office.docx_extractor
+import universal_parser.extractors.office.legacy_extractor
+import universal_parser.extractors.office.pptx_extractor
+import universal_parser.extractors.office.xlsx_extractor
+
+# Import all extractors to trigger their @register decorators.
+# Without this, the router registry remains empty until the files are imported.
+import universal_parser.extractors.pdf.native
+import universal_parser.extractors.structured.csv_extractor
+import universal_parser.extractors.structured.json_xml_extractor
+import universal_parser.extractors.structured.parquet_extractor
+import universal_parser.extractors.web.epub_extractor
+import universal_parser.extractors.web.html_extractor  # noqa: F401
+
+# Import the main entry point to expose it at the root of the package
+from universal_parser.core.engine import parse
+from universal_parser.exports.to_chunks import to_chunks
+from universal_parser.exports.to_graph import to_graph
+from universal_parser.exports.to_markdown import to_markdown
+
+# Define what is exposed when doing: from universal_parser import *
+__all__ = ["__version__", "parse", "to_chunks", "to_graph", "to_markdown"]

universal_parser/adaptive/__init__.py

@@ -0,0 +1,17 @@
+from universal_parser.adaptive.config_cache import ParserConfig, TemplateConfigCache
+from universal_parser.adaptive.fingerprint import (
+    LayoutFingerprint,
+    compute_fingerprint,
+    fingerprint_similarity,
+)
+from universal_parser.adaptive.tuner import AdaptiveTuner, FeedbackSignal
+
+__all__ = [
+    "AdaptiveTuner",
+    "FeedbackSignal",
+    "LayoutFingerprint",
+    "ParserConfig",
+    "TemplateConfigCache",
+    "compute_fingerprint",
+    "fingerprint_similarity",
+]

universal_parser/adaptive/config_cache.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import json
+from collections import OrderedDict
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from universal_parser.adaptive.fingerprint import (
+    LayoutFingerprint,
+    fingerprint_similarity,
+)
+
+
+class ParserConfig(BaseModel):
+    """Hyperparameters and configuration tuned for a specific document layout template."""
+
+    column_gap_threshold: float = 30.0
+    heading_p95_ratio: float = 1.30
+    heading_p85_ratio: float = 1.15
+    table_detection_mode: str = "auto"  # "lattice", "stream", "auto"
+    ocr_dpi: int = 150
+    min_table_confidence: float = 0.60
+    custom_overrides: dict[str, Any] = Field(default_factory=dict)
+
+
+class TemplateConfigCache:
+    """Thread-safe, LRU cache for template fingerprints and parser configurations."""
+
+    def __init__(self, capacity: int = 1000) -> None:
+        self.capacity = capacity
+        self._cache: OrderedDict[str, tuple[LayoutFingerprint, ParserConfig]] = OrderedDict()
+        self._lock = Lock()
+
+    def get_exact(self, hash_digest: str) -> ParserConfig | None:
+        """Retrieves matching ParserConfig strictly by exact SHA-256 hash."""
+        with self._lock:
+            if hash_digest in self._cache:
+                self._cache.move_to_end(hash_digest)
+                _, config = self._cache[hash_digest]
+                return config.model_copy(deep=True)
+            return None
+
+    def get(
+        self, fingerprint: LayoutFingerprint, similarity_threshold: float = 0.85
+    ) -> tuple[str, ParserConfig] | None:
+        """Retrieves matching ParserConfig either by exact hash or best fuzzy match >= similarity_threshold."""
+        with self._lock:
+            # 1. Exact match
+            if fingerprint.hash_digest in self._cache:
+                self._cache.move_to_end(fingerprint.hash_digest)
+                _, config = self._cache[fingerprint.hash_digest]
+                return fingerprint.hash_digest, config.model_copy(deep=True)
+
+            # 2. Fuzzy similarity search
+            best_match_key: str | None = None
+            best_score = 0.0
+            best_config: ParserConfig | None = None
+
+            for key, (cached_fp, cached_cfg) in self._cache.items():
+                sim = fingerprint_similarity(fingerprint, cached_fp)
+                if sim > best_score:
+                    best_score = sim
+                    best_match_key = key
+                    best_config = cached_cfg
+
+            if (
+                best_match_key is not None
+                and best_score >= similarity_threshold
+                and best_config is not None
+            ):
+                self._cache.move_to_end(best_match_key)
+                return best_match_key, best_config.model_copy(deep=True)
+
+            return None
+
+    def set(self, fingerprint: LayoutFingerprint, config: ParserConfig) -> None:
+        """Saves or updates a template fingerprint and its tuned configuration."""
+        with self._lock:
+            if fingerprint.hash_digest in self._cache:
+                self._cache.move_to_end(fingerprint.hash_digest)
+            self._cache[fingerprint.hash_digest] = (
+                fingerprint,
+                config.model_copy(deep=True),
+            )
+            if len(self._cache) > self.capacity:
+                self._cache.popitem(last=False)
+
+    def save(self, file_path: str | Path) -> None:
+        """Serializes cached template configurations to a JSON file."""
+        path = Path(file_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with self._lock:
+            data = {}
+            for digest, (fp, cfg) in self._cache.items():
+                data[digest] = {
+                    "fingerprint": fp.model_dump(),
+                    "config": cfg.model_dump(),
+                }
+            with path.open("w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+
+    def load(self, file_path: str | Path) -> None:
+        """Loads template configurations from a JSON file."""
+        path = Path(file_path)
+        if not path.is_file():
+            return
+
+        with path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        with self._lock:
+            self._cache.clear()
+            for digest, payload in data.items():
+                fp = LayoutFingerprint.model_validate(payload["fingerprint"])
+                cfg = ParserConfig.model_validate(payload["config"])
+                self._cache[digest] = (fp, cfg)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._cache.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._cache)

universal_parser/adaptive/fingerprint.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from universal_parser.core.schema import Document
+
+
+class LayoutFingerprint(BaseModel):
+    """Structural layout fingerprint of a document or page template."""
+
+    hash_digest: str
+    spatial_grid: list[list[float]] = Field(default_factory=list)
+    type_distribution: dict[str, float] = Field(default_factory=dict)
+    page_count: int = 1
+    avg_elements_per_page: float = 0.0
+
+
+def compute_fingerprint(doc: Document, grid_size: int = 10) -> LayoutFingerprint:
+    """Computes a content-agnostic structural layout fingerprint from a Document.
+    Quantizes spatial bounding boxes into an N x N normalized occupancy matrix
+    and aggregates element type proportions.
+    """
+    grid = [[0.0 for _ in range(grid_size)] for _ in range(grid_size)]
+    type_counts: dict[str, int] = {}
+    total_elements = len(doc.content_tree)
+
+    page_count = doc.metadata.page_count or 1
+    if page_count <= 0:
+        page_count = 1
+
+    # Standard document dimension reference (Letter / A4 approx: 612 x 792 pt)
+    ref_w = 612.0
+    ref_h = 792.0
+
+    for idx, elem in enumerate(doc.content_tree):
+        t = elem.type
+        type_counts[t] = type_counts.get(t, 0) + 1
+
+        if elem.bbox is not None:
+            # Normalize coordinates to [0.0, 1.0]
+            norm_x0 = max(0.0, min(1.0, elem.bbox.x0 / ref_w))
+            norm_y0 = max(0.0, min(1.0, elem.bbox.y0 / ref_h))
+            norm_x1 = max(0.0, min(1.0, elem.bbox.x1 / ref_w))
+            norm_y1 = max(0.0, min(1.0, elem.bbox.y1 / ref_h))
+
+            # Discretize into grid buckets
+            gx0 = min(grid_size - 1, int(norm_x0 * grid_size))
+            gy0 = min(grid_size - 1, int(norm_y0 * grid_size))
+            gx1 = min(grid_size - 1, int(norm_x1 * grid_size))
+            gy1 = min(grid_size - 1, int(norm_y1 * grid_size))
+
+            for r in range(gy0, gy1 + 1):
+                for c in range(gx0, gx1 + 1):
+                    grid[r][c] += 1.0
+
+        else:
+            # Fallback for bbox-less elements: sequential normalized bucket
+            pos_ratio = idx / max(1, total_elements)
+            r = min(grid_size - 1, int(pos_ratio * grid_size))
+            c = 0
+            grid[r][c] += 1.0
+
+    # Normalize grid density to sum to 1.0 (if non-empty)
+    grid_sum = sum(sum(row) for row in grid)
+    if grid_sum > 0:
+        grid = [[round(val / grid_sum, 4) for val in row] for row in grid]
+
+    # Normalize type distribution
+    type_dist = (
+        {k: round(v / total_elements, 4) for k, v in sorted(type_counts.items())}
+        if total_elements > 0
+        else {}
+    )
+
+    avg_elements = round(total_elements / page_count, 2)
+
+    # Compute deterministic SHA-256 hash digest
+    payload: dict[str, Any] = {
+        "grid": grid,
+        "types": type_dist,
+        "page_count": page_count,
+    }
+    raw_bytes = json.dumps(payload, sort_keys=True).encode("utf-8")
+    hash_digest = hashlib.sha256(raw_bytes).hexdigest()
+
+    return LayoutFingerprint(
+        hash_digest=hash_digest,
+        spatial_grid=grid,
+        type_distribution=type_dist,
+        page_count=page_count,
+        avg_elements_per_page=avg_elements,
+    )
+
+
+def _vector_cosine(v1: list[float], v2: list[float]) -> float:
+    """Computes cosine similarity between two flat float vectors."""
+    dot = sum(a * b for a, b in zip(v1, v2))
+    norm1 = math.sqrt(sum(a * a for a in v1))
+    norm2 = math.sqrt(sum(b * b for b in v2))
+    if norm1 == 0.0 or norm2 == 0.0:
+        return 1.0 if norm1 == norm2 else 0.0
+    return max(0.0, min(1.0, dot / (norm1 * norm2)))
+
+
+def fingerprint_similarity(fp1: LayoutFingerprint, fp2: LayoutFingerprint) -> float:
+    """Calculates a normalized similarity score in [0.0, 1.0] between two fingerprints.
+    Combines spatial layout alignment (70% weight) and element type distribution (30% weight).
+    """
+    if fp1.hash_digest == fp2.hash_digest:
+        return 1.0
+
+    # 1. Flatten spatial grid
+    flat_grid1 = [val for row in fp1.spatial_grid for val in row]
+    flat_grid2 = [val for row in fp2.spatial_grid for val in row]
+    spatial_sim = _vector_cosine(flat_grid1, flat_grid2)
+
+    # 2. Type distribution similarity
+    all_keys = sorted(set(fp1.type_distribution.keys()) | set(fp2.type_distribution.keys()))
+    if not all_keys:
+        type_sim = 1.0
+    else:
+        v1 = [fp1.type_distribution.get(k, 0.0) for k in all_keys]
+        v2 = [fp2.type_distribution.get(k, 0.0) for k in all_keys]
+        type_sim = _vector_cosine(v1, v2)
+
+    # 3. Weighted total score
+    score = 0.7 * spatial_sim + 0.3 * type_sim
+    return round(max(0.0, min(1.0, score)), 4)

universal_parser/adaptive/tuner.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from universal_parser.adaptive.config_cache import ParserConfig
+
+SignalType = Literal[
+    "missed_heading",
+    "false_heading",
+    "missed_table",
+    "false_table",
+    "merged_columns",
+    "split_columns",
+    "ocr_quality",
+]
+
+
+class FeedbackSignal(BaseModel):
+    """User-flagged or auto-detected parsing error signal."""
+
+    signal_type: SignalType
+    severity: float = 1.0  # Learning step multiplier (0.1 - 2.0)
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+# Hard mathematical boundaries to prevent degenerate parameter drift
+GUARD_RAILS: dict[str, tuple[float, float]] = {
+    "column_gap_threshold": (10.0, 120.0),
+    "heading_p95_ratio": (1.05, 3.00),
+    "heading_p85_ratio": (1.01, 2.50),
+    "min_table_confidence": (0.30, 0.95),
+    "ocr_dpi": (100.0, 300.0),
+}
+
+
+class AdaptiveTuner:
+    """Heuristic optimizer that adjusts ParserConfig parameters based on feedback signals."""
+
+    @staticmethod
+    def _clamp(param_name: str, value: float) -> float:
+        if param_name in GUARD_RAILS:
+            min_val, max_val = GUARD_RAILS[param_name]
+            return max(min_val, min(max_val, value))
+        return value
+
+    def tune(
+        self,
+        current_config: ParserConfig,
+        signals: list[FeedbackSignal],
+        base_step: float = 0.05,
+    ) -> ParserConfig:
+        """Calculates parameter adjustments from feedback signals while strictly respecting guardrails."""
+        cfg = current_config.model_copy(deep=True)
+
+        for sig in signals:
+            step = base_step * max(0.1, min(2.0, sig.severity))
+
+            if sig.signal_type == "missed_heading":
+                # Lower heading thresholds to make heading detection more sensitive
+                cfg.heading_p95_ratio -= step * 0.5
+                cfg.heading_p85_ratio -= step * 0.4
+            elif sig.signal_type == "false_heading":
+                # Raise heading thresholds to require larger font difference
+                cfg.heading_p95_ratio += step * 0.5
+                cfg.heading_p85_ratio += step * 0.4
+            elif sig.signal_type == "missed_table":
+                # Lower table confidence requirement or switch to stream mode
+                cfg.min_table_confidence -= step * 0.5
+                if cfg.min_table_confidence < 0.5:
+                    cfg.table_detection_mode = "stream"
+            elif sig.signal_type == "false_table":
+                # Increase table confidence threshold
+                cfg.min_table_confidence += step * 0.5
+            elif sig.signal_type == "merged_columns":
+                # Columns were incorrectly merged -> reduce gap threshold to split columns more aggressively
+                cfg.column_gap_threshold -= step * 20.0
+            elif sig.signal_type == "split_columns":
+                # Single column was falsely split into multi-column -> increase gap threshold
+                cfg.column_gap_threshold += step * 20.0
+            elif sig.signal_type == "ocr_quality":
+                # Higher resolution for OCR rasterization
+                cfg.ocr_dpi = int(min(300, cfg.ocr_dpi + 50))
+
+        # Apply guardrail clamping and rounding
+        cfg.column_gap_threshold = round(
+            self._clamp("column_gap_threshold", cfg.column_gap_threshold), 2
+        )
+        cfg.heading_p95_ratio = round(self._clamp("heading_p95_ratio", cfg.heading_p95_ratio), 3)
+        cfg.heading_p85_ratio = round(self._clamp("heading_p85_ratio", cfg.heading_p85_ratio), 3)
+        cfg.min_table_confidence = round(
+            self._clamp("min_table_confidence", cfg.min_table_confidence), 3
+        )
+        cfg.ocr_dpi = int(self._clamp("ocr_dpi", float(cfg.ocr_dpi)))
+
+        return cfg

universal_parser/core/engine.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from universal_parser.core.router import get_extractor
+from universal_parser.core.schema import Document, DocumentMetadata
+from universal_parser.core.sniffer import sniff
+
+
+def parse(path: str | Path) -> Document:
+    """
+    Parse any supported document into a Document object.
+    This is the only function external code needs to call.
+    Internally it:
+        1. Sniffs the file type via magic bytes
+        2. Looks up the registered extractor for that type
+        3. Streams Elements from the extractor into content_tree
+        4. Returns a validated Document
+    Args:
+        path: path to the document to parse
+    Returns:
+        Document — fully validated Pydantic model
+    Raises:
+        FileNotFoundError: if the file does not exist
+        ValueError: if the file type is unsupported (no extractor registered)
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+
+    # Step 1 — What is this file?
+    file_type = sniff(path)
+
+    # Step 2 — Do we have an extractor for it?
+    extractor = get_extractor(file_type)
+    if extractor is None:
+        raise ValueError(
+            f"Unsupported file type: {file_type.name} ({path.suffix}). "
+            f"No extractor registered for this format yet."
+        )
+
+    # Step 3 — Build the document shell
+    doc = Document(
+        metadata=DocumentMetadata(
+            file_name=path.name,
+            file_type=file_type.name.lower(),
+        )
+    )
+
+    # Step 4 — Stream elements from the extractor into content_tree
+    for element in extractor.stream(path):
+        doc.content_tree.append(element)
+
+    return doc

universal_parser/core/router.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from universal_parser.core.sniffer import FileType
+from universal_parser.extractors.base import BaseExtractor
+
+# Central registry: FileType -> Extractor class
+# Extractors are added here as they are built, phase by phase.
+# engine.py reads this — it never imports an extractor directly.
+
+FORMAT_REGISTRY: dict[FileType, type[BaseExtractor]] = {}
+
+
+def register(extractor_cls: type[BaseExtractor]) -> type[BaseExtractor]:
+    """
+    Decorator to register an extractor class into FORMAT_REGISTRY.
+    Usage — put this on any extractor class:
+        @register
+        class PDFExtractor(BaseExtractor):
+            supported_types = [FileType.PDF]
+            ...
+    This automatically maps FileType.PDF -> PDFExtractor in the registry.
+    No manual entry needed in this file when adding a new format.
+    """
+    for file_type in extractor_cls.supported_types:
+        FORMAT_REGISTRY[file_type] = extractor_cls
+    return extractor_cls
+
+
+def get_extractor(file_type: FileType) -> BaseExtractor | None:
+    """
+    Look up and return an instantiated extractor for the given FileType.
+    Returns None if no extractor is registered for this type.
+    engine.py handles the None case — it never crashes here.
+    """
+    extractor_cls = FORMAT_REGISTRY.get(file_type)
+    if extractor_cls is None:
+        return None
+    return extractor_cls()

universal_parser/core/schema.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import uuid
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class BBox(BaseModel):
+    """Bounding box of an element on a page. Coordinates in points (PDF units)."""
+
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+
+
+class TableData(BaseModel):
+    """Structured representation of a table."""
+
+    headers: list[str]
+    rows: list[list[str]]
+
+
+class Element(BaseModel):
+    """A single unit of content extracted from a document."""
+
+    element_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    type: Literal["heading", "paragraph", "table", "figure", "list_item", "code_block"]
+    level: int | None = None  # heading level: 1, 2, 3 etc. None for non-headings
+    text: str | None = None
+    page: int | None = None  # 1-indexed page number
+    bbox: BBox | None = None
+    parent_id: str | None = (
+        None  # links to a parent element (e.g. heading this paragraph belongs to)
+    )
+    data: TableData | None = None  # only for type="table"
+    markdown_repr: str | None = None  # pre-rendered markdown string of this element
+    confidence: float | None = None  # 0.0 to 1.0, used for tables and OCR output
+    vlm_description: str | None = None  # Phase 8 — optional VLM-generated caption for figures
+
+
+class DocumentMetadata(BaseModel):
+    """Facts about the source file — not its content."""
+
+    file_name: str
+    file_type: str
+    page_count: int | None = None
+    has_scanned_pages: bool = False
+
+
+class Document(BaseModel):
+    """The top-level output object. This is what parse() returns."""
+
+    schema_version: str = "1.0"
+    doc_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    metadata: DocumentMetadata
+    content_tree: list[Element] = Field(default_factory=list)