Struct KnowledgeGraph 

pub struct KnowledgeGraph { /* private fields */ }

Implementations

impl KnowledgeGraph

pub fn new(path: &Path) -> Result<Self>

pub const fn interner(&self) -> &StringInterner

pub fn get_entity(&self, name: &str) -> Option<Entity>

Return a single entity by exact name match.

pub fn graph_stats(&self) -> Value

Return aggregate statistics about the graph.

pub fn search_relations( &self, from: Option<&str>, to: Option<&str>, rtype: Option<&str>, ) -> Vec<Relation>

Search relations by optional filters: from, to, relationType. Any filter that is absent matches everything. A filter value that does not exist in the graph returns empty results.

pub fn find_path(&self, from: &str, to: &str) -> Result<Vec<String>>

BFS shortest-path between two entity names. Returns the sequence of entity names along the path (inclusive of both endpoints).

pub fn compact(&mut self) -> Result<()>

Rewrite the binary log from the current in-memory state. After compaction the log contains only the minimal set of records needed to reconstruct the graph (all creates, no deletes). Crash-safe: writes to a temp file, then atomically renames (C3).

pub fn create_entities(&mut self, entities: &[Entity]) -> Result<Vec<Entity>>

pub fn create_relations( &mut self, relations: &[Relation], ) -> Result<Vec<Relation>>

pub fn add_observations( &mut self, entity_name: &str, contents: &[String], ) -> Result<Vec<String>>

pub fn delete_entities(&mut self, entity_names: &[String]) -> Result<()>

pub fn delete_observations( &mut self, entity_name: &str, observations: &[String], ) -> Result<()>

pub fn delete_relations(&mut self, relations: &[Relation]) -> Result<()>

pub fn read_graph(&self) -> KnowledgeGraphOut

pub fn read_graph_view(&self) -> GraphView<'_>

Borrowing, allocation-light view of the full graph (M6). Serializing it streams interned &str directly instead of materializing a String per name/type/observation.

pub fn search_nodes(&self, query: &str) -> KnowledgeGraphOut

Relevance-ranked substring search returning all matches (no pagination). Equivalent to search_nodes_filtered(query, None, 0, usize::MAX).

pub fn open_nodes(&self, names: &[String]) -> KnowledgeGraphOut

pub fn open_nodes_view(&self, names: &[String]) -> GraphView<'_>

Borrowing view variant of [open_nodes] (M6).

pub fn entity_type_counts(&self) -> Vec<(String, usize)>

Tally distinct entity types and their live-entity counts, ranked by count descending (ties broken by name). One linear pass over the dense slot vec; only the final names are allocated.

pub fn relation_type_counts(&self) -> Vec<(String, usize)>

Tally distinct relation types and their counts, ranked by count desc.

pub fn search_nodes_filtered( &self, query: &str, entity_type: Option<&str>, offset: usize, limit: usize, ) -> KnowledgeGraphOut

Relevance-ranked, optionally type-filtered, paginated node search. Entities come back best-match-first (see SearchIndex::search_ranked). Relations touching any returned entity (either endpoint) are included.

pub fn search_nodes_view( &self, query: &str, entity_type: Option<&str>, offset: usize, limit: usize, ) -> GraphView<'_>

Borrowing view variant of [search_nodes_filtered] (M6).

pub fn read_graph_filtered( &self, entity_type: Option<&str>, offset: usize, limit: usize, ) -> KnowledgeGraphOut

Type-filtered, paginated view of the whole graph. Unlike [read_graph], relations are restricted to those whose both endpoints fall in the returned entity page, so the slice is internally consistent.

pub fn read_graph_filtered_view( &self, entity_type: Option<&str>, offset: usize, limit: usize, ) -> GraphView<'_>

Borrowing view variant of [read_graph_filtered] (M6).

pub fn neighbors( &self, name: &str, direction: Direction, rtype: Option<&str>, depth: u32, ) -> Result<KnowledgeGraphOut>

Neighborhood expansion around name out to depth hops, following edges in the requested Direction and (optionally) of one relation type. Returns the origin plus reached entities, and every relation (passing the type filter) whose endpoints are both inside that set.

depth == 1 (the common case) is a single linear pass over the flat relation vec; deeper queries build an adjacency map once (O(E)) and BFS.

pub fn describe_entity(&self, name: &str) -> Result<Value>

One-shot context bundle for a single entity: the entity itself, every incident relation, its distinct neighbor names, and its degree. Saves an agent the get_entity + two search_relations round-trips.

pub fn upsert_entities(&mut self, entities: &[Entity]) -> Result<Vec<Value>>

Create-or-merge a batch of entities idempotently. Missing entities are created; existing ones keep their type and gain any new observations (deduplicated). Returns a per-entity outcome. The caller is responsible for flushing — every underlying op is already write-ahead logged.

pub fn export(&self, format: &str) -> Result<String>

Serialize the graph in one of: json (read_graph), mermaid, dot.

pub fn merge_entities(&mut self, source: &str, target: &str) -> Result<Value>

Merge source entity into target entity. All observations from source are moved to target (deduplicated), all relations involving source are redirected to target (deduplicated), and source is then deleted.

The whole merge is atomic: every sub-record is written to the log inside a single TxnBegin…TxnCommit transaction before any in-memory mutation. A failed or torn write therefore leaves both memory and the log untouched (an uncommitted transaction is discarded on replay), so the graph can never observe a half-applied merge. Caller flushes.

pub fn extract_subgraph( &self, names: &[String], depth: u32, ) -> Result<KnowledgeGraphOut>

Extract a connected subgraph around one or more seed entity names, expanding out to depth hops along all relations (undirected). Returns the set of reached entities and the relations among them.

pub fn batch_get_entities(&self, names: &[String]) -> Vec<Option<Entity>>

Return full entities for a list of names. Missing names yield None.

pub fn find_all_paths( &self, from: &str, to: &str, max_depth: usize, max_paths: usize, ) -> Result<Vec<Vec<String>>>

Find all simple paths between from and to up to max_depth hops, returning at most max_paths results. Paths are found via DFS with backtracking and include both endpoints.

pub fn snapshot(&self) -> ReadSnapshot

Create a wait-free read snapshot (item 2 in plan). Freezes entity_slots and relations into Arc<[_]> and clones the rest.

pub fn flush_and_sync(&mut self) -> Result<()>

Flush and fsync the log to stable storage.