Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

perf(relevance/bm25): count the shared query once per batch, not per item (#3274)

Abhay Singh70edfb4617d3
diff --git a/headroom/relevance/bm25.py b/headroom/relevance/bm25.py
index 2e83204f8..01c7efc43 100644
--- a/headroom/relevance/bm25.py
+++ b/headroom/relevance/bm25.py
@@ -123,6 +123,7 @@ class BM25Scorer(RelevanceScorer):
query_tokens: list[str],
avg_doc_len: float | None = None,
idf_map: dict[str, float] | None = None,
+ query_freq: Counter[str] | None = None,
) -> tuple[float, list[str]]:
"""Compute BM25 score between document and query.
@@ -130,6 +131,10 @@ class BM25Scorer(RelevanceScorer):
doc_tokens: Tokenized document.
query_tokens: Tokenized query.
avg_doc_len: Average document length (optional).
+ query_freq: Pre-computed ``Counter(query_tokens)``. In a batch the
+ query (context) is identical for every item, so counting it once
+ and passing it in avoids rebuilding the same Counter per item.
+ When ``None`` it is computed from ``query_tokens`` as before.
idf_map: Pre-computed corpus IDF per term. When supplied (batch
scoring, where a real corpus exists) each term is weighted by
its inverse document frequency, so a discriminative term such
@@ -148,7 +153,8 @@ class BM25Scorer(RelevanceScorer):
avgdl = avg_doc_len or doc_len or 1
doc_freq = Counter(doc_tokens)
- query_freq = Counter(query_tokens)
+ if query_freq is None:
+ query_freq = Counter(query_tokens)
score = 0.0
matched_terms: list[str] = []
@@ -231,6 +237,11 @@ class BM25Scorer(RelevanceScorer):
if not context_tokens:
return [RelevanceScore(score=0.0, reason="BM25: empty context") for _ in items]
+ # Count the query once: it is the same context for every item, so
+ # rebuilding Counter(context_tokens) inside each _bm25_score call would
+ # redo identical work per item.
+ context_freq = Counter(context_tokens)
+
# Compute average document length for normalization
all_tokens = [self._tokenize(item) for item in items]
avg_len = sum(len(t) for t in all_tokens) / max(len(items), 1)
@@ -253,7 +264,11 @@ class BM25Scorer(RelevanceScorer):
results = []
for item_tokens in all_tokens:
raw_score, matched = self._bm25_score(
- item_tokens, context_tokens, avg_doc_len=avg_len, idf_map=idf_map
+ item_tokens,
+ context_tokens,
+ avg_doc_len=avg_len,
+ idf_map=idf_map,
+ query_freq=context_freq,
)
# Normalize
diff --git a/tests/test_relevance.py b/tests/test_relevance.py
index f5941c42f..162b5c39d 100644
--- a/tests/test_relevance.py
+++ b/tests/test_relevance.py
@@ -148,6 +148,21 @@ class TestBM25Scorer:
assert scores[0].matched_terms == ["alpha"]
assert sorted(scores[1].matched_terms) == ["alpha", "beta"]
+ def test_precomputed_query_freq_matches_recomputed(self):
+ """Passing a precomputed Counter(query_tokens) into ``_bm25_score``
+ must yield identical (score, matched_terms) to letting it recompute
+ the Counter itself. ``score_batch`` relies on this to count the shared
+ context once instead of once per item."""
+ from collections import Counter
+
+ scorer = BM25Scorer()
+ doc_tokens = scorer._tokenize("alpha beta beta gamma id-9c1f2a3b4d5e")
+ query_tokens = scorer._tokenize("beta gamma id-9c1f2a3b4d5e delta")
+
+ recomputed = scorer._bm25_score(doc_tokens, query_tokens)
+ with_freq = scorer._bm25_score(doc_tokens, query_tokens, query_freq=Counter(query_tokens))
+ assert with_freq == recomputed
+
class TestEmbeddingScorer:
"""Tests for embedding-based semantic scorer."""