Metadata-Version: 2.5
Name: parsecraft
Version: 2026.11.3
Summary: Document intelligence: align existing converters, parsers, and OCR/VLM models behind one workflow and one typed output format
Author-email: "Jan.Reimes" <Jan.Reimes@head-acoustics.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: binaryornot>=0.6
Requires-Dist: charset-normalizer>=3.4
Requires-Dist: fonttools>=4.5
Requires-Dist: huggingface-hub>=0.34
Requires-Dist: liteparse>=2.14
Requires-Dist: markdown-it-py>=4.2
Requires-Dist: openpyxl>=3.1
Requires-Dist: pdf-inspector>=1.25.2
Requires-Dist: pillow>=10.4
Requires-Dist: platformdirs>=4.3
Requires-Dist: pydantic-settings>=2.15
Requires-Dist: pydantic>=2.13
Requires-Dist: pypandoc>=1.15
Requires-Dist: pypdf>=5
Requires-Dist: pypdfium2>=5.14
Requires-Dist: tomlkit>=0.13
Requires-Dist: typer>=0.12.0
Requires-Dist: typesafe-sdk>=0.7.2
Provides-Extra: docling
Requires-Dist: docling-rs>=2.55; extra == 'docling'
Provides-Extra: mineru
Requires-Dist: accelerate>=0.34; extra == 'mineru'
Requires-Dist: torch>=2.5; extra == 'mineru'
Requires-Dist: torchvision; extra == 'mineru'
Requires-Dist: transformers<6,>=5.17; extra == 'mineru'
Provides-Extra: ocr
Requires-Dist: accelerate>=0.34; extra == 'ocr'
Requires-Dist: addict; extra == 'ocr'
Requires-Dist: easydict; extra == 'ocr'
Requires-Dist: einops; extra == 'ocr'
Requires-Dist: matplotlib; extra == 'ocr'
Requires-Dist: requests; extra == 'ocr'
Requires-Dist: torch>=2.5; extra == 'ocr'
Requires-Dist: torchvision; extra == 'ocr'
Requires-Dist: transformers<6,>=5.17; extra == 'ocr'
Provides-Extra: pdf-full
Requires-Dist: accelerate>=0.34; extra == 'pdf-full'
Requires-Dist: pymupdf>=1.28.2; extra == 'pdf-full'
Requires-Dist: torch>=2.5; extra == 'pdf-full'
Requires-Dist: torchvision; extra == 'pdf-full'
Requires-Dist: transformers<6,>=5.17; extra == 'pdf-full'
Provides-Extra: pymupdf
Requires-Dist: pymupdf>=1.28.2; extra == 'pymupdf'
Provides-Extra: surya
Requires-Dist: accelerate>=0.34; extra == 'surya'
Requires-Dist: torch>=2.5; extra == 'surya'
Requires-Dist: torchvision; extra == 'surya'
Requires-Dist: transformers<6,>=5.17; extra == 'surya'
Provides-Extra: vllm
Requires-Dist: vllm>=0.11; (sys_platform != 'win32') and extra == 'vllm'
Provides-Extra: web
Requires-Dist: httpx>=0.27; extra == 'web'
Requires-Dist: trafilatura>=2.3.1; extra == 'web'
Description-Content-Type: text/markdown

# ParseCraft

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

<p align="center">
  <a href="#"><img alt="Python 3.13 | 3.14+" src="https://img.shields.io/badge/python-3.13%20%7C%203.14%2B-3776ab?logo=python"></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-green.svg"></a>
  <a href="https://github.com/jr2804/parsecraft/actions"><img alt="CI" src="https://github.com/jr2804/parsecraft/actions/workflows/ci.yml/badge.svg"></a>
  <a href="https://pypi.org/project/parsecraft/"><img alt="PyPI" src="https://img.shields.io/pypi/v/parsecraft.svg"></a>
</p>

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](https://docs.astral.sh/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](https://jr2804.github.io/parsecraft/reference/backends/).

## 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:

```bash
uv add parsecraft      # or: pip install parsecraft
uv run parsecraft backends
```

First release: `2026.9.2`. The current version is on
[PyPI](https://pypi.org/project/parsecraft/).

Building from a source checkout, running the test suite, and working on the
codebase are covered in the [development setup](https://jr2804.github.io/parsecraft/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 |

```bash
uv run parsecraft backends
# No backends registered.        (no third-party backend installed yet)
```

See the [CLI reference](https://jr2804.github.io/parsecraft/reference/cli/) for
every command, flag, exit code, and environment variable.

## How it works

```text
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](https://jr2804.github.io/parsecraft/architecture/overview/),
the [IR model](https://jr2804.github.io/parsecraft/architecture/ir/), the
[backend catalog](https://jr2804.github.io/parsecraft/reference/backends/), and
the [backend authoring guide](https://jr2804.github.io/parsecraft/guides/backend-authoring/).

## Documentation

- [Installation](https://jr2804.github.io/parsecraft/getting-started/installation/)
- [Quickstart](https://jr2804.github.io/parsecraft/getting-started/quickstart/)
- [Architecture](https://jr2804.github.io/parsecraft/architecture/overview/)
- [Backends](https://jr2804.github.io/parsecraft/architecture/backends/)
- [Write a backend](https://jr2804.github.io/parsecraft/guides/backend-authoring/)
- [Backend catalog](https://jr2804.github.io/parsecraft/reference/backends/)
- [CLI reference](https://jr2804.github.io/parsecraft/reference/cli/)
- [API reference](https://jr2804.github.io/parsecraft/reference/api/)
- [Development setup](https://jr2804.github.io/parsecraft/development/setup/)

## License

MIT — see [LICENSE](LICENSE) for details.
