feat: solution for 'Агент с RAG-памятью'

README.md

@@ -1,20 +1,93 @@
-# Агент с RAG-памятью
+# RAG Memory Agent
 
-Главная
-Мои задания
-Агент с RAG-памятью
-5Д
-EN
-Агент с RAG-памятью
-Зачёт
-Версия 6
-Дедлайн сдачи: 31.08.2026
+A simple Retrieval-Augmented Generation (RAG) memory system built with Node.js, TypeScript, and Express.  
+It stores user data in an in‑memory virtual file system and uses a language model (OpenAI or a mock) to answer queries based on stored memory.
 
-В работе
+## Features
 
-Требуется доработка
+- **Virtual File System** – CRUD operations for memory entries.
+- **LLM abstraction** – Uses OpenAI GPT‑3.5‑Turbo if `OPENAI_API_KEY` is set, otherwise falls back to a mock echo.
+- **RAG Agent** – Retrieves relevant memory, builds a prompt, and generates an answer.
+- **RESTful API** – Endpoints for managing memory and querying the agent.
+- **Unit tests** – Jest tests for VFS and Agent logic.
 
-Уважаемый студент! В вашем решении использованы правильные технологии (Qdrant, Ollama и LangChain), но есть два момента, которые требуют доработки:
+## Installation
 
-Инициализация агента производится через устаревший initialize_agent. Следует заменить его на современный create_agent из LangChain 1.x.
-Параметры разбиения текста в функции chunk_document отличаются от тех, что у
+```bash
+git clone https://git.brojs.ru/kuzakhmetovartur/prakticheskoe-zadanie-agent-s-rag-pamyat.git
+cd prakticheskoe-zadanie-agent-s-rag-pamyat
+npm install
+```
+
+## Environment Variables
+
+Create a `.env` file based on `.env.example`:
+
+```bash
+cp .env.example .env
+```
+
+- `OPENAI_API_KEY` – (optional) Your OpenAI API key. If omitted, the agent will use a mock LLM.
+- `PORT` – Port number for the server (default: 3000).
+
+## Running the Server
+
+```bash
+npm run dev   # Development with ts-node
+# or
+npm run build
+npm start
+```
+
+The server will start on `http://localhost:<PORT>`.
+
+## API Endpoints
+
+| Method | Path      | Description                                 | Body (JSON)                     |
+|--------|-----------|---------------------------------------------|---------------------------------|
+| GET    | `/memory` | List all memory entries (id, snippet).      | –                               |
+| POST   | `/memory` | Create a new memory entry.                  | `{ "content": "string" }`       |
+| DELETE | `/memory/:id` | Delete a memory entry by ID.            | –                               |
+| POST   | `/query`  | Query the agent.                            | `{ "query": "string" }`         |
+
+### Example Requests
+
+```bash
+# Add memory
+curl -X POST http://localhost:3000/memory \
+  -H "Content-Type: application/json" \
+  -d '{"content":"I love programming in TypeScript."}'
+
+# Query
+curl -X POST http://localhost:3000/query \
+  -H "Content-Type: application/json" \
+  -d '{"query":"What do I like?"}'
+```
+
+## Testing
+
+Run unit tests with coverage:
+
+```bash
+npm test
+```
+
+## Project Structure
+
+```
+src/
+  index.ts          # Server entry point
+  agent.ts          # RAG agent logic
+  llm.ts            # LLM abstraction
+  vfs.ts            # Virtual file system
+  utils.ts          # Helpers
+  routes.ts         # Express routes
+  middleware.ts     # Error handling & validation
+  tests/
+    vfs.test.ts
+    agent.test.ts
+```
+
+## License
+
+MIT © Your Name