# Intent Router Specification (MVP) — v1.1
Version: 1.1  
Scope: Routing + query normalization + anchor extraction for layered RAG (CODE + DOCS)

---

## 1) Цель

Intent Router принимает:
- `user_query: string`
- `conversation_state: object`
- `repo_context: object` (язык/структура репо/доступные слои)

И возвращает:
- `intent`
- `graph_id`
- `conversation_mode`
- `query_plan` (нормализация + якоря)
- `retrieval_spec` (запрос по слоям RAG)
- `evidence_policy`

Router **не делает** retrieval и **не генерирует** ответ.

---

## 2) MVP интенты (строго 4)

- `CODE_QA` — объяснение/поиск по коду
- `DOCS_QA` — объяснение/поиск по документации
- `GENERATE_DOCS_FROM_CODE` — генерация документации по коду
- `PROJECT_MISC` — прочие вопросы по проекту

---

## 3) Диалоговый режим (контекст темы)

### 3.1 Политика
Router обязан сохранять intent в рамках темы.

- Если `conversation_state.active_intent` задан
- и нет явного сигнала смены темы
- то `intent = conversation_state.active_intent` и `conversation_mode = CONTINUE`

Смена intent допускается только если:
- есть явный сигнал смены домена/задачи, или
- новый запрос явно не соответствует текущему intent (жёсткое несоответствие)

---

## 4) Обязательная нормализация запроса и извлечение якорей

Router обязан выполнять:

### 4.1 Query normalization
Выход должен содержать:
- `raw` — исходный запрос
- `normalized` — каноническая, детерминированная и meaning-preserving форма `raw`
- `expansions[]` — добавочные токены для retrieval/rerank
- `keyword_hints[]` — компактные ключевые токены (символы/пути/доменные термины)

Требования:
- `raw` хранит исходную строку пользователя без изменений
- `normalized` строится **только** из `raw` и безопасных правил форматирования
- `normalized` не должен включать appended expansions, синонимы и догаданные keywords
- все enrichment должны жить только в `expansions[]`, `keyword_hints[]`, `anchors[]`

### 4.2 RU→EN mapping (минимальный словарь)
Router обязан поддерживать RU→EN mapping терминов только как `expansions`:

- `класс` → `class`
- `метод` → `method`
- `функция` → `function`, `def`
- `модуль` → `module`
- `пакет` → `package`
- `файл` → `file`
- `тест`, `юнит-тест` → `test`, `unit test`

Словарь должен быть расширяемым, но эти ключи обязательны.

### 4.3 Anchor extraction (якоря)
Router обязан извлекать **явные якоря** из user_query и conversation_state:

Типы якорей:
- `FILE_PATH` — путь/часть пути (`src/...`, `package/module.py`, `README.md`)
- `SYMBOL` — идентификатор (CamelCase, snake_case, dotted path)
- `DOC_REF` — ссылка на doc file/section (если есть явные маркеры)
- `KEY_TERM` — важные термины, влияющие на retrieval (класс/метод/функция и т.п.)

Каждый якорь должен возвращаться структурировано.

---

## 5) Контракт выхода Router

Top-level:

```json
{
  "schema_version": "1.1",
  "intent": "CODE_QA",
  "graph_id": "CodeQAGraph",
  "conversation_mode": "CONTINUE",
  "query_plan": {
    "raw": "",
    "normalized": "",
    "expansions": [],
    "keyword_hints": [],
    "anchors": []
  },
  "retrieval_spec": {
    "domains": [],
    "layer_queries": [],
    "filters": {},
    "rerank_profile": ""
  },
  "evidence_policy": {
    "require_def": false,
    "require_flow": false,
    "require_spec": false,
    "allow_answer_without_evidence": false
  }
}


## 6) query_plan.anchors контракт

{
  "type": "FILE_PATH | SYMBOL | DOC_REF | KEY_TERM",
  "value": "string",
  "subtype": "optional string",
  "span": { "start": 0, "end": 0 },
  "confidence": 0.0
}

Требования:
- FILE_PATH.value хранит путь как в запросе (без попытки “исправить”)
- SYMBOL.value хранит символ как в запросе (с сохранением регистра)
- KEY_TERM используется для выставления expected evidence и выбора слоёв
- anchors может быть пустым, но router должен пытаться извлечь их всегда


## 7) retrieval_spec контракт (слои + фильтры)

### 7.1 Структура

{
  "domains": ["CODE", "DOCS"],
  "layer_queries": [
    { "layer_id": "C1", "top_k": 30 },
    { "layer_id": "C3", "top_k": 15 }
  ],
  "filters": {
    "test_policy": "EXCLUDE",
    "path_scope": [],
    "language": []
  },
  "rerank_profile": "code"
}

## 7.2 Требования по intent

- CODE_QA → domains = ["CODE"], rerank_profile="code"
- DOCS_QA → domains = ["DOCS"], rerank_profile="docs"
- GENERATE_DOCS_FROM_CODE → domains = ["CODE"], rerank_profile="generate"
- PROJECT_MISC → domains = ["CODE","DOCS"], rerank_profile="project"

## 7.3 Требования по якорям

- Если найден FILE_PATH → router обязан добавить filters.path_scope (минимум: этот путь/директория)
- Если найден SYMBOL → router обязан добавить SYMBOL в query_plan.keyword_hints и query_plan.expansions (при необходимости)
- Если найден KEY_TERM (например "класс") → router обязан добавить RU→EN expansions

## 8) evidence_policy (минимальные требования)
{
  "require_def": true,
  "require_flow": true,
  "require_spec": false,
  "allow_answer_without_evidence": false
}

Требования:
- CODE_QA: require_def=true; require_flow=true
- DOCS_QA: require_spec=true
- GENERATE_DOCS_FROM_CODE: require_def=true
- PROJECT_MISC: allow_answer_without_evidence=true

## 9) Минимально обязательные поля (строго)

Router обязан всегда возвращать:
- intent
- graph_id
- conversation_mode
- query_plan.raw
- query_plan.normalized
- query_plan.expansions
- query_plan.anchors
- retrieval_spec.domains
- retrieval_spec.layer_queries
- retrieval_spec.filters.test_policy
- retrieval_spec.rerank_profile
- evidence_policy.*