Agent/README.md

# 🤖 Agentic RAG — Локальный AI-ассистент с базой знаний

Полностью автономный AI-агент с RAG (Retrieval-Augmented Generation) для работы с вашими документами и кодом. Работает без интернета!

## 📋 Требования

- **Python 3.10+**
- **Ollama** — для запуска LLM локально
- **Qdrant** — векторная база данных (запускается автоматически)
- Операционная система: Linux, macOS, Windows (WSL2 рекомендуется)

## 🚀 Установка

### 1. Клонируйте репозиторий

```bash
git clone <ваш-репозиторий>
cd <папка-проекта>
```

### 2. Установите Ollama

```bash
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows (через WSL2)
# Установите WSL2, затем следуйте инструкции для Linux
```

### 3. Загрузите модели

```bash
# LLM модель (рекомендуется 3B параметров)
ollama pull llama3.2:3b

# Модель эмбеддингов
ollama pull nomic-embed-text
```

### 4. Установите Qdrant

Приложение использует Qdrant в embedded-режиме (база хранится локально в папке `qdrant_data/`). Для работы нужен бинарник Qdrant.

#### Вариант А: Через Docker (рекомендуется)

```bash
# Скачайте бинарник Qdrant
curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz \
  | tar -xz

# Или для macOS:
curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-apple-darwin.tar.gz \
  | tar -xz

# Переместите в PATH
sudo mv qdrant /usr/local/bin/
```

#### Вариант Б: Только Python (альтернатива)

Если не хотите устанавливать бинарник, можно использовать Qdrant как Python-библиотеку (требуется больше ресурсов):

```bash
pip install qdrant[fast]
```

При этом в коде `local_knowledge_base.py` нужно изменить инициализацию клиента:

```python
# Вместо:
self.client = QdrantClient(path=persist_dir, prefer_grpc=True)

# Использовать:
self.client = QdrantClient.from_mutable_local(path=persist_dir)
```

#### Вариант В: Через Docker

```bash
# Запуск Qdrant в контейнере
docker run -d --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant
```

После запуска измените подключение в `local_knowledge_base.py`:

```python
# Вместо локального подключения:
self.client = QdrantClient(path=persist_dir, prefer_grpc=True)

# Использовать HTTP подключение:
self.client = QdrantClient(host="localhost", port=6333)
```

### 5. Настройте виртуальное окружение (рекомендуется)

```bash
# Создание виртуального окружения
python -m venv venv

# Активация (Linux/macOS)
source venv/bin/activate

# Активация (Windows)
venv\Scripts\activate
```

### 6. Установите Python-зависимости

```bash
pip install -r requirements.txt
```

### 7. Запустите Ollama (если не запущен)

```bash
ollama serve
```

Оставьте этот терминал открытым (или запустите в фоне).

## ▶️ Запуск

```bash
python main.py
```

После запуска откройте браузер по адресу: **http://localhost:7860**

## 📖 Использование

### Базовая работа

1. Введите ваш запрос в текстовое поле
2. Включите/выключите переключатель **"Использовать базу знаний (RAG)"**
3. Нажмите **"Отправить"** или Enter

### Индексация файлов

1. Введите путь к папке с документами в поле **"Путь к папке с файлами"**
2. Нажмите кнопку **"📥 Индексировать"**
3. Дождитесь завершения индексации (индикатор прогресса)

#### Поддерживаемые типы файлов

| Тип | Расширение |
|-----|------------|
| PDF | `.pdf` |
| Текст | `.txt` |
| Word | `.docx` |
| C++ | `.cpp`, `.hpp`, `.h`, `.cc` |

#### Рекомендации по индексации

- Для C++ проектов укажите корневую папку с исходным кодом
- Папки `build`, `.git`, `vendor`, `node_modules` автоматически пропускаются
- После индексации можно задавать вопросы о коде

### Примеры запросов

```
"Объясни как работает класс Parser в загруженном коде"
"Найди функцию обработки JSON"
"Спланируй изучение Python на месяц"
"Посчитай: (15 * 4) + (120 / 3)"
```

## ⚙️ Конфигурация

### Изменение модели LLM

В файле `agent_core.py`:

```python
llm = Ollama(
    model="llama3.2:3b",  # Измените здесь
    temperature=0.1,
    num_predict=1024,
)
```

### Изменение модели эмбеддингов

В файле `agent_core.py`:

```python
embeddings = OllamaEmbeddings(
    model="nomic-embed-text",  # Измените здесь
)
```

### Доступные модели Ollama

Список доступных моделей: https://ollama.com/library

Рекомендуемые модели для эмбеддингов:
- `nomic-embed-text` (768 dim) — универсальные
- `mxbai-embed-large` (1024 dim) — более мощные
- `bge-m3` (1024 dim) — мультиязычные

## 🛠 Устранение проблем

### Ошибка: "connection refused"

Ollama не запущен. Запустите:
```bash
ollama serve
```

### Ошибка: "model not found"

Модель не загружена. Скачайте:
```bash
ollama pull llama3.2:3b
ollama pull nomic-embed-text
```

### Медленная работа

- Используйте модель меньшего размера (например, `llama3.2:1b`)
- Уменьшите `num_predict` в настройках LLM
- Используйте SSD для хранения Qdrant

### Не загружаются файлы

- Проверьте путь к папке
- Убедитесь, что у приложения есть права на чтение
- Проверьте, что файлы имеют поддерживаемые расширения

### Ошибка: "Qdrant binary not found"

Qdrant не установлен. Следуйте инструкции выше (раздел "Установите Qdrant").

### Ошибка: "Failed to connect to Qdrant"

Проблема с подключением к Qdrant. Проверьте:
- Qdrant бинарник установлен и доступен в PATH
- Права на запись в папку проекта (нужно для создания `qdrant_data/`)

## 📂 Структура проекта

```
.
├── main.py                      # Точка входа
├── agent_core.py                # Логика агента и инструменты
├── local_knowledge_base.py      # Работа с Qdrant
├── agentic_rag_interface.py     # Gradio-интерфейс
├── README.md                    # Этот файл
└── qdrant_data/                 # Данные Qdrant (создаётся автоматически)
```

## 📄 Лицензия

MIT License