Deployment Bundles Guide

Use ONNX bundles as the supported deployment handoff artifact. They keep the strict SCM inference contract together with the metadata needed to validate and reload it.

Bundle contents

An exported bundle includes at least:

  • model.onnx
  • metadata.json

Validation and regenerated report artifacts typically live beside those files:

  • VALIDATION_REPORT.md
  • VALIDATION_REPORT.summary.json
  • VALIDATION_REPORT.summary.svg

Export and validate

from zeroproofml.inference import (
    SCMInferenceWrapper,
    export_bundle,
    load_onnx_runtime_bundle,
    run_bundle_reference_smoke_test,
    validate_bundle,
)

export_bundle(wrapped_model, (x_example,), "bundle_dir")
validate_bundle("bundle_dir")

runtime = load_onnx_runtime_bundle("bundle_dir", providers=["CPUExecutionProvider"])
decoded, bottom_mask, gap_mask = runtime.run(x_numpy)

run_bundle_reference_smoke_test("bundle_dir", wrapped_model, (x_smoke,))

Use run_bundle_reference_smoke_test(...) before shipping so the exported ONNX path is checked against the wrapped Python model on a known sample.

What downstream consumers should rely on

  • metadata.json records tau_infer and optional tau_train
  • schema-v2 ONNX output order is decoded, bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, bottom_provenance
  • Python unpacking stays decoded, bottom_mask, gap_mask
  • new schema-v2 metadata.json declares strict_inference_exports as stable_provenance_outputs
  • recorded schema-v1 merged_only_masks and deprecated experimental_provenance_outputs bundles remain valid under their own metadata

Previously exported bundles are validated under their recorded schema and metadata, including strict_inference_schema_version, strict_inference_exports, and any inference_output_schema or legacy experimental_inference_output_schema sidecar. They are not silently reinterpreted under the new hardened schema.

For schema-v2 stable provenance outputs, fault_mask and semantic_bottom_mask are not disjoint. A sample with both an IEEE-fault payload and a below-threshold denominator sets both split masks. Consumers reading the split masks see the full picture; consumers reading bottom_provenance alone see the same four-state picture through NONE, FAULT, SEMANTIC, and MIXED.

The promoted bundle metadata name is inference_output_schema. Recorded bundles that still use experimental_inference_output_schema validate as a compatibility alias and emit DeprecationWarning. New bundles should not write the old key.

Treat that metadata as part of the deployment interface, not as an optional comment.

Regenerate the operator report

From an existing bundle directory:

python -m zeroproofml.report bundle bundle_dir

That refreshes the Markdown validation report and writes the SVG summary figure used for operator handoff.

Shipping checklist

  1. Freeze InferenceConfig with the deployment thresholds.
  2. Export the bundle from the wrapped model.
  3. Run validate_bundle(...).
  4. Run a reference smoke test with saved example inputs.
  5. Regenerate the bundle report and ship the report with the bundle.