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 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 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 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 #[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 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 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 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 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
200fn 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}