Words - Language Learning Telegram Bot

Telegram-бот для изучения иностранных слов с адаптивными уроками, интервальным повторением и проверкой ответов (exact/fuzzy/LLM).

Features

• Регистрация пользователя и языковых профилей (родной/изучаемый язык, уровень CEFR).
• Добавление слов с автопереводом и примерами через LLM + кэш.
• При ➕ Add Word (если у пользователя несколько языков) сначала выбирается язык, после чего слово добавляется только для выбранной языковой пары (изучаемый↔родной).
• Показ транскрипции слова при добавлении и в вопросах урока для иностранного слова (если доступна).
• При автодобавлении новых слов в урок перед первым вопросом показывается отдельное объяснение для каждого нового слова (перевод и примеры).
• Уроки с двумя форматами: multiple_choice и input.
• Адаптивный подбор слов:
  • spaced repetition (next_review_at, easiness_factor)
  • приоритизация просроченных и сложных слов
  • прогресс статуса new -> learning -> reviewing -> mastered
• Статистика по словарю и урокам (📊 Statistics).
• Настройки в боте (⚙️ Settings):
  • включение/выключение уведомлений
  • переключение активного языкового профиля
  • смена уровня CEFR для активного профиля
• Фоновые push-уведомления через APScheduler.
• Логирование в консоль и файл с ротацией.

Requirements

• Python 3.10+
• Linux + systemd (для режима сервиса)
• Telegram bot token
• LLM API key

Installation

cd /opt/projects/words
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Создай .env на основе .env.example и заполни обязательные параметры:

• TELEGRAM_BOT_TOKEN
• LLM_API_KEY
• DATABASE_URL (по умолчанию SQLite)

Инициализация БД:

python scripts/init_db.py

Рекомендуется: загрузка частотных словарей (дистракторы для multiple choice, автодобавление слов в уроки при нехватке пользовательского словаря).

Файлы в data/frequency_lists/ должны быть упорядочены по частотности (самые частые — первыми), а не по алфавиту. Если файлы были алфавитными, сначала переупорядочь:

# Переупорядочить по частотности (для en подтягивается эталон Wiktionary)
python scripts/reorder_frequency_lists.py --language en

# Загрузить новые слова и при необходимости обновить ранги уже загруженных
python scripts/load_frequency_words.py
python scripts/load_frequency_words.py --update-ranks   # если слова уже в БД

После загрузки словарей слова не имеют переводов. Для предзаполнения переводов через LLM запусти скрипт перевода (рекомендуется запускать в фоне):

# Авто-определение языковых пар из профилей пользователей
python scripts/translate_frequency_words.py

# Конкретная пара языков
python scripts/translate_frequency_words.py --source en --target ru --limit 500

# Посмотреть что будет переводиться без реальных запросов
python scripts/translate_frequency_words.py --dry-run

Без предзаполнения переводы запрашиваются у LLM on-demand при первом показе слова в уроке (~3 сек/слово единоразово), после чего кешируются в БД.

Run (Foreground)

python -m src.words

Run As Systemd Service

Быстрая установка сервиса:

sudo ./install_service.sh
sudo systemctl start words-bot
sudo systemctl status words-bot

Управление сервисом:

./manage_service.sh status
sudo ./manage_service.sh restart
./manage_service.sh logs
./manage_service.sh logs-live
sudo ./manage_service.sh enable
sudo ./manage_service.sh disable

Сервисные файлы:

• words-bot.service
• install_service.sh
• manage_service.sh

Подробности: README_SERVICE.md.

Testing

Запуск всех тестов:

venv/bin/pytest tests -q

Запуск отдельных блоков:

venv/bin/pytest tests/services -q
venv/bin/pytest tests/bot -q
venv/bin/pytest tests/infrastructure -q

Project Structure

/opt/projects/words/
├── src/words/               # Приложение
│   ├── algorithm/           # Adaptive algorithm (SR, selector, difficulty)
│   ├── bot/                 # Telegram handlers/keyboards/states
│   ├── config/              # Settings/constants
│   ├── infrastructure/      # DB, LLM client, scheduler
│   ├── models/              # ORM models
│   ├── repositories/        # Data access layer
│   ├── services/            # Business logic
│   └── utils/               # Logger/string utils
├── scripts/                 # init_db, load_frequency_words, translate_frequency_words
├── data/frequency_lists/    # Частотные словари
├── docs/                    # Архитектура и техдоки
└── tests/                   # Тесты

Documentation

• docs/requirements.md
• docs/architecture.md
• docs/database_guidelines.md
• README_SERVICE.md

Development Notes

• Основные dev-инструкции: AGENTS.md.
• Текущая реализация ориентирована на async SQLAlchemy и aiogram 3.x.

Архитектурные заметки

On-demand перевод слов из частотных списков:
Слова из частотных списков загружаются без переводов (translations={}). При первом показе слова в уроке LessonService._ensure_word_translations() автоматически запрашивает перевод у LLM и сохраняет его в Word.translations. Для предзаполнения батчами используй scripts/translate_frequency_words.py.

Fallback multiple-choice → input:
Если для слова нет перевода (или переводов-дистракторов меньше 2), вопрос автоматически переключается с multiple_choice на input.

Направления перевода:
Каждый вопрос генерируется случайно в одном из двух направлений: родной→изучаемый (native_to_foreign) или изучаемый→родной (foreign_to_native). Статистика ведётся отдельно по каждому направлению.

License

TBD