I. Платформа «Эфцекабот»

1. Рабочее название

Эфцекабот — (fckbot, производное от ФЦК БОТ) — корпоративная платформа для интеллектуальной обработки документов и диалогов, реализующая гибридный RAG (Retrieval-Augmented Generation) на базе GigaChat. Платформа включает единое RAG-ядро и несколько специализированных ботов-клиентов (методолог, коробочник, персональный ассистент), работающих в корпоративном мессенджере (XMPP). Ориентирована на поддержку бережливого производства, производительности труда, нормативной документации, ИИ-метрик, разработки лучших практик и коробочных решений, а также других функций.

2. Подход к построению

Архитектура: платформа состоит из трех основных слоев.

1. RAG-ядро (HTTP-сервис) — центральный компонент, выполняющий все этапы обработки запросов: классификацию намерений, расширение запроса, гибридный поиск (dense + sparse) в Qdrant, переранжирование через локальный кросс-энкодер, синтез ответа через GigaChat, самокритику и перегенерацию. Ядро также управляет индексацией документов и хранением истории диалогов в PostgreSQL. RAG-ядро реализовано как отдельный HTTP-сервер (FastAPI + Uvicorn), что позволяет использовать его для любых клиентов (XMPP, Telegram, Mastodon, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты /rag/vision для распознавания текста на изображениях (OCR) и /rag/transcribe для транскрибации аудио, что централизует обработку медиафайлов.

2. Тонкие XMPP-боты-клиенты — каждый профиль (методолог, коробочник, персональный ассистент) представляет собой отдельный XMPP-клиент, который подключается к ejabberd, обрабатывает команды, принимает файлы и пересылает запросы пользователей в RAG-ядро по HTTP. Боты не содержат RAG-логики, не имеют локальной БД или Qdrant, а только загружают свои промпты и передают их в запросах. Это делает их легковесными и независимыми. Вся обработка изображений и аудио выполняется на RAG-сервере, что дополнительно упрощает клиентов.

3. Внешние системы хранения и API:

• Ejabberd — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload);
• PostgreSQL — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи. Управление схемой через Alembic (миграции). Добавлена колонка file_text для хранения исходного текста документов.
• Qdrant — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру.
• GigaChat API — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами.
• Redis (опционально) — кэширование эмбеддингов (TTL 1 час) и результатов SOMA-оценок (TTL 5 мин).
• Внешние API — для инструментов ReAct: DuckDuckGo (поиск), OpenWeatherMap (погода), заглушки для бронирования и курсов валют.

Философия:

• Каждый документ принадлежит контексту (личный, комнатный, глобальный).
• Боты-клиенты не имеют собственных знаний — они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG).
• Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой.
• Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов — все это реализовано в RAG-ядре и доступно всем клиентам.
• Добавлены инновационные техники: SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность, реальные обработчики инструментов, фоновый ReindexWorker для переиндексации документов после сбоев.

Сервисы распределены по джейлам FreeBSD/Linux:

• rag-server (Python 3.11/3.12) — HTTP-сервис RAG-ядра.
• metabot, korobot, persobot — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP.
• Ejabberd, PostgreSQL, Qdrant, Redis — внешние системы.

Инфраструктура развернута на FreeBSD с использованием джейлов (изолированных окружений), ZFS (файловая система с поддержкой снэпшотов и сжатия) и 10-гигабитной внутренней сети между сервисами. Балансировщик HAProxy обеспечивает маршрутизацию внешних запросов и, при необходимости, горизонтальное масштабирование. Автоматические снэпшоты ZFS настроены через zfs-auto-snapshot для надежного резервного копирования.

3. Уникальность решения

1. Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы.

2. Персональный ассистент как часть экосистемы — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи.

3. Единая чат-среда и единый RAG-бэкенд для всех коммуникаций — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram или веб-интерфейс благодаря универсальному HTTP API RAG-ядра.

4. Полный контроль над данными — все компоненты развернуты внутри компании. Никакие документы или переписка не покидают периметр. История и документы хранятся только на серверах компании.

5. Открытая агентная архитектура — можно подключить любого RPA, внешнее API, 1С, SAP, календарь, тревел-агрегатор без необходимости переписывать ядро бота — достаточно реализовать HTTP-клиент к RAG-ядру. Конкуренты, как правило, предлагают закрытые экосистемы.

6. Автоматическая индексация файлов в комнатах — файл, попавший в групповой чат, автоматически становится доступен всей команде через RAG-ядро. Даже у Slack и Teams нет такой функции «из коробки».

7. Встроенные инновационные техники — SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность — позволяют повысить качество ответов, экономить токены и автоматизировать сложные рабочие процессы.

4. Преимущества и недостатки работы бота в чате

Преимущества

• Единое корпоративное окно — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате.
• Мгновенный обмен файлами — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в том числе в групповых комнатах).
• Учет контекста беседы — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб).
• Поддержка комнат (MUC) — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом.
• Легковесные клиенты — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре.
• Не требует установки уникального клиентского ПО — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работы через веб-интерфейс (который также может использовать RAG-ядро).
• Полный контроль данных — развертывание внутри периметра, никаких облачных сервисов.
• Поддерживаемые форматы: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z.
• Размер загружаемого файла: до 1 Гб.
• Расширенные возможности — SOMA-оценка ответов, ReAct-вызовы внешних API, планирование, многоагентность, фоновый ReindexWorker для восстановления после сбоев.

Недостатки

• Задержка — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги, SOMA) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы.
• Сложность отладки — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование, структурированные JSON-логи и единая точка входа (RAG-ядро) упрощают мониторинг.

5. Как чат-бот влияет на работу с GigaChat

Аспект	Влияние
Скорость	GigaChat — облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика, SOMA). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд.
Экономия токенов	Переранжирование и гибридный поиск (sparse + dense) уменьшают объем контекста. История диалога обрезается точно по токенам (через tiktoken) с пагинацией. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что еще больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. Кэширование SOMA-оценок (TTL 5 мин) избегает повторных вызовов.
Качество ответа	GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации — самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Дополнительно внедрен SOMA-анализ (LLM-as-judge), который оценивает ответ по 5 критериям и при низких оценках перегенерирует его. ReAct и планирование повышают точность сложных расчётов и инструкций. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах.
Надежность	GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации (retry с экспоненциальной задержкой), а также использует circuit breaker для защиты от сбоев. При отказе API возвращается сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.).
Гибридные векторы	GigaChat генерирует только dense-эмбеддинги, sparse-векторы вычисляются через FastEmbed (Qdrant/bm25) локально на сервере RAG-ядра. Это разгружает GigaChat и не требует дополнительных API, а также позволяет использовать общий кэш эмбеддингов для всех клиентов.

6. Архитектура проекта

6.1. Общая архитектура

Платформа состоит из трех основных логических слоев.

┌──────────────────────────────────────────────────────────────────────────────────────-┐
│                              ВНЕШНИЕ КЛИЕНТЫ (пользователи)                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │  XMPP-боты  │  │  Telegram   │  │  Mastodon   │  │ Веб-интерф. │  │   API       │  │
│  │  (тонкие)   │  │  (клиент)   │  │  (клиент)   │  │  (клиент)   │  │  интеграции │  │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  │
│         │                │                │                │                │         │
│         └────────────────┼────────────────┼────────────────┼────────────────┘         │
│                          │                │                │                          │
│                          ▼                ▼                ▼                          │
│  ┌────────────────────────────────────────────────────────────────────────────────-┐  │
│  │                         RAG-Сервер (HTTP API / FastAPI)                         │  │
│  │                                                                                 │  │
│  │  ┌──────────────────────────────────────────────────────────────────────────-┐  │  │
│  │  │                         RAG Orchestrator (ядро)                           │  │  │
│  │  │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐  │  │  │
│  │  │  │  History     │ │   Intent     │ │   Query      │ │   Indexing       │  │  │  │
│  │  │  │  Manager     │ │   Router     │ │   Processor  │ │   Manager        │  │  │  │
│  │  │  └──────────────┘ └──────────────┘ └──────┬───────┘ └──────────────────┘  │  │  │
│  │  │                                           │                               │  │  │
│  │  │  ┌────────────────────────────────────────┼───────────────────────────-┐  │  │  │
│  │  │  │              Дополнительные модули     │                            │  │  │  │
│  │  │  │  ┌─────────────┐ ┌─────────────┐ ┌─────┴───-───┐ ┌──────────────┐   │  │  │  │
│  │  │  │  │   SOMA      │ │    ReAct    │ │  Planning   │ │   Agents     │   │  │  │  │
│  │  │  │  │  (LLM-as-   │ │  (внешние   │ │  (генерация │ │  (методолог, │   │  │  │  │
│  │  │  │  │   judge)    │ │  вызовы)    │ │    плана)   │ │  коробочник, │   │  │  │  │
│  │  │  │  └─────────────┘ └─────────────┘ └─────────────┘ │  ассистент)  │   │  │  │  │
│  │  │  │                                                  └──────────────┘   │  │  │  │
│  │  │  │  ┌─────────────────────────────────────────────────────────────────┐│  │  │  │
│  │  │  │  │                    ToolHandler (реальные инструменты)           ││  │  │  │
│  │  │  │  │         search() │ get_weather() │ book_flight() │ exchange()   ││  │  │  │
│  │  │  │  └─────────────────────────────────────────────────────────────────┘│  │  │  │
│  │  │  └─────────────────────────────────────────────────────────────────────┘  │  │  │
│  │  └──────────────────────────────────────────────────────────────────────────-┘  │  │
│  │                                                                                 │  │
│  │  ┌────────────────────────────────────────────────────────────────────────-──┐  │  │
│  │  │                  ReindexWorker (фоновый воркер)                           │  │  │
│  │  │        переиндексация документов с indexed=False                          │  │  │
│  │  └─────────────────────────────────────────────────────────────────────────-─┘  │  │
│  │                                                                                 │  │
│  │  ┌──────────────────────────────────────────────────────────────────────────-┐  │  │
│  │  │                          Эндпоинты REST API                               │  │  │
│  │  │  /rag/query  /rag/index  /rag/vision  /rag/transcribe                     │  │  │
│  │  │  /rag/clear  /rag/list   /rag/delete_global                               │  │  │
│  │  │  /rag/template/*  /rag/reset_history  /rag/room/*  /rag/stats             │  │  │
│  │  │  /rag/generate_document                                                   │  │  │
│  │  │  /health  /docs  /redoc  /openapi.json  /metrics                          │  │  │
│  │  └──────────────────────────────────────────────────────────────────────────-┘  │  │
│  └────────────────────────────────────────────────────────────────────────────────-┘  │
│                                          │                                            │
│                                          ▼                                            │
│  ┌────────────────────────────────────────────────────────────────────────────────-┐  │
│  │                      ВНЕШНИЕ СИСТЕМЫ (данные и API)                             │  │
│  │                                                                                 │  │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────────┐    │  │
│  │  │PostgreSQL │  │  Qdrant   │  │ GigaChat  │  │  Redis    │  │   Файлы     │    │  │
│  │  │(история,  │  │(векторный │  │ (генерация│  │ (кэш эм-  │  │  (DOCX,     │    │  │
│  │  │ документы,│  │ поиск,    │  │ эмбеддинги│  │ беддингов,│  │   PDF,      │    │  │
│  │  │  права,   │  │ гибридный │  │   Vision) │  │   SOMA)   │  │   XLSX,     │    │  │
│  │  │  шаблоны, │  │  dense+   │  │           │  │           │  │   PPTX,     │    │  │
│  │  │  file_text│  │  sparse)  │  │           │  │           │  │   аудио,    │    │  │
│  │  └───────────┘  └───────────┘  └───────────┘  └───────────┘  │   изображ.) │    │  │
│  │                                                              └─────────────┘    │  │
│  │                                                                                 │  │
│  │  ┌──────────────────────────────────────────────────────────────────────────┐   │  │
│  │  │                    ВНЕШНИЕ API (инструменты)                             │   │  │
│  │  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐   │   │  │
│  │  │  │  DuckDuckGo  │  │OpenWeatherMap│  │ Booking API  │  │ Exchange    │   │   │  │
│  │  │  │   (поиск)    │  │  (погода)    │  │  (заглушка)  │  │  Rate API   │   │   │  │
│  │  │  │              │  │              │  │              │  │  (заглушка) │   │   │  │
│  │  │  └──────────────┘  └──────────────┘  └──────────────┘  └─────────────┘   │   │  │
│  │  └──────────────────────────────────────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────────────────────────────-─┘  │
└─────────────────────────────────────────────────────────────────────────────────────-─┘

Ключевые компоненты:

• RAG-сервер — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис.
• RAG Orchestrator — фасад, координирующий менеджеры и модули:
  • HistoryManager — управление историей (пагинация, сжатие).
  • IntentRouter — маршрутизация специализированных намерений.
  • QueryProcessor — интеграция SOMA, ReAct, планирования и агентов.
  • IndexingManager — индексация с предварительным сжатием.
• Дополнительные модули:
  • SOMA (LLM-as-judge) — оценка ответов с кэшированием.
  • ReAct — вызов внешних инструментов (поиск, погода, бронирование, курс).
  • Planning — генерация пошагового плана.
  • Agents — многоагентная архитектура (методолог, коробочник, ассистент).
  • ToolHandler — реальные обработчики инструментов.
• ReindexWorker — фоновый воркер для переиндексации документов после сбоев.
• Эндпоинты — основные, административные, управление шаблонами, комнатами, статистика, генерация документов, health, метрики.
• Внешние системы — PostgreSQL (с file_text, управление через Alembic), Qdrant (гибридный поиск), GigaChat, Redis (кэширование), файлы, внешние API.

6.2. Структура каталогов проекта

Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта.

/usr/local/etc/fckbot/                   # КОРЕНЬ ПРОЕКТА
│ 
├── alembic.ini                          # Конфигурация Alembic (миграции)
│ 
├── rag/                                 # RAG-ядро (HTTP-сервер)
│   ├── alembic/                         # Миграции PostgreSQL
│   │   ├── env.py                       # Настройка окружения для Alembic
│   │   ├── script.py.mako               # Шаблон для миграций
│   │   └── versions/                    # Папка с миграциями
│   ├── auth.py                          # Аутентификация (проверка API-ключа)
│   ├── config_models.py                 # Pydantic-модели для конфигурации (AppConfig)
│   ├── create_qdrant_collection.py      # Скрипт создания коллекции в Qdrant
│   ├── history_manager.py               # Менеджер истории диалогов (сжатие, пагинация, обрезка)
│   ├── indexing_manager.py              # Менеджер индексации документов (сжатие, вызов KBService)
│   ├── intent_router.py                 # Маршрутизатор специализированных намерений
│   ├── prompt_builder.py                # Построитель промтов (few-shot, сэндвич, санитизация)
│   ├── query_processor.py               # Обработчик RAG-запросов (поиск, синтез, критика, SOMA, ReAct, планирование, агенты)
│   ├── rag_api.py                       # Локальный API-интерфейс (facade)
│   ├── rag.conf.example                 # Шаблон конфига RAG-сервера (YAML): БД, Qdrant, GigaChat, Redis, новые параметры
│   ├── rag_orchestrator.py              # Оркестратор RAG-пайплайна (менеджеры, ToolHandler)
│   ├── rag_server.py                    # HTTP-сервер на FastAPI + Uvicorn (точка входа)
│   ├── README.md                        # Документация (этот файл)
│   ├── requirements.txt                 # Зависимости Python (включая tenacity, pybreaker, redis, aioredis, python-json-logger)
│   ├── schema.sql                       # Схема PostgreSQL (используется только для тестов; в продакшене — Alembic)
│   ├── functions/                       # Чистые функции (без состояния)
│   │   ├── check_consistency.py         # Проверка противоречий
│   │   ├── check_spelling.py            # Проверка орфографии
│   │   ├── critique_answer.py           # Самокритика ответа
│   │   ├── expand_query.py              # Расширение запроса
│   │   ├── extract_metrics.py           # Извлечение KPI в JSON
│   │   ├── file_processor.py            # Обработка файлов, теги SURGICAL_REPLACE и др.
│   │   ├── generate_document.py         # Генерация документа по шаблону
│   │   ├── hierarchical_summarize.py    # Иерархическое резюмирование
│   │   ├── intent_classify.py           # Классификация намерений
│   │   ├── plan_generation.py           # Генерация плана действий (новый)
│   │   ├── react.py                     # Цикл ReAct (вызов внешних инструментов)
│   │   ├── rerank_context.py            # Переранжирование контекста
│   │   ├── soma_evaluate.py             # SOMA-анализ (LLM-as-judge) с кэшированием
│   │   ├── summarize_document.py        # Суммаризация документа
│   │   └── tools.py                     # Реальные обработчики инструментов (поиск, погода, бронирование, курс)
│   ├── services/                        # Сервисы (долгоживущие компоненты)
│   │   ├── embedding_service.py         # Эмбеддинги GigaChat с кэшированием (Redis + локальный)
│   │   ├── file_service.py              # Извлечение текста из файлов, транскрибация (экранирование путей)
│   │   ├── giga_client.py               # Клиент GigaChat с retry и circuit breaker
│   │   ├── kb_service.py                # База знаний (индексация, поиск, управление доступом, file_text)
│   │   ├── postgres_service.py          # Пул соединений с PostgreSQL (с проверкой таблиц, Alembic)
│   │   ├── qdrant_service.py            # Векторная БД (гибридный поиск, полнотекстовый, индексы)
│   │   └── reranker_service.py          # Кросс-энкодер с асинхронной загрузкой модели
│   ├── utils/                           # Утилиты
│   │   ├── arg_parser.py                # Парсинг аргументов командной строки
│   │   ├── config_loader.py             # Загрузка конфигов, слияние, создание AppConfig
│   │   ├── logger.py                    # Настройка логирования (с поддержкой JSON-формата)
│   │   ├── text_utils.py                # Разбиение на чанки, подсчет токенов
│   │   └── web_utils.py                 # Веб-скрапинг (с ограничением размера)
│   └── workers/                         # Фоновые воркеры
│       └── reindex_worker.py            # Переиндексация документов с indexed=False
│ 
├── bots/                                # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ
│   ├── bot.py                           # Точка входа для запуска XMPP-бота (принимает --profile-dir)
│   ├── rag_client.py                    # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками)
│   ├── commands/                        # Команды ботов (XMPP-интерфейс)
│   │   ├── base.py                      # Базовый класс Command (алиасы, права доступа, кэширование)
│   │   ├── create.py                    # !create – генерация документа по шаблону
│   │   ├── expert.py                    # !summary, !metrics – экспертные функции
│   │   ├── global_remove.py             # !global_remove – удаление глобального документа (админ)
│   │   ├── help.py                      # !help – подробная справка по командам
│   │   ├── info.py                      # !info – краткая справка
│   │   ├── kb.py                        # !clear, !global_clear, !kb – управление базой знаний
│   │   ├── learn.py                     # !learn, !stop_learn, !global_learn – режим обучения
│   │   ├── other.py                     # !reset – сброс истории
│   │   ├── registry.py                  # Регистрация команд, алиасы, подсказки при опечатке
│   │   ├── stats.py                     # !stats, !status, !clean – администрирование
│   │   └── template.py                  # !template_save, !template_list, !template_delete – шаблоны
│   ├── handlers/                        # Обработчики XMPP событий
│   │   ├── file_handler.py              # Скачивание файлов и постановка в очередь индексации
│   │   ├── health_handler.py            # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов)
│   │   ├── message_handler.py           # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient
│   │   ├── metrics_handler.py           # Счетчики (сообщения, файлы, AI-запросы, ошибки)
│   │   ├── room_handler.py              # MUC комнаты (приглашения, вход, переподключение)
│   │   └── subscription_handler.py      # Подписки (roster subscription)
│   ├── workers/                         # Фоновые воркеры
│   │   └── indexing_worker.py           # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient)
│   └── xmpp/                            # XMPP-клиент
│       └── client.py                    # Основной класс Bot (наследует slixmpp.ClientXMPP)
│ 
├── template_bot_profile/                # ШАБЛОН ПРОФИЛЯ (для создания новых ботов)
│   ├── bot.conf.sample                  # Пример конфига бота-клиента (копируется в bot.conf)
│   ├── data/                            # Каталог для постоянных копий файлов
│   │   └── fewshot_examples.json        # Примеры few-shot (можно редактировать)
│   ├── prompts/                         # Пример промптов (копируются в профиль)
│   │   ├── consistency_check.txt        # Проверка противоречий между фрагментами
│   │   ├── expand.txt                   # Расширение запроса (синонимы, аббревиатуры)
│   │   ├── generate_document.txt        # Генерация документа по шаблону
│   │   ├── hierarchical_summary.txt     # Иерархическое резюмирование
│   │   ├── intent_classify.txt          # Классификация намерений
│   │   ├── metrics_extract.txt          # Извлечение KPI в JSON
│   │   ├── quality_criteria.txt         # Дополнительные критерии качества ответа
│   │   ├── self_critique.txt            # Самокритика ответа
│   │   ├── smart_summary.txt            # Суммаризация документа
│   │   ├── spellcheck.txt               # Проверка орфографии и пунктуации
│   │   ├── synthesis.txt                # Шаблон синтеза ответа
│   │   ├── soma_evaluate.txt            # Промпт для SOMA
│   │   ├── react_system.txt             # Системный промпт для ReAct
│   │   ├── planning.txt                 # Промпт для генерации плана
│   │   └── system.txt                   # Системный промпт (роль, стиль, правила)
│   └── temp/                            # Пустой каталог для временных файлов
│ 
├── tests/                               # ЮНИТ-ТеТЫ (общие для всего проекта)
│   ├── conftest.py                      # Фикстуры и моки для pytest
│   ├── test_check_spelling.py           # Тесты проверки орфографии
│   ├── test_consistency.py              # Тесты проверки противоречий
│   ├── test_critique.py                 # Тесты самокритики
│   ├── test_expand_query.py             # Тесты расширения запроса
│   ├── test_extract_metrics.py          # Тесты извлечения метрик
│   ├── test_hierarchical_summary.txt    # Тесты иерархического резюмирования
│   ├── test_intent_classify.py          # Тесты классификации намерений
│   └── test_summarize.py                # Тесты суммаризации
│ 
├── venv/                                # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python
│   ├── bin/                             # Исполняемые файлы (python, pip, activate)
│   ├── lib/                             # Установленные библиотеки
│   └── ...
│ 
└── .env.example                         # ШАБЛОН ПЕРЕМЕННЫХ ОКРУЖЕНИЯ
    ├── XMPP_PASSWORD=...                # Пароль для XMPP-аккаунта бота
    ├── DB_PASSWORD=...                  # Пароль для PostgreSQL
    ├── GIGACHAT_API_KEY=...             # API-ключ GigaChat
    ├── SALUTE_SPEECH_AUTH=...           # Авторизация для SaluteSpeech (голосовые сообщения)
    └── RAG_API_KEY=...                  # API-ключ для доступа к RAG-серверу (защита эндпоинтов)

Важные примечания:

• Реальные профили ботов создаются администратором вручную вне репозитория.
• Конфигурационные файлы и переменные окружения не хранятся в репозитории.
• Управление схемой PostgreSQL — через Alembic (миграции в rag/alembic/).
• Все новые модули (SOMA, ReAct, планирование, агенты, ToolHandler, ReindexWorker) интегрированы в основной пайплайн.

6.3. Взаимодействие компонентов

┌─────────────┐      HTTP      ┌─────────────┐      SQL       ┌─────────────┐
│   Пользова- │ ──────────────▶│    RAG-     │ ──────────────▶│ PostgreSQL  │
│    тель     │                │   сервер    │                │  (история,  │
│   (XMPP)    │ ◀──────────────│   (ядро)    │ ◀──────────────│  документы, │
└─────────────┘                └─────────────┘                │  file_text) │
      │                               │                       └─────────────┘
      │ XMPP                          │ HTTP (gRPC)                  │
      ▼                               ▼                              ▼
┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│  ejabberd   │                │   Qdrant    │                │  GigaChat   │
│ (чат-серв.) │                │ (векторная  │                │   (API)     │
└─────────────┘                │     БД)     │                └─────────────┘
      │                        └─────────────┘                       │
      │ XMPP                          │                              │
      ▼                               ▼                              ▼
┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│  XMPP-бот   │                │ FastEmbed   │                │   Файлы     │
│  (тонкий)   │                │ (локальный  │                │   (диск)    │
│  клиент     │                │ кросс-энк.) │                └─────────────┘
└─────────────┘                └─────────────┘
      │                               │                              │
      │                               │                              │
      ▼                               ▼                              ▼
┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│   Redis     │                │   Tool-     │                │   Reindex-  │
│ (кэш эм-    │                │   Handler   │                │   Worker    │
│ беддингов,  │                │ (внешние    │                │ (фоновый)   │
│  SOMA)      │                │   API)      │                └─────────────┘
└─────────────┘                └─────────────┘

Поток данных:

1. Запрос пользователя → XMPP-бот → HTTP → RAG-сервер.
2. RAG-сервер:
   • Получает историю из PostgreSQL (с пагинацией и обрезкой).
   • Выполняет классификацию намерений.
   • При необходимости вызывает SOMA, ReAct, планирование, агентов.
   • Ищет в Qdrant (гибридный поиск), переранжирует, генерирует ответ через GigaChat.
   • Выполняет самокритику и SOMA-оценку, при низких оценках перегенерирует.
   • Сохраняет историю в PostgreSQL.
3. Ответ → HTTP → XMPP-бот → ejabberd → пользователь.
4. Индексация файла → XMPP-бот → HTTP → RAG-сервер → разбиение на чанки, эмбеддинги (кэшируются в Redis), сохранение в Qdrant и PostgreSQL (с file_text).
5. OCR/транскрибация → XMPP-бот → HTTP → RAG-сервер → распознанный текст.
6. ReindexWorker периодически проверяет документы с indexed=False и переиндексирует их, используя сохранённый file_text.
7. ReAct вызывает внешние API через ToolHandler (поиск, погода, бронирование, курс).

6.4. Тестирование

Проект покрыт unit-тестами и интеграционными тестами.

Unit-тесты (в tests/) проверяют критически важные функции:

• классификацию намерений (test_intent_classify.py);
• расширение запроса (test_expand_query.py);
• извлечение метрик (test_extract_metrics.py);
• суммаризацию (test_summarize.py);
• проверку противоречий (test_consistency.py);
• самокритику (test_critique.py);
• проверку орфографии (test_check_spelling.py);
• иерархическое резюмирование (test_hierarchical_summarize.py).

Интеграционные тесты (в tests/integration/) проверяют:

• эндпоинты RAG-сервера (test_endpoints.py) – /rag/clear, /rag/list, /rag/delete_global, /rag/template/*, /rag/reset_history, /rag/room/*, /rag/stats, /rag/generate_document.
• переработанные команды бота (test_commands.py) – !clear, !kb, !global_remove, !reset, !template_*, !stats, !status, !create, !summary, !metrics, !learn и др.

Запуск всех тестов:

cd /usr/local/etc/fckbot
source venv/bin/activate
pytest tests/ -v

Для тестирования RAG-сервера отдельно можно использовать curl или Postman.

6.5. Конфигурационные параметры

В bot.conf доступны следующие параметры RAG-пайплайна (добавлены новые):

• max_context_tokens — лимит токенов для истории диалога (по умолчанию 3000).
• rerank.min_length — порог длины контекста для переранжирования (по умолчанию 5000).
• rag_server_url — URL RAG-сервера (используется ботами).
• mention_keyword — ключевое слово для упоминания бота в группах.
• fewshot — настройки few-shot примеров (max_examples, examples_file).

Включение/отключение новых функций

enable_soma: true enable_react: true enable_planning: true enable_agents: true enable_reindex: true

Параметры SOMA

soma_temperature: 0.1 soma_threshold: 3.5 soma_cache_ttl: 300 # TTL кэша SOMA (сек) soma_timeout: 30

Параметры ReAct

react_temperature: 0.3 react_max_iterations: 5

Параметры планирования

planning_temperature: 0.2

Параметры ReindexWorker

reindex_interval: 300 # интервал проверки (сек) reindex_batch_size: 10

Параметры агентов

agent_temperature: 0.3

API-ключи для инструментов

weather_api_key: "" # для OpenWeatherMap

Redis для кэширования

redis_url: "redis://localhost:6379"

Лимиты истории

max_history_message_length: 10000

Эти параметры позволяют гибко настраивать поведение без изменения кода.

6.6. Основные слои (что есть что)

Слой	Назначение
RAG-сервер (rag_server.py)	HTTP-сервис, обрабатывающий все RAG-запросы. Содержит оркестратор, ReindexWorker, ToolHandler. Предоставляет эндпоинты для команд бота, статистики, шаблонов, комнат.
RAG-оркестратор (rag_orchestrator.py)	Фасад, координирующий менеджеры и модули. Содержит HistoryManager, IntentRouter, QueryProcessor, IndexingManager.
Менеджер истории (history_manager.py)	Получение истории из БД, сжатие (иерархическое резюмирование), сохранение новых сообщений. Поддерживает пагинацию и обрезку сообщений.
Маршрутизатор намерений (intent_router.py)	Обрабатывает специализированные намерения (METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SURGICAL, GREETING, SPELLCHECK).
Процессор запросов (query_processor.py)	Выполняет RAG-пайплайн с интеграцией SOMA, ReAct, планирования и агентов. Использует ToolHandler для вызова внешних инструментов.
Построитель промтов (prompt_builder.py)	Динамический подбор few-shot, санитизация пользовательских данных, структура «сэндвич».
Менеджер индексации (indexing_manager.py)	Сжимает большие документы, вызывает KBService.
HTTP-клиент (rag_client.py)	Используется ботами для отправки запросов к RAG-серверу. Асинхронный, с повторными попытками.
Сервисы (services/)	Долгоживущие компоненты: PostgreSQL, Qdrant, эмбеддинги, база знаний, файлы, GigaChat, переранжирование.
Функции (functions/)	Чистые функции: классификация, расширение, суммаризация, проверка противоречий, самокритика, иерархическое резюмирование, SOMA, ReAct, планирование, генерация плана, инструменты.
XMPP-боты-клиенты (xmpp/client.py)	Тонкие клиенты, только XMPP-логика и команды, все RAG-запросы через rag_client.py.
Обработчики XMPP (handlers/)	Реагируют на события XMPP, маршрутизируют запросы.
Воркеры (workers/)	Фоновые задачи: indexing_worker (индексация файлов и URL) и reindex_worker (переиндексация после сбоев).
Команды (commands/)	Реализуют команды бота, используют только RAGClient.
Утилиты (utils/)	Вспомогательные функции (конфигурация, логирование, чанкинг, веб-скрапинг, парсинг аргументов).
Alembic (alembic/)	Управление версиями схемы PostgreSQL.

7. Функции бота

Ниже представлен полный перечень функций платформы Эфцекабот, доступных пользователям. Каждая функция описана максимально детально: указано, что она делает, в чем ее уникальность, какая от нее польза, а также приведены все возможные сценарии использования — от простых запросов до сложных рабочих процессов.

Ранжирование по ценности

Место	Функция	Обоснование
1	Генерация по шаблону	Основной инструмент для создания коробочных решений — автоматизирует производство документов.
2	Гибридный RAG	Без него бот не может отвечать по документам — фундамент системы.
3	Комнатные/глобальные БЗ	Обеспечивают коллективную работу над коробочными решениями.
4	SOMA-анализ (LLM-as-judge)	Значительно повышает качество ответов, экономит токены за счёт кэширования.
5	ReAct (вызов внешних инструментов)	Открывает возможность выполнения реальных действий (поиск, погода, бронирование).
6	Планирование действий	Повышает точность расчётов и инструкций.
7	Многоагентность	Позволяет специализировать ботов под разные роли, повышая качество экспертных ответов.
8	Хирургическая замена	Ускоряет доработку документов.
9	Проверка орфографии	Повышает качество исходящих документов.
10	Суммаризация	Ускоряет анализ больших объемов информации.
11	Самокритика	Повышает надежность ответов.
12	Извлечение метрик	Автоматизирует сбор KPI.
13	Проверка противоречий	Исключает ошибки в документации.
14	Классификация намерений	Обеспечивает интеллектуальную маршрутизацию.
15	Цепочка рассуждений	Повышает точность расчетов и инструкций.
16	Полнотекстовый поиск	Гарантирует юридическую точность и поиск инструкций.
17	Расширение запроса	Улучшает полноту поиска.
18	Переранжирование	Экономит токены и повышает точность.
19	Автоиндексация	Упрощает коллективную работу.
20	Веб-скрапинг	Интегрирует внешние источники.
21	Голосовые сообщения	Удобство для мобильных пользователей.
22	Администрирование	Оперативный контроль без доступа к серверу.

7.1. Ключевые функции для создания документов (коробочных решений)

1. Генерация коробочных решений по шаблону

Что делает:
По команде !create "Коробочное решение" бот генерирует готовый коробочный документ на основе шаблона, заполняя все плейсхолдеры {{...}} данными из базы знаний комнаты. Шаблон содержит следующие разделы (соответствует файлу Шаблон коробочного решения.docx):

1. Профиль коробочного решения — параметры внедрения, ресурсы, сроки.
2. Актуальность коробочного решения — потенциал повышения производительности, задачи, ожидаемые результаты.
3. Решаемая проблема — типовой процесс (до улучшения), проблемные зоны, коренные причины.
4. Решение — целевой процесс (после улучшения), детальное описание решений, результаты внедрения.
5. Алгоритм внедрения коробочного решения — состав рабочей группы, последовательность этапов.
6. Риски — описание рисков и мер по их снижению.
7. Термины, сокращения, определения — глоссарий из документов комнаты.
8. Сопроводительные документы — перечень приложений, шаблонов, регламентов.
9. Лучшие практики — ссылки на реализованные аналогичные решения.

Уникальность:
Превращает бота из информатора в инструмент производства готовых коробочных решений. Достаточно один раз настроить шаблон, и бот будет генерировать документы на основе актуальных данных из базы знаний. Все, что требуется от пользователя — загрузить в комнату документы-источники (регламенты, отчеты, методики, ГОСТы, аналитические записки).

Польза:
Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1–2 недель до 10–30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций.

Примеры использования (все возможные сценарии):

1.1. Сохранение шаблона коробочного решения

Загружаете в чат DOCX-файл Шаблон коробочного решения.docx (содержит плейсхолдеры вида {{DOC_CODE}}, {{TARGET_ORG_TYPES}} и т.д.). Вводите:

!template_save "Коробочное решение v1.0"

Бот сохраняет шаблон в БД комнаты как "Коробочное решение v1.0". Если шаблон с таким именем уже существует – он перезаписывается.

1.2. Просмотр всех шаблонов в комнате

!template_list

Бот выводит список: «Коробочное решение v1.0», «Коробочное решение v2.0», «Договор поставки» и т.д.

1.3. Генерация коробочного решения

Вы вводите:

!create "Коробочное решение v1.0"

Бот выполняет следующие шаги:

1. Извлекает шаблон из БД комнаты.

2. Находит все плейсхолдеры в шаблоне (их около 70+):

   • Профиль: {{DOC_CODE}}, {{TARGET_ORG_TYPES}}, {{TARGET_ORG_COUNT}}, {{FINANCIAL_RESOURCES}}, {{HUMAN_RESOURCES}}, {{IMPLEMENTATION_TERM_MIN}}, {{KPI_NAME}}, {{KPI_BEFORE}}, {{KPI_AFTER}} и т.д.
   • Актуальность: {{PROCESS_NAME}}, {{DATA_DATE}}, {{TOTAL_STAFF}}, {{TYPICAL_PROBLEM_DESCRIPTION}}, {{PREREQUISITE_1}}, {{TASK_1}}, {{RESULT_1}} и т.д.
   • Решаемая проблема: {{STAGE_1_NAME}}, {{STAGE_1_ACTORS}}, {{STAGE_1_PROBLEMS}}, {{ROOT_CAUSE_1}} и т.д.
   • Решение: {{TARGET_STAGE_1_DESC}}, {{IMPROVEMENT_1}}, {{SOLUTION_1_NAME}}, {{SOLUTION_1_DESCRIPTION}}, {{KPI_1_NAME}} и т.д.
   • Алгоритм внедрения: {{ROLE_1}}, {{ROLE_1_DUTIES}}, {{STAGE1_DURATION}}, {{STAGE1_ACTIONS}} и т.д.
   • Риски: {{RISK_1_NAME}}, {{RISK_1_DESCRIPTION}}, {{RISK_1_MITIGATION}}.
   • Термины: {{TERM_1}}, {{TERM_1_DEF}}.
   • Сопроводительные документы: {{APPENDIX_1_NAME}}.
   • Лучшие практики: {{BEST_PRACTICE_1_LINK}}, {{BEST_PRACTICE_1_DESC}}.

3. Для каждого плейсхолдера выполняет поиск в базе знаний комнаты (личные + комнатные + глобальные документы). Поиск использует:

   • Семантический поиск (dense-эмбеддинги) — для общих запросов.
   • Полнотекстовый поиск (MatchText) — для точных цитат и номеров пунктов.
   • Расширение запроса (query expansion) — добавляет синонимы и аббревиатуры.
   • Переранжирование (кросс-энкодер) — отбирает только релевантные фрагменты.

4. Формирует промпт для GigaChat с инструкцией заполнить плейсхолдер на основе найденных фрагментов. Промпт содержит контекст из фрагментов документов и сам плейсхолдер.

5. Генерирует значение для каждого плейсхолдера — например, для {{TYPICAL_PROBLEM_DESCRIPTION}} GigaChat напишет: «В региональной системе наблюдается дефицит сотрудников с профильным образованием (только 30% из 100), нерегулярное планирование, отсутствие единой методики оценки компетенций».

6. Заменяет плейсхолдеры в копии шаблона, сохраняя все форматирование (жирный шрифт, курсив, цвета, таблицы, колонтитулы). Замена выполняется с учетом возможного разбиения текста на несколько runs в DOCX, что повышает точность.

7. Отправляет готовый DOCX-файл в чат.

Пример заполнения (фрагменты):

**{{DOC_CODE}}** → **КР-5S-2025-001**
**{{TARGET_ORG_TYPES}}** → «Библиотеки, культурно-досуговые учреждения»
**{{TARGET_ORG_COUNT}}** → «47»
**{{FINANCIAL_RESOURCES}}** → «1 200»
**{{HUMAN_RESOURCES}}** → «5»
**{{IMPLEMENTATION_TERM_MIN}}** → «3»
**{{KPI_NAME}}** → «Процент сотрудников с профильным образованием»
**{{KPI_BEFORE}}** → «30%»
**{{KPI_AFTER}}** → «85%»

1.4. Обновление коробочного решения

Если вы улучшили шаблон или изменили структуру, загружаете новую версию DOCX и повторяете:

!template_save "Коробочное решение v1.0"

Старый шаблон перезаписывается новым. Все последующие генерации будут использовать обновленный шаблон.

1.5. Удаление шаблона

!template_delete "Коробочное решение v1.0"

Шаблон удаляется из БД комнаты.

1.6. Кастомизация шаблона под конкретный проект

Вы можете создать несколько версий шаблона для разных типов организаций или отраслей:

!template_save "Коробочное решение_Библиотеки"
!template_save "Коробочное решение_Музеи"
!template_save "Коробочное решение_Образование"

Затем генерировать нужную версию:

!create "Коробочное решение_Библиотеки"

1.7. Использование общих знаний (если разрешено)

Если для какого-то плейсхолдера не нашлось данных в БЗ (например, {{BEST_PRACTICE_1_LINK}}), бот может использовать свои общие знания для заполнения (если в конфиге allow_public_knowledge: true). Это полезно для лучших практик и терминов.

1.8. Многоязычность

Если в документах есть информация на иностранном языке, бот переведет ее на язык шаблона (русский) и заполнит плейсхолдер.

Пример: плейсхолдер {{KPI_NAME}} – бот найдет в английских документах «Overall Equipment Effectiveness» и переведет как «Общая эффективность оборудования» (или оставит аббревиатуру OEE, если так указано в документах).

2. Гибридный RAG с самокритикой

Что делает:
Это ядро системы, которое используется для поиска данных для каждого плейсхолдера шаблона. Бот выполняет:

• Семантический поиск (dense-эмбеддинги от GigaChat);
• Ключевой поиск (sparse-векторы BM25 от FastEmbed);
• Объединение через Reciprocal Rank Fusion (RRF);
• Генерацию ответа через GigaChat;
• Проверку через самокритику (оценка по 5 критериям);
• Перегенерацию при необходимости.

Уникальность:
Комбинация двух типов поиска + самокритика – это значительно повышает точность и доверие к ответам. Редкая функция для корпоративных ботов.

Польза:
Гарантирует, что ответ или каждое значение в коробочном решении основано на реальных документах, а не на выдумках LLM. Это критично для юридической и финансовой достоверности. Это фундамент, без которого остальные функции теряют смысл.

Примеры использования:

1. Фактологический вопрос (FACT):

   • «Какое тактовое время установлено на линии сборки?»
   • Бот ищет в документах (регламент линии, паспорт оборудования) и выдает точное значение с указанием источника:
     Тактовое время на линии сборки составляет 120 секунд. [Источник: Регламент_линии_2025.docx]

2. Инструкция / процедура (PROCEDURE):

   • «Как рассчитать OEE для станка?»
   • Бот находит алгоритм расчета в методических документах и выдает пошаговое руководство (с цепочкой рассуждений).

3. Сравнение показателей (COMPARISON):

   • «Сравни производительность труда до и после внедрения кайдзен»
   • Бот находит данные в отчетах (по периодам) и выдает сравнительный анализ с цифрами.

4. Расчет по формуле (CALCULATION):

   • «Рассчитай ожидаемую выработку на следующую смену при загрузке 120%»
   • Бот использует формулу из документов, выполняет расчет (пошагово) и выдает результат.

5. Поиск по юридически значимым пунктам:

   • «Выведи пункт 3.2.1 из договора №123»
   • Бот переключается на точный подстроковый поиск (см. пункт 12) и выдает цитату.

6. Общий вопрос (GENERAL):

   • «О чем этот документ?»
   • Бот дает краткое описание на основе содержания (если есть контекст).

7. Приветствие (GREETING):

   • «Привет» – бот отвечает вежливо, без поиска.

Примеры использования для коробочных решений:

1. Поиск KPI по ключевым словам:

   • Для плейсхолдера {{KPI_NAME}} бот ищет в документах упоминания показателей: «OEE», «процент брака», «выработка на человека».
   • Находит в отчетах: «Процент сотрудников с профильным образованием».
   • Возвращает точное название.

2. Поиск числовых значений:

   • Для {{KPI_BEFORE}} и {{KPI_AFTER}} бот находит в документах цифры: «в 2024 году – 30%», «целевой показатель – 85%».
   • Возвращает числа.

3. Поиск корневых причин проблем:

   • Для {{ROOT_CAUSE_1}} бот анализирует документы и выделяет ключевые проблемы: «дефицит кадров», «отсутствие регламентов», «нерегулярное планирование».

4. Поиск постановки задач:

   • Для {{TASK_1}} бот находит в стратегических документах перечень задач: «разработать стандарт», «обучить персонал», «внедрить систему мониторинга».

3. Комнатные и глобальные базы знаний

Что делает:
Документы могут быть трех типов:

• Личные – видны только владельцу (загружаются в личном чате без флагов).
• Комнатные – доступны всем участникам комнаты (автоматически при загрузке в групповой чат).
• Глобальные – доступны всем пользователям (загружаются администратором с флагом --global в личном чате).

Последний загруженный файл привязан к комнате, что предотвращает перезапись файлов разных пользователей в одной комнате.

Уникальность:
Позволяет естественно разграничивать доступ и организовывать коллективную работу. Редко встречается в RAG-ботах.

Польза:
Юридические документы для всех сотрудников (глобальные), конфиденциальные отчеты для отдела (комнатные), личные заметки – все в одном боте. Команда может совместно разрабатывать шаблоны и коробочные решения.

Примеры использования:

1. Личная БЗ:

   • В личном чате с ботом загружаете файл (например, личный план работы). Бот индексирует его как личный – доступен только вам.

2. Комнатная БЗ:

   • В групповом чате загружаете файл (регламент отдела). Бот автоматически индексирует его в комнатную БЗ – доступен всем участникам комнаты.

3. Глобальная БЗ:

   • Администратор в личном чате вводит:
     !learn --global
     Затем отправляет файл (или ссылку). Бот индексирует документ как глобальный – доступен всем пользователям во всех контекстах.

4. Просмотр доступных документов:

   • !kb – в личном чате покажет список личных + глобальных документов.
   • !kb в комнате – покажет комнатные + глобальные документы.

5. Очистка БЗ:

   • !clear – в личном чате очищает личную БЗ.
   • !clear в комнате (только админ) – очищает комнатную БЗ.
   • !global_clear (админ, личный чат) – очищает глобальную БЗ.

6. Удаление конкретного глобального документа (админ):

   • !global_remove "Название документа" – удаляет документ из глобальной БЗ по точному названию.

7.2. Функции работы с документами

4. «Хирургическая» (точечная) замена текста в DOCX

Что делает:
По запросу «замени старое слово на новое» бот выполняет умную замену с учетом грамматических форм (падежи, числа, роды) без потери форматирования. Поддерживает замену словоформ (например, «учеников» → «строителей»). Работает только с DOCX, использует морфологический анализатор mawo-pymorphy3.

Уникальность:
Очень редкая функция для RAG-систем; превращает бота из информатора в инструмент редактирования документов.

Польза:
Автоматизация рутинных правок в отчетах, договорах, планах. Снижение человеческих ошибок. Экономия времени на переделку документов.

Примеры использования (все возможные сценарии):

1. Простая замена:

   • Загружаете DOCX, затем вводите:
     Замени ООО "Ромашка" на ООО "Тюльпан"
   • Бот заменяет все вхождения во всех падежах (ООО "Ромашка", "Ромашке", "Ромашку" и т.д.) и возвращает исправленный файл.

2. Замена с морфологией:

   • Замени учеников на строителей
   • Бот заменит «ученик», «ученика», «ученикам», «учениками» и т.д. на соответствующие формы «строитель», «строителя», «строителям», «строителями» и т.д.

3. Замена дат или чисел:

   • Замени 2024 на 2025
   • Заменит все цифры 2024 (в том числе в тексте и таблицах) на 2025.

4. Множественные замены – можно загрузить файл и выполнить несколько команд подряд, бот будет применять их последовательно (каждая команда работает с последним измененным файлом).

5. Замена в таблицах и колонтитулах – замены выполняются во всех элементах документа, включая таблицы, сноски, колонтитулы и надписи.

6. Сохранение форматирования – замены выполняются без потери жирного шрифта, курсива, подчеркивания, цветов, размеров шрифта, выравнивания.

7. Работа с архивами – если загружен ZIP-архив, бот распаковывает его, выполняет замену во всех DOCX-файлах внутри и упаковывает обратно (если включена поддержка архивов).

5. Проверка орфографии

Что делает:
Пользователь загружает DOCX, затем пишет «Проверь орфографию» или «Найди ошибки». Бот разбивает текст на чанки (учитывая токены), отправляет каждый чанк в GigaChat с промптом на исправление ошибок. Исправления применяются с сохранением форматирования. Возвращает исправленный файл и список изменений в виде «было → стало».

Уникальность:
Автоматическое исправление ошибок в готовых документов без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию razdel для разбиения на предложения).

Польза:
Экономия времени на вычитку, повышение грамотности исходящих документов. Незаменимо при подготовке коробочных решений и официальных документов.

Примеры использования:

1. Базовая проверка:

   • Загружаете DOCX, пишете:
     Проверь орфографию
   • Бот возвращает исправленный файл и список всех исправлений:
     было «пашол» → стало «пошел»
было «молоко хлеб» → стало «молоко, хлеб»

2. Альтернативные команды:

   • Найди ошибки в документе
   • Исправь ошибки
   • Проверь грамматику
   • Работают аналогично.

3. Проверка с сохранением стиля – бот исправляет только орфографические и пунктуационные ошибки, не меняет структуру предложений, не заменяет синонимы, не улучшает стилистику (это сделано намеренно, чтобы сохранить авторский стиль).

4. Обработка ошибок парсинга – если GigaChat не смог сформировать список изменений в требуемом формате ([CHANGES]...[/CHANGES]), бот покажет сырой ответ модели, чтобы исправления не потерялись, и предложит проверить вручную.

5. Работа с большими документами – текст разбивается на чанки (по токенам) и обрабатывается последовательно, что позволяет проверять документы любого размера.

6. Только в личном чате – проверка орфографии доступна только в личном чате с ботом (для безопасности и предотвращения спама в комнатах).

6. Суммаризация документа

Что делает:
Создает краткий пересказ (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. Использует промпт, который фокусируется на наиболее важных аспектах документа.

Уникальность:
Не просто сжатие, а интеллектуальное выделение самой важной информации на основе промпта (а не просто первые предложения).

Польза:
Быстрое ознакомление с объемными регламентами, отчетами, ГОСТами. Ускоряет анализ больших документов при разработке коробочных решений.

Примеры использования:

1. Суммаризация последнего загруженного файла:

   • !summary
   • Бот выдает краткое изложение документа (не более 30% объема) с выделением цели, выводов и ключевых цифр. В конце обязательно указывается источник.

2. Автоматическая суммаризация при намерении SUMMARY – если пользователь спросит «Сделай суммаризацию документа», классификатор распознает это намерение и вызовет функцию автоматически (без команды !summary).

3. Фокус на числовых показателях – если в документе есть OEE, такт, выработка, проценты, они выделяются в отдельный раздел.

4. Быстрое ознакомление – можно использовать для регламентов, ГОСТов, длинных отчетов, чтобы понять суть за 1–2 минуты.

5. Ограничение длины – если документ длиннее max_chars (по умолчанию 8000 символов), он обрезается по границам предложений (с использованием razdel), чтобы суммаризация была по полному тексту.

7.3. Функции анализа и качества

7. Самокритика ответа с перегенерацией

Что делает:
После генерации ответа другой экземпляр LLM оценивает его по пяти критериям:

1. Соответствие источнику – все ли факты подтверждаются контекстом.
2. Отсутствие галлюцинаций – нет ли информации, отсутствующей в контексте.
3. Соблюдение стиля и форматирования (нет LaTeX, есть источники, правильные списки).
4. Логическая связность – ответ не противоречит сам себе.
5. Запрет внешних знаний – не используются личные знания модели (если allow_public_knowledge = false).

При неудовлетворительной оценке ответ перегенерируется один раз. Если и после перегенерации неудовлетворительно, выдается сообщение о неуверенности.

Уникальность:
Редкий механизм самоконтроля, повышающий доверие к боту. Работает как «человек проверяет себя».

Польза:
Снижает вероятность ошибочного ответа, особенно в критических областях (юриспруденция, финансы, медицина, нормативная документация).

Примеры использования:

1. Обычный запрос – самокритика работает в фоновом режиме. Если ответ не проходит проверку, бот перегенерирует его один раз. Если и после перегенерации неудовлетворительно, выдается сообщение:
   «⚠️ Извините, я не уверен в точности ответа. Проверьте данные.»

2. Отключение самокритики – если в конфиге bot.conf установить enable_self_critique: false, она отключается для увеличения скорости (полезно для тестирования или простых запросов).

3. Влияет только на обычные RAG-запросы – для экспертных функций (METRICS, SUMMARY, CONTRADICTION) самокритика не применяется, так как их ответы уже структурированы и проверены на уровне функций.

4. Перегенерация с тем же контекстом – при перегенерации используется тот же контекст, что и при первом ответе, чтобы не потерять релевантность.

8. Извлечение метрик (KPI) из документов

Что делает:
Анализирует базу знаний, находит числовые показатели (OEE, тактовое время, выработку, проценты, суммы, количества) и выдает в структурированном виде (JSON или маркированный список). Использует промпт, который заставляет LLM выделять только явно указанные числа/значения, без додумывания.

Уникальность:
Команда !metrics работает без предварительной разметки данных – LLM сама выделяет показатели. Не требуется специальных тегов или шаблонов.

Польза:
Быстрый анализ эффективности, контроль KPI по всем документам компании. Автоматизация сбора показателей для отчетности.

Примеры использования:

1. Извлечение всех KPI из базы знаний:

   • !metrics
   • Бот ищет все документы (личные + глобальные или комнатные + глобальные) и выдает список метрик:
     - OEE линии: 85,2% (первый квартал 2025)
- Тактовое время на сборке: 120 сек
- Выработка на одного рабочего: 450 деталей в смену
- Время переналадки: 35 мин
- Процент брака: 2,1%

2. Автоматический ответ на намерение METRICS – если пользователь спросит:
   «Выведи все KPI из отчета» или «Покажи показатели эффективности», классификатор распознает намерение и вызовет функцию автоматически.

3. Кэширование – для команды !metrics результат кэшируется на 5 минут, что ускоряет повторные запросы (полезно для частого мониторинга).

4. Ограничение количества – выводится не более 20 метрик, чтобы не перегружать ответ.

5. Указание источника – каждая метрика сопровождается фрагментом источника (первые 100 символов), чтобы можно было проверить оригинал.

9. Проверка противоречий между документами

Что делает:
Находит логические, числовые или терминологические расхождения в разных фрагментах базы знаний. Сравнивает факты, цифры, даты, определения. Возвращает структурированный ответ: [OK] если противоречий нет, или [CONFLICT] с описанием каждого расхождения и предполагаемой причиной.

Уникальность:
Помогает аудиторам и аналитикам обнаруживать конфликты данных. Автоматизирует процесс верификации документации.

Польза:
Исключение ошибок в нормативной базе, устранение дублирующихся требований, повышение качества документооборота.

Примеры использования:

1. Проверка противоречий в OEE:

   • «Есть ли противоречия в расчете OEE?»
   • Бот ищет все фрагменты с упоминанием OEE и сравнивает цифры. Если в одном документе 85%, а в другом 90%, выдает предупреждение:
     [CONFLICT] В фрагменте 1 указано 85%, в фрагменте 2 – 90%. Предполагаемая причина: разные источники или разные периоды.

2. Проверка сроков:

   • «Проверь, нет ли противоречий в сроках реализации проекта»
   • Находит все даты в документах и сравнивает их.

3. Сравнение терминов:

   • «Есть ли противоречия в определении понятия "цикл производства"?»
   • Находит все определения и проверяет их на согласованность.

4. Ограничение фрагментов – для экономии токенов проверяются только первые max_fragments (по умолчанию 5) наиболее релевантных фрагментов.

5. Учет первичного источника – если один источник явно первичен (например, официальный документ), это указывается в ответе.

10. SOMA-анализ (LLM-as-judge)

Что делает:
После генерации ответа другой экземпляр LLM (или тот же, с другим системным промптом) оценивает ответ по пяти критериям:

1. Релевантность – насколько ответ соответствует вопросу.
2. Полнота – охвачены ли все аспекты вопроса.
3. Отсутствие галлюцинаций – факты подтверждены контекстом.
4. Стиль и читаемость – логичность, ясность, отсутствие излишней сложности.
5. Полезность – содержит ли ответ практические рекомендации или чёткие выводы.

Каждый критерий оценивается по шкале от 1 до 5. Если средняя оценка ниже порога (по умолчанию 3.5), ответ перегенерируется (с повышенной температурой для разнообразия) и оценивается повторно. Если и повторная оценка неудовлетворительна, пользователю выводится предупреждение о неуверенности.

Результаты SOMA-оценок кэшируются на 5 минут (TTL настраивается) на основе хеша (query, context, answer), чтобы избежать повторных вызовов GigaChat для идентичных запросов.

Уникальность:
SOMA-анализ обеспечивает автоматический контроль качества без участия человека, что редко встречается в корпоративных RAG-ботах. Кэширование снижает затраты на токены.

Польза:
Повышает доверие к ответам, особенно в критических областях. Позволяет A/B-тестировать промпты и модели, так как SOMA даёт объективную метрику качества.

Примеры использования:

• Все обычные RAG-запросы (GENERAL, FACT, PROCEDURE, COMPARISON, CALCULATION) проходят SOMA-оценку (если включена).
• При низкой оценке бот перегенерирует ответ, что особенно полезно для сложных расчётов и юридических вопросов.
• Результаты SOMA могут использоваться для сбора статистики качества и оптимизации промптов.

11. ReAct (вызов внешних инструментов) – НОВОЕ!

Что делает:
ReAct (Reasoning + Acting) — это итеративный цикл, в котором модель:

1. Генерирует мысль (обдумывает, что нужно сделать).
2. Выбирает действие (вызов внешнего инструмента).
3. Наблюдает результат (получает ответ от API).
4. Повторяет до тех пор, пока не будет готов финальный ответ.

Доступные инструменты (реализованы в ToolHandler):

• Поиск в интернете (DuckDuckGo Instant Answer API) – находит факты, новости, определения.
• Погода (OpenWeatherMap API) – текущая погода в указанном городе (требуется API-ключ).
• Бронирование авиабилетов (заглушка для демонстрации).
• Курс валют (заглушка для демонстрации).

ReAct автоматически активируется, если запрос содержит ключевые слова «найди», «поищи», «забронируй», «погода», «билеты», «курс» и т.д. (настраивается в _needs_external_data).

Уникальность:
Редкая возможность для корпоративных RAG-ботов — выполнять реальные действия через внешние API, а не только генерировать текст. Это превращает бота из пассивного информатора в активного помощника.

Польза:

• Быстрый доступ к актуальной информации из интернета.
• Автоматизация поиска билетов, отелей, погоды.
• Возможность расширения инструментов под любые корпоративные API (1С, SAP, календари).

Примеры использования:

1. Поиск информации:
   • Запрос: «Найди последние новости о квантовых вычислениях»
   • Бот выполняет поиск через DuckDuckGo и возвращает краткую выжимку.
2. Погода:
   • Запрос: «Какая погода в Москве завтра?»
   • Бот вызывает OpenWeatherMap и возвращает прогноз.
3. Бронирование (заглушка):
   • Запрос: «Забронируй билет Москва-Сочи на 15 июля»
   • Бот имитирует бронирование, демонстрируя возможную интеграцию.
4. Комбинированный сценарий:
   • Запрос: «Найди информацию о достопримечательностях Парижа и какая там погода?»
   • Бот сначала ищет достопримечательности, затем погоду, объединяет ответы.

12. Планирование действий

Что делает:
Для сложных запросов (расчёты, многошаговые инструкции) бот сначала генерирует пошаговый план, а затем последовательно выполняет каждый шаг. План содержит описание шага, необходимые данные и ожидаемый результат. Это повышает точность и логичность ответов.

Уникальность:
Планирование добавляет метакогнитивный уровень – модель обдумывает структуру ответа перед его генерацией, что улучшает качество для сложных задач.

Польза:

• Повышает точность расчётов и алгоритмов.
• Улучшает структурированность ответов для инструкций.
• Позволяет пользователю видеть логику решения.

Примеры использования:

1. Расчёт OEE:

   • Запрос: «Рассчитай OEE для линии»
   • Бот генерирует план: 1) найти доступное время, 2) вычислить время простоев, 3) рассчитать производительность и качество, 4) вычислить OEE. Затем выполняет каждый шаг, показывая промежуточные результаты.

2. Инструкция по внедрению 5S:

   • Запрос: «Как внедрить 5S на производстве?»
   • Бот создаёт план из 5 этапов, затем последовательно описывает каждый.

13. Многоагентность

Что делает:
В системе могут одновременно работать несколько специализированных агентов:

• Методолог – экспертиза в стандартах, ГОСТах, методиках.
• Коробочник – генерация коробочных решений, шаблонов.
• Персональный ассистент – командировки, календарь, бронирование.

Координатор (AgentCoordinator) автоматически выбирает подходящего агента на основе ключевых слов запроса. Например, если запрос содержит «методолог», «стандарт», «ГОСТ» — вызывается методолог. Агенты могут обмениваться сообщениями для решения сложных задач.

Уникальность:
Многоагентная архитектура позволяет декомпозировать сложные задачи между специализированными ИИ-ассистентами, что повышает качество и релевантность ответов. Это редкость для корпоративных RAG-ботов.

Польза:

• Каждый агент настроен на свою предметную область, использует соответствующие промпты.
• Пользователь может задавать вопросы разной тематики одному боту, а маршрутизация будет автоматической.
• Возможность расширения новыми агентами без изменения ядра.

Примеры использования:

1. Запрос к методологу:
   • «Найди требования к описанию бизнес-процесса в ГОСТ Р ИСО 9001» → автоматически направляется агенту-методологу.
2. Запрос к коробочнику:
   • «Создай коробочное решение для библиотеки» → направляется агенту-коробочнику.
3. Запрос к ассистенту:
   • «Запланируй командировку в Казань на следующую неделю» → направляется агенту-ассистенту.
4. Совместная работа агентов:
   • Если запрос требует и методологии, и коробочного решения, координатор может организовать диалог между агентами.

14. Реальные инструменты (ToolHandler)

Что делает:
ToolHandler предоставляет реальные обработчики для внешних API:

• search(query) – поиск через DuckDuckGo Instant Answer API (без ключа).
• get_weather(city) – погода через OpenWeatherMap API (требуется weather_api_key).
• book_flight(origin, destination, date) – заглушка для демонстрации.
• get_exchange_rate(from_currency, to_currency) – заглушка для демонстрации.

Все инструменты асинхронны, используют aiohttp, имеют таймауты и обработку ошибок.

Уникальность:
Инструменты интегрированы в ReAct-цикл, что позволяет модели динамически решать, когда и какой инструмент вызывать. Это делает бота активным, а не пассивным.

Польза:

• Реализация реальных действий (поиск, погода) повышает практическую ценность.
• Заглушки для бронирования и курсов демонстрируют возможности интеграции с любыми API.
• Легко добавлять новые инструменты через расширение ToolHandler.

Примеры использования (см. раздел ReAct).

7.4. Интеллектуальная маршрутизация и поиск

15. Классификация намерений

Что делает:
Определяет тип запроса пользователя по ключевым словам и контексту. Поддерживает следующие коды намерений: FACT, PROCEDURE, COMPARISON, CALCULATION, SURGICAL, METRICS, SUMMARY, CONTRADICTION, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL. Выбирает соответствующую стратегию обработки. Результаты классификации кэшируются на 5 минут для ускорения повторных запросов.

Уникальность:
Не все RAG-боты имеют интеллектуальную маршрутизацию. Кэширование дополнительно повышает отзывчивость.

Польза:
Экономия токенов, времени и повышение точности ответов за счет выбора специализированной стратегии.

Примеры работы (как классификатор определяет тип запроса):

Запрос пользователя	Распознанное намерение
«Какое тактовое время установлено на линии?»	FACT
«Как рассчитать OEE?»	PROCEDURE
«Сравни показатели производительности до и после кайдзен»	COMPARISON
«Замени 5000 на 6000 в плане производства»	SURGICAL
«Выведи все KPI из отчета»	METRICS
«Сделай суммаризацию документа»	SUMMARY
«Есть ли противоречия в расчете OEE?»	CONTRADICTION
«Привет»	GREETING
«Заполни шаблон договора»	TEMPLATE_FILL
«Проверь орфографию»	SPELLCHECK
«О чем этот документ?»	GENERAL

16. Цепочка рассуждений (Chain‑of‑Thought)

Что делает:
Для запросов с намерениями CALCULATION (расчет) и PROCEDURE (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом.

Польза:
Повышает точность расчетов и алгоритмов, позволяет пользователю проверить логику и выявить возможные ошибки на промежуточных этапах.

Примеры использования:

1. Расчет OEE:

   • Запрос: «Рассчитай OEE для линии»
   • Ответ:

     Шаг 1: Доступное время = 480 мин
     Шаг 2: Время простоев = 45 мин
     Шаг 3: Операционное время = 435 мин
     Шаг 4: OEE = (435 / 480) × 100% = 90,6%
     Итоговый ответ: OEE составляет 90,6%.

2. Расчет выработки:

   • Запрос: «Какая будет выработка при загрузке 110%?»
   • Ответ с пошаговым расчетом:

     Шаг 1: Номинальная выработка = 100 ед/час
     Шаг 2: При загрузке 110% выработка = 100 × 1,1 = 110 ед/час
     Итог: 110 ед/час.

3. Пошаговая инструкция:

   • Запрос: «Как внедрить 5S?»
   • Бот выдает последовательность шагов с пояснениями.

17. Полнотекстовый поиск по точным фрагментам и поиск инструкций (HOW TO)

Что делает:
При обнаружении номеров пунктов (1.1, 3.2.1), фраз в кавычках или ключевых слов «как», «инструкция», «алгоритм», «порядок», «последовательность», «этапы», «методика», «процедура», «регламент», «правила», «способ», «метод» – бот переключается с гибридного RAG на точный подстроковый поиск в Qdrant (MatchText). Это гарантирует попадание в нужный раздел документа, а не просто семантически похожий фрагмент.

Ключевая особенность:
Если запрос содержит вопрос «как сделать Х», бот не просто находит фрагмент с упоминанием Х, а извлекает всю инструкцию или процедуру, даже если она не оформлена как маркированный список, а просто описана в тексте. Для этого используется дополнительный промпт, который заставляет LLM выделить и структурировать последовательность действий.

Уникальность:

• Гарантирует юридически значимые цитаты и ссылки на пункты нормативных актов.
• Может находить и выдавать пошаговые инструкции из неструктурированного текста.
• Объединяет точный поиск с цепочкой рассуждений (CoT), если инструкция требует расчетов или последовательных действий.

Польза:

• Позволяет получать готовые алгоритмы и процедуры без необходимости читать весь документ.
• Быстрое освоение новых процессов – достаточно спросить «как сделать Х», и бот найдет инструкцию в документах.
• Снижение времени на поиск регламентов и стандартов.

Примеры использования (все возможные сценарии):

1. Поиск инструкции по номеру пункта:

   • Запрос: «Выведи пункт 4.2 из регламента по внедрению 5S»
   • Ответ:

     [Источник: Регламент_внедрения_5S.docx]
     Пункт 4.2. Порядок проведения аудита рабочего места:
     1. Подготовка: сформировать чек-лист на основе стандарта 5S.
     2. Проведение аудита: визуальный осмотр рабочих мест, фиксация нарушений.
     3. Оценка: выставление баллов по каждому критерию...
     

2. Поиск процедуры по ключевому слову «как» + «инструкция»:

   • Запрос: «Как провести хронометраж рабочего времени?»
   • Ответ:

     [Источник: Методика_хронометража.pdf]
     Инструкция по проведению хронометража:
     1. Определить цель...
     2. Выбрать объект наблюдения...
     3. Разработать лист наблюдений...
     4. Провести наблюдение...
     5. Обработать данные...
     6. Сделать выводы...
     

3. Поиск алгоритма по ключевым словам «порядок действий», «этапы»:

   • Запрос: «Опиши порядок действий при внедрении кайдзен-предложения»
   • Ответ с пошаговым алгоритмом.

4. Поиск по цитате с кавычками:

   • Запрос: «"Срок исполнения не более 5 рабочих дней"»
   • Ответ: точная цитата с указанием раздела и документа.

5. Поиск методики по ключевым словам «методика» + «расчет»:

   • Запрос: «Найди методику расчета OEE»
   • Ответ с формулами и пояснениями.

6. Поиск инструкции с уточнением «напиши инструкцию»:

   • Запрос: «Напиши инструкцию по безопасной работе с электроинструментом»
   • Ответ с полным текстом инструкции.

7. Поиск с комбинацией: «как» + «внедрить» + конкретный инструмент:

   • Запрос: «Как внедрить систему 5S на производстве?»
   • Ответ с пошаговым алгоритмом внедрения.

8. Поиск регламента:

   • Запрос: «Какой регламент по проведению инвентаризации?»
   • Ответ с описанием процедуры.

9. Поиск по номеру документа:

   • Запрос: «ГОСТ Р 12345-2023»
   • Находит документ с этим номером в названии или тексте.

10. Комбинированный поиск:

    • Запрос: «Порядок расчета OEE по методике из приложения 2»
    • Находит точный раздел и выдает инструкцию.

18. Расширение запроса (query expansion)

Что делает:
Добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. Использует GigaChat для генерации до 10 дополнительных ключевых слов. Результаты кэшируются на 5 минут.

Уникальность:
Улучшает recall без участия пользователя. Автоматически подбирает термины, которые могут встречаться в документах.

Польза:
Помогает находить документы, даже если пользователь использует нестандартные термины или сокращения.

Примеры расширения:

Исходный запрос	Расширенный запрос (пример)
«OEE»	«OEE общая эффективность оборудования производительность коэффициент использования»
«время переналадки»	«время переналадки длительность смены инструмента SMED время простоя»
«5S»	«5S сортировка соблюдение порядка сияние стандартизация совершенствование рабочее место»
«Кайдзен»	«Кайдзен непрерывное улучшение малые шаги оптимизация процессов бережливое производство»
«выработка на человека»	«выработка на человека производительность труда выработка на одного сотрудника ПТ»
«расчет такта»	«расчет такта тактовое время Takt time формула такта время выпуска единицы»

19. Переранжирование контекста (кросс-энкодер)

Что делает:
После получения фрагментов из Qdrant, специализированная модель (кросс-энкодер) ранжирует их по релевантности запросу, отбрасывая шум. Используется локальная модель intfloat/multilingual-e5-reranker, что исключает затраты на токены и снижает задержку.

Уникальность:
Вместо дорогого вызова LLM используется легкий кросс-энкодер, работающий быстрее и дешевле. При этом качество ранжирования сравнимо с LLM.

Польза:
Уменьшает объем контекста, отправляемого в GigaChat, что экономит токены и улучшает точность ответа (убираются нерелевантные фрагменты).

Пример работы:
Запрос: «Какой OEE на линии А?»
Qdrant вернул 30 фрагментов. Кросс-энкодер отбирает только те, где есть упоминания «OEE» и «линия А», отбрасывая фрагменты про другие линии или общие описания. В результате в GigaChat отправляется только релевантный контекст (обычно 5–10 лучших фрагментов).

7.5. Функции автоматизации и интеграции

20. Автоматическая индексация файлов в комнатах (без !learn)

Что делает:
Любой файл (DOCX, PDF, XLSX, PPTX, изображение, аудио, архив), отправленный в групповой чат, автоматически индексируется в базу знаний комнаты. Не требуется включать режим обучения (!learn). Это работает «из коробки» для всех участников комнаты.

Уникальность:
Удобство для коллективной работы – не надо запоминать команды. Даже у Slack и Teams нет такой функции «из коробки».

Польза:
Быстрый старт для новых участников комнаты – они сразу могут задавать вопросы по документам, которые уже загружены. Автоматическое пополнение базы знаний без лишних действий.

Примеры использования:

1. Пользователь отправляет в групповой чат файл «Регламент_отдела.docx» – бот автоматически индексирует его в комнатную БЗ, и все участники могут задавать по нему вопросы.

2. Новый сотрудник приходит в комнату – он сразу может спрашивать бота о документах, которые уже загружены, без необходимости отдельно загружать их.

3. В комнате с файлами по проекту каждый участник может добавлять новые версии документов, и бот автоматически обновляет индекс (при изменении хеша файла).

4. Если файл является архивом (ZIP, 7z), бот распаковывает его и индексирует все поддерживаемые форматы внутри.

21. Веб-скрапинг с рекурсивным обходом

Что делает:
Бот может загрузить сайт по ссылке, рекурсивно обойти страницы (с ограничением глубины и количества) и проиндексировать их в базу знаний. Поддерживаются HTML-страницы и PDF-документы по ссылкам.

Уникальность:
Превращает произвольные веб-страницы в документы для RAG. Позволяет автоматически собирать информацию из внешних источников.

Польза:
Актуальная информация из внешних источников (изменения законодательства, новости отрасли, техническая документация) – автоматически попадает в базу знаний.

Примеры использования:

1. Индексация одной страницы:

   • В режиме !learn (личный чат) вводите:
     https://example.com/document
   • Бот загружает страницу, извлекает основной текст (с помощью readability-lxml) и индексирует.

2. Рекурсивный обход сайта:

   • https://example.com --recursive --depth 2 --max 10
   • Бот загружает страницу, затем переходит по ссылкам на глубину 2 уровня, обрабатывая не более 10 страниц, и индексирует все.

3. Индексация PDF по ссылке:

   • https://example.com/report.pdf
   • Бот скачивает PDF, извлекает текст и индексирует.

4. Задание заголовка:

   • https://example.com --title "Новый ГОСТ"
   • Документ сохраняется в БЗ с указанным заголовком.

5. Ограничения – глубина по умолчанию 1, максимум страниц 5 (настраивается в конфиге). Это предотвращает перегрузку системы.

22. Поддержка голосовых сообщений (распознавание через SaluteSpeech)

Что делает:
Аудиофайлы (.ogg, .wav, .mp3, .amr, .m4a) транскрибируются в текст через SaluteSpeech API. Полученный текст затем обрабатывается как обычный запрос (классификация, поиск, генерация ответа). Ответ отправляется текстом в чат.

Уникальность:
Редкость для RAG-ботов, удобно для мобильных клиентов. Не требует установки дополнительных приложений – работает с любым аудиофайлом.

Польза:
Можно «продиктовать» вопрос, не набирая текст. Удобно в дороге, в производственных условиях (где руки заняты) или для людей с ограниченными возможностями.

Примеры использования:

1. Пользователь отправляет голосовое сообщение в личный чат боту (или в комнату). Бот распознает речь, превращает в текст, и если это вопрос – обрабатывает через RAG, отправляя ответ текстом (или голосом, если настроено дополнительно).

2. В мобильном клиенте (например, Conversations) пользователь нажимает кнопку записи голоса, говорит вопрос, бот отвечает в чат текстом.

3. Голосовое сообщение может содержать не только вопрос, но и команду (например, «!summary») – бот распознает и выполняет.

4. Поддерживаются длинные сообщения – транскрипция работает с учетом лимитов API.

23. Административные команды (!stats, !status, !clean)

Что делает:

• !stats – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ.
• !status – проверяет доступность внешних сервисов: PostgreSQL, Qdrant, GigaChat, а также состояние дискового пространства.
• !clean – очищает временную директорию (удаляет все временные файлы).

Уникальность:
Полный контроль без доступа к серверу. Все команды доступны из любого XMPP-клиента.

Польза:
Оперативное администрирование, мониторинг состояния системы, освобождение места на диске.

Примеры использования:

1. Проверка состояния сервисов:

   • !status
   • Бот проверяет подключение к PostgreSQL, Qdrant, GigaChat и выводит результат:
     ✅ PostgreSQL Online
✅ Qdrant Online
✅ GigaChat Online
💾 Диск: 512MB / 10GB (свободно 9.5GB)

2. Статистика работы бота:

   • !stats
   • Выводит:
     ⏱ Uptime: 2 дня 5 часов
💬 Сообщений: 1 234
🤖 AI запросов: 567
📁 Файлов обработано: 89
❌ Ошибок: 12
📚 Документов в БЗ: 45

3. Очистка временных файлов:

   • !clean
   • Удаляет все файлы из временной директории (temp/), освобождая место на диске. Выводит количество удаленных объектов.

4. Только для администраторов – команды !stats, !status, !clean доступны только пользователям, перечисленным в admin_jids в конфиге.

7.6. Дополнительные возможности

Режим обучения (!learn и !stop_learn)

• !learn – включает режим обучения. Следующий файл или ссылка, отправленные в чат, будут добавлены в базу знаний (личную, комнатную или глобальную, в зависимости от контекста и флагов).
• !learn --global – (только в личном чате, для админов) – следующий файл/ссылка станут глобальными.
• !stop_learn – выключает режим обучения.

Пример:
!learn → затем отправляете файл → он индексируется.
!stop_learn – режим выключен.

Работа с историей диалога

Бот автоматически сохраняет историю диалогов (личную и комнатную) в PostgreSQL. История используется для контекста при ответах. Команда !reset сбрасывает историю (личную или комнатную). Для длинных диалогов применяется иерархическое резюмирование, чтобы сжать историю и не превысить лимит токенов.

Поддержка вложенных файлов и архивов

Бот умеет распаковывать ZIP и 7z-архивы и индексировать все файлы внутри (DOCX, PDF, XLSX и т.д.). Это позволяет загружать целые пакеты документов одной ссылкой.

Многоязычность

Промпты настроены так, что бот может отвечать на любом языке, на котором задан вопрос, если в документах есть информация на этом языке. В системном промпте явно указано: «Ты можешь использовать информацию из документов на ЛЮБОМ языке (русском, английском, немецком и т.д.)». При необходимости бот переводит нужную часть на язык вопроса.

Работа с изображениями (Vision)

Если загружено изображение (JPEG, PNG, BMP, TIFF) и в конфиге включена опция vision: true, бот отправляет изображение на RAG-сервер (эндпоинт /rag/vision) для распознавания текста (OCR). Распознанный текст отправляется в чат.

Работа с таблицами в DOCX

При извлечении текста из DOCX бот обрабатывает таблицы, сохраняя их структуру. Это позволяет отвечать на вопросы, требующие табличных данных.

7.7. Сценарий полного цикла создания коробочного решения

Этап 1: Подготовка источников

1. Администратор загружает глобальные документы (ГОСТы, методики):

   !learn --global → отправляет ГОСТ Р 12345-2023.pdf
   

2. Команда проекта загружает в комнату отраслевые документы:

   • «Регламент работы библиотек.docx»
   • «Отчет о кадровом составе.xlsx»
   • «Методика оценки компетенций.pdf»
   • «План внедрения 5S.docx»

3. Бот автоматически индексирует все файлы в комнатную БЗ.

4. Пользователь делает !summary по каждому документу, чтобы быстро понять содержание.

Этап 2: Сохранение шаблона

5. Пользователь загружает Шаблон коробочного решения.docx и сохраняет как шаблон:

   !template_save "Коробочное решение_Библиотеки"
   

Этап 3: Генерация коробочного решения

6. Пользователь вводит:

   !create "Коробочное решение_Библиотеки"
   

7. Бот:

   • Находит все плейсхолдеры в шаблоне.
   • Для каждого плейсхолдера выполняет гибридный поиск в БЗ комнаты.
   • Использует расширение запроса и переранжирование.
   • Генерирует значение через GigaChat (с самокритикой).
   • Заменяет плейсхолдеры в копии шаблона.
   • Отправляет готовый DOCX-файл в чат.

Этап 4: Проверка и доработка

8. Пользователь открывает готовый DOCX, проверяет содержание.

9. При необходимости делает хирургическую замену:

   Замени ООО "Ромашка" на ООО "Тюльпан"
   

10. Проверяет орфографию:

    Проверь орфографию
    

11. Получает исправленный файл и отправляет руководству или клиенту.

Этап 5: Обновление и масштабирование

12. Если в базу знаний добавляются новые документы, можно перегенерировать коробочное решение:

    !create "Коробочное решение_Библиотеки"
    

    Бот использует обновленную БЗ и создает актуальную версию.

13. Для другого типа организаций (музеи) создается аналогичный шаблон:

    !template_save "Коробочное решение_Музеи"
    !create "Коробочное решение_Музеи"
    

---

II. Перспективы развития Эфцекабот

1. Типология ботов: от общефункциональных до персонального ассистента

Платформа Эфцекабот построена на едином RAG-ядре (HTTP-сервере), которое обслуживает любое количество клиентов – XMPP-ботов, Telegram-ботов, Mastodon-ботов, веб-интерфейсы, системы аналитики. Это означает, что одна и та же база знаний, история диалогов и логика обработки запросов доступны через любой интерфейс. Пользователь может начать диалог в XMPP, продолжить в Telegram, и контекст сохранится – все благодаря централизованному хранению истории на RAG-сервере.

1.1. Общие боты

Тип бота	Отдел	Примеры запросов
Методолог (стандарты)	Методология, бизнес-аналитика, внутренний контроль	«Найди требования к описанию бизнес-процесса»
Писатель коробочных решений	Методология	«Напиши коробочное решение по образцу»
Юрист-эксперт	Юридический	«Составь претензию по шаблону»
Финансовый аналитик	Финансы, управленческий учет	«Рассчитай OEE по проекту X»
HR-помощник	Отдел персонала	«Образец служебной записки или бизнес-процесса»
Менеджер проектов	Проектный офис	«Сформируй выжимку по проекту за месяц»
ИТ-архитектор	IT-департамент	«Сравни конфигурации серверов из ТЗ»
Комплаенс-контроль	Служба безопасности	«Проверь отчет на соответствие регламенту»
Executive-бот	Топ-менеджмент	«Сводка KPI по всем проектам»

Каждый из этих ботов может быть реализован как отдельный XMPP-клиент (или другой клиент), подключающийся к общему RAG-ядру. Благодаря единому ядру, все боты используют одни и те же документы и историю, но могут иметь свои промпты, что позволяет настраивать стиль и глубину ответов под конкретную задачу.

1.2. Персональный ассистент

Уникальная особенность: один и тот же бот, но с персональными настройками (история командировок, бюджетные лимиты, предпочтения по отелям, закрепленные проекты). Сотрудник общается с ботом как с личным секретарем.

В новой архитектуре персональные настройки хранятся в общей БД и доступны всем клиентам. Пользователь может начать диалог в XMPP, а продолжить в Telegram – история и контекст сохраняются.

Ключевые сценарии персонального ассистента:

Сценарий	Пример запроса	Автоматизация
Планирование командировки	«Запланируй командировку в Нижний Новгород на 10–12 мая»	Бот через агента-тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует
Поиск и бронирование билетов	«Найди ближайший рейс до Екатеринбурга на завтра утро»	Интеграция с корпоративным тревел-агентом (API), выдача вариантов, бронирование по команде
Бронирование гостиницы	«Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь»	Агент-отельер возвращает список, пользователь выбирает – бронь автоматически
Оформление командировочного удостоверения	«Сформируй командировочное удостоверение по поездке №45»	Бот заполняет шаблон данными из бронирования, высылает PDF
Авансовый отчет по командировке	«Сделай авансовый отчет за поездку в Уфу»	Бот предзаполняет даты, маршрут, суммы билетов и отеля; сотрудник добавляет фото чеков → OCR распознает и вносит суммы
Согласование отчета	«Отправь отчет руководителю на подпись»	Бот пересылает отчет в личный чат руководителя, тот ставит «OK» кнопкой
Календарь командировок	«Добавь поездку в мой календарь на 15–17 мая»	Синхронизация с корпоративным календарем (Exchange/Google)
Статус командировок	«Какие у меня утвержденные командировки на следующую неделю?»	Бот извлекает из базы данных (или внешней системы) и отвечает

2. Как бот «вызывает» агентов – архитектура оркестрации

Эфцекабот выступает универсальным диспетчером. В текущей архитектуре сами боты-клиенты не вызывают агентов напрямую. Вместо этого:

1. Клиент (XMPP-бот, Telegram-бот и т.д.) отправляет запрос пользователя в RAG-сервер через HTTP.
2. RAG-сервер выполняет классификацию намерений (intent_classify.py).
3. Если запрос требует внешнего действия (бронирование, расчет, генерация отчета, OCR), RAG-сервер возвращает структурированную команду (например, в формате [SURGICAL_REPLACE], [REWRITE], или через теги для вызова агента).
4. Клиент (или отдельный агент-оркестратор) выполняет эту команду через API внешних систем и возвращает результат в RAG-сервер для финальной обработки.

Запрос пользователя	Намерение (intent)	Вызываемый агент	Действие агента	Результат
«Найди билеты Москва-Питер на 15 мая»	BOOKING	Агент-тревел	Запрос к API билетной системы	Список рейсов с ценами
«Подбери гостиницу рядом с вокзалом»	BOOKING	Агент-отельер	Поиск по API Booking.com / Ostrovok	Варианты отелей, кнопка бронирования
«Сделай авансовый отчет по командировке #123»	REPORT	Агент-генератор DOCX	Заполняет шаблон из данных бронирования и чеков	Готовый отчет в чат
«Проверь этот чек»	OCR	Агент-распознаватель (OCR)	Извлекает сумму, дату, назначение	Структурированные данные, которые бот вставляет в отчет

Вывод: RAG-сервер – это «мозг», а агенты – «руки». Без RAG-сервера агенты разрозненны; с ним они работают как единая система, управляемая естественным языком через единый HTTP API.

3. Экономический эффект (исходные данные для штата 300 человек)

3.1. Экономия на поиске информации (RAG-функции)

• Время, затрачиваемое на поиск информации в документах в день на сотрудника (среднее) – 1 час.
• Доля запросов, полностью автоматизируемых ботом (типовые вопросы по регламентам, KPI, стандартам) – 30%.
• Доля запросов, где бот ускоряет поиск в 2 раза – 50%.
• Остальные 20% – сложные, где экономия меньше, но мы не учитываем их консервативно.

Экономия в часах:

• Полная автоматизация: 300 × 247 (раб. дней) × 1 × 0,3 = 22 230 часов.
• Ускорение поиска: 300 × 247 × 0,5 × 0,5 = 18 525 часов (поскольку ускорение в 2 раза = 50% экономии).

3.2. Экономия на командировочных процессах (персональный ассистент)

Допущения:

• Количество командировок в год: 200 чел. × 44 недели = 8 800 командировок.
• Без автоматизации затраты времени на одну командировку (поиск билетов, бронирование отеля, оформление заявки, составление авансового отчета, согласование) – 2 часа (суммарно).
• С ботом (интеграция с тревел-агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – 0,4 часа (24 минуты). Экономия = 1,6 часа на командировку.

Экономия в часах: 8 800 × 1,6 = 14 080 часов.

3.3. Экономия на снижении ошибок и автоматической проверке документов

• Бот автоматически проверяет отчеты, договоры, счета на соответствие регламентам (CONTRADICTION, TEMPLATE_FILL). Предотвращает переделки и штрафы.
• Допустим, среднее время на переделку, исправление отчета, повторное согласование – 2 часа.
• В компании с 300 сотрудниками происходит минимум 1000 документооборотных ошибок в год (отчеты, договоры, заявки). Бот выявляет и исправляет 80% из них.

Экономия в часах: 800 ошибок × 2 часа = 1 600 часов (консервативно).

3.4. Итоговая годовая экономия

Статья	Часы
Поиск информации (RAG)	40 755
Командировки (бронирование + отчетность)	14 080
Снижение ошибок в документообороте	1 600
Итого прямая экономия времени	56 435

Не учтены косвенные эффекты: ускорение согласования, повышение мотивации, снижение текучки.

3.5. Затраты на внедрение и обслуживание

Статья	Стоимость
Развертывание инфраструктуры (серверы, настройка)	1 млн руб. (разово)
Разработка интеграций (агенты, тревел-API, 1С, календарь)	2 млн руб. (разово, можно тиражировать)
Обслуживание, обновление БЗ, поддержка	1 млн руб./год
Итого первый год	4 млн руб.
Итого последующие годы	1 млн руб./год

4. Перспективы развития (12–24 месяца)

4.1. Уже реализованные улучшения (доступны сейчас)

В текущей версии платформы уже реализованы следующие ключевые возможности (дополнены):

• Цепочка рассуждений (Chain-of-Thought) – для расчетов и инструкций модель показывает пошаговое решение.
• Кэширование классификации и расширения запроса – результаты кэшируются на 5 минут, что ускоряет повторные запросы.
• Переранжирование через локальный кросс-энкодер – вместо дорогого вызова LLM используется легкая модель intfloat/multilingual-e5-reranker.
• Обрезка истории диалога по токенам – точный подсчет через tiktoken, эффективное использование контекстного окна. Добавлена пагинация и обрезка сообщений до лимита.
• Единое RAG-ядро с HTTP API – все клиенты (XMPP, Telegram, веб) подключаются к одному серверу.
• Генерация коробочных решений по шаблону – команды !create, !template_save, !template_list, !template_delete.
• Автоматическая индексация файлов в комнатах – файлы индексируются без команды !learn.
• Полнотекстовый поиск по точным фрагментам – поиск по номерам пунктов, кавычкам и инструкциям.
• Рефакторинг оркестратора – RAGOrchestrator разбит на менеджеры (HistoryManager, IntentRouter, QueryProcessor, IndexingManager), что повышает тестируемость и сопровождаемость.
• Конфигурация на Pydantic – вместо ручной загрузки используется AppConfig с валидацией и автодополнением.
• Аутентификация через API-ключ – все эндпоинты RAG-сервера защищены заголовком X-API-Key (кроме /health).
• Автоматическая документация OpenAPI – доступны Swagger UI (/docs) и ReDoc (/redoc), а также сырая спецификация (/openapi.json).
• Генерация API-ключа – в .env добавлена переменная RAG_API_KEY.
• Динамические few-shot примеры – подбор релевантных примеров на основе запроса и построение промта по структуре «сэндвич».
• SOMA-анализ (LLM-as-judge) – автоматическая оценка качества ответов с перегенерацией при низких оценках. Результаты кэшируются (TTL 5 мин).
• ReAct (вызов внешних инструментов) – модель может итеративно вызывать внешние API (поиск, погода, бронирование, курс). Реализованы реальные обработчики.
• Планирование действий – генерация пошагового плана для сложных запросов (расчёты, инструкции).
• Многоагентная архитектура – координатор и специализированные агенты (методолог, коробочник, персональный ассистент).
• Фоновый ReindexWorker – автоматическая переиндексация документов с indexed=False (восстановление после сбоев).
• Улучшения безопасности – экранирование путей (shlex.quote), санитизация пользовательского ввода (ChatML), ограничение CORS, rate limiting (slowapi), retry + circuit breaker для GigaChat.
• Кэширование эмбеддингов в Redis – снижение нагрузки на GigaChat, экономия токенов.
• Пагинация и обрезка истории диалога – защита от переполнения БД, ускорение запросов.
• Хранение исходного текста документов в PostgreSQL (колонка file_text) – позволяет переиндексировать документы без потери данных.
• Миграции через Alembic – управление схемой БД через версионные миграции.
• Интеграционные тесты – покрытие новых эндпоинтов и команд.
• Структурированное JSON-логирование – для централизованного сбора логов (ELK/Loki).

4.2. Планируемые улучшения

• Интеграция с системами документооборота (СЭД) – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы.
• Прогнозная аналитика командировок – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования.
• Агент-индексатор сетевых папок (SMB) – бот сам сканирует общие каталоги и обновляет базу знаний.
• Кэширование результатов генерации – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (Redis) на уровне RAG-сервера.
• Сбор обратной связи – команда !feedback для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД.
• A/B-тестирование промптов – возможность разделять пользователей на группы и применять разные версии промптов.
• Гибкие промты – автоматический выбор краткой или расширенной версии промпта в зависимости от длины доступного контекстного окна.
• Команда !style – изменение стиля ответов (кратко/подробно/по умолчанию).
• Подключение дополнительных клиентов – Telegram, МАХ, без изменения ядра.

---

III. Описание модулей

Платформа Эфцекабот построена по принципу «тонкий клиент – толстый сервер». Вся RAG-логика вынесена в отдельный HTTP-сервис – RAG-сервер, который обслуживает все клиенты. Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики.

Все модули, описанные ниже, расположены в каталоге rag/. Часть из них работает на RAG-сервере, часть – в клиентах, часть является общими утилитами.

1. Модуль rag_orchestrator.py – оркестратор RAG-пайплайна

Назначение: это сердце платформы. Модуль координирует все этапы обработки запроса через менеджеры:

• HistoryManager – получение и сжатие истории.
• IntentRouter – обработка специализированных намерений.
• QueryProcessor – обычный RAG-пайплайн (поиск, генерация, критика).
• IndexingManager – индексация документов с предварительным сжатием.

Добавлены новые параметры: tool_handler для передачи реальных обработчиков инструментов в QueryProcessor.

Ключевые методы:

• process_query() – основной метод, выполняет полный цикл обработки запроса.
• index_document() – индексация документа (вызывается из /rag/index). Перед индексацией применяет иерархическое резюмирование, если документ слишком большой.

Особенности:

• Не содержит состояния, использует переданные сервисы и промпты.
• Поддерживает специализированные намерения: METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SPELLCHECK, SURGICAL, GREETING.
• Добавляет цепочку рассуждений (Chain-of-Thought) для CALCULATION и PROCEDURE.
• Включает интеграцию SOMA, ReAct, планирования и агентов через QueryProcessor.

2. Модуль rag_server.py – HTTP-сервер (FastAPI)

Назначение: предоставляет REST API для всех клиентов. Является точкой входа в платформу.

Эндпоинты (добавлены новые):

Метод	Эндпоинт	Назначение	Требует аутентификации
POST	/rag/query	Выполнить RAG-запрос (история берется из БД)	Да
POST	/rag/index	Проиндексировать документ	Да
POST	/rag/vision	Распознать текст на изображении (OCR)	Да
POST	/rag/transcribe	Транскрибировать аудио (SaluteSpeech)	Да
POST	/rag/clear	Очистка БЗ (личной/комнатной/глобальной)	Да
POST	/rag/list	Список документов	Да
POST	/rag/delete_global	Удаление глобального документа	Да (админ)
POST	/rag/template/save	Сохранить шаблон	Да
POST	/rag/template/list	Список шаблонов комнаты	Да
POST	/rag/template/delete	Удалить шаблон	Да
POST	/rag/reset_history	Сброс истории диалога	Да
POST	/rag/room/add	Добавить комнату	Да
GET	/rag/room/list	Список комнат	Да
POST	/rag/stats	Статистика	Да (админ)
POST	/rag/generate_document	Генерация документа по шаблону	Да
GET	/health	Проверка состояния сервера	Нет
GET	/metrics	Метрики Prometheus	Нет
GET	/docs	Swagger UI	Нет
GET	/redoc	ReDoc	Нет
GET	/openapi.json	OpenAPI-спецификация	Нет

Место в архитектуре: запускается как отдельный процесс (с помощью Uvicorn). Обслуживает все клиенты. Инициализирует все сервисы (БД, Qdrant, GigaChat) и создает экземпляр RAGOrchestrator.

Особенности:

• Использует Pydantic для валидации запросов и ответов.
• Поддерживает CORS для возможности запросов с других доменов.
• Имеет встроенный healthcheck для мониторинга.
• Эндпоинты /rag/vision и /rag/transcribe используют FileService для обработки медиафайлов.
• Аутентификация через API-ключ (X-API-Key).
• Полная OpenAPI-документация с примерами и кодами ошибок.
• Graceful shutdown (сигналы SIGTERM/SIGINT) с остановкой ReindexWorker и закрытием ToolHandler.
• Расширенный /health с проверкой PostgreSQL и Qdrant.
• Ограничение CORS через переменную окружения.
• Метрики Prometheus (/metrics).
• Структурированное JSON-логирование.
• Гарантированное удаление временных файлов (tempfile.TemporaryDirectory).
• Интеграция ReindexWorker, SOMA, ReAct, планирования, агентов, ToolHandler.

3. Модуль rag_client.py – HTTP-клиент для ботов

Назначение: используется тонкими клиентами для отправки запросов к RAG-серверу.

Методы:

• query() – отправляет запрос на /rag/query.
• index_document() – отправляет запрос на /rag/index.
• vision(file_path) – отправляет изображение на /rag/vision.
• transcribe(file_path) – отправляет аудио на /rag/transcribe.
• health_check() – проверяет доступность сервера.
• clear() – очистка БЗ.
• list_documents() – список документов.
• delete_global() – удаление глобального документа.
• template_save(), template_list(), template_delete() – управление шаблонами.
• reset_history() – сброс истории.
• add_room(), get_rooms() – управление комнатами.
• get_stats() – статистика.
• generate_document() – генерация документа по шаблону.

Особенности:

• Асинхронный (aiohttp).
• Поддерживает повторные попытки (retry) при сетевых ошибках.
• Автоматически добавляет заголовок X-API-Key.
• Не содержит бизнес-логики – только HTTP-вызовы.

4. Модуль rag_api.py – локальный API-интерфейс

Назначение: прослойка (facade) между ботами и RAGOrchestrator для локального использования (без HTTP). Этот модуль опционален – в новой архитектуре предпочтительнее использовать RAGClient.

Место в архитектуре: может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент.

5. Модуль prompt_builder.py – построитель промтов

Назначение: динамически подбирает релевантные few-shot примеры из файла data/fewshot_examples.json (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов.

Формат файла fewshot_examples.json:

[
  {
    "keywords": ["OEE", "эффективность"],
    "intents": ["PROCEDURE", "CALCULATION"],
    "question": "Как рассчитать OEE?",
    "answer": "OEE = Доступность × Производительность × Качество."
  }
]

• keywords – список ключевых слов для поиска релевантности.
• intents – список намерений, для которых применим пример.
• question – вопрос пользователя.
• answer – эталонный ответ.

Место в архитектуре: используется в QueryProcessor при синтезе ответа.

Добавлена санитизация пользовательских данных (_sanitize) для защиты от инъекций ChatML.

6. Модули функций (каталог functions/)

Все функции являются чистыми, без состояния. Добавлены новые:

• soma_evaluate.py – SOMA-анализ (LLM-as-judge) с кэшированием.
• react.py – цикл ReAct с улучшенным fallback-парсингом JSON.
• plan_generation.py – генерация плана действий.
• tools.py – реальные обработчики инструментов (поиск, погода, бронирование, курс).

Обновлены:

• rerank_context.py – использует асинхронную загрузку модели.
• critique_answer.py – самокритика по 5 критериям (без изменений).

6.1. intent_classify.py – классификация намерений

Назначение: определяет тип запроса пользователя (FACT, PROCEDURE, METRICS, SUMMARY, CONTRADICTION, SURGICAL, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL) по тексту запроса. Примеры в промпте перемешаны для уменьшения эффекта якорения.

Место в архитектуре: вызывается из RAGOrchestrator перед поиском.

Как работает: отправляет промпт (intent_classify.txt) в GigaChat, получает один из кодов, кэширует результат на 5 минут.

Вход: текст запроса, промпт, конфиг.
Выход: код намерения (str) или "GENERAL".

6.2. expand_query.py – расширение запроса

Назначение: добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска.

Место в архитектуре: вызывается перед поиском в Qdrant.

Как работает: отправляет промпт (expand.txt) в GigaChat, получает до 10 дополнительных ключевых слов, кэширует на 5 минут.

Вход: текст запроса, промпт, конфиг.
Выход: расширенный запрос (строка) или исходный, если расширение не удалось.

6.3. extract_metrics.py – извлечение метрик

Назначение: извлекает числовые показатели (KPI, OEE, такт, выработку, проценты) из текста в структурированном виде (JSON).

Место в архитектуре: вызывается при намерении METRICS.

Как работает: отправляет промпт (metrics_extract.txt) в GigaChat, парсит JSON-ответ. При неудаче – fallback-парсинг строк вида ключ: значение.

Вход: контекст (текст), промпт, конфиг.
Выход: список словарей с полями metric_name, value, unit, period, source_fragment.

6.4. summarize_document.py – суммаризация документа

Назначение: создает краткий пересказ документа (≤30% от оригинала) с выделением целей, выводов и ключевых цифр.

Место в архитектуре: вызывается при намерении SUMMARY.

Как работает: отправляет промпт (smart_summary.txt) в GigaChat, подставляя текст документа.

Вход: текст, название, промпт, конфиг.
Выход: строка с кратким изложением.

6.5. hierarchical_summarize.py – иерархическое резюмирование

Назначение: сжимает очень большие тексты (документы, историю диалога) с помощью рекурсивного резюмирования блоков. Разбивает текст на блоки по предложениям, резюмирует каждый блок через GigaChat, объединяет результаты, и при необходимости повторяет процесс рекурсивно до достижения целевой длины.

Место в архитектуре: вызывается из RAGOrchestrator:

• В process_query – для сжатия длинной истории диалога.
• В index_document – для сжатия больших документов перед индексацией (через метод _compress_document_if_needed).

Как работает: использует промпт (hierarchical_summary.txt) для каждого блока.

Вход: текст, целевой размер в токенах, размер блока, глубина.
Выход: сжатый текст.

6.6. check_consistency.py – проверка противоречий

Назначение: находит логические, числовые или терминологические расхождения в разных фрагментах текста.

Место в архитектуре: вызывается при намерении CONTRADICTION.

Как работает: отправляет промпт (consistency_check.txt) в GigaChat, получает ответ [OK] или [CONFLICT] с описанием.

Вход: список фрагментов, запрос, промпт, конфиг.
Выход: строка с результатом проверки.

6.7. critique_answer.py – самокритика ответа

Назначение: оценивает качество сгенерированного ответа по пяти критериям (соответствие источнику, отсутствие галлюцинаций, стиль, логика, запрет внешних знаний).

Место в архитектуре: вызывается после генерации ответа (если включена в конфиге).

Как работает: отправляет промпт (self_critique.txt) в GigaChat, анализирует ответ на наличие [OK] или [ISSUES].

Вход: запрос, контекст, ответ, промпт, конфиг.
Выход: True (ответ хороший) или False (есть замечания).

6.8. rerank_context.py – переранжирование контекста

Назначение: отбирает только релевантные фрагменты из результатов поиска, отбрасывая шум. Использует локальный кросс-энкодер вместо LLM.

Место в архитектуре: вызывается после поиска в Qdrant (если контекст длиннее min_length).

Как работает: отправляет фрагменты в кросс-энкодер (intfloat/multilingual-e5-reranker), ранжирует и возвращает только топ-N фрагментов.

Вход: запрос, контекст, конфиг.
Выход: отфильтрованный контекст (строка).

6.9. file_processor.py – обработка файлов

Назначение: отправка файлов пользователю через HTTP Upload (XEP-0363) и обработка тегов [SURGICAL_REPLACE], [REWRITE], [FILE] из ответа AI.

Место в архитектуре: вызывается из клиентов (XMPP-ботов) и из RAG-пайплайна при наличии тегов.

Как работает: парсит ответ AI, извлекает теги, вызывает методы FileService для замены или создания DOCX-файлов, отправляет результат через HTTP Upload.

Вход: ответ AI, JID пользователя, путь к файлу.
Выход: отправленный файл или сообщение об ошибке.

6.10. generate_document.py – генерация по шаблону

Назначение: заполняет плейсхолдеры {{название}} в шаблоне документа на основе данных из базы знаний.

Место в архитектуре: вызывается из команды !create (через RAG-сервер).

Как работает: находит все плейсхолдеры, для каждого выполняет поиск в БЗ, генерирует значение через GigaChat, заменяет в копии шаблона.

Вход: шаблон (DOCX), запрос пользователя, конфиг.
Выход: готовый DOCX-файл.

7. Сервисы (каталог services/)

Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами.

Файл	Назначение
postgres_service.py	Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. Добавлена колонка file_text, проверка таблиц (Alembic), составные индексы для полнотекстового поиска, пагинация в get_history.
qdrant_service.py	Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по doc_id. Сохранение file_text при индексации, метод reindex_failed_documents().
embedding_service.py	Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (lru_cache), обрезка текста до 800 символов. Внедрён Redis для кэширования эмбеддингов (с fallback на локальный кэш).
kb_service.py	База знаний. Индексация документов (разбиение на чанки, получение эмбеддингов, сохранение в Qdrant и PostgreSQL), поиск, управление доступом. Транзакционная индексация с флагом indexed.
file_service.py	Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы). Хирургическая замена, создание DOCX. Используется на RAG-сервере для OCR и транскрибации.
giga_client.py	Клиент GigaChat. Методы chat() и upload_file() – без бизнес-логики. Добавлены retry (tenacity) и circuit breaker (pybreaker).
reranker_service.py	Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели. Асинхронная загрузка модели с использованием asyncio.Lock и asyncio.Event.
file_service.py	Экранирование путей (shlex.quote) в transcribe_audio.
web_utils.py	Ограничение размера загружаемого контента в fetch_any_url.

8. Обработчики, команды, воркеры (для XMPP-клиентов)

Эти модули работают только на стороне тонких клиентов (XMPP-ботов) и не входят в RAG-сервер.

Команды переписаны на использование RAGClient, удалены обращения к kb, db, qdrant.

• room_handler.py – сохранение комнат на сервере через rag_client.add_room(), загрузка комнат при старте.
• file_handler.py – гарантированное удаление временных файлов (tempfile.TemporaryDirectory).
• client.py – загрузка комнат с сервера, периодическая очистка словарей _last_file_path и last_file_texts.
• reindex_worker.py (новый) – фоновый воркер для переиндексации документов с indexed=False.

8.1. Обработчики (handlers/)

Файл	Назначение
metrics_handler.py	Счетчики (сообщения, файлы, AI-запросы, ошибки).
message_handler.py	Маршрутизация входящих сообщений (использует RAGClient).
file_handler.py	Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь все через RAGClient.
room_handler.py	MUC комнаты (приглашения, вход, переподключение).
subscription_handler.py	Подписки (roster subscription).
health_handler.py	Очистка файлов, healthcheck БД/Qdrant (для клиентов).

8.2. Команды (commands/)

Файл	Назначение
base.py	Базовый класс Command.
registry.py	Регистрация команд, алиасы, подсказки.
info.py	!info – краткая справка.
help.py	!help – подробная справка.
learn.py	!learn, !stop_learn, !global_learn.
kb.py	!clear, !global_clear, !kb.
stats.py	!stats, !status, !clean (админ).
expert.py	!summary, !metrics.
other.py	!reset.
template.py	!template_save, !template_list, !template_delete.
create.py	!create – генерация документа по шаблону.
global_remove.py	!global_remove – удаление глобального документа (админ).

8.3. Воркеры (workers/)

Файл	Назначение
indexing_worker.py	Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через RAGClient. Обработка изображений и аудио теперь через RAG-сервер.

9. Утилиты (каталог utils/)

Вспомогательные функции, используемые как сервером, так и клиентами:

Файл	Назначение
config_loader.py	Загрузка rag.conf и bot.conf, слияние, чтение .env, создание AppConfig с помощью Pydantic.
logger.py	Настройка логирования (уровни, вывод в файл и консоль).
layout_converter.py	Конвертер раскладки клавиатуры (русская ↔ английская).
text_utils.py	Разбиение текста на чанки (tiktoken + razdel), подсчет токенов (count_tokens).
web_utils.py	Веб-скрапинг (fetch_any_url, crawl_url).
arg_parser.py	Парсинг аргументов команд (--flag value).

• logger.py – добавлена поддержка JSON-логирования (параметр json_format).
• web_utils.py – ограничение размера загружаемого контента.

10. Тесты (каталог tests/)

Покрывают критически важные функции:

• test_intent_classify.py – классификация намерений.
• test_expand_query.py – расширение запроса.
• test_extract_metrics.py – извлечение метрик.
• test_summarize.py – суммаризация.
• test_consistency.py – проверка противоречий.
• test_critique.py – самокритика.
• test_check_spelling.py – проверка орфографии.
• test_hierarchical_summarize.py – иерархическое резюмирование.

Тесты используют pytest и pytest-asyncio, не требуют реального подключения к внешним сервисам (используются моки). Запуск: pytest tests/ -v.

• Unit-тесты – без изменений.
• Интеграционные тесты – добавлены test_endpoints.py и test_commands.py для проверки новых эндпоинтов и команд.

11. Конфигурационные файлы

Платформа использует два основных конфигурационных файла:

• rag.conf – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция summarization.
• bot.conf – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты).

Переменные окружения (пароли, ключи API) хранятся в .env. Примеры конфигурации предоставлены в файлах rag.conf.example, bot.conf.sample, env.example.

12. Схема базы данных (PostgreSQL)

Схема управляется через Alembic. Таблицы:

• documents – добавлена колонка file_text TEXT для хранения исходного текста документа.
• document_access – права доступа.
• history – история диалогов.
• rooms – список MUC-комнат.
• room_templates – шаблоны.

Индексы: добавлены составные индексы (room_jid, source_name) и (owner_jid, source_name) для ускорения полнотекстового поиска.

---

IV. Руководство по настройке аутентификации и доступу к API

IV. Руководство по настройке аутентификации и доступу к API

1. Генерация API-ключа

Для защиты RAG-сервера используется API-ключ в заголовке X-API-Key. Сгенерировать ключ:

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

2. Прописать ключ в переменные окружения

В .env добавьте:

RAG_API_KEY=ваш_ключ

3. Использование в Swagger UI

Откройте http://localhost:8080/docs, нажмите Authorize, введите ключ.

4. Использование в боте

В client.py RAGClient автоматически использует config.rag_api_key.

5. Миграции Alembic

Для управления схемой БД используйте Alembic. Установите переменную окружения FCKBOT_PROFILE_DIR с путём к профилю бота, затем:

alembic upgrade head

Для создания новой миграции:

alembic revision --autogenerate -m "описание"