<h1 align="center">kANNolo</h1>
<p align="center">
<img width="300px" src="/imgs/kannolo_with_text.jpeg" />
</p>
<p align="center">
<a href="https://rdcu.be/eii62"><img src="https://badgen.net/static/paper/ECIR 2025/yellow"" /></a>
<a href="https://arxiv.org/abs/2501.06121"><img src="https://badgen.net/static/arXiv/2501.06121/red" /></a>
</p>
<p align="center">
<a href="https://crates.io/crates/kannolo"><img src="https://badgen.infra.medigy.com/crates/v/kannolo" /></a>
<a href="https://crates.io/crates/kannolo"><img src="https://badgen.infra.medigy.com/crates/d/kannolo" /></a>
<a href="LICENSE"><img src="https://badgen.net/static/license/MIT/blue" /></a>
</p>
<!--
<p align="center">
<a href="https://crates.io/crates/seismic"><img src="https://badgen.infra.medigy.com/crates/v/seismic" /></a>
<a href="https://crates.io/crates/seismic"><img src="https://badgen.infra.medigy.com/crates/d/seismic" /></a>
<a href="LICENSE.md"><img src="https://badgen.net/static/license/MIT/blue" /></a>
</p>
-->
kANNolo is a research-oriented library for Approximate Nearest Neighbors (ANN) search written in Rust 🦀. It is explicitly designed to combine usability with performance effectively. Designed with modularity and researchers in mind, kANNolo makes prototyping new ANN search algorithms and data structures easy. kANNolo supports both dense and sparse embeddings seamlessly. It implements the HNSW graph index and Product Quantization.
### Python - Maximum performance
If you want to compile the package optimized for your CPU, you need to install the package from the Source Distribution.
In order to do that you need to have the Rust toolchain installed. Use the following commands:
#### Prerequisites
Install Rust (via `rustup`):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
#### Installation
```bash
RUSTFLAGS="-C target-cpu=native" pip install --no-binary :all: kannolo
```
This will compile the Rust code tailored for your machine, providing maximum performance.
### Python - Easy installation
If you are not interested in obtaining the maximum performance, you can install the package from a prebuilt Wheel.
If a compatible wheel exists for your platform, `pip` will download and install it directly, avoiding the compilation phase.
If no compatible wheel exists, pip will download the source distribution and attempt to compile it using the Rust compiler (rustc).
```bash
pip install kannolo
```
Prebuilt wheels are available for Linux platforms (x86_64, i686, aarch64) with different Python implementation (CPython, PyPy) for linux distros using glibc 2.17 or later.
Wheels are also available x86_64 platforms with linux distros using musl 1.2 or later.
### Rust
This command allows you to compile all the Rust binaries contained in `src/bin`
```bash
RUSTFLAGS="-C target-cpu=native" cargo build --release
```
Details on how to use kANNolo's core engine in Rust 🦀 can be found in [`docs/RustUsage.md`](docs/RustUsage.md).
Details on how to use kANNolo's Python interface can be found in [`docs/PythonUsage.md`](docs/PythonUsage.md).
### Resources
Check out our `docs` folder for a more detailed guide on how to use kANNolo directly in Rust, replicate the results of our paper, or use kANNolo with your custom collection.
Disclaimer: The results in the paper are obtained with a direct-access table shared among threads to keep track of visited nodes. In the current version, this is substituted with a hash set, with the double goal of simplifying the code for users and to make it independent of the size of the dataset, a feature that one would like to enable when dealing with large datasets. This may affect performance.
### <a name="bib">📚 Bibliography</a>
Leonardo Delfino, Domenico Erriquez, Silvio Martinico, Franco Maria Nardini, Cosimo Rulli and Rossano Venturini. "*kANNolo: Sweet and Smooth Approximate k-Nearest Neighbors Search*." Proc. ECIR. 2025.
### Citation License
The source code in this repository is subject to the following citation license:
By downloading and using this software, you agree to cite the under-noted paper in any kind of material you produce where it was used to conduct a search or experimentation, whether be it a research paper, dissertation, article, poster, presentation, or documentation. By using this software, you have agreed to the citation license.
ECIR 2025
```bibtex
@InProceedings{10.1007/978-3-031-88717-8_29,
author = "Leonardo Delfino and
Domenico Erriquez and
Silvio Martinico and
Franco Maria Nardini and
Cosimo Rulli and
Rossano Venturini",
title = "kANNolo: Sweet and Smooth Approximate k-Nearest Neighbors Search",
booktitle = "Advances in Information Retrieval",
year = "2025",
publisher = "Springer Nature Switzerland",
pages = "400--406",
isbn = "978-3-031-88717-8"
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "kannolo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "Approximate Nearest Neighbors, Similarity Search, indexing, Rust",
"author": null,
"author_email": "Silvio Martinico <silvio.martinico@phd.unipi.it>, Leonardo Delfino <l.delfino1@studenti.unipi.it>, Domenico Erriquez <d.erriquez1@studenti.unipi.it>, Cosimo Rulli <cosimo.rulli@isti.cnr.it>, Franco Maria Nardini <francomaria.nardini@isti.cnr.it>, Rossano Venturini <rossano.venturini@unipi.it>",
"download_url": "https://files.pythonhosted.org/packages/38/8f/1d9cef4d8c59ddbb5a2ef8aa3dd477214feb68b0d62240a53d33c9fd1034/kannolo-0.3.1.tar.gz",
"platform": null,
"description": "\n\n<h1 align=\"center\">kANNolo</h1>\n<p align=\"center\">\n <img width=\"300px\" src=\"/imgs/kannolo_with_text.jpeg\" />\n</p>\n\n<p align=\"center\">\n <a href=\"https://rdcu.be/eii62\"><img src=\"https://badgen.net/static/paper/ECIR 2025/yellow\"\" /></a> \n <a href=\"https://arxiv.org/abs/2501.06121\"><img src=\"https://badgen.net/static/arXiv/2501.06121/red\" /></a>\n</p>\n\n<p align=\"center\"> \n <a href=\"https://crates.io/crates/kannolo\"><img src=\"https://badgen.infra.medigy.com/crates/v/kannolo\" /></a>\n <a href=\"https://crates.io/crates/kannolo\"><img src=\"https://badgen.infra.medigy.com/crates/d/kannolo\" /></a>\n <a href=\"LICENSE\"><img src=\"https://badgen.net/static/license/MIT/blue\" /></a>\n</p>\n\n<!--\n<p align=\"center\"> \n <a href=\"https://crates.io/crates/seismic\"><img src=\"https://badgen.infra.medigy.com/crates/v/seismic\" /></a>\n <a href=\"https://crates.io/crates/seismic\"><img src=\"https://badgen.infra.medigy.com/crates/d/seismic\" /></a>\n <a href=\"LICENSE.md\"><img src=\"https://badgen.net/static/license/MIT/blue\" /></a>\n</p>\n\n-->\n\nkANNolo is a research-oriented library for Approximate Nearest Neighbors (ANN) search written in Rust \ud83e\udd80. It is explicitly designed to combine usability with performance effectively. Designed with modularity and researchers in mind, kANNolo makes prototyping new ANN search algorithms and data structures easy. kANNolo supports both dense and sparse embeddings seamlessly. It implements the HNSW graph index and Product Quantization.\n\n\n### Python - Maximum performance\nIf you want to compile the package optimized for your CPU, you need to install the package from the Source Distribution.\nIn order to do that you need to have the Rust toolchain installed. Use the following commands:\n#### Prerequisites\nInstall Rust (via `rustup`):\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n```\n#### Installation\n```bash\nRUSTFLAGS=\"-C target-cpu=native\" pip install --no-binary :all: kannolo\n```\nThis will compile the Rust code tailored for your machine, providing maximum performance.\n\n### Python - Easy installation\nIf you are not interested in obtaining the maximum performance, you can install the package from a prebuilt Wheel.\nIf a compatible wheel exists for your platform, `pip` will download and install it directly, avoiding the compilation phase.\nIf no compatible wheel exists, pip will download the source distribution and attempt to compile it using the Rust compiler (rustc).\n```bash\npip install kannolo\n```\n\nPrebuilt wheels are available for Linux platforms (x86_64, i686, aarch64) with different Python implementation (CPython, PyPy) for linux distros using glibc 2.17 or later.\nWheels are also available x86_64 platforms with linux distros using musl 1.2 or later.\n\n### Rust \n\nThis command allows you to compile all the Rust binaries contained in `src/bin`\n\n```bash\nRUSTFLAGS=\"-C target-cpu=native\" cargo build --release\n```\n\nDetails on how to use kANNolo's core engine in Rust \ud83e\udd80 can be found in [`docs/RustUsage.md`](docs/RustUsage.md).\n\nDetails on how to use kANNolo's Python interface can be found in [`docs/PythonUsage.md`](docs/PythonUsage.md).\n\n\n### Resources\nCheck out our `docs` folder for a more detailed guide on how to use kANNolo directly in Rust, replicate the results of our paper, or use kANNolo with your custom collection. \n\nDisclaimer: The results in the paper are obtained with a direct-access table shared among threads to keep track of visited nodes. In the current version, this is substituted with a hash set, with the double goal of simplifying the code for users and to make it independent of the size of the dataset, a feature that one would like to enable when dealing with large datasets. This may affect performance.\n\n### <a name=\"bib\">\ud83d\udcda Bibliography</a>\nLeonardo Delfino, Domenico Erriquez, Silvio Martinico, Franco Maria Nardini, Cosimo Rulli and Rossano Venturini. \"*kANNolo: Sweet and Smooth Approximate k-Nearest Neighbors Search*.\" Proc. ECIR. 2025.\n\n\n### Citation License\nThe source code in this repository is subject to the following citation license:\n\nBy downloading and using this software, you agree to cite the under-noted paper in any kind of material you produce where it was used to conduct a search or experimentation, whether be it a research paper, dissertation, article, poster, presentation, or documentation. By using this software, you have agreed to the citation license.\n\n\nECIR 2025\n```bibtex\n@InProceedings{10.1007/978-3-031-88717-8_29,\nauthor = \"Leonardo Delfino and\n Domenico Erriquez and\n Silvio Martinico and\n Franco Maria Nardini and\n Cosimo Rulli and\n Rossano Venturini\",\ntitle = \"kANNolo: Sweet and\u00a0Smooth Approximate k-Nearest Neighbors Search\",\nbooktitle = \"Advances in Information Retrieval\",\nyear = \"2025\",\npublisher = \"Springer Nature Switzerland\",\npages = \"400--406\",\nisbn = \"978-3-031-88717-8\"\n}\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python interface for the kANNolo library",
"version": "0.3.1",
"project_urls": {
"Source Code": "https://github.com/TusKANNy/kannolo"
},
"split_keywords": [
"approximate nearest neighbors",
" similarity search",
" indexing",
" rust"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bac65bf9dc66518ce55f02622252e66ffbba247e03e2195e54e8a9af88e3af4f",
"md5": "b63afc60aadad24aa313640d75319843",
"sha256": "820fa0a6f4d10d818de6dca2f1f9fa868c25f8331c1674c1c06db169d711b5c2"
},
"downloads": -1,
"filename": "kannolo-0.3.1-cp312-cp312-manylinux_2_34_x86_64.whl",
"has_sig": false,
"md5_digest": "b63afc60aadad24aa313640d75319843",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.7",
"size": 795340,
"upload_time": "2025-08-16T17:56:32",
"upload_time_iso_8601": "2025-08-16T17:56:32.266886Z",
"url": "https://files.pythonhosted.org/packages/ba/c6/5bf9dc66518ce55f02622252e66ffbba247e03e2195e54e8a9af88e3af4f/kannolo-0.3.1-cp312-cp312-manylinux_2_34_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "388f1d9cef4d8c59ddbb5a2ef8aa3dd477214feb68b0d62240a53d33c9fd1034",
"md5": "278c99f7a26dd7562156edcf0873e387",
"sha256": "4779bc92815090eaf8031090dc7841c2eaeaa0d15a5fb18f17224246d231f019"
},
"downloads": -1,
"filename": "kannolo-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "278c99f7a26dd7562156edcf0873e387",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 648668,
"upload_time": "2025-08-16T17:56:34",
"upload_time_iso_8601": "2025-08-16T17:56:34.683337Z",
"url": "https://files.pythonhosted.org/packages/38/8f/1d9cef4d8c59ddbb5a2ef8aa3dd477214feb68b0d62240a53d33c9fd1034/kannolo-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 17:56:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "TusKANNy",
"github_project": "kannolo",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "kannolo"
}
JSON
