DLE/docs/RAG_TASKS.md

<!--
  Copyright (c) 2024-2025 Тарабанов Александр Викторович
  All rights reserved.
  
  This software is proprietary and confidential.
  Unauthorized copying, modification, or distribution is prohibited.
  
  For licensing inquiries: info@hb3-accelerator.com
  Website: https://hb3-accelerator.com
  GitHub: https://github.com/HB3-ACCELERATOR
-->

# Внедрение RAG-ассистента: поэтапный план

---

## Особенности проекта: разнообразие клиентов, каналов и данных

- **Клиенты:**
  - Различные сегменты: B2B, B2C, VIP, оптовые и розничные покупатели, корпоративные клиенты, частные лица и др.
  - Различные сценарии взаимодействия (покупка, поддержка, консультация, возврат и т.д.).

- **Каналы коммуникации:**
  - Веб-чат
  - Email
  - Telegram/мессенджеры
  - Возможна интеграция с другими каналами (WhatsApp, телефон и др.)

- **Типы данных:**
  - Текстовые сообщения
  - Аудио, видео, изображения (мультимодальные данные)
  - Вложения (документы, сканы, фото товаров и т.д.)

- **Языки:**
  - Русский
  - Английский
  - Испанский
  - Китайский
  - Возможность расширения на другие языки

- **Товары и услуги:**
  - Широкий ассортимент товаров (разные категории, бренды, характеристики)
  - Различные услуги (консультации, сервис, доставка, гарантия, возврат и др.)
  - Возможность кросс-продаж и рекомендаций

- **Требования к RAG:**
  - Гибкая фильтрация знаний по сегменту клиента, языку, категории товара/услуги, каналу обращения
  - Поддержка мультиязычности и мультимодальности
  - Масштабируемость для добавления новых ассистентов, сегментов, каналов и языков

---

## Многоагентная архитектура AI-ассистента

### 🎯 Главный AI-координатор
- **Роль:** Анализирует входящие сообщения и координирует работу специализированных агентов
- **Функции:**
  - Определяет какие агенты нужны для обработки сообщения
  - Собирает результаты от всех агентов
  - Генерирует финальный персонализированный ответ
  - Управляет контекстом беседы

### 🤖 Специализированные агенты

#### 1. Агент "Персонализация пользователя"
- **Задача:** Извлечение и управление персональными данными
- **Функции:**
  - Извлекает имя из сообщений ("меня зовут Саша")
  - Анализирует профиль пользователя (компания, должность, предпочтения)
  - Отслеживает историю взаимодействий
  - Определяет стадию в воронке продаж
- **Результат:** Персонализированный контекст для ответа

#### 2. Агент "Анализ запроса"
- **Задача:** Классификация и понимание сути обращения
- **Функции:**
  - Определяет тип вопроса (техническая проблема, вопрос о цене, жалоба)
  - Анализирует эмоциональное состояние клиента
  - Выявляет скрытые потребности
  - Определяет приоритетность запроса
- **Результат:** Структурированный анализ запроса

#### 3. Агент "RAG поиск"
- **Задача:** Поиск релевантной информации в базе знаний
- **Функции:**
  - Векторный поиск по RAG базе
  - Фильтрация по тегам пользователя
  - Поиск похожих случаев и решений
  - Извлечение контекстной информации
- **Результат:** Релевантные ответы и шаблоны

#### 4. Агент "Контекст беседы"
- **Задача:** Анализ истории взаимодействий
- **Функции:**
  - Изучает предыдущие сообщения в беседе
  - Анализирует все предыдущие обращения пользователя
  - Определяет повторяющиеся темы и проблемы
  - Отслеживает прогресс в решении задач
- **Результат:** Контекстная картина взаимодействия

#### 5. Агент "Детализация"
- **Задача:** Выяснение недостающей информации
- **Функции:**
  - Формулирует уточняющие вопросы
  - Определяет какие детали нужны для решения
  - Адаптирует вопросы под контекст беседы
  - Отслеживает ответы на уточняющие вопросы
- **Результат:** Структурированные уточняющие вопросы

#### 6. Агент "Персонализация ответа"
- **Задача:** Адаптация ответа под конкретного пользователя
- **Функции:**
  - Учитывает стиль общения пользователя
  - Адаптирует тон (формальный/неформальный)
  - Использует имя и персональные данные
  - Ссылается на предыдущие взаимодействия
- **Результат:** Персонализированный ответ

#### 7. Агент "Мультиязычность"
- **Задача:** Обработка многоязычных запросов
- **Функции:**
  - Определяет язык входящего сообщения
  - Ищет ответы на соответствующем языке
  - Генерирует ответы на языке пользователя
  - Адаптирует культурные особенности
- **Результат:** Локализованный ответ

#### 8. Агент "Мультимодальность"
- **Задача:** Обработка различных типов контента
- **Функции:**
  - Анализ изображений, аудио, видео
  - Извлечение текста из медиафайлов
  - Поиск похожих медиа в базе знаний
  - Генерация мультимодальных ответов
- **Результат:** Контекст из медиафайлов

#### 9. Агент "Саммари беседы"
- **Задача:** Создание краткого саммари истории беседы
- **Функции:**
  - Анализирует последние 10-20 сообщений из истории
  - Создает краткое саммари через AI (вместо передачи полной истории)
  - Кэширует результат для повторного использования
  - Обновляет саммари при поступлении новых сообщений
  - Оптимизирует количество токенов в промпте
- **Результат:** Оптимизированный контекст беседы для AI

#### 10. Агент "Анализ контакта"
- **Задача:** Извлечение и анализ данных пользователя из профиля
- **Функции:**
  - Получает данные из профиля контакта (имя, теги, язык, роль)
  - Анализирует предпочтения и историю взаимодействий
  - Кэширует анализ для быстрого доступа
  - Обновляет при изменении профиля пользователя
  - Определяет стиль общения и приоритет
- **Результат:** Персонализированный контекст для ответа

#### 11. Агент "Кэширование бесед"
- **Задача:** Управление кэшем бесед и контекста
- **Функции:**
  - Кэширует саммари беседы + анализ контакта
  - Управляет TTL (Time To Live) для автоматической очистки
  - Проверяет актуальность кэша при новых сообщениях
  - Оптимизирует производительность системы
  - Предотвращает повторные вычисления
- **Результат:** Быстрый доступ к контексту без пересчета

### ⚙️ Логика работы многоагентной системы

#### Шаг 1: Получение сообщения
- Координатор получает входящее сообщение
- Анализирует базовый контекст
- Определяет необходимых агентов

#### Шаг 2: Параллельный запуск агентов
- Агент "Персонализация" → извлекает данные пользователя
- Агент "Анализ запроса" → классифицирует обращение
- Агент "RAG поиск" → ищет релевантную информацию
- Агент "Контекст" → анализирует историю
- Агент "Мультиязычность" → определяет язык
- Агент "Мультимодальность" → обрабатывает медиа
- Агент "Саммари беседы" → создает краткое саммари истории
- Агент "Анализ контакта" → извлекает данные из профиля
- Агент "Кэширование бесед" → проверяет и обновляет кэш

#### Шаг 3: Сбор и анализ результатов
- Координатор собирает данные от всех агентов
- Анализирует полноту информации
- Определяет необходимость дополнительных уточнений

#### Шаг 4: Генерация ответа
- Если информации достаточно → генерирует персонализированный ответ
- Если нужно уточнить → запускает агента "Детализация"
- Если требуется дополнительный контекст → запрашивает у других агентов

#### Шаг 5: Сохранение контекста
- Обновляет профиль пользователя
- Сохраняет контекст беседы
- Логирует использованные знания
- Обновляет кэш саммари и анализа контакта
- Сохраняет оптимизированный контекст для будущих запросов

### 🎨 Преимущества многоагентной архитектуры

1. **Модульность:** Каждый агент решает свою специализированную задачу
2. **Масштабируемость:** Легко добавлять новых агентов
3. **Эффективность:** Параллельная обработка разных аспектов
4. **Гибкость:** Разные комбинации агентов для разных ситуаций
5. **Персонализация:** Глубокое понимание каждого пользователя
6. **Качество:** Специализированная обработка каждого аспекта
7. **Оптимизация:** Саммари бесед снижает количество токенов
8. **Кэширование:** Быстрый доступ к контексту без пересчета
9. **Производительность:** Уменьшение времени ответа и нагрузки на AI

---

## Персонализация на уровне аккаунта пользователя

### 👤 Профиль пользователя
- **Базовые данные:** Имя, компания, должность, контактная информация
- **История взаимодействий:** Все предыдущие обращения и решения
- **Предпочтения:** Стиль общения, технический уровень, приоритеты
- **Статус:** Стадия в воронке продаж, статус клиента
- **Теги:** Категории, сегменты, специализации

### 📊 Контекстная картина
- **Текущая беседа:** Сообщения в рамках одной сессии
- **История обращений:** Все предыдущие взаимодействия
- **Решенные проблемы:** Успешно закрытые задачи
- **Открытые вопросы:** Незавершенные обращения
- **Эмоциональное состояние:** Тон и настроение клиента

### 🎯 Алгоритм персонализации

#### 1. Анализ входящего сообщения
- Определение типа обращения
- Извлечение ключевой информации
- Анализ эмоционального контекста

#### 2. Загрузка профиля пользователя
- Получение персональных данных
- Анализ истории взаимодействий
- Определение текущего статуса

#### 3. Поиск в RAG базе
- Фильтрация по тегам пользователя
- Поиск релевантных решений
- Анализ похожих случаев

#### 4. Формирование контекста
- Объединение данных профиля и истории
- Анализ текущей ситуации
- Определение оптимального подхода

#### 5. Генерация персонализированного ответа
- Учет персональных данных
- Адаптация под стиль общения
- Ссылки на предыдущие взаимодействия

---

## Этап 1. Проектирование и подготовка инфраструктуры
1. **Проектирование схемы хранения знаний (RAG):**
   - Описать структуру таблицы `knowledge_documents` (миграция).
   - Определить поля: id, content, language, type (текст/медиа), метаданные, дата, автор и т.д.
2. **Подготовка backend:**
   - Создать миграцию и модель для `knowledge_documents`.
   - Подготовить базовые CRUD-эндпоинты для работы с базой знаний.

---

## Этап 2. Интеграция векторного поиска (RAG)
1. **Реализация векторного хранилища:**
   - Реализовать методы инициализации и поиска (`initVectorStore`, `findSimilarDocuments`) в `ai-assistant.js`.
   - Настроить хранение эмбеддингов для документов.
2. **API для поиска знаний:**
   - Добавить эндпоинт для поиска релевантных знаний по запросу пользователя.

---

## Этап 3. Разработка многоагентной архитектуры
1. **Создание базовой структуры агентов:**
   - Реализовать главный AI-координатор
   - Создать базовые классы для специализированных агентов
   - Настроить систему координации между агентами
2. **Разработка специализированных агентов:**
   - Агент "Персонализация пользователя"
   - Агент "Анализ запроса"
   - Агент "RAG поиск"
   - Агент "Контекст беседы"
   - Агент "Детализация"
   - Агент "Персонализация ответа"
   - Агент "Саммари беседы" (новый)
   - Агент "Анализ контакта" (новый)
   - Агент "Кэширование бесед" (новый)
3. **Интеграция с существующей системой:**
   - Подключение агентов к текущему pipeline
   - Настройка логирования и мониторинга
   - Тестирование взаимодействия агентов
4. **Реализация оптимизаций:**
   - Создание сервиса саммари бесед
   - Интеграция анализа контактов для персонализации
   - Настройка кэширования для повышения производительности

---

## Этап 4. Интеграция RAG в pipeline ассистента
1. **Модификация логики ответа ассистента:**
   - При получении сообщения пользователя — искать релевантные знания и включать их в prompt LLM.
   - Обеспечить мультиязычность поиска и генерации ответа.
   - Интегрировать саммари беседы вместо передачи полной истории.
   - Использовать анализ контактов для персонализации ответов.
2. **Логирование и трассировка:**
   - Сохранять, какие знания были использованы для ответа.
   - Логировать использование саммари и кэширования.
   - Отслеживать производительность оптимизаций.

---

## Этап 5. Интерфейс для админа
1. **UI для управления знаниями:**
   - Добавить на фронте раздел для просмотра, добавления, редактирования и удаления знаний.
2. **UI для модерации ответов ассистента:**
   - Кнопки "Редактировать", "Отправить", "Добавить в RAG" для сообщений и ответов.
   - Возможность быстро добавить сообщение пользователя или ответ ассистента в базу знаний.

---

## Этап 6. Поддержка мультимодальности и мультиязычности
1. **Обработка вложений (аудио, видео, картинки):**
   - Решить, как хранить и индексировать такие данные (например, хранить ссылки и метаданные, а не сами файлы).
2. **Мультиязычный поиск и генерация:**
   - Проверить корректность работы эмбеддингов и LLM для разных языков.

---

## Этап 7. Тестирование и оптимизация
1. **Покрытие тестами ключевых сценариев (unit, интеграционные).**
2. **Оптимизация скорости поиска и генерации.**
3. **Тестирование производительности саммари и кэширования.**
4. **Оптимизация использования токенов и времени ответа.**
5. **Документация для команды.**

---

## Бизнес-логика управления знаниями и тегами для RAG-ассистента

### 1. Гибкая система тегов и связей с пользователями
- Пользователь может создавать собственные таблицы тегов (например, "покупатель", "поставщик", "VIP-клиент" и т.д.).
- В таблице тегов должна быть возможность добавлять ссылки (relation) на пользователей из таблицы `users`.
- Для одного тега может быть привязано несколько пользователей (мультисвязь).
- Для одного пользователя может быть несколько тегов.

### 2. Управление знаниями (FAQ, инструкции, ответы)
- Пользователь может создавать таблицы с вопросами и ответами (например, FAQ для определённой группы клиентов).
- Каждая запись (вопрос-ответ) может быть связана с определённым тегом или группой тегов.
- Возможна фильтрация и поиск знаний по тегам, языку, типу клиента и другим параметрам.

### 3. Использование тегов и знаний в RAG-ассистенте
- При обработке запроса пользователя RAG-ассистент определяет его теги (по связям в таблице тегов).
- Для генерации ответа ассистент использует только те знания (вопросы/ответы), которые соответствуют тегам пользователя.
- Администратор может добавлять новые теги, связывать их с пользователями, а также создавать и редактировать знания для каждой группы.
- **Оптимизация через саммари:** Вместо передачи полной истории беседы (10 сообщений), система создает краткое саммари через AI.
- **Персонализация через контакты:** Ассистент использует данные из профиля контакта (имя, язык, теги) для персонализации ответов.
- **Кэширование контекста:** Саммари беседы и анализ контактов кэшируются для быстрого доступа без пересчета.

### 4. UI/UX требования
- В интерфейсе создания/редактирования пользовательских таблиц должен быть доступен тип столбца "relation" (связь с users).
- Для ячеек типа "relation" реализовать выпадающий список с поиском по пользователям.
- Для таблиц знаний — возможность выбора одного или нескольких тегов для каждой записи.

**Пример структуры:**
- Таблица `user_tags`:  id, name, [user_id (relation, мультисвязь)]
- Таблица `faq`:  id, question, answer, [tag_id (relation, мультисвязь)]

**Применение:**
- RAG-ассистент использует связи между пользователями, тегами и знаниями для персонализации ответов и поиска релевантной информации.

### 5. Безопасность и контроль
- Только администратор может создавать и редактировать системные теги и знания.
- Обычные пользователи могут видеть только свои теги и связанные с ними знания.

---

## Требования к CRM-интерфейсу для работы с контактами, тегами и настройками RAG-ассистента

### 1. Раздел "Контакты" в CRM
- **Фильтры:**
  - Новые пользователи (по дате создания или статусу "новый").
  - Новые входящие сообщения (по наличию непрочитанных/неотвеченных сообщений).
  - Теги (мультиселект по тегам пользователя).
- **Детали контакта:**
  - Просмотр истории сообщений.
  - Список тегов пользователя.
  - Добавление/удаление тегов через выпадающий список или автокомплит (создание связи в таблице user_tags).

### 2. Настройки ИИ-ассистента
- **Выбор RAG-таблиц:**
  - В настройках ассистента отображается список всех доступных RAG-таблиц.
  - Администратор выбирает (чекбоксами или мультиселектом), какие таблицы использовать для поиска ответов.
  - Для каждой выбранной таблицы отображается список тегов, которые она содержит.
- **Связь с тегами:**
  - При генерации ответа ИИ использует только те RAG-таблицы и записи, которые соответствуют тегам пользователя.

### 3. Рекомендации по интерфейсу (Vue)
- Компоненты:
  - `ContactList.vue` — фильтры, список пользователей
  - `ContactDetails.vue` — история сообщений, теги, добавление тегов
  - `AssistantSettings.vue` — выбор RAG-таблиц
  - `RagTableSelector.vue` — список таблиц с чекбоксами
  - `TagList.vue` — просмотр тегов в выбранной таблице

### 4. Схема действий администратора
1. В разделе "Контакты" находит нового пользователя/сообщение через фильтры.
2. В деталях контакта добавляет нужные теги пользователю.
3. В настройках ассистента выбирает, какие RAG-таблицы использовать для поиска по тегам.
4. ИИ-ассистент при ответе использует только релевантные RAG-таблицы и теги.

### 5. Пример структуры таблиц для RAG и тегов
- `users` — пользователи
- `messages` — сообщения
- `tags` — справочник тегов
- `user_tags` — связь пользователей и тегов (user_id, tag_id)
- `rag_tables` — таблицы знаний (например, FAQ, инструкции)
- `rag_entries` — записи в таблицах знаний (content, rag_table_id, ...)
- `rag_entry_tags` — связь записей знаний и тегов (rag_entry_id, tag_id)

---

## План внедрения RAG-ассистента в CRM

1. **Создать RAG-таблицы для ИИ-ассистента**
   - Таблицы для хранения знаний о компании, продуктах, услугах (например, `rag_tables`, `rag_entries`).
   - Возможность добавлять, редактировать, удалять записи через UI.
   - Каждая запись может быть связана с тегами (например, категория продукта, язык, сегмент клиента).

2. **Создать таблицы с тегами для пользователей**
   - Таблица тегов (`tags`).
   - Связующая таблица `user_tags` (user_id, tag_id).
   - UI для управления тегами и их привязкой к пользователям.

3. **Отредактировать страницу настройки ИИ-ассистента**
   - Добавить выбор, какие RAG-таблицы использовать для поиска.
   - Отображать список тегов, связанных с выбранными таблицами.
   - Возможность быстро подключать/отключать таблицы и теги.

4. **Добавить в раздел "Контакты" фильтры (отдельные компоненты)**
   - Фильтр по новым пользователям.
   - Фильтр по новым входящим сообщениям.
   - Фильтр по тегам (мультиселект).
   - Каждый фильтр реализовать отдельным Vue-компонентом для переиспользования.

5. **В "Детали контакта" добавить инлайн-кнопки**
   - Кнопки:
     - Сгенерировать (ответ с помощью ИИ)
     - Редактировать (отредактировать сгенерированный ответ)
     - Отправить (отправить ответ пользователю)
     - Добавить в RAG-таблицу (сделать сообщение или ответ частью базы знаний)
   - Кнопки должны быть доступны для каждого сообщения в истории.

---

**Этот документ будет дополняться по мере реализации каждого этапа.**