# Runtime Integration Plan (question_mode=address_query)

Дата: 2026-03-29

## 1) Цель интеграции

Добавить отдельный runtime-контур для быстрых адресных запросов к 1С через MCP, не ломая существующий Stage 4 deep-analysis path.

## 2) As-Is (подтверждено кодом)

Текущий assistant pipeline:

1. normalizer -> route summary
2. execution plan по deep-routes
3. `assistantDataLayer.executeRouteRuntime(...)`
4. admissibility / eligibility guards
5. answer composer

Ключевые точки в текущем коде:

- `llm_normalizer/backend/src/services/assistantService.ts`
- `llm_normalizer/backend/src/services/routeHintAdapter.ts`
- `llm_normalizer/backend/src/services/assistantDataLayer.ts`
- `llm_normalizer/backend/src/services/assistantRuntimeGuards.ts`
- `llm_normalizer/backend/src/services/answerComposer.ts`

## 2.1) Architecture Reference (mandatory)

Перед любыми изменениями address lane сверяться с:

- `address_architecture_contract_v1.md`

Ключевая рамка:

- `Decompose -> Resolve -> Execute -> Compose`
- runtime не хранит company-specific словари
- company entities подтверждаются только через live resolver/MCP

## 3) To-Be: Separate Address Lane

Новый high-level flow:

1. Входящий вопрос.
2. L0 hybrid router: LLM decompose + deterministic fallback.
3. Mode-classifier: `address_query` | `deep_analysis` | `unsupported`.
4. Если `address_query`:
- resolve `address_intent`;
- extract+validate filters;
- select recipe;
- execute MCP (live-first);
- normalize result schema;
- return factual answer.
5. Если не `address_query`: текущий deep path без изменений.

## 3.1) L0 Hybrid Router (stabilization layer)

Назначение: убрать хрупкость на шумном пользовательском вводе (опечатки, сленг, лишние слова), не раздувая словари.

Порядок работы:

1. Сначала запускаем LLM decompose в строгий JSON-контракт.
2. Если LLM дал пустой/невалидный/неиспользуемый фрагмент, включается короткий deterministic fallback:
- триггеры по корням/подстрокам (не giant словарь словоформ);
- парсинг дат/периодов/счетов;
- шумоочистка (служебные слова, междометия, мусорные хвосты).
3. Если и fallback не дал валидный результат, возвращаем `LIMITED_WITH_REASON`, без выдумывания фактов.

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

- без company-specific словарей в runtime;
- без генерации SQL/1C-query в свободной форме;
- только интерпретация вопроса + передача в whitelist recipes.

## 4) Встраивание по слоям

### 4.1 Normalizer / Routing Layer

Изменения:

- добавить `question_mode` и `address_intent` в normalizer contract;
- добавить L0 router contract (decompose output + fallback reason);
- в `routeHintAdapter` добавить address-query rule set до deep route discipline.

Рекомендуемые файлы:

- `llm_normalizer/backend/src/types/normalizer.ts`
- `llm_normalizer/backend/src/services/routeHintAdapter.ts`

### 4.2 Assistant Service Orchestration

Изменения:

- в `AssistantService.processMessage(...)` добавить раннюю развилку по `question_mode`;
- для `address_query` запускать отдельный pipeline (без claim-bound deep-chain).

Рекомендуемый новый сервис:

- `llm_normalizer/backend/src/services/addressQueryService.ts`

### 4.3 Intent + Filter Extraction

Новые компоненты:

- `addressIntentResolver.ts`
- `addressFilterExtractor.ts`
- `addressFilterValidator.ts`

Выход контракта:

- `detected_mode`
- `detected_intent`
- `required_filters`
- `resolved_filters`
- `missing_filters`

### 4.4 Recipe Selection + MCP Execution

Новые компоненты:

- `addressRecipeCatalog.ts` (статический whitelist recipes)
- `addressRecipeSelector.ts`
- `addressMcpExecutor.ts`

Правила:

- только whitelist `recipe_id`;
- live-first; snapshot только explicit fallback;
- hard limit на строки и fixed sorting profile.

### 4.5 Result Materialization + Answer Composer

Новые компоненты:

- `addressResultMaterializer.ts`
- `addressAnswerComposer.ts`

Режимы ответа:

- `FACTUAL_LIST`
- `FACTUAL_SUMMARY`
- `LIMITED_WITH_REASON`

### 4.6 Debug/Trace Contract

Минимальный debug блок для address lane:

- `detected_mode`
- `detected_intent`
- `extracted_filters`
- `selected_recipe`
- `mcp_call_status`
- `rows_fetched`
- `rows_matched`
- `response_type`
- `llm_decomposition_attempted`
- `llm_decomposition_applied`
- `llm_decomposition_reason`
- `fallback_rule_hit`
- `sanitized_user_message`

## 5) Fallback Rules

- Если mode=`address_query`, но `missing_required_filters` -> `LIMITED_WITH_REASON` (без silent fallback в deep).
- Если mode=`address_query`, но `intent` не поддержан -> `LIMITED_WITH_REASON` или controlled handoff в deep-path с явной пометкой.
- Если live недоступен -> `LIMITED_WITH_REASON: live_unavailable`.

## 5.1) Compound factual scope (M2.1 real status)

- `COMPOUND_FACTUAL_QUERY` is currently **detection-only**.
- Runtime does **not** execute multi-intent decomposition yet.
- Current behavior for compound prompts:
  - one selected intent;
  - one selected recipe;
  - one factual/limited output block.
- Multi-step decomposition (`subquery planning -> per-subquery execution -> stitched composer`) is planned for V1.1.

## 6) Safety Guardrails

- Никакого free-form query generation от LLM.
- Query только через recipe whitelist.
- Все параметры проходят типовую и value-валидацию.
- Account anchors — только validated account tokens (исключая date/amount pollution).
- Read-only MCP profile для address lane.

## 7) Minimal Implementation Queue

1. `M0`: контракты (`question_mode`, `address_intent`, filter schema, recipe schema).
2. `M1`: classifier + resolver + validator (без MCP execution).
3. `M1.5`: L0 hybrid router (LLM-first + deterministic fallback) в shadow mode.
4. `M2`: MCP executor + 5 P0 recipe.
5. `M3`: factual composer + debug payload + basic tests.
6. `M4`: live rerun pack в `docs/ADDRESS/runs/...`.

## 7.2) L0 rollout policy

1. `Shadow`: LLM decompose не влияет на ответ, только trace/audit.
2. `Soft-enable`: LLM decompose влияет на routing только для P0 intents.
3. `Full-enable`: LLM decompose + fallback включены для всего `address_query`.

Правило безопасности:

- любой сбой LLM должен откатываться в deterministic fallback, а не в random behavior.

## 7.1) Sprint B priority order (adapted to current reality)

1. `documents_by_counterparty`
2. `bank_operations_by_counterparty`
3. `documents_forming_balance`
4. `documents_by_contract`
5. `bank_operations_by_contract`

Rationale:

- start from anchors with higher resolver stability (counterparty first);
- unlock early positive evidence before contract-heavy variants;
- keep contract scenarios behind anchor-resolution hardening.

## 8) Out of Scope for V1

- Новый proof engine.
- Расширение доменов beyond P0 address intents.
- Полный redesign deep-stage routing.
- Автоматический свободный доступ к произвольным сущностям 1С.

## 9) Expected Acceptance (V1)

- Deep-analysis path не деградировал.
- Address intents из P0 стабильно маршрутизируются в MCP/live-first lane.
- Factual-ответы по P0 сценариям возвращаются в предсказуемом формате.
- `false_factual_rate = 0`.
- Нет silent-degradation: при провале LLM есть explainable fallback reason.
- На шумном вводе нет ложного сдвига anchor (`counterparty`, `account`, `period`).