Metadata-Version: 2.4
Name: vss_ctx_rag
Version: 0.5.0
Project-URL: Homepage, https://github.com/NVIDIA/context-aware-rag
Project-URL: Documentation, https://nvidia.github.io/context-aware-rag/index.html
Project-URL: Repository, https://github.com/NVIDIA/context-aware-rag
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.3rdparty
Requires-Dist: openai<2.0.0,>=1.68.2
Requires-Dist: langchain_core==0.3.21
Requires-Dist: langchain==0.3.3
Requires-Dist: langchain_community==0.3.2
Requires-Dist: langchain_milvus==0.1.5
Requires-Dist: langchain-openai==0.2.2
Requires-Dist: langchain-experimental==0.3.2
Requires-Dist: langchain-nvidia-ai-endpoints==0.3.7
Requires-Dist: pymilvus==2.4.4
Requires-Dist: pydantic==2.10.6
Requires-Dist: uvicorn<0.31.0,>=0.30.5
Requires-Dist: fastapi<0.116.0,>=0.115.4
Requires-Dist: requests<2.33.0,>=2.32.3
Requires-Dist: jsonschema<4.23.0,>=4.22.0
Requires-Dist: schema<0.8.0,>=0.7.7
Requires-Dist: neo4j==5.24
Requires-Dist: json-repair==0.30.2
Requires-Dist: opentelemetry-sdk>=1.28.2
Requires-Dist: opentelemetry-api>=1.28.2
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.28.2
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.49b2
Requires-Dist: nvtx==0.2.10
Requires-Dist: matplotlib==3.10.0
Provides-Extra: docs
Requires-Dist: ipython~=8.31; extra == "docs"
Requires-Dist: myst-parser~=4.0; extra == "docs"
Requires-Dist: nbsphinx~=0.9; extra == "docs"
Requires-Dist: nvidia-sphinx-theme>=0.0.7; extra == "docs"
Requires-Dist: sphinx~=8.2; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: sphinx-autoapi>=3.6; extra == "docs"
Requires-Dist: vale==3.9.5; extra == "docs"
Requires-Dist: setuptools-scm>=8.1.0; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=1.0.0; extra == "docs"
Dynamic: license-file

<!--
SPDX-FileCopyrightText: Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
 *
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
 *
http://www.apache.org/licenses/LICENSE-2.0
 *
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->


# NVIDIA Context Aware RAG

![image](docs/source/_static/data_architecture.png)

Context Aware RAG is a flexible library designed to seamlessly integrate into existing data processing workflows to build customized data ingestion and retrieval (RAG) pipelines.

## Key Features

- [**Data Ingestion Service:**](https://nvidia.github.io/context-aware-rag/overview/features.html#ingestion-strategies) Add data to the RAG pipeline from a variety of sources.
- [**Data Retrieval Service:**](https://nvidia.github.io/context-aware-rag/overview/features.html#retrieval-strategies) Retrieve data from the RAG pipeline using natural language queries.
- [**Function and Tool Components:**](https://nvidia.github.io/context-aware-rag/overview/architecture.html#components) Easy to create custom functions and tools to support your existing workflows.
- [**GraphRAG:**](https://nvidia.github.io/context-aware-rag/overview/features.html#retrieval-strategies) Seamlessly extract knowledge graphs from data to support your existing workflows.
- [**Observability:**](https://nvidia.github.io/context-aware-rag/metrics.html) Monitor and troubleshoot your workflows with any OpenTelemetry-compatible monitoring tool.


With Context Aware RAG, you can quickly build RAG pipelines to support your existing workflows.

## Links

 * [Documentation](https://nvidia.github.io/context-aware-rag): Explore the full documentation for Context Aware RAG.
 * [Context Aware RAG Architecture](https://nvidia.github.io/context-aware-rag/overview/architecture.html): Learn more about how Context Aware RAG works and its components.
 * [Getting Started Guide](https://nvidia.github.io/context-aware-rag/guides/index.html): Set up your environment and start integrating Context Aware RAG into your workflows.
 * [Examples](https://nvidia.github.io/context-aware-rag/guides/library.html#document-ingestion): Explore examples of Context Aware RAG workflows.
 * [Troubleshooting](https://nvidia.github.io/context-aware-rag/troubleshooting.html): Get help with common issues.
 * [Release Notes](https://nvidia.github.io/context-aware-rag/release-notes.html): Learn about the latest features and improvements.

## Getting Started

### Prerequisites

Before you begin using Context Aware RAG, ensure that you have the following software installed.

- Install [Git](https://git-scm.com/)
- Install [uv](https://docs.astral.sh/uv/getting-started/installation/)


### Installation

#### Clone the repository

```bash
git clone git@github.com:NVIDIA/context-aware-rag.git
cd context-aware-rag/
```

#### Create a virtual environment using uv

```bash
uv venv --seed .venv
source .venv/bin/activate
```

#### Installing from source

```bash
uv pip install -e .
```

#### Optional: Building and Installing the wheel file

```bash
uv build
uv pip install vss_ctx_rag-0.5.0-py3-none-any.whl
```

## Service Example



### Setting up environment variables


Create a .env file in the root directory and set the following variables:

```bash
   NVIDIA_API_KEY=<IF USING NVIDIA>
   NVIDIA_VISIBLE_DEVICES=<GPU ID>

   OPENAI_API_KEY=<IF USING OPENAI>

   VSS_CTX_PORT_RET=<DATA RETRIEVAL PORT>
   VSS_CTX_PORT_IN=<DATA INGESTION PORT>
```

### Build docker

```bash
make -C docker build
```

### Using docker compose

```bash
make -C docker start_compose
```

This will start the following services:


* ctx-rag-data-ingestion

  * Service available at `http://<HOST>:<VSS_CTX_PORT_IN>`

* ctx-rag-data-retrieval

  * Service available at `http://<HOST>:<VSS_CTX_PORT_RET>`

* neo4j

  * UI available at `http://<HOST>:7474`

* milvus

* otel-collector

* jaeger

  * UI available at `http://<HOST>:16686`

* prometheus

  * UI available at `http://<HOST>:9090`

* cassandra

To change the storage volumes, export `DOCKER_VOLUME_DIRECTORY` to the desired directory.

### Data Ingestion Example

```python
import requests
import json

base_url = "http://<HOST>:<VSS_CTX_PORT_IN>"

headers = {"Content-Type": "application/json"}

### Initialize the service with a unique uuid
init_data = {"uuid": "1"}
### Optional: Initialize the service with a config file or context config
"""
init_data = {"config_path": "/app/config/config.yaml", "uuid": "1"}
init_data = {"context_config": yaml.safe_load(open("/app/config/config.yaml")), "uuid": "1"}
"""
response = requests.post(
    f"{base_url}/init", headers=headers, data=json.dumps(init_data)
)

# POST request to /add_doc to add documents to the service
add_doc_data_list = [
    {"document": "User1: I went hiking to Mission Peak", "doc_index": 4},
    {
        "document": "User1: Hi how are you?",
        "doc_index": 0,
        "doc_metadata": {"is_first": True},
    },
    {"document": "User1: I went hiking to Mission Peak", "doc_index": 4},
    {"document": "User1: I am great too. Thanks for asking", "doc_index": 2},
    {"document": "User2: I am good. How are you?", "doc_index": 1},
    {"document": "User2: So what did you do over the weekend?", "doc_index": 3},
    {
        "document": "User3: Guys there is a fire. Let us get out of here",
        "doc_index": 5,
        "doc_metadata": {"is_last": True},
    },
]

# Send POST requests for each document
for add_doc_data in add_doc_data_list:
    response = requests.post(
        f"{base_url}/add_doc", headers=headers, data=json.dumps(add_doc_data)
    )
```

### Data Retrieval Example

```python
import requests
import json


base_url = "http://<HOST>:<VSS_CTX_PORT_RET>"

headers = {"Content-Type": "application/json"}

### Initialize the service with the same uuid as the data ingestion service
init_data = {"config_path": "/app/config/config.yaml", "uuid": "1"}
response = requests.post(
    f"{base_url}/init", headers=headers, data=json.dumps(init_data)
)

### Send a retrieval request to the service
call_data = {"chat": {"question": "What happens in this situation?"}}

request_data = {"state": call_data}

response = requests.post(
    f"{base_url}/call", headers=headers, data=json.dumps(request_data)
)
print(response.json()["result"])

```

## Acknowledgements

We would like to thank the following projects that made Context Aware RAG possible:

- [FastAPI](https://github.com/tiangolo/fastapi)
- [LangChain](https://github.com/langchain-ai/langchain)
- [Neo4j](https://github.com/neo4j/neo4j)
- [Milvus](https://github.com/milvus-io/milvus)
- [uv](https://github.com/astral-sh/uv)
- [OpenTelemetry](https://github.com/open-telemetry/opentelemetry-python)
