🤖 Telegram Bot Skeleton

Мультимодальный Telegram бот с поддержкой текста, голоса и изображений.

🌟 Возможности

• Текстовая обработка: общение через LLM (OpenRouter)
• Голосовые сообщения: распознавание речи (STT) и синтез речи (TTS)
• Работа с изображениями:
  • Анализ и описание изображений
  • Генерация изображений по текстовому описанию
• Модульная архитектура: легко расширяемая структура

🏗️ Архитектура

telegram-bot-skeleton/
├── backend/
│   ├── api/                    # API модули
│   │   ├── routes.py           # Основные маршруты
│   │   ├── telegram_core.py    # Telegram интеграция
│   │   ├── telegram_polling.py # Polling система
│   │   ├── telegram_vision.py  # Обработка изображений
│   │   └── telegram_voice.py   # Обработка голоса
│   ├── core/                   # Ядро системы
│   ├── llm/                    # LLM интеграция
│   │   └── openrouter.py       # OpenRouter клиент
│   ├── memory/                 # Система памяти (опционально)
│   ├── voice/                  # Голосовые функции
│   │   ├── tts.py              # Text-to-Speech
│   │   └── stt.py              # Speech-to-Text
│   ├── vision/                 # Обработка изображений
│   │   ├── image_generator.py  # Генерация изображений
│   │   └── image_analyzer.py   # Анализ изображений
│   ├── utils/                  # Утилиты
│   ├── config.py               # Конфигурация
│   └── main.py                 # Точка входа
├── frontend/                   # Веб-интерфейс (опционально)
├── data/                       # Данные
├── logs/                       # Логи
├── temp/                       # Временные файлы
├── requirements.txt            # Зависимости
└── .env.example               # Пример конфигурации

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

1. Установка зависимостей

pip install -r requirements.txt

2. Настройка переменных окружения

Скопируйте .env.example в .env и заполните необходимые ключи:

cp .env.example .env

Отредактируйте .env:

OPENROUTER_API_KEY=your_openrouter_api_key
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

3. Запуск

cd backend
python main.py

Или из корня проекта:

python -m backend.main

📡 API Эндпоинты

Основные

• POST /api/message - Отправка текстового сообщения
• POST /api/image/generate - Генерация изображения
• GET /health - Проверка здоровья системы

🎯 Telegram команды

• /generate [описание] или /рисунок [описание] - Генерация изображения
• Отправка текста - обычный диалог с ботом
• Отправка фото - анализ изображения
• Отправка голосового сообщения - распознавание речи

🔧 Настройка

LLM модели

В backend/config.py можно настроить модели:

LLM_CONFIG = {
    "model": "openai/gpt-oss-20b:free",
    "fallback_model": "deepseek/deepseek-chat-v3.1:free",
    "temperature": 0.7,
    "max_tokens": 4096,
}

Генерация изображений

Поддерживаются два провайдера:

• Pollinations.ai (бесплатно, по умолчанию)
• Hugging Face (требует API ключ)

Голосовые функции

• TTS: gTTS (бесплатно) или ElevenLabs (высокое качество)
• STT: SpeechRecognition (Google) или Whisper (локально)

📝 Разработка

Проект следует модульной архитектуре:

1. Модули разделены по функциональности
2. Каждый модуль имеет четкую ответственность
3. Легко добавлять новые функции

Добавление новой функции

1. Создайте модуль в соответствующей папке
2. Импортируйте в telegram_polling.py или routes.py
3. Добавьте обработку в process_message()

🔐 Безопасность

• Все API ключи хранятся в .env файле
• .env должен быть в .gitignore
• Никогда не коммитьте реальные ключи

📚 Зависимости

Основные библиотеки:

• fastapi - веб-фреймворк
• aiohttp - асинхронные HTTP запросы
• openai - интеграция с OpenAI API
• gtts / SpeechRecognition - голосовые функции
• Pillow - обработка изображений

🐛 Устранение неполадок

Бот не отвечает

• Проверьте TELEGRAM_BOT_TOKEN в .env
• Убедитесь, что бот запущен
• Проверьте логи в logs/bot.log

Ошибки генерации изображений

• Pollinations работает без ключа
• Для Hugging Face нужен HF_API_KEY

Проблемы с голосом

• Установите librosa и soundfile для конвертации аудио
• Для Whisper установите openai-whisper

📄 Лицензия

MIT

---

Создано на основе архитектуры IKAR-ASSISTANT