Integrations

ZeroProofML integrations all follow the same rule: keep payloads numeric and carry singularity state in explicit masks.

Backend Extras

Install only the backends you need:

pip install "zeroproofml[torch]"
pip install "zeroproofml[jax]"
pip install "zeroproofml[viz]"
pip install "zeroproofml[interactive]"

From a checkout:

pip install -e ".[torch]"
pip install -e ".[jax]"

You can also run a minimal integration check without pytest:

.venv/bin/python scripts/smoke_integrations.py

NumPy

Use the IEEE bridge for external floats and vectorized SCM ops for arrays:

import numpy as np
from zeroproofml.scm.ops import scm_mul_numpy
from zeroproofml.utils.ieee_bridge import from_ieee

v = from_ieee(float("nan"))
assert v.is_bottom

payload = np.array([1.0, 2.0, 3.0])
mask = np.array([False, True, False])
out, out_mask = scm_mul_numpy(payload, payload, mask, mask)

PyTorch

SCM layers return explicit masks:

import torch
from zeroproofml.layers import SCMRationalLayer

layer = SCMRationalLayer(3, 2)
y, bottom_mask = layer(torch.randn(128))

coverage = 1.0 - bottom_mask.float().mean()

Use masks for coverage metrics, rejection losses, strict decoding, fallback routing, and reports.

JAX

JAX vectorized SCM ops follow the same payload-plus-mask contract through scm_*_jax helpers. For high-performance JIT training, keep the same mask and threshold semantics even when you write task-specific JAX code around the reference helpers.

ONNX Runtime

For non-Python serving, prefer validated ONNX bundles:

from zeroproofml.inference import load_onnx_runtime_bundle

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
semantic_bottom_mask = result.semantic_bottom_mask
bottom_provenance = result.bottom_provenance

Downstream consumers should validate metadata.json, preserve output order, and treat bottom_mask as the authoritative reject/fallback signal. Schema-v2 bundles export six ONNX outputs (decoded, bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, bottom_provenance); Python unpacking keeps the stable three-field prefix.

C++ Consumers

A header-only ONNX Runtime C++ wrapper lives at examples/cpp/zeroproofml_bundle.hpp, with a reference consumer at examples/cpp/minimal_bundle_consumer.cpp. It targets current schema-v2 stable-provenance bundles and validates:

bundle format/version
strict_inference_exports="stable_provenance_outputs"
mask semantics
batch-axis semantics
six-output order: decoded, bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, bottom_provenance

Recorded schema-v1 merged_only_masks bundles still validate under their own metadata, but the C++ wrapper is a minimal current-contract consumer. For robotics or embedded adopters that already consume ONNX Runtime from C++, prefer the header wrapper over copying the example. A pure C ABI remains deferred until there is a concrete non-C++ runtime consumer that needs it.

Build against your local ONNX Runtime and nlohmann/json install:

c++ -std=c++17 examples/cpp/minimal_bundle_consumer.cpp \
  -I/path/to/onnxruntime/include \
  -I/path/to/nlohmann \
  -L/path/to/onnxruntime/lib \
  -lonnxruntime \
  -o minimal_bundle_consumer
./minimal_bundle_consumer path/to/bundle_dir

REST, gRPC, And Inference Servers

A minimal REST service can be a useful adapter over load_onnx_runtime_bundle(...) for non-ROS consumers. Keep it thin:

validate the bundle at startup
expose the stable strict tuple
return masks explicitly
avoid adding a second semantic contract around bottom handling

gRPC and Triton-style model serving are better treated as downstream recipes until a deployment needs binary tensor transport, streaming, dynamic batching, multi-model hosting, GPU scheduling, or platform-native server metrics.

ROS 2 Companion Workspace

The optional ROS 2 beta path lives outside the root Python package so the core install stays ROS-free.

Current companion-workspace contract:

validated RMW: rmw_cyclonedds_cpp
target distros: Humble/Jammy and Jazzy/Noble (Kilted is experimental/manual-only)
startup bundle loading via bundle_dir
strict-inference node consumes std_msgs/msg/Float64MultiArray
results publish zeroproofml_msgs/msg/StrictInferenceResult with flattened decoded payloads, merged bottom_mask/gap_mask, bundle metadata, thresholds, and optional fault_mask/semantic_bottom_mask/bottom_provenance slots
telemetry publishes plot-friendly numeric vectors including fallback_rate, fault_fallback_rate, and semantic_fallback_rate

Launch the RR IK strict-inference path:

ros2 launch zeroproofml_ros rr_ik_strict_inference.launch.py \
  bundle_dir:=/absolute/path/to/results/reference_deploy_robotics/.../bundle

Launch the DOSE offline batch path:

ros2 launch zeroproofml_ros dose_offline_batch.launch.py \
  bundle_dir:=/absolute/path/to/bundle

Use qos_preset=low_latency_control for fresh control-loop samples and qos_preset=offline_batch_replay for deterministic rosbag or batch replay. Lifecycle deployments can use the lifecycle_strict_inference_node variant, which loads bundles in on_configure and gates input processing on activation.

Visualization And Reports

Optional visualization helpers live under zeroproofml.utils.viz. They are experimental plotting primitives for:

mask rates
denominator histograms (with provenance-aware coloring for finite/fault/semantic splits)
tau_infer and tau_train sweeps
2D/3D mask maps
workspace heatmaps
route-to-solver overlays
fallback-route timelines
monitoring batch summaries
|det(J)|-stratified metrics
confusion matrices and reliability plots
safety/accuracy Pareto fronts

Use regenerated report commands for durable artifacts:

python -m zeroproofml.report benchmark results/benchmarks/dose/<run_dir>
python -m zeroproofml.report bundle path/to/bundle_dir
python -m zeroproofml.report training-log runs/scm_train_metrics.jsonl

Integration Checklist

Convert IEEE NaN/Inf to SCM only at boundaries.
Keep payloads and masks together across every handoff.
Preserve decoded, bottom_mask, gap_mask unpacking order.
Preserve the schema-v2 six-output order in ONNX consumers.
Validate ONNX bundle metadata before serving.
Log bottom, gap, acceptance, and fallback rates.
Alert on fault_rate, semantic_bottom_rate, and numerical_hazard_rate separately.

Docs