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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
// The backend caps progress at 0.99 until verifying against `expected_bytes`, which counts every
// repo file while training fetches a subset, so settling has to be decided here.
import assert from "node:assert/strict";
import test from "node:test";
import {
type DownloadProgressReading,
type DownloadState,
EMPTY_DOWNLOAD_STATE,
coerceCachedStateReady,
downloadStateFromProgress,
} from "../src/features/studio/download-state.ts";
const MB = 1e6;
const GB = 1e9;
function state(over: Partial<DownloadState> = {}): DownloadState {
return {
downloadedBytes: 0,
completedBytes: 0,
totalBytes: 0,
percent: 0,
cachePath: "/home/u/.cache/huggingface/hub/datasets--unsloth--alpaca-cleaned",
completeOnDisk: false,
settled: false,
moving: false,
...over,
};
}
function pollTwice(reading: DownloadProgressReading): DownloadState {
const first = downloadStateFromProgress(reading, EMPTY_DOWNLOAD_STATE);
return downloadStateFromProgress(reading, first);
}
test("a verified snapshot settles on the first reading", () => {
const verified = downloadStateFromProgress({
downloaded_bytes: 1.51 * GB,
completed_bytes: 1.51 * GB,
expected_bytes: 1.51 * GB,
progress: 1,
complete_on_disk: true,
cache_path: "/home/u/.cache/huggingface/hub/datasets--unsloth--LaTeX_OCR",
});
assert.equal(verified.percent, 100);
assert.equal(verified.settled, true);
});
test("a subset fetch settles once its bytes stop moving", () => {
// expected counts README/LICENSE/.gitattributes the trainer never fetches.
const reading: DownloadProgressReading = {
downloaded_bytes: 1_769_897_109,
completed_bytes: 1_769_897_109,
expected_bytes: 1_769_913_749,
progress: 0.99,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--Qwen--Qwen3.5-0.8B-Base",
};
assert.equal(downloadStateFromProgress(reading).settled, false);
assert.equal(pollTwice(reading).settled, true);
});
test("a settled subset fetch reports the bytes it actually holds", () => {
// Not `expected_bytes`: a dataset can ship configs load_dataset never fetches.
const settled = coerceCachedStateReady(
pollTwice({
downloaded_bytes: 14_002_749,
completed_bytes: 14_002_749,
expected_bytes: 28_059_770,
progress: 0.499,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/datasets--ryanmarten--OpenThoughts-1k-sample",
}),
);
assert.equal(settled.percent, 100);
assert.equal(settled.totalBytes, 14_002_749);
});
test("one quiet reading is not enough, because blobs finalize between files", () => {
// Between files downloaded == completed for a single tick.
const betweenFiles = downloadStateFromProgress({
downloaded_bytes: 5 * GB,
completed_bytes: 5 * GB,
expected_bytes: 20 * GB,
progress: 0.25,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--unsloth--gpt-oss-120b",
});
assert.equal(betweenFiles.settled, false);
assert.equal(coerceCachedStateReady(betweenFiles).percent, 25);
});
test("bytes in flight never settle, however long they sit", () => {
const resuming: DownloadProgressReading = {
downloaded_bytes: 20 * GB,
completed_bytes: 19.9 * GB,
expected_bytes: 20 * GB,
progress: 0.99,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--unsloth--gpt-oss-120b",
};
assert.equal(pollTwice(resuming).settled, false);
});
test("a growing download never settles", () => {
const first = downloadStateFromProgress({
downloaded_bytes: 5 * GB,
completed_bytes: 5 * GB,
expected_bytes: 20 * GB,
progress: 0.25,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--unsloth--gpt-oss-120b",
});
const second = downloadStateFromProgress(
{
downloaded_bytes: 6 * GB,
completed_bytes: 6 * GB,
expected_bytes: 20 * GB,
progress: 0.3,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--unsloth--gpt-oss-120b",
},
first,
);
assert.equal(second.settled, false);
});
test("a transfer that stalled and resumed stops reading as settled", () => {
// A slow multi-file download can go quiet for two polls, so settlement must not latch.
const reading: DownloadProgressReading = {
downloaded_bytes: 5 * GB,
completed_bytes: 5 * GB,
expected_bytes: 20 * GB,
progress: 0.25,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--unsloth--gpt-oss-120b",
};
const stalled = pollTwice(reading);
assert.equal(stalled.settled, true);
const resumed = downloadStateFromProgress(
{ ...reading, downloaded_bytes: 5.2 * GB, completed_bytes: 5 * GB, progress: 0.26 },
stalled,
);
assert.equal(resumed.settled, false);
assert.equal(coerceCachedStateReady(resumed).percent, 26);
});
test("a cache dir with bytes still expected is not ready", () => {
const empty = state({ downloadedBytes: 0, completedBytes: 0, totalBytes: 20 * GB });
assert.deepEqual(coerceCachedStateReady(empty), empty);
});
test("a resource with no cache path is never coerced", () => {
const uncached = state({
downloadedBytes: 42.3 * MB,
completedBytes: 42.3 * MB,
totalBytes: 42.3 * MB,
percent: 99,
cachePath: null,
settled: true,
});
assert.deepEqual(coerceCachedStateReady(uncached), uncached);
});
test("a cached entry of unknown size still settles instead of hanging", () => {
const unsized = coerceCachedStateReady(state());
assert.equal(unsized.percent, 100);
assert.equal(unsized.settled, true);
});
test("a response without complete_on_disk never settles on verification alone", () => {
// Older backend: a missing field must not read as truthy and settle an unverified row.
const legacy = {
downloaded_bytes: 400 * MB,
completed_bytes: 200 * MB,
expected_bytes: 20 * GB,
progress: 0.02,
cache_path: "/home/u/.cache/huggingface/hub/models--Qwen--Qwen3.5-0.8B-Base",
} as DownloadProgressReading;
const first = downloadStateFromProgress(legacy);
assert.equal(first.completeOnDisk, false);
assert.equal(first.settled, false);
assert.equal(downloadStateFromProgress(legacy, first).settled, false);
});
test("a stale reading cannot become the baseline the next poll settles against", () => {
// The poll is an interval, so a slow request can resolve after a newer one; a stale pair
// looks exactly like a quiet one.
const fresh: DownloadProgressReading = {
downloaded_bytes: 12 * GB,
completed_bytes: 12 * GB,
expected_bytes: 20 * GB,
progress: 0.6,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--Qwen--Qwen3.5-0.8B-Base",
};
const stale = { ...fresh, downloaded_bytes: 4 * GB, completed_bytes: 4 * GB, progress: 0.2 };
const settled = pollTwice(fresh);
assert.equal(settled.settled, true);
assert.equal(coerceCachedStateReady(settled).totalBytes, 12 * GB);
const afterStale = downloadStateFromProgress(stale, settled);
assert.equal(afterStale.settled, false);
assert.equal(downloadStateFromProgress(stale, afterStale).totalBytes, 20 * GB);
});
test("an orphaned .incomplete blob stops the transfer without ever settling", () => {
// A stray `.incomplete` blob in the raw hub cache means the row never settles, so preparation
// must not be gated on `!settled`.
const stuck: DownloadProgressReading = {
downloaded_bytes: 14.1 * MB,
completed_bytes: 13.4 * MB,
expected_bytes: 26.8 * MB,
progress: 0.52,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/datasets--unsloth--alpaca-cleaned",
};
const quiet = pollTwice(stuck);
assert.equal(quiet.settled, false, "an unfinalized blob is never settled");
assert.equal(quiet.moving, false, "but no bytes are moving, so preparation may show");
});
test("a live transfer keeps reporting movement", () => {
const first = downloadStateFromProgress({
downloaded_bytes: 4 * GB,
completed_bytes: 3 * GB,
expected_bytes: 20 * GB,
progress: 0.2,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--Qwen--Qwen3.5-0.8B-Base",
});
const second = downloadStateFromProgress(
{
downloaded_bytes: 6 * GB,
completed_bytes: 5 * GB,
expected_bytes: 20 * GB,
progress: 0.3,
complete_on_disk: false,
cache_path: "/home/u/.cache/huggingface/hub/models--Qwen--Qwen3.5-0.8B-Base",
},
first,
);
assert.equal(second.moving, true);
assert.equal(second.settled, false);
});
test("a verified snapshot is never reported as moving", () => {
// `complete_on_disk` stops the poll, so a `moving: true` on that reading would freeze forever.
const verified = downloadStateFromProgress({
downloaded_bytes: 1.51 * GB,
completed_bytes: 1.51 * GB,
expected_bytes: 1.51 * GB,
progress: 1,
complete_on_disk: true,
cache_path: "/home/u/.cache/huggingface/hub/models--Qwen--Qwen3.5-0.8B-Base",
});
assert.equal(verified.settled, true);
assert.equal(verified.moving, false, "verified means nothing is in flight");
});