symbi_runtime/context/
vector_db_trait.rs

1//! Backend-agnostic vector database trait.
2//!
3//! The runtime selects the concrete implementation at startup based on
4//! environment variables or config. LanceDB is the default embedded
5//! backend; Qdrant is available behind the `vector-qdrant` feature.
6
7use async_trait::async_trait;
8use std::collections::HashMap;
9
10use crate::context::types::{
11    ContextError, ContextItem, KnowledgeItem, MemoryItem, VectorBatchOperation, VectorId,
12};
13use crate::context::vector_db::VectorDatabaseStats;
14use crate::types::AgentId;
15use serde_json::Value;
16
17/// Distance metric for vector similarity.
18#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
19pub enum DistanceMetric {
20    #[default]
21    Cosine,
22    Euclidean,
23    DotProduct,
24}
25
26/// Backend-agnostic vector database trait.
27///
28/// All vector operations go through this trait. Implementations:
29/// - `LanceDbBackend` — embedded, zero-config (default)
30/// - `QdrantClientWrapper` — remote, feature-gated behind `vector-qdrant`
31/// - `NoOpVectorDatabase` — fallback when no backend is configured
32#[async_trait]
33pub trait VectorDb: Send + Sync {
34    /// Initialize the backend (create collection/table if needed).
35    async fn initialize(&self) -> Result<(), ContextError>;
36
37    /// Store a knowledge item with its embedding vector.
38    async fn store_knowledge_item(
39        &self,
40        item: &KnowledgeItem,
41        embedding: Vec<f32>,
42    ) -> Result<VectorId, ContextError>;
43
44    /// Store a memory item with its embedding vector.
45    async fn store_memory_item(
46        &self,
47        agent_id: AgentId,
48        memory: &MemoryItem,
49        embedding: Vec<f32>,
50    ) -> Result<VectorId, ContextError>;
51
52    /// Store multiple items in batch.
53    async fn batch_store(&self, batch: VectorBatchOperation)
54        -> Result<Vec<VectorId>, ContextError>;
55
56    /// Search the knowledge base by semantic similarity.
57    async fn search_knowledge_base(
58        &self,
59        agent_id: AgentId,
60        query_embedding: Vec<f32>,
61        limit: usize,
62    ) -> Result<Vec<KnowledgeItem>, ContextError>;
63
64    /// Semantic similarity search returning context items.
65    async fn semantic_search(
66        &self,
67        agent_id: AgentId,
68        query_embedding: Vec<f32>,
69        limit: usize,
70        threshold: f32,
71    ) -> Result<Vec<ContextItem>, ContextError>;
72
73    /// Advanced search with metadata filters.
74    async fn advanced_search(
75        &self,
76        agent_id: AgentId,
77        query_embedding: Vec<f32>,
78        filters: HashMap<String, String>,
79        limit: usize,
80        threshold: f32,
81    ) -> Result<Vec<super::types::VectorSearchResult>, ContextError>;
82
83    /// Delete a knowledge item by vector ID.
84    async fn delete_knowledge_item(&self, vector_id: VectorId) -> Result<(), ContextError>;
85
86    /// Delete multiple vectors by ID.
87    async fn batch_delete(&self, vector_ids: Vec<VectorId>) -> Result<(), ContextError>;
88
89    /// Update metadata on an existing vector.
90    async fn update_metadata(
91        &self,
92        vector_id: VectorId,
93        metadata: HashMap<String, Value>,
94    ) -> Result<(), ContextError>;
95
96    /// Get statistics about the vector database.
97    async fn get_stats(&self) -> Result<VectorDatabaseStats, ContextError>;
98
99    /// Create an index on a field.
100    async fn create_index(&self, field_name: &str) -> Result<(), ContextError>;
101
102    /// Optimize the collection (compact, reindex, etc.).
103    async fn optimize_collection(&self) -> Result<(), ContextError>;
104
105    /// Health check — can the backend be reached?
106    async fn health_check(&self) -> Result<bool, ContextError>;
107}
108
109#[cfg(test)]
110mod tests {
111    use super::*;
112
113    #[test]
114    fn test_distance_metric_default() {
115        let metric = DistanceMetric::default();
116        assert!(matches!(metric, DistanceMetric::Cosine));
117    }
118}
symbi_runtime/context/vector_db_trait.rs

symbi_runtime/context/
vector_db_trait.rs
