https://github.com/rithulkamesh/docproc
Document Intelligence Platform — Extract, refine, and query documents with vision LLMs and config-driven RAG.
https://github.com/rithulkamesh/docproc
content-extraction data-extraction document-analysis document-parsing equation-detection layout-analysis machine-learning mathematical-symbols ocr pdf-processing pdf-text-extraction python region-detection text-classification text-extraction
Last synced: about 2 months ago
JSON representation
Document Intelligence Platform — Extract, refine, and query documents with vision LLMs and config-driven RAG.
- Host: GitHub
- URL: https://github.com/rithulkamesh/docproc
- Owner: rithulkamesh
- License: mit
- Created: 2025-01-30T09:08:57.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-30T03:54:11.000Z (about 2 months ago)
- Last Synced: 2026-03-30T06:04:47.573Z (about 2 months ago)
- Topics: content-extraction, data-extraction, document-analysis, document-parsing, equation-detection, layout-analysis, machine-learning, mathematical-symbols, ocr, pdf-processing, pdf-text-extraction, python, region-detection, text-classification, text-extraction
- Language: Python
- Homepage:
- Size: 1.09 MB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# docproc
docproc
Turn messy documents into clean markdown for AI pipelines.
Document → Markdown → AI
---
docproc is a document-to-markdown extraction engine. It converts PDFs, DOCX, PPTX, and XLSX into clean structured markdown while preserving equations, figures, and embedded images. It is designed to power LLM pipelines, RAG systems, and document processing workflows.
## Features
- **PDF → Markdown** — Native text extraction plus vision-based handling of embedded images
- **DOCX → Markdown** — Full document structure and formatting
- **PPTX → Markdown** — Slides to structured content
- **XLSX → Markdown** — Spreadsheets to readable tables
- **Equation preservation** — LaTeX and math kept intact (with optional LLM refinement)
- **Figure extraction** — Every image, diagram, and label described by a vision model
- **Clean structured output** — Ready for LLMs, RAG, and downstream pipelines
## Example
**Before:** A PDF with mixed text, equations, and diagrams.
**After:** A single `.md` file with extracted text, LaTeX math blocks, and every figure explained by the vision model—ready to embed, chunk, or feed into an LLM.
```bash
docproc --file paper.pdf -o paper.md
```
## Installation
```bash
pip install git+https://github.com/rithulkamesh/docproc.git
```
Or with [uv](https://github.com/astral-sh/uv):
```bash
uv tool install git+https://github.com/rithulkamesh/docproc.git
```
From source:
```bash
git clone https://github.com/rithulkamesh/docproc.git && cd docproc
uv sync --python 3.12
```
## Usage
One-time config (generates `docproc.yaml` from your `.env`):
```bash
docproc init-config --env .env
```
Extract a document to markdown:
```bash
docproc --file input.pdf -o output.md
```
Optional: `--config path`, `-v` for verbose output. Shell completions: `docproc completions bash` or `docproc completions zsh`.
### Python library
Install the package, then use the `Docproc` facade with instance-scoped config (PEP 561 typing via `py.typed`):
```python
from docproc import Docproc
Docproc.from_config_path("docproc.yaml").extract_to_file("input.pdf", "output.md")
# Or minimal OpenAI in code (uses OPENAI_API_KEY):
Docproc.with_openai().extract_to_file("input.pdf", "output.md")
# String output for RAG / LLM pipelines:
md = Docproc.from_env().extract("paper.pdf")
```
Lower-level API: `extract_document_to_text`, `parse_config`, `docprocConfig`. Runnable samples: [examples/](examples/).
## Why docproc?
Naive PDF parsers often drop equations, misread layouts, and leave images as black boxes. docproc uses native extractors where possible (PyMuPDF, python-docx, etc.) and runs a vision model on every embedded image—so diagrams, charts, and equations become text or LaTeX that your AI stack can actually use. Optional LLM refinement cleans markdown and normalizes math. The result is document content that fits cleanly into RAG pipelines and LLM context windows instead of noisy, incomplete text.
## Architecture
docproc ships as a **CLI** and an **importable Python library**; there is no bundled server or database for extraction. The pipeline is:
1. **Load** — Read the file (PDF/DOCX/PPTX/XLSX) and extract full text from the native layer.
2. **Vision** — For PDFs, run a vision model on every embedded image; get descriptions, LaTeX, or structured captions.
3. **Refine** (optional) — LLM pass to tidy markdown, normalize LaTeX, and strip boilerplate.
4. **Sanitize** — Dedupe and clean; write a single `.md` file.
Configuration lives in `docproc.yaml` (or generated via `docproc init-config --env .env`). AI providers: OpenAI, Azure, Anthropic, Ollama, LiteLLM. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for details.
## Demo (docproc // edu)
The [demo/](demo/) is a full study workspace: upload docs, chat over them, generate notes and flashcards, create and take assessments. It’s a separate Go + React app that calls this CLI when a document is uploaded. See [demo/README.md](demo/README.md).
## Docs
| Doc | Description |
|-----|-------------|
| [docs/README.md](docs/README.md) | Index |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Config schema, providers, ingest, RAG |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Pipeline, CLI, Python library |
| [docs/AZURE_SETUP.md](docs/AZURE_SETUP.md) | Azure OpenAI and Vision setup |
| [docs/ASSESSMENTS_AI.md](docs/ASSESSMENTS_AI.md) | Assessments and grading in the demo |
**Environment:** `DOCPROC_CONFIG` for config path (default: `docproc.yaml`). Provider keys: `OPENAI_API_KEY`, `AZURE_OPENAI_*`, `ANTHROPIC_API_KEY`, etc. See [.env.example](.env.example).
## Contributing
Pull requests welcome. Run the tests before sending.
## License
MIT. See [LICENSE.md](LICENSE.md).