ProDocuX Kernel

Deterministic document kernel for ProDocuX. Runtime does not call any LLM API (semantic drafting stays on the solver side).

License: Apache-2.0. See LICENSE.

Current prerelease on PyPI: 0.3.0rc2. Working tree for the next unpublished distribution is 0.3.0rc3 (not pushed, tagged, or published).

Documents

• ARCHITECTURE.md — public architecture overview
• CONTRACT.md — boundaries, API, scoring contract
• docs/PHASE0_DECISIONS.md — Phase 0 sidecar, sink, and private-auth paper freeze
• CAPABILITY_REQUESTS.md — capability request template
• docs/RELEASE.md — release-candidate boundary and checks
• compatibility/pdx_prodocux_compatibility_v3.json — frozen additive render/extract pins and G1A render-conformance fixture digests
• compatibility/pdx_prodocux_release_v1.json — published rc2/a2 tags, package versions, release assets, and publication status
• compatibility/pdx_prodocux_release_rc3_a3.json — unpublished rc3/a3 working-tree overlay; does not rewrite v1
• compatibility/pdx_prodocux_compatibility_v2.json — 0.3.0rc1 prerelease versions, operations, and schema digests
• compatibility/pdx_prodocux_compatibility_v1.json — frozen historical compatibility evidence

Install

git clone https://github.com/prodocux/prodocux.git
cd prodocux
.\runtime\install.ps1 -Fresh
.\runtime\verify.ps1

Or:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q

Install the deterministic extract/render prerelease from PyPI:

python -m pip install "prodocux==0.3.0rc2"

See the prodocux PyPI 0.3.0rc2 release and GitHub prerelease.

The older published wheel prodocux PyPI 0.3.0rc1 predates the additive extract/render freeze and must not be overwritten. Frozen compatibility v3 still pins implementation commit 53c4784d4b2bae4437252a287193e897973e8474. See docs/RELEASE.md.

See runtime/INSTALL.md for environment variables and private-sidecar notes.

Release maintainers can verify a wheel from an isolated temporary directory:

python scripts/verify_clean_install.py

See docs/RELEASE.md for the PyPI Trusted Publisher and GitHub approval-boundary workflow.

Test

.\.venv\Scripts\python.exe -m pytest -q

Start API

.\.venv\Scripts\python.exe run_kernel.py   # http://localhost:8900/v1

Available capabilities

The PDF intake endpoint accepts only a bounded base64 payload and a plain .pdf basename. It returns source SHA-256, bounded page text, truncation disclosure, and an explicit ocr_required status without persisting the source document or calling an LLM.

GET /v1/intake/capabilities is the authoritative machine-readable source for available intake operations and their raw-byte/page ceilings. Clients should discover these limits instead of copying constants into adapters.

The evidence verifier accepts already-extracted typed evidence and declarative presence, equality, numeric-range, and date/version checks. It returns stable pass/fail/review reasons without interpreting product claims or regulations. Image OCR is available only through an explicitly injected bounded backend; otherwise the profile reports ocr_unavailable. Normalized diff reports source-linked structural/value changes but leaves business impact to the host.

Library hosts may inject an opaque artifact:// resolver. ProDocuX rejects network/local-path identities at this boundary and verifies declared media type, size, and SHA-256 before returning bytes; storage authorization and tenant isolation remain host responsibilities.

Flagship pipeline

Deterministic template extract → field mapping → precise write → structure repair → L0 gate. Content drafts are supplied by the solver as drafts.json.

See examples/pif_tw/ for curated synthetic fixtures (no customer documents).

Skills (first-party)

All first-party skills are deterministic. CLI messages support en and zh-TW.

Acknowledgments

Codex and Cursor contributed implementation support, contract hardening, and cross-review for the multi-format intake upgrade. Final design and release decisions remain with the project maintainers.