Metadata-Version: 2.4
Name: zeroproofml
Version: 0.6.1
Summary: Signed Common Meadow arithmetic for stable machine learning
Author-email: Zsolt Döme <dome@zeroproofml.com>
License-Expression: MIT
Project-URL: Homepage, https://zeroproofml.com
Project-URL: Repository, https://gitlab.com/domezsolt/zeroproofml
Project-URL: Documentation, https://zeroproofml-9aafa4.gitlab.io/
Project-URL: Issues, https://gitlab.com/domezsolt/zeroproofml/-/issues
Keywords: signed-common-meadow,scm,machine-learning,numerical-stability,autodiff,robustness
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: torch
Requires-Dist: torch>=1.12; extra == "torch"
Provides-Extra: benchmarks
Requires-Dist: numpy>=1.23; extra == "benchmarks"
Requires-Dist: torch>=1.12; extra == "benchmarks"
Provides-Extra: jax
Requires-Dist: jax>=0.4.14; extra == "jax"
Requires-Dist: jaxlib>=0.4.14; (platform_machine != "arm64" or platform_system != "Darwin") and extra == "jax"
Provides-Extra: dev
Requires-Dist: numpy>=1.23; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: hypothesis>=6.88; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mypy>=1.4; extra == "dev"
Requires-Dist: pre-commit>=3.3; extra == "dev"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Requires-Dist: tensorboard>=2.8; extra == "viz"
Requires-Dist: Pillow>=9.3; extra == "viz"
Requires-Dist: pandas>=2.0; extra == "viz"
Provides-Extra: interactive
Requires-Dist: plotly>=5.22; extra == "interactive"
Provides-Extra: deployment
Requires-Dist: torch>=2.7.1; extra == "deployment"
Requires-Dist: onnx>=1.18; extra == "deployment"
Requires-Dist: onnxruntime>=1.22; extra == "deployment"
Requires-Dist: onnxscript>=0.5; extra == "deployment"
Provides-Extra: onnx
Requires-Dist: torch>=2.7.1; extra == "onnx"
Requires-Dist: onnx>=1.18; extra == "onnx"
Requires-Dist: onnxruntime>=1.22; extra == "onnx"
Requires-Dist: onnxscript>=0.5; extra == "onnx"
Provides-Extra: backends
Requires-Dist: numpy>=1.23; extra == "backends"
Requires-Dist: torch>=1.12; extra == "backends"
Requires-Dist: jax>=0.4.14; extra == "backends"
Requires-Dist: jaxlib>=0.4.14; (platform_machine != "arm64" or platform_system != "Darwin") and extra == "backends"
Provides-Extra: all
Requires-Dist: numpy>=1.23; extra == "all"
Requires-Dist: torch>=1.12; extra == "all"
Requires-Dist: jax>=0.4.14; extra == "all"
Requires-Dist: jaxlib>=0.4.14; (platform_machine != "arm64" or platform_system != "Darwin") and extra == "all"
Provides-Extra: full
Requires-Dist: numpy>=1.23; extra == "full"
Requires-Dist: torch>=2.7.1; extra == "full"
Requires-Dist: jax>=0.4.14; extra == "full"
Requires-Dist: jaxlib>=0.4.14; (platform_machine != "arm64" or platform_system != "Darwin") and extra == "full"
Requires-Dist: onnx>=1.18; extra == "full"
Requires-Dist: onnxruntime>=1.22; extra == "full"
Requires-Dist: onnxscript>=0.5; extra == "full"
Requires-Dist: matplotlib>=3.7; extra == "full"
Requires-Dist: tensorboard>=2.8; extra == "full"
Requires-Dist: Pillow>=9.3; extra == "full"
Requires-Dist: pandas>=2.0; extra == "full"
Requires-Dist: plotly>=5.22; extra == "full"
Dynamic: license-file

# ZeroProofML

<div align="center">

**Machine learning that handles division by zero gracefully**

[![Pipeline](https://gitlab.com/domezsolt/zeroproofml/badges/main/pipeline.svg)](https://gitlab.com/domezsolt/zeroproofml/-/pipelines)
[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://zeroproofml-9aafa4.gitlab.io/)

*Built on Signed Common Meadow (SCM) semantics for totalized arithmetic*

</div>

## What is ZeroProofML?

ZeroProofML is a Python library for Signed Common Meadow (SCM) arithmetic and
PyTorch rational models. It lets scientific and ML code represent division by
zero as an explicit bottom element `⊥` with masks, instead of letting NaN/Inf
payloads silently drive later computations.

[Documentation](https://zeroproofml-9aafa4.gitlab.io/) ·
[PyPI](https://pypi.org/project/zeroproofml/) ·
[Changelog](CHANGELOG.md) ·
[Examples](examples/README.md) ·
[Architecture](ARCHITECTURE.md) ·
[Assurance](TRUST_BOUNDARIES.md) ·
[Security](SECURITY.md) ·
[License](LICENSE)

## Status

> **Alpha; not safety-deployment or experiment-qualified.**
>
> `v0.6.x` is **gauge-dependent**: rejection scores based on `|Q|` are not
> invariant across every call site. Treat deployment safety scores as
> gauge-dependent. See [CHANGELOG.md](CHANGELOG.md) `[0.6.1]` for the current
> containment surface and limitations.

## Install

```bash
python -m pip install zeroproofml
python -m pip install "zeroproofml[torch]"

# ONNX bundle export and runtime
python -m pip install "zeroproofml[deployment]"
# `onnx` remains a compatibility alias for the deployment extra.
python -m pip install "zeroproofml[onnx]"

# scientific benchmark harness
python -m pip install "zeroproofml[benchmarks]"

# optional experimental plotting/logging utilities
python -m pip install "zeroproofml[viz]"

# optional interactive training-log reports
python -m pip install "zeroproofml[interactive]"

# compatibility backend aggregate / every public optional feature
python -m pip install "zeroproofml[all]"
python -m pip install "zeroproofml[full]"
```

The core package has no required runtime dependencies. Use the `torch` extra for
PyTorch layers, training, strict inference wrappers, and export workflows; the
v0.6.x compatibility floor is `torch>=1.12`. Use `benchmarks` for the shipped
DOSE / RF / IK benchmark harness, `viz` for experimental reporting helpers, and
`interactive` when report regeneration should also write Plotly HTML.

## Quick Start

The base package is enough to see the SCM boundary:

```python
from zeroproofml.scm import scm_div, scm_real

print(scm_div(scm_real(1.0), scm_real(2.0)))
singular = scm_div(scm_real(1.0), scm_real(0.0))
print(singular)
print(singular.is_bottom)
```

```text
SCMValue(0.5)
SCMValue(⊥)
True
```

For PyTorch strict inference, install `zeroproofml[torch]`:

```python
import torch

from zeroproofml.inference import InferenceConfig, SCMInferenceWrapper


class Reciprocal(torch.nn.Module):
    def forward(self, x):
        return torch.ones_like(x), x


model = SCMInferenceWrapper(
    Reciprocal(),
    config=InferenceConfig(tau_infer=1e-6, tau_train=1e-4),
)
model.eval()

decoded, bottom_mask, gap_mask = model(torch.tensor([[-1.0], [0.0], [2.0]]))
print(decoded.squeeze().tolist())
print(bottom_mask.squeeze().tolist())
print(gap_mask.squeeze().tolist())
```

```text
[-1.0, nan, 0.5]
[False, True, False]
[False, False, False]
```

The decoded NaN is only a payload sentinel. Consumers should branch on
`bottom_mask`, `fault_mask`, `semantic_bottom_mask`, and `bottom_provenance`
instead of interpreting decoded non-finite values as data.

## Why ZeroProofML?

- **Totalized arithmetic:** singular scalar operations become explicit `⊥`
  values instead of unclassified IEEE carrier values.
- **Projective training path:** rational heads can learn `⟨N,D⟩` tuples while
  strict inference decides when denominators are too small to accept.
- **Mask-first inference:** `bottom_mask`, `gap_mask`, `fault_mask`, and
  semantic-bottom masks give downstream code an auditable rejection surface.
- **Scientific and robotics use cases:** useful for rational approximations,
  inverse kinematics, projective geometry, singular potentials, and censored
  target streams.
- **Compatibility path:** the legacy implementation namespace remains
  importable while public examples and docs use `zeroproofml.*`.

## Requirements and Compatibility

- Python: 3.10 through 3.14, CPython.
- Core install: no mandatory third-party runtime dependencies.
- PyTorch extra: `torch>=1.12`; CI includes a Python 3.10 minimum-Torch lane.
  The extra is not platform-empty on Linux, Windows, macOS x86_64, or macOS
  arm64.
- Optional backends: PyTorch via `zeroproofml[torch]`; JAX is available as an
  optional backend for supported local workflows.
- `deployment` is the ONNX export/runtime extra; `onnx` is its v0.6.x
  compatibility alias. `backends` is the lean backend aggregate and `all` is
  its compatibility alias; use `full` for every supported public optional feature.
- Benchmarks: install `zeroproofml[benchmarks]` before running
  `python -m zeroproofml.benchmarks ...`.
- Stability: alpha. Public APIs are versioned, but `v0.7.0a1` is expected to
  introduce breaking semantic/status changes.
- Documentation: published docs track the latest `main` branch at the site root.

`zeroproofml` is the canonical public namespace for package/docs/install references.
The legacy `zeroproof` import path remains supported as a compatibility namespace.
That compatibility commitment holds through the roadmap's next major milestone,
the M4 core 1.0-or-stay-0.x decision, and no namespace deprecation warning is
planned before then unless a concrete migration plan is published.
Layering rule for new code: keep SCM implementation modules under `zeroproof.*`,
expose them through `zeroproofml.*` for public imports/docs, and reserve
`zeroproofml.*`-only modules for product-level surfaces that have no legacy
counterpart (for example `zeroproofml.benchmarks`).
Import guidance lives in
[`docs/33_namespace_guide.md`](docs/33_namespace_guide.md).

## Limitations and Non-Goals

- `v0.6.x` does not provide gauge-invariant deployment qualification.
- Observation, censoring, missingness, domain-invalid values, semantic bottom,
  and runtime faults are still being separated into the breaking `v0.7.x`
  contract.
- Full trainer run-accounting and deterministic DataLoader worker contracts
  remain deferred; gradient-policy contexts are isolated per task/thread in
  this release.
- Safety-critical deployment wording is unsupported for this release line.
- For paper-exact reproduction, pin to `zeroproofml==0.4.3` or the matching
  release tag `v0.4.3`; the v0.6.x line should not reinterpret paper-era
  bundles under newer strict-inference schemas.

## Documentation

- [Getting started](docs/00_getting_started.md)
- [Documentation hub](docs/index.md)
- [API reference](docs/08_api_reference.md)
- [Namespace guide](docs/33_namespace_guide.md)
- [Masks and provenance guide](docs/34_masks_and_provenance_guide.md)
- [`examples/README.md`](examples/README.md) — maintained-vs-archival map.
- [`docs/38_examples_inventory.md`](docs/38_examples_inventory.md) — full
  examples label map.
- [`docs/39_examples_tutorials.md`](docs/39_examples_tutorials.md) — tutorial
  path through maintained examples.
- [`examples/deployment/README.md`](examples/deployment/README.md) —
  deployment workflow examples.
- [Reproducibility](REPRODUCIBILITY.md)

## Development and Release Checks

```bash
make install
make quality
make test-fast
make test-coverage
make test-release-blockers
make docs
```

These targets use the locked environment and the same profile definitions as
CI. Run the broader optional-backend/package matrix with `make test-all`.
Build and validate release artifacts from a clean candidate checkout with:

```bash
make build
```

Scientific claim benchmark runs and performance microbenchmarks are separate.
GitLab `claim-benchmark:*` jobs exercise the current `v0.6.x` scientific
benchmark harness in the bounded `contract` mode. Paper-exact experiments are frozen to
`zeroproofml==0.4.3` / tag `v0.4.3`; do not interpret current `v0.6.1`
benchmark runs as paper reproduction. The `benchmark_results/` JSON files
belong to the performance microbenchmark suite:

```bash
python -m pip install "zeroproofml[benchmarks]"
make benchmark-contract
python -m zeroproofml.benchmarks dose --mode contract --out-root runs/dose-contract
python -m zeroproofml.report training-log runs/scm_train_metrics.jsonl
python perf/run_benchmarks.py --suite all --output benchmark_results
```

## Support, Security, and Citation

- Report bugs through the [GitLab issue tracker](https://gitlab.com/domezsolt/zeroproofml/-/issues).
- Read the release history in [CHANGELOG.md](CHANGELOG.md); the `[0.6.1]`
  entry lists the current containment surface, disabled paths, and
  known limitations.
- Read a compact per-defect summary of the `v0.6.0` audit that motivated
  `v0.6.1` in [docs/16_verification_report.md](docs/16_verification_report.md)
  under "v0.6.0 audit summary".
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution and release-check
  expectations.
- Cite the software with [CITATION.cff](CITATION.cff). The published paper
  artifact DOI is `10.5281/zenodo.18944465`.

## Acknowledgements

The theoretical foundation builds on Jan A. Bergstra and John V. Tucker's work
on meadows and common meadows, algebraic structures that make division total by
adding an absorptive element.

## License

MIT License. See [LICENSE](LICENSE) for details.
