install method

  1. @override
Future<void> install(
  1. ModelSource source, {
  2. CancelToken? cancelToken,
  3. String? targetFilename,
})
override

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:

Implementation

@override
Future<void> install(
  ModelSource source, {
  CancelToken? cancelToken,
  String? targetFilename,
}) 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 = targetFilename ?? 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);
  assertInstalledFilePresent(sizeBytes, 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);
}