NODEDC_1C/docs/ADDRESS/address_query/runtime_integration_plan.md

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).