agent/app/modules/shared/README.md

Модуль shared

1. Функции модуля

• Общие инфраструктурные компоненты для всех модулей:
  • подключение к БД (db.py, bootstrap.py),
  • шина событий (event_bus.py),
  • retry и idempotency (retry_executor.py, idempotency_store.py),
  • checkpointer,
  • клиент и настройки GigaChat (gigachat/*).

2. Диаграмма классов и взаимосвязей

classDiagram
    class EventBus
    class RetryExecutor
    class IdempotencyStore
    class GigaChatClient
    class GigaChatSettings
    class GigaChatTokenProvider

    GigaChatClient --> GigaChatSettings
    GigaChatClient --> GigaChatTokenProvider

3. Описание классов

• EventBus: общий асинхронный event-bus для публикации и SSE-стриминга. Методы: subscribe — подписка на канал; unsubscribe — удаление подписки; publish — отправка события; as_sse — сериализация события в SSE-формат.
• RetryExecutor: общий механизм повторных попыток для временных ошибок. Методы: run — выполняет async-операцию с retry по временным исключениям.
• IdempotencyStore: in-memory хранилище идемпотентных ключей. Методы: get_task_id — находит ранее созданную задачу по ключу; put — сохраняет ключ и task_id.
• GigaChatSettings: конфигурация доступа к GigaChat. Методы: from_env — собирает настройки из переменных окружения.
• GigaChatTokenProvider: управление access token для GigaChat API. Методы: get_access_token — возвращает валидный токен (с обновлением при необходимости).
• GigaChatClient: HTTP-клиент для completion и embeddings. Методы: complete — выполняет генерацию ответа модели; embed — получает векторные представления для списка текстов.

4. Сиквенс-диаграммы API

В модуле нет HTTP endpoint'ов: он предоставляет только инфраструктурные классы для других модулей.