Metadata-Version: 2.4
Name: pdf-section-tree
Version: 0.1.0
Summary: Fast, lightweight PDF structure parser to hierarchical JSON & Markdown section trees.
Keywords: pdf,markdown,parser,llm,rag,structure
Author: anthopy
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Text Processing :: Markup
License-File: LICENSE
Requires-Dist: PyMuPDF>=1.23.0
Project-URL: Homepage, https://github.com/anthopy/pdf-section-tree

# pdf-section-tree 🌳

[![PyPI version](https://img.shields.io/pypi/v/pdf-section-tree.svg)](https://pypi.org/project/pdf-section-tree/)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://pypi.org/project/pdf-section-tree/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install pdf-section-tree
```

## Quickstart

```python
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

