| Name | aquiles-rag JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | Aquiles-RAG is a high-performance Retrieval-Augmented Generation (RAG) solution built on Redis. It offers a high-level interface through FastAPI REST APIs |
| upload_time | 2025-07-25 22:22:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Apache License 2.0 |
| keywords |
fastapi
ai
rag
vector-database
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">Aquiles‑RAG</h1>
<div align="center">
<img src="aquiles/static/aq-rag2.png" alt="Aquiles‑RAG Logo" width="200"/>
</div>
<p align="center">
<strong>High‑performance Retrieval‑Augmented Generation (RAG) on Redis</strong><br/>
🚀 FastAPI • Redis Vector Search • Async • Embedding‑agnostic
</p>
<p align="center">
<a href="https://aquiles-ai.github.io/aqRAG-docs/">📖 Documentation</a>
</p>
## 📑 Table of Contents
1. [Features](#features)
2. [Tech Stack](#tech-stack)
3. [Requirements](#requirements)
4. [Installation](#installation)
5. [Configuration & Connection Options](#configuration--connection-options)
6. [Usage](#usage)
* [CLI](#cli)
* [REST API](#rest-api)
* [Python Client](#python-client)
* [UI Playground](#ui-playground)
7. [Architecture](#architecture)
8. [License](#license)
## ⭐ Features
* 📈 **High Performance**: Redis-powered vector search using HNSW.
* 🛠️ **Simple API**: Endpoints for index creation, insertion, and querying.
* 🔌 **Embedding‑agnostic**: Works with any embedding model (OpenAI, Llama 3, etc.).
* 💻 **Integrated CLI**: Configure and serve with built‑in commands.
* 🧩 **Extensible**: Ready to integrate into ML pipelines or microservices.
## 🛠 Tech Stack
* **Python 3.9+**
* [FastAPI](https://fastapi.tiangolo.com/)
* [Redis](https://redis.io/) + \[`redis-py` async / cluster]
* [NumPy](https://numpy.org/)
* [Pydantic](https://pydantic-docs.helpmanual.io/)
* [Jinja2](https://jinja.palletsprojects.com/)
* [Click](https://click.palletsprojects.com/) (CLI)
* [Requests](https://docs.python-requests.org/) (Python client)
* [Platformdirs](https://github.com/platformdirs/platformdirs) (config management)
## ⚙️ Requirements
1. **Redis** (standalone or cluster)
2. **Python 3.9+**
3. **pip**
> **Optional**: Run Redis with Docker:
>
> ```bash
> docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest
> ```
## 🚀 Installation
### Via PyPI
The easiest way is to install directly from PyPI:
```bash
pip install aquiles-rag
```
### From Source (optional)
If you’d like to work from the latest code or contribute:
1. Clone the repository and navigate into it:
```bash
git clone https://github.com/Aquiles-ai/Aquiles-RAG.git
cd Aquiles-RAG
```
2. Create a virtual environment and install dependencies:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
3. (Optional) Install in editable/development mode:
```bash
pip install -e .
```
## 🔧 Configuration & Connection Options
Aquiles‑RAG stores its configuration in:
```
~/.local/share/aquiles/aquiles_config.json
```
By default, it uses:
```json
{
"local": true,
"host": "localhost",
"port": 6379,
"username": "",
"password": "",
"cluster_mode": false,
"tls_mode": false,
"ssl_certfile": "",
"ssl_keyfile": "",
"ssl_ca_certs": "",
"allows_api_keys": [""],
"allows_users": [{"username": "root", "password": "root"}]
}
```
You can modify the config file manually or use the CLI:
```bash
aquiles-rag configs --host redis.example.com --port 6380 --username user --password pass
```
### Redis Connection Modes
Aquiles‑RAG supports four modes to connect to Redis, based on your config:
1. **Local Cluster** (`local=true` & `cluster_mode=true`)
```python
RedisCluster(host=host, port=port, decode_responses=True)
```
2. **Standalone Local** (`local=true`)
```python
redis.Redis(host=host, port=port, decode_responses=True)
```
3. **Remote with TLS/SSL** (`local=false`, `tls_mode=true`)
```python
redis.Redis(
host=host,
port=port,
username=username or None,
password=password or None,
ssl=True,
decode_responses=True,
ssl_certfile=ssl_certfile, # if provided
ssl_keyfile=ssl_keyfile, # if provided
ssl_ca_certs=ssl_ca_certs # if provided
)
```
4. **Remote without TLS/SSL** (`local=false`, `tls_mode=false`)
```python
redis.Redis(
host=host,
port=port,
username=username or None,
password=password or None,
decode_responses=True
)
```
These options give full flexibility to connect to any Redis topology securely.
## 📖 Usage
### CLI
* **Save configs**
```bash
aquiles-rag configs --host "127.0.0.1" --port 6379
```
* **Serve the API**
```bash
aquiles-rag serve --host "0.0.0.0" --port 5500
```
* **Deploy custom config**
```bash
aquiles-rag deploy --host "0.0.0.0" --port 5500 my_config.py
```
### REST API
1. **Create Index**
```bash
curl -X POST http://localhost:5500/create/index \
-H "X-API-Key: YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"indexname": "documents",
"embeddings_dim": 768,
"dtype": "FLOAT32",
"delete_the_index_if_it_exists": false
}'
```
2. **Insert Chunk**
```bash
curl -X POST http://localhost:5500/rag/create \
-H "X-API-Key: YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"index": "documents",
"name_chunk": "doc1_part1",
"dtype": "FLOAT32",
"chunk_size": 1024,
"raw_text": "Text of the chunk...",
"embeddings": [0.12, 0.34, 0.56, ...]
}'
```
3. **Query Top‑K**
```bash
curl -X POST http://localhost:5500/rag/query-rag \
-H "X-API-Key: YOUR_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"index": "documents",
"embeddings": [0.78, 0.90, ...],
"dtype": "FLOAT32",
"top_k": 5,
"cosine_distance_threshold": 0.6
}'
```
### Python Client
```python
from aquiles.client import AquilesRAG
client = AquilesRAG(host="http://127.0.0.1:5500", api_key="YOUR_API_KEY")
# Create an index
client.create_index("documents", embeddings_dim=768, dtype="FLOAT32")
# Insert chunks using your embedding function
def get_embedding(text):
# e.g. call OpenAI, Llama3, etc.
return embedding_model.encode(text)
responses = client.send_rag(
embedding_func=get_embedding,
index="documents",
name_chunk="doc1",
raw_text=full_text
)
# Query the index
results = client.query("documents", query_embedding, top_k=5)
print(results)
```
### UI Playground
Access the web UI (with basic auth) at:
```
http://localhost:5500/ui
```
Use it to:
* Edit configurations live
* Test `/create/index`, `/rag/create`, `/rag/query-rag`
* Explore protected Swagger UI & ReDoc docs
#### 🚀 Screenshots
1. **Playground Home**
2. **Live Configurations**
3. **Creating an Index**
4. **Adding Data to RAG**
5. **Querying RAG Results**
## 🏗 Architecture
The following diagram shows the high‑level architecture of Aquiles‑RAG:
1. **Clients** (HTTP/HTTPS, Python SDK, or UI Playground) make asynchronous HTTP requests.
2. **FastAPI Server** acts as the orchestration and business‑logic layer, validating requests and translating them to vector store commands.
3. **Redis / RedisCluster** serves as the RAG vector store (HASH + HNSW/COSINE search).
> ***Test Suite***\*: See the **`test/`** direct\*ory for automated tests:
>
> * **client tests** for the Python SDK
> * **API tests** for endpoint behavior
> * **test\_deploy.py** for deployment configuration and startup validation
## 📄 License
[MIT License](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "aquiles-rag",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fastapi, ai, rag, vector-database",
"author": null,
"author_email": "Aquiles-ai / Fredy <riveraaai200678@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/45/bc/b5fb323e8163c9674676be33625d043e3602c2eb5620e8fe14740bf916c9/aquiles_rag-0.2.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">Aquiles\u2011RAG</h1>\n\n<div align=\"center\">\n <img src=\"aquiles/static/aq-rag2.png\" alt=\"Aquiles\u2011RAG Logo\" width=\"200\"/>\n</div>\n\n<p align=\"center\">\n <strong>High\u2011performance Retrieval\u2011Augmented Generation (RAG) on Redis</strong><br/>\n \ud83d\ude80 FastAPI \u2022 Redis Vector Search \u2022 Async \u2022 Embedding\u2011agnostic\n</p>\n\n<p align=\"center\">\n <a href=\"https://aquiles-ai.github.io/aqRAG-docs/\">\ud83d\udcd6 Documentation</a>\n</p>\n\n\n\n## \ud83d\udcd1 Table of Contents\n\n1. [Features](#features)\n2. [Tech Stack](#tech-stack)\n3. [Requirements](#requirements)\n4. [Installation](#installation)\n5. [Configuration & Connection Options](#configuration--connection-options)\n6. [Usage](#usage)\n\n * [CLI](#cli)\n * [REST API](#rest-api)\n * [Python Client](#python-client)\n * [UI Playground](#ui-playground)\n7. [Architecture](#architecture)\n8. [License](#license)\n\n\n## \u2b50 Features\n\n* \ud83d\udcc8 **High Performance**: Redis-powered vector search using HNSW.\n* \ud83d\udee0\ufe0f **Simple API**: Endpoints for index creation, insertion, and querying.\n* \ud83d\udd0c **Embedding\u2011agnostic**: Works with any embedding model (OpenAI, Llama 3, etc.).\n* \ud83d\udcbb **Integrated CLI**: Configure and serve with built\u2011in commands.\n* \ud83e\udde9 **Extensible**: Ready to integrate into ML pipelines or microservices.\n\n\n## \ud83d\udee0 Tech Stack\n\n* **Python\u00a03.9+**\n* [FastAPI](https://fastapi.tiangolo.com/)\n* [Redis](https://redis.io/) + \\[`redis-py` async / cluster]\n* [NumPy](https://numpy.org/)\n* [Pydantic](https://pydantic-docs.helpmanual.io/)\n* [Jinja2](https://jinja.palletsprojects.com/)\n* [Click](https://click.palletsprojects.com/) (CLI)\n* [Requests](https://docs.python-requests.org/) (Python client)\n* [Platformdirs](https://github.com/platformdirs/platformdirs) (config management)\n\n\n## \u2699\ufe0f Requirements\n\n1. **Redis** (standalone or cluster)\n2. **Python\u00a03.9+**\n3. **pip**\n\n> **Optional**: Run Redis with Docker:\n>\n> ```bash\n> docker run -d --name redis-stack -p 6379:6379 redis/redis-stack-server:latest\n> ```\n\n\n## \ud83d\ude80 Installation\n\n### Via PyPI\n\nThe easiest way is to install directly from PyPI:\n\n```bash\npip install aquiles-rag\n```\n\n### From Source (optional)\n\nIf you\u2019d like to work from the latest code or contribute:\n\n1. Clone the repository and navigate into it:\n\n ```bash\n git clone https://github.com/Aquiles-ai/Aquiles-RAG.git\n cd Aquiles-RAG\n ```\n\n2. Create a virtual environment and install dependencies:\n\n ```bash\n python -m venv .venv\n source .venv/bin/activate\n pip install -r requirements.txt\n ```\n\n3. (Optional) Install in editable/development mode:\n\n ```bash\n pip install -e .\n ```\n\n\n## \ud83d\udd27 Configuration & Connection Options\n\nAquiles\u2011RAG stores its configuration in:\n\n```\n~/.local/share/aquiles/aquiles_config.json\n```\n\nBy default, it uses:\n\n```json\n{\n \"local\": true,\n \"host\": \"localhost\",\n \"port\": 6379,\n \"username\": \"\",\n \"password\": \"\",\n \"cluster_mode\": false,\n \"tls_mode\": false,\n \"ssl_certfile\": \"\",\n \"ssl_keyfile\": \"\",\n \"ssl_ca_certs\": \"\",\n \"allows_api_keys\": [\"\"],\n \"allows_users\": [{\"username\": \"root\", \"password\": \"root\"}]\n}\n```\n\nYou can modify the config file manually or use the CLI:\n\n```bash\naquiles-rag configs --host redis.example.com --port 6380 --username user --password pass\n```\n\n### Redis Connection Modes\n\nAquiles\u2011RAG supports four modes to connect to Redis, based on your config:\n\n1. **Local Cluster** (`local=true` & `cluster_mode=true`)\n\n ```python\n RedisCluster(host=host, port=port, decode_responses=True)\n ```\n\n2. **Standalone Local** (`local=true`)\n\n ```python\n redis.Redis(host=host, port=port, decode_responses=True)\n ```\n\n3. **Remote with TLS/SSL** (`local=false`, `tls_mode=true`)\n\n ```python\n redis.Redis(\n host=host,\n port=port,\n username=username or None,\n password=password or None,\n ssl=True,\n decode_responses=True,\n ssl_certfile=ssl_certfile, # if provided\n ssl_keyfile=ssl_keyfile, # if provided\n ssl_ca_certs=ssl_ca_certs # if provided\n )\n ```\n\n4. **Remote without TLS/SSL** (`local=false`, `tls_mode=false`)\n\n ```python\n redis.Redis(\n host=host,\n port=port,\n username=username or None,\n password=password or None,\n decode_responses=True\n )\n ```\n\nThese options give full flexibility to connect to any Redis topology securely.\n\n## \ud83d\udcd6 Usage\n\n### CLI\n\n* **Save configs**\n\n ```bash\n aquiles-rag configs --host \"127.0.0.1\" --port 6379\n ```\n\n* **Serve the API**\n\n ```bash\n aquiles-rag serve --host \"0.0.0.0\" --port 5500\n ```\n\n* **Deploy custom config**\n\n ```bash\n aquiles-rag deploy --host \"0.0.0.0\" --port 5500 my_config.py\n ```\n\n### REST API\n\n1. **Create Index**\n\n ```bash\n curl -X POST http://localhost:5500/create/index \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"indexname\": \"documents\",\n \"embeddings_dim\": 768,\n \"dtype\": \"FLOAT32\",\n \"delete_the_index_if_it_exists\": false\n }'\n ```\n\n2. **Insert Chunk**\n\n ```bash\n curl -X POST http://localhost:5500/rag/create \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"index\": \"documents\",\n \"name_chunk\": \"doc1_part1\",\n \"dtype\": \"FLOAT32\",\n \"chunk_size\": 1024,\n \"raw_text\": \"Text of the chunk...\",\n \"embeddings\": [0.12, 0.34, 0.56, ...]\n }'\n ```\n\n3. **Query Top\u2011K**\n\n ```bash\n curl -X POST http://localhost:5500/rag/query-rag \\\n -H \"X-API-Key: YOUR_API_KEY\" \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"index\": \"documents\",\n \"embeddings\": [0.78, 0.90, ...],\n \"dtype\": \"FLOAT32\",\n \"top_k\": 5,\n \"cosine_distance_threshold\": 0.6\n }'\n ```\n\n### Python Client\n\n```python\nfrom aquiles.client import AquilesRAG\n\nclient = AquilesRAG(host=\"http://127.0.0.1:5500\", api_key=\"YOUR_API_KEY\")\n\n# Create an index\nclient.create_index(\"documents\", embeddings_dim=768, dtype=\"FLOAT32\")\n\n# Insert chunks using your embedding function\ndef get_embedding(text):\n # e.g. call OpenAI, Llama3, etc.\n return embedding_model.encode(text)\n\nresponses = client.send_rag(\n embedding_func=get_embedding,\n index=\"documents\",\n name_chunk=\"doc1\",\n raw_text=full_text\n)\n\n# Query the index\nresults = client.query(\"documents\", query_embedding, top_k=5)\nprint(results)\n```\n\n### UI Playground\n\nAccess the web UI (with basic auth) at:\n\n```\nhttp://localhost:5500/ui\n```\n\n\nUse it to:\n\n* Edit configurations live\n* Test `/create/index`, `/rag/create`, `/rag/query-rag`\n* Explore protected Swagger UI & ReDoc docs\n\n#### \ud83d\ude80 Screenshots\n\n1. **Playground Home** \n \n\n2. **Live Configurations** \n \n\n3. **Creating an Index** \n \n\n4. **Adding Data to RAG** \n \n\n5. **Querying RAG Results** \n \n\n\n## \ud83c\udfd7 Architecture\n\nThe following diagram shows the high\u2011level architecture of Aquiles\u2011RAG:\n\n\n\n1. **Clients** (HTTP/HTTPS, Python SDK, or UI Playground) make asynchronous HTTP requests.\n2. **FastAPI Server** acts as the orchestration and business\u2011logic layer, validating requests and translating them to vector store commands.\n3. **Redis / RedisCluster** serves as the RAG vector store (HASH + HNSW/COSINE search).\n\n> ***Test Suite***\\*: See the **`test/`** direct\\*ory for automated tests:\n>\n> * **client tests** for the Python SDK\n> * **API tests** for endpoint behavior\n> * **test\\_deploy.py** for deployment configuration and startup validation\n\n\n## \ud83d\udcc4 License\n\n[MIT License](LICENSE)\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Aquiles-RAG is a high-performance Retrieval-Augmented Generation (RAG) solution built on Redis. It offers a high-level interface through FastAPI REST APIs",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/Aquiles-ai/Aquiles-RAG",
"Issues": "https://github.com/Aquiles-ai/Aquiles-RAG/issues"
},
"split_keywords": [
"fastapi",
" ai",
" rag",
" vector-database"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d66ae5dd0547bf6215222a386f7c0f83dff3b5a29c46bde00c053e3233956077",
"md5": "ffd0ce6bc6a68753b93fb9aa56af19a5",
"sha256": "9c1b04ab2787a1bf4bb451267a93afaac918cb9ce9c015657aeca198a00d0695"
},
"downloads": -1,
"filename": "aquiles_rag-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ffd0ce6bc6a68753b93fb9aa56af19a5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 1039239,
"upload_time": "2025-07-25T22:22:22",
"upload_time_iso_8601": "2025-07-25T22:22:22.637831Z",
"url": "https://files.pythonhosted.org/packages/d6/6a/e5dd0547bf6215222a386f7c0f83dff3b5a29c46bde00c053e3233956077/aquiles_rag-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "45bcb5fb323e8163c9674676be33625d043e3602c2eb5620e8fe14740bf916c9",
"md5": "3684125afcff1e3b69ae4920a98e0652",
"sha256": "b42c3b26d87cee12c60f294ab42597f54a3e7c94f94a4298394ba48a136ce3b2"
},
"downloads": -1,
"filename": "aquiles_rag-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "3684125afcff1e3b69ae4920a98e0652",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1057485,
"upload_time": "2025-07-25T22:22:24",
"upload_time_iso_8601": "2025-07-25T22:22:24.206655Z",
"url": "https://files.pythonhosted.org/packages/45/bc/b5fb323e8163c9674676be33625d043e3602c2eb5620e8fe14740bf916c9/aquiles_rag-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 22:22:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Aquiles-ai",
"github_project": "Aquiles-RAG",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "aquiles-rag"
}
