ZeroProofML v0.6.0 API Reference (Phase 9)

This page collects the public Python API for the signed common meadow (SCM) implementation described in this documentation set. The emphasis is on the functions and classes that are stable for the v0.6.0 release; experimental helpers remain internal.

Stability map (stable vs experimental)

The table below is the stability contract for this documentation set. Anything not listed here should be treated as experimental/internal and may change without notice. The table uses the canonical zeroproofml.* import paths; matching zeroproof.* compatibility imports have the same support level unless noted otherwise. Namespace layering rule for future additions: add SCM implementation modules under zeroproof.*, keep zeroproofml.* as the canonical public import/docs surface for those modules, and use zeroproofml.* directly only for product-level surfaces that do not have a legacy zeroproof.* counterpart (for example zeroproofml.benchmarks). The zeroproof compatibility namespace is part of this stability contract through the roadmap's next major milestone, the M4 core 1.0-or-stay-0.x decision; no namespace deprecation warning is planned before then unless a concrete migration plan is published.

Module Symbols Stability Notes
zeroproofml.scm.value SCMValue, scm_real, scm_complex, scm_bottom Stable Core SCM value contract
zeroproofml.scm.ops scm_add, scm_sub, scm_mul, scm_div, scm_inv, scm_neg, scm_pow, scm_log, scm_exp, scm_sqrt, scm_sin, scm_cos, scm_tan, plus tested *_numpy, *_torch, and *_jax variants Stable Scalar SCM helpers plus backend shims
zeroproofml.scm.fracterm Fracterm, Polynomial, SimplificationMode, StrictPreservingTarget Stable Symbolic/common-meadow helpers exercised by property tests and flattening docs; Fracterm.strict_preserving_target declares the pure strict (P, Q) target, nonzero domain_assumptions are caller contracts for local simplification, and field-rational cancellation requires explicit unsafe simplification_mode="field_rational"
zeroproofml.scm.sign WeakSignState, weak_sign Stable Weak-sign/orientation tracking; non-finite payloads return bottom rather than an orientation tag
zeroproofml.autodiff.policies GradientPolicy, gradient_policy, register_policy, apply_policy, apply_policy_vector Stable Policy routing for gradients near ⊥
zeroproofml.autodiff.graph SCMNode, add, sub, mul, div, stop_gradient Experimental Low-level graph scaffolding kept primarily for docs/examples/tests
zeroproofml.autodiff.projective GaugePolicy, ProjectiveNormalize, ProjectiveSample, encode, decode, renormalize, projectively_equal Stable Projective tuple utilities
zeroproofml.training lift_targets, lift_semantic_targets, SemanticTargets, lift_targets_torch, lift_targets_jax, lift_targets_numpy, AdaptiveSampler, AdaptiveSamplerConfig, sampling_weights, singularity_prob, perturbed_threshold, TrainingConfig, SCMTrainer, LinearRamp, LossWeightsCurriculum Stable Training entry points, sampling helpers, and curricula
zeroproofml.layers AngularProjectiveHead, SCMRationalLayer, SCMNorm, SCMSoftmax Stable Core layers used throughout examples/benchmarks
zeroproofml.layers.fru FractermRationalUnit, FRUExpression, FRUConstant, FRUVariable, FRURational, FRUAdd, FRUMul, FRUDiv, FlattenedFRU, UnflattenedFRUAudit, FRUDenominatorSource, DomainAssumption Experimental Small symbolic FRU AST for local P/Q flattening, simplification, experimental structural-validity metadata, and audit-only domain assumptions or unflattened bound-refusal records; public structural-validity fields/accessors such as FlattenedFRU.denominator_provenance, FlattenedFRU.strict_validity_sources, and FlattenedFRU.validity_factors are experimental and orthogonal to the stable fault/semantic mask split
zeroproofml.layers.projective_rational ProjectiveRationalMultiHead, ProjectiveRRModelConfig, RRProjectiveRationalModel Stable Projective rational builders used by the README and inference/training integration tests
zeroproofml.inference InferenceConfig, strict_inference, strict_inference_jax, strict_inference_numpy, SCMInferenceWrapper, validate_bundle, generate_validation_report, ONNXRuntimeBundle, load_onnx_runtime_bundle, run_bundle_reference_smoke_test, SemanticDecodeResult, decode_strict_censored_3way, StrictInferenceMonitor, strict_inference_rates, reject_on_bottom, reject_on_gap, safe_sentinel, route_to_analytic_solver, script_module, export_onnx_model, export_bundle Stable core Deployment/bundle/monitoring surfaces are stable, eager Python strict-inference results expose stable fault_mask, semantic_bottom_mask, and bottom_provenance attributes, script_module remains a legacy TorchScript compatibility helper, and ONNX is the preferred deployment path
zeroproofml.benchmarks BenchmarkConfig, BenchmarkArtifacts, BenchmarkRun, BenchmarkComparison, BenchmarkBaselineComparison, run_benchmark, run_dose_benchmark, run_rf_benchmark, run_ik_benchmark, load_benchmark_run, compare_benchmark_runs, validate_run_dir Stable Top-level benchmark runner plus run loading/comparison and run-directory validation; direct zeroproofml.benchmarks.domains.* imports stay outside this stable contract
zeroproofml.losses LossConfig, implicit_loss, implicit_loss_jax, margin_loss, sign_consistency_loss, coverage, rejection_loss, soft_coverage_loss, SCMTrainingLoss Stable Core SCM loss stack
zeroproofml.metrics tau_infer_sweep_from_q_abs, tau_infer_sweep_report, write_tau_infer_sweep Stable Strict-gating evaluation helpers; RR-specific pole metrics remain example-level/internal for now
zeroproofml.reference_robotics_trajectory_eval ReferenceRoboticsTrajectoryAction, ReferenceRoboticsTrajectoryStepRequest, evaluate_reference_robotics_trajectory_policy, make_reference_robotics_dls_policy Experimental Closed-loop RR trajectory evaluation over the synthetic near-singularity dataset; intended for rollout/control-loop studies rather than the stable SCM core
zeroproofml.downstream_pipeline DownstreamPipelineReferenceSample, DownstreamPipelineSample, DownstreamPipelineStage, DownstreamPipelineSimulator, build_downstream_pipeline_simulator, compare_downstream_pipeline_strategies, simulate_downstream_pipeline, write_downstream_pipeline_visualization_pack Experimental Downstream composability simulator with configurable stage boundaries, built-in baseline comparisons over 1-step / 3-step / 5-step variants, and per-stage visualization artifacts
zeroproofml.utils from_ieee, to_ieee Stable IEEE-754 bridge helpers
zeroproofml.utils.logging JsonlLogger, read_jsonl Stable core TensorBoardLogger and jsonl_to_dataframe are experimental reporting conveniences; zeroproof.utils.logging remains a compatibility import
zeroproofml.utils.viz plot_mask_rates, plot_denominator_hist, plot_tau_infer_sweep, plot_tau_train_sweep, plot_2d_mask_map, plot_3d_mask_map, plot_workspace_rate_heatmaps, plot_route_to_solver_overlay, plot_fallback_route_timeline, plot_monitoring_batch_summary, plot_confusion_matrix, plot_categorical_reliability, plot_detj_stratified_metrics, plot_safety_accuracy_pareto, plot_eval_log Experimental Lightweight plotting primitives stay under the canonical zeroproofml.utils.viz path and are grouped under training, strict_inference, benchmarks, and domains submodules; higher-level report generators should live in a separate report layer if they become maintained APIs; zeroproof.utils.viz remains a compatibility import

The examples/robotics/rrr_ik_* and ik6r_* scripts are intentionally absent from this table: they remain example-level workflows rather than first-class experimental integrations until they gain a maintained zeroproofml.* surface plus the same artifact-contract and CI expectations used for supported robotics entry points.

SCM Core (zeroproofml.scm)

zeroproofml.scm.value

  • SCMValue: immutable value container carrying either a numeric payload or the absorptive bottom ⊥.
  • scm_real(x: float) -> SCMValue: construct a finite SCM value from a real number.
  • scm_complex(z: complex) -> SCMValue: construct a finite SCM value from a complex number.
  • scm_bottom() -> SCMValue: return the absorptive bottom element.

zeroproofml.scm.ops

  • Arithmetic helpers mirror common meadow semantics: scm_add, scm_sub, scm_mul, scm_div, scm_inv, scm_neg, scm_pow.
  • Transcendental helpers respect the bottom element: scm_log, scm_exp, scm_sqrt, scm_sin, scm_cos, scm_tan.
  • All functions accept SCMValue or plain Python scalars for ergonomic use in notebooks and examples.

Autodiff (zeroproofml.autodiff)

Gradient policies (zeroproofml.autodiff.policies)

  • GradientPolicy: enum of gradient handling strategies (CLAMP, PROJECT, REJECT, PASSTHROUGH).
  • gradient_policy(policy: GradientPolicy): context manager to override the active policy.
  • register_policy(layer: str, policy: GradientPolicy): register layer-specific defaults.
  • apply_policy(gradient: float, is_bottom: bool, policy: GradientPolicy | None = None) -> float: transform a gradient according to the active policy.
  • apply_policy_vector(...): vectorised version of apply_policy.

Computation graph (zeroproofml.autodiff.graph) (experimental)

  • Experimental: this low-level graph scaffolding is kept primarily for docs/examples/tests and may change without notice.
  • SCMNode: lightweight computation node carrying a forward SCMValue, autodiff metadata, and an is_bottom flag for policy routing.
  • Constructors: SCMNode.constant(value), SCMNode.stop_gradient(node).
  • Primitives: add, sub, mul, div, each propagating bottom semantics.
  • Utilities: backward(upstream=1.0, policy=None), trace(depth=0).
  • Functional helpers mirror the methods: add, sub, mul, div, stop_gradient.

Projective tuples (zeroproofml.autodiff.projective)

  • GaugePolicy: enum of projective magnitude conventions (canonical_denominator, unit_l2_projective, and angular_unit_circle).
  • ProjectiveNormalize(policy=GaugePolicy.CANONICAL_DENOMINATOR, gamma=0.0): callable helper for applying an explicit gauge convention to (N, D) before downstream thresholding or monitoring. The default preserves exported denominator magnitudes; the unit policies normalize by the projective L2 norm and leave (0, 0) unchanged for explicit caller routing.
  • ProjectiveSample: dataclass representing a homogeneous tuple (N, D).
  • encode(value: SCMValue) -> ProjectiveSample: lift an SCM value to projective coordinates (finite → (x, 1), bottom → (1, 0)).
  • decode(sample: ProjectiveSample) -> SCMValue: map a projective tuple back to SCM, emitting ⊥ when D = 0.
  • renormalize(numerator, denominator, gamma=1e-9, stop_gradient=None): detached renormalisation used in projective training (auto-detects Torch/JAX tensors and applies detach/stop_gradient to the norm).
  • projectively_equal(a, b, atol=1e-8) -> bool: compare projective tuples up to scaling.

Training helpers (zeroproofml.training)

  • zeroproofml.training.targets.lift_targets: legacy/simple sentinel lifting for finite values plus NaN/Inf bottoms; stable for compatibility, but not the preferred audit path.
  • zeroproofml.training.targets.lift_semantic_targets: lift numeric targets plus explicit status labels (finite, bottom, censored_below, censored_above, domain_invalid, missing, or fault) into SemanticTargets with projective coordinates, finite/bottom masks, orientation labels, and semantic-vs-fault bottom-kind codes.
  • zeroproofml.training.sampler.AdaptiveSampler: wraps PyTorch dataloaders with singularity-aware sampling weights.
  • zeroproofml.training.sampler.AdaptiveSamplerConfig: sampler config for AdaptiveSampler.
  • zeroproofml.training.sampler.singularity_prob and sampling_weights: tested helper functions for adaptive sampling decisions.
  • zeroproofml.training.gap.perturbed_threshold: lightweight training-time gap helper.
  • zeroproofml.training.trainer.TrainingConfig: config container for SCMTrainer (early-stop thresholds, AMP toggle, optional validation loader, logging hook, gradient-policy override, tau_infer, and the explicit allow_bottom_unreachable escape hatch).
  • zeroproofml.training.trainer.SCMTrainer: v0.6.0 training loop integrating projective decoding, coverage tracking, and gradient policies. The trainer accepts legacy (inputs, targets) batches and typed (inputs, values, status_labels) batches; typed batches are lifted with lift_semantic_targets(...), and loss functions that accept semantic_targets receive the full SemanticTargets object for masking/routing.
  • SCMTrainer checks inf/NaN bottom labels against projective heads that expose bottom_capability(tau_infer) and raises when the denominator construction cannot enter |Q| < tau_infer. Set allow_bottom_unreachable=True only when those labels are intentional noise or outside the current task.
  • lift_targets_torch, lift_targets_jax, and lift_targets_numpy: backend-specific target lifting helpers.
  • Optional curricula:
  • LinearRamp and LossWeightsCurriculum for per-epoch loss-weight schedules (passed into loss functions that accept loss_weights).

Layers (zeroproofml.layers)

  • AngularProjectiveHead: unit-circle projective output head (P=cosθ, Q=sinθ) for stable strict gating. bottom_capability(tau_infer) reports whether strict bottom emission is reachable by construction.
  • SCMRationalLayer, SCMNorm, SCMSoftmax: SCM-aware PyTorch layers.
  • zeroproofml.layers.fru (experimental): typed symbolic FRU helpers (FRUExpression, FRURational, FlattenedFRU, FractermRationalUnit) for flattening small composed rational heads into a checked P/Q pair with structural validity provenance and audit-only domain_assumptions. FractermRationalUnit.flatten_expression(..., preserve_unflattened=True) returns UnflattenedFRUAudit instead of raising when strict flattening succeeds algebraically but exceeds the configured local FRU depth or degree budget; it still runs strict flattening and bound checks first, is not a pre-flatten shortcut, and does not preserve artifacts that fail only after an explicit non-strict flattening mode. UnflattenedFRUAudit.preservation_mode is explicitly audit_only, so the record stores the original FRUExpression tree plus refusal metadata and is not a runtime eager-evaluation fallback. Any future runtime fallback must be a separate opt-in that uses eager SCM semantics and documents the slower path. FlattenedFRU.denominator_provenance and FlattenedFRU.validity_factors are experimental structural-validity fields/accessors. FlattenedFRU.denominator_provenance is preserved for compatibility, FlattenedFRU.strict_validity_sources is the experimental structural-validity source field for factors not already enforced by the reduced payload denominator, and FlattenedFRU.validity_factors is the derived factor-only accessor. FlattenedFRU.structural_validity_output_schema(...) reserves deterministic value, fault-mask, and semantic-mask output names for a future consumer-requested structural-provenance promotion without making those outputs stable today. FlattenedFRU.cancellation_domain_assumptions records the declared nonzero facts tied to cancelled symbolic factors for audit/export consumers. FlattenedFRU.strict_preserving_target declares the guarded strict FRU target, where reduced payloads rely on load-bearing validity factors. The structural provenance trace is orthogonal to the stable strict-inference fault/semantic mask split and has no promotion gate. If a future consumer requests promotion, define a new structural-provenance gate at that time rather than pre-committing thresholds now. Guarded strict FRU evaluation still treats its validity factors as required internal checks for reduced payloads. Field-rational simplification requires explicit unsafe simplification_mode="field_rational"; declared nonzero assumptions are caller contracts, not runtime guards.
  • zeroproofml.layers.projective_rational: ProjectiveRationalMultiHead, ProjectiveRRModelConfig, and RRProjectiveRationalModel are the supported projective-rational building blocks used by the README quickstart and integration tests. ProjectiveRationalMultiHead.bottom_capability(tau_infer) reports "unreachable_by_construction" when configured denominator floors, including anchored softplus floors, cannot enter the strict |Q| < tau_infer region.

Inference (zeroproofml.inference)

  • InferenceConfig: inference thresholds (tau_infer, optional tau_train for gap diagnostics) plus legacy provenance metadata controls (provenance, deprecated provenance_fault_threshold, and provenance_representation). Prefer numerical_hazard_threshold for monitor-only finite-denominator hazard metadata; the deprecated provenance_fault_threshold constructor/metadata name is an alias. Neither setting contributes to bottom_mask, fault_mask, or semantic_bottom_mask.
  • strict_inference(...): strict SCM decode for projective tuples. Results still unpack as (decoded, bottom_mask, gap_mask) for backward compatibility and also expose stable fault_mask, semantic_bottom_mask, and integer-coded bottom_provenance attributes. Optional experimental validity_factors for guarded FRU payloads are checked factorwise with ~isfinite(V_i) | (abs(V_i) < tau_i): non-finite factors route to fault_mask, while below-threshold finite factors route to semantic_bottom_mask.
  • decode_strict_censored_3way(...): semantic/censored strict decoder returning a tuple-compatible SemanticDecodeResult(decoded, bottom_mask, class_id).
  • strict_inference_numpy(...) / strict_inference_jax(...): backend-specific decode helpers used when callers want an explicit NumPy or JAX entry point.
  • SCMInferenceWrapper: wraps a (P, Q)-outputting model and applies strict decoding in eval mode; eager Python results expose the stable mask provenance attributes while retaining the three-field tuple unpacking path. The eager tuple override is documented as wrapper((inputs, validity_denominator)): the second tensor is an external validity denominator Q_valid used for additional bottom/gap mask gating, not a boolean mask, while the model-returned Q remains the value denominator for decoding and bottom detection.
  • get_inference_output_schema(...): returns the promoted schema-v2 descriptor for stable provenance-bearing bundle outputs.
  • get_experimental_inference_output_schema(...): returns the legacy versioned schema descriptor used by recorded pre-promotion provenance sidecars. New schema-v2 bundle metadata writes the promoted descriptor under inference_output_schema; the old experimental_inference_output_schema key is a deprecated loading alias.
  • Bundle utilities:
  • validate_bundle(bundle_dir) checks model.onnx + metadata.json consistency.
  • load_onnx_runtime_bundle(bundle_dir, providers=..., session_options=...) validates the bundle, opens model.onnx with onnxruntime, and returns an ONNXRuntimeBundle whose run(...) / __call__(...) methods keep three-field Python unpacking while mapping schema-v2 ONNX provenance outputs onto fault_mask, semantic_bottom_mask, and bottom_provenance attributes.
  • run_bundle_reference_smoke_test(bundle_dir, wrapped_model, smoke_inputs, ...) runs a small in-process parity check between the wrapped model and the exported bundle, raising if masks or non-bottom decoded values drift on the supplied smoke sample and returning a small comparison summary when they match.
  • generate_validation_report(bundle_dir, benchmark_dir=..., output_path=..., runtime_summary_path=..., calibration_report_path=...) writes a lightweight Markdown report, includes provenance schema / fault-vs-semantic rate breakdowns when those diagnostics are available, automatically picks up adjacent inference_summary.json runtime/fallback stats plus parent benchmark summaries and DOSE operating-point calibration provenance when those sidecars are present (or via the explicit path overrides), and saves a concise *.summary.json sidecar when you persist the report to disk.
  • Patterns and operations:
  • decode_strict_censored_3way(...) implements a strict-gate + optional finite orientation side-channel / direction-head decode for 3-way censoring tasks and can optionally consume provenance diagnostics to reserve the direction head for semantic bottoms while keeping fault-like bottoms out of implicit IEEE-infinity sign routing.
  • StrictInferenceMonitor and strict_inference_rates(...) help monitor bottom/gap/acceptance rates, optionally split bottoms into fault vs semantic rates when provenance diagnostics are supplied, optionally expose monitor-only numerical_hazard_rate from a supplied finite-hazard mask, can export monitor state plus per-update histograms and per-batch summaries through StrictInferenceMonitor.export_state(...), and can emit structured trigger/drift records through an optional event_logger.
  • Fallback helpers: reject_on_bottom, reject_on_gap, safe_sentinel, route_to_analytic_solver. route_to_analytic_solver(...) can also emit structured fallback-routing events with provenance tags when an event_logger is provided.
  • Export helpers:
  • script_module(model) for legacy TorchScript compatibility only.
  • export_onnx_model(model, example_inputs, output_path, ...) for ONNX; this is the preferred deployment/export path.
  • export_bundle(model, example_inputs, out_dir, ...) for a model.onnx + metadata.json bundle; bundle metadata declares its own top-level schema_name / schema_version, strict_inference_exports, per-input/per-output tensor signatures, batch-axis semantics, optional preprocessing/postprocessing or normalization sidecars, and provenance-configured exports also include a versioned inference_output_schema declaration.

Losses (zeroproofml.losses)

  • LossConfig: grouped hyperparameters for the combined training loss.
  • implicit_loss, implicit_loss_jax, margin_loss, sign_consistency_loss, coverage, rejection_loss, and soft_coverage_loss implement the objectives described in 04_loss_functions.md; sign_consistency_loss is a singular-orientation auxiliary loss, not a generic finite-regression loss, hard rejection_loss(is_bottom, ...) is detached metric-style penalty accounting, and soft_coverage_loss(Q, tau, temperature, target) is the differentiable under-coverage surrogate.
  • implicit_loss(..., detach_scale=False) and implicit_loss_jax(..., detach_scale=False) keep the implicit-loss scale attached by default; pass detach_scale=True to opt into the legacy detached-scale shrink heuristic.
  • margin_loss(..., reduction="population" | "conditional") defaults to the population-style masked batch mean; conditional reduction averages over finite targets only.
  • SCMTrainingLoss combines the individual terms with configurable weights (λ_margin, λ_sign, λ_rej).
  • When sign_consistency_loss is called without mask_singular, or SCMTrainingLoss receives lambda_sign > 0 without mask_singular, sign supervision is restricted to targets with abs(Y_d) <= epsilon_sing; pass mask_singular explicitly to supervise finite orientations or another signed task domain.
  • DOSE-specific direction-head losses, samplers, and mixed finite-MSE/censoring recipes remain benchmark-only; use the generic losses above plus curricula instead of depending on DOSE follow-up scripts as public APIs.

Benchmarks (zeroproofml.benchmarks)

  • run_dose_benchmark(...), run_rf_benchmark(...), and run_ik_benchmark(...) are the per-domain benchmark APIs used by the CLI.
  • BenchmarkConfig and run_benchmark(...) remain available when tooling wants to assemble the domain/config pair programmatically.
  • Direct zeroproofml.benchmarks.domains.* imports remain importable for tests/tooling, but the stable contract stays at the top-level zeroproofml.benchmarks package and CLI.
  • DOSE-specific direction-head and loss follow-ups are benchmark-only evidence paths, including python -m zeroproofml.benchmarks dose --mode frozen-dirhead; no DOSE-only head/loss is promoted to zeroproofml.layers or zeroproofml.losses in this release.
  • Legacy wrapper files under scripts/ and examples/robotics/rr_ik_dataset.py still delegate to these APIs, but now emit DeprecationWarning at runtime so migration is visible in code as well as docs.
  • BenchmarkConfig.resume / python -m zeroproofml.benchmarks ... --resume continue interrupted paper-mode runs from the same out_root while preserving per-attempt provenance history.
  • BenchmarkConfig.skip_complete_seeds / --skip-complete-seeds reuse an existing out_root and run only missing canonical seed artifacts; BenchmarkConfig.force_rerun / --force-rerun rerun the requested seeds in an existing out_root.
  • BenchmarkConfig.html_report / python -m zeroproofml.benchmarks ... --html-report add an optional RUN_REPORT.html; every completed run always writes RUN_REPORT.md.
  • zeroproofml.report.generate_benchmark_report(...), generate_bundle_report(...), and generate_training_log_report(...) regenerate Markdown reports from stored artifacts and write standard SVG summary figures; benchmark reports write metric means, per-seed distributions, and baseline-delta plots when paired stats are present, and DOSE benchmark reports also write figures/dose_figure_pack/ when aggregated/dose_diagnostics.json is present. Benchmark reports can also write optional embedded HTML with --html-report, and training-log reports add an interactive <stem>_REPORT.html when Plotly is installed via zeroproofml[interactive]. Regenerated benchmark and training-log reports use artifact-relative source labels so copied artifact directories reproduce the same report content.
  • load_benchmark_run(run_dir) validates and loads a completed scientific benchmark run directory into a BenchmarkRun object containing the manifest, provenance, summary, and paired stats payloads.
  • compare_benchmark_runs(target, baselines) compares one run with one or more baseline run directories or loaded BenchmarkRun objects and returns per-baseline paired statistics plus common model/metric metadata.
  • validate_run_dir(run_dir) checks a completed run directory for the required artifacts, validates the manifest / provenance / summary / paired-stats JSON schemas, and verifies recorded artifact hashes against the files on disk.

Metrics (zeroproofml.metrics)

  • tau_infer_sweep_from_q_abs(...): compute FN/FP/bottom-rate curves from cached |Q| values without re-running full inference.
  • tau_infer_sweep_report(curves, title=...): render a compact Markdown report for those curves.
  • write_tau_infer_sweep(out_dir, curves, provenance=...): write the JSON + Markdown pair used by deployment/benchmark reporting.
  • RR-specific pole metrics under zeroproofml.metrics.pole_2d remain example-level helpers and are not part of the stable contract yet.

RR trajectory evaluation (zeroproofml.reference_robotics_trajectory_eval) (experimental)

  • ReferenceRoboticsTrajectoryStepRequest: closed-loop per-step request object containing the current RR state, current det(J) diagnostics, target waypoint, derived workspace command, and the dataset's reference DLS action.
  • ReferenceRoboticsTrajectoryAction: policy response container with (dtheta1, dtheta2) plus optional fallback markers so evaluations can report fallback frequency by trajectory bin and, when fallback labels include fault / semantic, provenance-aware splits.
  • make_reference_robotics_dls_policy(...): build a DLS baseline policy that can replay the synthetic RR trajectory dataset under the same damping law used by the dataset generator.
  • evaluate_reference_robotics_trajectory_policy(dataset, policy, ...): replay a policy over the stratified RR trajectory dataset and summarize aggregate plus per-start-bin tracking error, reference-error gap, joint-step magnitude, fallback rate, per-step fallback-rate traces, joint-limit violations, chattering events, and policy latency/budget violations.

Downstream pipeline simulator (zeroproofml.downstream_pipeline) (experimental)

  • DownstreamPipelineSample: lightweight carrier for decoded scalar/vector payloads plus a reject flag and optional provenance label.
  • DownstreamPipelineReferenceSample: strategy-agnostic reference payload used to encode the built-in scalar-only, abstention/uncertainty, strict-SCM, and strict-SCM-plus-direction-head comparison baselines.
  • DownstreamPipelineStage: configurable downstream boundary that can drop the reject flag, provenance side channel, and optional direction-label side channel before an optional sample transform runs, with built-in bad-downstream toggles for nan_to_num, missing-flag drops, clipping, default fills, JSON/CSV round-trips, and aggregate_mean reductions.
  • build_downstream_pipeline_simulator(...): builds the default 1-step, 3-step, or 5-step variants used for composability experiments, threads shared bad-downstream toggle settings into the default stages, or validates a caller-supplied stage list against one of those variant lengths.
  • compare_downstream_pipeline_strategies(...): replay the same configured pipeline across the built-in scalar-only baseline, abstention/uncertainty baseline, strict SCM, and strict SCM + direction head encodings, returning one simulation result per strategy.
  • simulate_downstream_pipeline(samples, config) / DownstreamPipelineSimulator.simulate(...): replay samples through the configured stage chain and summarize per-stage finite-payload rates, reject-flag fidelity, propagated reject/censor/singularity fidelity, downstream decision accuracy, a payload/flag consistency calibration proxy under corruption, provenance survival (including per-label fault-vs-semantic fidelity when available), direction-label fidelity, and unsafe finite accepts when reject-flag carriers are lost.
  • build_downstream_pipeline_stage_summary_rows(...), write_downstream_pipeline_stage_summaries(...): flatten a simulation or strategy comparison into per-stage JSON/CSV summaries for transition analysis.
  • render_downstream_pipeline_transition_diagram_svg(...), render_downstream_pipeline_failure_propagation_svg(...), and render_downstream_pipeline_corruption_sensitivity_svg(...): generate notebook-free SVG diagnostics for stage handoffs, failure propagation, and downstream corruption sensitivity.
  • write_downstream_pipeline_visualization_pack(...): writes composability_figure_pack/ with stage-summary JSON/CSV, transition diagrams, failure-propagation diagrams, corruption-sensitivity curves, README, and manifest.
  • render_downstream_pipeline_report_markdown(...), render_downstream_pipeline_report_html(...), and write_downstream_pipeline_report(...): turn a simulation result or strategy comparison into composability artifacts, with write_downstream_pipeline_report(...) now also saving a machine-readable DOWNSTREAM_PIPELINE_REPORT.json sidecar containing per-stage sample snapshots for later analysis and optionally writing the visualization pack.

How to read this page

The functions above intentionally mirror the conceptual contract: train on smooth, infer on strict. Use the docstrings in each module for parameter details and examples; this page is a signpost for the available surfaces.

Utilities (zeroproofml.utils)

  • Prefer the stable JSONL path (JsonlLogger, read_jsonl) in release-facing integrations; the reporting conveniences below remain experimental.
  • IEEE bridge: from_ieee, to_ieee
  • zeroproofml.utils.logging: stable core = JsonlLogger, read_jsonl; experimental reporting conveniences = TensorBoardLogger, jsonl_to_dataframe, plus read_metric_log_runs(...) / aggregate_metric_logs(...) for multi-seed and multi-run JSONL summaries. The legacy zeroproof.utils.logging path remains supported as a compatibility import.
  • The same logging module also exposes experimental metric_log_records_to_wide_rows(...) / metric_log_records_to_long_rows(...) converters so dashboards and downstream tooling can flatten versioned metric logs without reimplementing schema parsing.
  • JSONL trainer/eval metric records use schema_name="zeroproofml.metric_log" and schema_version=1; metric_log_record(...) creates the canonical metrics payload while preserving flat top-level metric keys for older readers.
  • zeroproofml.utils.viz: experimental lightweight plotting primitives (plot_mask_rates, plot_denominator_hist, plot_tau_infer_sweep, plot_tau_train_sweep, plot_2d_mask_map, plot_3d_mask_map, plot_workspace_rate_heatmaps, plot_route_to_solver_overlay, plot_fallback_route_timeline, plot_monitoring_batch_summary, plot_confusion_matrix, plot_categorical_reliability, plot_detj_stratified_metrics, plot_safety_accuracy_pareto, plot_eval_log). Lightweight plotting primitives stay under the canonical zeroproofml.utils.viz path and are grouped under training, strict_inference, benchmarks, and domains submodules; plot_denominator_hist accepts optional provenance masks or enum labels to color finite/fault/semantic denominator samples; higher-level report generators should live in a separate report layer if they become maintained APIs; zeroproof.utils.viz remains a compatibility import.