Skip to main content

khive_runtime/retrieval/
single_engine.rs

1use khive_score::DeterministicScore;
2use khive_storage::{StorageCapability, StorageError, VectorSearchHit, VectorSearchRequest};
3use khive_types::SubstrateKind;
4use uuid::Uuid;
5
6use crate::{KhiveRuntime, NamespaceToken, RuntimeError, RuntimeResult};
7
8impl KhiveRuntime {
9    /// The vector stage of hybrid entity search: one KNN query over the entity vectors of
10    /// the primary namespace. It does not depend on an entity kind, which only the text
11    /// stage and the filter after fusion apply.
12    pub(super) async fn hybrid_vector_stage(
13        &self,
14        token: &NamespaceToken,
15        query_text: &str,
16        query_vector: Option<Vec<f32>>,
17        candidates: u32,
18        vector_similarity_floor: Option<f64>,
19        tolerate_vector_error: bool,
20    ) -> RuntimeResult<(Vec<VectorSearchHit>, Option<String>)> {
21        khive_storage::await_request_read_phase("hybrid_search.vector", async {
22            let mut vector_error: Option<String> = None;
23            let mut vector_hits =
24                if query_vector.is_some() || !self.default_embedder_name().is_empty() {
25                    crate::search_audit::record(crate::search_audit::SearchArm::Vector);
26                    match self
27                        .vector_search(
28                            token,
29                            query_vector,
30                            Some(query_text),
31                            candidates,
32                            Some(SubstrateKind::Entity),
33                        )
34                        .await
35                    {
36                        Ok(hits) => hits,
37                        Err(e) if tolerate_vector_error => {
38                            vector_error = Some(e.to_string());
39                            Vec::new()
40                        }
41                        Err(e) => return Err(e),
42                    }
43                } else {
44                    Vec::new()
45                };
46            if let Some(cosine_floor) = vector_similarity_floor {
47                // Vector store scores use canonical cosine similarity (`1 - distance`),
48                // so the caller's raw-cosine floor is already on the comparison scale.
49                let score_floor = DeterministicScore::from_f64(cosine_floor);
50                vector_hits.retain(|hit| hit.score >= score_floor);
51            }
52            Ok((vector_hits, vector_error))
53        })
54        .await?
55    }
56
57    /// Search one configured embedding space using a raw vector or query text.
58    ///
59    /// This compatibility API selects the configured default (the first configured
60    /// peer). It never infers a space from vector dimensions or falls through to
61    /// another engine. Use [`Self::vector_search_in`] to name the space explicitly.
62    pub async fn vector_search(
63        &self,
64        token: &NamespaceToken,
65        query_embedding: Option<Vec<f32>>,
66        query_text: Option<&str>,
67        top_k: u32,
68        kind: Option<SubstrateKind>,
69    ) -> RuntimeResult<Vec<VectorSearchHit>> {
70        validate_query_input(query_embedding.as_deref(), query_text)?;
71        let engine = self.require_default_embedder()?;
72        self.vector_search_in(token, engine, query_embedding, query_text, top_k, kind)
73            .await
74    }
75
76    /// Search exactly the named engine's space, even when another engine has the
77    /// same dimensions. Built-in aliases resolve to their canonical model name.
78    ///
79    /// A supplied vector avoids embedding. Otherwise the named query embedder is
80    /// invoked with the caller's token. Unknown/excluded engines, wrong dimensions
81    /// and nonfinite coordinates refuse even when `top_k` is zero.
82    /// Entity queries exclude knowledge-atom vectors before their candidate window.
83    // REASON: preserve vector_search's arguments while adding an explicit engine identity.
84    #[allow(clippy::too_many_arguments)]
85    pub async fn vector_search_in(
86        &self,
87        token: &NamespaceToken,
88        engine: &str,
89        query_embedding: Option<Vec<f32>>,
90        query_text: Option<&str>,
91        top_k: u32,
92        kind: Option<SubstrateKind>,
93    ) -> RuntimeResult<Vec<VectorSearchHit>> {
94        validate_query_input(query_embedding.as_deref(), query_text)?;
95        let (engine, dimensions) = self.vector_model_metadata(engine)?;
96        let embedding = match query_embedding {
97            Some(vector) => vector,
98            None => {
99                let text = query_text.ok_or_else(missing_query)?;
100                self.embed_query_with_model_for_token(token, &engine, text)
101                    .await?
102            }
103        };
104        validate_vector(&engine, dimensions, &embedding, "vec_search")?;
105        let hits = self
106            .vectors_for_model(token, &engine)?
107            .search(VectorSearchRequest {
108                query_vectors: vec![embedding],
109                top_k,
110                namespace: Some(token.namespace().as_str().to_owned()),
111                kind,
112                embedding_model: None,
113                filter: None,
114                backend_hints: entity_vector_backend_hints(kind),
115            })
116            .await;
117        crate::usage::count(crate::usage::UsageUnit::VectorPasses, 1);
118        hits.map_err(RuntimeError::from)
119    }
120
121    /// Exact entity KNN in the configured default (first configured peer) space.
122    /// Use [`Self::knn_in`] when the query vector belongs to a named engine.
123    pub async fn knn(
124        &self,
125        token: &NamespaceToken,
126        query_vector: Vec<f32>,
127        top_k: u32,
128    ) -> RuntimeResult<Vec<VectorSearchHit>> {
129        let engine = self.require_default_embedder()?;
130        self.knn_in(token, engine, query_vector, top_k).await
131    }
132
133    /// Exact entity KNN in the named engine's space and token namespace.
134    /// Unknown/excluded names and invalid vectors refuse before search, including
135    /// zero-result requests. No embedding service is instantiated for this API.
136    /// Knowledge-atom vectors do not consume the entity candidate window.
137    pub async fn knn_in(
138        &self,
139        token: &NamespaceToken,
140        engine: &str,
141        query_vector: Vec<f32>,
142        top_k: u32,
143    ) -> RuntimeResult<Vec<VectorSearchHit>> {
144        let (engine, dimensions) = self.vector_model_metadata(engine)?;
145        validate_vector(&engine, dimensions, &query_vector, "vec_search")?;
146        Ok(self
147            .vectors_for_model(token, &engine)?
148            .search(VectorSearchRequest {
149                query_vectors: vec![query_vector],
150                top_k,
151                namespace: Some(token.namespace().as_str().to_owned()),
152                kind: Some(SubstrateKind::Entity),
153                embedding_model: None,
154                filter: None,
155                backend_hints: entity_vector_backend_hints(Some(SubstrateKind::Entity)),
156            })
157            .await?)
158    }
159
160    /// Score only the supplied entity candidates in the configured default
161    /// (first configured peer) space. Use [`Self::rerank_in`] for a named space.
162    pub async fn rerank(
163        &self,
164        token: &NamespaceToken,
165        query_vector: &[f32],
166        candidate_ids: &[Uuid],
167        top_k: u32,
168    ) -> RuntimeResult<Vec<VectorSearchHit>> {
169        let engine = self.require_default_embedder()?;
170        self.rerank_in(token, engine, query_vector, candidate_ids, top_k)
171            .await
172    }
173
174    /// Score only the supplied entity candidates in the named engine's space.
175    ///
176    /// Missing or out-of-scope vectors are omitted; equal scores use ascending
177    /// IDs and duplicate IDs yield one hit. The result limit applies after all
178    /// candidates are scored. Unsupported storage propagates its capability error
179    /// without falling back to namespace-wide search. Engine identity, dimensions
180    /// and finite coordinates are checked even for empty candidates or zero limit.
181    pub async fn rerank_in(
182        &self,
183        token: &NamespaceToken,
184        engine: &str,
185        query_vector: &[f32],
186        candidate_ids: &[Uuid],
187        top_k: u32,
188    ) -> RuntimeResult<Vec<VectorSearchHit>> {
189        let (engine, dimensions) = self.vector_model_metadata(engine)?;
190        validate_vector(&engine, dimensions, query_vector, "score_candidates")?;
191        let mut hits = self
192            .vectors_for_model(token, &engine)?
193            .score_candidates(query_vector, candidate_ids, Some(SubstrateKind::Entity))
194            .await?;
195        hits.truncate(top_k as usize);
196        Ok(hits)
197    }
198}
199
200// Atom vectors share the entity substrate tag but belong to knowledge retrieval.
201// The fixed private SQLite hint excludes them before KNN cuts its candidate window.
202fn entity_vector_backend_hints(kind: Option<SubstrateKind>) -> Option<serde_json::Value> {
203    (kind == Some(SubstrateKind::Entity))
204        .then(|| serde_json::json!({ "exclude_knowledge_atoms": true }))
205}
206
207fn missing_query() -> RuntimeError {
208    RuntimeError::InvalidInput("vector search requires query_embedding or query_text".into())
209}
210
211fn validate_query_input(vector: Option<&[f32]>, text: Option<&str>) -> RuntimeResult<()> {
212    if vector.is_none() {
213        let text = text.ok_or_else(missing_query)?;
214        if text.trim().is_empty() {
215            return Err(RuntimeError::InvalidInput(
216                "query_text must not be empty".into(),
217            ));
218        }
219    }
220    Ok(())
221}
222
223fn validate_vector(
224    engine: &str,
225    dimensions: usize,
226    vector: &[f32],
227    operation: &'static str,
228) -> RuntimeResult<()> {
229    let message = if vector.len() != dimensions {
230        Some(format!(
231            "engine '{engine}' query has {} dims, expected {dimensions}",
232            vector.len()
233        ))
234    } else {
235        vector
236            .iter()
237            .position(|coordinate| !coordinate.is_finite())
238            .map(|index| {
239                format!("engine '{engine}' query has a nonfinite coordinate at index {index}")
240            })
241    };
242    if let Some(message) = message {
243        return Err(StorageError::InvalidInput {
244            capability: StorageCapability::Vectors,
245            operation: operation.into(),
246            message,
247        }
248        .into());
249    }
250    Ok(())
251}