vicinity 0.1.0__tar.gz → 0.2.1__tar.gz

vicinity-0.2.1/.github/workflows/ci.yaml

@@ -0,0 +1,67 @@
+name: Run tests and upload coverage
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  test:
+    name: Run tests with pytest
+    if: ${{ !github.event.pull_request.draft }}  # Skip draft PRs
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: ["ubuntu-latest", "windows-latest"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        exclude:
+          - os: windows-latest
+            python-version: "3.9"
+          - os: windows-latest
+            python-version: "3.11"
+          - os: windows-latest
+            python-version: "3.12"
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }} on ${{ matrix.os }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+
+      # Step for Windows: Create and activate a virtual environment
+      - name: Create and activate a virtual environment (Windows)
+        if: ${{ runner.os == 'Windows' }}
+        run: |
+          irm https://astral.sh/uv/install.ps1 | iex
+          $env:Path = "C:\Users\runneradmin\.local\bin;$env:Path"
+          uv venv .venv
+          "VIRTUAL_ENV=.venv" | Out-File -FilePath $env:GITHUB_ENV -Append
+          "$PWD/.venv/Scripts" | Out-File -FilePath $env:GITHUB_PATH -Append
+
+      # Step for Unix: Create and activate a virtual environment
+      - name: Create and activate a virtual environment (Unix)
+        if: ${{ runner.os != 'Windows' }}
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          uv venv .venv
+          echo "VIRTUAL_ENV=.venv" >> $GITHUB_ENV
+          echo "$PWD/.venv/bin" >> $GITHUB_PATH
+
+      # Install dependencies using uv pip
+      - name: Install dependencies
+        run: make install-no-pre-commit
+
+      # Run tests with coverage
+      - name: Run tests under coverage
+        run: |
+          coverage run -m pytest
+          coverage report
+
+      # Upload results to Codecov
+      - name: Upload results to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

vicinity-0.2.1/Makefile

@@ -0,0 +1,21 @@
+clean:
+
+
+venv:
+	uv venv
+
+install: venv
+	uv sync --all-extras
+	uv run pre-commit install
+
+install-no-pre-commit:
+	uv pip install ".[dev,hnsw,pynndescent,annoy,faiss,usearch]"
+
+install-base:
+	uv sync --extra dev
+
+fix:
+	uv run pre-commit run --all-files
+
+test:
+	uv run pytest --cov=vicinity --cov-report=term-missing

vicinity-0.2.1/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.1
+Name: vicinity
+Version: 0.2.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
+        
+        Copyright (c) 2024 The Minish Lab
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/MinishLab
+Project-URL: Bug Reports, https://github.com/MinishLab/vicinity/issues
+Project-URL: Source, https://github.com/MinishLab/vicinity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: orjson
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-coverage; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Provides-Extra: hnsw
+Requires-Dist: hnswlib; extra == "hnsw"
+Provides-Extra: pynndescent
+Requires-Dist: pynndescent>=0.5.10; extra == "pynndescent"
+Requires-Dist: numba>=0.59.0; extra == "pynndescent"
+Requires-Dist: llvmlite>=0.42.0; extra == "pynndescent"
+Requires-Dist: numpy>=1.24.0; extra == "pynndescent"
+Provides-Extra: annoy
+Requires-Dist: annoy; extra == "annoy"
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu; extra == "faiss"
+Provides-Extra: usearch
+Requires-Dist: usearch; extra == "usearch"
+
+<div align="center">
+
+# Vicinity: The Lightweight Vector Store
+
+</div>
+
+
+<div align="center">
+  <h2>
+    <a href="https://pypi.org/project/vicinity/"><img src="https://img.shields.io/pypi/v/vicinity?color=%23007ec6&label=pypi%20package" alt="Package version"></a>
+    <a href="https://pypi.org/project/vicinity/"><img src="https://img.shields.io/pypi/pyversions/vicinity" alt="Supported Python versions"></a>
+    <a href="https://pepy.tech/project/vicinity">
+    <img src="https://static.pepy.tech/badge/vicinity" alt="Downloads">
+    </a>
+    <a href="https://app.codecov.io/gh/MinishLab/vicinity">
+    <img src="https://codecov.io/gh/MinishLab/vicinity/graph/badge.svg?token=0MQ2945OZL" alt="Codecov">
+    </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>
+</div>
+
+
+## Table of contents
+
+- [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.
+
+## Quickstart
+
+Install the package with:
+```bash
+pip install vicinity
+```
+
+
+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
+
+# 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)
+
+# Query for nearest neighbors with a top-k search
+query_vector = np.random.rand(128)
+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
+vicinity.save('my_vector_store')
+
+# Load the vector store
+vicinity = Vicinity.load('my_vector_store')
+```
+
+## 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.
+- Easy to Use: Simple and intuitive API.
+
+## Supported Backends
+The following backends are supported:
+- `BASIC`: A simple 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.
+- [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.
+
+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.
+
+### Backend Parameters
+
+
+| Backend         | Parameter           | Description                                                                                   | Default Value       |
+|-----------------|---------------------|-----------------------------------------------------------------------------------------------|---------------------|
+| **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"`          |
+|                 | `index_type`        | Type of FAISS index (`flat`, `ivf`, `hnsw`, `lsh`, `scalar`, `pq`, `ivf_scalar`, `ivfpq`, `ivfpqr`). | `"hnsw"`           |
+|                 | `nlist`             | Number of cells for IVF indexes.                                                              | `100`               |
+|                 | `m`                 | Number of subquantizers for PQ and HNSW indexes.                                              | `8`                 |
+|                 | `nbits`             | Number of bits for LSH and PQ indexes.                                                        | `8`                 |
+|                 | `refine_nbits`      | Number of bits for the refinement stage in IVFPQR indexes.                                    | `8`                 |
+| **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"`          |
+|                 | `n_neighbors`       | Number of neighbors to use for search.                                                        | `15`                |
+| **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`                |
+
+
+
+## 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:
+
+```python
+vicinity = Vicinity.load('my_vector_store')
+```
+</details>
+
+## License
+
+MIT

vicinity-0.2.1/README.md

@@ -0,0 +1,195 @@
+<div align="center">
+
+# Vicinity: The Lightweight Vector Store
+
+</div>
+
+
+<div align="center">
+  <h2>
+    <a href="https://pypi.org/project/vicinity/"><img src="https://img.shields.io/pypi/v/vicinity?color=%23007ec6&label=pypi%20package" alt="Package version"></a>
+    <a href="https://pypi.org/project/vicinity/"><img src="https://img.shields.io/pypi/pyversions/vicinity" alt="Supported Python versions"></a>
+    <a href="https://pepy.tech/project/vicinity">
+    <img src="https://static.pepy.tech/badge/vicinity" alt="Downloads">
+    </a>
+    <a href="https://app.codecov.io/gh/MinishLab/vicinity">
+    <img src="https://codecov.io/gh/MinishLab/vicinity/graph/badge.svg?token=0MQ2945OZL" alt="Codecov">
+    </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>
+</div>
+
+
+## Table of contents
+
+- [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.
+
+## Quickstart
+
+Install the package with:
+```bash
+pip install vicinity
+```
+
+
+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
+
+# 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)
+
+# Query for nearest neighbors with a top-k search
+query_vector = np.random.rand(128)
+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
+vicinity.save('my_vector_store')
+
+# Load the vector store
+vicinity = Vicinity.load('my_vector_store')
+```
+
+## 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.
+- Easy to Use: Simple and intuitive API.
+
+## Supported Backends
+The following backends are supported:
+- `BASIC`: A simple 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.
+- [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.
+
+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.
+
+### Backend Parameters
+
+
+| Backend         | Parameter           | Description                                                                                   | Default Value       |
+|-----------------|---------------------|-----------------------------------------------------------------------------------------------|---------------------|
+| **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"`          |
+|                 | `index_type`        | Type of FAISS index (`flat`, `ivf`, `hnsw`, `lsh`, `scalar`, `pq`, `ivf_scalar`, `ivfpq`, `ivfpqr`). | `"hnsw"`           |
+|                 | `nlist`             | Number of cells for IVF indexes.                                                              | `100`               |
+|                 | `m`                 | Number of subquantizers for PQ and HNSW indexes.                                              | `8`                 |
+|                 | `nbits`             | Number of bits for LSH and PQ indexes.                                                        | `8`                 |
+|                 | `refine_nbits`      | Number of bits for the refinement stage in IVFPQR indexes.                                    | `8`                 |
+| **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"`          |
+|                 | `n_neighbors`       | Number of neighbors to use for search.                                                        | `15`                |
+| **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`                |
+
+
+
+## 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:
+
+```python
+vicinity = Vicinity.load('my_vector_store')
+```
+</details>
+
+## License
+
+MIT

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

@@ -3,7 +3,7 @@ name = "vicinity"
 description = "Lightweight Nearest Neighbors with Flexible Backends"
 readme = { file = "README.md", content-type = "text/markdown" }
 dynamic = ["version"]
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 license = { file = "LICENSE" }
 authors = [{ name = "Stéphan Tulkens", email = "stephantul@gmail.com"}, {name = "Thomas van Dongen", email = "thomas123@live.nl"}]
 
@@ -15,6 +15,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -39,8 +40,23 @@ dev = [
     "pytest",
     "pytest-coverage",
     "ruff",
+    "setuptools"
 ]
 hnsw = ["hnswlib"]
+pynndescent = [
+    "pynndescent>=0.5.10",
+    "numba>=0.59.0",
+    "llvmlite>=0.42.0",
+    "numpy>=1.24.0"
+]
+annoy = ["annoy"]
+faiss = ["faiss-cpu"]
+usearch = ["usearch"]
+
+[project.urls]
+"Homepage" = "https://github.com/MinishLab"
+"Bug Reports" = "https://github.com/MinishLab/vicinity/issues"
+"Source" = "https://github.com/MinishLab/vicinity"
 
 [tool.ruff]
 exclude = [".venv/"]

vicinity-0.2.1/tests/conftest.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from vicinity import Vicinity
+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"]
+
+
+@pytest.fixture(scope="session")
+def items() -> list[str]:
+    """Fixture providing a list of item names."""
+    return [f"item{i}" for i in range(1, 10001)]
+
+
+@pytest.fixture(scope="session")
+def vectors() -> np.ndarray:
+    """Fixture providing an array of vectors corresponding to items."""
+    return random_gen.random((10000, 8))
+
+
+@pytest.fixture(scope="session")
+def query_vector() -> np.ndarray:
+    """Fixture providing a query vector."""
+    return random_gen.random(8)
+
+
+BACKEND_PARAMS = [(Backend.FAISS, index_type) for index_type in _faiss_index_types] + [
+    (Backend.BASIC, None),
+    (Backend.HNSW, None),
+    (Backend.ANNOY, None),
+    (Backend.PYNNDESCENT, None),
+    (Backend.USEARCH, None),
+]
+
+
+# Create human-readable ids for each backend type
+BACKEND_IDS = [f"{backend.name}-{index_type}" if index_type else backend.name for backend, index_type in BACKEND_PARAMS]
+
+
+@pytest.fixture(params=BACKEND_PARAMS)
+def backend_type(request: pytest.FixtureRequest) -> Backend:
+    """Fixture parametrizing over all backend types defined in Backend."""
+    return request.param
+
+
+@pytest.fixture(params=BACKEND_PARAMS, ids=BACKEND_IDS)
+def vicinity_instance(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
+            )
+        else:
+            return Vicinity.from_vectors_and_items(
+                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)