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 has_entity(&self, id: &EntityId) -> Result<bool, AgentRuntimeError>

Return true if an entity with the given id exists in the graph.

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

Return true if the graph contains at least one entity.

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

Return the number of distinct entity label strings present in the graph.

pub fn labels(&self) -> Result<Vec<String>, AgentRuntimeError>

Return the distinct entity labels present in the graph, sorted.

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

Return the number of incoming relationships for the given entity.

Returns 0 if the entity has no in-edges or does not exist.

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

Return the number of outbound edges from the given entity.

Returns 0 if the entity has no outgoing relationships.

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

Return the count of entities that have no outgoing edges (sink nodes).

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

Return the count of entity pairs (A, B) where edges exist in both directions.

Each bidirectional pair is counted once.

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

Return true if any relationship is a self-loop (from == to).

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

Return the count of entities that have no incoming edges (source nodes).

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

Return the number of entities that have no outgoing relationships.

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

Return the count of entities that have neither outgoing nor incoming relationships.

pub fn avg_relationship_weight(&self) -> Result<f64, AgentRuntimeError>

Return the mean weight of all relationships in the graph.

Returns 0.0 if no relationships have been added.

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

Return the sum of in-degrees across all entities.

Equal to the total number of relationships in the graph (each relationship contributes 1 to the in-degree of its target entity).

pub fn relationship_count_between( &self, from: &EntityId, to: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the count of directed relationships from from to to.

Returns 0 if no such relationships exist.

pub fn edges_from( &self, id: &EntityId, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all relationships originating from id, in insertion order.

Returns an empty Vec if the entity has no outgoing relationships or does not exist.

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

Return true if there is at least one directed edge from from to to.

Returns false when either entity does not exist or when no direct relationship exists between the two. To test reachability over multiple hops use reachable_from.

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

Return the EntityIds reachable from id in a single hop, sorted.

Returns an empty Vec if the entity has no outgoing relationships or does not exist.

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_relationship( &self, from: &EntityId, to: &EntityId, kind: &str, ) -> Result<(), AgentRuntimeError>

Remove a specific relationship by (from, to, kind).

Returns Err if no matching relationship exists.

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 node_count(&self) -> Result<usize, AgentRuntimeError>

Return the number of entities in the graph.

Alias for entity_count using graph-theory terminology.

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

Return the number of relationships in the graph.

pub fn average_out_degree(&self) -> Result<f64, AgentRuntimeError>

Return the average out-degree across all entities.

Returns 0.0 for an empty graph. The result is the total number of directed edges divided by the number of nodes.

pub fn in_degree_for( &self, entity_id: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the in-degree (number of incoming edges) for the given entity.

Returns 0 if the entity does not exist or has no incoming edges.

pub fn out_degree_for( &self, entity_id: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the out-degree (number of outgoing edges) for the given entity.

Returns 0 if the entity does not exist or has no outgoing edges.

pub fn predecessors( &self, entity_id: &EntityId, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have a directed edge pointing to entity_id (its predecessors in the directed graph).

Returns an empty Vec if the entity has no incoming edges or does not exist.

pub fn is_source(&self, entity_id: &EntityId) -> Result<bool, AgentRuntimeError>

Return true if the entity has no incoming edges (in-degree == 0).

In a DAG, source nodes (roots) have no predecessors. Returns false if the entity does not exist.

pub fn successors( &self, entity_id: &EntityId, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities directly reachable from entity_id via outgoing edges (its successors / immediate out-neighbors).

Returns an empty Vec if the entity has no outgoing edges or does not exist.

pub fn is_sink(&self, entity_id: &EntityId) -> Result<bool, AgentRuntimeError>

Return true if the entity has no outgoing edges (out-degree == 0).

In a DAG, sink nodes (leaves) have no successors. Returns true if the entity does not exist (unknown nodes cannot have outgoing edges).

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

Return the set of all entity IDs reachable from start via directed edges (BFS traversal). The starting node itself is not included.

Returns an empty HashSet if start has no outgoing edges or does not exist.

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

Return true if the directed graph contains at least one cycle.

Uses iterative DFS with a three-colour scheme (unvisited / in-stack / done). An empty graph is acyclic.

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

Return the number of relationships in the graph.

Alias for relationship_count using graph-theory terminology.

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

Return true if the directed graph contains no cycles.

Shorthand for !self.contains_cycle().

pub fn avg_out_degree(&self) -> Result<f64, AgentRuntimeError>

Return the mean out-degree across all entities.

Returns 0.0 for graphs with no entities.

pub fn avg_in_degree(&self) -> Result<f64, AgentRuntimeError>

Return the mean in-degree across all entities.

Returns 0.0 for graphs with no entities.

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

Return the maximum out-degree across all entities, or 0 for empty graphs.

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

Return the maximum in-degree across all entities, or 0 for empty graphs.

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

Return the minimum out-degree across all entities, or 0 for empty graphs.

This counts only entities that are registered in the graph. An entity with no outgoing edges has out-degree 0 and contributes to the minimum.

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

Return the minimum in-degree across all entities, or 0 for empty graphs.

An entity with no incoming edges has in-degree 0 and contributes to the minimum. Source nodes (those with no predecessors) always have in-degree 0.

pub fn relationship_kinds_from( &self, id: &EntityId, ) -> Result<Vec<String>, AgentRuntimeError>

Return the distinct relationship kinds that originate from id, sorted lexicographically.

Returns an empty Vec if the entity has no outgoing edges or does not exist.

pub fn weight_stats(&self) -> Result<Option<(f64, f64, f64)>, AgentRuntimeError>

Return (min_weight, max_weight, mean_weight) across all relationships.

Returns None if the graph has no relationships.

pub fn isolated_nodes(&self) -> Result<HashSet<EntityId>, AgentRuntimeError>

Return the set of entity IDs that have no inbound and no outbound edges.

An isolated node is one that does not appear as a from or to endpoint in any relationship. Useful for detecting orphaned entities.

pub fn sum_edge_weights(&self) -> Result<f64, AgentRuntimeError>

Return the sum of all relationship weights in the graph.

Returns 0.0 for graphs with no relationships.

pub fn entity_ids(&self) -> Result<Vec<EntityId>, AgentRuntimeError>

Return all entity IDs in the graph without allocating full Entity objects.

Cheaper than all_entities when only IDs are needed.

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

Return true if the graph contains no entities.

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

Remove all entities and relationships from the graph.

After this call entity_count() and relationship_count() both return 0.

pub fn entity_count_by_label( &self, label: &str, ) -> Result<usize, AgentRuntimeError>

Count entities whose label equals label (case-sensitive).

pub fn graph_density(&self) -> Result<f64, AgentRuntimeError>

Compute the directed graph density: |E| / (|V| × (|V| − 1)).

Returns 0.0 for graphs with fewer than two entities (no edges possible). A density of 1.0 means every possible directed edge is present.

pub fn entity_labels(&self) -> Result<Vec<String>, AgentRuntimeError>

Return all distinct entity label strings present in the graph, sorted.

pub fn relationship_kinds(&self) -> Result<Vec<String>, AgentRuntimeError>

Return all distinct relationship kind strings present in the graph, sorted.

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

Return the number of distinct relationship kind strings present in the graph.

pub fn entities_with_self_loops( &self, ) -> Result<Vec<EntityId>, AgentRuntimeError>

Return the EntityIds of entities that have at least one self-loop relationship.

A self-loop is a relationship where from == to.

pub fn update_entity_label( &self, id: &EntityId, new_label: impl Into<String>, ) -> Result<bool, AgentRuntimeError>

Update the label of an existing entity in-place.

Returns Ok(true) if the entity was found and updated, Ok(false) if not found.

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 topological_sort(&self) -> Result<Vec<EntityId>, AgentRuntimeError>

Compute a topological ordering of all entities.

Returns the entities sorted so that for every directed edge (A → B), A appears before B in the result. Uses iterative DFS (post-order).

Errors

Returns Err(AgentRuntimeError::Graph(...)) if the graph contains a cycle.

pub fn update_entity_property( &self, id: &EntityId, key: impl Into<String>, value: Value, ) -> Result<bool, AgentRuntimeError>

Update a single property on an existing entity.

Returns Ok(true) if the entity was found and updated, Ok(false) otherwise.

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

Return true if the graph is a DAG (directed acyclic graph).

Equivalent to !detect_cycles() but reads more naturally in condition expressions.

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

Count the number of weakly connected components in the graph.

Treats all edges as undirected for component assignment. Isolated nodes (no edges) each count as their own component. Uses Union-Find.

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

Return true if the graph is weakly connected (i.e. has at most one connected component when all edges are treated as undirected).

An empty graph is considered weakly connected by convention.

Errors

Propagates any lock-poisoning error from [connected_components].

pub fn sink_nodes(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no outgoing edges (out-degree == 0).

In a DAG these are the leaf nodes. Useful for identifying terminal states in a workflow or dependency graph.

pub fn source_nodes(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no incoming edges (in-degree == 0).

In a DAG these are the root nodes. Useful for finding entry points in a workflow or dependency graph.

pub fn isolates(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no edges (neither incoming nor outgoing).

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

Return the number of outgoing edges (out-degree) for id.

Returns 0 if the entity has no outgoing edges or does not exist.

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

Return the number of incoming edges (in-degree) for id.

Uses the reverse adjacency index for O(in-degree) lookup.

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

Return the total degree (in-degree + out-degree) for entity id.

Returns 0 for unknown entities. Self-loops are counted once in each direction (so they contribute 2 to the total degree).

pub fn entity_property_keys( &self, id: &EntityId, ) -> Result<Vec<String>, AgentRuntimeError>

Return the sorted property keys for entity id.

Returns an empty Vec if the entity has no properties or does not exist.

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 shortest_path_length( &self, from: &EntityId, to: &EntityId, ) -> Result<Option<usize>, AgentRuntimeError>

Return the hop-count of the shortest path from from to to.

Returns Some(hops) if a path exists, None if the nodes are disconnected. Both node IDs must exist or returns Err.

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 all_entities(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities in the graph.

pub fn all_relationships(&self) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all relationships in the graph.

pub fn find_relationships_by_kind( &self, kind: &str, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all relationships whose kind matches kind (case-sensitive).

pub fn count_relationships_by_kind( &self, kind: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of relationships whose kind matches kind (case-sensitive).

pub fn find_entities_by_label( &self, label: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose label matches label (case-sensitive).

pub fn find_entities_by_labels( &self, labels: &[&str], ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose label is contained in labels.

Order of results is unspecified. An empty labels slice returns an empty result (never all entities).

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

Remove all isolated entities (those with no incoming or outgoing edges).

Returns the number of entities removed.

pub fn get_relationships_for( &self, id: &EntityId, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all outgoing relationships from id (those where id is the source).

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

Return all relationships where both endpoints are from and to (any direction or kind).

pub fn find_entities_by_property( &self, key: &str, expected: &Value, ) -> Result<Vec<Entity>, AgentRuntimeError>

Find entities that have a property key whose value equals expected.

Uses serde_json::Value equality; for string properties pass serde_json::Value::String(...).

pub fn merge(&self, other: &GraphStore) -> Result<(), AgentRuntimeError>

Merge another GraphStore into this one.

Entities are inserted (or replaced if the same ID exists); relationships are inserted only if the (from, to, kind) triple does not already exist.

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

Return the Entity objects for all direct out-neighbors of id.

Neighbors are the targets of all outgoing relationships from id. Entities that no longer exist (orphan edge targets) are silently skipped.

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

Return the IDs of all directly reachable neighbours from id (i.e. the to end of every outgoing relationship).

Cheaper than neighbor_entities when only IDs are needed.

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

Remove all relationships where id is the source (outgoing edges).

Also updates the adjacency index. Does not remove incoming edges from other nodes that point to id — use this before remove_entity to ensure consistent graph state.

Returns the number of relationships removed.

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

Check whether an entity with the given ID exists.

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

Check whether a relationship (from, to, kind) exists.

Uses the adjacency index (O(out-degree of from)) rather than a full O(|E|) scan over all relationships.

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

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

pub fn reverse(&self) -> Result<GraphStore, AgentRuntimeError>

Return a new graph with all edge directions reversed.

Every relationship A → B becomes B → A in the returned graph. All entities are copied; relationship weights and kinds are preserved.

pub fn common_neighbors( &self, a: &EntityId, b: &EntityId, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return entities that are out-neighbors of both a and b.

Useful for link-prediction and community detection heuristics. Returns an empty Vec if either node has no outgoing edges.

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

Return the weight of the first relationship from from to to.

Returns None if no such edge exists.

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

Return the IDs of all entities that have an outgoing edge pointing to id.

This is the inverse of neighbor_entities, which returns out-neighbors. Returns an empty Vec if no incoming edges exist for id.

pub fn density(&self) -> Result<f64, AgentRuntimeError>

Return the graph density: edges / (nodes * (nodes − 1)) for a directed graph.

Returns 0.0 when the graph has fewer than 2 nodes (no directed edges are possible). Values range from 0.0 (sparse) to 1.0 (complete).

pub fn avg_degree(&self) -> Result<f64, AgentRuntimeError>

Return the average out-degree across all nodes.

Returns 0.0 for an empty graph.

pub fn total_weight(&self) -> Result<f32, AgentRuntimeError>

Return the sum of all edge weights in the graph.

Returns 0.0 for an empty graph or a graph with no relationships.

pub fn max_edge_weight(&self) -> Result<Option<f32>, AgentRuntimeError>

Return the maximum edge weight, or None if the graph has no edges.

pub fn min_edge_weight(&self) -> Result<Option<f32>, AgentRuntimeError>

Return the minimum edge weight, or None if the graph has no edges.

pub fn top_n_by_out_degree( &self, n: usize, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return the top-N entities by out-degree (most outgoing edges first).

If n == 0 or the graph is empty, returns an empty Vec. Ties are broken by arbitrary hash-map iteration order.

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

Remove id and all relationships where it is the source or target.

Equivalent to calling remove_entity and remove_all_relationships_for in a single lock acquisition, avoiding two separate look-ups.

Returns Ok(()) if the entity was found and removed. Returns Err(AgentRuntimeError::Graph) if no entity with that ID exists.

pub fn hub_nodes( &self, threshold: usize, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose out-degree is at or above threshold.

Useful for finding hub or gateway nodes in a knowledge graph.

pub fn incident_relationships( &self, entity_id: &EntityId, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all relationships incident to entity_id (where the entity is either the source or the target).

pub fn max_out_degree_entity(&self) -> Result<Option<Entity>, AgentRuntimeError>

Return the entity with the highest out-degree (most outgoing edges), or None if the graph is empty.

If multiple entities share the maximum out-degree, the first one encountered (in arbitrary hash-map iteration order) is returned.

pub fn max_in_degree_entity(&self) -> Result<Option<Entity>, AgentRuntimeError>

Return the entity with the most incoming edges (highest in-degree).

Uses the reverse adjacency index for O(V) computation. Returns None for an empty graph or a graph with no edges.

pub fn leaf_nodes(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities with out-degree = 0 (no outgoing edges).

Leaf nodes (also called sink nodes in directed graphs) are entities that have no outgoing relationships. See also sink_nodes which also counts nodes with no outgoing edges but filters differently.

pub fn top_nodes_by_out_degree( &self, n: usize, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return the top n entities sorted by out-degree (descending).

Uses the adjacency index for O(V log V) computation. Useful for finding hub nodes — entities with the most outgoing connections. Returns fewer than n entities if the graph has fewer nodes.

pub fn top_nodes_by_in_degree( &self, n: usize, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return the top n entities sorted by in-degree (descending).

Uses the reverse adjacency index for O(V log V) computation. Useful for finding sink hubs — entities with the most incoming connections.

pub fn relationship_type_counts( &self, ) -> Result<HashMap<String, usize>, AgentRuntimeError>

Return a map of relationship type label → count across the entire graph.

Useful for understanding the composition of a knowledge graph at a glance. Returns an empty map when the graph has no relationships.

pub fn entities_without_property( &self, key: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that do not have a property with key.

Useful for finding incomplete nodes that need a required attribute filled in before they can participate in downstream graph queries.

pub fn unique_relationship_types( &self, ) -> Result<Vec<String>, AgentRuntimeError>

Return a sorted, deduplicated list of all relationship type labels present in the graph.

Returns an empty Vec when the graph has no relationships.

pub fn avg_property_count(&self) -> Result<f64, AgentRuntimeError>

Return the average number of properties per entity.

Returns 0.0 when the graph is empty.

pub fn property_key_frequency( &self, ) -> Result<HashMap<String, usize>, AgentRuntimeError>

Return a map of property key → number of entities that have that key.

Useful for auditing schema coverage: a key that appears on all entities has count == entity_count; a key that appears on only one entity may indicate a one-off annotation.

Returns an empty map when the graph has no entities or no entity has any properties.

pub fn entities_sorted_by_label(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities sorted ascending by their label string.

Entities with the same label are ordered by their ID for a stable, fully deterministic output regardless of internal hash-map iteration order.

pub fn entities_with_property( &self, key: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have the given property key, regardless of value.

Returns an empty Vec when no entities carry the key or the graph is empty.

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

Return the total number of directed edges stored in this graph.

Each relationship contributes exactly one edge to this count, so a bidirectional pair of relationships contributes two.

pub fn path_to_string( &self, path: &[EntityId], ) -> Result<String, AgentRuntimeError>

Format a slice of EntityIds as a human-readable path string.

Each ID is rendered using its label if the entity exists in the store, otherwise the raw ID string is used. Nodes are joined with →.

Returns an empty String for an empty path slice.

Example

"Alice → Bob → Carol"

pub fn relationships_of_kind( &self, kind: &str, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all relationships whose kind equals kind (case-sensitive).

Returns an empty Vec when no relationships of that kind exist.

pub fn entities_without_label( &self, label: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose label does not equal label.

Useful for filtering out a specific entity type without loading all entities first. Returns all entities for an empty graph.

pub fn entities_without_outgoing( &self, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no outgoing edges (out-degree == 0).

Entities that appear only as relationship targets, or entities with no relationships at all, are included.

pub fn entities_without_incoming( &self, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no incoming edges (in-degree == 0).

These are entities that no other entity points to — i.e., root / source nodes in the directed graph.

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

Return the total out-degree of the graph — the sum of the number of outgoing edges across all entities.

Equivalent to total_relationship_count but traverses the adjacency list directly without accessing the reverse index.

pub fn relationships_with_weight_above( &self, threshold: f32, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all relationships whose weight is strictly greater than threshold.

Returns an empty Vec when the graph has no relationships or none exceeds the threshold.

pub fn entity_with_most_properties( &self, ) -> Result<Option<Entity>, AgentRuntimeError>

Return the entity with the most properties, or None for an empty graph.

When multiple entities share the maximum property count the one whose ID sorts first lexicographically is returned for deterministic output.

pub fn avg_weight(&self) -> Result<Option<f64>, AgentRuntimeError>

Return the arithmetic mean weight across all relationships, or None if the graph has no relationships.

pub fn entity_count_with_label( &self, label: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of entities whose label matches label exactly.

Returns 0 when no entities carry that label.

pub fn edge_count_above_weight( &self, threshold: f32, ) -> Result<usize, AgentRuntimeError>

Return the count of directed edges whose weight is strictly above threshold.

Unlike relationships_with_weight_above this performs a lightweight count-only scan without cloning relationship data.

pub fn entities_with_label_prefix( &self, prefix: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose label starts with prefix.

Returns an empty Vec when no entities match or the graph is empty.

pub fn bidirectional_pairs( &self, ) -> Result<Vec<(EntityId, EntityId)>, AgentRuntimeError>

Return entity-ID pairs (a, b) where both a → b and b → a edges exist.

Each bidirectional pair appears exactly once, ordered so that a < b lexicographically.

pub fn mean_in_degree(&self) -> Result<f64, AgentRuntimeError>

Return the mean in-degree across all entities in the graph.

Computed as total_relationships / entity_count. Returns 0.0 when the graph has no entities.

pub fn entity_count_by_label_prefix( &self, prefix: &str, ) -> Result<usize, AgentRuntimeError>

Return the count of entities whose label starts with prefix.

Returns 0 when no entities match or the graph is empty.

pub fn relationship_weight_sum(&self) -> Result<f32, AgentRuntimeError>

Return the sum of all relationship weights in the graph.

Returns 0.0 for an empty graph or when there are no relationships.

pub fn label_frequency( &self, ) -> Result<HashMap<String, usize>, AgentRuntimeError>

Return a frequency map of entity label → count.

Returns an empty map for an empty graph.

pub fn entities_sorted_by_id(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities sorted ascending by their ID string.

Provides a stable, deterministic ordering that is independent of internal HashMap iteration order. Returns an empty Vec for an empty graph.

pub fn entities_with_label_containing( &self, substr: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose label contains substr as a substring.

Case-sensitive. Useful for filtering entities by a partial label token (e.g. "Person" substring matches "PersonA" and "PersonB"). Returns an empty Vec for an empty graph or when no label matches.

pub fn entity_neighbor_count( &self, entity_id: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the number of outgoing neighbors (out-degree) for entity_id.

Returns 0 if the entity has no outgoing edges or does not exist.

pub fn entity_labels_sorted(&self) -> Result<Vec<String>, AgentRuntimeError>

Return all unique entity labels in alphabetical order.

Deduplicates labels so each label appears only once. Returns an empty Vec for an empty graph.

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

Return the number of unique relationship (edge) types in the graph.

Counts distinct kind values across all relationships. Returns 0 for an empty graph.

pub fn entities_with_exact_label( &self, label: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose label exactly matches label (case-sensitive).

Unlike entities_with_label_containing this performs an exact match. Returns an empty Vec for an empty graph or when no entity matches.

pub fn entity_ids_sorted(&self) -> Result<Vec<EntityId>, AgentRuntimeError>

Return all entity IDs present in the graph, sorted alphabetically.

Returns an empty Vec for an empty graph.

pub fn relationship_count_for( &self, entity_id: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the number of outgoing relationships from entity_id.

Returns 0 for an unknown entity or one with no outgoing edges.

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

Return true if there is at least one directed edge from from to to.

Returns false when either entity is unknown.

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

Return all entity IDs reachable from start via directed edges (breadth-first), excluding start itself.

Returns an empty Vec when start is unknown or has no outgoing edges.

pub fn average_weight(&self) -> Result<f64, AgentRuntimeError>

Return the average relationship weight across all edges in the graph.

Returns 0.0 when the graph has no edges.

pub fn max_weight(&self) -> Result<Option<f64>, AgentRuntimeError>

Return the maximum relationship weight in the graph, or None if there are no edges.

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

Return the weight of the first edge from from to to, or None if no such edge exists.

pub fn total_relationship_weight(&self) -> Result<f64, AgentRuntimeError>

Return the sum of all relationship weights in the graph.

Returns 0.0 for a graph with no edges.

pub fn avg_weight_for_kind(&self, kind: &str) -> Result<f64, AgentRuntimeError>

Return the average weight of all edges with the given relationship kind.

Returns 0.0 when no edges of that kind exist.

pub fn entity_degree_ratio( &self, entity_id: &EntityId, ) -> Result<f64, AgentRuntimeError>

Return the ratio of out-degree to total entity count for entity_id.

Returns 0.0 when the graph is empty or the entity has no outgoing edges.

pub fn nodes_with_no_outgoing(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose out-degree is at least min_degree. Return all entities that have zero outgoing edges (sink nodes).

Returns an empty Vec for an empty graph.

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

Return the in-degree of the entity with the given id — the number of relationships whose to field equals id.

Returns 0 when the entity has no incoming edges or does not exist.

pub fn total_weight_for_kind( &self, kind: &str, ) -> Result<f64, AgentRuntimeError>

Return the sum of weights of all relationships whose kind equals the given string.

Returns 0.0 when no relationships of that kind exist.

pub fn entity_ids_with_label( &self, label: &str, ) -> Result<Vec<EntityId>, AgentRuntimeError>

Return the EntityIds of all entities with the given label.

Returns an empty Vec when no matching entities exist.

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

Return the number of distinct entity labels currently in the graph.

pub fn entities_with_property_key( &self, property_key: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have the given property_key set in their properties map.

pub fn entity_properties_count( &self, property_key: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of entities that have the given property_key set.

pub fn edges_to( &self, id: &EntityId, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Returns all relationships that point to the entity with the given id.

pub fn entity_has_property_value( &self, id: &EntityId, key: &str, value: &str, ) -> Result<bool, AgentRuntimeError>

Returns true if the entity’s property key equals value (string comparison).

pub fn relationships_from( &self, id: &EntityId, ) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all outgoing Relationships from the entity with the given id.

Returns an empty Vec when the entity has no outgoing edges or does not exist.

pub fn entities_with_min_out_degree( &self, min_degree: usize, ) -> Result<Vec<Entity>, AgentRuntimeError>

Entities with no outgoing edges have an out-degree of 0 and are excluded unless min_degree is 0. Returns an empty Vec for an empty graph.

pub fn entities_with_min_in_degree( &self, min_degree: usize, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities whose in-degree is at least min_degree.

In-degree is the number of relationships that target the entity. Returns an empty Vec when no entity satisfies the threshold.

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

Return the total number of properties across all entities in the graph.

Counts every key-value pair in every entity’s property map. Returns 0 for an empty graph or when no entity carries any properties.

pub fn entities_with_no_properties( &self, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no properties.

Useful for identifying bare “stub” nodes that have not yet been annotated.

pub fn weight_above_threshold_ratio( &self, threshold: f32, ) -> Result<f64, AgentRuntimeError>

Return the fraction of relationships whose weight is strictly greater than threshold.

Returns 0.0 when the graph has no relationships.

pub fn entities_sorted_by_out_degree( &self, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities sorted by out-degree in descending order.

Entities with the most outgoing relationships appear first. Ties are broken by entity ID in ascending lexicographic order.

pub fn entity_by_label( &self, label: &str, ) -> Result<Option<Entity>, AgentRuntimeError>

Return the first entity whose label exactly matches label, or None.

When multiple entities share the same label the returned entity is arbitrary (HashMap iteration order). Returns None for an empty graph.

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

Return the number of distinct relationship kinds (types) in the graph.

Returns 0 for an empty graph or one with no relationships.

pub fn has_entity_with_label( &self, label: &str, ) -> Result<bool, AgentRuntimeError>

Return true if at least one entity in the graph has label as its label.

Returns false for an empty graph.

pub fn min_weight(&self) -> Result<Option<f32>, AgentRuntimeError>

Return the minimum edge weight across all relationships, or None if the graph has no relationships.

pub fn relationships_of_kind_count( &self, kind: &str, ) -> Result<usize, AgentRuntimeError>

Return the number of relationships whose kind field matches kind exactly (case-sensitive).

Returns 0 when no relationships of that kind exist or the graph is empty.

pub fn relationship_count_for_entity( &self, entity_id: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the number of outgoing relationships from entity_id.

Returns 0 when the entity has no outgoing edges or does not exist.

pub fn entities_by_label( &self, label: &str, ) -> Result<Vec<EntityId>, AgentRuntimeError>

Return the IDs of all entities whose label matches the given string.

Returns an empty Vec when no entity with that label exists.

pub fn edge_count_between( &self, from_id: &EntityId, to_id: &EntityId, ) -> Result<usize, AgentRuntimeError>

Return the number of edges from from_id that point to to_id.

Returns 0 when either entity does not exist or no such edge is found.

pub fn is_connected( &self, from_id: &EntityId, to_id: &EntityId, ) -> Result<bool, AgentRuntimeError>

Return true if there is at least one direct edge from from_id to to_id.

Returns false when either entity does not exist or no direct edge is found.

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

Return true if the graph contains no entities and no relationships.

pub fn unique_relationship_kinds( &self, ) -> Result<Vec<String>, AgentRuntimeError>

Return a sorted list of all unique relationship kinds present in the graph.

Returns an empty Vec for a graph with no relationships.

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

Return true if the graph has at least one relationship.

pub fn avg_edge_weight(&self) -> Result<f64, AgentRuntimeError>

Return the average weight across all relationships in the graph.

Returns 0.0 for a graph with no relationships.

pub fn entities_with_incoming(&self) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have at least one incoming relationship (in-degree ≥ 1).

Complements entities_without_incoming. Returns an empty Vec for a graph with no relationships.

pub fn entities_with_no_relationships( &self, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return all entities that have no outgoing relationships in the graph.

These are “sink” nodes — they may still have incoming edges from other entities but emit none themselves.

pub fn total_edge_weight(&self) -> Result<f64, AgentRuntimeError>

Return the sum of all edge weights in the graph.

Returns 0.0 for a graph with no relationships.

pub fn entity_with_max_out_degree( &self, ) -> Result<Option<Entity>, AgentRuntimeError>

Return the entity with the highest out-degree (most outgoing edges).

Returns None for an empty graph. When multiple entities share the maximum degree the first one encountered is returned.

pub fn self_loops(&self) -> Result<Vec<Relationship>, AgentRuntimeError>

Return all self-loop relationships — where the from entity and the to entity are the same.

Returns an empty Vec when no self-loops exist.

pub fn entities_with_label_and_property( &self, label: &str, key: &str, ) -> Result<Vec<Entity>, AgentRuntimeError>

Return entities that have the given label and have a property with key key.

Returns an empty Vec when no entity matches both criteria.

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

Return true if the entity identified by id has at least one outgoing edge in the adjacency list.

Returns false for unknown entity IDs as well as for nodes with no outgoing relationships.

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

Return the number of distinct nodes that have at least one self-loop (i.e. an edge from a node to itself).

Complements GraphStore::self_loops which returns the full list of self-loop relationships.

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

Return the total number of self-loop edges in the graph — relationships where from == to.

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

Return the out-degree (number of outgoing edges) for a specific entity.

Returns 0 for unknown entity IDs. Complements GraphStore::in_degree_of which counts incoming edges.

pub fn has_relationship_with_kind( &self, kind: &str, ) -> Result<bool, AgentRuntimeError>

Return true if the graph contains at least one relationship with the given kind.

A cheaper alternative to GraphStore::relationships_of_kind_count when a boolean answer is sufficient.

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

Return true if every entity in the graph has at least one entry in its properties map.

Returns true vacuously when the graph contains no entities.

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.