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.

Source version in this branch: 0.3.0a11.

Latest verified PyPI release: 0.3.0a9, published from tag v0.3.0a9 at commit 629f641fe3f3e108c08e1ceb51622c524c6cb57e.

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

Media adapter 0.2.0a3 remains the current standalone release and was not republished with Engine a9.

The separately packaged OfficeCLI adapter 0.1.0a1 remains an unpublished, disabled prototype.

Engine a6 adds an authenticated, read-only per-step recovery projection without modifying the a5 workflow contracts or durable authority model.

The prior coordinated security cut and its accepted OS boundary remain recorded in the rc4/a4 publication record. Engine a5 adds the runtime-provider workflow without changing those frozen historical records.

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 current Engine prerelease using the verified PyPI command at the top of this README.

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.0a3"

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/training/   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/ARCHITECTURE.md for the supported runtime boundaries and docs/PUBLIC_DOCUMENTATION_POLICY.md for the public/private documentation boundary.

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