MinishLab/vicinity

Vicinity – Light‑weight Nearest‑Neighbour Store with Pluggable Back‑ends

What it is – Vicinity is a Python library that lets you store vectors (e.g., embeddings from language models) and run fast nearest‑neighbour queries. It wraps a variety of popular ANN engines (FAISS, HNSW‑lib, Annoy, Usearch, etc.) behind a single, tiny‑dependency API, so you can swap the underlying index without changing your code.

Why it matters – In many AI applications (retrieval‑augmented generation, semantic search, recommendation, clustering) you need to find the most similar vectors quickly. Existing libraries each have their own Python interface and configuration quirks, making benchmarking and switching painful. Vicinity solves that by providing:

• a unified Vicinity class,
• a common set of metrics (cosine, euclidean, …),
• built‑in evaluation of query‑per‑second and recall, and
• easy persistence and sharing via the Hugging Face Hub.

Key features

• Unified API for many back‑ends (basic exact, FAISS, HNSW, Annoy, PyNNDescent, Usearch, Voyager).
• Low‑dependency core package; optional extras install only the back‑ends you need.
• Serialization – save() / load() to local disk or push_to_hub() / load_from_hub() for Hugging Face.
• Evaluation helper that reports QPS and recall on a held‑out query set.
• Flexible configuration – each back‑end exposes its most relevant parameters (e.g., ef_construction for HNSW, nlist for FAISS IVF).

Typical workflow

import numpy as np
from vicinity import Vicinity, Backend, Metric

# 1️⃣ Prepare data
items   = ["triforce", "master sword", "hylian shield"]
vectors = np.random.rand(len(items), 128)

# 2️⃣ Build an index (here the simple exact backend)
vic = Vicinity.from_vectors_and_items(
    vectors=vectors,
    items=items,
    backend_type=Backend.BASIC,
    metric=Metric.COSINE,
)

# 3️⃣ Query – top‑k or threshold
query = np.random.rand(128)
print(vic.query(query, k=3))               # → [(item, score), …]
print(vic.query_threshold(query, 0.9))    # → items with similarity ≥ 0.9

# 4️⃣ Persist / share
vic.save('my_store')
# or push to HuggingFace Hub
vic.push_to_hub(repo_id='my‑username/my‑vicinity')

Installation – The base package is tiny:

pip install vicinity          # core only
pip install vicinity[all]    # core + every optional back‑end & integration

You can also install just what you need, e.g. pip install vicinity[faiss].

Who should use it

• Researchers comparing ANN algorithms for a new embedding model.
• Engineers building semantic‑search or RAG pipelines who want to experiment with different indexes without rewriting code.
• Anyone needing a simple, serialisable vector store that can be version‑controlled via the Hugging Face Hub.

License & citation – MIT‑licensed. If used in academic work, cite the provided Zenodo reference.