# Текущая архитектура тестового пайплайна `pipeline_setup_v3`

Документ предназначен как краткое, но точное описание текущего устройства `pipeline_setup_v3` для внешней модели вроде ChatGPT.

Важно: текущий `pipeline_setup_v3` уже использует реальные runtime-компоненты агента, но по сути остается в первую очередь `code-first` пайплайном. Это особенно заметно в `evidence gate` и в наборе prompt'ов для LLM.

## 1. Общая схема пайплайна

`pipeline_setup_v3` запускает один из трех режимов:

- `router_only`
- `router_rag`
- `full_chain`

Во всех режимах используется `AgentRuntimeAdapter`, который является тестовым адаптером поверх реальных компонентов рантайма.

Общий поток для `full_chain`:

1. Пользовательский запрос
2. `IntentRouterV2`
3. Построение `RetrievalRequest`
4. `RuntimeRetrievalAdapter`
5. Построение нормализованного `RetrievalResult`
6. Сборка `EvidenceBundle`
7. `pre-evidence gate`
8. `RuntimeAnswerPolicy`
9. Вызов LLM через `AgentLlmService`
10. `post-evidence gate`
11. При необходимости `repair`
12. Сборка итогового результата, диагностики и артефактов теста

Ключевая идея: `pipeline_setup_v3` не эмулирует локальный тестовый сценарий вручную, а прогоняет реальные компоненты: роутер, retrieval, runtime executor и LLM.

## 2. Из каких компонентов состоит `pipeline_setup_v3`

### 2.1. Harness уровня тестов

Основные части:

- `tests/pipeline_setup_v3/run.py` — CLI-вход для запуска набора кейсов
- `tests/pipeline_setup_v3/core/runner.py` — оркестратор прогона кейсов
- `tests/pipeline_setup_v3/core/case_loader.py` — загрузка YAML-кейсов
- `tests/pipeline_setup_v3/core/validators.py` — проверка ожиданий
- `tests/pipeline_setup_v3/core/artifacts.py` — запись JSON/Markdown-результатов
- `tests/pipeline_setup_v3/runtime/agent_runtime_adapter.py` — мост к runtime-компонентам приложения

### 2.2. Runtime-компоненты, которые реально вызываются

- `IntentRouterV2`
- `RuntimeRepoContextFactory`
- `RuntimeRetrievalAdapter`
- `AgentRuntimeExecutor`
- `AgentLlmService`
- `PromptLoader`

### 2.3. Два варианта исполнения

#### `router_only`

Проверяет только результат роутера:

- `intent`
- `sub_intent`
- `graph_id`
- `conversation_mode`

RAG и LLM не вызываются.

#### `router_rag`

Проверяет:

- роутер
- retrieval plan
- реальный retrieval
- нормализованный `RetrievalResult`

LLM не вызывается.

#### `full_chain`

Проверяет полный runtime-контур:

- роутер
- retrieval
- evidence bundle
- pre-gate
- answer policy
- LLM
- post-gate
- repair
- итоговый answer/diagnostics

## 3. Компонент: Intent Router

### 3.1. Что это такое

`IntentRouterV2` классифицирует запрос и возвращает структурированный план для retrieval и дальнейшего рантайма.

Он не просто выбирает `intent`, а сразу строит:

- `conversation_mode`
- `query_plan`
- `retrieval_spec`
- `retrieval_constraints`
- `symbol_resolution`
- `evidence_policy`
- `graph_id`

### 3.2. Какие интенты есть сейчас

Сейчас в коде поддерживаются:

- `CODE_QA`
- `DOCUMENTATION_EXPLAIN`
- `GENERATE_DOCS_FROM_CODE`
- `FALLBACK`

### 3.3. Какие саб-интенты есть сейчас

#### Для `CODE_QA`

- `OPEN_FILE`
- `EXPLAIN`
- `EXPLAIN_LOCAL`
- `FIND_TESTS`
- `FIND_ENTRYPOINTS`
- `TRACE_FLOW`
- `ARCHITECTURE`
- `NEXT_STEPS` может появляться как follow-up режим на уровне query planning

#### Для `DOCUMENTATION_EXPLAIN`

- `SYSTEM_FLOW_EXPLAIN`
- `COMPONENT_EXPLAIN`
- `API_METHOD_EXPLAIN`
- `ENTITY_EXPLAIN`

#### Для `FALLBACK`

- `GENERIC_FALLBACK`

### 3.4. Что роутер возвращает на выходе

Результат роутера — это `IntentRouterResult`.

Ключевые поля:

- `intent`
- `retrieval_profile`
- `graph_id`
- `conversation_mode`
- `query_plan`
- `retrieval_spec`
- `retrieval_constraints`
- `symbol_resolution`
- `evidence_policy`

### 3.5. Что входит в `query_plan`

`query_plan` содержит:

- `raw`
- `normalized`
- `sub_intent`
- `negations`
- `expansions`
- `keyword_hints`
- `path_hints`
- `doc_scope_hints`
- `symbol_candidates`
- `symbol_kind_hint`
- `anchors`

Это основной bridge между классификацией запроса и retrieval.

### 3.6. Что входит в `retrieval_spec`

`retrieval_spec` содержит:

- `domains`
- `layer_queries`
- `filters`
- `rerank_profile`

Именно этот объект задает, какие слои RAG должны быть запрошены.

### 3.7. Что важно про текущее состояние

Текущий роутер уже умеет выделять docs-интенты и docs-сабинтенты, но downstream runtime ниже по пайплайну все еще во многом оптимизирован под `CODE_QA`.

Это означает:

- docs routing уже есть
- docs layer selection уже есть
- но `pre/post evidence gate` и prompt selection пока ориентированы в первую очередь на code sub-intents

## 4. Структура RAG

### 4.1. Общая идея

RAG устроен как многослойный индекс. Retrieval работает не по одному единственному типу чанков, а по наборам специализированных слоев.

### 4.2. Code-слои

- `C0_SOURCE_CHUNKS` — сырой код / чанки исходников
- `C1_SYMBOL_CATALOG` — каталог символов
- `C2_DEPENDENCY_GRAPH` — зависимости и связи
- `C3_ENTRYPOINTS` — точки входа, маршруты, handler'ы
- `C4_SEMANTIC_ROLES` — семантические роли и behavioral hints

### 4.3. Docs-слои

- `D0_DOC_CHUNKS` — чанки документов
- `D1_DOCUMENT_CATALOG` — каталог документов
- `D2_FACT_INDEX` — атомарные факты
- `D3_ENTITY_CATALOG` — сущности
- `D4_WORKFLOW_INDEX` — сценарии и workflow
- `D5_RELATION_GRAPH` — связи между документами

### 4.4. Как retrieval связывается с роутером

Роутер возвращает:

- `domains`
- `layer_queries`
- `filters`
- `retrieval_constraints`

Дальше `build_retrieval_request(...)` превращает это в `RetrievalRequest`, который содержит:

- `rag_session_id`
- `query`
- `sub_intent`
- `path_scope`
- `keyword_hints`
- `symbol_candidates`
- `requested_layers`
- `retrieval_spec`
- `retrieval_constraints`
- `query_plan`

### 4.5. Что возвращает retrieval

Сырые строки RAG затем нормализуются в `RetrievalResult`, который содержит:

- `target_symbol_candidates`
- `resolved_symbol`
- `symbol_resolution_status`
- `file_candidates`
- `code_chunks`
- `relations`
- `semantic_hints`
- `entrypoints`
- `test_candidates`
- `layer_outcomes`
- `missing_layers`
- `raw_rows`
- `retrieval_report`

### 4.6. Как из retrieval строится evidence

`build_evidence_bundle(...)` собирает `EvidenceBundle`.

Ключевые поля:

- `resolved_intent`
- `resolved_sub_intent`
- `resolved_target`
- `target_type`
- `target_symbol_candidates`
- `file_candidates`
- `code_chunks`
- `relations`
- `entrypoints`
- `test_evidence`
- `evidence_count`
- `sufficient`
- `failure_reasons`
- `retrieval_summary`

Важно: `evidence_count` сейчас считается по количеству `code_chunks`. Это еще одно подтверждение, что runtime сегодня code-first.

## 5. Evidence Gate

В пайплайне есть два gate'а.

## 5.1. Pre-evidence gate

Расположение:

- `src/app/modules/agent/runtime/steps/gates/pre/evidence_gate.py`

Когда срабатывает:

- после retrieval
- после сборки `EvidenceBundle`
- до вызова LLM

Задача:

- понять, достаточно ли evidence для уверенного ответа
- выдать `passed/failure_reasons/degraded_message`

Как работает сейчас:

- для `OPEN_FILE` требует найденный path/file и хотя бы один `C0` chunk
- для `EXPLAIN` требует target symbol и минимум 2 evidence chunk'а
- для `FIND_TESTS` требует target и хотя бы один test candidate
- для `FIND_ENTRYPOINTS` требует хотя бы один entrypoint
- для остальных сценариев требует минимум 1 evidence

Что возвращает:

- `passed`
- `failure_reasons`
- `degraded_message`

Ограничение:

- логика pre-gate пока написана в терминах code sub-intents
- docs-сценарии там явно не моделированы

## 5.2. Post-evidence gate

Расположение:

- `src/app/modules/agent/runtime/steps/gates/post/post_gate.py`

Когда срабатывает:

- после генерации draft answer
- до возврата финального ответа

Задача:

- проверить groundedness черновика
- убедиться, что ответ действительно опирается на evidence
- решить, нужен ли `repair`

Что проверяет:

- что ответ не пустой
- что degraded/not_found/ambiguous-ответы содержат обязательные guardrail-фразы
- что normal answer не слишком общий
- что упоминаются обязательные факты из curated evidence
- что нет явной semantic leakage или contradictions

Отдельные проверки есть для:

- `FIND_ENTRYPOINTS`
- `EXPLAIN`
- `ARCHITECTURE`
- `TRACE_FLOW`

Если gate не проходит, он возвращает:

- `passed=False`
- `action="repair"`
- список `reasons`

После этого runtime может сделать дополнительный шаг `repair` через LLM.

Ограничение:

- post-gate тоже пока ориентирован на code-oriented sub-intents
- docs-сабинтенты для него еще не описаны отдельными правилами

## 6. Обращение к LLM

### 6.1. Где вызывается LLM

В `pipeline_setup_v3` есть два места использования LLM:

1. В классификации интента внутри `IntentClassifierV2`
2. В финальной генерации ответа внутри `AgentRuntimeExecutor`

### 6.2. Prompt для классификации интента

Используется prompt:

- `rag_intent_router_v2`

Назначение:

- если deterministic rules не дали результата, LLM выбирает интент

Текущий prompt исторически описывает старые имена интентов, поэтому его еще нужно синхронизировать с новым docs/fallback контрактом.

### 6.3. Prompt'ы для генерации ответа

Prompt selector сейчас выбирает:

- `code_qa_architecture_answer`
- `code_qa_explain_answer`
- `code_qa_explain_local_answer`
- `code_qa_find_entrypoints_answer`
- `code_qa_find_tests_answer`
- `code_qa_general_answer`
- `code_qa_open_file_answer`
- `code_qa_trace_flow_answer`
- `code_qa_degraded_answer`

Дополнительно для repair используется:

- `code_qa_repair_answer`

### 6.4. Как строится payload для LLM

Перед вызовом LLM runtime собирает:

- `AnswerSynthesisInput`
- `EvidenceBundle`
- `prompt_payload`

В payload передаются:

- `user_question`
- `resolved_target`
- `answer_mode`
- `evidence_summary`
- `retrieval_summary`
- curated facts
- обязательные для упоминания сущности, методы, связи, шаги и т.д.

То есть LLM не получает просто "вопрос и куски текста", а получает уже структурированный grounded payload.

### 6.5. Что важно про текущее состояние prompt'ов

Сейчас runtime prompt selection и prompt contracts явно заточены под code QA.

Это значит:

- для `CODE_QA` full chain оформлен хорошо
- для `DOCUMENTATION_EXPLAIN` routing и retrieval есть, но отдельного docs answer-prompt слоя пока нет
- для docs full-chain пока не хватает собственных prompt names, prompt payload contract и post-gate правил

## 7. Что именно сейчас проверяет `pipeline_setup_v3`

YAML-кейс может проверять четыре группы ожиданий:

- `router`
- `retrieval`
- `llm`
- `pipeline`

Примеры ожиданий:

- ожидаемый `intent`
- ожидаемый `sub_intent`
- нужные слои в `layers_include`
- что retrieval не пустой
- что в answer есть нужные фразы
- какой `answer_mode` получился

## 8. Ключевые выводы о текущей архитектуре

### 8.1. Что уже сделано хорошо

- `pipeline_setup_v3` работает поверх реальных runtime-компонентов
- есть явный контракт между router → retrieval → evidence → answer
- есть два evidence gate
- есть structured diagnostics
- есть нормализованные типы `RetrievalRequest`, `RetrievalResult`, `EvidenceBundle`

### 8.2. Что остается code-first

- pre-evidence gate
- post-evidence gate
- prompt selector
- набор answer prompts
- часть логики нормализации evidence

### 8.3. Что это значит для docs use case

Сейчас docs use case уже частично внедрен:

- есть docs intent
- есть docs sub-intents
- есть docs layer mapping
- есть docs retrieval profile

Но для полноценного `full_chain` по документации еще не хватает:

- docs-oriented pre-gate правил
- docs-oriented post-gate правил
- docs-specific answer prompts
- docs-specific synthesis contract
- отдельных full-chain test cases для `DOCUMENTATION_EXPLAIN` и `FALLBACK`

## 9. Краткое резюме по компонентам

### Intent Router

Назначение:

- классифицировать запрос
- построить retrieval plan
- задать evidence policy

Выход:

- `IntentRouterResult`

### RAG

Назначение:

- вернуть evidence из многослойного индекса

Выход:

- `RetrievalResult`
- затем `EvidenceBundle`

### Pre-evidence gate

Назначение:

- решить, можно ли вообще уверенно отвечать

Выход:

- `passed/failure_reasons/degraded_message`

### Post-evidence gate

Назначение:

- проверить, grounded ли уже сгенерированный ответ

Выход:

- `return` или `repair`

### LLM

Назначение:

- классификация сложных интентов
- генерация финального ответа
- repair ответа при провале post-gate

Текущий фокус:

- в первую очередь `CODE_QA`