valuebridge-tdfloat 1.0.0

Triadic Dot Float — exact rational arithmetic as a single Python integer

valuebridge-tdfloat

Triadic Dot Float (TDFloat) — exact rational arithmetic as a single Python integer.

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:

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

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

# With uv (recommended)
uv add valuebridge-tdfloat

# With pip
pip install valuebridge-tdfloat

---

Development

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