АДРЕСНЫЙ РЕЖИМ - локальная подель на декомпозе
This commit is contained in:
@@ -9,6 +9,7 @@
|
||||
- `query_recipes_v1.md` - каталог фильтров и recipe-контракты.
|
||||
- `runtime_integration_plan.md` - план встраивания `question_mode=address_query`.
|
||||
- `address_runtime_contracts.md` - контракты runtime/debug/result для address lane.
|
||||
- `address_architecture_contract_v1.md` - архитектурные границы `Decompose -> Resolve -> Execute -> Compose` и политика data-agnostic runtime.
|
||||
- `runtime_readiness_matrix_v1.md` - матрица structural vs runtime readiness.
|
||||
- `known_positive_live_suite_v1.md` - базовый template positive-evidence suite.
|
||||
- `data_aware_positive_acceptance_suite_v1.md` - M2.3 canonical guide для curated live acceptance.
|
||||
@@ -23,4 +24,5 @@
|
||||
- `docs/ADDRESS/runs/2026-03-29_Address_Query_Runtime_V1_M2_3A_Stage_Diagnostic_Materialization/`
|
||||
- `docs/ADDRESS/runs/2026-03-29_Address_Query_Runtime_V1_M2_3B_AccountScope_Mode_Tuning/`
|
||||
- `docs/ADDRESS/runs/2026-03-29_Address_Query_Runtime_V1_M2_3C_Resolver_Filter_Tuning_And_AccountScope_Audit/`
|
||||
- `docs/ADDRESS/runs/2026-04-01_Address_Query_Runtime_V1_M2_3D_Query_Variants_Expansion/`
|
||||
|
||||
|
||||
@@ -0,0 +1,154 @@
|
||||
# Address Architecture Contract V1
|
||||
|
||||
Дата: 2026-04-01
|
||||
|
||||
## 1) Зачем документ
|
||||
|
||||
Этот контракт фиксирует архитектурные границы `address_query`-контура, чтобы система оставалась переносимой между разными 1С-базами и не обрастала company-specific логикой.
|
||||
|
||||
Контракт обязателен для всех следующих инкрементов (`M2.4+`), рефакторов и новых intent/recipe.
|
||||
|
||||
## 2) Непересекаемые принципы
|
||||
|
||||
- `MCP/live-first`: основной источник фактов - live MCP.
|
||||
- `MSP-only` в runtime: production path работает через MCP/MSP; snapshot - только controlled fallback.
|
||||
- `snapshot` допускается только как явный fallback с reason code, а не как скрытая подмена.
|
||||
- `runtime = data-agnostic`: никаких хардкодов под конкретную компанию.
|
||||
- `acceptance = data-aware`: positive-кейсы можно подбирать на текущей базе только для проверки.
|
||||
- `false_factual_rate = 0`: factual-ответ только при подтвержденных `rows_matched > 0`.
|
||||
- `whitelist execution only`: никаких свободных NL->query генераторов.
|
||||
|
||||
## 3) Канонический pipeline
|
||||
|
||||
## Stage A: Decompose
|
||||
|
||||
Назначение: интерпретация текста вопроса, без обращения к данным компании.
|
||||
|
||||
Выход stage:
|
||||
|
||||
- `question_mode`
|
||||
- `query_shape`
|
||||
- `intent_candidates`
|
||||
- `anchors_raw`
|
||||
- `time_scope_raw`
|
||||
- `filters_raw`
|
||||
- `decomposition_plan` (опционально, для compound)
|
||||
|
||||
Запрещено на этапе Decompose:
|
||||
|
||||
- резолвить реальные объекты базы (контрагентов, договоры, документы);
|
||||
- тянуть company-specific словари;
|
||||
- генерировать запросы к 1С.
|
||||
|
||||
## Stage B: Resolve
|
||||
|
||||
Назначение: привязка raw-якорей к живым объектам через MCP.
|
||||
|
||||
Выход stage:
|
||||
|
||||
- `anchor_type`
|
||||
- `anchor_value_raw`
|
||||
- `anchor_value_resolved`
|
||||
- `resolver_confidence`
|
||||
- `ambiguity_count`
|
||||
|
||||
Правило:
|
||||
|
||||
- если якорь не подтвержден, runtime не выдумывает факт и идет в `LIMITED_WITH_REASON`.
|
||||
|
||||
## Stage C: Execute
|
||||
|
||||
Назначение: выполнение только через recipe whitelist.
|
||||
|
||||
Правила:
|
||||
|
||||
- `intent -> recipe_id` только из каталога;
|
||||
- fixed `limit/sort/window` политика;
|
||||
- `MCP` read-only;
|
||||
- `MSP/MCP-only` execution path в production;
|
||||
- snapshot fallback только явный.
|
||||
|
||||
Диагностика по стадиям:
|
||||
|
||||
- `no_raw_rows`
|
||||
- `raw_rows_received_but_not_materialized`
|
||||
- `materialized_but_not_anchor_matched`
|
||||
- `materialized_but_filtered_out_by_recipe`
|
||||
- `matched_non_empty`
|
||||
- `error`
|
||||
|
||||
## Stage D: Compose
|
||||
|
||||
Назначение: финальный ответ строго по execution-результату.
|
||||
|
||||
Правила:
|
||||
|
||||
- factual только из `rows_matched`;
|
||||
- если пусто - `LIMITED_WITH_REASON` с конкретной причиной;
|
||||
- без reasoning-галлюцинаций и без “догадки по смыслу”.
|
||||
|
||||
## 4) Политика словарей
|
||||
|
||||
Разрешено (статически в коде):
|
||||
|
||||
- доменная типовая лексика (`доки`, `остаток`, `договор`, `дебиторка` и т.д.);
|
||||
- правила парсинга дат/периодов/счетов;
|
||||
- stop-слова и служебные alias-правила.
|
||||
|
||||
Запрещено:
|
||||
|
||||
- хранить в коде списки компаний, ИНН, договоров, документов конкретной базы;
|
||||
- пополнять глобальные normalization-библиотеки живыми entity-именами;
|
||||
- строить скрытые “памяти компании” вне runtime-сессии.
|
||||
|
||||
Допустимо:
|
||||
|
||||
- использовать runtime-сессионный контекст диалога (`followup context`) без записи в глобальные словари.
|
||||
|
||||
## 5) Критерии переносимости между компаниями
|
||||
|
||||
Система считается переносимой, если:
|
||||
|
||||
- новая база подключается без code change в resolver/intent logic;
|
||||
- меняются только live-данные MCP, а не кодовые словари;
|
||||
- question-bank остается валиден (с ожидаемыми различиями factual/limited по данным).
|
||||
|
||||
## 6) Антипаттерны (нельзя делать)
|
||||
|
||||
- Добавлять company alias map в `src/services/*` с реальными названиями контрагентов.
|
||||
- Перекладывать проблему резолвинга в hardcoded `if company == ...`.
|
||||
- Подмешивать deep-analysis ответ в address factual-блок без явного route handoff.
|
||||
- Поднимать “временные” exceptions, которые ломают stage-контракт.
|
||||
|
||||
## 7) Техническая дисциплина кода
|
||||
|
||||
Новая логика должна ложиться в явные stage-модули:
|
||||
|
||||
- decompose
|
||||
- resolve
|
||||
- execute
|
||||
- compose
|
||||
- diagnostics
|
||||
|
||||
Если функция не относится к stage - это smell и повод к вынесению.
|
||||
|
||||
## 8) Как подключать LLM decompose
|
||||
|
||||
LLM на первом этапе нужен не для “знания компании”, а для структурной интерпретации вопроса.
|
||||
|
||||
LLM должен возвращать схему-stage-output:
|
||||
|
||||
- intent candidates
|
||||
- shape
|
||||
- anchor spans
|
||||
- time scope
|
||||
- filter hints
|
||||
- confidence
|
||||
|
||||
Дальше все company-specific подтверждается только Resolver/Execute через MCP.
|
||||
|
||||
Итог:
|
||||
|
||||
- LLM decompose уменьшает NLP-хрупкость;
|
||||
- не требует жирных живых словарей компаний;
|
||||
- не нарушает data-agnostic принцип runtime.
|
||||
@@ -2,11 +2,18 @@
|
||||
|
||||
Дата: 2026-03-29
|
||||
|
||||
Reference:
|
||||
|
||||
- `address_architecture_contract_v1.md` (architecture guardrails and stage boundaries).
|
||||
|
||||
## Runtime Policy
|
||||
|
||||
- Runtime lane is `data-agnostic`: no hardcoded counterparties/contracts/accounts from one concrete base.
|
||||
- Acceptance lane is `data-aware`: positive cases are curated after exploratory live pass.
|
||||
- Address lane remains MCP/live-first, whitelist-only, read-only.
|
||||
- Runtime execution is MSP-only in production; snapshot usage is explicit fallback only.
|
||||
- Canonical pipeline boundary: `Decompose -> Resolve -> Execute -> Compose` (no cross-stage leakage).
|
||||
- LLM decompose stage interprets question structure only; company entities are resolved only in live resolver stage.
|
||||
|
||||
## Input Contract
|
||||
|
||||
|
||||
Binary file not shown.
@@ -10,6 +10,9 @@
|
||||
- какие хвосты висят по договору
|
||||
- у кого самый большой долг перед нами
|
||||
- кому больше всего должны мы
|
||||
- покажи дебиторку по контрагентам на дату
|
||||
- покажи кредиторку по поставщикам на дату
|
||||
- что висит по взаиморасчетам на текущую дату
|
||||
|
||||
## B. Счета и остатки
|
||||
|
||||
@@ -18,6 +21,9 @@
|
||||
- что висит на 60 счете
|
||||
- какие документы формируют остаток по 62
|
||||
- оборот по 60 за период
|
||||
- раскрой остаток по счету 62 до документов
|
||||
- покажи сальдо по счету 60.01 на дату
|
||||
- из чего сложился остаток по 76 счету
|
||||
|
||||
## C. Договоры
|
||||
|
||||
@@ -25,6 +31,9 @@
|
||||
- что по договору 15/24
|
||||
- есть ли долг по договору с Альфой
|
||||
- какие документы связаны с этим договором
|
||||
- покажи незакрытые договоры по контрагенту
|
||||
- какие хвосты по договору №15/24 на дату
|
||||
- есть ли открытые позиции по договору
|
||||
|
||||
## D. Документы
|
||||
|
||||
@@ -32,6 +41,9 @@
|
||||
- покажи документы по договору за период
|
||||
- найди документ по номеру и дате
|
||||
- покажи проведенные документы по организации
|
||||
- какие документы доступны по компании СВК за 2021 год
|
||||
- выведи документы по клиенту Бета за июль 2020
|
||||
- покажи документы по поставщику Альфа за весь период
|
||||
|
||||
## E. Bank/Payment lookup
|
||||
|
||||
@@ -39,24 +51,33 @@
|
||||
- были ли поступления от Беты
|
||||
- покажи списания с расчетного счета по договору
|
||||
- найди оплату на сумму 150000
|
||||
- покажи банковские операции по контрагенту Альфа
|
||||
- покажи поступления и списания по клиенту Бета
|
||||
- выведи bank operations by counterparty Alfa for all time
|
||||
|
||||
## F. Drilldown
|
||||
|
||||
- кто должен нам и какие документы это формируют
|
||||
- что висит по Альфе и раскрой по документам
|
||||
- по 60 счету что висит и раскрой по контрагентам
|
||||
- какие документы формируют остаток по счету 62 на 2020-07-31
|
||||
- расшифруй остаток по 60 счету до документов
|
||||
|
||||
## G. Составные factual вопросы
|
||||
|
||||
- покажи хвосты по Альфе и отдельно по Бете
|
||||
- кто должен нам и отдельно кому должны мы
|
||||
- найди долг по договору и покажи документы
|
||||
- покажи документы по контрагенту и сразу банковские операции
|
||||
- остаток по счету 60 и какие документы его формируют
|
||||
|
||||
## H. Check/verify (still factual)
|
||||
|
||||
- проверь, есть ли долг по Альфе
|
||||
- проверь, есть ли незакрытые документы
|
||||
- проверь, что висит на 60 счете
|
||||
- проверь, есть ли открытые позиции по договору
|
||||
- проверь, есть ли документы по контрагенту за июль 2020
|
||||
|
||||
## Правило маршрутизации
|
||||
|
||||
|
||||
@@ -24,6 +24,18 @@
|
||||
- `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:
|
||||
|
||||
Reference in New Issue
Block a user