quantumclaw/clawhdf5
3
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

perf(agent): replace BM25 WAND top-k re-sort with a min-heap

Browse Source 
top_k_scores.sort_by(...) ran over the full k-sized buffer for every
matching document that beat the running threshold (twice in the full
branch), plus another full sort on first reaching k results —
O(m·k log k) for m matching documents. Replace the Vec<f32> buffer
with a BinaryHeap<Reverse<HeapScore>> min-heap of size k, giving
O(m log k). Existing wand_returns_same_results_as_exhaustive test
confirms results are unchanged.

INT-11
This commit is contained in:
ClawHDF5 Coding Agent
2026-08-17 00:29:44 +00:00
parent 603fcf8757
commit 934d053f92
1 changed files with 36 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
crates/clawhdf5-agent/src/bm25.rs
+36 -20
View File
@@ -8,7 +8,28 @@
//! - Sorted posting lists by doc_id for cache-friendly access
//! - Block-Max WAND early termination
use std::collections::HashMap;
use std::cmp::Reverse;
use std::collections::{BinaryHeap, HashMap};
/// `f32` wrapper providing a total order (via `total_cmp`) so BM25 scores can
/// be kept in a `BinaryHeap`. Scores are always finite in practice (no NaN
/// inputs reach this path), so `total_cmp`'s NaN ordering is never exercised.
#[derive(Debug, Clone, Copy, PartialEq)]
struct HeapScore(f32);
impl Eq for HeapScore {}
impl PartialOrd for HeapScore {
fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
Some(self.cmp(other))
}
}
impl Ord for HeapScore {
fn cmp(&self, other: &Self) -> std::cmp::Ordering {
self.0.total_cmp(&other.0)
}
}
/// Default BM25 term-frequency saturation parameter.
const DEFAULT_K1: f32 = 1.2;
@@ -97,9 +118,11 @@ impl BM25Index {
let total_max_contribution: f32 = max_tf_score.iter().sum();
// Threshold for WAND early termination
// Threshold for WAND early termination. `top_k_heap` is a min-heap of
// size k (worst-of-the-top-k at the head) so it can be maintained in
// O(log k) per update instead of re-sorting the whole buffer.
let mut threshold = 0.0f32;
let mut top_k_scores: Vec<f32> = Vec::with_capacity(k);
let mut top_k_heap: BinaryHeap<Reverse<HeapScore>> = BinaryHeap::with_capacity(k);
for (term_idx, (_, idf, postings)) in query_terms.iter().enumerate() {
for &(doc_id, freq) in *postings {
@@ -118,24 +141,17 @@ impl BM25Index {
if term_idx == query_terms.len() - 1 {
// Last term: check if this doc beats threshold
let final_score = *entry;
if final_score > threshold && top_k_scores.len() >= k {
// Update threshold
top_k_scores
.sort_by(|a, b| b.partial_cmp(a).unwrap_or(std::cmp::Ordering::Equal));
if final_score > top_k_scores[k - 1] {
top_k_scores[k - 1] = final_score;
top_k_scores.sort_by(|a, b| {
b.partial_cmp(a).unwrap_or(std::cmp::Ordering::Equal)
});
threshold = top_k_scores[k - 1];
if top_k_heap.len() >= k {
if final_score > threshold {
// Replace the current worst-of-top-k.
top_k_heap.pop();
top_k_heap.push(Reverse(HeapScore(final_score)));
threshold = top_k_heap.peek().map(|Reverse(s)| s.0).unwrap_or(0.0);
}
} else if top_k_scores.len() < k {
top_k_scores.push(final_score);
if top_k_scores.len() == k {
top_k_scores.sort_by(|a, b| {
b.partial_cmp(a).unwrap_or(std::cmp::Ordering::Equal)
});
threshold = top_k_scores[k - 1];
} else {
top_k_heap.push(Reverse(HeapScore(final_score)));
if top_k_heap.len() == k {
threshold = top_k_heap.peek().map(|Reverse(s)| s.0).unwrap_or(0.0);
}
}
}