# MVP: процесс v2

## 1. Общее описание

Процесс v2 в текущем MVP ориентирован в первую очередь на **документацию проекта**, но роутер также поддерживает `GENERAL / GENERAL_QA / SUMMARY` для общих обзорных вопросов. Для документных веток нужна активная RAG-сессия с проиндексированными документами.

Это **узкий MVP**, а не полная target architecture. Поддерживаются три маршрута:

- `GENERAL`
- `GENERAL_QA`
- `SUMMARY`
- `DOCS`
- `DOC_EXPLAIN`
- `SUMMARY`
- `FIND_FILES`

Запрос проходит следующие смысловые этапы:

1. проверка готовности сессии;
2. intent routing;
3. формирование retrieval-параметров;
4. retrieval из `DOCS RAG`;
5. минимальная сборка evidence;
6. запуск task-focused workflow нужной ветки;
7. формирование ответа.

```mermaid
flowchart TB
  subgraph api [API]
    RS[RequestService]
  end
  subgraph runtime [Agent runtime]
    AR[AgentRuntime]
    PR[ProcessRunner]
  end
  subgraph v2 [Процесс v2]
    P2[V2Process]
    IR[V2IntentRouter]
    POL[V2RetrievalPolicyResolver]
    AD[V2RagRetrievalAdapter]
    RSR[RagSessionRetriever]
    ASM[DocsEvidenceAssembler]
  end
  subgraph rag [Пакет rag]
    RR[RagRepository]
  end
  subgraph wf [Workflow]
    SUM[DocsExplainSummaryGraph]
    FF[DocsExplainFindFilesGraph]
  end
  LLM[AgentLlmService]
  RS --> AR --> PR --> P2
  P2 --> IR --> POL --> AD --> RSR --> RR
  AD --> ASM
  ASM --> SUM
  ASM --> FF
  SUM --> LLM
```

Клиент указывает `process_version: v2`. Без `active_rag_session_id` в сессии процесс возвращает сообщение об ошибке. Иначе выполняется цепочка:

маршрутизация → `RetrievalPlan` → retrieval строк из `DOCS RAG` → минимальная сборка evidence → ветвление по `subintent` → запуск workflow.

### Реализованные домены, интенты и сабинтенты

В коде заданы константы `V2Domain`, `V2Intent`, `V2Subintent`. Сейчас процесс intentionally ограничен одной рабочей областью.

| Уровень | Значение (строка) | Реализация |
|--------|-------------------|------------|
| **Домен (routing_domain)** | `DOCS` | Единственный поддерживаемый домен: документация проекта. |
| **Интент** | `DOC_EXPLAIN` | Единственный интент: объяснение по документации. |
| **Сабинтент** | `SUMMARY` | Объяснение темы по SUMMARY-блокам документации. |
| **Сабинтент** | `FIND_FILES` | Поиск путей к документам, где описана нужная сущность или тема. |

Итого в текущем MVP реализована **одна** рабочая тройка домен×интент: `DOCS` + `DOC_EXPLAIN`, с **двумя** ветками по сабинтенту.

---

## 2. Этапы вне workflow (внутри `V2Process.run`)

### 2.1. `V2IntentRouter.route`

| | |
|--|--|
| **Название** | Маршрутизация запроса (v2) |
| **Задача** | Определить домен, интент, subintent и извлечь якоря из текста. |
| **Вход** | `user_query: str` (текст сообщения пользователя). |
| **Выход** | `V2RouteResult`: `routing_domain`, `intent`, `subintent`, `user_query`, `normalized_query`, `target_terms`, `anchors` (`V2RouteAnchors`), `confidence`. |
| **Как работает** | Router реализован по схеме **LLM-first**: `normalization` → `target_terms`/`anchors extraction` → `LLM router` → `deterministic validator` → `fallback`. LLM является **основным селектором маршрута**. Deterministic-слой больше не выбирает маршрут по умолчанию: он отвечает только за extraction, валидацию enum/комбинаций и fallback при сломанном или невалидном ответе LLM. В trace пишется событие `intent_routed`. |

Код: `src/app/core/agent/processes/v2/intent_router/router.py`, `modules/normalizer.py`, `modules/target_terms.py`, `modules/anchors.py`, `routers/llm.py`, `routers/validator.py`, `routers/fallback.py`.

---

### 2.2. `V2RetrievalPolicyResolver.resolve`

| | |
|--|--|
| **Название** | Политика retrieval для v2 |
| **Задача** | По результату роутинга выбрать профиль, список слоёв RAG и лимит строк выдачи. |
| **Вход** | `V2RouteResult`. |
| **Выход** | `RetrievalPlan`: `profile`, `layers`, `limit`, опционально `filters`. |
| **Как работает** | Это отдельный смысловой шаг между routing и retrieval. Он не ходит в БД и не извлекает данные, а только подготавливает параметры поиска. Для `FIND_FILES` выбирается один профиль слоёв и лимит, для `SUMMARY` — другой. Лог: `retrieval_plan_resolved`. |

Код: `src/app/core/agent/processes/v2/retrieval/policy_resolver.py`.

---

### 2.3. `V2RagRetrievalAdapter` → `RagSessionRetriever.retrieve`

| | |
|--|--|
| **Название** | Загрузка сырых строк из RAG по плану |
| **Задача** | Делегировать поиск в единственную реализацию retrieval в пакете `rag`. |
| **Вход** | `rag_session_id`, `query_text` (нормализованный запрос), `RetrievalPlan`. |
| **Выход** | `list[dict]` — строки чанков в формате `RagRepository.retrieve` (поля `path`, `layer`, `metadata`, и т.д.). |
| **Как работает** | Выполняется retrieval по уже сформированному плану: профиль, список слоёв и лимит. На этом шаге происходит только извлечение сырых строк из `DOCS RAG`. Лог: `rag_rows_fetched`. |

Код адаптера: `src/app/core/agent/processes/v2/retrieval/v2_rag_adapter.py`.  
Код API: `src/app/core/rag/retrieval/session_retriever.py`.

---

### 2.4. `DocsEvidenceAssembler`

| | |
|--|--|
| **Название** | Сборка evidence для задачи |
| **Задача** | Превратить сырые строки retrieval в списки summary или кандидатов файлов с дедупом и скорингом. |
| **Вход** | Список строк `rows`, `V2RouteResult` (для `target_terms`). |
| **Выход** | `list[RetrievedSummary]` или `list[RetrievedFile]`. |
| **Как работает** | Это **минимальная evidence-проверка**, достаточная для MVP. Для `SUMMARY` отбрасываются записи без summary-текста и summary-like секции, затем применяется дедуп и простой скоринг по терминам. Для `FIND_FILES` остаются только релевантные пути документов, также с дедупом и простым скорингом. Здесь нет сложной многоступенчатой валидации: задача шага — отфильтровать очевидный шум и передать в workflow компактное evidence. Лог: `evidence_assembled`. |

Код: `src/app/core/agent/processes/v2/evidence/assembler.py`.

---

## 3. Шаги workflow

Текущие workflow являются **task-focused**: каждая ветка решает одну узкую прикладную задачу и не содержит общей универсальной логики для всех типов вопросов.

### 3.1. Ветка `SUMMARY`: `GenerateSummaryAnswerStep`

| | |
|--|--|
| **Название** | Сборка ответа по summary |
| **Задача** | Сформировать ответ пользователю по найденным SUMMARY-блокам или сообщить об отсутствии. |
| **Вход** | `DocsExplainSummaryContext`: `runtime`, `route`, `rag_session_id`, `prompt_name`, `documents` (список `RetrievedSummary`). |
| **Выход** | Контекст с `answer: str`, `prompt_input` при успешном вызове LLM. |
| **Как работает** | Workflow получает уже отобранные summary-документы. Если документов нет — возвращает честный fallback-ответ. Иначе собирает prompt input из запроса пользователя и найденных summary-блоков и вызывает LLM. Workflow не занимается retrieval и не строит retrieval-план: он решает только задачу генерации ответа по уже подготовленному evidence. |

Код: `src/app/core/agent/processes/v2/workflows/docs_explain_summary/steps/generate_summary_answer_step.py`.  
Граф: `DocsExplainSummaryGraph` (`V2WorkflowGraph`).

---

### 3.2. Ветка `FIND_FILES`: `FinalizeFindFilesAnswerStep`

| | |
|--|--|
| **Название** | Сборка списка файлов |
| **Задача** | Вывести пользователю markdown-список путей к файлам документации. |
| **Вход** | `DocsExplainFindFilesContext`: `runtime`, `route`, `rag_session_id`, `files` (`RetrievedFile`). |
| **Выход** | Контекст с `answer: str`. |
| **Как работает** | Workflow получает уже собранный список файлов и формирует финальный ответ. Если файлов нет — возвращает fallback. Если файлы есть — отдает детерминированный список путей. Эта ветка intentionally не использует LLM, потому что задача сводится к выдаче путей, а не к генерации объяснения. |

Код: `src/app/core/agent/processes/v2/workflows/docs_explain_find_files/steps/finalize_find_files_answer_step.py`.  
Граф: `DocsExplainFindFilesGraph` (`V2WorkflowGraph`).

---

### 3.3. Транспорт: `V2WorkflowGraph`

| | |
|--|--|
| **Название** | Workflow v2 с буфером trace |
| **Задача** | Выполнить шаги без пошаговых `step_started`/`step_completed` в trace; один раз сбросить сводку. |
| **Вход** | Контекст workflow (`DocsExplainSummaryContext` или `DocsExplainFindFilesContext`). |
| **Выход** | Обновлённый контекст. |
| **Как работает** | Для каждого шага: `trace_input` до `run`, затем `run`, затем `trace_output`; записи копятся в список. В trace уходят `workflow_started`, затем `workflow_trace_flushed` с массивом шагов, затем `workflow_completed`. Статусы пользователю публикуются через `publisher` как и раньше. |

Код: `src/app/core/agent/processes/v2/workflows/v2_workflow_graph.py`.

---

## 4. Сборка в приложении

В `ModularApplication` создаются `RagSessionRetriever`, `V2RagRetrievalAdapter`, `V2RetrievalPolicyResolver`, `DocsEvidenceAssembler` и передаются в `V2Process` (см. `src/app/core/application.py`).

---

## 5. Итоговая концептуальная схема текущего MVP

В концептуальном виде текущий `v2` работает так:

1. **Session check**
   Проверка, что есть активная RAG-сессия проекта.

2. **LLM-first intent routing**
   Нормализация, extraction (`target_terms`, `anchors`), затем основной выбор маршрута через LLM.

3. **Deterministic validation + fallback**
   Проверка enum/комбинации маршрута и fallback только если LLM не ответил или вернул невалидный маршрут.

4. **Retrieval parameter planning**
   Формирование профиля поиска, слоёв и лимитов.

5. **RAG retrieval**
   Загрузка сырых строк из `DOCS RAG`.

6. **Minimal evidence assembly**
   Дедуп, базовый скоринг, отбор полезных summary или файлов.

7. **Task-focused workflow**
   Узкая ветка `SUMMARY` или `FIND_FILES`.

8. **Final response**
   Либо explanation через LLM, либо детерминированный список файлов.

Это и есть актуальная архитектура **узкого MVP**, синхронизированная с текущей реализацией.