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 forge from "node-forge";
import { authFetch } from "@/features/auth/api";
import { formatFastApiDetail } from "@/lib/format-fastapi-error";
import type { ModelCatalogSnapshotEntry } from "../model-catalog-snapshot";
import type { CustomReasoningConfig } from "../custom-reasoning";
export type ProviderAuthKind = "api_key" | "chatgpt_oauth";
export type ProviderAuthStatus =
| "disconnected"
| "connected"
| "reauthorization_required";
export interface ProviderRegistryEntry {
provider_type: string;
display_name: string;
base_url: string;
default_models: string[];
model_capabilities?: Record<string, { vision?: boolean; studio_tools?: boolean }>;
supports_streaming: boolean;
supports_vision: boolean;
supports_tool_calling: boolean;
/** Unsloth runs its own tool loop (search/code/MCP/RAG) against this provider. */
supports_studio_tools?: boolean;
/** Backend-only entry, surfaced through a custom preset rather than the dropdown. */
hidden?: boolean;
/** remote = fetch /models; curated = huge catalogs — UI uses defaults + manual IDs only */
model_list_mode?: "remote" | "curated";
auth_kind?: ProviderAuthKind;
base_url_editable?: boolean;
model_ids_editable?: boolean;
}
export type ProviderApiType = "chat_completions" | "responses";
export type ConnectionApiType = ProviderApiType | "systemone";
export interface ProviderConfig {
api_type?: ConnectionApiType;
id: string;
provider_type: string;
display_name: string;
base_url: string;
is_enabled: boolean;
has_api_key: boolean;
auth_kind?: ProviderAuthKind;
auth_status?: ProviderAuthStatus;
models?: string[];
available_models?: string[];
max_output_tokens?: number | null;
reasoning_config?: CustomReasoningConfig | null;
extra_headers?: Record<string, string>;
shared?: boolean;
shared_by_owner?: boolean;
created_at: string;
updated_at: string;
}
export interface ProviderModelInfo {
id: string;
display_name: string;
context_length?: number | null;
owned_by?: string | null;
/** Only the ChatGPT plan catalog reports this; the registry describes the rest. */
vision?: boolean | null;
/** Only Ollama's /api/tags reports these; absent is not the same as none. */
capabilities?: string[] | null;
}
export interface ProviderModelReasoningInfo {
supported_efforts?: string[] | null;
mandatory?: boolean | null;
default_effort?: string | null;
default_enabled?: boolean | null;
}
export interface ProviderModelCapabilityInfo {
id: string;
input_modalities?: string[] | null;
reasoning?: ProviderModelReasoningInfo | null;
max_output_tokens?: number | null;
supported_parameters?: string[] | null;
}
export interface ModelCatalogResponse {
fetched_at: number;
providers: Record<string, Record<string, ModelCatalogSnapshotEntry>>;
}
export interface ProviderTestResult {
success: boolean;
message: string;
models_count?: number | null;
}
function parseErrorText(status: number, body: unknown): string {
if (body && typeof body === "object") {
const detail = (body as { detail?: unknown }).detail;
const formatted = formatFastApiDetail(detail);
if (formatted) return formatted;
const message = (body as { message?: unknown }).message;
if (typeof message === "string" && message) return message;
}
return `Request failed (${status})`;
}
async function parseJsonOrThrow<T>(response: Response): Promise<T> {
const body = await response.json().catch(() => null);
if (!response.ok) {
throw new Error(parseErrorText(response.status, body));
}
return body as T;
}
export function isProviderKeyRotationError(error: unknown): boolean {
if (!(error instanceof Error)) return false;
const normalized = error.message.toLowerCase();
return (
normalized.includes("public key may have changed") ||
normalized.includes("server key may have changed")
);
}
// node-forge (~270 KB) loads with the first key encryption, not with the app.
function loadForge(): Promise<typeof forge> {
return import("node-forge").then((module) => module.default);
}
let cachedPublicKeyPem: string | null = null;
let cachedForgeKey: forge.pki.rsa.PublicKey | null = null;
export function clearProviderPublicKeyCache(): void {
cachedPublicKeyPem = null;
cachedForgeKey = null;
}
async function importProviderPublicKey(
forceRefresh = false,
): Promise<forge.pki.rsa.PublicKey> {
if (!forceRefresh && cachedForgeKey) {
return cachedForgeKey;
}
const response = await authFetch("/api/providers/public-key");
const body = await parseJsonOrThrow<{ public_key: string }>(response);
const publicKeyPem = body.public_key?.trim();
if (!publicKeyPem) {
throw new Error("Provider public key is missing.");
}
if (!forceRefresh && cachedPublicKeyPem === publicKeyPem && cachedForgeKey) {
return cachedForgeKey;
}
const { pki } = await loadForge();
const forgeKey = pki.publicKeyFromPem(publicKeyPem);
cachedPublicKeyPem = publicKeyPem;
cachedForgeKey = forgeKey;
return forgeKey;
}
const ENVELOPE_VERSION = "v1";
const ENVELOPE_AAD = "unsloth-studio-provider-key-v1";
const AES_KEY_BYTES = 32;
const NONCE_BYTES = 12;
function randomBinaryString(byteLength: number): string {
const bytes = new Uint8Array(byteLength);
crypto.getRandomValues(bytes);
return String.fromCharCode(...bytes);
}
/** RSA-OAEP wraps only the 32-byte content key: wrapping the API key itself caps it at 190 bytes. */
export async function encryptProviderApiKey(
plaintextApiKey: string,
forceRefresh = false,
): Promise<string> {
const key = await importProviderPublicKey(forceRefresh);
const forge = await loadForge();
const aesKey = randomBinaryString(AES_KEY_BYTES);
const nonce = randomBinaryString(NONCE_BYTES);
const cipher = forge.cipher.createCipher("AES-GCM", aesKey);
cipher.start({ iv: nonce, additionalData: ENVELOPE_AAD, tagLength: 128 });
// forge ciphers take bytes: without encodeUtf8 a non-ASCII key loses all but each low byte.
cipher.update(forge.util.createBuffer(forge.util.encodeUtf8(plaintextApiKey)));
if (!cipher.finish()) {
throw new Error("Failed to encrypt API key.");
}
const wrappedKey = key.encrypt(aesKey, "RSA-OAEP", {
md: forge.md.sha256.create(),
mgf1: { md: forge.md.sha256.create() },
});
return [
ENVELOPE_VERSION,
forge.util.encode64(wrappedKey),
forge.util.encode64(nonce),
forge.util.encode64(cipher.output.getBytes() + cipher.mode.tag.getBytes()),
].join(".");
}
export async function listProviderRegistry(): Promise<ProviderRegistryEntry[]> {
// include_hidden returns the self-hosted presets carrying the studio-tools capability; older
// backends ignore it, leaving the capability unknown.
const response = await authFetch(
"/api/providers/registry?include_hidden=true&include_oauth=true",
);
return parseJsonOrThrow<ProviderRegistryEntry[]>(response);
}
export async function listProviderConfigs(): Promise<ProviderConfig[]> {
const response = await authFetch("/api/providers/");
return parseJsonOrThrow<ProviderConfig[]>(response);
}
export async function createProviderConfig(payload: {
providerType: string;
displayName: string;
baseUrl?: string | null;
apiType?: ConnectionApiType;
models?: string[];
availableModels?: string[];
maxOutputTokens?: number | null;
reasoningConfig?: CustomReasoningConfig | null;
extraHeaders?: Record<string, string>;
shared?: boolean;
apiKey?: string;
}): Promise<ProviderConfig> {
return withApiKeyEncryptionRetry(payload.apiKey ?? "", async (encryptedApiKey) => {
const response = await authFetch("/api/providers/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
provider_type: payload.providerType,
display_name: payload.displayName,
base_url: payload.baseUrl ?? null,
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
models: payload.models ?? [],
available_models: payload.availableModels ?? [],
...(payload.maxOutputTokens === undefined
? {}
: { max_output_tokens: payload.maxOutputTokens }),
...(payload.reasoningConfig === undefined
? {}
: { reasoning_config: payload.reasoningConfig }),
...(payload.extraHeaders === undefined
? {}
: { extra_headers: payload.extraHeaders }),
...(payload.shared === undefined ? {} : { shared: payload.shared }),
encrypted_api_key: encryptedApiKey,
}),
});
return parseJsonOrThrow<ProviderConfig>(response);
});
}
export async function deleteProviderConfig(providerId: string): Promise<void> {
const response = await authFetch(`/api/providers/${providerId}`, {
method: "DELETE",
});
// 404 means another tab deleted it; prune the cache instead of throwing.
if (response.status === 404) {
return;
}
if (!response.ok) {
const body = await response.json().catch(() => null);
throw new Error(parseErrorText(response.status, body));
}
}
export async function updateProviderConfig(
providerId: string,
payload: {
displayName?: string;
baseUrl?: string | null;
apiType?: ConnectionApiType;
isEnabled?: boolean;
models?: string[];
availableModels?: string[];
maxOutputTokens?: number | null;
reasoningConfig?: CustomReasoningConfig | null;
extraHeaders?: Record<string, string>;
shared?: boolean;
apiKey?: string;
clearApiKey?: boolean;
},
): Promise<ProviderConfig> {
return withApiKeyEncryptionRetry(payload.apiKey ?? "", async (encryptedApiKey) => {
const response = await authFetch(`/api/providers/${providerId}`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
...(payload.displayName === undefined ? {} : { display_name: payload.displayName }),
...(payload.baseUrl === undefined ? {} : { base_url: payload.baseUrl }),
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
...(payload.isEnabled === undefined ? {} : { is_enabled: payload.isEnabled }),
...(payload.models === undefined ? {} : { models: payload.models }),
...(payload.availableModels === undefined
? {}
: { available_models: payload.availableModels }),
...(payload.maxOutputTokens === undefined
? {}
: { max_output_tokens: payload.maxOutputTokens }),
...(payload.reasoningConfig === undefined
? {}
: { reasoning_config: payload.reasoningConfig }),
...(payload.extraHeaders === undefined
? {}
: { extra_headers: payload.extraHeaders }),
...(payload.shared === undefined ? {} : { shared: payload.shared }),
...(payload.apiKey === undefined ? {} : { encrypted_api_key: encryptedApiKey }),
...(payload.clearApiKey === undefined ? {} : { clear_api_key: payload.clearApiKey }),
}),
});
return parseJsonOrThrow<ProviderConfig>(response);
});
}
export async function migrateProviderApiKey(
providerId: string,
apiKey: string,
): Promise<ProviderConfig> {
return withApiKeyEncryptionRetry(apiKey, async (encryptedApiKey) => {
const response = await authFetch(`/api/providers/${providerId}/api-key/migrate`, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ encrypted_api_key: encryptedApiKey }),
});
return parseJsonOrThrow<ProviderConfig>(response);
});
}
async function withApiKeyEncryptionRetry<T>(
plaintextApiKey: string,
call: (encryptedApiKey: string | null) => Promise<T>,
): Promise<T> {
// Empty key (local providers): skip RSA round-trip and let the backend omit auth.
if (!plaintextApiKey) {
return await call(null);
}
try {
const encrypted = await encryptProviderApiKey(plaintextApiKey, false);
return await call(encrypted);
} catch (error) {
if (!isProviderKeyRotationError(error)) {
throw error;
}
clearProviderPublicKeyCache();
const encrypted = await encryptProviderApiKey(plaintextApiKey, true);
return await call(encrypted);
}
}
export async function testProviderConnection(payload: {
providerType: string;
providerId?: string | null;
apiKey: string;
baseUrl?: string | null;
apiType?: ConnectionApiType;
extraHeaders?: Record<string, string>;
modelId?: string | null;
}): Promise<ProviderTestResult> {
return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
const response = await authFetch("/api/providers/test", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
provider_type: payload.providerType,
provider_id: payload.providerId ?? null,
encrypted_api_key: encryptedApiKey,
base_url: payload.baseUrl ?? null,
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
...(payload.extraHeaders === undefined
? {}
: { extra_headers: payload.extraHeaders }),
model_id: payload.modelId ?? null,
}),
});
return parseJsonOrThrow<ProviderTestResult>(response);
});
}
export async function listProviderModels(payload: {
providerType: string;
providerId?: string | null;
apiKey: string;
baseUrl?: string | null;
apiType?: ConnectionApiType;
extraHeaders?: Record<string, string>;
}): Promise<ProviderModelInfo[]> {
return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
const response = await authFetch("/api/providers/models", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
provider_type: payload.providerType,
provider_id: payload.providerId ?? null,
encrypted_api_key: encryptedApiKey,
base_url: payload.baseUrl ?? null,
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
...(payload.extraHeaders === undefined
? {}
: { extra_headers: payload.extraHeaders }),
}),
});
return parseJsonOrThrow<ProviderModelInfo[]>(response);
});
}
export async function fetchModelCatalog(): Promise<ModelCatalogResponse> {
const response = await authFetch("/api/providers/model-catalog");
return parseJsonOrThrow<ModelCatalogResponse>(response);
}
export async function listProviderModelCapabilities(payload: {
providerType: string;
providerId?: string | null;
apiKey: string;
baseUrl?: string | null;
apiType?: ProviderApiType;
}): Promise<ProviderModelCapabilityInfo[]> {
return withApiKeyEncryptionRetry(payload.apiKey, async (encryptedApiKey) => {
const response = await authFetch("/api/providers/model-capabilities", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
provider_type: payload.providerType,
provider_id: payload.providerId ?? null,
encrypted_api_key: encryptedApiKey,
base_url: payload.baseUrl ?? null,
...(payload.apiType === undefined ? {} : { api_type: payload.apiType }),
}),
});
return parseJsonOrThrow<ProviderModelCapabilityInfo[]>(response);
});
}
export interface CodexSubscriptionModels {
models: ProviderModelInfo[];
/** Every model the plan returned, offered or not: absent from this means the account cannot reach
* it, while present-but-unoffered only means it is no longer shown. */
known?: ProviderModelInfo[];
/** "reauthorization_required" is a curated answer that also says the connection has to be
* reconnected: the picker must not treat it as the plan's catalog. */
source: "subscription" | "curated" | "reauthorization_required";
}
export async function fetchCodexSubscriptionModels(
providerId: string,
options?: { refresh?: boolean },
): Promise<CodexSubscriptionModels> {
// An explicit reload asks about plan changes, so it must not be served from cache.
const query = options?.refresh ? "?refresh=true" : "";
const response = await authFetch(`/api/providers/${providerId}/codex/models${query}`);
return parseJsonOrThrow<CodexSubscriptionModels>(response);
}
export interface CodexOAuthFlow {
flow_id: string;
method: "browser" | "device";
status: "pending" | "connected" | "error" | "cancelled";
expires_at: number;
authorization_url?: string | null;
verification_url?: string | null;
user_code?: string | null;
message?: string | null;
}
export async function startCodexOAuth(
providerId: string,
method: "browser" | "device",
): Promise<CodexOAuthFlow> {
const response = await authFetch(`/api/providers/${providerId}/oauth/start`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ method }),
});
return parseJsonOrThrow<CodexOAuthFlow>(response);
}
export async function getCodexOAuthFlow(providerId: string, flowId: string): Promise<CodexOAuthFlow> {
const response = await authFetch(`/api/providers/${providerId}/oauth/flows/${flowId}`);
return parseJsonOrThrow<CodexOAuthFlow>(response);
}
export async function completeCodexOAuth(
providerId: string,
flowId: string,
callbackUrl: string,
): Promise<CodexOAuthFlow> {
const response = await authFetch(`/api/providers/${providerId}/oauth/flows/${flowId}/complete`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ callback_url: callbackUrl }),
});
return parseJsonOrThrow<CodexOAuthFlow>(response);
}
export async function cancelCodexOAuthFlow(
providerId: string,
flowId: string,
): Promise<void> {
const response = await authFetch(
`/api/providers/${providerId}/oauth/flows/${flowId}`,
{ method: "DELETE" },
);
if (!response.ok) {
const body = await response.json().catch(() => null);
throw new Error(parseErrorText(response.status, body));
}
}
export async function disconnectCodexOAuth(providerId: string): Promise<void> {
const response = await authFetch(`/api/providers/${providerId}/oauth`, { method: "DELETE" });
if (!response.ok) {
const body = await response.json().catch(() => null);
throw new Error(parseErrorText(response.status, body));
}
}