Metadata-Version: 2.4
Name: valuebridge-tdfloat
Version: 1.0.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.

```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 even thread orderings. The same model can produce different outputs on different hardware, or after recompilation, or across NumPy versions.

TDFloat arithmetic is deterministic by construction. There is no rounding, no platform-specific behaviour, no "it worked on my machine." The same inputs always produce the same output, encoded as the same integer. This makes AI outputs **auditable**: you can replay any computation and verify it step by step.

---

### 2. Associativity is a Theorem, Not a Hope

A fundamental requirement for any system that needs to explain its reasoning is that the order of operations should not change the result. In IEEE 754, it does:

```
(a + b) + c  ≠  a + (b + c)   -- in IEEE 754, for many values of a, b, c
```

This means that simply reordering additions in a neural network — something optimising compilers do routinely — can change the model's output.

TDFloat's associativity is **formally proved in Coq** (`proofs/tdfloat_ieee_resolution.v`). It is not a property that holds approximately or usually — it is a theorem. Any system built on TDFloat inherits this guarantee.

---

### 3. Every Number Has an Interpretable Identity

In IEEE 754, numbers are opaque 64-bit patterns. `3.141592653589793` is just a bit string — you cannot read off that it approximates 22/7, or that it is an integer, or anything structural about it.

In TDFloat, every number's encoding carries explicit structural information:

- **The info-bit** (the `"."`) declares whether the number is an integer or a fractional. This is formally proved (`proofs/tdfloat_dot_encoding.v`): the dot IS the axis-selector bit. `td(3)` and `td(3.0)` are provably different kinds of numbers.
- **Constants are exact rationals**: π = 22/7, e = 19/7, φ = 3/2. Not approximations — exact fractions with an explicit numerator and denominator. A model using TDFloat constants can be inspected and its reasoning followed.
- **Every result is a fraction**: the output of any computation is always `p/q` for some integers `p` and `q`. You can always ask "what fraction did this computation produce?" and get a precise, human-readable answer.

---

### 4. Fairness Audits Can Be Verified

A core problem in algorithmic fairness is verifying that a decision-making system treats groups consistently. With IEEE 754, floating-point drift means that two computations that should be identical (same formula, different data ordering) can diverge. This makes it impossible to prove that a model's disparity between groups is real versus artefact.

With TDFloat, if two computations produce the same rational value, their encodings are equal. If they produce different rationals, their encodings are provably different. There is no grey zone of "close enough." Fairness claims can be verified arithmetically, not just statistically.

---

### 5. Intermediate Results Are Traceable

When debugging why a model made a decision, the ability to inspect intermediate values matters. A TDFloat value always exposes:

```python
x = td('3.14')
x.as_fraction()   # (157, 50)  — exact numerator and denominator
x.info_bit        # 1          — it's on the half-step axis (has a dot)
x.dot_pos         # 2          — two decimal places
x.fields()        # full encoding breakdown
```

There is no hidden rounding. Every intermediate result is fully inspectable as an exact rational.

---

## Formal Verification

The mathematical foundations of TDFloat are proved in Coq:

| Proof file | What it proves |
|---|---|
| `proofs/encoding_any_symbol.v` | The abstract half-step encoding is injective and perfectly reversible |
| `proofs/tdfloat_dot_encoding.v` | The `"."` is the info-bit; integer and fractional encodings never collide |
| `proofs/tdfloat_ieee_resolution.v` | TDFloat addition is associative; IEEE 754 addition provably is not |

These are not documentation claims. They are machine-checked mathematical proofs.

---

## 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 constants
print(PI)             # 22/7
print(E)              # 19/7
print(PHI)            # 3/2

# Exact geometry
print(circle_area(td(7)))          # 154  (exact integer)
print(circle_area(td(1)))          # 22/7 (exact π)

# Exact vector similarity
u = [td(3), td(4)]
v = [td(4), td(3)]
print(cosine_similarity(u, v))    # 24/25 (exact)
```

---

## Installation

```bash
# With uv (recommended)
uv add valuebridge-tdfloat

# With pip
pip install valuebridge-tdfloat
```

---

## Development

```bash
git clone https://github.com/valuebridge-ai/tdfloat
cd tdfloat
uv sync
uv run pytest tests/
```

---

## Architecture

```
valuebridge/tdfloat/
├── tdfloat.py      — TDFloat class: encoding, arithmetic operators, constructors
├── _encoding.py    — Half-step line: pack/unpack, from_rational, to_rational
├── _arithmetic.py  — Exact rational ops: add, sub, mul, div, sqrt, divmod
├── constants.py    — Exact constants: π=22/7, e=19/7, φ=3/2, √2=7/5, ...
└── math.py         — Functions: sqrt, exp, log, sin, cos, vector ops

proofs/
├── encoding_any_symbol.v      — Abstract half-step encoding theory
├── tdfloat_dot_encoding.v     — The dot is the info-bit (Coq)
└── tdfloat_ieee_resolution.v  — TDFloat vs IEEE 754 associativity (Coq)
```

---

## License

MIT — Copyright 2026 Tushar Dadlani / Valuebridge AI
