use super::{
explicitly_requested_status, json, status_multiplier, vamana, DeterministicScore, HashMap,
KhiveRuntime, NamespaceToken, ScoredHit, Uuid, Value,
};
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(super) struct ScoreProvenance {
pub(super) lexical: bool,
pub(super) ann: bool,
pub(super) embedding_rerank: bool,
}
impl ScoreProvenance {
pub(super) const fn lexical() -> Self {
Self {
lexical: true,
ann: false,
embedding_rerank: false,
}
}
pub(super) const fn ann() -> Self {
Self {
lexical: false,
ann: true,
embedding_rerank: false,
}
}
pub(super) fn merge_sources(&mut self, other: Self) {
self.lexical |= other.lexical;
self.ann |= other.ann;
self.embedding_rerank |= other.embedding_rerank;
}
pub(super) fn to_json(self) -> Value {
let mut sources = Vec::with_capacity(2);
if self.lexical {
sources.push("lexical");
}
if self.ann {
sources.push("ann");
}
json!({
"sources": sources,
"embedding_rerank": self.embedding_rerank,
"normalization": "s_over_s_plus_1",
"calibrated": false,
})
}
}
pub(super) fn candidate_fallback(hits: &[ScoredHit]) -> &'static str {
if hits.iter().any(|hit| hit.provenance.ann) && !hits.iter().any(|hit| hit.provenance.lexical) {
"ann"
} else {
"none"
}
}
pub(super) enum AnnAvailability {
Ready,
WarmingTimedOut { corpus_non_empty: bool },
Absent,
}
pub(super) struct AnnSearchState {
pub(super) hits: Vec<(Uuid, f32)>,
pub(super) availability: AnnAvailability,
pub(super) source_exhausted: bool,
}
struct FreshTailSearchState {
hits: Vec<(Uuid, f32)>,
source_exhausted: bool,
}
async fn merge_fresh_tail_for_search(
runtime: &KhiveRuntime,
ann: &vamana::SharedAnn,
key: &vamana::AnnKey,
query_embedding: &[f32],
k: usize,
loaded: Option<(Vec<(Uuid, f32)>, u64)>,
) -> FreshTailSearchState {
let (candidates, watermark, source_exhausted) = match loaded {
Some((candidates, watermark)) => {
let source_exhausted = candidates.len() < k;
(candidates, Some(watermark), source_exhausted)
}
None => (Vec::new(), None, true),
};
match vamana::fresh_tail_leg(runtime, ann, key, query_embedding, k, watermark).await {
vamana::FreshTailOutcome::Ops(ops) => FreshTailSearchState {
hits: vamana::merge_fresh_tail_off_thread(candidates, query_embedding, ops).await,
source_exhausted,
},
vamana::FreshTailOutcome::Replace {
candidates,
source_exhausted,
} => FreshTailSearchState {
hits: candidates,
source_exhausted,
},
vamana::FreshTailOutcome::Skipped => FreshTailSearchState {
hits: candidates,
source_exhausted,
},
}
}
pub(super) async fn search_ann_with_warm_wait(
runtime: &KhiveRuntime,
token: &NamespaceToken,
ann: &vamana::SharedAnn,
key: &vamana::AnnKey,
query_embedding: &[f32],
k: usize,
) -> AnnSearchState {
if let Some(loaded) = vamana::search_loaded_with_seq(ann, key, query_embedding, k).await {
let tail =
merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, Some(loaded)).await;
return AnnSearchState {
hits: tail.hits,
availability: AnnAvailability::Ready,
source_exhausted: tail.source_exhausted,
};
}
if !vamana::is_warming_not_loaded(ann, key) {
let tail = merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, None).await;
return AnnSearchState {
hits: tail.hits,
availability: AnnAvailability::Absent,
source_exhausted: tail.source_exhausted,
};
}
if vamana::wait_ready(
ann,
key,
vamana::warm_wait_timeout_ms(),
vamana::ANN_WARM_WAIT_POLL_MS,
)
.await
{
let loaded = vamana::search_loaded_with_seq(ann, key, query_embedding, k).await;
let availability = if loaded.is_some() {
AnnAvailability::Ready
} else {
AnnAvailability::Absent
};
let tail = merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, loaded).await;
return AnnSearchState {
hits: tail.hits,
availability,
source_exhausted: tail.source_exhausted,
};
}
let corpus_non_empty =
vamana::compute_fingerprint(runtime, token, runtime.default_embedder_name())
.await
.map(|fingerprint| fingerprint.vector_count > 0)
.unwrap_or(false);
let tail = merge_fresh_tail_for_search(runtime, ann, key, query_embedding, k, None).await;
AnnSearchState {
hits: tail.hits,
availability: AnnAvailability::WarmingTimedOut { corpus_non_empty },
source_exhausted: tail.source_exhausted,
}
}
pub(super) use khive_fusion::DEFAULT_RRF_K as RRF_K;
pub(super) fn normalize_rrf_score(raw: f32, source_count: usize, k: usize) -> f32 {
if source_count == 0 {
return 0.0;
}
let theoretical_max = source_count as f32 / (k as f32 + 1.0);
(raw / theoretical_max).clamp(0.0, 1.0)
}
pub(super) fn fuse_ann_hits(fts_hits: &mut Vec<ScoredHit>, ann_hits: &[ScoredHit], min_score: f32) {
let drained: Vec<ScoredHit> = std::mem::take(fts_hits);
let fts_source: Vec<(String, DeterministicScore)> = drained
.iter()
.map(|hit| (hit.id.clone(), DeterministicScore::from_f32(hit.score)))
.collect();
let mut by_id: HashMap<String, ScoredHit> = drained
.into_iter()
.map(|hit| (hit.id.clone(), hit))
.collect();
let ann_source: Vec<(String, DeterministicScore)> = ann_hits
.iter()
.map(|hit| (hit.id.clone(), DeterministicScore::from_f32(hit.score)))
.collect();
for hit in ann_hits {
by_id
.entry(hit.id.clone())
.and_modify(|existing| existing.provenance.merge_sources(hit.provenance))
.or_insert_with(|| hit.clone());
}
let source_count = usize::from(!fts_source.is_empty()) + usize::from(!ann_source.is_empty());
let fused = khive_fusion::reciprocal_rank_fusion(vec![fts_source, ann_source], RRF_K);
for (id, fused_score) in fused {
let raw_score = fused_score.to_f64() as f32;
let score = normalize_rrf_score(raw_score, source_count, RRF_K);
if score < min_score {
continue;
}
if let Some(mut hit) = by_id.remove(&id) {
hit.score = score;
fts_hits.push(hit);
}
}
}
pub(super) fn filter_by_excluded_statuses(hits: &mut Vec<ScoredHit>, exclude_statuses: &[&str]) {
if exclude_statuses.is_empty() {
return;
}
hits.retain(|hit| {
let status = hit.status.as_deref().unwrap_or("");
!exclude_statuses.contains(&status)
});
}
pub(super) fn filter_hits_by_status(
hits: &mut Vec<ScoredHit>,
statuses: &[String],
exclude_statuses: &[&str],
) {
if statuses.is_empty() {
filter_by_excluded_statuses(hits, exclude_statuses);
return;
}
hits.retain(|hit| {
hit.status
.as_deref()
.is_some_and(|status| statuses.iter().any(|allowed| allowed == status))
});
}
pub(super) fn deprecated_allowed_by_status_policy(
statuses: &[String],
exclude_statuses: &[&str],
) -> bool {
if statuses.is_empty() {
!exclude_statuses.contains(&"deprecated")
} else {
explicitly_requested_status(statuses, "deprecated")
}
}
pub(super) fn filter_hits_by_type(hits: &mut Vec<ScoredHit>, type_filter: Option<&str>) {
let filt = match type_filter {
Some(f) if !f.is_empty() => f,
_ => return,
};
let want_domain = filt == "domain";
hits.retain(|hit| {
if want_domain {
hit.is_domain
} else {
!hit.is_domain
}
});
}
pub(super) fn apply_status_multipliers(hits: &mut Vec<ScoredHit>, include_deprecated: bool) {
hits.retain_mut(|hit| {
let multiplier = status_multiplier(hit.status.as_deref());
hit.score = (hit.score / (hit.score + 1.0) * multiplier).clamp(0.0, 1.0);
include_deprecated || multiplier > 0.0
});
hits.sort_by(|a, b| {
b.score
.partial_cmp(&a.score)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.slug.cmp(&b.slug))
});
}
pub(super) fn enforce_min_score_floor(hits: &mut Vec<ScoredHit>, min_score: f32) {
hits.retain(|hit| hit.score >= min_score);
}