ParseCraft

Document intelligence: convert any document into typed structured chunks, with Markdown as a deterministic projection

ParseCraft turns a document into a typed intermediate representation (IR) of structured chunks. Backends analyze a source and convert bounded page slices into IR pages; a dependency-free renderer projects the IR to deterministic Markdown. The IR is the source of truth — every other output is a projection of it.

The project is at Phase 0. The IR schema, the backend protocol and registry, and the CLI are implemented and covered by tests. Document adapters, the config engine, and concrete OCR/VLM backends arrive in later phases.

Requirements

• Python 3.13 (GIL only — the free-threaded 3.13t build is not supported)
• Python 3.14 or newer, including free-threaded builds (3.14t)
• uv for dependency management
• mise for the project task runner

Quick Start

git clone https://github.com/jr2804/parsecraft.git
cd parsecraft
mise dev            # uv sync -U --dev --all-extras --all-groups
mise test           # pytest with the 100% coverage gate
uv run parsecraft backends

mise dev installs dependencies only. mise test, mise lint, and mise format run the quality gates.

CLI

uv run parsecraft backends
# No backends registered.        (fresh checkout)

# After installing a backend:
# example-echo             cpu              text
# warning: backend 'broken' failed to load: ...   (stderr)

uv run parsecraft --version

Project Structure

parsecraft/
├── .config/mise/               # mise task definitions
├── .github/workflows/          # CI, docs, and release workflows
├── docs/                       # Zensical documentation site
│   ├── adr/                    # Architecture decision records
│   └── reference/              # API + CLI reference
├── examples/
│   └── third_party_backend/    # Working entry-point backend
├── scripts/
│   └── gen_credits.py          # Credits generator for the docs site
├── src/parsecraft/
│   ├── __init__.py
│   ├── __about__.py            # Package metadata
│   ├── backends/               # Protocol, registry, errors
│   ├── cli/                    # Typer app, commands, args
│   ├── ir/                     # IR models + Markdown projection
│   └── py.typed
├── tests/                      # pytest suite (100% coverage gate)
├── pyproject.toml              # uv + hatch + pytest config
├── ruff.toml                   # Linter + formatter config
├── ty.toml                     # Type checker config
└── zensical.toml               # Docs site configuration

Development

mise test       # pytest with the 100% coverage gate
mise lint       # ruff check
mise typecheck  # ty check src/ tests/
mise spell      # codespell
mise format     # ruff format + isort + clean-sort
mise all        # test + lint + spell + format + format-md + docs

Pre-commit hooks run a subset of these on every commit:

pre-commit install
pre-commit run --all-files

The docs site builds with mise docs (uv run zensical build). Serve it live with uv run --link-mode=copy zensical serve.

CI/CD

Documentation

Full documentation: https://jr2804.github.io/parsecraft/

• Getting started
• Architecture
• Write a backend
• CLI reference
• API reference

AI Dev-Features

The project ships optional AI-agent tooling. After mise dev, install with:

mise run add-mcp-servers <agent>   # register MCP servers (claude, codex, gemini, ...)
mise run add-skills                # install agent skills

Enabled dev-features are listed in .config/mise/conf.d/mcp.toml and .config/mise/conf.d/skills.toml.

Tech Stack

License

MIT — see LICENSE for details.

Generated from copier-uv-plus.