# async-annoy README
## Overview
`async-annoy` simplifies working with Annoy indices in async applications like web servers. It's built to let you read from or write to Annoy indices without worrying about the complexities of concurrent access. You get easy, thread-safe operations, whether you're querying nearest neighbors or building the index, all in the background.
## Features
- **Automated Index Management**: Handles all the tricky parts of managing Annoy indices on disk.
- **Concurrency Made Simple**: Supports multiple readers at once or a single writer by managing access locks behind the scenes.
## Installation
```bash
pip install async-annoy
```
Make sure Annoy and numpy are installed as they're needed to run the library.
## How to Use
### Reading from the Index
Ideal for fetching nearest neighbors in response to web requests.
```python
from async_annoy import AsyncAnnoy
async with AsyncAnnoy("my_index").reader() as reader:
neighbours = await reader.get_neighbours_for(vector=my_vector, n=5)
print(neighbours)
```
### Writing to the Index
The writer will wait for all readers to finish and start the index from scratch.
The Annoy library doesn't support index updates, only rebuilds.
```python
from async_annoy import AsyncAnnoy
async with AsyncAnnoy("my_index").writer() as writer:
await writer.add_item(index=1, vector=my_vector)
# The index is automatically built and saved when done.
```
## Configuration
The initial setup of `async-annoy` relies on environment variables to configure the Annoy index parameters, ensuring a seamless start. While these defaults offer convenience, you may need to customize settings to fit your application's specific requirements. It's critical to maintain parameter consistency across all readers and writers interacting with the same index.
### Default Parameters
`async-annoy` uses the following environment variables for initial configuration:
- `ASYNC_ANNOY_DIMENSIONS`: The dimensionality of the vectors stored in the index.
- `ASYNC_ANNOY_METRIC`: The distance metric used for comparing vectors in the index (e.g., "angular", "euclidean").
### Overriding Default Parameters
Although `async-annoy` configures itself with environment variables, you can override these defaults directly in your code. When creating a new `AnnoyReader` or `AnnoyWriter`, simply pass the desired dimensions and metric as arguments:
```python
from async_annoy import AsyncAnnoy
# Override default parameters when initializing
index_manager = AsyncAnnoy("my_index", dimensions=128, metric="euclidean")
```
## Development Status
Currently, async-annoy is in alpha. It's ready for testing, and we're eager for your feedback to make it better. This is an initial version, so we're still working on adding more features and smoothing out the experience.
Raw data
{
"_id": null,
"home_page": "https://github.com/ryzhakar/async-annoy",
"name": "async-annoy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "annoy,asynchronous,nearest neighbors,semantic search,vector database,search,aiorwlock",
"author": "Arthur Ryzhak",
"author_email": "ryzhakar@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f5/41/dd0e991673937db71c116975e7a6acc71f95f5dbca863d282f2a263cfcc9/async_annoy-0.2.0.tar.gz",
"platform": null,
"description": "# async-annoy README\n\n## Overview\n`async-annoy` simplifies working with Annoy indices in async applications like web servers. It's built to let you read from or write to Annoy indices without worrying about the complexities of concurrent access. You get easy, thread-safe operations, whether you're querying nearest neighbors or building the index, all in the background.\n\n## Features\n- **Automated Index Management**: Handles all the tricky parts of managing Annoy indices on disk.\n- **Concurrency Made Simple**: Supports multiple readers at once or a single writer by managing access locks behind the scenes.\n\n## Installation\n```bash\npip install async-annoy\n```\nMake sure Annoy and numpy are installed as they're needed to run the library.\n\n## How to Use\n### Reading from the Index\nIdeal for fetching nearest neighbors in response to web requests.\n```python\nfrom async_annoy import AsyncAnnoy\n\nasync with AsyncAnnoy(\"my_index\").reader() as reader:\n neighbours = await reader.get_neighbours_for(vector=my_vector, n=5)\n print(neighbours)\n```\n### Writing to the Index\nThe writer will wait for all readers to finish and start the index from scratch.\nThe Annoy library doesn't support index updates, only rebuilds.\n```python\nfrom async_annoy import AsyncAnnoy\n\nasync with AsyncAnnoy(\"my_index\").writer() as writer:\n await writer.add_item(index=1, vector=my_vector)\n # The index is automatically built and saved when done.\n```\n## Configuration\nThe initial setup of `async-annoy` relies on environment variables to configure the Annoy index parameters, ensuring a seamless start. While these defaults offer convenience, you may need to customize settings to fit your application's specific requirements. It's critical to maintain parameter consistency across all readers and writers interacting with the same index.\n\n### Default Parameters\n`async-annoy` uses the following environment variables for initial configuration:\n- `ASYNC_ANNOY_DIMENSIONS`: The dimensionality of the vectors stored in the index.\n- `ASYNC_ANNOY_METRIC`: The distance metric used for comparing vectors in the index (e.g., \"angular\", \"euclidean\").\n\n### Overriding Default Parameters\nAlthough `async-annoy` configures itself with environment variables, you can override these defaults directly in your code. When creating a new `AnnoyReader` or `AnnoyWriter`, simply pass the desired dimensions and metric as arguments:\n\n```python\nfrom async_annoy import AsyncAnnoy\n\n# Override default parameters when initializing\nindex_manager = AsyncAnnoy(\"my_index\", dimensions=128, metric=\"euclidean\")\n```\n\n## Development Status\nCurrently, async-annoy is in alpha. It's ready for testing, and we're eager for your feedback to make it better. This is an initial version, so we're still working on adding more features and smoothing out the experience.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Asynchronous wrapper around the Annoy library for approximate nearest neighbor search.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/ryzhakar/async-annoy",
"Repository": "https://github.com/ryzhakar/async-annoy"
},
"split_keywords": [
"annoy",
"asynchronous",
"nearest neighbors",
"semantic search",
"vector database",
"search",
"aiorwlock"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f00385d5b8046e3811b64cab45761185caa4e65284982056e035b2fc1464dde",
"md5": "00fe2a16c3d3a980a47cbeeb8d223abf",
"sha256": "5d0c027bb6891e1d1bdf220b0bd180987e3f400eaf40d2c2ab25cf857004c8d0"
},
"downloads": -1,
"filename": "async_annoy-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00fe2a16c3d3a980a47cbeeb8d223abf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 5309,
"upload_time": "2024-03-18T16:36:54",
"upload_time_iso_8601": "2024-03-18T16:36:54.833759Z",
"url": "https://files.pythonhosted.org/packages/8f/00/385d5b8046e3811b64cab45761185caa4e65284982056e035b2fc1464dde/async_annoy-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f541dd0e991673937db71c116975e7a6acc71f95f5dbca863d282f2a263cfcc9",
"md5": "2cdff5cef705b5d4f48218cb0499b746",
"sha256": "e8cd2db57261edda95e4af3c3f73e795044e35a071101c878723cca19dd7ed5d"
},
"downloads": -1,
"filename": "async_annoy-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "2cdff5cef705b5d4f48218cb0499b746",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 4619,
"upload_time": "2024-03-18T16:36:56",
"upload_time_iso_8601": "2024-03-18T16:36:56.896796Z",
"url": "https://files.pythonhosted.org/packages/f5/41/dd0e991673937db71c116975e7a6acc71f95f5dbca863d282f2a263cfcc9/async_annoy-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-18 16:36:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ryzhakar",
"github_project": "async-annoy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "async-annoy"
}
JSON
