vicinity 0.3.1__tar.gz → 0.3.3__tar.gz

{vicinity-0.3.1 → vicinity-0.3.3}/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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vicinity
-Version: 0.3.1
+Version: 0.3.3
 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,16 +142,25 @@ 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)
 
 # Query for nearest neighbors with a top-k search
-results = vicinity.query([query_vector], k=3)
+results = vicinity.query(query_vector, k=3)
 
 # Query for nearest neighbors with a threshold search
-results = vicinity.query_threshold([query_vector], threshold=0.9)
+results = vicinity.query_threshold(query_vector, threshold=0.9)
+
+# Query with a list of query vectors
+query_vectors = np.random.rand(5, 128)
+results = vicinity.query(query_vectors, k=3)
 ```
 
 Saving and loading a vector store:
@@ -178,7 +195,7 @@ The following backends are supported:
 - [HNSW](https://github.com/nmslib/hnswlib): Hierarchical Navigable Small World Graph (HNSW) for ANN search using hnswlib.
 - [USEARCH](https://github.com/unum-cloud/usearch): ANN search using Usearch. This uses a highly optimized version of the HNSW algorithm.
 - [ANNOY](https://github.com/spotify/annoy): "Approximate Nearest Neighbors Oh Yeah" for approximate nearest neighbor search.
-- [PYNNDescent](https://github.com/lmcinnes/pynndescent): ANN search using PyNNDescent.
+- [PYNNDESCENT](https://github.com/lmcinnes/pynndescent): ANN search using PyNNDescent.
 - [FAISS](https://github.com/facebookresearch/faiss): All FAISS indexes are supported:
   - `flat`: Exact search.
   - `ivf`: Inverted file search.
@@ -189,7 +206,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 +217,8 @@ 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"`          |
+| **BASIC**       | `metric`            | Similarity metric to use (`cosine`, `euclidean`).                                             | `"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 +230,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 +255,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.3}/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,16 +60,25 @@ 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)
 
 # Query for nearest neighbors with a top-k search
-results = vicinity.query([query_vector], k=3)
+results = vicinity.query(query_vector, k=3)
 
 # Query for nearest neighbors with a threshold search
-results = vicinity.query_threshold([query_vector], threshold=0.9)
+results = vicinity.query_threshold(query_vector, threshold=0.9)
+
+# Query with a list of query vectors
+query_vectors = np.random.rand(5, 128)
+results = vicinity.query(query_vectors, k=3)
 ```
 
 Saving and loading a vector store:
@@ -99,7 +113,7 @@ The following backends are supported:
 - [HNSW](https://github.com/nmslib/hnswlib): Hierarchical Navigable Small World Graph (HNSW) for ANN search using hnswlib.
 - [USEARCH](https://github.com/unum-cloud/usearch): ANN search using Usearch. This uses a highly optimized version of the HNSW algorithm.
 - [ANNOY](https://github.com/spotify/annoy): "Approximate Nearest Neighbors Oh Yeah" for approximate nearest neighbor search.
-- [PYNNDescent](https://github.com/lmcinnes/pynndescent): ANN search using PyNNDescent.
+- [PYNNDESCENT](https://github.com/lmcinnes/pynndescent): ANN search using PyNNDescent.
 - [FAISS](https://github.com/facebookresearch/faiss): All FAISS indexes are supported:
   - `flat`: Exact search.
   - `ivf`: Inverted file search.
@@ -110,7 +124,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 +135,8 @@ 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"`          |
+| **BASIC**       | `metric`            | Similarity metric to use (`cosine`, `euclidean`).                                             | `"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 +148,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 +173,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.3}/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.3}/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_and_store(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.3}/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_and_store: 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_and_store.get_vector_by_index(0)
+    assert np.allclose(v, vectors[0])
+
+    idx = [0, 1, 2, 3, 4, 10]
+    v = vicinity_with_basic_backend_and_store.get_vector_by_index(idx)
+    assert np.allclose(v, vectors[idx])
+
+    with pytest.raises(ValueError):
+        vicinity_with_basic_backend_and_store.get_vector_by_index([10_000])
+
+    with pytest.raises(ValueError):
+        vicinity_with_basic_backend_and_store.get_vector_by_index([-1])
 
 
 def test_vicinity_insert_duplicate(vicinity_instance: Vicinity, query_vector: np.ndarray) -> None:
@@ -163,6 +203,35 @@ def test_vicinity_delete_nonexistent(vicinity_instance: Vicinity) -> None:
         vicinity_instance.delete(["item10002"])
 
 
+def test_vicinity_insert_with_store(vicinity_with_basic_backend_and_store: Vicinity) -> None:
+    """
+    Test that Vicinity.insert raises ValueError when trying to insert vectors into a Vicinity instance with stored vectors.
+
+    :param vicinity_with_basic_backend_and_store: A Vicinity instance with stored vectors.
+    """
+    new_item = ["item10002"]
+    new_vector = np.full((1, vicinity_with_basic_backend_and_store.dim), 0.5)
+
+    vicinity_with_basic_backend_and_store.insert(new_item, new_vector)
+    assert vicinity_with_basic_backend_and_store.vector_store is not None
+    assert len(vicinity_with_basic_backend_and_store) == len(vicinity_with_basic_backend_and_store.vector_store)
+
+
+def test_vicinity_delete_with_store(vicinity_with_basic_backend_and_store: Vicinity) -> None:
+    """
+    Test Vicinity.delete method by verifying that the vector for a deleted item is not returned in subsequent queries.
+
+    :param vicinity_with_basic_backend_and_store: A Vicinity instance.
+    """
+    assert vicinity_with_basic_backend_and_store.vector_store is not None
+    # Delete "item2" from the Vicinity instance
+    vicinity_with_basic_backend_and_store.delete(["item2"])
+
+    # Ensure "item2" is no longer in the items list
+    assert "item2" not in vicinity_with_basic_backend_and_store.items
+    assert len(vicinity_with_basic_backend_and_store) == len(vicinity_with_basic_backend_and_store.vector_store)
+
+
 def test_vicinity_insert_mismatched_lengths(vicinity_instance: Vicinity, query_vector: np.ndarray) -> None:
     """
     Test that Vicinity.insert raises ValueError when tokens and vectors lengths do not match.

{vicinity-0.3.1 → vicinity-0.3.3}/uv.lock

@@ -1087,7 +1087,7 @@ wheels = [
 
 [[package]]
 name = "vicinity"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "numpy" },
@@ -1105,6 +1105,7 @@ all = [
     { name = "numpy" },
     { name = "pynndescent" },
     { name = "usearch" },
+    { name = "voyager" },
 ]
 annoy = [
     { name = "annoy" },
@@ -1134,6 +1135,9 @@ pynndescent = [
 usearch = [
     { name = "usearch" },
 ]
+voyager = [
+    { name = "voyager" },
+]
 
 [package.metadata]
 requires-dist = [
@@ -1164,6 +1168,8 @@ requires-dist = [
     { name = "tqdm" },
     { name = "usearch", marker = "extra == 'all'" },
     { name = "usearch", marker = "extra == 'usearch'" },
+    { name = "voyager", marker = "extra == 'all'" },
+    { name = "voyager", marker = "extra == 'voyager'" },
 ]
 
 [[package]]
@@ -1180,6 +1186,40 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/ae/92/78324ff89391e00c8f4cf6b8526c41c6ef36b4ea2d2c132250b1a6fc2b8d/virtualenv-20.27.1-py3-none-any.whl", hash = "sha256:f11f1b8a29525562925f745563bfd48b189450f61fb34c4f9cc79dd5aa32a1f4", size = 3117838 },
 ]
 
+[[package]]
+name = "voyager"
+version = "2.0.9"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "numpy" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/79/d9/62399eb8a907da7f9eba0e2facf78925d54ba644a9be671cd98e7b4f547f/voyager-2.0.9-cp310-cp310-macosx_10_13_universal2.whl", hash = "sha256:f3cfe84666314daaf51836f77dabaafeb064bcbe5d9435d9c97886af19ae2876", size = 731200 },
+    { url = "https://files.pythonhosted.org/packages/51/70/0d90ebf90ca6fa415513b63925f4b21aeebd9f6400ecce5dffdb3743039f/voyager-2.0.9-cp310-cp310-macosx_10_13_x86_64.whl", hash = "sha256:956a60f864a586991cdde09373caf5630ab3319c47b6cdad4bf05ea8ba96a578", size = 377180 },
+    { url = "https://files.pythonhosted.org/packages/6e/af/76bb88b390bbf9c1dcbab90acd669168294c6d20b6a230b7333b432eee1b/voyager-2.0.9-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:56e6e7d6f1597207141d224d5420dc690ae27a2feb6c4164180cecc453cd5816", size = 356644 },
+    { url = "https://files.pythonhosted.org/packages/2b/b9/a514e2f88b7cdf35cb182064d5859258488cfe7e7b82bfff012d9cffd746/voyager-2.0.9-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7be032a8ae5447ce289f1c95f349e825e9d4edc915db7ea1b2c273940de2acbe", size = 4211154 },
+    { url = "https://files.pythonhosted.org/packages/db/95/1032e54e27eeac13f9affaf1fdeb834cc389f728316c9e7244c0e57c3e98/voyager-2.0.9-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ed85d23006f98091a137f637894560d1020ba25217b5332729417ac0a200b0bd", size = 4280843 },
+    { url = "https://files.pythonhosted.org/packages/2c/dc/395551a312110ad53cdac4f0126708d02c2d5c11c9f63ecf6a64985fab56/voyager-2.0.9-cp310-cp310-win_amd64.whl", hash = "sha256:053f22b23bd090f6376cf026c31653d3c040f9eaf0c6d1267e766a442a5b8ff8", size = 199722 },
+    { url = "https://files.pythonhosted.org/packages/c2/17/ace9aaf1e65553dae2ce3ba947e922e6bd16aa89abe558543471b5fe065c/voyager-2.0.9-cp311-cp311-macosx_10_13_universal2.whl", hash = "sha256:d270b29bafb5a133abd611a03b1b9ec7b03a44361966609abef72dde2518eb5e", size = 734474 },
+    { url = "https://files.pythonhosted.org/packages/3b/73/83d047ad7f6cb4fad426ed6f8b6c249c3ffecffa85ebb017e6d4e725aa0c/voyager-2.0.9-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:216c517dd66e0095f5f14277627a233c081797119028737f71168f094bacb9d0", size = 378460 },
+    { url = "https://files.pythonhosted.org/packages/92/3e/7648441cf72258fc2e5cb9be6f39890684f15a06f66db42f12a8041e4e30/voyager-2.0.9-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a2ea7f5e61bb7de06d0196b1fbd43826908c6f2811576c94d97e353e7b32cb78", size = 358415 },
+    { url = "https://files.pythonhosted.org/packages/42/02/0f7c5e4d9eaf83d932ab0c89e93117166575163f670a6200f55a56dae268/voyager-2.0.9-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4c451b25d449ac6923f7424a3255995f97263ed694fa873119703da01a09f6d7", size = 4237185 },
+    { url = "https://files.pythonhosted.org/packages/38/7c/47598f5630b97cf7cf8f29ac390b8beab24adeb3f322d004244660b96e8f/voyager-2.0.9-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ecd1e690a69a044b988fd102676bb8584ed423af4b7aa9e69349203690263aad", size = 4304425 },
+    { url = "https://files.pythonhosted.org/packages/1a/95/fa3f090d8e1bdbd8401e9944080f3c12d1e8f1385980da4151f6ab62a783/voyager-2.0.9-cp311-cp311-win_amd64.whl", hash = "sha256:5e1c264f4202b551ca8cb5a33d456f451c598ea7b9680134177dc5443819f328", size = 200738 },
+    { url = "https://files.pythonhosted.org/packages/22/fa/455fbd3a709403dd98f910b1ba5bfd9bf38db3e718edd03c8758ecb3b750/voyager-2.0.9-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:2d344617a1c97d6b317f13e801b3377a55f1e5b91786f9354dcde12b7945b3e0", size = 736030 },
+    { url = "https://files.pythonhosted.org/packages/d4/9f/ee29e306901be0ea521b464c3533bd95d49dbe08c54df64cd49bbb13918e/voyager-2.0.9-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:d58682f2f8d9cfccb95d2278eeec01ed76f90636cf6123db7850eb9a4b7e70e7", size = 380145 },
+    { url = "https://files.pythonhosted.org/packages/e5/83/d9b40742c17f674cbafec55b751804e68ee9b492cfb02fddc72f060beb17/voyager-2.0.9-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:510485dafa539ae130f2ad8bf7c95b21a2fa454f0b25581b37be3ca36bab29a1", size = 358094 },
+    { url = "https://files.pythonhosted.org/packages/33/61/e705ee3154450802912d35e881261182c01ba0e65cc83c6ef16b84c56e1b/voyager-2.0.9-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a4015db48c0c5d596e8bc536f4b05b601a2138e6439e00b06410e18286896273", size = 4234321 },
+    { url = "https://files.pythonhosted.org/packages/13/7a/4ac271fb5a8068f97dd6446622d679d26237a772ab12d1e6241cc0848dca/voyager-2.0.9-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:805f1736e5fe309ae8884e572b78d9816ff4fd6f1ef364298a2f62566ea86bc9", size = 4312789 },
+    { url = "https://files.pythonhosted.org/packages/b4/f6/906b21d4b42df264fc231c74753ca164f14cb09d40cd6b3a32d293aa0418/voyager-2.0.9-cp312-cp312-win_amd64.whl", hash = "sha256:abc7041ba8047d25942afe457db597be6f33161a669aac00dfffc00b7d833bfa", size = 201868 },
+    { url = "https://files.pythonhosted.org/packages/9f/9a/f5467d52356995c9f64cb27a99211142abead24290bfb8ccfb38168ef91d/voyager-2.0.9-cp39-cp39-macosx_10_13_universal2.whl", hash = "sha256:a38b7a232367095ef28350889b0c4ec8ce9f53c0a7839f2b06f517b652938e2c", size = 731403 },
+    { url = "https://files.pythonhosted.org/packages/ab/be/ecef9dfce07c535af6d11a4011a4a8693c4174ca8f87495e9ba30c8c7884/voyager-2.0.9-cp39-cp39-macosx_10_13_x86_64.whl", hash = "sha256:e5968f516a94832a599c9c1b64246b7f81344ed3fb49247fbdaba7e673c1e8a9", size = 377365 },
+    { url = "https://files.pythonhosted.org/packages/55/99/d31f596e887d998c81671b8e345925f07ccc36dee7144dbf80f1c86fb187/voyager-2.0.9-cp39-cp39-macosx_11_0_arm64.whl", hash = "sha256:f4095d4012479fa53b21f8a65c7790e844c3634a8ead1fca04f69a4a34ebc362", size = 356976 },
+    { url = "https://files.pythonhosted.org/packages/6f/43/096fcfa3443d37d8b5e4163b49b0d91f0456022df59017a8ae25ae4482d9/voyager-2.0.9-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:d55f85d36111e950d42e7d78accca84c582d5606ec1bae2d4b2da41ccc3e7f2e", size = 4209912 },
+    { url = "https://files.pythonhosted.org/packages/ff/51/c35a343471746e8964cb5d002a3367f5e28f5787c2c0689e0566a7406f66/voyager-2.0.9-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:83e1dd648040df093ddda74a6f361ec912caf981d20dfdd4b0d3bd7fb230147b", size = 4280035 },
+    { url = "https://files.pythonhosted.org/packages/ba/6c/5643effb7e495f8ee5c346e7b41961cb8d4dd6ef6952b24ec929a868f41c/voyager-2.0.9-cp39-cp39-win_amd64.whl", hash = "sha256:a2b17036c9b825f7062eb09ac613ca1e3fdb11712b1fc6d58bbbc201698e09c9", size = 196377 },
+]
+
 [[package]]
 name = "wcwidth"
 version = "0.2.13"

{vicinity-0.3.1 → vicinity-0.3.3}/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.3}/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.3}/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)