FlutterGemma class

Modern API facade for Flutter Gemma

Provides clean, type-safe API for model management and inference.

Initialization

Initialize once at app startup:

void main() {
  FlutterGemma.initialize(
    huggingFaceToken: 'hf_...',     // Optional: for gated models
    maxDownloadRetries: 10,         // Optional: default is 10
  );
  runApp(MyApp());
}

Install Models

// From network
final installation = await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromNetwork('https://huggingface.co/.../model.bin')
  .withProgress((progress) => print('Progress: $progress%'))
  .install();

// From asset
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromAsset('models/gemma.bin')
  .install();

// From bundled resource
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromBundled('gemma.bin')
  .install();

// From external file
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromFile('/path/to/model.bin')
  .install();

Load Models

// Get active model after installation
final model = await FlutterGemma.getActiveModel(maxTokens: 1024);
final session = await model.createSession();
final response = await session.getResponse();

Constructors

FlutterGemma()

Properties

hashCode → int: The hash code for this object.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Properties

activeEmbedderSpec → EmbeddingModelSpec?: The active embedding model's identity (EmbeddingModelSpec), or null.
no setter
activeModelSpec → InferenceModelSpec?: The active inference model's identity (its InferenceModelSpec), or null if none is set. Cheap synchronous read — does NOT load the engine (use getActiveModel for that). hasActiveModel() == (activeModelSpec != null).
no setter
activeSttSpec → SttModelSpec?: The active STT model's identity (SttModelSpec), or null.
no setter
activeTtsSpec → TtsModelSpec?: The active TTS model's identity (TtsModelSpec), or null.
no setter
logLevel ↔ GemmaLogLevel: Controls flutter_gemma's internal log verbosity.
getter/setter pair

Static Methods

cleanupStorage() → Future<int>: Delete orphaned files; returns the number of files removed.
clearActiveEmbeddingIdentity() → Future<void>: Clears the active embedding identity (in-memory spec + persisted prefs).
clearActiveInferenceIdentity() → Future<void>: Clears the active inference identity (in-memory spec + persisted prefs).
clearActiveSttIdentity() → Future<void>: Clears the active STT identity (in-memory spec + persisted prefs).
clearActiveTtsIdentity() → Future<void>: Clears the active TTS identity (in-memory spec + persisted prefs).
dispose() → Future<void>: Closes the active vector store (releasing its native handle — qdrant-edge shard / sqlite connection) and then resets the DI singleton.
engineHuggingFaceResolvers(List<InferenceEngineProvider> engines) → List<HuggingFaceResolver>: The Hugging Face resolvers contributed by engines that implement HuggingFaceResolverSource (e.g. LiteRtLmEngine → LitertlmManifestResolver). initialize registers these AFTER the explicit huggingFaceResolvers: list, so an app's explicit resolver wins the equal-priority tie. An engine that does not implement HuggingFaceResolverSource contributes nothing. Extracted so the derivation is unit-testable without a full initialize.
getActiveEmbedder({PreferredBackend? preferredBackend}) → Future<EmbeddingModel>: Get the active embedding model as a ready-to-use EmbeddingModel
getActiveModel({ModelRuntimeDefaults? defaults, int? maxTokens, PreferredBackend? preferredBackend, PreferredBackend? preferredVisionBackend, PreferredBackend? preferredAudioBackend, bool? supportImage, bool? supportAudio, int? maxNumImages, bool? enableSpeculativeDecoding, int? maxConcurrentSessions}) → Future<InferenceModel>: Get the active inference model as a ready-to-use InferenceModel
getActiveStt({PreferredBackend? preferredBackend, String? language}) → Future<SpeechRecognizer>: Get the active STT model as a ready-to-use SpeechRecognizer
getActiveTts({PreferredBackend? preferredBackend, String? language}) → Future<SpeechSynthesizer>: Get the active TTS model as a ready-to-use SpeechSynthesizer
getModelPath(String fileName) → Future<String>: Absolute on-device read path for an installed model file, keyed by its fileName (the file's basename, e.g. gemma-4-E2B-it.litertlm). On web this resolves to a URL/OPFS handle, not a filesystem path. The path is computed, not stat-ed — it is returned even if nothing is installed there.
getOrphanedFiles() → Future<List<OrphanedFileInfo>>: Files on disk that have no matching installed-model metadata.
getStorageInfo() → Future<StorageStats>: Current on-device storage usage across installed models.
hasActiveEmbedder() → bool: Check if there's an active embedding model
hasActiveModel() → bool: Check if there's an active inference model
hasActiveStt() → bool: Check if there's an active STT model
hasActiveTts() → bool: Check if there's an active TTS model
initialize({String? huggingFaceToken, int maxDownloadRetries = 10, WebStorageMode webStorageMode = WebStorageMode.cacheApi, bool? enableWebCache, List<InferenceEngineProvider> inferenceEngines = const [], List<EmbeddingBackendProvider> embeddingBackends = const [], List<SttBackendProvider> sttBackends = const [], List<TtsBackendProvider> ttsBackends = const [], List<SkillExecutorProvider> skillExecutors = const [], List<HuggingFaceResolver> huggingFaceResolvers = const [], VectorStoreRepository? vectorStore, FilterSchema filterSchema = const FilterSchema(), Stream<Object>? downloadUpdatesStream, FileSystemService? fileSystemService}) → Future<void>: Initialize Flutter Gemma
installEmbedder() → EmbeddingInstallationBuilder: Start building an embedding model installation
installModel({required ModelType modelType, ModelFileType fileType = ModelFileType.task}) → InferenceInstallationBuilder: Start building an inference model installation
installStt() → SttInstallationBuilder: Start building an STT (speech-to-text) model installation
installTts() → TtsInstallationBuilder: Start building a TTS (text-to-speech) model installation
isModelInstalled(String modelId) → Future<bool>: Check if a model is installed
isStreamingSupported() → Future<bool>: Check if OPFS streaming mode is supported by the current browser
listInstalledModels() → Future<List<String>>: List all installed models
mergeRuntimeDefault<T>(T? explicit, T? manifest, T sdkDefault) → T: Three-tier runtime-default merge used by getActiveModel: an explicit argument wins over a manifest ModelRuntimeDefaults value, which wins over the SDK default. Extracted so the precedence rule is stated — and tested — in one place.
performCleanup() → Future<void>: Delete orphaned files and stale metadata left by interrupted installs.
reset() → void: Reset ServiceRegistry (primarily for testing)
resolveHuggingFace(String repo, {ModelFileType? fileType, String? token, PreferredBackend? preferredBackend}) → Future<ResolvedHfModel>: Resolves a Hugging Face repo id into a ResolvedHfModel by reading that repo's deployment metadata (e.g. litertlm_manifest.json), using a resolver registered via initialize — either passed in huggingFaceResolvers: or auto-derived from a registered engine that ships one (LiteRtLmEngine, OnnxEngine, BuiltInAiEngine).
uninstallEmbedder() → Future<void>: Uninstall the active embedding model — deletes ALL its files (model + tokenizer) and clears the active-embedder identity. No-op if none active.
uninstallModel(String modelId) → Future<void>: Uninstall a model
uninstallStt() → Future<void>: Uninstall the active STT model — deletes all its files and clears the active-STT identity. No-op if none active.
uninstallTts() → Future<void>: Uninstall the active TTS model — deletes all its files and clears the active-TTS identity. No-op if none active.

Constants

rag → const GemmaRag: Retrieval-augmented-generation (vector store) operations, namespaced.

FlutterGemma class

Initialization

Install Models

Load Models

Constructors

Properties

Methods

Operators

Static Properties

Static Methods

Constants

flutter_gemma library