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.

---

Quick Start

pip install constraint-theory-sdk

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)

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)

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)

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)

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

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

pip install constraint-theory-sdk

Or from source:

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) — Rust implementation with full formal proofs
• Fleet Math Foundations (fleet-math-foundations) — Research documentation
• H1 Routing (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