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.

14.2 KB
Raw Blame
# 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)"
    )