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

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

Возможности

• 📚 Управление словарным запасом с автоматическим переводом через AI
• ✍️ Интерактивные задания на перевод слов с проверкой через AI
• 📊 Статистика прогресса и точность ответов
• 🔄 Умные повторения (spaced repetition)
• 💬 Диалоговая практика с ИИ (в разработке)

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

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

• ✅ /start - регистрация и приветствие пользователя
• ✅ /add [слово] - добавление слов в словарь с AI-переводом, транскрипцией и примерами
• ✅ /vocabulary - просмотр личного словаря (последние 10 слов)
• ✅ /task - интерактивные задания на перевод слов (EN→RU и RU→EN)
• ✅ /stats - детальная статистика обучения
• ✅ /help - справка по командам
• ✅ Проверка ответов через 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 - Начать работу с ботом
• /add [слово] - Добавить слово в словарь
• /vocabulary - Посмотреть свой словарь
• /help - Показать справку

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

1. Запустите бота: /start
2. Добавьте слово: /add elephant
3. Бот переведёт слово через AI и предложит добавить в словарь
4. Подтвердите добавление
5. Просмотрите словарь: /vocabulary

Roadmap

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

Следующие этапы:

• Ежедневные задания с разными типами упражнений
• Тематические подборки слов
• Импорт слов из текста
• Диалоговая практика с AI
• Статистика и прогресс
• Spaced repetition алгоритм

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