Docs

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]"

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"])
decoded, bottom_mask, gap_mask = runtime.run(x_numpy)

Downstream consumers should validate metadata.json, preserve output order, and treat bottom_mask as the authoritative reject/fallback signal.

C++ Consumers

The library docs include a minimal ONNX Runtime C++ consumer pattern around stable bundles. The C++ side should validate:

  • bundle schema/version
  • strict_inference_exports
  • mask semantics
  • batch-axis semantics
  • output order: decoded, bottom_mask, gap_mask

Keep C++ consumers on the stable merged-mask contract unless a future release promotes provenance-bearing outputs.

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
  • startup bundle loading via bundle_dir
  • strict-inference node consumes std_msgs/msg/Float64MultiArray
  • results publish StrictInferenceResult
  • telemetry publishes plot-friendly numeric vectors

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.

Visualization And Reports

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

  • mask rates
  • denominator histograms
  • tau_infer sweeps
  • 2D/3D mask maps
  • workspace heatmaps
  • fallback-route timelines
  • confusion matrices
  • reliability plots
  • benchmark/report figures

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 output order.
  • Validate ONNX bundle metadata before serving.
  • Log bottom, gap, acceptance, and fallback rates.
  • Treat provenance diagnostics as optional unless a future stable schema says otherwise.