agent/_process/components/v2_intent_router_architecture.md

# V2IntentRouter Architecture

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

Текущий `V2IntentRouter` реализован как **LLM-first router**.
Deterministic-слой не выбирает маршрут по умолчанию и используется только для:

- preprocessing
- validation ответа LLM
- fallback, если LLM не ответил или вернул невалидный маршрут

Актуальные компоненты:

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

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

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

- `modules/anchors.py`
  Извлечение `anchors` и marker-сигналов для fallback и downstream retrieval.

- `routers/route_catalog.py`
  Каталог допустимых маршрутов (`allowed_routes`).

- `routers/llm.py`
  Основной LLM-router. Получает нормализованный запрос, `target_terms`, `anchors` и список допустимых маршрутов.

- `routers/validator.py`
  Deterministic validator для enum-значений, комбинации маршрута и базовой нормализации `confidence`.

- `routers/confidence.py`
  Пост-обработка confidence после ответа LLM.

- `routers/fallback.py`
  Fallback-маршрутизация, если LLM не ответил или ответ не прошёл validator.

- `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]`
- `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`

Эти маршруты централизованно заданы в `routers/route_catalog.py`.

## 4. Актуальный флоу

Пайплайн обработки запроса:

1. `router.py` принимает `user_query`.
2. `modules/normalizer.py` строит `normalized_query`.
3. `modules/target_terms.py` извлекает:
   - `target_terms`
   - `endpoint_paths`
   - `matched_aliases`
   - `alias_docs`
4. `modules/anchors.py` строит:
   - `anchors`
   - `file_markers`
   - `architecture_markers`
   - `logic_markers`
   - `domain_markers`
   - `endpoint_markers`
5. `router.py` собирает `QueryFeatures`.
6. `routers/llm.py` вызывается как **основной селектор маршрута**.
7. `routers/validator.py` проверяет:
   - что значения входят в допустимые enum
   - что комбинация маршрута разрешена
   - что `confidence` можно привести к `float`
8. `routers/confidence.py` корректирует confidence на основе силы сигналов.
9. Если ответ LLM валиден, возвращается `V2RouteResult` с `routing_mode="llm_default"`.
10. Если LLM не ответил, вернул сломанный JSON или невалидный маршрут, `routers/fallback.py` строит fallback route:
    - `FIND_FILES`, если есть `file_markers`
    - `DOCS / DOC_EXPLAIN / SUMMARY`, если есть docs-oriented anchors
    - иначе `GENERAL / GENERAL_QA / SUMMARY`

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

### `router.py`

- Задача
  Оркестрировать полный routing pipeline.

- Как решает
  Последовательно вызывает:
  - normalizer
  - target terms extractor
  - anchor extractor
  - LLM router
  - validator
  - confidence adjuster
  - fallback router

- Вход
  `user_query: str`

- Выход
  `V2RouteResult`

### `modules/normalizer.py`

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

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

- Вход
  `user_query: str`

- Выход
  `normalized_query: str`

### `modules/target_terms.py`

- Задача
  Построить **чистое retrieval-поле** `target_terms`.

- Как решает
  Использует позитивную модель отбора и включает в `target_terms` только:
  - endpoint paths
  - identifier-like tokens
  - alias canonical terms
  - domain terms

  Исключаются:
  - question words
  - intent words
  - filler/noisy words
  - marker words
  - короткие токены `< 3`, если это не endpoint или alias
  - битые path-like токены

  Дополнительно:
  - lowercase
  - trim punctuation по краям
  - dedupe
  - ограничение до `7` элементов
  - приоритет: endpoints → identifiers → aliases → domain terms

- Вход
  `normalized_query: str`

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

### `modules/anchors.py`

- Задача
  Построить `anchors` и marker-сигналы, не смешивая их с `target_terms`.

- Как решает
  Извлекает:
  - `entity_names` из PascalCase-like токенов
  - `file_names` только по жёстким правилам:
    - `*.md`, `*.yaml`, `*.yml`, `*.json`
    - `docs/...`, `doc/...`, `documentation/...`
  - `endpoint_paths` из `TargetTermsAnalysis`
  - `target_doc_hints` из alias docs, endpoint map и marker-сигналов

  Marker-сигналы живут отдельно:
  - `file_markers`
  - `architecture_markers`
  - `logic_markers`
  - `domain_markers`
  - `endpoint_markers`

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

- Выход
  `AnchorAnalysis`

### `routers/route_catalog.py`

- Задача
  Держать один источник истины для допустимых маршрутов.

- Как решает
  Возвращает:
  - список `allowed_routes` для payload LLM
  - проверку допустимости комбинации `routing_domain + intent + subintent`

### `routers/llm.py`

- Задача
  Выбрать маршрут через LLM как основной селектор.

- Как решает
  Формирует JSON payload из:
  - `normalized_query`
  - `target_terms`
  - `anchors`
  - `allowed_routes`

  Затем:
  - вызывает LLM
  - парсит JSON
  - возвращает сырой candidate route без deterministic business-routing

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

- Выход
  `dict | None`

### `routers/validator.py`

- Задача
  Deterministic validation ответа LLM.

- Как решает
  Проверяет:
  - что `routing_domain`, `intent`, `subintent` заполнены
  - что комбинация маршрута входит в `route_catalog`
  - что `confidence` можно привести к числу

- Вход
  `dict | None`

- Выход
  Валидированный `dict | None`

### `routers/confidence.py`

- Задача
  Сделать confidence осмысленным после ответа LLM.

- Как решает
  Корректирует confidence:
  - `-0.1`, если нет strong anchors
  - `-0.1`, если запрос короткий или vague
  - `+0.05`, если есть явный signal (`file_markers`, `endpoint_paths`, `endpoint_markers`)
  - затем clamp в диапазон `0.0..1.0`

- Вход
  - `confidence: float`
  - `QueryFeatures`

- Выход
  `confidence: float`

### `routers/fallback.py`

- Задача
  Построить deterministic fallback, если LLM невалиден.

- Как решает
  Правила:
  - есть `file_markers` → `DOCS / DOC_EXPLAIN / FIND_FILES`
  - есть docs-signals (`endpoint_paths`, `target_doc_hints`, `matched_aliases`, marker groups) → `DOCS / DOC_EXPLAIN / SUMMARY`
  - иначе → `GENERAL / GENERAL_QA / SUMMARY`

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

- Выход
  `V2RouteResult`

### `routers/prompts.yml`

- Задача
  Задать LLM-router контракт ответа и guidance по confidence.

- Как решает
  Ограничивает модель только `allowed_routes` и требует JSON с полями:
  - `routing_domain`
  - `intent`
  - `subintent`
  - `confidence`
  - `reason_short`

## 6. Ключевые инварианты

- LLM является default router.
- Deterministic-слой не принимает основной routing decision.
- `target_terms` содержат только retrieval-useful terms.
- `anchors` не содержат `terms`.
- `/health` и другие endpoint paths не должны попадать в `file_names`, если это не файл с расширением.
- `file_names` содержат только реальные file/doc paths.
- Fallback используется только если LLM недоступен или вернул невалидный маршрут.