Telegram Chat Analyzer Bot

Бот для анализа и суммаризации истории Telegram чатов с использованием OpenRouter-compatible LLM API.

🚀 Быстрый старт за 5 минут →

Возможности

• 📊 Суммаризация переписок - получение краткого резюме обсуждений за любой период
• 💬 Свободные запросы - вопросы о содержании чатов ("о чем говорили?", "до чего договорились?")
• 🤖 Естественный язык - команды описываются обычным текстом, AI понимает ваши запросы
• 📅 Гибкие периоды - "за неделю", "вчера", "сегодня", "за последний час", "последние 1000 сообщений" или без указания периода
• 🔍 Умный поиск чатов - находит чаты даже при неточном совпадении названия
• 💾 Контекст запросов - запоминает последний чат и период для быстрых запросов
• 🔐 Доступ ко всем чатам - через Telethon получаем доступ ко всей вашей истории переписок
• 🤖 Гибкая модель LLM - настраивается через /setmodel, можно задать несколько моделей по приоритету
• 🔒 Безопасность - работает только для вас, все данные хранятся локально
• ⚡ Простота - runtime-переопределение URL/токена/модели через команды

Установка

Автоматическая установка (рекомендуется)

./setup.sh

Скрипт автоматически:

• Проверит наличие Python
• Создаст виртуальное окружение
• Установит все зависимости
• Предложит создать файл .env

Ручная установка

1. Убедитесь, что Python 3.8+ установлен:

python3 --version

Если Python не установлен, см. docs/INSTALL.md

2. Создайте виртуальное окружение:

python3 -m venv venv
source venv/bin/activate

3. Установите зависимости:

pip install -r requirements.txt

📖 Подробная инструкция по установке: docs/INSTALL.md

2. Получите необходимые API ключи

Telegram Bot Token

1. Найдите @BotFather в Telegram
2. Отправьте команду /newbot
3. Следуйте инструкциям и получите токен

Telethon API Credentials

1. Перейдите на https://my.telegram.org
2. Войдите с вашим номером телефона
3. Перейдите в "API development tools"
4. Создайте приложение и получите api_id и api_hash

OpenRouter API Key (опционально)

1. Перейдите на https://openrouter.ai/keys
2. Создайте API ключ для доступа к OpenRouter-compatible API
3. Ключ можно задать сразу в .env или позже через команду /settoken

Ваш Telegram User ID

1. Найдите @userinfobot в Telegram
2. Отправьте ему любое сообщение
3. Скопируйте ваш ID

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

Скопируйте env.example в .env:

cp env.example .env

Заполните значения в файле .env:

# Telegram
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_PHONE=+79991234567

# OpenRouter-compatible LLM API (опционально)
# Получите токен: https://openrouter.ai/keys
PRIMARY_LLM_URL=https://openrouter.ai/api/v1/chat/completions
PRIMARY_LLM_MODEL=meta-llama/llama-3.3-70b-instruct:free,qwen/qwen3-32b:free
PRIMARY_LLM_API_KEY=your_openrouter_api_key_here

# Или Yandex Cloud AliceAI
# folder_id указывается прямо в model, отдельная env-переменная не нужна
# PRIMARY_LLM_URL=https://ai.api.cloud.yandex.net/v1/chat/completions
# PRIMARY_LLM_MODEL=gpt://your_folder_id/aliceai-llm/latest
# PRIMARY_LLM_API_KEY=your_yandex_api_key_here

# Опциональный fallback
FALLBACK_LLM_URL=https://openrouter.ai/api/v1/chat/completions
FALLBACK_LLM_MODEL=openrouter/free
FALLBACK_LLM_TOKEN=

# Admin
ADMIN_USER_ID=your_telegram_user_id_here

Установите правильные права доступа:

chmod 600 .env

4. Запустите бота

Простой способ (с автоматической проверкой):

./start.sh

Скрипт автоматически проверит конфигурацию и запустит бота.

Ручной способ:

python bot.py

При первом запуске Telethon попросит вас авторизоваться:

1. Введите код подтверждения из Telegram
2. Если у вас включена двухфакторная аутентификация, введите пароль

После первого запуска сессия сохранится, и повторная авторизация не потребуется.

Настройка

Команды бота

• /start - приветствие и информация о боте
• /help - показать все доступные команды
• /context - показать текущий контекст (последний чат и период)
• /reset - сбросить контекст
• /llmconfig - показать текущие runtime-настройки LLM
• /limits [primary|fallback] - показать лимиты/квоты API ключа
• /seturl [primary|fallback] <url> - задать URL OpenAI-compatible endpoint
• /setmodel [primary|fallback] <model[,model2,...]> - задать одну или несколько моделей
• /settoken [primary|fallback] <token> - задать API ключ

Для Yandex Cloud достаточно задать:

• PRIMARY_LLM_URL=https://ai.api.cloud.yandex.net/v1/chat/completions
• PRIMARY_LLM_MODEL=gpt://<folder_id>/aliceai-llm/latest
• PRIMARY_LLM_API_KEY=<api_key>

Бот сам переключит заголовок авторизации на Authorization: Api-Key ... и возьмет x-folder-id из model URI. /limits для Yandex Cloud не поддерживается, так как у него нет OpenRouter-style endpoint .../key.

Команды /seturl, /setmodel, /settoken сохраняют изменения в .env, поэтому настройки сохраняются после перезапуска. Периодические расписания суммаризации сохраняются в локальной SQLite базе schedules.db. Логи пишутся в bot.log и llm_traffic.log с ротацией (LOG_* и LLM_TRAFFIC_LOG_* в .env).

Настройки в config.py и через чат

Значения по умолчанию можно изменить в config.py, а во время работы переопределять командами /seturl, /setmodel, /settoken:

# Количество сообщений для загрузки, если период не указан
DEFAULT_MESSAGES_LIMIT = 300

# Runtime LLM (OpenRouter-compatible)
DEFAULT_LLM_URL = "https://openrouter.ai/api/v1/chat/completions"
DEFAULT_LLM_MODEL = "meta-llama/llama-3.3-70b-instruct:free"
DEFAULT_LLM_TOKEN = os.getenv("PRIMARY_LLM_API_KEY", "")

Используемые модели

Бот использует primary + fallback runtime-модели для парсинга команд и анализа переписок. По умолчанию primary — meta-llama/llama-3.3-70b-instruct:free, fallback — openrouter/free. Изменение через /setmodel primary <model> и /setmodel fallback <model>.

Для primary и fallback можно задать список моделей через запятую:

/setmodel primary meta-llama/llama-3.3-70b-instruct:free,qwen/qwen3-32b:free
/setmodel fallback openrouter/free,deepseek/deepseek-chat-v3-0324:free

Логика выбора такая:

• внутри одной попытки бот перебирает модели по порядку без паузы
• если модель вернула 429 или некачественный ответ, бот сразу пробует следующую
• пауза применяется только после полного неуспешного прохода по всему списку
• затем бот повторяет тот же список моделей

Использование

После запуска бота найдите его в Telegram и отправьте /start.

📖 Полный список примеров в EXAMPLES.md

Основные примеры команд

Суммаризация

Суммаризируй что происходило в чате Работа за последние сутки

Сделай краткую выжимку из чата Проект за неделю

Что обсуждали вчера в личке с Иваном?

Что сегодня писали в чате Команда?

Покажи что было за последний час в чате Поддержка

Дай последние 500 сообщений из чата Разработка

Работа с контекстом

Суммаризируй чат Работа за неделю
# Бот анализирует и запоминает чат "Работа" и период "неделя"

О чем договорились?
# Бот использует тот же чат и период!

А какие следующие шаги?
# Снова тот же чат и период

Свободные запросы

О чем говорили в чате Проект на тему дедлайнов?

До чего договорились в чате Команда, какие следующие шаги?

Что писал Александр в чате Встречи?

Нечеткий поиск чатов

Найди чат "Замедл"
# Бот найдет "Замедление в такси-зоне" с 75% схожестью

Архитектура

1. Telegram Bot API (python-telegram-bot) - получение команд от пользователя
2. Telethon - доступ к истории всех чатов от вашего имени
3. OpenRouter-compatible API - доступ к LLM модели

Процесс обработки команды

1. Получение команды: Пользователь отправляет запрос боту на естественном языке
2. Парсинг: Бот отправляет текст в настроенную LLM-модель для парсинга команды
3. Извлечение структуры: AI возвращает JSON с названием чата, периодом и запросом
4. Контекст: Если чат/период не указаны, используется сохраненный контекст
5. Поиск чата: Telethon находит нужный чат (с нечетким поиском ~72% схожести)
6. Загрузка истории:
   • За N часов: "за последний час", "за последние 5 часов"
   • За N дней: "за неделю", "за 3 дня", "вчера"
   • Сегодня: "сегодня" (с начала суток)
   • Последние N сообщений: "последние 100 сообщений"
   • По умолчанию: последние 300 сообщений
7. Обработка: История + запрос отправляются в ту же LLM-модель для анализа
8. Анализ: AI анализирует переписку и генерирует ответ
9. Сохранение контекста: Чат и период сохраняются для следующих запросов
10. Результат: Бот отправляет ответ пользователю

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

Хранение данных

Файл .env:

• ✅ Содержит все API ключи и токены
• ✅ Автоматически исключен из git (.gitignore)
• ✅ Рекомендуется установить права доступа: chmod 600 .env
• 📌 Это стандартная практика для хранения конфигурации

Telethon сессия:

• ✅ Файл telethon_session.session сохраняет авторизацию
• ✅ Избавляет от необходимости вводить код при каждом запуске
• ✅ Данные зашифрованы и безопасны
• ✅ Автоматически исключен из git
• 📌 Рекомендуется установить права доступа: chmod 600 *.session

Доступ к боту

• ✅ Бот работает только с одним пользователем (проверка ADMIN_USER_ID)
• ✅ Даже если кто-то узнает токен бота, он не сможет его использовать
• ⚠️ Не делитесь своими API ключами и токенами

Рекомендации

1. После создания .env файла выполните: chmod 600 .env
2. После первого запуска выполните: chmod 600 *.session
3. Регулярно обновляйте зависимости: pip install -U -r requirements.txt
4. Храните резервные копии .env в безопасном месте

Требования

• Python 3.11 - 3.13 (рекомендуется 3.11 или 3.12)
• Активный Telegram аккаунт
• OpenRouter API ключ (опционально, можно задать через /settoken)

Примечание: Python 3.14 пока не поддерживается из-за несовместимости библиотек.

Лицензия

MIT

Troubleshooting

Если возникли проблемы, проверьте:

1. 📖 docs/FAQ.md - часто задаваемые вопросы и решения
2. Логи бота в консоли на наличие ошибок
3. Все ли переменные окружения заполнены в .env (бот проверяет это при запуске)

Поддержка

Если ваша проблема не решена:

1. Проверьте docs/FAQ.md
2. Проверьте docs/EXAMPLES.md для примеров использования
3. Создайте Issue в репозитории с описанием проблемы и логами