160 lines
13 KiB
Markdown
160 lines
13 KiB
Markdown
# ADDRESS Query Docs
|
||
|
||
Дата: 2026-04-13
|
||
Статус синхронизации: актуализировано по текущему коду в `llm_normalizer/backend/src/services/*`.
|
||
|
||
## Актуальный статус (2026-04-13)
|
||
|
||
- Этап стабилизации закрыт под `strict_policy=route`.
|
||
- Step-0 pre-prod rails закрыт (reference-domain + nightly automation).
|
||
- Этап 3 (универсализация value-вопросов общего домена) закрыт на уровне кода и targeted-тестов.
|
||
- Batch-1 domain live-gate закрыт: `strict 28/28`
|
||
`docs/ADDRESS/runs/2026-04-03_Address_Domain_General_B1_PhaseC_LiveGate_R3/run_summary.json`
|
||
- Batch-3 value live-gate закрыт: `strict 33/33`
|
||
`docs/ADDRESS/runs/2026-04-03_Address_Domain_General_B3_Value_LiveGate_R2/run_summary.json`
|
||
- Global nightly comparator после фиксов закрыт (`overall_ok=true`, comparator PASS):
|
||
`docs/ADDRESS/runs/2026-04-03_Address_Nightly_Regression_Post_AnchorHardening_R6/nightly_summary.json`
|
||
- Ручной контрольный nightly (`2026-04-08 10:29`) зафиксировал точечный flake:
|
||
- `stress_102`: `101/102` (провал `S019`, `materialized_but_not_anchor_matched`)
|
||
- `followup_25`: `25/25`
|
||
- run: `docs/ADDRESS/runs/2026-04-08_Address_Nightly_Regression_2026-04-08_10-29-08/nightly_summary.json`
|
||
- Повторный контрольный nightly (`2026-04-08 10:51`) закрыт в `PASS`:
|
||
- `stress_102`: `102/102`
|
||
- `followup_25`: `25/25`
|
||
- comparator: `PASS`
|
||
- run: `docs/ADDRESS/runs/2026-04-08_Address_Nightly_Regression_2026-04-08_10-51-20/nightly_summary.json`
|
||
- Batch-2 lifecycle закрыт до `Phase C` (domain + global gates PASS):
|
||
- domain card: `domain_general_batch2_lifecycle_card_v1.md`
|
||
- backlog closeout: `step4_wave1_batch2_phaseA_backlog_v1.md`
|
||
- domain live-gate: `docs/ADDRESS/runs/2026-04-08_Address_Batch2_Lifecycle_FullGate_PhaseC_PostFix2/run_summary.json` (`strict 36/36`)
|
||
- targeted code gate: `addressQueryRuntimeM23.test.ts + assistantAddressFollowupContext.test.ts = 223/223`, `build=PASS`
|
||
- global non-regression: `docs/ADDRESS/runs/2026-04-08_Address_Nightly_Regression_2026-04-08_13-19-24/nightly_summary.json` (`stress 102/102`, `followup 25/25`, comparator PASS)
|
||
- Принят `domain scope freeze`: новые домены временно не расширяем; фокус смещен на Step-5 (архитектура + UX + качество ответов).
|
||
- Step-5 bootstrap (2026-04-08):
|
||
- UX compose first-line direct-answer patch внедрен;
|
||
- targeted tests: `220/220 + 3/3`;
|
||
- live smoke: `docs/ADDRESS/runs/2026-04-08_Address_Step5_UX_Smoke_v2/run_summary.json` (`strict 6/6`).
|
||
- Step-5 living router increment (2026-04-08):
|
||
- added `FEATURE_ASSISTANT_LIVING_CHAT_ROUTER_V1` (default `true`);
|
||
- added chat mode (`chat`) for non-data conversational messages with safe fallback to deep pipeline;
|
||
- added OpenAI-compatible `chat()` in `OpenAIResponsesClient` (with local `/responses` -> `/chat/completions` fallback).
|
||
- Финальный stress-pack: `102/102`
|
||
`docs/ADDRESS/runs/2026-04-02_Address_Slang_Live_Stress_2026-04-02_12-57-27/run_summary.json`
|
||
- Финальный follow-up pack: `25/25`
|
||
`docs/ADDRESS/runs/2026-04-02_Address_Followup_Context_Chains_2026-04-02_19-15-Run5/run_summary.json`
|
||
- Актуальный nightly regression (green):
|
||
`docs/ADDRESS/runs/2026-04-08_Address_Nightly_Regression_2026-04-08_13-19-24/nightly_summary.json`
|
||
- Task Scheduler: `NDC_ADDRESS_Nightly_Regression` временно `Disabled` (ручной режим до стабилизации infra-канала).
|
||
- Текущий production-контур: `question_mode=address_query`, live-first через MCP.
|
||
- Следующий этап: `Step-5` Architecture + UX Quality (LLM-first валидация входа, улучшение пользовательского ответа, без расширения domain scope).
|
||
- Contracts domain increment (2026-04-13):
|
||
- прямой вопрос об открытых договорах теперь идет в exact-capability `open_contracts_confirmed_as_of_date`;
|
||
- heuristic `list_open_contracts` сохранен как diagnostic-only слой;
|
||
- business-view exact-ответа усилен через `net/gross`, split `special_valid` vs `dirty_unresolved` и разрез компонентных остатков.
|
||
|
||
## Что реально реализовано в коде (срез 2026-04-13)
|
||
|
||
Поддерживаемые intents в runtime:
|
||
|
||
- `period_coverage_profile` (Wave-1 B1, gate-closed)
|
||
- `document_type_and_account_section_profile` (Wave-1 B1, pre-gate)
|
||
- `counterparty_population_and_roles` (Wave-1 B1, pre-gate)
|
||
- `counterparty_activity_lifecycle` (Wave-1 B2, gate-closed)
|
||
- `contract_usage_overview` (Wave-1 B1, gate-closed)
|
||
- `customer_revenue_and_payments` (Wave-1 B3 value, gate-closed)
|
||
- `supplier_payouts_profile` (Wave-1 B3 value, gate-closed)
|
||
- `contract_usage_and_value` (Wave-1 B3 value, gate-closed)
|
||
- `open_contracts_confirmed_as_of_date`
|
||
- `list_open_contracts` (diagnostic heuristic)
|
||
- `list_payables_counterparties`
|
||
- `list_receivables_counterparties`
|
||
- `account_balance_snapshot`
|
||
- `open_items_by_counterparty_or_contract`
|
||
- `list_documents_by_counterparty`
|
||
- `bank_operations_by_counterparty`
|
||
- `list_documents_by_contract`
|
||
- `bank_operations_by_contract`
|
||
- `documents_forming_balance`
|
||
|
||
Ключевой scope-лимит:
|
||
|
||
- `COMPOUND_FACTUAL_QUERY` пока detection-only (без multi-intent execution).
|
||
- management/value intents реализованы в коде и закрыты через domain live-gate (Batch-1/Batch-3).
|
||
- глобальный comparator на `102 + 25` закрыт в `PASS` (nightly R6).
|
||
- для value-ranking ответов действует дефолт: `top-20` (если пользователь явно не запросил другой лимит).
|
||
- `account_turnover_snapshot` и `list_documents_by_type` не реализованы в runtime V1.
|
||
|
||
## Основные документы
|
||
|
||
- `address_scenario_matrix.md` - актуальная матрица сценариев `question -> intent -> recipe_id`.
|
||
- `query_recipes_v1.md` - фактический каталог runtime recipes и их контрактов.
|
||
- `../../TECH/address_open_contracts_confirmed_as_of_date_spec.md` - exact-spec для домена открытых договоров на дату.
|
||
- `runtime_readiness_matrix_v1.md` - статус готовности сценариев по текущему коду.
|
||
- `address_runtime_contracts.md` - актуальный debug/output контракт address lane.
|
||
- `runtime_integration_plan.md` - фактическая схема интеграции в `assistantService`.
|
||
- `address_architecture_contract_v1.md` - guardrails `Decompose -> Resolve -> Execute -> Compose`.
|
||
- `global_execution_checklist_v1.md` - release-gate и шаги этапа.
|
||
- `stage_closeout_2026-04-02.md` - закрытие этапа стабилизации.
|
||
- `step0_preprod_rail_plan_v1.md` - обязательный pre-prod рельсовый этап перед массовым расширением доменов.
|
||
- `step0_closeout_2026-04-02.md` - факт закрытия Step-0 с артефактами и gate-подтверждением.
|
||
- `domain_expansion_implementation_plan_v1.md` - план `Step-4`.
|
||
- `step5_architecture_ux_quality_plan_v1_2026-04-08.md` - план `Step-5` (LLM-first input validation, UX, качество ответов).
|
||
- `general_domain_questions_analysis_plan_v1_2026-04-02.md` - глубокий разбор общего домена (40 вопросов), route-модель и batch-план внедрения.
|
||
- `management_route_probe_report_g1_2026-04-02.md` - live Batch-0 probe по первой группе общего домена (Q1–Q5) с route-верификацией через MCP/1С.
|
||
- `complex_questions_status_and_reuse_map_2026-04-02.md` - сверка кода/доков по "сложным вопросам": что реализовано, что detection-only, и как переиспользовать в продуктовом плане.
|
||
- `step4_wave1_batch1_master_checker_v1.md` - master checker первой волны Step-4 (`Q1..Q7 + Q28`) с go/no-go фазами.
|
||
- `wave1_batch1_readiness_report_2026-04-02.md` - авто-отчет готовности к старту Batch-1.
|
||
- `stage3_value_universalization_closeout_2026-04-03.md` - закрытие этапа 3 по value-вопросам общего домена (профит, тестовый gate, остаточные риски).
|
||
- `wave1_batch1_batch3_live_gate_report_2026-04-03.md` - фактический отчет по live-gate Batch-1/Batch-3 и статусу глобального regression/comparator (PASS в R6).
|
||
- `project_status_rails_graph_2026-04-08.md` - визуальный граф текущего статуса рельсов (закрытые гейты, operational-контур, точка входа в Batch-2).
|
||
- `domain_general_batch2_lifecycle_card_v1.md` - domain card для Batch-2 lifecycle (`Q8..Q13 + Q26 + Q27 + Q31 + Q32`).
|
||
- `wave1_batch2_phaseA_probe_report_2026-04-08.md` - baseline probe Batch-2 с фактическими gap-ами перед Phase B.
|
||
- `step4_wave1_batch2_phaseA_backlog_v1.md` - рабочий backlog Batch-2 (Phase A/B/C).
|
||
- `wave1_batch2_phaseB_resolver_hotpass_2026-04-08.md` - фиксация закрытия resolver drift на критичных Batch-2 формулировках (`6/6`).
|
||
- `domain_general_batch1_foundation_card_v1.md` - domain card первой волны (Phase A).
|
||
- `step4_wave1_batch1_phaseA_backlog_v1.md` - рабочий backlog по подготовке кода и gate-этапам Batch-1.
|
||
- `domain_card_template_v1.md` - шаблон описания домена для repeatable delivery.
|
||
- `domain_acceptance_question_set_template_v1.md` - шаблон структуры domain acceptance question set.
|
||
- `run_pack_spec_v1.md` - обязательный формат run-артефактов и gate-валидации.
|
||
|
||
Исторические и supporting docs:
|
||
|
||
- `entity_map_1c_2020.md`
|
||
- `address_query_bootstrap_report_2026-03-29.md`
|
||
- `known_positive_live_suite_v1.md`
|
||
- `data_aware_positive_acceptance_suite_v1.md`
|
||
- `curated_positive_live_suite_v1.md`
|
||
|
||
## Step-0 Automation (rail tools)
|
||
|
||
- `python scripts/validate_address_run_pack.py docs/ADDRESS/runs/<run_id>`
|
||
- `python scripts/compare_address_run_summary.py --baseline-summary <baseline_run_summary.json> --candidate-summary <candidate_run_summary.json>`
|
||
- `python scripts/run_address_nightly_regression.py`
|
||
- `python scripts/run_address_nightly_regression.py --dry-run`
|
||
- `python scripts/check_address_wave1_batch1_readiness.py`
|
||
- `powershell -ExecutionPolicy Bypass -File .\scripts\run_address_nightly_regression.ps1`
|
||
|
||
## Связанные run-паки
|
||
|
||
- `docs/ADDRESS/runs/2026-03-29_Address_Query_Entity_Inventory_2020/`
|
||
- `docs/ADDRESS/runs/2026-03-29_Address_Query_Runtime_V1_M2_2_Documents_BankOps_By_Counterparty/`
|
||
- `docs/ADDRESS/runs/2026-03-29_Address_Query_Runtime_V1_M2_3_DocumentsFormingBalance_DataAwareAcceptance/`
|
||
- `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/`
|
||
- `docs/ADDRESS/runs/2026-04-01_Address_Query_Runtime_V1_M2_3E_Stability_Hardening_AccountQueryScope/`
|
||
- `docs/ADDRESS/runs/2026-04-01_Address_Query_Runtime_V1_M2_3F_LLM_Decompose_Coercion_Layer/`
|
||
- `docs/ADDRESS/runs/2026-04-02_Address_Slang_Live_Stress_2026-04-02_12-57-27/`
|
||
- `docs/ADDRESS/runs/2026-04-02_Address_Followup_Context_Chains_2026-04-02_19-15-Run5/`
|
||
- `docs/ADDRESS/runs/2026-04-02_Address_Domain_ContractsOpenItems_Reference_Acceptance_2026-04-02_17-00-22/`
|
||
- `docs/ADDRESS/runs/2026-04-02_Address_Nightly_Regression_2026-04-02_17-35-00/`
|
||
- Step-5 follow-up hardening (2026-04-08):
|
||
- `address_dialog_continuation_contract_v2` for context continuation/switching.
|
||
- Safe retry on retryable limited outcomes (`missing_anchor` / `empty_match`) using raw user message + preserved context.
|
||
- Regression confirmation: `246/246` PASS (`assistantAddressFollowupContext`, `addressQueryRuntimeM23`, `assistantAddressLlmPredecompose`).
|
||
- Step-5 living router validation (2026-04-08):
|
||
- `assistantLivingRouter.test.ts`: `4/4` PASS
|
||
- `assistantLivingChatMode.test.ts`: `1/1` PASS
|
||
- build: PASS
|