PDF Outline Architect

Multilingual, offline-capable PDF outline extraction that detects headings and produces clean, schema-valid JSON. Production-ready, Dockerized, and easy to run locally on Windows, macOS, and Linux.

🎯 Overview

This tool processes PDF files to automatically identify headings and generate a hierarchical outline (H1/H2/H3) as JSON. It uses PyMuPDF for robust text extraction and spaCy for light-weight linguistic cues.

Features

• Multilingual support: English, Japanese, Chinese, Korean, Arabic
• Fully offline: ships with a local spaCy model in models/
• Dockerized: consistent, reproducible runs
• Fast and resilient: handles corrupted/empty PDFs gracefully
• Schema-compliant output: 0-based page indexing

🏗️ Architecture

• pdf_processor.py: Extracts text blocks and formatting with PyMuPDF
• heading_detector.py: Scores candidate headings via font, pattern, and simple NLP signals
• outline_builder.py: Builds a 10-item outline with H1/H2/H3 levels and a best-effort title
• utils/language_utils.py: Language detection and normalization helpers

� Install & Run (Windows-friendly)

You can run it with Python directly or via Docker. The project expects PDFs in input/ and writes JSON to output/.

Option A — Python (recommended for development)

1. Create folders:

mkdir input
mkdir output

2. Create a virtual environment and install deps:

py -3 -m venv .venv
.venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

3. Run the processor:

python process_pdfs.py

Option B — Docker (works with paths that contain spaces)

1. Build the image:

docker build -t pdf-outline-architect:latest .

2. Create folders and run:

mkdir input
mkdir output
docker run --rm ^
   -v "%cd%\input:/app/input" ^
   -v "%cd%\output:/app/output" ^
   pdf-outline-architect:latest

📤 Output format (example)

{
   "title": "Document Title",
   "outline": [
      { "level": "H1", "text": "Chapter 1: Introduction", "page": 0 },
      { "level": "H2", "text": "1.1 Overview", "page": 1 }
   ]
}

�️ Project structure

.
├── config/
├── input/
├── models/
├── output/
├── utils/
├── Dockerfile
├── heading_detector.py
├── outline_builder.py
├── output_schema.json
├── pdf_processor.py
├── process_pdfs.py
├── README.md
└── requirements.txt

� Notes & limits

• Best on single-column documents; multi-column PDFs may reduce accuracy
• English performs best; other languages supported with heuristics
• Relies on font metadata to distinguish headings from body text

🤝 Contributing

Issues and PRs are welcome. Please include before/after JSON samples when reporting detection issues.

� License

This project uses open‑source libraries under their respective licenses. Choose a license (e.g., MIT/Apache-2.0) before publishing on GitHub.