Optimize get_scores(): 77x speedup via sparse precomputation + C accelerator

[EliMunkey]

Summary

• 77x faster get_scores() on BEIR benchmarks (head-to-head, same machine)
• Zero quality regression — NDCG@10 is bit-identical across all datasets
• Fully backward-compatible — public API unchanged, graceful fallback if no C compiler

What changed

Replace the O(V×D) Python list comprehension in get_scores() with a precomputed sparse matrix + compiled C scatter-add:

1. Scipy CSC sparse matrix for term frequencies (replaces list[dict])
2. Precomputed BM25 weights at index time — idf × tf×(k1+1) / (tf + len_norm) stored as CSC, eliminating all math from the query hot path
3. Optional C accelerator — a tiny C function compiled at init via ctypes/clang/gcc with c_void_p and cached raw pointers for minimal FFI overhead. Falls back to np.add.at if no compiler is available
4. float32 score buffer to halve L1 cache pressure on random writes
5. int32 index downcast to halve index memory bandwidth
6. np.argpartition for O(N) top-k in get_top_n

Benchmark results

Measured on BEIR datasets (NFCorpus 3.6K docs, SciFact 5K docs, FiQA 57K docs), head-to-head on the same machine, back-to-back runs:

Dataset	Before (QPS)	After (QPS)	Speedup	NDCG@10
NFCorpus	359	16,751	47×	0.2893 → 0.2893
SciFact	62	6,567	106×	0.6408 → 0.6408
FiQA	5.70	522	92×	0.2049 → 0.2049
Aggregate	50	3,859	77×	identical

New dependency

• scipy — used for csc_matrix/csc_array sparse matrix construction. Added to requirements.txt and setup.py.

Compatibility

• Python 3.8–3.12 (uses csc_array with fallback to csc_matrix for older scipy)
• C accelerator compiles on Linux (gcc) and macOS (clang); falls back gracefully on systems without a C compiler
• All existing tests pass

Test plan

• pytest passes (existing tests)
• flake8 — no new errors introduced
• NDCG@10 verified identical on 3 BEIR datasets
• Graceful fallback tested (np.add.at path works without C compiler)
• BM25L and BM25Plus classes unchanged and functional

🤖 Generated with Claude Code