AI Edge Model DL (Downloader)

A Flutter plugin for downloading and managing AI models efficiently, with seamless integration for AI Edge packages. Simplifies model path management and provides resumable downloads, progress tracking, and automatic validation.

Features

• 🤝 AI Edge Integration - Seamless path resolution for AI Edge packages - just pass the model path directly
• 📥 Resumable Downloads - Automatically resume interrupted downloads from where they left off
• 📊 Progress Tracking - Real-time download progress with speed and time estimates
• ✅ Checksum Validation - Automatic MD5/SHA256 validation to ensure model integrity
• 🔄 Parallel Downloads - Concurrent chunk downloading for faster speeds
• 💾 Smart Storage - Platform-specific directory management with customizable paths
• 🎯 File Management - List, check, and delete downloaded models
• ⚡ Optimized Performance - Configurable chunk size and connection settings

Installation

flutter pub add ai_edge_model_dl

Or add it manually to your pubspec.yaml:

dependencies:
  ai_edge_model_dl:

Getting Started

Basic Usage

import 'package:ai_edge_model_dl/ai_edge_model_dl.dart';

// Create a downloader instance
final downloader = ModelDownloader();

// Download a model
final result = await downloader.downloadModel(
  Uri.parse('https://example.com/model.task'),
  fileName: 'gemma.task',
  expectedChecksum: 'abc123...', // Optional MD5 or SHA256
  expectedFileSize: 1024000,     // Optional size validation
  onProgress: (progress) {
    print('Progress: ${(progress.progress * 100).toStringAsFixed(1)}%');
    print('Speed: ${progress.speed}');
    print('Remaining: ${progress.remainingTime}');
  },
);

print('Model downloaded to: ${result.filePath}');
print('Size: ${result.fileSize} bytes');
print('Checksum: ${result.checksum}');

Integration with AI Edge

import 'package:ai_edge/ai_edge.dart';
import 'package:ai_edge_model_dl/ai_edge_model_dl.dart';

// Download and use model with AI Edge
final downloader = ModelDownloader();

// Download model
final result = await downloader.downloadModel(
  Uri.parse('https://example.com/gemma.task'),
  fileName: 'gemma.task',
);

// Use directly with AI Edge - path resolution is handled automatically
final aiEdge = AiEdge.instance;
await aiEdge.initialize(
  modelPath: result.filePath,  // Direct path usage - no manual path management needed
  maxTokens: 512,
);

// Or check if model exists before initializing
final modelPath = await downloader.getModelPath('gemma.task');
if (await downloader.isModelDownloaded('gemma.task')) {
  await aiEdge.initialize(
    modelPath: modelPath,
    maxTokens: 512,
  );
}

Configuration

// Create a downloader with custom configuration
final downloader = ModelDownloader(
  config: const ModelDownloaderConfig(
    // Custom base directory (default: platform-specific)
    baseDirectory: '/custom/path',

    // Subdirectory for models (default: 'models')
    modelSubdirectory: 'ai_models',

    // Download settings
    chunkSize: 5 * 1024 * 1024,  // 5MB chunks
    maxConcurrentRequests: 4,     // Parallel connections
    maxRetries: 3,                // Retry attempts
    connectionTimeout: Duration(seconds: 30),

    // Validation
    checksumType: ChecksumType.sha256,
    validationFailureAction: ValidationFailureAction.deleteAndError,

    // Progress updates
    progressInterval: Duration(milliseconds: 500),

    // File conflict strategy
    conflictStrategy: FileConflictStrategy.overwrite,

    // Custom headers (e.g., for authentication)
    headers: {'Authorization': 'Bearer token'},
  ),
);

Usage

Download with Progress Tracking

await downloader.downloadModel(
  Uri.parse('https://huggingface.co/model.task'),
  fileName: 'model.task',
  onProgress: (progress) {
    // Progress information
    print('Downloaded: ${progress.downloadedSize} / ${progress.totalSize}');
    print('Progress: ${(progress.progress * 100).toStringAsFixed(1)}%');
    print('Speed: ${progress.speed}');

    // Time estimates
    print('Remaining time: ${progress.remainingTime}');

    // Custom time formatting
    final formatted = progress.formatRemainingTime('H hours M minutes');
    print('Time left: $formatted');
  },
);

Checksum Validation

// MD5 validation (32 characters)
final result = await downloader.downloadModel(
  modelUri,
  expectedChecksum: 'd41d8cd98f00b204e9800998ecf8427e',
);

// SHA256 validation (64 characters)
final result = await downloader.downloadModel(
  modelUri,
  expectedChecksum: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
);

// File size validation
final result = await downloader.downloadModel(
  modelUri,
  expectedFileSize: 1024000, // Expected size in bytes
);

Cancel Downloads

// Start a download
final downloadFuture = downloader.downloadModel(
  modelUri,
  onProgress: (progress) {
    print('Progress: ${progress.progress}');
  },
);

// Cancel if needed (uses CancelToken internally)
downloader.cancelDownload();

// Handle cancellation
try {
  await downloadFuture;
} catch (e) {
  print('Download cancelled or failed: $e');
}

Model Management

// Get models directory path
final modelsDir = await downloader.getModelsDirectory();
print('Models stored in: $modelsDir');

// Get path for a specific model
final modelPath = await downloader.getModelPath('gemma.task');
print('Model path: $modelPath');

// Check if a model exists
final exists = await downloader.isModelDownloaded('gemma.task');
print('Model exists: $exists');

// List all downloaded models
final models = await downloader.getDownloadedModels();
for (final model in models) {
  print('Found model: $model');
}

// Delete a model
await downloader.deleteModel('old_model.task');

Error Handling

try {
  final result = await downloader.downloadModel(
    modelUri,
    expectedChecksum: 'abc123...',
    expectedFileSize: 1024000,
  );
} on ModelDownloaderException catch (e) {
  switch (e.code) {
    case ModelDownloaderErrorCode.checksumMismatch:
      print('Checksum validation failed: ${e.message}');
    case ModelDownloaderErrorCode.fileSizeMismatch:
      print('File size validation failed: ${e.message}');
    case ModelDownloaderErrorCode.invalidChecksumFormat:
      print('Invalid checksum format: ${e.message}');
  }
} catch (e) {
  // Handle other exceptions (network errors, etc.)
  print('Download failed: $e');
}

Resume Interrupted Downloads

Downloads are automatically resumed if interrupted. The downloader:

1. Detects partial downloads (.tmp files)
2. Verifies existing chunks
3. Continues from the last successful position
4. Validates the complete file after resuming

// If this download is interrupted...
await downloader.downloadModel(
  modelUri,
  fileName: 'large_model.task',
);

// ...calling it again will resume from where it stopped
await downloader.downloadModel(
  modelUri,
  fileName: 'large_model.task',
);

Platform Setup

iOS

No additional setup required. Models are stored in the app's Application Support directory.

Android

No additional setup required. Models are stored in the app's external storage directory (if available) or Application Support directory.

Storage Locations

By default, models are stored in:

• iOS: <app_support>/models/ (Application Support directory - not backed up to iCloud)
• Android: <external_storage>/models/ or <app_support>/models/ (External storage preferred for better space availability)

You can customize the storage location:

final downloader = ModelDownloader(
  config: const ModelDownloaderConfig(
    baseDirectory: '/custom/path',
    modelSubdirectory: 'ai_models',
  ),
);

API Reference

Main Classes

ModelDownloader

The main class for downloading and managing models.

ModelDownloaderConfig

Configuration options:

• baseDirectory: Custom base directory path (nullable)
• modelSubdirectory: Subdirectory name for models (default: 'models')
• headers: HTTP headers for requests
• checksumType: Type of checksum validation (ChecksumType.md5, ChecksumType.sha256, ChecksumType.none)
• conflictStrategy: How to handle existing files (FileConflictStrategy.overwrite, FileConflictStrategy.rename, FileConflictStrategy.error)
• progressInterval: How often to emit progress updates
• connectionTimeout: HTTP connection timeout
• maxConcurrentRequests: Number of parallel connections
• chunkSize: Size of each download chunk in bytes
• maxRetries: Number of retry attempts
• tempFileExtension: Extension for temporary files during download (default: '.tmp')
• validationFailureAction: Action on validation failure (ValidationFailureAction.deleteAndError, ValidationFailureAction.keepAndError)

ModelDownloadProgress

Download progress information:

• progress: Download percentage (0.0 to 1.0)
• downloadedBytes: Bytes downloaded so far
• totalBytes: Total file size
• bytesPerSecond: Current download speed
• estimatedTimeRemaining: Estimated time to completion
• downloadedSize: Human-readable downloaded size (e.g., "1.5 MB")
• totalSize: Human-readable total size
• speed: Human-readable speed (e.g., "2.5 MB/s")
• remainingTime: Formatted remaining time
• formatRemainingTime(pattern): Custom time formatting

ValidationFailureAction

Actions when validation fails:

• deleteAndError: Delete the file and throw error (default)
• keepAndError: Keep the file and throw error

ModelDownloaderException

Exception class for model downloader errors:

• code: Error code (ModelDownloaderErrorCode)
• message: Human-readable error message
• details: Optional details map with error-specific information

ModelDownloaderErrorCode

Error codes for exception handling:

• checksumMismatch: Checksum validation failed
• fileSizeMismatch: File size validation failed
• invalidChecksumFormat: Invalid checksum format (wrong length)

Example App

Check out the complete example in the repository for demonstrations of:

• Model downloading with progress UI
• Resume capability after app restart
• Download cancellation
• Error handling
• Model management (list, delete)

Troubleshooting

Common Issues

Download fails immediately:

• Check network connectivity
• Verify the URL is accessible
• Ensure proper headers are set if authentication is required

Checksum validation fails:

• Verify the expected checksum is correct
• Ensure the checksum type matches (MD5 vs SHA256)
• Check if the file is corrupted during download

Out of storage space:

• Check available device storage
• Clean up old models using deleteModel()
• Consider downloading to external storage on Android

Slow download speeds:

• Increase chunkSize for better throughput
• Adjust maxConcurrentRequests based on server capabilities
• Check network connection quality

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Links

• Pub.dev Package
• GitHub Repository
• Issue Tracker