initialize static method

Future<void> initialize({ String? huggingFaceToken, int maxDownloadRetries = 10, WebStorageMode webStorageMode = WebStorageMode.cacheApi, @Deprecated('Use webStorageMode instead. Will be removed in v0.13.0') bool? enableWebCache, })

Initialize Flutter Gemma

Call this once at app startup before using any other API.

Parameters:

• huggingFaceToken: Optional HuggingFace API token for authenticated downloads
• maxDownloadRetries: Maximum retry attempts for transient errors (default: 10) Note: Auth errors (401/403/404) always fail after 1 attempt
• webStorageMode: Storage mode for web platform (default: WebStorageMode.cacheApi)
  • cacheApi: Cache API with Blob URLs (for models <2GB)
  • streaming: OPFS with streaming (for models >2GB like E4B, 7B, 27B)
  • none: No caching (ephemeral, for development) Note: This parameter only affects web platform, ignored on mobile
• enableWebCache: DEPRECATED - Use webStorageMode instead Will be removed in v0.13.0. Converts to webStorageMode internally.

Example:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // For small models (<2GB) - default
  await FlutterGemma.initialize();

  // For large models (>2GB)
  await FlutterGemma.initialize(
    webStorageMode: WebStorageMode.streaming,
  );

  runApp(MyApp());
}

Implementation

static Future<void> initialize({
  String? huggingFaceToken,
  int maxDownloadRetries = 10,
  WebStorageMode webStorageMode = WebStorageMode.cacheApi,
  @Deprecated('Use webStorageMode instead. Will be removed in v0.13.0')
  bool? enableWebCache,
}) async {
  // Migration: enableWebCache takes precedence if provided (for backward compatibility)
  final effectiveStorageMode = enableWebCache != null
      ? (enableWebCache ? WebStorageMode.cacheApi : WebStorageMode.none)
      : webStorageMode;

  await ServiceRegistry.initialize(
    huggingFaceToken: huggingFaceToken,
    maxDownloadRetries: maxDownloadRetries,
    webStorageMode: effectiveStorageMode,
  );
}