initialize static method

Future<void> initialize({ String? huggingFaceToken, int maxDownloadRetries = 10, WebStorageMode webStorageMode = WebStorageMode.cacheApi, @Deprecated('Use webStorageMode instead. Scheduled for removal in 1.0.') bool? enableWebCache, List<InferenceEngineProvider> inferenceEngines = const [], List<EmbeddingBackendProvider> embeddingBackends = const [], List<SkillExecutorProvider> skillExecutors = const [], VectorStoreRepository? vectorStore, FilterSchema filterSchema = const FilterSchema(), Stream<Object>? downloadUpdatesStream, FileSystemService? fileSystemService, })

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 [],
  // Opt-in agentic "skills" runtime, provided by the `flutter_gemma_agent`
  // package (each executor `implements SkillExecutorProvider`). Core holds
  // only this list + the probe-chain [SkillExecutorRegistry]; the concrete
  // `SkillExecutor` / `SkillResult` types live in the agent package so core
  // stays dependency-free (no webview_flutter / url_launcher). Empty default
  // is a no-op — existing apps are unaffected.
  List<SkillExecutorProvider> skillExecutors = const [],
  VectorStoreRepository? vectorStore,
  // Declares which metadata fields the configured [vectorStore] should make
  // filterable. Threaded to the store via `configure()` at registration,
  // BEFORE its `initialize()`, so it can promote the declared fields to typed
  // storage columns (sqlite/vec0) or top-level payload keys (qdrant). The
  // empty default keeps every store in its existing "filters are a safe
  // no-op" mode.
  FilterSchema filterSchema = const FilterSchema(),

  /// Optional host-provided broadcast of download task updates (mobile).
  ///
  /// On iOS/Android, events must be [TaskUpdate] values from
  /// `package:background_downloader` — the same shape as
  /// [FileDownloader.updates]. Ignored on web. When omitted,
  /// [SmartDownloader] uses its internal broadcast wrapper.
  Stream<Object>? downloadUpdatesStream,

  /// Optional custom model file storage (e.g. outside Documents).
  ///
  /// [FileSystemService] is defined in core but not exported from the
  /// public barrel; pass an implementation from your app or tests.
  FileSystemService? fileSystemService,
}) 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,
    filterSchema: filterSchema,
    downloadUpdatesStream: downloadUpdatesStream,
    fileSystemService: fileSystemService,
  );

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

  // 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();
}