Telegram Бот для изучения языков

Интеллектуальный Telegram бот для изучения английского языка с использованием AI.

Возможности

• 🎯 Автоматический тест определения уровня (A1-C2)
• 📚 Управление словарным запасом с автоматическим переводом через AI
• 📖 Тематические подборки и извлечение слов из текстов
• ✍️ Интерактивные задания 3-х типов с проверкой через AI
• 💬 Диалоговая практика с ИИ в разных сценариях
• 📊 Статистика прогресса и точность ответов
• 🔄 Умные повторения (spaced repetition)
• ⏰ Ежедневные напоминания по расписанию
• ⚙️ Адаптивная сложность под твой уровень

Текущая версия (MVP)

Реализовано:

• ✅ /start - регистрация и приветствие пользователя
• ✅ /level_test - тест для определения уровня английского (7 вопросов, автоматическое определение A1-C2)
• ✅ /add [слово] - добавление слов в словарь с AI-переводом, транскрипцией и примерами
• ✅ /words [тема] - AI-генерация тематических подборок слов (travel, food, work и т.д.)
• ✅ /import - извлечение слов из текста с помощью AI (книги, статьи, тексты песен)
• ✅ /practice - диалоговая практика с AI (6 сценариев: ресторан, магазин, путешествие, работа, врач, общение)
• ✅ /vocabulary - просмотр личного словаря (последние 10 слов)
• ✅ /task - интерактивные задания 3-х типов:
  • Перевод EN→RU
  • Перевод RU→EN
  • Заполнение пропусков в предложениях
• ✅ /stats - детальная статистика обучения
• ✅ /settings - настройки пользователя (уровень A1-C2, язык интерфейса)
• ✅ /reminder - ежедневные напоминания о практике (настройка времени и включение/выключение)
• ✅ /help - справка по командам
• ✅ Проверка ответов через AI с детальной обратной связью
• ✅ AI-генерация предложений для практики в контексте
• ✅ Исправление ошибок в реальном времени во время диалога
• ✅ Автоматический тест уровня при первом запуске
• ✅ Отслеживание прогресса по каждому слову
• ✅ Автоматические ежедневные напоминания по расписанию
• ✅ База данных (PostgreSQL) для хранения данных
• ✅ Docker-развёртывание (полное и только БД)

Установка и запуск

🐳 Docker Compose (рекомендуется)

# Клонировать репозиторий
git clone http://103.137.249.134:3000/NANDI/tg_bot_language.git
cd tg_bot_language

# Настроить .env
cp .env.example .env
# Отредактируйте .env и добавьте BOT_TOKEN и OPENAI_API_KEY

# Запустить
docker-compose up -d

# Проверить логи
docker-compose logs -f bot

📖 Подробная инструкция: README_DOCKER.md

---

Локальная установка

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

# Клонировать репозиторий
git clone http://103.137.249.134:3000/NANDI/tg_bot_language.git
cd tg_bot_language

# Запустить скрипт установки
./setup.sh

# Отредактировать .env и добавить токены
nano .env

# Активировать виртуальное окружение
source .venv/bin/activate

# Запустить бота
python main.py

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

# Установить всё
make install

# Запустить бота
make run

# Показать все команды
make help

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

1. Клонирование репозитория

git clone http://103.137.249.134:3000/NANDI/tg_bot_language.git
cd tg_bot_language

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

python3 -m venv .venv
source .venv/bin/activate

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

pip install --upgrade pip
pip install -r requirements.txt

4. Настройка окружения

cp .env.example .env
nano .env  # или любой редактор

Заполните необходимые параметры:

BOT_TOKEN=your_telegram_bot_token_here
OPENAI_API_KEY=your_openai_api_key_here
DATABASE_URL=postgresql+asyncpg://botuser:botpassword@localhost:5432/language_bot
DEBUG=True

Получение токенов:

• Telegram Bot Token: создайте бота через @BotFather
• OpenAI API Key: получите на platform.openai.com

5. Настройка базы данных

Запустите PostgreSQL через Docker (рекомендуется):

# Через Makefile (рекомендуется)
make docker-db

# Или напрямую через docker-compose
docker-compose up -d db

# Или через отдельный dev-compose
docker-compose -f docker-compose.dev.yml up -d

Параметры подключения:

• Host: localhost
• Port: 15433 (не конфликтует с другими PostgreSQL)
• User: botuser
• Password: botpassword
• Database: language_bot
• URL: postgresql+asyncpg://botuser:botpassword@localhost:15433/language_bot

Или установите PostgreSQL локально:

# macOS
brew install postgresql
createdb language_bot

# Linux
sudo apt install postgresql
sudo -u postgres createdb language_bot

6. Запуск бота

# Активировать venv
source .venv/bin/activate

# Запустить
python main.py

# Или через Makefile
make run

Остановка БД:

make docker-db-stop
# или
docker-compose stop db

Структура проекта

bot_tg_language/
├── bot/
│   ├── handlers/          # Обработчики команд
│   │   ├── start.py       # /start, /help
│   │   └── vocabulary.py  # /add, /vocabulary
│   └── keyboards/         # Клавиатуры (пока не используется)
├── database/
│   ├── models.py          # Модели БД (User, Vocabulary, Task)
│   └── db.py              # Подключение к БД
├── services/
│   ├── ai_service.py      # Сервис для работы с OpenAI
│   ├── user_service.py    # Сервис пользователей
│   └── vocabulary_service.py  # Сервис словаря
├── config/
│   └── settings.py        # Настройки приложения
├── main.py                # Точка входа
├── requirements.txt       # Зависимости
├── .env.example          # Пример конфигурации
└── TZ.md                 # Техническое задание

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

Команды бота

• /start - Начать работу с ботом
• /level_test - Пройти тест определения уровня
• /add [слово] - Добавить слово в словарь
• /words [тема] - Получить тематическую подборку слов
• /import - Извлечь слова из текста
• /practice - Диалоговая практика с AI
• /vocabulary - Посмотреть свой словарь
• /task - Получить интерактивное задание
• /stats - Просмотреть статистику
• /settings - Настройки бота
• /reminder - Настроить ежедневные напоминания
• /help - Показать справку

Пример использования

1. Запустите бота: /start
2. Пройдите тест уровня (или пропустите)
3. Добавьте слово: /add elephant
4. Бот переведёт слово через AI и предложит добавить в словарь
5. Подтвердите добавление
6. Получите тематическую подборку: /words travel
7. Выберите слова для добавления из предложенного списка
8. Просмотрите словарь: /vocabulary
9. Выполните задание: /task
10. Настройте напоминания: /reminder и установите время (например, 09:00 UTC)

Тест определения уровня

При первом запуске бот предложит пройти тест:

• 7 вопросов разной сложности (A1 → C2)
• Автоматическое определение уровня по результатам
• 2-3 минуты на прохождение
• Можно пропустить и пройти позже: /level_test
• Или установить уровень вручную в /settings

Тест помогает подобрать задания и материалы под твой реальный уровень!

Настройка напоминаний

Команда /reminder позволяет настроить ежедневные напоминания:

• Установите время в формате HH:MM (UTC)
• Включите/выключите напоминания
• Бот будет отправлять напоминание каждый день в указанное время
• Важно: время указывается в UTC (МСК = UTC + 3)

Roadmap

См. TZ.md для полного технического задания.

MVP завершён! 🎉

Все основные функции реализованы:

• Ежедневные задания с разными типами упражнений
• Тематические подборки слов
• Импорт слов из текста
• Диалоговая практика с AI
• Статистика и прогресс
• Spaced repetition алгоритм (базовая версия)
• Напоминания и ежедневные задания по расписанию
• Убрать переводы текстов (скрыть перевод в упражнениях/диалогах/тестах)
• Добавлены английский и японский в локализацию интерфейса
• Добавлены языки для обучения
• Добавить возможность иметь словам несколько переводов
• Добавить возможность импорта слов из файлов (txt, md)
• Добавить импорт нескольких слов (bulk-импорт)
• Добавлена механика "Слова дня"
• Добавлена механика "Мини истории"

Следующие улучшения:

• Экспорт словаря (PDF, Anki, CSV)
• Голосовые сообщения для практики произношения
• Групповые челленджи и лидерборды
• Gamification (стрики, достижения, уровни)
• Расширенная аналитика с графиками
• Создание задач на выбранные слова (из словаря/подборок)
• Изменить словарь: оставить только слова и добавить возможность получать инфо о словах

Cloudflare AI Gateway (опционально)

Бот поддерживает использование Cloudflare AI Gateway для:

• 🚀 Кэширование запросов - экономия до 99% на повторных запросах
• 📊 Аналитика - детальная статистика использования AI
• 💰 Контроль расходов - мониторинг стоимости запросов
• 🛡️ Безопасность - защита API ключей и rate limiting

Настройка:

1. Создайте Gateway на dash.cloudflare.com → AI → AI Gateway
2. Добавьте в .env:

CLOUDFLARE_ACCOUNT_ID=ваш_account_id
CLOUDFLARE_GATEWAY_ID=gpt

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

Технологии

• Python 3.11+
• aiogram 3.x - Telegram Bot framework
• SQLAlchemy 2.x - ORM для работы с БД
• PostgreSQL - База данных
• OpenAI API - AI для перевода и проверки
• Cloudflare AI Gateway - кэширование и мониторинг AI запросов (опционально)

Лицензия

MIT