PDF Vision Processor
A FastAPI service that converts PDFs into page images, sends them to an OpenAI-compatible Vision LLM, and exposes the parsed layout/markdown through both REST APIs and a built-in UI. The project now ships as an installable package named pdf-vision-processor so it can be deployed with a single CLI command.
Installation (PyPI)
python -m venv venv && source venv/bin/activate
pip install pdf-vision-processor
pdf-vision-processor --host 0.0.0.0 --port 8080
The CLI loads a .env file from your current working directory (if present), applies overrides from environment variables prefixed with PDF_VISION_PROCESSOR_, and falls back to sensible defaults. Static assets and Jinja templates are bundled inside the wheel.
Note:
PyMuPDF(fitz) is expected to be available in the runtime environment (e.g., preinstalled in the platform image). The PyPI package does not vendor it; installpymupdfmanually if your deployment does not already include it.
Configuration
| Setting | CLI Flag | Environment Variable | Default |
|---|---|---|---|
| Host interface | --host |
PDF_VISION_PROCESSOR_HOST |
127.0.0.1 |
| Port | --port |
PDF_VISION_PROCESSOR_PORT |
8000 |
| Reload | --reload/--no-reload |
PDF_VISION_PROCESSOR_RELOAD |
False |
| Log level | --log-level |
PDF_VISION_PROCESSOR_LOG_LEVEL |
info |
| Data directory | --data-dir |
PDF_VISION_PROCESSOR_DATA_DIR |
~/.pdf-vision-processor/data |
| Logs directory | --logs-dir |
PDF_VISION_PROCESSOR_LOG_DIR |
~/.pdf-vision-processor/logs |
| Database URL | --database-url |
PDF_VISION_PROCESSOR_DATABASE_URL |
sqlite:///<home>/db.sqlite3 |
Additional LLM specific variables (e.g., LLM_API_KEY, LLM_BASE_URL, LLM_MODEL, LLM_MAX_TOKENS) continue to be read from the environment; see docs/env_config.md for the full catalog. When no overrides are provided, uploads, derived images, and logs are stored under ~/.pdf-vision-processor/ so the package works even when installed system-wide.
Optional project-level configuration can also be provided through a config.toml file with sections named [server], [paths], and [database]. The CLI resolves settings in the following order: CLI flags → environment variables → config.toml → defaults.
Running from Source
Developers contributing to the repository can still use run.py, which now delegates directly to the packaged CLI to ensure consistent behavior:
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python run.py --host 127.0.0.1 --port 8000 --reload
Ensure your virtual environment already has pymupdf installed (or install it manually) before running the processor locally.
Assets, templates, and compatibility shims remain under the legacy app/ namespace for existing imports, but all active code now lives inside the pdf_vision_processor/ package (matching what ships to PyPI).
Usage
- Upload – Visit
/and upload a PDF. - Process – Click Process next to the document to kick off background ingestion.
- Inspect – Open the document view to see rendered pages, bounding box overlays, and extracted Markdown side-by-side.
API Examples
# Upload a PDF
curl -X POST -F "file=@/path/to/document.pdf" http://localhost:8000/upload
# Start processing (replace {id} with the returned document id)
curl -X POST http://localhost:8000/process/{id}
# Retrieve page analysis
curl http://localhost:8000/pages/{page_id}/analysis
Packaging & Release Workflow
Use the helper script to build and validate distribution artifacts:
python scripts/build_dist.py --bump patch
# optional: publish to TestPyPI / PyPI with twine upload dist/*
The script bumps the version (optional), cleans previous artifacts, runs setup.py sdist bdist_wheel, and executes twine check so we catch metadata issues before publication. See docs/plans/publishing_checklist.md for the full release checklist.
Metadata
Release files for pdf-vision-processor 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pdf_vision_processor-0.1.1.tar.gz | 31.4 kB | Without provenance | Details for pdf_vision_processor-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pdf_vision_processor-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for pdf_vision_processor-0.1.1-py3-none-any.whl |
Total release size: 65.4 kB
Release files / pdf_vision_processor-0.1.1.tar.gz
| Download URL | pdf_vision_processor-0.1.1.tar.gz |
|---|---|
| Size | 31.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
be307c79bcd53e234e2491527354110534606e7cfbb6b977f3536511c8730fe9
|
|
BLAKE2b-256 checksum How to use checksums |
a395aabe4c301426e283920710e4ae8a13d47ffce25c30e5723e4b197def8de4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Release files / pdf_vision_processor-0.1.1-py3-none-any.whl
| Download URL | pdf_vision_processor-0.1.1-py3-none-any.whl |
|---|---|
| Size | 34.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ac79da4d585a40f8b5120ad94f499a56e431cbbf26c3a159f35576e613d72cd7
|
|
BLAKE2b-256 checksum How to use checksums |
8dce39c7099e2252a8794e0109f7a3b94a005cda55d9f506cf99d576cd94e7ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.12
|
Security for pdf-vision-processor 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.