Docs

Inference & Deployment

Inference in v0.6.0 is strict SCM inference. There are no stochastic training thresholds, no gradient policies, and no hidden guard branches. A deployment receives numeric payloads plus masks and must treat those masks as the contract.

Stable Output Contract

Strict inference returns:

decoded, bottom_mask, gap_mask = result

The eager result object also exposes stable provenance detail:

fault_mask = result.fault_mask
semantic_bottom_mask = result.semantic_bottom_mask
bottom_provenance = result.bottom_provenance
Field Meaning Deployment use
decoded Finite decoded payload when accepted; commonly NaN for bottom samples Feed accepted samples to downstream code
bottom_mask Authoritative fail-closed mask (fault_mask | semantic_bottom_mask) Reject, abstain, or route to fallback
gap_mask Finite samples where `tau_infer <= Q
fault_mask Bottom from non-finite P/Q/validity payload Provenance-aware routing (fault → analytic fallback)
semantic_bottom_mask Bottom from a finite threshold trigger Provenance-aware routing (semantic → reject)
bottom_provenance Integer codes: NONE, FAULT, SEMANTIC, MIXED Merged provenance signal when split masks are not exported

bottom_mask and gap_mask are disjoint. fault_mask and semantic_bottom_mask are not — a non-finite P with |Q| < tau_infer sets both, and bottom_provenance records MIXED.

Strict Decode

from zeroproofml.inference import InferenceConfig, strict_inference

cfg = InferenceConfig(tau_infer=1e-6, tau_train=1e-4)
result = strict_inference(P, Q, config=cfg)
decoded, bottom_mask, gap_mask = result

Runtime rules:

non-finite P or Q             -> bottom_mask=True, fault_mask=True
|Q| < tau_infer (finite)      -> bottom_mask=True, semantic_bottom_mask=True
tau_infer <= |Q| < tau_train  -> gap_mask=True

If tau_train is not known or not relevant, omit it and monitor only bottoms.

Warning: bottom_mask is the authoritative bottom signal. decoded may contain NaN; any downstream stage that ignores bottom_mask and coerces NaN with nan_to_num, drops it in JSON/CSV, or otherwise rewrites it can turn an invalid payload into a finite-looking downstream value.

Choosing tau_infer

Pick tau_infer from held-out denominator data, not from a training default.

from zeroproofml.metrics import tau_infer_sweep_from_q_abs, write_tau_infer_sweep

curves = tau_infer_sweep_from_q_abs(
    q_abs=q_abs_held_out,
    is_in_range=is_in_range,
    taus=[1e-6, 3e-6, 1e-5, 3e-5, 1e-4],
)
write_tau_infer_sweep(
    "results/tau_calibration",
    curves,
    provenance={"split": "held_out"},
)

Selection trade-off:

  • Larger tau_infer: fewer unsafe finite accepts near singularities, more rejection.
  • Smaller tau_infer: higher coverage, more risk near the denominator boundary.

Freeze the chosen value in InferenceConfig and ship it inside bundle metadata. Post-hoc sweeps over cached |Q| remain valid only for the head and magnitude convention that produced those distributions; re-run the sweep after gauge, normalization, or preprocessing changes.

Wrapping A Model

from zeroproofml.inference import InferenceConfig, SCMInferenceWrapper

wrapped = SCMInferenceWrapper(
    model,
    config=InferenceConfig(tau_infer=1e-6, tau_train=1e-4),
).eval()

result = wrapped(x)
decoded, bottom_mask, gap_mask = result
fault_mask = result.fault_mask

In training mode, wrappers can pass projective outputs through for loss computation. In eval mode, they decode strictly and expose the stable provenance attributes on the returned result object.

ONNX Bundles

ONNX bundles are the preferred deployment handoff artifact:

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

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

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

A stable bundle contains:

  • model.onnx
  • metadata.json

Common report artifacts beside the bundle:

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

Schema-v2 Contract

v0.6.0 bundles declare strict_inference_schema_version=2 and strict_inference_exports="stable_provenance_outputs". The ONNX graph exposes six named outputs in this order:

decoded, bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, bottom_provenance

Python unpacking of runtime.run(...) keeps the three-field compatibility prefix; the provenance outputs land on the result attributes. TorchScript exports continue to ship only the three-field tuple.

metadata.json records the strict output contract, tau_infer, optional tau_train, per-input/per-output tensor signatures, batch-axis semantics, mask semantics, package versions, and provenance schema descriptor. Recorded schema-v1 (merged_only_masks) and deprecated experimental_provenance_outputs bundles remain valid under their own metadata. They are not silently reinterpreted under the hardened schema.

The provenance metadata sidecar is now inference_output_schema. The old experimental_inference_output_schema key remains a deprecated alias that validates with DeprecationWarning.

TorchScript support remains a legacy compatibility path. Prefer ONNX for new deployments.

Smoke Test

Run a parity check against the wrapped model on a saved smoke sample:

summary = run_bundle_reference_smoke_test(
    "bundle_dir",
    wrapped,
    (x_smoke,),
    providers=["CPUExecutionProvider"],
)
print(summary["decoded_max_abs_diff"])

The smoke test validates bottom_mask first and compares decoded values only on non-bottom entries, so bottom payload sentinels do not carry semantics.

Fallback Patterns

The simplest deployment action is reject-on-bottom:

from zeroproofml.inference import reject_on_bottom

decoded_safe, accept_mask = reject_on_bottom(decoded, bottom_mask)

For conservative systems, reject the gap region too:

from zeroproofml.inference import reject_on_gap

decoded_safe, accept_mask = reject_on_gap(decoded, bottom_mask, gap_mask)

For robotics or control systems, route bottom or risky samples to an analytic solver. When provenance diagnostics are threaded through, semantic bottoms can stay rejected in place while fault-like bottoms and other invalid samples get the analytic fallback:

from zeroproofml.inference import route_to_analytic_solver

resolved, route_mask = route_to_analytic_solver(
    decoded,
    bottom_mask=bottom_mask,
    fault_mask=fault_mask,
    semantic_bottom_mask=semantic_bottom_mask,
    bottom_provenance=bottom_provenance,
    analytic_solver=solver,
    inputs=x,
)

Keep the mask and the selected route in logs. Silent replacement of rejected values makes audits much harder.

Monitoring

from zeroproofml.inference import StrictInferenceMonitor
from zeroproofml.utils.logging import JsonlLogger

events = JsonlLogger("strict_inference_events.jsonl")
monitor = StrictInferenceMonitor(
    bundle_id="robotics_rr_ik_v1",
    event_logger=events,
    acceptance_rate_drift_threshold=0.1,
)

monitor.update(
    bottom_mask,
    gap_mask,
    fault_mask=fault_mask,
    semantic_bottom_mask=semantic_bottom_mask,
    bottom_provenance=bottom_provenance,
)
rates = monitor.rates()
state = monitor.export_state(
    include_histograms=True,
    include_batch_summaries=True,
)

Monitor at least:

  • bottom rate (plus fault_rate / semantic_bottom_rate when provenance is available)
  • gap rate
  • acceptance rate
  • route/fallback rate
  • denominator minimums when available
  • drift against calibration or validation rates

StrictInferenceMonitor.update(...) emits structured fault-bottom-trigger, semantic-bottom-trigger, numerical-hazard-trigger, gap-trigger, and acceptance-rate-drift records when an event_logger is set. Treat sustained high fault_rate as a non-finite/runtime debugging signal rather than a model-quality signal, and alert on numerical_hazard_rate separately from both provenance rates.

Numerical Hazards Are Monitor-Only

InferenceConfig.numerical_hazard_threshold reports finite tiny denominators through the numerical_hazard_rate axis. It does not contribute to bottom_mask, fault_mask, or semantic_bottom_mask. The old provenance_fault_threshold name is a deprecated alias.

Direction-Aware Censoring

For three-way censoring problems, combine strict bottom gating with an optional finite direction signal. decode_strict_censored_3way(...) accepts an independently computed weak-sign side channel, an angular/projective direction head, or an auxiliary direction head, plus optional provenance diagnostics so the direction head only handles semantic bottoms:

from zeroproofml.inference import decode_strict_censored_3way

decoded, bottom_mask, class_id = decode_strict_censored_3way(
    P.squeeze(-1),
    Q.squeeze(-1),
    tau_infer=1e-6,
    direction_logits=direction_logits,
    orientation_signal=weak_sign_side_channel,
    fault_mask=fault_mask,
    semantic_bottom_mask=semantic_bottom_mask,
    bottom_provenance=bottom_provenance,
)

Fault-like bottoms use orientation_signal when supplied and otherwise carry the neutral class. IEEE +inf / -inf decoded payloads are not treated as orientation carriers.

Reference Deployment

The reference robotics deployment runs train → bundle → strict inference → fallback → report:

python scripts/reference_robotics_deployment.py --device cpu --epochs 2 --n-samples 6000

It writes a self-contained directory under results/reference_deploy_robotics/ with the ONNX bundle, validation report, inference summary, strict-inference audit, and output contract.

The same path is importable:

from zeroproofml.reference_robotics_deployment import (
    ReferenceRoboticsDeploymentConfig,
    load_reference_robotics_deployment_artifacts,
    run_reference_robotics_deployment,
)

artifacts = run_reference_robotics_deployment(
    ReferenceRoboticsDeploymentConfig(device="cpu", epochs=2, n_samples=6000)
)
same_run = load_reference_robotics_deployment_artifacts(artifacts.out_root)
print(artifacts.bundle_model_path)

Named Operating Points

DOSE benchmark artifacts define named deployment presets. They are not magic values — use a post-hoc sweep or held-out calibration set to set the actual thresholds for your domain:

  • safety_first: reject both strict-bottom and gap-region samples.
  • direction_aware: keep the censored direction meaningful with a direction head.
  • accuracy_first: keep tau_infer tight and treat the gap region as monitor-only.

Completed DOSE runs back these names with aggregated/dose_operating_points.{json,md}, including recorded tau_infer / tau_train and, when provenance splits are available, a provenance-weighted bottom-cost signal fault_rate + 0.5 * semantic_bottom_rate.

Deployment Checklist

  • Freeze InferenceConfig from held-out calibration data.
  • Export a schema-v2 ONNX bundle from the eval wrapper.
  • Run validate_bundle(...).
  • Run run_bundle_reference_smoke_test(...) against saved smoke inputs.
  • Regenerate the validation report with python -m zeroproofml.report bundle <bundle_dir>.
  • Confirm downstream consumers gate decoded values with bottom_mask before use.
  • Log route/fallback actions and acceptance-rate drift in production.
  • Alert on fault_rate, semantic_bottom_rate, and numerical_hazard_rate separately.