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
"""Pydantic schemas for the external LLM providers API."""
from __future__ import annotations
import re
from typing import Literal, Optional
from urllib.parse import quote
from pydantic import BaseModel, ConfigDict, Field, StrictBool, ValidationError, field_validator
ProviderApiType = Literal["chat_completions", "responses", "systemone"]
class ProviderReasoningConfig(BaseModel):
"""Explicit Custom Chat Completions wire dialect, never inferred from the URL."""
model_config = ConfigDict(extra = "forbid")
enabled: StrictBool
style: Literal[
"reasoning_effort", "reasoning", "thinking", "chat_template_kwargs.enable_thinking"
]
def normalize_provider_reasoning_config(value) -> Optional[dict]:
"""Treat absent or corrupt persisted/internal configuration as unconfigured."""
if isinstance(value, ProviderReasoningConfig):
value = value.model_dump()
try:
return ProviderReasoningConfig.model_validate(value).model_dump()
except (ValidationError, TypeError, ValueError):
return None
def validate_provider_reasoning_contract(provider_type: str, api_type: str, config) -> None:
if config is None:
return
if provider_type != "custom":
raise ValueError("reasoning_config is supported only for Custom connections.")
normalized = normalize_provider_reasoning_config(config)
if normalized and normalized["enabled"] and api_type != "chat_completions":
raise ValueError("Enabled Custom reasoning requires the Chat Completions API.")
MAX_JSON_SAFE_INTEGER = 9_007_199_254_740_991
_MAX_EXTRA_HEADERS = 16
_MAX_HEADER_NAME = 64
_MAX_HEADER_VALUE = 1024
_HEADER_NAME_RE = re.compile(r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$")
# httpx encodes header values as ASCII; anything else fails every request to the connection.
_HEADER_VALUE_RE = re.compile(r"^[\t\x20-\x7e]*$")
_HEADER_SAFE_CHARS = "".join(chr(c) for c in range(0x20, 0x7F) if chr(c) != "%")
_HEADER_TEMPLATE_RE = re.compile(r"\{\{\s*([A-Z][A-Z0-9_]*)\s*\}\}")
_FORBIDDEN_EXTRA_HEADERS = frozenset(
{
"authorization",
"proxy-authorization",
"cookie",
"set-cookie",
"host",
"content-length",
"content-type",
"connection",
"transfer-encoding",
"te",
"trailer",
"upgrade",
"keep-alive",
"api-key",
"x-api-key",
"x-goog-api-key",
}
)
def normalize_provider_extra_headers(value) -> dict[str, str]:
"""Validate a connection's extra headers. Empty or absent becomes {}."""
if value is None:
return {}
if not isinstance(value, dict):
raise ValueError("extra_headers must be an object of header name to value.")
if len(value) > _MAX_EXTRA_HEADERS:
raise ValueError(f"At most {_MAX_EXTRA_HEADERS} extra headers are allowed.")
headers: dict[str, str] = {}
for raw_name, raw_value in value.items():
if not isinstance(raw_name, str) or not isinstance(raw_value, str):
raise ValueError("extra_headers keys and values must be strings.")
name = raw_name.strip()
if not name or len(name) > _MAX_HEADER_NAME or not _HEADER_NAME_RE.fullmatch(name):
raise ValueError(f"Invalid extra header name: {raw_name!r}.")
if name.lower() in _FORBIDDEN_EXTRA_HEADERS:
raise ValueError(f"Cannot set reserved header {name!r}.")
if not _HEADER_VALUE_RE.fullmatch(raw_value):
raise ValueError(f"Header {name!r} must be printable ASCII on one line.")
if len(raw_value) > _MAX_HEADER_VALUE:
raise ValueError(f"Header {name!r} is too long.")
# h11 refuses a value with surrounding whitespace.
headers[name] = raw_value.strip(" \t")
return headers
def render_provider_extra_headers(
headers: dict[str, str] | None, variables: dict[str, str] | None = None
) -> dict[str, str]:
"""Replace ``{{ VAR }}`` placeholders. Unknown names become empty strings."""
if not headers:
return {}
values = variables or {}
def replace(match: re.Match[str]) -> str:
# Substituted ids and model names are arbitrary text; percent-encode what httpx cannot send.
return quote(values.get(match.group(1), ""), safe = _HEADER_SAFE_CHARS)
return {
name: _HEADER_TEMPLATE_RE.sub(replace, value).strip(" \t")
for name, value in headers.items()
}
class ProviderRegistryEntry(BaseModel):
"""A supported provider type with its default configuration."""
provider_type: str = Field(..., description = "Provider identifier (e.g. 'openai', 'mistral')")
display_name: str = Field(..., description = "Human-readable provider name")
base_url: str = Field(..., description = "Default API base URL")
default_models: list[str] = Field(
default_factory = list, description = "Well-known model IDs for this provider"
)
model_capabilities: dict[str, dict[str, bool]] = Field(default_factory = dict)
supports_streaming: bool = Field(
True, description = "Whether this provider supports SSE streaming"
)
supports_vision: bool = Field(
False, description = "Whether this provider supports vision/image input"
)
supports_tool_calling: bool = Field(
False, description = "Whether this provider supports tool/function calling"
)
supports_studio_tools: bool = Field(
False,
description = "Whether Unsloth runs its own tool loop (search/code/MCP/RAG) against this provider",
)
hidden: bool = Field(
False,
description = "Backend-only entry; the UI surfaces it via a custom preset, not the dropdown",
)
auth_kind: Literal["api_key", "chatgpt_oauth"] = "api_key"
base_url_editable: bool = True
model_ids_editable: bool = True
model_list_mode: Literal["remote", "curated"] = Field(
"remote",
description = "remote = fetch /models; curated = huge catalogs — UI uses defaults + manual IDs only",
)
class ExtraHeadersMixin(BaseModel):
extra_headers: Optional[dict[str, str]] = Field(
default = None,
description = "Optional request headers. Values may include {{CHAT_SESSION_ID}}.",
)
@field_validator("extra_headers", mode = "before")
@classmethod
def _validate_extra_headers(cls, value):
if value is None:
return None
return normalize_provider_extra_headers(value)
class ProviderCreate(ExtraHeadersMixin):
"""Request to create a saved provider configuration."""
api_type: ProviderApiType = "chat_completions"
reasoning_config: Optional[ProviderReasoningConfig] = None
provider_type: str = Field(..., description = "Provider type from the registry")
display_name: str = Field(..., description = "User-chosen label (e.g. 'My OpenAI Key')")
base_url: Optional[str] = Field(
None,
description = "Custom base URL (overrides registry default). Omit to use the default.",
)
models: list[str] = Field(
default_factory = list,
description = "Enabled model IDs for this connection",
)
available_models: list[str] = Field(
default_factory = list,
description = "Discovered catalog model IDs last fetched for this connection",
)
max_output_tokens: Optional[int] = Field(
None,
strict = True,
ge = 64,
le = MAX_JSON_SAFE_INTEGER,
description = "Optional maximum Max Tokens cap for this connection",
)
encrypted_api_key: Optional[str] = Field(
None,
description = "Optional RSA-encrypted API key to persist for this connection",
)
shared: bool = Field(
False,
description = "Let every account on this installation use this connection (owner only)",
)
class ProviderUpdate(ExtraHeadersMixin):
"""Request to update a saved provider configuration."""
api_type: Optional[ProviderApiType] = None
reasoning_config: Optional[ProviderReasoningConfig] = None
display_name: Optional[str] = Field(None, description = "New display name")
base_url: Optional[str] = Field(None, description = "New base URL")
is_enabled: Optional[bool] = Field(None, description = "Enable or disable this provider")
models: Optional[list[str]] = Field(None, description = "Enabled model IDs for this connection")
available_models: Optional[list[str]] = Field(
None,
description = "Discovered catalog model IDs last fetched for this connection",
)
max_output_tokens: Optional[int] = Field(
None,
strict = True,
ge = 64,
le = MAX_JSON_SAFE_INTEGER,
description = "Optional maximum Max Tokens cap for this connection",
)
encrypted_api_key: Optional[str] = Field(
None,
description = "Optional RSA-encrypted replacement API key; omission preserves the saved key",
)
clear_api_key: bool = Field(
False,
description = "Explicitly remove the saved API key",
)
shared: Optional[bool] = Field(
None,
description = "Let every account on this installation use this connection (owner only)",
)
class ProviderCredentialMigration(BaseModel):
"""One-time browser credential migration that never replaces a saved key."""
encrypted_api_key: str = Field(
...,
min_length = 1,
description = "RSA-encrypted legacy API key to insert only when no key exists",
)
class ProviderResponse(BaseModel):
"""A saved provider configuration (returned by list/get endpoints)."""
api_type: ProviderApiType = "chat_completions"
reasoning_config: Optional[ProviderReasoningConfig] = None
id: str = Field(..., description = "Unique provider config ID")
provider_type: str = Field(..., description = "Provider type (e.g. 'openai')")
display_name: str = Field(..., description = "User-chosen label")
base_url: str = Field(..., description = "API base URL")
is_enabled: bool = Field(True, description = "Whether this provider is enabled")
has_api_key: bool = Field(False, description = "Whether this caller has a saved API key")
auth_kind: Literal["api_key", "chatgpt_oauth"] = "api_key"
auth_status: Literal["disconnected", "connected", "reauthorization_required"] = "disconnected"
models: list[str] = Field(
default_factory = list,
description = "Enabled model IDs for this connection",
)
available_models: list[str] = Field(
default_factory = list,
description = "Discovered catalog model IDs last fetched for this connection",
)
max_output_tokens: Optional[int] = Field(
None,
description = "Configured maximum Max Tokens cap for this connection",
)
extra_headers: dict[str, str] = Field(
default_factory = dict,
description = "Optional request headers. Values may include {{CHAT_SESSION_ID}}.",
)
shared: bool = Field(False, description = "Whether every account on this installation can use it")
shared_by_owner: bool = Field(
False,
description = "The installation owner shared this connection; this account can use but not edit it",
)
created_at: str = Field(..., description = "ISO 8601 creation timestamp")
updated_at: str = Field(..., description = "ISO 8601 last-update timestamp")
class ProviderModelInfo(BaseModel):
"""A model available from an external provider."""
id: str = Field(..., description = "Model ID as expected by the provider API")
display_name: str = Field("", description = "Human-readable model name")
context_length: Optional[int] = Field(None, description = "Maximum context length in tokens")
owned_by: Optional[str] = Field(None, description = "Model owner/organization")
capabilities: Optional[list[str]] = Field(
None,
description = "Per-model capability names (Ollama /api/tags: thinking, tools, vision, ...)",
)
class ProviderModelReasoningInfo(BaseModel):
supported_efforts: Optional[list[str]] = None
mandatory: bool = False
default_effort: Optional[str] = None
default_enabled: Optional[bool] = None
class ProviderModelCapabilityInfo(BaseModel):
id: str
input_modalities: Optional[list[str]] = None
reasoning: Optional[ProviderModelReasoningInfo] = None
max_output_tokens: Optional[int] = None
supported_parameters: Optional[list[str]] = None
class ModelCatalogResponse(BaseModel):
fetched_at: float
providers: dict[str, dict[str, dict]]
class ProviderModelsRequest(ExtraHeadersMixin):
"""Request to list models from an external provider."""
api_type: ProviderApiType = "chat_completions"
provider_id: Optional[str] = Field(
None, description = "Saved provider config whose stored key may be used"
)
provider_type: str = Field(..., description = "Provider type from the registry")
encrypted_api_key: Optional[str] = Field(
None,
description = "RSA-encrypted, base64-encoded API key (optional for local providers)",
)
base_url: Optional[str] = Field(
None, description = "Custom base URL (overrides registry default)"
)
class ProviderTestRequest(ExtraHeadersMixin):
"""Request to test connectivity to an external provider."""
api_type: ProviderApiType = "chat_completions"
provider_id: Optional[str] = Field(
None, description = "Saved provider config whose stored key may be used"
)
provider_type: str = Field(..., description = "Provider type from the registry")
encrypted_api_key: Optional[str] = Field(
None,
description = "RSA-encrypted, base64-encoded API key (optional for local providers)",
)
base_url: Optional[str] = Field(
None, description = "Custom base URL (overrides registry default)"
)
model_id: Optional[str] = Field(
None, description = "Model ID for providers that need a chat probe"
)
class ProviderTestResult(BaseModel):
"""Result of a provider connectivity test."""
success: bool = Field(..., description = "Whether the test succeeded")
message: str = Field(..., description = "Human-readable result message")
models_count: Optional[int] = Field(
None, description = "Number of models found (if test succeeded)"
)