exo-hypergraph 0.1.0

Hypergraph substrate for higher-order relational reasoning with persistent homology and sheaf theory
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

# exo-hypergraph

Hypergraph substrate for higher-order relational reasoning in the EXO-AI cognitive substrate.

[![Crates.io](https://img.shields.io/crates/v/exo-hypergraph.svg)](https://crates.io/crates/exo-hypergraph)
[![Documentation](https://docs.rs/exo-hypergraph/badge.svg)](https://docs.rs/exo-hypergraph)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)

## Features

- **Hyperedge Support**: Relations spanning multiple entities (not just pairwise)
- **Topological Data Analysis**: Persistent homology and Betti number computation (interface ready, full algorithms to be implemented)
- **Sheaf Theory**: Consistency checks for distributed data structures
- **Thread-Safe**: Lock-free concurrent access using DashMap

## Architecture

This crate implements the hypergraph layer as described in the EXO-AI architecture:

```
HypergraphSubstrate
├── HyperedgeIndex        # Efficient indexing for hyperedge queries
├── SimplicialComplex     # TDA structures and Betti numbers
└── SheafStructure        # Sheaf-theoretic consistency checking
```

## Usage

```rust
use exo_hypergraph::{HypergraphSubstrate, HypergraphConfig};
use exo_core::{EntityId, Relation, RelationType};

// Create hypergraph
let config = HypergraphConfig::default();
let mut hypergraph = HypergraphSubstrate::new(config);

// Add entities
let e1 = EntityId::new();
let e2 = EntityId::new();
let e3 = EntityId::new();

hypergraph.add_entity(e1, serde_json::json!({"name": "Alice"}));
hypergraph.add_entity(e2, serde_json::json!({"name": "Bob"}));
hypergraph.add_entity(e3, serde_json::json!({"name": "Charlie"}));

// Create 3-way hyperedge (beyond pairwise!)
let relation = Relation {
    relation_type: RelationType::new("collaboration"),
    properties: serde_json::json!({"project": "EXO-AI"}),
};

let hyperedge_id = hypergraph.create_hyperedge(
    &[e1, e2, e3],
    &relation
).unwrap();

// Query topology
let betti = hypergraph.betti_numbers(2);  // Get Betti numbers β₀, β₁, β₂
println!("Topological structure: {:?}", betti);
```

## Topological Queries

### Betti Numbers

Betti numbers are topological invariants that describe the structure:

- **β₀**: Number of connected components
- **β₁**: Number of 1-dimensional holes (loops)
- **β₂**: Number of 2-dimensional holes (voids)

```rust
let betti = hypergraph.betti_numbers(2);
// β₀ = connected components
// β₁ = loops (currently returns 0 - stub)
// β₂ = voids (currently returns 0 - stub)
```

### Persistent Homology (Interface Ready)

The persistent homology interface is implemented, with full algorithm to be added:

```rust
use exo_core::TopologicalQuery;

let query = TopologicalQuery::PersistentHomology {
    dimension: 1,
    epsilon_range: (0.0, 1.0),
};

let result = hypergraph.query(&query).unwrap();
// Returns persistence diagram (currently empty - stub)
```

## Implementation Status

✅ **Complete**:
- Hyperedge creation and indexing
- Entity-to-hyperedge queries
- Simplicial complex construction
- Betti number computation (β₀)
- Sheaf consistency checking
- Thread-safe concurrent access

🚧 **Stub Interfaces** (Complex algorithms, interfaces ready):
- Persistent homology computation (requires boundary matrix reduction)
- Higher Betti numbers (β₁, β₂, ...) require Smith normal form
- Filtration building for persistence

## Dependencies

- `exo-core`: Core types and traits
- `petgraph`: Graph algorithms
- `dashmap`: Concurrent hash maps
- `serde`: Serialization

## Links

- [GitHub](https://github.com/ruvnet/ruvector)
- [Website](https://ruv.io)
- [EXO-AI Documentation](https://github.com/ruvnet/ruvector/tree/main/examples/exo-ai-2025)

## License

MIT OR Apache-2.0