This commit is contained in:
@@ -1,100 +1,166 @@
|
||||
# Educational Agent with Retrieval-Augmented Generation (RAG) Memory
|
||||
# RAG Agent with Retrieval-Augmented Generation
|
||||
|
||||
This repository contains a lightweight educational agent that demonstrates
|
||||
Retrieval-Augmented Generation (RAG) using only Python standard libraries.
|
||||
The implementation is fully self‑contained and does not rely on external
|
||||
AI services or heavy dependencies, making it suitable for the Deep Agents
|
||||
Virtual File System environment.
|
||||
**Version:** 20
|
||||
**Author:** Artur Kuzakhmetov
|
||||
**Course:** Deep Agents Virtual File System
|
||||
**Deadline:** 31.08.2026
|
||||
|
||||
## Features
|
||||
---
|
||||
|
||||
- **RAG Memory** – Stores documents and builds simple bag‑of‑words embeddings.
|
||||
- **Retrieval Engine** – Performs cosine‑similarity based nearest‑neighbor search.
|
||||
- **Rule‑Based Agent** – Generates responses by concatenating retrieved context
|
||||
with a placeholder answer.
|
||||
- **CLI** – Ask a question and receive an answer that includes relevant context.
|
||||
## 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
|
||||
|
||||
```
|
||||
.
|
||||
├── src
|
||||
│ └── index.py # Main implementation
|
||||
└── README.md # This file
|
||||
├── data/ # Place your .txt documents here
|
||||
├── src/
|
||||
│ └── index.py # FastAPI app and RAG logic
|
||||
├── .env # (Optional) Environment variables
|
||||
├── README.md
|
||||
└── requirements.txt
|
||||
```
|
||||
|
||||
## Installation
|
||||
> **Note:** The `data/` directory is **not** committed to version control.
|
||||
> Add your own documents there before running the agent.
|
||||
|
||||
No external dependencies are required. The code uses only the Python
|
||||
standard library.
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://git.brojs.ru/kuzakhmetovartur/agent-s-rag-pamyatyu.git
|
||||
cd agent-s-rag-pamyatyu
|
||||
|
||||
# Ensure you have Python 3.8+ installed
|
||||
python3 --version
|
||||
```
|
||||
|
||||
## Usage
|
||||
### 2. Create a Virtual Environment
|
||||
|
||||
1. **Prepare a data directory**
|
||||
Place one or more `.txt` files in a directory. Each file will be
|
||||
treated as a separate document. Example:
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
```
|
||||
|
||||
```
|
||||
data/
|
||||
├── doc1.txt
|
||||
├── doc2.txt
|
||||
└── doc3.txt
|
||||
```
|
||||
### 3. Install Dependencies
|
||||
|
||||
2. **Run the agent**
|
||||
```bash
|
||||
python3 src/index.py --data-dir data --question "What is the capital of France?"
|
||||
```
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
The agent will:
|
||||
- Load all `.txt` files from `data/`.
|
||||
- Compute bag‑of‑words embeddings for each document.
|
||||
- Retrieve the top 3 most relevant documents for the question.
|
||||
- Print the question, retrieved context, and a placeholder answer.
|
||||
> `requirements.txt` contains:
|
||||
> ```text
|
||||
> fastapi
|
||||
> uvicorn
|
||||
> langchain
|
||||
> openai
|
||||
> faiss-cpu
|
||||
> python-dotenv
|
||||
> ```
|
||||
|
||||
## How It Works
|
||||
### 4. Set Up OpenAI API Key
|
||||
|
||||
1. **Tokenization & Vectorization**
|
||||
Text is tokenized by lowercasing, removing punctuation, and splitting on
|
||||
whitespace. A bag‑of‑words vector (word → count) is created for each
|
||||
document and for the query.
|
||||
Create a file named `.env` in the project root:
|
||||
|
||||
2. **Similarity Calculation**
|
||||
Cosine similarity between the query vector and each document vector is
|
||||
computed using only standard Python data structures.
|
||||
```dotenv
|
||||
OPENAI_API_KEY=sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
||||
```
|
||||
|
||||
3. **Retrieval**
|
||||
The top‑k documents with the highest similarity scores are returned.
|
||||
> **Security:** Do **not** commit the `.env` file to version control.
|
||||
> Add it to `.gitignore` if you have one.
|
||||
|
||||
4. **Response Generation**
|
||||
The agent concatenates the question, the retrieved context snippets,
|
||||
and a simple placeholder answer.
|
||||
### 5. Add Documents
|
||||
|
||||
## Extending the Agent
|
||||
Place any number of `.txt` files in the `data/` directory.
|
||||
Each file will be treated as a separate document.
|
||||
|
||||
- **Better Embeddings** – Replace the bag‑of‑words approach with a
|
||||
lightweight embedding model (e.g., a pre‑trained sentence transformer
|
||||
loaded locally) if you have the resources.
|
||||
- **More Sophisticated Generation** – Integrate a template‑based or
|
||||
rule‑based system that uses the retrieved context to produce more
|
||||
informative answers.
|
||||
- **Persistence** – Add serialization of the memory to disk for faster
|
||||
startup.
|
||||
---
|
||||
|
||||
## Individual Effort Statement
|
||||
## Running the Agent
|
||||
|
||||
This work was completed independently by the author and does not rely
|
||||
on external automated tools or AI services for the core implementation.
|
||||
```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
|
||||
|
||||
MIT License – see `LICENSE` for details.
|
||||
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
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user