vicinity 0.1.0__py3-none-any.whl

vicinity/__init__.py

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

vicinity/backends/__init__.py

@@ -0,0 +1,17 @@
+from vicinity.backends.base import AbstractBackend
+from vicinity.backends.basic import BasicBackend
+from vicinity.datatypes import Backend
+
+
+def get_backend_class(backend: Backend | str) -> type[AbstractBackend]:
+    """Get all available backends."""
+    backend = Backend(backend)
+    if backend == Backend.BASIC:
+        return BasicBackend
+    elif backend == Backend.HNSW:
+        from vicinity.backends.hnsw import HNSWBackend
+
+        return HNSWBackend
+
+
+__all__ = ["get_backend_class", "AbstractBackend"]

vicinity/backends/base.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, TypeVar
+
+from numpy import typing as npt
+
+from vicinity.datatypes import Backend, QueryResult
+
+
+@dataclass(frozen=True)
+class BaseArgs:
+    dim: int | None = None
+
+    def dump(self, file: Path) -> None:
+        """Dump the arguments to a file."""
+        with open(file, "w") as f:
+            json.dump(asdict(self), 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))
+
+    def dict(self) -> dict[str, Any]:
+        """Dump the arguments to a string."""
+        return asdict(self)
+
+
+ArgType = TypeVar("ArgType", bound=BaseArgs)
+
+
+class AbstractBackend(ABC):
+    argument_class: type[BaseArgs]
+
+    def __init__(self, arguments: ArgType, *args: Any, **kwargs: Any) -> None:
+        """Initialize the backend with vectors."""
+        self.arguments = arguments
+
+    @classmethod
+    @abstractmethod
+    def from_vectors(cls: type[BaseType], vectors: npt.NDArray, *args: Any, **kwargs: Any) -> BaseType:
+        """Create a new instance from vectors."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """The number of items in the backend."""
+        raise NotImplementedError()
+
+    @property
+    @abstractmethod
+    def backend_type(self) -> Backend:
+        """The type of the backend."""
+        raise NotImplementedError()
+
+    @property
+    @abstractmethod
+    def dim(self) -> int:
+        """The size of the space."""
+        raise NotImplementedError()
+
+    @classmethod
+    @abstractmethod
+    def load(cls: type[BaseType], path: Path) -> BaseType:
+        """Load a backend from a file."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def save(self, base_path: Path) -> None:
+        """Save the backend to a file."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def insert(self, vectors: npt.NDArray) -> None:
+        """Insert vectors into the backend."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def delete(self, indices: list[int]) -> None:
+        """Delete vectors from the backend."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def threshold(self, vectors: npt.NDArray, threshold: float) -> list[npt.NDArray]:
+        """Threshold the backend."""
+        raise NotImplementedError()
+
+    @abstractmethod
+    def query(self, vectors: npt.NDArray, k: int) -> QueryResult:
+        """Query the backend."""
+        raise NotImplementedError()
+
+
+BaseType = TypeVar("BaseType", bound=AbstractBackend)

vicinity/backends/basic.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from numpy import typing as npt
+
+from vicinity.backends.base import AbstractBackend, BaseArgs
+from vicinity.datatypes import Backend, Matrix, QueryResult
+from vicinity.utils import normalize, normalize_or_copy
+
+
+@dataclass(frozen=True)
+class BasicArgs(BaseArgs): ...
+
+
+class BasicBackend(AbstractBackend):
+    argument_class = BasicArgs
+
+    def __init__(self, vectors: npt.NDArray, arguments: BasicArgs) -> None:
+        """Initialize the backend using vectors."""
+        super().__init__(arguments)
+        self._vectors = vectors
+        self._norm_vectors: npt.NDArray | None = None
+
+    def __len__(self) -> int:
+        """Get the number of vectors."""
+        return self.vectors.shape[0]
+
+    @property
+    def backend_type(self) -> Backend:
+        """The type of the backend."""
+        return Backend.BASIC
+
+    @classmethod
+    def from_vectors(cls: type[BasicBackend], vectors: npt.NDArray, dim: int | None = None) -> BasicBackend:
+        """Create a new instance from vectors."""
+        if dim is None:
+            dim = vectors.shape[1]
+        return cls(vectors, BasicArgs(dim=dim))
+
+    @classmethod
+    def load(cls: type[BasicBackend], folder: Path) -> BasicBackend:
+        """Load the vectors from a path."""
+        path = folder / "vectors.npy"
+        arguments = BasicArgs.load(folder / "arguments.json")
+        with open(path, "rb") as f:
+            return cls(np.load(f), arguments)
+
+    def save(self, folder: Path) -> None:
+        """Save the vectors to a path."""
+        path = Path(folder) / "vectors.npy"
+        self.arguments.dump(folder / "arguments.json")
+        with open(path, "wb") as f:
+            np.save(f, self._vectors)
+
+    @property
+    def dim(self) -> int:
+        """The size of the space."""
+        return self.vectors.shape[1]
+
+    @property
+    def vectors(self) -> npt.NDArray:
+        """The vectors themselves."""
+        return self._vectors
+
+    @vectors.setter
+    def vectors(self, x: Matrix) -> None:
+        matrix = np.asarray(x)
+        if not np.ndim(matrix) == 2:
+            raise ValueError(f"Your array does not have 2 dimensions: {np.ndim(matrix)}")
+        self._vectors = matrix
+        # Make sure norm vectors is updated.
+        if self._norm_vectors is not None:
+            self._norm_vectors = normalize_or_copy(matrix)
+
+    @property
+    def norm_vectors(self) -> npt.NDArray:
+        """
+        Vectors, but normalized to unit length.
+
+        NOTE: when all vectors are unit length, this attribute _is_ vectors.
+        """
+        if self._norm_vectors is None:
+            self._norm_vectors = normalize_or_copy(self.vectors)
+        return self._norm_vectors
+
+    def threshold(
+        self,
+        vectors: npt.NDArray,
+        threshold: float,
+    ) -> list[npt.NDArray]:
+        """Batched cosine similarity."""
+        out: list[npt.NDArray] = []
+        for i in range(0, len(vectors), 1024):
+            batch = vectors[i : i + 1024]
+            distances = self._dist(batch, self.norm_vectors)
+            for _, sims in enumerate(distances):
+                indices = np.flatnonzero(sims <= threshold)
+                sorted_indices = indices[np.argsort(sims[indices])]
+                out.append(sorted_indices)
+
+        return out
+
+    def query(
+        self,
+        vectors: npt.NDArray,
+        k: int,
+    ) -> QueryResult:
+        """Batched cosine distance."""
+        if k < 1:
+            raise ValueError("num should be >= 1, is now {num}")
+
+        out: QueryResult = []
+
+        for index in range(0, len(vectors), 1024):
+            batch = vectors[index : index + 1024]
+            distances = self._dist(batch, self.norm_vectors)
+            if k == 1:
+                sorted_indices = np.argmin(distances, 1, keepdims=True)
+            elif k >= len(self.vectors):
+                # If we want more than we have, just sort everything.
+                sorted_indices = np.stack([np.arange(len(self.vectors))] * len(vectors))
+            else:
+                sorted_indices = np.argpartition(distances, kth=k, axis=1)
+                sorted_indices = sorted_indices[:, :k]
+            for lidx, indices in enumerate(sorted_indices):
+                dists_for_word = distances[lidx, indices]
+                word_index = np.argsort(dists_for_word)
+                i = indices[word_index]
+                d = dists_for_word[word_index]
+                out.append((i, d))
+
+        return out
+
+    @classmethod
+    def _dist(cls, x: npt.NDArray, y: npt.NDArray) -> npt.NDArray:
+        """Cosine distance function. This assumes y is normalized."""
+        sim = normalize(x).dot(y.T)
+
+        return 1 - sim
+
+    def insert(self, vectors: npt.NDArray) -> None:
+        """Insert vectors into the vector space."""
+        self._vectors = np.vstack([self._vectors, vectors])
+
+    def delete(self, indices: list[int]) -> None:
+        """Deletes specific indices from the vector space."""
+        self._vectors = np.delete(self._vectors, indices, axis=0)

vicinity/backends/hnsw.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from hnswlib import Index as HnswIndex
+from numpy import typing as npt
+
+from vicinity.backends.base import AbstractBackend, BaseArgs
+from vicinity.datatypes import Backend, QueryResult
+
+
+@dataclass(frozen=True)
+class HNSWArgs(BaseArgs):
+    dim: int | None = None
+    space: Literal["cosine", "l2"] = "cosine"
+    ef_construction: int = 200
+    m: int = 16
+
+
+class HNSWBackend(AbstractBackend):
+    argument_class = HNSWArgs
+
+    def __init__(
+        self,
+        index: HnswIndex,
+        arguments: HNSWArgs,
+    ) -> None:
+        """Initialize the backend using vectors."""
+        super().__init__(arguments)
+        self.index = index
+
+    @classmethod
+    def from_vectors(
+        cls: type[HNSWBackend],
+        vectors: npt.NDArray,
+        dim: int | None,
+        space: Literal["cosine", "l2"],
+        ef_construction: int,
+        m: int,
+    ) -> HNSWBackend:
+        """Create a new instance from vectors."""
+        if dim is None:
+            dim = vectors.shape[1]
+        index = HnswIndex(space=space, dim=dim)
+        index.init_index(max_elements=vectors.shape[0], ef_construction=ef_construction, M=m)
+        index.add_items(vectors)
+        arguments = HNSWArgs(dim=dim, space=space, ef_construction=ef_construction, m=m)
+        return HNSWBackend(index, arguments=arguments)
+
+    @property
+    def backend_type(self) -> Backend:
+        """The type of the backend."""
+        return Backend.HNSW
+
+    @property
+    def dim(self) -> int:
+        """Get the dimension of the space."""
+        return self.index.dim
+
+    def __len__(self) -> int:
+        """Get the number of vectors."""
+        return self.index.get_current_count()
+
+    @classmethod
+    def load(cls: type[HNSWBackend], base_path: Path) -> HNSWBackend:
+        """Load the vectors from a path."""
+        path = Path(base_path) / "index.bin"
+        arguments = HNSWArgs.load(base_path / "arguments.json")
+        index = HnswIndex(space=arguments.space, dim=arguments.dim)
+        index.load_index(str(path))
+        return cls(index, arguments=arguments)
+
+    def save(self, base_path: Path) -> None:
+        """Save the vectors to a path."""
+        path = Path(base_path) / "index.bin"
+        self.index.save_index(str(path))
+        self.arguments.dump(base_path / "arguments.json")
+
+    def query(self, vectors: npt.NDArray, k: int) -> QueryResult:
+        """Query the backend."""
+        return list(zip(*self.index.knn_query(vectors, k)))
+
+    def insert(self, vectors: npt.NDArray) -> None:
+        """Insert vectors into the backend."""
+        self.index.add_items(vectors)
+
+    def delete(self, indices: list[int]) -> None:
+        """Delete vectors from the backend."""
+        for index in indices:
+            self.index.mark_deleted(index)
+
+    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

vicinity/datatypes.py

@@ -0,0 +1,20 @@
+from enum import Enum
+from pathlib import Path
+from typing import Iterable, TypeAlias
+
+import numpy as np
+from numpy import typing as npt
+
+PathLike = str | Path
+Matrix: TypeAlias = npt.NDArray | list[npt.NDArray]
+SimilarityItem = list[tuple[str, float]]
+SimilarityResult = list[SimilarityItem]
+# Tuple of (indices, distances)
+SingleQueryResult = tuple[npt.NDArray, npt.NDArray]
+QueryResult = list[SingleQueryResult]
+Tokens = Iterable[str]
+
+
+class Backend(str, Enum):
+    HNSW = "hnsw"
+    BASIC = "basic"

vicinity/utils.py

@@ -0,0 +1,51 @@
+import numpy as np
+from numpy import typing as npt
+
+
+def normalize(vectors: npt.NDArray, norms: npt.NDArray | None = None) -> npt.NDArray:
+    """
+    Normalize a matrix of row vectors to unit length.
+
+    Contains a shortcut if there are no zero vectors in the matrix.
+    If there are zero vectors, we do some indexing tricks to avoid
+    dividing by 0.
+
+    :param vectors: The vectors to normalize.
+    :param norms: Precomputed norms. If this is None, the norms are computed.
+    :return: The input vectors, normalized to unit length.
+    """
+    if np.ndim(vectors) == 1:
+        norm_float = np.linalg.norm(vectors)
+        if np.isclose(norm_float, 0):
+            return np.zeros_like(vectors)
+        return vectors / norm_float
+
+    if norms is None:
+        norm: npt.NDArray = np.linalg.norm(vectors, axis=1)
+    else:
+        norm = norms
+
+    if np.any(np.isclose(norm, 0.0)):
+        vectors = np.copy(vectors)
+        nonzero = norm > 0.0
+        result = np.zeros_like(vectors)
+        masked_norm = norm[nonzero]
+        masked_vectors = vectors[nonzero]
+        result[nonzero] = masked_vectors / masked_norm[:, None]
+
+        return result
+    else:
+        return vectors / norm[:, None]
+
+
+def normalize_or_copy(vectors: npt.NDArray) -> npt.NDArray:
+    """
+    Return the original vectors if they are already normalized.
+
+    Otherwise, the vectors are normalized, and a new array is returned.
+    """
+    norms = np.linalg.norm(vectors, axis=-1)
+    all_unit_length = np.allclose(norms[norms != 0], 1)
+    if all_unit_length:
+        return vectors
+    return normalize(vectors, norms)

vicinity/version.py

@@ -0,0 +1,2 @@
+__version_triple__ = (0, 1, 0)
+__version__ = ".".join(map(str, __version_triple__))

vicinity/vicinity.py

@@ -0,0 +1,228 @@
+"""A small vector store."""
+
+from __future__ import annotations
+
+import logging
+from io import open
+from pathlib import Path
+from typing import Any, Sequence
+
+import numpy as np
+import orjson
+from numpy import typing as npt
+
+from vicinity.backends import AbstractBackend, get_backend_class
+from vicinity.datatypes import Backend, PathLike
+
+logger = logging.getLogger(__name__)
+
+
+class Vicinity:
+    """
+    Work with vector representations of items.
+
+    Supports functions for calculating fast batched similarity
+    between items or composite representations of items.
+    """
+
+    def __init__(
+        self,
+        items: Sequence[str],
+        backend: AbstractBackend,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Initialize a Vicinity instance with an array and list of items.
+
+        :param items: The items in the vector space.
+            A list of items. Length must be equal to the number of vectors, and
+            aligned with the vectors.
+        :param backend: The backend to use for the vector space.
+        :param metadata: A dictionary containing metadata about the vector space.
+        :raises ValueError: If the length of the items and vectors are not the same.
+        """
+        if len(items) != len(backend):
+            raise ValueError(
+                "Your vector space and list of items are not the same length: " f"{len(backend)} != {len(items)}"
+            )
+        self.items: list[str] = list(items)
+        self.backend: AbstractBackend = backend
+        self.metadata = metadata or {}
+
+    def __len__(self) -> int:
+        """The number of the items in the vector space."""
+        return len(self.items)
+
+    @classmethod
+    def from_vectors_and_items(
+        cls: type[Vicinity],
+        vectors: npt.NDArray,
+        items: Sequence[str],
+        backend_type: Backend = Backend.BASIC,
+        **kwargs: Any,
+    ) -> Vicinity:
+        """
+        Create a Vicinity instance from vectors and items.
+
+        :param vectors: The vectors to use.
+        :param items: The items to use.
+        :param backend_type: The type of backend to use.
+        :param **kwargs: Additional arguments to pass to the backend.
+        :return: A Vicinity instance.
+        """
+        backend_cls = get_backend_class(backend_type)
+        arguments = backend_cls.argument_class(**kwargs)
+        backend = backend_cls.from_vectors(vectors, **arguments.dict())
+
+        return cls(items, backend)
+
+    @property
+    def dim(self) -> int:
+        """The dimensionality of the vectors."""
+        return self.backend.dim
+
+    def query(
+        self,
+        vectors: npt.NDArray,
+        k: int = 10,
+    ) -> list[list[tuple[str, float]]]:
+        """
+        Find the nearest neighbors to some arbitrary vector.
+
+        Use this to look up the nearest neighbors to a vector that is not in the vocabulary.
+
+        :param vectors: The vectors to find the nearest neighbors to.
+        :param k: The number of most similar items to retrieve.
+        :return: For each item in the input, the num most similar items are returned in the form of
+            (NAME, SIMILARITY) tuples.
+        """
+        vectors = np.asarray(vectors)
+        if np.ndim(vectors) == 1:
+            vectors = vectors[None, :]
+
+        out = []
+        for index, distances in self.backend.query(vectors, k):
+            distances.clip(min=0, out=distances)
+            out.append([(self.items[idx], dist) for idx, dist in zip(index, distances)])
+
+        return out
+
+    def query_threshold(
+        self,
+        vectors: npt.NDArray,
+        threshold: float = 0.5,
+    ) -> list[list[str]]:
+        """
+        Find the nearest neighbors to some arbitrary vector with some threshold.
+
+        :param vectors: The vectors to find the most similar vectors to.
+        :param threshold: The threshold to use.
+
+        :return: For each item in the input, all items above the threshold are returned.
+        """
+        vectors = np.array(vectors)
+        if np.ndim(vectors) == 1:
+            vectors = vectors[None, :]
+
+        out = []
+        for indexes in self.backend.threshold(vectors, threshold):
+            out.append([self.items[idx] for idx in indexes])
+
+        return out
+
+    def save(
+        self,
+        folder: PathLike,
+        overwrite: bool = False,
+    ) -> None:
+        """
+        Save a Vicinity instance in a fast format.
+
+        The Vicinity fast format stores the words and vectors of a Vicinity instance
+        separately in a JSON and numpy format, respectively.
+
+        :param folder: The path to which to save the JSON file. The vectors are saved separately. The JSON contains a path to the numpy file.
+        :param overwrite: Whether to overwrite the JSON and numpy files if they already exist.
+        :raises ValueError: If the path is not a directory.
+        """
+        path = Path(folder)
+        path.mkdir(parents=True, exist_ok=overwrite)
+
+        if not path.is_dir():
+            raise ValueError(f"Path {path} should be a directory.")
+
+        items_dict = {"items": self.items, "metadata": self.metadata, "backend_type": self.backend.backend_type.value}
+
+        with open(path / "data.json", "wb") as file_handle:
+            file_handle.write(orjson.dumps(items_dict))
+
+        self.backend.save(path)
+
+    @classmethod
+    def load(cls, filename: PathLike) -> Vicinity:
+        """
+        Load a Vicinity instance in fast format.
+
+        As described above, the fast format stores the words and vectors of the
+        Vicinity instance separately and is drastically faster than loading from
+        .txt files.
+
+        :param filename: The filename to load.
+        :return: A Vicinity instance.
+        """
+        folder_path = Path(filename)
+
+        with open(folder_path / "data.json", "rb") as file_handle:
+            data: dict[str, Any] = orjson.loads(file_handle.read())
+        items: Sequence[str] = data["items"]
+
+        metadata: dict[str, Any] = data["metadata"]
+        backend_type = Backend(data["backend_type"])
+
+        backend_cls: type[AbstractBackend] = get_backend_class(backend_type)
+        backend = backend_cls.load(folder_path)
+
+        instance = cls(items, backend, metadata=metadata)
+
+        return instance
+
+    def insert(self, tokens: Sequence[str], vectors: npt.NDArray) -> None:
+        """
+        Insert new items into the vector space.
+
+        :param tokens: A list of items to insert into the vector space.
+        :param vectors: The vectors to insert into the vector space.
+        :raises ValueError: If the tokens and vectors are not the same length.
+        """
+        if len(tokens) != len(vectors):
+            raise ValueError(f"Your tokens and vectors are not the same length: {len(tokens)} != {len(vectors)}")
+
+        if vectors.shape[1] != self.dim:
+            raise ValueError("The inserted vectors must have the same dimension as the backend.")
+
+        item_set = set(self.items)
+        for token in tokens:
+            if token in item_set:
+                raise ValueError(f"Token {token} is already in the vector space.")
+            self.items.append(token)
+        self.backend.insert(vectors)
+
+    def delete(self, tokens: Sequence[str]) -> None:
+        """
+        Delete tokens from the vector space.
+
+        The removal of tokens is done in place. If the tokens are not in the vector space,
+        a ValueError is raised.
+
+        :param tokens: A list of tokens to remove from the vector space.
+        :raises ValueError: If any passed tokens are not in the vector space.
+        """
+        try:
+            curr_indices = [self.items.index(token) for token in tokens]
+        except KeyError as exc:
+            raise ValueError(f"Token {exc} was not in the vector space.") from exc
+
+        self.backend.delete(curr_indices)
+
+        for index in curr_indices:
+            self.items.pop(index)

vicinity-0.1.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+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.

vicinity-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.1
+Name: vicinity
+Version: 0.1.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
+        
+        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.
+        
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+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'
+Provides-Extra: hnsw
+Requires-Dist: hnswlib ; extra == 'hnsw'
+
+<div align="center">
+
+# Vicinity: The Lightweight Vector Store
+
+</div>
+
+## Table of contents
+
+- [Quickstart](#quickstart)
+- [Main Features](#main-features)
+- [Supported Backends](#supported-backends)
+- [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.
+- Dynamic Updates: Insert and delete items in the vector store.
+- 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`: Hierarchical Navigable Small World Graph for approximate nearest neighbor search.
+
+## 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.dist-info/RECORD

@@ -0,0 +1,15 @@
+vicinity/__init__.py,sha256=66yyoNFqDf_K-O-hoFFNNPLOIym-6z7cnwOIqmpRt5E,196
+vicinity/datatypes.py,sha256=Wx2SSDwOY7ZMuclk6V6zQXCCAs2jF5YpZLAQqnyyg-Q,505
+vicinity/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vicinity/utils.py,sha256=tyUpZ7R3u5SzT15AocJNQ-zN1FdcxCmxJ62-NYTTt-g,1610
+vicinity/version.py,sha256=0ZST8YQ_2d0ualYw52Frv3F_O9ULTFPCjDUI8Zy4qoA,84
+vicinity/vicinity.py,sha256=EbU5khCMTzJaaGowuBhwYh2zZT8aIgDJqbXbOJJDzhg,7884
+vicinity/backends/__init__.py,sha256=Q48R4fedzjdAJfTLjKRb4Rtj2-NkzL6kv7plMS6qRyY,513
+vicinity/backends/base.py,sha256=z8FNQKOUNBAvp5bwuZXnYbwWa0uAkntHHubu-ibfdFc,2752
+vicinity/backends/basic.py,sha256=m1SaAJNKtOeDzoK3JovTfNcvMljtw3hfhVnA6O2lV8o,5109
+vicinity/backends/hnsw.py,sha256=WT6xVs_Y2KLhrwcWD1Ze-76esoNsrgyY8N92IQ04WjE,3145
+vicinity-0.1.0.dist-info/LICENSE,sha256=6CbsCtUBhLgsb6-YTEeH38lhp-qr9KhOAWOYT0sz_58,1071
+vicinity-0.1.0.dist-info/METADATA,sha256=rrRS690_DeYn9HnYDtYXV7r6utF8BUMlg5_9TeXmrYM,5793
+vicinity-0.1.0.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+vicinity-0.1.0.dist-info/top_level.txt,sha256=GT01ApOJe1lkgL-E_A_j0wU45CJmzQSiezfN2LOZEog,9
+vicinity-0.1.0.dist-info/RECORD,,

vicinity-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.3.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vicinity-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vicinity