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.

14.7 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 { apiUrl, getApiPort, isTauri } from "@/lib/api-base";
import { setHfEndpoints } from "@/lib/hf-endpoint";
import {
  isDetectionDeferred,
  isProvisionalVerdict,
  resolveVerdict,
  trainsOnCpu,
} from "@/config/hardware-verdict";
import { create } from "zustand";

// Backend routes, so same origin: the page CSP already allows them whatever endpoint is saved later.
const MODELSCOPE_HUB_PATH = "/api/hub/modelscope";

function backendUrl(path: string): string {
  return new URL(apiUrl(path), window.location.href).href;
}

export const env = {
  MODE: import.meta.env.MODE,
  DEV: import.meta.env.DEV,
  PROD: import.meta.env.PROD,
  BASE_URL: import.meta.env.BASE_URL,
} as const;

export type DeviceType = "mac" | "windows" | "linux" | string;

export type FileManager = "finder" | "explorer" | "files" | null;

interface PlatformState {
  deviceType: DeviceType;
  // Unified memory: an over-committed load takes the machine down. Narrower than deviceType
  // "mac" (Intel Macs spill to RAM). Mirrors the backend's is_apple_silicon gate.
  appleSilicon: boolean;
  fileManager: FileManager | undefined;
  chatOnly: boolean;
  // /api/health reason for chatOnly; null while training is enabled.
  chatOnlyReason: string | null;
  // MLX gate covers mlx, mlx-lm, and mlx-vlm together; record the blocker when known.
  chatOnlyDetail: string | null;
  chatOnlyHint: string | null;
  // Developer mode's CPU video opt-in, from authed /api/health; keeps the Video row navigable
  // on a no-GPU host that opted in.
  videoCpuOptIn: boolean;
  // authed /api/health cpu_training: training runs (or would, on "no_torch") on the CPU backend.
  cpuTraining: boolean;
  // authenticated /api/health values for cloudflareUrl, serverUrl, and secure.
  cloudflareUrl: string | null;
  serverUrl: string | null;
  secure: boolean;
  lanUrls: string[];
  fetched: boolean;
  verdictStale: boolean;
  // Detection stays cold until a hardware-dependent page or operation requests it.
  detectionDeferred: boolean;
  isChatOnly: () => boolean;
  // Train and /studio are off: chat-only, except a host that trains on the CPU backend.
  isTrainUnavailable: () => boolean;
  isCpuTrainingHost: () => boolean;
  // true until /api/health returns a verdict; guesses cannot gate features.
  capabilitiesUnknown: () => boolean;
}

function detectLocalPlatform(): DeviceType {
  if (typeof navigator === "undefined") return "linux";
  const platform = navigator.platform.toLowerCase();
  const ua = navigator.userAgent.toLowerCase();
  if (platform.includes("mac") || ua.includes("mac")) return "mac";
  if (platform.includes("win") || ua.includes("win")) return "windows";
  return "linux";
}

const localDeviceType = detectLocalPlatform();

export const usePlatformStore = create<PlatformState>()((_, get) => ({
  deviceType: localDeviceType,
  appleSilicon: false,
  fileManager: undefined,
  // user-agent guess for redirects; capability gates await the server.
  chatOnly: localDeviceType === "mac",
  chatOnlyReason: null,
  chatOnlyDetail: null,
  chatOnlyHint: null,
  videoCpuOptIn: false,
  cpuTraining: false,
  cloudflareUrl: null,
  serverUrl: null,
  secure: false,
  lanUrls: [],
  fetched: false,
  verdictStale: false,
  detectionDeferred: false,
  isChatOnly: () => get().chatOnly,
  isTrainUnavailable: () => get().chatOnly && !get().isCpuTrainingHost(),
  isCpuTrainingHost: () => {
    const state = get();
    return state.chatOnly && trainsOnCpu(state.chatOnlyReason, state.cpuTraining);
  },
  // Deferred is unknown, not an unsupported host; navigation can request detection.
  capabilitiesUnknown: () => {
    const state = get();
    return !state.fetched || state.verdictStale || state.detectionDeferred;
  },
}));

// Never let a non-forced response overwrite an authoritative platform: the early unauthed fetch
// in main.tsx can resolve late. Forced refreshes still write.
function shouldKeepAuthoritativePlatform(force?: boolean): boolean {
  return !force && usePlatformStore.getState().fetched;
}

// Wait for a still-detecting backend, sized from the warm torch import (~1-2s) plus headroom.
const HARDWARE_DETECT_WAIT_MS = 5000;
const HARDWARE_DETECT_POLL_MS = 200;
// The bounded wait above is spent at most once per page load: see fetchDeviceType.
let hardwareWaitSpent = false;

/** A repair or restart replaced the backend: its predecessor's verdict is no longer measured. Platform fields stay. */
export function forgetMeasuredVerdict(): void {
  hardwareWaitSpent = false;
  backendGeneration += 1;
  // The old deferred flag would mask staleness, so a failed first read would look settled.
  usePlatformStore.setState({ verdictStale: true, detectionDeferred: false });
}

// Backend not ready: use client detection, keep fetched=false, but never wipe an authoritative one.
function localPlatformFallback(force?: boolean): DeviceType {
  if (shouldKeepAuthoritativePlatform(force)) {
    return usePlatformStore.getState().deviceType;
  }
  const deviceType = detectLocalPlatform();
  const chatOnly = deviceType === "mac";
  usePlatformStore.setState({ deviceType, chatOnly, fetched: false });
  return deviceType;
}

// Bumped on a backend replacement so a read sent to the old backend is never joined.
let backendGeneration = 0;
// Once detection was requested or observed, an older idle reply cannot defer this backend again.
let requestedHardwareGeneration: number | null = null;
let systemVerdictRead: { generation: number; promise: Promise<DeviceType> } | null = null;

/** Refresh the picker verdict; a cached caller may need to request detection again. */
export function refreshDeviceTypeAfterSystemInfo(
  { detectHardware = false }: { detectHardware?: boolean } = {},
): void {
  if (!usePlatformStore.getState().capabilitiesUnknown()) return;
  if (systemVerdictRead?.generation === backendGeneration) return;
  const entry = {
    generation: backendGeneration,
    promise: fetchDeviceType({ force: true, detectHardware }),
  };
  systemVerdictRead = entry;
  const release = () => {
    if (systemVerdictRead === entry) systemVerdictRead = null;
  };
  // System data remains usable while this independent health read finishes or fails.
  void entry.promise.then(release, release);
}

// main.tsx and __root.tsx's beforeLoad both read at startup: an unforced call joins an unforced
// read in flight for the same token, URL and backend generation. Forced refreshes never share.
let sharedHealthRead: {
  token: string | null;
  url: string;
  generation: number;
  promise: Promise<DeviceType>;
} | null = null;

function readAuthToken(): string | null {
  // device_type is only reported to authed callers. Read the token directly: importing
  // features/auth would cycle.
  return typeof window === "undefined"
    ? null
    : localStorage.getItem("unsloth_auth_token");
}

// `force` re-reads /api/health even if cached, to pick up a late-arriving tunnel URL.
export async function fetchDeviceType(options?: {
  force?: boolean;
  detectHardware?: boolean;
}): Promise<DeviceType> {
  const { fetched } = usePlatformStore.getState();
  if (fetched && !options?.force && !options?.detectHardware)
    return usePlatformStore.getState().deviceType;
  // Desktop before server-port: port 0 never connects, so take the refused-fetch fallback.
  if (isTauri && getApiPort() === null) {
    return localPlatformFallback(options?.force);
  }
  if (options?.detectHardware) return readHealth({ ...options, force: true });
  if (options?.force) return readHealth(options);

  let token: string | null;
  try {
    token = readAuthToken();
  } catch {
    // Same fallback as a failed read; readHealth records it.
    return readHealth(options);
  }
  const url = apiUrl("/api/health");
  const shared = sharedHealthRead;
  if (
    shared !== null &&
    shared.token === token &&
    shared.url === url &&
    shared.generation === backendGeneration
  ) {
    return shared.promise;
  }
  const entry = {
    token,
    url,
    generation: backendGeneration,
    promise: readHealth(options, token),
  };
  sharedHealthRead = entry;
  const release = () => {
    if (sharedHealthRead === entry) sharedHealthRead = null;
  };
  entry.promise.then(release, release);
  return entry.promise;
}

async function readHealth(
  options: { force?: boolean; detectHardware?: boolean } | undefined,
  knownToken?: string | null,
): Promise<DeviceType> {
  const generation = backendGeneration;
  try {
    const token = knownToken === undefined ? readAuthToken() : knownToken;
    // Re-read while the backend is still detecting: chat_only is its pre-detection default and
    // __root.tsx's beforeLoad acts on it.
    const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
    // Wait only when authed (else beforeLoad stalls /login), and only once. Claim the latch after.
    const spendWait = Boolean(token) && !hardwareWaitSpent;
    const deadline = spendWait ? Date.now() + HARDWARE_DETECT_WAIT_MS : 0;
    let tokenRejected = false;
    let detectionDeferred = false;
    // Only an authenticated, explicit page visit may request the cold hardware probe.
    const healthUrl = apiUrl(
      options?.detectHardware && token ? "/api/health?detect_hardware=true" : "/api/health",
    );
    let res = await fetch(healthUrl, { headers });
    while (res.ok && Date.now() < deadline) {
      const peek = (await res.clone().json()) as {
        hardware_detecting?: boolean;
        hardware_detection_deferred?: boolean;
        version?: string;
      };
      // Deferred is not "in progress": nothing will settle, so do not wait.
      detectionDeferred = isDetectionDeferred(peek);
      if (!isProvisionalVerdict(peek) || detectionDeferred) break;
      // A rejected token gets the unauthed body: no `version`, so the wait could only time out.
      if (peek.version === undefined) {
        tokenRejected = true;
        break;
      }
      await new Promise((resolve) => setTimeout(resolve, HARDWARE_DETECT_POLL_MS));
      res = await fetch(healthUrl, { headers });
    }
    if (generation !== backendGeneration) return usePlatformStore.getState().deviceType;
    // A rejected token or a deferred probe has not used the first real detection's wait.
    if (spendWait && !tokenRejected && !detectionDeferred) hardwareWaitSpent = true;
    if (res.ok) {
      const data = (await res.json()) as {
        device_type?: string;
        version?: string;
        apple_silicon?: boolean;
        file_manager?: FileManager;
        chat_only?: boolean;
        chat_only_reason?: string | null;
        video_cpu_opt_in?: boolean;
        cpu_training?: boolean;
        hardware_detecting?: boolean;
        cloudflare_url?: string | null;
        server_url?: string | null;
        secure?: boolean;
        hf_endpoint?: string;
        hf_datasets_server?: string;
        hub_source?: string;
        hub_proxy?: string | null;
        datasets_server_proxy?: string | null;
      };
      if (generation !== backendGeneration) return usePlatformStore.getState().deviceType;
      if (
        data.version !== undefined &&
        !isDetectionDeferred(data) &&
        (options?.detectHardware || !isProvisionalVerdict(data))
      ) {
        requestedHardwareGeneration = generation;
      }
      if (
        !options?.detectHardware &&
        isDetectionDeferred(data) &&
        requestedHardwareGeneration === backendGeneration
      ) {
        return usePlatformStore.getState().deviceType;
      }
      // Before the authoritative-platform guard: hub_proxy is unauthed and idempotent, and a mirror
      // whose first authoritative reply already landed would otherwise never route Hub calls.
      const hubProxy = typeof data.hub_proxy === "string" ? data.hub_proxy : null;
      const datasetsProxy =
        typeof data.datasets_server_proxy === "string" ? data.datasets_server_proxy : null;
      setHfEndpoints(
        data.hub_source === "modelscope"
          ? backendUrl(MODELSCOPE_HUB_PATH)
          : hubProxy
            ? backendUrl(hubProxy)
            : data.hf_endpoint,
        datasetsProxy ? backendUrl(datasetsProxy) : data.hf_datasets_server,
        data.hub_source,
        { endpoint: hubProxy !== null, datasetsServer: datasetsProxy !== null },
      );
      if (shouldKeepAuthoritativePlatform(options?.force)) {
        return usePlatformStore.getState().deviceType;
      }
      const previous = usePlatformStore.getState();
      // A provisional reply omits device_type; keep the server's answer rather than relabel a remote host.
      const keepPlatform = data.device_type === undefined && previous.fetched;
      const deviceType =
        data.device_type ?? (keepPlatform ? previous.deviceType : detectLocalPlatform());
      // Kept on the same terms as device_type; absent means false (correct on Intel Macs).
      const appleSilicon =
        data.apple_silicon ?? (keepPlatform ? previous.appleSilicon : false);
      const fileManager =
        data.device_type !== undefined
          ? data.file_manager
          : keepPlatform
            ? previous.fileManager
            : undefined;
      // Provisional keeps the stored verdict; a replaced backend must not keep the old reason.
      const { chatOnly, chatOnlyReason, chatOnlyDetail, chatOnlyHint } = resolveVerdict(
        data,
        previous.verdictStale && isDetectionDeferred(data)
          ? { chatOnly: previous.chatOnly, chatOnlyReason: null, chatOnlyDetail: null, chatOnlyHint: null }
          : previous,
      );
      // Cache only server-reported platforms: browser fallbacks differ from the host, so retry
      // until authed.
      usePlatformStore.setState({
        deviceType,
        appleSilicon,
        fileManager,
        chatOnly,
        chatOnlyReason,
        chatOnlyDetail,
        chatOnlyHint,
        // Rides with the verdict: a provisional reply carries neither, so it keeps the stored one.
        videoCpuOptIn:
          data.video_cpu_opt_in === undefined
            ? previous.videoCpuOptIn
            : data.video_cpu_opt_in === true,
        cpuTraining:
          data.cpu_training === undefined ? previous.cpuTraining : data.cpu_training === true,
        cloudflareUrl: data.cloudflare_url ?? null,
        serverUrl: data.server_url ?? null,
        secure: data.secure ?? false,
        // A deferred reply names the platform but stays unfetched, so later reads can settle the verdict.
        fetched: (data.device_type !== undefined && !isDetectionDeferred(data)) || keepPlatform,
        verdictStale: previous.verdictStale && isProvisionalVerdict(data) && !isDetectionDeferred(data),
        detectionDeferred: isDetectionDeferred(data),
      });
      return deviceType;
    }
  } catch {
    if (generation !== backendGeneration) return usePlatformStore.getState().deviceType;
    return localPlatformFallback(options?.force);
  }

  return usePlatformStore.getState().deviceType;
}