### Install Gemma Model with LoRA and Progress Callback

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_inference_installation_builder/InferenceInstallationBuilder-class.html

Example of installing a Gemma model from a network URL, including optional LoRA weights and a progress callback. Ensure the network URL is accessible and the token is valid.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
)
  .fromNetwork('https://example.com/model.task', token: 'hf_...')
  .withProgress((progress) => print('$progress%'))
  .install();

```

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

### Install Model with Progress Tracking

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_asset_source_handler/AssetSourceHandler/installWithProgress.html

Use this snippet to install a model and monitor its installation progress. It handles potential cancellation via a CancelToken. Note that progress simulation varies by source type.

```dart
final cancelToken = CancelToken();

try {
  await for (final progress in handler.installWithProgress(
    source,
    cancelToken: cancelToken,
  )) {
    print('Progress: $progress%');
  }
} catch (e) {
  if (CancelToken.isCancel(e)) {
    print('Installation cancelled');
  }
}
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_network_source_handler_stub/WebNetworkSourceHandler/installWithProgress.html

Installs a model from a given source and streams the installation progress as percentages (0-100). Supports cancellation via a CancelToken.

```APIDOC
## installWithProgress

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
`Stream<int>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `source` (ModelSource) - Required - The model source to install from.
* `cancelToken` (CancelToken?) - Optional - Token for cancelling the installation.

### Notes
Some sources may not support true progress:
* AssetSource: simulates progress (copy is instant)
* BundledSource: returns 100 immediately (no download)
* FileSource: returns 100 immediately (just registration)

### Request Example
```dart
final cancelToken = CancelToken();

try {
  await for (final progress in handler.installWithProgress(
    source,
    cancelToken: cancelToken,
  )) {
    print('Progress: $progress%');
  }
} catch (e) {
  if (CancelToken.isCancel(e)) {
    print('Installation cancelled');
  }
}
```

### Response
#### Success Response (Stream<int>)
* `progress` (int) - The current installation progress percentage (0-100).

#### Response Example
```
Progress: 25%
Progress: 50%
Progress: 75%
Progress: 100%
```

### Throws
* `DownloadCancelledException` if cancelled via cancelToken.
```

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

### Installation Execution

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_embedding_installation_builder/EmbeddingInstallationBuilder-class.html

The method to execute the model and tokenizer installation.

```APIDOC
## `install()`

### Description
Execute the installation process for the configured model and tokenizer. If successful, the installed model is automatically set as the active embedding model.

### Method
POST (Implicitly called by the builder)

### Endpoint
(Internal to the builder)

### Return Value
- `Future<EmbeddingInstallation>`: A future that resolves to an `EmbeddingInstallation` object upon successful installation.
```

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

### Install and Get Active Model

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_flutter_gemma/FlutterGemma/getActiveModel.html

Installs a model from a network URL and then retrieves it as an active InferenceModel. Demonstrates creating models with different context lengths and backend preferences, including audio support.

```dart
// Install model first
await FlutterGemma.installModel(
  modelType: ModelType.gemmaIt,
).fromNetwork('https://example.com/model.task').install();

// Create with short context
final shortModel = await FlutterGemma.getActiveModel(
  maxTokens: 512,
);

// Create with long context and GPU
final longModel = await FlutterGemma.getActiveModel(
  maxTokens: 4096,
  preferredBackend: PreferredBackend.gpu,
);

// Create with audio support (Gemma 3n E4B only)
final audioModel = await FlutterGemma.getActiveModel(
  supportAudio: true,
);

```

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

### installEmbedder static method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_flutter_gemma/FlutterGemma/installEmbedder.html

Starts the process of building an embedding model installation. Returns a type-safe builder for installing embedding models, which requires both a model and a tokenizer. The model will be automatically set as the active embedding model after installation.

```APIDOC
## installEmbedder static method

### Description
Starts building an embedding model installation. Returns a type-safe builder for installing embedding models (requires model + tokenizer). The model will be automatically set as the active embedding model after installation.

### Method
static

### Endpoint
N/A (static method)

### Parameters
None

### Request Example
```dart
await FlutterGemma.installEmbedder()
  .modelFromNetwork('https://example.com/model.tflite', token: 'hf_...')
  .tokenizerFromNetwork('https://example.com/tokenizer.model', token: 'hf_...')
  .withModelProgress((p) => print('Model: $p%'))
  .withTokenizerProgress((p) => print('Tokenizer: $p%'))
  .install();
```

### Response
#### Success Response (EmbeddingInstallationBuilder)
Returns an `EmbeddingInstallationBuilder` instance to configure the installation.

#### Response Example
```dart
// Returns an instance of EmbeddingInstallationBuilder
```
```

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

### Install Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_network_source_handler_stub/WebNetworkSourceHandler/install.html

The install method is used to install a model from a specified source. It supports different source types like NetworkSource, AssetSource, BundledSource, and FileSource. The installation process can be cancelled using a CancelToken.

```APIDOC
## Future<void> install(ModelSource source, {CancelToken? cancelToken})

### Description
Installs the model from the given source. This method performs the actual installation:
  * NetworkSource: downloads from URL
  * AssetSource: copies from Flutter assets
  * BundledSource: accesses native resources
  * FileSource: registers external file path

### Method
Future<void>

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None

### Throws
  * UnsupportedError if this handler doesn't support the source type
  * ArgumentError if the source is invalid
  * DownloadCancelledException if cancelled via cancelToken
  * Platform-specific exceptions for download/file errors
```

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

### Install DeepSeek with LoRA Weights

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_flutter_gemma/FlutterGemma/installModel.html

Install a DeepSeek model along with LoRA weights from network sources. This example demonstrates how to specify both the model and LoRA file URLs.

```dart
// Install DeepSeek with LoRA weights
await FlutterGemma.installModel(
  modelType: ModelType.deepSeek,
)
  .fromNetwork('https://example.com/model.task')
  .withLoraFromNetwork('https://example.com/lora.bin')
  .install();
```

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

### Implement Install Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_asset_source_handler_stub/WebAssetSourceHandler/install.html

This implementation of the install method throws an UnsupportedError, indicating it's only available on the web platform. Use this when the installation logic is not applicable to the current environment.

```dart
@override
Future<void> install(
  ModelSource source, {
  CancelToken? cancelToken,
}) async {
  throw UnsupportedError(
    'WebAssetSourceHandler is only available on web platform',
  );
}
```

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

### Control Model Behavior with System Instructions

Source: https://pub.dev/documentation/flutter_gemma/latest/index.html

Initialize a chat session with a system instruction to guide the model's behavior. This example sets the model to be a concise assistant that responds in bullet points.

```dart
final chat = await model.createChat(
  systemInstruction: 'You are a concise assistant. Always respond in bullet points.',
);

```

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

### Install Gemma Model from Network

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_flutter_gemma/FlutterGemma-class.html

Install a Gemma model from a network URL. Includes progress tracking during the download and installation process. Requires specifying the model type and the network source.

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

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

### Install Model

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_bundled_source_handler/BundledSourceHandler/install.html

Installs a model from a specified source. Supports NetworkSource, AssetSource, BundledSource, and FileSource.

```APIDOC
## POST /models/install

### Description
Installs the model from the given source. This method performs the actual installation:
  * NetworkSource: downloads from URL
  * AssetSource: copies from Flutter assets
  * BundledSource: accesses native resources
  * FileSource: registers external file path

### Method
POST

### Endpoint
/models/install

### Parameters
#### Query Parameters
- **source** (ModelSource) - Required - The model source to install from
- **cancelToken** (CancelToken) - Optional - Optional token for cancelling the installation

### Request Example
```json
{
  "source": {
    "type": "NetworkSource",
    "url": "http://example.com/model.zip"
  }
}
```

### Response
#### Success Response (200)
- **void** - Installation successful

#### Response Example
```json
{}
```

### Errors
- **UnsupportedError**: If this handler doesn't support the source type.
- **ArgumentError**: If the source is invalid.
- **DownloadCancelledException**: If cancelled via cancelToken.
- **Platform-specific exceptions**: For download/file errors.
```

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

### Add Progress Callback to Installation

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_inference_installation_builder/InferenceInstallationBuilder/withProgress.html

Use this method to register a callback that will be invoked periodically with the installation progress percentage (0-100).

```dart
InferenceInstallationBuilder withProgress(
    void Function(int progress) onProgress) {
  _onProgress = onProgress;
  return this;
}
```

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

### Install and Initialize FunctionGemma Model

Source: https://pub.dev/documentation/flutter_gemma/latest/index.html

Installs the FunctionGemma model from a network URL and initializes it for use. Specify maxTokens and preferredBackend for optimal performance.

```dart
await FlutterGemma.installModel(
  modelType: ModelType.functionGemma,
).fromNetwork(
  'https://huggingface.co/sasha-denisov/function-gemma-270M-it/resolve/main/functiongemma-270M-it.task',
).install();

final model = await FlutterGemma.getActiveModel(
  maxTokens: 1024,
  preferredBackend: PreferredBackend.gpu,
);

final chat = await model.createChat(
  tools: myTools,
  supportsFunctionCalls: true,
);
```

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

### Install Model from Source

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_network_source_handler/NetworkSourceHandler/install.html

Installs a model from a given source. Supports NetworkSource, AssetSource, BundledSource, and FileSource. Can be cancelled via CancelToken.

```dart
@override
Future<void> install(
  ModelSource source, {
  CancelToken? cancelToken,
})
```

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

### Implement Install Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_bundled_source_handler_stub/WebBundledSourceHandler/install.html

This implementation of the install method throws an UnsupportedError, indicating it's only available on the web platform.

```dart
@override
Future<void> install(ModelSource source, {CancelToken? cancelToken}) {
  throw UnsupportedError('WebBundledSourceHandler is only available on web platform');
}
```

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

### Install DeepSeek Models with Flutter

Source: https://pub.dev/documentation/flutter_gemma/latest/index.html

Install DeepSeek models by using ModelType.deepSeek. This example assumes a valid network URL is provided.

```dart
await FlutterGemma.installModel(modelType: ModelType.deepSeek)
  .fromNetwork(url).install();
```

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

### Model Installation

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_network_source_handler/WebNetworkSourceHandler/install.html

Installs a model from a specified source. Supports network downloads, asset copying, native resources, and external file paths.

```APIDOC
## POST /models/install

### Description
Installs the model from the given source. This method handles downloading from a URL, copying from Flutter assets, accessing native resources, or registering an external file path.

### Method
POST

### Endpoint
/models/install

### Parameters
#### Request Body
- **source** (ModelSource) - Required - The model source to install from. Can be NetworkSource, AssetSource, BundledSource, or FileSource.
- **cancelToken** (CancelToken) - Optional - A token to cancel the installation process.

### Response
#### Success Response (200)
- **void** - Indicates successful installation.

#### Error Response
- **UnsupportedError**: If the handler does not support the provided source type.
- **ArgumentError**: If the provided source is invalid.
- **DownloadCancelledException**: If the installation was cancelled via `cancelToken`.
- **Platform-specific exceptions**: For download or file-related errors.
```

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

### WebAssetSourceHandler.installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_asset_source_handler/WebAssetSourceHandler-class.html

Installs the model with progress tracking.

```APIDOC
## POST /installWithProgress

### Description
Installs the model with progress tracking.

### Method
POST

### Endpoint
/installWithProgress

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source** (ModelSource) - Required - The model source to install.
- **cancelToken** (CancelToken) - Optional - A token to cancel the installation.

### Request Example
```json
{
  "source": { ... },
  "cancelToken": null
}
```

### Response
#### Success Response (200)
- **Stream<int>** - A stream of integers representing the installation progress.

#### Response Example
```json
{
  "progress": [0, 25, 50, 75, 100]
}
```
```

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

### Get PrefsKey for Installation Status

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/InferenceModelFile/prefsKey.html

Retrieves the SharedPreferences key used for storing the installation status of a file. This key is defined in PreferencesKeys.

```dart
@override
String get prefsKey => PreferencesKeys.installedModelFileName;
```

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

### Get Installed Model Count

Source: https://pub.dev/documentation/flutter_gemma/latest/core_infrastructure_in_memory_model_repository/InMemoryModelRepository/count.html

Use this getter to retrieve the current number of installed models. It is useful for debugging or telemetry purposes.

```dart
int get count => _models.length;
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_file_source_handler/FileSourceHandler/installWithProgress.html

Installs a model and streams progress updates. Supports cancellation via `CancelToken`.

```APIDOC
## POST /models/install

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/models/install

### Parameters
#### Request Body
- **source** (ModelSource) - Required - The model source to install from.
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation.

### Request Example
```json
{
  "source": {
    "type": "AssetSource",
    "path": "path/to/model"
  },
  "cancelToken": null 
}
```

### Response
#### Success Response (200)
- **progress** (Stream<int>) - A stream of integers representing installation progress (0-100).

#### Response Example
```json
{
  "progress": [0, 25, 50, 75, 100]
}
```

### Notes
- Some sources may not support true progress:
  - AssetSource: simulates progress (copy is instant)
  - BundledSource: returns 100 immediately (no download)
  - FileSource: returns 100 immediately (just registration)

### Throws
- DownloadCancelledException if cancelled via cancelToken.
```

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

### Get Installed Models by Type

Source: https://pub.dev/documentation/flutter_gemma/latest/web_flutter_gemma_web/WebModelManager/getInstalledModels.html

Retrieves a list of installed model filenames, filtering by inference or embedding types. Ensure the ServiceRegistry and ModelRepository are initialized before calling.

```dart
@override
Future<List<String>> getInstalledModels(ModelManagementType type) async {
  await _ensureInitialized();

  // Phase 5: Delegate to Modern API
  final registry = ServiceRegistry.instance;
  final repository = registry.modelRepository;

  // Get all installed models from repository
  final allInstalled = await repository.listInstalled();

  // Filter by type
  final filtered = allInstalled.where((m) {
    if (type == ModelManagementType.inference) {
      return m.type == repo.ModelType.inference;
    } else {
      return m.type == repo.ModelType.embedding;
    }
  }).toList();

  // Return filenames
  return filtered.map((m) => m.id).toList();
}
```

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

### Get Installed Models Abstract Method

Source: https://pub.dev/documentation/flutter_gemma/latest/model_file_manager_interface/ModelFileManager/getInstalledModels.html

This abstract method is used to retrieve all installed models for a specific management type. Ensure the ModelManagementType is correctly specified.

```dart
Future<List<String>> getInstalledModels(ModelManagementType type);
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_asset_source_handler/AssetSourceHandler/installWithProgress.html

Installs a model and streams progress updates. Supports cancellation via a `CancelToken`.

```APIDOC
## POST /models/install

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/models/install

### Parameters
#### Query Parameters
- **source** (ModelSource) - Required - The model source to install from.
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation.

### Request Example
```json
{
  "source": {
    "type": "ModelSource",
    "path": "path/to/model"
  },
  "cancelToken": null 
}
```

### Response
#### Success Response (200)
- **progress** (Stream<int>) - A stream of integers representing the installation progress percentage (0-100).

#### Response Example
```
Progress: 50%
Progress: 75%
Progress: 100%
```

### Notes
- Some sources may not support true progress:
  - AssetSource: simulates progress (copy is instant)
  - BundledSource: returns 100 immediately (no download)
  - FileSource: returns 100 immediately (just registration)

### Throws
- DownloadCancelledException if cancelled via cancelToken.
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_bundled_source_handler/BundledSourceHandler/installWithProgress.html

Installs a model and returns a stream of progress percentages.

```APIDOC
## POST /websites/pub_dev_flutter_gemma/installWithProgress

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/websites/pub_dev_flutter_gemma/installWithProgress

### Parameters
#### Query Parameters
- **source** (ModelSource) - Required - The model source to install from
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation

### Request Example
```json
{
  "source": "{ModelSource object}",
  "cancelToken": "{CancelToken object}"
}
```

### Response
#### Success Response (200)
- **progress** (int) - The progress percentage (0-100)

#### Response Example
```json
{
  "progress": 50
}
```

### Throws
- DownloadCancelledException if cancelled via cancelToken
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_asset_source_handler/WebAssetSourceHandler/installWithProgress.html

Installs a Gemma model with progress tracking. Returns a stream of integers representing the progress percentage (0-100).

```APIDOC
## POST /installWithProgress

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/installWithProgress

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **source** (ModelSource) - Required - The model source to install from.
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation.

### Request Example
```json
{
  "source": {
    "type": "AssetSource",
    "path": "assets/gemma_model.bin"
  },
  "cancelToken": null 
}
```

### Response
#### Success Response (200)
- **Stream<int>** - A stream of integers representing the installation progress (0-100).

#### Response Example
```
0
25
50
75
100
```

### Notes
- Some sources may not support true progress:
  - AssetSource: simulates progress (copy is instant)
  - BundledSource: returns 100 immediately (no download)
  - FileSource: returns 100 immediately (just registration)

### Throws
- DownloadCancelledException if cancelled via cancelToken.
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_network_source_handler/NetworkSourceHandler/installWithProgress.html

Installs a model from a given source and streams progress updates.

```APIDOC
## POST /models/install

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/models/install

### Parameters
#### Request Body
- **source** (ModelSource) - Required - The model source to install from.
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation.

### Request Example
```json
{
  "source": {
    "type": "NetworkSource",
    "url": "http://example.com/model.gguf"
  },
  "cancelToken": null
}
```

### Response
#### Success Response (200)
- **progress** (int) - The current installation progress percentage (0-100).

#### Response Example
```json
{
  "progress": 50
}
```

### Notes
Some sources may not support true progress:
  * AssetSource: simulates progress (copy is instant)
  * BundledSource: returns 100 immediately (no download)
  * FileSource: returns 100 immediately (just registration)

### Throws
  * DownloadCancelledException if cancelled via cancelToken
```

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

### Get Installed Models by Type

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/MobileModelManager/getInstalledModels.html

Retrieves a list of installed model IDs for either inference or embedding types. Handles potential errors during the process by returning an empty list.

```dart
@override
Future<List<String>> getInstalledModels(ModelManagementType type) async {
  await _ensureInitialized();

  try {
    final registry = ServiceRegistry.instance;
    final repository = registry.modelRepository;

    // Convert ModelManagementType to repo.ModelType
    final modelType = type == ModelManagementType.inference
        ? repo.ModelType.inference
        : repo.ModelType.embedding;

    // Get all installed models and filter by type
    final allModels = await repository.listInstalled();
    final files =
        allModels.where((info) => info.type == modelType).map((info) => info.id).toList();

    debugPrint('UnifiedModelManager: Found ${files.length} installed files for type $type');
    return files;
  } catch (e) {
    debugPrint('UnifiedModelManager: Failed to get installed models for type $type: $e');
    return [];
  }
}
```

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

### Get PrefsKey Property

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/ModelFile/prefsKey.html

Retrieve the SharedPreferences key for storing the installation status of this file.

```dart
String get prefsKey;
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_network_source_handler/WebNetworkSourceHandler/installWithProgress.html

Installs a model from a given source and streams progress updates. Supports cancellation.

```APIDOC
## POST /models/install

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/models/install

### Parameters
#### Request Body
- **source** (ModelSource) - Required - The model source to install from.
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation.

### Request Example
```json
{
  "source": {
    "type": "NetworkSource",
    "url": "https://example.com/model.bin"
  },
  "cancelToken": null
}
```

### Response
#### Success Response (200)
- **progress** (int) - The current installation progress percentage (0-100).

#### Response Example
```json
{
  "progress": 50
}
```

### Notes
- Some sources may not support true progress:
  - AssetSource: simulates progress (copy is instant)
  - BundledSource: returns 100 immediately (no download)
  - FileSource: returns 100 immediately (just registration)

### Throws
- DownloadCancelledException: if cancelled via cancelToken.
- ArgumentError: if the source is not a NetworkSource or the URL is invalid.
```

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

### Unsupported Install Implementation

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_file_source_handler_stub/WebFileSourceHandler/install.html

This implementation of the install method is specific to WebFileSourceHandler and throws an UnsupportedError, indicating it's only available on the web platform.

```dart
@override
Future<void> install(ModelSource source, {CancelToken? cancelToken}) {
  throw UnsupportedError('WebFileSourceHandler is only available on web platform');
}
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_bundled_source_handler/WebBundledSourceHandler/installWithProgress.html

Installs a model and streams progress updates. Supports cancellation.

```APIDOC
## POST /websites/pub_dev_flutter_gemma/installWithProgress

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/websites/pub_dev_flutter_gemma/installWithProgress

### Parameters
#### Query Parameters
- **source** (ModelSource) - Required - The model source to install from.
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation.

### Request Example
```json
{
  "source": "{ModelSource object}",
  "cancelToken": "{CancelToken object}"
}
```

### Response
#### Success Response (200)
- **Stream<int>** - A stream of integers representing progress percentages (0-100).

#### Response Example
```
0
25
50
75
100
```

### Notes
Some sources may not support true progress:
- AssetSource: simulates progress (copy is instant)
- BundledSource: returns 100 immediately (no download)
- FileSource: returns 100 immediately (just registration)

### Throws
- DownloadCancelledException if cancelled via cancelToken
```

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

### installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_file_source_handler_stub/WebFileSourceHandler/installWithProgress.html

Installs a model and streams progress updates. Supports cancellation.

```APIDOC
## installWithProgress

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
STREAM

### Endpoint
N/A (Method Signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `source` (ModelSource) - Required - The model source to install from.
* `cancelToken` (CancelToken?) - Optional - Token for cancelling the installation.

### Notes
Some sources may not support true progress:
* AssetSource: simulates progress (copy is instant)
* BundledSource: returns 100 immediately (no download)
* FileSource: returns 100 immediately (just registration)

### Request Example
```dart
final cancelToken = CancelToken();

try {
  await for (final progress in handler.installWithProgress(
    source,
    cancelToken: cancelToken,
  )) {
    print('Progress: $progress%');
  }
} catch (e) {
  if (CancelToken.isCancel(e)) {
    print('Installation cancelled');
  }
}
```

### Response
#### Success Response (Stream<int>)
- `progress` (int) - The current installation progress percentage (0-100).

#### Response Example
```
Progress: 25%
Progress: 50%
Progress: 75%
Progress: 100%
```

### Throws
* `DownloadCancelledException` if cancelled via `cancelToken`.
```

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

### Get requiresDownload Property

Source: https://pub.dev/documentation/flutter_gemma/latest/core_domain_model_source/ModelSource/requiresDownload.html

Use this getter to check if the source requires downloading. No specific setup is needed.

```dart
bool get requiresDownload;
```

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

### Install Model

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_file_source_handler/FileSourceHandler/install.html

Installs a model from a specified source. Supports network downloads, asset copying, native resources, and external file paths.

```APIDOC
## POST /models/install

### Description
Installs the model from the given source. This method performs the actual installation:
  * NetworkSource: downloads from URL
  * AssetSource: copies from Flutter assets
  * BundledSource: accesses native resources
  * FileSource: registers external file path

### Method
POST

### Endpoint
/models/install

### Parameters
#### Request Body
- **source** (ModelSource) - Required - The model source to install from
- **cancelToken** (CancelToken) - Optional - Optional token for cancelling the installation

### Response
#### Success Response (200)
- **void** - Installation successful

#### Error Response
- **UnsupportedError** - If this handler doesn't support the source type
- **ArgumentError** - If the source is invalid
- **DownloadCancelledException** - If cancelled via cancelToken
- **Exception** - Platform-specific exceptions for download/file errors
```

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

### Implement Model Installation

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_file_source_handler/FileSourceHandler/install.html

This method handles the installation of models from various sources, including network, assets, bundled resources, and external file paths. It includes checks for file existence, registration, and saving model metadata.

```dart
@override
Future<void> install(
  ModelSource source, {
  CancelToken? cancelToken,
}) async {
  // File sources are instant (just registration), no cancellation needed
  if (source is! FileSource) {
    throw ArgumentError('FileSourceHandler only supports FileSource');
  }

  // Verify external file exists
  final exists = await fileSystem.fileExists(source.path);
  if (!exists) {
    throw Exception('External file does not exist: ${source.path}');
  }

  // Generate unique filename for tracking
  final filename = path.basename(source.path);

  // Register external file in file system
  await fileSystem.registerExternalFile(filename, source.path);

  // Protect file from cleanup operations
  await protectedFiles.protect(filename);

  // Register external path mapping
  await protectedFiles.registerExternalPath(filename, source.path);

  // Get file size for metadata
  final sizeBytes = await fileSystem.getFileSize(source.path);

  // Save metadata to repository
  final modelInfo = ModelInfo(
    id: filename,
    source: source,
    installedAt: DateTime.now(),
    sizeBytes: sizeBytes,
    type: ModelType.inference,
    hasLoraWeights: false,
  );

  await repository.saveModel(modelInfo);
}
```

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

### POST /installWithProgress

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_source_handler/SourceHandler/installWithProgress.html

Installs a model and streams progress updates. Note that some sources may not provide true progress.

```APIDOC
## POST /installWithProgress

### Description
Installs the model with progress tracking. Returns a stream of progress percentages (0-100).

### Method
POST

### Endpoint
/installWithProgress

### Parameters
#### Query Parameters
- **source** (ModelSource) - Required - The model source to install from
- **cancelToken** (CancelToken) - Optional - Token for cancelling the installation

### Request Example
```json
{
  "source": "some_model_source",
  "cancelToken": null 
}
```

### Response
#### Success Response (200)
- **Stream<int>** - A stream of integers representing installation progress (0-100).

#### Response Example
```json
{
  "progress": [0, 10, 25, 50, 75, 100]
}
```

### Error Handling
- **DownloadCancelledException**: Thrown if the installation is cancelled via `cancelToken`.
```

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

### Get Model File Paths - Dart

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/MobileModelManager/getModelFilePaths.html

Retrieves file paths for an installed model. Handles different file source types: external, bundled, and downloaded/asset. Returns null if the model is not installed or an error occurs.

```dart
@override
Future<Map<String, String>?> getModelFilePaths(ModelSpec spec) async {
  await _ensureInitialized();

  try {
    if (!await isModelInstalled(spec)) {
      return null;
    }

    final filePaths = <String, String>{};

    final registry = ServiceRegistry.instance;
    final fileSystem = registry.fileSystemService;

    for (final file in spec.files) {
      // Get path based on source type
      final String path;
      if (file.source is FileSource) {
        // External file - use path from source
        path = (file.source as FileSource).path;
      } else if (file.source is BundledSource) {
        // Bundled source - get platform-specific bundled path
        final bundledSource = file.source as BundledSource;
        path = await fileSystem.getBundledResourcePath(bundledSource.resourceName);
      } else {
        // Downloaded/Asset file - use standard app directory
        path = await ModelFileSystemManager.getModelFilePath(file.filename);
      }
      filePaths[file.prefsKey] = path;
    }

    return filePaths;
  } catch (e) {
    debugPrint('UnifiedModelManager: Failed to get file paths for ${spec.name}: $e');
    return null;
  }
}
```

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

### Get supportsProgress Property

Source: https://pub.dev/documentation/flutter_gemma/latest/core_domain_model_source/ModelSource/supportsProgress.html

Use this getter to check if the current source supports progress tracking. No setup is required.

```dart
bool get supportsProgress;
```

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

### POST /install

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_bundled_source_handler/WebBundledSourceHandler/install.html

Installs a model from a specified source. This method handles downloading from URLs, copying from assets, accessing native resources, or registering external file paths.

```APIDOC
## POST /install

### Description
Installs the model from the given source. This method performs the actual installation:
  * NetworkSource: downloads from URL
  * AssetSource: copies from Flutter assets
  * BundledSource: accesses native resources
  * FileSource: registers external file path

### Method
POST

### Endpoint
/install

### Parameters
#### Query Parameters
- **source** (ModelSource) - Required - The model source to install from
- **cancelToken** (CancelToken?) - Optional - Optional token for cancelling the installation

### Request Example
```json
{
  "source": "NetworkSource(url: 'http://example.com/model.zip')",
  "cancelToken": null
}
```

### Response
#### Success Response (200)
- **void** - Indicates successful installation.

#### Error Handling
- **UnsupportedError**: Thrown if this handler doesn't support the source type.
- **ArgumentError**: Thrown if the source is invalid.
- **DownloadCancelledException**: Thrown if cancelled via cancelToken.
- **Platform-specific exceptions**: Thrown for download/file errors.
```

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

### Install and Get Active Embedding Model

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_flutter_gemma/FlutterGemma/getActiveEmbedder.html

First, install the embedding model. Then, retrieve the active embedding model, optionally specifying a preferred backend like CPU. This method returns an EmbeddingModel configured with runtime parameters.

```dart
// Install embedding model first
await FlutterGemma.installEmbedder()
  .modelFromNetwork('https://example.com/model.tflite')
  .tokenizerFromNetwork('https://example.com/tokenizer.model')
  .install();

// Create with default backend
final embeddingModel = await FlutterGemma.getActiveEmbedder();

// Create with specific backend
final cpuModel = await FlutterGemma.getActiveEmbedder(
  preferredBackend: PreferredBackend.cpu,
);

```

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

### Implement Model Installation

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_file_source_handler/WebFileSourceHandler/install.html

This method installs a model from a given source, supporting FileSource for web path registration. It validates and normalizes the path, registers the URL with the file system, and saves model metadata.

```dart
@override
Future<void> install(
  ModelSource source, {
  CancelToken? cancelToken,
}) async {
  // Web file registration is instant, no cancellation needed
  if (source is! FileSource) {
    throw ArgumentError('WebFileSourceHandler only supports FileSource');
  }

  // Validate and normalize the path
  final validatedUrl = _validateAndNormalizePath(source.path);

  // Generate filename from path
  final filename = path.basename(source.path);

  // Register URL with WebFileSystemService
  // This allows MediaPipe to look up the URL via getUrl()
  fileSystem.registerUrl(filename, validatedUrl);

  // Save metadata to repository
  // Note: Can't determine file size without HTTP HEAD request
  final modelInfo = ModelInfo(
    id: filename,
    source: source,
    installedAt: DateTime.now(),
    sizeBytes: -1, // Unknown for web external files
    type: ModelType.inference,
    hasLoraWeights: false,
  );

  await repository.saveModel(modelInfo);
}
```

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

### Get Default SamplerConfig Instance

Source: https://pub.dev/documentation/flutter_gemma/latest/desktop_generated_litertlm.pb/SamplerConfig/getDefault.html

Retrieves the default instance of SamplerConfig. This method is typically used to get a pre-configured instance without manual setup. It utilizes a private static variable to ensure a single instance is created and reused.

```dart
@$core.pragma('dart2js:noInline')
static SamplerConfig getDefault() => _defaultInstance ??= $pb.GeneratedMessage.$_defaultFor<SamplerConfig>(create);
```

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

### ServiceRegistry Initialization and Usage

Source: https://pub.dev/documentation/flutter_gemma/latest/core_di_service_registry/ServiceRegistry-class.html

Demonstrates how to initialize the ServiceRegistry and access its services.

```APIDOC
## ServiceRegistry Initialization and Usage

### Description
This section shows the required steps to initialize the ServiceRegistry and how to access its singleton instance and specific handlers later in your application.

### Method
Static method `initialize()` and instance access `ServiceRegistry.instance`.

### Endpoint
N/A (Class methods)

### Parameters
#### Static Method: `initialize()`
- **huggingFaceToken** (String?) - Optional - Token for Hugging Face services.
- **maxDownloadRetries** (int) - Optional - Maximum number of download retries. Defaults to 10.
- **webStorageMode** (WebStorageMode) - Optional - Mode for web storage. Defaults to `WebStorageMode.cacheApi`.
- **fileSystemService** (FileSystemService?) - Optional - Custom file system service.
- **assetLoader** (AssetLoader?) - Optional - Custom asset loader.
- **downloadService** (DownloadService?) - Optional - Custom download service.
- **modelRepository** (ModelRepository?) - Optional - Custom model repository.
- **protectedFilesRegistry** (ProtectedFilesRegistry?) - Optional - Custom protected files registry.
- **vectorStoreRepository** (VectorStoreRepository?) - Optional - Custom vector store repository.

### Request Example
```dart
void main() {
  WidgetsFlutterBinding.ensureInitialized(); // Required for mobile
  ServiceRegistry.initialize(
    huggingFaceToken: "YOUR_HF_TOKEN",
    maxDownloadRetries: 5,
    webStorageMode: WebStorageMode.persistentStorage
  );
  runApp(MyApp());
}

// Later in your code:
final registry = ServiceRegistry.instance;
final handlerRegistry = registry.sourceHandlerRegistry;
final handler = handlerRegistry.getHandler(source);
await handler.install(source);
```

### Response
#### Success Response (200)
- **void** - The `initialize` method returns a `Future<void>` that completes when the registry is initialized.

#### Response Example
N/A (Initialization is asynchronous and returns void upon completion)

```

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

### Progress and Cancellation Methods

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_embedding_installation_builder/EmbeddingInstallationBuilder-class.html

Methods for handling installation progress and cancellation.

```APIDOC
## Progress and Cancellation Methods

### `withModelProgress(void onProgress(int progress))`
Add model file progress callback. The callback receives the current progress percentage (0-100).

### `withTokenizerProgress(void onProgress(int progress))`
Add tokenizer file progress callback. The callback receives the current progress percentage (0-100).

### `withCancelToken(CancelToken cancelToken)`
Set cancellation token for this installation. Allows external cancellation of the installation process.
```

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

### EmbeddingInstallationBuilder() Constructor

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_embedding_installation_builder/EmbeddingInstallationBuilder/EmbeddingInstallationBuilder.html

Initializes a new instance of the EmbeddingInstallationBuilder class. This is the primary way to start building an embedding installation configuration.

```APIDOC
## EmbeddingInstallationBuilder Constructor

### Description
Initializes a new instance of the `EmbeddingInstallationBuilder` class.

### Method
Constructor

### Endpoint
N/A (Class Constructor)

### Parameters
This constructor does not take any parameters.

### Request Example
```dart
var builder = EmbeddingInstallationBuilder();
```

### Response
N/A (Constructor returns an instance of the class)

### Response Example
N/A
```

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

### Modern API: Install and Get Active Model

Source: https://pub.dev/documentation/flutter_gemma/latest/index.html

Uses the modern, recommended API to install a model from a network URL and retrieve the active model instance. This API offers type-safe model sourcing and automatic active model management.

```dart
await FlutterGemma.installModel(modelType: ModelType.gemmaIt)
  .fromNetwork(url).install();
final model = await FlutterGemma.getActiveModel(maxTokens: 2048);
```

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

### Get isInitialized Status

Source: https://pub.dev/documentation/flutter_gemma/latest/desktop_grpc_client/LiteRtLmClient/isInitialized.html

Use this getter to check if the client is connected and the model is ready. No setup is required beyond initializing the client.

```dart
bool get isInitialized => _isInitialized;
```

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

### Web Platform Setup for Bundled Models

Source: https://pub.dev/documentation/flutter_gemma/latest/index.html

Place model files in the web directory for automatic copying during production builds. Note that this is only for production builds; debug mode does not serve these files.

```bash
# Place model files in web/ directory
example/web/gemma-3-270m-it.task

# Files are automatically copied to build/web/ during production build
flutter build web
```

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

### Get hasErrors Property

Source: https://pub.dev/documentation/flutter_gemma/latest/core_migration_legacy_preferences_migrator/MigrationResult/hasErrors.html

Use this getter to check if the errors list is not empty. No specific setup is required beyond having an errors list.

```dart
bool get hasErrors => errors.isNotEmpty;
```

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

### installWithProgress Method Implementation (Dart)

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_file_source_handler/FileSourceHandler/installWithProgress.html

This is the implementation of the installWithProgress method. It handles FileSource, verifies file existence, registers the file, protects it from cleanup, and saves model metadata. It yields 100% progress immediately for FileSource.

```dart
@override
Stream<int> installWithProgress(
  ModelSource source, {
  CancelToken? cancelToken,
}) async*
{
  // Same as above - file registration is instant
  if (source is! FileSource) {
    throw ArgumentError('FileSourceHandler only supports FileSource');
  }

  // Verify external file exists
  final exists = await fileSystem.fileExists(source.path);
  if (!exists) {
    throw Exception('External file does not exist: ${source.path}');
  }

  // Generate unique filename for tracking
  final filename = path.basename(source.path);

  // Register external file in file system
  await fileSystem.registerExternalFile(filename, source.path);

  // Protect file from cleanup operations
  await protectedFiles.protect(filename);

  // Register external path mapping
  await protectedFiles.registerExternalPath(filename, source.path);

  // External files are immediately available, report 100% after registration
  yield 100;

  // Get file size for metadata
  final sizeBytes = await fileSystem.getFileSize(source.path);

  // Save metadata to repository
  final modelInfo = ModelInfo(
    id: filename,
    source: source,
    installedAt: DateTime.now(),
    sizeBytes: sizeBytes,
    type: ModelType.inference,
    hasLoraWeights: false,
  );

  await repository.saveModel(modelInfo);
}
```

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

### Create InferenceInstallationBuilder

Source: https://pub.dev/documentation/flutter_gemma/latest/core_api_inference_installation_builder/InferenceInstallationBuilder-class.html

Initializes the InferenceInstallationBuilder with the required model type and an optional file type. This is the starting point for configuring model installation.

```dart
InferenceInstallationBuilder({required ModelType modelType, ModelFileType fileType = ModelFileType.task})
```

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

### Get PrefsKey Implementation

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/LoraModelFile/prefsKey.html

This code snippet shows the implementation of the prefsKey getter, which returns the SharedPreferences key for storing the installation status of a file.

```dart
@override
String get prefsKey => PreferencesKeys.installedLoraFileName;
```

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

### Initialize Method

Source: https://pub.dev/documentation/flutter_gemma/latest/web_vector_store_web/SQLiteVectorStore/initialize.html

The `initialize` method is used to set up the Gemma SDK. It requires the path to the database.

```APIDOC
## POST /initialize

### Description
Initializes the Gemma SDK with the specified database path.

### Method
POST

### Endpoint
/initialize

### Parameters
#### Query Parameters
- **databasePath** (String) - Required - The path to the database file.

### Request Example
```json
{
  "databasePath": "/path/to/your/database.db"
}
```

### Response
#### Success Response (200)
- **result** (JSAny?) - Indicates the success or failure of the initialization.

#### Response Example
```json
{
  "result": true
}
```
```

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

### Implementation of installWithProgress

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_asset_source_handler/WebAssetSourceHandler/installWithProgress.html

This is the core implementation of the installWithProgress method. It handles loading assets, caching, and saving model information. Note that it currently only supports AssetSource.

```dart
@override
Stream<int> installWithProgress(
  ModelSource source, {
  CancelToken? cancelToken,
}) async*
{
  if (source is! AssetSource) {
    throw ArgumentError('WebAssetSourceHandler only supports AssetSource');
  }

  final filename = path.basename(source.path);
  final cacheKey = source.normalizedPath; // Already has 'assets/' prefix

  try {
    // Use unified caching helper (cache key is already normalized, no '?' added)
    yield* cacheService.getOrCacheAndRegisterWithProgress(
      cacheKey: cacheKey,
      loader: (onProgress) async {
        debugPrint('[WebAssetSourceHandler] Loading asset: ${source.normalizedPath}');

        onProgress(0.0);
        final byteData = await rootBundle.load(source.normalizedPath);
        final bytes = byteData.buffer.asUint8List();

        // Validate asset is not empty
        if (bytes.isEmpty) {
          throw StateError(
            'Asset file is empty: ${source.normalizedPath}. '
            'Check that the file exists and is not corrupted.'
          );
        }

        debugPrint('[WebAssetSourceHandler] Asset loaded: ${bytes.length} bytes');
        onProgress(1.0);

        return bytes;
      },
      targetPath: filename,
    );

    // Save metadata to repository
    // Repository type is selected by ServiceRegistry based on enableCache:
    // - enableCache=true: SharedPreferencesModelRepository (persistent)
    // - enableCache=false: InMemoryModelRepository (ephemeral)
    final modelInfo = ModelInfo(
      id: filename,
      source: source,
      installedAt: DateTime.now(),
      sizeBytes: -1,
      type: ModelType.inference,
      hasLoraWeights: false,
    );

    await repository.saveModel(modelInfo);
  } catch (e) {
    debugPrint('[WebAssetSourceHandler] ❌ Failed to install asset: $e');
    rethrow;
  }
}
```

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

### Get prefsKey Implementation

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/EmbeddingTokenizerFile/prefsKey.html

This getter returns the SharedPreferences key used for storing the installation status of a file. Ensure PreferencesKeys.embeddingTokenizerFile is correctly defined.

```dart
@override
String get prefsKey => PreferencesKeys.embeddingTokenizerFile;
```

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

### Get isRequired Property

Source: https://pub.dev/documentation/flutter_gemma/latest/mobile_flutter_gemma_mobile/ModelFile/isRequired.html

Use this getter to determine if a file is required for the model to function. No specific setup or imports are needed beyond the class definition.

```dart
bool get isRequired;
```

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

### Implement installWithProgress Method

Source: https://pub.dev/documentation/flutter_gemma/latest/core_handlers_web_file_source_handler/WebFileSourceHandler/installWithProgress.html

This is the implementation of the installWithProgress method for WebFileSourceHandler. It simulates progress and registers the web file.

```dart
@override
Stream<int> installWithProgress(
  ModelSource source, {
  CancelToken? cancelToken,
}) async*
{
  // Same as above - web file registration is instant
  if (source is! FileSource) {
    throw ArgumentError('WebFileSourceHandler only supports FileSource');
  }

  // Simulate progress for UX consistency
  yield 0;
  await Future.delayed(const Duration(milliseconds: 50));
  yield 50;
  await Future.delayed(const Duration(milliseconds: 50));

  // Validate and normalize the path
  final validatedUrl = _validateAndNormalizePath(source.path);

  // Generate filename from path
  final filename = path.basename(source.path);

  // Register URL with WebFileSystemService
  fileSystem.registerUrl(filename, validatedUrl);

  yield 100;

  // Save metadata to repository
  final modelInfo = ModelInfo(
    id: filename,
    source: source,
    installedAt: DateTime.now(),
    sizeBytes: -1, // Unknown for web external files
    type: ModelType.inference,
    hasLoraWeights: false,
  );

  await repository.saveModel(modelInfo);
}
```