use super::*;
#[derive(Debug, Default, Clone)]
pub(super) struct QueryEmbeddingCache {
pub(super) role_specific: RoleSpecificEmbedding,
pub(super) generic: Option<Vec<f32>>,
}
#[derive(Debug, Clone, Default, PartialEq)]
pub(super) enum RoleSpecificEmbedding {
#[default]
NotAttempted,
Failed,
Vector(Vec<f32>),
}
impl RoleSpecificEmbedding {
pub(super) fn as_deref(&self) -> Option<&[f32]> {
match self {
Self::Vector(v) => Some(v.as_slice()),
Self::NotAttempted | Self::Failed => None,
}
}
pub(super) fn is_not_attempted(&self) -> bool {
matches!(self, Self::NotAttempted)
}
}
impl QueryEmbeddingCache {
pub(super) fn any(&self) -> Option<&[f32]> {
self.role_specific.as_deref().or(self.generic.as_deref())
}
}
pub(super) async fn embed_cosine_scores(
runtime: &KhiveRuntime,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
candidate_texts: &[String],
) -> Result<Option<Vec<f32>>, RuntimeError> {
if runtime.default_embedder_name().is_empty() || candidate_texts.is_empty() {
return Ok(None);
}
let query_was_cached = query_embedding.any().is_some();
let texts = if query_was_cached {
candidate_texts.to_vec()
} else {
let mut texts = Vec::with_capacity(candidate_texts.len() + 1);
texts.push(query.to_string());
texts.extend_from_slice(candidate_texts);
texts
};
let embeddings = match khive_storage::await_request_read_phase(
"knowledge.embedding_rerank",
runtime.embed_batch(&texts),
)
.await
{
Ok(Ok(embeddings)) => embeddings,
Ok(Err(_)) => return Ok(None),
Err(e) if is_timeout(&e) => return Ok(None),
Err(e) => return Err(e.into()),
};
if embeddings.len() != texts.len() {
return Ok(None);
}
let candidate_embeddings = if query_was_cached {
embeddings.as_slice()
} else {
query_embedding.generic = Some(embeddings[0].clone());
&embeddings[1..]
};
let query_emb = query_embedding
.any()
.expect("query embedding was cached or populated from non-empty batch");
Ok(Some(
candidate_embeddings
.iter()
.map(|emb| cosine_similarity(query_emb, emb, false))
.collect(),
))
}
pub(super) async fn rerank_with_embeddings(
runtime: &KhiveRuntime,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
hits: &mut [ScoredHit],
alpha: f32,
) -> Result<bool, RuntimeError> {
if hits.is_empty() {
return Ok(false);
}
let texts: Vec<String> = hits
.iter()
.map(|h| format!("{} {}", h.name, h.content.as_deref().unwrap_or("")))
.collect();
if let Some(cosines) = embed_cosine_scores(runtime, query, query_embedding, &texts).await? {
let max_tfidf = hits
.iter()
.map(|h| h.score)
.fold(0.0f32, f32::max)
.max(1e-6);
for (hit, cos) in hits.iter_mut().zip(cosines.iter()) {
let norm_tfidf = hit.score / max_tfidf;
hit.score = alpha * norm_tfidf + (1.0 - alpha) * cos.max(0.0);
hit.provenance.embedding_rerank = true;
}
hits.sort_by(compare_scored_hits);
return Ok(true);
}
Ok(false)
}
pub(super) async fn rerank_search_with_stored_vectors(
runtime: &KhiveRuntime,
token: &NamespaceToken,
namespace: &str,
query: &str,
query_embedding: &mut QueryEmbeddingCache,
hits: &mut [ScoredHit],
alpha: f32,
) -> Result<Option<Value>, RuntimeError> {
if hits.is_empty() {
return Ok(None);
}
if query_embedding.role_specific.is_not_attempted() {
query_embedding.role_specific = match khive_storage::await_request_read_phase(
"knowledge.embedding_rerank",
runtime.embed_query(query),
)
.await
{
Ok(Ok(vector)) => RoleSpecificEmbedding::Vector(vector),
Ok(Err(_)) => RoleSpecificEmbedding::Failed,
Err(error) if is_timeout(&error) => RoleSpecificEmbedding::Failed,
Err(error) => return Err(error.into()),
};
}
let Some(query_vector) = query_embedding.role_specific.as_deref() else {
return Ok(None);
};
let store = match runtime.vectors_for_model(token, runtime.default_embedder_name()) {
Ok(store) => Some(store),
Err(RuntimeError::Storage(khive_storage::StorageError::Unsupported { .. })) => None,
Err(error) => return Err(error),
};
rerank_search_from_store(
runtime,
store.as_deref(),
namespace,
query_vector,
hits,
alpha,
)
.await
}
pub(super) async fn rerank_search_from_store(
runtime: &KhiveRuntime,
store: Option<&dyn khive_storage::VectorStore>,
namespace: &str,
query_vector: &[f32],
hits: &mut [ScoredHit],
alpha: f32,
) -> Result<Option<Value>, RuntimeError> {
let candidate_ids: Vec<Uuid> = hits
.iter()
.filter_map(|hit| Uuid::parse_str(&hit.id).ok())
.collect();
let mut stored_vectors = HashMap::new();
let mut stored_vector_lookup = "unsupported";
if let Some(store) = store {
if store.capabilities().supports_vector_read {
stored_vector_lookup = "supported";
if !candidate_ids.is_empty() {
stored_vectors = match khive_storage::await_request_read_phase(
"knowledge.embedding_rerank.vector_read",
store.get_vectors(&candidate_ids, namespace, "knowledge.atom"),
)
.await
{
Ok(Ok(vectors)) => vectors,
Ok(Err(khive_storage::StorageError::Unsupported { .. })) => {
stored_vector_lookup = "unsupported";
HashMap::new()
}
Ok(Err(error)) => return Err(error.into()),
Err(error) if is_timeout(&error) => return Ok(None),
Err(error) => return Err(error.into()),
};
}
}
}
let mut fallback_indices = Vec::new();
let mut fallback_texts = Vec::new();
let mut candidate_vectors = vec![None; hits.len()];
for (index, hit) in hits.iter().enumerate() {
let stored = Uuid::parse_str(&hit.id)
.ok()
.and_then(|id| stored_vectors.get(&id));
if let Some(vector) = stored {
candidate_vectors[index] = Some(vector.clone());
continue;
}
fallback_indices.push(index);
fallback_texts.push(hit.atom_embed_text.clone().unwrap_or_else(|| {
atom_embed_text_fields(
&hit.name,
hit.content.as_deref().unwrap_or(""),
hit.tags.as_deref().unwrap_or("[]"),
)
}));
}
if !fallback_texts.is_empty() {
let embedded = match khive_storage::await_request_read_phase(
"knowledge.embedding_rerank.fallback",
runtime.embed_document_batch_outcomes(&fallback_texts),
)
.await
{
Ok(Ok(outcomes)) => outcomes
.into_iter()
.map(|outcome| outcome.vector)
.collect::<Vec<_>>(),
Ok(Err(_)) => return Ok(None),
Err(error) if is_timeout(&error) => return Ok(None),
Err(error) => return Err(error.into()),
};
if embedded.len() != fallback_indices.len() {
return Ok(None);
}
for (index, vector) in fallback_indices.iter().copied().zip(embedded) {
candidate_vectors[index] = Some(vector);
}
}
let from_stored = hits.len() - fallback_indices.len();
let max_score = hits
.iter()
.map(|hit| hit.score)
.fold(0.0f32, f32::max)
.max(1e-6);
for (hit, vector) in hits.iter_mut().zip(candidate_vectors) {
let vector = vector.expect("every rerank candidate has a stored or fallback vector");
let cosine = cosine_similarity(query_vector, &vector, false);
hit.score = alpha * (hit.score / max_score) + (1.0 - alpha) * cosine.max(0.0);
hit.provenance.embedding_rerank = true;
}
hits.sort_by(compare_scored_hits);
Ok(Some(json!({
"stored_vector_lookup": stored_vector_lookup,
"candidates": hits.len(),
"from_stored": from_stored,
"embedded_fallback": fallback_indices.len(),
})))
}