# Модуль agent

## 1. Функции модуля
- Оркестрация выполнения пользовательского запроса поверх роутера интентов и графов.
- Формирование `TaskSpec`, запуск оркестратора шагов и сборка финального результата.
- Реализация необходимых для агента tools и их интеграция с остальной логикой выполнения.
- Сохранение quality-метрик и session-артефактов для последующей привязки к Story.

## 2. Диаграмма классов и взаимосвязей
```mermaid
classDiagram
    class AgentModule
    class GraphAgentRuntime
    class OrchestratorService
    class TaskSpecBuilder
    class StorySessionRecorder
    class StoryContextRepository
    class ConfluenceService
    class AgentRepository

    AgentModule --> GraphAgentRuntime
    AgentModule --> ConfluenceService
    AgentModule --> StorySessionRecorder
    StorySessionRecorder --> StoryContextRepository
    GraphAgentRuntime --> OrchestratorService
    GraphAgentRuntime --> TaskSpecBuilder
    GraphAgentRuntime --> AgentRepository
    GraphAgentRuntime --> ConfluenceService
```

## 3. Описание классов
- `AgentModule`: собирает runtime и публикует внутренние tools-роуты.
  Методы: `__init__` — связывает зависимости модуля; `internal_router` — регистрирует internal API tools.
- `GraphAgentRuntime`: основной исполнитель агентного запроса.
  Методы: `run` — выполняет цикл route -> retrieval -> orchestration -> ответ/changeset.
- `OrchestratorService`: управляет планом шагов и выполнением quality gates.
  Методы: `run` — строит, валидирует и исполняет execution plan.
- `TaskSpecBuilder`: формирует спецификацию задачи для оркестратора.
  Методы: `build` — собирает `TaskSpec` из route, контекстов и ограничений.
- `ProjectQaConversationGraphFactory`, `ProjectQaClassificationGraphFactory`, `ProjectQaRetrievalGraphFactory`, `ProjectQaAnalysisGraphFactory`, `ProjectQaAnswerGraphFactory`: набор маленьких graph-исполнителей для `project/qa`.
  Роли: нормализация запроса; классификация project-question; поздний retrieval из `RAG`; анализ code/docs контекста; сборка финального ответа.
- `StorySessionRecorder`: пишет session-scoped артефакты для последующего bind к Story.
  Методы: `record_run` — сохраняет входные источники и выходные артефакты сессии.
- `StoryContextRepository`: репозиторий Story-контекста и его связей.
  Методы: `record_story_commit` — фиксирует commit-контекст Story; `upsert_story` — создает/обновляет карточку Story; `add_session_artifact` — добавляет session-артефакт; `bind_session_to_story` — переносит артефакты сессии в Story; `add_artifact` — добавляет версионный Story-артефакт; `get_story_context` — возвращает агрегированный контекст Story.
- `ConfluenceService`: tool для загрузки страницы по URL.
  Методы: `fetch_page` — валидирует URL и возвращает нормализованный payload страницы.
- `AgentRepository`: хранение router-контекста и quality-метрик.
  Методы: `ensure_tables` — создает таблицы модуля; `get_router_context` — читает контекст маршрутизации; `update_router_context` — обновляет историю диалога и last-route; `save_quality_metrics` — сохраняет метрики качества; `get_quality_metrics` — читает историю метрик.

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

### POST /internal/tools/confluence/fetch
Назначение: загружает страницу Confluence по URL и возвращает ее контент для дальнейшего использования в сценариях агента.
```mermaid
sequenceDiagram
    participant Router as AgentModule.APIRouter
    participant Confluence as ConfluenceService

    Router->>Confluence: fetch_page(url)
    Confluence-->>Router: page(content_markdown, metadata)
```

### `project/qa` reasoning flow
Назначение: оркестратор планирует шаги, а каждый шаг исполняется отдельным graph. Retrieval вызывается поздно, внутри шага `context_retrieval`.
```mermaid
sequenceDiagram
    participant Runtime as GraphAgentRuntime
    participant Orch as OrchestratorService
    participant G1 as conversation_understanding
    participant G2 as question_classification
    participant G3 as context_retrieval
    participant Rag as RagService
    participant G4 as context_analysis
    participant G5 as answer_composition

    Runtime->>Orch: run(task)
    Orch->>G1: execute
    G1-->>Orch: resolved_request
    Orch->>G2: execute
    G2-->>Orch: question_profile
    Orch->>G3: execute
    G3->>Rag: retrieve(query)
    Rag-->>G3: rag_items
    G3-->>Orch: source_bundle
    Orch->>G4: execute
    G4-->>Orch: analysis_brief
    Orch->>G5: execute
    G5-->>Orch: final_answer
    Orch-->>Runtime: final_answer
```
