Struct GraphStore 

pub struct GraphStore { /* private fields */ }

In-memory knowledge graph supporting entities, relationships, BFS/DFS, shortest-path, weighted shortest-path, and graph analytics.

Guarantees

• Thread-safe via Arc<Mutex<_>>
• BFS/DFS are non-recursive (stack-safe)
• Shortest-path is hop-count based (BFS)
• Weighted shortest-path uses Dijkstra’s algorithm

Implementations

impl GraphStore

pub fn new() -> Self

Create a new, empty graph store.

pub fn add_entity(&self, entity: Entity) -> Result<(), AgentRuntimeError>

Add an entity to the graph.

If an entity with the same ID already exists, it is replaced.

pub fn get_entity(&self, id: &EntityId) -> Result<Entity, AgentRuntimeError>

Retrieve an entity by ID.

pub fn add_relationship( &self, rel: Relationship, ) -> Result<(), AgentRuntimeError>

Add a directed relationship between two existing entities.

Both source and target entities must already exist in the graph.

pub fn remove_entity(&self, id: &EntityId) -> Result<(), AgentRuntimeError>

Remove an entity and all relationships involving it.

pub fn bfs(&self, start: &EntityId) -> Result<Vec<EntityId>, AgentRuntimeError>

Breadth-first search starting from start.

Returns entity IDs in BFS discovery order (not including the start node).

pub fn dfs(&self, start: &EntityId) -> Result<Vec<EntityId>, AgentRuntimeError>

Depth-first search starting from start.

Returns entity IDs in DFS discovery order (not including the start node).

pub fn shortest_path( &self, from: &EntityId, to: &EntityId, ) -> Result<Option<Vec<EntityId>>, AgentRuntimeError>

Find the shortest path (by hop count) between from and to.

Returns

• Some(path) — ordered list of EntityIds from from to to (inclusive)
• None — no path exists

pub fn shortest_path_weighted( &self, from: &EntityId, to: &EntityId, ) -> Result<Option<(Vec<EntityId>, f32)>, AgentRuntimeError>

Find the shortest weighted path between from and to using Dijkstra’s algorithm.

Uses Relationship::weight as edge cost. Negative weights are not supported and will cause this method to return an error.

Returns

• Ok(Some((path, total_weight))) — the shortest path and its total weight
• Ok(None) — no path exists between from and to
• Err(...) — either entity not found, or a negative edge weight was encountered

pub fn transitive_closure( &self, start: &EntityId, ) -> Result<HashSet<EntityId>, AgentRuntimeError>

Compute the transitive closure: all entities reachable from start (including start itself).

Uses a single lock acquisition and builds the result as a HashSet directly, avoiding the intermediate Vec that would otherwise be produced by delegating to bfs.

pub fn entity_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of entities in the graph.

pub fn relationship_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of relationships in the graph.

pub fn degree_centrality( &self, ) -> Result<HashMap<EntityId, f32>, AgentRuntimeError>

Compute normalized degree centrality for each entity. Degree = (in_degree + out_degree) / (n - 1), or 0.0 if n <= 1.

pub fn betweenness_centrality( &self, ) -> Result<HashMap<EntityId, f32>, AgentRuntimeError>

Compute normalized betweenness centrality for each entity. Uses Brandes’ algorithm with hop-count BFS.

Complexity

O(V * E) time. Not suitable for very large graphs (>1000 nodes).

pub fn label_propagation_communities( &self, max_iterations: usize, ) -> Result<HashMap<EntityId, usize>, AgentRuntimeError>

Detect communities using label propagation. Each entity starts as its own community. In each iteration, each entity adopts the most frequent label among its neighbours. Returns a map of entity ID → community ID (usize).

pub fn detect_cycles(&self) -> Result<bool, AgentRuntimeError>

Detect whether the directed graph contains any cycles.

Uses iterative DFS with a three-color marking scheme. The result is cached until the next mutation (add_entity, add_relationship, or remove_entity).

Returns

• Ok(true) — at least one cycle exists
• Ok(false) — the graph is acyclic (a DAG)

pub fn path_exists( &self, from: &str, to: &str, ) -> Result<bool, AgentRuntimeError>

Return true if there is any path from from to to.

Both nodes must exist or returns Err. Uses BFS internally. Returns Ok(false) if nodes exist but are not connected.

pub fn bfs_bounded( &self, start: &str, max_depth: usize, max_nodes: usize, ) -> Result<Vec<EntityId>, AgentRuntimeError>

BFS limited by maximum depth and maximum node count.

Returns the subset of nodes visited within those limits (including start).

pub fn dfs_bounded( &self, start: &str, max_depth: usize, max_nodes: usize, ) -> Result<Vec<EntityId>, AgentRuntimeError>

DFS limited by maximum depth and maximum node count.

Returns the subset of nodes visited within those limits (including start).

pub fn subgraph( &self, node_ids: &[EntityId], ) -> Result<GraphStore, AgentRuntimeError>

Extract a subgraph containing only the specified entities and the relationships between them.

Trait Implementations

impl Clone for GraphStore

fn clone(&self) -> GraphStore

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GraphStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GraphStore

fn default() -> Self

Returns the “default value” for a type.