tgimguard — анти-спам бот по тексту с картинок в Telegram

Бот для групп/супергрупп: извлекает текст с изображений через OpenAI и проверяет на наличие запрещённого текста. Если текст содержит запрещённые строки, то удаляет сообщение, банит отправителя и уведомляет владельца чата.

Возможности

• OCR через OpenAI: извлечение видимого текста из изображений
• Фильтрация по правилам: поддержка простых строк и регулярных выражений
• Автодействия: удаление сообщения, бан пользователя, уведомление владельца чата
• Безопасность и логгирование: ротация логов в logs/tgimguard.log

Требования

• Python: >= 3.12
• Telegram Bot Token
• OpenAI API Key (или совместимый API, если меняете OPENAI_BASE_URL)

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

1. Создайте конфиг на основе примера: env.example -> .env
2. Заполните .env: как минимум TELEGRAM_BOT_TOKEN, OPENAI_BASE_URL и OPENAI_API_KEY
3. Установите зависимости с использованием uv:

uv sync

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

uv run main.py

5. Добавьте бота в группу и выдайте ему права администратора (удаление сообщений, бан пользователей).
6. Владелец группы должен запустить бота (/start), чтобы бот мог уведомлять его о спаме.

Переменные окружения (.env)

• TELEGRAM_BOT_TOKEN — токен бота (обязательно)
• OPENAI_API_KEY — ключ OpenAI (обязательно)
• OPENAI_BASE_URL — базовый URL API (по умолчанию https://api.openai.com/v1)
• OPENAI_MODEL_ID — модель, по умолчанию gpt-4o-mini

Правила фильтрации

Правила фильтрации определены в YAML-файлах в каталоге rules/. Каждый файл *.yaml — это одно правило.

Структура правила:

name: название правила
min_matches: 2
patterns:
  - type: literal
    value: строка для поиска
  - type: regex
    value: регулярное выражение

Параметры:

• name — человекочитаемое название правила (опционально)
• min_matches — минимальное количество уникальных паттернов, которые должны совпасть, чтобы правило сработало
• patterns — массив паттернов для проверки:
  • type: literal — простая подстрока, поиск без учёта регистра
  • type: regex — регулярное выражение Python (флаги через inline, например (?i))

Логика срабатывания:
Правило срабатывает, если в тексте найдено ≥ min_matches уникальных паттернов.

Примеры:

Простое правило (1 паттерн):

name: buy now spam
min_matches: 1
patterns:
  - type: literal
    value: buy now

Комбинированное правило (несколько паттернов):

name: водительские права
min_matches: 2
patterns:
  - type: literal
    value: водительск
  - type: literal
    value: прав
  - type: literal
    value: удостоверение

В этом примере правило сработает, если найдены хотя бы 2 из 3 слов.

• IMAGE_COMPRESSION_THRESHOLD_KB — порог размера, выше которого изображение ресайзится и преобразуются в JPEG
• IMAGE_RESIZE_WIDTH_PX — ширина в пикселях при ресайзе
• CHAT_OWNER_ID — ID владельца чата для уведомлений (опционально, иначе автоопределение)

Как это работает

1. Пользователь отправляет изображение в групповой чат
2. Бот скачивает файл, при необходимости сжимает/ресайзит
3. Отправляет в OpenAI и получает извлечённый с изображения текст
4. Проверяет текст на соответствие любому правилу из rules/
5. При совпадении: удаляет сообщение, банит отправителя, уведомляет владельца группы

Логи

• Файл: logs/tgimguard.log (суточная ротация, хранение 30 дней)

Примечания

• Бот реагирует только в чатах типов group и supergroup
• Для корректной работы нужны права: удаление сообщений и бан пользователей
• Чем проще и короче список правил, тем меньше ложных срабатываний