smart-bot-factory 0.1.4__tar.gz → 0.1.6__tar.gz

smart_bot_factory-0.1.6/CLIENTS_USAGE.md

@@ -0,0 +1,74 @@
+# Использование клиентов в Smart Bot Factory
+
+## Простой импорт клиентов
+
+```python
+from smart_bot_factory.clients import supabase_client, openai_client
+```
+
+## Автозаполнение работает!
+
+После импорта IDE знает типы и предлагает:
+
+### Supabase Client
+```python
+# IDE предлагает методы SupabaseClient
+users = supabase_client.client.table('users').select('*').execute()
+user = supabase_client.create_or_get_user(user_data)
+session = supabase_client.create_chat_session(user_data, system_prompt)
+```
+
+### OpenAI Client  
+```python
+# IDE предлагает методы OpenAIClient
+response = openai_client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "Hello"}]
+)
+```
+
+## Пример глобального обработчика
+
+```python
+from smart_bot_factory.core import global_handler
+from smart_bot_factory.clients import supabase_client
+
+@global_handler("mass_notification", notify=True)
+async def send_mass_notification(message_text: str):
+    """Отправляет сообщение всем пользователям"""
+    
+    # Проверяем доступность
+    if not supabase_client:
+        return {"status": "error", "message": "Supabase клиент не найден"}
+    
+    try:
+        # Получаем всех пользователей - автозаполнение работает!
+        users = supabase_client.client.table('users').select('telegram_id').execute()
+        
+        sent_count = 0
+        for user in users.data:
+            # Отправляем сообщение каждому пользователю
+            # ... логика отправки ...
+            sent_count += 1
+        
+        return {
+            "status": "completed",
+            "sent_count": sent_count,
+            "message": f"Отправлено {sent_count} сообщений"
+        }
+        
+    except Exception as e:
+        return {"status": "error", "message": str(e)}
+```
+
+## Доступные клиенты
+
+- `supabase_client` - клиент для работы с Supabase
+- `openai_client` - клиент для работы с OpenAI
+
+## Важно
+
+- Клиенты доступны только после запуска бота через `BotBuilder`
+- Все клиенты типизированы для полной поддержки автозаполнения
+- Остальные глобальные переменные (config, admin_manager и т.д.) недоступны пользователю
+

smart_bot_factory-0.1.6/PKG-INFO

@@ -0,0 +1,466 @@
+Metadata-Version: 2.4
+Name: smart-bot-factory
+Version: 0.1.6
+Summary: Библиотека для создания умных чат-ботов
+Author-email: Kopatych <herousplay@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: chatbot,cli,openai,supabase,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: aiogram>=3.4.1
+Requires-Dist: click>=8.0.0
+Requires-Dist: openai>=1.12.0
+Requires-Dist: project-root-finder>=1.9
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pytz>=2023.3
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: supabase>=2.3.4
+Description-Content-Type: text/markdown
+
+# Smart Bot Factory
+
+Инструмент для создания умных чат-ботов с поддержкой AI, административной панели и тестирования.
+
+## 🚀 Быстрый старт
+
+### Установка
+
+```bash
+pip install smart-bot-factory
+```
+
+### Создание первого бота
+
+```bash
+# Создать нового бота
+sbf create my-bot
+
+# Запустить бота
+sbf run my-bot
+```
+
+## 📋 Команды CLI
+
+### `sbf create <bot_id> [template]`
+
+Создает нового бота с указанным ID.
+
+```bash
+# Создать бота с базовым шаблоном
+sbf create my-bot
+
+# Создать бота на основе существующего
+sbf create new-bot existing-bot
+```
+
+**Что создается:**
+- 📁 `bots/my-bot/` - папка с конфигурацией бота
+- 📄 `my-bot.py` - файл для запуска бота
+- ⚙️ `.env` - файл конфигурации
+- 📝 Промпты, тесты, файлы из шаблона
+
+### `sbf run <bot_id>`
+
+Запускает бота в рабочем режиме.
+
+```bash
+sbf run my-bot
+```
+
+**Автоматически:**
+- ✅ Проверяет наличие всех необходимых файлов
+- ⚙️ Загружает конфигурацию из `.env`
+- 🚀 Запускает бота
+
+### `sbf test <bot_id> [options]`
+
+Запускает тесты бота.
+
+```bash
+# Все тесты
+sbf test my-bot
+
+# Конкретный файл тестов
+sbf test my-bot scenario_examples.yaml
+
+# Подробный вывод
+sbf test my-bot -v
+
+# Больше потоков для быстрого тестирования
+sbf test my-bot --max-concurrent 10
+```
+
+### `sbf list`
+
+Показывает список всех доступных ботов.
+
+```bash
+sbf list
+```
+
+### `sbf config <bot_id>`
+
+Открывает конфигурацию бота в редакторе.
+
+```bash
+sbf config my-bot
+```
+
+### `sbf prompts <bot_id> [options]`
+
+Управление промптами бота.
+
+```bash
+# Показать список промптов
+sbf prompts my-bot --list
+
+# Редактировать промпт
+sbf prompts my-bot --edit system_prompt
+
+# Добавить новый промпт
+sbf prompts my-bot --add custom_prompt
+```
+
+### `sbf copy <source_bot> <new_bot>`
+
+Копирует существующего бота как шаблон.
+
+```bash
+# Скопировать бота
+sbf copy my-bot my-bot-v2
+
+# Перезаписать существующего бота
+sbf copy my-bot my-bot-v2 --force
+```
+
+### `sbf rm <bot_id>`
+
+Удаляет бота и все его файлы.
+
+```bash
+# Удалить с подтверждением
+sbf rm my-bot
+
+# Удалить без подтверждения
+sbf rm my-bot --force
+```
+
+### `sbf link`
+
+Создает UTM-ссылки для бота.
+
+```bash
+sbf link
+```
+
+### `sbf path`
+
+Показывает путь к проекту.
+
+```bash
+sbf path
+```
+
+## 🏗️ Структура проекта
+
+```
+project/
+├── bots/
+│   └── my-bot/
+│       ├── .env                 # Конфигурация
+│       ├── prompts/             # Промпты
+│       │   ├── system_prompt.txt
+│       │   ├── welcome_message.txt
+│       │   └── final_instructions.txt
+│       ├── tests/               # Тесты
+│       │   └── scenario_examples.yaml
+│       ├── reports/             # Отчеты тестирования
+│       ├── welcome_files/       # Файлы для приветствия
+│       └── files/               # Дополнительные файлы
+├── my-bot.py                    # Файл запуска бота
+└── smart_bot_factory/           # Библиотека
+```
+
+## ⚙️ Конфигурация (.env)
+
+```env
+# Telegram
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+
+# Supabase
+SUPABASE_URL=https://your-project.supabase.co
+SUPABASE_KEY=your_supabase_anon_key
+
+# OpenAI
+OPENAI_API_KEY=sk-your-openai-api-key
+OPENAI_MODEL=gpt-4
+OPENAI_MAX_TOKENS=1500
+OPENAI_TEMPERATURE=0.7
+
+# Администраторы
+ADMIN_TELEGRAM_IDS=123456789,987654321
+ADMIN_SESSION_TIMEOUT_MINUTES=30
+
+# Настройки
+DEBUG_MODE=false
+MAX_CONTEXT_MESSAGES=50
+LOG_LEVEL=INFO
+MESSAGE_PARSE_MODE=Markdown
+```
+
+## 🧪 Тестирование
+
+### Формат тестов (YAML)
+
+```yaml
+scenarios:
+  - name: "Тест приветствия"
+    steps:
+      - user_input: "Привет!"
+        expected_keywords:
+          - ["привет", "здравствуйте", "добро пожаловать"]
+          - ["помочь", "помощь"]
+        forbidden_keywords: ["пока", "до свидания"]
+
+  - name: "Тест с синонимами"
+    steps:
+      - user_input: "Сколько это стоит?"
+        expected_keywords:
+          - ["стоит", "цена", "стоимость", "сколько"]
+          - ["рубл", "пакет", "вариант"]
+        forbidden_keywords: ["бесплатно"]
+```
+
+### Поддержка синонимов
+
+В `expected_keywords` можно использовать:
+- **Одно слово:** `["привет"]`
+- **Синонимы:** `[["привет", "здравствуйте", "добро пожаловать"]]`
+- **Смешанный формат:** `["привет", ["здравствуйте", "добро пожаловать"]]`
+
+## 🤖 Программирование ботов
+
+### Основной файл бота
+
+```python
+#!/usr/bin/env python3
+"""
+Бот my-bot - создан с помощью Smart Bot Factory
+"""
+
+import asyncio
+from smart_bot_factory.core import event_handler, send_message_by_human
+from smart_bot_factory.creation import BotBuilder
+
+# =============================================================================
+# ОБРАБОТЧИКИ СОБЫТИЙ
+# =============================================================================
+
+@event_handler("appointment_booking", "Записывает пользователя на прием")
+async def handle_appointment(user_id: int, event_data: dict):
+    """Обработчик записи на прием"""
+    await send_message_by_human(
+        user_id=user_id,
+        message_text="✅ Ваша запись на прием подтверждена!"
+    )
+    
+    return {
+        "status": "success",
+        "appointment_id": "123"
+    }
+
+# =============================================================================
+# ОСНОВНАЯ ФУНКЦИЯ
+# =============================================================================
+
+async def main():
+    """Основная функция запуска бота"""
+    try:
+        # Создаем и собираем бота
+        bot_builder = BotBuilder("my-bot")
+        await bot_builder.build()
+        
+        # Запускаем бота
+        await bot_builder.start()
+        
+    except Exception as e:
+        print(f"❌ Ошибка запуска бота: {e}")
+        raise
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Обработчики событий
+
+```python
+@event_handler("phone_collection", "Собирает номер телефона")
+async def collect_phone(user_id: int, event_data: dict):
+    """Сбор номера телефона"""
+    phone = event_data.get('phone')
+    # Логика сохранения номера
+    
+    return {
+        "status": "success",
+        "phone": phone
+    }
+```
+
+## 👑 Административная панель
+
+### Команды для админов
+
+- `/admin` - Вход в режим администратора
+- `/чаты` - Показать активные диалоги
+- `/чат <user_id>` - Начать диалог с пользователем
+- `/завершить` - Завершить текущий диалог
+- `/отладка <user_id>` - Отладочная информация
+
+### Живой чат
+
+Админы могут:
+- 💬 Вести диалоги с пользователями в реальном времени
+- 📊 Видеть историю сообщений
+- ⏰ Автоматическое завершение диалогов по таймауту
+- 🎛️ Управление через кнопки
+
+## 📊 Отчеты и аналитика
+
+### Тестирование
+
+- 📈 Детальные отчеты по каждому тесту
+- ⏱️ Время выполнения тестов
+- 📊 Статистика прохождения
+- 💾 Сохранение отчетов в `bots/my-bot/reports/`
+
+### Логирование
+
+```bash
+# Уровни логирования
+LOG_LEVEL=DEBUG    # Подробная отладка
+LOG_LEVEL=INFO     # Основная информация
+LOG_LEVEL=WARNING  # Только предупреждения
+LOG_LEVEL=ERROR    # Только ошибки
+```
+
+## 🔧 Расширенные возможности
+
+### UTM-трекинг
+
+```bash
+# Генерация UTM-ссылок
+sbf link
+```
+
+Поддерживаемые параметры:
+- `utm_source` - источник трафика
+- `utm_medium` - канал
+- `utm_campaign` - кампания
+- `utm_content` - контент
+- `utm_term` - ключевое слово
+
+### Файлы и медиа
+
+- 📁 `welcome_files/` - файлы для приветствия
+- 📎 `files/` - дополнительные файлы бота
+- 🖼️ Поддержка изображений, документов, видео
+
+### Кастомизация промптов
+
+```bash
+# Редактирование системного промпта
+sbf prompts my-bot --edit system_prompt
+
+# Создание нового промпта
+sbf prompts my-bot --add custom_instructions
+```
+
+## 🆘 Поддержка и помощь
+
+### Частые проблемы
+
+1. **Бот не запускается**
+   - Проверьте `.env` файл
+   - Убедитесь в правильности токенов
+   - Проверьте логи: `LOG_LEVEL=DEBUG`
+
+2. **Тесты не проходят**
+   - Проверьте формат YAML
+   - Используйте `-v` для подробного вывода
+   - Убедитесь в корректности ключевых слов
+
+3. **Админские функции не работают**
+   - Проверьте `ADMIN_TELEGRAM_IDS` в `.env`
+   - Убедитесь, что ID указан правильно
+   - Используйте `/admin` для входа в режим
+
+### Отладка
+
+```bash
+# Включить режим отладки
+DEBUG_MODE=true
+
+# Подробные логи
+LOG_LEVEL=DEBUG
+
+# Тестирование с подробным выводом
+sbf test my-bot -v
+```
+
+## 📚 Примеры
+
+### Полный цикл разработки
+
+```bash
+# 1. Создать бота
+sbf create sales-bot
+
+# 2. Настроить конфигурацию
+sbf config sales-bot
+
+# 3. Редактировать промпты
+sbf prompts sales-bot --edit system_prompt
+
+# 4. Создать тесты
+sbf prompts sales-bot --add test_scenarios
+
+# 5. Запустить тесты
+sbf test sales-bot -v
+
+# 6. Запустить бота
+sbf run sales-bot
+```
+
+### Копирование и модификация
+
+```bash
+# Скопировать успешного бота
+sbf copy sales-bot sales-bot-v2
+
+# Модифицировать копию
+sbf prompts sales-bot-v2 --edit system_prompt
+
+# Протестировать изменения
+sbf test sales-bot-v2
+
+# Запустить новую версию
+sbf run sales-bot-v2
+```
+
+---
+
+**Smart Bot Factory** - создавайте умных ботов быстро и эффективно! 🚀