feat(searcher): unify exploration control into single eps_or_ef parameter

- High-level C++ Searcher and Python bindings now accept a single eps_or_ef parameter
- Dispatches to fixed-pool search_ef when eps_or_ef >= 1.0, and relative search_eps otherwise
- Simplifies VIBE benchmarking adapter and grid-searches
- Updates API docs, READMEs (C++, Python, Sphinx), and test suites

Author: Neiko2002

cpp/deglib/include/deglib/search/searcher.h

@@ -111,6 +111,24 @@ auto dynamic_graph = deglib::load_dynamic_graph("index.deg", /*chunk_size=*/1024
 auto mutable_graph = deglib::load_mutable_graph("index.deg", /*new_max_size=*/10000);
 ```
 
+### High-Performance Searcher (`eps_or_ef`)
+
+`deglib::search::Searcher` provides a high-throughput query execution pipeline supporting entry vertex optimization, optional on-the-fly query quantization, exact candidate reranking, and multithreaded batch search with unified exploration parameter `eps_or_ef`:
+
+```cpp
+#include <deglib/search/searcher.h>
+
+// 1. Create searcher on top of a graph (optionally with quantizer & refiner)
+auto searcher = deglib::search::make_searcher(readonly_graph);
+searcher->optimize(/*n_clusters=*/128); // entry vertex medoids via k-means
+
+// 2. Query with relative distance margin (eps_or_ef < 1.0)
+auto eps_results = searcher->search(std::span<const float>(query), /*k=*/10, /*eps_or_ef=*/0.1f);
+
+// 3. Query with fixed candidate pool size (eps_or_ef >= 1.0, HNSW-style)
+auto ef_results = searcher->search(std::span<const float>(query), /*k=*/10, /*eps_or_ef=*/128.0f);
+```
+
 ---
 
 ## Prerequisites

cpp/readme.md

@@ -233,3 +233,42 @@ TEST(SearcherTest, FlatBatchAndIntoSearch) {
     }
 }
 
+TEST(SearcherTest, SearchEfSingleAndBatch) {
+    const uint32_t dim = 4;
+    const uint32_t count = 30;
+
+    std::vector<float> data(count * dim);
+    for (size_t i = 0; i < data.size(); ++i) {
+        data[i] = static_cast<float>(i * 0.5f + 0.1f);
+    }
+
+    auto graph = deglib::builder::build_from_data(std::span<const float>(data), dim, {}, 8, deglib::distances::Metric::FP32_L2);
+    auto searcher = deglib::search::make_searcher(graph.internal());
+
+    const uint32_t k = 4;
+    const float ef = 32.0f;
+
+    // 1. Single search with eps_or_ef >= 1.0 (ef mode)
+    auto q0 = std::span<const float>(data.data(), dim);
+    auto single_res = searcher->search(q0, k, /*eps_or_ef=*/ef, /*rerank_factor=*/1.0f, /*return_distances=*/true);
+    EXPECT_GE(single_res.size(), 1u);
+    EXPECT_EQ(single_res.indices[0], 0u);
+    EXPECT_NEAR(single_res.distances[0], 0.0f, 1e-5f);
+
+    // 2. Batch search with eps_or_ef >= 1.0 (ef mode) with flat result and 2 worker threads
+    const size_t n_queries = 5;
+    auto batch_res = searcher->search_batch(
+        std::span<const float>(data.data(), n_queries * dim),
+        n_queries, k, /*eps_or_ef=*/ef, /*rerank_factor=*/1.0f, /*threads=*/2, /*return_distances=*/true
+    );
+    EXPECT_EQ(batch_res.size(), n_queries);
+    EXPECT_EQ(batch_res.k, k);
+    for (size_t q = 0; q < n_queries; ++q) {
+        auto q_indices = batch_res.get_indices(q);
+        auto q_dists = batch_res.get_distances(q);
+        EXPECT_EQ(q_indices[0], static_cast<uint32_t>(q));
+        EXPECT_NEAR(q_dists[0], 0.0f, 1e-5f);
+    }
+}
+
+

cpp/test/src/unit/test_searcher.cpp

@@ -67,13 +67,16 @@ High-Performance Searcher with Reranking
        refine_data=data,
    )
 
-   # Single query
-   indices, distances = searcher.search(query, k=10, eps=0.1, rerank_factor=1.5, return_distances=True)
+   # Single query using relative margin (eps_or_ef < 1.0)
+   indices, distances = searcher.search(query, k=10, eps_or_ef=0.1, rerank_factor=1.5, return_distances=True)
 
-   # Batch query
+   # Single query using fixed pool exploration (eps_or_ef >= 1.0, HNSW-style)
+   indices_ef, distances_ef = searcher.search(query, k=10, eps_or_ef=128, rerank_factor=1.5, return_distances=True)
+
+   # Multithreaded batch query (supports eps_or_ef < 1.0 or >= 1.0)
    batch_queries = np.random.randn(100, dim).astype(np.float32)
    batch_indices, batch_distances = searcher.search(
-       batch_queries, k=10, eps=0.1, rerank_factor=1.5, threads=8, return_distances=True
+       batch_queries, k=10, eps_or_ef=128, rerank_factor=1.5, threads=8, return_distances=True
    )
 
 Filtered Search

docs/api/search.rst

@@ -11,11 +11,11 @@ float:
     run_groups:
       base:
         args:
-          k: [48]
-          opt_target: ['LowLID']
-          prune_non_rng: [false]
+          k: [16, 24, 30, 40, 48]
+          opt_target: ['LowLID', 'StreamingData']
+          prune_non_rng: [false, true]
         query_args:
-          eps_or_ef: [0.0, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.15, 0.2, 0.25, 0.3]
+          eps_or_ef: [64, 96, 128, 160, 200, 250, 320, 400, 0.0, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.15, 0.2, 0.25, 0.3]
   - name: deg-qg
     module: vibe.algorithms.deg
     constructor: QG
@@ -27,9 +27,9 @@ float:
     run_groups:
       linear_pool:
         args:
-          k: [48]
-          opt_target: ['LowLID']
-          prune_non_rng: [false]
+          k: [16, 24, 30, 40, 48]
+          opt_target: ['LowLID', 'StreamingData']
+          prune_non_rng: [false, true]
         query_args:
           rerank_size_factor: [1.0, 1.15, 1.35]
-          eps_or_ef: [0.0, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.15, 0.2, 0.25, 0.3]
+          eps_or_ef: [64, 96, 128, 160, 200, 250, 320, 400, 0.0, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.12, 0.15, 0.2, 0.25, 0.3]

examples/vibe/BENCHMARK_PLAN.md

@@ -100,8 +100,7 @@ def __init__(
         self.opt_target = opt_target
         self.prune_non_rng = bool(prune_non_rng)
         self.threads = int(threads)
-        self.search_eps = 0.1
-        self.ef = 0
+        self.eps_or_ef = 0.1
         self.metric_enum = _METRIC_MAP[self.metric][0]
         self.opt_enum = deglib.builder.OptimizationTarget[self.opt_target]
         self.graph = None
@@ -166,14 +165,8 @@ def fit(self, X: np.ndarray, cache_dir: Path | None = None):
         print(f"Optimized Searcher for the provided graph and hardware in {time.time() - t_km:.2f}s", flush=True)
 
     def set_query_arguments(self, eps_or_ef: float | int):
-        """Sets query-time parameter: values > 1.0 are treated as ef, <= 1.0 as eps."""
-        val = float(eps_or_ef)
-        if val > 1.0:
-            self.ef = int(round(val))
-            self.search_eps = 0.0
-        else:
-            self.search_eps = val
-            self.ef = 0
+        """Sets query-time parameter: values >= 1.0 are treated as ef, < 1.0 as eps."""
+        self.eps_or_ef = float(eps_or_ef)
 
     def query(self, v: np.ndarray, n: int) -> np.ndarray:
         """Single query search on 1 thread with Float32 via C++ searcher."""
@@ -182,17 +175,16 @@ def query(self, v: np.ndarray, n: int) -> np.ndarray:
         return self.searcher.search(
             np.ascontiguousarray(v, dtype=np.float32),
             k=n,
-            ef=self.ef,
-            eps=self.search_eps,
+            eps_or_ef=self.eps_or_ef,
             threads=1,
             return_distances=False,
             unsorted=True,
         )
 
     def __str__(self) -> str:
-        if self.ef > 0:
-            return f"DEG(k={self.k}, opt={self.opt_target}, prune_rng={self.prune_non_rng}, ef={self.ef})"
-        return f"DEG(k={self.k}, opt={self.opt_target}, prune_rng={self.prune_non_rng}, eps={self.search_eps})"
+        if self.eps_or_ef >= 1.0:
+            return f"DEG(k={self.k}, opt={self.opt_target}, prune_rng={self.prune_non_rng}, ef={int(round(self.eps_or_ef))})"
+        return f"DEG(k={self.k}, opt={self.opt_target}, prune_rng={self.prune_non_rng}, eps={self.eps_or_ef})"
 
 
 class QG(BaseANN):
@@ -303,15 +295,9 @@ def fit(self, X: np.ndarray, cache_dir: Path | None = None):
         print(f"Optimized Searcher for the provided graph and hardware in {time.time() - t_km:.2f}s", flush=True)
 
     def set_query_arguments(self, eps_or_ef: float | int, rerank_size_factor: float = 1.0):
-        """Sets query-time parameters: values > 1.0 are treated as ef, <= 1.0 as eps."""
+        """Sets query-time parameters: values >= 1.0 are treated as ef, < 1.0 as eps."""
         self.rerank_size_factor = float(rerank_size_factor)
-        val = float(eps_or_ef)
-        if val > 1.0:
-            self.ef = int(round(val))
-            self.search_eps = 0.0
-        else:
-            self.search_eps = val
-            self.ef = 0
+        self.eps_or_ef = float(eps_or_ef)
 
     def query(self, v: np.ndarray, n: int) -> np.ndarray:
         """Single query search on 1 thread with INT8 search and FP16 reranking directly in C++."""
@@ -320,22 +306,21 @@ def query(self, v: np.ndarray, n: int) -> np.ndarray:
         return self.searcher.search(
             np.ascontiguousarray(v, dtype=np.float32),
             k=n,
-            ef=self.ef,
-            eps=self.search_eps,
+            eps_or_ef=self.eps_or_ef,
             rerank_factor=self.rerank_size_factor,
             threads=1,
             return_distances=False,
             unsorted=True,
         )
 
     def __str__(self) -> str:
-        if getattr(self, "ef", 0) > 0:
+        if self.eps_or_ef >= 1.0:
             return (
                 f"DEG-QG(k={self.k}, opt={self.opt_target}, prune_rng={self.prune_non_rng}, "
-                f"rerank_factor={self.rerank_size_factor}, ef={self.ef})"
+                f"rerank_factor={self.rerank_size_factor}, ef={int(round(self.eps_or_ef))})"
             )
         return (
             f"DEG-QG(k={self.k}, opt={self.opt_target}, prune_rng={self.prune_non_rng}, "
-            f"rerank_factor={self.rerank_size_factor}, eps={self.search_eps})"
+            f"rerank_factor={self.rerank_size_factor}, eps={self.eps_or_ef})"
         )
 

examples/vibe/config.yml

@@ -275,6 +275,27 @@ class Filter:
 # unsorted: If True, skips sorting the resulting candidates
 # Returns 2D uint32 array [Q, k_top] of candidate IDs, or (indices, distances) if return_distances is True.
 rerank(space, queries, candidate_indices, base_vectors=None, k_top=0, num_threads=0, return_distances=False, unsorted=False)
+
+
+# High-performance searcher with optional on-the-fly quantization and exact reranking.
+class Searcher:
+    # Constructor via create_searcher(graph, quantizer=None, refine_space=None, refine_data=None)
+
+    # Entry vertex optimization via k-means medoids
+    optimize(n_clusters=128, n_iter=15, sample_size=0, seed=42, num_threads=0)
+
+    # Search for nearest neighbors of a single query (1D) or a batch of queries (2D).
+    # query: 1D vector [D] or 2D batch [N, D]
+    # k: Number of nearest neighbors to return
+    # eps_or_ef: Exploration parameter. Values >= 1.0 are treated as fixed pool size (ef),
+    #            values < 1.0 are treated as relative distance margin (eps). Default: 0.1.
+    # rerank_factor: Candidate expansion factor for exact reranking (retrieves ceil(k * rerank_factor) candidates)
+    # threads: Number of worker threads for batch queries
+    # return_distances: If True, returns (indices, distances) tuple
+    # unsorted: If True, returns candidates in heap order instead of ascending distance order
+    search(query, k, eps_or_ef=0.1, rerank_factor=1.0, threads=1, return_distances=False, unsorted=False) -> np.ndarray | tuple[np.ndarray, np.ndarray]
+
+create_searcher(graph, quantizer=None, refine_space=None, refine_data=None) -> Searcher
 ```
 
 ---

examples/vibe/module.py

@@ -250,10 +250,21 @@ Controls the topology optimization strategy:
 - `OptimizationTarget.HighLID`: Optimized for datasets with high local intrinsic dimensionality (supports multithreaded building).
 - `OptimizationTarget.StreamingData`: Optimized for continuous dynamic additions and deletions.
 
-### Search Parameter `eps`
-- The epsilon parameter expands the search priority queue during graph exploration.
-- Small values (e.g. `eps=0.001` or `eps=0.01`): Faster query execution.
-- Higher values (e.g. `eps=0.1` to `eps=0.3`): Higher recall rate.
+### Unified Search Parameter: `eps_or_ef`
+`Searcher` provides a unified exploration parameter `eps_or_ef`:
+- **Relative Distance Margin (`eps_or_ef < 1.0`)**: Standard DEG dynamic distance exploration bound $(1 + \epsilon) \cdot d_{\text{cur}}$.
+  - Small values (e.g. `eps_or_ef=0.001` or `0.01`): Faster query execution.
+  - Higher values (e.g. `eps_or_ef=0.1` to `0.3`): Higher recall rate.
+- **Fixed Candidate Pool (`eps_or_ef >= 1.0`)**: HNSW-style search with a fixed candidate pool size of `round(eps_or_ef)` during exploration.
+  - Typical values: `64`, `96`, `128`, `200`, `400`.
+
+```python
+# Mode 1: Relative distance margin (default: eps_or_ef=0.1)
+indices, distances = searcher.search(query, k=10, eps_or_ef=0.1)
+
+# Mode 2: Fixed candidate pool (HNSW-style)
+indices, distances = searcher.search(query, k=10, eps_or_ef=128)
+```
 
 ### Supported Metrics & Data Types
 - `Metric.FP32_L2`: Euclidean distance (`np.float32`)

python/API.md

@@ -819,7 +819,7 @@ class SearcherPy {
         searcher_->optimize(n_clusters, n_iter, sample_size, seed, num_threads);
     }
 
-    py::object search(py::array query, uint32_t k, float eps = 0.1f, float rerank_factor = 1.0f, bool return_distances = false, bool unsorted = false, uint32_t ef = 0) {
+    py::object search(py::array query, uint32_t k, float eps_or_ef = 0.1f, float rerank_factor = 1.0f, bool return_distances = false, bool unsorted = false) {
         auto buf = query.request();
         if (buf.ndim != 1 && (buf.ndim != 2 || (buf.shape[0] != 1 && buf.shape[1] != 1))) {
             throw std::invalid_argument("search query must be 1D vector (or 1xDim / Dimx1 2D array)");
@@ -835,17 +835,18 @@ class SearcherPy {
         }
 
         uint32_t count = 0;
-        if (ef > 0) {
+        if (eps_or_ef >= 1.0f) {
+            const uint32_t ef = static_cast<uint32_t>(std::lround(eps_or_ef));
             if (buf.itemsize == 2 && (buf.format == "H" || buf.format == "h" || buf.format == "e")) {
                 count = searcher_->search_ef_f16(static_cast<const uint16_t*>(buf.ptr), k, ef, rerank_factor, out_ptr, dist_ptr, unsorted);
             } else {
                 count = searcher_->search_ef_f32(static_cast<const float*>(buf.ptr), k, ef, rerank_factor, out_ptr, dist_ptr, unsorted);
             }
         } else {
             if (buf.itemsize == 2 && (buf.format == "H" || buf.format == "h" || buf.format == "e")) {
-                count = searcher_->search_f16(static_cast<const uint16_t*>(buf.ptr), k, eps, rerank_factor, out_ptr, dist_ptr, unsorted);
+                count = searcher_->search_f16(static_cast<const uint16_t*>(buf.ptr), k, eps_or_ef, rerank_factor, out_ptr, dist_ptr, unsorted);
             } else {
-                count = searcher_->search_f32(static_cast<const float*>(buf.ptr), k, eps, rerank_factor, out_ptr, dist_ptr, unsorted);
+                count = searcher_->search_f32(static_cast<const float*>(buf.ptr), k, eps_or_ef, rerank_factor, out_ptr, dist_ptr, unsorted);
             }
         }
 
@@ -855,7 +856,7 @@ class SearcherPy {
         return result;
     }
 
-    py::object search_batch(py::array queries, uint32_t k, float eps = 0.1f, float rerank_factor = 1.0f, size_t num_threads = 1, bool return_distances = false, bool unsorted = false, uint32_t ef = 0) {
+    py::object search_batch(py::array queries, uint32_t k, float eps_or_ef = 0.1f, float rerank_factor = 1.0f, size_t num_threads = 1, bool return_distances = false, bool unsorted = false) {
         auto buf = queries.request();
         if (buf.ndim != 2) {
             throw std::invalid_argument("search_batch queries must be 2D array");
@@ -873,17 +874,18 @@ class SearcherPy {
 
         {
             py::gil_scoped_release release;
-            if (ef > 0) {
+            if (eps_or_ef >= 1.0f) {
+                const uint32_t ef = static_cast<uint32_t>(std::lround(eps_or_ef));
                 if (buf.itemsize == 2 && (buf.format == "H" || buf.format == "h" || buf.format == "e")) {
                     searcher_->search_batch_ef_f16(static_cast<const uint16_t*>(buf.ptr), n_queries, k, ef, rerank_factor, out_ptr, dist_ptr, num_threads, unsorted);
                 } else {
                     searcher_->search_batch_ef_f32(static_cast<const float*>(buf.ptr), n_queries, k, ef, rerank_factor, out_ptr, dist_ptr, num_threads, unsorted);
                 }
             } else {
                 if (buf.itemsize == 2 && (buf.format == "H" || buf.format == "h" || buf.format == "e")) {
-                    searcher_->search_batch_f16(static_cast<const uint16_t*>(buf.ptr), n_queries, k, eps, rerank_factor, out_ptr, dist_ptr, num_threads, unsorted);
+                    searcher_->search_batch_f16(static_cast<const uint16_t*>(buf.ptr), n_queries, k, eps_or_ef, rerank_factor, out_ptr, dist_ptr, num_threads, unsorted);
                 } else {
-                    searcher_->search_batch_f32(static_cast<const float*>(buf.ptr), n_queries, k, eps, rerank_factor, out_ptr, dist_ptr, num_threads, unsorted);
+                    searcher_->search_batch_f32(static_cast<const float*>(buf.ptr), n_queries, k, eps_or_ef, rerank_factor, out_ptr, dist_ptr, num_threads, unsorted);
                 }
             }
         }
@@ -1586,13 +1588,32 @@ PYBIND11_MODULE(deglib_cpp, m) {
         )
         .def(
             "search", &SearcherPy::search,
-            py::arg("query"), py::arg("k"), py::arg("eps") = 0.1f, py::arg("rerank_factor") = 1.0f,
-            py::arg("return_distances") = false, py::arg("unsorted") = false, py::arg("ef") = 0
+            py::arg("query"), py::arg("k"), py::arg("eps_or_ef") = 0.1f, py::arg("rerank_factor") = 1.0f,
+            py::arg("return_distances") = false, py::arg("unsorted") = false,
+            "Search for nearest neighbors of a single query vector.\n\n"
+            "Args:\n"
+            "    query: 1D query vector (or 1xDim 2D array).\n"
+            "    k: Number of nearest neighbors to return.\n"
+            "    eps_or_ef: Exploration parameter. Values >= 1.0 are treated as fixed pool size (ef),\n"
+            "               values < 1.0 are treated as relative distance margin (eps).\n"
+            "    rerank_factor: Expansion factor for exact candidate reranking (default: 1.0).\n"
+            "    return_distances: If True, returns a tuple of (indices, distances).\n"
+            "    unsorted: If True, returns candidates in heap order instead of ascending distance."
         )
         .def(
             "search_batch", &SearcherPy::search_batch,
-            py::arg("queries"), py::arg("k"), py::arg("eps") = 0.1f, py::arg("rerank_factor") = 1.0f,
-            py::arg("num_threads") = 1, py::arg("return_distances") = false, py::arg("unsorted") = false, py::arg("ef") = 0
+            py::arg("queries"), py::arg("k"), py::arg("eps_or_ef") = 0.1f, py::arg("rerank_factor") = 1.0f,
+            py::arg("num_threads") = 1, py::arg("return_distances") = false, py::arg("unsorted") = false,
+            "Search for nearest neighbors for a batch of query vectors.\n\n"
+            "Args:\n"
+            "    queries: 2D query array (shape N x Dim).\n"
+            "    k: Number of nearest neighbors to return per query.\n"
+            "    eps_or_ef: Exploration parameter. Values >= 1.0 are treated as fixed pool size (ef),\n"
+            "               values < 1.0 are treated as relative distance margin (eps).\n"
+            "    rerank_factor: Expansion factor for exact candidate reranking (default: 1.0).\n"
+            "    num_threads: Number of worker threads for parallel search.\n"
+            "    return_distances: If True, returns a tuple of (indices, distances).\n"
+            "    unsorted: If True, returns candidates in heap order instead of ascending distance."
         )
         .def(
             "optimize", &SearcherPy::optimize,