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.
getActiveEmbedder({PreferredBackend? preferredBackend}) → Future<EmbeddingModel>
Get the active embedding model as a ready-to-use EmbeddingModel
getActiveModel({int maxTokens = 1024, PreferredBackend? preferredBackend, bool supportImage = false, bool supportAudio = false, int? maxNumImages, bool? enableSpeculativeDecoding, int? maxConcurrentSessions}) → Future<InferenceModel>
Get the active inference model as a ready-to-use InferenceModel
getActiveStt({PreferredBackend? preferredBackend}) → Future<SpeechRecognizer>
Get the active STT model as a ready-to-use SpeechRecognizer
getActiveTts({PreferredBackend? preferredBackend}) → 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 [], 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
performCleanup() → Future<void>
Delete orphaned files and stale metadata left by interrupted installs.
reset() → void
Reset ServiceRegistry (primarily for testing)
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.