NODEDC_1C/docs/assistant_orchestration_spec.md

Assistant Orchestration Spec (Layer 7)

Date: 2026-03-23
Status: architecture-ready, partial runtime implementation

1. Objective

Route user questions to the correct execution path:

• live read-only bridge (point drill-down)
• canonical/feature/risk stores (fast analytical answer)
• refresh/feature/risk jobs (if cached context is stale or missing)

2. Routing modes

Mode A: Live Drill-down

Use when user asks for a specific object/fact:

• one document
• one posting
• one account entry chain

Path:

Assistant -> runtime bridge tools -> user answer

Mode B: Cached Analytics

Use when answer is already represented in stores:

• features
• anomalies
• risk patterns

Path:

Assistant -> /features/* + /risk/* + canonical store -> user answer

Mode C: Recompute Then Answer

Use when data freshness is not acceptable or context missing:

1. trigger refresh (/refresh/run)
2. trigger features (/features/run)
3. trigger risk (/risk/run)
4. return updated answer

3. Current API surface used by orchestrator

• POST /refresh/run
• GET /refresh/runs
• GET /store/stats
• POST /features/run
• GET /features/stats
• GET /features/anomalies
• POST /risk/run
• GET /risk/patterns
• GET /risk/stats

4. Freshness policy (MVP)

1. If stale_refresh signal exists, trigger Mode C.
2. If no feature run exists, trigger Mode C.
3. If no risk run exists, trigger Mode C.
4. Otherwise use Mode B with optional Mode A drill-down evidence.

5. Response shape (recommended)

Assistant output should include:

1. direct answer
2. evidence source (live, canonical, feature, risk)
3. freshness markers (timestamps/run ids)
4. optional next action (rerun refresh/features/risk)

6. Safety rule

Orchestrator never sends write commands to 1C. All runtime access is read-only by policy.