Installation
Requirements¶
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.13 or 3.14+ | requires-python = ">=3.13" — see Supported runtimes |
| uv | current | Dependency and environment manager |
| mise | current | Runs the project tasks and tool versions |
Supported runtimes¶
| Runtime | Support |
|---|---|
| CPython 3.13 | GIL-enabled build only; the free-threaded 3.13t build is not supported |
| CPython 3.14 | Supported, including the free-threaded 3.14t build (Ubuntu, macOS, Windows) |
| CPython 3.15-dev | Best-effort |
Core installs and runs on all of the above. Individual extras can be narrower:
some publish wheels for one interpreter family only (a Rust abi3 extension does
not load on a free-threaded build; onnxruntime has no free-threaded macOS or
Windows wheel at all). See Interpreter and platform availability
before choosing a free-threaded host for a workflow that needs a specific engine.
GPU torch¶
OCR backends need torch, and the PyPI Windows/Linux wheels are CPU builds
— so an OCR backend on a CUDA host would silently run on the CPU. When torch
or torchvision is resolved from this project (a checkout, or a downstream
project that copies the index block from pyproject.toml), uv therefore pulls
them from the PyTorch cu128 index automatically:
| Platform | torch source |
Device |
|---|---|---|
| Windows, Linux | download.pytorch.org/whl/cu128 |
CUDA (cu128; older GPUs may need a different CUDA — override the index in your own pyproject.toml) |
| macOS | PyPI (index excluded by marker) | CPU + MPS |
On a GPU host the CUDA driver still has to match the wheel — the index selects the CUDA build, not the driver.
The project's torch version ranges are unchanged by this — the index only
provides the CUDA variant. uv tool install/uvx installs of the CLI carry no
torch at all (torch arrives with the OCR extras), so plain CLI installs are
unaffected.
From PyPI¶
Add the dependency with uv:
uv add parsecraft
uv run parsecraft backends
Or with pip:
pip install parsecraft
parsecraft backends
Current version on PyPI.
Extras¶
The base install is self-sufficient for the routing pipeline: the System One
judge client, the OCR-need classifier, the fast liteparse parser,
openpyxl for spreadsheets, and the pypandoc wrapper all ship in the core.
Extras add the heavyweight or licence-isolated engines:
parsecraft[docling]— layout-aware parsing.parsecraft[pymupdf]— PyMuPDF extraction for PDF and office documents (AGPL-3.0-or-commercial).parsecraft[mineru]— the native MinerU2.5 VLM backend (Apache-2.0 checkpoint, nominerupackage).parsecraft[pdf-full]— the full PDF stack in one name: PyMuPDF and the native VLM backend.parsecraft[ocr]— the GPU OCR/VLM backends (torch, transformers).parsecraft[vllm]— the vLLM accelerator (Linux/WSL2 only).parsecraft[web]— thetrafilaturaHTML backend.
pandoc conversions need no extra but do need the pandoc binary on the
host (install it with your package manager); the backend is eligible only
where the engine exists. Judge credentials come from the environment
(TYPESAFE_API_KEY, OPENCODE_API_KEY) — see
Backends for the per-backend extras table and
Steer the auto-backend selector for the
flags themselves.
No base install converts an office document. Word (.docx) has three separate
routes: parsecraft[docling] — headings, tables, and reading order,
conversion-verified 2026-10-17 — parsecraft[pymupdf] (AGPL), or the
pandoc binary above. The same split applies to .pptx; .xlsx needs no
extra (openpyxl is core). Legacy Word 97-2003 binary (.doc) has one route:
parsecraft[docling] reads it natively in Rust, with no LibreOffice and no
model download.
Conditional-licence extras¶
One extra carries licence terms you are consenting to by installing it — it is neither a core nor a dev dependency and is opt-in:
parsecraft[pymupdf]— PyMuPDF, AGPL-3.0-or-commercial.
Read the full statement on the Backends page before installing.
The mineru extra was in this category until 2026-10-26: parsecraft now runs
the MinerU2.5 checkpoint itself (Apache-2.0 weights, MIT code), and the
mineru package with its conditional code licence — and its
onnxruntime-carrying GIL-builds-only install constraint — is no longer a
dependency. See ADR-0007's amendment.
Upgrading¶
Releases are CalVer (YYYY.M.N); pin an exact version when you depend on
anything beyond the CLI. The table lists the changes that need work on your
side — if you do not touch the named surface, a plain upgrade is safe.
| If you use | Changed in | What to do |
|---|---|---|
"docling" in installed_extras |
2026.10.15 only | Pin parsecraft==2026.10.14, or upgrade to >=2026.10.16. That single release installed docling-rs while probing for the old docling distribution, so parsecraft[docling] reported the extra as absent and the docling backend was ineligible for every source. In auto mode that is silent — the candidate is dropped before planning and no surface names it — while a --backend docling pin fails loudly with pinned backend 'docling' is not eligible for this source. |
parsecraft.backends.docling.libreoffice (LIBREOFFICE_ENV, find_libreoffice_cmd, resolve_libreoffice_cmd, configure_libreoffice_env, LibreOfficeUnavailableError) |
2026.10.16 | Copy the helpers you need, or pin parsecraft==2026.10.15. The module is gone, not renamed; the backend stopped calling it in 2026.10.15 and no declared format needs LibreOffice. |
DOCLING_LIBREOFFICE_CMD |
2026.10.15 | Nothing — the backend stopped reading it. Office formats are already parsed natively by docling-rs and the variable has no effect. |
| OCR being implicitly off | next release | Nothing, unless you relied on it. OCR permission is now derived from EnvironmentInfo.ocr_backends — the registered OCR-family backends whose dependency group is installed or whose engine is usable — instead of an ocr- extra-name prefix that no extra ever carried. So installing parsecraft[ocr] or parsecraft[surya] now permits OCR where it previously never did, and on a host with no OCR harness an image-only page is planned onto an installed OCR-capable parser (docling, marker, mineru) with intent=ocr rather than degrading to native. Permission is not capability: whether a permitted backend runs is still decided by the existing GPU and VRAM gate, so installing [ocr] on a host without a usable GPU changes nothing. Pass --no-ocr to keep the old behaviour. |
convert stderr on OCR pages |
next release | Nothing — additive. A degraded-empty-output quality signal, and a matching stderr line, now appears when an OCR-capable parser returns no blocks for a page that needed OCR and reported no diagnosis of its own; the constant DEGRADED_EMPTY_OUTPUT_CODE is exported from parsecraft.pipeline. Exit codes are unchanged: a document where every pass failed still exits 1 on the distinct pipeline-all-passes-failed, and an adapter that explained itself (for example docling with OCR models missing) reports through its own page diagnostic instead. |
--backend docling with --backend-option |
next release | Fix the option name, or stop passing it. The docling adapter now honours --backend-option — until now it accepted the flag and discarded it — so a key it does not know is rejected with exit 1 and the accepted list, where it used to be ignored in silence. This only bites a script that already pinned --backend docling and passed a key nothing read: the flag requires --backend, so auto-mode callers cannot reach it. The other backends still ignore unknown keys (pc-23b); do not read their silence as acceptance. |
Per-release behaviour changes are in the GitHub release body. The body is written by an opt-in AI step; when that step is not configured it carries only the compare link, which still lists every commit and its message.
From source¶
Use a checkout when contributing or testing unreleased changes. Clone and sync:
git clone https://github.com/jr2804/parsecraft.git
cd parsecraft
uv sync --dev
uv run parsecraft backends
Or use mise, which also installs the pinned tool versions:
git clone https://github.com/jr2804/parsecraft.git
cd parsecraft
mise dev
uv run parsecraft backends
mise dev writes the virtual environment created by uv. Activate it with
source .venv/bin/activate (POSIX) or .venv\Scripts\activate (Windows) if
you prefer parsecraft over uv run parsecraft.
Verify the install¶
uv run parsecraft --version
uv run parsecraft backends
parsecraft backends prints No backends registered. on a fresh checkout —
no third-party backend is installed by default. Install the example backend to
see discovery working:
uv pip install examples/third_party_backend
uv run parsecraft backends
# example-echo cpu text