Add cuvs-bench-elastic: HTTP backend for Elasticsearch GPU vector search

dependencies.yaml

@@ -213,6 +213,14 @@ files:
       table: project
     includes:
       - bench_python
+  py_elastic_cuvs_bench:
+    output: pyproject
+    pyproject_dir: python/cuvs_bench
+    extras:
+      table: project.optional-dependencies
+      key: elastic
+    includes:
+      - bench_elastic
 channels:
   - rapidsai-nightly
   - rapidsai
@@ -500,6 +508,11 @@ dependencies:
       - output_types: [requirements, pyproject]
         packages:
           - matplotlib>=3.9
+  bench_elastic:
+    common:
+      - output_types: [conda, pyproject, requirements]
+        packages:
+          - cuvs-bench-elastic>=26.4.0
   depends_on_cuda_python:
     specific:
       - output_types: [conda, requirements, pyproject]

python/cuvs_bench/cuvs_bench/backends/registry.py

@@ -12,10 +12,15 @@
 from typing import Dict, Type, Optional
 from pathlib import Path
 import importlib
+import importlib.metadata
 import yaml
 
 from .base import BenchmarkBackend
 
+# Entry point group names for plugin discovery
+_BACKENDS_GROUP = "cuvs_bench.backends"
+_CONFIG_LOADERS_GROUP = "cuvs_bench.config_loaders"
+
 
 class BackendRegistry:
     """
@@ -375,10 +380,43 @@ def get_backend(name: str, config: Dict) -> BenchmarkBackend:
     return registry.get_backend(name, config)
 
 
+def _try_load_plugin(name: str) -> None:
+    """
+    Try to load backend and config loader from entry points for the given name.
+
+    Plugins register themselves when their entry point is loaded.
+    Raises ImportError with install instructions if the plugin requires
+    an optional dependency that is not installed.
+    """
+    for group in (_BACKENDS_GROUP, _CONFIG_LOADERS_GROUP):
+        try:
+            eps = importlib.metadata.entry_points(group=group)
+        except TypeError:
+            eps = importlib.metadata.entry_points().get(group, [])
+        if hasattr(eps, "select"):  # Python 3.10+
+            eps = list(eps.select(name=name))
+        else:
+            eps = [e for e in eps if e.name == name]
+        for ep in eps:
+            try:
+                ep.load()()
+            except ImportError as e:
+                if "elasticsearch" in str(e).lower() or "elasticsearch" in str(e):
+                    raise ImportError(
+                        f"Elasticsearch backend requires the 'elastic' extra. "
+                        f"Install with: pip install cuvs-bench[elastic]"
+                    ) from e
+                raise
+            return  # Plugin loaded successfully
+
+
 def get_backend_class(name: str) -> Type[BenchmarkBackend]:
     """
     Get the backend class (not instance) from the global registry.
 
+    If the backend is not registered, attempts to load it from entry points
+    (e.g., optional plugins like elastic).
+
     Parameters
     ----------
     name : str
@@ -390,10 +428,15 @@ def get_backend_class(name: str) -> Type[BenchmarkBackend]:
         Backend class
     """
     registry = get_registry()
+    if name not in registry._backends:
+        _try_load_plugin(name)
     if name not in registry._backends:
         available = ", ".join(registry._backends.keys())
+        hint = ""
+        if name == "elastic":
+            hint = " Install with: pip install cuvs-bench[elastic]"
         raise ValueError(
-            f"Backend '{name}' not found. Available backends: {available or '(none)'}"
+            f"Backend '{name}' not found. Available backends: {available or '(none)'}.{hint}"
         )
     return registry._backends[name]
 
@@ -440,6 +483,9 @@ def get_config_loader(name: str) -> Type:
     """
     Get a registered config loader class by name.
 
+    If the config loader is not registered, attempts to load it from entry points
+    (e.g., optional plugins like elastic).
+
     Parameters
     ----------
     name : str
@@ -455,15 +501,32 @@ def get_config_loader(name: str) -> Type:
     ValueError
         If config loader is not registered
     """
-    # _CONFIG_LOADER_REGISTRY is a dictionary that maps backend names to config loader classes
+    if name not in _CONFIG_LOADER_REGISTRY:
+        _try_load_plugin(name)
     if name not in _CONFIG_LOADER_REGISTRY:
         available = ", ".join(_CONFIG_LOADER_REGISTRY.keys()) or "none"
+        hint = ""
+        if name == "elastic":
+            hint = " Install with: pip install cuvs-bench[elastic]"
         raise ValueError(
-            f"Unknown config loader for backend: '{name}'. Available: {available}"
+            f"Unknown config loader for backend: '{name}'. Available: {available}.{hint}"
         )
     return _CONFIG_LOADER_REGISTRY[name]
 
 
 def list_config_loaders() -> Dict[str, Type]:
     """Return all registered config loaders."""
     return dict(_CONFIG_LOADER_REGISTRY)
+
+
+def unregister_config_loader(name: str) -> None:
+    """
+    Unregister a config loader by name (primarily for testing).
+
+    Parameters
+    ----------
+    name : str
+        Backend name to unregister
+    """
+    if name in _CONFIG_LOADER_REGISTRY:
+        del _CONFIG_LOADER_REGISTRY[name]

python/cuvs_bench/cuvs_bench/backends/search_spaces.py

@@ -158,6 +158,46 @@
             "ef": {"type": "int", "min": 10, "max": 1000},
         },
     },
+    # =========================================================================
+    # Elasticsearch GPU HNSW (hnsw, int8_hnsw, int4_hnsw, bbq_hnsw)
+    # Per ES-GPU-API-REFERENCE.md: index_options (m, ef_construction), knn (num_candidates)
+    # =========================================================================
+    "elastic_hnsw": {
+        "build": {
+            "m": {"type": "int", "min": 8, "max": 64},
+            "ef_construction": {"type": "int", "min": 50, "max": 500},
+        },
+        "search": {
+            "num_candidates": {"type": "int", "min": 50, "max": 500},
+        },
+    },
+    "elastic_int8_hnsw": {
+        "build": {
+            "m": {"type": "int", "min": 8, "max": 64},
+            "ef_construction": {"type": "int", "min": 50, "max": 500},
+        },
+        "search": {
+            "num_candidates": {"type": "int", "min": 50, "max": 500},
+        },
+    },
+    "elastic_int4_hnsw": {
+        "build": {
+            "m": {"type": "int", "min": 8, "max": 64},
+            "ef_construction": {"type": "int", "min": 50, "max": 500},
+        },
+        "search": {
+            "num_candidates": {"type": "int", "min": 50, "max": 500},
+        },
+    },
+    "elastic_bbq_hnsw": {
+        "build": {
+            "m": {"type": "int", "min": 8, "max": 64},
+            "ef_construction": {"type": "int", "min": 50, "max": 500},
+        },
+        "search": {
+            "num_candidates": {"type": "int", "min": 50, "max": 500},
+        },
+    },
 }
 
 

python/cuvs_bench/cuvs_bench/tests/conftest.py

@@ -0,0 +1,23 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+#
+"""Pytest configuration for cuvs_bench tests."""
+
+
+def pytest_configure(config):
+    """Register elastic plugin when elasticsearch is available.
+
+    Ensures elastic tests run when elasticsearch is installed, even if
+    cuvs-bench-elastic was not installed via pip (e.g. using PYTHONPATH).
+    """
+    try:
+        import elasticsearch  # noqa: F401
+    except ImportError:
+        return
+
+    try:
+        from cuvs_bench_elastic import register
+        register()
+    except ImportError:
+        pass

python/cuvs_bench/cuvs_bench/tests/integration/README.md

@@ -0,0 +1,34 @@
+# Integration Tests
+
+Integration tests run against real services (e.g. Elasticsearch in Docker).
+
+**Note:** The Elasticsearch integration test is currently disabled. It targets the
+Elasticsearch GPU backend (cuVS-accelerated), which requires an ES GPU image,
+cuVS libs from this repo, and a GPU-enabled runner. See `test_elastic_integration.py`
+module docstring for details. Can be re-enabled when CI has these dependencies.
+
+## Requirements
+
+- **Docker** running locally
+- Optional dependencies:
+
+  ```bash
+  pip install cuvs-bench[elastic,integration]
+  ```
+
+  Or install separately:
+
+  ```bash
+  pip install cuvs-bench[elastic]
+  pip install testcontainers[elasticsearch]
+  ```
+
+## Running
+
+```bash
+# From repo root
+PYTHONPATH="python/cuvs_bench:python/cuvs_bench_elastic:$PYTHONPATH" \
+  pytest python/cuvs_bench/cuvs_bench/tests/integration/ -v
+```
+
+Integration tests are skipped automatically if `testcontainers` or `elasticsearch` is not installed.

python/cuvs_bench/cuvs_bench/tests/integration/__init__.py

@@ -0,0 +1,9 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+#
+"""Integration tests for cuvs-bench backends.
+
+These tests require Docker and optional dependencies:
+    pip install cuvs-bench[elastic,integration]
+"""

python/cuvs_bench/cuvs_bench/tests/integration/conftest.py

@@ -0,0 +1,73 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
+# SPDX-License-Identifier: Apache-2.0
+#
+"""Pytest fixtures for integration tests.
+
+Requires: pip install cuvs-bench[elastic,integration]
+Requires: Docker running locally
+"""
+
+import pytest
+
+
+def _testcontainers_available():
+    try:
+        from testcontainers.elasticsearch import ElasticSearchContainer
+        return True
+    except ImportError:
+        return False
+
+
+def _elasticsearch_installed():
+    try:
+        import elasticsearch  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+@pytest.fixture(scope="module")
+def elasticsearch_container():
+    """Start an Elasticsearch container for the duration of the test module.
+
+    Yields a dict with host, port, and get_url() for connecting.
+    Skips the test module if testcontainers or elasticsearch is not installed.
+    """
+    if not _testcontainers_available():
+        pytest.skip(
+            "Requires testcontainers[elasticsearch]. "
+            "Install with: pip install cuvs-bench[integration]"
+        )
+    if not _elasticsearch_installed():
+        pytest.skip(
+            "Requires elasticsearch. Install with: pip install cuvs-bench[elastic]"
+        )
+
+    from testcontainers.elasticsearch import ElasticSearchContainer
+
+    # Use standard ES OSS image (no GPU in OSS; use use_gpu=False in tests)
+    with ElasticSearchContainer(
+        image="elasticsearch:8.15.0",
+        mem_limit="2g",
+    ) as container:
+        url = container.get_url()
+        # Parse host:port from URL (e.g. http://localhost:32768)
+        if url.startswith("http://"):
+            rest = url[7:]
+        elif url.startswith("https://"):
+            rest = url[8:]
+        else:
+            rest = url
+        if "/" in rest:
+            host_port = rest.split("/")[0]
+        else:
+            host_port = rest
+        if ":" in host_port:
+            host, port_str = host_port.rsplit(":", 1)
+            port = int(port_str)
+        else:
+            host = host_port
+            port = 9200
+
+        yield {"host": host, "port": port, "url": url}