---

name: acceleration-and-selection description: "Use optional Numba retrieval and CSC acceleration, NumPy/JAX top-k selection, and diagnose dependency or backend fallbacks in bm25s." disable-model-invocation: true metadata: disco-role: operating license: MIT

Acceleration and selection

Use this route when a local bm25s index needs optional Numba scoring/retrieval, Numba-assisted CSC construction, NumPy/JAX top-k selection, or a diagnosis of backend and optional-dependency behavior. Keep the ordinary indexing/retrieval recipe in the core route; this route supplies the acceleration choices that are safe to add to it.

Make the backend decision explicit

• The required path is CPU NumPy: BM25(backend="numpy", csc_backend="numpy"), followed by retrieve(..., backend_selection="numpy"). The base package requires NumPy; optional speed packages are not a runtime prerequisite.
• backend selects scoring/retrieval execution. "numba" requires Numba; "auto" resolves to Numba when the import is available and otherwise to NumPy. The resolved value is stored in retriever.backend at construction.
• csc_backend selects index construction: "numpy" is the dependency-light default, "scipy" uses scipy.sparse.csc_matrix, and "auto" resolves to SciPy when SciPy imports successfully and otherwise to NumPy. This choice is made while constructing the index, not while selecting top-k results.
• backend_selection is a separate top-k selector. For a NumPy BM25 backend, "numpy", "jax", and "auto" are meaningful. "auto" uses JAX when bm25s.selection.JAX_IS_AVAILABLE is true and NumPy otherwise. JAX is a CPU option here; this skill makes no CUDA or GPU-performance promise.
• For a Numba BM25 backend, retrieval internally maps backend_selection="auto" to "numba"; the Numba retrieval path requires backend_selection="numba". Do not combine backend="numba" with backend_selection="jax" or "numpy".

The complete parameter and error table is in references/api-reference.md. Use the bounded local checker at scripts/numba_smoke.py before benchmarking or changing a production configuration.

Install only what the chosen path needs

pip install bm25s                 # NumPy base path
pip install "bm25s[core]"         # project core extras, including Numba
pip install "bm25s[indexing]"      # SciPy CSC option
pip install "bm25s[selection]"     # CPU JAX top-k option

The package metadata also exposes numba, scipy, and jax[cpu] through the corresponding extras. full combines extras, but is not required for this route. Install into the same interpreter that imports bm25s; report the actual availability flags rather than assuming that an extra was installed.

Baseline, Numba, and selector recipes

Start with a baseline when correctness or portability matters:

retriever = bm25s.BM25(backend="numpy", csc_backend="numpy")
retriever.index(corpus_tokens, show_progress=False)
results = retriever.retrieve(
    query_tokens, k=10, backend_selection="numpy", show_progress=False
)

For CPU Numba retrieval and optional Numba CSC construction, make compilation an explicit decision:

retriever = bm25s.BM25(
    backend="numba", csc_backend="numpy", auto_compile=False
)
retriever.compile(activate_numba=True, warmup=False)
retriever.index(corpus_tokens, show_progress=False)
results = retriever.retrieve(
    query_tokens, k=10, backend_selection="numba", show_progress=False
)

Call compile before index when Numba CSC construction should be used; call it after loading an existing index when only retrieval scoring needs activation. warmup=True runs small dummy CSC and scorer calls to pay JIT compilation before the first real request. The first call can still have signature/cache overhead, and Numba is CPU-only in this operating contract. See references/numba-workflows.md for the timing, thread, and fallback decisions.

For NumPy scoring with optional JAX selection:

retriever = bm25s.BM25(backend="numpy", csc_backend="numpy")
retriever.index(corpus_tokens, show_progress=False)
results = retriever.retrieve(
    query_tokens, k=10, backend_selection="jax", show_progress=False
)

Use backend_selection="auto" only when a JAX-versus-NumPy choice is acceptable. bm25s.selection.topk accepts one-dimensional score arrays and raises ValueError for an invalid selector; an explicit JAX request raises ImportError when JAX is unavailable. The Numba selector is a separate bm25s.numba.selection.topk API and accepts only backend="numba".

Compile and fallback rules

• auto_compile is a constructor control and defaults to True, but explicit compile(...) is the reproducible choice when relying on JIT activation. This revision's constructor guard is environment-sensitive; with NUMBA_DISABLE_JIT unset, inspection observed no automatic compiled wrapper despite the default. Do not infer compilation from the constructor flag; inspect or run a smoke retrieval.
• If NUMBA_DISABLE_JIT is set, the scorer activation/warmup path is skipped. Unset it when JIT execution is intended. Keep auto_compile=False for predictable setup and compile deliberately.
• Missing Numba with backend="auto" is a normal fallback to NumPy. Missing Numba with backend="numba" or compile(...) is an actionable ImportError.
• Missing SciPy with csc_backend="auto" falls back to NumPy. Explicit csc_backend="scipy" raises ImportError.
• Missing JAX with selector "auto" falls back to NumPy. Explicit "jax" raises ImportError; an invalid selector raises ValueError.
• Do not present optional backends as CUDA support. If a dependency emits a GPU-availability warning but imports its CPU implementation, record that as CPU execution rather than claiming accelerator coverage.

For install/import, data/configuration, API/CLI, and workflow-specific failures, use references/troubleshooting.md. Do not use Hub/BEIR network examples as acceleration tests; keep checks local and bounded.