smart-bot-factory 0.3.5__tar.gz → 0.3.7__tar.gz

{smart_bot_factory-0.3.5 → smart_bot_factory-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart-bot-factory
-Version: 0.3.5
+Version: 0.3.7
 Summary: Библиотека для создания умных чат-ботов
 Author-email: Kopatych <eserov73@gmail.com>
 License: MIT
@@ -44,6 +44,7 @@ Description-Content-Type: text/markdown
   - [event_handler](#event_handler---обработчики-событий)
   - [schedule_task](#schedule_task---запланированные-задачи)
   - [global_handler](#global_handler---глобальные-обработчики)
+- [Dashboard Info](#-dashboard-info---отправка-данных-в-дашборд)
 - [Хуки для кастомизации](#-хуки-для-кастомизации)
 - [Telegram роутеры](#-telegram-роутеры)
 - [Расширенные возможности](#-расширенные-возможности)
@@ -187,9 +188,10 @@ sbf link
 
 ```python
 @event_router.event_handler(
-    event_type: str,      # Тип события
-    notify: bool = False, # Уведомлять админов
-    once_only: bool = True # Выполнять только 1 раз
+    event_type: str,                # Тип события
+    notify: bool = False,           # Уведомлять админов
+    once_only: bool = True,         # Выполнять только 1 раз
+    send_ai_response: bool = True   # Отправлять ответ от ИИ
 )
 async def handler(user_id: int, event_data: str):
     # Ваш код
@@ -201,6 +203,7 @@ async def handler(user_id: int, event_data: str):
 - **`event_type`** (обязательный) - Уникальное имя события
 - **`notify`** (по умолчанию `False`) - Отправлять уведомление админам после выполнения
 - **`once_only`** (по умолчанию `True`) - Если `True`, событие выполнится только 1 раз для пользователя
+- **`send_ai_response`** (по умолчанию `True`) - Если `False`, ИИ НЕ отправит сообщение после выполнения обработчика
 
 **Как работает:**
 
@@ -235,6 +238,16 @@ async def handle_question(user_id: int, question: str):
     """Обрабатывает вопросы (может быть много)"""
     # Логика обработки
     return {"status": "answered"}
+
+# БЕЗ отправки ответа от ИИ
+@event_router.event_handler("silent_event", send_ai_response=False)
+async def handle_silent(user_id: int, event_data: str):
+    """
+    Выполняет логику БЕЗ отправки сообщения от ИИ
+    Используйте когда хотите только собрать данные без ответа пользователю
+    """
+    await send_message_by_human(user_id, "✅ Данные сохранены")
+    return {"status": "saved"}
 ```
 
 ---
@@ -247,12 +260,13 @@ async def handle_question(user_id: int, question: str):
 
 ```python
 @event_router.schedule_task(
-    task_name: str,              # Название задачи
-    delay: Union[str, int],      # Задержка: "1h 30m" или секунды
-    notify: bool = False,        # Уведомлять админов
-    smart_check: bool = True,    # Умная проверка активности
-    once_only: bool = True,      # Выполнять только 1 раз
-    event_type: Union[str, Callable] = None  # Источник времени события
+    task_name: str,                     # Название задачи
+    delay: Union[str, int],             # Задержка: "1h 30m" или секунды
+    notify: bool = False,               # Уведомлять админов
+    smart_check: bool = True,           # Умная проверка активности
+    once_only: bool = True,             # Выполнять только 1 раз
+    event_type: Union[str, Callable] = None,  # Источник времени события
+    send_ai_response: bool = True       # Отправлять ответ от ИИ
 )
 async def handler(user_id: int, user_data: str):
     # Ваш код
@@ -273,6 +287,7 @@ async def handler(user_id: int, user_data: str):
 - **`event_type`** (опционально) - Источник времени события:
   - **Строка**: `"appointment_booking"` - ищет событие в БД и вычисляет время
   - **Функция**: `async def(user_id, user_data) -> datetime` - кастомная логика
+- **`send_ai_response`** (по умолчанию `True`) - Если `False`, ИИ НЕ отправит сообщение после выполнения задачи
 
 **Формула времени с `event_type`:**
 
@@ -362,11 +377,12 @@ async def important_reminder(user_id: int, text: str):
 
 ```python
 @event_router.global_handler(
-    handler_type: str,           # Тип обработчика
-    delay: Union[str, int],      # Задержка
-    notify: bool = False,        # Уведомлять админов
-    once_only: bool = True,      # Выполнять только 1 раз
-    event_type: Union[str, Callable] = None  # Источник времени
+    handler_type: str,                  # Тип обработчика
+    delay: Union[str, int],             # Задержка
+    notify: bool = False,               # Уведомлять админов
+    once_only: bool = True,             # Выполнять только 1 раз
+    event_type: Union[str, Callable] = None,  # Источник времени
+    send_ai_response: bool = True       # Отправлять ответ от ИИ
 )
 async def handler(handler_data: str):
     # Ваш код
@@ -420,6 +436,173 @@ async def notify_promo_ending(handler_data: str):
 
 ---
 
+## 📊 Dashboard Info - Отправка данных в дашборд
+
+**Назначение:** Позволяет отправлять информацию о событиях в дашборд (таблица `scheduled_events`, столбец `info_dashboard`) для аналитики и мониторинга.
+
+### Как работает
+
+1. Обработчик события возвращает результат с полем `'info'`
+2. Система автоматически извлекает это поле и записывает в `info_dashboard` таблицы
+3. Функция `prepare_dashboard_info` автоматически:
+   - Получает `username` из таблицы `sales_users`
+   - Форматирует строку с подстановкой данных
+   - Добавляет московское время (UTC+3)
+
+### Сигнатура
+
+```python
+from smart_bot_factory.dashboard import prepare_dashboard_info
+
+dashboard_data = await prepare_dashboard_info(
+    description_template: str,  # Строка с {username}, например "{username} купил подписку"
+    title: str,                 # Заголовок для дашборда
+    user_id: int                # Telegram ID пользователя
+)
+```
+
+**Возвращает:**
+
+```python
+{
+    'title': 'Заголовок',
+    'description': '@username123 купил подписку',  # С подстановкой реального username
+    'created_at': '2025-10-18T15:30:45.123456+03:00'  # Московское время
+}
+```
+
+### Примеры использования
+
+#### С event_handler
+
+```python
+from smart_bot_factory.dashboard import prepare_dashboard_info
+
+@event_router.event_handler("collect_phone", notify=True, once_only=True)
+async def handle_phone_collection(user_id: int, phone_number: str):
+    """Сохраняет телефон клиента"""
+    
+    # Ваша бизнес-логика
+    session = await supabase_client.get_active_session(user_id)
+    if session:
+        metadata = session.get('metadata', {})
+        metadata['phone'] = phone_number
+        await supabase_client.update_session_metadata(session['id'], metadata)
+    
+    await send_message_by_human(
+        user_id=user_id,
+        message_text=f"✅ Спасибо! Ваш номер {phone_number} сохранен"
+    )
+    
+    # 📊 Возвращаем результат С данными для дашборда
+    return {
+        "status": "success",
+        "phone": phone_number,
+        "info": await prepare_dashboard_info(
+            description_template="{username} оставил номер телефона",
+            title="Новый контакт",
+            user_id=user_id
+        )
+    }
+```
+
+#### С schedule_task
+
+```python
+@event_router.schedule_task("follow_up", delay="24h", smart_check=True)
+async def send_follow_up(user_id: int, reminder_text: str):
+    """Напоминание через 24 часа"""
+    
+    await send_message_by_human(
+        user_id=user_id,
+        message_text=f"👋 {reminder_text}"
+    )
+    
+    # 📊 Работает и для задач!
+    return {
+        "status": "sent",
+        "type": "follow_up",
+        "info": await prepare_dashboard_info(
+            description_template="{username} получил напоминание",
+            title="Напоминание отправлено",
+            user_id=user_id
+        )
+    }
+```
+
+#### БЕЗ дашборда
+
+Если не нужно отправлять данные в дашборд - просто не добавляйте поле `'info'`:
+
+```python
+@event_router.event_handler("collect_name", once_only=False)
+async def handle_name_collection(user_id: int, client_name: str):
+    """БЕЗ дашборда - просто сохраняем имя"""
+    
+    await send_message_by_human(
+        user_id=user_id,
+        message_text=f"✅ Спасибо! Ваше имя {client_name} сохранено"
+    )
+    
+    # Возвращаем БЕЗ поля 'info' - дашборд останется пустым
+    return {"status": "success"}
+```
+
+### Что попадает в БД
+
+**События С дашбордом:**
+
+```sql
+SELECT * FROM scheduled_events WHERE id = '123';
+
+id: 123
+event_type: collect_phone
+event_category: user_event
+user_id: 12345
+status: completed
+result_data: {"status": "success", "phone": "+79001234567", "info": {...}}
+info_dashboard: {
+  "title": "Новый контакт",
+  "description": "@username123 оставил номер телефона",
+  "created_at": "2025-10-18T15:30:45+03:00"
+}
+```
+
+**События БЕЗ дашборда:**
+
+```sql
+SELECT * FROM scheduled_events WHERE id = '124';
+
+id: 124
+event_type: collect_name
+event_category: user_event
+user_id: 12345
+status: completed
+result_data: {"status": "success"}
+info_dashboard: NULL  ← Остается пустым
+```
+
+### Форматирование строк
+
+Функция `prepare_dashboard_info` поддерживает подстановку `{username}`:
+
+```python
+# Примеры шаблонов:
+"{username} купил подписку на 1 год"
+"{username} оставил контакт"
+"{username} записался на консультацию"
+"{username} задал вопрос о продукте"
+"{username} завершил оплату"
+
+# После подстановки:
+"@user123 купил подписку на 1 год"
+"@ivan_petrov оставил контакт"
+```
+
+Если пользователь не найден в `sales_users` - будет использован fallback: `user_12345`
+
+---
+
 ## 🎣 Хуки для кастомизации
 
 Хуки позволяют внедрять свою логику в стандартную обработку сообщений без переписывания всей функции.
@@ -813,16 +996,46 @@ DEBUG_MODE=false
 
 ## 🎯 Сравнение декораторов
 
-| Декоратор | Когда выполняется | Для кого | Параметры |
-|-----------|-------------------|----------|-----------|
-| `@event_handler` | Немедленно | 1 пользователь | `event_type`, `notify`, `once_only` |
-| `@schedule_task` | Через время | 1 пользователь | `task_name`, `delay`, `event_type`, `smart_check`, `once_only`, `notify` |
-| `@global_handler` | Через время | Все пользователи | `handler_type`, `delay`, `event_type`, `once_only`, `notify` |
+| Декоратор | Когда выполняется | Для кого | Ключевые параметры |
+|-----------|-------------------|----------|--------------------|
+| `@event_handler` | Немедленно | 1 пользователь | `event_type`, `notify`, `once_only`, `send_ai_response` |
+| `@schedule_task` | Через время | 1 пользователь | `task_name`, `delay`, `event_type`, `smart_check`, `once_only`, `notify`, `send_ai_response` |
+| `@global_handler` | Через время | Все пользователи | `handler_type`, `delay`, `event_type`, `once_only`, `notify`, `send_ai_response` |
 
 ---
 
 ## 🔑 Ключевые концепции
 
+### `send_ai_response=True`
+
+Контролирует отправку сообщения от ИИ после выполнения обработчика:
+
+- **`True`** (по умолчанию) - ИИ отправит сообщение пользователю после выполнения обработчика
+- **`False`** - ИИ НЕ отправит сообщение (используйте когда нужна только фоновая обработка или когда отправляете сообщение вручную)
+
+**Когда использовать `send_ai_response=False`:**
+
+- Когда нужно только собрать данные без ответа пользователю
+- Когда вы сами отправляете сообщение через `send_message_by_human()`
+- Для фоновых задач без взаимодействия с пользователем
+
+```python
+# ИИ отправит сообщение (по умолчанию)
+@event_router.event_handler("collect_phone")
+async def save_phone(user_id: int, phone: str):
+    # Сохраняем телефон
+    # ИИ автоматически отправит сообщение после выполнения
+    return {"status": "success"}
+
+# ИИ НЕ отправит сообщение
+@event_router.event_handler("collect_name", send_ai_response=False)
+async def save_name(user_id: int, name: str):
+    # Сохраняем имя
+    await send_message_by_human(user_id, f"✅ Имя {name} сохранено")
+    # ИИ не будет отправлять свое сообщение
+    return {"status": "success"}
+```
+
 ### `once_only=True`
 
 Гарантирует выполнение события только 1 раз для пользователя:

{smart_bot_factory-0.3.5 → smart_bot_factory-0.3.7}/README.md

@@ -11,6 +11,7 @@
   - [event_handler](#event_handler---обработчики-событий)
   - [schedule_task](#schedule_task---запланированные-задачи)
   - [global_handler](#global_handler---глобальные-обработчики)
+- [Dashboard Info](#-dashboard-info---отправка-данных-в-дашборд)
 - [Хуки для кастомизации](#-хуки-для-кастомизации)
 - [Telegram роутеры](#-telegram-роутеры)
 - [Расширенные возможности](#-расширенные-возможности)
@@ -154,9 +155,10 @@ sbf link
 
 ```python
 @event_router.event_handler(
-    event_type: str,      # Тип события
-    notify: bool = False, # Уведомлять админов
-    once_only: bool = True # Выполнять только 1 раз
+    event_type: str,                # Тип события
+    notify: bool = False,           # Уведомлять админов
+    once_only: bool = True,         # Выполнять только 1 раз
+    send_ai_response: bool = True   # Отправлять ответ от ИИ
 )
 async def handler(user_id: int, event_data: str):
     # Ваш код
@@ -168,6 +170,7 @@ async def handler(user_id: int, event_data: str):
 - **`event_type`** (обязательный) - Уникальное имя события
 - **`notify`** (по умолчанию `False`) - Отправлять уведомление админам после выполнения
 - **`once_only`** (по умолчанию `True`) - Если `True`, событие выполнится только 1 раз для пользователя
+- **`send_ai_response`** (по умолчанию `True`) - Если `False`, ИИ НЕ отправит сообщение после выполнения обработчика
 
 **Как работает:**
 
@@ -202,6 +205,16 @@ async def handle_question(user_id: int, question: str):
     """Обрабатывает вопросы (может быть много)"""
     # Логика обработки
     return {"status": "answered"}
+
+# БЕЗ отправки ответа от ИИ
+@event_router.event_handler("silent_event", send_ai_response=False)
+async def handle_silent(user_id: int, event_data: str):
+    """
+    Выполняет логику БЕЗ отправки сообщения от ИИ
+    Используйте когда хотите только собрать данные без ответа пользователю
+    """
+    await send_message_by_human(user_id, "✅ Данные сохранены")
+    return {"status": "saved"}
 ```
 
 ---
@@ -214,12 +227,13 @@ async def handle_question(user_id: int, question: str):
 
 ```python
 @event_router.schedule_task(
-    task_name: str,              # Название задачи
-    delay: Union[str, int],      # Задержка: "1h 30m" или секунды
-    notify: bool = False,        # Уведомлять админов
-    smart_check: bool = True,    # Умная проверка активности
-    once_only: bool = True,      # Выполнять только 1 раз
-    event_type: Union[str, Callable] = None  # Источник времени события
+    task_name: str,                     # Название задачи
+    delay: Union[str, int],             # Задержка: "1h 30m" или секунды
+    notify: bool = False,               # Уведомлять админов
+    smart_check: bool = True,           # Умная проверка активности
+    once_only: bool = True,             # Выполнять только 1 раз
+    event_type: Union[str, Callable] = None,  # Источник времени события
+    send_ai_response: bool = True       # Отправлять ответ от ИИ
 )
 async def handler(user_id: int, user_data: str):
     # Ваш код
@@ -240,6 +254,7 @@ async def handler(user_id: int, user_data: str):
 - **`event_type`** (опционально) - Источник времени события:
   - **Строка**: `"appointment_booking"` - ищет событие в БД и вычисляет время
   - **Функция**: `async def(user_id, user_data) -> datetime` - кастомная логика
+- **`send_ai_response`** (по умолчанию `True`) - Если `False`, ИИ НЕ отправит сообщение после выполнения задачи
 
 **Формула времени с `event_type`:**
 
@@ -329,11 +344,12 @@ async def important_reminder(user_id: int, text: str):
 
 ```python
 @event_router.global_handler(
-    handler_type: str,           # Тип обработчика
-    delay: Union[str, int],      # Задержка
-    notify: bool = False,        # Уведомлять админов
-    once_only: bool = True,      # Выполнять только 1 раз
-    event_type: Union[str, Callable] = None  # Источник времени
+    handler_type: str,                  # Тип обработчика
+    delay: Union[str, int],             # Задержка
+    notify: bool = False,               # Уведомлять админов
+    once_only: bool = True,             # Выполнять только 1 раз
+    event_type: Union[str, Callable] = None,  # Источник времени
+    send_ai_response: bool = True       # Отправлять ответ от ИИ
 )
 async def handler(handler_data: str):
     # Ваш код
@@ -387,6 +403,173 @@ async def notify_promo_ending(handler_data: str):
 
 ---
 
+## 📊 Dashboard Info - Отправка данных в дашборд
+
+**Назначение:** Позволяет отправлять информацию о событиях в дашборд (таблица `scheduled_events`, столбец `info_dashboard`) для аналитики и мониторинга.
+
+### Как работает
+
+1. Обработчик события возвращает результат с полем `'info'`
+2. Система автоматически извлекает это поле и записывает в `info_dashboard` таблицы
+3. Функция `prepare_dashboard_info` автоматически:
+   - Получает `username` из таблицы `sales_users`
+   - Форматирует строку с подстановкой данных
+   - Добавляет московское время (UTC+3)
+
+### Сигнатура
+
+```python
+from smart_bot_factory.dashboard import prepare_dashboard_info
+
+dashboard_data = await prepare_dashboard_info(
+    description_template: str,  # Строка с {username}, например "{username} купил подписку"
+    title: str,                 # Заголовок для дашборда
+    user_id: int                # Telegram ID пользователя
+)
+```
+
+**Возвращает:**
+
+```python
+{
+    'title': 'Заголовок',
+    'description': '@username123 купил подписку',  # С подстановкой реального username
+    'created_at': '2025-10-18T15:30:45.123456+03:00'  # Московское время
+}
+```
+
+### Примеры использования
+
+#### С event_handler
+
+```python
+from smart_bot_factory.dashboard import prepare_dashboard_info
+
+@event_router.event_handler("collect_phone", notify=True, once_only=True)
+async def handle_phone_collection(user_id: int, phone_number: str):
+    """Сохраняет телефон клиента"""
+    
+    # Ваша бизнес-логика
+    session = await supabase_client.get_active_session(user_id)
+    if session:
+        metadata = session.get('metadata', {})
+        metadata['phone'] = phone_number
+        await supabase_client.update_session_metadata(session['id'], metadata)
+    
+    await send_message_by_human(
+        user_id=user_id,
+        message_text=f"✅ Спасибо! Ваш номер {phone_number} сохранен"
+    )
+    
+    # 📊 Возвращаем результат С данными для дашборда
+    return {
+        "status": "success",
+        "phone": phone_number,
+        "info": await prepare_dashboard_info(
+            description_template="{username} оставил номер телефона",
+            title="Новый контакт",
+            user_id=user_id
+        )
+    }
+```
+
+#### С schedule_task
+
+```python
+@event_router.schedule_task("follow_up", delay="24h", smart_check=True)
+async def send_follow_up(user_id: int, reminder_text: str):
+    """Напоминание через 24 часа"""
+    
+    await send_message_by_human(
+        user_id=user_id,
+        message_text=f"👋 {reminder_text}"
+    )
+    
+    # 📊 Работает и для задач!
+    return {
+        "status": "sent",
+        "type": "follow_up",
+        "info": await prepare_dashboard_info(
+            description_template="{username} получил напоминание",
+            title="Напоминание отправлено",
+            user_id=user_id
+        )
+    }
+```
+
+#### БЕЗ дашборда
+
+Если не нужно отправлять данные в дашборд - просто не добавляйте поле `'info'`:
+
+```python
+@event_router.event_handler("collect_name", once_only=False)
+async def handle_name_collection(user_id: int, client_name: str):
+    """БЕЗ дашборда - просто сохраняем имя"""
+    
+    await send_message_by_human(
+        user_id=user_id,
+        message_text=f"✅ Спасибо! Ваше имя {client_name} сохранено"
+    )
+    
+    # Возвращаем БЕЗ поля 'info' - дашборд останется пустым
+    return {"status": "success"}
+```
+
+### Что попадает в БД
+
+**События С дашбордом:**
+
+```sql
+SELECT * FROM scheduled_events WHERE id = '123';
+
+id: 123
+event_type: collect_phone
+event_category: user_event
+user_id: 12345
+status: completed
+result_data: {"status": "success", "phone": "+79001234567", "info": {...}}
+info_dashboard: {
+  "title": "Новый контакт",
+  "description": "@username123 оставил номер телефона",
+  "created_at": "2025-10-18T15:30:45+03:00"
+}
+```
+
+**События БЕЗ дашборда:**
+
+```sql
+SELECT * FROM scheduled_events WHERE id = '124';
+
+id: 124
+event_type: collect_name
+event_category: user_event
+user_id: 12345
+status: completed
+result_data: {"status": "success"}
+info_dashboard: NULL  ← Остается пустым
+```
+
+### Форматирование строк
+
+Функция `prepare_dashboard_info` поддерживает подстановку `{username}`:
+
+```python
+# Примеры шаблонов:
+"{username} купил подписку на 1 год"
+"{username} оставил контакт"
+"{username} записался на консультацию"
+"{username} задал вопрос о продукте"
+"{username} завершил оплату"
+
+# После подстановки:
+"@user123 купил подписку на 1 год"
+"@ivan_petrov оставил контакт"
+```
+
+Если пользователь не найден в `sales_users` - будет использован fallback: `user_12345`
+
+---
+
 ## 🎣 Хуки для кастомизации
 
 Хуки позволяют внедрять свою логику в стандартную обработку сообщений без переписывания всей функции.
@@ -780,16 +963,46 @@ DEBUG_MODE=false
 
 ## 🎯 Сравнение декораторов
 
-| Декоратор | Когда выполняется | Для кого | Параметры |
-|-----------|-------------------|----------|-----------|
-| `@event_handler` | Немедленно | 1 пользователь | `event_type`, `notify`, `once_only` |
-| `@schedule_task` | Через время | 1 пользователь | `task_name`, `delay`, `event_type`, `smart_check`, `once_only`, `notify` |
-| `@global_handler` | Через время | Все пользователи | `handler_type`, `delay`, `event_type`, `once_only`, `notify` |
+| Декоратор | Когда выполняется | Для кого | Ключевые параметры |
+|-----------|-------------------|----------|--------------------|
+| `@event_handler` | Немедленно | 1 пользователь | `event_type`, `notify`, `once_only`, `send_ai_response` |
+| `@schedule_task` | Через время | 1 пользователь | `task_name`, `delay`, `event_type`, `smart_check`, `once_only`, `notify`, `send_ai_response` |
+| `@global_handler` | Через время | Все пользователи | `handler_type`, `delay`, `event_type`, `once_only`, `notify`, `send_ai_response` |
 
 ---
 
 ## 🔑 Ключевые концепции
 
+### `send_ai_response=True`
+
+Контролирует отправку сообщения от ИИ после выполнения обработчика:
+
+- **`True`** (по умолчанию) - ИИ отправит сообщение пользователю после выполнения обработчика
+- **`False`** - ИИ НЕ отправит сообщение (используйте когда нужна только фоновая обработка или когда отправляете сообщение вручную)
+
+**Когда использовать `send_ai_response=False`:**
+
+- Когда нужно только собрать данные без ответа пользователю
+- Когда вы сами отправляете сообщение через `send_message_by_human()`
+- Для фоновых задач без взаимодействия с пользователем
+
+```python
+# ИИ отправит сообщение (по умолчанию)
+@event_router.event_handler("collect_phone")
+async def save_phone(user_id: int, phone: str):
+    # Сохраняем телефон
+    # ИИ автоматически отправит сообщение после выполнения
+    return {"status": "success"}
+
+# ИИ НЕ отправит сообщение
+@event_router.event_handler("collect_name", send_ai_response=False)
+async def save_name(user_id: int, name: str):
+    # Сохраняем имя
+    await send_message_by_human(user_id, f"✅ Имя {name} сохранено")
+    # ИИ не будет отправлять свое сообщение
+    return {"status": "success"}
+```
+
 ### `once_only=True`
 
 Гарантирует выполнение события только 1 раз для пользователя: