docs updated v0.7.0

2025-12-22 01:40:24 -05:00
parent b4613ac30c
commit f1471cde84
3 changed files with 478 additions and 38 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,271 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Se

 ---

+## [0.7.0] - 2025-12-21
+
+### Added - Standard Mode & UI Enhancements
+
+**Standard Mode Implementation**
+- Added "Standard Mode" chat option that bypasses complex cortex reasoning pipeline
+  - Provides simple chatbot functionality for coding and practical tasks
+  - Maintains full conversation context across messages
+  - Backend-agnostic - works with SECONDARY (Ollama), OPENAI, or custom backends
+  - Created `/simple` endpoint in Cortex router [cortex/router.py:389](cortex/router.py#L389)
+- Mode selector in UI with toggle between Standard and Cortex modes
+  - Standard Mode: Direct LLM chat with context retention
+  - Cortex Mode: Full 7-stage reasoning pipeline (unchanged)
+
+**Backend Selection System**
+- UI settings modal with LLM backend selection for Standard Mode
+  - Radio button selector: SECONDARY (Ollama/Qwen), OPENAI (GPT-4o-mini), or custom
+  - Backend preference persisted in localStorage
+  - Custom backend text input for advanced users
+- Backend parameter routing through entire stack:
+  - UI sends `backend` parameter in request body
+  - Relay forwards backend selection to Cortex
+  - Cortex `/simple` endpoint respects user's backend choice
+- Environment-based fallback: Uses `STANDARD_MODE_LLM` if no backend specified
+
+**Session Management Overhaul**
+- Complete rewrite of session system to use server-side persistence
+  - File-based storage in `core/relay/sessions/` directory
+  - Session files: `{sessionId}.json` for history, `{sessionId}.meta.json` for metadata
+  - Server is source of truth - sessions sync across browsers and reboots
+- Session metadata system for friendly names
+  - Sessions display custom names instead of random IDs
+  - Rename functionality in session dropdown
+  - Last modified timestamps and message counts
+- Full CRUD API for sessions in Relay:
+  - `GET /sessions` - List all sessions with metadata
+  - `GET /sessions/:id` - Retrieve session history
+  - `POST /sessions/:id` - Save session history
+  - `PATCH /sessions/:id/metadata` - Update session name/metadata
+  - `DELETE /sessions/:id` - Delete session and metadata
+- Session management UI in settings modal:
+  - List of all sessions with message counts and timestamps
+  - Delete button for each session with confirmation
+  - Automatic session cleanup when deleting current session
+
+**UI Improvements**
+- Settings modal with hamburger menu (⚙ Settings button)
+  - Backend selection section for Standard Mode
+  - Session management section with delete functionality
+  - Clean modal overlay with cyberpunk theme
+  - ESC key and click-outside to close
+- Light/Dark mode toggle with dark mode as default
+  - Theme preference persisted in localStorage
+  - CSS variables for seamless theme switching
+  - Toggle button shows current mode (🌙 Dark Mode / ☀️ Light Mode)
+- Removed redundant model selector dropdown from header
+- Fixed modal positioning and z-index layering
+  - Modal moved outside #chat container for proper rendering
+  - Fixed z-index: overlay (999), modal content (1001)
+  - Centered modal with proper backdrop blur
+
+**Context Retention for Standard Mode**
+- Integration with Intake module for conversation history
+  - Added `get_recent_messages()` function in intake.py
+  - Standard Mode retrieves last 20 messages from session buffer
+  - Full context sent to LLM on each request
+- Message array format support in LLM router:
+  - Updated Ollama provider to accept `messages` parameter
+  - Updated OpenAI provider to accept `messages` parameter
+  - Automatic conversion from messages to prompt string for non-chat APIs
+
+### Changed - Architecture & Routing
+
+**Relay Server Updates** [core/relay/server.js](core/relay/server.js)
+- ES module migration for session persistence:
+  - Imported `fs/promises`, `path`, `fileURLToPath` for file operations
+  - Created `SESSIONS_DIR` constant for session storage location
+- Mode-based routing in both `/chat` and `/v1/chat/completions` endpoints:
+  - Extracts `mode` parameter from request body (default: "cortex")
+  - Routes to `CORTEX_SIMPLE` for Standard Mode, `CORTEX_REASON` for Cortex Mode
+  - Backend parameter only used in Standard Mode
+- Session persistence functions:
+  - `ensureSessionsDir()` - Creates sessions directory if needed
+  - `loadSession(sessionId)` - Reads session history from file
+  - `saveSession(sessionId, history, metadata)` - Writes session to file
+  - `loadSessionMetadata(sessionId)` - Reads session metadata
+  - `saveSessionMetadata(sessionId, metadata)` - Updates session metadata
+  - `listSessions()` - Returns all sessions with metadata, sorted by last modified
+  - `deleteSession(sessionId)` - Removes session and metadata files
+
+**Cortex Router Updates** [cortex/router.py](cortex/router.py)
+- Added `backend` field to `ReasonRequest` Pydantic model (optional)
+- Created `/simple` endpoint for Standard Mode:
+  - Bypasses reflection, reasoning, refinement stages
+  - Direct LLM call with conversation context
+  - Uses backend from request or falls back to `STANDARD_MODE_LLM` env variable
+  - Returns simple response structure without reasoning artifacts
+- Backend selection logic in `/simple`:
+  - Normalizes backend names to uppercase
+  - Maps UI backend names to system backend names
+  - Validates backend availability before calling
+
+**Intake Integration** [cortex/intake/intake.py](cortex/intake/intake.py)
+- Added `get_recent_messages(session_id, limit)` function:
+  - Retrieves last N messages from session buffer
+  - Returns empty list if session doesn't exist
+  - Used by `/simple` endpoint for context retrieval
+
+**LLM Router Enhancements** [cortex/llm/llm_router.py](cortex/llm/llm_router.py)
+- Added `messages` parameter support across all providers
+- Automatic message-to-prompt conversion for legacy APIs
+- Chat completion format for Ollama and OpenAI providers
+- Stop sequences for MI50/DeepSeek R1 to prevent runaway generation:
+  - `"User:"`, `"\nUser:"`, `"Assistant:"`, `"\n\n\n"`
+
+**Environment Configuration** [.env](.env)
+- Added `STANDARD_MODE_LLM=SECONDARY` for default Standard Mode backend
+- Added `CORTEX_SIMPLE_URL=http://cortex:7081/simple` for routing
+
+**UI Architecture** [core/ui/index.html](core/ui/index.html)
+- Server-based session loading system:
+  - `loadSessionsFromServer()` - Fetches sessions from Relay API
+  - `renderSessions()` - Populates session dropdown from server data
+  - Session state synchronized with server on every change
+- Backend selection persistence:
+  - Loads saved backend from localStorage on page load
+  - Includes backend parameter in request body when in Standard Mode
+  - Settings modal pre-selects current backend choice
+- Dark mode by default:
+  - Checks localStorage for theme preference
+  - Sets dark theme if no preference found
+  - Toggle button updates localStorage and applies theme
+
+**CSS Styling** [core/ui/style.css](core/ui/style.css)
+- Light mode CSS variables:
+  - `--bg-dark: #f5f5f5` (light background)
+  - `--text-main: #1a1a1a` (dark text)
+  - `--text-fade: #666` (dimmed text)
+- Dark mode CSS variables (default):
+  - `--bg-dark: #0a0a0a` (dark background)
+  - `--text-main: #e6e6e6` (light text)
+  - `--text-fade: #999` (dimmed text)
+- Modal positioning fixes:
+  - `position: fixed` with `top: 50%`, `left: 50%`, `transform: translate(-50%, -50%)`
+  - Z-index layering: overlay (999), content (1001)
+  - Backdrop blur effect on modal overlay
+- Session list styling:
+  - Session item cards with hover effects
+  - Delete button with red hover state
+  - Message count and timestamp display
+
+### Fixed - Critical Issues
+
+**DeepSeek R1 Runaway Generation**
+- Root cause: R1 reasoning model generates thinking process and hallucinates conversations
+- Solution:
+  - Changed `STANDARD_MODE_LLM` to SECONDARY (Ollama/Qwen) instead of PRIMARY (MI50/R1)
+  - Added stop sequences to MI50 provider to prevent continuation
+  - Documented R1 limitations for Standard Mode usage
+
+**Context Not Maintained in Standard Mode**
+- Root cause: `/simple` endpoint didn't retrieve conversation history from Intake
+- Solution:
+  - Created `get_recent_messages()` function in intake.py
+  - Standard Mode now pulls last 20 messages from session buffer
+  - Full context sent to LLM with each request
+- User feedback: "it's saying it hasn't received any other messages from me, so it looks like the standard mode llm isn't getting the full chat"
+
+**OpenAI Backend 400 Errors**
+- Root cause: OpenAI provider only accepted prompt strings, not messages arrays
+- Solution: Updated OpenAI provider to support messages parameter like Ollama
+- Now handles chat completion format correctly
+
+**Modal Formatting Issues**
+- Root cause: Settings modal inside #chat container with overflow constraints
+- Symptoms: Modal appearing at bottom, jumbled layout, couldn't close
+- Solution:
+  - Moved modal outside #chat container to be direct child of body
+  - Changed positioning from absolute to fixed
+  - Added proper z-index layering (overlay: 999, content: 1001)
+  - Removed old model selector from header
+- User feedback: "the formating for the settings is all off. Its at the bottom and all jumbling together, i cant get it to go away"
+
+**Session Persistence Broken**
+- Root cause: Sessions stored only in localStorage, not synced with server
+- Symptoms: Sessions didn't persist across browsers or reboots, couldn't load messages
+- Solution: Complete rewrite of session system
+  - Implemented server-side file persistence in Relay
+  - Created CRUD API endpoints for session management
+  - Updated UI to load sessions from server instead of localStorage
+  - Added metadata system for session names
+  - Sessions now survive container restarts and sync across browsers
+- User feedback: "sessions seem to exist locally only, i cant get them to actually load any messages and there is now way to delete them. If i open the ui in a different browser those arent there."
+
+### Technical Improvements
+
+**Backward Compatibility**
+- All changes include defaults to maintain existing behavior
+- Cortex Mode completely unchanged - still uses full 7-stage pipeline
+- Standard Mode is opt-in via UI mode selector
+- If no backend specified, falls back to `STANDARD_MODE_LLM` env variable
+- Existing requests without mode parameter default to "cortex"
+
+**Code Quality**
+- Consistent async/await patterns throughout stack
+- Proper error handling with fallbacks
+- Clean separation between Standard and Cortex modes
+- Session persistence abstracted into helper functions
+- Modular UI code with clear event handlers
+
+**Performance**
+- Standard Mode bypasses 6 of 7 reasoning stages for faster responses
+- Session loading optimized with file-based caching
+- Backend selection happens once per message, not per LLM call
+- Minimal overhead for mode detection and routing
+
+### Architecture - Dual-Mode Chat System
+
+**Standard Mode Flow:**
+```
+User (UI) → Relay → Cortex /simple → Intake (get_recent_messages)
+→ LLM (direct call with context) → Relay → UI
+```
+
+**Cortex Mode Flow (Unchanged):**
+```
+User (UI) → Relay → Cortex /reason → Reflection → Reasoning
+→ Refinement → Persona → Relay → UI
+```
+
+**Session Persistence:**
+```
+UI → POST /sessions/:id → Relay → File system (sessions/*.json)
+UI → GET /sessions → Relay → List all sessions → UI dropdown
+```
+
+### Known Limitations
+
+**Standard Mode:**
+- No reflection, reasoning, or refinement stages
+- No RAG integration (same as Cortex Mode - currently disabled)
+- No NeoMem memory storage (same as Cortex Mode - currently disabled)
+- DeepSeek R1 not recommended for Standard Mode (generates reasoning artifacts)
+
+**Session Management:**
+- Sessions stored in container filesystem - need volume mount for true persistence
+- No session import/export functionality yet
+- No session search or filtering
+
+### Migration Notes
+
+**For Users Upgrading:**
+1. Existing sessions in localStorage will not automatically migrate to server
+2. Create new sessions after upgrade for server-side persistence
+3. Theme preference (light/dark) will be preserved from localStorage
+4. Backend preference will default to SECONDARY if not previously set
+
+**For Developers:**
+1. Relay now requires `fs/promises` for session persistence
+2. Cortex `/simple` endpoint expects `backend` parameter (optional)
+3. UI sends `mode` and `backend` parameters in request body
+4. Session files stored in `core/relay/sessions/` directory
+
+---
+
 ## [0.6.0] - 2025-12-18

 ### Added - Autonomy System (Phase 1 & 2)