odysseus/docs/discovery/domains/chat.md

Chat

Features in this document are generated from ../feature-catalog.json, the canonical inventory.

CHAT-001 — Core Chat Streaming & SSE Message Generation

• Domain: chat
• Status: verified
• Evidence Maturity: E2
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: pending — Requires access to a live LLM provider endpoint (OpenAI API key or local Ollama server).

Purpose

Handles real-time Server-Sent Events (SSE) chat streaming, token rendering, and model response generation.

Evidence summary

• routes/chat_routes.py — chat_stream — POST /api/chat_stream SSE endpoint; builds the shared chat context, then dispatches to the chat-mode or agent-mode streaming path.
• routes/chat_helpers.py — build_chat_context — Shared context builder invoked by chat_stream; runs message preprocessing and assembles the memory/RAG/web context preface.
• src/chat_handler.py — ChatHandler.preprocess_message — Message preprocessing (attachments, URLs, tool preprocessing) reached from build_chat_context via routes/chat_helpers.py:preprocess.
• src/chat_processor.py — ChatProcessor.build_context_preface — Builds the retrieval and web-source context preface injected into the streamed request.
• src/llm_core.py — stream_llm_with_fallback — Chat-mode streaming dispatcher called from chat_stream; wraps stream_llm with an ordered provider fallback chain.
• src/llm_core.py — stream_llm — Per-request streaming entry wrapped by stream_llm_with_fallback; acquires the local model slot and delegates to _stream_llm_inner.
• src/agent_loop.py — stream_agent_loop — Agent-mode streaming path called from chat_stream when the request selects agent mode.
• tests/test_chat_metrics.py — test_stream_llm_passes_through_llamacpp_timings — Inspected unit test asserting stream_llm forwards backend generation timings into the emitted metrics chunk.
• tests/test_resend_message_nondestructive.py — test_resend_message_does_not_truncate_by_default — Inspected unit test asserting the frontend resend path does not truncate prior conversation turns.

Unknowns

• Stream interruption on connection drops requires retry logic.

CHAT-002 — Session Management & Conversation State

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Manages session creation, listing, switching, renaming, and persistence of conversation metadata.

Evidence summary

• routes/session_routes.py — @router.get('/api/sessions') — Lists active sessions filtered by user owner scope.
• core/session_manager.py — SessionManager — Provides thread-safe session storage operations.

Unknowns

• Concurrent file writes to sessions.json under high load.

CHAT-003 — Chat History & Message Editing/Truncation

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Provides history retrieval, message content updating, message deletion, and history branch truncation.

Evidence summary

• routes/history/history_routes.py — @router.get('/api/history/{session_id}') — Fetches message history timeline for a session.
• routes/history_routes.py — _sys.modules[__name__] = _canonical — Backward-compatibility shim module.

Unknowns

• Truncating messages re-indexes context window and clears cached tool calls.

CHAT-004 — File & Multimodal Attachment Handling

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Handles uploading, mime validation, image preview, vision encoding, and file attachments in chat messages.

Evidence summary

• routes/upload_routes.py — @router.post('') — Accepts multi-part file uploads and generates vision metadata.
• src/upload_handler.py — UploadHandler.save_file — Validates upload size and atomicity on disk.

Unknowns

• Large file uploads may consume server disk space if cleanup task fails.

CHAT-005 — Chat Message Search

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Enables full-text keyword search across stored chat messages and sessions.

Evidence summary

• routes/search_routes.py — setup_search_routes — Registers chat message search endpoint.
• src/session_search.py — search_sessions — Executes query matching against session transcripts.

Unknowns

• Full table scans on un-indexed text columns for very large databases.

CHAT-006 — System Prompts & Preset Management

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Provides creation, selection, and customization of system prompt presets for chat sessions.

Evidence summary

• routes/preset_routes.py — setup_preset_routes — API routes for listing and modifying system prompt presets.
• src/preset_manager.py — PresetManager — Disk-backed manager for prompt presets.

Unknowns

• Invalid JSON syntax in user presets file can corrupt preset loading.

CHAT-007 — Emoji Rendering & Twemoji SVG Proxy

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Proxies Twemoji SVG icons locally to render flat SVG emojis in message text without external CDN dependencies.

Evidence summary

• routes/emoji_routes.py — setup_emoji_routes — Serves locally cached Twemoji SVGs.

Unknowns

• First request fetches SVG from remote CDN before caching locally.

CHAT-008 — Input History Recall (Arrow Up)

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Allows users to cycle through previously sent prompt messages in the chat composer input using Arrow-Up/Down keys.

Evidence summary

• static/js/composerArrowUpRecall.js — initComposerRecall — Listens for ArrowUp keypress on composer textarea.

Unknowns

• Client-side browser storage limits.

CHAT-009 — Context Window Compaction & Truncation

• Domain: chat
• Status: verified
• Evidence Maturity: E0
• Commit Verified: d8a2059df8e53bc7275c45339849d14c8651e73c
• Runtime Validation: not-required — No separate environment-dependent runtime validation was identified during this documentation pass.

Purpose

Compacts session transcript history when prompt size exceeds context limits using summarization.

Evidence summary

• routes/history/history_routes.py — @router.post('/api/session/{session_id}/compact') — Triggers context summarization and compaction.
• src/context_compactor.py — compact_context — Executes context token pruning and summary generation.

Unknowns

• Aggressive compaction may discard subtle user instructions.