1use std::collections::{hash_map::Entry, HashMap, HashSet};
4
5use uuid::Uuid;
6
7use khive_score::DeterministicScore;
8use khive_storage::types::{
9 PageRequest, TextFilter, TextQueryMode, TextSearchHit, TextSearchRequest, VectorSearchHit,
10};
11use khive_storage::EntityFilter;
12use khive_types::SubstrateKind;
13
14use crate::error::{RuntimeError, RuntimeResult};
15use crate::retrieval::{SearchHit, SearchSource};
16use crate::runtime::{KhiveRuntime, NamespaceToken};
17
18pub use khive_fusion::FusionStrategy;
19
20const CANDIDATE_MULTIPLIER: u32 = 4;
21
22pub fn fuse_with_strategy(
25 text_hits: Vec<TextSearchHit>,
26 vector_hits: Vec<VectorSearchHit>,
27 strategy: &FusionStrategy,
28 limit: usize,
29) -> RuntimeResult<Vec<SearchHit>> {
30 match strategy {
31 FusionStrategy::VectorOnly => fuse_sources(Vec::new(), vector_hits, strategy, limit),
32 FusionStrategy::KeywordOnly => fuse_sources(text_hits, Vec::new(), strategy, limit),
33 FusionStrategy::Rrf { .. } | FusionStrategy::Weighted { .. } | FusionStrategy::Union => {
34 fuse_sources(text_hits, vector_hits, strategy, limit)
35 }
36 FusionStrategy::Custom { ref name, .. } => {
37 Err(khive_fusion::FuseError::CustomRequiresRuntime(name.clone()).into())
38 }
39 }
40}
41
42pub(crate) fn rrf_fuse_k(
44 text_hits: Vec<TextSearchHit>,
45 vector_hits: Vec<VectorSearchHit>,
46 k: usize,
47 limit: usize,
48) -> RuntimeResult<Vec<SearchHit>> {
49 fuse_with_strategy(text_hits, vector_hits, &FusionStrategy::Rrf { k }, limit)
50}
51
52fn fuse_sources(
53 text_hits: Vec<TextSearchHit>,
54 vector_hits: Vec<VectorSearchHit>,
55 strategy: &FusionStrategy,
56 limit: usize,
57) -> RuntimeResult<Vec<SearchHit>> {
58 let mut metadata: HashMap<Uuid, SearchHit> =
59 HashMap::with_capacity(text_hits.len() + vector_hits.len());
60
61 let text_source: Vec<(Uuid, DeterministicScore)> = text_hits
62 .into_iter()
63 .map(|h| {
64 let hit = SearchHit {
65 entity_id: h.subject_id,
66 score: h.score,
67 source: SearchSource::Text,
68 title: h.title,
69 snippet: h.snippet,
70 };
71 let id = hit.entity_id;
72 let score = hit.score;
73 merge_metadata(&mut metadata, hit);
74 (id, score)
75 })
76 .collect();
77
78 let vector_source: Vec<(Uuid, DeterministicScore)> = vector_hits
79 .into_iter()
80 .map(|h| {
81 let hit = SearchHit {
82 entity_id: h.subject_id,
83 score: h.score,
84 source: SearchSource::Vector,
85 title: None,
86 snippet: None,
87 };
88 let id = hit.entity_id;
89 let score = hit.score;
90 merge_metadata(&mut metadata, hit);
91 (id, score)
92 })
93 .collect();
94
95 let sources: Vec<Vec<(Uuid, DeterministicScore)>> = vec![vector_source, text_source];
98
99 Ok(khive_fusion::fuse(sources, strategy, limit)?
100 .into_iter()
101 .filter_map(|(id, score)| {
102 let mut hit = metadata.remove(&id)?;
103 hit.score = score;
104 Some(hit)
105 })
106 .collect())
107}
108
109fn merge_metadata(metadata: &mut HashMap<Uuid, SearchHit>, hit: SearchHit) {
110 match metadata.entry(hit.entity_id) {
111 Entry::Occupied(mut entry) => {
112 let existing = entry.get_mut();
113 existing.source = merge_sources(existing.source, hit.source);
114 if existing.title.is_none() {
115 existing.title = hit.title;
116 }
117 if existing.snippet.is_none() {
118 existing.snippet = hit.snippet;
119 }
120 }
121 Entry::Vacant(entry) => {
122 entry.insert(hit);
123 }
124 }
125}
126
127fn merge_sources(left: SearchSource, right: SearchSource) -> SearchSource {
128 match (left, right) {
129 (SearchSource::Both, _) | (_, SearchSource::Both) => SearchSource::Both,
130 (SearchSource::Text, SearchSource::Vector) | (SearchSource::Vector, SearchSource::Text) => {
131 SearchSource::Both
132 }
133 (SearchSource::Text, SearchSource::Text) => SearchSource::Text,
134 (SearchSource::Vector, SearchSource::Vector) => SearchSource::Vector,
135 }
136}
137
138impl KhiveRuntime {
139 async fn retain_alive_search_hits(
140 &self,
141 token: &NamespaceToken,
142 mut fused: Vec<SearchHit>,
143 limit: usize,
144 ) -> RuntimeResult<Vec<SearchHit>> {
145 if !fused.is_empty() {
148 let candidate_ids: Vec<Uuid> = fused.iter().map(|h| h.entity_id).collect();
149 let alive_page = self
150 .entities(token)?
151 .query_entities(
152 token.namespace().as_str(),
153 EntityFilter {
154 ids: candidate_ids,
155 ..EntityFilter::default()
156 },
157 PageRequest {
158 offset: 0,
159 limit: u32::try_from(fused.len()).unwrap_or(u32::MAX),
160 },
161 )
162 .await?;
163 let alive: HashSet<Uuid> = alive_page.items.into_iter().map(|e| e.id).collect();
164 fused.retain(|h| alive.contains(&h.entity_id));
165 }
166
167 fused.truncate(limit);
168 Ok(fused)
169 }
170
171 pub async fn hybrid_search_with_strategy(
173 &self,
174 token: &NamespaceToken,
175 query_text: &str,
176 query_vector: Option<Vec<f32>>,
177 strategy: FusionStrategy,
178 limit: u32,
179 ) -> RuntimeResult<Vec<SearchHit>> {
180 let candidates = limit.saturating_mul(CANDIDATE_MULTIPLIER).max(limit);
181
182 let ns = token.namespace().as_str().to_owned();
183 let text_search_result = self
188 .text(token)?
189 .search(TextSearchRequest {
190 query: query_text.to_string(),
191 mode: TextQueryMode::Plain,
192 filter: Some(TextFilter {
193 namespaces: vec![ns.clone()],
194 ..TextFilter::default()
195 }),
196 top_k: candidates,
197 snippet_chars: 200,
198 })
199 .await;
200 let text_hits = crate::error::fts_text_leg_or_err(
201 text_search_result.map_err(RuntimeError::from),
202 "hybrid_search_with_strategy",
203 query_text,
204 )?;
205
206 let vector_hits = if query_vector.is_some() || self.config().embedding_model.is_some() {
207 self.vector_search(
208 token,
209 query_vector,
210 Some(query_text),
211 candidates,
212 Some(SubstrateKind::Entity),
213 )
214 .await?
215 } else {
216 Vec::new()
217 };
218
219 let fusion_limit = text_hits.len().saturating_add(vector_hits.len());
224 let fused = fuse_with_strategy(text_hits, vector_hits, &strategy, fusion_limit)?;
225 self.retain_alive_search_hits(token, fused, limit as usize)
226 .await
227 }
228}
229
230#[cfg(test)]
231mod tests {
232 use super::*;
233 use chrono::Utc;
234 use khive_storage::types::{TextDocument, TextSearchHit, VectorSearchHit, VectorSearchRequest};
235 use khive_storage::Entity;
236 use lattice_embed::EmbeddingModel;
237
238 use crate::RuntimeConfig;
239
240 fn text_hit(id: Uuid, score: f64, title: &str) -> TextSearchHit {
241 TextSearchHit {
242 subject_id: id,
243 score: DeterministicScore::from_f64(score),
244 rank: 1,
245 title: Some(title.to_string()),
246 snippet: Some("...".to_string()),
247 }
248 }
249
250 fn vector_hit(id: Uuid, score: f64) -> VectorSearchHit {
251 VectorSearchHit {
252 subject_id: id,
253 score: DeterministicScore::from_f64(score),
254 rank: 1,
255 }
256 }
257
258 fn cosine_fixture_vector(dimensions: usize, x: f32, y: f32) -> Vec<f32> {
259 let mut vector = vec![0.0; dimensions];
260 vector[0] = x;
261 vector[1] = y;
262 vector
263 }
264
265 async fn stale_full_prefix_fixture() -> (
266 KhiveRuntime,
267 NamespaceToken,
268 &'static str,
269 Vec<f32>,
270 Vec<TextSearchHit>,
271 Vec<VectorSearchHit>,
272 HashSet<Uuid>,
273 ) {
274 let model = EmbeddingModel::AllMiniLmL6V2;
275 let dimensions = model.dimensions();
276 let rt = KhiveRuntime::new(RuntimeConfig {
277 db_path: None,
278 embedding_model: Some(model),
279 additional_embedding_models: vec![],
280 ..RuntimeConfig::default()
281 })
282 .unwrap();
283 let tok = NamespaceToken::local();
284 let query_text = "fusionrefillterm";
285 let query_vector = cosine_fixture_vector(dimensions, 1.0, 0.0);
286
287 let common_stale_a = Uuid::from_u128(1);
288 let common_stale_b = Uuid::from_u128(2);
289 let text_only_stale = Uuid::from_u128(3);
290 let vector_only_stale = Uuid::from_u128(4);
291
292 let live_text = Entity::new("local", "concept", "live text candidate");
293 let live_vector = Entity::new("local", "concept", "live vector candidate");
294 rt.entities(&tok)
295 .unwrap()
296 .upsert_entities(vec![live_text.clone(), live_vector.clone()])
297 .await
298 .unwrap();
299
300 let document = |subject_id, repetitions: usize| TextDocument {
301 subject_id,
302 kind: SubstrateKind::Entity,
303 namespace: "local".to_string(),
304 title: None,
305 body: std::iter::repeat_n(query_text, repetitions)
306 .collect::<Vec<_>>()
307 .join(" "),
308 tags: vec![],
309 metadata: None,
310 updated_at: Utc::now(),
311 };
312 rt.text(&tok)
313 .unwrap()
314 .upsert_documents(vec![
315 document(common_stale_a, 12),
316 document(common_stale_b, 8),
317 document(text_only_stale, 4),
318 document(live_text.id, 1),
319 ])
320 .await
321 .unwrap();
322
323 let vectors = rt.vectors(&tok).unwrap();
324 for (id, vector) in [
325 (common_stale_a, cosine_fixture_vector(dimensions, 1.0, 0.0)),
326 (common_stale_b, cosine_fixture_vector(dimensions, 0.8, 0.6)),
327 (
328 vector_only_stale,
329 cosine_fixture_vector(dimensions, 0.5, 0.866_025_4),
330 ),
331 (live_vector.id, cosine_fixture_vector(dimensions, -1.0, 0.0)),
332 ] {
333 vectors
334 .insert(
335 id,
336 SubstrateKind::Entity,
337 "local",
338 "entity.body",
339 vec![vector],
340 )
341 .await
342 .unwrap();
343 }
344
345 let text_hits = rt
346 .text(&tok)
347 .unwrap()
348 .search(TextSearchRequest {
349 query: query_text.to_string(),
350 mode: TextQueryMode::Plain,
351 filter: Some(TextFilter {
352 namespaces: vec!["local".to_string()],
353 ..TextFilter::default()
354 }),
355 top_k: CANDIDATE_MULTIPLIER,
356 snippet_chars: 0,
357 })
358 .await
359 .unwrap();
360 let vector_hits = vectors
361 .search(VectorSearchRequest {
362 query_vectors: vec![query_vector.clone()],
363 top_k: CANDIDATE_MULTIPLIER,
364 namespace: Some("local".to_string()),
365 kind: Some(SubstrateKind::Entity),
366 embedding_model: None,
367 filter: None,
368 backend_hints: None,
369 })
370 .await
371 .unwrap();
372
373 assert_eq!(text_hits.len(), CANDIDATE_MULTIPLIER as usize);
374 assert_eq!(vector_hits.len(), CANDIDATE_MULTIPLIER as usize);
375 let live = HashSet::from([live_text.id, live_vector.id]);
376 (
377 rt,
378 tok,
379 query_text,
380 query_vector,
381 text_hits,
382 vector_hits,
383 live,
384 )
385 }
386
387 #[test]
389 fn rrf_custom_k_differs_from_k60() {
390 let a = Uuid::new_v4();
391 let b = Uuid::new_v4();
392 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
396 let hits_k1 =
397 fuse_with_strategy(text.clone(), vec![], &FusionStrategy::Rrf { k: 1 }, 10).unwrap();
398 let hits_k60 =
399 fuse_with_strategy(text, vec![], &FusionStrategy::Rrf { k: 60 }, 10).unwrap();
400 assert_eq!(hits_k1[0].entity_id, a);
402 assert_eq!(hits_k60[0].entity_id, a);
403 assert!(hits_k1[0].score > hits_k60[0].score);
405 }
406
407 #[test]
409 fn weighted_ordering_depends_on_weights() {
410 let a = Uuid::new_v4();
411 let b = Uuid::new_v4();
412 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
414 let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
415
416 let heavy_vector = fuse_with_strategy(
417 text.clone(),
418 vec_hits.clone(),
419 &FusionStrategy::Weighted {
420 weights: vec![0.7, 0.3],
421 },
422 10,
423 )
424 .unwrap();
425 let heavy_keyword = fuse_with_strategy(
426 text,
427 vec_hits,
428 &FusionStrategy::Weighted {
429 weights: vec![0.3, 0.7],
430 },
431 10,
432 )
433 .unwrap();
434
435 assert_eq!(heavy_vector[0].entity_id, b);
436 assert_eq!(heavy_keyword[0].entity_id, a);
437 }
438
439 #[test]
441 fn weighted_scale_invariant() {
442 let a = Uuid::new_v4();
443 let b = Uuid::new_v4();
444 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
445 let vec_hits = vec![vector_hit(b, 0.9), vector_hit(a, 0.1)];
446
447 let w1 = fuse_with_strategy(
448 text.clone(),
449 vec_hits.clone(),
450 &FusionStrategy::Weighted {
451 weights: vec![0.7, 0.3],
452 },
453 10,
454 )
455 .unwrap();
456 let w2 = fuse_with_strategy(
457 text,
458 vec_hits,
459 &FusionStrategy::Weighted {
460 weights: vec![7.0, 3.0],
461 },
462 10,
463 )
464 .unwrap();
465
466 assert_eq!(w1[0].entity_id, w2[0].entity_id);
467 assert_eq!(w1[1].entity_id, w2[1].entity_id);
468 let diff = (w1[0].score.to_f64() - w2[0].score.to_f64()).abs();
469 assert!(diff < 1e-9, "scores differ by {diff}");
470 }
471
472 #[test]
474 fn weighted_zero_weights_equal_fallback() {
475 let a = Uuid::new_v4();
476 let b = Uuid::new_v4();
477 let text = vec![text_hit(a, 0.9, "a"), text_hit(b, 0.1, "b")];
479 let vec_hits = vec![vector_hit(a, 0.9), vector_hit(b, 0.1)];
480
481 let hits = fuse_with_strategy(
482 text,
483 vec_hits,
484 &FusionStrategy::Weighted {
485 weights: vec![0.0, 0.0],
486 },
487 10,
488 )
489 .unwrap();
490 assert_eq!(hits[0].entity_id, a);
491 }
492
493 #[test]
495 fn weighted_negative_weight_clamped() {
496 let a = Uuid::new_v4();
497 let text = vec![text_hit(a, 0.9, "a")];
498 let hits = fuse_with_strategy(
500 text,
501 vec![],
502 &FusionStrategy::Weighted {
503 weights: vec![-0.5, 1.0],
504 },
505 10,
506 )
507 .unwrap();
508 assert_eq!(hits.len(), 1);
509 assert_eq!(hits[0].entity_id, a);
510 }
511
512 #[test]
513 fn weighted_empty_arm_keeps_canonical_position() {
514 let text_only = Uuid::new_v4();
515 let hits = fuse_with_strategy(
516 vec![text_hit(text_only, 0.9, "text")],
517 vec![],
518 &FusionStrategy::Weighted {
519 weights: vec![1.0, 0.0],
521 },
522 10,
523 )
524 .unwrap();
525 assert!(
526 hits.is_empty(),
527 "dropping the empty vector arm would incorrectly rebind text to its weight"
528 );
529 }
530
531 #[test]
533 fn union_max_score_per_entity() {
534 let a = Uuid::new_v4();
535 let text = vec![text_hit(a, 0.3, "a")];
536 let vec_hits = vec![vector_hit(a, 0.9)];
537
538 let hits = fuse_with_strategy(text, vec_hits, &FusionStrategy::Union, 10).unwrap();
539 assert_eq!(hits.len(), 1);
540 assert!((hits[0].score.to_f64() - 0.9).abs() < 1e-6);
541 assert_eq!(hits[0].source, SearchSource::Both);
542 }
543
544 #[test]
546 fn vector_only_drops_text() {
547 let a = Uuid::new_v4();
548 let b = Uuid::new_v4();
549 let text = vec![text_hit(b, 0.9, "b")];
550 let vec_hits = vec![vector_hit(a, 0.8)];
551
552 let hits = fuse_with_strategy(text, vec_hits, &FusionStrategy::VectorOnly, 10).unwrap();
553 assert_eq!(hits.len(), 1);
554 assert_eq!(hits[0].entity_id, a);
555 assert_eq!(hits[0].source, SearchSource::Vector);
556 assert!(hits[0].title.is_none());
557 }
558
559 #[test]
560 fn keyword_only_drops_vector() {
561 let text_id = Uuid::new_v4();
562 let vector_id = Uuid::new_v4();
563 let hits = fuse_with_strategy(
564 vec![text_hit(text_id, 0.8, "text")],
565 vec![vector_hit(vector_id, 0.9)],
566 &FusionStrategy::KeywordOnly,
567 10,
568 )
569 .unwrap();
570 assert_eq!(hits.len(), 1);
571 assert_eq!(hits[0].entity_id, text_id);
572 assert_eq!(hits[0].source, SearchSource::Text);
573 }
574
575 #[test]
577 fn default_strategy_is_rrf_k60() {
578 assert_eq!(FusionStrategy::default(), FusionStrategy::Rrf { k: 60 });
579 }
580
581 #[tokio::test]
582 async fn hybrid_union_alive_filter_refills_below_complete_four_x_prefix() {
583 let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
584 stale_full_prefix_fixture().await;
585 let truncated = fuse_with_strategy(
586 text_hits,
587 vector_hits,
588 &FusionStrategy::Union,
589 CANDIDATE_MULTIPLIER as usize,
590 )
591 .unwrap();
592 assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
593
594 let hits = rt
595 .hybrid_search_with_strategy(
596 &tok,
597 query_text,
598 Some(query_vector),
599 FusionStrategy::Union,
600 1,
601 )
602 .await
603 .unwrap();
604
605 assert_eq!(hits.len(), 1);
606 assert!(live.contains(&hits[0].entity_id));
607 }
608
609 #[tokio::test]
610 async fn hybrid_rrf_alive_filter_refills_below_complete_four_x_prefix() {
611 let (rt, tok, query_text, query_vector, text_hits, vector_hits, live) =
612 stale_full_prefix_fixture().await;
613 let strategy = FusionStrategy::Rrf { k: 60 };
614 let truncated = fuse_with_strategy(
615 text_hits,
616 vector_hits,
617 &strategy,
618 CANDIDATE_MULTIPLIER as usize,
619 )
620 .unwrap();
621 assert!(truncated.iter().all(|hit| !live.contains(&hit.entity_id)));
622
623 let hits = rt
624 .hybrid_search_with_strategy(&tok, query_text, Some(query_vector), strategy, 1)
625 .await
626 .unwrap();
627
628 assert_eq!(hits.len(), 1);
629 assert!(live.contains(&hits[0].entity_id));
630 }
631
632 #[tokio::test]
633 async fn hybrid_default_rrf_alive_filter_refills_below_complete_four_x_prefix() {
634 let (rt, tok, query_text, query_vector, _text_hits, _vector_hits, live) =
635 stale_full_prefix_fixture().await;
636
637 let hits = rt
638 .hybrid_search(
639 &tok,
640 query_text,
641 Some(query_vector),
642 1,
643 None,
644 None,
645 &[],
646 None,
647 )
648 .await
649 .unwrap();
650
651 assert_eq!(hits.len(), 1);
652 assert!(live.contains(&hits[0].entity_id));
653 }
654
655 #[test]
657 fn serde_roundtrip() {
658 let cases = vec![
659 FusionStrategy::Rrf { k: 60 },
660 FusionStrategy::Rrf { k: 20 },
661 FusionStrategy::Weighted {
662 weights: vec![0.7, 0.3],
663 },
664 FusionStrategy::Union,
665 FusionStrategy::VectorOnly,
666 FusionStrategy::KeywordOnly,
667 ];
668 for strategy in cases {
669 let json = serde_json::to_string(&strategy).expect("serialize");
670 let back: FusionStrategy = serde_json::from_str(&json).expect("deserialize");
671 assert_eq!(strategy, back, "roundtrip failed for {json}");
672 }
673 }
674
675 #[tokio::test]
680 async fn hybrid_search_with_strategy_dollar_sign_query_does_not_error() {
681 let rt = KhiveRuntime::memory().unwrap();
682 let tok = NamespaceToken::local();
683 rt.create_entity(
684 &tok,
685 "concept",
686 None,
687 "DSL docs",
688 Some("use $prev.id to chain calls"),
689 None,
690 vec![],
691 )
692 .await
693 .unwrap();
694
695 let result = rt
696 .hybrid_search_with_strategy(&tok, "$prev.id", None, FusionStrategy::default(), 10)
697 .await;
698
699 assert!(
700 result.is_ok(),
701 "#388 hybrid_search_with_strategy must not hard-fail on a '$'-bearing query, got: {:?}",
702 result.err()
703 );
704 }
705
706 #[tokio::test]
712 async fn hybrid_search_with_strategy_residual_fts5_char_now_sanitized() {
713 let rt = KhiveRuntime::memory().unwrap();
714 let tok = NamespaceToken::local();
715 rt.create_entity(
716 &tok,
717 "concept",
718 None,
719 "DSL docs",
720 Some("use foo@bar to chain calls"),
721 None,
722 vec![],
723 )
724 .await
725 .unwrap();
726
727 let result = rt
728 .hybrid_search_with_strategy(&tok, "foo@bar", None, FusionStrategy::default(), 10)
729 .await;
730
731 let hits = result.unwrap_or_else(|e| {
732 panic!(
733 "#916 hybrid_search_with_strategy must not fail on an '@'-bearing query, got: {e:?}"
734 )
735 });
736 assert!(
737 !hits.is_empty(),
738 "#916 '@'-bearing query must still find the seeded 'foo@bar' content via the \
739 quoted-phrase alternative"
740 );
741 }
742}