install method

@override Future<void> install(ModelSource source, { CancelToken? cancelToken, String? targetFilename, ModelType modelType = ModelType.inference, })

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

Parameters:

• source: The model source to install from
• cancelToken: Optional token for cancelling the installation
• targetFilename: Optional override for the installed file's identity (write-target basename, ModelInfo.id, and — on web — the registration/cache key). Defaults to null, which reproduces today's behavior: the basename is derived from source (URL path segment / asset path / bundled resource name / file path). Passed by the four *InstallationBuilders so a companion file's on-disk identity can be namespaced by its owning model (see docs/superpowers/specs/2026-08-02-install-identity-namespacing-design.md).

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 modelType: the repository model-type tag written to ModelInfo (defaults to inference; STT/TTS/embedding builders override).

Implementation

@override
Future<void> install(
  ModelSource source, {
  CancelToken? cancelToken,
  String? targetFilename,
  ModelType modelType = ModelType.inference,
}) async {
  // Bundled resources are instant, no cancellation needed
  if (source is! BundledSource) {
    throw ArgumentError('BundledSourceHandler only supports BundledSource');
  }

  // Get platform-specific bundled resource path
  // This path is used directly by the native layer (no copying needed)
  final bundledPath = await fileSystem.getBundledResourcePath(
    source.resourceName,
  );

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

  // Save metadata to repository
  final modelInfo = ModelInfo(
    id: targetFilename ?? source.resourceName,
    source: source,
    installedAt: DateTime.now(),
    sizeBytes: sizeBytes,
    type: modelType,
    hasLoraWeights: false,
  );

  await repository.saveModel(modelInfo);
}