Metadata-Version: 2.4
Name: constraint-theory
Version: 0.1.0
Summary: Deterministic manifold snapping — maps continuous vectors to exact Pythagorean coordinates
Author-email: SuperInstance Fleet <fleet@cocapn.ai>
License: MIT
Project-URL: Homepage, https://github.com/SuperInstance/constraint-theory-core
Project-URL: Repository, https://github.com/SuperInstance/constraint-theory-core
Keywords: constraint-theory,pythagorean,manifold,snapping,deterministic,geometry
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# constraint-theory

Deterministic manifold snapping — maps continuous vectors to exact Pythagorean coordinates.

Part of the [PLATO framework](https://github.com/SuperInstance) — deterministic AI knowledge management through tile-based architecture.

For the high-performance Rust implementation, see [constraint-theory-core on crates.io](https://crates.io/crates/constraint-theory-core).

## Installation

```bash
pip install constraint-theory
```

## Usage

```python
from constraint_theory import PythagoreanManifold, find_pythagorean_triples

m = PythagoreanManifold(density=100)

# Snap continuous vector to exact Pythagorean coordinates
point = m.snap((1.414, 0.707))
print(point)  # (3, 1) — on 3^2 + 1^2 = 10

# Verify it's a real Pythagorean triple
print(m.is_pythagorean(3, 1))  # True

# Zero drift — snap the same vector a million times, always the same result
print(m.drift_test(10000))  # 0.0

# Generate all triples up to max_side
triples = find_pythagorean_triples(100)
print(len(triples))  # 52 distinct triples
```

## The Core Insight

Float arithmetic drifts. After 1 billion operations, float error reaches 29,666.

Constraint theory trades continuous precision for discrete exactness. By snapping vectors to Pythagorean coordinates — points where a² + b² = c² exactly — we get:

- **Zero drift**: Same input, same output, every machine, every time
- **4% faster**: 9,875 vs 9,433 million vector operations per second
- **93.8% perfectly idempotent**: Worst-case drift bounded at 0.000112
- **2,780 distinct directions** in 2D with sides < 1000 (11.4 bits of precision)

Zero external dependencies. Compatible with Python 3.8+.

[GitHub](https://github.com/SuperInstance/constraint-theory-core) · [crates.io](https://crates.io/crates/constraint-theory-core)
