API Reference

This page is the public v0.5.1 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` for small rational terms
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`	`ProjectiveSample`, `encode`, `decode`, `renormalize`, `projectively_equal`
Training	`zeroproofml.training`	Target lifting, `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 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 and denominator 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
Provenance diagnostics	Inference result attributes such as `fault_mask` and `bottom_provenance`	Opt-in diagnostic contract only

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

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)

Projective Utilities

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

Use these helpers when a rational value should be trained as (P, Q) and decoded only at a boundary.

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,
)

Experimental FRU flattening:

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

Use FRU flattening for small post-training analysis/export checks, not for whole-network symbolic lowering.

Losses

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

JAX-specific implicit loss is available as implicit_loss_jax.

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,
    TrainingConfig,
    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

Inference

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

Stable strict decode returns:

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

Backend entry points:

strict_inference_numpy
strict_inference_jax

Bundle and report helpers:

validate_bundle
generate_validation_report
load_onnx_runtime_bundle
run_bundle_reference_smoke_test
export_onnx_model
export_bundle

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

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.

Benchmarks

from zeroproofml.benchmarks import (
    BenchmarkConfig,
    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 still supported in v0.5.1; there is no immediate deprecation warning planned.

Docs