Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

60.5 KB
Raw Blame
"""Nanobot-style normalized runtime configuration for DeepTutor."""

from __future__ import annotations

from dataclasses import dataclass, field
import ipaddress
import json
from typing import Any
from urllib.parse import urlparse

from deeptutor.services.imagegen.config import ImagegenConfig
from deeptutor.services.keypool import primary_api_key
from deeptutor.services.model_selection import LLMSelection, apply_llm_selection_to_catalog
from deeptutor.services.provider_registry import (
    NANOBOT_LLM_PROVIDERS,
    PROVIDERS,
    ProviderSpec,
    api_format_for_provider,
    api_format_from_legacy,
    canonical_provider_name,
    find_by_model,
    find_by_name,
    find_gateway,
    wire_api_for_provider,
    wire_api_from_api_format,
)
from deeptutor.services.videogen.config import VideogenConfig
from deeptutor.services.voice.config import (
    AUTH_API_KEY_HEADER,
    AUTH_BEARER,
    STT_BASE64_JSON,
    STT_MULTIPART,
    STTConfig,
    TTSConfig,
    resolve_tts_request_timeout,
)

from .embedding_endpoint import (
    EMBEDDING_PROVIDER_ALIASES,
    EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS,
    dashscope_embedding_endpoint,
    embedding_endpoint_validation_error,
    gemini_default_embedding_endpoint,
    normalize_embedding_endpoint_for_display,
)
from .loader import load_config_with_main
from .model_catalog import (
    LLM_SHAPED_SERVICES,
    MODEL_CAPABILITY_KEYS,
    ModelCatalogService,
    get_model_catalog_service,
)
from .provider_links import resolve_profile_provider


@dataclass(frozen=True)
class SearchProviderSpec:
    """Single web-search-provider metadata entry.

    This table is the ONE place that decides what a search provider is: which
    connection fields it consumes (``requires_api_key`` / ``requires_base_url``),
    what happens when one is missing (``soft_fallback``), and whether it writes
    its own answer or needs :mod:`deeptutor.services.search.consolidation` to
    synthesize one (``supports_answer``).

    ``soft_fallback=False`` marks the paid providers: when their credentials are
    missing we raise instead of quietly running the query through a different
    search engine, so a configured-and-billed provider never turns into
    DuckDuckGo behind the user's back. It also marks the China-hosted providers,
    where the fallback is not merely surprising but unreachable — DuckDuckGo is
    blocked on the networks those are chosen for, so a silent fallback would
    turn "no API key" into a mystery timeout.

    The provider registry (``deeptutor/services/search/providers``), the
    Settings dropdown (``deeptutor/api/routers/settings.py``) and the web
    connection-field form all derive from this table — keep new providers here
    and they show up everywhere at once.
    """

    label: str
    requires_api_key: bool = False
    requires_base_url: bool = False
    soft_fallback: bool = True
    supports_answer: bool = False


# Insertion order is the Settings dropdown order.
SEARCH_PROVIDERS: dict[str, SearchProviderSpec] = {
    "none": SearchProviderSpec(label="None"),
    "brave": SearchProviderSpec(label="Brave", requires_api_key=True),
    "tavily": SearchProviderSpec(label="Tavily", requires_api_key=True, supports_answer=True),
    "jina": SearchProviderSpec(label="Jina", requires_api_key=True),
    "searxng": SearchProviderSpec(label="SearXNG", requires_base_url=True),
    "duckduckgo": SearchProviderSpec(label="DuckDuckGo"),
    "perplexity": SearchProviderSpec(
        label="Perplexity",
        requires_api_key=True,
        soft_fallback=False,
        supports_answer=True,
    ),
    "serper": SearchProviderSpec(label="Serper", requires_api_key=True, soft_fallback=False),
    "serply": SearchProviderSpec(label="Serply", requires_api_key=True, soft_fallback=False),
    "firecrawl": SearchProviderSpec(label="Firecrawl", requires_api_key=True, soft_fallback=False),
    # China-hosted engines. Doubao is the one that writes its own answer: Ark
    # exposes web search only as a tool on a Doubao model, never standalone.
    "doubao": SearchProviderSpec(
        label="Doubao",
        requires_api_key=True,
        soft_fallback=False,
        supports_answer=True,
    ),
    "bocha": SearchProviderSpec(label="Bocha", requires_api_key=True, soft_fallback=False),
    "zhipu": SearchProviderSpec(label="Zhipu", requires_api_key=True, soft_fallback=False),
    "qianfan": SearchProviderSpec(
        label="Baidu Qianfan", requires_api_key=True, soft_fallback=False
    ),
    "aliyun_iqs": SearchProviderSpec(
        label="Aliyun IQS", requires_api_key=True, soft_fallback=False
    ),
}

# The credential-free provider every soft fallback lands on.
SEARCH_FALLBACK_PROVIDER = "duckduckgo"

SUPPORTED_SEARCH_PROVIDERS = frozenset(SEARCH_PROVIDERS)
DEPRECATED_SEARCH_PROVIDERS = frozenset({"exa", "baidu", "openrouter"})


def search_provider_spec(provider: str | None) -> SearchProviderSpec | None:
    """Look up a provider's spec, or ``None`` for unknown/deprecated names."""
    return SEARCH_PROVIDERS.get((provider or "").strip().lower())


def supported_search_providers_hint() -> str:
    """Human-readable provider list for error messages and CLI output."""
    return ", ".join(name for name in SEARCH_PROVIDERS if name != "none")


LLM_LOCALHOST_PROVIDERS = ("ollama", "vllm")


@dataclass(frozen=True)
class EmbeddingProviderSpec:
    """Single embedding-provider metadata entry.

    Note on `default_api_base`: as of v1.3.0 this is the **fully-qualified
    embedding endpoint URL** (e.g. ``https://api.openai.com/v1/embeddings``),
    not a base. Adapters use the configured URL verbatim — no path appending.
    """

    label: str
    default_api_base: str
    keywords: tuple[str, ...]
    is_local: bool
    adapter: str = "openai_compat"
    mode: str = "standard"
    default_model: str = ""
    default_dim: int = 0
    # Per-provider cap on items per embedding request batch. Adapters/clients
    # clamp `batch_size` against this. SiliconFlow Qwen3 family caps at 32;
    # DashScope caps at 20; most others have generous limits.
    max_batch_items: int = 256
    # Whether the active default model supports multimodal `contents` input.
    multimodal: bool = False


EMBEDDING_PROVIDERS: dict[str, EmbeddingProviderSpec] = {
    "openai": EmbeddingProviderSpec(
        label="OpenAI",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["openai"],
        keywords=("openai", "text-embedding", "ada-002", "embedding-3"),
        is_local=False,
        default_model="text-embedding-3-large",
        default_dim=3072,
    ),
    "gemini": EmbeddingProviderSpec(
        label="Gemini",
        adapter="gemini",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["gemini"],
        keywords=("gemini", "gemini-embedding", "text-embedding"),
        is_local=False,
        default_model="gemini-embedding-2",
        default_dim=3072,
    ),
    "azure_openai": EmbeddingProviderSpec(
        label="Azure OpenAI",
        mode="direct",
        default_api_base="",
        keywords=("azure", "aoai"),
        is_local=False,
    ),
    "cohere": EmbeddingProviderSpec(
        label="Cohere",
        adapter="cohere",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["cohere"],
        keywords=("cohere", "embed-v4", "embed-english", "embed-multilingual"),
        is_local=False,
        default_model="embed-v4.0",
        default_dim=1024,
        multimodal=True,
    ),
    "jina": EmbeddingProviderSpec(
        label="Jina",
        adapter="jina",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["jina"],
        keywords=("jina", "jina-embeddings"),
        is_local=False,
        default_model="jina-embeddings-v3",
        default_dim=1024,
    ),
    "ollama": EmbeddingProviderSpec(
        label="Ollama",
        adapter="ollama",
        mode="local",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["ollama"],
        keywords=("ollama", "nomic-embed", "mxbai", "snowflake-arctic", "all-minilm"),
        is_local=True,
        default_model="nomic-embed-text",
        default_dim=768,
    ),
    "vllm": EmbeddingProviderSpec(
        label="vLLM / LM Studio",
        mode="local",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["vllm"],
        keywords=("vllm", "lmstudio"),
        is_local=True,
    ),
    "lemonade": EmbeddingProviderSpec(
        label="Lemonade Server",
        mode="local",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["lemonade"],
        keywords=("lemonade",),
        is_local=True,
    ),
    "siliconflow": EmbeddingProviderSpec(
        label="SiliconFlow",
        adapter="openai_compat",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["siliconflow"],
        keywords=(
            "siliconflow",
            "qwen3-embedding",
            "qwen3-vl-embedding",
            "bge-m3",
            "Pro/BAAI",
        ),
        is_local=False,
        default_model="Qwen/Qwen3-Embedding-8B",
        default_dim=4096,
        max_batch_items=32,
        multimodal=True,
    ),
    "aliyun": EmbeddingProviderSpec(
        label="Aliyun DashScope",
        adapter="dashscope_native",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["aliyun"],
        keywords=("dashscope", "qwen3-vl-embedding", "qwen3-embedding", "aliyun", "bailian"),
        is_local=False,
        default_model="qwen3-vl-embedding",
        default_dim=2560,
        max_batch_items=20,
        multimodal=True,
    ),
    "custom": EmbeddingProviderSpec(
        label="OpenAI Compatible",
        mode="direct",
        default_api_base="",
        keywords=(),
        is_local=False,
    ),
    # Retained for legacy configs only. Public Settings providers use exact
    # endpoint URLs and raw HTTP adapters so no request path is hidden.
    "custom_openai_sdk": EmbeddingProviderSpec(
        label="Custom (OpenAI SDK)",
        adapter="openai_sdk",
        mode="direct",
        default_api_base="",
        keywords=(),
        is_local=False,
    ),
    "openrouter": EmbeddingProviderSpec(
        label="OpenRouter",
        adapter="openai_compat",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["openrouter"],
        keywords=("openrouter",),
        is_local=False,
    ),
    "opper": EmbeddingProviderSpec(
        label="Opper",
        adapter="openai_compat",
        default_api_base=EMBEDDING_PROVIDER_DEFAULT_ENDPOINTS["opper"],
        keywords=("opper",),
        is_local=False,
        default_model="openai/text-embedding-3-large",
        default_dim=3072,
    ),
}


@dataclass(frozen=True)
class VoiceProviderSpec:
    """Metadata for one TTS or STT provider entry.

    ``default_api_base`` is the provider's **API base** (e.g.
    ``https://api.openai.com/v1``); the voice adapter appends ``/audio/speech``
    or ``/audio/transcriptions``. ``adapter`` selects the HTTP adapter; the
    OpenAI-compatible cluster all share ``openai_compat`` and differ only by
    ``auth_style`` (Azure uses ``api-key``) and STT ``request_style``
    (OpenRouter uses base64-JSON).
    """

    label: str
    default_api_base: str
    adapter: str = "openai_compat"
    auth_style: str = AUTH_BEARER
    default_model: str = ""
    default_voice: str = ""  # TTS only
    request_style: str = STT_MULTIPART  # STT only
    is_local: bool = False


# Voice providers either use the shared OpenAI-compatible adapter or a native
# protocol adapter registered by name (DashScope and Volcengine Speech TTS/STT).
TTS_PROVIDERS: dict[str, VoiceProviderSpec] = {
    "xiaomi_mimo": VoiceProviderSpec(
        label="Xiaomi MiMo",
        default_api_base="https://api.xiaomimimo.com/v1",
        adapter="mimo_tts",
        default_model="mimo-v2.5-tts",
    ),
    "minimax": VoiceProviderSpec(
        label="MiniMax",
        default_api_base="https://api.minimax.io/v1",
        adapter="minimax",
        default_model="speech-2.8-hd",
    ),
    "volcengine_speech": VoiceProviderSpec(
        label="Volcengine Speech (Doubao)",
        default_api_base="https://openspeech.bytedance.com/api/v3",
        adapter="volcengine",
        default_model="seed-tts-2.0",
    ),
    "dashscope": VoiceProviderSpec(
        label="Aliyun DashScope",
        default_api_base="https://dashscope.aliyuncs.com/api/v1",
        adapter="dashscope",
        default_model="qwen3-tts-flash",
    ),
    "openai": VoiceProviderSpec(
        label="OpenAI",
        default_api_base="https://api.openai.com/v1",
        default_model="gpt-4o-mini-tts",
    ),
    # Gemini TTS only speaks the native generateContent audio API, never the
    # OpenAI-compatible /audio/speech endpoint, so it gets its own adapter.
    "gemini": VoiceProviderSpec(
        label="Google Gemini",
        default_api_base="https://generativelanguage.googleapis.com/v1beta",
        adapter="gemini",
        default_model="gemini-2.5-flash-preview-tts",
    ),
    "openrouter": VoiceProviderSpec(
        label="OpenRouter",
        default_api_base="https://openrouter.ai/api/v1",
        adapter="openrouter_tts",
        default_model="openai/gpt-4o-mini-tts",
    ),
    "groq": VoiceProviderSpec(
        label="Groq",
        default_api_base="https://api.groq.com/openai/v1",
        default_model="canopylabs/orpheus-v1-english",
    ),
    "siliconflow": VoiceProviderSpec(
        label="SiliconFlow",
        default_api_base="https://api.siliconflow.cn/v1",
        default_model="FunAudioLLM/CosyVoice2-0.5B",
    ),
    "azure_openai": VoiceProviderSpec(
        label="Azure OpenAI",
        default_api_base="",
        auth_style=AUTH_API_KEY_HEADER,
        default_model="tts-1",
    ),
    "vllm": VoiceProviderSpec(
        label="vLLM / Local",
        default_api_base="http://localhost:8000/v1",
        default_model="",
        is_local=True,
    ),
    "custom": VoiceProviderSpec(
        label="OpenAI Compatible",
        default_api_base="",
        default_model="",
    ),
    # Edge's free read-aloud voices via the edge-tts package; no key, no endpoint.
    "edge": VoiceProviderSpec(
        label="Microsoft Edge (free)",
        default_api_base="",
        adapter="edge",
        default_model="edge-tts",
        default_voice="zh-CN-XiaoxiaoNeural",
        is_local=True,
    ),
}

STT_PROVIDERS: dict[str, VoiceProviderSpec] = {
    "volcengine_speech": VoiceProviderSpec(
        label="Volcengine Speech (Doubao)",
        default_api_base="https://openspeech.bytedance.com/api/v3",
        adapter="volcengine",
        default_model="bigmodel",
    ),
    # DashScope's native adapter speaks the Paraformer real-time WebSocket API,
    # which only accepts `paraformer-realtime-*` ids. `paraformer-v2` is a batch
    # transcription id and the handshake fails with "Model not found".
    "dashscope": VoiceProviderSpec(
        label="Aliyun DashScope",
        default_api_base="https://dashscope.aliyuncs.com/api/v1",
        adapter="dashscope",
        default_model="paraformer-realtime-v2",
    ),
    "openai": VoiceProviderSpec(
        label="OpenAI",
        default_api_base="https://api.openai.com/v1",
        default_model="gpt-4o-mini-transcribe",
    ),
    "openrouter": VoiceProviderSpec(
        label="OpenRouter",
        default_api_base="https://openrouter.ai/api/v1",
        default_model="openai/whisper-large-v3",
        request_style=STT_BASE64_JSON,
    ),
    "groq": VoiceProviderSpec(
        label="Groq",
        default_api_base="https://api.groq.com/openai/v1",
        default_model="whisper-large-v3-turbo",
    ),
    "siliconflow": VoiceProviderSpec(
        label="SiliconFlow",
        default_api_base="https://api.siliconflow.cn/v1",
        default_model="FunAudioLLM/SenseVoiceSmall",
    ),
    "azure_openai": VoiceProviderSpec(
        label="Azure OpenAI",
        default_api_base="",
        auth_style=AUTH_API_KEY_HEADER,
        default_model="whisper-1",
    ),
    "vllm": VoiceProviderSpec(
        label="vLLM / Local",
        default_api_base="http://localhost:8000/v1",
        default_model="",
        is_local=True,
    ),
    "custom": VoiceProviderSpec(
        label="OpenAI Compatible",
        default_api_base="",
        default_model="",
    ),
}

# Provider-name aliases accepted from older/loose catalog values.
VOICE_PROVIDER_ALIASES = {
    "volcengine": "volcengine_speech",
    "doubao": "volcengine_speech",
    "aliyun": "dashscope",
    "bailian": "dashscope",
    "azure": "azure_openai",
    "aoai": "azure_openai",
    "openai_compatible": "custom",
    "lmstudio": "vllm",
}


def _canonical_voice_provider(name: str | None, table: dict[str, VoiceProviderSpec]) -> str:
    key = (name or "").strip().lower().replace("-", "_")
    key = VOICE_PROVIDER_ALIASES.get(key, key)
    return key if key in table else "custom"


@dataclass(frozen=True)
class GenerationProviderSpec:
    """Metadata for one image- or video-generation provider entry.

    ``default_api_base`` is the provider's **API base** (e.g.
    ``https://api.openai.com/v1`` or ``https://ark.cn-beijing.volces.com/api/v3``);
    the adapter appends the relative path (``images/generations`` or
    ``contents/generations/tasks``). ``adapter`` selects the HTTP adapter:
    imagegen providers share ``openai_compat``; videogen task-style providers
    use ``async_task``.
    """

    label: str
    default_api_base: str
    adapter: str = "openai_compat"
    auth_style: str = AUTH_BEARER
    default_model: str = ""
    is_local: bool = False


# Image-generation providers in the OpenAI-compatible cluster. A single adapter
# covers all of these; ``default_model`` is only a Settings prefill hint.
IMAGEGEN_PROVIDERS: dict[str, GenerationProviderSpec] = {
    "dashscope": GenerationProviderSpec(
        label="Aliyun DashScope",
        default_api_base="https://dashscope.aliyuncs.com/api/v1",
        adapter="dashscope",
        default_model="wanx2.1-t2i-turbo",
    ),
    "openai": GenerationProviderSpec(
        label="OpenAI",
        default_api_base="https://api.openai.com/v1",
        default_model="gpt-image-1",
    ),
    "volcengine": GenerationProviderSpec(
        label="Volcengine Ark (Seedream)",
        default_api_base="https://ark.cn-beijing.volces.com/api/v3",
        default_model="doubao-seedream-3-0-t2i-250415",
    ),
    "siliconflow": GenerationProviderSpec(
        label="SiliconFlow",
        default_api_base="https://api.siliconflow.cn/v1",
        default_model="Kwai-Kolors/Kolors",
    ),
    # OpenRouter generates images through /chat/completions (modalities), not the
    # OpenAI Images API — so it uses the chat_completions adapter, not openai_compat.
    "openrouter": GenerationProviderSpec(
        label="OpenRouter",
        default_api_base="https://openrouter.ai/api/v1",
        adapter="chat_completions",
        default_model="google/gemini-2.5-flash-image-preview",
    ),
    "azure_openai": GenerationProviderSpec(
        label="Azure OpenAI",
        default_api_base="",
        auth_style=AUTH_API_KEY_HEADER,
        default_model="dall-e-3",
    ),
    "custom": GenerationProviderSpec(
        label="OpenAI Compatible",
        default_api_base="",
        default_model="",
    ),
    # Generic chat-completions image output (any OpenRouter-style gateway).
    "custom_chat": GenerationProviderSpec(
        label="Chat Completions (Custom)",
        default_api_base="",
        adapter="chat_completions",
        default_model="",
    ),
}

# Video-generation providers. Text-to-video has no synchronous standard; these
# all use the async-task adapter (submit → poll → download).
VIDEOGEN_PROVIDERS: dict[str, GenerationProviderSpec] = {
    "dashscope": GenerationProviderSpec(
        label="Aliyun DashScope",
        default_api_base="https://dashscope.aliyuncs.com/api/v1",
        adapter="dashscope",
        default_model="wanx2.1-t2v-turbo",
    ),
    "volcengine": GenerationProviderSpec(
        label="Volcengine Ark (Seedance)",
        default_api_base="https://ark.cn-beijing.volces.com/api/v3",
        adapter="async_task",
        default_model="doubao-seedance-1-0-pro-250528",
    ),
    "custom": GenerationProviderSpec(
        label="Async Task (Custom)",
        default_api_base="",
        adapter="async_task",
        default_model="",
    ),
}

# Provider-name aliases accepted from older/loose catalog values.
GENERATION_PROVIDER_ALIASES = {
    "aliyun": "dashscope",
    "bailian": "dashscope",
    "ark": "volcengine",
    "volces": "volcengine",
    "doubao": "volcengine",
    "seedream": "volcengine",
    "seedance": "volcengine",
    "azure": "azure_openai",
    "aoai": "azure_openai",
    "openai_compatible": "custom",
}


def _canonical_generation_provider(
    name: str | None, table: dict[str, GenerationProviderSpec]
) -> str:
    key = (name or "").strip().lower().replace("-", "_")
    key = GENERATION_PROVIDER_ALIASES.get(key, key)
    return key if key in table else "custom"


@dataclass(slots=True)
class NormalizedProviderConfig:
    """Normalized provider configuration input."""

    name: str
    api_key: str | list[str] = ""
    api_base: str | None = None
    api_version: str | None = None
    extra_headers: dict[str, str] | None = None


@dataclass(slots=True)
class ResolvedLLMConfig:
    """Resolved runtime LLM config used by get_llm_config/factory."""

    model: str
    provider_name: str
    provider_mode: str
    binding_hint: str | None = None
    binding: str = "openai"
    api_key: str | list[str] = ""
    base_url: str | None = None
    effective_url: str | None = None
    api_version: str | None = None
    extra_headers: dict[str, str] = field(default_factory=dict)
    wire_api: str = "auto"
    api_format: str = "auto"
    reasoning_effort: str | None = None
    context_window: int | None = None
    # The active model's explicit capability overrides (see MODEL_CAPABILITY_KEYS).
    capabilities: dict[str, bool] = field(default_factory=dict)


@dataclass(slots=True)
class ResolvedEmbeddingConfig:
    """Resolved runtime embedding config."""

    model: str
    provider_name: str
    provider_mode: str
    binding_hint: str | None = None
    binding: str = "openai"
    api_key: str | list[str] = ""
    base_url: str | None = None
    effective_url: str | None = None
    api_version: str | None = None
    extra_headers: dict[str, str] = field(default_factory=dict)
    dimension: int = 0
    send_dimensions: bool | None = None
    request_timeout: int = 60
    batch_size: int = 10
    batch_delay: float = 0.0


@dataclass(slots=True)
class ResolvedSearchConfig:
    """Resolved runtime web-search config."""

    provider: str
    requested_provider: str
    api_key: str = ""
    base_url: str = ""
    max_results: int = 5
    proxy: str | None = None
    unsupported_provider: bool = False
    deprecated_provider: bool = False
    missing_credentials: bool = False
    fallback_reason: str | None = None

    @property
    def status(self) -> str:
        if self.unsupported_provider:
            return "unsupported"
        if self.deprecated_provider:
            return "deprecated"
        if self.missing_credentials:
            return "missing_credentials"
        if self.fallback_reason:
            return "fallback"
        return "ok"


def _as_str(value: Any) -> str:
    return str(value).strip() if value is not None else ""


def _as_api_key(value: Any) -> str | list[str]:
    if isinstance(value, list):
        return [key for item in value if (key := _as_str(item))]
    return _as_str(value)


def _to_headers(value: Any) -> dict[str, str]:
    if isinstance(value, dict):
        return {str(k): str(v) for k, v in value.items() if str(k).strip() and v is not None}
    if isinstance(value, str) and value.strip():
        try:
            parsed = json.loads(value)
        except json.JSONDecodeError:
            return {}
        if isinstance(parsed, dict):
            return {str(k): str(v) for k, v in parsed.items() if str(k).strip() and v is not None}
    return {}


def _is_local_base_url(base_url: str | None) -> bool:
    if not base_url:
        return False
    try:
        parsed = urlparse(base_url if "://" in base_url else f"http://{base_url}")
    except Exception:
        return False
    host = (parsed.hostname or "").lower()
    return host in {"localhost", "127.0.0.1", "::1"} or host.endswith(".local")


def _load_catalog(catalog: dict[str, Any] | None) -> dict[str, Any]:
    if catalog is not None:
        return catalog
    return get_model_catalog_service().load()


def _with_personal_llm_profiles(catalog: dict[str, Any]) -> dict[str, Any]:
    """Add the current owner's own owner-bound LLM profiles to *catalog*.

    An ordinary user's Codex profile lives in their own catalog rather than
    the shared one (see :mod:`deeptutor.multi_user.personal_models`), so
    resolving a personal selection against the shared catalog alone would
    fail to find the profile it names. Imported lazily and guarded: the LLM
    layer must keep resolving in contexts where multi-user state is absent
    (CLI, tests, background jobs).
    """
    try:
        from deeptutor.multi_user.personal_models import merge_personal_llm_profiles

        return merge_personal_llm_profiles(catalog)
    except Exception:
        return catalog


def _model_capabilities(model: dict[str, Any] | None) -> dict[str, bool]:
    raw = (model or {}).get("capabilities")
    if not isinstance(raw, dict):
        return {}
    return {key: bool(raw[key]) for key in MODEL_CAPABILITY_KEYS if isinstance(raw.get(key), bool)}


def _register_catalog_capabilities(catalog: dict[str, Any]) -> None:
    """Publish every model's explicit capability overrides to the LLM tables.

    Runs on each resolution so an override removed in Settings stops applying
    without a restart. Imported lazily: ``deeptutor.services.llm`` imports this
    module for its config, so a module-level import would close a cycle.
    """
    from deeptutor.services.llm.capabilities import set_catalog_capability_overrides

    entries: list[tuple[str, str, dict[str, bool]]] = []
    for service_name in LLM_SHAPED_SERVICES:
        service = catalog.get("services", {}).get(service_name, {})
        for profile in service.get("profiles", []) or []:
            if not isinstance(profile, dict):
                continue
            binding = canonical_provider_name(_as_str(profile.get("binding"))) or ""
            for model in profile.get("models", []) or []:
                if not isinstance(model, dict):
                    continue
                effective = resolve_profile_provider(catalog, service_name, profile, model)
                binding = canonical_provider_name(_as_str(effective.get("binding"))) or ""
                overrides = _model_capabilities(model)
                if overrides:
                    entries.append((binding, _as_str(model.get("model")), overrides))
    set_catalog_capability_overrides(entries)


def _active_profile_and_model(
    catalog: dict[str, Any],
    service: ModelCatalogService,
    service_name: str,
) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
    profile = service.get_active_profile(catalog, service_name)
    model = service.get_active_model(catalog, service_name)
    return profile, model


def _collect_provider_pool(catalog: dict[str, Any]) -> dict[str, NormalizedProviderConfig]:
    providers: dict[str, NormalizedProviderConfig] = {}
    llm_profiles = catalog.get("services", {}).get("llm", {}).get("profiles", [])
    for raw in llm_profiles:
        profile = resolve_profile_provider(
            catalog, "llm", raw, next(iter(raw.get("models", [])), None)
        )
        name = canonical_provider_name(_as_str(profile.get("binding")))
        if not name:
            continue
        providers[name] = NormalizedProviderConfig(
            name=name,
            api_key=_as_api_key(profile.get("api_key")),
            api_base=_as_str(profile.get("base_url")) or None,
            api_version=_as_str(profile.get("api_version")) or None,
            extra_headers=_to_headers(profile.get("extra_headers")) or None,
        )
    return providers


def _choose_resolved_provider(
    *,
    hint: str | None,
    model: str,
    api_key: str | list[str],
    api_base: str | None,
    provider_pool: dict[str, NormalizedProviderConfig],
) -> ProviderSpec:
    explicit_spec = find_by_name(hint) if hint else None
    detected_gateway = find_gateway(
        provider_name=None,
        api_key=primary_api_key(api_key),
        api_base=api_base or None,
    )
    # Keep backward compatibility: old `binding=openai` should not block
    # gateway detection when key/base clearly indicates a gateway provider.
    if explicit_spec and detected_gateway and explicit_spec.name == "openai":
        return detected_gateway
    if explicit_spec:
        return explicit_spec
    if detected_gateway:
        return detected_gateway

    model_spec = find_by_model(model)
    if model_spec:
        return model_spec

    if _is_local_base_url(api_base):
        if api_base and "11434" in api_base:
            return find_by_name("ollama") or find_by_name("vllm") or find_by_name("openai")
        return find_by_name("vllm") or find_by_name("ollama") or find_by_name("openai")

    for spec in PROVIDERS:
        configured = provider_pool.get(spec.name)
        if not configured:
            continue
        if spec.is_gateway and (configured.api_key or configured.api_base):
            return spec
    for spec in PROVIDERS:
        configured = provider_pool.get(spec.name)
        if not configured:
            continue
        if spec.is_local and configured.api_base:
            return spec
        if not spec.is_oauth and configured.api_key:
            return spec

    return find_by_name("openai") or PROVIDERS[0]


def resolve_llm_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
    llm_selection: dict[str, Any] | LLMSelection | None = None,
    service_name: str = "llm",
) -> ResolvedLLMConfig:
    """Resolve active LLM config with TutorBot-style provider matching.

    ``service_name`` selects which catalog service supplies the profile and
    model. It is ``llm`` for everything the user drives; the ``task`` service
    is the same shape and stands in for it on the calls DeepTutor makes on its
    own. The provider pool it falls back to stays the LLM one either way —
    a task profile that names a bare model still resolves against the
    credentials configured for chat.
    """
    catalog_service = service or get_model_catalog_service()
    loaded = _with_personal_llm_profiles(_load_catalog(catalog))
    # Parse the payload once: ``apply_llm_selection_to_catalog`` would otherwise
    # re-parse it, so a malformed selection would be validated (and rejected)
    # from two places. ``from_payload`` is idempotent on an already-parsed value.
    if service_name == "task" and llm_selection is None:
        task = loaded.get("services", {}).get("task", {})
        if task.get("mode") == "reference":
            llm_selection = task.get("selection")
            if not llm_selection:
                raise ValueError("Choose a task model from a configured provider.")
            service_name = "llm"
        elif task.get("mode") == "inherit":
            service_name = "llm"
    selection = LLMSelection.from_payload(llm_selection)
    loaded = apply_llm_selection_to_catalog(loaded, selection)

    profile, model = _active_profile_and_model(loaded, catalog_service, service_name)
    resolved_model = _as_str((model or {}).get("model"))

    binding_hint_raw = _as_str((profile or {}).get("binding"))
    binding_hint = canonical_provider_name(binding_hint_raw)

    active_api_key = _as_api_key((profile or {}).get("api_key"))
    active_api_base = _as_str((profile or {}).get("base_url"))
    active_api_version = _as_str((profile or {}).get("api_version"))
    configured_wire_api = _as_str((profile or {}).get("wire_api")) or "auto"
    configured_api_format = (profile or {}).get("api_format")
    reasoning_effort = _as_str((model or {}).get("reasoning_effort")) or None
    # Per-conversation override (#641): an explicit reasoning_effort on the
    # caller's LLMSelection takes precedence over the profile/model default
    # resolved above. The model/global config value stays the fallback when
    # no override is present, preserving today's behavior.
    if selection is not None and selection.reasoning_effort:
        reasoning_effort = selection.reasoning_effort
    active_extra_headers = _to_headers((profile or {}).get("extra_headers"))
    context_window = _coerce_optional_int((model or {}).get("context_window"))
    if context_window is None:
        context_window = _coerce_optional_int((model or {}).get("context_window_tokens"))

    # Old diagnostics allowed users to adopt a guessed budget as model capacity.
    # Preserve manual/provider values, but retire those explicitly marked fallback.
    if (model or {}).get("context_window_source") == "default":
        context_window = None

    provider_pool = _collect_provider_pool(loaded)
    spec = _choose_resolved_provider(
        hint=binding_hint,
        model=resolved_model,
        api_key=active_api_key,
        api_base=active_api_base or None,
        provider_pool=provider_pool,
    )

    # Profiles written before ``api_format`` existed carry only ``wire_api``.
    # Settle the protocol before choosing its vendor-specific default address.
    if configured_api_format is None:
        api_format = api_format_from_legacy(spec, configured_wire_api)
    else:
        api_format = api_format_for_provider(configured_api_format, spec)
    wire_api = wire_api_for_provider(wire_api_from_api_format(api_format), spec)

    mapped = (
        None
        if (profile or {}).get("provider_ref") or (model or {}).get("provider_ref")
        else provider_pool.get(spec.name)
    )
    api_key = active_api_key or (mapped.api_key if mapped else "")
    api_base = active_api_base or ((mapped.api_base or "") if mapped else "")
    api_version = active_api_version or ((mapped.api_version or "") if mapped else "")
    if not api_base:
        api_base = spec.default_api_base_for(api_format)
    if not api_key and spec.is_local:
        api_key = "sk-no-key-required"
    extra_headers = active_extra_headers or ((mapped.extra_headers or {}) if mapped else {})
    _register_catalog_capabilities(loaded)

    return ResolvedLLMConfig(
        model=resolved_model,
        provider_name=spec.name,
        provider_mode=spec.mode,
        binding_hint=binding_hint,
        binding=spec.name,
        api_key=api_key,
        base_url=api_base or None,
        effective_url=api_base or None,
        api_version=api_version or None,
        extra_headers=extra_headers,
        wire_api=wire_api,
        api_format=api_format,
        reasoning_effort=reasoning_effort,
        context_window=context_window,
        capabilities=_model_capabilities(model),
    )


def _canonical_embedding_provider_name(name: str | None) -> str | None:
    if not name:
        return None
    key = name.strip().replace("-", "_")
    if not key:
        return None
    key = EMBEDDING_PROVIDER_ALIASES.get(key, key)
    key = canonical_provider_name(key) or key
    key = EMBEDDING_PROVIDER_ALIASES.get(key, key)
    if key in EMBEDDING_PROVIDERS:
        return key
    return None


def _collect_embedding_provider_pool(
    catalog: dict[str, Any],
) -> dict[str, NormalizedProviderConfig]:
    providers: dict[str, NormalizedProviderConfig] = {}
    embedding_profiles = catalog.get("services", {}).get("embedding", {}).get("profiles", [])
    for raw in embedding_profiles:
        profile = resolve_profile_provider(
            catalog, "embedding", raw, next(iter(raw.get("models", [])), None)
        )
        name = _canonical_embedding_provider_name(_as_str(profile.get("binding")))
        if not name:
            continue
        providers[name] = NormalizedProviderConfig(
            name=name,
            api_key=_as_api_key(profile.get("api_key")),
            api_base=_as_str(profile.get("base_url")) or None,
            api_version=_as_str(profile.get("api_version")) or None,
            extra_headers=_to_headers(profile.get("extra_headers")) or None,
        )
    return providers


def _resolve_embedding_dimension(value: Any, default: int = 0) -> int:
    """Parse the dimension value. Returns 0 when unknown/unparseable.

    A value of 0 means "use the provider's native default" downstream;
    test_runner auto-fills the catalog with the actual response dim on
    first successful connection test.
    """
    try:
        parsed = int(str(value).strip())
    except (TypeError, ValueError):
        return default
    if parsed <= 0:
        return default
    return parsed


def _coerce_optional_bool(value: Any) -> bool | None:
    """Parse a tri-state bool from catalog values.

    Returns ``True``/``False`` for explicit values and ``None`` for missing,
    empty, or unrecognised inputs (which means "use the default behaviour").
    """
    if value is None:
        return None
    if isinstance(value, bool):
        return value
    text = str(value).strip().lower()
    if not text:
        return None
    if text in {"true", "1", "yes", "on"}:
        return True
    if text in {"false", "0", "no", "off"}:
        return False
    return None


def _coerce_optional_int(value: Any) -> int | None:
    """Parse a positive int from catalog values, returning ``None`` when unset."""
    if value is None:
        return None
    try:
        parsed = int(str(value).strip())
    except (TypeError, ValueError):
        return None
    return parsed if parsed > 0 else None


def _is_nonpublic_embedding_host(hostname: str) -> bool:
    """Loopback, LAN, and container names that are not a public vendor host."""
    host = hostname.lower().strip("[]").rstrip(".")
    if not host:
        return False
    if host in {
        "localhost",
        "127.0.0.1",
        "::1",
        "lemonade",
        "host.docker.internal",
        "gateway.docker.internal",
    }:
        return True
    if host.endswith(".local") or host.endswith(".internal"):
        return True
    # Docker Compose service names are a single DNS label.
    if "." not in host:
        return True
    try:
        address = ipaddress.ip_address(host)
    except ValueError:
        return False
    return bool(address.is_private or address.is_loopback or address.is_link_local)


def _is_legacy_lemonade_endpoint(api_base: str) -> bool:
    """Keyless Lemonade servers saved as a generic OpenAI-compatible URL.

    Unraid and Docker installs often point at a LAN address or
    ``host.docker.internal`` and store the chat root (``/api/v1``) rather than
    the embeddings path. Those still have to resolve as local Lemonade, or
    knowledge-base creation demands an API key the server does not use (#1782).
    A public host on the same port stays a remote OpenAI-compatible endpoint.
    """
    try:
        endpoint = urlparse(api_base if "://" in api_base else f"http://{api_base}")
        if endpoint.port != 13305:
            return False
    except ValueError:
        return False
    if not _is_nonpublic_embedding_host(endpoint.hostname or ""):
        return False
    path = endpoint.path.rstrip("/")
    return path.endswith(("/embeddings", "/v1")) or path in {"", "/"}


def _resolve_embedding_provider(
    *,
    hint: str | None,
    model: str,
    api_base: str | None,
    provider_pool: dict[str, NormalizedProviderConfig],
) -> str:
    if api_base and _is_legacy_lemonade_endpoint(api_base) and hint in {None, "custom", "openai"}:
        # Older keyless Lemonade profiles were saved as generic OpenAI
        # Compatible embeddings. Recognize that endpoint before a Qwen3 model
        # name is mistaken for a remote embedding vendor (#1568, #1782).
        return "lemonade"

    if _is_local_base_url(api_base) and hint in {None, "custom", "openai"}:
        # Ollama also serves OpenAI-compatible embeddings on /v1/embeddings.
        # Select the wire protocol by path, not by a port substring.
        endpoint = urlparse(api_base if "://" in api_base else f"http://{api_base}")
        path = endpoint.path.rstrip("/")
        try:
            native_root = not path and endpoint.port == 11434
        except ValueError:
            native_root = False
        if path in {"/api/embed", "/api/embeddings"} or native_root:
            return "ollama"
        return "vllm"

    if hint and hint in EMBEDDING_PROVIDERS:
        return hint

    model_lower = (model or "").lower()
    model_prefix = model_lower.split("/", 1)[0].replace("-", "_") if "/" in model_lower else ""
    if model_prefix in EMBEDDING_PROVIDERS:
        return model_prefix

    for provider_name, spec in EMBEDDING_PROVIDERS.items():
        if any(keyword in model_lower for keyword in spec.keywords):
            return provider_name

    for provider_name, spec in EMBEDDING_PROVIDERS.items():
        configured = provider_pool.get(provider_name)
        if not configured:
            continue
        if spec.is_local and configured.api_base:
            return provider_name
        if configured.api_key:
            return provider_name

    return "openai"


def resolve_embedding_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> ResolvedEmbeddingConfig:
    """Resolve active embedding config using provider-runtime normalization."""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    profile, model = _active_profile_and_model(loaded, catalog_service, "embedding")
    resolved_model = _as_str((model or {}).get("model"))
    if not resolved_model:
        raise ValueError(
            "No active embedding model is configured. Set it in Settings > Embedding models."
        )

    binding_hint_raw = _as_str((profile or {}).get("binding"))
    binding_hint = _canonical_embedding_provider_name(binding_hint_raw)

    active_api_key = _as_api_key((profile or {}).get("api_key"))
    active_api_base = _as_str((profile or {}).get("base_url"))
    active_api_version = _as_str((profile or {}).get("api_version"))
    active_extra_headers = _to_headers((profile or {}).get("extra_headers"))
    # Default 0 means "not yet known" — the test_runner auto-fills on first
    # successful connection. Adapters/clients should treat 0 as "let the
    # provider use its native default". 3072 used to be hard-coded here, which
    # forced every non-OpenAI provider to fail dim validation on first use.
    dimension = _resolve_embedding_dimension((model or {}).get("dimension") or 0, default=0)
    # ``None`` means "fall back to adapter heuristic".
    send_dimensions = _coerce_optional_bool((model or {}).get("send_dimensions"))

    provider_pool = _collect_embedding_provider_pool(loaded)
    provider_name = _resolve_embedding_provider(
        hint=binding_hint,
        model=resolved_model,
        api_base=active_api_base or None,
        provider_pool=provider_pool,
    )
    spec = EMBEDDING_PROVIDERS[provider_name]
    mapped = (
        None
        if (profile or {}).get("provider_ref") or (model or {}).get("provider_ref")
        else provider_pool.get(provider_name)
    )

    api_key = active_api_key or (mapped.api_key if mapped else "")
    api_base = active_api_base or ((mapped.api_base or "") if mapped else "")
    if not api_base:
        if provider_name == "gemini":
            # Gemini's native endpoint embeds the selected model in the path,
            # and only Embedding 2 defaults to it — see
            # gemini_default_embedding_endpoint for why 001 stays where it was.
            api_base = gemini_default_embedding_endpoint(resolved_model)
        elif spec.default_api_base:
            api_base = spec.default_api_base
    if provider_name == "lemonade" and api_base:
        # Chat-root URLs such as ``/api/v1`` are what Settings saves for an
        # OpenAI-compatible Lemonade connection. Embedding calls need the
        # ``/embeddings`` path or the client rejects them after the key check.
        api_base = normalize_embedding_endpoint_for_display("lemonade", api_base)
    if provider_name == "aliyun":
        # DashScope's SDK derives the endpoint from the model id and ignores any
        # configured URL, so a saved multimodal endpoint would mislead the
        # diagnostic for a text model (issue #660). Surface the true per-model
        # endpoint the SDK will actually POST to.
        api_base = dashscope_embedding_endpoint(resolved_model)
    api_version = active_api_version or ((mapped.api_version or "") if mapped else "")
    extra_headers = active_extra_headers or ((mapped.extra_headers or {}) if mapped else {})

    return ResolvedEmbeddingConfig(
        model=resolved_model,
        provider_name=provider_name,
        provider_mode=spec.mode,
        binding_hint=binding_hint,
        binding=provider_name,
        api_key=api_key,
        base_url=api_base or None,
        effective_url=api_base or None,
        api_version=api_version or None,
        extra_headers=extra_headers,
        dimension=dimension,
        send_dimensions=send_dimensions,
        request_timeout=60,
        # Some providers (e.g. Volcengine Ark plan tier) enforce very low RPM limits;
        # allow per-profile batch_size/batch_delay in the embedding profile, defaults unchanged
        batch_size=_clamp_batch_size(profile),
        batch_delay=_clamp_batch_delay(profile),
    )


def _coerce_optional_float(value: Any) -> float | None:
    """Parse a positive float from catalog values, returning ``None`` when unset."""
    if value is None or (isinstance(value, str) and not value.strip()):
        return None
    try:
        parsed = float(str(value).strip())
    except (TypeError, ValueError):
        return None
    return parsed if parsed > 0 else None


def resolve_tts_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> TTSConfig:
    """Resolve the active text-to-speech config from the model catalog."""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    profile, model = _active_profile_and_model(loaded, catalog_service, "tts")
    resolved_model = _as_str((model or {}).get("model"))
    if not resolved_model:
        raise ValueError("No active TTS model is configured. Set it in Settings > Voice.")

    provider = _canonical_voice_provider(_as_str((profile or {}).get("binding")), TTS_PROVIDERS)
    spec = TTS_PROVIDERS[provider]
    api_base = _as_str((profile or {}).get("base_url")) or spec.default_api_base
    api_key = _as_str((profile or {}).get("api_key"))
    if not api_key and spec.is_local:
        api_key = "sk-no-key-required"
    from deeptutor.services.voice.options import voice_model_options

    options = voice_model_options(provider, "tts", resolved_model)
    voice = _as_str((model or {}).get("voice"))
    response_format = _as_str((model or {}).get("response_format")) or options["formats"][0]
    raw_speed = (model or {}).get("speed")
    speed = _coerce_optional_float(raw_speed)
    if raw_speed not in (None, "") and speed is None:
        raise ValueError("Speech speed must be a positive number.")
    limits = options.get("speed")
    if speed is not None and limits and not limits["min"] <= speed <= limits["max"]:
        raise ValueError(f"Speech speed must be between {limits['min']} and {limits['max']}.")

    return TTSConfig(
        model=resolved_model,
        provider_name=provider,
        adapter=spec.adapter,
        auth_style=spec.auth_style,
        api_key=api_key,
        app_id=_as_str((profile or {}).get("app_id")),
        resource_id=_as_str((model or {}).get("resource_id")),
        base_url=api_base,
        api_version=_as_str((profile or {}).get("api_version")) or None,
        extra_headers=_to_headers((profile or {}).get("extra_headers")),
        voice=voice,
        response_format=response_format,
        speed=speed,
        language=_as_str((model or {}).get("language")) or None,
        sample_rate=int((model or {}).get("sample_rate") or 24000),
        instructions=_as_str((model or {}).get("instructions")),
        max_input_chars=options.get("max_input_chars", 4096),
        request_timeout=resolve_tts_request_timeout((model or {}).get("request_timeout")),
    )


def resolve_stt_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> STTConfig:
    """Resolve the active speech-to-text config from the model catalog."""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    profile, model = _active_profile_and_model(loaded, catalog_service, "stt")
    resolved_model = _as_str((model or {}).get("model"))
    if not resolved_model:
        raise ValueError("No active STT model is configured. Set it in Settings > Voice.")

    provider = _canonical_voice_provider(_as_str((profile or {}).get("binding")), STT_PROVIDERS)
    spec = STT_PROVIDERS[provider]
    api_base = _as_str((profile or {}).get("base_url")) or spec.default_api_base
    api_key = _as_str((profile or {}).get("api_key"))
    if not api_key and spec.is_local:
        api_key = "sk-no-key-required"

    return STTConfig(
        model=resolved_model,
        provider_name=provider,
        adapter=spec.adapter,
        request_style=spec.request_style,
        auth_style=spec.auth_style,
        api_key=api_key,
        app_id=_as_str((profile or {}).get("app_id")),
        resource_id=_as_str((model or {}).get("resource_id")),
        base_url=api_base,
        api_version=_as_str((profile or {}).get("api_version")) or None,
        extra_headers=_to_headers((profile or {}).get("extra_headers")),
        language=_as_str((model or {}).get("language")) or None,
    )


def resolve_imagegen_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> ImagegenConfig:
    """Resolve the active text-to-image config from the model catalog."""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    profile, model = _active_profile_and_model(loaded, catalog_service, "imagegen")
    resolved_model = _as_str((model or {}).get("model"))
    if not resolved_model:
        raise ValueError(
            "No active image-generation model is configured. "
            "Set it in Settings > Media Generation > Image Generation."
        )

    provider = _canonical_generation_provider(
        _as_str((profile or {}).get("binding")), IMAGEGEN_PROVIDERS
    )
    spec = IMAGEGEN_PROVIDERS[provider]
    api_base = _as_str((profile or {}).get("base_url")) or spec.default_api_base
    api_key = _as_str((profile or {}).get("api_key"))
    if not api_key and spec.is_local:
        api_key = "sk-no-key-required"

    return ImagegenConfig(
        model=resolved_model,
        provider_name=provider,
        adapter=spec.adapter,
        auth_style=spec.auth_style,
        api_key=api_key,
        base_url=api_base,
        api_version=_as_str((profile or {}).get("api_version")) or None,
        extra_headers=_to_headers((profile or {}).get("extra_headers")),
        size=_as_str((model or {}).get("size")),
        quality=_as_str((model or {}).get("quality")),
        style=_as_str((model or {}).get("style")),
        response_format=_as_str((model or {}).get("response_format")),
    )


def resolve_videogen_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> VideogenConfig:
    """Resolve the active text-to-video config from the model catalog."""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    profile, model = _active_profile_and_model(loaded, catalog_service, "videogen")
    resolved_model = _as_str((model or {}).get("model"))
    if not resolved_model:
        raise ValueError(
            "No active video-generation model is configured. "
            "Set it in Settings > Media Generation > Video Generation."
        )

    provider = _canonical_generation_provider(
        _as_str((profile or {}).get("binding")), VIDEOGEN_PROVIDERS
    )
    spec = VIDEOGEN_PROVIDERS[provider]
    api_base = _as_str((profile or {}).get("base_url")) or spec.default_api_base
    api_key = _as_str((profile or {}).get("api_key"))
    if not api_key and spec.is_local:
        api_key = "sk-no-key-required"

    return VideogenConfig(
        model=resolved_model,
        provider_name=provider,
        adapter=spec.adapter,
        auth_style=spec.auth_style,
        api_key=api_key,
        base_url=api_base,
        api_version=_as_str((profile or {}).get("api_version")) or None,
        extra_headers=_to_headers((profile or {}).get("extra_headers")),
        aspect_ratio=_as_str((model or {}).get("aspect_ratio")),
        duration=_as_str((model or {}).get("duration")),
        resolution=_as_str((model or {}).get("resolution")),
    )


def _resolve_search_max_results(catalog: dict[str, Any], default: int = 5) -> int:
    profile = get_model_catalog_service().get_active_profile(catalog, "search") or {}
    raw = profile.get("max_results")
    if raw is not None:
        try:
            value = int(raw)
            return max(1, min(value, 10))
        except (TypeError, ValueError):
            pass
    try:
        settings = load_config_with_main("main.yaml")
    except Exception:
        return default
    tools = settings.get("tools", {}) if isinstance(settings, dict) else {}
    web_search = tools.get("web_search", {}) if isinstance(tools, dict) else {}
    if isinstance(web_search, dict):
        raw = web_search.get("max_results")
        if raw is not None:
            try:
                value = int(raw)
                return max(1, min(value, 10))
            except (TypeError, ValueError):
                pass
    web = tools.get("web", {}) if isinstance(tools, dict) else {}
    search = web.get("search", {}) if isinstance(web, dict) else {}
    raw = search.get("max_results") if isinstance(search, dict) else None
    if raw is None:
        return default
    try:
        value = int(raw)
        return max(1, min(value, 10))
    except (TypeError, ValueError):
        return default


def _search_profiles(catalog: dict[str, Any]) -> list[dict[str, Any]]:
    profiles = catalog.get("services", {}).get("search", {}).get("profiles", [])
    return [
        resolve_profile_provider(catalog, "search", profile)
        for profile in profiles
        if isinstance(profile, dict) and not profile.get("provider_only")
    ]


def search_provider_credentials(
    provider: str,
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> tuple[str, str]:
    """Return ``(api_key, base_url)`` from the search profile targeting *provider*.

    Search profiles are a list, so several providers can stay configured side by
    side with only one active. Looking credentials up by provider is what keeps a
    non-active provider from reaching for whatever key the active profile holds
    (which used to send e.g. a Brave key to Tavily). The active profile wins when
    it matches; otherwise the first profile naming the provider supplies them.
    """
    name = (provider or "").strip().lower()
    if not name:
        return "", ""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    active = catalog_service.get_active_profile(loaded, "search") or {}
    for profile in (active, *_search_profiles(loaded)):
        if _as_str(profile.get("provider")).lower() == name:
            return _as_str(profile.get("api_key")), _as_str(profile.get("base_url"))
    return "", ""


def search_missing_credential(provider: str, api_key: str, base_url: str) -> str | None:
    """Name the connection field *provider* needs but does not have."""
    spec = search_provider_spec(provider)
    if spec is None:
        return None
    if spec.requires_api_key and not api_key:
        return "api_key"
    if spec.requires_base_url and not base_url:
        return "base_url"
    return None


def search_fallback_candidates(
    requested: str,
    catalog: dict[str, Any] | None = None,
) -> list[str]:
    """Ordered providers to try after *requested* fails at runtime.

    A rate-limited or unreachable search engine should cost the query its first
    choice, not the whole turn. Candidates are the user's other fully-configured
    search profiles (they opted into those providers by configuring them), then
    the credential-free fallback. Providers whose credentials are missing never
    enter the chain, and ``none`` — an explicit "search is off" — is excluded.
    """
    name = (requested or "").strip().lower()
    loaded = _load_catalog(catalog)
    candidates: list[str] = []
    for profile in _search_profiles(loaded):
        provider = _as_str(profile.get("provider")).lower()
        spec = search_provider_spec(provider)
        if spec is None or provider in {"none", name} or provider in candidates:
            continue
        if search_missing_credential(
            provider, _as_str(profile.get("api_key")), _as_str(profile.get("base_url"))
        ):
            continue
        candidates.append(provider)
    if name != SEARCH_FALLBACK_PROVIDER and SEARCH_FALLBACK_PROVIDER not in candidates:
        candidates.append(SEARCH_FALLBACK_PROVIDER)
    return candidates


def resolve_search_runtime_config(
    catalog: dict[str, Any] | None = None,
    *,
    service: ModelCatalogService | None = None,
) -> ResolvedSearchConfig:
    """Resolve active web-search config with TutorBot-style fallback behavior."""
    catalog_service = service or get_model_catalog_service()
    loaded = _load_catalog(catalog)
    profile = catalog_service.get_active_profile(loaded, "search") or {}

    requested_provider = (_as_str(profile.get("provider")) or SEARCH_FALLBACK_PROVIDER).lower()
    provider = requested_provider
    api_key = _as_str(profile.get("api_key"))
    base_url = _as_str(profile.get("base_url"))
    proxy = _as_str(profile.get("proxy")) or None
    max_results = _resolve_search_max_results(loaded)

    spec = search_provider_spec(provider)
    if spec is None:
        return ResolvedSearchConfig(
            provider=provider,
            requested_provider=requested_provider,
            api_key=api_key,
            base_url=base_url,
            max_results=max_results,
            proxy=proxy,
            unsupported_provider=True,
            deprecated_provider=provider in DEPRECATED_SEARCH_PROVIDERS,
        )

    if provider == "none":
        return ResolvedSearchConfig(
            provider="none",
            requested_provider="none",
            api_key="",
            base_url="",
            max_results=max_results,
            proxy=proxy,
        )

    missing = search_missing_credential(provider, api_key, base_url)
    fallback_reason: str | None = None
    if missing and spec.soft_fallback:
        fallback_reason = (
            f"{provider} requires {missing}, falling back to {SEARCH_FALLBACK_PROVIDER}"
        )
        provider = SEARCH_FALLBACK_PROVIDER

    return ResolvedSearchConfig(
        provider=provider,
        requested_provider=requested_provider,
        api_key=api_key,
        base_url=base_url,
        max_results=max_results,
        proxy=proxy,
        unsupported_provider=False,
        deprecated_provider=False,
        missing_credentials=bool(missing) and not spec.soft_fallback,
        fallback_reason=fallback_reason,
    )


def search_provider_state(provider: str | None) -> str:
    """Return provider status class for UI/CLI/system output."""
    value = (provider or "").strip().lower()
    if not value:
        return "not_configured"
    if value in DEPRECATED_SEARCH_PROVIDERS:
        return "deprecated"
    if value not in SUPPORTED_SEARCH_PROVIDERS:
        return "unsupported"
    return "supported"


__all__ = [
    "SUPPORTED_SEARCH_PROVIDERS",
    "DEPRECATED_SEARCH_PROVIDERS",
    "SEARCH_PROVIDERS",
    "SEARCH_FALLBACK_PROVIDER",
    "SearchProviderSpec",
    "search_provider_spec",
    "search_provider_credentials",
    "search_missing_credential",
    "search_fallback_candidates",
    "supported_search_providers_hint",
    "NANOBOT_LLM_PROVIDERS",
    "EmbeddingProviderSpec",
    "EMBEDDING_PROVIDERS",
    "VoiceProviderSpec",
    "TTS_PROVIDERS",
    "STT_PROVIDERS",
    "resolve_tts_runtime_config",
    "resolve_stt_runtime_config",
    "GenerationProviderSpec",
    "IMAGEGEN_PROVIDERS",
    "VIDEOGEN_PROVIDERS",
    "resolve_imagegen_runtime_config",
    "resolve_videogen_runtime_config",
    "EMBEDDING_PROVIDER_ALIASES",
    "embedding_endpoint_validation_error",
    "normalize_embedding_endpoint_for_display",
    "NormalizedProviderConfig",
    "ResolvedLLMConfig",
    "ResolvedEmbeddingConfig",
    "ResolvedSearchConfig",
    "LLM_LOCALHOST_PROVIDERS",
    "resolve_llm_runtime_config",
    "resolve_embedding_runtime_config",
    "resolve_search_runtime_config",
    "search_provider_state",
]


def _clamp_batch_size(profile: dict | None) -> int:
    try:
        return max(1, int((profile or {}).get("batch_size", 10)))
    except Exception:
        return 10


def _clamp_batch_delay(profile: dict | None) -> float:
    try:
        return max(0.0, float((profile or {}).get("batch_delay", 0.0)))
    except Exception:
        return 0.0