agenticraft_foundation.topology.hypergraph

Hypergraph topology for group coordination — incidence matrices, hypergraph Laplacian \(L_H = D_v - H W D_e^{-1} H^T\), and group coordination metrics.

Hypergraph extension for multi-agent group coordination.

Extends the graph model with hyperedges that connect >2 agents, enabling formal analysis of group communication patterns.

Hypergraph H = (V, E_h) where each hyperedge e ∈ E_h ⊆ 2^V can connect any subset of vertices.

Key features: - Hyperedge management for group coordination patterns - Hypergraph Laplacian: L_H = D_v - H W D_e^{-1} H^T - Group coordination analysis (consensus time for multi-party patterns) - Conversion from/to standard graphs

References: - Zhou et al. (2006) - Learning with Hypergraphs - Agarwal et al. (2006) - Higher Order Learning with Graphs

Hyperedge dataclass

A hyperedge connecting multiple nodes.

Unlike standard edges, a hyperedge can connect any number of nodes, modeling group communication patterns (broadcast, scatter-gather, consensus).

edge_id instance-attribute

Unique hyperedge identifier

nodes instance-attribute

Set of connected node IDs

weight = 1.0 class-attribute instance-attribute

Hyperedge weight

metadata = field(default_factory=dict) class-attribute instance-attribute

Additional edge metadata

degree property

Hyperedge degree (number of nodes it connects).

contains(node_id)

Check if a node is in this hyperedge.

HypergraphAnalysis dataclass

Results of hypergraph spectral analysis.

num_nodes instance-attribute

Number of nodes

num_hyperedges instance-attribute

Number of hyperedges

avg_hyperedge_degree instance-attribute

Average number of nodes per hyperedge

max_hyperedge_degree instance-attribute

Maximum hyperedge degree

algebraic_connectivity instance-attribute

Algebraic connectivity (λ₂) of hypergraph Laplacian

eigenvalues instance-attribute

Eigenvalues of hypergraph Laplacian

consensus_bound instance-attribute

Estimated consensus convergence time

is_connected instance-attribute

Whether the hypergraph is connected

HypergraphNetwork

Hypergraph network for group coordination analysis.

H = (V, E_h) with weighted hyperedges.

nodes property

Get all nodes.

hyperedges property

Get all hyperedges.

add_node(node_id, metadata=None)

Add a node to the hypergraph.

add_hyperedge(edge_id, nodes, weight=1.0, metadata=None)

Add a hyperedge connecting multiple nodes.

All referenced nodes must exist. Missing nodes are auto-added.

PARAMETER	DESCRIPTION
edge_id	Unique edge identifier TYPE: str
nodes	Set of node IDs to connect TYPE: set[str]
weight	Edge weight TYPE: float DEFAULT: 1.0
metadata	Additional metadata TYPE: dict[str, Any] | None DEFAULT: None

RETURNS	DESCRIPTION
Hyperedge	The created Hyperedge

remove_hyperedge(edge_id)

Remove a hyperedge.

node_degree(node_id)

Get degree of a node (number of hyperedges it belongs to).

node_weighted_degree(node_id)

Get weighted degree: sum of weights of incident hyperedges.

incident_edges(node_id)

Get hyperedges incident to a node.

neighbors(node_id)

Get all nodes connected to a node via any hyperedge.

is_connected()

Check if the hypergraph is connected via BFS.

incidence_matrix()

Compute incidence matrix H.

H[v][e] = 1 if node v is in hyperedge e, 0 otherwise.

RETURNS	DESCRIPTION
tuple[list[str], list[str], list[list[float]]]	(node_ids, edge_ids, matrix H)

laplacian_matrix()

Compute hypergraph Laplacian: L_H = D_v - H W D_e^{-1} H^T.

Where: - D_v: diagonal node degree matrix - W: diagonal hyperedge weight matrix - D_e: diagonal hyperedge degree matrix - H: incidence matrix

RETURNS	DESCRIPTION
tuple[list[str], list[list[float]]]	(node_ids, Laplacian matrix)

analyze()

Perform spectral analysis of the hypergraph.

Computes eigenvalues of the hypergraph Laplacian and derives connectivity and consensus convergence metrics.

RETURNS	DESCRIPTION
HypergraphAnalysis	HypergraphAnalysis with spectral properties

from_graph(edges, weights=None) classmethod

Create a hypergraph from a standard graph.

Each edge becomes a 2-hyperedge.

PARAMETER	DESCRIPTION
edges	List of (source, target) pairs TYPE: list[tuple[str, str]]
weights	Optional edge weights TYPE: dict[tuple[str, str], float] | None DEFAULT: None

RETURNS	DESCRIPTION
HypergraphNetwork	HypergraphNetwork with 2-hyperedges

clique_expansion(groups, weights=None) classmethod

Create a hypergraph from clique groups.

Each group of nodes becomes a hyperedge.

PARAMETER	DESCRIPTION
groups	List of node groups TYPE: list[set[str]]
weights	Optional weights per group TYPE: list[float] | None DEFAULT: None

RETURNS	DESCRIPTION
HypergraphNetwork	HypergraphNetwork

analyze_group_coordination()

Analyze group coordination patterns.

Returns metrics about how effectively the hypergraph supports multi-party coordination.