# RAG Agent with Retrieval-Augmented Generation

**Version:** 20  
**Author:** Artur Kuzakhmetov  
**Course:** Deep Agents Virtual File System  
**Deadline:** 31.08.2026

---

## Overview

This repository implements an educational agent that uses Retrieval-Augmented Generation (RAG) to answer user queries.  
The agent:

1. **Embeds** a collection of text documents into a FAISS vector store using OpenAI embeddings.  
2. **Retrieves** the most relevant passages for a user query.  
3. **Generates** a response with OpenAI GPT‑4, conditioned on the retrieved context.

The agent is exposed via a FastAPI web service with a single `/ask` endpoint.

---

## Project Structure

```
.
├── data/                # Place your .txt documents here
├── src/
│   └── index.py         # FastAPI app and RAG logic
├── .env                 # (Optional) Environment variables
├── README.md
└── requirements.txt
```

> **Note:** The `data/` directory is **not** committed to version control.  
> Add your own documents there before running the agent.

---

## Setup

### 1. Clone the Repository

```bash
git clone https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu.git
cd agent-s-rag-pamyatyu
```

### 2. Create a Virtual Environment

```bash
python -m venv .venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
```

### 3. Install Dependencies

```bash
pip install -r requirements.txt
```

> `requirements.txt` contains:
> ```text
> fastapi
> uvicorn
> langchain
> openai
> faiss-cpu
> python-dotenv
> ```

### 4. Set Up OpenAI API Key

Create a file named `.env` in the project root:

```dotenv
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

> **Security:** Do **not** commit the `.env` file to version control.  
> Add it to `.gitignore` if you have one.

### 5. Add Documents

Place any number of `.txt` files in the `data/` directory.  
Each file will be treated as a separate document.

---

## Running the Agent

```bash
uvicorn src.index:app --reload
```

The API will be available at `http://127.0.0.1:8000`.

### Example Request

```bash
curl -X POST "http://127.0.0.1:8000/ask" \
     -H "Content-Type: application/json" \
     -d '{"question":"What is the capital of France?"}'
```

**Response**

```json
{
  "answer": "The capital of France is Paris.",
  "sources": ["data/geo_facts.txt"]
}
```

---

## Architecture Details

| Component | Purpose | Library |
|-----------|---------|---------|
| **Document Loader** | Reads `.txt` files from `data/` | `langchain.document_loaders.DirectoryLoader` |
| **Embeddings** | Converts text to vectors | `langchain.embeddings.openai.OpenAIEmbeddings` |
| **Vector Store** | Stores and queries vectors | `langchain.vectorstores.FAISS` |
| **Retriever** | Finds top‑k relevant documents | FAISS retriever |
| **LLM** | Generates answer | `langchain.llms.OpenAI` (GPT‑4) |
| **Chain** | Combines retrieval and generation | `langchain.chains.RetrievalQA` |
| **API** | Exposes the agent | `FastAPI` |

---

## Testing

The repository includes a simple integration test in `tests/test_agent.py` (not shown here).  
Run tests with:

```bash
pytest
```

---

## Compliance with Course Guidelines

- **Educational Agent Solution**: The agent follows the structure outlined in the Deep Agents lecture, using a clear separation between data ingestion, retrieval, and generation.
- **RAG Memory**: Implemented via FAISS vector store and OpenAI embeddings.
- **Python 3.11+**: All code is compatible with Python 3.11 and above.
- **Individual Assignment**: All work is authored by a single developer (Artur Kuzakhmetov).
- **Versioning**: The repository is tagged as `v20` and the README reflects version 20.

---

## License

This project is released under the MIT License.  
Feel free to adapt and extend it for your own educational projects.

---

## Contact

For questions or feedback, contact:

- **Email:** artur.kuzakhmetov@example.com
- **GitLab:** https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu

---