GDZilla — Smart Telegram Bot for Homework Help

🚀 Ready-to-Use Bot

The bot is already deployed on Yandex Cloud and ready to use (after docker startup): https://t.me/gdz1lla_bot

Landing page: https://e-dyagin.sourcecraft.site/napoleon-gdz-case/

Napoleon is a Telegram bot that helps students solve homework assignments (GDZ) safely and with gamification elements. The bot combines automatic answer checking, hints, OCR for recognizing tasks from images, a points/rewards system, and built-in safety and moderation measures to minimize the risks of misuse.

Key Features

• Help solving tasks across school subjects (algebra, Russian language).
• Automatic answer verification (answer_checker).
• OCR support for photos of assignments (packages/ocr_client).
• Hints system (hints_service) with hint balance control.
• Gamification: points, levels, achievements, leaderboard (packages/gamification_service).
• Safety:
  • Content filtering and intent classification (intent_classifier).
  • Minimization of directly providing ready-made solutions — focus on help and explanation.
  • Logs and moderation capability.
• LLM integration via wrappers (packages/yagpt_client, packages/prompt_system).
• Configurable architecture — easy to set up for local development and Docker deployment.

Repository Structure (Main)

• apps/telegram_bot/ — Telegram bot code (handlers, keyboards, services, config).
  • main.py, run.py — entry points / startup.
  • config/settings.py — configuration (tokens, DB address, etc.).
• packages/ — modular logic: answer_checker, gamification_service, hints_service, ocr_client, etc.
• benchmark/ — question/answer sets and results for quality testing.
• src/ — frontend/static site (if used).
• Dockerfile, docker-compose.yml — environment for containerized deployment.
• requirements.txt — Python dependencies.

Requirements

• Python 3.10+ (check requirements.txt)
• Telegram Bot Token
• (Optional) DBMS (Postgres/MySQL) / SQLite for development
• Docker and docker-compose (for container deployment)

Quick Start (Local Development)

1. Clone the repository:

git clone ssh://ssh.sourcecraft.dev/e-dyagin/napoleon-gdz-case.git

2. Install dependencies:

python -m pip install -r requirements.txt

3. Create an environment file (.env) in the project root with the following variables:

# Yandex API
YC_FOLDER_ID=
YC_API_KEY=
YAGPT_MODEL=           # model name like 'yandexgpt'
YAGPT_TEMPERATURE=     # temperature from 0 to 1
YAGPT_MAX_TOKENS=      # max output tokens
MAX_MESSAGE_HISTORY=   # history length for model
TOKEN_BUDGET=          # max num tokens can be used in one api call

BOT_TOKEN=             # tg bot token
OCR_ENABLED=           # bool value
DEFAULT_OCR_PROVIDER=mock  # do not change this value

LOG_LEVEL=INFO         # log level
DATABASE_URL=          # url to your database

Or set the variables in apps/telegram_bot/config/settings.py.

4. Run the bot locally:

python -m apps.telegram_bot.run

(Alternative: python apps/telegram_bot/run.py)

5. Open the bot in Telegram and test it.

Quick Start (Docker)

1. Create/edit .env next to docker-compose.yml with the required values (TELEGRAM_BOT_TOKEN, etc.).
2. Run:

docker-compose up --build

3. Containers will start and the bot will begin listening for incoming messages.

Configuration and Setup

• Main settings are stored in apps/telegram_bot/config/settings.py. It is recommended to load sensitive data from environment variables.
• OCR: packages/ocr_client/providers.py — different providers are available; configured via env.
• Gamification modules are in packages/gamification_service/service.py — points and achievement rules can be customized.
• Answer checking: packages/answer_checker/service.py — rules and thresholds can be adjusted per subject.

How It Works (Brief Overview)

1. The user sends a text or photo of a task to the bot.
2. If it is a photo — OCR is triggered (packages/ocr_client) and task text is extracted.
3. The intent classifier determines the request type (solution, hint, check).
4. If needed, a hint or explanation is generated via the prompt system / LLM.
5. The response goes through answer_checker and is returned to the user.
6. The user earns points for the interaction; the bot updates progress in gamification_service and the database.

Response Rules and Safety

• By default, the bot avoids simply copying a ready-made solution without explanation: the focus is on methodology and steps.
• Built-in intent classification prevents abuse attempts (e.g., bulk retrieval of ready-made work).
• Content filtering and logging for subsequent moderation.
• If needed, response verbosity levels can be toggled in the config.

Testing and Benchmarks

• The benchmark/ folder contains example questions and reference answers.
• Use comparison/evaluation scripts based on benchmark/*/results.json to assess quality.
• Unit tests and integration tests can be added around packages/* modules.

Development

• Code is organized modularly — to add a new OCR provider, checker module, or gamification rule, add the corresponding module to packages/.
• It is recommended to run locally with virtualenv/venv.
• Code formatting and static analysis: use black, flake8 (add configs if needed).

Useful Files

• apps/telegram_bot/main.py — startup and initialization.
• apps/telegram_bot/run.py — main entry-point script for running.
• apps/telegram_bot/handlers/ — command/message handlers.
• packages/ocr_client/ — OCR integration.
• packages/answer_checker/ — answer verification logic.
• packages/gamification_service/ — points/achievements logic.
• benchmark/ — test sets.

Deployment

• Deployment via Docker Compose or Kubernetes is recommended.
• Configure environment variables in CI/CD and store secrets in a vault/secret store.
• Set up monitoring and logging (stdout/ELK, Sentry for errors).

FAQ

• Can the bot be used as a "cheat sheet"? The bot is designed to provide explanations and help understand the material, rather than simply giving out ready-made answers.
• How do I configure new subjects/rules? Add data sources and rules to packages/answer_checker and packages/prompt_system.