### Install External File Model

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Example of installing a model from a local file path on native platforms.

```dart
// Native only - after user selects file with file_picker
final path = '/data/user/0/com.app/files/model.litertlm';
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromFile(path)
  .install();
```

--------------------------------

### Web Setup for Embeddings and VectorStore (Local Build)

Source: https://github.com/denisovav/flutter_gemma/blob/main/docs/LEGACY_API.md

Build the JavaScript modules locally by navigating to the web/rag directory, installing dependencies, and running the build command. Copy the output to your web project and add the script tags to index.html.

```bash
# Navigate to web/rag directory
cd <flutter_gemma_package_path>/web/rag

# Install dependencies
npm install

# Build modules (embeddings + VectorStore)
npm run build

# Copy to your web project
cp dist/* <your_flutter_project>/web/

# Add script tags to index.html
<script type="module" src="litert_embeddings.js"></script>
<script type="module" src="sqlite_vector_store.js"></script>
```

--------------------------------

### Run the example application

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma_speech/example/README.md

Commands to navigate to the example directory and launch the application on macOS.

```bash
cd packages/flutter_gemma_speech/example
flutter run -d macos      # verified target (see below)
```

--------------------------------

### Run the example application

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/CONTRIBUTING.md

Commands to navigate to the example directory and launch the application on various platforms.

```bash
cd example
flutter pub get

# Run on your preferred platform:
flutter run -d chrome       # Web
flutter run -d android      # Android
flutter run -d ios          # iOS
flutter run -d windows      # Windows
flutter run -d macos        # macOS
```

--------------------------------

### Install Bundled Model

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Example of installing a model from the application bundle using the FlutterGemma API.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
)
  .fromBundled('gemma3-270m-it-q8.litertlm')
  .install();
```

--------------------------------

### Install Model from Network

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from a network URL. It allows tracking installation progress via a callback.

```APIDOC
## Install Model from Network

### Description
Installs a model from a network URL. It allows tracking installation progress via a callback.

### Method
`FlutterGemma.installModel().fromNetwork(url).withProgress(callback).install()`

### Parameters
- **url** (string) - Required - The URL of the model file.
- **callback** (Function(double)) - Optional - A function that receives the installation progress (0.0 to 1.0).
```

--------------------------------

### Install Models from Network

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Compare legacy network model installation with the modern builder-pattern approach.

```dart
// Network download
final spec = MobileModelManager.createInferenceSpec(
  name: 'model.bin',
  modelUrl: 'https://example.com/model.bin',
);

await FlutterGemmaPlugin.instance.modelManager
  .downloadModelWithProgress(spec, token: token)
  .listen((progress) {
    print('${progress.overallProgress}%');
  });
```

```dart
// Network download
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromNetwork(
    'https://example.com/model.bin',
    token: token,
  )
  .withProgress((progress) {
    print('$progress%');
  })
  .install();
```

--------------------------------

### Install Application Executable

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_flutter_gemma/example/windows/CMakeLists.txt

Installs the main application executable to the runtime destination.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)
```

--------------------------------

### Install Model from Network

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from a network URL (HTTP/HTTPS). Includes progress reporting during the download and installation process.

```dart
final installation = await FlutterGemma.installModel()
  .fromNetwork('https://huggingface.co/.../model.bin')
  .withProgress((progress) => print('Progress: $progress%'))
  .install();
```

--------------------------------

### Install a native ONNX model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/onnx.md

Install a model from a local directory path.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.general,
  fileType: ModelFileType.onnx,
).fromFile('/path/to/my-model/genai_config.json').install();
```

--------------------------------

### Install Dependencies

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/web/rag/README.md

Navigate to the RAG directory and install required npm packages.

```bash
# Navigate to this directory
cd <your_flutter_gemma_package_path>/web/rag

# Install npm packages (one-time setup)
npm install
```

--------------------------------

### Get and Install Model Source Handler

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Retrieve the appropriate handler for a given model source from the registry and use it to install the source.

```dart
final handler = handlerRegistry.getHandler(source);
await handler.install(source);
```

--------------------------------

### Initialize and setup Genkit Flutter Gemma

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/genkit.md

Register inference engines, install models, and instantiate the Genkit plugin.

```dart
import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:flutter_gemma_litertlm/flutter_gemma_litertlm.dart';
import 'package:flutter_gemma_mediapipe/flutter_gemma_mediapipe.dart';
import 'package:genkit/genkit.dart';
import 'package:genkit_flutter_gemma/genkit_flutter_gemma.dart';

// 1. Register providers (call once in main).
await FlutterGemma.initialize(
  inferenceEngines: const [LiteRtLmEngine(), MediaPipeEngine()],
  embeddingBackends: const [LiteRtEmbeddingBackend()], // flutter_gemma_litertlm
);

// 2. Install the model (host app responsibility).
await FlutterGemma.installModel(modelType: ModelType.gemmaIt)
    .fromAsset('assets/gemma-3-1b-it-int4.task')
    .install();

// 3. Create a Genkit instance with the plugin.
final ai = Genkit(plugins: [
  GenkitFlutterGemmaPlugin(
    models: [
      FlutterGemmaModelConfig(
        name: 'gemma-3-nano',
        modelType: ModelType.gemmaIt,
      ),
    ],
    embedders: [
      FlutterGemmaEmbedderConfig(name: 'embedding-gemma-300m'),
    ],
  ),
]);
```

--------------------------------

### Setup Configuration File

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Commands to initialize the configuration file and ignore it in version control.

```bash
cp config.json.example config.json
# Edit config.json and add your token from https://huggingface.co/settings/tokens
```

```gitignore
# Never commit tokens!
config.json
```

```bash
flutter run --dart-define-from-file=config.json
```

--------------------------------

### Integration Test for Full Model Installation

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Demonstrates testing the complete model installation process, from network download to verification of installation status.

```dart
test('Full installation flow', () async {
  FlutterGemma.initialize();

  final installation = await FlutterGemma.installModel()
    .fromNetwork('https://example.com/test.bin')
    .install();

  expect(installation.modelId, 'test.bin');
  expect(await FlutterGemma.isModelInstalled('test.bin'), isTrue);
});
```

--------------------------------

### Clone the repository

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/CONTRIBUTING.md

Initial commands to download the project and install dependencies.

```bash
git clone https://github.com/DenisovAV/flutter_gemma.git
cd flutter_gemma
flutter pub get
```

--------------------------------

### Install and use a .litertlm model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/litertlm.md

Install a model with the correct file type and manage inference sessions.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.gemma4,
  fileType: ModelFileType.litertlm,
).fromNetwork(
  'https://huggingface.co/litert-community/gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm',
  token: 'hf_...',
).install();

// Create the model once and keep it for the app's lifetime.
final model = await FlutterGemma.getActiveModel(
  maxTokens: 4096,
  preferredBackend: PreferredBackend.gpu,
);

final session = await model.createSession();
await session.addQueryChunk(const Message(text: 'Hello!', isUser: true));
await for (final chunk in session.getResponseAsync()) {
  print(chunk);
}
await session.close();
```

--------------------------------

### Initialize and use Genkit with Flutter Gemma

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_flutter_gemma/README.md

Complete setup including model installation, plugin configuration, and generating text responses.

```dart
import 'package:flutter_gemma/flutter_gemma.dart';
// Engines/backends are opt-in (see Setup) — register the ones you need.
import 'package:flutter_gemma_litertlm/flutter_gemma_litertlm.dart';
import 'package:flutter_gemma_mediapipe/flutter_gemma_mediapipe.dart';
import 'package:genkit/genkit.dart';
import 'package:genkit_flutter_gemma/genkit_flutter_gemma.dart';

// Initialize and install model (host app responsibility)
await FlutterGemma.initialize(
  inferenceEngines: const [LiteRtLmEngine(), MediaPipeEngine()],
  embeddingBackends: const [LiteRtEmbeddingBackend()],
);
await FlutterGemma.installModel(modelType: ModelType.gemmaIt)
    .fromAsset('assets/gemma-3-1b-it-int4.task')
    .install();

// Create Genkit with plugin
final ai = Genkit(plugins: [
  GenkitFlutterGemmaPlugin(
    models: [
      FlutterGemmaModelConfig(
        name: 'gemma-3-nano',
        modelType: ModelType.gemmaIt,
      ),
    ],
    embedders: [
      FlutterGemmaEmbedderConfig(name: 'embedding-gemma-300m'),
    ],
  ),
]);

// Generate
final response = await ai.generate(
  model: flutterGemma.model('gemma-3-nano'),
  prompt: 'Hello!',
);
print(response.text);
```

--------------------------------

### Install Model from File

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from an external file path, typically provided by the user.

```APIDOC
## Install Model from File

### Description
Installs a model from an external file path, typically provided by the user.

### Method
`FlutterGemma.installModel().fromFile(filePath).install()`

### Parameters
- **filePath** (string) - Required - The absolute path to the model file.
```

--------------------------------

### Install and use a .task model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/mediapipe.md

Download and interact with a model using the MediaPipe engine.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
).fromNetwork('https://.../gemma3-1b-it.task').install();

final model = await FlutterGemma.getActiveModel(maxTokens: 4096);
final session = await model.createSession();
await session.addQueryChunk(const Message(text: 'Hello!', isUser: true));
final response = await session.getResponse();
```

--------------------------------

### Get Dependencies

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_flutter_gemma/CLAUDE.md

Run this command to fetch all necessary project dependencies.

```bash
flutter pub get
```

--------------------------------

### Installation Rules for Application Bundle

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/example/linux/CMakeLists.txt

Defines installation rules for creating a relocatable application bundle. This includes cleaning the bundle directory, installing the executable, data files, libraries, and native assets.

```cmake
# === Installation ===
# By default, "installing" just makes a relocatable bundle in the build
# directory.
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

# Start with a clean build bundle directory every time.
install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)

# Copy the native assets provided by the build.dart from all packages.
set(NATIVE_ASSETS_DIR "${PROJECT_BUILD_DIR}native_assets/linux/")
install(DIRECTORY "${NATIVE_ASSETS_DIR}"
   DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
   COMPONENT Runtime)

# Fully re-copy the assets directory on each build to avoid having stale files
# from a previous install.
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)

# Install the AOT library on non-Debug builds only.
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Install Models from Different Sources

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Demonstrates how to install models using network URLs, local Flutter assets, native bundles, or external file paths.

```dart
// Network — .litertlm is the cross-platform default (Android/iOS/Desktop).
// For mobile-only or web-only apps you can substitute a .task URL of the
// same model — and drop the fileType, which defaults to ModelFileType.task.
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
)
  .fromNetwork('https://example.com/model.litertlm', token: 'optional')
  .install();

// Flutter assets
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
)
  .fromAsset('assets/models/model.litertlm')
  .install();

// Native bundle
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
)
  .fromBundled('model.litertlm')
  .install();

// External file
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
)
  .fromFile('/path/to/model.litertlm')
  .install();
```

--------------------------------

### Install Model from Bundled Resource

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from a resource bundled with the native application.

```APIDOC
## Install Model from Bundled Resource

### Description
Installs a model from a resource bundled with the native application.

### Method
`FlutterGemma.installModel().fromBundled(resourceName).install()`

### Parameters
- **resourceName** (string) - Required - The name of the bundled resource.
```

--------------------------------

### Install Models from Assets

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Compare legacy asset-based model installation with the modern builder-pattern approach, including LoRA support.

```dart
// From assets
await modelManager.installModelFromAssetWithProgress(
  'model.bin',
  loraPath: 'lora.bin',
).listen((progress) {
  print('$progress%');
});
```

```dart
// From assets
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromAsset('model.bin')
  .withProgress((progress) {
    print('$progress%');
  })
  .install();

// LoRA weights can be installed with the model
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromAsset('model.bin')
  .withLoraFromAsset('lora.bin')
  .install();
```

--------------------------------

### Install Model from Network (Legacy)

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Demonstrates the deprecated method for downloading a model using the legacy API. Use the modern API for new installations.

```dart
import 'package:flutter_gemma/core/legacy/legacy_model_manager.dart';

final spec = InferenceModelSpec(
  name: 'gemma-2b',
  files: [ModelFile(filename: 'model.bin', url: 'https://...')],
);

await LegacyModelManager.downloadModel(spec);  // DEPRECATED
```

--------------------------------

### Install Model from Asset

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from the Flutter application's assets.

```APIDOC
## Install Model from Asset

### Description
Installs a model from the Flutter application's assets.

### Method
`FlutterGemma.installModel().fromAsset(assetPath).install()`

### Parameters
- **assetPath** (string) - Required - The path to the model file within the Flutter assets.
```

--------------------------------

### Install Model from Asset with Progress

Source: https://github.com/denisovav/flutter_gemma/blob/main/docs/LEGACY_API.md

Installs a model from local assets and listens to the loading progress. The loraPath is optional. Handles completion and errors.

```dart
modelManager.installModelFromAssetWithProgress('model.bin', loraPath: 'lora_weights.bin').listen(
    (progress) {
      print('Loading progress: $progress%');
    },
    onDone: () {
      print('Model loading complete.');
    },
    onError: (error) {
      print('Error loading model: $error');
    },
  );
```

--------------------------------

### Install Embedding Model

Source: https://github.com/denisovav/flutter_gemma/blob/main/docs/LEGACY_API.md

Demonstrates how to install embedding models and tokenizers from both network URLs and local assets. Includes progress tracking for network downloads.

```APIDOC
## Install Embedding Model

### Description
Installs an embedding model and its corresponding tokenizer from network sources or local assets. Supports progress tracking for downloads.

### Method
```dart
FlutterGemma.installEmbedder()
  .modelFromNetwork(String url, {String token})
  .tokenizerFromNetwork(String url, {String token, String iosPath})
  .withModelProgress((progress) => print('Model: $progress%'))
  .withTokenizerProgress((progress) => print('Tokenizer: $progress%'))
  .install();

FlutterGemma.installEmbedder()
  .modelFromAsset(String path)
  .tokenizerFromAsset(String path)
  .install();
```

### Parameters
*   `modelFromNetwork(url, token)`: Downloads the model from the specified URL. `token` is required for gated models.
*   `tokenizerFromNetwork(url, token, iosPath)`: Downloads the tokenizer from the specified URL. `token` is required for gated models. `iosPath` is an optional URL for iOS-specific tokenizers.
*   `modelFromAsset(path)`: Loads the model from the specified asset path.
*   `tokenizerFromAsset(path)`: Loads the tokenizer from the specified asset path.
*   `withModelProgress(callback)`: Callback function to track model download progress.
*   `withTokenizerProgress(callback)`: Callback function to track tokenizer download progress.
*   `install()`: Initiates the installation process.
```

--------------------------------

### Install Model from External File

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from a file path provided by the user, typically obtained via a file picker.

```dart
// User-provided file via file picker
await FlutterGemma.installModel()
  .fromFile('/path/to/model.bin')
  .install();
```

--------------------------------

### Install a web ONNX model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/onnx.md

Install a model using a Hugging Face repository ID for web platforms.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.general,
  fileType: ModelFileType.onnx,
).fromNetwork('onnx-community/Qwen2.5-0.5B-Instruct').install();
```

--------------------------------

### Install Model from Network (Modern)

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Shows the recommended way to install a model from a network URL using the modern Flutter Gemma API. Includes progress tracking.

```dart
import 'package:flutter_gemma/core/api/flutter_gemma.dart';

await FlutterGemma.installModel()
  .fromNetwork('https://...')
  .withProgress((p) => print(p))
  .install();
```

--------------------------------

### Installation Prefix Configuration

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_flutter_gemma/example/windows/CMakeLists.txt

Configures the installation prefix to be next to the executable for in-place running, especially for Visual Studio builds.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")
```

--------------------------------

### Install Flutter Library

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_flutter_gemma/example/windows/CMakeLists.txt

Installs the main Flutter library file to the library directory within the bundle.

```cmake
install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Install Model from Bundled Native Resource

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Installs a model from a resource bundled with the native application code.

```dart
await FlutterGemma.installModel()
  .fromBundled('gemma.bin')
  .install();
```

--------------------------------

### Install a Gemma model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/getting-started.md

Downloads and installs a model from a network URL. Requires a Hugging Face token and supports progress tracking.

```dart
import 'package:flutter_gemma/flutter_gemma.dart';

// Install model. The URL below uses the .litertlm variant so the same code
// works on Desktop (Windows/macOS/Linux) and mobile/web. For web only, the
// `.task` / `-web.task` variants of the same model also work.
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
).fromNetwork(
  'https://huggingface.co/litert-community/Gemma3-1B-IT/resolve/main/Gemma3-1B-IT_multi-prefill-seq_q4_ekv4096.litertlm',
  token: 'your_hf_token',
).withProgress((progress) {
  print('Downloading: $progress%');
}).install();
```

--------------------------------

### Check Model Installation Status

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Compare legacy and modern methods for verifying if a model is installed.

```dart
final spec = MobileModelManager.createInferenceSpec(
  name: 'model.bin',
  modelUrl: url,
);

final isInstalled = await FlutterGemmaPlugin
  .instance.modelManager
  .isModelInstalled(spec);
```

```dart
final isInstalled = await FlutterGemma
  .isModelInstalled('model.bin');
```

--------------------------------

### Install Bundled Plugin Libraries

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_flutter_gemma/example/windows/CMakeLists.txt

Installs any bundled plugin libraries to the library directory within the bundle, if they exist.

```cmake
if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Install a Gemma Model

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Downloads and installs a model file from a network URL using the FlutterGemma API.

```dart
import 'package:flutter_gemma/flutter_gemma.dart';

// Install model. URL example uses the .litertlm variant so the same code
// works on Desktop (Windows/macOS/Linux) and mobile/web. For web only, the
// `.task`/`-web.task` variants of the same model also work.
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
).fromNetwork(
  'https://huggingface.co/litert-community/Gemma3-1B-IT/resolve/main/Gemma3-1B-IT_multi-prefill-seq_q4_ekv4096.litertlm',
  token: 'your_hf_token',
).withProgress((progress) {
  print('Downloading: $progress%');
}).install();
```

--------------------------------

### Install Required Libraries for Gemma Fine-Tuning

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/colabs/gemma_lora_1.ipynb

Installs a suite of Python libraries essential for fine-tuning Gemma, including transformers, mediapipe, bitsandbytes, peft, trl, datasets, fsspec, and gcsfs. Specific versions of fsspec and gcsfs are required for compatibility.

```bash
!pip install -q transformers mediapipe bitsandbytes peft trl datasets fsspec==2024.6.1 gcsfs==2024.9.0
```

--------------------------------

### Install Dependencies

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/colabs/functiongemma_finetuning.ipynb

Installs the necessary libraries for fine-tuning, including transformers, datasets, and trl. Note that PyTorch is assumed to be pre-installed in the Colab environment.

```python
# =============================================================================
# Install dependencies (use Colab's pre-installed torch)
# =============================================================================
# Don't reinstall torch - Colab has optimized version pre-installed

!pip install -q transformers==4.57.3 datasets accelerate evaluate trl==0.26.2 protobuf sentencepiece
!pip install -q huggingface_hub tensorboard

print("\nDependencies installed!")
```

--------------------------------

### FlutterGemma.installModel

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Installs a machine learning model by specifying the model type and source URL.

```APIDOC
## FlutterGemma.installModel

### Description
Initiates the installation process for a specific model type from a network source.

### Parameters
- **modelType** (ModelType) - Required - The type of model to install (e.g., ModelType.gemmaIt, ModelType.deepSeek, ModelType.general).

### Usage Example
```dart
await FlutterGemma.installModel(modelType: ModelType.gemmaIt)
  .fromNetwork(url).install();
```
```

--------------------------------

### Unchanged API Usage

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/MIGRATION.md

Examples of model installation, chat generation, and RAG operations that remain unchanged in version 1.0.

```dart
// install + run a model
await FlutterGemma.installModel(
        modelType: ModelType.gemma4, fileType: ModelFileType.litertlm)
    .fromNetwork(url, token: token).install();
final model = await FlutterGemma.getActiveModel(maxTokens: 2048);
final chat  = await model.createChat();
await chat.addQueryChunk(Message.text(text: 'Hello', isUser: true));
await for (final r in chat.generateChatResponseAsync()) { /* r is a ModelResponse */ }

// embeddings + RAG
await FlutterGemma.installEmbedder()
    .modelFromNetwork(modelUrl, token: token)
    .tokenizerFromNetwork(tokenizerUrl, token: token)
    .install();
await FlutterGemmaPlugin.instance.addDocument(/* ... */);
final hits = await FlutterGemmaPlugin.instance.searchSimilar(query: query, topK: 5);
```

--------------------------------

### Check availability and prepare model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/builtin-ai.md

Verify if the OS model is ready and trigger the download process if necessary.

```dart
final status = await BuiltInAi.availability();
// available · downloadable · downloading · unavailable* (device/OS/disabled/other)

await BuiltInAi.ensureReady(
  onProgress: (percent) => debugPrint('Preparing built-in AI: $percent%'),
);
// Throws BuiltInAiUnavailableException for any unavailable* status.
```

--------------------------------

### Copy Configuration Template

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/example/README.md

Copy the example configuration file to be edited. This is the first step in configuring HuggingFace tokens.

```bash
cp config.json.example config.json
```

--------------------------------

### Authenticate Per-Download

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Pass an authentication token directly during a specific model installation request.

```dart
// Pass token directly for specific downloads
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
  fileType: ModelFileType.litertlm,
)
  .fromNetwork(
    'https://huggingface.co/google/gemma-3n-E2B-it-litert-lm/resolve/main/gemma-3n-E2B-it-int4.litertlm',
    token: 'hf_your_token_here',  // ⚠️ Not recommended - use config.json
  )
  .install();
```

--------------------------------

### Manage Installed Models

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Provides functions to check if a model is installed, list all installed models, and uninstall a specific model.

```dart
// Check if installed
final isInstalled = await FlutterGemma.isModelInstalled('gemma-2b-it.bin');

// List all installed models
final models = await FlutterGemma.listInstalledModels();
print('Installed: $models');

// Uninstall model
await FlutterGemma.uninstallModel('gemma-2b-it.bin');
```

--------------------------------

### Implement On-device RAG with Flutter Gemma

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Demonstrates installing an embedding model, initializing a vector store, adding documents, and performing semantic searches.

```dart
import 'package:flutter_gemma/flutter_gemma.dart';

// 1. Install an embedding model (any of Gecko / EmbeddingGemma)
await FlutterGemma.installEmbedder()
    .modelFromNetwork(
      'https://huggingface.co/litert-community/embeddinggemma-300m/resolve/main/embeddinggemma-300M_seq256_mixed-precision.tflite',
      token: 'hf_...',
    )
    .tokenizerFromNetwork(
      'https://huggingface.co/litert-community/embeddinggemma-300m/resolve/main/sentencepiece.model',
      token: 'hf_...',
    )
    .install();

// 2. Initialize the vector store (one shard per database path)
await FlutterGemmaPlugin.instance.initializeVectorStore('rag_store');

// 3. Add documents — let the plugin compute embeddings for you
for (final doc in docs) {
  await FlutterGemmaPlugin.instance.addDocument(
    id: doc.id,
    content: doc.content,
    metadata: '{"category":"science","lang":"en"}',
  );
}

// 3b. Or batch-embed yourself and feed pre-computed vectors via
//     addDocumentWithEmbedding(...) for higher throughput.
final embedder = FlutterGemmaPlugin.instance.initializedEmbeddingModel!;
final embeddings = await embedder.generateEmbeddings(
  docs.map((d) => d.content).toList(),
  taskType: TaskType.retrievalDocument,
);
for (var i = 0; i < docs.length; i++) {
  await FlutterGemmaPlugin.instance.addDocumentWithEmbedding(
    id: docs[i].id,
    content: docs[i].content,
    embedding: embeddings[i],
    metadata: '{"category":"science","lang":"en"}',
  );
}

// 4. Semantic search, with optional payload-aware Filter (all backends + platforms)
final results = await FlutterGemmaPlugin.instance.searchSimilar(
  query: 'quantum entanglement',
  topK: 10,
  threshold: 0.0,
  filter: Filter(
    must: [FieldEquals(key: 'category', value: 'science')],
    mustNot: [FieldEquals(key: 'lang', value: 'fr')],
  ),
);
```

--------------------------------

### Example Usage of Hybrid Model (Commented Out)

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/genkit_hybrid/docs/plans/2026-06-14-genkit-hybrid.md

A minimal illustration of how to build a hybrid model in `example/genkit_hybrid_example.dart`. The actual model instantiation is commented out, requiring the host app to provide the `onDeviceModel` and `cloudModel`.

```dart
import 'package:genkit_hybrid/genkit_hybrid.dart';

/// Minimal illustration. `onDeviceModel` and `cloudModel` are ordinary Genkit
/// Models provided by the host app (e.g. from genkit_flutter_gemma and googleAI).
void buildHybrid(/* Model onDeviceModel, Model cloudModel */) {
  // Prefer on-device, fall back to cloud on failure/offline:
  // final smart = hybridModelOnDeviceCloud(
  //   onDevice: onDeviceModel,
  //   cloud: cloudModel,
  //   strategy: FallbackStrategy([kOnDevice, kCloud]),
  // );
}

```

--------------------------------

### Create Message Types in Flutter Gemma

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/README.md

Examples of constructing various message objects including text, multimodal, tool responses, and system information.

```dart
// Text only
final textMessage = Message.text(text: "Hello!", isUser: true);

// Text + Image
final multimodalMessage = Message.withImages(
  text: "What's in this image?",
  imageBytes: [imageBytes],
  isUser: true,
);

// Image only
final imageMessage = Message.imagesOnly(imageBytes: [imageBytes], isUser: true);

// Tool response (for function calling)
final toolMessage = Message.toolResponse(
  toolName: 'change_background_color',
  response: {'status': 'success', 'color': 'blue'},
);

// System information message
final systemMessage = Message.systemInfo(text: "Function completed successfully");

// Thinking content (for DeepSeek models)
final thinkingMessage = Message.thinking(text: "Let me analyze this problem...");

// Check if message contains image
if (message.hasImage) {
  print('This message contains an image');
}

// Create a copy of message
final copiedMessage = message.copyWith(text: "Updated text");
```

--------------------------------

### Install MediaPipe and Dependencies

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/colabs/functiongemma_tflite_to_task.ipynb

Installs MediaPipe version 0.10.20 and a compatible version of numpy (<2.1). This step is crucial for avoiding binary incompatibilities. A runtime restart is required after installation.

```python
# =============================================================================
# Step 1: Install mediapipe (clean environment, no ai-edge-torch)
# =============================================================================
!pip install mediapipe==0.10.20 -q

# CRITICAL: Install numpy<2.1 AFTER mediapipe (fixes binary incompatibility)
!pip install "numpy<2.1" --force-reinstall -q

print("Installed:")
!pip show mediapipe | grep Version
!pip show numpy | grep Version

print("\n⚠️  RESTART RUNTIME after this step! (Runtime → Restart session)")
print("Then run cells starting from Step 2.")
```

--------------------------------

### Initialize and Use Embedding Backend

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma_embeddings/example/README.md

Demonstrates initializing the LiteRT embedding backend, installing the model and tokenizer, and generating an embedding vector.

```dart
import 'package:flutter/widgets.dart';
import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:flutter_gemma_litertlm/flutter_gemma_litertlm.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Opt into the LiteRT embedding backend (flutter_gemma_litertlm).
  await FlutterGemma.initialize(
    embeddingBackends: [LiteRtEmbeddingBackend()],
  );

  // Install an embedding model (downloads + sets it active). The model and its
  // tokenizer are separate downloads.
  await FlutterGemma.installEmbedder()
      .modelFromNetwork('https://example.com/embeddinggemma.tflite', token: 'hf_...')
      .tokenizerFromNetwork('https://example.com/sentencepiece.model', token: 'hf_...')
      .install();

  // Create the embedding model and embed text.
  final embedder = await FlutterGemma.getActiveEmbedder();
  final vector = await embedder.generateEmbedding('Gemma runs on-device.');
  print('embedding dim: ${vector.length}');

  await embedder.close();
}
```

--------------------------------

### Install Dependencies for .litertlm Conversion

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/colabs/functiongemma_to_litertlm.ipynb

Installs ai-edge-torch-nightly, ai-edge-litert-nightly, transformers, and a compatible numpy version. This step is critical and requires a runtime restart. Ensure numpy<2.1 is installed after ai-edge-torch.

```python
# =============================================================================
# Step 1: Install ai-edge-torch-nightly
# =============================================================================
!pip uninstall -y tensorflow 2>/dev/null || true
!pip cache purge

# Install ai-edge-torch packages
!pip install ai-edge-torch-nightly --force-reinstall --no-cache-dir -q
!pip install ai-edge-litert-nightly --no-cache-dir -q

# CRITICAL: Install numpy<2.1 AFTER ai-edge-torch (it may override)
!pip install "numpy<2.1" --force-reinstall -q

# Install transformers with pinned version
!pip install transformers==4.57.3 huggingface_hub sentencepiece -q

# Restore Colab's native Pillow
!pip install Pillow --force-reinstall -q

print("\nInstalled:")
!pip show ai-edge-torch-nightly | grep Version
!pip show transformers | grep Version
!pip show numpy | grep Version
!pip show Pillow | grep Version

print("\n⚠️  RESTART RUNTIME after this step! (Runtime → Restart session)")
```

--------------------------------

### List Installed Models

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Retrieves a list of all models currently installed on the device.

```APIDOC
## List Installed Models

### Description
Retrieves a list of all models currently installed on the device.

### Method
`FlutterGemma.listInstalledModels()`

### Returns
- **List<String>** - A list of installed model names.
```

--------------------------------

### Configure Podfile for macOS Build

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/desktop.md

Add this post_install hook to your Podfile to bundle required dylibs as framework bundles and patch LiteRtLm references.

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_macos_build_settings(target)
  end

  # flutter_gemma: bundle Apple accelerator dylibs as .framework bundles into
  # Contents/Frameworks/ and re-point LiteRtLm.dylib's LC_LOAD_DYLIB reference.
  installer.aggregate_targets.each do |aggregate_target|
    aggregate_target.user_targets.each do |user_target|
      phase_name = '[flutter_gemma] Setup LiteRT-LM macOS'

      # Only the app target embeds the Frameworks/ this phase patches.
      unless user_target.name == 'Runner'
        user_target.build_phases
          .select { |p| p.respond_to?(:name) && p.name == phase_name }
          .each { |p| user_target.build_phases.delete(p) }
        next
      end

      existing = user_target.shell_script_build_phases.find { |p| p.name == phase_name }
      phase = existing || user_target.new_shell_script_build_phase(phase_name)
      phase.output_paths = ['$(DERIVED_FILE_DIR)/flutter_gemma_litertlm_macos.stamp']
      phase.shell_script = <<~SHELL
        set -e
        FRAMEWORKS="${BUILT_PRODUCTS_DIR}/${PRODUCT_NAME}.app/Contents/Frameworks"
        if [ ! -d "${FRAMEWORKS}" ]; then
          exit 0
        fi
        for base in LiteRtMetalAccelerator LiteRtTopKMetalSampler GemmaModelConstraintProvider; do
          rm -f "${FRAMEWORKS}/lib${base}.dylib"
        done
        # The Native Assets cache is where hook/build.dart puts these on
        # `flutter pub get`, and it is the only source an app ever sees —
        # the in-repo prebuilt/ ships in no package and is gitignored.
        PLUGIN_PREBUILT="${HOME}/Library/Caches/flutter_gemma/native/macos_arm64"
        if [ ! -f "${PLUGIN_PREBUILT}/libGemmaModelConstraintProvider.dylib" ]; then
          echo "[flutter_gemma] ERROR: macOS companion dylibs not found at ${PLUGIN_PREBUILT}."
          echo "  Run 'flutter clean && flutter pub get' to repopulate the Native Assets cache."
          exit 1
        fi
        for base in GemmaModelConstraintProvider LiteRtMetalAccelerator LiteRtTopKMetalSampler; do
          src="${PLUGIN_PREBUILT}/lib${base}.dylib"
          if [ ! -f "${src}" ]; then
            echo "[flutter_gemma] WARNING: ${src} not found — runtime dlopen will fail"
            continue
          fi
          fw_dir="${FRAMEWORKS}/${base}.framework"
          mkdir -p "${fw_dir}/Versions/A/Resources"
          cp "${src}" "${fw_dir}/Versions/A/${base}"
          install_name_tool -id "@rpath/${base}.framework/Versions/A/${base}" \
            "${fw_dir}/Versions/A/${base}" 2>/dev/null || true
          (cd "${fw_dir}" && ln -sfh A Versions/Current && ln -sfh "Versions/Current/${base}" "${base}" && ln -sfh "Versions/Current/Resources" Resources)
          cat > "${fw_dir}/Versions/A/Resources/Info.plist" <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleExecutable</key><string>${base}</string>
  <key>CFBundleIdentifier</key><string>dev.flutterberlin.flutter_gemma.${base}</string>
  <key>CFBundleVersion</key><string>1</string>
  <key>CFBundleShortVersionString</key><string>1.0</string>
  <key>CFBundlePackageType</key><string>FMWK</string>
</dict>
</plist>
EOF
          # Re-sign the framework binary: install_name_tool invalidated its
          # code signature, and unlike LiteRtLm these companion frameworks are
          # not re-signed by Xcode — an unsigned/modified page trips CODESIGNING
          # "Invalid Page" at dlopen. Ad-hoc sign like LiteRtLm below.
          codesign --force --sign - "${fw_dir}/Versions/A/${base}" 2>/dev/null || true
        done
        LITERTLM="${FRAMEWORKS}/LiteRtLm.framework/Versions/A/LiteRtLm"
        if [ -f "${LITERTLM}" ]; then
          install_name_tool -change \
            @rpath/libGemmaModelConstraintProvider.dylib \
            @rpath/GemmaModelConstraintProvider.framework/Versions/A/GemmaModelConstraintProvider \
            "${LITERTLM}" 2>/dev/null || true
          codesign --force --sign - "${LITERTLM}" 2>/dev/null || true
        fi
        mkdir -p "$(dirname "${SCRIPT_OUTPUT_FILE_0}")"
        touch "${SCRIPT_OUTPUT_FILE_0}"
      SHELL
    end
  end
end
```

--------------------------------

### Initialize SFTTrainer and Start Training

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/colabs/functiongemma_finetuning.ipynb

Configures the SFTTrainer to use pre-formatted text data and executes the training process.

```python
# =============================================================================
# Create SFTTrainer and start training
# =============================================================================
# dataset_text_field="text" is configured in SFTConfig above.
# This tells SFTTrainer to use our pre-formatted text directly,
# without applying HuggingFace's chat template (which uses wrong format).

trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset['train'],
    eval_dataset=dataset['test'],
    processing_class=tokenizer,  # TRL 0.26.2: use processing_class, not tokenizer
)

print("Starting training...")
print(f"   Train examples: {len(dataset['train'])}")
print(f"   Eval examples: {len(dataset['test'])}")
print(f"   Format: Google FunctionGemma (manual)")
print(f"   Estimated time: ~5 minutes on A100")
print("-" * 50)

# Train!
train_result = trainer.train()

print("\n" + "=" * 50)
print("Training complete!")
print(f"   Final loss: {train_result.training_loss:.4f}")
```

--------------------------------

### Check Model Installation

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/lib/core/README.md

Checks if a specific model is currently installed on the device.

```APIDOC
## Check Model Installation

### Description
Checks if a specific model is currently installed on the device.

### Method
`FlutterGemma.isModelInstalled(modelName)`

### Parameters
- **modelName** (string) - Required - The name or identifier of the model to check.
```

--------------------------------

### Initialize QdrantVectorStore with error handling

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma_rag_qdrant/README.md

Demonstrates how to initialize the vector store and handle legacy store exceptions during the upgrade process.

```dart
import 'package:flutter_gemma_rag_qdrant/flutter_gemma_rag_qdrant.dart';

final store = QdrantVectorStore();
try {
  await store.initialize(path);
} on QdrantLegacyStoreException catch (e) {
  // e.message names exactly what to remove. Do it with the file APIs you
  // already use for `path`, then initialize() again and re-index.
  rethrow;
}
```

--------------------------------

### Install an embedding model

Source: https://github.com/denisovav/flutter_gemma/blob/main/website/content/docs/embeddings-and-rag.md

Downloads and installs an embedding model and its tokenizer from a network source.

```dart
await FlutterGemma.installEmbedder()
    .modelFromNetwork(
      'https://huggingface.co/litert-community/embeddinggemma-300m/resolve/main/embeddinggemma-300M_seq256_mixed-precision.tflite',
      token: 'hf_...',
    )
    .tokenizerFromNetwork(
      'https://huggingface.co/litert-community/embeddinggemma-300m/resolve/main/sentencepiece.model',
      token: 'hf_...',
    )
    .install();
```

--------------------------------

### Initialize Web Dependencies

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma/example/web/index.html

Configures global variables and imports necessary libraries for LLM inference in the browser.

```javascript
// Use the {{flutter_service_worker_version}} template token
const serviceWorkerVersion = "{{flutter_service_worker_version}}";

import { FilesetResolver, LlmInference } from 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-genai@0.10.27';
window.FilesetResolver = FilesetResolver;
window.LlmInference = LlmInference;

window.litertLmReady = (async () => {
  const m = await import('https://cdn.jsdelivr.net/npm/@litert-lm/core@0.14.0/+esm');
  window.Engine = m.Engine;
  return m.Engine;
})();

window.ortReady = (async () => {
  const m = await import('https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0/dist/ort.bundle.min.mjs');
  m.env.wasm.wasmPaths = 'https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0/dist/';
  window.ort = m;
  return m;
})();

window.transformersReady = (async () => {
  const m = await import('https://cdn.jsdelivr.net/npm/@huggingface/transformers@4.2.0');
  window.transformers = m;
  return m;
})();
```

--------------------------------

### Prepare Built-in AI

Source: https://github.com/denisovav/flutter_gemma/blob/main/packages/flutter_gemma_builtin_ai/README.md

Ensure the OS feature is ready and monitor download progress for on-device models.

```dart
await BuiltInAi.ensureReady(
  onProgress: (percent) => print('Preparing built-in AI: $percent%'),
);
```