smart-bot-factory 1.1.1__py3-none-any.whl

smart_bot_factory/memory/__init__.py

@@ -0,0 +1,8 @@
+"""
+Модуль для работы с памятью бота.
+"""
+
+from .static_memory import StaticMemoryManager
+
+__all__ = ["StaticMemoryManager"]
+

smart_bot_factory/memory/memory_manager.py

@@ -0,0 +1,299 @@
+import asyncio
+import logging
+from typing import List, Optional, Dict, Any
+from ..handlers.handlers import get_global_var
+
+from langchain.messages import SystemMessage
+from langchain_openai import ChatOpenAI
+from langchain_core.output_parsers import StrOutputParser
+
+logger = logging.getLogger(__name__)
+
+class MemoryManager:
+    def __init__(self):
+        self.supabase_client = get_global_var("supabase_client")
+        config = get_global_var("config")
+        
+        self.max_memory_messages = config.MAX_CONTEXT_MESSAGES
+        self.min_memory_messages = config.HISTORY_MIN_MESSAGES if config.HISTORY_MIN_MESSAGES else 4
+        self.token_limit = config.HISTORY_MAX_TOKENS if config.HISTORY_MAX_TOKENS else 5000
+        
+        self.chat_model = ChatOpenAI(model="gpt-5-mini", api_key=config.OPENAI_API_KEY) | StrOutputParser()
+        
+        # Словарь для отслеживания активных фоновых задач суммаризации по session_id
+        self._active_summarization_tasks: Dict[str, asyncio.Task] = {}
+        
+
+    async def get_memory_messages(self, session_id: str) -> List[Dict[str, Any]]:
+        """Возвращает историю сообщений в формате OpenAI (список словарей с role и content)"""
+        chat_messages: List[Dict[str, Any]] = []
+        
+        logger.debug(f"[MemoryManager] Запрос истории для сессии {session_id}")
+        session_info = await self.supabase_client.get_session_info(session_id)
+        messages_len = session_info.get('messages_len', self.min_memory_messages)
+        logger.info(
+            f"[MemoryManager] Текущий messages_len={messages_len}, min={self.min_memory_messages}, max={self.max_memory_messages}"
+        )
+        
+        stored_summary = session_info.get('summary', '')
+        if stored_summary:
+            logger.info("[MemoryManager] Найдена сохраненная суммаризация — добавляем в контекст")
+            formatted_summary = self._format_summary(stored_summary)
+            logger.debug(f"[MemoryManager] Форматированная суммаризация: {formatted_summary[:200]}...")
+            chat_messages.append({"role": "system", "content": formatted_summary})
+        else:
+            logger.info("[MemoryManager] Суммаризация не найдена в сессии")
+        
+        messages = await self.supabase_client.get_chat_history(session_id, limit=messages_len)
+        logger.info(f"[MemoryManager] Получено {len(messages)} сообщений из истории (limit={messages_len})")
+        
+        added_count = 0
+        for msg in messages:
+            if msg['role'] in ('user', 'assistant'):
+                chat_messages.append({"role": msg['role'], "content": msg['content']})
+                added_count += 1
+            else:
+                logger.debug(f"[MemoryManager] Пропущено сообщение с ролью: {msg['role']}")
+        
+        logger.info(f"[MemoryManager] Добавлено {added_count} сообщений из истории в контекст")
+        
+        total_tokens = self._count_tokens(chat_messages)
+        logger.info(
+            f"[MemoryManager] Подготовлено сообщений: {len(chat_messages)}, оценка токенов: {total_tokens}"
+        )
+        
+        # Проверяем, нужно ли обрезать (исключаем суммаризацию из подсчета для проверки лимита сообщений)
+        has_summary = chat_messages and chat_messages[0].get('role') == 'system' and self._is_summary_message(chat_messages[0])
+        effective_messages_count = len(chat_messages) - (1 if has_summary else 0)
+        
+        # Если нужно обрезать, делаем быструю обрезку без суммаризации и запускаем фоновую задачу
+        if total_tokens > self.token_limit or effective_messages_count > self.max_memory_messages - 1:
+            logger.warning(
+                f"[MemoryManager] История превышает лимиты (tokens>{self.token_limit} или messages>{effective_messages_count}>{self.max_memory_messages - 1}). Делаем быструю обрезку и запускаем фоновую суммаризацию."
+            )
+            # Быстрая обрезка: просто берем последние сообщения
+            history_tail_size = max(self.min_memory_messages - 1, 0)
+            if has_summary:
+                # Сохраняем суммаризацию и берем хвост истории
+                summary_msg = chat_messages[0]
+                history_messages = chat_messages[1:]
+                history_tail = history_messages[-history_tail_size:] if history_tail_size else []
+                chat_messages = [summary_msg] + history_tail
+            else:
+                # Берем только хвост истории
+                chat_messages = chat_messages[-history_tail_size:] if history_tail_size else []
+            
+            logger.info(f"[MemoryManager] Быстрая обрезка выполнена: {len(chat_messages)} сообщений")
+            
+            # Очищаем завершенные задачи из словаря (предотвращаем утечки памяти)
+            completed_sessions = [
+                sid for sid, task in self._active_summarization_tasks.items()
+                if task.done()
+            ]
+            for sid in completed_sessions:
+                del self._active_summarization_tasks[sid]
+                logger.debug(f"[MemoryManager] Удалена завершенная задача для сессии {sid}")
+            
+            # Проверяем, не запущена ли уже фоновая суммаризация для этой сессии
+            if session_id in self._active_summarization_tasks:
+                existing_task = self._active_summarization_tasks[session_id]
+                if not existing_task.done():
+                    logger.info(
+                        f"[MemoryManager] Фоновая суммаризация уже выполняется для сессии {session_id}, "
+                        f"пропускаем запуск новой. Существующая задача обработает все сообщения из БД."
+                    )
+                    # Не запускаем новую задачу, существующая уже обработает все сообщения из БД
+                else:
+                    # Задача завершена (не должна быть здесь после очистки, но на всякий случай)
+                    del self._active_summarization_tasks[session_id]
+                    task = asyncio.create_task(self._background_summarize(session_id))
+                    self._active_summarization_tasks[session_id] = task
+                    logger.info(f"[MemoryManager] Запущена новая фоновая задача суммаризации для сессии {session_id}")
+            else:
+                # Нет активной задачи, запускаем новую
+                task = asyncio.create_task(self._background_summarize(session_id))
+                self._active_summarization_tasks[session_id] = task
+                logger.info(f"[MemoryManager] Запущена фоновая задача суммаризации для сессии {session_id}")
+            
+        # Извлекаем суммаризацию из финального списка сообщений
+        summary_for_storage = self._extract_summary(chat_messages)
+        messages_len = self._calculate_messages_len(chat_messages)
+        
+        # Логируем финальное состояние перед возвратом
+        logger.info(
+            f"[MemoryManager] Финальное состояние: {len(chat_messages)} сообщений, messages_len={messages_len}, summary={'есть (' + str(len(summary_for_storage)) + ' символов)' if summary_for_storage else 'нет'}"
+        )
+        
+        # Логируем первые несколько сообщений для отладки
+        for idx, msg in enumerate(chat_messages[:3]):
+            role = msg.get('role', 'unknown')
+            content_preview = (msg.get('content', '') or '')[:100].replace("\n", " ")
+            logger.info(f"[MemoryManager] Сообщение #{idx + 1}: {role} - {content_preview}...")
+        
+        # Обновляем сессию без ожидания (быстрое обновление)
+        await self.supabase_client.update_session(
+            session_id, {"messages_len": messages_len, "summary": summary_for_storage}
+        )
+        logger.info(f"[MemoryManager] Сессия {session_id} обновлена в БД")
+        
+        return chat_messages
+    
+    async def _background_summarize(self, session_id: str):
+        """
+        Фоновая задача для создания суммаризации истории диалога.
+        Выполняется асинхронно, не блокирует основной поток.
+        """
+        try:
+            logger.info(f"[MemoryManager] 🔄 Начало фоновой суммаризации для сессии {session_id}")
+            
+            # Получаем полную историю из БД для суммаризации
+            session_info = await self.supabase_client.get_session_info(session_id)
+            messages_len = session_info.get('messages_len', self.min_memory_messages)
+            
+            # Получаем больше сообщений для суммаризации (берем больше, чем обычно)
+            full_messages = await self.supabase_client.get_chat_history(session_id, limit=messages_len * 2)
+            
+            # Формируем список сообщений для суммаризации
+            messages_for_summary: List[Dict[str, Any]] = []
+            existing_summary = session_info.get('summary', '')
+            
+            if existing_summary:
+                formatted_summary = self._format_summary(existing_summary)
+                messages_for_summary.append({"role": "system", "content": formatted_summary})
+            
+            for msg in full_messages:
+                if msg['role'] in ('user', 'assistant'):
+                    messages_for_summary.append({"role": msg['role'], "content": msg['content']})
+            
+            logger.info(f"[MemoryManager] 📚 Получено {len(messages_for_summary)} сообщений для суммаризации")
+            
+            # Создаем суммаризацию
+            trimmed_messages = await self._trim_messages(messages_for_summary, existing_summary)
+            
+            # Извлекаем новую суммаризацию
+            new_summary = self._extract_summary(trimmed_messages)
+            new_messages_len = self._calculate_messages_len(trimmed_messages)
+            
+            # Сохраняем результат в БД
+            await self.supabase_client.update_session(
+                session_id, {"messages_len": new_messages_len, "summary": new_summary}
+            )
+            
+            logger.info(
+                f"[MemoryManager] ✅ Фоновая суммаризация завершена для сессии {session_id}. "
+                f"Новая суммаризация: {len(new_summary)} символов, messages_len={new_messages_len}"
+            )
+            
+        except Exception as e:
+            logger.error(f"[MemoryManager] ❌ Ошибка в фоновой суммаризации для сессии {session_id}: {e}")
+            logger.exception("Полный стек ошибки:")
+        finally:
+            # Удаляем задачу из словаря активных задач после завершения (успешного или с ошибкой)
+            if session_id in self._active_summarization_tasks:
+                del self._active_summarization_tasks[session_id]
+                logger.debug(f"[MemoryManager] Задача суммаризации для сессии {session_id} удалена из активных")
+    
+    async def _trim_messages(
+        self,
+        messages: List[Dict[str, Any]],
+        summary: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """Обрезает сообщения, создавая суммаризацию. Работает со словарями OpenAI."""
+        existing_summary = summary or self._extract_summary(messages)
+        logger.info(f"[MemoryManager] Извлечена существующая суммаризация: {len(existing_summary) if existing_summary else 0} символов")
+        
+        messages_history: List[Dict[str, Any]] = (
+            messages[1:] if messages and messages[0].get('role') == 'system' and self._is_summary_message(messages[0]) else messages
+        )
+        logger.info(f"[MemoryManager] История для суммаризации: {len(messages_history)} сообщений (исходно было {len(messages)})")
+
+        summary_prompt = SystemMessage(
+            content=f"""
+            Ты — ассистент для суммаризации диалогов.
+            Твоя задача — объединить уже существующую суммаризацию с новыми сообщениями из истории.
+
+            Прошлая суммаризация: (может быть пустой)
+            {existing_summary} (если ее не было не пиши об этом и если есть тоже писать не надо)
+
+            Новые сообщения будут добавлены после этого system message.
+            Сохраняй все ключевые мысли и действия, избегай потерь информации, делай связную компактную суммаризацию.
+            
+            ВАЖНО:
+            - не надо ничего советовать, не надо ничего объяснять - твоя задача только суммаризация
+            
+            Возвращай только суммаризацию, без других комментариев.
+            Максимальный размер суммаризации - 500 токенов.
+            """
+        )
+
+        # Конвертируем словари OpenAI в LangChain сообщения для вызова модели
+        from ..handlers.handlers import openai_messages_to_langchain, langchain_messages_to_openai
+        langchain_history = openai_messages_to_langchain(messages_history)
+        prompt_messages = [summary_prompt] + langchain_history
+        
+        logger.info(f"[MemoryManager] Отправляем {len(messages_history)} сообщений на суммаризацию")
+        new_summary_text = await self.chat_model.ainvoke(prompt_messages)
+        logger.info(f"[MemoryManager] Получена новая суммаризация: {len(new_summary_text)} символов")
+        
+        formatted_summary = self._format_summary(new_summary_text)
+        new_summary = {"role": "system", "content": formatted_summary}
+        logger.info(f"[MemoryManager] Форматированная суммаризация: {len(formatted_summary)} символов")
+
+        history_tail_size = max(self.min_memory_messages - 1, 0)
+        history_tail = messages_history[-history_tail_size:] if history_tail_size else []
+        logger.info(
+            f"[MemoryManager] Новая суммаризация создана. Возвращаем {1 + len(history_tail)} сообщений (summary + хвост)."
+        )
+
+        return [new_summary] + history_tail
+
+    def _calculate_messages_len(
+        self, messages: List[Dict[str, Any]]
+    ) -> int:
+        """Вычисляет messages_len для словарей OpenAI"""
+        effective_len = len(messages)
+
+        if messages and messages[0].get('role') == 'system' and self._is_summary_message(messages[0]):
+            effective_len -= 1
+
+        result = max(effective_len, 0) + 2
+        logger.debug(
+            f"[MemoryManager] Расчет messages_len: исходно={len(messages)}, эффективно={effective_len}, итог={result}"
+        )
+        return result
+
+    def _count_tokens(self, messages: List[Dict[str, Any]]) -> int:
+        """Подсчитывает токены для словарей OpenAI"""
+        tokens = 0
+        for msg in messages:
+            content = msg.get('content', '')
+            tokens += max(1, len(content) // 4)
+        logger.debug(f"[MemoryManager] Оценка токенов для {len(messages)} сообщений: {tokens}")
+        return tokens
+
+    def _format_summary(self, summary: str) -> str:
+        header = "## Суммаризация истории диалога (предыдущие сообщения до текущего момента):"
+        summary_body = summary.strip()
+        if not summary_body:
+            return header
+        return f"{header}\n{summary_body}"
+
+    def _is_summary_message(self, message: Dict[str, Any]) -> bool:
+        """Проверяет, является ли сообщение суммаризацией (для словаря OpenAI)."""
+        if message.get('role') != 'system':
+            return False
+        content = message.get('content', '').strip()
+        return content.startswith("## Суммаризация истории диалога")
+
+    def _extract_summary(self, messages: List[Dict[str, Any]]) -> str:
+        """Извлекает суммаризацию из первого сообщения (для словарей OpenAI)."""
+        if not messages or messages[0].get('role') != 'system' or not self._is_summary_message(messages[0]):
+            return ""
+
+        content = messages[0].get('content', '').strip()
+        header = "## Суммаризация истории диалога (предыдущие сообщения до текущего момента):"
+        if content.startswith(header):
+            summary_text = content[len(header):].lstrip()
+            # Возвращаем пустую строку, если суммаризация содержит только заголовок
+            return summary_text if summary_text else ""
+        return content

smart_bot_factory/memory/static_memory.py

@@ -0,0 +1,214 @@
+"""
+Модуль для работы со статической памятью бота из текстовых файлов.
+"""
+
+import logging
+from pathlib import Path
+from typing import Optional, Dict, List
+
+from project_root_finder import root
+
+logger = logging.getLogger(__name__)
+
+PROJECT_ROOT = root
+
+
+def _get_bot_id_from_globals() -> Optional[str]:
+    """
+    Пытается получить bot_id из глобальных переменных.
+    Сначала пробует supabase_client, затем config.
+    
+    Returns:
+        bot_id если найден, None в противном случае
+    """
+    try:
+        from ..handlers.handlers import get_global_var
+        
+        # Пробуем получить из supabase_client
+        supabase_client = get_global_var("supabase_client")
+        if supabase_client and hasattr(supabase_client, "bot_id") and supabase_client.bot_id:
+            logger.debug(f"[StaticMemoryManager] bot_id получен из supabase_client: {supabase_client.bot_id}")
+            return supabase_client.bot_id
+        
+        # Пробуем получить из config
+        config = get_global_var("config")
+        if config and hasattr(config, "BOT_ID") and config.BOT_ID:
+            logger.debug(f"[StaticMemoryManager] bot_id получен из config: {config.BOT_ID}")
+            return config.BOT_ID
+        
+        logger.warning("[StaticMemoryManager] bot_id не найден в глобальных переменных")
+        return None
+    except Exception as e:
+        logger.debug(f"[StaticMemoryManager] Ошибка при получении bot_id из глобальных переменных: {e}")
+        return None
+
+
+class StaticMemoryManager:
+    """
+    Класс для работы со статической памятью бота из текстовых файлов.
+    
+    Автоматически ищет папку 'memory' в конфигурации бота (bots/{bot_id}/memory)
+    и предоставляет удобный интерфейс для чтения текстовых файлов.
+    
+    Пример использования:
+        # С автоматическим определением bot_id из глобальных переменных
+        memory = StaticMemoryManager()  # bot_id будет взят из supabase_client или config
+        
+        # Или с явным указанием bot_id
+        memory = StaticMemoryManager("mdclinica")
+        
+        # Чтение файлов
+        actions_info = memory.get("actions")  # Читает файл actions.txt
+        promotions = memory.get("promotions")  # Читает файл promotions.txt
+        all_files = memory.list_all()  # Список всех доступных файлов
+    """
+    
+    def __init__(self, bot_id: Optional[str] = None):
+        """
+        Инициализация менеджера статической памяти.
+        
+        Args:
+            bot_id: Идентификатор бота. Если не указан, будет попытка получить из глобальных переменных
+                   (supabase_client или config через get_global_var)
+        
+        Raises:
+            ValueError: Если bot_id не указан и не найден в глобальных переменных
+        """
+        # Если bot_id не указан, пытаемся получить из глобальных переменных
+        if bot_id is None:
+            bot_id = _get_bot_id_from_globals()
+            if bot_id is None:
+                raise ValueError(
+                    "bot_id не указан и не найден в глобальных переменных. "
+                    "Укажите bot_id явно или убедитесь, что supabase_client или config инициализированы."
+                )
+        
+        self.bot_id = bot_id
+        self.memory_dir = PROJECT_ROOT / "bots" / bot_id / "memory"
+        self._cache: Dict[str, str] = {}
+        
+        if not self.memory_dir.exists():
+            logger.warning(
+                f"[StaticMemoryManager] Папка memory не найдена для бота {bot_id}: {self.memory_dir}"
+            )
+            logger.info(f"[StaticMemoryManager] Создайте папку {self.memory_dir} для использования статической памяти")
+        else:
+            logger.info(f"[StaticMemoryManager] Инициализирован для бота {bot_id}, папка: {self.memory_dir}")
+    
+    def get(self, name: str, use_cache: bool = True) -> Optional[str]:
+        """
+        Читает содержимое текстового файла по имени.
+        
+        Args:
+            name: Имя файла без расширения (например, "actions" для файла actions.txt)
+            use_cache: Использовать ли кэш для повторных запросов (по умолчанию True)
+        
+        Returns:
+            Содержимое файла как строка, или None если файл не найден
+        
+        Examples:
+            >>> memory = StaticMemoryManager()  # или StaticMemoryManager("mdclinica")
+            >>> actions = memory.get("actions")  # Читает bots/{bot_id}/memory/actions.txt
+        """
+        # Проверяем кэш
+        if use_cache and name in self._cache:
+            logger.debug(f"[StaticMemoryManager] Возвращаем из кэша: {name}")
+            return self._cache[name]
+        
+        # Проверяем существование папки
+        if not self.memory_dir.exists():
+            logger.warning(f"[StaticMemoryManager] Папка memory не существует: {self.memory_dir}")
+            return None
+        
+        # Формируем путь к файлу
+        file_path = self.memory_dir / f"{name}.txt"
+        
+        if not file_path.exists():
+            logger.warning(f"[StaticMemoryManager] Файл не найден: {file_path}")
+            return None
+        
+        try:
+            content = file_path.read_text(encoding="utf-8")
+            logger.debug(f"[StaticMemoryManager] Прочитан файл {name}: {len(content)} символов")
+            
+            # Сохраняем в кэш
+            if use_cache:
+                self._cache[name] = content
+            
+            return content
+        except Exception as e:
+            logger.error(f"[StaticMemoryManager] Ошибка при чтении файла {file_path}: {e}")
+            return None
+    
+    def list_all(self) -> List[str]:
+        """
+        Возвращает список всех доступных файлов памяти (без расширения .txt).
+        
+        Returns:
+            Список имен файлов без расширения
+        
+        Examples:
+            >>> memory = StaticMemoryManager()  # или StaticMemoryManager("mdclinica")
+            >>> files = memory.list_all()  # ["actions", "promotions", "faq"]
+        """
+        if not self.memory_dir.exists():
+            logger.warning(f"[StaticMemoryManager] Папка memory не существует: {self.memory_dir}")
+            return []
+        
+        files = []
+        for file_path in self.memory_dir.glob("*.txt"):
+            files.append(file_path.stem)
+        
+        logger.debug(f"[StaticMemoryManager] Найдено файлов: {len(files)}")
+        return sorted(files)
+    
+    def exists(self, name: str) -> bool:
+        """
+        Проверяет, существует ли файл с указанным именем.
+        
+        Args:
+            name: Имя файла без расширения
+        
+        Returns:
+            True если файл существует, False в противном случае
+        """
+        if not self.memory_dir.exists():
+            return False
+        
+        file_path = self.memory_dir / f"{name}.txt"
+        return file_path.exists()
+    
+    def clear_cache(self):
+        """
+        Очищает кэш загруженных файлов.
+        Полезно, если файлы были изменены и нужно перезагрузить их.
+        """
+        self._cache.clear()
+        logger.debug("[StaticMemoryManager] Кэш очищен")
+    
+    def reload(self, name: str) -> Optional[str]:
+        """
+        Принудительно перезагружает файл из диска, игнорируя кэш.
+        
+        Args:
+            name: Имя файла без расширения
+        
+        Returns:
+            Содержимое файла как строка, или None если файл не найден
+        """
+        # Удаляем из кэша если есть
+        if name in self._cache:
+            del self._cache[name]
+        
+        # Читаем заново
+        return self.get(name, use_cache=True)
+    
+    def get_memory_dir(self) -> Path:
+        """
+        Возвращает путь к папке memory.
+        
+        Returns:
+            Path объект с путем к папке memory
+        """
+        return self.memory_dir
+

smart_bot_factory/message/__init__.py

@@ -0,0 +1,56 @@
+"""
+Message модули smart_bot_factory
+"""
+
+from ..core.message_sender import (send_message, send_message_by_ai,
+                                   send_message_by_human,
+                                   send_message_to_users_by_stage)
+
+
+def get_bot():
+    """
+    Получает aiogram Bot из глобального контекста
+
+    Доступен после вызова bot_builder.start()
+
+    Returns:
+        Bot: aiogram Bot объект
+
+    Raises:
+        RuntimeError: Если bot еще не инициализирован
+
+    Example:
+        from smart_bot_factory.message import get_bot
+
+        @event_router.event_handler("booking")
+        async def handle_booking(user_id: int, event_data: str):
+            bot = get_bot()
+
+            # Получаем информацию о пользователе из Telegram
+            telegram_user = await bot.get_chat(user_id)
+            name = telegram_user.first_name or 'Клиент'
+
+            # Используем любые методы aiogram Bot
+            await bot.send_message(user_id, f"Привет, {name}!")
+            await bot.send_photo(user_id, photo=...)
+    """
+    from ..handlers.handlers import get_global_var
+
+    bot = get_global_var("bot")
+    if not bot:
+        raise RuntimeError(
+            "Bot еще не инициализирован. "
+            "Убедитесь что bot_builder.start() уже вызван. "
+            "Функция get_bot() доступна только внутри обработчиков событий, "
+            "которые выполняются во время работы бота."
+        )
+    return bot
+
+
+__all__ = [
+    "send_message_by_human",
+    "send_message_by_ai",
+    "send_message_to_users_by_stage",
+    "send_message",  # Чистая отправка с файлами и кнопками
+    "get_bot",  # Доступ к aiogram Bot
+]

smart_bot_factory/rag/__init__.py

@@ -0,0 +1,5 @@
+from .vectorstore import VectorStore
+from .decorators import rag
+from .router import RagRouter
+
+__all__ = ["VectorStore", "rag", "RagRouter"]

smart_bot_factory/rag/decorators.py

@@ -0,0 +1,29 @@
+from typing import Any, Callable
+
+from langchain.tools import tool as langchain_tool
+
+
+def rag(*tool_args: Any, **tool_kwargs: Any):
+    """
+    Wrapper around langchain.tools.tool to keep rag-related tooling imports localized.
+
+    Usage:
+        @rag
+        def my_tool(...):
+            ...
+
+        @rag(return_direct=True)
+        def my_other_tool(...):
+            ...
+    """
+
+    if tool_args and callable(tool_args[0]) and not tool_kwargs:
+        # Called without params: @rag
+        func = tool_args[0]
+        return langchain_tool(func)
+
+    def decorator(func: Callable[..., Any]):
+        return langchain_tool(*tool_args, **tool_kwargs)(func)
+
+    return decorator
+

smart_bot_factory/rag/router.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+from langchain_core.tools import BaseTool
+
+from .decorators import rag
+from ..utils.tool_router import ToolRouter
+
+logger = logging.getLogger(__name__)
+
+
+class RagRouter(ToolRouter):
+    """
+    Упрощенный роутер для регистрации RAG-инструментов.
+
+    Позволяет описывать инструменты через декоратор `@rag_router.tool`
+    и потом одним вызовом подключать их к `BotBuilder`.
+    """
+
+    def tool(self, *tool_args: Any, **tool_kwargs: Any) -> Callable[[Callable[..., Any]], BaseTool]:
+        """
+        Декоратор для регистрации функции как RAG-инструмента.
+
+        Пример:
+            rag_router = RagRouter("mdclinica_rag")
+
+            @rag_router.tool
+            async def get_service(...):
+                ...
+        """
+
+        if tool_args and callable(tool_args[0]) and not tool_kwargs:
+            func = tool_args[0]
+            tool_obj = rag(func)
+            self.add_tool(tool_obj)
+            return tool_obj
+
+        def decorator(func: Callable[..., Any]) -> BaseTool:
+            tool_obj = rag(*tool_args, **tool_kwargs)(func)
+            self.add_tool(tool_obj)
+            return tool_obj
+
+        return decorator
+
+    def register_to(self, bot_builder) -> None:
+        tools = self.get_tools()
+        if not tools:
+            logger.warning("⚠️ RagRouter %s не содержит инструментов для регистрации", self.name)
+            return
+        bot_builder.register_rag(self)
+        logger.info("✅ RagRouter %s: зарегистрировано %d инструментов", self.name, len(tools))
+