Metadata-Version: 2.4
Name: constraint-theory-sdk
Version: 0.1.0
Summary: Python SDK for constraint theory: H¹ cohomology, holonomy, Laman rigidity
Author-email: Cocapn <cocapn@proton.me>
License: Apache-2.0
Project-URL: Homepage, https://github.com/SuperInstance/constraint-theory-sdk
Project-URL: Repository, https://github.com/SuperInstance/constraint-theory-sdk
Keywords: constraint-theory,h1,cohomology,holonomy,laman,rigidity,emergence
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# Constraint Theory SDK

> **Python SDK for constraint theory: H¹ cohomology, holonomy, Laman rigidity**

Wraps the core mathematics from FM's constraint theory for use in fleet routing, emergence detection, and graph analysis.

[![PyPI Version](https://img.shields.io/pypi/v/constraint-theory-sdk.svg)](https://pypi.org/project/constraint-theory-sdk/)

---

## Quick Start

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

```python
from constraint_theory_sdk import compute_h1, is_emergence, is_laman_rigid, compute_holonomy

# H¹ cohomology dimension
h1 = compute_h1(n_vertices=10, n_edges=18)  # → 9
# H¹ = E - V + H0 = 18 - 10 + 1 = 9

# Check for emergence (β₁ > V-2)
if is_emergence(h1, n_vertices=10):
    print("⚠️ Emergence detected — graph is under-constrained")

# Check Laman rigidity
is_rigid, margin = is_laman_rigid(n_vertices=10, n_edges=17)
print(f"Rigid: {is_rigid}, margin: {margin}")  # Rigid: True, margin: 0

# Compute holonomy around a cycle
hol = compute_holonomy(
    edges=[("A","B"), ("B","C"), ("C","A")],
    direction=1.0  # parallel transport angle in radians
)
print(f"Holonomy: {hol:.3f} rad")  # Non-zero means curvature
```

---

## Core Mathematics

### H¹ Cohomology

For a constraint graph G = (V, E) with H₀ connected components:

```
H¹_dim = E - V + H₀
```

- **H¹ = V-2**: Laman rigid (minimally constrained, just enough to determine positions)
- **H¹ > V-2**: Under-constrained (coordination fails — emergence detected)
- **H¹ < V-2**: Over-constrained (redundant edges)

### Emergence Threshold

```
Emergence when: β₁ > V - 2
```

### Laman Rigidity

A graph is **minimally rigid** when:
- E = 2V - 3 edges
- No subgraph has more edges than 2V' - 3

### Holonomy

Holonomy measures the curvature of the connection around closed loops:

```
Holonomy = ∮ A·dx  (line integral of connection)
```

In discrete terms: multiply edge connection values around a cycle.
Non-zero holonomy means parallel transport doesn't return to original value.

---

## API Reference

### compute_h1(n_vertices, n_edges, n_components=1)

```python
from constraint_theory_sdk import compute_h1

h1 = compute_h1(n_vertices=10, n_edges=18, n_components=1)
# Returns: 9
```

### is_emergence(h1, n_vertices, offset=-2)

```python
from constraint_theory_sdk import is_emergence

if is_emergence(h1=12, n_vertices=10):
    print("⚠️ Emergence — β₁=12 > V-2=8")
```

### is_laman_rigid(n_vertices, n_edges)

```python
from constraint_theory_sdk import is_laman_rigid

is_rigid, margin = is_laman_rigid(n_vertices=10, n_edges=17)
# is_rigid = True (E = 2*10 - 3 = 17)
# margin = 0 (exactly minimal)
```

### compute_holonomy(edges, direction=1.0)

```python
from constraint_theory_sdk import compute_holonomy

# Edges: list of (node_a, node_b) pairs forming a cycle
holonomy = compute_holonomy(
    edges=[("A","B"), ("B","C"), ("C","A")],
    direction=1.0
)
```

### FleetGraph

```python
from constraint_theory_sdk import FleetGraph

graph = FleetGraph()
graph.add_nodes(["oracle1", "ccc", "forgemaster"])
graph.add_edge("oracle1", "plato-sync")
graph.add_edge("ccc", "telegram-bot")
graph.add_edge("forgemaster", "llvm-compile")

status = graph.get_status()
print(f"H¹: {status['h1_dimension']}, {status['description']}")
```

---

## Installation

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

Or from source:

```bash
git clone https://github.com/SuperInstance/constraint-theory-sdk.git
cd constraint-theory-sdk
pip install -e .
```

---

## Related Research

This SDK implements the constraint theory mathematics from:

- **FM's constraint_theory_core** ([SuperInstance/constraint-theory-core](https://github.com/SuperInstance/constraint-theory-core)) — Rust implementation with full formal proofs
- **Fleet Math Foundations** ([fleet-math-foundations](https://github.com/SuperInstance/fleet-math-foundations)) — Research documentation
- **H1 Routing** ([fleet-h1-router](https://github.com/SuperInstance/fleet-h1-router)) — Fleet routing driven by H¹ constraints

---

## Citation

If you use this SDK in research, cite:

```
Cocapn. (2026). Constraint Theory SDK.
https://github.com/SuperInstance/constraint-theory-sdk
```

Based on:
- Forgemaster's constraint theory research (SuperInstance)
- Laman, G. (1972). On graphs and the rigidity of plane skeletal structures.
- Barrett, T.W. et al. (2025). Holonomy and curvature in agent coordination frameworks.

---

## License

Apache 2.0
