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.

v0.3.0a1 prerelease: the repository ships pdx_artifact_core execution contracts plus bounded snapshots, replay-safe resume primitives, repository ports, external-operation reconciliation, execution context/cancellation, publication receipts, and ordered run events. Legacy Dispatcher compatibility and the frozen compatibility v1 surface remain available.

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 published GitHub prerelease wheel with:

pip install "https://github.com/prodocux/pdx-artifact-engine/releases/download/v0.3.0a1/pdx_artifact_engine-0.3.0a1-py3-none-any.whl"

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

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. 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
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

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

1. Register real ProDocuX skill executors (M1).
2. Convert ProDocuX runs into planner traces.
3. Train and publish PDX-Core-1B out of band; wire LlamaCppPlanner (v0.2.0).
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.