agent-s-rag-pamyatyu/README.md

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

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

2. Create a Virtual Environment

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

3. Install Dependencies

pip install -r requirements.txt

requirements.txt contains:

fastapi
uvicorn
langchain
openai
faiss-cpu
python-dotenv

4. Set Up OpenAI API Key

Create a file named .env in the project root:

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

uvicorn src.index:app --reload

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

Example Request

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

Response

{
  "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:

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

---