# Model Configuration UI Enhancement Plan

## Overview

This document outlines the detailed implementation plan to complete the "Enhance model configuration UI" task in the Community Edition. It covers adding a dedicated Model Settings tab to the macOS desktop app, introducing cost tracking and performance histories, expanding one-click provider switching, and fixing critical configuration sync issues between the desktop app and the CLI.

## 1. Desktop App Model Settings UI

- **Goal:** Create a dedicated UI for managing AI models, providers, and default selections in the desktop app.
- **Files to Modify:**
  - `apps/macos/Sources/SOPHIAClaw/UI/Settings/SettingsView.swift`: Add a new `models` case to the `SettingsTab` enum and display `ModelSettingsView` when selected.
  - **New File:** `apps/macos/Sources/SOPHIAClaw/UI/Settings/ModelSettingsView.swift`: A new SwiftUI view containing the model and provider management UI.
- **Implementation Details:**
  - Display active and available providers (OpenAI, Anthropic, Gemini, Ollama, Groq, Together, etc.).
  - Allow users to select their default provider (`SOPHIACLAW_DEFAULT_PROVIDER`) and default model (`SOPHIACLAW_DEFAULT_MODEL`) via dropdowns or lists.
  - Implement a segmented control or tab view to switch between "Cloud Providers" and "Local Providers" (e.g., Ollama).
  - Add API key fields inline for disabled providers to activate them quickly (moving them from the generic Security tab).

## 2. Basic Cost Tracking and Budget Alerts

- **Goal:** Provide visibility into API spending and alert users when approaching their budget limits.
- **Files to Modify:**
  - `apps/macos/Sources/SOPHIAClaw/Core/AppState.swift`: Add properties for `monthlyBudget` and `currentSpend` to `GatewayConfiguration`.
  - `src/gateway/server-methods/usage.ts` (New or modify existing): Add a Node-side mechanism to track tokens and calculate cost, emitting events or updating a persistent `usage.json` file.
  - `ModelSettingsView.swift`: Display a budget progress bar showing `currentSpend` vs `monthlyBudget`.
- **Implementation Details:**
  - Extend the Node.js backend to calculate costs dynamically based on model usage metrics.
  - Store budget settings in `~/.sophiaclaw/sophiaclaw.json` (e.g., `budget: { monthlyLimit: 50.00, alertThreshold: 0.8 }`).
  - Desktop app listens to budget changes and triggers an `UNUserNotificationCenter` alert when `currentSpend >= (monthlyLimit * alertThreshold)`.

## 3. Model Performance History and Comparison

- **Goal:** Help users choose the best model by displaying historical metrics.
- **Files to Modify:**
  - `src/gateway/server-methods/metrics.ts` (New or existing): Introduce backend metric gathering (Latency, Tokens/sec, Error Rate).
  - `ModelSettingsView.swift`: Add a "Performance" section with a chart/table comparing the performance of used models.
- **Implementation Details:**
  - The Node gateway stores performance data per run (timestamp, model, timeToFirstToken, tokensPerSecond, success).
  - Add a new Gateway API endpoint (e.g., `models.metrics`) to serve aggregated stats to the desktop app.
  - In SwiftUI, use the `Charts` framework (e.g., `BarChart` or `LineChart`) to visualize speed and reliability per model.

## 4. Enhanced Configuration Sync (CLI/Desktop)

- **Goal:** Prevent the desktop app from overwriting CLI configuration properties, and ensure the app updates instantly when the CLI edits the config.
- **Files to Modify:**
  - `apps/macos/Sources/SOPHIAClaw/Core/AppState.swift`
- **Implementation Details:**
  - **Fix Destructive Save:** Modify `saveConfiguration()` in `AppState.swift` to first read the existing `sophiaclaw.json` file, parse it into a dictionary, update only the gateway-specific keys that the UI manages, and re-serialize the dictionary. Currently, the UI wipes out any CLI-specific arrays/objects (like plugins, tools, webhooks).
  - **File Watcher:** Add a `DispatchSourceFileSystemObject` or `NSFilePresenter` to `AppState.swift` to monitor `~/.sophiaclaw/sophiaclaw.json` for external modifications.
  - **Live Reload:** When the file watcher detects a change from the CLI, call `loadConfiguration()` to refresh the SwiftUI state immediately, keeping the desktop settings view perfectly in sync with CLI commands (like `sophiaclaw config set ...`).

## 5. Expand One-Click Provider Switching

- **Goal:** Standardize one-click switching across all supported model types without needing to touch terminal scripts.
- **Files to Modify:**
  - `apps/macos/Sources/SOPHIAClaw/UI/Settings/ModelSettingsView.swift`
  - `src/agents/models-config.ts` (if needed for backend capability parsing)
- **Implementation Details:**
  - Add quick-switch buttons (e.g., "Use Claude 3.5 Sonnet", "Use GPT-4o", "Use Llama 3 Local") inside the `ModelSettingsView`.
  - Clicking these buttons immediately sets the required environment variables (`SOPHIACLAW_DEFAULT_PROVIDER`, `SOPHIACLAW_DEFAULT_MODEL`) within the `customSecrets` dictionary and reloads the gateway state.
  - If a provider is clicked but lacks an API key, automatically focus the respective key input field.