tg_bot_language/README.md

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

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

Возможности

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

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

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

• ✅ Команда /start - приветствие и регистрация пользователя
• ✅ Команда /add [слово] - добавление слов в словарь с AI-переводом
• ✅ Команда /vocabulary - просмотр словаря
• ✅ Команда /help - справка
• ✅ База данных (PostgreSQL) для хранения пользователей и словарей
• ✅ Интеграция с OpenAI API для перевода слов

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

🐳 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 алгоритм

Технологии

• Python 3.11+
• aiogram 3.x - Telegram Bot framework
• SQLAlchemy 2.x - ORM для работы с БД
• PostgreSQL - База данных
• OpenAI API - AI для перевода и проверки

Лицензия

MIT