Add: radius parameter for distance-bounded search

[andrea-dagostino]

Summary

• The change implements the radius argument for search across the C++ core and Python wrapper, allowing users to exclude results beyond a maximum distance threshold.
• Adds float radius to index_search_config_t, threaded through index_dense_gt::search() and filtered_search() overloads, with post-sort filtering in index_gt::search().
• Wires the existing-but-unused radius parameter in Python Index.search() through _search_in_compiled(), and adds it to Indexes.search() and the module-level search().
• Results with distance > radius are excluded; distance == radius is included. Default is infinity (no filtering, fully backward-compatible).

Changed files

File	What
include/usearch/index.hpp	radius field in index_search_config_t + filtering after sort_ascending()/shrink()
include/usearch/index_dense.hpp	radius param on all 12 search()/filtered_search() overloads + search_()
python/usearch/index.py	radius wired through _search_in_compiled(), Index.search(), Indexes.search(), search()
cpp/test.cpp	test_radius_search() -- default, tight, zero, and infinite radius with L2sq
python/scripts/test_index.py	4 test functions (11 parametrized cases) covering filtering, defaults, edge cases, single/batch

Design notes

• C++ filtering happens after HNSW traversal completes (post-filter on sorted results), not during traversal;
• Python filtering uses np.searchsorted on the ascending-sorted distance arrays in _search_in_compiled(). This handles both the HNSW and brute-force exact search paths without changing lib.cpp;
• lib.cpp (pybind11 bindings) is intentionally not changed -- the module-level search(exact=True) path forwards **kwargs to _exact_search, which doesn't accept radius. Extracting radius as a named parameter in _search_in_compiled() avoids this cleanly.

Tests

• C++ test_radius_search() passes (default, tight, zero, infinite radius)
• C++ full test suite passes (build_debug/test_cpp)
• Python radius tests pass (11/11 cases)
• Python full test suite passes (593 passed, 6 skipped -- skips are pre-existing)

[andrea-dagostino]

Any updates?

[shankar-iyer]

C++ filtering happens after HNSW traversal completes (post-filter on sorted results), not during traversal;

Would it mean that callers will have to experiment or pass a very high nn value to be sure that they retrieved all the nieghbours within a specific distance bound?

[andrea-dagostino]

C++ filtering happens after HNSW traversal completes (post-filter on sorted results), not during traversal;

Would it mean that callers will have to experiment or pass a very high nn value to be sure that they retrieved all the nieghbours within a specific distance bound?

Yes. At the moment, this is by design.

The current flow is:

• HNSW traversal runs to find wanted neighbors
• Results are sorted ascending by distance
• Then results beyond radius are filtered out

If we don't want this, we could let radius drive the HNSW traversal termination (stopping expansion when the nearest unvisited candidate exceeds radius) rather than acting as a post-filter.

This is more of a design constraint more than other.