Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

9.1 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

import { AUDIO_CPP_REPO } from "@/features/audio/audio-cpp-catalog";
import { audioWorkflowForPick } from "@/features/audio/route-search";
import type { ModelConfigHandoffRequest } from "@/features/model-picker";
import {
  audioPickIsRoutable,
  curatedAudioInventoryTask,
  speechGgufIsUndecodable,
} from "@/features/model-picker/components/model-selector/audio-picker-policy";
import {
  AUDIO_CATALOG,
  artifactForRepoId,
} from "@/features/model-picker/components/model-selector/model-catalog";
import type { SelectedModelView } from "../types";
import { EMBEDDING_TAGS } from "./hf-model-meta.ts";
import { routableToMediaPage } from "./local-path.ts";

export interface HubModelRunSelection {
  checkpointFilename?: string;
  ggufVariant?: string;
  ggufFilename?: string;
  expectedBytes?: number;
  /** ggufVariant is an MLX precision folder, fetched by the load itself. */
  precisionFolder?: boolean;
  downloaded?: boolean;
}

function isPresent(value: string | null | undefined): value is string {
  return Boolean(value?.trim());
}

function hasSupportedFormat(model: SelectedModelView): boolean {
  if (model.modelFormat === "gguf") {
    return model.isGguf;
  }
  return (
    (model.modelFormat === "safetensors" ||
      model.modelFormat === "checkpoint" ||
      model.modelFormat === "adapter") &&
    !model.isGguf
  );
}

const GENERATIVE_CAPABILITIES = new Set([
  "conversational",
  "tools",
  "reasoning",
  "code",
  "vision",
  "audio",
  "diffusion",
]);

export function isEmbeddingOnly(model: SelectedModelView): boolean {
  if (
    model.isGguf ||
    !model.capabilities.some((capability) => capability.key === "embedding")
  ) {
    return false;
  }
  if (EMBEDDING_TAGS.has(model.pipelineTag?.trim().toLowerCase() ?? "")) {
    return true;
  }
  return !model.capabilities.some((capability) =>
    GENERATIVE_CAPABILITIES.has(capability.key),
  );
}

function hasCompleteInventoryModel(model: SelectedModelView): boolean {
  return model.isDownloaded && !model.isPartial && isPresent(model.loadId);
}

function hasRunnableChatModel(model: SelectedModelView): boolean {
  return (
    model.runtimeCanChat &&
    hasCompleteInventoryModel(model) &&
    !isEmbeddingOnly(model) &&
    hasSupportedFormat(model)
  );
}

function hasValidSelection(
  model: SelectedModelView,
  selection: HubModelRunSelection,
): boolean {
  const hasGgufVariant = isPresent(selection.ggufVariant);
  const hasGgufFilename = isPresent(selection.ggufFilename);
  if (model.modelFormat !== "gguf") {
    return !(hasGgufVariant || hasGgufFilename);
  }
  return !model.requiresVariant || hasGgufVariant;
}

function createHandoffMeta(
  model: SelectedModelView,
  selection: HubModelRunSelection,
  usesLocalIdentity: boolean,
): ModelConfigHandoffRequest["meta"] {
  const meta: ModelConfigHandoffRequest["meta"] = {
    source: usesLocalIdentity ? "local" : "hub",
    isLora: model.modelFormat === "adapter",
    loadId: model.loadId,
    isDownloaded: true,
    isGguf: model.modelFormat === "gguf",
    pipelineTag: model.task ?? model.pipelineTag ?? null,
  };
  if (isPresent(selection.ggufVariant)) {
    meta.ggufVariant = selection.ggufVariant;
  }
  if (isPresent(selection.ggufFilename)) {
    meta.ggufFilename = selection.ggufFilename;
  }
  if (
    selection.expectedBytes != null &&
    Number.isFinite(selection.expectedBytes) &&
    selection.expectedBytes > 0
  ) {
    meta.expectedBytes = selection.expectedBytes;
  }
  return meta;
}

function createPrecisionFolderHandoff(
  requestId: string,
  model: SelectedModelView,
  selection: HubModelRunSelection,
): ModelConfigHandoffRequest | null {
  const id = model.hubRepoId ?? model.id;
  if (
    !isPresent(id) ||
    !isPresent(selection.ggufVariant) ||
    isEmbeddingOnly(model)
  ) {
    return null;
  }
  const meta: ModelConfigHandoffRequest["meta"] = {
    source: "hub",
    isLora: false,
    isDownloaded: selection.downloaded === true,
    isGguf: false,
    ggufVariant: selection.ggufVariant,
    pipelineTag: model.task ?? model.pipelineTag ?? null,
  };
  if (isPresent(selection.ggufFilename)) {
    meta.ggufFilename = selection.ggufFilename;
  }
  if (
    selection.expectedBytes != null &&
    Number.isFinite(selection.expectedBytes) &&
    selection.expectedBytes > 0
  ) {
    meta.expectedBytes = selection.expectedBytes;
  }
  return { requestId, id, displayName: model.title, meta };
}

/** The task the Audio handoff runs on: offline, a cached curated audio GGUF carries only the
 *  backend's generic text-generation task, which the picker maps back from the catalog too. */
export function hubAudioTask(
  model: SelectedModelView,
  task: string | null,
): string | null {
  const artifact = model.hubRepoId
    ? artifactForRepoId(model.hubRepoId, AUDIO_CATALOG)
    : null;
  return curatedAudioInventoryTask({
    inventoryTask: task,
    isExactCatalogArtifact: artifact !== null,
    catalogScope: artifact?.group.scope,
    catalogTask: artifact?.group.task,
  });
}

/** Whether Run opens this model on the Audio page rather than in chat, which refuses audio models.
 *  Judged on the gate the chat picker routes by, so both surfaces send the same models there. */
export function hubModelRunsOnAudioPage(
  model: SelectedModelView,
  task: string | null,
): boolean {
  // A filesystem row has no Hub id for the Audio handoff, so it keeps its chat Run.
  const id = model.hubRepoId;
  if (!id || !routableToMediaPage(model.kind, model.localSource)) return false;
  // The shared GGUF audio repo holds many models; the Audio page lists them one by one.
  if (id.toLowerCase() === AUDIO_CPP_REPO.toLowerCase()) return false;
  task = hubAudioTask(model, task);
  const audioType = model.audioType ?? null;
  if (audioWorkflowForPick({ id, task, audioType }) === null) return false;
  return audioPickIsRoutable({
    id,
    task,
    isGguf: model.isGguf,
    isCurated: artifactForRepoId(id, AUDIO_CATALOG) !== null,
    // An on-device GGUF is tagged text-to-audio only by the audio runtime's header classifier.
    taskFromGgufArch: model.isGguf && model.task === "text-to-audio",
    baseModel: model.baseModel,
    tags: model.tags,
    libraryName: model.libraryName,
    audioType,
  });
}

// Speech, music and separation tasks. ASR is left out: chat keeps its Run for transcription
// models (MLX Whisper on Mac reaches Audio only from the picker).
const CHAT_UNLOADABLE_AUDIO_TASKS: ReadonlySet<string> = new Set([
  "text-to-speech",
  "text-to-audio",
  "audio-to-audio",
]);

// A speech GGUF from these stacks loads in llama.cpp, and chat reads an Orpheus-style codec
// vocabulary at load, so a fine-tune named for no family still speaks there. Other libraries (nemo) do not load.
const LLAMA_CPP_GGUF_LIBRARIES: ReadonlySet<string> = new Set([
  "transformers",
  "gguf",
  "llama.cpp",
]);

/** Whether Run must refuse an audio model the Audio page cannot run, instead of handing it to
 *  chat, which cannot load it either and would unload the chat model first. The chat picker
 *  refuses the same picks. */
export function hubAudioRunRefused(
  model: SelectedModelView,
  task: string | null,
): boolean {
  const id = model.hubRepoId;
  if (!id || !routableToMediaPage(model.kind, model.localSource)) return false;
  const audioTask = hubAudioTask(model, task);
  if (!audioTask || !CHAT_UNLOADABLE_AUDIO_TASKS.has(audioTask)) return false;
  const library = model.libraryName?.toLowerCase();
  if (
    audioTask === "text-to-speech" &&
    model.isGguf &&
    (!library || LLAMA_CPP_GGUF_LIBRARIES.has(library)) &&
    !speechGgufIsUndecodable({
      isGguf: true,
      id,
      baseModel: model.baseModel,
      tags: model.tags,
    })
  )
    return false;
  return !hubModelRunsOnAudioPage(model, task);
}

export function isHubModelRunEligible({
  model,
  isDataset,
  mediaRuntime,
  nonGgufRuntimeAvailable,
}: {
  model: SelectedModelView | null;
  isDataset: boolean;
  mediaRuntime: boolean;
  nonGgufRuntimeAvailable: boolean;
}): boolean {
  if (!model || isDataset) {
    return false;
  }

  if (mediaRuntime) {
    return (
      hasCompleteInventoryModel(model) &&
      isPresent(model.hubRepoId) &&
      routableToMediaPage(model.kind, model.localSource)
    );
  }

  if (!hasRunnableChatModel(model)) {
    return false;
  }

  return model.modelFormat === "gguf" || nonGgufRuntimeAvailable;
}

export function createHubModelConfigHandoff({
  requestId,
  model,
  selection,
}: {
  requestId: string;
  model: SelectedModelView;
  selection: HubModelRunSelection;
}): ModelConfigHandoffRequest | null {
  if (!isPresent(requestId)) {
    return null;
  }
  if (selection.precisionFolder) {
    return createPrecisionFolderHandoff(requestId, model, selection);
  }
  if (!hasRunnableChatModel(model)) {
    return null;
  }

  if (!hasValidSelection(model, selection)) {
    return null;
  }

  const usesLocalIdentity = model.isLocal && model.localSource !== "hf_cache";
  const id = usesLocalIdentity ? model.id : (model.hubRepoId ?? model.id);
  if (!isPresent(id)) {
    return null;
  }

  return {
    requestId,
    id,
    displayName: model.title,
    meta: createHandoffMeta(model, selection, usesLocalIdentity),
  };
}