Initial import NDC_1C

llm_normalizer/docs/assistant_mode_flow.md

@@ -0,0 +1,45 @@
+# Assistant Mode Flow
+
+## End-to-End
+1. User opens `Assistant` mode in GUI.
+2. User enters message and clicks `Send`.
+3. Frontend starts status ticker:
+   - `Razbirayu zapros`
+   - `Proveryayu kontur`
+   - `Opredelyayu marshrut`
+   - `Ishchu dannye`
+   - `Sobirayu otvet`
+4. Backend stores user message in session history.
+5. Backend runs normalizer (`normalizer_v2_0_2`) with provided prompt/config.
+6. Backend derives deterministic route summary from normalized payload.
+7. Backend builds retrieval plan (current stage: stubbed/diagnostic).
+8. Backend composes human-readable assistant answer via `answer_composer`.
+9. Backend stores assistant reply in session history.
+10. Backend returns reply + debug payload + updated conversation snapshot.
+11. Frontend updates chat timeline and keeps debug expandable per assistant message.
+
+## Fallback Behavior
+- `out_of_scope`: polite contour boundary response.
+- `clarification`: asks for concrete period/account/document/counterparty.
+- `partial`: reports available in-scope part and marks unavailable part.
+- `none`: reports routed fragments and planned execution path.
+
+## Debug Drawer Data
+Each assistant reply can expose:
+- `trace_id`
+- normalized fragments
+- route summary and fallback type
+- retrieval plan payload
+- full normalized object snapshot
+
+## Session Memory Rules
+- scope: current backend process memory only
+- key: `session_id`
+- message cap: bounded in-memory list per session
+- persistence: not durable across backend restart
+
+## Why This Stage Exists
+This mode creates a usable operator loop before deeper field-hardening:
+- gather real dialog traces
+- identify where clarification/no-route appears in practice
+- evaluate answer quality and UX with real user input