vicinity 0.2.1__tar.gz → 0.3.0__tar.gz

{vicinity-0.2.1 → vicinity-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vicinity
-Version: 0.2.1
+Version: 0.3.0
 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,10 +67,19 @@ Provides-Extra: faiss
 Requires-Dist: faiss-cpu; extra == "faiss"
 Provides-Extra: usearch
 Requires-Dist: usearch; extra == "usearch"
+Provides-Extra: all
+Requires-Dist: hnswlib; extra == "all"
+Requires-Dist: pynndescent>=0.5.10; extra == "all"
+Requires-Dist: numba>=0.59.0; extra == "all"
+Requires-Dist: llvmlite>=0.42.0; extra == "all"
+Requires-Dist: numpy>=1.24.0; extra == "all"
+Requires-Dist: annoy; extra == "all"
+Requires-Dist: faiss-cpu; extra == "all"
+Requires-Dist: usearch; extra == "all"
 
 <div align="center">
 
-# Vicinity: The Lightweight Vector Store
+# Vicinity: Lightweight Nearest Neighbors
 
 </div>
 
@@ -87,18 +96,21 @@ Requires-Dist: usearch; extra == "usearch"
     </a>
     <a href="https://github.com/MinishLab/vicinity/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License - MIT"></a>
   </h2>
+
+[Quickstart](#quickstart) •
+[Main Features](#main-features) •
+[Supported Backends](#supported-backends) •
+[Installation](#installation)
+
 </div>
 
 
-## Table of contents
+Vicinity is a light-weight, low-dependency vector store. It provides a simple and intuitive interface for nearest neighbor search, with support for different backends and evaluation.
+
+There are many nearest neighbors packages and methods out there. However, we found it difficult to compare them. Every package has its own interface, quirks, and limitations, and learning a new package can be time-consuming. In addition to that, how do you effectively evaluate different packages? How do you know which one is the best for your use case?
 
-- [Quickstart](#quickstart)
-- [Main Features](#main-features)
-- [Supported Backends](#supported-backends)
-  - [Backend Parameters](#backend-parameters)
-- [Usage](#usage)
 
-Vicinity is the lightest-weight vector store. Just put in some vectors, calculate query vectors, and off you go. It provides a simple and intuitive API for nearest neighbor search, with support for different backends.
+ This is where Vicinity comes in. Instead of learning a new interface for each new package or backend, Vicinity provides a unified interface for all backends. This allows you to easily experiment with different indexing methods and distance metrics and choose the best one for your use case. Vicinity also provides a simple way to evaluate the performance of different backends, allowing you to measure the queries per second and recall.
 
 ## Quickstart
 
@@ -106,50 +118,81 @@ Install the package with:
 ```bash
 pip install vicinity
 ```
+Optinally, [install any of the supported backends](#installation), or simply install all of them with:
+```bash
+pip install vicinity[all]
+```
 
 
 The following code snippet demonstrates how to use Vicinity for nearest neighbor search:
 ```python
 import numpy as np
 from vicinity import Vicinity
-from vicinity.datatypes import Backend
+from vicinity.datatypes import Backend, Metric
 
 # Create some dummy data
 items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
 vectors = np.random.rand(len(items), 128)
 
-# Initialize the Vicinity instance (using the basic backend)
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items, backend_type=Backend.BASIC)
+# 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)
 
-# Query for nearest neighbors with a top-k search
+# 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)
 
 # Query for nearest neighbors with a threshold search
 results = vicinity.query_threshold([query_vector], threshold=0.9)
+```
 
-# Save the vector store
+Saving and loading a vector store:
+```python
 vicinity.save('my_vector_store')
-
-# Load the vector store
 vicinity = Vicinity.load('my_vector_store')
 ```
 
+Evaluating a backend:
+```python
+# Use the first 1000 vectors as query vectors
+query_vectors = vectors[:1000]
+
+# Evaluate the Vicinity instance by measuring the queries per second and recall
+qps, recall = vicinity.evaluate(
+    full_vectors=vectors,
+    query_vectors=query_vectors,
+)
+```
+
 ## Main Features
 Vicinity provides the following features:
 - Lightweight: Minimal dependencies and fast performance.
 - Flexible Backend Support: Use different backends for vector storage and search.
 - Serialization: Save and load vector stores for persistence.
+- Evaluation: Easily evaluate the performance of different backends.
 - Easy to Use: Simple and intuitive API.
 
 ## Supported Backends
 The following backends are supported:
-- `BASIC`: A simple flat index for vector storage and search.
+- `BASIC`: A simple (exact matching) flat index for vector storage and search.
 - [HNSW](https://github.com/nmslib/hnswlib): Hierarchical Navigable Small World Graph (HNSW) for ANN search using hnswlib.
-- [FAISS](https://github.com/facebookresearch/faiss): ANN search using FAISS. All FAISS indexes are supported.
+- [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.
-- [USEARCH](https://github.com/unum-cloud/usearch): ANN search using Usearch. This uses a highly optimized version of the HNSW algorithm.
+- [FAISS](https://github.com/facebookresearch/faiss): All FAISS indexes are supported:
+  - `flat`: Exact search.
+  - `ivf`: Inverted file search.
+  - `hnsw`: Hierarchical Navigable Small World Graph.
+  - `lsh`: Locality Sensitive Hashing.
+  - `scalar`: Scalar quantizer.
+  - `pq`: Product Quantizer.
+  - `ivf_scalar`: Inverted file search with scalar quantizer.
+  - `ivfpq`: Inverted file search with product quantizer.
+  - `ivfpqr`: Inverted file search with product quantizer and refinement.
+
+
+
 
 NOTE: the ANN backends do not support dynamic deletion. To delete items, you need to recreate the index. Insertion is supported in the following backends: `FAISS`, `HNSW`, and `Usearch`. The `BASIC` backend supports both insertion and deletion.
 
@@ -178,87 +221,22 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 |                 | `expansion_search`  | Number of candidates considered during search.                                                | `64`                |
 
 
+## Installation
+The following installation options are available:
+```bash
+# Install the base package
+pip install vicinity
 
-## Usage
-
-<details>
-<summary>  Creating a Vector Store
- </summary>
-<br>
-
-You can create a Vicinity instance by providing items and their corresponding vectors:
-
-
-```python
-from vicinity import Vicinity
-import numpy as np
-
-items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
-vectors = np.random.rand(len(items), 128)
-
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items)
-```
-
-</details>
-
-<details>
-<summary>  Querying
- </summary>
-<br>
-
-Find the k nearest neighbors for a given vector:
-
-```python
-query_vector = np.random.rand(128)
-results = vicinity.query([query_vector], k=3)
-```
-
-Find all neighbors within a given threshold:
-
-```python
-query_vector = np.random.rand(128)
-results = vicinity.query_threshold([query_vector], threshold=0.9)
-```
-</details>
-
-<details>
-
-<summary>  Inserting and Deleting Items
- </summary>
-<br>
-
-Insert new items:
-
-```python
-new_items = ["ocarina", "bow"]
-new_vectors = np.random.rand(2, 128)
-vicinity.insert(new_items, new_vectors)
-```
-
-Delete items:
-
-```python
-vicinity.delete(["hookshot"])
-```
-</details>
-
-<details>
-<summary>  Saving and Loading
- </summary>
-<br>
-
-Save the vector store:
-
-```python
-vicinity.save('my_vector_store')
-```
-
-Load the vector store:
+# Install all backends
+pip install vicinity[all]
 
-```python
-vicinity = Vicinity.load('my_vector_store')
+# Install specific backends
+pip install vicinity[annoy]
+pip install vicinity[faiss]
+pip install vicinity[hnsw]
+pip install vicinity[pynndescent]
+pip install vicinity[usearch]
 ```
-</details>
 
 ## License
 

{vicinity-0.2.1 → vicinity-0.3.0}/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# Vicinity: The Lightweight Vector Store
+# Vicinity: Lightweight Nearest Neighbors
 
 </div>
 
@@ -17,18 +17,21 @@
     </a>
     <a href="https://github.com/MinishLab/vicinity/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License - MIT"></a>
   </h2>
+
+[Quickstart](#quickstart) •
+[Main Features](#main-features) •
+[Supported Backends](#supported-backends) •
+[Installation](#installation)
+
 </div>
 
 
-## Table of contents
+Vicinity is a light-weight, low-dependency vector store. It provides a simple and intuitive interface for nearest neighbor search, with support for different backends and evaluation.
+
+There are many nearest neighbors packages and methods out there. However, we found it difficult to compare them. Every package has its own interface, quirks, and limitations, and learning a new package can be time-consuming. In addition to that, how do you effectively evaluate different packages? How do you know which one is the best for your use case?
 
-- [Quickstart](#quickstart)
-- [Main Features](#main-features)
-- [Supported Backends](#supported-backends)
-  - [Backend Parameters](#backend-parameters)
-- [Usage](#usage)
 
-Vicinity is the lightest-weight vector store. Just put in some vectors, calculate query vectors, and off you go. It provides a simple and intuitive API for nearest neighbor search, with support for different backends.
+ This is where Vicinity comes in. Instead of learning a new interface for each new package or backend, Vicinity provides a unified interface for all backends. This allows you to easily experiment with different indexing methods and distance metrics and choose the best one for your use case. Vicinity also provides a simple way to evaluate the performance of different backends, allowing you to measure the queries per second and recall.
 
 ## Quickstart
 
@@ -36,50 +39,81 @@ Install the package with:
 ```bash
 pip install vicinity
 ```
+Optinally, [install any of the supported backends](#installation), or simply install all of them with:
+```bash
+pip install vicinity[all]
+```
 
 
 The following code snippet demonstrates how to use Vicinity for nearest neighbor search:
 ```python
 import numpy as np
 from vicinity import Vicinity
-from vicinity.datatypes import Backend
+from vicinity.datatypes import Backend, Metric
 
 # Create some dummy data
 items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
 vectors = np.random.rand(len(items), 128)
 
-# Initialize the Vicinity instance (using the basic backend)
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items, backend_type=Backend.BASIC)
+# 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)
 
-# Query for nearest neighbors with a top-k search
+# 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)
 
 # Query for nearest neighbors with a threshold search
 results = vicinity.query_threshold([query_vector], threshold=0.9)
+```
 
-# Save the vector store
+Saving and loading a vector store:
+```python
 vicinity.save('my_vector_store')
-
-# Load the vector store
 vicinity = Vicinity.load('my_vector_store')
 ```
 
+Evaluating a backend:
+```python
+# Use the first 1000 vectors as query vectors
+query_vectors = vectors[:1000]
+
+# Evaluate the Vicinity instance by measuring the queries per second and recall
+qps, recall = vicinity.evaluate(
+    full_vectors=vectors,
+    query_vectors=query_vectors,
+)
+```
+
 ## Main Features
 Vicinity provides the following features:
 - Lightweight: Minimal dependencies and fast performance.
 - Flexible Backend Support: Use different backends for vector storage and search.
 - Serialization: Save and load vector stores for persistence.
+- Evaluation: Easily evaluate the performance of different backends.
 - Easy to Use: Simple and intuitive API.
 
 ## Supported Backends
 The following backends are supported:
-- `BASIC`: A simple flat index for vector storage and search.
+- `BASIC`: A simple (exact matching) flat index for vector storage and search.
 - [HNSW](https://github.com/nmslib/hnswlib): Hierarchical Navigable Small World Graph (HNSW) for ANN search using hnswlib.
-- [FAISS](https://github.com/facebookresearch/faiss): ANN search using FAISS. All FAISS indexes are supported.
+- [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.
-- [USEARCH](https://github.com/unum-cloud/usearch): ANN search using Usearch. This uses a highly optimized version of the HNSW algorithm.
+- [FAISS](https://github.com/facebookresearch/faiss): All FAISS indexes are supported:
+  - `flat`: Exact search.
+  - `ivf`: Inverted file search.
+  - `hnsw`: Hierarchical Navigable Small World Graph.
+  - `lsh`: Locality Sensitive Hashing.
+  - `scalar`: Scalar quantizer.
+  - `pq`: Product Quantizer.
+  - `ivf_scalar`: Inverted file search with scalar quantizer.
+  - `ivfpq`: Inverted file search with product quantizer.
+  - `ivfpqr`: Inverted file search with product quantizer and refinement.
+
+
+
 
 NOTE: the ANN backends do not support dynamic deletion. To delete items, you need to recreate the index. Insertion is supported in the following backends: `FAISS`, `HNSW`, and `Usearch`. The `BASIC` backend supports both insertion and deletion.
 
@@ -108,87 +142,22 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 |                 | `expansion_search`  | Number of candidates considered during search.                                                | `64`                |
 
 
+## Installation
+The following installation options are available:
+```bash
+# Install the base package
+pip install vicinity
 
-## Usage
-
-<details>
-<summary>  Creating a Vector Store
- </summary>
-<br>
-
-You can create a Vicinity instance by providing items and their corresponding vectors:
-
-
-```python
-from vicinity import Vicinity
-import numpy as np
-
-items = ["triforce", "master sword", "hylian shield", "boomerang", "hookshot"]
-vectors = np.random.rand(len(items), 128)
-
-vicinity = Vicinity.from_vectors_and_items(vectors=vectors, items=items)
-```
-
-</details>
-
-<details>
-<summary>  Querying
- </summary>
-<br>
-
-Find the k nearest neighbors for a given vector:
-
-```python
-query_vector = np.random.rand(128)
-results = vicinity.query([query_vector], k=3)
-```
-
-Find all neighbors within a given threshold:
-
-```python
-query_vector = np.random.rand(128)
-results = vicinity.query_threshold([query_vector], threshold=0.9)
-```
-</details>
-
-<details>
-
-<summary>  Inserting and Deleting Items
- </summary>
-<br>
-
-Insert new items:
-
-```python
-new_items = ["ocarina", "bow"]
-new_vectors = np.random.rand(2, 128)
-vicinity.insert(new_items, new_vectors)
-```
-
-Delete items:
-
-```python
-vicinity.delete(["hookshot"])
-```
-</details>
-
-<details>
-<summary>  Saving and Loading
- </summary>
-<br>
-
-Save the vector store:
-
-```python
-vicinity.save('my_vector_store')
-```
-
-Load the vector store:
+# Install all backends
+pip install vicinity[all]
 
-```python
-vicinity = Vicinity.load('my_vector_store')
+# Install specific backends
+pip install vicinity[annoy]
+pip install vicinity[faiss]
+pip install vicinity[hnsw]
+pip install vicinity[pynndescent]
+pip install vicinity[usearch]
 ```
-</details>
 
 ## License
 

{vicinity-0.2.1 → vicinity-0.3.0}/pyproject.toml

@@ -52,6 +52,16 @@ pynndescent = [
 annoy = ["annoy"]
 faiss = ["faiss-cpu"]
 usearch = ["usearch"]
+all = [
+    "hnswlib",
+    "pynndescent>=0.5.10",
+    "numba>=0.59.0",
+    "llvmlite>=0.42.0",
+    "numpy>=1.24.0",
+    "annoy",
+    "faiss-cpu",
+    "usearch"
+]
 
 [project.urls]
 "Homepage" = "https://github.com/MinishLab"

{vicinity-0.2.1 → vicinity-0.3.0}/tests/test_vicinity.py

@@ -220,3 +220,23 @@ def test_vicinity_delete_and_query(vicinity_instance: Vicinity, items: list[str]
 
     # Check that the queried item is in the results
     assert "item3" in returned_items
+
+
+def test_vicinity_evaluate(vicinity_instance: Vicinity, vectors: np.ndarray) -> None:
+    """
+    Test the evaluate method of the Vicinity instance.
+
+    :param vicinity_instance: A Vicinity instance.
+    :param vectors: The full dataset vectors used to build the index.
+    """
+    query_vectors = vectors[:10]
+    qps, recall = vicinity_instance.evaluate(vectors, query_vectors)
+
+    # Ensure the QPS and recall values are within valid ranges
+    assert qps > 0
+    assert 0 <= recall <= 1
+
+    # Test with an unsupported metric
+    vicinity_instance.backend.arguments.metric = "manhattan"
+    with pytest.raises(ValueError):
+        vicinity_instance.evaluate(vectors, query_vectors)

vicinity-0.3.0/vicinity/__init__.py

@@ -0,0 +1,8 @@
+"""Small vector store."""
+
+from vicinity.datatypes import Backend
+from vicinity.utils import Metric, normalize
+from vicinity.version import __version__
+from vicinity.vicinity import Vicinity
+
+__all__ = ["Backend", "Metric", "Vicinity", "normalize", "__version__"]

{vicinity-0.2.1 → vicinity-0.3.0}/vicinity/backends/annoy.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any, Union
 
 import numpy as np
 from annoy import AnnoyIndex
@@ -10,19 +10,25 @@ from numpy import typing as npt
 
 from vicinity.backends.base import AbstractBackend, BaseArgs
 from vicinity.datatypes import Backend, QueryResult
-from vicinity.utils import normalize
+from vicinity.utils import Metric, normalize
 
 
 @dataclass
 class AnnoyArgs(BaseArgs):
     dim: int = 0
-    metric: Literal["dot", "euclidean", "cosine"] = "cosine"
+    metric: str = "cosine"
     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 = {
+        Metric.COSINE: "dot",
+        Metric.EUCLIDEAN: "euclidean",
+        Metric.INNER_PRODUCT: "dot",
+    }
 
     def __init__(
         self,
@@ -40,25 +46,28 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
     def from_vectors(
         cls: type[AnnoyBackend],
         vectors: npt.NDArray,
-        metric: Literal["dot", "euclidean", "cosine"],
+        metric: Union[str, Metric],
         trees: int,
         **kwargs: Any,
     ) -> AnnoyBackend:
         """Create a new instance from vectors."""
-        dim = vectors.shape[1]
-        actual_metric: Literal["dot", "euclidean"]
-        if metric == "cosine":
-            actual_metric = "dot"
+        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 AnnoyBackend.")
+
+        metric = cls._map_metric_to_string(metric_enum)
+
+        if metric == "dot":
             vectors = normalize(vectors)
-        else:
-            actual_metric = metric
 
-        index = AnnoyIndex(f=dim, metric=actual_metric)
+        dim = vectors.shape[1]
+        index = AnnoyIndex(f=dim, metric=metric)  # type: ignore
         for i, vector in enumerate(vectors):
             index.add_item(i, vector)
         index.build(trees)
 
-        arguments = AnnoyArgs(dim=dim, trees=trees, metric=metric, length=len(vectors))
+        arguments = AnnoyArgs(dim=dim, metric=metric, trees=trees, length=len(vectors))  # type: ignore
         return AnnoyBackend(index, arguments=arguments)
 
     @property
@@ -80,11 +89,7 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
         """Load the vectors from a path."""
         path = Path(base_path) / "index.bin"
         arguments = AnnoyArgs.load(base_path / "arguments.json")
-
-        metric = arguments.metric
-        actual_metric = "dot" if metric == "cosine" else metric
-
-        index = AnnoyIndex(arguments.dim, actual_metric)
+        index = AnnoyIndex(arguments.dim, arguments.metric)  # type: ignore
         index.load(str(path))
 
         return cls(index, arguments=arguments)
@@ -93,7 +98,7 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
         """Save the vectors to a path."""
         path = Path(base_path) / "index.bin"
         self.index.save(str(path))
-        # NOTE: set the length before saving.
+        # Ensure the length is set before saving
         self.arguments.length = len(self)
         self.arguments.dump(base_path / "arguments.json")
 
@@ -101,28 +106,27 @@ class AnnoyBackend(AbstractBackend[AnnoyArgs]):
         """Query the backend."""
         out = []
         for vec in vectors:
-            if self.arguments.metric == "cosine":
+            if self.arguments.metric == "dot":
                 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 == "cosine":
-                # Turn cosine similarity into cosine distance.
+            if self.arguments.metric == "dot":
+                # Convert cosine similarity to cosine distance
                 scores_array = 1 - scores_array
             out.append((np.asarray(indices), scores_array))
         return out
 
     def insert(self, vectors: npt.NDArray) -> None:
         """Insert vectors into the backend."""
-        raise NotImplementedError("Insertion is not supported in ANNOY backend.")
+        raise NotImplementedError("Insertion is not supported in Annoy backend.")
 
     def delete(self, indices: list[int]) -> None:
         """Delete vectors from the backend."""
-        raise NotImplementedError("Deletion is not supported in ANNOY backend.")
+        raise NotImplementedError("Deletion is not supported in Annoy 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, 100):
             out.append(x[y < threshold])
-
         return out