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.

11.6 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 assert from "node:assert/strict";
import test from "node:test";

import {
  formatBytesGiB,
  formatGiB,
  formatKvRate,
} from "../src/lib/memory/format.ts";
import {
  DEFAULT_VRAM_BUDGET_FRACTION,
  MEMORY_FIT_TIGHT_RATIO,
  PRESSURE_CRITICAL_PCT,
  PRESSURE_HIGH_PCT,
} from "../src/lib/memory/thresholds.ts";
import {
  classifyMemoryFit,
  fromModelMemoryStatus,
  toModelMemoryStatus,
  worseMemoryFit,
} from "../src/lib/memory/verdict.ts";

import { readSrc } from "./helpers/kit.ts";

const GIB = 1024 ** 3;

test("every formatter names a BINARY unit, because every divide is binary", () => {
  // Each divides by 1024, so each must name a binary unit.
  assert.equal(formatGiB(7.24), "7.2 GiB");
  assert.equal(formatGiB(24), "24 GiB");
  assert.equal(formatBytesGiB(24 * GIB), "24.00 GiB");
  assert.equal(formatKvRate(6234), "6.1 KiB");
  assert.equal(formatKvRate(1024 * 1024 * 3), "3.0 MiB");
});

test("the two size formatters take DIFFERENT units, and say so in their names", () => {
  // The old pair shared a name and signature but took bytes vs GiB, off by 1024^3.
  const oneGibAsBytes = GIB;
  const oneGib = 1;
  assert.equal(formatBytesGiB(oneGibAsBytes), "1.00 GiB");
  assert.equal(formatGiB(oneGib), "1.0 GiB");
  assert.notEqual(formatGiB(oneGibAsBytes), "1.0 GiB");
});

test("no formatter renders a number that does not exist", () => {
  // Figures come off the wire; NaN or negative must not read as measurements.
  for (const bad of [Number.NaN, Number.POSITIVE_INFINITY, -5, undefined]) {
    assert.equal(formatGiB(bad as number), "0 GiB");
    assert.equal(formatBytesGiB(bad as number), "0.00 GiB");
    assert.equal(formatKvRate(bad as number), "0 KiB");
  }
});

test("the budget fraction matches what the loader admits at", () => {
  // 0.97 is _CTX_FIT_VRAM_FRACTION in core/inference/llama_cpp.py; verdicts must match admission.
  assert.equal(DEFAULT_VRAM_BUDGET_FRACTION, 0.97);
  // Not 0.90: llama_cpp.py records it as reverted (dropped fits to CPU offload).
  assert.notEqual(DEFAULT_VRAM_BUDGET_FRACTION, 0.9);
});

test("the fit threshold and the pressure ramp stay distinct", () => {
  assert.equal(MEMORY_FIT_TIGHT_RATIO, 0.85);
  assert.equal(PRESSURE_HIGH_PCT, 80);
  assert.equal(PRESSURE_CRITICAL_PCT, 90);
  assert.ok(PRESSURE_HIGH_PCT < PRESSURE_CRITICAL_PCT);
});

test("a figure that does not exist is never a confident fit", () => {
  // NaN fails every comparison, so `<= 0` alone lets it fall through to "fits".
  assert.equal(classifyMemoryFit(Number.NaN, 24), "unknown");
  assert.equal(classifyMemoryFit(8 * GIB, Number.NaN), "unknown");
  assert.equal(classifyMemoryFit(Number.POSITIVE_INFINITY, 24), "unknown");
  assert.equal(classifyMemoryFit(8 * GIB, 0), "unknown");
});

test("the bands land where the thresholds say", () => {
  assert.equal(classifyMemoryFit(8 * GIB, 24), "fits");
  // Just over 85% of 24 GiB.
  assert.equal(classifyMemoryFit(21 * GIB, 24), "tight");
  assert.equal(classifyMemoryFit(25 * GIB, 24), "exceeds");
});

test("unknown never erases a real verdict", () => {
  assert.equal(worseMemoryFit("unknown", "exceeds"), "exceeds");
  assert.equal(worseMemoryFit("fits", "tight"), "tight");
  assert.equal(worseMemoryFit("tight", "exceeds"), "exceeds");
});

test("neither surface loses a distinction it used to make", () => {
  assert.equal(classifyMemoryFit(21 * GIB, 24), "tight");
  assert.equal(
    toModelMemoryStatus({ verdict: "exceeds", cause: "context" }),
    "context-exceeds",
  );
  assert.equal(
    toModelMemoryStatus({ verdict: "exceeds", cause: "irreducible" }),
    "model-exceeds",
  );
});

test("tight folds into fits for the bar, which colours that band instead", () => {
  // The bar has no "tight" status; its pressure ramp expresses that band.
  assert.equal(toModelMemoryStatus({ verdict: "tight", cause: null }), "fits");
  assert.equal(toModelMemoryStatus({ verdict: "fits", cause: null }), "fits");
  assert.equal(toModelMemoryStatus({ verdict: "unknown", cause: null }), "unknown");
});

test("the bar's vocabulary round-trips, and is honest about what it loses", () => {
  for (const status of ["unknown", "fits", "context-exceeds", "model-exceeds"] as const) {
    assert.equal(toModelMemoryStatus(fromModelMemoryStatus(status)), status);
  }
  assert.equal(fromModelMemoryStatus("fits").verdict, "fits");
});

test("the Hub fit badge and the memory bar share one budget constant", async () => {
  // These render on the same row, so they must share one budget.
  const { VRAM_HEADROOM_RATIO } = await import("../src/lib/gguf-fit.ts");
  assert.equal(
    VRAM_HEADROOM_RATIO,
    DEFAULT_VRAM_BUDGET_FRACTION,
    "the badge and the bar are judging against different budgets again",
  );
});

test("aligning the constant narrows the badge/bar gap without closing it", async () => {
  // Residual disagreement is the estimator difference, which a shared constant cannot remove.
  const { classifyGgufFit, requiredGgufMemoryGb } = await import(
    "../src/lib/gguf-fit.ts"
  );
  const bytes = 20 * 1024 ** 3;
  assert.ok(
    requiredGgufMemoryGb(bytes) > 20,
    "the badge's heuristic no longer inflates, so this note is stale",
  );
  assert.notEqual(classifyGgufFit(bytes, { gpuGb: 24, systemRamGb: 64 }), "fits");
});

test("a saved VRAM Budget moves the badge, not only the bar", async () => {
  // The badge must use the user's saved fraction, as the bar beside it does.
  const { classifyGgufFit, requiredGgufMemoryGb } = await import(
    "../src/lib/gguf-fit.ts"
  );
  const bytes = 18 * 1024 ** 3;
  const required = requiredGgufMemoryGb(bytes);
  assert.ok(
    required > 24 * 0.9 && required <= 24 * DEFAULT_VRAM_BUDGET_FRACTION,
    `fixture must sit between the two budgets; required=${required}`,
  );
  assert.equal(
    classifyGgufFit(bytes, { gpuGb: 24, systemRamGb: 64, budgetFraction: 0.9 }),
    "marginal",
    "a saved 0.90 must push this over the line the loader draws",
  );
  assert.equal(
    classifyGgufFit(bytes, { gpuGb: 24, systemRamGb: 64 }),
    "fits",
    "and without a saved fraction the default still applies, unchanged",
  );
});

test("an absent or unusable budget falls back rather than refusing everything", async () => {
  // Absent budgetFraction (first paint, old backend) must mean the default, not 1 or 0.
  const { classifyGgufFit } = await import("../src/lib/gguf-fit.ts");
  const bytes = 18 * 1024 ** 3;
  const withDefault = classifyGgufFit(bytes, { gpuGb: 24, systemRamGb: 64 });
  for (const bad of [undefined, 0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
    assert.equal(
      classifyGgufFit(bytes, {
        gpuGb: 24,
        systemRamGb: 64,
        budgetFraction: bad as number,
      }),
      withDefault,
      `budgetFraction=${String(bad)} must fall back to the shared default`,
    );
  }
  assert.equal(
    classifyGgufFit(bytes, { gpuGb: 24, systemRamGb: 64, budgetFraction: 1 }),
    "fits",
  );
});

test("the badge's call sites read the live fraction", async () => {
  // Asserted on source because the .tsx call sites cannot render here.
  const card = readSrc("features/hub/catalog/gguf-download-card.tsx");
  assert.match(
    card,
    /useVramBudgetFraction\(\)/,
    "the Hub card must read the saved budget, not rely on the default",
  );
  // The sort uses the same classifier, so it must get the fraction too.
  const passes = card.match(/budgetFraction,/g) ?? [];
  assert.ok(
    passes.length >= 3,
    `expected the fraction at the badge, the sort and the menu; found ${passes.length}`,
  );
});

test("the offload band credits the budget, not the whole card", async () => {
  // Once layers spill, only the budgeted GPU share counts; driven at the legal minimum 0.80.
  const { classifyGgufFit, requiredGgufMemoryGb } = await import(
    "../src/lib/gguf-fit.ts"
  );
  const input = { gpuGb: 24, systemRamGb: 16, budgetFraction: 0.8 };
  for (const sizeGb of [23, 24, 25, 26]) {
    const bytes = sizeGb * 1024 ** 3;
    const required = requiredGgufMemoryGb(bytes);
    // Beyond what budget plus offloadable RAM can hold: 19.2 + 8 = 27.2.
    assert.ok(required > 27.2, `fixture ${sizeGb} must exceed the real ceiling`);
    assert.equal(
      classifyGgufFit(bytes, input),
      "oom",
      `a ${sizeGb} GiB quant needs ${required.toFixed(2)} GiB, and 0.80 of a ` +
        "24 GiB card plus half of 16 GiB of RAM cannot hold it",
    );
  }
});

test("marginal stays on the raw card, or the band cannot be reached", async () => {
  // Not scored against the budget, or this band would be dead code behind `fits`.
  const { classifyGgufFit } = await import("../src/lib/gguf-fit.ts");
  // 20 GiB needs 24.00 GiB: over 0.80 of the card (19.2) and exactly at the card.
  assert.equal(
    classifyGgufFit(20 * 1024 ** 3, {
      gpuGb: 24,
      systemRamGb: 16,
      budgetFraction: 0.8,
    }),
    "marginal",
    "a load between the budget and the card must still be reachable",
  );
});

test("every fit-scoring surface reads the saved budget, not just the Hub card", async () => {
  // The On Device card shows a bar and a classifyGgufFit-sorted menu; both need the fraction.
  for (const rel of [
    "features/hub/catalog/gguf-download-card.tsx",
    "features/hub/catalog/local-on-device-card.tsx",
  ]) {
    const source = readSrc(rel);
    assert.match(
      source,
      /useVramBudgetFraction\(\)/,
      `${rel} scores GGUF fit but does not read the saved VRAM Budget`,
    );
    assert.match(
      source,
      /budgetFraction,/,
      `${rel} reads the fraction but never passes it to the classifier`,
    );
  }
});

test("the budget read is shared, not one request per mounted card", async () => {
  // loadVramBudgetSettings has no cache, so a per-card call would GET once per card.
  const source = readSrc("hooks/use-vram-budget-fraction.ts");
  assert.match(
    source,
    /let cachedFraction/,
    "the fraction must be cached module-wide; it is one host-wide value",
  );
  assert.match(
    source,
    /let inFlight/,
    "cards mounting in the same tick must share one request",
  );
  assert.match(
    source,
    /routeAbsent/,
    "a 404 must be remembered, or every card retries a route that does not exist",
  );
  assert.match(
    source,
    /subscribeVramBudgetSettings\(\([\s\S]{0,200}?cachedFraction = settings\.fraction/,
    "the change event must refresh the cache, or a save never reaches the cards",
  );
});

test("a variant's fit counts the companions fetched with it", async () => {
  // Bartowski Muse Glimmer Q3_K_S: weights, projector, DFlash drafter; only the weights fit 16 GiB.
  const { classifyGgufVariantFit, ggufVariantFitSizeBytes } = await import(
    "../src/lib/gguf-fit.ts"
  );
  const weights = 12_789_199_648;
  const variant = {
    size_bytes: weights,
    download_size_bytes: weights + 3_849_173_920 + 1_451_094_176,
  };
  const budget = { gpuGb: 16, systemRamGb: 32 };

  assert.equal(ggufVariantFitSizeBytes(variant), variant.download_size_bytes);
  assert.equal(
    classifyGgufVariantFit({ size_bytes: weights }, budget),
    "fits",
    "the fixture only proves anything while the weights alone still fit",
  );
  assert.equal(classifyGgufVariantFit(variant, budget), "partial");
});

test("a total below the weights never lowers the estimate", async () => {
  // A positive-but-smaller total is the case a `??` or `||` fallback lets through.
  const { ggufVariantFitSizeBytes } = await import("../src/lib/gguf-fit.ts");
  const bytes = 12 * GIB;
  for (const download_size_bytes of [undefined, 0, bytes - 1, 1]) {
    assert.equal(
      ggufVariantFitSizeBytes({ size_bytes: bytes, download_size_bytes }),
      bytes,
      `a total of ${download_size_bytes} must not score below the weights`,
    );
  }
});