valuebridge-tdfloat 1.0.0__tar.gz → 1.1.0__tar.gz

valuebridge_tdfloat-1.1.0/MANIFEST.in

@@ -0,0 +1,21 @@
+include README.md
+include LICENSE
+include pyproject.toml
+
+recursive-include valuebridge *.py
+
+# Keep the sdist lean: exclude Rust crate, Coq proofs, docs, tests,
+# build artifacts, and lockfiles. These live in the git repository.
+prune tdfloat_core
+prune proofs
+prune docs
+prune tests
+prune dist
+prune build
+prune .venv
+prune valuebridge_tdfloat.egg-info
+exclude uv.lock
+exclude .gitignore
+global-exclude __pycache__
+global-exclude *.pyc
+global-exclude *.pyo

valuebridge_tdfloat-1.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: valuebridge-tdfloat
+Version: 1.1.0
+Summary: Triadic Dot Float — exact rational arithmetic as a single Python integer
+Author-email: Tushar Dadlani <tushar@valuebridge.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/valuebridge-ai/tdfloat
+Project-URL: Source, https://github.com/valuebridge-ai/tdfloat
+Project-URL: Bug Tracker, https://github.com/valuebridge-ai/tdfloat/issues
+Keywords: arithmetic,rational,exact,floating-point,mathematics,encoding,number-theory
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# valuebridge-tdfloat
+
+**Triadic Dot Float (TDFloat)** — exact rational arithmetic as a single
+Python integer, with a Rust backend and Coq-verified foundations.
+
+```python
+from valuebridge.tdfloat import td, frac
+
+td('0.1') + td('0.2') == td('0.3')        # True — always
+(a + b) + c == a + (b + c)                  # True — for any a, b, c
+```
+
+---
+
+## Why This Matters for Explainable AI
+
+Modern AI systems — language models, recommendation engines, fairness
+audits, financial models — all perform millions of arithmetic operations.
+Every one of those operations runs on IEEE 754 floating-point, a format
+designed in 1985 for numerical simulation, not for systems that need to
+be explained, audited, or trusted.
+
+**TDFloat replaces floating-point approximation with provably exact
+rational arithmetic.** The consequences for explainable AI are direct.
+
+### 1. Computations Are Reproducible — Exactly
+
+IEEE 754 arithmetic is non-deterministic across platforms, compilers, and
+thread orderings. TDFloat arithmetic is deterministic by construction.
+The same inputs always produce the same output, encoded as the same
+integer. AI outputs become **auditable**: you can replay any computation
+and verify it step by step.
+
+### 2. Associativity is a Theorem, Not a Hope
+
+In IEEE 754:
+
+```
+(a + b) + c  ≠  a + (b + c)   for many values
+```
+
+Simply reordering additions in a neural network — which optimising
+compilers do routinely — can change the model's output.
+
+TDFloat's associativity is **formally proved in Coq**
+(`proofs/tdfloat_ieee_resolution.v`).
+
+### 3. Every Number Has an Interpretable Identity
+
+In IEEE 754, `3.141592653589793` is just a 64-bit pattern. In TDFloat:
+
+```python
+x = td('3.14')
+x.as_fraction()   # (157, 50)  — exact numerator and denominator
+x.info_bit        # 1          — half-step axis (has a dot)
+x.dot_pos         # 2          — two decimal places
+```
+
+Every intermediate result is fully inspectable as an exact rational.
+
+### 4. Fairness Audits Can Be Verified
+
+If two computations produce the same rational value, their encodings are
+equal. If different, provably different. There is no grey zone of "close
+enough." Fairness claims can be verified arithmetically, not just
+statistically.
+
+---
+
+## Quick Start
+
+```python
+from valuebridge.tdfloat import td, frac, TDFloat, PI, E, PHI
+from valuebridge.tdfloat.math import sqrt, circle_area, cosine_similarity
+
+# Exact arithmetic
+assert td('0.1') + td('0.2') == td('0.3')
+
+# Exact (legacy-rational) constants
+print(PI)                          # 22/7
+print(E)                           # 19/7
+print(circle_area(td(7)))         # 154 — exact integer
+
+# Exact vector similarity
+u = [td(3), td(4)]
+v = [td(4), td(3)]
+print(cosine_similarity(u, v))    # 24/25 — exact
+```
+
+### IEEE 754 / MPFR-accurate constants
+
+For numerically-accurate values of irrational constants (π, e, √2, ln 2,
+…), use the parallel `ieee754` namespace:
+
+```python
+from valuebridge.tdfloat import ieee754
+
+ieee754.PI()                      # π at 200 bits (default)
+ieee754.PI(bits=53)               # π at IEEE 754 double precision
+ieee754.E(bits=128)
+ieee754.SQRT2(bits=256)
+ieee754.LN2(bits=64)
+ieee754.EULER_GAMMA()
+```
+
+Each constant is computed by GNU MPFR (via `gmpy2`) at the requested
+precision and returned as a `TDFloat` rational approximation. The legacy
+`PI = 22/7` stays unchanged for backward compat.
+
+`gmpy2` is a development-group dependency; install with
+`uv sync --group dev` to enable.
+
+---
+
+## Installation
+
+```bash
+# With uv (recommended)
+uv add valuebridge-tdfloat
+
+# With pip
+pip install valuebridge-tdfloat
+```
+
+For the Rust backend (optional; accelerates large-operand arithmetic):
+
+```bash
+cd tdfloat_core
+maturin develop --release
+```
+
+---
+
+## Architecture
+
+```
+  Coq specification                 proofs/*.v
+     │   HelixBit → BigInt → helix-closed arithmetic
+     ▼   (formal refinement)
+  Rust backend                      tdfloat_core/
+     │   TDBigInt { sign, Arc<[u64]> limbs } + 5 ops
+     ▼   (PyO3 boundary)
+  Python surface                    valuebridge/tdfloat/
+     │   TDFloat exact rational p/q, dot-axis encoding
+     │   math funcs, vector ops
+     ▼
+  IEEE 754 reference layer          valuebridge/tdfloat/ieee754/
+      MPFR-backed irrational constants at configurable precision
+```
+
+Each layer has one job. Each arrow is a formal refinement that preserves
+the observable behavior of the layer above it.
+
+See:
+
+- [`docs/mathematics.md`](./docs/mathematics.md) — the triadic geometry,
+  half-step encoding, NAND double helix, how all five arithmetic
+  operators are grounded in one bit-level construction.
+- [`docs/implementation.md`](./docs/implementation.md) — how the Python
+  surface, Rust backend, and Coq proofs fit together; testing,
+  benchmarks, development loop.
+
+---
+
+## Formal Verification
+
+The mathematical foundations are proved in Coq. Every `.v` file has a
+companion `.md` explaining it in prose.
+
+| Proof file                         | What it proves |
+| ---------------------------------- | -------------- |
+| `encoding_any_symbol.v`            | The abstract half-step encoding is injective and reversible |
+| `tdfloat_dot_encoding.v`           | The `"."` IS the info-bit; integer and fractional encodings never collide |
+| `tdfloat_ieee_resolution.v`        | TDFloat addition is associative; IEEE 754 addition provably is not |
+| `NANDDoubleHelix.v`                | A bit is two perpendicular strands; all gates derive from NAND |
+| `BitwiseArbitraryInt.v`            | Complete BigInt library (or/and/xor/not/shl/shr/add/mul/compare) with 10 invariants |
+| `HelixArithClosed.v`               | Subtraction (`a + ¬a + 1 ≡ 0 mod 2ⁿ`), division (shift-and-subtract with invariant), modulo |
+
+These are machine-checked proofs, not documentation claims. The Rust
+backend is a refinement of the Coq spec — its `get_bit(k)` returns the
+same value as the Coq `get_bit`, so every theorem lifts observationally.
+
+Run with:
+
+```bash
+coqc proofs/*.v
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/valuebridge-ai/tdfloat
+cd tdfloat
+
+# Python layer
+uv sync --group dev
+uv run pytest tests/ -q
+# 268 passed, 15 xfailed, 4 xpassed
+
+# Rust backend
+cd tdfloat_core
+VIRTUAL_ENV=../.venv maturin develop --release
+cargo test --release --lib
+# 27 passed; 0 failed
+
+# Benchmark Rust vs Python
+uv run python tests/bench_rust_vs_python.py
+
+# Compile proofs
+cd ../proofs
+coqc *.v
+```
+
+---
+
+## Project Layout
+
+```
+valuebridge-tdfloat/
+├── valuebridge/tdfloat/    Python surface (TDFloat, math, ieee754)
+├── tdfloat_core/           Rust backend (PyO3 + maturin)
+├── proofs/                 Coq specifications + .md explanations
+├── tests/                  pytest (268 tests) + benchmark
+├── docs/                   mathematics.md, implementation.md
+└── pyproject.toml
+```
+
+---
+
+## License
+
+MIT — Copyright 2026 Tushar Dadlani / Valuebridge AI

valuebridge_tdfloat-1.1.0/README.md

@@ -0,0 +1,234 @@
+# valuebridge-tdfloat
+
+**Triadic Dot Float (TDFloat)** — exact rational arithmetic as a single
+Python integer, with a Rust backend and Coq-verified foundations.
+
+```python
+from valuebridge.tdfloat import td, frac
+
+td('0.1') + td('0.2') == td('0.3')        # True — always
+(a + b) + c == a + (b + c)                  # True — for any a, b, c
+```
+
+---
+
+## Why This Matters for Explainable AI
+
+Modern AI systems — language models, recommendation engines, fairness
+audits, financial models — all perform millions of arithmetic operations.
+Every one of those operations runs on IEEE 754 floating-point, a format
+designed in 1985 for numerical simulation, not for systems that need to
+be explained, audited, or trusted.
+
+**TDFloat replaces floating-point approximation with provably exact
+rational arithmetic.** The consequences for explainable AI are direct.
+
+### 1. Computations Are Reproducible — Exactly
+
+IEEE 754 arithmetic is non-deterministic across platforms, compilers, and
+thread orderings. TDFloat arithmetic is deterministic by construction.
+The same inputs always produce the same output, encoded as the same
+integer. AI outputs become **auditable**: you can replay any computation
+and verify it step by step.
+
+### 2. Associativity is a Theorem, Not a Hope
+
+In IEEE 754:
+
+```
+(a + b) + c  ≠  a + (b + c)   for many values
+```
+
+Simply reordering additions in a neural network — which optimising
+compilers do routinely — can change the model's output.
+
+TDFloat's associativity is **formally proved in Coq**
+(`proofs/tdfloat_ieee_resolution.v`).
+
+### 3. Every Number Has an Interpretable Identity
+
+In IEEE 754, `3.141592653589793` is just a 64-bit pattern. In TDFloat:
+
+```python
+x = td('3.14')
+x.as_fraction()   # (157, 50)  — exact numerator and denominator
+x.info_bit        # 1          — half-step axis (has a dot)
+x.dot_pos         # 2          — two decimal places
+```
+
+Every intermediate result is fully inspectable as an exact rational.
+
+### 4. Fairness Audits Can Be Verified
+
+If two computations produce the same rational value, their encodings are
+equal. If different, provably different. There is no grey zone of "close
+enough." Fairness claims can be verified arithmetically, not just
+statistically.
+
+---
+
+## Quick Start
+
+```python
+from valuebridge.tdfloat import td, frac, TDFloat, PI, E, PHI
+from valuebridge.tdfloat.math import sqrt, circle_area, cosine_similarity
+
+# Exact arithmetic
+assert td('0.1') + td('0.2') == td('0.3')
+
+# Exact (legacy-rational) constants
+print(PI)                          # 22/7
+print(E)                           # 19/7
+print(circle_area(td(7)))         # 154 — exact integer
+
+# Exact vector similarity
+u = [td(3), td(4)]
+v = [td(4), td(3)]
+print(cosine_similarity(u, v))    # 24/25 — exact
+```
+
+### IEEE 754 / MPFR-accurate constants
+
+For numerically-accurate values of irrational constants (π, e, √2, ln 2,
+…), use the parallel `ieee754` namespace:
+
+```python
+from valuebridge.tdfloat import ieee754
+
+ieee754.PI()                      # π at 200 bits (default)
+ieee754.PI(bits=53)               # π at IEEE 754 double precision
+ieee754.E(bits=128)
+ieee754.SQRT2(bits=256)
+ieee754.LN2(bits=64)
+ieee754.EULER_GAMMA()
+```
+
+Each constant is computed by GNU MPFR (via `gmpy2`) at the requested
+precision and returned as a `TDFloat` rational approximation. The legacy
+`PI = 22/7` stays unchanged for backward compat.
+
+`gmpy2` is a development-group dependency; install with
+`uv sync --group dev` to enable.
+
+---
+
+## Installation
+
+```bash
+# With uv (recommended)
+uv add valuebridge-tdfloat
+
+# With pip
+pip install valuebridge-tdfloat
+```
+
+For the Rust backend (optional; accelerates large-operand arithmetic):
+
+```bash
+cd tdfloat_core
+maturin develop --release
+```
+
+---
+
+## Architecture
+
+```
+  Coq specification                 proofs/*.v
+     │   HelixBit → BigInt → helix-closed arithmetic
+     ▼   (formal refinement)
+  Rust backend                      tdfloat_core/
+     │   TDBigInt { sign, Arc<[u64]> limbs } + 5 ops
+     ▼   (PyO3 boundary)
+  Python surface                    valuebridge/tdfloat/
+     │   TDFloat exact rational p/q, dot-axis encoding
+     │   math funcs, vector ops
+     ▼
+  IEEE 754 reference layer          valuebridge/tdfloat/ieee754/
+      MPFR-backed irrational constants at configurable precision
+```
+
+Each layer has one job. Each arrow is a formal refinement that preserves
+the observable behavior of the layer above it.
+
+See:
+
+- [`docs/mathematics.md`](./docs/mathematics.md) — the triadic geometry,
+  half-step encoding, NAND double helix, how all five arithmetic
+  operators are grounded in one bit-level construction.
+- [`docs/implementation.md`](./docs/implementation.md) — how the Python
+  surface, Rust backend, and Coq proofs fit together; testing,
+  benchmarks, development loop.
+
+---
+
+## Formal Verification
+
+The mathematical foundations are proved in Coq. Every `.v` file has a
+companion `.md` explaining it in prose.
+
+| Proof file                         | What it proves |
+| ---------------------------------- | -------------- |
+| `encoding_any_symbol.v`            | The abstract half-step encoding is injective and reversible |
+| `tdfloat_dot_encoding.v`           | The `"."` IS the info-bit; integer and fractional encodings never collide |
+| `tdfloat_ieee_resolution.v`        | TDFloat addition is associative; IEEE 754 addition provably is not |
+| `NANDDoubleHelix.v`                | A bit is two perpendicular strands; all gates derive from NAND |
+| `BitwiseArbitraryInt.v`            | Complete BigInt library (or/and/xor/not/shl/shr/add/mul/compare) with 10 invariants |
+| `HelixArithClosed.v`               | Subtraction (`a + ¬a + 1 ≡ 0 mod 2ⁿ`), division (shift-and-subtract with invariant), modulo |
+
+These are machine-checked proofs, not documentation claims. The Rust
+backend is a refinement of the Coq spec — its `get_bit(k)` returns the
+same value as the Coq `get_bit`, so every theorem lifts observationally.
+
+Run with:
+
+```bash
+coqc proofs/*.v
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/valuebridge-ai/tdfloat
+cd tdfloat
+
+# Python layer
+uv sync --group dev
+uv run pytest tests/ -q
+# 268 passed, 15 xfailed, 4 xpassed
+
+# Rust backend
+cd tdfloat_core
+VIRTUAL_ENV=../.venv maturin develop --release
+cargo test --release --lib
+# 27 passed; 0 failed
+
+# Benchmark Rust vs Python
+uv run python tests/bench_rust_vs_python.py
+
+# Compile proofs
+cd ../proofs
+coqc *.v
+```
+
+---
+
+## Project Layout
+
+```
+valuebridge-tdfloat/
+├── valuebridge/tdfloat/    Python surface (TDFloat, math, ieee754)
+├── tdfloat_core/           Rust backend (PyO3 + maturin)
+├── proofs/                 Coq specifications + .md explanations
+├── tests/                  pytest (268 tests) + benchmark
+├── docs/                   mathematics.md, implementation.md
+└── pyproject.toml
+```
+
+---
+
+## License
+
+MIT — Copyright 2026 Tushar Dadlani / Valuebridge AI

{valuebridge_tdfloat-1.0.0 → valuebridge_tdfloat-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "valuebridge-tdfloat"
-version = "1.0.0"
+version = "1.1.0"
 description = "Triadic Dot Float — exact rational arithmetic as a single Python integer"
 readme = "README.md"
 license = "MIT"
@@ -44,4 +44,8 @@ where = ["."]
 include = ["valuebridge*"]
 
 [dependency-groups]
-dev = ["pytest>=8"]
+dev = ["pytest>=8", "gmpy2>=2.1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

{valuebridge_tdfloat-1.0.0 → valuebridge_tdfloat-1.1.0}/valuebridge/tdfloat/__init__.py

@@ -39,6 +39,7 @@ All constants are exact rationals:
 from .tdfloat import TDFloat, td, frac, divmod_td
 from . import math
 from . import constants
+from . import ieee754
 
 # Expose constants at package level
 PI    = TDFloat.PI
@@ -60,5 +61,5 @@ __all__ = [
     'TDFloat', 'td', 'frac', 'divmod_td',
     'PI', 'TAU', 'E', 'PHI', 'SQRT2', 'SQRT3', 'HALF',
     'ZERO', 'ONE', 'TWO', 'NAN', 'INF',
-    'math', 'constants',
+    'math', 'constants', 'ieee754',
 ]

valuebridge_tdfloat-1.1.0/valuebridge/tdfloat/ieee754/__init__.py

@@ -0,0 +1,37 @@
+"""
+valuebridge.tdfloat.ieee754
+===========================
+MPFR-computed reference constants in IEEE 754 / MPFR semantics.
+
+This submodule is parallel to the legacy ``valuebridge.tdfloat`` surface:
+the legacy constants stay as exact rational definitions (``PI = 22/7`` etc.)
+for backward compatibility, while this namespace exposes the mathematically
+correct irrational values at user-selectable precision, computed via GNU MPFR
+through the ``gmpy2`` binding.
+
+Usage
+-----
+    from valuebridge.tdfloat import ieee754
+
+    pi200 = ieee754.PI()          # default 200 bits
+    pi53  = ieee754.PI(bits=53)   # IEEE 754 double precision
+    area  = ieee754.PI * 5 * 5    # usable as a TDFloat-like value
+
+Dependencies
+------------
+Requires ``gmpy2`` (a Python binding for GNU MPFR/GMP). Install as a dev
+dependency; the base library remains pure-Python.
+"""
+
+from ._precision import DEFAULT_BITS
+from ._mpfr_bridge import mpfr_to_tdfloat
+from .constants import (
+    PI, TAU, E, LN2, LN10, LOG2E, LOG10E,
+    SQRT2, SQRT3, PHI, EULER_GAMMA, CATALAN,
+)
+
+__all__ = [
+    'PI', 'TAU', 'E', 'LN2', 'LN10', 'LOG2E', 'LOG10E',
+    'SQRT2', 'SQRT3', 'PHI', 'EULER_GAMMA', 'CATALAN',
+    'DEFAULT_BITS', 'mpfr_to_tdfloat',
+]

valuebridge_tdfloat-1.1.0/valuebridge/tdfloat/ieee754/_mpfr_bridge.py

@@ -0,0 +1,33 @@
+"""MPFR mpfr <-> TDFloat conversion.
+
+Uses gmpy2.f2q to extract the exact dyadic rational of an MPFR value, then
+builds a TDFloat from (numerator, denominator). gmpy2 is imported lazily so
+the base library stays pure-Python if gmpy2 is not installed.
+"""
+
+from __future__ import annotations
+
+from ..tdfloat import TDFloat
+
+
+def _require_gmpy2():
+    try:
+        import gmpy2
+    except ImportError as e:
+        raise ImportError(
+            "valuebridge.tdfloat.ieee754 requires gmpy2. "
+            "Install with: pip install gmpy2"
+        ) from e
+    return gmpy2
+
+
+def mpfr_to_tdfloat(m) -> TDFloat:
+    """Convert an MPFR value to an exact TDFloat (dyadic rational)."""
+    gmpy2 = _require_gmpy2()
+    if m.is_nan():
+        return TDFloat.NAN
+    if m.is_infinite():
+        return TDFloat.INF if m > 0 else TDFloat.NINF
+    q = gmpy2.f2q(m, 0)
+    p, d = q.numerator, q.denominator
+    return TDFloat.from_frac(int(p), int(d))

valuebridge_tdfloat-1.1.0/valuebridge/tdfloat/ieee754/_precision.py

@@ -0,0 +1,3 @@
+"""Default precision for MPFR-computed reference constants."""
+
+DEFAULT_BITS = 200