rank-bm25

Implements the canonical BM25 (Best Matching 25) algorithm using the Okapi variant, which scores document relevance to queries through a probabilistic ranking function that combines term frequency, inverse document frequency, and document length normalization. The implementation accepts pre-tokenized document corpora and queries, computing relevance scores via numpy-based matrix operations on term statistics (document frequencies, term positions, corpus-wide IDF values). Initialization computes IDF values across the entire corpus once, then get_scores() applies the BM25 formula with tunable k1 (term saturation) and b (length normalization) parameters to generate per-document relevance scores.

Implements the BM25L variant, which modifies the standard BM25 formula to normalize document length more aggressively, addressing the bias toward longer documents that can occur with standard BM25. The algorithm adjusts the length normalization component by using a different formula that prevents saturation effects when documents vary significantly in length. Like BM25Okapi, it computes corpus-wide IDF once during initialization and applies the modified scoring formula during get_scores(), but the length normalization parameter b has different semantics and impact compared to the standard variant.

Implements the BM25+ variant, which refines the term frequency saturation component of standard BM25 by adding a constant term to the numerator of the saturation function, preventing term frequency from ever reaching zero contribution. This addresses a theoretical limitation in BM25Okapi where very high term frequencies can paradoxically reduce relevance scores. The implementation maintains the same initialization and scoring interface as other variants but applies a modified formula during get_scores() that ensures monotonic improvement with term frequency.

Computes inverse document frequency (IDF) statistics across the entire tokenized corpus during algorithm initialization, storing term-to-IDF mappings that are reused across all subsequent queries. The implementation iterates through the corpus once to count document frequencies per term, then applies the IDF formula (typically log(N / df) where N is corpus size and df is document frequency) to generate a lookup table. This one-time computation cost is amortized across multiple queries, but requires that the corpus is static — adding new documents necessitates recomputing IDF values for the entire corpus.

Provides a get_top_n() method that scores all documents in the corpus against a query and returns the top N results sorted by relevance score in descending order. The implementation calls get_scores() internally to compute relevance for all documents, then uses numpy argsort or similar sorting to identify and return the N highest-scoring documents as tuples of (document_index, score). This convenience method eliminates the need for users to manually sort and filter results, providing a common retrieval pattern in a single function call.

Exposes k1 (term saturation parameter) and b (length normalization parameter) as configurable hyperparameters during algorithm initialization, allowing users to customize the ranking behavior without modifying the library code. The k1 parameter controls how quickly term frequency saturates (higher k1 = slower saturation, more weight on term frequency), while b controls the degree of length normalization (b=0 disables length normalization, b=1 applies full normalization). These parameters are stored as instance variables and applied during get_scores() computation, enabling empirical tuning for specific domains or datasets.

Implements all BM25 algorithms using only numpy for numerical operations, avoiding heavy dependencies on full IR frameworks (Elasticsearch, Solr) or machine learning libraries (scikit-learn, TensorFlow). The library uses numpy arrays for efficient vector operations (IDF lookups, score computation) and basic Python data structures (lists, dicts) for corpus management. This design choice minimizes installation overhead and allows the library to be embedded in larger systems without dependency conflicts, though it sacrifices some performance optimizations available in specialized IR libraries.

Accepts pre-tokenized documents and queries as input, leaving all text preprocessing (lowercasing, stemming, stopword removal, punctuation handling) to the caller. The library makes no assumptions about tokenization strategy and works with any tokenization scheme the user provides, whether simple whitespace splitting, sophisticated NLP pipelines (spaCy, NLTK), or domain-specific tokenizers. This design maximizes flexibility but requires users to implement preprocessing themselves, making the library a pure ranking algorithm rather than an end-to-end search solution.

Provides a uniform get_scores(tokenized_query) method across all BM25 variants (Okapi, L, Plus) that takes a pre-tokenized query and returns a numpy array of relevance scores, one per document in the corpus. The method is stateless — it does not modify internal state or cache results — and produces deterministic scores given the same query and corpus. All variants share this interface, allowing users to swap implementations without changing calling code, though the underlying scoring formulas differ.