# 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.