universal-doc-parser 1.0.1__tar.gz → 1.0.2__tar.gz

{universal_doc_parser-1.0.1 → universal_doc_parser-1.0.2}/PKG-INFO

@@ -1,7 +1,12 @@
 Metadata-Version: 2.5
 Name: universal-doc-parser
-Version: 1.0.1
+Version: 1.0.2
 Summary: A zero-GPU, CPU-only document ingestion engine for RAG pipelines and AI agents.
+Project-URL: Homepage, https://github.com/Edge-Explorer/Parse-Anything-
+Project-URL: Live Demo, https://huggingface.co/spaces/Karan6124/universal-doc-parser
+Project-URL: Repository, https://github.com/Edge-Explorer/Parse-Anything-
+Project-URL: Documentation, https://github.com/Edge-Explorer/Parse-Anything-#readme
+Project-URL: Issues, https://github.com/Edge-Explorer/Parse-Anything-/issues
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
@@ -49,13 +54,16 @@ Description-Content-Type: text/markdown
 # UNIVERSAL PARSER
 
 [![CI](https://github.com/Edge-Explorer/Parse-Anything-/actions/workflows/ci.yml/badge.svg)](https://github.com/Edge-Explorer/Parse-Anything-/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/badge/PyPI-v1.0.1-blue.svg)](https://pypi.org/project/universal-doc-parser/)
+[![PyPI](https://img.shields.io/badge/PyPI-v1.0.2-blue.svg)](https://pypi.org/project/universal-doc-parser/)
+[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Live%20Demo-yellow.svg)](https://huggingface.co/spaces/Karan6124/universal-doc-parser)
 [![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12-blue.svg)](https://pypi.org/project/universal-doc-parser/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Memory: <250MB](https://img.shields.io/badge/Memory_Limit-%3C250MB_RSS-success.svg)](#memory-and-performance)
 
 A CPU-only document ingestion engine for RAG pipelines and AI agents. Parses 15+ file formats into a unified Pydantic schema with hierarchical chunking, adaptive layout fingerprinting, and a FastMCP server interface.
 
+**[Try the Live Interactive Demo on Hugging Face Spaces](https://huggingface.co/spaces/Karan6124/universal-doc-parser)**
+
 No GPU. No paid API. No recurring cost.
 
 ---

{universal_doc_parser-1.0.1 → universal_doc_parser-1.0.2}/README.md

@@ -5,13 +5,16 @@
 # UNIVERSAL PARSER
 
 [![CI](https://github.com/Edge-Explorer/Parse-Anything-/actions/workflows/ci.yml/badge.svg)](https://github.com/Edge-Explorer/Parse-Anything-/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/badge/PyPI-v1.0.1-blue.svg)](https://pypi.org/project/universal-doc-parser/)
+[![PyPI](https://img.shields.io/badge/PyPI-v1.0.2-blue.svg)](https://pypi.org/project/universal-doc-parser/)
+[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Live%20Demo-yellow.svg)](https://huggingface.co/spaces/Karan6124/universal-doc-parser)
 [![Python](https://img.shields.io/badge/Python-3.11%20%7C%203.12-blue.svg)](https://pypi.org/project/universal-doc-parser/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Memory: <250MB](https://img.shields.io/badge/Memory_Limit-%3C250MB_RSS-success.svg)](#memory-and-performance)
 
 A CPU-only document ingestion engine for RAG pipelines and AI agents. Parses 15+ file formats into a unified Pydantic schema with hierarchical chunking, adaptive layout fingerprinting, and a FastMCP server interface.
 
+**[Try the Live Interactive Demo on Hugging Face Spaces](https://huggingface.co/spaces/Karan6124/universal-doc-parser)**
+
 No GPU. No paid API. No recurring cost.
 
 ---

universal_doc_parser-1.0.2/docs/ADDING_A_FORMAT.md

@@ -0,0 +1,212 @@
+# Adding a New Document Format
+
+This guide walks contributors and integrators through the complete process of adding support for a new document format to `universal-doc-parser`.
+
+The architecture uses a decoupled Registry and Strategy pattern: adding a new format requires implementing a single extractor class and registering it with a decorator. The core engine, validation layer, and export pipelines require zero modifications.
+
+---
+
+## Prerequisites and Design Constraints
+
+Before implementing a new extractor:
+
+1. **Permissive Licensing Only:** Any third-party library introduced must be licensed under MIT, Apache-2.0, or BSD. AGPL-licensed dependencies are strictly prohibited.
+2. **Streaming Execution:** Extractors must yield `Element` objects incrementally via Python generators (`yield`). Do not buffer entire multi-gigabyte files in RAM.
+3. **Graceful Failure:** Extractors must never leak raw third-party library exceptions. Catch library-specific errors and raise standard `ValueError` with descriptive diagnostic messages.
+4. **No GPU Requirement:** All parsing logic must execute on CPU within the bounded memory envelope (<250 MB RSS).
+
+---
+
+## Step-by-Step Implementation Guide
+
+### Step 1: Declare the Format in the Sniffer
+
+Open `universal_parser/core/sniffer.py`:
+
+1. Add your format to the `FileType` enum:
+   ```python
+   class FileType(Enum):
+       # ... existing types ...
+       MARKDOWN = auto()  # Example: adding Markdown support
+   ```
+
+2. Add extension mappings to `_EXT_MAP`:
+   ```python
+   _EXT_MAP: dict[str, FileType] = {
+       # ...
+       ".md": FileType.MARKDOWN,
+       ".markdown": FileType.MARKDOWN,
+   }
+   ```
+
+3. If the format has standard MIME types, add them to `_MIME_MAP`:
+   ```python
+   _MIME_MAP: dict[str, FileType] = {
+       # ...
+       "text/markdown": FileType.MARKDOWN,
+       "text/x-markdown": FileType.MARKDOWN,
+   }
+   ```
+
+---
+
+### Step 2: Implement the Extractor Class
+
+Create a new module in the appropriate category subdirectory under `universal_parser/extractors/`:
+
+- `universal_parser/extractors/pdf/`
+- `universal_parser/extractors/office/`
+- `universal_parser/extractors/images/`
+- `universal_parser/extractors/structured/`
+- `universal_parser/extractors/web/`
+- `universal_parser/extractors/mail/`
+
+Create `universal_parser/extractors/structured/markdown_extractor.py`:
+
+```python
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+from typing import ClassVar
+
+from universal_parser.core.router import register
+from universal_parser.core.schema import BBox, Element
+from universal_parser.core.sniffer import FileType
+from universal_parser.extractors.base import BaseExtractor
+
+
+@register
+class MarkdownExtractor(BaseExtractor):
+    """Extracts structured headings, paragraphs, and code blocks from Markdown files."""
+
+    supported_types: ClassVar[list[FileType]] = [FileType.MARKDOWN]
+
+    def stream(self, path: str | Path) -> Iterator[Element]:
+        """Stream elements from a Markdown file line-by-line."""
+        path = Path(path)
+        if not path.is_file():
+            raise FileNotFoundError(f"File not found: {path}")
+
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                for line_idx, raw_line in enumerate(f, start=1):
+                    line = raw_line.strip()
+                    if not line:
+                        continue
+
+                    # Heading detection
+                    if line.startswith("#"):
+                        level = min(6, len(line) - len(line.lstrip("#")))
+                        text = line.lstrip("#").strip()
+                        yield Element(
+                            type="heading",
+                            level=level,
+                            text=text,
+                            page=1,
+                        )
+                    else:
+                        yield Element(
+                            type="paragraph",
+                            text=line,
+                            page=1,
+                        )
+        except Exception as err:
+            raise ValueError(f"Failed to parse Markdown file {path.name}: {err}") from err
+```
+
+---
+
+### Step 3: Register the Extractor in Package Initialization
+
+Open `universal_parser/__init__.py` and add the import to ensure the `@register` decorator executes when the package loads:
+
+```python
+import universal_parser.extractors.structured.markdown_extractor  # noqa: F401
+```
+
+---
+
+### Step 4: Add Test Fixtures
+
+Every format requires at least three real test fixture files in `tests/fixtures/<format>/`:
+
+1. `sample.<ext>`: Standard clean document with common features (headings, text, lists).
+2. `complex.<ext>`: Complex document with nested sections, large tables, or mixed encoding.
+3. `malformed.<ext>`: Deliberately broken or empty file to verify graceful error handling.
+
+Create the directory:
+```bash
+tests/fixtures/markdown/
+├── sample.md
+├── complex.md
+└── malformed.md
+```
+
+---
+
+### Step 5: Write Unit and Integration Tests
+
+Create `tests/test_markdown.py`:
+
+```python
+from pathlib import Path
+import pytest
+from universal_parser import parse, to_chunks, to_markdown
+from universal_parser.core.sniffer import FileType, sniff
+
+FIXTURES = Path(__file__).parent / "fixtures" / "markdown"
+
+
+def test_markdown_sniffing():
+    assert sniff(FIXTURES / "sample.md") == FileType.MARKDOWN
+
+
+def test_markdown_parsing():
+    doc = parse(FIXTURES / "sample.md")
+    assert doc.metadata.file_type == "markdown"
+    assert len(doc.content_tree) > 0
+
+    headings = [el for el in doc.content_tree if el.type == "heading"]
+    assert len(headings) >= 1
+    assert headings[0].level == 1
+
+
+def test_markdown_chunking():
+    doc = parse(FIXTURES / "sample.md")
+    chunks = to_chunks(doc, max_tokens=256)
+    assert len(chunks) > 0
+    assert all(c.text for c in chunks)
+
+
+def test_malformed_markdown_handling():
+    # Verify the parser handles empty or corrupt files without crashing
+    doc = parse(FIXTURES / "malformed.md")
+    assert doc is not None
+```
+
+---
+
+### Step 6: Verify Code Quality Gates
+
+Run the local quality checks:
+
+```bash
+# 1. Lint and format checks
+uv run ruff check .
+uv run ruff format .
+
+# 2. Run full test suite
+uv run pytest tests/test_markdown.py -v
+uv run pytest -v
+
+# 3. Check memory limits
+uv run python benchmarks/memory_profile.py
+```
+
+---
+
+### Step 7: Update Documentation and Changelog
+
+1. Add your format row to the Supported Formats table in `README.md`.
+2. Document the new format under the `[Unreleased]` or current release section in `docs/CHANGELOG.md`.

universal_doc_parser-1.0.2/docs/ARCHITECTURE.md

@@ -0,0 +1,164 @@
+# Architecture and System Design
+
+This document provides a comprehensive technical overview of `universal-doc-parser`. It details the internal data structures, algorithms, subsystem boundaries, and design rationales governing the document ingestion engine.
+
+---
+
+## 1. High-Level System Architecture
+
+The parser follows a multi-stage, generator-driven pipeline designed for deterministic memory consumption (<250 MB RSS) and zero cloud API dependency.
+
+```
++-----------------------------------------------------------------------------------+
+|                                  Input Document                                   |
++-----------------------------------------------------------------------------------+
+                                          |
+                                          v
++-----------------------------------------------------------------------------------+
+|                        Stage 1: Sniffer (MIME & Byte Detection)                   |
+|  - Magic byte inspection via python-magic (optional OS fallback)                  |
+|  - Extension-based disambiguation and normalization                               |
++-----------------------------------------------------------------------------------+
+                                          |
+                                          v
++-----------------------------------------------------------------------------------+
+|                        Stage 2: Router & Extractor Registry                       |
+|  - Maps FileType enum to registered BaseExtractor subclass                        |
+|  - Dynamic registry populated via @register decorators                            |
++-----------------------------------------------------------------------------------+
+                                          |
+                                          v
++-----------------------------------------------------------------------------------+
+|                    Stage 3: Streaming Extractor Execution                         |
+|  - Yields Element generator stream page-by-page / record-by-record                |
+|  - PDF: 2-Pass Table Extraction -> Font Percentile Headings -> Column Order       |
+|  - Office / Compound: Recursive embedded asset unpacker                           |
+|  - Scanned / Image: RapidOCR ONNX CPU inference with deskewing                    |
++-----------------------------------------------------------------------------------+
+                                          |
+                                          v
++-----------------------------------------------------------------------------------+
+|                     Stage 4: Normalizer & Tree Assembler                          |
+|  - UUID v4 assignment for document and elements                                   |
+|  - Heading ancestry stack: links child paragraphs/tables to nearest parent_id     |
+|  - Pydantic v2 strict schema validation                                           |
++-----------------------------------------------------------------------------------+
+                                          |
+                                          v
++-----------------------------------------------------------------------------------+
+|                        Stage 5: Downstream Export Layer                           |
+|  - to_markdown(): Pre-rendered GFM Markdown                                       |
+|  - to_chunks(): Hierarchical token-budgeted chunks with breadcrumb ancestry       |
+|  - to_graph(): Knowledge graph nodes and edges for GraphRAG                       |
+|  - FastMCP Server: Stdio tool interface for AI agents                             |
++-----------------------------------------------------------------------------------+
+```
+
+---
+
+## 2. Core Ingestion Pipeline
+
+### 2.1 Sniffer (`universal_parser/core/sniffer.py`)
+File identification relies on a multi-tier sniffing strategy:
+1. **Magic Bytes:** Reads the initial 2048 bytes of the file stream using `python-magic` to inspect file signatures (e.g., `%PDF-`, `PK\x03\x04`, `\xD0\xCF\x11\xE0`).
+2. **Ambiguity Resolution:** For plain text containers (where MIME is `text/plain` or `text/csv`), the file extension is evaluated against `_EXT_MAP` to disambiguate CSV, TSV, JSON, and XML.
+3. **Graceful Fallback:** If `python-magic` or `libmagic` is unavailable at the OS level, sniffing safely defaults to extension mapping without raising exceptions. Unrecognized formats return `FileType.UNKNOWN`.
+
+### 2.2 Router (`universal_parser/core/router.py`)
+The router maintains an in-memory mapping of `FileType -> type[BaseExtractor]`. Extractors register themselves using the `@register` decorator upon module import. This decouples individual parser implementations from the core dispatch loop.
+
+### 2.3 Streaming Generator Pipeline (`universal_parser/core/engine.py`)
+Every extractor implements `BaseExtractor.stream(path: Path) -> Iterator[Element]`. Memory consumption remains bounded because elements are yielded lazily as individual pages or records are processed, rather than assembling the entire document in memory.
+
+---
+
+## 3. PDF Extraction Subsystem
+
+PDF documents represent the highest layout complexity. The PDF engine in `universal_parser/extractors/pdf/` uses a cooperative multi-pass strategy:
+
+```
+PDF Page Stream
+       |
+       +---> Pass 1: Table Extraction (PDFTableExtractor)
+       |       |-- Lattice Strategy: Explicit horizontal/vertical vector lines
+       |       |-- Stream Strategy: Whitespace column clustering with density guardrails
+       |       +-> Computes Table Bounding Boxes
+       |
+       +---> Pass 2: Native Text Extraction (pypdfium2 / pdfplumber)
+       |       |-- Filters out words falling inside Table Bounding Boxes
+       |       |-- Computes font size percentiles (H1: >=95th, H2: >=85th, H3: >=75th)
+       |       |-- Column Band Clustering: partitions into Left, Right, Full-Width bands
+       |       +-> Orders elements in natural reading sequence
+       |
+       +---> Scanned Fallback (if 0 text characters found)
+               +-> RapidOCR ONNX inference on CPU at 200 DPI with deskew preprocessing
+```
+
+### 3.1 Two-Pass Table Extraction (`tables.py`)
+1. **Lattice Strategy:** Identifies bordered tables by analyzing intersecting vector ruling lines using explicit coordinate snap and join tolerances (`snap_tolerance=3`, `join_tolerance=3`). Confidence is scored at `0.95+`.
+2. **Stream Strategy:** Identifies borderless tables using whitespace gaps and text alignment. False positives (such as multi-column paragraphs) are suppressed using two mathematical constraints:
+   - **Word Density Constraint:** Average words per non-empty cell must be $\le 2.5$. If cells contain paragraph sentences, the candidate table is rejected.
+   - **Height Ratio Constraint:** The table bounding box must not exceed 40% of the total page height ($table\_h \le 0.40 \times page\_h$).
+
+### 3.2 Font-Size Percentile Hierarchy (`native.py`)
+Rather than relying on brittle hardcoded point sizes (e.g. `size > 14`), the parser samples the font size distribution across the document and calculates empirical percentiles:
+- **H1 (Top-level Title):** $\ge 95\text{th percentile}$ (guaranteed $\ge \text{median} + 3.0\text{pt}$)
+- **H2 (Section Header):** $\ge 85\text{th percentile}$ (guaranteed $\ge \text{median} + 1.5\text{pt}$)
+- **H3 (Subsection Header):** $\ge 75\text{th percentile}$ (guaranteed $\ge \text{median} + 0.5\text{pt}$)
+- **Paragraphs / Body Text:** All remaining text below the 75th percentile.
+
+### 3.3 Multi-Column Reading Order Reconstruction (`native.py`)
+Elements are partitioned spatially relative to the page horizontal midpoint ($X_{\text{mid}} = \frac{\text{page\_width}}{2}$):
+1. **Full-Width Header Zone:** Spans with bounding box width $> 0.70 \times \text{page\_width}$ appearing near the top are yielded first.
+2. **Left Column:** Elements where $x_1 \le X_{\text{mid}} + 15\text{pt}$, sorted top-to-bottom ($y_0$).
+3. **Right Column:** Elements where $x_0 \ge X_{\text{mid}} - 15\text{pt}$, sorted top-to-bottom ($y_0$).
+4. **Full-Width Footer Zone:** Full-width elements at the bottom of the page.
+
+---
+
+## 4. Adaptive Layout Fingerprinting Subsystem (`universal_parser/adaptive/`)
+
+In recurring document workflows (invoices, tax forms, financial 10-K filings), identical templates are ingested repeatedly. The adaptive subsystem enables self-tuning parameter caching for recurring document structures.
+
+```
+Document Bounding Boxes
+          |
+          v
+[ Spatial Grid Quantization ] -> 10x10 Content-Agnostic Occupancy Matrix
+          |
+          v
+[ SHA-256 Fingerprint Hash ]  -> Hex Digest + Spatial Histogram
+          |
+          v
+[ TemplateConfigCache ]       -> Exact Match OR Fuzzy Cosine-Jaccard Lookup (Threshold >= 0.85)
+          |
+          v
+[ Auto-Tuned Extractor Config ] -> Injects optimal column/table thresholds into extractor
+```
+
+1. **Fingerprinter (`fingerprint.py`):** Normalizes all element coordinates to a reference 612x792 pt coordinate space and quantizes them into a 10x10 binary spatial occupancy grid. Combines the spatial grid with element type distribution proportions and hashes the payload with SHA-256.
+2. **Configuration Cache (`config_cache.py`):** Thread-safe LRU cache with atomic JSON disk persistence. Supports exact SHA-256 lookup and fuzzy Cosine-Jaccard similarity matching for documents with minor layout shifts.
+3. **Auto-Tuner (`tuner.py`):** Uses coordinate descent optimization against reference ground-truth data to automatically discover optimal extraction parameters (such as column split boundaries and table tolerances) without manual configuration.
+
+---
+
+## 5. Downstream RAG & Export Subsystem
+
+### 5.1 Hierarchical Chunking (`universal_parser/exports/to_chunks.py`)
+Standard token-window chunking slices text arbitrarily, splitting paragraphs and losing title context. The hierarchical chunker:
+- Accumulates elements while respecting a configurable token budget (`max_tokens`, default 512).
+- Prepends full heading ancestry to every chunk: `Context: Executive Summary > Financial Results\n\n{text}`.
+- Keeps tables intact within a single chunk whenever budget permits.
+
+### 5.2 Knowledge Graph Generator (`universal_parser/exports/to_graph.py`)
+Generates GraphRAG-compatible nodes and edges:
+- **Document Root Node:** Links metadata properties.
+- **Section Nodes:** Represents headings with hierarchical `CONTAINS_SECTION` edges.
+- **Content Nodes:** Paragraphs and tables linked to parent sections via `CONTAINS` edges and sequenced via `FOLLOWS` edges.
+
+---
+
+## 6. Observability and FastMCP Integration
+
+1. **Telemetry Collector (`universal_parser/observability/metrics.py`):** Thread-safe singleton capturing parsing latency, element distributions, scanned page occurrences, and structural anomalies per invocation. Exports standalone interactive HTML dashboards.
+2. **FastMCP Server (`universal_parser/mcp/server.py`):** Exposes `parse_document` and `list_supported_formats` tools over stdio for Claude Desktop, Cursor, and agent frameworks.

{universal_doc_parser-1.0.1 → universal_doc_parser-1.0.2}/docs/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project are documented in this file. Entries are org
 
 ---
 
+## [1.0.2]
+
+### Release Context
+
+Documentation and metadata release adding live Hugging Face Spaces integration links, project URLs, and comprehensive architecture specifications across the documentation suite.
+
+### Added
+
+- Added live Hugging Face Space interactive demo badge and links to `README.md` and `pyproject.toml` (`[project.urls]`).
+- Created complete `docs/ARCHITECTURE.md` specification detailing the two-pass extraction engine, font-size percentile hierarchy, and adaptive fingerprinting.
+- Created complete `docs/SCHEMA.md` field-level reference covering all Pydantic models, type constraints, and null semantics.
+- Created complete `docs/ADDING_A_FORMAT.md` step-by-step contributor implementation guide for extending format coverage.
+- Added UI payload safeguards and thread ceilings in `main.py` to ensure smooth browser rendering on multi-page reports.
+
+---
+
 ## [1.0.1]
 
 ### Release Context

universal_doc_parser-1.0.2/docs/SCHEMA.md

@@ -0,0 +1,183 @@
+# Output Schema Specification
+
+This document provides the canonical field-level specification for all output data models produced by `universal-doc-parser`. All models are implemented using Pydantic v2 (`universal_parser/core/schema.py`).
+
+---
+
+## 1. Top-Level Models
+
+### 1.1 `Document`
+
+The root object returned by `parse(path)`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `schema_version` | `str` | Yes | Schema specification version. Always `"1.0"` in this release. |
+| `doc_id` | `str` | Yes | Unique UUID v4 identifier generated at parse time. |
+| `metadata` | `DocumentMetadata` | Yes | Document-level metadata (filename, detected format, page count). |
+| `content_tree` | `list[Element]` | Yes | Ordered sequence of extracted document elements in natural reading order. |
+
+```json
+{
+  "schema_version": "1.0",
+  "doc_id": "c8cdb60a-fc20-4e79-bb30-37218c8dba8a",
+  "metadata": {
+    "file_name": "annual_report.pdf",
+    "file_type": "pdf",
+    "page_count": 42,
+    "has_scanned_pages": false
+  },
+  "content_tree": [ ... ]
+}
+```
+
+---
+
+### 1.2 `DocumentMetadata`
+
+Captures file container properties and parsing telemetry.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `file_name` | `str` | Yes | Original filename including file extension. |
+| `file_type` | `str` | Yes | Normalized format identifier: `pdf`, `docx`, `xlsx`, `pptx`, `html`, `epub`, `csv`, `tsv`, `parquet`, `json`, `xml`, `eml`, `msg`, `mbox`, `image`, `doc`, `xls`, `ppt`. |
+| `page_count` | `int or None` | No | Total pages in paginated documents. `null` for non-paginated formats (e.g. CSV, Parquet, JSON). |
+| `has_scanned_pages` | `bool` | Yes | `true` if any page in the document required CPU OCR fallback processing. |
+
+---
+
+## 2. Element Models
+
+### 2.1 `Element`
+
+The atomic unit of extracted content within `content_tree`.
+
+| Field | Type | Required | Null Semantics / Invariants |
+|---|---|---|---|
+| `element_id` | `str` | Yes | Unique UUID v4 assigned to this specific element. |
+| `type` | `str` | Yes | One of: `"heading"`, `"paragraph"`, `"table"`, `"figure"`, `"list_item"`, `"code_block"`. |
+| `level` | `int or None` | No | Heading hierarchy depth ($1 \le \text{level} \le 6$). `null` for all non-heading elements. |
+| `text` | `str or None` | No | Plain text content. `null` for pure table elements. |
+| `page` | `int or None` | No | 1-indexed page number where the element appears. `null` for non-paginated files. |
+| `bbox` | `BBox or None` | No | Spatial coordinates in standard PDF points (72 pt = 1 inch). `null` for non-spatial files. |
+| `parent_id` | `str or None` | No | `element_id` of the nearest ancestor heading above this element. `null` for root-level items. |
+| `data` | `TableData or None` | No | Structured grid data (`headers`, `rows`). Populated **only** when `type == "table"`. |
+| `markdown_repr` | `str or None` | No | Pre-rendered GitHub-Flavored Markdown representation of the element. |
+| `confidence` | `float or None` | No | Extraction confidence score in $[0.0, 1.0]$. Populated for OCR text and tables; `null` for digital text. |
+| `vlm_description` | `str or None` | No | Optional visual description for images/figures. Reserved for multimodal extensions. |
+
+---
+
+### 2.2 `BBox` (Bounding Box)
+
+Spatial coordinates for layout-aware document elements.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `x0` | `float` | Yes | Left horizontal coordinate in PDF points from top-left origin. |
+| `y0` | `float` | Yes | Top vertical coordinate in PDF points from top-left origin. |
+| `x1` | `float` | Yes | Right horizontal coordinate in PDF points from top-left origin. |
+| `y1` | `float` | Yes | Bottom vertical coordinate in PDF points from top-left origin. |
+
+---
+
+### 2.3 `TableData`
+
+Structured tabular representation.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `headers` | `list[str]` | Yes | Ordered list of table column header strings. |
+| `rows` | `list[list[str]]` | Yes | 2D list of row cell values normalized to string representations. |
+
+```json
+{
+  "headers": ["Quarter", "Revenue (USD)", "Operating Margin"],
+  "rows": [
+    ["Q1", "$1.2B", "24.5%"],
+    ["Q2", "$1.4B", "26.1%"]
+  ]
+}
+```
+
+---
+
+## 3. Element Type Examples
+
+### 3.1 Heading Element (H1)
+```json
+{
+  "element_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+  "type": "heading",
+  "level": 1,
+  "text": "1. Executive Summary",
+  "page": 1,
+  "bbox": { "x0": 72.0, "y0": 100.0, "x1": 540.0, "y1": 124.0 },
+  "parent_id": null,
+  "data": null,
+  "markdown_repr": "# 1. Executive Summary",
+  "confidence": null,
+  "vlm_description": null
+}
+```
+
+### 3.2 Paragraph Element (Child of H1)
+```json
+{
+  "element_id": "f2e3d4c5-b6a7-4890-1234-567890abcdef",
+  "type": "paragraph",
+  "level": null,
+  "text": "Operating cash flow reached record highs across all European business units.",
+  "page": 1,
+  "bbox": { "x0": 72.0, "y0": 135.0, "x1": 540.0, "y1": 160.0 },
+  "parent_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+  "data": null,
+  "markdown_repr": "Operating cash flow reached record highs across all European business units.",
+  "confidence": null,
+  "vlm_description": null
+}
+```
+
+### 3.3 Table Element
+```json
+{
+  "element_id": "99887766-5544-3322-1100-aabbccddeeff",
+  "type": "table",
+  "level": null,
+  "text": null,
+  "page": 2,
+  "bbox": { "x0": 72.0, "y0": 200.0, "x1": 540.0, "y1": 350.0 },
+  "parent_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+  "data": {
+    "headers": ["Region", "YoY Growth"],
+    "rows": [["APAC", "+18%"], ["EMEA", "+12%"]]
+  },
+  "markdown_repr": "| Region | YoY Growth |\n|---|---|\n| APAC | +18% |\n| EMEA | +12% |",
+  "confidence": 0.98,
+  "vlm_description": null
+}
+```
+
+---
+
+## 4. Export Models
+
+### 4.1 `Chunk` (Produced by `to_chunks()`)
+
+| Field | Type | Description |
+|---|---|---|
+| `chunk_id` | `str` | Unique chunk identifier formatted as `{doc_id}-chunk-{index}`. |
+| `text` | `str` | Full chunk text prepended with heading ancestry breadcrumbs: `Context: H1 > H2\n\n{text}`. |
+| `headings` | `list[str]` | Ordered list of ancestor heading titles from root to nearest section. |
+| `element_types` | `list[str]` | Deduplicated list of element types contained within this chunk. |
+| `page_numbers` | `list[int]` | Sorted list of page numbers spanned by the chunk. |
+| `estimated_tokens` | `int` | Approximate token count (estimated at ~4 characters per token). |
+
+---
+
+### 4.2 `KnowledgeGraph` (Produced by `to_graph()`)
+
+| Field | Type | Description |
+|---|---|---|
+| `nodes` | `list[GraphNode]` | Graph vertices representing the document root, sections, and content elements. |
+| `edges` | `list[GraphEdge]` | Directed relationship edges: `CONTAINS_SECTION`, `CONTAINS`, `FOLLOWS`. |