Telegram Quiz Bot — LLM Mixed Trivia

Коротко: это квиз-бот для Telegram на любую тему, который сам генерирует темы, вопросы и объяснения с помощью AI.
Работает на реальных Telegram-опросах типа quiz (не кнопки), даёт 30 секунд на ответ и сам двигается дальше.

---

⚠️ Важное правило проекта

Это 100% вайбкоддинг.
Код, документация, CI/CD в этом репозитории написаны 99.9% с использованием GenAI. Запрещается писать не через вайбкоддинг. PR’ы с занудством, enterprise-ритуалами и «давайте созвонимся» — в /dev/null. Подтверждение вайбкоддинга обязательно.

---

Что умеет

• /start <тема> — квиз строго по указанной теме.
• /start — LLM придумает «смешанную» тему и план из 10 подтем.
• 10 вопросов с градиентом сложности: easy → medium → hard.
• Варианты перемешиваются — правильный не всегда «A».
• На вопрос даётся 30 секунд, затем бот печатает:
  • правильную букву (A/B/C/D),
  • короткое объяснение,
  • список игроков, ответивших верно,
  • и через 5 секунд задаёт следующий вопрос.
• Пул вопросов правдоподобный (не «шутки-ради»), с анти-повторами формулировок.
• Приз («бейджик») формируется LLM под текущую тему.
• /statistics — простая таблица по игрокам: призы, верные ответы, сыгранные квизы.
• Хранилище статистики — файл quiz_stats.json рядом с приложением.

---

Как это работает внутри

• Генерация: gpt-4o (по умолчанию), затем верификация правильного варианта отдельной моделью (gpt-4o-mini).
• Телеграм: настоящие Polls (type=quiz) с open_period=30.
• После тайм-аута бот сам печатает результат и двигается дальше — никаких кнопок «Время истекло».
• Корректная финализация после 10-го вопроса и идемпотентный учёт призов.

---

Переменные окружения

Обязательные:

• TELEGRAM_BOT_TOKEN — токен вашего бота
• OPENAI_TOKEN — API-ключ OpenAI

Необязательные:

• QUIZ_OPENAI_MODEL — модель генерации (по умолчанию gpt-4o)
• QUIZ_OPENAI_VERIFIER — модель верификации (по умолчанию gpt-4o-mini)
• PASS_THRESHOLD — сколько правильных из 10 нужно для приза (по умолчанию 7)

---

Запуск локально

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

export TELEGRAM_BOT_TOKEN=xxx
export OPENAI_TOKEN=yyy
# опционально:
export QUIZ_OPENAI_MODEL=gpt-4o
export QUIZ_OPENAI_VERIFIER=gpt-4o-mini
export PASS_THRESHOLD=7

python quiz_poll_bot_mixed_llm.py

---

Docker

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

TELEGRAM_BOT_TOKEN=xxx OPENAI_TOKEN=yyy \
docker compose up --build

docker-compose.yml уже ожидает переменные из окружения и запускает один сервис quizbot.

Пример .env (опционально):

TELEGRAM_BOT_TOKEN=xxx
OPENAI_TOKEN=yyy
QUIZ_OPENAI_MODEL=gpt-4o
QUIZ_OPENAI_VERIFIER=gpt-4o-mini
PASS_THRESHOLD=7

---

Обновление через CI/CD (GHCR → Portainer)

В репозитории есть GitHub Actions, которые:

• собирают образ и пушат в GHCR с тэгами latest, <branch>, <sha>;
• деплоят в Portainer: ищут стек по имени, при необходимости создают, при апдейте всегда делают pullImage=true, так что образ перетягивается даже при том же теге.

Требуемые secrets для деплоя:

• PORTAINER_BASEURL (пример: https://portainer.example.com:9443)
• PORTAINER_USER, PORTAINER_PASS
• STACK_NAME (имя стека)
• опц. PORTAINER_INSECURE=true для self-signed TLS

Если используете Docker Hub — поменяйте логин/push в workflow и image: в compose.

---

Команды бота

• /start — старт смешанной викторины
• /start <тема> — викторина по заданной теме
• /statistics — простая сводка по игрокам

---

Частые вопросы (FAQ)

Где хранятся результаты?

В файле quiz_stats.json в рабочей директории контейнера/процесса.
Хотите сохранять между рестартами — смонтируйте том и положите файл туда.

Почему иногда «никто не попал»?

Бот честно фиксирует ответы из PollAnswerHandler и печатает тех, кто выбрал правильный индекс после тайм-аута.

Сколько нужно правильных, чтобы взять приз?

По умолчанию 7 из 10 (см. PASS_THRESHOLD).

---

Вайбкоддинг манифест

Мы пишем, как чувствуем, и чувствуем, как пишем.
Никаких «сначала нарисуем диаграмму согласования диаграмм».
Если код читается и работает — значит, вайб совпал.
Любые правки без вайба — отклоняются с сообщением «перепиши через вайб».

---

Лицензия

Apache 2.0. Делайте с ботом что хотите (желательно — через вайбкоддинг).