Settings & Model Picker UI
Relevant source files
The following files were used as context for generating this wiki page:
The Settings and Model Picker UI provides a comprehensive interface for configuring AI providers, selecting large language models (LLMs), and managing API credentials. It allows users to fine-tune the behavior of the "Nudge" assistant, specifically focusing on provider-specific capabilities such as vision and reasoning effort.
This system is divided into a full-scale configuration modal and a compact "Quick Pick" interface for rapid adjustments during the pre-call lobby phase. It ensures that the application has the necessary API keys and model metadata to function, particularly for latency-sensitive voice interactions where "time-to-first-word" is critical.
Sources: apps/web/src/components/settings/ModelsSettings.tsx:162-164, apps/web/src/components/live/ModelQuickPick.tsx:11-13
Component Architecture
The UI is built using a modular React-based architecture, utilizing tanstack/react-query for data fetching and state synchronization.
SettingsModal
The root container for full settings, employing framer-motion (via motion/react) for entrance animations and a custom useFocusTrap hook for accessibility. It wraps the ModelsSettings component in an animated overlay.
Sources: apps/web/src/components/settings/SettingsModal.tsx:14-20
ModelsSettings
The primary configuration engine. It manages sections for:
- Provider & API Key: Selection of AI providers (e.g., OpenAI, Anthropic) and secure entry of API keys.
- Live Model: Searchable selection of the primary model used for voice turns.
- Vision Model: An optional, advanced section to route visual data through a different model if the primary one lacks vision capabilities.
- Reasoning Effort: Configuration of model reasoning levels (Auto, Low, Medium, High).
Sources: apps/web/src/components/settings/ModelsSettings.tsx:129-215
SearchSelect
A specialized UI component that replaces standard HTML <select> elements for long model lists. It supports text-based filtering, keyboard navigation (Arrow keys, Enter, Esc), and displays metadata hints like "vision" or "reasoning".
Sources: apps/web/src/components/settings/SearchSelect.tsx:16-24
Data Flow & State Management
The settings system interacts with a backend API to persist configurations and fetch dynamic model lists based on the selected provider.
This diagram illustrates how provider selection triggers model list updates and how mutations synchronize local state with the backend.
Sources: apps/web/src/components/settings/ModelsSettings.tsx:130-145, apps/web/src/components/settings/SearchSelect.tsx:30-40
Key Data Structures
| Option | Type | Description |
|---|---|---|
liveProviderId | string | The ID of the currently active AI provider. |
liveModel | string | The specific model ID selected for live interaction. |
liveEffort | string | Reasoning effort level: auto, low, medium, or high. |
visionModel | string | (Optional) Secondary model ID dedicated to processing image frames. |
| Sources: apps/web/src/components/settings/ModelsSettings.tsx:156-159, apps/web/src/lib/live/useLiveSession.ts:168-171 |
Model Capability & Validation
The UI includes logic to validate model capabilities, particularly vision, to ensure the "Study Tutor" features (which require screen/camera access) function correctly.
Vision Validation Logic
If a selected model is identified as "blind" (e.g., model.vision === false), the UI displays an AlertTriangle warning. Users are prompted to either pick a vision-capable model or configure a dedicated vision model in the advanced settings.
Sources: apps/web/src/components/settings/ModelsSettings.tsx:180-188, apps/web/src/components/live/ModelQuickPick.tsx:32-34
Sequence showing the validation of vision capabilities during model selection.
Sources: apps/web/src/components/settings/ModelsSettings.tsx:180-188
API Key Management
API keys are handled through the ProviderKey component. Keys are:
- Stored Securely: Encrypted at rest on the host machine.
- Masked in UI: Only the last 4 digits are displayed (e.g.,
••••1234). - Keyless Support: Certain providers (like local Ollama instances) are flagged as
keyless, disabling the key input requirement.
Sources: apps/web/src/components/settings/ModelsSettings.tsx:49-62
Model Metadata Display
The ModelBadges component extracts and displays technical specifications for selected models:
- Context Window: Formatted (e.g., 128k, 1M).
- Max Output: Formatted in thousands (e.g., 4k).
- Cost: Input/Output costs per million tokens.
- Capabilities: Icons for
Eye(Vision),Brain(Reasoning), andZap(Fast).
Sources: apps/web/src/components/settings/ModelsSettings.tsx:84-97
Summary
The Settings & Model Picker UI acts as the configuration hub for the AI agent. By combining the ModelsSettings modal for deep configuration and ModelQuickPick for lobby-level adjustments, the system balances technical depth with ease of use. It ensures that critical capabilities like vision and reasoning effort are correctly configured before a live session begins.
Sources: apps/web/src/components/settings/ModelsSettings.tsx:129-130, apps/web/src/components/live/ModelQuickPick.tsx:11-15