Подробности есть в описании архитектуры и структуре проекта.

Технологии

Быстрый запуск

Понадобятся Git, Docker с Docker Compose, Telegram bot token и ключ OpenRouter либо доступ к LiteLLM-compatible proxy.

1. Подготовьте окружение

git clone https://github.com/akiamuradev/evolution-tutor-bot.git
cd evolution-tutor-bot
cp .env.example .env

Для PowerShell:

Copy-Item .env.example .env

Заполните в .env как минимум:

TG_BOT_TOKEN=your-telegram-bot-token
BOT_USERNAME=@your_bot_username

OPENROUTER_API_KEY=your-openrouter-api-key

POSTGRES_USER=tutor_user
POSTGRES_PASSWORD=choose-a-password
POSTGRES_DB=tutor_db
DATABASE_URL=postgresql://tutor_user:choose-a-password@postgres:5432/tutor_db

WEB_API_PORT=8080

Для прямой работы с OpenRouter удалите или закомментируйте LITELLM_BASE_URL и LITELLM_API_KEY. Если они заданы, приложение считает LiteLLM основным провайдером. Сам LiteLLM в docker-compose.yml не запускается.

2. Запустите backend

docker compose up -d --build
docker compose ps

Будут запущены три сервиса:

• tutor-bot — Telegram polling;
• tutor-api — HTTP API на порту 8080;
• postgres — PostgreSQL с постоянным volume postgres_data.

Проверка API:

curl http://localhost:8080/health

Логи:

docker compose logs -f --tail=100 tutor-bot tutor-api

Остановка:

docker compose down

3. Запустите VK Mini App

cd frontend/vk-mini-app
npm ci
npm run dev

Vite откроет приложение на http://localhost:5173. В режиме разработки запросы /api проксируются на http://localhost:8080.

Для внешнего API создайте frontend/vk-mini-app/.env:

VITE_API_BASE_URL=https://api.example.com

HTTP API

VK-запросы могут авторизовываться через подписанные launch params. Для локальной разработки поведение настраивается переменными WEB_API_ALLOW_UNSIGNED_VK_LAUNCH и WEB_API_ALLOW_INSECURE_USER_ID.

Учебные данные

Docker создаёт структуру базы, но публичный репозиторий не содержит production dump с готовым банком заданий. Практика и RAG требуют заполненных таблиц subjects и fipi_tasks.

Инструменты загрузки и обслуживания данных находятся в:

• backend/src/parsers/;
• backend/src/download_fipi_tasks.py;
• backend/src/load_full_fipi_base.py;
• tools/fipi/ и tools/db/.

Перед production-использованием загрузчики следует проверить на соответствие актуальной схеме и правилам источников данных.

Структура репозитория

.
├── backend/
│   ├── database/          # начальная SQL-схема
│   └── src/
│       ├── api/           # HTTP handlers
│       ├── modules/       # AI, память, лимиты, TutorEngine
│       ├── rag/           # поиск по учебным заданиям
│       ├── routers/       # Telegram-сценарии
│       └── parsers/       # загрузка учебных данных
├── frontend/
│   └── vk-mini-app/       # React/Vite приложение
├── docs/                  # архитектура и конфигурация Nginx
├── tools/                 # служебные скрипты
├── docker-compose.yml
└── .github/workflows/ci.yml

Проверки качества

Backend compile check:

python -m compileall -q backend/src

Frontend build:

cd frontend/vk-mini-app
npm ci
npm run build

Эти проверки выполняются в GitHub Actions при push в main и в pull request. Отдельного набора unit/integration-тестов в текущей версии репозитория нет.

Ограничения текущей версии

• Для practice и RAG нужен отдельно подготовленный банк учебных заданий.
• Используется текстовый и метаданный поиск с локальным reranking; полноценный embedding search не подключён.
• VK Mini App запускается отдельно от backend-контейнеров.
• Перед публичным production-запуском необходимо запретить небезопасные dev-флаги авторизации, ограничить CORS и настроить HTTPS/reverse proxy.

Лицензия

Проект распространяется по лицензии MIT.

English

TL;DR

• EVO:LUTION Tutor Bot is an AI tutor for Telegram and VK Mini App, not a thin chat-model wrapper.
• A shared TutorEngine combines LLM calls, student memory, task-based RAG, progress tracking and achievements.
• The system uses an async Python/aiohttp/PostgreSQL backend and a React/Vite/VK Bridge frontend.
• Docker Compose and GitHub Actions are included; the public repository does not contain a production task dump or a dedicated test suite.

About

EVO:LUTION Tutor Bot is a multi-platform educational assistant for students. Users can ask study questions, work through practice tasks and review their progress in Telegram or a VK Mini App. Both clients rely on the same backend tutoring core.

The repository goes beyond basic LLM integration. It includes an asynchronous Telegram layer, an aiohttp API, PostgreSQL persistence, dialog memory, task-based retrieval, model routing, anti-spam controls, AI concurrency limits and a separate React interface.

Key Features

• Telegram onboarding, tutoring chat, practice flows, statistics, activity tracking and achievements.
• VK Mini App with chat, practice, achievements and profile sections.
• Shared TutorEngine for Telegram and HTTP API clients.
• OpenRouter-compatible LLM integration with optional LiteLLM proxy support.
• Fast, standard and reasoning model routing based on request complexity.
• Fallback models, reduced-token retries and an in-memory response cache.
• Dialog history, searchable memory and a long-term learning profile.
• RAG over a PostgreSQL task bank using query analysis, metadata search and local reranking.
• Anti-spam rules, global request limits and per-user generation control.
• Function graph generation with SymPy, NumPy and Matplotlib.

Architecture

flowchart LR
    TG["Telegram Bot<br/>aiogram"] --> ENGINE["TutorEngine<br/>shared tutoring core"]
    VK["VK Mini App<br/>React + VK Bridge"] --> API["HTTP API<br/>aiohttp"]
    API --> ENGINE
    ENGINE --> MEMORY["Dialog memory<br/>history + profile"]
    ENGINE --> RAG["Task-based RAG<br/>search + reranking"]
    ENGINE --> GATEWAY["AI Gateway<br/>limits + model routing"]
    MEMORY --> DB[("PostgreSQL<br/>users and progress")]
    RAG --> DB
    GATEWAY --> LLM["OpenRouter / LiteLLM"]

See architecture details and the project structure guide.

Technology Stack