API Reference

This page is the public v0.6.0 API map. It is intentionally a signpost, not a replacement for docstrings. Use it to decide which imports are stable enough for application code and which ones are experimental evidence or reporting surfaces.

Canonical imports use zeroproofml.*. Matching zeroproof.* compatibility imports remain supported unless noted.

Stability Map

Anything not listed here should be treated as internal or experimental.

Area	Stable surface	Notes
SCM values	`zeroproofml.scm.value`	`SCMValue`, `scm_real`, `scm_complex`, `scm_bottom`
SCM ops	`zeroproofml.scm.ops`	Scalar ops plus NumPy, Torch, and JAX vectorized variants
Fracterms	`zeroproofml.scm.fracterm`	`Fracterm`, `Polynomial`, `SimplificationMode`, `StrictPreservingTarget`
Weak sign	`zeroproofml.scm.sign`	`WeakSignState`, `weak_sign`
Gradient policies	`zeroproofml.autodiff.policies`	`GradientPolicy`, `gradient_policy`, `register_policy`, `apply_policy`, `apply_policy_vector`
Projective tuples	`zeroproofml.autodiff.projective`	`GaugePolicy`, `ProjectiveNormalize`, `ProjectiveSample`, `encode`, `decode`, `renormalize`, `projectively_equal`
Training	`zeroproofml.training`	Target lifting (sentinel and semantic), `TrainingConfig`, `SCMTrainer`, samplers, curricula
Layers	`zeroproofml.layers`	`SCMRationalLayer`, `SCMNorm`, `SCMSoftmax`, `AngularProjectiveHead`
Projective rational layers	`zeroproofml.layers.projective_rational`	`ProjectiveRationalMultiHead`, `ProjectiveRRModelConfig`, `RRProjectiveRationalModel`
Inference	`zeroproofml.inference`	Strict decode, wrappers, monitors, fallbacks, ONNX bundle helpers
Losses	`zeroproofml.losses`	`LossConfig`, implicit/margin/sign/coverage/rejection/soft-coverage losses, `SCMTrainingLoss`
Metrics	`zeroproofml.metrics`	`tau_infer_sweep_from_q_abs`, `tau_infer_sweep_report`, `write_tau_infer_sweep`
Benchmarks	`zeroproofml.benchmarks`	Top-level benchmark runner, loaders, validators, comparison helpers
Utilities	`zeroproofml.utils`	IEEE bridge helpers
Logging	`zeroproofml.utils.logging`	Stable: `JsonlLogger`, `read_jsonl`; reporting helpers are experimental

Experimental but documented surfaces:

Area	Surface	Status
Low-level autodiff graph	`zeroproofml.autodiff.graph`	Reference scaffolding for examples/tests
FRU AST	`zeroproofml.layers.fru`	Local rational-head flattening plus experimental structural-validity provenance
Visualization	`zeroproofml.utils.viz`	Plotting helpers for reports and diagnostics
Reference robotics	`zeroproofml.reference_robotics_*`	Maintained reference workflows, not core SCM primitives
Downstream simulator	`zeroproofml.downstream_pipeline`	Experimental composability harness

The stable v0.6.x provenance attributes (fault_mask, semantic_bottom_mask, bottom_provenance) are guaranteed strict-inference result attributes and are not experimental. The FRU structural-validity provenance trace on FlattenedFRU is a separate experimental axis with no defined promotion gate.

SCM Core

from zeroproofml.scm.value import SCMValue, scm_bottom, scm_complex, scm_real
from zeroproofml.scm.ops import scm_add, scm_div, scm_inv, scm_mul, scm_sub
from zeroproofml.scm.fracterm import Fracterm, Polynomial, SimplificationMode

Common scalar operations:

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

Vectorized variants follow the same payload-plus-mask contract:

payload_out, mask_out = scm_div_numpy(payload_a, payload_b, mask_a, mask_b)
payload_out, mask_out = scm_div_torch(payload_a, payload_b, mask_a, mask_b)
payload_out, mask_out = scm_div_jax(payload_a, payload_b, mask_a, mask_b)

SimplificationMode is the public alias distinguishing strict SCM simplification (scm_strict, default) from the unsafe field-rational opt-in (field_rational). Strict flattening/cancellation refuses configured depth and degree-bound violations and refuses symbolic factor cancellation unless the factor is a safe numeric constant or is covered by a proven or declared nonzero assumption.

Projective Utilities

from zeroproofml.autodiff.projective import (
    GaugePolicy,
    ProjectiveNormalize,
    ProjectiveSample,
    decode,
    encode,
    projectively_equal,
    renormalize,
)

GaugePolicy records which magnitude convention a head or bundle uses:

GaugePolicy.CANONICAL_DENOMINATOR (default)
GaugePolicy.UNIT_L2_PROJECTIVE
GaugePolicy.ANGULAR_UNIT_CIRCLE

ProjectiveNormalize(policy=..., gamma=0.0) is the opt-in helper for applying a gauge convention before downstream thresholding or monitoring.

Gradient Policies

from zeroproofml.autodiff.policies import (
    GradientPolicy,
    apply_policy,
    apply_policy_vector,
    gradient_policy,
    register_policy,
)

Available policies:

GradientPolicy.CLAMP
GradientPolicy.PROJECT
GradientPolicy.REJECT
GradientPolicy.PASSTHROUGH

Layers

from zeroproofml.layers import (
    AngularProjectiveHead,
    SCMNorm,
    SCMRationalLayer,
    SCMSoftmax,
)

Projective rational builders:

from zeroproofml.layers.projective_rational import (
    ProjectiveRationalMultiHead,
    ProjectiveRRModelConfig,
    RRProjectiveRationalModel,
)

Both AngularProjectiveHead and ProjectiveRationalMultiHead expose bottom_capability(tau_infer), which reports "unreachable_by_construction" when the denominator construction cannot enter the strict |Q| < tau_infer region.

Experimental FRU flattening:

from zeroproofml.layers.fru import (
    FRUAdd,
    FRUConstant,
    FRUDiv,
    FRUMul,
    FRURational,
    FRUVariable,
    FractermRationalUnit,
    FlattenedFRU,
    UnflattenedFRUAudit,
    FRUDenominatorSource,
    DomainAssumption,
)

Use FRU flattening for small post-training analysis/export checks, not for whole-network symbolic lowering. FlattenedFRU.strict_validity_sources and FlattenedFRU.validity_factors are the experimental structural-provenance accessors; FlattenedFRU.cancellation_domain_assumptions records declared nonzero facts tied to cancelled symbolic factors for audit consumers.

Losses

from zeroproofml.losses import (
    LossConfig,
    SCMTrainingLoss,
    coverage,
    implicit_loss,
    margin_loss,
    rejection_loss,
    sign_consistency_loss,
    soft_coverage_loss,
)

JAX-specific implicit loss is available as implicit_loss_jax.

Key v0.6.0 defaults:

implicit_loss(..., detach_scale=False) and implicit_loss_jax(..., detach_scale=False) keep the scale factor attached in the backward pass.
margin_loss(..., reduction="population") defaults to the population-style masked batch mean; reduction="conditional" averages only over finite targets.
sign_consistency_loss and SCMTrainingLoss are singular-only when mask_singular is omitted (using abs(Y_d) <= epsilon_sing).

The generic loss stack is stable. DOSE-specific direction-head losses, samplers, and mixed finite-MSE/censoring recipes remain benchmark-level evidence paths rather than public core APIs.

Training

from zeroproofml.training import (
    AdaptiveSampler,
    AdaptiveSamplerConfig,
    LinearRamp,
    LossWeightsCurriculum,
    SCMTrainer,
    SemanticTargets,
    TrainingConfig,
    lift_semantic_targets,
    lift_targets,
)

Backend-specific target helpers:

lift_targets_torch
lift_targets_jax
lift_targets_numpy

Sampling and threshold helpers:

sampling_weights
singularity_prob
perturbed_threshold

lift_targets(...) is the legacy sentinel path (finite payload plus NaN/Inf bottom labels). lift_semantic_targets(values, status_labels) is the preferred audit path and returns SemanticTargets with projective coordinates, finite/bottom masks, orientation labels, and bottom-kind codes for finite, bottom, censored_below, censored_above, domain_invalid, missing, and fault.

TrainingConfig accepts tau_infer and allow_bottom_unreachable; when target bottoms are present and the projective head cannot reach them under tau_infer, SCMTrainer raises unless the flag is set.

Inference

from zeroproofml.inference import (
    InferenceConfig,
    SCMInferenceWrapper,
    SemanticDecodeResult,
    StrictInferenceMonitor,
    decode_strict_censored_3way,
    export_bundle,
    export_onnx_model,
    generate_validation_report,
    load_onnx_runtime_bundle,
    reject_on_bottom,
    reject_on_gap,
    route_to_analytic_solver,
    run_bundle_reference_smoke_test,
    safe_sentinel,
    script_module,
    strict_inference,
    strict_inference_rates,
    validate_bundle,
)

Stable strict decode:

result = strict_inference(P, Q, config=config)
decoded, bottom_mask, gap_mask = result

fault_mask = result.fault_mask
semantic_bottom_mask = result.semantic_bottom_mask
bottom_provenance = result.bottom_provenance

Backend entry points:

strict_inference_numpy
strict_inference_jax

Schema helpers:

get_inference_output_schema(...) returns the promoted schema-v2 descriptor.
get_experimental_inference_output_schema(...) returns the legacy versioned descriptor used by recorded pre-promotion sidecars.

Bundle and report helpers:

validate_bundle
generate_validation_report
load_onnx_runtime_bundle
run_bundle_reference_smoke_test
export_onnx_model
export_bundle

Schema-v2 bundles export six ONNX outputs (decoded, bottom_mask, gap_mask, fault_mask, semantic_bottom_mask, bottom_provenance) while Python unpacking of runtime.run(...) keeps the stable three-field prefix.

script_module(model) remains available for legacy TorchScript consumers, but ONNX is the preferred deployment path.

InferenceConfig owns:

tau_infer and optional tau_train
numerical_hazard_threshold (monitor-only; deprecated alias provenance_fault_threshold)
legacy provenance / provenance_representation controls retained for call-site compatibility

Non-finite P, Q, or evaluated validity factors route through fault_mask regardless of the legacy provenance flags.

Metrics

from zeroproofml.metrics import (
    tau_infer_sweep_from_q_abs,
    tau_infer_sweep_report,
    write_tau_infer_sweep,
)

Use these helpers to pick and document a strict denominator threshold from held-out |Q| values. RR-specific pole metrics under zeroproofml.metrics.pole_2d remain example-level helpers and are not part of the stable contract yet.

Benchmarks

from zeroproofml.benchmarks import (
    BenchmarkArtifacts,
    BenchmarkBaselineComparison,
    BenchmarkComparison,
    BenchmarkConfig,
    BenchmarkRun,
    compare_benchmark_runs,
    load_benchmark_run,
    run_benchmark,
    run_dose_benchmark,
    run_ik_benchmark,
    run_rf_benchmark,
    validate_run_dir,
)

The stable benchmark surface is top-level zeroproofml.benchmarks. Direct imports from zeroproofml.benchmarks.domains.* may be useful for tests and internal tooling, but they are outside the stable public contract.

Utilities

IEEE bridge:

from zeroproofml.utils.ieee_bridge import from_ieee, to_ieee

Logging:

from zeroproofml.utils.logging import JsonlLogger, read_jsonl

Experimental reporting conveniences include TensorBoardLogger, jsonl_to_dataframe, metric aggregation helpers, CSV/BI row converters, and zeroproofml.utils.viz plotting functions.

Namespace Guidance

Use zeroproofml.* in new documentation, package examples, and application code. Keep zeroproof.* only for compatibility with existing integrations or old code snippets. The compatibility namespace is supported through the roadmap's next major milestone; no namespace deprecation warning is planned before then unless a concrete migration plan is published.

Some product-level surfaces live only under zeroproofml.* and should be documented that way:

zeroproofml.benchmarks
zeroproofml.report
zeroproofml.reference_robotics_deployment

These modules do not have a legacy zeroproof.* counterpart.

Docs