use std::collections::{HashMap, HashSet};
use std::sync::Arc;
use futures::future::BoxFuture;
use crate::error::RagError;
use crate::types::{
Embedder, Hit, KeywordQuery, PARENT_KEY, Reranker, RetrievalRequest, Retriever, StoredChunk, VectorQuery,
VectorStore,
};
const CANDIDATE_FACTOR: usize = 4;
const MIN_CANDIDATES: usize = 20;
const FILTERED_CANDIDATE_FACTOR: usize = 20;
const MAX_CANDIDATES: usize = 1_000;
#[derive(Clone, Debug)]
pub struct StoreRetriever {
store: Arc<dyn VectorStore>,
embedder: Arc<dyn Embedder>,
reranker: Option<Arc<dyn Reranker>>,
}
impl StoreRetriever {
pub fn new(store: Arc<dyn VectorStore>, embedder: Arc<dyn Embedder>) -> Self {
Self { store, embedder, reranker: None }
}
pub fn with_reranker(mut self, reranker: Option<Arc<dyn Reranker>>) -> Self {
self.reranker = reranker;
self
}
pub fn store(&self) -> &Arc<dyn VectorStore> {
&self.store
}
pub fn embedder(&self) -> &Arc<dyn Embedder> {
&self.embedder
}
}
impl Retriever for StoreRetriever {
fn retrieve<'a>(&'a self, request: &'a RetrievalRequest) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
Box::pin(async move {
let query = request.query.trim();
if query.is_empty() || request.top_k == 0 {
return Ok(Vec::new());
}
let factor = if request.filter.is_some() { FILTERED_CANDIDATE_FACTOR } else { CANDIDATE_FACTOR };
let candidates =
request.top_k.saturating_mul(factor).max(MIN_CANDIDATES).min(MAX_CANDIDATES.max(request.top_k));
let weights = request.weights;
if weights.keyword > 0.0 && !self.store.supports_keyword() {
return Err(RagError::Config(
"keyword (hybrid) weight requested, but this dataset's store has no keyword index".into(),
));
}
if request.rerank && self.reranker.is_none() {
return Err(RagError::Config(
"reranking requested, but this dataset has no reranker configured".into(),
));
}
let use_keyword = weights.keyword > 0.0;
let use_vector = weights.vector > 0.0 || !use_keyword;
let vector_hits = if use_vector {
let vector = self.embedder.embed_query(query).await?;
self.store
.search(VectorQuery {
datasets: &request.datasets,
vector: &vector,
top_k: candidates,
filter: request.filter.as_ref(),
})
.await?
} else {
Vec::new()
};
let keyword_hits = if use_keyword {
self.store
.keyword_search(KeywordQuery {
datasets: &request.datasets,
text: query,
top_k: candidates,
filter: request.filter.as_ref(),
})
.await?
} else {
Vec::new()
};
let mut hits = if use_keyword {
let vector_weight = if use_vector { weights.vector } else { 0.0 };
merge_weighted(vector_hits, keyword_hits, vector_weight, weights.keyword)
} else {
vector_hits
};
if let Some(filter) = &request.filter {
hits.retain(|h| filter.matches(&h.metadata));
}
hits = expand_parents(self.store.as_ref(), hits).await?;
if let (true, Some(reranker)) = (request.rerank, &self.reranker) {
hits = rerank(reranker.as_ref(), query, hits).await?;
}
Ok(finalize(hits, request.score_threshold, request.top_k))
})
}
}
async fn expand_parents(store: &dyn VectorStore, hits: Vec<Hit>) -> Result<Vec<Hit>, RagError> {
let parent_of = |hit: &Hit| hit.metadata.get(PARENT_KEY).and_then(serde_json::Value::as_u64);
if !hits.iter().any(|h| parent_of(h).is_some()) {
return Ok(hits);
}
let mut documents: HashMap<(String, String), Vec<StoredChunk>> = HashMap::new();
for hit in hits.iter().filter(|h| parent_of(h).is_some()) {
if let std::collections::hash_map::Entry::Vacant(slot) =
documents.entry((hit.dataset_id.clone(), hit.document_id.clone()))
{
slot.insert(store.document_chunks(&hit.dataset_id, &hit.document_id).await?);
}
}
let mut seen: HashSet<(String, String, u64)> = HashSet::new();
let mut expanded = Vec::with_capacity(hits.len());
let mut ordered = hits;
ordered.sort_by(|a, b| b.score.total_cmp(&a.score));
for mut hit in ordered {
let Some(parent) = parent_of(&hit) else {
expanded.push(hit);
continue;
};
let key = (hit.dataset_id.clone(), hit.document_id.clone(), parent);
if !seen.insert(key) {
continue;
}
if let Some(chunks) = documents.get(&(hit.dataset_id.clone(), hit.document_id.clone())) {
let mut children: Vec<&StoredChunk> = chunks
.iter()
.filter(|c| c.metadata.get(PARENT_KEY).and_then(serde_json::Value::as_u64) == Some(parent))
.collect();
children
.sort_by_key(|c| c.metadata.get("chunk_index").and_then(serde_json::Value::as_u64).unwrap_or(u64::MAX));
if !children.is_empty() {
hit.content = children.iter().map(|c| c.text.as_str()).collect::<Vec<_>>().join(" ");
}
}
expanded.push(hit);
}
Ok(expanded)
}
pub fn merge_weighted(vector: Vec<Hit>, keyword: Vec<Hit>, vector_weight: f32, keyword_weight: f32) -> Vec<Hit> {
let total = (vector_weight + keyword_weight).max(f32::EPSILON);
let (wv, wk) = (vector_weight / total, keyword_weight / total);
let max_kw = keyword.iter().map(|h| h.score).fold(0.0f32, f32::max);
let mut merged: Vec<Hit> = Vec::with_capacity(vector.len() + keyword.len());
let mut index: HashMap<String, usize> = HashMap::new();
for mut hit in vector {
hit.score = wv * hit.score.clamp(0.0, 1.0);
index.insert(hit.id.clone(), merged.len());
merged.push(hit);
}
for mut hit in keyword {
let normalized = if max_kw > 0.0 { hit.score / max_kw } else { 0.0 };
match index.get(&hit.id).and_then(|&ix| merged.get_mut(ix)) {
Some(existing) => existing.score += wk * normalized,
None => {
hit.score = wk * normalized;
index.insert(hit.id.clone(), merged.len());
merged.push(hit);
}
}
}
merged.sort_by(|a, b| b.score.total_cmp(&a.score));
merged
}
pub async fn rerank(reranker: &dyn Reranker, query: &str, mut hits: Vec<Hit>) -> Result<Vec<Hit>, RagError> {
if hits.is_empty() {
return Ok(hits);
}
let docs: Vec<String> = hits.iter().map(|h| h.content.clone()).collect();
let scores = reranker.rerank(query, &docs).await?;
if scores.len() != hits.len() {
return Err(RagError::Decode(format!(
"reranker returned {} scores for {} documents",
scores.len(),
hits.len()
)));
}
for (hit, score) in hits.iter_mut().zip(scores) {
if !score.is_finite() {
return Err(RagError::Decode("reranker returned a non-finite score".into()));
}
hit.score = score;
}
hits.sort_by(|a, b| b.score.total_cmp(&a.score));
Ok(hits)
}
pub fn finalize(mut hits: Vec<Hit>, threshold: Option<f32>, top_k: usize) -> Vec<Hit> {
hits.retain(|h| h.score.is_finite());
if let Some(t) = threshold {
hits.retain(|h| h.score >= t);
}
hits.sort_by(|a, b| b.score.total_cmp(&a.score));
hits.truncate(top_k);
hits
}
#[cfg(test)]
mod tests {
use super::*;
fn hit(id: &str, score: f32) -> Hit {
Hit {
id: id.into(),
dataset_id: "d".into(),
document_id: String::new(),
title: String::new(),
content: id.into(),
score,
metadata: serde_json::Map::new(),
}
}
#[test]
fn weighted_merge_combines_by_id() {
let vector = vec![hit("a", 0.9), hit("b", 0.5)];
let keyword = vec![hit("b", 10.0), hit("c", 5.0)];
let merged = merge_weighted(vector, keyword, 0.5, 0.5);
let ids: Vec<&str> = merged.iter().map(|h| h.id.as_str()).collect();
assert_eq!(ids, vec!["b", "a", "c"]);
assert!((merged[0].score - 0.75).abs() < 1e-6);
assert!((merged[1].score - 0.45).abs() < 1e-6);
assert!((merged[2].score - 0.25).abs() < 1e-6);
}
#[test]
fn finalize_thresholds_and_truncates() {
let out = finalize(vec![hit("a", 0.2), hit("b", 0.8), hit("c", 0.5)], Some(0.4), 1);
assert_eq!(out.len(), 1);
assert_eq!(out[0].id, "b");
}
}