Skip to main content

ParseCraft

Document intelligence: align existing converters, parsers, and OCR/VLM models behind one workflow and one typed output format

Python 3.13 | 3.14+ License CI PyPI

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.13t build is not supported)
  • Python 3.14 or newer (free-threaded 3.14t builds 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 BackendFactory under the parsecraft.backends entry-point group; the core package does not change to add one.
  • One typed IR. DocumentResult, PageResult, and StructuredChunk move 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 PassFailure rather than silently dropping a page.

Continue with the architecture overview, the IR model, the backend catalog, and the backend authoring guide.

Documentation

License

MIT — see LICENSE for details.

Metadata

Release files for parsecraft 2026.11.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for parsecraft 2026.11.5
File Size Uploaded Provenance Actions
parsecraft-2026.11.5.tar.gz 965.5 kB With provenance Details for parsecraft-2026.11.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for parsecraft 2026.11.5
File Interpreter ABI Platform Actions
parsecraft-2026.11.5-py3-none-any.whl Python 3 none any Details for parsecraft-2026.11.5-py3-none-any.whl

Total release size: 1.4 MB

Release files / parsecraft-2026.11.5.tar.gz

Download URL parsecraft-2026.11.5.tar.gz
Size 965.5 kB
Tags Source
SHA-256 checksum
How to use checksums
fa2637aabbb23bcf9ae65111fd425b18c5a68947d4a70886979ceb3e551b18e8
BLAKE2b-256 checksum
How to use checksums
2e8ee5cb3dcdf768f89a6e73b8ffd56c301f76ca241c708f53d4303a627c9bf4
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 4, 2026.

Transparency log

Release files / parsecraft-2026.11.5-py3-none-any.whl

Download URL parsecraft-2026.11.5-py3-none-any.whl
Size 453.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ac836d3ebea685113cef1ce96553becc32ad00898ac902d9bf31705034411349
BLAKE2b-256 checksum
How to use checksums
8939d95435862359564d69c5be6eb7dbb2d0a120ff787a8313293d1ae6ca073b
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 4, 2026.

Transparency log

Security for parsecraft 2026.11.5

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.

Select from 2 files

Attestation for parsecraft-2026.11.5.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 4, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page