vicinity 0.3.1__tar.gz → 0.3.2__tar.gz

{vicinity-0.3.1 → vicinity-0.3.2}/Makefile

@@ -9,7 +9,7 @@ install: venv
 	uv run pre-commit install
 
 install-no-pre-commit:
-	uv pip install ".[dev,hnsw,pynndescent,annoy,faiss,usearch]"
+	uv pip install ".[dev,all]"
 
 install-base:
 	uv sync --extra dev

{vicinity-0.3.1 → vicinity-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vicinity
-Version: 0.3.1
+Version: 0.3.2
 Summary: Lightweight Nearest Neighbors with Flexible Backends
 Author-email: Stéphan Tulkens <stephantul@gmail.com>, Thomas van Dongen <thomas123@live.nl>
 License: MIT License
@@ -67,6 +67,8 @@ Provides-Extra: faiss
 Requires-Dist: faiss-cpu; extra == "faiss"
 Provides-Extra: usearch
 Requires-Dist: usearch; extra == "usearch"
+Provides-Extra: voyager
+Requires-Dist: voyager; extra == "voyager"
 Provides-Extra: all
 Requires-Dist: hnswlib; extra == "all"
 Requires-Dist: pynndescent>=0.5.10; extra == "all"
@@ -76,13 +78,19 @@ Requires-Dist: numpy>=1.24.0; extra == "all"
 Requires-Dist: annoy; extra == "all"
 Requires-Dist: faiss-cpu; extra == "all"
 Requires-Dist: usearch; extra == "all"
+Requires-Dist: voyager; extra == "all"
 
-<div align="center">
-
-# Vicinity: Lightweight Nearest Neighbors
 
+<div align="center">
+    <picture>
+      <img width="40%" alt="Model2Vec logo" src="assets/images/vicinity_logo.png">
+    </picture>
+  </a>
 </div>
 
+<div align="center">
+  <h2>Lightweight Nearest Neighbors with Flexible Backends</h2>
+</div>
 
 <div align="center">
   <h2>
@@ -118,7 +126,7 @@ Install the package with:
 ```bash
 pip install vicinity
 ```
-Optinally, [install any of the supported backends](#installation), or simply install all of them with:
+Optionally, [install any of the supported backends](#installation), or simply install all of them with:
 ```bash
 pip install vicinity[all]
 ```
@@ -134,7 +142,12 @@ items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
 vectors = np.random.rand(len(items), 128)
 
 # Initialize the Vicinity instance (using the basic backend and cosine metric)
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items, backend_type=Backend.BASIC, metric=Metric.COSINE)
+vicinity = Vicinity.from_vectors_and_items(
+    vectors=vectors,
+    items=items,
+    backend_type=Backend.BASIC,
+    metric=Metric.COSINE
+)
 
 # Create a query vector
 query_vector = np.random.rand(128)
@@ -189,7 +202,7 @@ The following backends are supported:
   - `ivf_scalar`: Inverted file search with scalar quantizer.
   - `ivfpq`: Inverted file search with product quantizer.
   - `ivfpqr`: Inverted file search with product quantizer and refinement.
-
+- [VOYAGER](https://github.com/spotify/voyager): Voyager is a library for performing fast approximate nearest-neighbor searches on an in-memory collection of vectors.
 
 
 
@@ -200,7 +213,7 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 
 | Backend         | Parameter           | Description                                                                                   | Default Value       |
 |-----------------|---------------------|-----------------------------------------------------------------------------------------------|---------------------|
-| **Annoy**       | `metric`            | Similarity metric to use (`dot`, `euclidean`, `cosine`).                                      | `"cosine"`          |
+| **ANNOY**       | `metric`            | Similarity metric to use (`dot`, `euclidean`, `cosine`).                                      | `"cosine"`          |
 |                 | `trees`             | Number of trees to use for indexing.                                                          | `100`               |
 |                 | `length`            | Optional length of the dataset.                                                               | `None`              |
 | **FAISS**       | `metric`            | Similarity metric to use (`cosine`, `l2`).                                                    | `"cosine"`          |
@@ -212,13 +225,15 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 | **HNSW**        | `metric`            | Similarity space to use (`cosine`, `l2`).                                                     | `"cosine"`          |
 |                 | `ef_construction`   | Size of the dynamic list during index construction.                                           | `200`               |
 |                 | `m`                 | Number of connections per layer.                                                              | `16`                |
-| **PyNNDescent** | `metric`            | Similarity metric to use (`cosine`, `euclidean`, `manhattan`).                                | `"cosine"`          |
+| **PYNNDESCENT** | `metric`            | Similarity metric to use (`cosine`, `euclidean`, `manhattan`).                                | `"cosine"`          |
 |                 | `n_neighbors`       | Number of neighbors to use for search.                                                        | `15`                |
-| **Usearch**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`).                        | `"cos"`             |
+| **USEARCH**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`).                        | `"cos"`             |
 |                 | `connectivity`      | Number of connections per node in the graph.                                                  | `16`                |
 |                 | `expansion_add`     | Number of candidates considered during graph construction.                                    | `128`               |
 |                 | `expansion_search`  | Number of candidates considered during search.                                                | `64`                |
-
+| **VOYAGER**        | `metric`            | Similarity space to use (`cosine`, `l2`).                                                     | `"cosine"`          |
+|                 | `ef_construction`   | The number of vectors that this index searches through when inserting a new vector into the index.                                           | `200`               |
+|                 | `m`                 | The number of connections between nodes in the tree’s internal data structure.                                                              | `16`                |
 
 ## Installation
 The following installation options are available:
@@ -235,6 +250,7 @@ pip install vicinity[faiss]
 pip install vicinity[hnsw]
 pip install vicinity[pynndescent]
 pip install vicinity[usearch]
+pip install vicinity[voyager]
 ```
 
 ## License

{vicinity-0.3.1 → vicinity-0.3.2}/README.md

@@ -1,9 +1,14 @@
-<div align="center">
-
-# Vicinity: Lightweight Nearest Neighbors
 
+<div align="center">
+    <picture>
+      <img width="40%" alt="Model2Vec logo" src="assets/images/vicinity_logo.png">
+    </picture>
+  </a>
 </div>
 
+<div align="center">
+  <h2>Lightweight Nearest Neighbors with Flexible Backends</h2>
+</div>
 
 <div align="center">
   <h2>
@@ -39,7 +44,7 @@ Install the package with:
 ```bash
 pip install vicinity
 ```
-Optinally, [install any of the supported backends](#installation), or simply install all of them with:
+Optionally, [install any of the supported backends](#installation), or simply install all of them with:
 ```bash
 pip install vicinity[all]
 ```
@@ -55,7 +60,12 @@ items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
 vectors = np.random.rand(len(items), 128)
 
 # Initialize the Vicinity instance (using the basic backend and cosine metric)
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items, backend_type=Backend.BASIC, metric=Metric.COSINE)
+vicinity = Vicinity.from_vectors_and_items(
+    vectors=vectors,
+    items=items,
+    backend_type=Backend.BASIC,
+    metric=Metric.COSINE
+)
 
 # Create a query vector
 query_vector = np.random.rand(128)
@@ -110,7 +120,7 @@ The following backends are supported:
   - `ivf_scalar`: Inverted file search with scalar quantizer.
   - `ivfpq`: Inverted file search with product quantizer.
   - `ivfpqr`: Inverted file search with product quantizer and refinement.
-
+- [VOYAGER](https://github.com/spotify/voyager): Voyager is a library for performing fast approximate nearest-neighbor searches on an in-memory collection of vectors.
 
 
 
@@ -121,7 +131,7 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 
 | Backend         | Parameter           | Description                                                                                   | Default Value       |
 |-----------------|---------------------|-----------------------------------------------------------------------------------------------|---------------------|
-| **Annoy**       | `metric`            | Similarity metric to use (`dot`, `euclidean`, `cosine`).                                      | `"cosine"`          |
+| **ANNOY**       | `metric`            | Similarity metric to use (`dot`, `euclidean`, `cosine`).                                      | `"cosine"`          |
 |                 | `trees`             | Number of trees to use for indexing.                                                          | `100`               |
 |                 | `length`            | Optional length of the dataset.                                                               | `None`              |
 | **FAISS**       | `metric`            | Similarity metric to use (`cosine`, `l2`).                                                    | `"cosine"`          |
@@ -133,13 +143,15 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 | **HNSW**        | `metric`            | Similarity space to use (`cosine`, `l2`).                                                     | `"cosine"`          |
 |                 | `ef_construction`   | Size of the dynamic list during index construction.                                           | `200`               |
 |                 | `m`                 | Number of connections per layer.                                                              | `16`                |
-| **PyNNDescent** | `metric`            | Similarity metric to use (`cosine`, `euclidean`, `manhattan`).                                | `"cosine"`          |
+| **PYNNDESCENT** | `metric`            | Similarity metric to use (`cosine`, `euclidean`, `manhattan`).                                | `"cosine"`          |
 |                 | `n_neighbors`       | Number of neighbors to use for search.                                                        | `15`                |
-| **Usearch**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`).                        | `"cos"`             |
+| **USEARCH**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`).                        | `"cos"`             |
 |                 | `connectivity`      | Number of connections per node in the graph.                                                  | `16`                |
 |                 | `expansion_add`     | Number of candidates considered during graph construction.                                    | `128`               |
 |                 | `expansion_search`  | Number of candidates considered during search.                                                | `64`                |
-
+| **VOYAGER**        | `metric`            | Similarity space to use (`cosine`, `l2`).                                                     | `"cosine"`          |
+|                 | `ef_construction`   | The number of vectors that this index searches through when inserting a new vector into the index.                                           | `200`               |
+|                 | `m`                 | The number of connections between nodes in the tree’s internal data structure.                                                              | `16`                |
 
 ## Installation
 The following installation options are available:
@@ -156,6 +168,7 @@ pip install vicinity[faiss]
 pip install vicinity[hnsw]
 pip install vicinity[pynndescent]
 pip install vicinity[usearch]
+pip install vicinity[voyager]
 ```
 
 ## License

{vicinity-0.3.1 → vicinity-0.3.2}/pyproject.toml

@@ -52,6 +52,7 @@ pynndescent = [
 annoy = ["annoy"]
 faiss = ["faiss-cpu"]
 usearch = ["usearch"]
+voyager = ["voyager"]
 all = [
     "hnswlib",
     "pynndescent>=0.5.10",
@@ -60,7 +61,8 @@ all = [
     "numpy>=1.24.0",
     "annoy",
     "faiss-cpu",
-    "usearch"
+    "usearch",
+    "voyager"
 ]
 
 [project.urls]
@@ -87,6 +89,7 @@ select = [
     "NPY",
     # Print: Forbid print statements
     "T20",
+    "F",
 ]
 ignore = [
     # Allow self and cls to be untyped, and allow Any type

{vicinity-0.3.1 → vicinity-0.3.2}/tests/conftest.py

@@ -8,7 +8,17 @@ from vicinity.datatypes import Backend
 
 random_gen = np.random.default_rng(42)
 
-_faiss_index_types = ["flat", "ivf", "hnsw", "lsh", "scalar", "pq", "ivf_scalar", "ivfpq", "ivfpqr"]
+_faiss_index_types = [
+    "flat",
+    "ivf",
+    "hnsw",
+    "lsh",
+    "scalar",
+    "pq",
+    "ivf_scalar",
+    "ivfpq",
+    "ivfpqr",
+]
 
 
 @pytest.fixture(scope="session")
@@ -35,6 +45,7 @@ BACKEND_PARAMS = [(Backend.FAISS, index_type) for index_type in _faiss_index_typ
     (Backend.ANNOY, None),
     (Backend.PYNNDESCENT, None),
     (Backend.USEARCH, None),
+    (Backend.VOYAGER, None),
 ]
 
 
@@ -57,11 +68,48 @@ def vicinity_instance(request: pytest.FixtureRequest, items: list[str], vectors:
         if index_type in ("pq", "ivfpq", "ivfpqr"):
             # Use smaller values for pq indexes since the dataset is small
             return Vicinity.from_vectors_and_items(
-                vectors, items, backend_type=backend_type, index_type=index_type, m=2, nbits=4
+                vectors,
+                items,
+                backend_type=backend_type,
+                index_type=index_type,
+                m=2,
+                nbits=4,
             )
         else:
             return Vicinity.from_vectors_and_items(
-                vectors, items, backend_type=backend_type, index_type=index_type, nlist=2, nbits=32
+                vectors,
+                items,
+                backend_type=backend_type,
+                index_type=index_type,
+                nlist=2,
+                nbits=32,
             )
 
     return Vicinity.from_vectors_and_items(vectors, items, backend_type=backend_type)
+
+
+@pytest.fixture(params=BACKEND_PARAMS, ids=BACKEND_IDS)
+def vicinity_instance_with_stored_vectors(
+    request: pytest.FixtureRequest, items: list[str], vectors: np.ndarray
+) -> Vicinity:
+    """Fixture providing a Vicinity instance for each backend type."""
+    backend_type, index_type = request.param
+    # Handle FAISS backend with specific FAISS index types
+    if backend_type == Backend.FAISS:
+        if index_type in ("pq", "ivfpq", "ivfpqr"):
+            # Use smaller values for pq indexes since the dataset is small
+            return Vicinity.from_vectors_and_items(
+                vectors, items, backend_type=backend_type, index_type=index_type, m=2, nbits=4, store_vectors=True
+            )
+        else:
+            return Vicinity.from_vectors_and_items(
+                vectors, items, backend_type=backend_type, index_type=index_type, nlist=2, nbits=32, store_vectors=True
+            )
+
+    return Vicinity.from_vectors_and_items(vectors, items, backend_type=backend_type, store_vectors=True)
+
+
+@pytest.fixture()
+def vicinity_with_basic_backend(vectors: np.ndarray, items: list[str]) -> Vicinity:
+    """Fixture providing a BasicBackend instance."""
+    return Vicinity.from_vectors_and_items(vectors, items, backend_type=Backend.BASIC, store_vectors=True)

{vicinity-0.3.1 → vicinity-0.3.2}/tests/test_vicinity.py

@@ -131,8 +131,48 @@ def test_vicinity_save_and_load(tmp_path: Path, vicinity_instance: Vicinity) ->
     """
     save_path = tmp_path / "vicinity_data"
     vicinity_instance.save(save_path)
+    assert vicinity_instance.vector_store is None
 
-    Vicinity.load(save_path)
+    v = Vicinity.load(save_path)
+    assert v.vector_store is None
+
+
+def test_vicinity_save_and_load_vector_store(tmp_path: Path, vicinity_instance_with_stored_vectors: Vicinity) -> None:
+    """
+    Test Vicinity.save and Vicinity.load.
+
+    :param tmp_path: Temporary directory provided by pytest.
+    :param vicinity_instance: A Vicinity instance.
+    """
+    save_path = tmp_path / "vicinity_data"
+    vicinity_instance_with_stored_vectors.save(save_path)
+
+    assert (save_path / "store").exists()
+    assert (save_path / "store" / "vectors.npy").exists()
+
+    v = Vicinity.load(save_path)
+    assert v.vector_store is not None
+
+
+def test_index_vector_store(vicinity_with_basic_backend: Vicinity, vectors: np.ndarray) -> None:
+    """
+    Index vectors in the Vicinity instance.
+
+    :param vicinity_instance: A Vicinity instance.
+    :param vectors: Array of vectors to index.
+    """
+    v = vicinity_with_basic_backend.get_vector_by_index(0)
+    assert np.allclose(v, vectors[0])
+
+    idx = [0, 1, 2, 3, 4, 10]
+    v = vicinity_with_basic_backend.get_vector_by_index(idx)
+    assert np.allclose(v, vectors[idx])
+
+    with pytest.raises(ValueError):
+        vicinity_with_basic_backend.get_vector_by_index([10_000])
+
+    with pytest.raises(ValueError):
+        vicinity_with_basic_backend.get_vector_by_index([-1])
 
 
 def test_vicinity_insert_duplicate(vicinity_instance: Vicinity, query_vector: np.ndarray) -> None:

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/__init__.py

@@ -1,7 +1,7 @@
 from typing import Union
 
 from vicinity.backends.base import AbstractBackend
-from vicinity.backends.basic import BasicBackend
+from vicinity.backends.basic import BasicBackend, BasicVectorStore
 from vicinity.datatypes import Backend
 
 
@@ -33,5 +33,10 @@ def get_backend_class(backend: Union[Backend, str]) -> type[AbstractBackend]:
 
         return UsearchBackend
 
+    elif backend == Backend.VOYAGER:
+        from vicinity.backends.voyager import VoyagerBackend
 
-__all__ = ["get_backend_class", "AbstractBackend"]
+        return VoyagerBackend
+
+
+__all__ = ["get_backend_class", "AbstractBackend", "BasicVectorStore"]

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/annoy.py

@@ -16,18 +16,18 @@ from vicinity.utils import Metric, normalize
 @dataclass
 class AnnoyArgs(BaseArgs):
     dim: int = 0
-    metric: str = "cosine"
+    metric: Metric = Metric.COSINE
+    internal_metric: str = "dot"
     trees: int = 100
     length: int | None = None
 
 
 class AnnoyBackend(AbstractBackend[AnnoyArgs]):
     argument_class = AnnoyArgs
-    supported_metrics = {Metric.COSINE, Metric.EUCLIDEAN, Metric.INNER_PRODUCT}
-    inverse_metric_mapping = {
+    supported_metrics = {Metric.COSINE, Metric.EUCLIDEAN}
+    inverse_metric_mapping: dict[Metric, str] = {
         Metric.COSINE: "dot",
         Metric.EUCLIDEAN: "euclidean",
-        Metric.INNER_PRODUCT: "dot",
     }
 
     def __init__(
@@ -56,18 +56,18 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
         if metric_enum not in cls.supported_metrics:
             raise ValueError(f"Metric '{metric_enum.value}' is not supported by AnnoyBackend.")
 
-        metric = cls._map_metric_to_string(metric_enum)
+        internal_metric = cls._map_metric_to_string(metric_enum)
 
-        if metric == "dot":
+        if metric_enum == Metric.COSINE:
             vectors = normalize(vectors)
 
         dim = vectors.shape[1]
-        index = AnnoyIndex(f=dim, metric=metric)  # type: ignore
+        index = AnnoyIndex(f=dim, metric=internal_metric)  # type: ignore
         for i, vector in enumerate(vectors):
             index.add_item(i, vector)
         index.build(trees)
 
-        arguments = AnnoyArgs(dim=dim, metric=metric, trees=trees, length=len(vectors))  # type: ignore
+        arguments = AnnoyArgs(dim=dim, metric=metric, trees=trees, length=len(vectors), internal_metric=internal_metric)  # type: ignore
         return AnnoyBackend(index, arguments=arguments)
 
     @property
@@ -88,8 +88,10 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
     def load(cls: type[AnnoyBackend], base_path: Path) -> AnnoyBackend:
         """Load the vectors from a path."""
         path = Path(base_path) / "index.bin"
+
         arguments = AnnoyArgs.load(base_path / "arguments.json")
-        index = AnnoyIndex(arguments.dim, arguments.metric)  # type: ignore
+        metric = cls._map_metric_to_string(arguments.metric)
+        index = AnnoyIndex(arguments.dim, metric)  # type: ignore
         index.load(str(path))
 
         return cls(index, arguments=arguments)
@@ -106,11 +108,11 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
         """Query the backend."""
         out = []
         for vec in vectors:
-            if self.arguments.metric == "dot":
+            if self.arguments.metric == Metric.COSINE:
                 vec = normalize(vec)
             indices, scores = self.index.get_nns_by_vector(vec, k, include_distances=True)
             scores_array = np.asarray(scores)
-            if self.arguments.metric == "dot":
+            if self.arguments.metric == Metric.COSINE:
                 # Convert cosine similarity to cosine distance
                 scores_array = 1 - scores_array
             out.append((np.asarray(indices), scores_array))

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/base.py

@@ -14,19 +14,25 @@ from vicinity.datatypes import Backend, QueryResult
 
 @dataclass
 class BaseArgs:
+    metric: Metric
+
     def dump(self, file: Path) -> None:
         """Dump the arguments to a file."""
         with open(file, "w") as f:
-            json.dump(asdict(self), f)
+            d = self.dict()
+            d["metric"] = d["metric"].value
+            json.dump(d, f)
 
     @classmethod
     def load(cls: type[ArgType], file: Path) -> ArgType:
         """Load the arguments from a file."""
         with open(file, "r") as f:
-            return cls(**json.load(f))
+            data = json.load(f)
+            data["metric"] = Metric.from_string(data["metric"])
+            return cls(**data)
 
     def dict(self) -> dict[str, Any]:
-        """Dump the arguments to a string."""
+        """Dump the arguments to a dict."""
         return asdict(self)
 
 

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/basic.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal, Union
+from typing import Any, Union
 
 import numpy as np
 from numpy import typing as npt
@@ -15,26 +15,61 @@ from vicinity.utils import Metric, normalize, normalize_or_copy
 
 @dataclass
 class BasicArgs(BaseArgs):
-    metric: str = "cosine"
+    metric: Metric = Metric.COSINE
 
 
-class BasicBackend(AbstractBackend[BasicArgs], ABC):
-    argument_class = BasicArgs
-    _vectors: npt.NDArray
-    supported_metrics = {Metric.COSINE, Metric.EUCLIDEAN}
+class BasicVectorStore:
+    def __init__(self, *, vectors: npt.NDArray, **kwargs: Any) -> None:
+        """
+        A basic vector store that just stores vectors.
 
-    def __init__(self, arguments: BasicArgs) -> None:
-        """Initialize the backend."""
-        super().__init__(arguments)
+        Note that we use kwargs in order to use this class as a mixin.
 
-    def __len__(self) -> int:
-        """Get the number of vectors."""
-        return self.vectors.shape[0]
+        :param vectors: The vectors to store.
+        :param **kwargs: Additional arguments. These are passed on to the super class.
+        """
+        super().__init__(**kwargs)
+        self._vectors = vectors
 
-    @property
-    def backend_type(self) -> Backend:
-        """The type of the backend."""
-        return Backend.BASIC
+    def _update_precomputed_data(self) -> None:
+        """Update precomputed data based on the metric."""
+        # NOTE: this is a no-op in the base implementation.
+        return
+
+    def get_by_index(self, indices: list[int]) -> npt.NDArray:
+        """Get vectors by index."""
+        return self._vectors[indices]
+
+    def insert(self, vectors: npt.NDArray) -> None:
+        """Insert vectors into the vector space."""
+        self._vectors = np.vstack([self._vectors, vectors])
+        self._update_precomputed_data()
+
+    def delete(self, indices: list[int]) -> None:
+        """Deletes specific indices from the vector space."""
+        self._vectors = np.delete(self._vectors, indices, axis=0)
+        self._update_precomputed_data()
+
+    def save(self, folder: Path) -> None:
+        """Save the vectors to a path."""
+        path = folder / "vectors.npy"
+        with open(path, "wb") as f:
+            np.save(f, self._vectors)
+
+    @staticmethod
+    def _load_vectors(folder: Path) -> npt.NDArray:
+        """Load the vectors from a path."""
+        path = folder / "vectors.npy"
+        with open(path, "rb") as f:
+            vectors = np.load(f)
+
+        return vectors
+
+    @classmethod
+    def load(cls, folder: Path) -> BasicVectorStore:
+        """Load the vectors from a path."""
+        vectors = cls._load_vectors(folder)
+        return cls(vectors=vectors)
 
     @property
     def dim(self) -> int:
@@ -55,10 +90,24 @@ class BasicBackend(AbstractBackend[BasicArgs], ABC):
         self._vectors = matrix
         self._update_precomputed_data()
 
-    @abstractmethod
-    def _update_precomputed_data(self) -> None:
-        """Update precomputed data based on the metric."""
-        raise NotImplementedError()
+
+class BasicBackend(BasicVectorStore, AbstractBackend[BasicArgs], ABC):
+    argument_class = BasicArgs
+    _vectors: npt.NDArray
+    supported_metrics = {Metric.COSINE, Metric.EUCLIDEAN}
+
+    def __init__(self, vectors: npt.NDArray, arguments: BasicArgs) -> None:
+        """Initialize the backend."""
+        super().__init__(vectors=vectors, arguments=arguments)
+
+    def __len__(self) -> int:
+        """Get the number of vectors."""
+        return self.vectors.shape[0]
+
+    @property
+    def backend_type(self) -> Backend:
+        """The type of the backend."""
+        return Backend.BASIC
 
     @abstractmethod
     def _dist(self, x: npt.NDArray) -> npt.NDArray:
@@ -72,11 +121,10 @@ class BasicBackend(AbstractBackend[BasicArgs], ABC):
         if metric_enum not in cls.supported_metrics:
             raise ValueError(f"Metric '{metric_enum.value}' is not supported by BasicBackend.")
 
-        metric = metric_enum.value
-        arguments = BasicArgs(metric=metric)
-        if metric == "cosine":
+        arguments = BasicArgs(metric=metric_enum)
+        if metric_enum == Metric.COSINE:
             return CosineBasicBackend(vectors, arguments)
-        elif metric == "euclidean":
+        elif metric_enum == Metric.EUCLIDEAN:
             return EuclideanBasicBackend(vectors, arguments)
         else:
             raise ValueError(f"Unsupported metric: {metric}")
@@ -84,23 +132,19 @@ class BasicBackend(AbstractBackend[BasicArgs], ABC):
     @classmethod
     def load(cls, folder: Path) -> BasicBackend:
         """Load the vectors from a path."""
-        path = folder / "vectors.npy"
         arguments = BasicArgs.load(folder / "arguments.json")
-        with open(path, "rb") as f:
-            vectors = np.load(f)
-        if arguments.metric == "cosine":
+        vectors = cls._load_vectors(folder)
+        if arguments.metric == Metric.COSINE:
             return CosineBasicBackend(vectors, arguments)
-        elif arguments.metric == "euclidean":
+        elif arguments.metric == Metric.EUCLIDEAN:
             return EuclideanBasicBackend(vectors, arguments)
         else:
             raise ValueError(f"Unsupported metric: {arguments.metric}")
 
     def save(self, folder: Path) -> None:
         """Save the vectors to a path."""
-        path = folder / "vectors.npy"
+        super().save(folder)
         self.arguments.dump(folder / "arguments.json")
-        with open(path, "wb") as f:
-            np.save(f, self._vectors)
 
     def threshold(
         self,
@@ -161,26 +205,12 @@ class BasicBackend(AbstractBackend[BasicArgs], ABC):
 
         return out
 
-    def insert(self, vectors: npt.NDArray) -> None:
-        """Insert vectors into the vector space."""
-        self._vectors = np.vstack([self._vectors, vectors])
-        self._update_precomputed_data()
-
-    def delete(self, indices: list[int]) -> None:
-        """Deletes specific indices from the vector space."""
-        self._vectors = np.delete(self._vectors, indices, axis=0)
-        self._update_precomputed_data()
-
 
 class CosineBasicBackend(BasicBackend):
     def __init__(self, vectors: npt.NDArray, arguments: BasicArgs) -> None:
         """Initialize the cosine basic backend."""
-        super().__init__(arguments)
-        self._vectors = normalize_or_copy(vectors)
-
-    def _update_precomputed_data(self) -> None:
-        """Update precomputed data for cosine similarity."""
-        pass
+        super().__init__(vectors=vectors, arguments=arguments)
+        self._vectors = normalize_or_copy(self._vectors)
 
     def _dist(self, x: npt.NDArray) -> npt.NDArray:
         """Compute cosine distance."""
@@ -198,21 +228,12 @@ class CosineBasicBackend(BasicBackend):
 class EuclideanBasicBackend(BasicBackend):
     def __init__(self, vectors: npt.NDArray, arguments: BasicArgs) -> None:
         """Initialize the Euclidean basic backend."""
-        super().__init__(arguments)
-        self._vectors = vectors
-        self._squared_norm_vectors: npt.NDArray | None = None
-        self._update_precomputed_data()
+        super().__init__(vectors=vectors, arguments=arguments)
+        self.squared_norm_vectors = (self._vectors**2).sum(1)
 
     def _update_precomputed_data(self) -> None:
         """Update precomputed data for Euclidean distance."""
-        self._squared_norm_vectors = (self._vectors**2).sum(1)
-
-    @property
-    def squared_norm_vectors(self) -> npt.NDArray:
-        """Return squared norms of vectors."""
-        if self._squared_norm_vectors is None:
-            self._squared_norm_vectors = (self._vectors**2).sum(1)
-        return self._squared_norm_vectors
+        self.squared_norm_vectors = (self._vectors**2).sum(1)
 
     def _dist(self, x: npt.NDArray) -> npt.NDArray:
         """Compute Euclidean distance."""

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/faiss.py

@@ -6,7 +6,6 @@ from pathlib import Path
 from typing import Any, Union
 
 import faiss
-import numpy as np
 from numpy import typing as npt
 
 from vicinity.backends.base import AbstractBackend, BaseArgs
@@ -37,7 +36,7 @@ TRAINABLE_INDEXES = (
 class FaissArgs(BaseArgs):
     dim: int = 0
     index_type: str = "flat"
-    metric: str = "cosine"
+    metric: Metric = Metric.COSINE
     nlist: int = 100
     m: int = 8
     nbits: int = 8
@@ -123,7 +122,7 @@ class FaissBackend(AbstractBackend[FaissArgs]):
         arguments = FaissArgs(
             dim=dim,
             index_type=index_type,
-            metric=metric_enum.value,
+            metric=metric_enum,
             nlist=nlist,
             m=m,
             nbits=nbits,

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/hnsw.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal, Union
+from typing import Any, Union
 
 from hnswlib import Index as HnswIndex
 from numpy import typing as npt
@@ -15,7 +15,7 @@ from vicinity.utils import Metric
 @dataclass
 class HNSWArgs(BaseArgs):
     dim: int = 0
-    metric: str = "cosine"
+    metric: Metric = Metric.COSINE
     ef_construction: int = 200
     m: int = 16
 
@@ -58,7 +58,7 @@ class HNSWBackend(AbstractBackend[HNSWArgs]):
         index = HnswIndex(space=metric, dim=dim)
         index.init_index(max_elements=vectors.shape[0], ef_construction=ef_construction, M=m)
         index.add_items(vectors)
-        arguments = HNSWArgs(dim=dim, metric=metric, ef_construction=ef_construction, m=m)
+        arguments = HNSWArgs(dim=dim, metric=metric_enum, ef_construction=ef_construction, m=m)
         return HNSWBackend(index, arguments=arguments)
 
     @property
@@ -80,7 +80,8 @@ class HNSWBackend(AbstractBackend[HNSWArgs]):
         """Load the vectors from a path."""
         path = Path(base_path) / "index.bin"
         arguments = HNSWArgs.load(base_path / "arguments.json")
-        index = HnswIndex(space=arguments.metric, dim=arguments.dim)
+        mapped_metric = cls.inverse_metric_mapping[arguments.metric]
+        index = HnswIndex(space=mapped_metric, dim=arguments.dim)
         index.load_index(str(path))
         return cls(index, arguments=arguments)
 

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/pynndescent.py

@@ -16,7 +16,7 @@ from vicinity.utils import Metric, normalize_or_copy
 @dataclass
 class PyNNDescentArgs(BaseArgs):
     n_neighbors: int = 15
-    metric: str = "cosine"
+    metric: Metric = Metric.COSINE
 
 
 class PyNNDescentBackend(AbstractBackend[PyNNDescentArgs]):
@@ -49,7 +49,7 @@ class PyNNDescentBackend(AbstractBackend[PyNNDescentArgs]):
         metric = metric_enum.value
 
         index = NNDescent(vectors, n_neighbors=n_neighbors, metric=metric, **kwargs)
-        arguments = PyNNDescentArgs(n_neighbors=n_neighbors, metric=metric)
+        arguments = PyNNDescentArgs(n_neighbors=n_neighbors, metric=metric_enum)
         return cls(index=index, arguments=arguments)
 
     def __len__(self) -> int:
@@ -105,10 +105,7 @@ class PyNNDescentBackend(AbstractBackend[PyNNDescentArgs]):
         arguments = PyNNDescentArgs.load(base_path / "arguments.json")
         vectors = np.load(Path(base_path) / "vectors.npy")
 
-        metric_enum = Metric.from_string(arguments.metric)
-        pynndescent_metric = metric_enum.value
-
-        index = NNDescent(vectors, n_neighbors=arguments.n_neighbors, metric=pynndescent_metric)
+        index = NNDescent(vectors, n_neighbors=arguments.n_neighbors, metric=arguments.metric.value)
 
         # Load the neighbor graph if it was saved
         neighbor_graph_path = base_path / "neighbor_graph.npy"

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/backends/usearch.py

@@ -16,7 +16,7 @@ from vicinity.utils import Metric
 @dataclass
 class UsearchArgs(BaseArgs):
     dim: int = 0
-    metric: str = "cos"
+    metric: Metric = Metric.COSINE
     connectivity: int = 16
     expansion_add: int = 128
     expansion_search: int = 64
@@ -67,10 +67,10 @@ class UsearchBackend(AbstractBackend[UsearchArgs]):
             expansion_add=expansion_add,
             expansion_search=expansion_search,
         )
-        index.add(keys=None, vectors=vectors)  # type: ignore
+        index.add(keys=None, vectors=vectors)  # type: ignore  # None keys are allowed but not typed
         arguments = UsearchArgs(
             dim=dim,
-            metric=metric,
+            metric=metric_enum,
             connectivity=connectivity,
             expansion_add=expansion_add,
             expansion_search=expansion_search,
@@ -99,7 +99,7 @@ class UsearchBackend(AbstractBackend[UsearchArgs]):
 
         index = UsearchIndex(
             ndim=arguments.dim,
-            metric=arguments.metric,
+            metric=cls._map_metric_to_string(arguments.metric),
             connectivity=arguments.connectivity,
             expansion_add=arguments.expansion_add,
             expansion_search=arguments.expansion_search,
@@ -122,7 +122,7 @@ class UsearchBackend(AbstractBackend[UsearchArgs]):
 
     def insert(self, vectors: npt.NDArray) -> None:
         """Insert vectors into the backend."""
-        self.index.add(None, vectors)  # type: ignore
+        self.index.add(None, vectors)  # type: ignore  # None keys are allowed, but not typed.
 
     def delete(self, indices: list[int]) -> None:
         """Delete vectors from the index (not supported by Usearch)."""

vicinity-0.3.2/vicinity/backends/voyager.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Union
+
+from numpy import typing as npt
+from voyager import Index, Space
+
+from vicinity.backends.base import AbstractBackend, BaseArgs
+from vicinity.datatypes import Backend, QueryResult
+from vicinity.utils import Metric
+
+
+@dataclass
+class VoyagerArgs(BaseArgs):
+    dim: int = 0
+    metric: Metric = Metric.COSINE
+    ef_construction: int = 200
+    m: int = 16
+
+
+class VoyagerBackend(AbstractBackend[VoyagerArgs]):
+    argument_class = VoyagerArgs
+    supported_metrics = {Metric.COSINE, Metric.EUCLIDEAN}
+    _metric_to_space = {
+        Metric.COSINE: Space.Cosine,
+        Metric.EUCLIDEAN: Space.Euclidean,
+    }
+
+    def __init__(
+        self,
+        index: Index,
+        arguments: VoyagerArgs,
+    ) -> None:
+        """Initialize the backend using vectors."""
+        super().__init__(arguments)
+        self.index = index
+
+    @classmethod
+    def from_vectors(
+        cls: type[VoyagerBackend],
+        vectors: npt.NDArray,
+        metric: Union[str, Metric],
+        ef_construction: int,
+        m: int,
+        **kwargs: Any,
+    ) -> VoyagerBackend:
+        """Create a new instance from vectors."""
+        metric_enum = Metric.from_string(metric)
+
+        if metric_enum not in cls.supported_metrics:
+            raise ValueError(f"Metric '{metric_enum.value}' is not supported by VoyagerBackend.")
+
+        space = cls._metric_to_space[metric_enum]
+        dim = vectors.shape[1]
+        index = Index(
+            space=space,
+            num_dimensions=dim,
+            M=m,
+            ef_construction=ef_construction,
+        )
+        index.add_items(vectors)
+        return cls(
+            index,
+            VoyagerArgs(dim=dim, metric=metric_enum, ef_construction=ef_construction, m=m),
+        )
+
+    def query(self, query: npt.NDArray, k: int) -> QueryResult:
+        """Query the backend for the nearest neighbors."""
+        indices, distances = self.index.query(query, k)
+        return list(zip(indices, distances))
+
+    @classmethod
+    def load(cls: type[VoyagerBackend], base_path: Path) -> VoyagerBackend:
+        """Load the vectors from a path."""
+        path = Path(base_path) / "index.bin"
+        arguments = VoyagerArgs.load(base_path / "arguments.json")
+        index = Index.load(str(path))
+        return cls(index, arguments=arguments)
+
+    def save(self, base_path: Path) -> None:
+        """Save the vectors to a path."""
+        path = Path(base_path) / "index.bin"
+        self.index.save(str(path))
+        self.arguments.dump(base_path / "arguments.json")
+
+    def insert(self, vectors: npt.NDArray) -> None:
+        """Insert vectors into the backend."""
+        self.index.add_items(vectors)
+
+    def delete(self, indices: list[int]) -> None:
+        """Delete vectors from the backend."""
+        raise NotImplementedError("Deletion is not supported in Voyager backend.")
+
+    def threshold(self, vectors: npt.NDArray, threshold: float) -> list[npt.NDArray]:
+        """Threshold the backend."""
+        out: list[npt.NDArray] = []
+        for x, y in self.query(vectors, len(self)):
+            out.append(x[y < threshold])
+
+        return out
+
+    @property
+    def backend_type(self) -> Backend:
+        """The type of the backend."""
+        return Backend.VOYAGER
+
+    @property
+    def dim(self) -> int:
+        """Get the dimension of the space."""
+        return self.index.num_dimensions
+
+    def __len__(self) -> int:
+        """Get the number of vectors."""
+        return self.index.num_elements

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/datatypes.py

@@ -2,7 +2,6 @@ from enum import Enum
 from pathlib import Path
 from typing import Iterable, List, Tuple, Union
 
-import numpy as np
 from numpy import typing as npt
 
 PathLike = Union[str, Path]
@@ -22,3 +21,4 @@ class Backend(str, Enum):
     PYNNDESCENT = "pynndescent"
     FAISS = "faiss"
     USEARCH = "usearch"
+    VOYAGER = "voyager"

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/version.py

@@ -1,2 +1,2 @@
-__version_triple__ = (0, 3, 1)
+__version_triple__ = (0, 3, 2)
 __version__ = ".".join(map(str, __version_triple__))

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity/vicinity.py

@@ -3,18 +3,17 @@
 from __future__ import annotations
 
 import logging
-import time
 from io import open
 from pathlib import Path
 from time import perf_counter
-from typing import Any, Sequence, Union
+from typing import Any, Iterable, Sequence, Union
 
 import numpy as np
 import orjson
 from numpy import typing as npt
 
 from vicinity import Metric
-from vicinity.backends import AbstractBackend, BasicBackend, get_backend_class
+from vicinity.backends import AbstractBackend, BasicBackend, BasicVectorStore, get_backend_class
 from vicinity.datatypes import Backend, PathLike
 
 logger = logging.getLogger(__name__)
@@ -33,6 +32,7 @@ class Vicinity:
         items: Sequence[str],
         backend: AbstractBackend,
         metadata: Union[dict[str, Any], None] = None,
+        vector_store: BasicVectorStore | None = None,
     ) -> None:
         """
         Initialize a Vicinity instance with an array and list of items.
@@ -42,6 +42,7 @@ class Vicinity:
             aligned with the vectors.
         :param backend: The backend to use for the vector space.
         :param metadata: A dictionary containing metadata about the vector space.
+        :param vector_store: A simple vector store only used for storing actual vectors.
         :raises ValueError: If the length of the items and vectors are not the same.
         """
         if len(items) != len(backend):
@@ -51,6 +52,19 @@ class Vicinity:
         self.items: list[str] = list(items)
         self.backend: AbstractBackend = backend
         self.metadata = metadata or {}
+        self.vector_store = vector_store
+
+    def get_vector_by_index(self, index: int | Iterable[int]) -> npt.NDArray:
+        """Get a vector by index."""
+        if isinstance(index, int):
+            index = [index]
+        if not all(0 <= i < len(self.items) for i in index):
+            raise ValueError("Index out of bounds.")
+        if self.vector_store is None:
+            raise ValueError(
+                "No vector store was provided. To get items by index, create a vicinity index by passing store_vectors=True on index creation."
+            )
+        return self.vector_store.get_by_index(list(index))
 
     def __len__(self) -> int:
         """The number of the items in the vector space."""
@@ -62,6 +76,7 @@ class Vicinity:
         vectors: npt.NDArray,
         items: Sequence[str],
         backend_type: Backend | str = Backend.BASIC,
+        store_vectors: bool = False,
         **kwargs: Any,
     ) -> Vicinity:
         """
@@ -70,6 +85,7 @@ class Vicinity:
         :param vectors: The vectors to use.
         :param items: The items to use.
         :param backend_type: The type of backend to use.
+        :param store_vectors: Whether to store the raw vectors in the backend.
         :param **kwargs: Additional arguments to pass to the backend.
         :return: A Vicinity instance.
         """
@@ -77,8 +93,12 @@ class Vicinity:
         backend_cls = get_backend_class(backend_type)
         arguments = backend_cls.argument_class(**kwargs)
         backend = backend_cls.from_vectors(vectors, **arguments.dict())
+        if store_vectors:
+            vector_store = BasicVectorStore(vectors=vectors)
+        else:
+            vector_store = None
 
-        return cls(items, backend)
+        return cls(items, backend, vector_store=vector_store)
 
     @property
     def dim(self) -> int:
@@ -166,6 +186,10 @@ class Vicinity:
             file_handle.write(orjson.dumps(items_dict))
 
         self.backend.save(path)
+        if self.vector_store is not None:
+            store_path = path / "store"
+            store_path.mkdir(exist_ok=overwrite)
+            self.vector_store.save(store_path)
 
     @classmethod
     def load(cls, filename: PathLike) -> Vicinity:
@@ -190,8 +214,12 @@ class Vicinity:
 
         backend_cls: type[AbstractBackend] = get_backend_class(backend_type)
         backend = backend_cls.load(folder_path)
+        if Path(folder_path / "store").exists():
+            vector_store = BasicVectorStore.load(folder_path / "store")
+        else:
+            vector_store = None
 
-        instance = cls(items, backend, metadata=metadata)
+        instance = cls(items, backend, metadata=metadata, vector_store=vector_store)
 
         return instance
 

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vicinity
-Version: 0.3.1
+Version: 0.3.2
 Summary: Lightweight Nearest Neighbors with Flexible Backends
 Author-email: Stéphan Tulkens <stephantul@gmail.com>, Thomas van Dongen <thomas123@live.nl>
 License: MIT License
@@ -67,6 +67,8 @@ Provides-Extra: faiss
 Requires-Dist: faiss-cpu; extra == "faiss"
 Provides-Extra: usearch
 Requires-Dist: usearch; extra == "usearch"
+Provides-Extra: voyager
+Requires-Dist: voyager; extra == "voyager"
 Provides-Extra: all
 Requires-Dist: hnswlib; extra == "all"
 Requires-Dist: pynndescent>=0.5.10; extra == "all"
@@ -76,13 +78,19 @@ Requires-Dist: numpy>=1.24.0; extra == "all"
 Requires-Dist: annoy; extra == "all"
 Requires-Dist: faiss-cpu; extra == "all"
 Requires-Dist: usearch; extra == "all"
+Requires-Dist: voyager; extra == "all"
 
-<div align="center">
-
-# Vicinity: Lightweight Nearest Neighbors
 
+<div align="center">
+    <picture>
+      <img width="40%" alt="Model2Vec logo" src="assets/images/vicinity_logo.png">
+    </picture>
+  </a>
 </div>
 
+<div align="center">
+  <h2>Lightweight Nearest Neighbors with Flexible Backends</h2>
+</div>
 
 <div align="center">
   <h2>
@@ -118,7 +126,7 @@ Install the package with:
 ```bash
 pip install vicinity
 ```
-Optinally, [install any of the supported backends](#installation), or simply install all of them with:
+Optionally, [install any of the supported backends](#installation), or simply install all of them with:
 ```bash
 pip install vicinity[all]
 ```
@@ -134,7 +142,12 @@ items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
 vectors = np.random.rand(len(items), 128)
 
 # Initialize the Vicinity instance (using the basic backend and cosine metric)
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items, backend_type=Backend.BASIC, metric=Metric.COSINE)
+vicinity = Vicinity.from_vectors_and_items(
+    vectors=vectors,
+    items=items,
+    backend_type=Backend.BASIC,
+    metric=Metric.COSINE
+)
 
 # Create a query vector
 query_vector = np.random.rand(128)
@@ -189,7 +202,7 @@ The following backends are supported:
   - `ivf_scalar`: Inverted file search with scalar quantizer.
   - `ivfpq`: Inverted file search with product quantizer.
   - `ivfpqr`: Inverted file search with product quantizer and refinement.
-
+- [VOYAGER](https://github.com/spotify/voyager): Voyager is a library for performing fast approximate nearest-neighbor searches on an in-memory collection of vectors.
 
 
 
@@ -200,7 +213,7 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 
 | Backend         | Parameter           | Description                                                                                   | Default Value       |
 |-----------------|---------------------|-----------------------------------------------------------------------------------------------|---------------------|
-| **Annoy**       | `metric`            | Similarity metric to use (`dot`, `euclidean`, `cosine`).                                      | `"cosine"`          |
+| **ANNOY**       | `metric`            | Similarity metric to use (`dot`, `euclidean`, `cosine`).                                      | `"cosine"`          |
 |                 | `trees`             | Number of trees to use for indexing.                                                          | `100`               |
 |                 | `length`            | Optional length of the dataset.                                                               | `None`              |
 | **FAISS**       | `metric`            | Similarity metric to use (`cosine`, `l2`).                                                    | `"cosine"`          |
@@ -212,13 +225,15 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 | **HNSW**        | `metric`            | Similarity space to use (`cosine`, `l2`).                                                     | `"cosine"`          |
 |                 | `ef_construction`   | Size of the dynamic list during index construction.                                           | `200`               |
 |                 | `m`                 | Number of connections per layer.                                                              | `16`                |
-| **PyNNDescent** | `metric`            | Similarity metric to use (`cosine`, `euclidean`, `manhattan`).                                | `"cosine"`          |
+| **PYNNDESCENT** | `metric`            | Similarity metric to use (`cosine`, `euclidean`, `manhattan`).                                | `"cosine"`          |
 |                 | `n_neighbors`       | Number of neighbors to use for search.                                                        | `15`                |
-| **Usearch**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`).                        | `"cos"`             |
+| **USEARCH**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`).                        | `"cos"`             |
 |                 | `connectivity`      | Number of connections per node in the graph.                                                  | `16`                |
 |                 | `expansion_add`     | Number of candidates considered during graph construction.                                    | `128`               |
 |                 | `expansion_search`  | Number of candidates considered during search.                                                | `64`                |
-
+| **VOYAGER**        | `metric`            | Similarity space to use (`cosine`, `l2`).                                                     | `"cosine"`          |
+|                 | `ef_construction`   | The number of vectors that this index searches through when inserting a new vector into the index.                                           | `200`               |
+|                 | `m`                 | The number of connections between nodes in the tree’s internal data structure.                                                              | `16`                |
 
 ## Installation
 The following installation options are available:
@@ -235,6 +250,7 @@ pip install vicinity[faiss]
 pip install vicinity[hnsw]
 pip install vicinity[pynndescent]
 pip install vicinity[usearch]
+pip install vicinity[voyager]
 ```
 
 ## License

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ README.md
 pyproject.toml
 uv.lock
 .github/workflows/ci.yaml
+assets/images/vicinity_logo.png
 tests/conftest.py
 tests/test_utils.py
 tests/test_vicinity.py
@@ -27,4 +28,5 @@ vicinity/backends/basic.py
 vicinity/backends/faiss.py
 vicinity/backends/hnsw.py
 vicinity/backends/pynndescent.py
-vicinity/backends/usearch.py
+vicinity/backends/usearch.py
+vicinity/backends/voyager.py

{vicinity-0.3.1 → vicinity-0.3.2}/vicinity.egg-info/requires.txt

@@ -11,6 +11,7 @@ numpy>=1.24.0
 annoy
 faiss-cpu
 usearch
+voyager
 
 [annoy]
 annoy
@@ -39,3 +40,6 @@ numpy>=1.24.0
 
 [usearch]
 usearch
+
+[voyager]
+voyager