add comprehensive README detailing project features, setup, and usage
This commit is contained in:
ruslangilfanov
parent
9747c9e9b0
commit
6ac3717ce2
131
README.md
131
README.md
@ -0,0 +1,131 @@
|
|||||||
|
# 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_* переменные и доступность сервиса.
|
||||||
|
|
||||||
|
## Лицензия
|
||||||
|
Не указана. При необходимости добавьте раздел с выбранной лицензией.
|
||||||
Loading…
Reference in New Issue
Block a user