Skip to content

Latest commit

 

History

History
211 lines (161 loc) · 6.1 KB

README.md

File metadata and controls

211 lines (161 loc) · 6.1 KB

Lingooru

CI codecov

Python 3.13+ aiogram 3.x FastAPI Ruff uv mypy License: MIT

Telegram bot for language learning with spaced repetition, voice practice, and AI-powered feedback.

Features

Learning

  • Vocabulary Management - Add words manually or from curated word lists
  • Spaced Repetition (SM-2) - Anki-like algorithm for optimal memorization
  • Multi-language Support - English and Korean learning with Russian interface

Practice

  • Voice Pronunciation - Record voice messages, get AI feedback via OpenAI Whisper
  • Audio Playback - Listen to word pronunciations (gTTS with S3/MinIO caching)
  • Review Sessions - Track progress with quality ratings

Technical

  • aiogram 3.x - Modern async Telegram bot framework
  • FastAPI - REST API with async support
  • SQLAlchemy 2.0 - Async ORM with PostgreSQL
  • i18n - Localized interface (Russian, English, Korean)

Prerequisites

  • Python 3.13+
  • uv package manager
  • PostgreSQL 17+
  • Docker (for MinIO)

Quick Start

1. Setup Environment

# Clone and enter project
cd lingooru

# Create and activate virtual environment
uv venv && source .venv/bin/activate
uv sync --all-groups

2. Configure

# Copy example config
cp .env.example .env

# Edit with your credentials
$EDITOR .env

Required settings:

# Database
DB__HOST=localhost
DB__PORT=5432
DB__NAME=lingooru
DB__USERNAME=postgres
DB__PASSWORD=postgres

# Telegram
telegram__bot_token=YOUR_BOT_TOKEN

# OpenAI (for voice recognition)
openai__api_key=YOUR_OPENAI_KEY

# S3/MinIO (for audio caching)
S3__ENDPOINT_URL=http://localhost:9000
S3__ACCESS_KEY=minioadmin
S3__SECRET_KEY=minioadmin
S3__BUCKET_NAME=lingooru-audio

3. Start Services

# Start MinIO for audio storage
docker run -d \
  --name minio \
  -p 9000:9000 \
  -p 9001:9001 \
  -v ~/minio/data:/data \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  minio/minio server /data --console-address ":9001"

# Create bucket
docker exec minio mc alias set local http://localhost:9000 minioadmin minioadmin
docker exec minio mc mb local/lingooru-audio --ignore-existing
docker exec minio mc anonymous set download local/lingooru-audio

4. Run Migrations

uv run alembic upgrade head

5. Start Bot

# Run Telegram bot
make bot

# Or run API server
uv run uvicorn main:app --host 0.0.0.0 --port 8000

Bot Commands

The bot uses inline keyboards for navigation. Main features:

Button Description
📚 Учить Learn new words
🔄 Повторять Review due words (spaced repetition)
🎤 Произношение Practice pronunciation with voice
📋 Меню Main menu with stats

Learning Flow

  1. Add Words - From word lists or manually
  2. Learn - See word, translation, example; rate as Know/Hard/Forgot
  3. Review - Spaced repetition based on SM-2 algorithm
  4. Voice Practice - Record pronunciation, get AI feedback

Development

Code Quality

make              # Run all checks (fmt, lint, db, test)
make fmt          # Format code with ruff
make lint         # Lint with ruff and mypy (strict)
make test         # Run pytest with coverage
make db           # Validate migrations

Project Structure

src/
├── bot/                    # Telegram bot
│   ├── handlers/           # Message & callback handlers
│   ├── keyboards/          # Inline & reply keyboards
│   ├── locales/            # i18n translations (ru, en, ko)
│   └── middleware/         # User loading, i18n
├── modules/
│   ├── audio/              # TTS generation & S3 storage
│   ├── srs/                # Spaced repetition (SM-2)
│   ├── users/              # User management
│   ├── vocabulary/         # Words, translations, user dictionary
│   └── voice/              # Voice transcription & feedback
├── core/                   # API core (routes, middleware, DI)
├── db/                     # Database config & sessions
└── config.py               # Application settings

tests/
├── unit/                   # Unit tests
├── integration/            # API & database tests
└── conftest.py             # Shared fixtures

Adding Features

See CLAUDE.md for detailed development guidelines.

Testing

# Run all tests
make test

# Run by category
uv run pytest -k unit -v
uv run pytest -k integration -v

# Run specific module
uv run pytest tests/unit/modules/audio/ -v

Coverage requirements: 80% line, 70% branch.

Configuration

Variable Description Default
DB__* PostgreSQL connection localhost:5432
telegram__bot_token Telegram bot token -
openai__api_key OpenAI API key -
S3__ENDPOINT_URL MinIO/S3 endpoint http://localhost:9000
S3__ACCESS_KEY S3 access key -
S3__SECRET_KEY S3 secret key -
S3__BUCKET_NAME Audio bucket name lingooru-audio
LOGGING_LEVEL Log level INFO

License

MIT