@vectorchat/mcp-server/vectorchat_flutter/IPFS_MODEL_DOWNLOAD_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

# IPFS Model Download Feature

**Date:** October 17, 2025  
**Status:** ✅ Implemented  
**Version:** 1.0.0

## Overview

Automatic download of the default AI model (Qwen 3 1.7B) from IPFS during first-time app initialization. Provides seamless onboarding experience with progress monitoring.

---

## Features

### 1. **Automatic Model Provisioning**
- First-time users automatically get Qwen 3 1.7B model
- No manual model download required
- Cached locally for future use

### 2. **IPFS Distribution**
- Model distributed via IPFS network
- Decentralized, censorship-resistant
- Multiple gateway fallback
- Content-addressed (CID-based)

### 3. **Progress Monitoring**
- Real-time download progress
- Bytes downloaded / total size
- Percentage completion
- Gateway status updates

### 4. **Smart Fallback**
- Tries local IPFS node first (fastest)
- Falls back to public gateways
- Multiple gateway options
- Automatic retry on failure

---

## Architecture

### Components

#### 1. **IPFSModelDownloader** (`lib/services/ipfs_model_downloader.dart`)

**Responsibilities:**
- Download models from IPFS
- Track download progress
- Handle gateway fallback
- Cache models locally

**Key Features:**
- Multiple IPFS gateway support
- Progress callbacks
- Error handling
- Cancellation support

**Gateway Chain:**
1. `http://127.0.0.1:8080` - Local IPFS node (fastest)
2. `https://ipfs.io` - Public gateway
3. `https://dweb.link` - Cloudflare gateway
4. `https://gateway.pinata.cloud` - Pinata gateway
5. `https://cloudflare-ipfs.com` - Alternative Cloudflare

#### 2. **ModelDownloadDialog** (`lib/widgets/model_download_dialog.dart`)

**Responsibilities:**
- Display download progress UI
- Show status updates
- Handle user cancellation
- Display errors

**UI Elements:**
- Progress bar with percentage
- Downloaded / Total bytes
- Status messages
- Gateway information
- Success/Error indicators

#### 3. **Main App Integration** (`lib/main.dart`)

**Initialization Flow:**
```
1. Check if model is configured
   ↓
2. If not, check for default model locally
   ↓
3. If not found, set needsModelDownload = true
   ↓
4. Pass flag to ChatScreen
   ↓
5. ChatScreen shows download dialog
   ↓
6. Model downloads from IPFS
   ↓
7. Model saved and loaded
   ↓
8. App continues normally
```

---

## Default Model Configuration

### Model Details

```dart
// In IPFSModelDownloader
static const String DEFAULT_MODEL_CID = 'QmYourModelCIDHere';
static const String DEFAULT_MODEL_NAME = 'Qwen3-1.7B-Q6_K.gguf';
static const int DEFAULT_MODEL_SIZE = 1635000000; // ~1.56 GB
```

### Model Specifications

- **Name:** Qwen 3 1.7B
- **Quantization:** Q6_K (6-bit)
- **Size:** ~1.56 GB
- **Format:** GGUF
- **Purpose:** Default AI model for encryption and chat

### Storage Location

```
~/.vectorchat/models/Qwen3-1.7B-Q6_K.gguf
```

---

## User Experience

### First-Time Launch

**Scenario:** User launches VectorChat for the first time

**Flow:**
1. App initializes
2. Detects no model configured
3. Checks for default model locally
4. Model not found
5. Shows download dialog automatically
6. Downloads from IPFS with progress
7. Model saved and loaded
8. App ready to use

**User sees:**
```
┌─────────────────────────────────────────┐
│ 📥 Downloading AI Model              ✕ │
├─────────────────────────────────────────┤
│ Qwen3-1.7B (Q6)                         │
│ Downloading from IPFS network...        │
│                                         │
│ ████████████░░░░░░░░░  65.3%           │
│ 1.02 GB / 1.56 GB                       │
│                                         │
│ ⏳ Downloading: 1.02 GB / 1.56 GB...   │
│                                         │
│ ℹ️ This is a one-time download.        │
│   The model will be cached locally.    │
└─────────────────────────────────────────┘
```

### Subsequent Launches

**Scenario:** User launches VectorChat again

**Flow:**
1. App initializes
2. Detects model configured
3. Loads model from cache
4. No download needed
5. App ready immediately

---

## Implementation Details

### Download Process

```dart
// 1. Check if model exists
final hasModel = await ipfsDownloader.hasDefaultModel();

if (!hasModel) {
  // 2. Show download dialog
  final modelPath = await showModelDownloadDialog(context);
  
  // 3. Save model path
  settings.lastModelPath = modelPath;
  await settingsService.saveSettings(settings);
  
  // 4. Load model
  await aiModel.loadModel(customPath: modelPath);
}
```

### Progress Tracking

```dart
// Setup callbacks
downloader.onProgress = (progress, downloaded, total) {
  setState(() {
    _progress = progress;
    _downloadedBytes = downloaded;
    _totalBytes = total;
  });
};

downloader.onStatusUpdate = (message) {
  setState(() {
    _status = message;
  });
};

downloader.onComplete = (modelPath) {
  // Download complete
  Navigator.pop(context, modelPath);
};
```

### Gateway Fallback

```dart
for (final gateway in IPFS_GATEWAYS) {
  try {
    final path = await _downloadFromGateway(
      gateway: gateway,
      cid: cid,
      outputPath: modelPath,
    );
    
    if (path != null) {
      return path; // Success!
    }
  } catch (e) {
    continue; // Try next gateway
  }
}
```

---

## Configuration

### Setting Up IPFS CID

**TODO:** Upload Qwen 3 1.7B model to IPFS and get CID

**Steps:**
1. Download Qwen 3 1.7B Q6_K model
2. Add to IPFS: `ipfs add Qwen3-1.7B-Q6_K.gguf`
3. Get CID (e.g., `QmXxXxXx...`)
4. Update `DEFAULT_MODEL_CID` in `ipfs_model_downloader.dart`
5. Pin on multiple nodes for availability

**Pinning Services:**
- Pinata (https://pinata.cloud)
- Web3.Storage (https://web3.storage)
- NFT.Storage (https://nft.storage)
- Filebase (https://filebase.com)

### Custom Model Configuration

Users can override the default model:

```dart
// Download custom model
await ipfsDownloader.downloadDefaultModel(
  customCID: 'QmCustomModelCID',
  customName: 'CustomModel.gguf',
);
```

---

## Error Handling

### Scenarios

#### 1. **All Gateways Fail**
```
Error: All IPFS gateways failed
Action: Show retry button
```

#### 2. **Network Timeout**
```
Error: Gateway timeout
Action: Try next gateway automatically
```

#### 3. **Disk Space**
```
Error: Insufficient disk space
Action: Show error, suggest cleanup
```

#### 4. **Corrupted Download**
```
Error: Downloaded file is empty
Action: Retry download
```

### User Actions

**Retry Button:**
- Clears error state
- Restarts download from beginning
- Tries all gateways again

**Cancel Button:**
- Stops download
- Closes dialog
- User can select model manually

---

## Testing

### Test Scenarios

#### 1. **First-Time User**
```bash
# Clear settings
rm ~/.vectorchat/settings.json

# Clear models
rm -rf ~/.vectorchat/models/

# Launch app
flutter run
```

**Expected:** Download dialog appears automatically

#### 2. **Model Already Downloaded**
```bash
# Model exists
ls ~/.vectorchat/models/Qwen3-1.7B-Q6_K.gguf

# Launch app
flutter run
```

**Expected:** No download, model loads immediately

#### 3. **Download Cancellation**
```bash
# Launch app
flutter run

# Click cancel during download
```

**Expected:** Download stops, dialog closes

#### 4. **Gateway Fallback**
```bash
# Disable local IPFS
# Launch app with no model
```

**Expected:** Falls back to public gateways

---

## Performance

### Download Speed

**Factors:**
- Gateway location
- Network bandwidth
- IPFS node availability
- Model size

**Typical Times:**
- Local IPFS: 30-60 seconds
- Public gateway: 2-5 minutes
- Slow connection: 10-15 minutes

### Caching

**Benefits:**
- One-time download
- Instant subsequent launches
- No bandwidth waste
- Offline capability

---

## Future Enhancements

### Planned Features

1. **Resume Support**
   - Resume interrupted downloads
   - Partial file recovery
   - Checkpoint system

2. **Multiple Models**
   - Download different models
   - Model library
   - Easy switching

3. **Peer-to-Peer**
   - Share models between users
   - Local network discovery
   - Faster distribution

4. **Compression**
   - Compressed downloads
   - Decompress on device
   - Smaller bandwidth usage

5. **Verification**
   - SHA256 checksums
   - Model integrity checks
   - Signature verification

6. **Background Download**
   - Download while using app
   - Non-blocking UI
   - Progress notification

---

## Security

### Considerations

**Content Addressing:**
- CID is hash of content
- Tamper-proof
- Verifiable integrity

**HTTPS Gateways:**
- Encrypted transport
- Prevents MITM attacks
- Secure downloads

**Local Verification:**
- File size check
- Empty file detection
- Corruption detection

---

## Troubleshooting

### Common Issues

#### Download Stuck at 0%
**Cause:** No gateway accessible  
**Solution:** Check internet connection, try manual download

#### Very Slow Download
**Cause:** Public gateway congestion  
**Solution:** Wait or run local IPFS node

#### Download Fails Repeatedly
**Cause:** Model not pinned on IPFS  
**Solution:** Verify CID, check pinning services

#### Out of Disk Space
**Cause:** Insufficient storage  
**Solution:** Free up space, model needs ~2GB

---

## Related Files

### Created:
- `lib/services/ipfs_model_downloader.dart` - Download service
- `lib/widgets/model_download_dialog.dart` - Progress UI
- `IPFS_MODEL_DOWNLOAD_FEATURE.md` - This documentation

### Modified:
- `lib/main.dart` - Added download check
- `lib/screens/chat_screen.dart` - Added download dialog trigger

### Dependencies:
- `http` package - HTTP requests
- `path` package - File path handling

---

## Notes

- **CID Placeholder:** Currently using placeholder CID, needs actual model CID
- **Model Size:** Hardcoded for now, should be fetched from IPFS metadata
- **Gateway List:** Can be extended with more gateways
- **Timeout:** 30 seconds per gateway, configurable

---

**Status:** Implementation complete, awaiting IPFS CID for actual model.

**Next Steps:**
1. Upload Qwen 3 1.7B to IPFS
2. Get CID and update code
3. Pin on multiple services
4. Test end-to-end flow
5. Deploy to users