NODEDC_1C/llm_normalizer/docs/route_executor_contracts.md

Route Executor Contracts

1. Общий контракт

Каждый route executor возвращает результат в unified-формате:

{
  "fragment_id": "F1",
  "route": "store_feature_risk",
  "status": "ok | empty | partial | error",
  "result_type": "list | summary | object | chain | ranking",
  "items": [],
  "summary": {},
  "evidence": [],
  "errors": []
}

Реализация:

• raw execution: backend/src/services/assistantDataLayer.ts
• normalizer: backend/src/services/retrievalResultNormalizer.ts

2. Вход executor’ов

Вызов выполняется через:

executeRoute(route: string, fragmentText: string)

Входы:

• route: выбранный маршрут из route planner.
• fragmentText: текст фрагмента после нормализации/декомпозиции.

Источник данных текущего MVP:

• snapshot-пакет docs/ARCH/2020экспорт/*.json

3. Route: hybrid_store_plus_live

Назначение:

• causal/cross-entity цепочки;
• связь документов с контрагентами;
• поиск разрывов связности.

Result:

• result_type = "chain"
• items: агрегаты по контрагенту (operations_count, document_refs_count, relation_types, samples)
• summary: checked_records, matched_counterparties, route_focus

4. Route: store_feature_risk

Назначение:

• anomaly/rule-check;
• риск-признаки в проблемных записях.

Result:

• result_type = "list"
• items: записи с risk_score, reasons, техническими индикаторами
• summary: checked_records, risky_records, average_risk_score

5. Route: batch_refresh_then_store

Назначение:

• обзорные и ranking-задачи;
• top/приоритизация проверки.

Result:

• result_type = "ranking"
• items: rank, entity, records_count
• summary: checked_records, ranked_entities

6. Route: store_canonical

Назначение:

• канонический factual path по документам.

Result:

• result_type = "list"
• items: документные записи (source_entity, source_id, period, counterparty_id, recorder)
• summary: checked_records, returned_records

7. Route: live_mcp_drilldown

Назначение:

• точечный drilldown по GUID/объекту.

Result:

• result_type = "object"
• items: найденные совпадения по GUID
• summary: query_guids, matched_records

8. Ошибки и no-route

Если fragment получает route=no_route, backend не вызывает executor, а формирует skipped-result:

• status = "empty"
• result_type = "summary"
• summary.skipped = true
• summary.no_route_reason

Если executor падает:

• status = "error"
• errors[] содержит текст ошибки.