agent/README.ARCH.md

Архитектура приложения

Документ описывает модульную архитектуру backend-приложения, связи между модулями и контрактные границы.

1. Диаграмма модулей и взаимосвязей

flowchart LR
    UI["Клиент / Frontend"] --> API["FastAPI (app/main.py)"]

    API --> CHAT["chat модуль"]
    API --> RAG["rag модуль"]
    API --> AGENT_INTERNAL["internal tools API"]

    CHAT -->|AgentRunner| AGENT["agent модуль"]
    AGENT -->|RagRetriever| RAG
    AGENT --> DB[(PostgreSQL + pgvector)]
    CHAT --> DB
    RAG --> DB

    AGENT --> GIGA["GigaChat API"]
    RAG --> GIGA

    AGENT_INTERNAL --> AGENT

    APP["ModularApplication\n(app/modules/application.py)"] --> CHAT
    APP --> AGENT
    APP --> RAG

Внутренние слои agent

flowchart TB
    ROUTER["Router\n(intent + context)"] --> ORCH["Orchestrator\n(task spec + plan + execution + quality)"]
    ORCH --> GRAPHS["Action Graphs\nLangGraph"]

    ORCH --> METRICS["Quality Metrics\n(faithfulness/coverage)"]
    METRICS --> DB[(agent_quality_metrics)]

2. Описание модулей

Модуль app/modules/chat

• Цель: принять пользовательский запрос, управлять задачей обработки, отдать результат и прогресс.
• Кратко о реализации:
  • ChatModule публикует HTTP API (/api/chat/*, /api/tasks/*, /api/events).
  • ChatOrchestrator запускает обработку асинхронной задачи, публикует SSE-события, обрабатывает retry и ошибки.
  • TaskStore, DialogSessionStore, IdempotencyStore держат состояние задач/диалогов.
• С кем взаимодействует:
  • с agent через контракт AgentRunner.
  • с rag для проверки rag_session_id.
  • с shared/event_bus для стриминга прогресса.
  • с БД через ChatRepository (dialog_sessions, chat_messages).
• Контракты:
  • потребляет AgentRunner.run(...) из app/modules/contracts.py.

Модуль app/modules/agent

• Цель: интеллектуальная обработка запроса, маршрутизация, оркестрация сценария, генерация ответа/changeset.
• Кратко о реализации:
  • GraphAgentRuntime выполняет pipeline: route -> task spec -> orchestrator -> post-processing.
  • Router (engine/router/*) выбирает domain/process и хранит routing-context.
  • Orchestrator (engine/orchestrator/*) строит и валидирует plan, исполняет шаги, запускает графовые/функциональные actions.
  • Graphs (engine/graphs/*) выполняют целевые действия (QA, edits, docs).
  • Рассчитывает quality-метрики (faithfulness, coverage) и сохраняет их в БД.
  • Поддерживает внутренний инструмент получения страниц Confluence (/internal/tools/confluence/fetch).
• С кем взаимодействует:
  • с rag через контракт RagRetriever.
  • с shared/checkpointer (LangGraph checkpoints в PostgreSQL).
  • с GigaChat (LLM-запросы, промпты).
  • с БД через AgentRepository (router_context, agent_quality_metrics).
• Контракты:
  • реализует AgentRunner (используется chat).
  • потребляет RagRetriever (реализуется rag).

Модуль app/modules/rag

• Цель: индексация проектных файлов и retrieval релевантного контекста.
• Кратко о реализации:
  • API для snapshot/changes индексации и retrieval.
  • Индексация хранит чанки, эмбеддинги и состояние job.
  • Retrieval ищет релевантные куски в rag_chunks (pgvector).
• С кем взаимодействует:
  • с agent (выдача контекста через RagRetriever).
  • с БД (rag_sessions, rag_chunks, rag_index_jobs).
  • с GigaChat Embeddings.
• Контракты:
  • реализует RagRetriever и RagIndexer из app/modules/contracts.py.

Модуль app/modules/shared

• Цель: общие инфраструктурные компоненты, переиспользуемые всеми модулями.
• Кратко о реализации:
  • db.py: engine/session factory.
  • event_bus.py: pub/sub для SSE.
  • retry_executor.py: общий retry.
  • checkpointer.py: PostgresSaver для LangGraph.
  • bootstrap.py: инициализация схем БД на старте.
• С кем взаимодействует:
  • со всеми бизнес-модулями (chat, agent, rag).
• Контракты:
  • внутренние инфраструктурные API без отдельного публичного контракта уровня contracts.py.

Модуль app/modules/contracts.py

• Цель: зафиксировать межмодульные интерфейсы и отделить реализацию от потребителей.
• Кратко о реализации:
  • AgentRunner, RagRetriever, RagIndexer определены как Protocol.
• С кем взаимодействует:
  • используется chat (как потребитель AgentRunner), agent (как потребитель RagRetriever), rag (как реализация RagRetriever/RagIndexer).
• Контракты:
  • это и есть контрактный слой.

Модуль композиции app/modules/application.py

• Цель: централизованный wiring зависимостей.
• Кратко о реализации:
  • ModularApplication создаёт EventBus, RetryExecutor, репозитории и модули.
  • На startup() выполняет bootstrap БД.
• С кем взаимодействует:
  • со всеми модулями, но не содержит бизнес-логики.
• Контракты:
  • использует contracts.py для сборки зависимостей без жёсткого сцепления по реализациям.

3. Ключевые контрактные границы

• chat -> agent: только через AgentRunner.
• agent -> rag: только через RagRetriever.
• rag: не зависит от agent internals.
• application.py: единственная точка связывания реализаций.

4. Схема данных (кратко)

• chat: dialog_sessions, chat_messages.
• rag: rag_sessions, rag_chunks, rag_index_jobs.
• agent:
  • router_context — контекст маршрутизации по диалогу.
  • agent_quality_metrics — пер-сценарные quality-метрики для отчетности:
    • faithfulness_score, coverage_score, quality_status, metrics_json, created_at.
  • story_records — карточка Story (статус, владелец, метаданные).
  • story_artifacts — артефакты по Story (analytics/doc_increment/test_model и версии).
  • story_links — внешние связи Story (тикеты, документы, URL).

5. Поток обработки запроса

1. Пользователь отправляет сообщение в chat.
2. chat создаёт task и вызывает AgentRunner.run(...).
3. agent/router выбирает маршрут (domain/process).
4. agent/orchestrator строит TaskSpec и ExecutionPlan.
5. Выполняются шаги плана (function/actions/graph steps).
6. Формируется answer или changeset.
7. Считаются faithfulness/coverage, сохраняются в agent_quality_metrics.
8. chat возвращает результат и стримит прогресс через SSE.