{"slug": "show-hn-docslicer-structure-aware-pdf-docx-pptx-parser-31-pages-sec-on-cpu", "title": "Show HN: DocSlicer – Structure-aware PDF/DOCX/PPTX parser, 31 pages/SEC on CPU", "summary": "DocSlicer, a new structure-aware document parser, achieves 31 pages per second on CPU and scored 0.88 overall on the BizDocBench benchmark, outperforming the next-best tool's 0.70. The deterministic parser handles PDF, DOCX, PPTX, and HTML without LLM or ML models, offering layout-aware chunking, heading hierarchy extraction, and structured table output for RAG pipelines.", "body_md": "Lightning-fast (31 pages/sec), deterministic document parser and chunker for business documents. No LLM calls or heavy ML models.\n\nDocSlicer turns PDFs, Word documents, HTML pages, and PowerPoint files into clean chunks, structured blocks, tables, charts, markdown and a navigable heading hierarchy.\n\nTop 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.\n\n**Add DocSlicer to your AI pipeline:**\n\n- Classic RAG: the layout-aware chunker gives you clean non-overlapping chunks, each carrying its full heading breadcrumb, ready to embed.\n- 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\n\n``` python\nimport docslicer\n\ndef main():\n    result = docslicer.parse_document(\"annual_report.pdf\")\n\n    # Inspect the outline first\n    result.hierarchy.to_outline()\n    # - PART I — FINANCIAL INFORMATION\n    #   - Item 1. Financial Statements\n    #     - Notes to Condensed Consolidated Financial Statements\n    #       - Note 4 – Financial Instruments\n    #         - Derivative Instruments and Hedging\n    #           - Foreign Exchange Rate Risk\n    #           - Interest Rate Risk\n    #         - Accounts Receivable\n    #           - Trade Receivables\n    #   - Item 2. Management's Discussion and Analysis\n    #     - Liquidity and Capital Resources\n    # - PART II — OTHER INFORMATION\n    #   ...\n\n    # Pull only the chunks you need\n    risk_section = result.find_heading(\"Risk Factors\")[0]\n    chunks = result.chunks_under(risk_section)\n\n    # Tables come back structured, not as flat text\n    for table in result.tables_under(risk_section):\n        print(table.markdown)\n\nif __name__ == \"__main__\":\n    main()\n```\n\n**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.`\n\n,`1.2.`\n\n,`1.2.3`\n\n) 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`\n\n,`blocks`\n\n,`tables`\n\n,`charts`\n\n,`metadata`\n\n, and`hierarchy`\n\nin 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**— including JS-rendered pages via Playwright`pdf`\n\n,`docx`\n\n,`pptx`\n\n, and`html`\n\n**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\n\nMeasured 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`\n\nis throughput across the full corpus.\n\n| Tool | Score | Coverage | Speed | Hierarchy | Faithfulness | Tables | Retrieval | Pages/sec |\n|---|---|---|---|---|---|---|---|---|\ndocslicer |\n0.8796 |\n1.0000 | 0.8836 | 0.8466 | 0.9824 | 0.8047 | 0.7601 | 31.27 |\n| docling | 0.7036 | 1.0000 | 0.3805 | 0.4905 | 0.8927 | 0.7467 | 0.7111 | 3.46 |\n| markitdown | 0.5838 | 1.0000 | 0.8513 | 0.0604 | 0.7972 | 0.2584 | 0.5357 | 27.42 |\n| unstructured | 0.5798 | 0.9091 | 0.1073 | 0.4327 | 0.9057 | 0.4812 | 0.6430 | 0.52 |\n| opendataloader | 0.5359 | 0.5844 | 1.0000 | 0.3853 | 0.6484 | 0.2655 | 0.3317 | 117.26 |\n| pymupdf4llm | 0.4519 | 0.5974 | 0.6492 | 0.1089 | 0.6456 | 0.3551 | 0.3552 | 11.84 |\n| mineru | 0.4107 | 0.5974 | 0.1353 | 0.4220 | 0.6176 | 0.3012 | 0.3910 | 0.70 |\n| marker | 0.3735 | 0.5974 | 0.1598 | 0.1926 | 0.6121 | 0.3012 | 0.3778 | 0.87 |\n\n```\npip install docslicer\n```\n\nThe core install is dependency-light. Optional features are available as extras:\n\n```\npip install 'docslicer[html]'    # HTML / URL parsing via Playwright\nplaywright install chromium       # one-time browser install (Chromium only)\n\npip install 'docslicer[ocr]'     # scanned PDF support via Tesseract + OpenCV\n# The tesserocr wheel bundles libtesseract but NOT the language models,\n# so install the Tesseract engine to provide them (docslicer auto-detects the path):\n# Linux:  apt install tesseract-ocr\n# macOS:  brew install tesseract\n\npip install 'docslicer[llm]'     # exact token counts via tiktoken (exact_tokens=True)\npip install 'docslicer[crypto]'  # password-protected Office files (msoffcrypto-tool)\npip install 'docslicer[parquet]' # Parquet export support\n```\n\nExtras can be combined: `pip install 'docslicer[html,ocr,llm]'`\n\n.\n\n**Requires Python 3.10+**\n\n`parse_document`\n\nreturns a `ParseResult`\n\n:\n\n```\nresult.chunks      # list[Chunk]   — heading-aware text chunks, ready for embedding\nresult.blocks      # list[Block]   — paragraph/heading/table blocks before chunking\nresult.tables      # list[Table]   — structured tables with cells, spans, and markdown\nresult.charts      # list[Chart]   — charts as extracted data points (docx/pptx)\nresult.metadata    # DocumentMetadata — title, author, language, page count, OCR flag\nresult.hierarchy   # HierarchyTree — navigable tree of all headings\n```\n\nEach `Chunk`\n\ncarries:\n\n```\nchunk.text          # str   — chunk text\nchunk.path          # list  — full heading breadcrumb from root to nearest heading\nchunk.heading       # str   — nearest heading above this chunk\nchunk.section       # str   — body | toc | exhibit | header | footer | coverpage | …\nchunk.page_number   # int   — 1-based physical page\nchunk.page_label    # str   — \"A-6\", \"iv\", \"F-3\" — as printed on the page\nchunk.table_ids     # list  — IDs of tables referenced in this chunk\nchunk.chart_ids     # list  — IDs of charts referenced in this chunk (docx/pptx)\nchunk.link_url      # list  — URLs found in this chunk\nchunk.bbox          # BBox  — bounding box (PDF only)\n```\n\nEvery chunk carries its full heading breadcrumb, no matter how deeply nested. For example, a paragraph six levels deep in a financial filing:\n\n```\nchunk.path == [\n    \"# PART I — FINANCIAL INFORMATION\",\n    \"## Item 1. Financial Statements\",\n    \"### Notes to Condensed Consolidated Financial Statements (Unaudited)\",\n    \"#### Note 4 – Financial Instruments\",\n    \"##### Accounts Receivable\",\n    \"###### Trade Receivables\",\n]\n```\n\nThis lets downstream code filter or group chunks by any level of the hierarchy without re-parsing the document.\n\n| Format | Extension | Notes |\n|---|---|---|\n`.pdf` |\nText-based and scanned (OCR extra required for scanned) | |\n| Word | `.docx` |\nFull style and outline hierarchy |\n| HTML | `.html` , URLs |\nStatic files and JS-rendered pages (html extra required for URLs) |\n| PowerPoint | `.pptx` |\nSlides, speaker notes, charts |\n\nNot supported: `.doc`\n\n, `.ppt`\n\n(legacy Office formats), `.xlsx`\n\n.\n\n`parse_document`\n\nauto-detects the format from the file extension or magic bytes. Pass a file path, URL, raw `bytes`\n\n, or a file-like object:\n\n```\nresult = docslicer.parse_document(\"contract.docx\")\nresult = docslicer.parse_document(\"report.pdf\")\nresult = docslicer.parse_document(\"https://www.sec.gov/Archives/edgar/data/.../10-K.htm\")\nresult = docslicer.parse_document(file_bytes)\n```\n\n`parse_document`\n\n(and the format-specific functions) accept options that control what\ngets parsed and how, before it's chunked. Format-specific toggles are accepted everywhere\nfor a uniform API but only take effect for the relevant format.\n\n```\nresult = docslicer.parse_document(\n    \"contract.docx\",\n    password=\"admin123\",           # decrypt password-protected files; .docx and .pptx needs [crypto] extra\n    max_workers=4,                 # process-pool width for PDF extraction/OCR (default: auto by CPU cores)\n    include_headers_footers=True,  # docx: include header/footer content (default False)\n    include_footnotes=True,        # docx: include footnotes (default True)\n    include_comments=True,         # docx: include review comments (default False)\n    include_speaker_notes=True,    # pptx: include slide speaker notes (default True)\n    use_browser=True,              # html/URL: render in a real browser (default True)\n)\nresult = docslicer.parse_document(\n    \"report.pdf\",\n    max_chunk_size=2000,          # hard cap, default 3200\n    optimal_chunk_size=800,       # target size, default 1500\n    min_chunk_size=400,           # soft floor, default 700\n    chunking=False,               # skip chunking, return blocks only (faster)\n    merge_small_chunks=True,      # merge chunks below min_chunk_size (default True)\n    table_representation=\"jsonl\", # \"markdown\" (default) | \"jsonl\" | \"melted\"\n    exact_tokens=True,            # exact tiktoken (cl100k_base) counts; needs [llm] extra, else char/4 estimate\n    extra_fields=[\"is_bold\", \"font_size\", \"font_name\"],  # surface internal pipeline columns on each chunk/block via .extra\n)\n```\n\nBecause DocSlicer is structure-aware, it initially produces one chunk per heading or paragraph boundary. For documents with many short sections this can yield a lot of small chunks. With `merge_small_chunks=True`\n\n(the default), sibling sections under the same parent heading are merged together until they reach `min_chunk_size`\n\n— but never across heading boundaries into a different parent.\n\nFor example, these five short sections all fall under `## Products and Services Performance`\n\n:\n\n```\n### Mac          → \"Mac net sales decreased …\"            (~120 chars)\n### iPad         → \"iPad net sales increased …\"           (~180 chars)\n### Wearables    → \"Wearables net sales decreased …\"      (~130 chars)\n### Services     → \"Services net sales increased …\"       (~160 chars)\n```\n\nInstead of four tiny chunks, they get merged into one coherent chunk that still carries the correct `path`\n\nfor each paragraph. Set `merge_small_chunks=False`\n\nif you need one chunk per section regardless of size.\n\n`table_representation`\n\ncontrols how tables are serialised into chunk text. Given a\nfinancial table with multi-row column headers:\n\n** \"markdown\" (default)** — preserves the original 2D layout:\n\n```\n|           | Three Months Ended    | Three Months Ended    |\n|           | December 27, 2025     | December 28, 2024     |\n|-----------|----------------------:|----------------------:|\n| iPhone ®  |              $85,269  |              $69,138  |\n| Mac ®     |               8,386   |               8,987   |\n| iPad ®    |               8,595   |               8,088   |\n| …         |                   …   |                   …   |\n```\n\n** \"melted\"** — one row per cell, headers joined with\n\n`>`\n\n. Good for sparse or\npivot-style tables where individual cell retrieval matters:\n\n```\niPhone ® | Three Months Ended > December 27, 2025 | $85,269\niPhone ® | Three Months Ended > December 28, 2024 | $69,138\nMac ® | Three Months Ended > December 27, 2025 | 8,386\nMac ® | Three Months Ended > December 28, 2024 | 8,987\niPad ® | Three Months Ended > December 27, 2025 | 8,595\niPad ® | Three Months Ended > December 28, 2024 | 8,088\n…\n```\n\n** \"jsonl\"** — one JSON object per row, multi-row headers joined with\n\n`_`\n\n. Useful\nwhen chunks are fed into structured extraction or tool-use pipelines:\n\n```\n{\"Metric\": \"iPhone ®\", \"Three Months Ended_December 27, 2025\": \"$85,269\", \"Three Months Ended_December 28, 2024\": \"$69,138\"}\n{\"Metric\": \"Mac ®\", \"Three Months Ended_December 27, 2025\": \"8,386\", \"Three Months Ended_December 28, 2024\": \"8,987\"}\n{\"Metric\": \"iPad ®\", \"Three Months Ended_December 27, 2025\": \"8,595\", \"Three Months Ended_December 28, 2024\": \"8,088\"}\n…\n```\n\nPoint `parse_all`\n\nat a folder (or pass a list of paths/URLs). It yields `(source, result)`\n\npairs, and a file that fails to parse yields the `Exception`\n\ninstead of aborting the batch.\nAny `parse_document`\n\nkeyword — chunk sizes, `include_*`\n\n, etc. — is forwarded per document.\n\n```\nfor path, result in docslicer.parse_all(\"documents/\", recursive=True, max_chunk_size=2000):\n    if isinstance(result, Exception):\n        print(f\"Failed {path}: {result}\")\n    else:\n        print(f\"{path}: {len(result.chunks)} chunks\")\n```\n\n`DocumentParser`\n\nholds a fixed `ParseConfig`\n\nacross many documents and keeps a single\nbrowser open across HTML/URL inputs (launched lazily on the first HTML parse), so a batch\nof URLs starts Chromium once instead of once per document. Use it as a context manager so\nthat browser is always released:\n\n``` python\nfrom docslicer import DocumentParser, ParseConfig\n\nconfig = ParseConfig(max_chunk_size=1500, optimal_chunk_size=600)\n\nwith DocumentParser(config) as parser:\n    for path, result in parser.parse_all(paths):   # or parser.parse(path) for one\n        ...\n```\n\nThere are two independent knobs, and they compose:\n\n—`ParseConfig(max_workers=N)`\n\n*within*a single document: parallelizes PDF word extraction, cell building, and OCR across processes (default: auto, sized to CPU cores). Best when documents are large.—`DocumentParser(config, workers=N)`\n\n*across*documents: fans whole documents out over`N`\n\nworker processes, each with its own config and browser. Best when you have many documents. Results arrive in submission order (this path isn't lazy per-document).\n\nSetting `workers`\n\nalone defaults each worker's `max_workers`\n\nto `1`\n\n, so nested pools don't\noversubscribe the machine; set both explicitly to run both levels at once. The `workers`\n\npath can't forward a browser session or `on_stage`\n\ncallback across processes — leave\n`workers`\n\nunset when you need those.\n\nGuard your entry point.DocSlicer uses a`ProcessPoolExecutor`\n\nwhenever there's real CPU work to fan out —any PDF over ~50 pages, any scanned/OCR PDF of any length, and both parallelism knobs above. This is not opt-in: a plain`docslicer.parse_document(\"big.pdf\")`\n\ntriggers it too. On macOS and Windows, Python spawns workers by re-importing your script top to bottom, so a parse that runs at module level makes each worker re-run it and spawn again — raising`RuntimeError: An attempt has been made to start a new process before the current process ... bootstrapping phase`\n\n. Put your parsing code inside a function behind an`if __name__ == \"__main__\":`\n\nguard:\n\n``` python\ndef main():\n    with DocumentParser(config, workers=4) as parser:\n        for path, result in parser.parse_all(paths):\n            ...\n\nif __name__ == \"__main__\":\n    main()\n```\n\nMost chunking libraries give you a flat list of text segments. DocSlicer also gives you a navigable tree of the document's heading structure, extracted deterministically from the document itself.\n\nThis is particularly useful for agents and retrieval pipelines working with long documents: rather than feeding the entire document into context, the agent can inspect the outline first to understand the structure, decide which sections are relevant, and then pull only those chunks — keeping token usage proportional to the task.\n\n```\n# Print the full heading tree\nresult.hierarchy.to_outline()\n\n# Walk all top-level sections and see how much content each contains\nfor node in result.hierarchy.level(1):\n    print(node.text, \"→\", len(result.chunks_under(node)), \"chunks\")\n```\n\n`.level(n)`\n\nreturns all headings at depth `n`\n\n. Pass a `parent`\n\nto scope it to a\nspecific subtree — the typical pattern for an agent navigating a long document:\n\n```\n# All top-level headings\nl1 = result.hierarchy.level(1)\n\n# Pick one, then list its subsections\nsection = result.find_heading(\"Financial Statements\")[0]\nfor node in result.hierarchy.level(2, parent=section):\n    print(node.text, f\"(p.{node.page_number})\")\n\n# Drill one level deeper\nsubsection = result.hierarchy.level(2, parent=section)[0]\nfor node in result.hierarchy.level(3, parent=subsection):\n    print(node.text)\n```\n\n`find_heading`\n\nmatches any node whose text contains the search term (case-insensitive).\nAll retrieval methods recurse into subsections by default.\n\n```\nnode = result.find_heading(\"Financial Instruments\")[0]\n\nchunks = result.chunks_under(node)              # text chunks, ready for embedding or prompting\nchunks = result.chunks_under(node, recursive=False)  # direct heading only, no subsections\ntables = result.tables_under(node)              # structured tables in this section\ncharts = result.charts_under(node)              # charts (with extracted data points) in this section\nblocks = result.blocks_under(node)              # raw paragraph/heading blocks\nresult.chunks_by_page(14)        # by page number\nresult.chunks_by_page(\"F-3\")     # by printed page label\nresult.blocks_by_page(14)\nresult.tables_by_page(14)\nresult.charts_by_page(14)\n```\n\nA 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:\n\n``` python\nfrom pathlib import Path\nimport docslicer\n\ncache = Path(\"annual_report.json\")\n\nif cache.exists():\n    result = docslicer.ParseResult.load(cache)\nelse:\n    result = docslicer.parse_document(\"annual_report.pdf\")\n    result.save(cache)\n```\n\nA reloaded result supports the full API — `hierarchy`\n\n, `find_heading`\n\n,\n`chunks_under`\n\n, `tables`\n\n— so a long-running agent session or document server can\nkeep documents open across requests without re-parsing.\n\n`save()`\n\ndecides what to write from the path you give it.\n\n```\n# Save the whole result and reload it later — keeps the heading hierarchy\nresult.save(\"result.json\")                     # same output as result.to_json()\nresult = docslicer.ParseResult.load(\"result.json\")\n\n# A single collection, in the format you name\nresult.save(\"chunks.csv\")\nresult.save(\"charts.jsonl\")       # stems: chunks | blocks | tables | charts | metadata\nresult.export_chunks_jsonl(\"chunks.jsonl\")\n\n# One file per collection\nresult.save(\"output/\")\n# → output/chunks.parquet, blocks.parquet, tables.parquet, metadata.json\n#   (+ charts.parquet when the document has charts)\n#   Falls back to .csv unless the [parquet] extra is installed.\n\n# Render as Markdown or plain text\nmd = result.export_to_markdown(include_tables=True)\ntxt = result.export_to_text()\n\n# DataFrames\ndf = result.chunks_df()\n```\n\nOnly `result.json`\n\nround-trips — the collection and directory forms write flat rows\nwithout the heading hierarchy, so `ParseResult.load()`\n\ncan't read them back.\n\n```\nresult = docslicer.parse_document(\"report.pdf\", debug=True)\n\n# result.pipeline_steps is an ordered dict of step name → DataFrame\nfor name, df in result.pipeline_steps.items():\n    print(name, df.shape)\n    df.to_csv(f\"debug/{name}.csv\", index=False)\n\n# PDF steps:        words → shapes → cells → lines → table_cells → blocks → chunks\n# DOCX/PPTX steps:  runs → chart_points → paragraphs → lines → table_cells → blocks → chunks\n```\n\n`parse_document`\n\nautomatically detects scanned pages and falls back to OCR when the\n`[ocr]`\n\nextra is installed. No configuration needed — `result.metadata.has_ocr`\n\ntells you whether OCR was used.\n\n```\npip install 'docslicer[ocr]'\n# tesserocr binds libtesseract directly, so install the Tesseract dev libraries first:\n# Linux:  apt install tesseract-ocr libtesseract-dev libleptonica-dev pkg-config\n# macOS:  brew install tesseract leptonica\n```\n\nIf you know the format upfront and want explicit failure on unexpected input, use the\nformat-specific variants. They accept the same arguments as `parse_document`\n\n:\n\n```\ndocslicer.parse_pdf(\"report.pdf\")\ndocslicer.parse_docx(\"contract.docx\")\ndocslicer.parse_pptx(\"deck.pptx\")\ndocslicer.parse_html(\"filing.html\")\n```\n\nDocSlicer is **dual-licensed**:\n\n— free to use, modify, and distribute, provided you comply with the AGPL's terms, including making the complete source of any application that uses DocSlicer available to its users (including over a network).[AGPL-3.0](/DocSlicer/DocSlicer/blob/main/LICENSE)— for embedding DocSlicer in a closed-source or proprietary product, or offering it as part of a hosted/SaaS service without releasing your source.[Commercial license](/DocSlicer/DocSlicer/blob/main/LICENSE-COMMERCIAL.md)\n\nSee [LICENSE-COMMERCIAL.md](/DocSlicer/DocSlicer/blob/main/LICENSE-COMMERCIAL.md) for details, or reach out about a commercial license.", "url": "https://wpnews.pro/news/show-hn-docslicer-structure-aware-pdf-docx-pptx-parser-31-pages-sec-on-cpu", "canonical_source": "https://github.com/DocSlicer/DocSlicer", "published_at": "2026-07-28 16:18:19+00:00", "updated_at": "2026-07-28 16:22:32.438363+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "natural-language-processing", "ai-infrastructure"], "entities": ["DocSlicer", "BizDocBench", "Playwright", "Tesseract"], "alternates": {"html": "https://wpnews.pro/news/show-hn-docslicer-structure-aware-pdf-docx-pptx-parser-31-pages-sec-on-cpu", "markdown": "https://wpnews.pro/news/show-hn-docslicer-structure-aware-pdf-docx-pptx-parser-31-pages-sec-on-cpu.md", "text": "https://wpnews.pro/news/show-hn-docslicer-structure-aware-pdf-docx-pptx-parser-31-pages-sec-on-cpu.txt", "jsonld": "https://wpnews.pro/news/show-hn-docslicer-structure-aware-pdf-docx-pptx-parser-31-pages-sec-on-cpu.jsonld"}}