Parsy — Document Intelligence Engine

Parsy is a high-performance, privacy-preserving document intelligence engine.
Parse PDFs, DOCX, HTML, TXT, CSV, JSON, and XML into clean Markdown, JSON, HTML, or CSV — fully locally with no data leaving your machine.

---

✨ Features

• ⚡ Blazing fast — Zero-copy PyMuPDF extraction, parallel page processing
• 🔒 Private — Runs 100% locally, no internet required after install
• 📄 Multi-format — PDF, DOCX, TXT, HTML, CSV, JSON, XML, XLSX
• 🧠 ML-powered (optional) — Layout regions, semantic heading clusters, table structure
• 🌊 SSE streaming — Real-time progressive output for large documents
• 🖥️ CLI + Python API + REST API — Use however you want

---

📦 Installation

pip install parsy-doc

With optional ML structural analysis:

pip install parsy-doc[ml]

With OCR support (requires Tesseract installed on your system):

pip install parsy-doc[ocr]

Full installation:

pip install parsy-doc[all]

---

🚀 Quick Start

Python API

import parsy

# Parse a PDF to Markdown
result = parsy.parse("contract.pdf")
print(result.markdown)

# Parse to JSON
result = parsy.parse("invoice.pdf", format="json")
print(result.json)

# Access tables directly
for table in result.tables:
    print(table)

# View parsing metrics
print(result.metrics)
# → {'wordCount': 4231, 'pageCount': 18, 'charCount': 24100, ...}

Async API (FastAPI, asyncio)

import parsy
import asyncio

async def main():
    result = await parsy.parse_async("report.pdf", format="markdown")
    print(result.markdown)

asyncio.run(main())

---

💻 Command-Line Interface

After installing, a parsy command is available globally:

# Parse a PDF and print to terminal
parsy parse report.pdf

# Save to file in JSON format
parsy parse invoice.pdf --format json --output invoice.json

# Parse all PDFs in a folder (batch mode)
parsy parse docs/*.pdf --format markdown --output ./results/

# Enable ML analysis
parsy parse research_paper.pdf --ml

# Launch the local REST API server + web UI
parsy serve

# Custom host and port
parsy serve --host 0.0.0.0 --port 8080

# Check version
parsy --version

---

🌐 REST API Server

Start the streaming REST API server:

parsy serve
# → http://localhost:8000

Then use the web UI at http://localhost:8000 or POST to the API:

curl -X POST http://localhost:8000/parse \
  -F "file=@report.pdf" \
  -F "format=markdown"

The API uses Server-Sent Events (SSE) for real-time streaming progress.

---

⚙️ Options

Option	Values	Default	Description
format	markdown, json, html, csv, plaintext	markdown	Output format
tables	bool	True	Extract tables
clean	bool	True	Whitespace cleanup
use_ml	bool	False	Enable ML structural analysis

---

🔬 Supported File Types

Format	Extension	Notes
PDF (digital)	.pdf	Full text + table extraction
PDF (scanned)	.pdf	OCR via Tesseract (pip install parsy-doc[ocr])
Word	.docx	Headings, paragraphs, tables
HTML	.html, .htm	Semantic extraction
Plain text	.txt, .rtf	Encoding auto-detected
Markdown	.md	Passthrough + re-format
Spreadsheet	.xlsx, .csv	Table-centric output
Data	.json, .xml	Structured extraction

---

🏛️ Architecture

parsy parse() / parse_async()
        │
        ▼
  DocumentRouter          ← heuristic inspection
        │
  ┌─────┴──────────┐
  │                │
Fast Parser     Vision OCR     ← PyMuPDF / Tesseract
  │
  ▼
Normalizer                     ← Markdown, JSON, HTML, CSV
  │
  ▼
ParseResult

---

📄 License

MIT — see LICENSE