1use std::collections::{HashMap, HashSet};
4
5use lattice_embed::{EmbeddingModel, MAX_TEXT_CHARS};
6use uuid::Uuid;
7
8use crate::config::{parse_embedding_model_alias, sanitize_key};
9use crate::curation::note_fts_document;
10use crate::error::{RuntimeError, RuntimeResult};
11use crate::runtime::{KhiveRuntime, NamespaceToken};
12use khive_score::{rrf_score, DeterministicScore};
13use khive_storage::types::{
14 PageRequest, TextFilter, TextQueryMode, TextSearchHit, TextSearchRequest, VectorSearchHit,
15 VectorSearchRequest,
16};
17use khive_storage::EntityFilter;
18use khive_types::SubstrateKind;
19
20#[cfg(any(test, feature = "fault-injection"))]
22std::thread_local! {
23 static BACKFILL_READER_FAIL: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
24}
25
26#[cfg(any(test, feature = "fault-injection"))]
32pub fn arm_backfill_reader_fail() {
33 BACKFILL_READER_FAIL.with(|c| c.set(true));
34}
35
36#[derive(Clone, Debug)]
38pub struct SearchHit {
39 pub entity_id: Uuid,
40 pub score: DeterministicScore,
41 pub source: SearchSource,
42 pub title: Option<String>,
43 pub snippet: Option<String>,
44}
45
46#[derive(Clone, Copy, Debug, PartialEq, Eq)]
48pub enum SearchSource {
49 Vector,
50 Text,
51 Both,
52}
53
54impl SearchSource {
55 #[must_use]
57 pub const fn union(self, other: Self) -> Self {
58 match (self, other) {
59 (Self::Text, Self::Text) => Self::Text,
60 (Self::Vector, Self::Vector) => Self::Vector,
61 _ => Self::Both,
62 }
63 }
64
65 #[must_use]
67 pub const fn as_str(self) -> &'static str {
68 match self {
69 Self::Vector => "vector",
70 Self::Text => "text",
71 Self::Both => "both",
72 }
73 }
74}
75
76const RRF_K: usize = 10;
83
84const CANDIDATE_MULTIPLIER: u32 = 4;
86
87pub const EMBEDDING_INPUT_TRUNCATED_WARNING: &str =
89 "embedding input was truncated to the embedder maximum; full content was stored unchanged";
90
91#[derive(Clone, Debug)]
93pub struct DocumentEmbeddingOutcome {
94 pub model_name: String,
95 pub vector: Vec<f32>,
96 pub source_bytes: usize,
97 pub embedded_bytes: usize,
98 pub truncated: bool,
99}
100
101#[derive(Clone, Debug, Default, PartialEq, Eq, serde::Deserialize, serde::Serialize)]
103pub struct EmbeddingTruncationReport {
104 pub truncated: u64,
105 pub discarded_bytes: u64,
106}
107
108impl EmbeddingTruncationReport {
109 pub fn observe(&mut self, outcome: &DocumentEmbeddingOutcome) {
110 if outcome.truncated {
111 self.truncated += 1;
112 self.discarded_bytes +=
113 outcome.source_bytes.saturating_sub(outcome.embedded_bytes) as u64;
114 }
115 }
116
117 #[must_use]
118 pub const fn any_truncated(&self) -> bool {
119 self.truncated > 0
120 }
121
122 pub fn merge(&mut self, other: Self) {
124 self.truncated = self.truncated.saturating_add(other.truncated);
125 self.discarded_bytes = self.discarded_bytes.saturating_add(other.discarded_bytes);
126 }
127}
128
129pub fn document_embedding_budget(model_name: &str) -> usize {
131 parse_embedding_model_alias(model_name)
132 .and_then(|model| model.document_instruction())
133 .map_or(MAX_TEXT_CHARS, |prefix| {
134 MAX_TEXT_CHARS.saturating_sub(prefix.len())
135 })
136}
137
138pub fn bounded_embedding_input(text: &str, max_bytes: usize) -> (&str, bool) {
140 if text.len() <= max_bytes {
141 return (text, false);
142 }
143
144 let end = text
145 .char_indices()
146 .map(|(index, _)| index)
147 .take_while(|index| *index <= max_bytes)
148 .last()
149 .unwrap_or(0);
150 (&text[..end], true)
151}
152
153impl KhiveRuntime {
154 pub async fn embed(&self, text: &str) -> RuntimeResult<Vec<f32>> {
159 let model_name = self.default_embedder_name();
160 if model_name.is_empty() {
161 return Err(RuntimeError::Unconfigured("embedding_model".into()));
162 }
163 self.embed_with_model(model_name, text).await
164 }
165
166 pub async fn embed_with_model(&self, model_name: &str, text: &str) -> RuntimeResult<Vec<f32>> {
182 let model = parse_embedding_model_alias(model_name);
183 let service = self.embedder(model_name).await?;
184 let emb_model = model.unwrap_or_default();
185 crate::usage::count(crate::usage::UsageUnit::EmbedCalls, 1);
189 let out = service.embed_one(text, emb_model).await;
190 Ok(out?)
191 }
192
193 pub async fn embed_document_with_model(
212 &self,
213 model_name: &str,
214 text: &str,
215 ) -> RuntimeResult<Vec<f32>> {
216 Ok(self
217 .embed_document_with_model_outcome_inner(None, model_name, text)
218 .await?
219 .vector)
220 }
221
222 pub async fn embed_document_with_model_outcome(
223 &self,
224 model_name: &str,
225 text: &str,
226 ) -> RuntimeResult<DocumentEmbeddingOutcome> {
227 self.embed_document_with_model_outcome_inner(None, model_name, text)
228 .await
229 }
230
231 pub(crate) async fn embed_document_with_model_outcome_for_token(
232 &self,
233 token: &NamespaceToken,
234 model_name: &str,
235 text: &str,
236 ) -> RuntimeResult<DocumentEmbeddingOutcome> {
237 self.embed_document_with_model_outcome_inner(Some(token), model_name, text)
238 .await
239 }
240
241 async fn embed_document_with_model_outcome_inner(
242 &self,
243 token: Option<&NamespaceToken>,
244 model_name: &str,
245 text: &str,
246 ) -> RuntimeResult<DocumentEmbeddingOutcome> {
247 let model = parse_embedding_model_alias(model_name);
248 let service = match token {
249 Some(token) => self.embedder_with_token(token, model_name).await?,
250 None => self.embedder(model_name).await?,
251 };
252 let emb_model = model.unwrap_or_default();
253 let source_bytes = text.len();
254 let (text, truncated) =
255 bounded_embedding_input(text, document_embedding_budget(model_name));
256 let embedded_bytes = text.len();
257 crate::usage::count(crate::usage::UsageUnit::EmbedCalls, 1);
259 let embeddings = service.embed_passage(&[text.to_string()], emb_model).await;
260 let mut vectors = embeddings?;
261 if vectors.len() != 1 {
262 return Err(RuntimeError::Internal(format!(
263 "embed_passage returned {} vectors for 1 input",
264 vectors.len()
265 )));
266 }
267 let out = vectors.pop().expect("checked len == 1 above");
268 Ok(DocumentEmbeddingOutcome {
269 model_name: model_name.to_owned(),
270 vector: out,
271 source_bytes,
272 embedded_bytes,
273 truncated,
274 })
275 }
276
277 pub async fn embed_query_with_model(
289 &self,
290 model_name: &str,
291 text: &str,
292 ) -> RuntimeResult<Vec<f32>> {
293 self.embed_query_with_model_inner(None, model_name, text)
294 .await
295 }
296
297 pub(crate) async fn embed_query_with_model_for_token(
298 &self,
299 token: &NamespaceToken,
300 model_name: &str,
301 text: &str,
302 ) -> RuntimeResult<Vec<f32>> {
303 self.embed_query_with_model_inner(Some(token), model_name, text)
304 .await
305 }
306
307 async fn embed_query_with_model_inner(
308 &self,
309 token: Option<&NamespaceToken>,
310 model_name: &str,
311 text: &str,
312 ) -> RuntimeResult<Vec<f32>> {
313 let model = parse_embedding_model_alias(model_name);
314 let service = match token {
315 Some(token) => self.embedder_with_token(token, model_name).await?,
316 None => self.embedder(model_name).await?,
317 };
318 let texts = [text.to_string()];
319 let emb_model = model.unwrap_or_default();
320 crate::usage::count(crate::usage::UsageUnit::EmbedCalls, 1);
322 let embeddings = match emb_model {
323 EmbeddingModel::BgeSmallEnV15
324 | EmbeddingModel::BgeBaseEnV15
325 | EmbeddingModel::BgeLargeEnV15 => service.embed(&texts, emb_model).await,
326 _ => service.embed_query(&texts, emb_model).await,
327 };
328 let out = embeddings?
329 .into_iter()
330 .next()
331 .ok_or_else(|| RuntimeError::Internal("embed_query returned empty vec".into()))?;
332 Ok(out)
333 }
334
335 pub async fn embed_document(&self, text: &str) -> RuntimeResult<Vec<f32>> {
342 let model_name = self.default_embedder_name();
343 if model_name.is_empty() {
344 return Err(RuntimeError::Unconfigured("embedding_model".into()));
345 }
346 self.embed_document_with_model(model_name, text).await
347 }
348
349 pub async fn embed_query(&self, text: &str) -> RuntimeResult<Vec<f32>> {
356 let model_name = self.default_embedder_name();
357 if model_name.is_empty() {
358 return Err(RuntimeError::Unconfigured("embedding_model".into()));
359 }
360 self.embed_query_with_model(model_name, text).await
361 }
362
363 async fn embed_query_for_token(
364 &self,
365 token: &NamespaceToken,
366 text: &str,
367 ) -> RuntimeResult<Vec<f32>> {
368 let model_name = self.default_embedder_name();
369 if model_name.is_empty() {
370 return Err(RuntimeError::Unconfigured("embedding_model".into()));
371 }
372 self.embed_query_with_model_for_token(token, model_name, text)
373 .await
374 }
375
376 pub async fn embed_batch(&self, texts: &[String]) -> RuntimeResult<Vec<Vec<f32>>> {
384 if texts.is_empty() {
385 return Ok(vec![]);
386 }
387 let model_name = self.default_embedder_name();
388 if model_name.is_empty() {
389 return Err(RuntimeError::Unconfigured("embedding_model".into()));
390 }
391 self.embed_batch_with_model(model_name, texts).await
392 }
393
394 pub async fn embed_batch_with_model(
399 &self,
400 model_name: &str,
401 texts: &[String],
402 ) -> RuntimeResult<Vec<Vec<f32>>> {
403 if texts.is_empty() {
404 return Ok(vec![]);
405 }
406 let model = parse_embedding_model_alias(model_name);
407 let service = self.embedder(model_name).await?;
408 let emb_model = model.unwrap_or_default();
409 let out = service.embed(texts, emb_model).await;
410 crate::usage::count(crate::usage::UsageUnit::EmbedCalls, texts.len() as u64);
411 Ok(out?)
412 }
413
414 pub async fn embed_document_batch_with_model(
426 &self,
427 model_name: &str,
428 texts: &[String],
429 ) -> RuntimeResult<Vec<Vec<f32>>> {
430 if texts.is_empty() {
431 return Ok(vec![]);
432 }
433 Ok(self
434 .embed_document_batch_with_model_outcomes(model_name, texts)
435 .await?
436 .into_iter()
437 .map(|outcome| outcome.vector)
438 .collect())
439 }
440
441 pub async fn embed_document_batch_with_model_outcomes(
442 &self,
443 model_name: &str,
444 texts: &[String],
445 ) -> RuntimeResult<Vec<DocumentEmbeddingOutcome>> {
446 if texts.is_empty() {
447 return Ok(vec![]);
448 }
449 let model = parse_embedding_model_alias(model_name);
450 let service = self.embedder(model_name).await?;
451 let emb_model = model.unwrap_or_default();
452 let budget = document_embedding_budget(model_name);
453 let out = if texts.iter().all(|text| text.len() <= budget) {
454 service.embed_passage(texts, emb_model).await
455 } else {
456 let bounded_texts: Vec<String> = texts
457 .iter()
458 .map(|text| bounded_embedding_input(text, budget).0.to_owned())
459 .collect();
460 service.embed_passage(&bounded_texts, emb_model).await
461 };
462 crate::usage::count(crate::usage::UsageUnit::EmbedCalls, texts.len() as u64);
463 let vectors = out?;
464 if vectors.len() != texts.len() {
465 return Err(RuntimeError::Internal(format!(
466 "embed_passage returned {} vectors for {} inputs",
467 vectors.len(),
468 texts.len()
469 )));
470 }
471 Ok(texts
472 .iter()
473 .zip(vectors)
474 .map(|(text, vector)| {
475 let (bounded, truncated) = bounded_embedding_input(text, budget);
476 DocumentEmbeddingOutcome {
477 model_name: model_name.to_owned(),
478 vector,
479 source_bytes: text.len(),
480 embedded_bytes: bounded.len(),
481 truncated,
482 }
483 })
484 .collect())
485 }
486
487 pub async fn embed_document_batch(&self, texts: &[String]) -> RuntimeResult<Vec<Vec<f32>>> {
494 if texts.is_empty() {
495 return Ok(vec![]);
496 }
497 let model_name = self.default_embedder_name();
498 if model_name.is_empty() {
499 return Err(RuntimeError::Unconfigured("embedding_model".into()));
500 }
501 self.embed_document_batch_with_model(model_name, texts)
502 .await
503 }
504
505 pub async fn embed_document_batch_outcomes(
507 &self,
508 texts: &[String],
509 ) -> RuntimeResult<Vec<DocumentEmbeddingOutcome>> {
510 if texts.is_empty() {
511 return Ok(vec![]);
512 }
513 let model_name = self.default_embedder_name();
514 if model_name.is_empty() {
515 return Err(RuntimeError::Unconfigured("embedding_model".into()));
516 }
517 self.embed_document_batch_with_model_outcomes(model_name, texts)
518 .await
519 }
520
521 pub async fn embed_query_batch_with_model(
528 &self,
529 model_name: &str,
530 texts: &[String],
531 ) -> RuntimeResult<Vec<Vec<f32>>> {
532 if texts.is_empty() {
533 return Ok(vec![]);
534 }
535 let model = parse_embedding_model_alias(model_name);
536 let service = self.embedder(model_name).await?;
537 let emb_model = model.unwrap_or_default();
538 let out = match emb_model {
539 EmbeddingModel::BgeSmallEnV15
540 | EmbeddingModel::BgeBaseEnV15
541 | EmbeddingModel::BgeLargeEnV15 => service.embed(texts, emb_model).await,
542 _ => service.embed_query(texts, emb_model).await,
543 };
544 crate::usage::count(crate::usage::UsageUnit::EmbedCalls, texts.len() as u64);
545 Ok(out?)
546 }
547
548 pub async fn vector_search(
554 &self,
555 token: &NamespaceToken,
556 query_embedding: Option<Vec<f32>>,
557 query_text: Option<&str>,
558 top_k: u32,
559 kind: Option<SubstrateKind>,
560 ) -> RuntimeResult<Vec<VectorSearchHit>> {
561 let embedding = match query_embedding {
562 Some(vec) => vec,
563 None => {
564 let text = query_text.ok_or_else(|| {
565 RuntimeError::InvalidInput(
566 "vector search requires query_embedding or query_text".into(),
567 )
568 })?;
569 if text.trim().is_empty() {
570 return Err(RuntimeError::InvalidInput(
571 "query_text must not be empty".into(),
572 ));
573 }
574 self.embed_query_for_token(token, text).await?
575 }
576 };
577
578 let ns = token.namespace().as_str().to_owned();
579 let hits = self
580 .vectors(token)?
581 .search(VectorSearchRequest {
582 query_vectors: vec![embedding],
583 top_k,
584 namespace: Some(ns),
585 kind,
586 embedding_model: None,
587 filter: None,
588 backend_hints: None,
589 })
590 .await;
591 crate::usage::count(crate::usage::UsageUnit::VectorPasses, 1);
592 Ok(hits?)
593 }
594
595 #[allow(clippy::too_many_arguments)]
636 pub async fn hybrid_search(
637 &self,
638 token: &NamespaceToken,
639 query_text: &str,
640 query_vector: Option<Vec<f32>>,
641 limit: u32,
642 entity_kind: Option<&str>,
643 entity_type: Option<&str>,
644 tags_any: &[String],
645 properties_filter: Option<&serde_json::Value>,
646 ) -> RuntimeResult<Vec<SearchHit>> {
647 self.hybrid_search_inner(
648 token,
649 query_text,
650 query_vector,
651 limit,
652 entity_kind,
653 entity_type,
654 tags_any,
655 properties_filter,
656 None,
657 )
658 .await
659 }
660
661 #[allow(clippy::too_many_arguments)]
666 pub(crate) async fn hybrid_search_with_vector_similarity_floor(
667 &self,
668 token: &NamespaceToken,
669 query_text: &str,
670 query_vector: Option<Vec<f32>>,
671 limit: u32,
672 entity_kind: Option<&str>,
673 entity_type: Option<&str>,
674 tags_any: &[String],
675 properties_filter: Option<&serde_json::Value>,
676 vector_similarity_floor: f64,
677 ) -> RuntimeResult<Vec<SearchHit>> {
678 self.hybrid_search_inner(
679 token,
680 query_text,
681 query_vector,
682 limit,
683 entity_kind,
684 entity_type,
685 tags_any,
686 properties_filter,
687 Some(vector_similarity_floor),
688 )
689 .await
690 }
691
692 #[allow(clippy::too_many_arguments)]
693 async fn hybrid_search_inner(
694 &self,
695 token: &NamespaceToken,
696 query_text: &str,
697 query_vector: Option<Vec<f32>>,
698 limit: u32,
699 entity_kind: Option<&str>,
700 entity_type: Option<&str>,
701 tags_any: &[String],
702 properties_filter: Option<&serde_json::Value>,
703 vector_similarity_floor: Option<f64>,
704 ) -> RuntimeResult<Vec<SearchHit>> {
705 let candidates = limit.saturating_mul(CANDIDATE_MULTIPLIER).max(limit);
706
707 let visible_ns: Vec<String> = token
708 .visible_namespaces()
709 .iter()
710 .map(|ns| ns.as_str().to_owned())
711 .collect();
712 let text_search_result = self
716 .text(token)?
717 .search(TextSearchRequest {
718 query: query_text.to_string(),
719 mode: TextQueryMode::Plain,
720 filter: Some(TextFilter {
721 namespaces: visible_ns.clone(),
722 ..TextFilter::default()
723 }),
724 top_k: candidates,
725 snippet_chars: 200,
726 })
727 .await;
728 let text_hits = crate::error::fts_text_leg_or_err(
733 text_search_result.map_err(RuntimeError::from),
734 "hybrid_search",
735 query_text,
736 )?;
737
738 let mut vector_hits = if query_vector.is_some() || self.config().embedding_model.is_some() {
739 self.vector_search(
740 token,
741 query_vector,
742 Some(query_text),
743 candidates,
744 Some(SubstrateKind::Entity),
745 )
746 .await?
747 } else {
748 Vec::new()
749 };
750 if let Some(cosine_floor) = vector_similarity_floor {
751 let score_floor = DeterministicScore::from_f64(cosine_floor);
754 vector_hits.retain(|hit| hit.score >= score_floor);
755 }
756
757 let fusion_limit = text_hits.len().saturating_add(vector_hits.len());
762 let mut fused = rrf_fuse(text_hits, vector_hits, fusion_limit, query_text);
763
764 if !fused.is_empty() {
767 let candidate_ids: Vec<Uuid> = fused.iter().map(|h| h.entity_id).collect();
768 let alive_page = self
769 .entities(token)?
770 .query_entities(
771 token.namespace().as_str(),
772 EntityFilter {
773 ids: candidate_ids,
774 kinds: entity_kind.map(|k| vec![k.to_string()]).unwrap_or_default(),
775 entity_types: entity_type.map(|t| vec![t.to_string()]).unwrap_or_default(),
776 namespaces: visible_ns,
777 tags_any: tags_any.to_vec(),
778 ..EntityFilter::default()
779 },
780 PageRequest {
781 offset: 0,
782 limit: u32::try_from(fused.len()).unwrap_or(u32::MAX),
783 },
784 )
785 .await?;
786 let mut entity_meta: HashMap<Uuid, (String, Option<String>)> = HashMap::new();
787 let mut alive: HashSet<Uuid> = HashSet::new();
788 for e in alive_page.items {
789 if let Some(pf) = properties_filter {
792 if !entity_props_match(e.properties.as_ref(), pf) {
793 continue;
794 }
795 }
796 alive.insert(e.id);
797 entity_meta.insert(e.id, (e.name, e.description));
798 }
799
800 fused.retain(|h| alive.contains(&h.entity_id));
801
802 for hit in &mut fused {
804 if let Some((name, description)) = entity_meta.get(&hit.entity_id) {
805 if hit.title.is_none() {
806 hit.title = Some(name.clone());
807 }
808 if hit.snippet.is_none() {
809 hit.snippet = description.clone();
810 }
811 }
812 }
813 }
814
815 fused.truncate(limit as usize);
816 Ok(fused)
817 }
818
819 pub async fn knn(
825 &self,
826 token: &NamespaceToken,
827 query_vector: Vec<f32>,
828 top_k: u32,
829 ) -> RuntimeResult<Vec<VectorSearchHit>> {
830 let ns = token.namespace().as_str().to_owned();
831 Ok(self
832 .vectors(token)?
833 .search(VectorSearchRequest {
834 query_vectors: vec![query_vector],
835 top_k,
836 namespace: Some(ns),
837 kind: Some(SubstrateKind::Entity),
838 embedding_model: None,
839 filter: None,
840 backend_hints: None,
841 })
842 .await?)
843 }
844
845 pub async fn rerank(
851 &self,
852 token: &NamespaceToken,
853 query_vector: &[f32],
854 candidate_ids: &[Uuid],
855 top_k: u32,
856 ) -> RuntimeResult<Vec<VectorSearchHit>> {
857 let candidate_set: HashSet<Uuid> = candidate_ids.iter().copied().collect();
858 let ns = token.namespace().as_str().to_owned();
859 let all_hits = self
860 .vectors(token)?
861 .search(VectorSearchRequest {
862 query_vectors: vec![query_vector.to_vec()],
863 top_k: candidate_ids.len() as u32,
864 namespace: Some(ns),
865 kind: Some(SubstrateKind::Entity),
866 embedding_model: None,
867 filter: None,
868 backend_hints: None,
869 })
870 .await?;
871 let mut hits: Vec<VectorSearchHit> = all_hits
872 .into_iter()
873 .filter(|h| candidate_set.contains(&h.subject_id))
874 .collect();
875 hits.sort_by_key(|hit| std::cmp::Reverse(hit.score));
876 hits.truncate(top_k as usize);
877 Ok(hits)
878 }
879
880 pub async fn backfill_missing_embeddings(&self, token: &NamespaceToken) -> RuntimeResult<u64> {
893 use khive_storage::types::{SqlRow, SqlStatement, SqlValue};
894
895 let model_names = self.registered_embedding_model_names();
896 if model_names.is_empty() {
897 tracing::debug!(
898 "backfill_missing_embeddings: no embedding models registered, skipping"
899 );
900 return Ok(0);
901 }
902
903 let ns = token.namespace().as_str().to_string();
904 let mut total_backfilled = 0u64;
905
906 for model_name in &model_names {
907 let mut model_truncation = EmbeddingTruncationReport::default();
908 let vec_table = format!("vec_{}", sanitize_key(model_name));
910
911 const PAGE_SIZE: usize = 500;
915 let mut entity_total = 0usize;
916 loop {
917 let entity_sql = SqlStatement {
918 sql: format!(
919 "SELECT id, name, description FROM entities \
920 WHERE namespace = ?1 AND deleted_at IS NULL \
921 AND id NOT IN (\
922 SELECT subject_id FROM {vec_table} \
923 WHERE namespace = ?1 AND embedding_model = ?2 \
924 ) LIMIT {PAGE_SIZE}"
925 ),
926 params: vec![
927 SqlValue::Text(ns.clone()),
928 SqlValue::Text(model_name.clone()),
929 ],
930 label: Some("backfill_entities".into()),
931 };
932
933 let entity_rows: Vec<SqlRow> = {
934 let sql = self.sql();
935 let reader_result = sql.reader().await;
936 #[cfg(any(test, feature = "fault-injection"))]
937 let reader_result = if BACKFILL_READER_FAIL.with(|c| c.get()) {
938 BACKFILL_READER_FAIL.with(|c| c.set(false));
939 Err(khive_storage::StorageError::Pool {
940 operation: "reader".into(),
941 message: "injected failure".into(),
942 })
943 } else {
944 reader_result
945 };
946 let mut reader = reader_result.map_err(RuntimeError::Storage)?;
947 reader
948 .query_all(entity_sql)
949 .await
950 .map_err(RuntimeError::Storage)?
951 };
952
953 let batch_len = entity_rows.len();
954 entity_total += batch_len;
955
956 for row in &entity_rows {
957 let id_str = row.columns.first().and_then(|c| {
958 if let SqlValue::Text(s) = &c.value {
959 Some(s.clone())
960 } else {
961 None
962 }
963 });
964 let description = row.columns.get(2).and_then(|c| {
965 if let SqlValue::Text(s) = &c.value {
966 Some(s.clone())
967 } else if let SqlValue::Null = &c.value {
968 None
969 } else {
970 None
971 }
972 });
973
974 let (Some(id_str), Some(desc)) = (id_str, description) else {
975 continue;
976 };
977 let Ok(id) = id_str.parse::<Uuid>() else {
978 continue;
979 };
980 if desc.trim().is_empty() {
981 continue;
982 }
983
984 match self
985 .embed_document_with_model_outcome_for_token(token, model_name, &desc)
986 .await
987 {
988 Ok(outcome) => {
989 model_truncation.observe(&outcome);
990 if let Ok(vs) = self.vectors_for_model(token, model_name) {
991 match vs
992 .insert(
993 id,
994 SubstrateKind::Entity,
995 &ns,
996 "entity.description",
997 vec![outcome.vector],
998 )
999 .await
1000 {
1001 Ok(()) => {
1002 total_backfilled += 1;
1003 }
1004 Err(e) => {
1005 tracing::warn!(
1006 id = %id, model = %model_name,
1007 error = %e,
1008 "backfill_missing_embeddings: entity vector insert failed"
1009 );
1010 }
1011 }
1012 }
1013 }
1014 Err(e) => {
1015 tracing::warn!(
1016 id = %id, model = %model_name,
1017 error = %e,
1018 "backfill_missing_embeddings: entity embed failed"
1019 );
1020 }
1021 }
1022 }
1023
1024 if batch_len < PAGE_SIZE {
1025 break;
1026 }
1027 }
1028
1029 let text_store = self.text_for_notes(token).ok();
1031 let note_store = self.notes(token).ok();
1032 let mut note_total = 0usize;
1033 loop {
1034 let note_sql = SqlStatement {
1037 sql: format!(
1038 "SELECT id FROM notes \
1039 WHERE namespace = ?1 AND deleted_at IS NULL \
1040 AND id NOT IN (\
1041 SELECT subject_id FROM {vec_table} \
1042 WHERE namespace = ?1 AND embedding_model = ?2 \
1043 ) LIMIT {PAGE_SIZE}"
1044 ),
1045 params: vec![
1046 SqlValue::Text(ns.clone()),
1047 SqlValue::Text(model_name.clone()),
1048 ],
1049 label: Some("backfill_notes".into()),
1050 };
1051
1052 let note_rows: Vec<SqlRow> = {
1053 let sql = self.sql();
1054 let reader_result = sql.reader().await;
1055 #[cfg(any(test, feature = "fault-injection"))]
1056 let reader_result = if BACKFILL_READER_FAIL.with(|c| c.get()) {
1057 BACKFILL_READER_FAIL.with(|c| c.set(false));
1058 Err(khive_storage::StorageError::Pool {
1059 operation: "reader".into(),
1060 message: "injected failure".into(),
1061 })
1062 } else {
1063 reader_result
1064 };
1065 let mut reader = reader_result.map_err(RuntimeError::Storage)?;
1066 reader
1067 .query_all(note_sql)
1068 .await
1069 .map_err(RuntimeError::Storage)?
1070 };
1071
1072 let batch_len = note_rows.len();
1073 note_total += batch_len;
1074
1075 for row in ¬e_rows {
1076 let id_str = row.columns.first().and_then(|c| {
1077 if let SqlValue::Text(s) = &c.value {
1078 Some(s.clone())
1079 } else {
1080 None
1081 }
1082 });
1083
1084 let Some(id_str) = id_str else {
1085 continue;
1086 };
1087 let Ok(id) = id_str.parse::<Uuid>() else {
1088 continue;
1089 };
1090
1091 let note = match ¬e_store {
1092 Some(store) => match store.get_note(id).await {
1093 Ok(Some(n)) => n,
1094 _ => continue,
1095 },
1096 None => continue,
1097 };
1098
1099 if note.content.trim().is_empty() {
1100 continue;
1101 }
1102
1103 if model_names.first().map(|n| n.as_str()) == Some(model_name.as_str()) {
1106 if let Some(ref ts) = text_store {
1107 if let Err(e) = ts.upsert_document(note_fts_document(¬e)).await {
1108 tracing::warn!(id = %id, error = %e,
1109 "backfill_missing_embeddings: note FTS upsert failed");
1110 }
1111 }
1112 }
1113
1114 let content = note.content.clone();
1115 match self
1116 .embed_document_with_model_outcome_for_token(token, model_name, &content)
1117 .await
1118 {
1119 Ok(outcome) => {
1120 model_truncation.observe(&outcome);
1121 if let Ok(vs) = self.vectors_for_model(token, model_name) {
1122 match vs
1123 .insert(
1124 id,
1125 SubstrateKind::Note,
1126 &ns,
1127 "note.content",
1128 vec![outcome.vector],
1129 )
1130 .await
1131 {
1132 Ok(()) => {
1133 total_backfilled += 1;
1134 }
1135 Err(e) => {
1136 tracing::warn!(
1137 id = %id, model = %model_name,
1138 error = %e,
1139 "backfill_missing_embeddings: note vector insert failed"
1140 );
1141 }
1142 }
1143 }
1144 }
1145 Err(e) => {
1146 tracing::warn!(
1147 id = %id, model = %model_name,
1148 error = %e,
1149 "backfill_missing_embeddings: note embed failed"
1150 );
1151 }
1152 }
1153 }
1154
1155 if batch_len < PAGE_SIZE {
1156 break;
1157 }
1158 }
1159
1160 tracing::info!(
1161 model = %model_name,
1162 namespace = %ns,
1163 entities = entity_total,
1164 notes = note_total,
1165 truncated = model_truncation.truncated,
1166 discarded_bytes = model_truncation.discarded_bytes,
1167 "backfill_missing_embeddings: model pass complete"
1168 );
1169 }
1170
1171 tracing::info!(
1172 namespace = %ns,
1173 total_backfilled = total_backfilled,
1174 "backfill_missing_embeddings: finished"
1175 );
1176
1177 Ok(total_backfilled)
1178 }
1179
1180 pub async fn sweep_orphan_vectors(
1195 &self,
1196 token: &NamespaceToken,
1197 max_delete_per_model: u32,
1198 dry_run: bool,
1199 ) -> RuntimeResult<u64> {
1200 use khive_storage::types::OrphanSweepConfig;
1201 use khive_storage::StorageError;
1202
1203 let model_names = self.registered_embedding_model_names();
1204 if model_names.is_empty() {
1205 tracing::debug!("sweep_orphan_vectors: no embedding models registered, skipping");
1206 return Ok(0);
1207 }
1208
1209 let ns = token.namespace().as_str().to_string();
1210 let mut total_deleted = 0u64;
1211
1212 for model_name in &model_names {
1213 let store = match self.vectors_for_model(token, model_name) {
1214 Ok(s) => s,
1215 Err(e) => {
1216 tracing::warn!(
1217 model = %model_name,
1218 error = %e,
1219 "sweep_orphan_vectors: failed to get vector store, skipping model"
1220 );
1221 continue;
1222 }
1223 };
1224
1225 let caps = store.capabilities();
1226 if !caps.supports_orphan_sweep {
1227 tracing::debug!(
1228 model = %model_name,
1229 "sweep_orphan_vectors: backend does not support orphan sweep, skipping"
1230 );
1231 continue;
1232 }
1233
1234 let config = OrphanSweepConfig {
1235 subject_id_allowlist: None,
1236 namespaces: vec![ns.clone()],
1237 substrate_kinds: vec![],
1238 max_delete: max_delete_per_model,
1239 dry_run,
1240 };
1241
1242 match store.orphan_sweep(&config).await {
1243 Ok(result) => {
1244 tracing::info!(
1245 model = %model_name,
1246 namespace = %ns,
1247 scanned = result.scanned,
1248 deleted = result.deleted,
1249 would_delete = result.would_delete,
1250 dry_run = dry_run,
1251 "sweep_orphan_vectors: sweep complete"
1252 );
1253 total_deleted += result.deleted;
1254 }
1255 Err(StorageError::Unsupported { .. }) => {
1256 tracing::debug!(
1257 model = %model_name,
1258 "sweep_orphan_vectors: backend returned Unsupported, skipping"
1259 );
1260 }
1261 Err(e) => {
1262 tracing::warn!(
1263 model = %model_name,
1264 error = %e,
1265 "sweep_orphan_vectors: sweep failed, continuing with other models"
1266 );
1267 }
1268 }
1269 }
1270
1271 tracing::info!(
1272 namespace = %ns,
1273 total_deleted = total_deleted,
1274 dry_run = dry_run,
1275 "sweep_orphan_vectors: finished"
1276 );
1277
1278 Ok(total_deleted)
1279 }
1280}
1281
1282fn entity_props_match(
1287 entity_props: Option<&serde_json::Value>,
1288 filter: &serde_json::Value,
1289) -> bool {
1290 let required = match filter.as_object() {
1291 Some(obj) if !obj.is_empty() => obj,
1292 _ => return true,
1293 };
1294 let actual = match entity_props.and_then(serde_json::Value::as_object) {
1295 Some(obj) => obj,
1296 None => return false,
1297 };
1298 required
1299 .iter()
1300 .all(|(k, v)| actual.get(k).is_some_and(|av| av == v))
1301}
1302
1303const EXACT_MATCH_BOOST: f64 = 0.5;
1307
1308fn rrf_fuse(
1316 text_hits: Vec<TextSearchHit>,
1317 vector_hits: Vec<VectorSearchHit>,
1318 limit: usize,
1319 query_text: &str,
1320) -> Vec<SearchHit> {
1321 #[derive(Default)]
1322 struct Bucket {
1323 score: DeterministicScore,
1324 source: Option<SearchSource>,
1325 title: Option<String>,
1326 snippet: Option<String>,
1327 }
1328
1329 let mut buckets: HashMap<Uuid, Bucket> = HashMap::new();
1330
1331 let query_lower = query_text.to_lowercase();
1332 let mut text_seen = HashSet::with_capacity(text_hits.len());
1333 for (i, hit) in text_hits.into_iter().enumerate() {
1334 if !text_seen.insert(hit.subject_id) {
1335 continue;
1336 }
1337 let rank = i + 1; let entry = buckets.entry(hit.subject_id).or_default();
1339 entry.score = entry.score + rrf_score(rank, RRF_K);
1340 entry.source = Some(match entry.source {
1341 Some(SearchSource::Vector) => SearchSource::Both,
1342 _ => SearchSource::Text,
1343 });
1344 if entry.title.is_none() {
1345 if let Some(ref title) = hit.title {
1347 if title.to_lowercase() == query_lower {
1348 entry.score = entry.score + DeterministicScore::from_f64(EXACT_MATCH_BOOST);
1349 }
1350 }
1351 entry.title = hit.title;
1352 }
1353 if entry.snippet.is_none() {
1354 entry.snippet = hit.snippet;
1355 }
1356 }
1357
1358 let mut vector_seen = HashSet::with_capacity(vector_hits.len());
1359 for (i, hit) in vector_hits.into_iter().enumerate() {
1360 if !vector_seen.insert(hit.subject_id) {
1361 continue;
1362 }
1363 let rank = i + 1;
1364 let entry = buckets.entry(hit.subject_id).or_default();
1365 entry.score = entry.score + rrf_score(rank, RRF_K);
1366 entry.source = Some(match entry.source {
1367 Some(SearchSource::Text) => SearchSource::Both,
1368 _ => SearchSource::Vector,
1369 });
1370 }
1371
1372 let mut hits: Vec<SearchHit> = buckets
1373 .into_iter()
1374 .map(|(id, b)| SearchHit {
1375 entity_id: id,
1376 score: b.score,
1377 source: b.source.expect("each bucket gets a source"),
1378 title: b.title,
1379 snippet: b.snippet,
1380 })
1381 .collect();
1382
1383 hits.sort_by(|a, b| b.score.cmp(&a.score).then(a.entity_id.cmp(&b.entity_id)));
1384 hits.truncate(limit);
1385 hits
1386}
1387
1388#[cfg(test)]
1389mod tests {
1390 use super::*;
1391 use crate::runtime::{KhiveRuntime, NamespaceToken, RuntimeConfig};
1392 use khive_storage::types::{TextSearchHit, VectorSearchHit};
1393 use khive_types::namespace::Namespace;
1394 use lattice_embed::EmbeddingModel;
1395
1396 #[test]
1397 fn bounded_embedding_input_reserves_prefix_and_preserves_utf8() {
1398 assert_eq!(
1399 document_embedding_budget("multilingual-e5-base"),
1400 MAX_TEXT_CHARS - "passage: ".len()
1401 );
1402
1403 let input = format!("{}\u{1f980}tail", "a".repeat(MAX_TEXT_CHARS - 1));
1404 let (bounded, truncated) = bounded_embedding_input(&input, MAX_TEXT_CHARS);
1405 assert!(truncated);
1406 assert_eq!(bounded.len(), MAX_TEXT_CHARS - 1);
1407 assert!(bounded.is_char_boundary(bounded.len()));
1408 assert!(!bounded.contains('\u{1f980}'));
1409 }
1410
1411 #[test]
1412 fn bounded_embedding_input_leaves_normal_text_unchanged() {
1413 let input = "normal byte-identical embedding input";
1414 let (bounded, truncated) = bounded_embedding_input(input, MAX_TEXT_CHARS);
1415 assert!(!truncated);
1416 assert_eq!(bounded, input);
1417 assert_eq!(bounded.as_ptr(), input.as_ptr());
1418 }
1419
1420 fn text_hit(id: Uuid, rank: u32, title: &str) -> TextSearchHit {
1421 TextSearchHit {
1422 subject_id: id,
1423 score: DeterministicScore::from_f64(1.0),
1424 rank,
1425 title: Some(title.to_string()),
1426 snippet: Some("...".to_string()),
1427 }
1428 }
1429
1430 fn vector_hit(id: Uuid, rank: u32) -> VectorSearchHit {
1431 VectorSearchHit {
1432 subject_id: id,
1433 score: DeterministicScore::from_f64(0.9),
1434 rank,
1435 }
1436 }
1437
1438 #[test]
1439 fn rrf_fuse_text_only() {
1440 let a = Uuid::new_v4();
1441 let b = Uuid::new_v4();
1442 let text = vec![text_hit(a, 1, "A"), text_hit(b, 2, "B")];
1443 let hits = rrf_fuse(text, vec![], 10, "query");
1444 assert_eq!(hits.len(), 2);
1445 assert_eq!(hits[0].entity_id, a);
1446 assert_eq!(hits[0].source, SearchSource::Text);
1447 assert_eq!(hits[0].title.as_deref(), Some("A"));
1448 }
1449
1450 #[test]
1451 fn rrf_fuse_vector_only() {
1452 let a = Uuid::new_v4();
1453 let hits = rrf_fuse(vec![], vec![vector_hit(a, 1)], 10, "query");
1454 assert_eq!(hits.len(), 1);
1455 assert_eq!(hits[0].source, SearchSource::Vector);
1456 assert!(hits[0].title.is_none());
1457 }
1458
1459 #[test]
1460 fn rrf_fuse_marks_both_when_in_both_lists() {
1461 let id = Uuid::new_v4();
1462 let text = vec![text_hit(id, 1, "A")];
1463 let vec = vec![vector_hit(id, 1)];
1464 let hits = rrf_fuse(text, vec, 10, "query");
1465 assert_eq!(hits.len(), 1);
1466 assert_eq!(hits[0].source, SearchSource::Both);
1467 }
1468
1469 #[test]
1470 fn rrf_fuse_preserves_unique_leg_scores_exactly() {
1471 let text_only = Uuid::new_v4();
1472 let both = Uuid::new_v4();
1473 let vector_only = Uuid::new_v4();
1474 let text = vec![text_hit(text_only, 1, "A"), text_hit(both, 2, "B")];
1475 let vector = vec![vector_hit(both, 1), vector_hit(vector_only, 2)];
1476
1477 let hits = rrf_fuse(text, vector, 10, "query");
1478 let score_for = |id| {
1479 hits.iter()
1480 .find(|hit| hit.entity_id == id)
1481 .expect("expected fused hit")
1482 .score
1483 };
1484
1485 assert_eq!(score_for(text_only), rrf_score(1, RRF_K));
1486 assert_eq!(score_for(both), rrf_score(2, RRF_K) + rrf_score(1, RRF_K));
1487 assert_eq!(score_for(vector_only), rrf_score(2, RRF_K));
1488 }
1489
1490 #[test]
1491 fn rrf_fuse_counts_duplicate_once_per_leg() {
1492 let id = Uuid::new_v4();
1493 let text = vec![text_hit(id, 1, "A"), text_hit(id, 2, "A duplicate")];
1494 let vector = vec![vector_hit(id, 1), vector_hit(id, 2)];
1495
1496 let hits = rrf_fuse(text, vector, 10, "query");
1497
1498 assert_eq!(hits.len(), 1);
1499 assert_eq!(hits[0].source, SearchSource::Both);
1500 assert_eq!(hits[0].score, rrf_score(1, RRF_K) + rrf_score(1, RRF_K));
1501 }
1502
1503 #[test]
1504 fn rrf_fuse_respects_limit() {
1505 let hits: Vec<TextSearchHit> = (0..20)
1506 .map(|i| text_hit(Uuid::new_v4(), i + 1, "x"))
1507 .collect();
1508 let fused = rrf_fuse(hits, vec![], 5, "query");
1509 assert_eq!(fused.len(), 5);
1510 }
1511
1512 #[test]
1513 fn rrf_fuse_orders_higher_score_first() {
1514 let a = Uuid::new_v4();
1516 let b = Uuid::new_v4();
1517 let text = vec![text_hit(a, 1, "A")];
1518 let vec = vec![vector_hit(a, 1), vector_hit(b, 2)];
1519 let hits = rrf_fuse(text, vec, 10, "query");
1520 assert_eq!(hits[0].entity_id, a);
1521 assert_eq!(hits[0].source, SearchSource::Both);
1522 assert!(hits[0].score > hits[1].score);
1523 }
1524
1525 #[test]
1526 fn rrf_fuse_k10_score_spread_exceeds_threshold() {
1527 let ids: Vec<Uuid> = (0..10).map(|_| Uuid::new_v4()).collect();
1530 let text: Vec<TextSearchHit> = ids
1531 .iter()
1532 .enumerate()
1533 .map(|(i, &id)| text_hit(id, (i + 1) as u32, "x"))
1534 .collect();
1535 let hits = rrf_fuse(text, vec![], 10, "query");
1536 assert_eq!(hits.len(), 10);
1537 let top_score = hits[0].score.to_f64();
1538 let bottom_score = hits[9].score.to_f64();
1539 let spread = top_score - bottom_score;
1540 assert!(
1541 spread >= 0.03,
1542 "score spread {spread:.4} between rank 1 and rank 10 must be ≥ 0.03 (was {spread:.4})"
1543 );
1544 }
1545
1546 #[test]
1547 fn rrf_fuse_exact_match_boost_elevates_score() {
1548 let exact_id = Uuid::new_v4();
1551 let other_id = Uuid::new_v4();
1552 let text = vec![
1554 text_hit(other_id, 1, "something else"),
1555 text_hit(exact_id, 2, "FlashAttention"),
1556 ];
1557 let hits = rrf_fuse(text, vec![], 10, "flashattention");
1558 assert_eq!(hits.len(), 2);
1559 assert_eq!(
1560 hits[0].entity_id, exact_id,
1561 "exact match must rank first despite being rank-2 in raw text search"
1562 );
1563 }
1564
1565 #[test]
1568 fn embed_batch_unconfigured_on_memory_runtime() {
1569 let rt = KhiveRuntime::memory().unwrap();
1571 let result = tokio::runtime::Runtime::new()
1572 .unwrap()
1573 .block_on(rt.embed_batch(&[]));
1574 assert!(result.is_ok());
1576 assert!(result.unwrap().is_empty());
1577 }
1578
1579 #[test]
1580 fn embed_batch_empty_input_returns_empty_vec() {
1581 let rt = KhiveRuntime::memory().unwrap();
1583 let result = tokio::runtime::Runtime::new()
1584 .unwrap()
1585 .block_on(rt.embed_batch(&[]));
1586 assert_eq!(result.unwrap(), Vec::<Vec<f32>>::new());
1587 }
1588
1589 #[test]
1590 fn embed_batch_no_model_non_empty_returns_unconfigured() {
1591 let rt = KhiveRuntime::memory().unwrap();
1592 let texts = vec!["hello".to_string()];
1593 let result = tokio::runtime::Runtime::new()
1594 .unwrap()
1595 .block_on(rt.embed_batch(&texts));
1596 match result {
1597 Err(crate::RuntimeError::Unconfigured(s)) => assert_eq!(s, "embedding_model"),
1598 Err(other) => panic!("expected Unconfigured, got {:?}", other),
1599 Ok(_) => panic!("expected Err, got Ok"),
1600 }
1601 }
1602
1603 #[test]
1604 #[ignore = "loads ~80 MB model; run with --include-ignored"]
1605 fn embed_batch_count_matches_input() {
1606 let config = RuntimeConfig {
1607 db_path: None,
1608 default_namespace: Namespace::parse("test").unwrap(),
1609 embedding_model: Some(EmbeddingModel::AllMiniLmL6V2),
1610 packs: vec!["kg".to_string()],
1611 ..RuntimeConfig::default()
1612 };
1613 let rt = KhiveRuntime::new(config).unwrap();
1614 let texts: Vec<String> = vec!["foo".to_string(), "bar".to_string(), "baz".to_string()];
1615 let result = tokio::runtime::Runtime::new()
1616 .unwrap()
1617 .block_on(rt.embed_batch(&texts));
1618 let embeddings = result.unwrap();
1619 assert_eq!(embeddings.len(), texts.len());
1620 }
1621
1622 #[test]
1623 fn vector_search_requires_embedding_or_text() {
1624 let rt = KhiveRuntime::memory().unwrap();
1625 let tok = NamespaceToken::local();
1626 let result = tokio::runtime::Runtime::new()
1627 .unwrap()
1628 .block_on(rt.vector_search(&tok, None, None, 10, Some(SubstrateKind::Entity)));
1629 match result {
1630 Err(crate::RuntimeError::InvalidInput(msg)) => {
1631 assert!(msg.contains("query_embedding or query_text"), "msg: {msg}");
1632 }
1633 other => panic!("expected InvalidInput, got {other:?}"),
1634 }
1635 }
1636
1637 #[test]
1638 fn vector_search_text_without_model_returns_unconfigured() {
1639 let rt = KhiveRuntime::memory().unwrap();
1640 let tok = NamespaceToken::local();
1641 let result = tokio::runtime::Runtime::new()
1642 .unwrap()
1643 .block_on(rt.vector_search(
1644 &tok,
1645 None,
1646 Some("attention"),
1647 10,
1648 Some(SubstrateKind::Entity),
1649 ));
1650 match result {
1651 Err(crate::RuntimeError::Unconfigured(s)) => assert_eq!(s, "embedding_model"),
1652 other => panic!("expected Unconfigured, got {other:?}"),
1653 }
1654 }
1655
1656 #[test]
1657 #[ignore = "loads ~80 MB model; run with --include-ignored"]
1658 fn embed_batch_vectors_have_expected_dimensions() {
1659 let model = EmbeddingModel::AllMiniLmL6V2;
1660 let config = RuntimeConfig {
1661 db_path: None,
1662 default_namespace: Namespace::parse("test").unwrap(),
1663 embedding_model: Some(model),
1664 packs: vec!["kg".to_string()],
1665 ..RuntimeConfig::default()
1666 };
1667 let rt = KhiveRuntime::new(config).unwrap();
1668 let texts = vec!["hello world".to_string()];
1669 let result = tokio::runtime::Runtime::new()
1670 .unwrap()
1671 .block_on(rt.embed_batch(&texts));
1672 let embeddings = result.unwrap();
1673 assert_eq!(embeddings[0].len(), model.dimensions());
1674 }
1675
1676 #[tokio::test]
1679 async fn hybrid_search_entity_hit_has_title() {
1680 let rt = KhiveRuntime::memory().unwrap();
1681 let tok = NamespaceToken::local();
1682 rt.create_entity(
1683 &tok,
1684 "concept",
1685 None,
1686 "FlashAttention",
1687 Some("IO-aware exact attention using tiling"),
1688 None,
1689 vec![],
1690 )
1691 .await
1692 .unwrap();
1693
1694 let hits = rt
1695 .hybrid_search(&tok, "FlashAttention", None, 10, None, None, &[], None)
1696 .await
1697 .unwrap();
1698
1699 assert!(!hits.is_empty(), "should find the entity");
1700 let hit = &hits[0];
1701 assert!(hit.title.is_some(), "title must be populated");
1702 assert!(
1703 hit.title.as_deref().unwrap().contains("FlashAttention"),
1704 "title must contain entity name"
1705 );
1706 }
1707
1708 #[tokio::test]
1714 async fn hybrid_search_with_dollar_sign_query_does_not_error() {
1715 let rt = KhiveRuntime::memory().unwrap();
1716 let tok = NamespaceToken::local();
1717 rt.create_entity(
1718 &tok,
1719 "concept",
1720 None,
1721 "DSL docs",
1722 Some("use $prev.id to chain calls"),
1723 None,
1724 vec![],
1725 )
1726 .await
1727 .unwrap();
1728
1729 let result = rt
1730 .hybrid_search(&tok, "$prev.id", None, 10, None, None, &[], None)
1731 .await;
1732
1733 assert!(
1734 result.is_ok(),
1735 "#388 hybrid_search must not hard-fail on a '$'-bearing query, got: {:?}",
1736 result.err()
1737 );
1738 }
1739
1740 #[tokio::test]
1749 async fn hybrid_search_with_residual_fts5_char_now_sanitized() {
1750 let rt = KhiveRuntime::memory().unwrap();
1751 let tok = NamespaceToken::local();
1752 rt.create_entity(
1753 &tok,
1754 "concept",
1755 None,
1756 "DSL docs",
1757 Some("use foo@bar to chain calls"),
1758 None,
1759 vec![],
1760 )
1761 .await
1762 .unwrap();
1763
1764 let result = rt
1765 .hybrid_search(&tok, "foo@bar", None, 10, None, None, &[], None)
1766 .await;
1767
1768 let hits = result.unwrap_or_else(|e| {
1769 panic!("#916 hybrid_search must not fail on an '@'-bearing query, got: {e:?}")
1770 });
1771 assert!(
1772 !hits.is_empty(),
1773 "#916 '@'-bearing query must still find the seeded 'foo@bar' content via the \
1774 quoted-phrase alternative"
1775 );
1776 }
1777
1778 #[tokio::test]
1786 async fn hybrid_search_with_916_issue_characters_finds_text_leg_hits() {
1787 let rt = KhiveRuntime::memory().unwrap();
1788 let tok = NamespaceToken::local();
1789
1790 rt.create_entity(
1791 &tok,
1792 "concept",
1793 None,
1794 "issue tracker",
1795 Some("tracking #682 Stage 2: MoE expert-cache prefetch work"),
1796 None,
1797 vec![],
1798 )
1799 .await
1800 .unwrap();
1801 rt.create_entity(
1802 &tok,
1803 "concept",
1804 None,
1805 "benchmark notes",
1806 Some("chunkwise B=128 traffic arithmetic simdgroup_matrix DPLR"),
1807 None,
1808 vec![],
1809 )
1810 .await
1811 .unwrap();
1812 rt.create_entity(
1813 &tok,
1814 "concept",
1815 None,
1816 "sampling notes",
1817 Some("evaluated with the Min-K%Prob membership inference method"),
1818 None,
1819 vec![],
1820 )
1821 .await
1822 .unwrap();
1823
1824 for query in ["#682 Stage 2", "B=128", "Min-K%Prob"] {
1825 let result = rt
1826 .hybrid_search(&tok, query, None, 10, None, None, &[], None)
1827 .await;
1828 let hits = result.unwrap_or_else(|e| {
1829 panic!("#916 hybrid_search must not fail on query {query:?}, got: {e:?}")
1830 });
1831 assert!(
1832 hits.iter()
1833 .any(|h| matches!(h.source, SearchSource::Text | SearchSource::Both)),
1834 "#916 query {query:?} must surface a Text/Both-sourced hit \
1835 (the FTS leg must contribute, not just the vector leg); got {hits:?}"
1836 );
1837 }
1838 }
1839
1840 #[tokio::test]
1854 async fn hybrid_search_tag_filter_pushed_before_truncation() {
1855 let rt = KhiveRuntime::memory().unwrap();
1856 let tok = NamespaceToken::local();
1857
1858 rt.create_entity(
1860 &tok,
1861 "concept",
1862 None,
1863 "alpha beta gamma decoy alpha beta gamma",
1864 Some("alpha beta gamma decoy description alpha beta gamma"),
1865 None,
1866 vec!["other-tag".to_string()],
1867 )
1868 .await
1869 .unwrap();
1870
1871 let target = rt
1873 .create_entity(
1874 &tok,
1875 "concept",
1876 None,
1877 "alpha beta gamma target",
1878 Some("alpha beta gamma target description"),
1879 None,
1880 vec!["target-tag".to_string()],
1881 )
1882 .await
1883 .unwrap();
1884
1885 let hits = rt
1889 .hybrid_search(
1890 &tok,
1891 "alpha beta gamma",
1892 None,
1893 1,
1894 None,
1895 None,
1896 &["target-tag".to_string()],
1897 None,
1898 )
1899 .await
1900 .unwrap();
1901
1902 assert_eq!(
1903 hits.len(),
1904 1,
1905 "exactly one hit expected (the tag-matching entity)"
1906 );
1907 assert_eq!(
1908 hits[0].entity_id, target.id,
1909 "the tag-filtered entity must be returned even when ranked below limit in raw fusion"
1910 );
1911 }
1912
1913 #[tokio::test]
1922 async fn hybrid_search_props_filter_pushed_before_truncation() {
1923 let rt = KhiveRuntime::memory().unwrap();
1924 let tok = NamespaceToken::local();
1925
1926 rt.create_entity(
1927 &tok,
1928 "concept",
1929 None,
1930 "delta epsilon zeta decoy delta epsilon zeta",
1931 Some("delta epsilon zeta decoy description delta epsilon zeta"),
1932 Some(serde_json::json!({"domain": "other"})),
1933 vec![],
1934 )
1935 .await
1936 .unwrap();
1937
1938 let target = rt
1939 .create_entity(
1940 &tok,
1941 "concept",
1942 None,
1943 "delta epsilon zeta target",
1944 Some("delta epsilon zeta target description"),
1945 Some(serde_json::json!({"domain": "target"})),
1946 vec![],
1947 )
1948 .await
1949 .unwrap();
1950
1951 let filter = serde_json::json!({"domain": "target"});
1952 let hits = rt
1953 .hybrid_search(
1954 &tok,
1955 "delta epsilon zeta",
1956 None,
1957 1,
1958 None,
1959 None,
1960 &[],
1961 Some(&filter),
1962 )
1963 .await
1964 .unwrap();
1965
1966 assert_eq!(hits.len(), 1, "exactly one hit expected (properties match)");
1967 assert_eq!(
1968 hits[0].entity_id, target.id,
1969 "the properties-filtered entity must be returned even when ranked below limit"
1970 );
1971 }
1972
1973 struct CapturingEmbeddingService {
1976 captured: std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
1977 }
1978
1979 #[async_trait::async_trait]
1980 impl EmbeddingService for CapturingEmbeddingService {
1981 async fn embed(
1982 &self,
1983 texts: &[String],
1984 _model: EmbeddingModel,
1985 ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
1986 self.captured.lock().unwrap().push(texts.to_vec());
1987 Ok(texts.iter().map(|_| vec![1.0]).collect())
1988 }
1989
1990 fn supports_model(&self, _model: EmbeddingModel) -> bool {
1991 true
1992 }
1993
1994 fn name(&self) -> &'static str {
1995 "capturing-embedding-service"
1996 }
1997 }
1998
1999 struct CapturingEmbedderProvider {
2000 name: String,
2001 captured: std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
2002 }
2003
2004 struct WrongCardinalityEmbeddingService;
2005
2006 #[async_trait::async_trait]
2007 impl EmbeddingService for WrongCardinalityEmbeddingService {
2008 async fn embed(
2009 &self,
2010 texts: &[String],
2011 _model: EmbeddingModel,
2012 ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
2013 Ok(texts
2014 .iter()
2015 .take(texts.len().saturating_sub(1))
2016 .map(|_| vec![1.0])
2017 .collect())
2018 }
2019
2020 fn supports_model(&self, _model: EmbeddingModel) -> bool {
2021 true
2022 }
2023
2024 fn name(&self) -> &'static str {
2025 "wrong-cardinality-embedding-service"
2026 }
2027 }
2028
2029 struct WrongCardinalityEmbedderProvider;
2030
2031 #[async_trait::async_trait]
2032 impl EmbedderProvider for WrongCardinalityEmbedderProvider {
2033 fn name(&self) -> &str {
2034 "wrong-cardinality-embedding-service"
2035 }
2036
2037 fn dimensions(&self) -> usize {
2038 1
2039 }
2040
2041 async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2042 Ok(std::sync::Arc::new(WrongCardinalityEmbeddingService))
2043 }
2044 }
2045
2046 struct SurplusCardinalityEmbeddingService;
2047
2048 #[async_trait::async_trait]
2049 impl EmbeddingService for SurplusCardinalityEmbeddingService {
2050 async fn embed(
2051 &self,
2052 texts: &[String],
2053 _model: EmbeddingModel,
2054 ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
2055 let mut vectors: Vec<Vec<f32>> = texts.iter().map(|_| vec![1.0]).collect();
2056 vectors.push(vec![1.0]);
2057 Ok(vectors)
2058 }
2059
2060 fn supports_model(&self, _model: EmbeddingModel) -> bool {
2061 true
2062 }
2063
2064 fn name(&self) -> &'static str {
2065 "surplus-cardinality-embedding-service"
2066 }
2067 }
2068
2069 struct SurplusCardinalityEmbedderProvider;
2070
2071 #[async_trait::async_trait]
2072 impl EmbedderProvider for SurplusCardinalityEmbedderProvider {
2073 fn name(&self) -> &str {
2074 "surplus-cardinality-embedding-service"
2075 }
2076
2077 fn dimensions(&self) -> usize {
2078 1
2079 }
2080
2081 async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2082 Ok(std::sync::Arc::new(SurplusCardinalityEmbeddingService))
2083 }
2084 }
2085
2086 #[async_trait::async_trait]
2087 impl EmbedderProvider for CapturingEmbedderProvider {
2088 fn name(&self) -> &str {
2089 &self.name
2090 }
2091
2092 fn dimensions(&self) -> usize {
2093 1
2094 }
2095
2096 async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2097 Ok(std::sync::Arc::new(CapturingEmbeddingService {
2098 captured: std::sync::Arc::clone(&self.captured),
2099 }))
2100 }
2101 }
2102
2103 fn runtime_with_capturing_embedder(
2104 model: EmbeddingModel,
2105 ) -> (
2106 KhiveRuntime,
2107 std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
2108 ) {
2109 let runtime = KhiveRuntime::memory().unwrap();
2110 let captured = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
2111 runtime.register_embedder(CapturingEmbedderProvider {
2112 name: model.to_string(),
2113 captured: std::sync::Arc::clone(&captured),
2114 });
2115 (runtime, captured)
2116 }
2117
2118 #[tokio::test]
2119 async fn bge_query_paths_pass_raw_unprefixed_text() {
2120 const BGE_QUERY_INSTRUCTION: &str =
2121 "Represent this sentence for searching relevant passages: ";
2122 let single = "single raw query";
2123 let batch = vec![
2124 "first raw query".to_string(),
2125 "second raw query".to_string(),
2126 ];
2127
2128 for model in [
2129 EmbeddingModel::BgeSmallEnV15,
2130 EmbeddingModel::BgeBaseEnV15,
2131 EmbeddingModel::BgeLargeEnV15,
2132 ] {
2133 let (runtime, captured) = runtime_with_capturing_embedder(model);
2134 runtime
2135 .embed_query_with_model(&model.to_string(), single)
2136 .await
2137 .unwrap();
2138 runtime
2139 .embed_query_batch_with_model(&model.to_string(), &batch)
2140 .await
2141 .unwrap();
2142
2143 let calls = captured.lock().unwrap().clone();
2144 assert_eq!(
2145 calls,
2146 vec![vec![single.to_string()], batch.clone()],
2147 "{model} must receive raw query text through single and batch paths"
2148 );
2149 assert!(
2150 calls
2151 .iter()
2152 .flatten()
2153 .all(|text| !text.contains(BGE_QUERY_INSTRUCTION)),
2154 "{model} must not receive the BGE retrieval instruction"
2155 );
2156 }
2157 }
2158
2159 #[tokio::test]
2160 async fn e5_query_paths_apply_query_prefix() {
2161 let model = EmbeddingModel::MultilingualE5Small;
2162 let single = "single raw query";
2163 let batch = vec![
2164 "first raw query".to_string(),
2165 "second raw query".to_string(),
2166 ];
2167 let (runtime, captured) = runtime_with_capturing_embedder(model);
2168
2169 runtime
2170 .embed_query_with_model(&model.to_string(), single)
2171 .await
2172 .unwrap();
2173 runtime
2174 .embed_query_batch_with_model(&model.to_string(), &batch)
2175 .await
2176 .unwrap();
2177
2178 assert_eq!(
2179 captured.lock().unwrap().as_slice(),
2180 [
2181 vec!["query: single raw query".to_string()],
2182 vec![
2183 "query: first raw query".to_string(),
2184 "query: second raw query".to_string(),
2185 ],
2186 ],
2187 "E5 must receive its query prefix through single and batch paths"
2188 );
2189 }
2190
2191 #[tokio::test]
2192 async fn mixed_document_batch_stays_one_ordered_provider_call() {
2193 let model = EmbeddingModel::AllMiniLmL6V2;
2194 let (runtime, captured) = runtime_with_capturing_embedder(model);
2195 let texts = vec![
2196 "first normal document".to_string(),
2197 "x".repeat(MAX_TEXT_CHARS + 1),
2198 "second normal document".to_string(),
2199 ];
2200
2201 let outcomes = runtime
2202 .embed_document_batch_with_model_outcomes(&model.to_string(), &texts)
2203 .await
2204 .expect("mixed batch must embed");
2205 assert_eq!(outcomes.len(), texts.len());
2206 assert!(!outcomes[0].truncated);
2207 assert_eq!(outcomes[0].source_bytes, outcomes[0].embedded_bytes);
2208 assert!(outcomes[1].truncated);
2209 assert_eq!(outcomes[1].source_bytes, MAX_TEXT_CHARS + 1);
2210 assert_eq!(outcomes[1].embedded_bytes, MAX_TEXT_CHARS);
2211 assert!(!outcomes[2].truncated);
2212 assert_eq!(
2213 captured.lock().unwrap().as_slice(),
2214 [vec![
2215 texts[0].clone(),
2216 "x".repeat(MAX_TEXT_CHARS),
2217 texts[2].clone(),
2218 ]]
2219 );
2220 }
2221
2222 #[tokio::test]
2223 async fn truncated_document_batch_rejects_provider_cardinality_mismatch() {
2224 let runtime = KhiveRuntime::memory().unwrap();
2225 runtime.register_embedder(WrongCardinalityEmbedderProvider);
2226 let model_name = "wrong-cardinality-embedding-service";
2227 let texts = vec!["x".repeat(MAX_TEXT_CHARS + 1), "normal".to_string()];
2228
2229 let error = runtime
2230 .embed_document_batch_with_model_outcomes(model_name, &texts)
2231 .await
2232 .expect_err("provider cardinality mismatch must fail the whole batch");
2233
2234 assert!(
2235 error
2236 .to_string()
2237 .contains("embed_passage returned 1 vectors for 2 inputs"),
2238 "unexpected error: {error}"
2239 );
2240 }
2241
2242 #[tokio::test]
2243 async fn singleton_document_embed_rejects_zero_vectors() {
2244 let runtime = KhiveRuntime::memory().unwrap();
2245 runtime.register_embedder(WrongCardinalityEmbedderProvider);
2246 let model_name = "wrong-cardinality-embedding-service";
2247
2248 let error = runtime
2249 .embed_document_with_model_outcome(model_name, "single document")
2250 .await
2251 .expect_err("provider returning zero vectors must fail closed");
2252
2253 assert!(
2254 error
2255 .to_string()
2256 .contains("embed_passage returned 0 vectors for 1 input"),
2257 "unexpected error: {error}"
2258 );
2259 }
2260
2261 #[tokio::test]
2262 async fn singleton_document_embed_rejects_surplus_vectors() {
2263 let runtime = KhiveRuntime::memory().unwrap();
2264 runtime.register_embedder(SurplusCardinalityEmbedderProvider);
2265 let model_name = "surplus-cardinality-embedding-service";
2266
2267 let error = runtime
2268 .embed_document_with_model_outcome(model_name, "single document")
2269 .await
2270 .expect_err("provider returning surplus vectors must fail closed");
2271
2272 assert!(
2273 error
2274 .to_string()
2275 .contains("embed_passage returned 2 vectors for 1 input"),
2276 "unexpected error: {error}"
2277 );
2278 }
2279
2280 #[test]
2281 #[ignore = "loads ~80 MB model; run with --include-ignored"]
2282 fn minilm_document_and_query_embed_are_identical_no_prefix_model() {
2283 let model = EmbeddingModel::AllMiniLmL6V2;
2287 let config = RuntimeConfig {
2288 db_path: None,
2289 default_namespace: Namespace::parse("test").unwrap(),
2290 embedding_model: Some(model),
2291 packs: vec!["kg".to_string()],
2292 ..RuntimeConfig::default()
2293 };
2294 let rt = KhiveRuntime::new(config).unwrap();
2295 let text = "attention is all you need".to_string();
2296 let rt_ref = &rt;
2297 let (doc_emb, query_emb) = tokio::runtime::Runtime::new().unwrap().block_on(async {
2298 let d = rt_ref
2299 .embed_document_with_model(&model.to_string(), &text)
2300 .await
2301 .unwrap();
2302 let q = rt_ref
2303 .embed_query_with_model(&model.to_string(), &text)
2304 .await
2305 .unwrap();
2306 (d, q)
2307 });
2308 assert_eq!(
2309 doc_emb, query_emb,
2310 "MiniLM has no instruction prefix: document and query embeds must be identical"
2311 );
2312 }
2313
2314 #[test]
2315 #[ignore = "loads multilingual-e5-small (~90 MB); run with --include-ignored"]
2316 fn e5_document_and_query_embed_differ_instruction_tuned_model() {
2317 let model = EmbeddingModel::MultilingualE5Small;
2322 let config = RuntimeConfig {
2323 db_path: None,
2324 default_namespace: Namespace::parse("test").unwrap(),
2325 embedding_model: Some(model),
2326 packs: vec!["kg".to_string()],
2327 ..RuntimeConfig::default()
2328 };
2329 let rt = KhiveRuntime::new(config).unwrap();
2330 let text = "attention is all you need".to_string();
2331 let rt_ref = &rt;
2332 let (doc_emb, query_emb) = tokio::runtime::Runtime::new().unwrap().block_on(async {
2333 let d = rt_ref
2334 .embed_document_with_model(&model.to_string(), &text)
2335 .await
2336 .unwrap();
2337 let q = rt_ref
2338 .embed_query_with_model(&model.to_string(), &text)
2339 .await
2340 .unwrap();
2341 (d, q)
2342 });
2343 assert_ne!(
2344 doc_emb, query_emb,
2345 "multilingual-e5-small uses asymmetric prefixes: document ('passage: ') \
2346 and query ('query: ') embeds of the same text must differ"
2347 );
2348 }
2349
2350 use crate::embedder_registry::EmbedderProvider;
2353 use lattice_embed::EmbeddingService;
2354
2355 struct StubEmbedderProvider;
2360
2361 #[async_trait::async_trait]
2362 impl EmbedderProvider for StubEmbedderProvider {
2363 fn name(&self) -> &str {
2364 "stub-model-m07"
2365 }
2366
2367 fn dimensions(&self) -> usize {
2368 4
2369 }
2370
2371 async fn build(&self) -> crate::error::RuntimeResult<std::sync::Arc<dyn EmbeddingService>> {
2372 struct StubSvc;
2373 #[async_trait::async_trait]
2374 impl EmbeddingService for StubSvc {
2375 async fn embed(
2376 &self,
2377 _texts: &[String],
2378 _model: lattice_embed::EmbeddingModel,
2379 ) -> std::result::Result<Vec<Vec<f32>>, lattice_embed::EmbedError> {
2380 Ok(vec![])
2381 }
2382
2383 fn supports_model(&self, _model: lattice_embed::EmbeddingModel) -> bool {
2384 true
2385 }
2386
2387 fn name(&self) -> &'static str {
2388 "stub-svc-m07"
2389 }
2390 }
2391 Ok(std::sync::Arc::new(StubSvc))
2392 }
2393 }
2394
2395 #[tokio::test]
2403 async fn backfill_reader_error_is_propagated_not_swallowed() {
2404 let rt = KhiveRuntime::memory().unwrap();
2405 rt.register_embedder(StubEmbedderProvider);
2406 let tok = NamespaceToken::local();
2407
2408 super::arm_backfill_reader_fail();
2411
2412 let result = rt.backfill_missing_embeddings(&tok).await;
2413 assert!(
2414 result.is_err(),
2415 "backfill_missing_embeddings must propagate the reader error (got Ok instead)"
2416 );
2417 let err_msg = result.unwrap_err().to_string();
2418 assert!(
2419 err_msg.contains("injected failure"),
2420 "error must originate from the injected reader failure, got: {err_msg}"
2421 );
2422 }
2423}