Initial import NDC_1C

2026-03-26 10:38:25 +03:00
commit a162d77ef7
2943 changed files with 3615871 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Assistant Mode Spec
+
+## Goal
+Add a second UI mode (`Assistant`) on top of the existing decomposition pipeline, without removing current decomposition/debug capabilities.
+
+## Scope Delivered
+- Keep existing `Decomposition` mode unchanged.
+- Add `Assistant` chat mode in frontend.
+- Add backend endpoint `POST /api/assistant/message`.
+- Add session-scoped chat memory (in-memory store).
+- Add `answer_composer` layer for human-readable output.
+- Add debug payload per assistant reply (expandable in UI).
+- Keep one shared backend normalization/routing pipeline.
+
+## Backend Contract
+
+### Endpoint
+`POST /api/assistant/message`
+
+### Request
+- `session_id` (optional)
+- `user_message` (required)
+- connection settings: `apiKey`, `model`, `baseUrl`, `temperature`, `maxOutputTokens`
+- prompt settings: `promptVersion`, `systemPrompt`, `developerPrompt`, `domainPrompt`, `fewShotExamples`
+- optional `context` (`period_hint`, `business_context`)
+- `useMock` (optional)
+
+### Response
+- `ok`
+- `session_id`
+- `assistant_reply`
+- `conversation_item` (assistant message)
+- `debug`:
+  - `trace_id`
+  - `fragments`
+  - `fallback_type`
+  - `route_summary`
+  - `retrieval`
+  - `normalized`
+- `conversation` (session items snapshot)
+
+### Session Endpoint
+`GET /api/assistant/session/:session_id`
+
+Returns current in-memory session transcript.
+
+## Internal Pipeline
+`user_message -> normalizer_v2_0_2 -> deterministic route summary -> retrieval plan -> answer_composer -> assistant reply`
+
+Notes:
+- retrieval layer is currently sandbox/stubbed in this stage;
+- answer is human-readable and not raw JSON;
+- debug JSON is still available per message.
+
+## Logging Fields
+Each assistant message writes structured log entry with:
+- `session_id`
+- `message_id`
+- `user_message`
+- `normalizer_output`
+- `resolved_execution_state`
+- `routes`
+- `fallback_type`
+- `retrieval_payloads`
+- `assistant_reply`
+- `trace_id`
+
+## Frontend Behavior
+
+### Mode Switch
+Two explicit modes:
+- `Assistant`
+- `Decomposition`
+
+### Assistant UI
+- chat feed (user/assistant messages)
+- message input + send
+- pipeline status text while processing
+- session reset button
+- optional debug section per assistant message (`details`)
+
+### Decomposition UI
+All existing panels stay as-is: normalize/eval/history/runtime/debug tabs.