PDX Artifact Engine

PDX Artifact Engine is a model-optional, deterministic artifact orchestration framework. It turns structured plans into skill calls, verification results, and checksummed manifests.

No trained PDX model weights are included in this repository. Plans may be supplied manually, by rules, or later by an external model provider. PDX-5B-1B+ experts are an optional future bundle, not a v0.1.0 requirement.

Current PyPI prerelease: 0.3.0a4, published from tag v0.3.0a4 at commit 2acdebf73134ed106a636ed38e1ecce6596eb751. Media adapter remains 0.2.0a2 and was not republished with Engine a4. The published rc4/a4 overlay is compatibility/pdx_prodocux_release_rc4_a4.json; it does not rewrite the frozen rc2/a2 or rc3/a3 records.

The current working tree is the unpublished 0.3.0a5 implementation candidate for runtime_provider_workflow_v1. It must not be confused with or republished as the immutable a4 release.

This coordinated security cut keeps runtime behavior and frozen contracts unchanged; its image omits pip/setuptools and pins the reviewed base digest. Media stays 0.2.0a2. See rc4/a4 publication and security boundary.

python -m pip install "pdx-artifact-engine==0.3.0a4"

Positioning

Target architecture (not present in v0.1.0): a future 8 GB mode may keep a PDX-Core-1B router resident and hot-swap specialists. That is a roadmap goal, not a current runtime capability.

Core thesis

plan.json  (manual | rules | future model provider)
  -> skill dispatch
  -> artifact outputs
  -> verification
  -> artifact_manifest.json + run_manifest.json

Small models should eventually plan and repair. Skills should execute artifact creation with deterministic tools. v0.1.0 proves the second half without the first.

Install

pip install -e ".[dev]"

Install the ProDocuX deterministic extract/render adapter prerelease from PyPI:

pip install "pdx-artifact-engine==0.3.0a2"

See the pdx-artifact-engine PyPI 0.3.0a2 release and GitHub prerelease.

The older published wheel pdx-artifact-engine PyPI 0.3.0a1 predates the additive extract/render freeze and must not be overwritten. Frozen compatibility v3 still pins implementation commit 37e89752560b22dc8724d470dce96187f19e3f98.

Requires Python 3.11+.

The product-neutral ProDocuX HTTP adapter ships in the main distribution. The media identity/probe adapter is optional and has its own package:

pip install ./adapters/media

Install its coordinated standalone PyPI package with:

pip install "pdx-adapter-media==0.2.0a2"

See the pdx-adapter-media PyPI project.

See docs/RELEASE.md for package boundaries and release verification.

The active coordinated ProDocuX/PDX prerelease surface is recorded in compatibility/pdx_prodocux_compatibility_v2.json. Additive extract/render pins are recorded in compatibility/pdx_prodocux_compatibility_v3.json. G1A in that manifest is the frozen synthetic render-conformance fixture set. Current tags, package versions, assets, and publication state are recorded in compatibility/pdx_prodocux_release_v1.json. The immutable v1 manifest remains packaged in the repository as historical compatibility evidence.

Deterministic demo (no LLM)

From the repository root:

python -m pdx_artifact_engine.cli.run \
  --plan examples/plans/pif_deterministic_plan.json \
  --output-dir .tmp/pif-deterministic \
  --mock

Or generate a plan with RulePlanner:

python -m pdx_artifact_engine.cli.run \
  --rule-request examples/requests/pif_rule_request.json \
  --output-dir .tmp/pif-rule \
  --mock

Both write:

• run_manifest.json — overall completed / completed_with_review / failed / blocked
• artifact_manifest.json — files, provenance, verification

CLI exit code is 1 when status is failed or blocked.

Aspirational plan (contains expert step)

examples/plans/pif_workflow_plan.json still includes a PDX-Doc-1B expert step to document the future shape. Without --mock, that plan blocks. With --mock, the expert is simulated and the run is marked completed_with_review.

Planner providers

Schemas

The packaged Core additionally publishes execution-plan, verifier-result, workflow-checkpoint, approval, artifact identity, step receipt, run snapshot, external operation, execution context, publication receipt, and run event v1 contracts. ArtifactRuntime accepts product-owned verifier implementations through an injected registry; missing verifiers fail closed unless the host explicitly selects review policy. Serialized snapshot resume validates plan, subject, evidence, artifact, and receipt digests and executes only pending steps. Provider polling, durable databases, scheduling, and domain policy stay outside Core.

Model weights stay outside git. Describe them with examples/models/*.manifest.json and docs/model-cards/.

Repository layout

docs/                 Architecture, roadmap, model cards, Phase 0 contracts
packages/             Packaged Core source and schemas
adapters/             Product-neutral optional integration packages
schemas/              JSON contracts
examples/             Plans, fixtures, rule requests, model manifests
notebooks/kaggle/     Training plans (no weights)
runtime/              Python package `pdx_artifact_engine`
skills/               Sample skill registry
evals/                Eval notes
tests/                pytest

Historical v0.1.0 release criteria

• Apache-2.0 license
• Unified skill + registry contract
• README states model-optional clearly
• depends_on + $step.output wiring
• Honest run status (no silent success on blocked experts)
• Deterministic E2E example without LLM
• model_manifest schema (weights out of band)
• Path traversal rejection for file_exists / mock outputs
• Unknown skill / executor errors always write schema-valid failed manifests
• Cycle detection covered by tests
• Fresh Python 3.12 venv pytest green

License

Apache License 2.0. See LICENSE.

Near-term roadmap

See docs/ROADMAP.md for the M0-M8 milestone definitions. Phase 0 private-job paper freeze: docs/PHASE0_DECISIONS.md.

1. Integrate the available ProDocuX HTTP adapter tools into product-owned skill registries and executors (M1).
2. Convert ProDocuX runs into planner traces.
3. Train and publish PDX-Core-1B out of band; wire LlamaCppPlanner in a future version.
4. Low-RAM hot-swap runtime (M7).

Acknowledgments

Codex and Cursor contributed implementation support, contract hardening, and cross-review during the v0.3 prerelease upgrade. Final design and release decisions remain with the project maintainers.