agent/_process/components/v2_intent_router_architecture.md

# V2IntentRouter Architecture

## 1. Архитектура

Текущий `V2IntentRouter` состоит из следующих компонентов:

- `router.py`
  Главная точка входа и оркестратор.

- `modules/normalizer.py`
  Нормализация текста запроса в `normalized_query`.

- `modules/target_terms.py`
  Извлечение `target_terms`, `endpoint_paths`, `matched_aliases`, `alias_docs`.

- `modules/anchors.py`
  Извлечение `anchors` и вспомогательных marker-сигналов.

- `routers/docs_subintent_resolver.py`
  Определение `subintent`.

- `routers/deterministic.py`
  Детерминированное определение `routing_domain`, `intent`, `subintent`, `confidence`, `routing_mode`, `llm_router_used`, `reason_short`.

- `routers/llm.py`
  LLM-based определение `routing_domain`, `intent`, `subintent`, `confidence`, `reason_short`.

- `routers/prompts.yml`
  Prompt для LLM-router.

## 2. Контракт

### Вход

- `user_query: str`

### Выход

`V2RouteResult`:

- `routing_domain: str`
- `intent: str`
- `subintent: str`
- `user_query: str`
- `normalized_query: str`
- `target_terms: list[str]`
- `anchors: V2RouteAnchors`
- `confidence: float`
- `routing_mode: str`
- `llm_router_used: bool`
- `reason_short: str`

`V2RouteAnchors`:

- `entity_names: list[str]`
- `terms: list[str]`
- `file_names: list[str]`
- `endpoint_paths: list[str]`
- `target_doc_hints: list[str]`
- `matched_aliases: list[str]`
- `process_domain: str | None`
- `process_subdomain: str | None`

## 3. Поддерживаемые домены, интенты и сабинтенты

### Домены

- `DOCS`
- `GENERAL`

### Интенты

- `DOC_EXPLAIN`
- `GENERAL_QA`

### Сабинтенты

- `SUMMARY`
- `FIND_FILES`

### Поддерживаемые маршруты

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

## 4. Флоу обработки запроса

1. `router.py` принимает `user_query`.
2. `modules/normalizer.py` строит `normalized_query`.
3. `modules/target_terms.py` извлекает ключевые термы и alias-based сигналы.
4. `modules/anchors.py` строит `anchors` и marker-сигналы.
5. `router.py` собирает `QueryFeatures`.
6. `routers/deterministic.py` пытается определить маршрут детерминированно.
7. Если deterministic route найден, он сразу возвращается.
8. Если deterministic route не найден, `router.py` вызывает `routers/llm.py`.
9. Если LLM вернул валидный маршрут, собирается `V2RouteResult` с `routing_mode="llm_assisted"`.
10. Если LLM недоступен или не вернул валидный маршрут, используется fallback:
    `GENERAL / GENERAL_QA / SUMMARY` с `routing_mode="llm_fallback"`.

## 5. Компоненты по флоу

### `router.py`

- Задача
  Собрать весь процесс роутинга в одной входной точке.

- Как решает
  Последовательно вызывает normalizer, target terms extractor, anchors extractor, deterministic router и при необходимости LLM router.

- Вход
  `user_query: str`

- Выход
  `V2RouteResult`

### `modules/normalizer.py`

- Задача
  Привести запрос к стабильной форме для дальнейшего анализа.

- Как решает
  Схлопывает лишние пробелы через `" ".join(...split())`.

- Вход
  `user_query: str`

- Выход
  `normalized_query: str`

### `modules/target_terms.py`

- Задача
  Выделить ключевые термы и retrieval-сигналы из запроса.

- Как решает
  Использует:
  - regex для path/entity-like фрагментов
  - список stop-words
  - alias rules с фразами и каноническими термами
  - эвристику для `/health`

- Вход
  `normalized_query: str`

- Выход
  `TargetTermsAnalysis`:
  - `target_terms`
  - `endpoint_paths`
  - `matched_aliases`
  - `alias_docs`

### `modules/anchors.py`

- Задача
  Построить полный набор `anchors` и doc-oriented marker-сигналов.

- Как решает
  Использует:
  - regex для `entity_names` и `file_names`
  - словари marker-фраз:
    - file markers
    - architecture markers
    - logic markers
    - domain markers
    - endpoint markers
  - map `endpoint -> target_doc_hint`
  - alias docs из `TargetTermsAnalysis`

- Вход
  - `normalized_query: str`
  - `TargetTermsAnalysis`

- Выход
  `AnchorAnalysis`:
  - `anchors`
  - `file_markers`
  - `architecture_markers`
  - `logic_markers`
  - `domain_markers`
  - `endpoint_markers`

### `routers/docs_subintent_resolver.py`

- Задача
  Определить `subintent`.

- Как решает
  Эвристика:
  - если есть `file_markers` -> `FIND_FILES`
  - если есть doc-signals (`endpoint_paths`, `endpoint_markers`, `architecture_markers`, `logic_markers`, `domain_markers`, `target_doc_hints`) -> `SUMMARY`
  - иначе `None`

- Вход
  `QueryFeatures`

- Выход
  `subintent: str | None`

### `routers/deterministic.py`

- Задача
  Детерминированно определить маршрут без LLM там, где это возможно.

- Как решает
  Использует:
  - `DocsSubintentResolver`
  - проверку conflicting doc anchors
  - список general markers

  Правила:
  - `FIND_FILES` -> `DOCS / DOC_EXPLAIN / FIND_FILES`
  - `subintent != None` и нет конфликта doc-signals -> `DOCS / DOC_EXPLAIN / SUMMARY`
  - general marker -> `GENERAL / GENERAL_QA / SUMMARY`

- Вход
  - `user_query: str`
  - `QueryFeatures`
  - `anchors: V2RouteAnchors`

- Выход
  `V2RouteResult | None`

### `routers/llm.py`

- Задача
  Определить маршрут через LLM, если deterministic routing не дал результата.

- Как решает
  Формирует JSON payload из:
  - `user_query`
  - `normalized_query`
  - `target_terms`
  - `anchors`
  - списка допустимых маршрутов

  Затем:
  - вызывает LLM
  - парсит JSON
  - валидирует маршрут по whitelist
  - нормализует `confidence`

- Вход
  - `user_query: str`
  - `normalized_query: str`
  - `target_terms: list[str]`
  - `anchors: dict`

- Выход
  `dict | None`:
  - `routing_domain`
  - `intent`
  - `subintent`
  - `confidence`
  - `reason_short`

### `routers/prompts.yml`

- Задача
  Задать LLM-router формальный контракт ответа.

- Как решает
  Описывает допустимые маршруты и требует вернуть только JSON.

- Вход
  Payload от `routers/llm.py`

- Выход
  Структурированный JSON-ответ LLM