@vectorchat/mcp-server/vectorchat_flutter/MODEL_SELECTION_FEATURE.md

VectorChat MCP Server - Encrypted AI-to-AI communication with hardware security (YubiKey/TPM). 45+ MCP tools for Windsurf, Claude, and AI assistants. Model-based identity with EMDM encryption. Dynamic AI playbook system, communication zones, message relay

# AI Model Selection Feature

## Overview

The Flutter app now includes a comprehensive AI model selection screen that appears on first run or can be accessed anytime to change the active AI model.

## Features

### 1. Automatic First-Run Detection
- Detects if no model has been configured
- Shows model selection screen automatically on first startup
- Cannot be skipped (must select a model or use fallback)

### 2. Model Discovery
- Scans all configured model directories
- Lists all available GGUF and binary models
- Shows model size, source, and location
- Displays helpful information if no models found

### 3. Visual Model Selection
- Card-based UI with model details
- Shows model name, size, and source
- Visual selection indicator
- Fallback option always available

### 4. Anytime Access
- Brain icon (🧠) in app bar to change model
- Can switch models without restarting
- Settings are persisted

## User Experience

### First Run

```
[App Starts]
  ↓
[No model configured detected]
  ↓
[Model Selection Screen appears]
  ↓
[User selects model or fallback]
  ↓
[Selection saved to settings]
  ↓
[App continues to main screen]
```

### Changing Model Later

```
[Click brain icon in app bar]
  ↓
[Model Selection Screen appears]
  ↓
[User selects different model]
  ↓
[Selection saved]
  ↓
[Notification: "Restart app to apply changes"]
```

## Model Selection Screen

### Header
- Welcome message (first run) or "AI Model Selection"
- Description: "Select an AI model for encryption and processing"
- Error messages if any

### Model Cards
Each model card shows:
- **Icon**: Memory chip icon
- **Name**: Model filename
- **Size**: Formatted file size (GB/MB)
- **Source**: VectorChat, LM Studio, Ollama, etc.
- **Selection indicator**: Blue checkmark when selected

### Fallback Option
- **Icon**: Cloud icon
- **Name**: "Use Fallback Model"
- **Description**: "Lightweight deterministic model"
- **Details**: "No download required • Basic encryption"

### No Models Found View
Shows:
- Search icon
- "No AI Models Found" message
- List of searched directories
- Instructions on how to add models
- "Refresh" button to scan again
- "Use Fallback" button

### Action Buttons
- **Cancel** (if not first run)
- **Confirm Selection** (enabled when model selected)

## Technical Implementation

### Files Created

**`lib/screens/model_selection_screen.dart`**
- Complete model selection UI
- Model discovery and listing
- Selection persistence
- Error handling

### Files Modified

**`lib/main.dart`**
- Added model selection check
- Passes `needsModelSelection` flag to app
- Updated startup sequence

**`lib/screens/chat_screen.dart`**
- Added `showModelSelectionOnStart` parameter
- Shows model selection on first run
- Added brain icon to app bar
- Added `_showModelSelection()` method

### Model Selection Logic

```dart
// Check if model selection needed
bool needsModelSelection = settings.lastModelPath == null;

// Pass to app
VectorChatApp(needsModelSelection: needsModelSelection)

// Show on startup if needed
if (widget.showModelSelectionOnStart) {
  WidgetsBinding.instance.addPostFrameCallback((_) {
    _showModelSelection(isFirstRun: true);
  });
}
```

## User Workflows

### Scenario 1: First-Time User (No Models)

1. App starts
2. Model selection screen appears
3. "No AI Models Found" view shown
4. User clicks "Use Fallback"
5. Fallback model selected
6. App continues with fallback encryption

### Scenario 2: First-Time User (Has LM Studio)

1. App starts
2. Model selection screen appears
3. Lists models from `~/.lmstudio/models`
4. User selects "Qwen3-1.7B-Instruct"
5. Model path saved to settings
6. App continues with selected model

### Scenario 3: Existing User Changing Model

1. User clicks brain icon in app bar
2. Model selection screen appears
3. Current model is pre-selected
4. User selects different model
5. Selection saved
6. Notification: "Restart app to apply changes"
7. User restarts app
8. New model loaded

### Scenario 4: User Adds New Model

1. User downloads model to `~/.vectorchat/models`
2. Opens model selection screen
3. Clicks "Refresh"
4. New model appears in list
5. User selects it
6. Model saved to settings

## Settings Integration

### Saved to Settings
```json
{
  "last_model_path": "/home/user/.vectorchat/models/qwen/model.gguf"
}
```

### Fallback Selection
```json
{
  "last_model_path": null
}
```

## UI Components

### Model Card (Selected)
```
┌─────────────────────────────────────┐
│ [🧠]  Qwen3-1.7B-Instruct-Q4_K_M   │
│       Size: 4.37 GB                 │
│       📁 Source: VectorChat      [✓]│
└─────────────────────────────────────┘
```

### Model Card (Unselected)
```
┌─────────────────────────────────────┐
│ [🧠]  llama-3.2-7b-instruct.gguf    │
│       Size: 4.12 GB                 │
│       📁 Source: LM Studio          │
└─────────────────────────────────────┘
```

### Fallback Option
```
┌─────────────────────────────────────┐
│ [☁️]  Use Fallback Model            │
│       Lightweight deterministic     │
│       No download • Basic encryption│
└─────────────────────────────────────┘
```

## App Bar Integration

The brain icon (🧠) appears in the app bar when connected:

```
[VectorChat] [🤖] [💬] [🧠] [⚙️] [ℹ️] [🚪]
              ↑     ↑    ↑
           Model  Group  Settings
          Select  Chat
```

## Benefits

✅ **User-friendly** - Visual selection with clear information  
✅ **Flexible** - Can change model anytime  
✅ **Discoverable** - Automatically finds models  
✅ **Fallback** - Always has a working option  
✅ **First-run** - Guides new users  
✅ **Persistent** - Remembers selection  
✅ **Accessible** - Easy to change from app bar  

## Model Search Paths

The selection screen searches:
1. `~/.vectorchat/models`
2. `~/.lmstudio/models`
3. `~/.ollama/models`
4. `~/.cache/huggingface`
5. `/usr/share/models`

## Error Handling

### No Models Found
- Shows helpful message
- Lists search paths
- Provides instructions
- Offers fallback option
- Refresh button to rescan

### Model Load Error
- Shows error message in header
- Allows retry
- Fallback always available

### Permission Issues
- Catches and displays errors
- Continues with accessible models
- Logs issues for debugging

## Future Enhancements

Potential additions:
- [ ] Model download from UI
- [ ] Model performance metrics
- [ ] Model recommendations
- [ ] Model testing before selection
- [ ] Multiple model profiles
- [ ] Model auto-update checking

## Testing

### Test Cases

1. **First run with no models**
   - Should show model selection
   - Should offer fallback
   - Should save selection

2. **First run with LM Studio models**
   - Should list LM Studio models
   - Should allow selection
   - Should save path

3. **Change model from app bar**
   - Should show current selection
   - Should allow change
   - Should show restart notification

4. **Refresh after adding model**
   - Should rescan directories
   - Should show new model
   - Should maintain selection if valid

5. **Cancel on non-first-run**
   - Should close without changes
   - Should keep current model

## Summary

The model selection feature provides a complete, user-friendly way to:
- Choose AI models on first run
- Change models anytime
- Discover available models
- Fall back to lightweight option
- Persist selections across sessions

**Ready to build and test!** 🚀