xz_knowledge_graph/
traits.rs

1use async_trait::async_trait;
2use std::fmt::Debug;
3
4use crate::error::KgError;
5use crate::types::consistency::ConsistencyIssue;
6use crate::types::entity::Entity;
7use crate::types::graph::{GraphStats, PathStep, SubGraph};
8use crate::types::import::{ImportResult, UpsertResult};
9use crate::types::query::{EntityPage, EntityQuery, RelationQuery};
10use crate::types::relation::Relation;
11
12/// Knowledge graph core interface.
13///
14/// Design principles:
15/// - Upsert semantics by ID with configurable merge strategy
16/// - Graph traversal as first-class citizen (BFS neighbors, shortest path)
17/// - Batch import within transactions with detailed statistics
18/// - Consistency checking as independent concern
19/// - delete_entity cascades to related relations
20#[async_trait]
21pub trait KnowledgeGraph: Send + Sync + Debug {
22    // === Entity Operations ===
23
24    async fn upsert_entity(&self, entity: Entity) -> Result<UpsertResult, KgError>;
25    async fn get_entity(&self, id: &str) -> Result<Option<Entity>, KgError>;
26    async fn search_entities(&self, query: &EntityQuery) -> Result<EntityPage, KgError>;
27    async fn delete_entity(&self, id: &str) -> Result<usize, KgError>;
28    async fn get_entities_batch(&self, ids: &[&str]) -> Result<Vec<Entity>, KgError>;
29
30    // === Relation Operations ===
31
32    async fn upsert_relation(&self, relation: Relation) -> Result<UpsertResult, KgError>;
33    async fn get_relations(&self, entity_id: &str) -> Result<Vec<Relation>, KgError>;
34    async fn query_relations(&self, query: &RelationQuery) -> Result<Vec<Relation>, KgError>;
35    async fn delete_relation(&self, id: &str) -> Result<(), KgError>;
36
37    // === Graph Traversal ===
38
39    async fn get_neighbors(&self, entity_id: &str, depth: u32) -> Result<SubGraph, KgError>;
40    async fn shortest_path(
41        &self,
42        from: &str,
43        to: &str,
44    ) -> Result<Option<Vec<PathStep>>, KgError>;
45    async fn all_paths(
46        &self,
47        from: &str,
48        to: &str,
49        max_depth: u32,
50    ) -> Result<Vec<Vec<PathStep>>, KgError>;
51
52    // === Batch Operations ===
53
54    async fn batch_import(
55        &self,
56        entities: Vec<Entity>,
57        relations: Vec<Relation>,
58    ) -> Result<ImportResult, KgError>;
59
60    // === Consistency ===
61
62    async fn check_consistency(&self) -> Result<Vec<ConsistencyIssue>, KgError>;
63
64    // === Statistics ===
65
66    async fn stats(&self) -> Result<GraphStats, KgError>;
67}
xz_knowledge_graph/traits.rs

xz_knowledge_graph/
traits.rs
