docslicer 0.2.0__tar.gz → 0.2.1__tar.gz

{docslicer-0.2.0/src/docslicer.egg-info → docslicer-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docslicer
-Version: 0.2.0
+Version: 0.2.1
 Summary: Deterministic hierarchical document parser and chunker
 Author-email: "Market Framer Inc." <jelle@docslicer.ai>
 License-Expression: AGPL-3.0-only
@@ -50,6 +50,9 @@ Provides-Extra: crypto
 Requires-Dist: msoffcrypto-tool>=5.0; extra == "crypto"
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=18.0; extra == "parquet"
+Provides-Extra: mcp
+Requires-Dist: mcp>=2.0; extra == "mcp"
+Requires-Dist: tiktoken>=0.10; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
@@ -57,11 +60,17 @@ Dynamic: license-file
 
 # DocSlicer
 
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Commercial license available](https://img.shields.io/badge/License-Commercial-green.svg)](LICENSE-COMMERCIAL.md)
+[![PyPI](https://img.shields.io/pypi/v/docslicer.svg)](https://pypi.org/project/docslicer/) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Commercial license available](https://img.shields.io/badge/License-Commercial-green.svg)](LICENSE-COMMERCIAL.md)
 
-Lightning-fast, deterministic hierarchical document parser and chunker for business documents. No LLM calls or heavy ML models.
+Lightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.
 
-DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, and a navigable heading hierarchy — preserving the document's own structure instead of guessing at it.
+DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, markdown and a navigable heading hierarchy.
+
+Top score on [BizDocBench](https://github.com/DocSlicer/BizDocBench) (0.88 overall vs 0.70 for the next-best tool). 0.80 table accuracy, 0.98 content faithfulness, 0.85 heading recognition and hierarchy preservation, and 0.76 RAG retrieval performance.
+
+**Add DocSlicer to your AI pipeline:**
+- Classic RAG: the layout-aware chunker gives you clean non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed.
+- Vectorless RAG: for when you want an answer out of a document right now. The agent pulls the outline, picks the section it needs, and navigates to the correct section of text without embedding the whole document
 
 ```python
 import docslicer
@@ -117,6 +126,23 @@ if __name__ == "__main__":
 
 ---
 
+## Benchmarks
+
+Measured with [BizDocBench](https://github.com/DocSlicer/BizDocBench) — an open benchmark for multi-format business document parsing. All scores are 0–1 (higher is better); `pages_per_sec_aggregate` is throughput across the full corpus.
+
+| Tool | Score | Coverage | Speed | Hierarchy | Faithfulness | Tables | Retrieval | Pages/sec |
+|---|---|---|---|---|---|---|---|---|
+| **docslicer** | **0.8796** | 1.0000 | 0.8836 | 0.8466 | 0.9824 | 0.8047 | 0.7601 | 31.27 |
+| docling | 0.7036 | 1.0000 | 0.3805 | 0.4905 | 0.8927 | 0.7467 | 0.7111 | 3.46 |
+| markitdown | 0.5838 | 1.0000 | 0.8513 | 0.0604 | 0.7972 | 0.2584 | 0.5357 | 27.42 |
+| unstructured | 0.5798 | 0.9091 | 0.1073 | 0.4327 | 0.9057 | 0.4812 | 0.6430 | 0.52 |
+| opendataloader | 0.5359 | 0.5844 | 1.0000 | 0.3853 | 0.6484 | 0.2655 | 0.3317 | 117.26 |
+| pymupdf4llm | 0.4519 | 0.5974 | 0.6492 | 0.1089 | 0.6456 | 0.3551 | 0.3552 | 11.84 |
+| mineru | 0.4107 | 0.5974 | 0.1353 | 0.4220 | 0.6176 | 0.3012 | 0.3910 | 0.70 |
+| marker | 0.3735 | 0.5974 | 0.1598 | 0.1926 | 0.6121 | 0.3012 | 0.3778 | 0.87 |
+
+---
+
 ## Install
 
 ```bash
@@ -135,6 +161,7 @@ pip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV
 # Linux:  apt install tesseract-ocr
 # macOS:  brew install tesseract
 
+pip install 'docslicer[mcp]'     # MCP server for LLM clients (Claude, Cursor, …)
 pip install 'docslicer[llm]'     # exact token counts via tiktoken (exact_tokens=True)
 pip install 'docslicer[crypto]'  # password-protected Office files (msoffcrypto-tool)
 pip install 'docslicer[parquet]' # Parquet export support
@@ -437,22 +464,51 @@ result.tables_by_page(14)
 result.charts_by_page(14)
 ```
 
+### Parse once, navigate many times
+
+A parsed result is plain data, so you can persist it and reload it later. When an
+agent asks many questions about the same document, there's no need to parse it
+again on every question:
+
+```python
+from pathlib import Path
+import docslicer
+
+cache = Path("annual_report.json")
+
+if cache.exists():
+    result = docslicer.ParseResult.load(cache)
+else:
+    result = docslicer.parse_document("annual_report.pdf")
+    result.save(cache)
+```
+
+A reloaded result supports the full API — `hierarchy`, `find_heading`,
+`chunks_under`, `tables` — so a long-running agent session or document server can
+keep documents open across requests without re-parsing.
+
 ---
 
 ## Export
 
+`save()` decides what to write from the path you give it.
+
 ```python
-# Save everything
-result.save("output/")
-# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
-#   (+ charts.parquet when the document has charts)
+# Save the whole result and reload it later — keeps the heading hierarchy
+result.save("result.json")                     # same output as result.to_json()
+result = docslicer.ParseResult.load("result.json")
 
-# Specific formats
+# A single collection, in the format you name
 result.save("chunks.csv")
 result.save("charts.jsonl")       # stems: chunks | blocks | tables | charts | metadata
-result.save("result.json")        # full parse result as JSON
 result.export_chunks_jsonl("chunks.jsonl")
 
+# One file per collection
+result.save("output/")
+# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
+#   (+ charts.parquet when the document has charts)
+#   Falls back to .csv unless the [parquet] extra is installed.
+
 # Render as Markdown or plain text
 md = result.export_to_markdown(include_tables=True)
 txt = result.export_to_text()
@@ -461,6 +517,9 @@ txt = result.export_to_text()
 df = result.chunks_df()
 ```
 
+Only `result.json` round-trips — the collection and directory forms write flat rows
+without the heading hierarchy, so `ParseResult.load()` can't read them back.
+
 ### Debug mode
 
 ```python
@@ -492,6 +551,96 @@ pip install 'docslicer[ocr]'
 
 ---
 
+## MCP server
+
+DocSlicer ships an [MCP](https://modelcontextprotocol.io) server, so LLM clients
+(Claude Desktop, Claude Code, Cursor, …) can parse and read documents directly.
+
+```bash
+pip install 'docslicer[mcp]'
+docslicer-mcp                    # stdio — what desktop clients launch
+docslicer-mcp --transport http --port 8000
+```
+
+Register it with a client by adding to its MCP config:
+
+```jsonc
+{
+  "mcpServers": {
+    "docslicer": {
+      "command": "docslicer-mcp",
+      "env": { "DOCSLICER_MCP_ROOT": "/Users/you/Documents" }
+    }
+  }
+}
+```
+
+### How it works
+
+A parsed document is far larger than a model's context window, so the server
+never returns one in a single call. `parse` registers the document and hands
+back a `doc_id` handle plus a heading outline. Every other tool takes that
+handle and returns a bounded slice — the model pulls in only what it needs.
+
+| Tool | Returns |
+| --- | --- |
+| `parse` | `doc_id` handle, title, page count, heading outline |
+| `get_outline` | The outline again, for when it scrolls out of context |
+| `read` | The text under one or more headings, named from the outline |
+| `search` | Headings to `read`, ranked, each with a snippet |
+| `to_markdown` | Writes the whole document to disk; returns the path |
+
+Every outline line carries what reading it would cost:
+
+```
+- Financial statements  ~48k
+  - Note 14 — Segment reporting  ~900
+  - Note 15 — Income taxes  ~2.1k
+```
+
+That figure is the same estimate `read` reports back, so a budget made from the
+outline holds when it is spent. Sizes are cumulative — a parent never costs less
+than the children beneath it — which is what makes "descend or just read it" a
+decision the model can make before spending the context rather than after.
+
+`read` takes heading text exactly as the outline prints it. Where a heading
+appears twice, prefixing any ancestor disambiguates it (`"Notes > Revenue"`);
+the full chain is never required. Returned text is interleaved with `[Page X]`
+markers using the document's own page labels (`S-23`, `iv`), so a quotation can
+be cited to the page it actually came from rather than to wherever its section
+began.
+
+`search` is the fallback for when the outline does not settle the question —
+headings that name nothing useful (`Note 14`, `Item 7A`), or a figure buried in
+a table no heading mentions. It combines a whole-word literal match with BM25
+over the chunks, and returns *places*, not answers: each hit is a heading to
+pass to `read`. Query terms that appear nowhere in the document are reported
+back, so a query that scored well on one rare word can be recognised as the bad
+query it was.
+
+`to_markdown` is the escape hatch for when the user wants the document itself
+rather than an answer drawn from it. It writes to disk and returns a path, so
+nothing enters the model's context and document size stops mattering.
+
+Parsed results are cached on disk, so re-parsing the same file with the same
+options is free. The cache key includes the file's size and mtime — edit the
+document and the next `parse` re-parses it automatically.
+
+### Configuration
+
+| Variable | Effect |
+| --- | --- |
+| `DOCSLICER_MCP_ROOT` | Restrict file sources **and** written output to this directory tree |
+| `DOCSLICER_MCP_ALLOW_URLS` | Set to `0` to reject `http(s)` sources |
+| `DOCSLICER_MCP_CACHE` | Where parsed results are persisted (default `~/.cache/docslicer-mcp`) |
+| `DOCSLICER_MCP_CACHE_MAX_MB` | Cache size ceiling, oldest pruned first (default `2048`; `0` disables) |
+
+Set `DOCSLICER_MCP_ROOT` when exposing the server to anything but yourself —
+without it, any readable path on the machine is parseable, and `to_markdown`
+can write anywhere the server process can.
+
+---
+
 ## Format-specific functions
 
 If you know the format upfront and want explicit failure on unexpected input, use the

{docslicer-0.2.0 → docslicer-0.2.1}/README.md

@@ -1,10 +1,16 @@
 # DocSlicer
 
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Commercial license available](https://img.shields.io/badge/License-Commercial-green.svg)](LICENSE-COMMERCIAL.md)
+[![PyPI](https://img.shields.io/pypi/v/docslicer.svg)](https://pypi.org/project/docslicer/) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE) [![Commercial license available](https://img.shields.io/badge/License-Commercial-green.svg)](LICENSE-COMMERCIAL.md)
 
-Lightning-fast, deterministic hierarchical document parser and chunker for business documents. No LLM calls or heavy ML models.
+Lightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.
 
-DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, and a navigable heading hierarchy — preserving the document's own structure instead of guessing at it.
+DocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, markdown and a navigable heading hierarchy.
+
+Top score on [BizDocBench](https://github.com/DocSlicer/BizDocBench) (0.88 overall vs 0.70 for the next-best tool). 0.80 table accuracy, 0.98 content faithfulness, 0.85 heading recognition and hierarchy preservation, and 0.76 RAG retrieval performance.
+
+**Add DocSlicer to your AI pipeline:**
+- Classic RAG: the layout-aware chunker gives you clean non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed.
+- Vectorless RAG: for when you want an answer out of a document right now. The agent pulls the outline, picks the section it needs, and navigates to the correct section of text without embedding the whole document
 
 ```python
 import docslicer
@@ -60,6 +66,23 @@ if __name__ == "__main__":
 
 ---
 
+## Benchmarks
+
+Measured with [BizDocBench](https://github.com/DocSlicer/BizDocBench) — an open benchmark for multi-format business document parsing. All scores are 0–1 (higher is better); `pages_per_sec_aggregate` is throughput across the full corpus.
+
+| Tool | Score | Coverage | Speed | Hierarchy | Faithfulness | Tables | Retrieval | Pages/sec |
+|---|---|---|---|---|---|---|---|---|
+| **docslicer** | **0.8796** | 1.0000 | 0.8836 | 0.8466 | 0.9824 | 0.8047 | 0.7601 | 31.27 |
+| docling | 0.7036 | 1.0000 | 0.3805 | 0.4905 | 0.8927 | 0.7467 | 0.7111 | 3.46 |
+| markitdown | 0.5838 | 1.0000 | 0.8513 | 0.0604 | 0.7972 | 0.2584 | 0.5357 | 27.42 |
+| unstructured | 0.5798 | 0.9091 | 0.1073 | 0.4327 | 0.9057 | 0.4812 | 0.6430 | 0.52 |
+| opendataloader | 0.5359 | 0.5844 | 1.0000 | 0.3853 | 0.6484 | 0.2655 | 0.3317 | 117.26 |
+| pymupdf4llm | 0.4519 | 0.5974 | 0.6492 | 0.1089 | 0.6456 | 0.3551 | 0.3552 | 11.84 |
+| mineru | 0.4107 | 0.5974 | 0.1353 | 0.4220 | 0.6176 | 0.3012 | 0.3910 | 0.70 |
+| marker | 0.3735 | 0.5974 | 0.1598 | 0.1926 | 0.6121 | 0.3012 | 0.3778 | 0.87 |
+
+---
+
 ## Install
 
 ```bash
@@ -78,6 +101,7 @@ pip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV
 # Linux:  apt install tesseract-ocr
 # macOS:  brew install tesseract
 
+pip install 'docslicer[mcp]'     # MCP server for LLM clients (Claude, Cursor, …)
 pip install 'docslicer[llm]'     # exact token counts via tiktoken (exact_tokens=True)
 pip install 'docslicer[crypto]'  # password-protected Office files (msoffcrypto-tool)
 pip install 'docslicer[parquet]' # Parquet export support
@@ -380,22 +404,51 @@ result.tables_by_page(14)
 result.charts_by_page(14)
 ```
 
+### Parse once, navigate many times
+
+A parsed result is plain data, so you can persist it and reload it later. When an
+agent asks many questions about the same document, there's no need to parse it
+again on every question:
+
+```python
+from pathlib import Path
+import docslicer
+
+cache = Path("annual_report.json")
+
+if cache.exists():
+    result = docslicer.ParseResult.load(cache)
+else:
+    result = docslicer.parse_document("annual_report.pdf")
+    result.save(cache)
+```
+
+A reloaded result supports the full API — `hierarchy`, `find_heading`,
+`chunks_under`, `tables` — so a long-running agent session or document server can
+keep documents open across requests without re-parsing.
+
 ---
 
 ## Export
 
+`save()` decides what to write from the path you give it.
+
 ```python
-# Save everything
-result.save("output/")
-# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
-#   (+ charts.parquet when the document has charts)
+# Save the whole result and reload it later — keeps the heading hierarchy
+result.save("result.json")                     # same output as result.to_json()
+result = docslicer.ParseResult.load("result.json")
 
-# Specific formats
+# A single collection, in the format you name
 result.save("chunks.csv")
 result.save("charts.jsonl")       # stems: chunks | blocks | tables | charts | metadata
-result.save("result.json")        # full parse result as JSON
 result.export_chunks_jsonl("chunks.jsonl")
 
+# One file per collection
+result.save("output/")
+# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json
+#   (+ charts.parquet when the document has charts)
+#   Falls back to .csv unless the [parquet] extra is installed.
+
 # Render as Markdown or plain text
 md = result.export_to_markdown(include_tables=True)
 txt = result.export_to_text()
@@ -404,6 +457,9 @@ txt = result.export_to_text()
 df = result.chunks_df()
 ```
 
+Only `result.json` round-trips — the collection and directory forms write flat rows
+without the heading hierarchy, so `ParseResult.load()` can't read them back.
+
 ### Debug mode
 
 ```python
@@ -435,6 +491,96 @@ pip install 'docslicer[ocr]'
 
 ---
 
+## MCP server
+
+DocSlicer ships an [MCP](https://modelcontextprotocol.io) server, so LLM clients
+(Claude Desktop, Claude Code, Cursor, …) can parse and read documents directly.
+
+```bash
+pip install 'docslicer[mcp]'
+docslicer-mcp                    # stdio — what desktop clients launch
+docslicer-mcp --transport http --port 8000
+```
+
+Register it with a client by adding to its MCP config:
+
+```jsonc
+{
+  "mcpServers": {
+    "docslicer": {
+      "command": "docslicer-mcp",
+      "env": { "DOCSLICER_MCP_ROOT": "/Users/you/Documents" }
+    }
+  }
+}
+```
+
+### How it works
+
+A parsed document is far larger than a model's context window, so the server
+never returns one in a single call. `parse` registers the document and hands
+back a `doc_id` handle plus a heading outline. Every other tool takes that
+handle and returns a bounded slice — the model pulls in only what it needs.
+
+| Tool | Returns |
+| --- | --- |
+| `parse` | `doc_id` handle, title, page count, heading outline |
+| `get_outline` | The outline again, for when it scrolls out of context |
+| `read` | The text under one or more headings, named from the outline |
+| `search` | Headings to `read`, ranked, each with a snippet |
+| `to_markdown` | Writes the whole document to disk; returns the path |
+
+Every outline line carries what reading it would cost:
+
+```
+- Financial statements  ~48k
+  - Note 14 — Segment reporting  ~900
+  - Note 15 — Income taxes  ~2.1k
+```
+
+That figure is the same estimate `read` reports back, so a budget made from the
+outline holds when it is spent. Sizes are cumulative — a parent never costs less
+than the children beneath it — which is what makes "descend or just read it" a
+decision the model can make before spending the context rather than after.
+
+`read` takes heading text exactly as the outline prints it. Where a heading
+appears twice, prefixing any ancestor disambiguates it (`"Notes > Revenue"`);
+the full chain is never required. Returned text is interleaved with `[Page X]`
+markers using the document's own page labels (`S-23`, `iv`), so a quotation can
+be cited to the page it actually came from rather than to wherever its section
+began.
+
+`search` is the fallback for when the outline does not settle the question —
+headings that name nothing useful (`Note 14`, `Item 7A`), or a figure buried in
+a table no heading mentions. It combines a whole-word literal match with BM25
+over the chunks, and returns *places*, not answers: each hit is a heading to
+pass to `read`. Query terms that appear nowhere in the document are reported
+back, so a query that scored well on one rare word can be recognised as the bad
+query it was.
+
+`to_markdown` is the escape hatch for when the user wants the document itself
+rather than an answer drawn from it. It writes to disk and returns a path, so
+nothing enters the model's context and document size stops mattering.
+
+Parsed results are cached on disk, so re-parsing the same file with the same
+options is free. The cache key includes the file's size and mtime — edit the
+document and the next `parse` re-parses it automatically.
+
+### Configuration
+
+| Variable | Effect |
+| --- | --- |
+| `DOCSLICER_MCP_ROOT` | Restrict file sources **and** written output to this directory tree |
+| `DOCSLICER_MCP_ALLOW_URLS` | Set to `0` to reject `http(s)` sources |
+| `DOCSLICER_MCP_CACHE` | Where parsed results are persisted (default `~/.cache/docslicer-mcp`) |
+| `DOCSLICER_MCP_CACHE_MAX_MB` | Cache size ceiling, oldest pruned first (default `2048`; `0` disables) |
+
+Set `DOCSLICER_MCP_ROOT` when exposing the server to anything but yourself —
+without it, any readable path on the machine is parseable, and `to_markdown`
+can write anywhere the server process can.
+
+---
+
 ## Format-specific functions
 
 If you know the format upfront and want explicit failure on unexpected input, use the

{docslicer-0.2.0 → docslicer-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "docslicer"
-version = "0.2.0"
+version = "0.2.1"
 description = "Deterministic hierarchical document parser and chunker"
 readme = "README.md"
 license = "AGPL-3.0-only"
@@ -65,6 +65,12 @@ crypto = [
 parquet = [
     "pyarrow>=18.0",
 ]
+mcp = [
+    "mcp>=2.0",
+    # The server reports token costs the model budgets against, so it counts
+    # exactly rather than estimating. Falls back to chars/4 if unusable.
+    "tiktoken>=0.10",
+]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.24",
@@ -72,6 +78,7 @@ dev = [
 
 [project.scripts]
 docslicer = "docslicer.cli:main"
+docslicer-mcp = "docslicer.mcp.server:main"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{docslicer-0.2.0 → docslicer-0.2.1}/src/docslicer/_config.py

@@ -13,7 +13,8 @@ class ParseConfig:
     """User-facing configuration for a parse.
 
     Chunking: ``max_chunk_size`` / ``optimal_chunk_size`` / ``min_chunk_size``
-    bound chunk length (in characters, or tokens when ``exact_tokens=True``);
+    bound chunk length in characters (always — ``exact_tokens`` changes how the
+    resulting chunks are *counted*, not where they are cut);
     ``chunking`` toggles chunking entirely and ``merge_small_chunks`` folds
     undersized chunks into neighbours. ``table_representation`` selects how
     tables are serialized ("markdown", "jsonl", or "melted"). ``extra_fields``

{docslicer-0.2.0 → docslicer-0.2.1}/src/docslicer/_orchestrator.py

@@ -64,6 +64,7 @@ def _resolve_metadata(
         source_url=source_url,
         file_size_bytes=file_size_bytes,
         is_password_protected=bool(discovered.get("is_password_protected", False)),
+        renderer=discovered.get("renderer"),
         page_count=int(discovered.get("page_count") or 0),
         page_width=discovered.get("page_width"),
         page_height=discovered.get("page_height"),
@@ -435,8 +436,11 @@ def _build_result(
     doc_token_count: int | None = None
     doc_token_count_exact = False
     if not df_chunks.empty and "token_count" in df_chunks.columns:
+        from .shared.step_08_chunk_builder import token_encoder
         doc_token_count = int(df_chunks["token_count"].fillna(0).sum())
-        doc_token_count_exact = bool(config.exact_tokens)
+        # Requesting exact counts is not getting them: tiktoken may be missing, or
+        # unable to fetch its vocabulary. Report what the counter actually did.
+        doc_token_count_exact = bool(config.exact_tokens) and token_encoder() is not None
 
     metadata = _resolve_metadata(
         discovered_metadata, source_url, source_filename, file_size_bytes, run_id, df_blocks,

{docslicer-0.2.0 → docslicer-0.2.1}/src/docslicer/_result.py

@@ -502,24 +502,81 @@ def _collect_block_ids(node: HierarchyNode, recursive: bool) -> set[str]:
     return ids
 
 
+def _split_table_row(line: str) -> list[str]:
+    """Split one pipe-table line into stripped cells, dropping the outer pipes."""
+    cells = line.strip().split("|")
+    if cells and cells[0].strip() == "":
+        cells = cells[1:]
+    if cells and cells[-1].strip() == "":
+        cells = cells[:-1]
+    return [c.strip() for c in cells]
+
+
+def _is_sep_cell(cell: str) -> bool:
+    return bool(cell) and all(c in "-:" for c in cell)
+
+
+def _is_sep_row(row: list[str]) -> bool:
+    return any(row) and all(_is_sep_cell(c) for c in row if c)
+
+
+def _gfm_normalize_table(markdown: str) -> str:
+    """Rewrite a table so it renders under GitHub-flavored Markdown.
+
+    ``_format_table_markdown`` is faithful to the source grid: it draws the
+    separator under the *last* header row, and omits it entirely for tables with
+    no header cells. GFM instead requires exactly one header row followed by one
+    separator, so:
+
+      * multiple header rows collapse into one, joined per column with " > "
+        (the convention ``_format_table_melted`` already uses for header paths), and
+      * headerless tables gain a blank header row, which keeps every source row
+        in the body rather than promoting one to a header the detector rejected.
+
+    Text that is not a pipe table passes through untouched.
+    """
+    lines = markdown.strip().splitlines()
+    if not lines or any(l.strip() and not l.strip().startswith("|") for l in lines):
+        return markdown
+
+    rows = [_split_table_row(l) for l in lines if l.strip().startswith("|")]
+    if not rows:
+        return markdown
+
+    n_cols = max(len(r) for r in rows)
+    for row in rows:
+        while len(row) < n_cols:
+            row.append("")
+
+    sep = ["---"] * n_cols
+    first_sep = next((i for i, row in enumerate(rows) if _is_sep_row(row)), None)
+
+    if first_sep is None:
+        rows = [[""] * n_cols, sep] + rows
+    elif first_sep == 0:
+        rows = [[""] * n_cols] + rows
+    elif first_sep > 1:
+        header = []
+        for col in range(n_cols):
+            parts: list[str] = []
+            for row in rows[:first_sep]:
+                # A rowspan header cell repeats down the header rows — "Region >
+                # Region" carries no more than "Region" does.
+                if row[col] and (not parts or parts[-1] != row[col]):
+                    parts.append(row[col])
+            header.append(" > ".join(parts))
+        rows = [header, sep] + rows[first_sep + 1:]
+
+    return "\n".join("| " + " | ".join(row) + " |" for row in rows)
+
+
 def _prettify_table(markdown: str) -> str:
     """Reformat a markdown table so pipe characters are vertically aligned."""
     lines = markdown.strip().splitlines()
     if not lines:
         return markdown
 
-    def _split_row(line: str) -> list[str]:
-        cells = line.strip().split("|")
-        if cells and cells[0].strip() == "":
-            cells = cells[1:]
-        if cells and cells[-1].strip() == "":
-            cells = cells[:-1]
-        return [c.strip() for c in cells]
-
-    def _is_sep(cell: str) -> bool:
-        return bool(cell) and all(c in "-:" for c in cell)
-
-    rows = [_split_row(l) for l in lines if l.strip().startswith("|")]
+    rows = [_split_table_row(l) for l in lines if l.strip().startswith("|")]
     if not rows:
         return markdown
 
@@ -528,7 +585,7 @@ def _prettify_table(markdown: str) -> str:
         while len(row) < n_cols:
             row.append("")
 
-    sep_indices = {i for i, row in enumerate(rows) if all(_is_sep(c) for c in row if c)}
+    sep_indices = {i for i, row in enumerate(rows) if _is_sep_row(row)}
     col_widths = [3] * n_cols
     for i, row in enumerate(rows):
         if i not in sep_indices:
@@ -664,8 +721,16 @@ class ParseResult:
         include_toc: bool = True,
         include_furniture: bool = True,
         prettify: bool = True,
+        gfm_tables: bool = True,
     ) -> str:
-        """Render the document as Markdown using blocks as the source of truth."""
+        """Render the document as Markdown using blocks as the source of truth.
+
+        ``gfm_tables`` rewrites tables to the one-header-row-plus-separator shape
+        GitHub-flavored Markdown renderers require. Pass ``False`` for the faithful
+        grid — multiple header rows, and no separator for tables that genuinely
+        have no header — which is what ``Table.markdown`` and the block text always
+        carry regardless of this flag.
+        """
         _HEADING_ROLES = {
             "heading", "toc_heading", "exhibit_heading", "hybrid_heading_paragraph",
         }
@@ -704,6 +769,8 @@ class ParseResult:
                 if include_tables:
                     table = tables_by_id.get(block.table_ids[0]) if block.table_ids else None
                     raw = table.markdown if table else text
+                    if gfm_tables:
+                        raw = _gfm_normalize_table(raw)
                     parts.append(_prettify_table(raw) if prettify else raw)
             elif block.type == "chart":
                 if text: