NODEDC_1C/llm_normalizer/docs/assistant_mode_spec.md

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.