166 lines
3.9 KiB
Markdown
166 lines
3.9 KiB
Markdown
# 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
|
||
|
||
--- |