vicinity 0.1.0__tar.gz

vicinity-0.1.0/.gitignore

@@ -0,0 +1,164 @@
+local/*
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

vicinity-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,34 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: check-ast
+        description: Simply check whether files parse as valid python.
+      - id: trailing-whitespace
+        description: Trims trailing whitespace
+      - id: end-of-file-fixer
+        description: Makes sure files end in a newline and only a newline.
+      - id: check-added-large-files
+        args: ['--maxkb=5000']
+        description: Prevent giant files from being committed.
+      - id: check-case-conflict
+        description: Check for files with names that would conflict on case-insensitive filesystems like MacOS/Windows.
+  - repo: https://github.com/jsh9/pydoclint
+    rev: 0.5.3
+    hooks:
+      - id: pydoclint
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: python
+        types: [python]

vicinity-0.1.0/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/Makefile

@@ -0,0 +1,15 @@
+clean:
+
+
+venv:
+	uv venv
+
+install: venv
+	uv sync --all-extras
+	uv run pre-commit install
+
+fix:
+	uv run pre-commit run --all-files
+
+test:
+	uv run pytest --cov=nearest --cov-report=term-missing

vicinity-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,146 @@
+<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/pyproject.toml

@@ -0,0 +1,94 @@
+[project]
+name = "vicinity"
+description = "Lightweight Nearest Neighbors with Flexible Backends"
+readme = { file = "README.md", content-type = "text/markdown" }
+dynamic = ["version"]
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Stéphan Tulkens", email = "stephantul@gmail.com"}, {name = "Thomas van Dongen", email = "thomas123@live.nl"}]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "numpy",
+    "orjson",
+    "tqdm"
+]
+
+[build-system]
+requires = ["setuptools>=64", "setuptools_scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "ipython",
+    "mypy",
+    "pre-commit",
+    "pytest",
+    "pytest-coverage",
+    "ruff",
+]
+hnsw = ["hnswlib"]
+
+[tool.ruff]
+exclude = [".venv/"]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    # Annotations: Enforce type annotations
+    "ANN",
+    # Complexity: Enforce a maximum cyclomatic complexity
+    "C90",
+    # Pydocstyle: Enforce docstrings
+    "D",
+    # Isort: Enforce import order
+    "I",
+    # Numpy: Enforce numpy style
+    "NPY",
+    # Print: Forbid print statements
+    "T20",
+]
+ignore = [
+    # Allow self and cls to be untyped, and allow Any type
+    "ANN101", "ANN102", "ANN401",
+    # Pydocstyle ignores
+    "D100", "D101", "D104", "D203", "D212", "D401",
+    # Allow use of f-strings in logging
+    "G004"
+]
+
+[tool.pydoclint]
+style = "sphinx"
+exclude = "test_"
+allow-init-docstring = true
+arg-type-hints-in-docstring = false
+check-return-types = false
+require-return-section-when-returning-nothing = false
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_configs = true
+ignore_missing_imports = true
+
+[tool.setuptools]
+packages = ["vicinity"]
+
+[tool.setuptools_scm]
+# can be empty if no extra settings are needed, presence enables setuptools_scm
+
+[tool.setuptools.dynamic]
+version = {attr = "vicinity.version.__version__"}

vicinity-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+