ParseCraft
Document intelligence: align existing converters, parsers, and OCR/VLM models behind one workflow and one typed output format
ParseCraft is a thin aggregation and alignment layer for document intelligence. Capable converters, parsers, and OCR/VLM models already exist, but each emits a different shape — and many ship demo-grade wrapper code pinned to an outdated Python version and dependency set. ParseCraft keeps every tool isolated behind a backend, translates its output into a single typed intermediate representation (IR), and projects that IR to deterministic Markdown. You get one workflow and one output format, while every heavy runtime stays optional.
The IR is the source of truth. Backends read a document and produce typed pages and chunks; every rendering — Markdown today, HTML/JSON/consumer trees later — is a projection of that same IR, never parsed back into state.
Requirements
- Python 3.13 (GIL only — the free-threaded
3.13tbuild is not supported) - Python 3.14 or newer (free-threaded
3.14tbuilds are suspended, not tested, until the heavy runtimes we use ship free-threaded macOS/Windows wheels — see the ADR-0001 amendment) - uv (recommended) or pip to install the package
Supported inputs
Plain text, Markdown, and HTML convert on the base install. PDF, images, and the
office family — DOCX, PPTX, XLSX, ODT, RTF, EPUB — route through backends that
must be present, and a .docx needs parsecraft[docling] (the layout-, table-,
and reading-order-aware Word path), parsecraft[pymupdf] (AGPL), or a pandoc
binary on the host. No base install converts an office document.
Per-backend formats, licences, and platform limits: the backend catalog.
OCR/VLM models
Every model runs behind its backend inside the ocr, surya, or mineru
extra — no model weights load at import time. Weights download into the managed
asset cache on first use (parsecraft models list shows them). Surya weights
are OpenRAIL-M (restricted use: research, personal, and capped startups) and
need --accept-license on install — check before commercial deployment.
| Backend | Model | Weights licence | Extra | VRAM |
|---|---|---|---|---|
ocr-ovis |
OvisOCR2 (ATH-MaaS/OvisOCR2) |
Apache-2.0 | ocr |
1.0 GB |
ocr-tele |
TeleOCR (StarDoc-AI/TeleOCR, zh + en) |
Apache-2.0 | ocr |
1.2 GB |
ocr-unlimited |
Unlimited-OCR (baidu/Unlimited-OCR) |
MIT | ocr |
3.0 GB |
ocr-qianfan |
Qianfan-OCR (baidu/Qianfan-OCR) |
Apache-2.0 | ocr |
4.0 GB |
ocr-surya |
Surya-OCR 2.5 (datalab-to/surya-ocr-2.5) |
OpenRAIL-M (weights; code Apache-2.0) | surya |
1.0 GB |
ocr-tesseract |
Tesseract engine (OS binary, eng + deu) |
Apache-2.0 (tessdata) | base install | CPU only |
mineru |
MinerU2.5-Pro (opendatalab/MinerU2.5-Pro-2605-1.2B) |
Apache-2.0 | mineru |
4.0 GB (GPU optional) |
Install and Quick Start
Install the released package and list the available backends:
uv add parsecraft # or: pip install parsecraft
uv run parsecraft backends
First release: 2026.9.2. The current version is on
PyPI.
Building from a source checkout, running the test suite, and working on the codebase are covered in the development setup.
CLI
| Command | Description |
|---|---|
parsecraft backends |
List registered backends; load warnings go to stderr |
parsecraft backends --json |
Emit backend descriptors as JSON |
parsecraft config check |
Validate the effective configuration |
parsecraft config show |
Show the resolved configuration with provenance |
parsecraft --version (-v) |
Print the package version |
uv run parsecraft backends
# No backends registered. (no third-party backend installed yet)
See the CLI reference for every command, flag, exit code, and environment variable.
Configuration
Settings live in a layered TOML config: ./parsecraft.toml (project) over
~/.config/parsecraft/config.toml (global), with PARSECRAFT_CONFIG_*
environment variables and CLI flags on top. Secrets are references, never
literals — write api_key = "${MY_KEY}".
[routing]
preference = "quality" # speed | balanced | quality
preferred_backend = "docling" # preference, not a permission
max_passes = 2 # fallback-pass budget
[routing.backend_options.docling]
do_ocr = false # forwarded verbatim to the backend
parsecraft config check validates the effective configuration (unknown
backend or engine names fail loudly); parsecraft config show prints every
effective key with the file or layer it came from. See the
configuration reference
for every key.
How it works
source document → backend (analyze / convert) → typed IR → Markdown projection
- Backends are the extension point. A third party ships a
BackendFactoryunder theparsecraft.backendsentry-point group; the core package does not change to add one. - One typed IR.
DocumentResult,PageResult, andStructuredChunkmove between layers, and Markdown is a deterministic, dependency-free projection. - Heavy runtimes stay optional. Model weights, CUDA, and OCR/VLM stacks load only inside a backend factory, so importing ParseCraft stays offline-clean.
- Failures are typed. A failed pass records a
PassFailurerather than silently dropping a page.
Continue with the architecture overview, the IR model, the backend catalog, and the backend authoring guide.
Documentation
- Installation
- Quickstart
- Architecture
- Backends
- Write a backend
- Backend catalog
- CLI reference
- API reference
- Development setup
License
MIT — see LICENSE for details.
Metadata
Release files for parsecraft 2026.11.7
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 |
|---|---|---|---|---|
| parsecraft-2026.11.7.tar.gz | 973.3 kB | With provenance | Details for parsecraft-2026.11.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| parsecraft-2026.11.7-py3-none-any.whl | Python 3 | none | any | Details for parsecraft-2026.11.7-py3-none-any.whl |
Total release size: 1.4 MB
Release files / parsecraft-2026.11.7.tar.gz
| Download URL | parsecraft-2026.11.7.tar.gz |
|---|---|
| Size | 973.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee056e75967d16f57ff08d6eefcfbaf6f48381d3111efd7d49eafc211f08d0b8
|
|
BLAKE2b-256 checksum How to use checksums |
67cf0e2075a2500c696e7d10ebf40923445452c181d53e198d67ac2381556231
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logRelease files / parsecraft-2026.11.7-py3-none-any.whl
| Download URL | parsecraft-2026.11.7-py3-none-any.whl |
|---|---|
| Size | 456.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1dabfd024caffe69077455e6906f300c456516e48bf7ae7cd4fc9e438adf4f93
|
|
BLAKE2b-256 checksum How to use checksums |
f14ed494d136e621aad49cdd694dcce6cd0401a8518234b48c7797db5d48ac1d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logSecurity for parsecraft 2026.11.7
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for parsecraft-2026.11.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.
Transparency logA 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.