initialize static method

Future<void> initialize({
  1. String? huggingFaceToken,
  2. int maxDownloadRetries = 10,
  3. WebStorageMode webStorageMode = WebStorageMode.cacheApi,
  4. @Deprecated('Use webStorageMode instead. Scheduled for removal in 1.0.') bool? enableWebCache,
  5. List<InferenceEngineProvider> inferenceEngines = const [],
  6. List<EmbeddingBackendProvider> embeddingBackends = const [],
  7. VectorStoreRepository? vectorStore,
})

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. Converts to webStorageMode internally; scheduled for removal in 1.0.

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. Scheduled for removal in 1.0.')
  bool? enableWebCache,
  // Opt-in registration. Engines/backends are FULLY opt-in: core registers
  // NONE by default. Pass the providers from the packages you use, e.g.
  // `LiteRtLmEngine()` (flutter_gemma_litertlm), `MediaPipeEngine()`
  // (flutter_gemma_mediapipe), `LiteRtEmbeddingBackend()`
  // (flutter_gemma_embeddings). If the lists are empty, the first
  // createModel / createEmbeddingModel throws a clear "add the engine
  // package" StateError. vectorStore null → ServiceRegistry's
  // UnconfiguredVectorStore sentinel (RAG is opt-in; it throws a clear "add a
  // RAG package" error on first use).
  List<InferenceEngineProvider> inferenceEngines = const [],
  List<EmbeddingBackendProvider> embeddingBackends = const [],
  VectorStoreRepository? vectorStore,
}) 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,
    vectorStoreRepository: vectorStore,
  );

  if (inferenceEngines.isNotEmpty) {
    EngineRegistry.instance.registerAll(inferenceEngines);
  }
  if (embeddingBackends.isNotEmpty) {
    EmbeddingRegistry.instance.registerAll(embeddingBackends);
  }

  // Single-flight model-manager init: restore the previously-active model
  // identity from storage before the app reads it (#227/#314). Awaited here
  // so the first getActiveModel/isModelInstalled after initialize() can't
  // race an in-flight restore. Restore failure degrades to no-active-model.
  await FlutterGemmaPlugin.instance.modelManager.ensureInitialized();
}