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
import type { ModelCatalogResponse, ProviderModelCapabilityInfo } from "./api/providers-api";
import {
MODEL_CATALOG_SNAPSHOT,
type ModelCatalogSnapshotEntry,
} from "./model-catalog-snapshot.ts";
export type ReasoningEffortLevel =
| "none"
| "minimal"
| "low"
| "medium"
| "high"
| "xhigh"
| "max";
/** Weakest -> strongest. Keep in sync with _REASONING_EFFORT_SCALE in llama_cpp.py. */
export const REASONING_EFFORT_SCALE = [
"none",
"minimal",
"low",
"medium",
"high",
"xhigh",
"max",
] as const satisfies readonly ReasoningEffortLevel[];
export interface ModelCatalogEntry {
reasoning: boolean;
efforts: readonly ReasoningEffortLevel[];
mandatory: boolean;
defaultEffort: ReasoningEffortLevel | null;
inputModalities: readonly string[] | null;
maxOutputTokens: number | null;
contextLength: number | null;
}
interface LiveCatalogRecord {
fetchedAt: number;
models: Record<string, ModelCatalogEntry>;
}
const LIVE_CATALOG_KEY = "unsloth_chat_provider_model_catalog";
const LIVE_CATALOG = new Map<string, LiveCatalogRecord>();
let liveCatalogHydrated = false;
const MODELS_DEV_KEY = "unsloth_chat_models_dev_catalog";
let modelsDev: ModelCatalogResponse | null = null;
let modelsDevHydrated = false;
const catalogListeners = new Set<() => void>();
let catalogVersion = 0;
function notifyCatalogChange(): void {
catalogVersion += 1;
for (const listener of catalogListeners) listener();
}
export function subscribeModelCatalog(listener: () => void): () => void {
catalogListeners.add(listener);
return () => {
catalogListeners.delete(listener);
};
}
export function modelCatalogVersion(): number {
return catalogVersion;
}
function canUseStorage(): boolean {
return typeof window !== "undefined";
}
function isEffortLevel(value: unknown): value is ReasoningEffortLevel {
return (
typeof value === "string" &&
(REASONING_EFFORT_SCALE as readonly string[]).includes(value)
);
}
export function sortReasoningEfforts(
levels: Iterable<unknown>,
): ReasoningEffortLevel[] {
const known = new Set<ReasoningEffortLevel>();
for (const level of levels) {
if (isEffortLevel(level)) known.add(level);
}
return REASONING_EFFORT_SCALE.filter((level) => known.has(level));
}
function hydrateLiveCatalog(): void {
if (liveCatalogHydrated) return;
liveCatalogHydrated = true;
if (!canUseStorage()) return;
try {
const parsed = JSON.parse(
localStorage.getItem(LIVE_CATALOG_KEY) ?? "{}",
) as Record<string, LiveCatalogRecord>;
for (const [providerType, record] of Object.entries(parsed)) {
if (
record &&
typeof record === "object" &&
typeof record.fetchedAt === "number" &&
record.models &&
typeof record.models === "object"
) {
LIVE_CATALOG.set(providerType, record);
}
}
} catch {
// Invalid browser state; the next refresh rewrites it.
}
}
function persistLiveCatalog(): void {
if (!canUseStorage()) return;
try {
localStorage.setItem(
LIVE_CATALOG_KEY,
JSON.stringify(Object.fromEntries(LIVE_CATALOG)),
);
} catch {
// Storage failures leave the in-memory copy valid for this session.
}
}
function hydrateModelsDev(): void {
if (modelsDevHydrated) return;
modelsDevHydrated = true;
if (!canUseStorage()) return;
try {
const parsed = JSON.parse(localStorage.getItem(MODELS_DEV_KEY) ?? "null") as ModelCatalogResponse | null;
if (
parsed &&
typeof parsed === "object" &&
typeof parsed.fetched_at === "number" &&
parsed.providers &&
typeof parsed.providers === "object"
) {
modelsDev = parsed;
}
} catch {
// Invalid browser state; the next refresh rewrites it.
}
}
export function setModelsDevCatalog(catalog: ModelCatalogResponse): void {
hydrateModelsDev();
modelsDev = catalog;
nameIndex = null;
familyIndex = null;
mergedNamespaces = null;
notifyCatalogChange();
if (!canUseStorage()) return;
try {
localStorage.setItem(MODELS_DEV_KEY, JSON.stringify(catalog));
} catch {
// Storage failures leave the in-memory copy valid for this session.
}
}
export function modelsDevCatalogFetchedAt(): number | null {
hydrateModelsDev();
return modelsDev?.fetched_at ?? null;
}
let mergedNamespaces: Map<string, Readonly<Record<string, ModelCatalogSnapshotEntry>>> | null = null;
/** Codex serves OpenAI models under OpenAI ids, so it reuses that namespace. */
const CATALOG_NAMESPACE_ALIASES: Record<string, string> = {
openai_codex: "openai",
qwencloud: "qwen",
};
function catalogNamespace(providerType: string): string {
return CATALOG_NAMESPACE_ALIASES[providerType] ?? providerType;
}
function snapshotNamespace(
providerType: string,
): Readonly<Record<string, ModelCatalogSnapshotEntry>> | undefined {
providerType = catalogNamespace(providerType);
hydrateModelsDev();
const served = modelsDev?.providers[providerType];
const bundled = MODEL_CATALOG_SNAPSHOT[providerType];
if (!served) return bundled;
if (!bundled) return served;
// Merge per model so a stale cache cannot hide models the bundled snapshot knows.
if (!mergedNamespaces) mergedNamespaces = new Map();
const cached = mergedNamespaces.get(providerType);
if (cached) return cached;
const merged: Record<string, ModelCatalogSnapshotEntry> = { ...bundled };
for (const [id, entry] of Object.entries(served)) {
// Older backends lack the context field, so fall back to the bundled value.
const context = entry.context ?? bundled[id]?.context;
merged[id] = context == null ? entry : { ...entry, context };
}
mergedNamespaces.set(providerType, merged);
return merged;
}
function fromLiveModel(model: ProviderModelCapabilityInfo): ModelCatalogEntry {
const reasoning = model.reasoning ?? null;
const defaultEffort = reasoning?.default_effort;
return {
reasoning: reasoning != null,
efforts: sortReasoningEfforts(reasoning?.supported_efforts ?? []),
mandatory: reasoning?.mandatory === true,
defaultEffort: isEffortLevel(defaultEffort) ? defaultEffort : null,
inputModalities: Array.isArray(model.input_modalities)
? model.input_modalities
: null,
maxOutputTokens:
typeof model.max_output_tokens === "number" && model.max_output_tokens > 0
? model.max_output_tokens
: null,
contextLength: null,
};
}
function fromSnapshotEntry(entry: ModelCatalogSnapshotEntry): ModelCatalogEntry {
const reasoning = entry.reasoning === true;
const efforts = sortReasoningEfforts(entry.efforts ?? []);
return {
reasoning,
efforts,
mandatory:
reasoning && entry.toggle !== true && !efforts.includes("none"),
defaultEffort: null,
inputModalities: entry.input ?? null,
maxOutputTokens: null,
contextLength: entry.context ?? null,
};
}
export function setProviderModelCatalog(
providerType: string,
models: readonly ProviderModelCapabilityInfo[],
fetchedAt: number = Date.now(),
): void {
hydrateLiveCatalog();
const entries: Record<string, ModelCatalogEntry> = {};
for (const model of models) {
const id = model.id?.trim().toLowerCase();
if (id) entries[id] = fromLiveModel(model);
}
LIVE_CATALOG.set(providerType, { fetchedAt, models: entries });
persistLiveCatalog();
notifyCatalogChange();
}
export function clearProviderModelCatalog(providerType: string): void {
hydrateLiveCatalog();
if (!LIVE_CATALOG.delete(providerType)) return;
persistLiveCatalog();
notifyCatalogChange();
}
export function providerModelCatalogFetchedAt(providerType: string): number | null {
hydrateLiveCatalog();
return LIVE_CATALOG.get(providerType)?.fetchedAt ?? null;
}
function lookupCandidates(providerType: string, modelId: string): string[] {
const normalized = modelId.trim().toLowerCase();
if (!normalized) return [];
const candidates = [normalized];
if (providerType === "openrouter") {
const bare = normalized.startsWith("~") ? normalized.slice(1) : normalized;
if (bare !== normalized) candidates.push(bare);
const variant = bare.indexOf(":");
if (variant > 0) candidates.push(bare.slice(0, variant));
}
if (providerType === "ollama") {
const tag = normalized.indexOf(":");
if (tag > 0) candidates.push(normalized.slice(0, tag));
}
return candidates;
}
function findByBaseName(
models: Readonly<Record<string, unknown>>,
baseName: string,
): string | null {
for (const id of Object.keys(models)) {
const tag = id.indexOf(":");
if ((tag > 0 ? id.slice(0, tag) : id) === baseName) return id;
}
return null;
}
export function resolveModelCatalogEntry(
providerType: string | null | undefined,
modelId: string | null | undefined,
): ModelCatalogEntry | null {
if (!providerType || !modelId) return null;
const normalizedProvider = providerType.trim().toLowerCase();
const candidates = lookupCandidates(normalizedProvider, modelId);
if (candidates.length === 0) return null;
hydrateLiveCatalog();
const snapshot = snapshotNamespace(normalizedProvider);
const live = LIVE_CATALOG.get(normalizedProvider)?.models;
if (live) {
for (const candidate of candidates) {
const entry = live[candidate];
if (!entry) continue;
if (entry.contextLength != null || !snapshot) return entry;
const fallback = candidates
.map((id) => snapshot[id]?.context)
.find((context) => typeof context === "number" && context > 0);
return fallback == null ? entry : { ...entry, contextLength: fallback };
}
}
if (!snapshot) return null;
for (const candidate of candidates) {
const entry = snapshot[candidate];
if (entry) return fromSnapshotEntry(entry);
}
if (normalizedProvider === "ollama") {
// Ollama 400s a thinking request on an instruct-only tag.
if (modelId.toLowerCase().includes("instruct")) return null;
const match = findByBaseName(snapshot, candidates[candidates.length - 1]);
if (match) return fromSnapshotEntry(snapshot[match]);
return resolveModelCatalogEntryByName(modelId);
}
return null;
}
const NAME_INDEX_NAMESPACES = [
"openrouter",
"huggingface",
"lmstudio",
"ollama",
"openai",
"deepseek",
"qwen",
"kimi",
"mistral",
"gemini",
"anthropic",
];
let nameIndex: Map<string, ModelCatalogSnapshotEntry> | null = null;
let familyIndex: Map<string, ModelCatalogSnapshotEntry> | null = null;
function bareModelName(modelId: string): string {
let name = modelId.trim().toLowerCase();
name = name.split("/").at(-1) ?? name;
name = name.replace(/\.gguf$/, "");
const tag = name.indexOf(":");
if (tag > 0) name = name.slice(0, tag);
return name.replace(/-(?:ud-)?(?:i?q\d[a-z0-9_]*|f16|bf16|fp16|fp8)$/, "");
}
function modelFamily(bareName: string): string {
return bareName
.split("-")
.filter((part) => !/^(?:\d+(?:\.\d+)?[bm]|a\d+b)$/.test(part))
.join("-");
}
function buildNameIndexes(): void {
nameIndex = new Map();
familyIndex = new Map();
for (const namespace of NAME_INDEX_NAMESPACES) {
const models = snapshotNamespace(namespace);
if (!models) continue;
for (const [id, entry] of Object.entries(models)) {
const name = bareModelName(id);
if (!nameIndex.has(name)) nameIndex.set(name, entry);
const family = modelFamily(name);
if (family !== name && !familyIndex.has(family)) familyIndex.set(family, entry);
}
}
}
export function resolveModelCatalogEntryByName(
modelId: string | null | undefined,
): ModelCatalogEntry | null {
if (!modelId) return null;
if (!nameIndex || !familyIndex) buildNameIndexes();
const name = bareModelName(modelId);
const entry = nameIndex?.get(name) ?? familyIndex?.get(modelFamily(name));
return entry ? fromSnapshotEntry(entry) : null;
}
export function modelCatalogSupportsVision(
providerType: string | null | undefined,
modelId: string | null | undefined,
): boolean | null {
const modalities = resolveModelCatalogEntry(providerType, modelId)?.inputModalities;
if (!modalities) return null;
return modalities.includes("image");
}