vicinity 0.2.1__tar.gz → 0.3.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: vicinity
-Version: 0.2.1
+Version: 0.3.1
 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,80 @@ 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 import Vicinity, 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 +220,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.1}/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,80 @@ 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 import Vicinity, 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 +141,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.1}/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.1}/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.2.1 → vicinity-0.3.1}/uv.lock

@@ -1087,7 +1087,7 @@ wheels = [
 
 [[package]]
 name = "vicinity"
-version = "0.2.0"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "numpy" },
@@ -1096,6 +1096,16 @@ dependencies = [
 ]
 
 [package.optional-dependencies]
+all = [
+    { name = "annoy" },
+    { name = "faiss-cpu" },
+    { name = "hnswlib" },
+    { name = "llvmlite" },
+    { name = "numba" },
+    { name = "numpy" },
+    { name = "pynndescent" },
+    { name = "usearch" },
+]
 annoy = [
     { name = "annoy" },
 ]
@@ -1127,24 +1137,32 @@ usearch = [
 
 [package.metadata]
 requires-dist = [
+    { name = "annoy", marker = "extra == 'all'" },
     { name = "annoy", marker = "extra == 'annoy'" },
     { name = "black", marker = "extra == 'dev'" },
+    { name = "faiss-cpu", marker = "extra == 'all'" },
     { name = "faiss-cpu", marker = "extra == 'faiss'" },
+    { name = "hnswlib", marker = "extra == 'all'" },
     { name = "hnswlib", marker = "extra == 'hnsw'" },
     { name = "ipython", marker = "extra == 'dev'" },
+    { name = "llvmlite", marker = "extra == 'all'", specifier = ">=0.42.0" },
     { name = "llvmlite", marker = "extra == 'pynndescent'", specifier = ">=0.42.0" },
     { name = "mypy", marker = "extra == 'dev'" },
+    { name = "numba", marker = "extra == 'all'", specifier = ">=0.59.0" },
     { name = "numba", marker = "extra == 'pynndescent'", specifier = ">=0.59.0" },
     { name = "numpy" },
+    { name = "numpy", marker = "extra == 'all'", specifier = ">=1.24.0" },
     { name = "numpy", marker = "extra == 'pynndescent'", specifier = ">=1.24.0" },
     { name = "orjson" },
     { name = "pre-commit", marker = "extra == 'dev'" },
+    { name = "pynndescent", marker = "extra == 'all'", specifier = ">=0.5.10" },
     { name = "pynndescent", marker = "extra == 'pynndescent'", specifier = ">=0.5.10" },
     { name = "pytest", marker = "extra == 'dev'" },
     { name = "pytest-coverage", marker = "extra == 'dev'" },
     { name = "ruff", marker = "extra == 'dev'" },
     { name = "setuptools", marker = "extra == 'dev'" },
     { name = "tqdm" },
+    { name = "usearch", marker = "extra == 'all'" },
     { name = "usearch", marker = "extra == 'usearch'" },
 ]
 

vicinity-0.3.1/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__"]