fromHuggingFace method

InferenceInstallationBuilder fromHuggingFace(
  1. String repo, {
  2. String? file,
  3. String revision = 'main',
  4. String? token,
  5. bool? foreground,
})

Set model source from a Hugging Face repo. Two modes:

Explicit file (pass file): builds https://huggingface.co/<repo>/resolve/<revision>/<file> and installs it via the network path. file may contain / for a repo that nests variants in subfolders (e.g. int4/model.litertlm); each segment is URL-encoded independently so the path structure survives. Use this when you know the exact path (and optionally a pinned revision).

Manifest (one-call) (OMIT file): resolves the repo's deployment manifest internally at install time — via the resolver registered for this builder's fileType (see FlutterEdgeAi.resolveHuggingFace) — then installs the resolved, revision-pinned variant and returns the manifest's overridable runtime defaults on InferenceInstallation.runtime:

final install = await FlutterEdgeAi
    .installModel(modelType: ModelType.general, fileType: ModelFileType.litertlm)
    .fromHuggingFace('org/repo')            // no file — resolve the manifest
    .install();
final model = await FlutterEdgeAi.getActiveModel(defaults: install.runtime);

Notes on the manifest mode:

  • revision must be left 'main': the registered resolver owns the pin (it builds a revision-pinned URL). Passing a non-'main' revision without a file throws ArgumentError.
  • The resolver's own behavior surfaces from install: .onnx resolves and installs an ORT-GenAI model DIRECTORY (via the HF file tree), while .builtIn throws UnsupportedError (the OS owns the weights — there is no Hugging Face file) — naming the repo.
  • Unlike other sources, this requires NETWORK access at install even if the model is already installed (the variant filename is only known after the manifest fetch). For offline-safe idempotent installs, cache the ResolvedHfModel yourself and install from fromNetwork(r.url).
  • modelType: pass ModelType.general to let the manifest decide the family; pass a SPECIFIC type to keep your choice (it wins over the manifest, and any disagreement is surfaced in InferenceInstallation.notes).
  • A CancelToken set via withCancelToken cannot interrupt the manifest fetch itself (the resolver takes no token); cancellation is honoured immediately after the fetch returns, before the download starts.

The plugin already applies the configured HuggingFace token to huggingface.co URLs for gated repos, so token is only needed to override it (it is also threaded into the manifest fetch).

Implementation

InferenceInstallationBuilder fromHuggingFace(
  String repo, {
  String? file,
  String revision = 'main',
  String? token,
  bool? foreground,
}) {
  // Fail loud at the seam — an empty repo would otherwise build a URL that
  // only 404s (or, worse, saves a CDN error page as the model) far downstream.
  if (repo.trim().isEmpty) {
    throw ArgumentError.value(repo, 'repo', 'must be a non-empty "org/name"');
  }
  if (file == null) {
    // Manifest mode: defer resolution to install(). The resolver builds the
    // revision-pinned URL, so a caller-supplied non-'main' revision here has
    // nowhere to go — reject it loudly rather than silently dropping the pin.
    if (revision != 'main') {
      throw ArgumentError.value(
        revision,
        'revision',
        'cannot be set without an explicit `file`: the registered resolver '
            'owns the revision pin. Pass `file:` to install a specific path '
            'at a specific revision, or register the resolver with the '
            'revision you want.',
      );
    }
    _clearSource();
    _modelSource = null; // cancel any earlier explicit source
    _hfRepo = repo;
    _hfToken = token;
    _hfForeground = foreground;
    return this;
  }
  if (file.trim().isEmpty) {
    throw ArgumentError.value(
      file,
      'file',
      'must be a non-empty repo-relative path (or omit `file` to resolve the '
          'repo manifest)',
    );
  }
  final encodedPath = file.split('/').map(Uri.encodeComponent).join('/');
  final url = 'https://huggingface.co/$repo/resolve/$revision/$encodedPath';
  return fromNetwork(url, token: token, foreground: foreground);
}