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.

Studio: show estimated context usage before model load (#9475)

Ayushmane347174f2365
diff --git a/studio/frontend/src/features/chat/chat-page.tsx b/studio/frontend/src/features/chat/chat-page.tsx
index 005d1aa5b25..203f5084d0a 100644
--- a/studio/frontend/src/features/chat/chat-page.tsx
+++ b/studio/frontend/src/features/chat/chat-page.tsx
@@ -282,6 +282,7 @@ import {
createAnnotationsFile,
} from "./utils/document-annotations";
import { requestTemporaryPromptQueueStop } from "./utils/prompt-queue-boundary";
+import { estimateContextUsage } from "./utils/estimate-chat-tokens";
import { isAssistantLocalThreadId } from "./utils/thread-ids";
import {
consumeProjectSourcesPending,
@@ -328,6 +329,31 @@ function getExternalProviderDropdownRank(providerType: string): number {
return EXTERNAL_PROVIDER_DROPDOWN_ORDER[providerType] ?? 2;
}
+type RuntimeStoreState = ReturnType<typeof useChatRuntimeStore.getState>;
+
+// The newest saved usage if the active checkpoint and window could have produced it, else null.
+function savedUsageFor(
+ messages: MessageRecord[],
+ store: RuntimeStoreState,
+): RuntimeStoreState["contextUsage"] {
+ const msg = [...messages].sort((a, b) => b.createdAt - a.createdAt)[0];
+ const usage = msg?.metadata?.contextUsage as RuntimeStoreState["contextUsage"];
+ if (!usage) return null;
+ const activeCheckpoint = store.params.checkpoint;
+ const usageModelId = (usage as { modelId?: unknown }).modelId;
+ if (typeof usageModelId === "string" && usageModelId) {
+ if (!activeCheckpoint || usageModelId !== activeCheckpoint) {
+ return null;
+ }
+ }
+ // llama.cpp stops at the window, so a count past it is stale; MLX runs past it, so its count stands.
+ const limit = store.loadedIsGguf ? store.loadedContextLength : null;
+ if (typeof limit === "number" && limit > 0 && (usage.totalTokens ?? 0) > limit) {
+ return null;
+ }
+ return usage;
+}
+
function messageHasImage(message: MessageRecord): boolean {
const contentParts = Array.isArray(message.content) ? message.content : [];
if (contentParts.some((part) => part.type === "image")) {
@@ -4107,44 +4133,14 @@ export function ChatPage({
}
viewBeforeCompareRef.current = null;
navigate({ to: "/chat", search: saved });
- // Restore usage from the last assistant message, only if it matches the active checkpoint, else
- // the relaxed render gate shows stale stats.
const threadId =
saved.thread ?? useChatRuntimeStore.getState().activeThreadId;
if (threadId) {
void listStoredChatMessages(threadId)
- .then(
- (messages) =>
- [...messages].sort((a, b) => b.createdAt - a.createdAt)[0],
- )
- .then((msg) => {
- const metadata = msg?.metadata as Record<string, unknown> | undefined;
- const usage = metadata?.contextUsage as ReturnType<
- typeof useChatRuntimeStore.getState
- >["contextUsage"];
- if (!usage) return;
+ .then((messages) => {
const store = useChatRuntimeStore.getState();
- const activeCheckpoint = store.params.checkpoint;
- const usageModelId = (usage as { modelId?: unknown }).modelId;
- // Scope by modelId when present; reject if no active checkpoint, since model-scoped usage cannot
- // be attributed to "nothing".
- if (typeof usageModelId === "string" && usageModelId) {
- if (!activeCheckpoint || usageModelId !== activeCheckpoint) {
- return;
- }
- }
- // For local turns, also require the restored count to fit in the active window. Skip when unknown
- // (external provider). llama.cpp only: it stops at the window, so a count past it is stale by definition.
- // MLX generates straight past instead, where an over-window count is the true one and the bar has a state
- // for it.
- const limit = store.loadedIsGguf ? store.loadedContextLength : null;
- if (
- typeof limit === "number" &&
- limit > 0 &&
- (usage.totalTokens ?? 0) > limit
- ) {
- return;
- }
+ const usage = savedUsageFor(messages, store) ?? estimateContextUsage(messages);
+ if (!usage) return;
// Key by the thread this restore read, like the history loader: the await above can outlast a
// switch away, and an unkeyed write would file this usage under the incoming thread.
store.setThreadContextUsage(threadId, usage);
@@ -4669,6 +4665,7 @@ export function ChatPage({
contextUnboundedWhenBatched={loadedContextUnboundedWhenBatched}
parallelSlots={loadedParallelSlots}
contextBudget={loadedContextBudget}
+ estimated={contextUsage?.estimated}
className="h-[var(--studio-chat-control-height,34px)]"
/>
) : null}
diff --git a/studio/frontend/src/features/chat/components/context-usage-bar.tsx b/studio/frontend/src/features/chat/components/context-usage-bar.tsx
index 0669195b776..fa04e2285d6 100644
--- a/studio/frontend/src/features/chat/components/context-usage-bar.tsx
+++ b/studio/frontend/src/features/chat/components/context-usage-bar.tsx
@@ -63,7 +63,9 @@ export const ContextUsageBar: FC<
const state = deriveContextUsageBar(input);
if (!state) return null;
- const { cached, cacheWrites, promptTokens, completionTokens } = input;
+ const { cached, cacheWrites, promptTokens, completionTokens } = input.estimated
+ ? {}
+ : input;
const { percent, advice, face, compactFace } = state;
const severity = getSeverityColor(percent ?? 0);
// Mono text, so widths are exact in ch. Full: padding, face, and the gap and bar. Compact: an icon button.
@@ -142,8 +144,11 @@ export const ContextUsageBar: FC<
<div className="grid min-w-44 gap-1.5 text-xs">
{percent !== null ? (
<div className="flex items-center justify-between gap-4">
- <span className="text-muted-foreground">Context usage</span>
+ <span className="text-muted-foreground">
+ {input.estimated ? "Estimated context usage" : "Context usage"}
+ </span>
<span className={cn("font-mono tabular-nums font-medium", severity.text)}>
+ {input.estimated ? "~" : ""}
{percent.toFixed(1)}%
</span>
</div>
@@ -187,6 +192,12 @@ export const ContextUsageBar: FC<
<span className="text-muted-foreground">{state.totalRowName}</span>
<span className="font-mono tabular-nums">{state.totalRowValue}</span>
</div>
+ {input.estimated ? (
+ <div className="mt-1 max-w-64 text-ui-11 leading-snug text-muted-foreground/90">
+ Estimated from the chat&apos;s text, without attachments. A
+ loaded model replaces it with an exact count.
+ </div>
+ ) : null}
{advice !== "none" ? (
<div className="mt-1 max-w-64 text-ui-11 leading-snug text-muted-foreground/90">
{advice === "mlx-past-limit" ? (
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 1165264ea26..fe16a91c4c8 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -762,7 +762,7 @@ async function syncInferenceStatusToStore(options?: {
// with a checkpoint already selected (an API load). Null thread guard: no empty count.
const hydrated = useChatRuntimeStore.getState();
if (
- hydrated.contextUsage == null &&
+ (hydrated.contextUsage == null || hydrated.contextUsage.estimated) &&
hydrated.activeThreadId != null &&
hydrated.loadedContextLength != null &&
!isExternalModelId(checkpointId)
diff --git a/studio/frontend/src/features/chat/lib/context-usage-bar-state.ts b/studio/frontend/src/features/chat/lib/context-usage-bar-state.ts
index 38d324c841f..ad814cb041d 100644
--- a/studio/frontend/src/features/chat/lib/context-usage-bar-state.ts
+++ b/studio/frontend/src/features/chat/lib/context-usage-bar-state.ts
@@ -30,6 +30,7 @@ export type ContextUsageBarInput = {
/** context_length_enforced as the load reported it; null where it does not answer. */
contextEnforced?: boolean | null;
contextBudget?: number | null;
+ estimated?: boolean;
};
/**
@@ -103,10 +104,39 @@ export function deriveContextUsageBar({
contextUnboundedWhenBatched,
parallelSlots,
contextBudget,
+ estimated,
}: ContextUsageBarInput): ContextUsageBarState | null {
const limit = typeof total === "number" && total > 0 ? total : null;
const usedTokens =
typeof used === "number" && Number.isFinite(used) ? used : null;
+
+ // no per-turn rows and no limit advice: neither is known from a guess
+ if (estimated && usedTokens !== null && usedTokens > 0) {
+ const approx = `~${formatTokenCount(usedTokens)}`;
+ const approxFull = `~${formatTokenCountFull(usedTokens)}`;
+ if (limit === null) {
+ return {
+ face: `${approx} tokens`,
+ compactFace: approx,
+ label: `Estimated context usage: ${approx} tokens`,
+ totalRowName: "Estimated tokens",
+ totalRowValue: approxFull,
+ percent: null,
+ hasUsageDetails: false,
+ advice: "none",
+ };
+ }
+ return {
+ face: `${approx} / ${formatTokenCount(limit)}`,
+ compactFace: null,
+ label: `Estimated context usage: ${approx} of ${formatTokenCount(limit)} tokens`,
+ totalRowName: "Estimated total",
+ totalRowValue: `${approxFull} / ${formatTokenCountFull(limit)}`,
+ percent: Math.min((usedTokens / limit) * 100, 100),
+ hasUsageDetails: false,
+ advice: "none",
+ };
+ }
const hasUsageDetails =
promptTokens !== undefined ||
completionTokens !== undefined ||
diff --git a/studio/frontend/src/features/chat/runtime-provider.tsx b/studio/frontend/src/features/chat/runtime-provider.tsx
index 1296bea686f..04856a48742 100644
--- a/studio/frontend/src/features/chat/runtime-provider.tsx
+++ b/studio/frontend/src/features/chat/runtime-provider.tsx
@@ -186,6 +186,7 @@ import {
} from "./utils/chat-attachment-events";
import { chatHistoryClearBoundary } from "./utils/chat-history-clear-boundary";
import { createParentResolver } from "./utils/message-order";
+import { estimateContextUsage } from "./utils/estimate-chat-tokens";
import {
awaitStoredChatThreadWrites,
deleteStoredChatThreads,
@@ -2693,12 +2694,13 @@ function useStudioRuntimeAdapters(
// The value, not a boolean: the writes below need the narrowing.
const restoredUsage =
savedUsage && withinLocalLimit && modelMatches ? savedUsage : null;
- if (restoredUsage) {
+ const shownUsage = restoredUsage ?? estimateContextUsage(msgs);
+ if (shownUsage) {
// Key by the thread this loader read, not whichever is active when the await resolves: a switch
// inside it would file this thread's usage under the incoming one.
- store.setThreadContextUsage(remoteId, restoredUsage);
+ store.setThreadContextUsage(remoteId, shownUsage);
if (store.activeThreadId === remoteId) {
- store.setContextUsage(restoredUsage);
+ store.setContextUsage(shownUsage);
}
}
// Only when nothing was restored: saved usage is the last completion's exact totals, and
@@ -3634,8 +3636,9 @@ function ThreadContextUsageRecount({
) {
return;
}
- // Only into a blank bar: restored or completion-written usage is exact, this is an estimate.
- if (useChatRuntimeStore.getState().contextUsage != null) return;
+ // Only into a blank or estimated bar: restored or completion-written usage is exact.
+ const shown = useChatRuntimeStore.getState().contextUsage;
+ if (shown != null && !shown.estimated) return;
void refreshContextUsage({ threadId: activeThreadId });
}, [
activeThreadId,
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index 2f42e67ca57..f7e8d50f6b7 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -2238,6 +2238,8 @@ type ContextUsageSnapshot = {
cachedTokens: number;
// Anthropic-only; optional so pre-cache-stats persisted entries load.
cacheWriteTokens?: number;
+ // a text-length guess from storage, replaced by any count
+ estimated?: boolean;
};
/** One live run behind `runningByThreadId[id]`, with the `local` flag it started with so the
diff --git a/studio/frontend/src/features/chat/utils/estimate-chat-tokens.ts b/studio/frontend/src/features/chat/utils/estimate-chat-tokens.ts
new file mode 100644
index 00000000000..4faf02870f2
--- /dev/null
+++ b/studio/frontend/src/features/chat/utils/estimate-chat-tokens.ts
@@ -0,0 +1,40 @@
+// 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 type { MessageRecord } from "../types";
+import { orderBySelectedBranch } from "./message-order.ts";
+
+export function estimateMessagesTokenCount(
+ records: readonly MessageRecord[] | null | undefined,
+): number | null {
+ if (!records || records.length === 0) return null;
+ let chars = 0;
+ for (const record of orderBySelectedBranch(records.slice())) {
+ const content = record.content as unknown;
+ if (typeof content === "string") {
+ chars += content.length;
+ continue;
+ }
+ if (!Array.isArray(content)) continue;
+ for (const part of content) {
+ const text = (part as { text?: unknown } | null)?.text;
+ if (typeof text === "string") chars += text.length;
+ }
+ }
+ return chars > 0 ? Math.max(1, Math.round(chars / 4)) : null;
+}
+
+// Text only, about 4 characters a token: shown until a loaded model counts the chat exactly.
+export function estimateContextUsage(
+ records: readonly MessageRecord[] | null | undefined,
+) {
+ const tokens = estimateMessagesTokenCount(records);
+ if (tokens === null) return null;
+ return {
+ promptTokens: tokens,
+ completionTokens: 0,
+ totalTokens: tokens,
+ cachedTokens: 0,
+ estimated: true,
+ };
+}
diff --git a/studio/frontend/tests/estimate-chat-tokens.test.ts b/studio/frontend/tests/estimate-chat-tokens.test.ts
new file mode 100644
index 00000000000..2de2a7d3b4c
--- /dev/null
+++ b/studio/frontend/tests/estimate-chat-tokens.test.ts
@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// #9330: a stored chat showed no context usage until a model was loaded to count it.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { deriveContextUsageBar } from "../src/features/chat/lib/context-usage-bar-state.ts";
+import type { MessageRecord } from "../src/features/chat/types.ts";
+import {
+ estimateContextUsage,
+ estimateMessagesTokenCount,
+} from "../src/features/chat/utils/estimate-chat-tokens.ts";
+
+function record(
+ id: string,
+ role: MessageRecord["role"],
+ text: string,
+ createdAt: number,
+ parentId?: string,
+): MessageRecord {
+ return {
+ id,
+ threadId: "t",
+ role,
+ content: [{ type: "text", text }] as MessageRecord["content"],
+ createdAt,
+ ...(parentId ? { parentId } : {}),
+ };
+}
+
+test("text length over four, at least one token", () => {
+ assert.equal(estimateMessagesTokenCount([record("1", "user", "a".repeat(3600), 1)]), 900);
+ assert.equal(estimateMessagesTokenCount([record("1", "user", "hi", 1)]), 1);
+});
+
+test("an empty or textless chat has no estimate", () => {
+ assert.equal(estimateMessagesTokenCount([]), null);
+ assert.equal(estimateMessagesTokenCount(null), null);
+ assert.equal(estimateContextUsage([record("1", "user", "", 1)]), null);
+});
+
+test("only the selected branch is counted", () => {
+ const messages = [
+ record("1", "user", "a".repeat(40), 100),
+ record("2", "assistant", "b".repeat(400), 200, "1"),
+ record("3", "assistant", "c".repeat(80), 300, "1"),
+ record("4", "user", "d".repeat(40), 400, "3"),
+ ];
+ assert.equal(estimateMessagesTokenCount(messages), 40);
+});
+
+test("the estimate is flagged so a count replaces it", () => {
+ assert.deepEqual(estimateContextUsage([record("1", "user", "a".repeat(400), 1)]), {
+ promptTokens: 100,
+ completionTokens: 0,
+ totalTokens: 100,
+ cachedTokens: 0,
+ estimated: true,
+ });
+});
+
+test("an estimate without a window reads as approximate tokens", () => {
+ const state = deriveContextUsageBar({
+ used: 4100,
+ total: null,
+ promptTokens: 4100,
+ completionTokens: 0,
+ estimated: true,
+ });
+ assert.ok(state);
+ assert.equal(state.face, "~4.1k tokens");
+ assert.equal(state.compactFace, "~4.1k");
+ assert.equal(state.totalRowValue, "~4,100");
+ assert.equal(state.percent, null);
+ assert.equal(state.hasUsageDetails, false);
+});
+
+test("an estimate against a window gives a ratio but no limit advice", () => {
+ const state = deriveContextUsageBar({ used: 30000, total: 32768, estimated: true });
+ assert.ok(state);
+ assert.equal(state.face, "~30.0k / 32.8k");
+ assert.equal(state.percent, (30000 / 32768) * 100);
+ assert.equal(state.advice, "none");
+ const exact = deriveContextUsageBar({ used: 30000, total: 32768 });
+ assert.equal(exact?.advice, "stops-at-limit");
+});