pdf-section-tree 0.1.0

Fast, lightweight PDF structure parser to hierarchical JSON & Markdown section trees.

pdf-section-tree 🌳

Fast, lightweight Python library that turns a PDF into a hierarchical Markdown or JSON section tree, using typographic heuristics instead of heavy ML models.

Most PDF tools fall into two camps: low-level extractors (pypdf, pdfplumber, PyMuPDF) that hand you raw characters and (x, y) coordinates with no document structure, or full layout-analysis frameworks (unstructured, layoutparser, marker) that rebuild structure but drag in gigabytes of PyTorch/OCR dependencies and a GPU. pdf-section-tree sits in between: it reconstructs the heading hierarchy from font size, weight and layout signals alone, in milliseconds, with a single lightweight dependency.

Installation

pip install pdf-section-tree

Quickstart

from pdf_section_tree import parse_pdf

# Parse a PDF into a hierarchical tree
doc = parse_pdf("sample.pdf")

# Export to Markdown
print(doc.to_markdown())

# Export to a nested dict (e.g. for RAG chunking)
data = doc.to_dict()

What it does

• Heading hierarchy from typography — font size and boldness are used to infer H1..H6 nesting, with heuristics to merge split titles ("1" + "Introduction" → "1 Introduction") and to avoid promoting numeric table cells or one-off oversized paragraphs to fake headings.
• Boilerplate removal — running headers/footers and page numbers, detected by page-margin position and repetition across pages, are stripped from the output.
• Figure & diagram detection — embedded images and dense native vector diagrams (charts, heatmaps) large enough to be real figures are replaced with a *[Figure]* marker; their caption is kept, the text baked into them is dropped, and decorative page-margin images (logos, banners) are silently ignored.
• Out-of-context text filtering — text much smaller than the document's body size (typically labels or captions rendered as part of an inserted image/screenshot) is dropped so only the main content remains.
• Ligature repair — broken ligature glyphs from subsetted fonts (Dol� → Dolfi) are decoded where the font data allows it.

Known limitations

• Tables are extracted as flattened text, not reconstructed into rows/columns.
• Sparse vector diagrams (few drawn elements) may fall under the density threshold and not be recognized as a figure.
• Heuristics are tuned on typical reports/books/papers; unusual layouts (dense multi-column magazines, forms) aren't specifically optimized for.

License

MIT