132 lines
7.1 KiB
Markdown
132 lines
7.1 KiB
Markdown
# greek_lang
|
||
|
||
Проект для изучения греческого языка: перевод слов между языками (греческий, русский, английский) с помощью OpenAI, сохранение в базе данных (PostgreSQL) вместе с транскрипцией, описанием, примерами, категорией и аудио‑произношением (генерация через Google TTS). Также включает телеграм‑бота (aiogram) с хранением состояния в Redis.
|
||
|
||
## Возможности
|
||
- Перевод слова между языками ru/en/el (ISO‑639‑1) через OpenAI.
|
||
- Автогенерация и сохранение:
|
||
- леммы, транскрипции (IPA), перевода, описания;
|
||
- части речи, семантической категории, примера и его перевода;
|
||
- краткой этимологии;
|
||
- аудио‑файла произношения (aiogTTS).
|
||
- Сохранение результатов в PostgreSQL (SQLAlchemy + Alembic миграции).
|
||
- Телеграм‑бот на aiogram с Redis FSM‑хранилищем.
|
||
- Конфигурация через .env и pydantic‑settings; инициализация зависимостей через dependency_injector.
|
||
|
||
## Требования
|
||
- Python 3.13+
|
||
- PostgreSQL 14+
|
||
- Redis 6+
|
||
- OpenAI API ключ
|
||
|
||
Рекомендуется менеджер зависимостей uv и утилита go-task (для Taskfile.yml).
|
||
|
||
## Установка
|
||
1. Клонируйте репозиторий:
|
||
git clone <repo-url>
|
||
cd greek_lang
|
||
|
||
2. Установите зависимости (через uv):
|
||
- Обновить/синхронизировать зависимости: uv sync
|
||
- Обновить lockfile: uv lock --upgrade && uv sync
|
||
|
||
3. Создайте файл .env в корне проекта (см. пример ниже).
|
||
|
||
## Настройка окружения (.env)
|
||
Значения по умолчанию указаны в скобках. Переменные без значения обязательны к заполнению.
|
||
|
||
# OpenAI
|
||
API_KEY=sk-...
|
||
|
||
# Telegram Bot
|
||
TG_TOKEN=123456:ABC...
|
||
|
||
# Логи (опционально: отправка ошибок в Telegram)
|
||
LOG_TELEGRAM_BOT_TOKEN=123456:DEF... # опционально
|
||
LOG_TELEGRAM_CHAT_ID=123456789 # опционально
|
||
|
||
# PostgreSQL
|
||
DB_HOST=127.0.0.1
|
||
DB_PORT=5432
|
||
DB_NAME=greek_lang
|
||
DB_USER=greek_lang
|
||
DB_PASSWORD=greek_lang
|
||
DB_POOL_SIZE=20
|
||
DB_POOL_MAX_OVERFLOW=5
|
||
DB_CONNECT_WAIT_TIMEOUT_SECONDS=5
|
||
DB_DEBUG=false
|
||
|
||
# Redis
|
||
REDIS_HOST=127.0.0.1
|
||
REDIS_PORT=6379
|
||
REDIS_DB=0
|
||
REDIS_USERNAME=
|
||
REDIS_PASSWORD=
|
||
REDIS_POOL_SIZE=100
|
||
|
||
Примечания:
|
||
- Переменные считываются классами конфигурации из src/greek_lang/configs/*.py.
|
||
- Для Alembic миграций можно переопределить URL через переменную окружения ALEMBIC_DB_URL. Если не задано, Alembic сам соберёт URL из .env.
|
||
|
||
## Инициализация базы и миграции
|
||
Alembic уже сконфигурирован (см. src/greek_lang/database/migrations/ и alembic.ini).
|
||
|
||
- Применить миграции к последней версии:
|
||
alembic -c src/greek_lang/database/alembic.ini upgrade head
|
||
|
||
- Откатить на один шаг:
|
||
alembic -c src/greek_lang/database/alembic.ini downgrade -1
|
||
|
||
- Использовать конкретный URL БД (в обход .env):
|
||
ALEMBIC_DB_URL="postgresql://user:pass@host:5432/dbname" \
|
||
alembic -c src/greek_lang/database/alembic.ini upgrade head
|
||
|
||
## Использование
|
||
### CLI переводчик
|
||
Пример запуска CLI для перевода одного слова:
|
||
|
||
python -m cli.translate "έμπορος" -s el -t ru
|
||
|
||
- -s/--source: исходный язык (ru|en|el), по умолчанию el
|
||
- -t/--target: язык перевода (ru|en|el), по умолчанию ru
|
||
|
||
При запуске создаются контейнеры зависимостей, выполняется запрос к OpenAI, генерируется аудио‑произношение и всё сохраняется в таблицу glossary_word.
|
||
|
||
### Телеграм‑бот
|
||
Убедитесь, что Redis и .env настроены. Затем запустите бота:
|
||
|
||
python -m greek_lang.tg_bot
|
||
|
||
Бот удалит вебхук и начнёт polling. Команда /start ответит тестовым сообщением (заглушка). В коде предусмотрена интеграция Redis FSM‑хранилища и готовность к добавлению диалогов (aiogram-dialog).
|
||
|
||
## Архитектура (кратко)
|
||
- Контейнеры зависимостей: src/greek_lang/container.py и под‑контейнеры для конфигов, БД, OpenAI, Redis.
|
||
- Конфигурация: pydantic‑settings, .env читается из корня проекта (src/greek_lang/configs/__init__.py).
|
||
- Перевод: src/greek_lang/translator.py — orchestration: OpenAI → TTS → вставка/обновление в БД (UPSERT по term).
|
||
- OpenAI: src/greek_lang/openai_manager — типизированный парсинг ответа через client.beta.chat.completions.parse в модель WordInfo.
|
||
- БД: SQLAlchemy 2.0, Alembic миграции; сущности в glossaries/models.py и openai_manager/models.py.
|
||
- Аудио: aiogTTS, генерация в BytesIO, хранение в столбце LargeBinary.
|
||
- Логи: JSON‑логгер, опциональная отправка ошибок в Telegram.
|
||
|
||
## Разработка
|
||
- Линт/типы через go-task (см. Taskfile.yml):
|
||
- Запуск проверок: task check
|
||
- Только mypy: task mypy
|
||
- Ruff lint/format: task ruff-check / task ruff-fix / task ruff-format
|
||
- Обновить зависимости: task deps-update
|
||
- Очистить кэши: task clean
|
||
|
||
- Установка dev‑зависимостей (uv):
|
||
uv sync --group dev
|
||
|
||
Примечание: В pyproject.toml определён entry point [project.scripts], но пока не реализована функция greek_lang:main. Используйте вызовы модулей через python -m как указано выше.
|
||
|
||
## Частые проблемы
|
||
- Нет доступа к OpenAI: проверьте переменную API_KEY и сетевые ограничения.
|
||
- Ошибка подключения к Postgres: проверьте DB_HOST/DB_PORT/DB_USER/DB_PASSWORD и что БД создана.
|
||
- Alembic не видит URL: либо задайте ALEMBIC_DB_URL, либо убедитесь, что .env заполнен корректно.
|
||
- Redis недоступен: проверьте REDIS_* переменные и доступность сервиса.
|
||
|
||
## Лицензия
|
||
Не указана. При необходимости добавьте раздел с выбранной лицензией.
|