DocSlicer

# DocSlicer

[![PyPI](https://img.shields.io/pypi/v/docslicer.svg)](https://pypi.org/project/docslicer/) [![Python versions](https://img.shields.io/pypi/pyversions/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)

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_server-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=docslicer&config=%7B%22name%22%3A%22docslicer%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--from%22%2C%22docslicer%5Bmcp%5D%22%2C%22docslicer-mcp%22%5D%7D) [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP_server-000000?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=docslicer&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJkb2NzbGljZXJbbWNwXSIsImRvY3NsaWNlci1tY3AiXX0%3D) [![Download .mcpb for Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Download_.mcpb-D97757?logo=claude&logoColor=white)](https://github.com/DocSlicer/DocSlicer/releases/latest)

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, 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.

**Two ways to use it:**

- **As a Python library — classic RAG.** The layout-aware chunker gives you clean, non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed. [Jump to the API ↓](#parsing)
- **As an MCP server — vectorless RAG.** For when you want an answer out of a document right now. Claude, Cursor, or VS Code pulls the outline, picks the section it needs, and reads only that — no embedding, and no 200-page document in the context window. [Jump to setup ↓](#mcp-server)

### Quick start

```python
import docslicer

def main():
    result = docslicer.parse_document("annual_report.pdf")

    # Inspect the outline first
    result.hierarchy.to_outline()
    # - PART I — FINANCIAL INFORMATION
    #   - Item 1. Financial Statements
    #     - Notes to Condensed Consolidated Financial Statements
    #       - Note 4 – Financial Instruments
    #         - Derivative Instruments and Hedging
    #           - Foreign Exchange Rate Risk
    #           - Interest Rate Risk
    #         - Accounts Receivable
    #           - Trade Receivables
    #   - Item 2. Management's Discussion and Analysis
    #     - Liquidity and Capital Resources
    # - PART II — OTHER INFORMATION
    #   ...

    # Pull only the chunks you need
    risk_section = result.find_heading("Risk Factors")[0]
    chunks = result.chunks_under(risk_section)

    # Tables come back structured, not as flat text
    for table in result.tables_under(risk_section):
        print(table.markdown)

if __name__ == "__main__":
    main()
```

---

## Features

- **No LLM, VLM, or ML models** — fully deterministic; no model weights to download, no GPU required, no cold-start delay
- **Lightweight** — ~630 KB wheel with no heavy ML dependencies
- **Agentic-friendly** — reduces token spend on long documents: have the agent inspect the outline first, then pull only the relevant chunks into context instead of feeding a 500-page document verbatim; well-suited for legal texts, technical SOPs, financial filings, and compliance documents
- **Deep hierarchy extraction** — works for both numbered (`1.`, `1.2.`, `1.2.3`) and free-form headings; uses font size, bold weight, and document structure — not inference; handles re-entry after exhibit breaks and repeated navigation headings across pages
- **Structure-aware chunking** — splits at heading and paragraph boundaries, preserving semantic coherence
- **Zero character overlap** — chunks are non-overlapping by default; no duplicated tokens in your context window
- **Unified result object** — `chunks`, `blocks`, `tables`, `charts`, `metadata`, and `hierarchy` in one place
- **Structured tables** — tables come back as cells, not flat text; export as Markdown, JSONL, or melted format
- **Multiple export formats** — CSV, Markdown, JSONL, Parquet, JSON, plain text, and DataFrames
- **Reading order preserved** — including multi-column PDF layouts
- **Supports `pdf`, `docx`, `pptx`, and `html`** — including JS-rendered pages via Playwright
- **Robust URL fetching** — always renders pages in a real browser, handling cookie banners and bot protection out of the box; also preserves styling signals like boldness that raw HTML omits, producing sharper heading detection and chunk quality
- **OCR fallback** — auto-detects scanned pages and falls back to Tesseract when the extra is installed

---

## 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
pip install docslicer
```

The core install is dependency-light. Optional features are available as extras:

```bash
pip install 'docslicer[html]'    # HTML / URL parsing via Playwright
playwright install chromium       # one-time browser install (Chromium only)

pip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV
# The tesserocr wheel bundles libtesseract but NOT the language models,
# so install the Tesseract engine to provide them (docslicer auto-detects the path):
# 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
```

Extras can be combined: `pip install 'docslicer[html,ocr,llm]'`.

**Requires Python 3.10+**

---

## What you get back (ParseResult)

`parse_document` returns a `ParseResult`:

```python
result.chunks      # list[Chunk]   — heading-aware text chunks, ready for embedding
result.blocks      # list[Block]   — paragraph/heading/table blocks before chunking
result.tables      # list[Table]   — structured tables with cells, spans, and markdown
result.charts      # list[Chart]   — charts as extracted data points (docx/pptx)
result.metadata    # DocumentMetadata — title, author, language, page count, OCR flag
result.hierarchy   # HierarchyTree — navigable tree of all headings
```

Each `Chunk` carries:

```python
chunk.text          # str   — chunk text
chunk.path          # list  — full heading breadcrumb from root to nearest heading
chunk.heading       # str   — nearest heading above this chunk
chunk.section       # str   — body | toc | exhibit | header | footer | coverpage | …
chunk.page_number   # int   — 1-based physical page
chunk.page_label    # str   — "A-6", "iv", "F-3" — as printed on the page
chunk.table_ids     # list  — IDs of tables referenced in this chunk
chunk.chart_ids     # list  — IDs of charts referenced in this chunk (docx/pptx)
chunk.link_url      # list  — URLs found in this chunk
chunk.bbox          # BBox  — bounding box (PDF only)
```

Every chunk carries its full heading breadcrumb, no matter how deeply nested. For example, a paragraph six levels deep in a financial filing:

```python
chunk.path == [
    "# PART I — FINANCIAL INFORMATION",
    "## Item 1. Financial Statements",
    "### Notes to Condensed Consolidated Financial Statements (Unaudited)",
    "#### Note 4 – Financial Instruments",
    "##### Accounts Receivable",
    "###### Trade Receivables",
]
```

This lets downstream code filter or group chunks by any level of the hierarchy without re-parsing the document.

---

## Supported formats

| Format | Extension | Notes |
|--------|-----------|-------|
| PDF | `.pdf` | Text-based and scanned (OCR extra required for scanned) |
| Word | `.docx` | Full style and outline hierarchy |
| HTML | `.html`, URLs | Static files and JS-rendered pages (html extra required for URLs) |
| PowerPoint | `.pptx` | Slides, speaker notes, charts |

Not supported: `.doc`, `.ppt` (legacy Office formats), `.xlsx`.

---

## Parsing

`parse_document` auto-detects the format from the file extension or magic bytes. Pass a file path, URL, raw `bytes`, or a file-like object:

```python
result = docslicer.parse_document("contract.docx")
result = docslicer.parse_document("report.pdf")
result = docslicer.parse_document("https://www.sec.gov/Archives/edgar/data/.../10-K.htm")
result = docslicer.parse_document(file_bytes)
```

### Parsing & content options

`parse_document` (and the format-specific functions) accept options that contro