smart-bot-factory 0.1.5

Библиотека для создания умных чат-ботов

Smart Bot Factory

Инструмент для создания умных чат-ботов с поддержкой AI, административной панели и тестирования.

🚀 Быстрый старт

Установка

pip install smart-bot-factory

Создание первого бота

# Создать нового бота
sbf create my-bot

# Запустить бота
sbf run my-bot

📋 Команды CLI

sbf create <bot_id> [template]

Создает нового бота с указанным ID.

# Создать бота с базовым шаблоном
sbf create my-bot

# Создать бота на основе существующего
sbf create new-bot existing-bot

Что создается:

• 📁 bots/my-bot/ - папка с конфигурацией бота
• 📄 my-bot.py - файл для запуска бота
• ⚙️ .env - файл конфигурации
• 📝 Промпты, тесты, файлы из шаблона

sbf run <bot_id>

Запускает бота в рабочем режиме.

sbf run my-bot

Автоматически:

• ✅ Проверяет наличие всех необходимых файлов
• ⚙️ Загружает конфигурацию из .env
• 🚀 Запускает бота

sbf test <bot_id> [options]

Запускает тесты бота.

# Все тесты
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

Показывает список всех доступных ботов.

sbf list

sbf config <bot_id>

Открывает конфигурацию бота в редакторе.

sbf config my-bot

sbf prompts <bot_id> [options]

Управление промптами бота.

# Показать список промптов
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>

Копирует существующего бота как шаблон.

# Скопировать бота
sbf copy my-bot my-bot-v2

# Перезаписать существующего бота
sbf copy my-bot my-bot-v2 --force

sbf rm <bot_id>

Удаляет бота и все его файлы.

# Удалить с подтверждением
sbf rm my-bot

# Удалить без подтверждения
sbf rm my-bot --force

sbf link

Создает UTM-ссылки для бота.

sbf link

sbf path

Показывает путь к проекту.

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)

# 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)

scenarios:
  - name: "Тест приветствия"
    steps:
      - user_input: "Привет!"
        expected_keywords:
          - ["привет", "здравствуйте", "добро пожаловать"]
          - ["помочь", "помощь"]
        forbidden_keywords: ["пока", "до свидания"]

  - name: "Тест с синонимами"
    steps:
      - user_input: "Сколько это стоит?"
        expected_keywords:
          - ["стоит", "цена", "стоимость", "сколько"]
          - ["рубл", "пакет", "вариант"]
        forbidden_keywords: ["бесплатно"]

Поддержка синонимов

В expected_keywords можно использовать:

• Одно слово: ["привет"]
• Синонимы: [["привет", "здравствуйте", "добро пожаловать"]]
• Смешанный формат: ["привет", ["здравствуйте", "добро пожаловать"]]

🤖 Программирование ботов

Основной файл бота

#!/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())

Обработчики событий

@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/

Логирование

# Уровни логирования
LOG_LEVEL=DEBUG    # Подробная отладка
LOG_LEVEL=INFO     # Основная информация
LOG_LEVEL=WARNING  # Только предупреждения
LOG_LEVEL=ERROR    # Только ошибки

🔧 Расширенные возможности

UTM-трекинг

# Генерация UTM-ссылок
sbf link

Поддерживаемые параметры:

• utm_source - источник трафика
• utm_medium - канал
• utm_campaign - кампания
• utm_content - контент
• utm_term - ключевое слово

Файлы и медиа

• 📁 welcome_files/ - файлы для приветствия
• 📎 files/ - дополнительные файлы бота
• 🖼️ Поддержка изображений, документов, видео

Кастомизация промптов

# Редактирование системного промпта
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 для входа в режим

Отладка

# Включить режим отладки
DEBUG_MODE=true

# Подробные логи
LOG_LEVEL=DEBUG

# Тестирование с подробным выводом
sbf test my-bot -v

📚 Примеры

Полный цикл разработки

# 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

Копирование и модификация

# Скопировать успешного бота
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 - создавайте умных ботов быстро и эффективно! 🚀