git init

.gitignore

@@ -0,0 +1,161 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+.vscode
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+.DS_Store
+*.sqlite3
+media/
+*.pyc
+*.db
+*.pid
+*.sqlite
+
+### VirtualEnv template
+# Virtualenv
+# http://iamzed.com/2009/05/07/a-primer-on-virtualenv/
+[Bb]in
+[Ii]nclude
+[Ll]ib
+[Ll]ib64
+[Ll]ocal
+pyvenv.cfg
+pip-selfcheck.json
+### JetBrains template
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff:
+.idea/workspace.xml
+.idea/tasks.xml
+.idea/dictionaries
+.idea/vcs.xml
+.idea/jsLibraryMappings.xml
+
+# Sensitive or high-churn files:
+.idea/dataSources.ids
+.idea/dataSources.xml
+.idea/dataSources.local.xml
+.idea/sqlDataSources.xml
+.idea/dynamic.xml
+.idea/uiDesigner.xml
+
+# Gradle:
+.idea/gradle.xml
+.idea/libraries
+
+**/.idea/
+.idea/
+.idea_modules/
+.idea/mongoSettings.xml
+
+## File-based project format:
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+/out/
+
+*.local.json
+
+#ansible part
+ansible-etcd.cache
+etcd.ini
+/inventory

.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.11.13
+    hooks:
+      - id: ruff
+        name: ruff (auto-fix & format)
+        args: [--fix]
+        files: ^src/greek_lang/.*\.py$
+        stages: [pre-commit]
+
+      - id: ruff
+        name: ruff (lint only)
+        args: [check]
+        files: ^src/greek_lang/.*\.py$
+        stages: [pre-push]
+
+  - repo: local
+    hooks:
+      - id: mypy-all
+        name: mypy (strict on all libs)
+        entry: bash -c 'mypy --strict src/greek_lang
+        language: system
+        pass_filenames: false
+        always_run: true

Taskfile.yml

@@ -0,0 +1,45 @@
+version: '3'
+
+tasks:
+  mypy:
+    desc: "Run mypy for type checking"
+    cmds:
+      - mypy --strict src/greek_lang --python-version 3.13 --strict
+
+  ruff-check:
+    desc: “Run ruff lint checks”
+    cmds:
+      - ruff check src/greek_lang
+      - ruff format --check src/greek_lang
+
+  ruff-fix:
+    desc: “Auto-fix issues and format code with ruff”
+    cmds:
+      - ruff check --fix src/greek_lang
+      - ruff format src/greek_lang
+
+  ruff-format:
+    desc: "Format code using ruff"
+    cmds:
+      - ruff format src/greek_lang
+
+  check:
+    desc: "Run mypy and ruff checks"
+    cmds:
+      - task mypy
+      - task ruff-check
+
+  fix:
+    desc: "Run auto-fixes using ruff"
+    cmds:
+      - task ruff-fix
+      - task ruff-format
+
+  clean:
+    desc: "Clean cache and temporary files"
+    cmds:
+      - rm -rf .mypy_cache
+      - rm -rf .ruff_cache
+      - rm -rf .pytest_cache
+      - rm -rf htmlcov
+      - rm -rf .coverage

pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "greek-lang"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "ruslangilfanov", email = "rgilfanov@walletteam.org" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "aiogtts>=1.1.1",
+    "alembic>=1.16.1",
+    "asyncpg>=0.30.0",
+    "dependency-injector>=4.47.1",
+    "greenlet>=3.2.3",
+    "openai>=1.84.0",
+    "pendulum>=3.1.0",
+    "psycopg2-binary>=2.9.10",
+    "pydantic>=2.11.5",
+    "pydantic-settings>=2.9.1",
+    "sqlalchemy>=2.0.41",
+]
+
+[project.scripts]
+greek-lang = "greek_lang:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "bandit>=1.8.3",
+    "go-task-bin>=3.43.3",
+    "mypy>=1.16.0",
+    "pre-commit>=4.2.0",
+    "pyupgrade>=3.20.0",
+    "ruff>=0.11.13",
+]

src/greek_lang/configs/__init__.py

@@ -0,0 +1,16 @@
+import os.path
+import pathlib
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class EnvConfig(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=pathlib.Path(__file__).parent
+        / os.path.pardir
+        / os.path.pardir
+        / os.path.pardir
+        / ".env",
+        env_file_encoding="utf-8",
+        extra="allow",
+    )

src/greek_lang/configs/container.py

@@ -0,0 +1,15 @@
+from dependency_injector import containers, providers
+
+from .db_config import PostgresConfig
+from .log_config import LoggerConfig
+from .openai_config import OpenAiConfig
+from .tg_bot_config import TgBotConfig
+
+
+class ConfigContainer(containers.DeclarativeContainer):
+    log_config: providers.Provider[LoggerConfig] = providers.Singleton(LoggerConfig)
+    postgres_config: providers.Provider[PostgresConfig] = providers.Singleton(
+        PostgresConfig
+    )
+    tg_bot_config: providers.Provider[TgBotConfig] = providers.Singleton(TgBotConfig)
+    openai_config: providers.Provider[OpenAiConfig] = providers.Singleton(OpenAiConfig)

src/greek_lang/configs/db_config.py

@@ -0,0 +1,15 @@
+import pydantic
+
+from . import EnvConfig
+
+
+class PostgresConfig(EnvConfig):
+    db_host: str = pydantic.Field(default="127.0.0.1")
+    db_port: int = pydantic.Field(default=5432)
+    db_name: str = pydantic.Field(default="greek_lang")
+    db_user: str = pydantic.Field(default="greek_lang")
+    db_password: pydantic.SecretStr = pydantic.SecretStr("greek_lang")
+    db_pool_size: int = pydantic.Field(default=20)
+    db_pool_max_overflow: int = pydantic.Field(default=5)
+    db_connect_wait_timeout_seconds: int = pydantic.Field(default=5)
+    db_debug: bool = pydantic.Field(default=False)

src/greek_lang/configs/log_config.py

@@ -0,0 +1,8 @@
+import pydantic
+
+from . import EnvConfig
+
+
+class LoggerConfig(EnvConfig):
+    telegram_bot_token: pydantic.SecretStr | None = None
+    telegram_chat_id: int | None = None

src/greek_lang/configs/openai_config.py

@@ -0,0 +1,7 @@
+import pydantic
+
+from . import EnvConfig
+
+
+class OpenAiConfig(EnvConfig):
+    api_key: pydantic.SecretStr

src/greek_lang/configs/tg_bot_config.py

@@ -0,0 +1,7 @@
+import pydantic
+
+from . import EnvConfig
+
+
+class TgBotConfig(EnvConfig):
+    token: pydantic.SecretStr

src/greek_lang/container.py

@@ -0,0 +1,49 @@
+import contextlib
+from collections.abc import AsyncIterator
+
+from dependency_injector import containers, providers
+
+from .configs.container import ConfigContainer
+from .database.container import DatabaseContainer
+from .openai_manager.container import OpenAiContainer
+
+
+class MainContainer(containers.DeclarativeContainer):
+    config_container = providers.Container(
+        ConfigContainer,
+    )
+    database_container = providers.Container(
+        DatabaseContainer, config_container=config_container
+    )
+    openai_container = providers.Container(
+        OpenAiContainer, config_container=config_container
+    )
+
+
+@contextlib.asynccontextmanager
+async def init_resources(
+    container: MainContainer,
+    packages: tuple[str, ...] = ("greek_lang",),
+    modules: tuple[str, ...] = (),
+) -> AsyncIterator[MainContainer]:
+    for provider in container.traverse(types=[providers.Container]):
+        provider.wire(packages=packages, modules=modules)
+    resources = container.init_resources()
+    if resources:
+        await resources
+    try:
+        yield container
+    finally:
+        shutdown_resources = container.shutdown_resources()
+        if shutdown_resources:
+            await shutdown_resources
+
+
+@contextlib.asynccontextmanager
+async def init_main_container(
+    packages: tuple[str, ...] = ("greek_lang",),
+    modules: tuple[str, ...] = (),
+) -> AsyncIterator[MainContainer]:
+    container = MainContainer()
+    async with init_resources(container, packages=packages, modules=modules):
+        yield container

src/greek_lang/database/alembic.ini

@@ -0,0 +1,120 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+# Use forward slashes (/) also on windows to provide an os agnostic path
+script_location = migrations
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+
+# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
+# Uncomment the line below if you want the files to be prepended with date and time
+# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
+# for all available tokens
+# file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+# defaults to the current working directory.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python>=3.9 or backports.zoneinfo library and tzdata library.
+# Any required deps can installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to ZoneInfo()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to migrations/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:migrations/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+# version_path_separator = newline
+#
+# Use os.pathsep. Default configuration used for new projects.
+version_path_separator = os
+
+# set to 'true' to search source files recursively
+# in each "version_locations" directory
+# new in Alembic version 1.10
+# recursive_version_locations = false
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+sqlalchemy.url = driver://user:pass@localhost/dbname
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# lint with attempts to fix using "ruff" - use the exec runner, execute a binary
+# hooks = ruff
+# ruff.type = exec
+# ruff.executable = %(here)s/.venv/bin/ruff
+# ruff.options = --fix REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARNING
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARNING
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

src/greek_lang/database/app_models.py

@@ -0,0 +1,11 @@
+import types
+
+
+def get_app_models_modules() -> list[types.ModuleType]:
+    from greek_lang.glossaries import models as glossaries_models
+    from greek_lang.openai_manager import models as openai_manager_models
+
+    return [
+        glossaries_models,
+        openai_manager_models,
+    ]

src/greek_lang/database/base.py

@@ -0,0 +1,17 @@
+from sqlalchemy import MetaData
+from sqlalchemy.orm import DeclarativeBase
+
+
+metadata_obj = MetaData(
+    naming_convention={
+        "ix": "ix_%(column_0_label)s",
+        "uq": "uq_%(table_name)s_%(column_0_name)s",
+        "ck": "ck_%(table_name)s_%(constraint_name)s",
+        "fk": "fk_%(table_name)s_%(column_0_name)s_%(referred_table_name)s",
+        "pk": "pk_%(table_name)s",
+    },
+)
+
+
+class Base(DeclarativeBase):
+    metadata = metadata_obj

src/greek_lang/database/container.py

@@ -0,0 +1,42 @@
+from collections.abc import AsyncIterator
+
+from dependency_injector import containers, providers
+from sqlalchemy import URL
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+
+from ..configs.db_config import PostgresConfig
+from .sessions import (
+    DRIVERNAME_SYNC,
+    create_async_engine,
+    create_url_dsn,
+    get_session_maker_async,
+)
+
+
+async def create_engine_rw_resource(
+    postgres_config: PostgresConfig,
+) -> AsyncIterator[AsyncEngine]:
+    engine = create_async_engine(postgres_config)
+    try:
+        yield engine
+    finally:
+        await engine.dispose()
+
+
+class DatabaseContainer(containers.DeclarativeContainer):
+    config_container = providers.DependenciesContainer()  # ConfigContainer
+    async_engine: providers.Resource[AsyncEngine] = providers.Resource(
+        create_engine_rw_resource,
+        postgres_config=config_container.postgres_config,
+    )
+    async_session_maker: providers.Factory[async_sessionmaker[AsyncSession]] = (
+        providers.Factory(
+            get_session_maker_async,
+            engine=async_engine,
+        )
+    )
+    db_url: providers.Provider[URL] = providers.Factory(
+        create_url_dsn,
+        DRIVERNAME_SYNC,
+        config_container.postgres_config,
+    )

src/greek_lang/database/migrations/README

@@ -0,0 +1 @@
+Generic single-database configuration.

src/greek_lang/database/migrations/env.py

@@ -0,0 +1,114 @@
+import asyncio
+import os
+from collections.abc import MutableMapping
+from logging.config import fileConfig
+from typing import Literal
+
+from alembic import context
+from sqlalchemy import URL, create_engine, make_url, pool
+from sqlalchemy.orm import DeclarativeBase
+
+from greek_lang.configs.container import ConfigContainer
+from greek_lang.database.app_models import get_app_models_modules
+from greek_lang.database.base import Base
+from greek_lang.database.container import DatabaseContainer
+
+
+_ = get_app_models_modules()
+
+# this is the Alembic Config object, which provides
+# access to the values within the .ini file in use.
+config = context.config
+
+# Interpret the config file for Python logging.
+# This line sets up loggers basically.
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+
+def include_name_filter(
+    name: str | None,
+    type_: Literal[
+        "schema",
+        "table",
+        "column",
+        "index",
+        "unique_constraint",
+        "foreign_key_constraint",
+    ],
+    parent_names: MutableMapping[
+        Literal["schema_name", "table_name", "schema_qualified_table_name"], str | None
+    ],
+) -> bool:
+    match type_:
+        case "table":
+            return name not in {
+                "apscheduler_jobs",
+                "apy_changes_logs",  # deprecated model, just for history
+            }
+        case _:
+            return True
+
+
+def run_migrations_offline(base_model: type[DeclarativeBase], url: URL) -> None:
+    """Run migrations in 'offline' mode.
+
+    This configures the context with just a URL
+    and not an Engine, though an Engine is acceptable
+    here as well.  By skipping the Engine creation
+    we don't even need a DBAPI to be available.
+
+    Calls to context.execute() here emit the given string to the
+    script output.
+
+    """
+    context.configure(
+        url=str(url),
+        target_metadata=base_model.metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        include_schemas=True,
+        include_name=include_name_filter,
+    )
+    if hasattr(base_model, "discover") and callable(base_model.discover):
+        base_model.discover()
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online(base_model: type[DeclarativeBase], url: URL) -> None:
+    connectable = create_engine(
+        url,
+        poolclass=pool.NullPool,
+    )
+    if hasattr(base_model, "discover") and callable(base_model.discover):
+        base_model.discover()
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=base_model.metadata,
+            include_schemas=True,
+            include_name=include_name_filter,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+async def get_db_url() -> URL:
+    database_container = DatabaseContainer(config_container=ConfigContainer())
+    database_container.wire(packages=["greek_lang.database"])
+    db_url = database_container.db_url()
+    return db_url
+
+
+alembic_db_url = os.environ.get("ALEMBIC_DB_URL")
+if alembic_db_url is None:
+    alembic_db_url = asyncio.run(get_db_url()).render_as_string(hide_password=False)
+    if alembic_db_url is None:
+        raise RuntimeError("alembic_db_url not set")
+
+
+if context.is_offline_mode():
+    run_migrations_offline(Base, make_url(alembic_db_url))
+else:
+    run_migrations_online(Base, make_url(alembic_db_url))

src/greek_lang/database/migrations/script.py.mako

@@ -0,0 +1,28 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    ${downgrades if downgrades else "pass"}

src/greek_lang/database/migrations/versions/20250615_1636_8c97f743c3c7_zero_state.py

@@ -0,0 +1,30 @@
+"""zero_state
+
+Revision ID: 8c97f743c3c7
+Revises:
+Create Date: 2025-06-15 16:36:01.523616
+
+"""
+
+from typing import Sequence, Union
+
+
+# revision identifiers, used by Alembic.
+revision: str = "8c97f743c3c7"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = ("zero",)
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    pass
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    pass
+    # ### end Alembic commands ###

src/greek_lang/database/migrations/versions/20250615_1651_c66487d803bf_glossaries.py

@@ -0,0 +1,95 @@
+"""glossaries
+
+Revision ID: c66487d803bf
+Revises: 8c97f743c3c7
+Create Date: 2025-06-15 16:51:41.279417
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "c66487d803bf"
+down_revision: Union[str, None] = "8c97f743c3c7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "glossary_word",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("term", sa.Text(), nullable=False),
+        sa.Column(
+            "language",
+            sa.Enum("ru", "en", "el", name="languageenum", native_enum=False),
+            nullable=False,
+        ),
+        sa.Column("transcription", sa.Text(), nullable=True),
+        sa.Column("translation", sa.Text(), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column(
+            "lexical_category",
+            sa.Enum(
+                "noun",
+                "verb",
+                "adjective",
+                "adverb",
+                "pronoun",
+                "preposition",
+                "conjunction",
+                "interjection",
+                "numeral",
+                "determiner",
+                "particle",
+                "other",
+                name="lexicalcategoryenum",
+                native_enum=False,
+            ),
+            nullable=False,
+        ),
+        sa.Column("meaning_category", sa.Text(), nullable=True),
+        sa.Column("example", sa.Text(), nullable=True),
+        sa.Column("etymology", sa.Text(), nullable=True),
+        sa.Column("audio_file", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.text("now()"),
+            nullable=False,
+        ),
+        sa.Column("note", sa.Text(), nullable=True),
+        sa.Column("tags", postgresql.ARRAY(sa.Text()), nullable=True),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_glossary_word")),
+    )
+    op.create_index(
+        op.f("ix_glossary_word_language"), "glossary_word", ["language"], unique=False
+    )
+    op.create_index(
+        op.f("ix_glossary_word_lexical_category"),
+        "glossary_word",
+        ["lexical_category"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(op.f("ix_glossary_word_lexical_category"), table_name="glossary_word")
+    op.drop_index(op.f("ix_glossary_word_language"), table_name="glossary_word")
+    op.drop_table("glossary_word")
+    # ### end Alembic commands ###

src/greek_lang/database/migrations/versions/20250615_1716_19fc4bee7a9f_openai_token_usage.py

@@ -0,0 +1,91 @@
+"""openai_token_usage
+
+Revision ID: 19fc4bee7a9f
+Revises: c66487d803bf
+Create Date: 2025-06-15 17:16:53.259466
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "19fc4bee7a9f"
+down_revision: Union[str, None] = "c66487d803bf"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "openai_token_usage",
+        sa.Column("id", sa.BigInteger(), autoincrement=True, nullable=False),
+        sa.Column("response_id", sa.Text(), nullable=False),
+        sa.Column("gpt_model", sa.Text(), nullable=False),
+        sa.Column("open_ai_created", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("response_fingerprint", sa.Text(), nullable=False),
+        sa.Column("completion_tokens", sa.Integer(), nullable=False),
+        sa.Column("prompt_tokens", sa.Integer(), nullable=False),
+        sa.Column("total_tokens", sa.Integer(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_openai_token_usage")),
+    )
+    op.create_index(
+        op.f("ix_openai_token_usage_created_at"),
+        "openai_token_usage",
+        ["created_at"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_openai_token_usage_gpt_model"),
+        "openai_token_usage",
+        ["gpt_model"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_openai_token_usage_open_ai_created"),
+        "openai_token_usage",
+        ["open_ai_created"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_openai_token_usage_response_fingerprint"),
+        "openai_token_usage",
+        ["response_fingerprint"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_openai_token_usage_response_id"),
+        "openai_token_usage",
+        ["response_id"],
+        unique=True,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(
+        op.f("ix_openai_token_usage_response_id"), table_name="openai_token_usage"
+    )
+    op.drop_index(
+        op.f("ix_openai_token_usage_response_fingerprint"),
+        table_name="openai_token_usage",
+    )
+    op.drop_index(
+        op.f("ix_openai_token_usage_open_ai_created"), table_name="openai_token_usage"
+    )
+    op.drop_index(
+        op.f("ix_openai_token_usage_gpt_model"), table_name="openai_token_usage"
+    )
+    op.drop_index(
+        op.f("ix_openai_token_usage_created_at"), table_name="openai_token_usage"
+    )
+    op.drop_table("openai_token_usage")
+    # ### end Alembic commands ###

src/greek_lang/database/sessions.py

@@ -0,0 +1,190 @@
+import dataclasses
+import functools
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from sqlalchemy import (
+    URL,
+    Connection,
+    Engine,
+    create_engine,
+    event,
+    text,
+)
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    AsyncSessionTransaction,
+    async_sessionmaker,
+)
+from sqlalchemy.orm import Session, sessionmaker
+
+from ..configs.db_config import PostgresConfig
+
+
+DRIVERNAME_SYNC = "postgresql"
+DRIVERNAME_ASYNC = "postgresql+asyncpg"
+
+
+def create_url_dsn(
+    driver_name: str,
+    config: PostgresConfig,
+) -> URL:
+    url = URL.create(
+        drivername=driver_name,
+        username=config.db_user,
+        password=config.db_password.get_secret_value(),
+        host=config.db_host,
+        port=config.db_port,
+        database=config.db_name,
+    )
+    return url
+
+
+create_sync_dsn = functools.partial(
+    create_url_dsn,
+    driver_name=DRIVERNAME_SYNC,
+)
+
+
+@dataclasses.dataclass(frozen=True)
+class EngineOptions:
+    read_only: bool
+    is_async: bool
+    username: str
+    password: str
+    host: str
+    port: int
+    database: str
+    # **kwargs for create_engine_async / create_engine
+    pool_size: int
+    max_overflow: int
+    pool_timeout: float
+    echo: bool
+    echo_pool: bool
+    pool_pre_ping: bool = dataclasses.field(default=True)
+    connect_args: dict[str, Any] = dataclasses.field(default_factory=lambda: {})
+
+    @property
+    def url(self) -> URL:
+        query: dict[str, Any] = {}
+        return URL.create(
+            drivername=DRIVERNAME_ASYNC if self.is_async else DRIVERNAME_SYNC,
+            username=self.username,
+            password=self.password,
+            host=self.host,
+            port=self.port,
+            database=self.database,
+            query=query,
+        )
+
+    @property
+    def params(self) -> dict[str, Any]:
+        params = dataclasses.asdict(self)
+        is_async = params.pop("is_async")
+        for name in ("read_only", "username", "password", "host", "port", "database"):
+            params.pop(name)
+        if is_async:
+            params["connect_args"].update(
+                {
+                    "prepared_statement_name_func": lambda: "",
+                    "statement_cache_size": 0,
+                    "prepared_statement_cache_size": 0,
+                }
+            )
+        else:
+            # TODO: implement disable prepared statement for sync
+            raise NotImplementedError(
+                "TODO: implement disable prepared statement for sync"
+            )
+        return params
+
+    def make_engine(self) -> Engine | AsyncEngine:
+        from sqlalchemy.ext.asyncio import create_async_engine
+
+        engine: Engine | AsyncEngine
+        if self.is_async:
+            engine = create_async_engine(self.url, **self.params)
+
+            if self.read_only:
+
+                @event.listens_for(engine.sync_engine, "begin")
+                def set_transaction_read_only(conn: Connection) -> None:
+                    conn.execute(text("SET TRANSACTION READ ONLY;"))
+
+            return engine
+        else:
+            engine = create_engine(self.url, **self.params)
+
+            if self.read_only:
+
+                @event.listens_for(engine, "begin")
+                def set_transaction_read_only(conn: Connection) -> None:
+                    conn.execute(text("SET TRANSACTION READ ONLY;"))
+
+            return engine
+
+
+AUTOFLUSH = False
+EXPIRE_ON_COMMIT = False
+
+
+def get_session_maker_async(
+    engine: AsyncEngine,
+) -> async_sessionmaker[AsyncSession]:
+    return async_sessionmaker(
+        bind=engine,
+        autoflush=AUTOFLUSH,
+        expire_on_commit=EXPIRE_ON_COMMIT,
+    )
+
+
+def get_session_maker_sync(engine: Engine) -> sessionmaker[Session]:
+    maker = sessionmaker(
+        bind=engine,
+        autoflush=AUTOFLUSH,
+        expire_on_commit=EXPIRE_ON_COMMIT,
+    )
+    return maker
+
+
+def create_async_engine(postgres_config: PostgresConfig) -> AsyncEngine:
+    engine = EngineOptions(
+        read_only=False,
+        is_async=True,
+        username=postgres_config.db_user,
+        password=postgres_config.db_password.get_secret_value(),
+        host=postgres_config.db_host,
+        port=postgres_config.db_port,
+        database=postgres_config.db_name,
+        pool_size=postgres_config.db_pool_size,
+        max_overflow=postgres_config.db_pool_max_overflow,
+        pool_timeout=postgres_config.db_connect_wait_timeout_seconds,
+        echo=postgres_config.db_debug,
+        echo_pool=postgres_config.db_debug,
+    ).make_engine()
+    if not isinstance(engine, AsyncEngine):
+        raise RuntimeError("engine must be an AsyncEngine")
+    return engine
+
+
+def use_db_session(session: AsyncSession) -> async_sessionmaker[AsyncSession]:
+    @asynccontextmanager
+    async def _maker() -> AsyncIterator[AsyncSession]:
+        yield session
+
+    return _maker  # type: ignore[return-value]
+
+
+@asynccontextmanager
+async def begin_maybe_nested(
+    session: AsyncSession,
+) -> AsyncIterator[AsyncSessionTransaction]:
+    tx: AsyncSessionTransaction
+    if session.in_transaction():
+        tx = session.begin_nested()
+    else:
+        tx = session.begin()
+    async with tx:
+        yield tx

src/greek_lang/glossaries/models.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import datetime
+import enum
+
+from sqlalchemy import BigInteger, Text, DateTime, Enum, func
+from sqlalchemy.dialects.postgresql import ARRAY
+from sqlalchemy.orm import Mapped, mapped_column
+
+from ..database.base import Base
+from ..languages import LanguageEnum
+
+
+class LexicalCategoryEnum(str, enum.Enum):
+    noun = "noun"
+    verb = "verb"
+    adjective = "adjective"
+    adverb = "adverb"
+    pronoun = "pronoun"
+    preposition = "preposition"
+    conjunction = "conjunction"
+    interjection = "interjection"
+    numeral = "numeral"
+    determiner = "determiner"
+    particle = "particle"
+    other = "other"
+
+
+class GlossaryWord(Base):
+    __tablename__ = "glossary_word"
+
+    id: Mapped[int] = mapped_column(
+        BigInteger(),
+        primary_key=True,
+        autoincrement=True,
+    )
+    term: Mapped[str] = mapped_column(
+        Text(),
+        nullable=False,
+    )
+    language: Mapped[LanguageEnum] = mapped_column(
+        Enum(LanguageEnum, native_enum=False),
+        nullable=False,
+        index=True,
+    )
+    transcription: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    translation: Mapped[str] = mapped_column(
+        Text(),
+        nullable=False,
+    )
+    description: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    lexical_category: Mapped[LexicalCategoryEnum] = mapped_column(
+        Enum(
+            LexicalCategoryEnum,
+            native_enum=False,
+        ),
+        nullable=False,
+        index=True,
+    )
+    meaning_category: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    example: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    etymology: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    audio_file: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )
+    updated_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True),
+        server_default=func.now(),
+    )
+    note: Mapped[str | None] = mapped_column(
+        Text(),
+        nullable=True,
+    )
+    tags: Mapped[list[str]] = mapped_column(
+        ARRAY(Text),
+        nullable=True,
+    )
+
+    def __repr__(self) -> str:
+        return (
+            f"<GlossaryWord(id={self.id}, term='{self.term}', language='{self.language.value}', "
+            f"translation='{self.translation}', transcription='{self.transcription}', "
+            f"lexical_category='{self.lexical_category}', meaning_category='{self.meaning_category}')>"
+        )

src/greek_lang/languages.py

@@ -0,0 +1,8 @@
+import enum
+
+
+@enum.unique
+class LanguageEnum(str, enum.Enum):
+    ru = "ru"
+    en = "en"
+    el = "el"

src/greek_lang/openai_manager/client.py

@@ -0,0 +1,41 @@
+import pendulum
+from dependency_injector.wiring import inject, Provide
+from openai import AsyncOpenAI
+from openai._types import ResponseT
+from sqlalchemy.ext.asyncio import async_sessionmaker, AsyncSession
+
+from ..database.container import DatabaseContainer
+
+from .models import OpenAiTokenUsage
+
+
+class AsyncOpenAICustom(AsyncOpenAI):
+    async def _process_response(  # type: ignore
+        self,
+        *args,
+        **kwargs,
+    ) -> ResponseT:
+        response: ResponseT = await super()._process_response(*args, **kwargs)
+        await self.save_token_usage(response)
+        return response
+
+    @inject
+    async def save_token_usage(
+        self,
+        response: ResponseT,
+        async_session_maker: async_sessionmaker[AsyncSession] = Provide[
+            DatabaseContainer.async_session_maker
+        ],
+    ) -> None:
+        async with async_session_maker.begin() as db_session:
+            db_session.add(
+                OpenAiTokenUsage(
+                    response_id=response.id,  # type: ignore[union-attr]
+                    gpt_model=response.model,  # type: ignore[union-attr]
+                    open_ai_created=pendulum.from_timestamp(response.created, tz="UTC"),  # type: ignore[union-attr]
+                    response_fingerprint=response.system_fingerprint,  # type: ignore[union-attr]
+                    completion_tokens=response.usage.completion_tokens,  # type: ignore[union-attr]
+                    prompt_tokens=response.usage.prompt_tokens,  # type: ignore[union-attr]
+                    total_tokens=response.usage.total_tokens,  # type: ignore[union-attr]
+                )
+            )

src/greek_lang/openai_manager/container.py

@@ -0,0 +1,25 @@
+from typing import AsyncIterator
+
+from dependency_injector import containers, providers
+from openai import AsyncOpenAI
+from pydantic import SecretStr
+
+from .client import AsyncOpenAICustom
+from .manager import OpenAiManager
+
+
+async def create_async_openai_client(api_key: SecretStr) -> AsyncIterator[AsyncOpenAI]:
+    async with AsyncOpenAICustom(api_key=api_key.get_secret_value()) as client:
+        yield client
+
+
+class OpenAiContainer(containers.DeclarativeContainer):
+    config_container = providers.DependenciesContainer()
+    ai_client: providers.Resource[AsyncOpenAI] = providers.Resource(
+        create_async_openai_client,
+        api_key=config_container.openai_config.provided.api_key,
+    )
+    ai_manager: providers.Factory[OpenAiManager] = providers.Factory(
+        OpenAiManager,
+        client=ai_client,
+    )

src/greek_lang/openai_manager/manager.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import dataclasses
+
+import pydantic
+from openai import AsyncOpenAI
+
+
+class WordInfo(pydantic.BaseModel):
+    transcription: str = pydantic.Field(
+        ...,
+        description="phonetic transcription in IPA",
+    )
+    translation: str = pydantic.Field(
+        ...,
+        description="translation in {target_language}",
+    )
+    description: str = pydantic.Field(
+        ...,
+        description="description in {target_language}",
+    )
+    part_of_speech: str = pydantic.Field(
+        ...,
+        description="part of speech in {target_language}",
+    )
+    example: str = pydantic.Field(
+        ...,
+        description="example",
+    )
+    example_transcription: str = pydantic.Field(
+        ...,
+        description="phonetic transcription in IPA of an example",
+    )
+    example_translation: str = pydantic.Field(
+        ...,
+        description="translation of the example in {target_language}",
+    )
+    category: str = pydantic.Field(
+        ...,
+        description="semantic category in {target_language}",
+    )
+    etymology: str = pydantic.Field(
+        ...,
+        description="short etymology of the word described in {target_language}",
+    )
+
+
+@dataclasses.dataclass(frozen=True)
+class OpenAiManager:
+    client: AsyncOpenAI
+
+    async def get_gpt_response(
+        self,
+        *,
+        word: str,
+        source_lang: str,
+        target_lang: str,
+        model: str = "gpt-4o",
+    ) -> WordInfo:
+        system_message = {
+            "role": "system",
+            "content": "You are a helpful assistant that provides detailed word information.",
+        }
+        user_message = {
+            "role": "user",
+            "content": f'Provide detailed information about the word "{word}" in language {source_lang}, set {{target_language}} = {target_lang}.',
+        }
+        response = await self.client.beta.chat.completions.parse(
+            model=model,
+            messages=(  # type: ignore
+                system_message,
+                user_message,
+            ),
+            response_format=WordInfo,
+        )
+        word_info: WordInfo | None = response.choices[0].message.parsed
+        if word_info is None:
+            raise RuntimeError("No word_info")
+        return word_info

src/greek_lang/openai_manager/models.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import datetime
+
+from sqlalchemy import BigInteger, Text, DateTime, Integer
+from sqlalchemy.orm import Mapped, mapped_column
+
+from ..database.base import Base
+
+
+class OpenAiTokenUsage(Base):
+    __tablename__ = "openai_token_usage"
+
+    id: Mapped[int] = mapped_column(
+        BigInteger(),
+        primary_key=True,
+        autoincrement=True,
+    )
+    response_id: Mapped[str] = mapped_column(
+        Text(),
+        nullable=False,
+        index=True,
+        unique=True,
+    )
+    gpt_model: Mapped[str] = mapped_column(
+        Text(),
+        nullable=False,
+        index=True,
+    )
+    open_ai_created: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        index=True,
+    )
+    created_at: Mapped[datetime.datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=datetime.datetime.now(datetime.UTC),
+        nullable=False,
+        index=True,
+    )
+    response_fingerprint: Mapped[str] = mapped_column(
+        Text(),
+        nullable=False,
+        index=True,
+    )
+    completion_tokens: Mapped[int] = mapped_column(
+        Integer(),
+        nullable=False,
+    )
+    prompt_tokens: Mapped[int] = mapped_column(
+        Integer(),
+        nullable=False,
+    )
+    total_tokens: Mapped[int] = mapped_column(
+        Integer(),
+        nullable=False,
+    )
+
+    def __repr__(self) -> str:
+        return (
+            f"<OpenAiTokenUsage(id={self.id}, response_id='{self.response_id}', gpt_model='{self.gpt_model}', "
+            f"open_ai_created={self.open_ai_created}, created_at={self.created_at}, "
+            f"response_fingerprint='{self.response_fingerprint}', completion_tokens={self.completion_tokens} "
+            f"prompt_tokens={self.prompt_tokens} total_tokens={self.total_tokens})>"
+        )