zeph_memory/
vector_store.rs

1// SPDX-FileCopyrightText: 2026 Andrei G <bug-ops>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4use std::collections::HashMap;
5use std::future::Future;
6use std::pin::Pin;
7
8#[derive(Debug, thiserror::Error)]
9pub enum VectorStoreError {
10    #[error("connection error: {0}")]
11    Connection(String),
12    #[error("collection error: {0}")]
13    Collection(String),
14    #[error("upsert error: {0}")]
15    Upsert(String),
16    #[error("search error: {0}")]
17    Search(String),
18    #[error("delete error: {0}")]
19    Delete(String),
20    #[error("scroll error: {0}")]
21    Scroll(String),
22    #[error("serialization error: {0}")]
23    Serialization(String),
24}
25
26#[derive(Debug, Clone)]
27pub struct VectorPoint {
28    pub id: String,
29    pub vector: Vec<f32>,
30    pub payload: HashMap<String, serde_json::Value>,
31}
32
33#[derive(Debug, Clone, Default)]
34pub struct VectorFilter {
35    pub must: Vec<FieldCondition>,
36    pub must_not: Vec<FieldCondition>,
37}
38
39#[derive(Debug, Clone)]
40pub struct FieldCondition {
41    pub field: String,
42    pub value: FieldValue,
43}
44
45#[derive(Debug, Clone)]
46pub enum FieldValue {
47    Integer(i64),
48    Text(String),
49}
50
51#[derive(Debug, Clone)]
52pub struct ScoredVectorPoint {
53    pub id: String,
54    pub score: f32,
55    pub payload: HashMap<String, serde_json::Value>,
56}
57
58/// Shared return type alias for all [`VectorStore`] trait methods.
59///
60/// Intentionally `pub(crate)` — all [`VectorStore`] implementations are internal to this crate.
61/// If the trait is ever made externally extensible, this alias should become `pub`.
62pub(crate) type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
63
64pub type ScrollResult = HashMap<String, HashMap<String, String>>;
65
66pub trait VectorStore: Send + Sync {
67    fn ensure_collection(
68        &self,
69        collection: &str,
70        vector_size: u64,
71    ) -> BoxFuture<'_, Result<(), VectorStoreError>>;
72
73    fn collection_exists(&self, collection: &str) -> BoxFuture<'_, Result<bool, VectorStoreError>>;
74
75    fn delete_collection(&self, collection: &str) -> BoxFuture<'_, Result<(), VectorStoreError>>;
76
77    fn upsert(
78        &self,
79        collection: &str,
80        points: Vec<VectorPoint>,
81    ) -> BoxFuture<'_, Result<(), VectorStoreError>>;
82
83    fn search(
84        &self,
85        collection: &str,
86        vector: Vec<f32>,
87        limit: u64,
88        filter: Option<VectorFilter>,
89    ) -> BoxFuture<'_, Result<Vec<ScoredVectorPoint>, VectorStoreError>>;
90
91    fn delete_by_ids(
92        &self,
93        collection: &str,
94        ids: Vec<String>,
95    ) -> BoxFuture<'_, Result<(), VectorStoreError>>;
96
97    fn scroll_all(
98        &self,
99        collection: &str,
100        key_field: &str,
101    ) -> BoxFuture<'_, Result<ScrollResult, VectorStoreError>>;
102
103    fn health_check(&self) -> BoxFuture<'_, Result<bool, VectorStoreError>>;
104}
zeph_memory/vector_store.rs

zeph_memory/
vector_store.rs
