tg_bot_language/README.md

# 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 (рекомендуется)

```bash
# Клонировать репозиторий
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](README_DOCKER.md)

---

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

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

```bash
# Клонировать репозиторий
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

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

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

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

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

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

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

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

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

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

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

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

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

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

```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](https://t.me/BotFather)
- OpenAI API Key: получите на [platform.openai.com](https://platform.openai.com/api-keys)

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

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

```bash
# Через 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 локально:

```bash
# macOS
brew install postgresql
createdb language_bot

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

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

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

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

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

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

```bash
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](TZ.md) для полного технического задания.

**MVP завершён! 🎉**

Все основные функции реализованы:
- [x] Ежедневные задания с разными типами упражнений
- [x] Тематические подборки слов
- [x] Импорт слов из текста
- [x] Диалоговая практика с AI
- [x] Статистика и прогресс
- [x] Spaced repetition алгоритм (базовая версия)
- [x] Напоминания и ежедневные задания по расписанию
- [x] Убрать переводы текстов (скрыть перевод в упражнениях/диалогах/тестах)

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

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

Бот поддерживает использование [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) для:

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

**Настройка:**

1. Создайте Gateway на [dash.cloudflare.com](https://dash.cloudflare.com/) → AI → AI Gateway
2. Добавьте в `.env`:
```env
CLOUDFLARE_ACCOUNT_ID=ваш_account_id
CLOUDFLARE_GATEWAY_ID=gpt
```

📖 Подробная инструкция: [docs/CLOUDFLARE_GATEWAY.md](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