use crate::core::Scored;
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct SourceContribution {
pub list_index: usize,
pub rank: usize,
pub partial_score: f32,
}
#[derive(Debug, Clone, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Explained<Id, Metadata = ()> {
pub scored: Scored<Id, Metadata>,
pub contributions: Vec<SourceContribution>,
}
impl<Id, Metadata> Explained<Id, Metadata> {
pub fn id(&self) -> &Id {
self.scored.id()
}
pub fn score(&self) -> f32 {
self.scored.score
}
}
#[cfg(test)]
mod tests {
use crate::core::{RankedList, Scored, ScoredList};
use crate::fusion::{Fusion, LinearFusion, Rrf, WeightedRrf};
use crate::reranking::{Pipeline, TopK};
fn ranked() -> Vec<RankedList<&'static str>> {
vec![
["a", "b", "c"].into_iter().collect(),
["b", "d", "a"].into_iter().collect(),
]
}
fn scored_lists() -> Vec<ScoredList<&'static str>> {
vec![
ScoredList::new(vec![
Scored::new("a", 0.95, ()),
Scored::new("b", 0.85, ()),
Scored::new("d", 0.20, ()),
]),
ScoredList::new(vec![Scored::new("b", 42.0, ()), Scored::new("c", 17.0, ())]),
]
}
#[track_caller]
fn assert_matches_plain<Id, M>(explained: &[crate::Explained<Id, M>], plain: &[Scored<Id, M>])
where
Id: PartialEq + std::fmt::Debug,
M: PartialEq + std::fmt::Debug,
{
assert_eq!(explained.len(), plain.len());
for (e, p) in explained.iter().zip(plain) {
assert_eq!(e.scored, *p);
let sum: f32 = e.contributions.iter().map(|c| c.partial_score).sum();
assert!(
(sum - e.scored.score).abs() < 1e-6,
"sum {sum} != fused {}",
e.scored.score
);
}
}
#[test]
fn rrf_contributions_sum_to_fused_score() {
let explained = Rrf::default().fuse_explained(ranked());
let plain = Rrf::default().fuse(ranked());
assert_matches_plain(&explained, &plain);
}
#[test]
fn weighted_rrf_contributions_sum_to_fused_score() {
let w = WeightedRrf::new(60.0, vec![1.0, 2.5]);
let explained = w.fuse_explained(ranked()).unwrap();
let plain = w.fuse(ranked()).unwrap();
assert_matches_plain(&explained, &plain);
}
#[test]
fn linear_contributions_sum_to_fused_score() {
let lf = LinearFusion::new(vec![1.0, 0.5]);
let explained = lf.fuse_explained(scored_lists()).unwrap();
let plain = lf.fuse(scored_lists()).unwrap();
assert_matches_plain(&explained, &plain);
}
#[test]
fn contributions_carry_list_and_rank() {
let explained = Rrf::default().fuse_explained(ranked());
let b = &explained[0];
assert_eq!(*b.id(), "b");
assert_eq!(b.contributions.len(), 2);
assert_eq!(
(b.contributions[0].list_index, b.contributions[0].rank),
(0, 2)
);
assert_eq!(
(b.contributions[1].list_index, b.contributions[1].rank),
(1, 1)
);
let c = explained.iter().find(|e| *e.id() == "c").unwrap();
assert_eq!(c.contributions.len(), 1);
assert_eq!(
(c.contributions[0].list_index, c.contributions[0].rank),
(0, 3)
);
}
#[test]
fn weighted_partial_scores_reflect_weights() {
let w = WeightedRrf::new(0.0, vec![2.0, 1.0]);
let explained = w.fuse_explained(ranked()).unwrap();
let b = explained.iter().find(|e| *e.id() == "b").unwrap();
assert_eq!(b.contributions[0].partial_score, 1.0);
assert_eq!(b.contributions[1].partial_score, 1.0);
}
#[test]
fn trait_fuse_explained_is_object_reachable() {
fn generic<F: Fusion<&'static str, ()>>(f: &F, lists: Vec<F::Input>) -> usize {
f.fuse_explained(lists).unwrap().len()
}
assert_eq!(generic(&Rrf::default(), ranked()), 4);
assert_eq!(
generic(&LinearFusion::new(vec![1.0, 1.0]), scored_lists()),
4
);
}
#[test]
fn pipeline_rank_explained_ignores_stages() {
let pipeline = Pipeline::new(Rrf::default()).reranker(TopK::new(1));
let explained = pipeline.rank_explained(ranked()).unwrap();
assert_eq!(explained.len(), 4); let plain = pipeline.rank(ranked()).unwrap();
assert_eq!(plain.len(), 1); }
}