This commit is contained in:
@@ -1,166 +1,74 @@
|
||||
# RAG Agent with Retrieval-Augmented Generation
|
||||
# Agent with RAG Memory
|
||||
|
||||
**Version:** 20
|
||||
**Author:** Artur Kuzakhmetov
|
||||
**Course:** Deep Agents Virtual File System
|
||||
**Deadline:** 31.08.2026
|
||||
This project implements a simple command‑line agent that uses **Ollama embeddings** for a Retrieval‑Augmented Generation (RAG) style knowledge base.
|
||||
The agent supports two main tools:
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
- **`search_knowledge_base`** – find the most relevant documents for a query.
|
||||
- **`add_to_knowledge_base`** – add new content to the knowledge base.
|
||||
|
||||
## 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
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Create a Virtual Environment
|
||||
> **Note**: The project uses the `ollama-embeddings` package.
|
||||
> Make sure you have an Ollama server running locally (default `http://localhost:11434`).
|
||||
> You can change the host or model via environment variables:
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
||||
# Example .env file
|
||||
OLLAMA_HOST=http://localhost:11434
|
||||
OLLAMA_MODEL=all-minilm
|
||||
```
|
||||
|
||||
### 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
|
||||
npm start
|
||||
```
|
||||
|
||||
The API will be available at `http://127.0.0.1:8000`.
|
||||
You will see a prompt:
|
||||
|
||||
### 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?"}'
|
||||
```
|
||||
Agent>
|
||||
```
|
||||
|
||||
**Response**
|
||||
### Commands
|
||||
|
||||
```json
|
||||
{
|
||||
"answer": "The capital of France is Paris.",
|
||||
"sources": ["data/geo_facts.txt"]
|
||||
}
|
||||
- `/search <query>` – Search the knowledge base for the most relevant documents.
|
||||
- `/add <content>` – Add new content to the knowledge base.
|
||||
- `/exit` – Exit the program.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Agent> /add The quick brown fox jumps over the lazy dog.
|
||||
Content added with id 3f1c2e4b-...
|
||||
|
||||
Agent> /search fox
|
||||
Searching for "fox"...
|
||||
Top results:
|
||||
1. [3f1c2e4b-...] (0.9123)
|
||||
The quick brown fox jumps over the lazy dog.
|
||||
```
|
||||
|
||||
---
|
||||
## Project Structure
|
||||
|
||||
## Architecture Details
|
||||
- `src/embeddings.js` – Wrapper around `ollama-embeddings`.
|
||||
- `src/tools/searchKnowledgeBase.js` – Implements the search tool.
|
||||
- `src/tools/addToKnowledgeBase.js` – Implements the add tool.
|
||||
- `src/index.js` – CLI entry point and agent logic.
|
||||
- `package.json` – Dependencies and scripts.
|
||||
|
||||
| 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` |
|
||||
## Extending
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
The current implementation uses an in‑memory vector store.
|
||||
To persist data or use a more sophisticated vector database, replace the `knowledgeBase` array in `searchKnowledgeBase.js` with your preferred storage solution.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user