vicinity 0.4.3__tar.gz → 0.4.5__tar.gz

{vicinity-0.4.3 → vicinity-0.4.5}/.github/workflows/ci.yaml

@@ -12,10 +12,8 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12"]
         exclude:
-          - os: windows-latest
-            python-version: "3.9"
           - os: windows-latest
             python-version: "3.11"
           - os: windows-latest

vicinity-0.4.5/.github/workflows/release.yaml

@@ -0,0 +1,40 @@
+name: Release to PyPI
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0d8abe699bfb85fec6de9f7adb5ae17292296ff
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b

vicinity-0.4.5/CITATION.cff

@@ -0,0 +1,27 @@
+cff-version: 1.2.0
+message: "If you use Vicinity in your research, please cite it as below."
+title: "Vicinity: Lightweight Nearest Neighbors with Flexible Backends"
+authors:
+  - family-names: "Tulkens"
+    given-names: "Stephan"
+  - family-names: "van Dongen"
+    given-names: "Thomas"
+doi: 10.5281/zenodo.17265874
+license: MIT
+url: "https://github.com/MinishLab/vicinity"
+repository-code: "https://github.com/MinishLab/vicinity"
+date-released: "2024-11-09"
+
+preferred-citation:
+  type: software
+  title: "Vicinity: Lightweight Nearest Neighbors with Flexible Backends"
+  authors:
+    - family-names: "Tulkens"
+      given-names: "Stephan"
+    - family-names: "van Dongen"
+      given-names: "Thomas"
+  year: 2024
+  publisher: Zenodo
+  doi: 10.5281/zenodo.17265874
+  url: "https://github.com/MinishLab/vicinity"
+  license: MIT

{vicinity-0.4.3 → vicinity-0.4.5}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: vicinity
-Version: 0.4.3
+Version: 0.4.5
 Summary: Lightweight Nearest Neighbors with Flexible Backends
-Author-email: Stéphan Tulkens <stephantul@gmail.com>, Thomas van Dongen <thomas123@live.nl>
+Author-email: Stéphan Tulkens <stephantul@gmail.com>, Thomas van Dongen <thomasvdongen@proton.me>
 License: MIT License
         
         Copyright (c) 2024 The Minish Lab
@@ -35,11 +35,10 @@ 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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: numpy
 Requires-Dist: orjson
@@ -254,7 +253,7 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 |                 | `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"`             |
+| **USEARCH**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`). `hamming` and `tanimoto` take uint8 vectors bit-packed with `np.packbits`. | `"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`                |
@@ -294,3 +293,19 @@ pip install vicinity[voyager]
 ## License
 
 MIT
+
+## Citing
+
+If you use Vicinity in your research, please cite the following:
+
+```bibtex
+@software{minishlab2024vicinity,
+  author       = {Stephan Tulkens and {van Dongen}, Thomas},
+  title        = {Vicinity: Lightweight Nearest Neighbors with Flexible Backends},
+  year         = {2024},
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.17265874},
+  url          = {https://github.com/MinishLab/vicinity},
+  license      = {MIT}
+}
+```

{vicinity-0.4.3 → vicinity-0.4.5}/README.md

@@ -158,7 +158,7 @@ NOTE: the ANN backends do not support dynamic deletion. To delete items, you nee
 |                 | `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"`             |
+| **USEARCH**     | `metric`            | Similarity metric to use (`cos`, `ip`, `l2sq`, `hamming`, `tanimoto`). `hamming` and `tanimoto` take uint8 vectors bit-packed with `np.packbits`. | `"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`                |
@@ -198,3 +198,19 @@ pip install vicinity[voyager]
 ## License
 
 MIT
+
+## Citing
+
+If you use Vicinity in your research, please cite the following:
+
+```bibtex
+@software{minishlab2024vicinity,
+  author       = {Stephan Tulkens and {van Dongen}, Thomas},
+  title        = {Vicinity: Lightweight Nearest Neighbors with Flexible Backends},
+  year         = {2024},
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.17265874},
+  url          = {https://github.com/MinishLab/vicinity},
+  license      = {MIT}
+}
+```

{vicinity-0.4.3 → vicinity-0.4.5}/pyproject.toml

@@ -3,9 +3,9 @@ name = "vicinity"
 description = "Lightweight Nearest Neighbors with Flexible Backends"
 readme = { file = "README.md", content-type = "text/markdown" }
 dynamic = ["version"]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = { file = "LICENSE" }
-authors = [{ name = "Stéphan Tulkens", email = "stephantul@gmail.com"}, {name = "Thomas van Dongen", email = "thomas123@live.nl"}]
+authors = [{ name = "Stéphan Tulkens", email = "stephantul@gmail.com"}, {name = "Thomas van Dongen", email = "thomasvdongen@proton.me"}]
 
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -15,7 +15,6 @@ 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",
@@ -143,3 +142,6 @@ license-files = []
 
 [tool.setuptools.dynamic]
 version = {attr = "vicinity.version.__version__"}
+
+[tool.uv]
+exclude-newer = "1 week"

{vicinity-0.4.3 → vicinity-0.4.5}/tests/test_vicinity.py

@@ -333,3 +333,34 @@ def test_vicinity_evaluate(vicinity_instance: Vicinity, vectors: np.ndarray) ->
     vicinity_instance.backend.arguments.metric = "manhattan"
     with pytest.raises(ValueError):
         vicinity_instance.evaluate(vectors, query_vectors)
+
+
+@pytest.mark.parametrize("metric", ["hamming", "tanimoto"])
+def test_vicinity_usearch_binary_metrics(tmp_path: Path, metric: str) -> None:
+    """
+    Test that the usearch backend supports binary metrics on bit-packed vectors.
+
+    :param tmp_path: Temporary directory for saving and loading.
+    :param metric: The binary metric to use.
+    """
+    bits = np.random.default_rng(42).integers(0, 2, size=(50, 64)).astype(bool)
+    packed = np.packbits(bits, axis=1)
+    items = [str(i) for i in range(len(bits))]
+    vicinity = Vicinity.from_vectors_and_items(packed, items, backend_type=Backend.USEARCH, metric=metric)
+    assert vicinity.dim == packed.shape[1]
+
+    if metric == "hamming":
+        expected = (bits[0] != bits).sum(axis=1)
+    else:
+        expected = 1 - (bits[0] & bits).sum(axis=1) / (bits[0] | bits).sum(axis=1)
+    ((_, distance),) = vicinity.query(packed[:1], k=1)[0]
+    ((_, farthest),) = vicinity.query(packed[:1], k=len(items))[0][-1:]
+    assert distance == pytest.approx(0)
+    assert farthest == pytest.approx(expected.max(), abs=1e-5)
+
+    vicinity.insert(["new"], packed[:1])
+    vicinity.save(tmp_path / "binary")
+    assert Vicinity.load(tmp_path / "binary").query(packed[:1], k=3)[0] == vicinity.query(packed[:1], k=3)[0]
+
+    with pytest.raises(ValueError, match="bit-packed"):
+        Vicinity.from_vectors_and_items(bits.astype(np.float32), items, backend_type=Backend.USEARCH, metric=metric)