initialize static method

Future<void> initialize({
  1. String? huggingFaceToken,
  2. int maxDownloadRetries = 10,
  3. WebStorageMode webStorageMode = WebStorageMode.cacheApi,
  4. FileSystemService? fileSystemService,
  5. AssetLoader? assetLoader,
  6. DownloadService? downloadService,
  7. ModelRepository? modelRepository,
  8. ProtectedFilesRegistry? protectedFilesRegistry,
  9. VectorStoreRepository? vectorStoreRepository,
})

Initializes the singleton instance

Call this once at app startup, before using instance. Multiple calls to initialize() are safe - subsequent calls are ignored.

Parameters:

  • huggingFaceToken: Optional HuggingFace API token for authenticated downloads
  • maxDownloadRetries: Maximum retry attempts for transient errors (default: 10) Note: Auth errors (401/403/404) fail after 1 attempt regardless
  • webStorageMode: Storage mode for web platform (default: WebStorageMode.cacheApi) Note: This parameter only affects web platform, ignored on mobile
  • vectorStoreRepository: Optional custom repository (for testing)
  • Services can be overridden for testing (dependency injection)

Note: This is async because web platform requires SharedPreferences initialization.

Implementation

static Future<void> initialize({
  String? huggingFaceToken,
  int maxDownloadRetries = 10,
  WebStorageMode webStorageMode = WebStorageMode.cacheApi,
  FileSystemService? fileSystemService,
  AssetLoader? assetLoader,
  DownloadService? downloadService,
  ModelRepository? modelRepository,
  ProtectedFilesRegistry? protectedFilesRegistry,
  VectorStoreRepository? vectorStoreRepository,
}) async {
  // Make idempotent - skip if already initialized
  if (_instance != null) {
    // Warn if critical parameters changed
    if (_instance!.webStorageMode != webStorageMode) {
      debugPrint(
          'WARNING: webStorageMode cannot be changed after initialization.\n'
          'Current: ${_instance!.webStorageMode}, Requested: $webStorageMode\n'
          'Restart the application to change this setting.');
    }
    debugPrint(
        'ServiceRegistry: Already initialized, skipping re-initialization');
    return;
  }

  _instance = await _create(
    huggingFaceToken: huggingFaceToken,
    maxDownloadRetries: maxDownloadRetries,
    webStorageMode: webStorageMode,
    fileSystemService: fileSystemService,
    assetLoader: assetLoader,
    downloadService: downloadService,
    modelRepository: modelRepository,
    protectedFilesRegistry: protectedFilesRegistry,
    vectorStoreRepository: vectorStoreRepository,
  );
}