Skip to content

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

27.0 KB
Raw Blame
"""
Provider Capabilities
=====================

Centralized configuration for LLM provider capabilities.
This replaces scattered hardcoded checks throughout the codebase.

Usage:
    from deeptutor.services.llm.capabilities import get_capability, supports_response_format

    # Check if a provider supports response_format
    if supports_response_format(binding, model):
        kwargs["response_format"] = {"type": "json_object"}

    # Generic capability check
    if get_capability(binding, "streaming", default=True):
        # use streaming
"""

from __future__ import annotations

from collections.abc import Iterable, Mapping
import threading

# Provider capabilities configuration
# Keys are binding names (lowercase), values are capability dictionaries
PROVIDER_CAPABILITIES: dict[str, dict[str, object]] = {
    # OpenAI and OpenAI-compatible providers
    "openai": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "system_in_messages": True,  # System prompt goes in messages array
        "newer_models_use_max_completion_tokens": True,
    },
    # Codex uses OpenAI's Responses API and converts image_url message parts
    # into native input_image blocks before sending the request.
    "openai_codex": {
        "supports_vision": True,
    },
    # Custom / user-defined OpenAI-compatible endpoints
    "custom": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,  # Most OpenAI-compat endpoints support function calling
        "supports_vision": False,  # Per-model; set True via MODEL_OVERRIDES
        "vision_url_supported": True,
        "system_in_messages": True,
        "has_thinking_tags": False,  # Per-model; MODEL_OVERRIDES handles qwen/deepseek etc.
    },
    "azure_openai": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "system_in_messages": True,
        "newer_models_use_max_completion_tokens": True,
        "requires_api_version": True,
    },
    # Anthropic
    "anthropic": {
        "supports_response_format": False,  # Anthropic uses different format
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "vision_url_supported": False,  # Our adapter only emits base64 image source
        "system_in_messages": False,  # System is a separate parameter
        "has_thinking_tags": False,
    },
    "claude": {  # Alias for anthropic
        "supports_response_format": False,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "vision_url_supported": False,
        "system_in_messages": False,
        "has_thinking_tags": False,
    },
    "custom_anthropic": {
        "supports_response_format": False,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "vision_url_supported": False,
        "system_in_messages": False,
        "has_thinking_tags": False,
    },
    "minimax_anthropic": {
        "supports_response_format": False,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "vision_url_supported": False,
        "system_in_messages": False,
        "has_thinking_tags": False,
    },
    "codebuddy": {
        "supports_response_format": False,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": False,
        "system_in_messages": True,
        "has_thinking_tags": False,
    },
    # DeepSeek
    "deepseek": {
        "supports_response_format": False,  # DeepSeek doesn't support strict JSON schema yet
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": False,
        "system_in_messages": True,
        "has_thinking_tags": True,  # DeepSeek reasoner has thinking tags
    },
    # SiliconFlow exposes OpenAI-compatible chat completions for hosted models
    # such as DeepSeek and Qwen; model-specific overrides below still govern
    # response_format, thinking tags, and vision.
    "siliconflow": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": False,
        "vision_url_supported": True,
        "system_in_messages": True,
        "has_thinking_tags": False,
    },
    # VolcEngine Ark (Doubao) and BytePlus — OpenAI-compatible gateways that
    # host natively multimodal models (Doubao-Vision). ``supports_vision`` is
    # the Stage-2 fallback hint (see ``multimodal.py``), not a pre-flight gate:
    # marking these True means a transient failure never causes images to be
    # silently dropped. The Ark API expects inline base64 image data, so
    # url-only attachments are resolved to bytes before sending.
    "volcengine": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "vision_url_supported": False,
        "system_in_messages": True,
    },
    "byteplus": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "vision_url_supported": False,
        "system_in_messages": True,
    },
    # OpenRouter (aggregator, generally OpenAI-compatible)
    "openrouter": {
        "supports_response_format": True,  # Depends on underlying model
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,  # Depends on underlying model
        "system_in_messages": True,
    },
    # Groq (fast inference)
    "groq": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "system_in_messages": True,
    },
    # Together AI
    "together": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "system_in_messages": True,
    },
    "together_ai": {  # Alias
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "system_in_messages": True,
    },
    # Mistral
    "mistral": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": True,
        "system_in_messages": True,
    },
    # DashScope / Alibaba Cloud (Qwen family)
    # Uses OpenAI-compatible API with native function calling support.
    "dashscope": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": False,  # Per-model; set True via MODEL_OVERRIDES
        "system_in_messages": True,
        "has_thinking_tags": True,  # Qwen reasoner models emit <think/> tags
    },
    # Moonshot / Kimi — vision is per-model (see MODEL_OVERRIDES below).
    # Per the official docs the image input must be base64-encoded inline; URL
    # form is rejected. We therefore force the multimodal layer to resolve any
    # url-only attachment to bytes before sending.
    "moonshot": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": False,
        "vision_url_supported": False,
        "system_in_messages": True,
    },
    # MiniMax's OpenAI-compatible endpoint supports Chat Completions tools /
    # function calling for M-series text models. Response-format support is
    # still disabled by the model override below.
    "minimax": {
        "supports_response_format": False,
        "supports_streaming": True,
        "supports_tools": True,
        "supports_vision": False,
        "system_in_messages": True,
    },
    # Local providers (generally OpenAI-compatible)
    "ollama": {
        "supports_response_format": True,  # Ollama supports JSON mode
        "supports_streaming": True,
        "supports_tools": False,  # Limited tool support
        "supports_vision": False,  # Depends on model; set True via model overrides
        "system_in_messages": True,
    },
    "lm_studio": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": False,
        "supports_vision": False,
        "system_in_messages": True,
    },
    "vllm": {
        "supports_response_format": True,
        "supports_streaming": True,
        "supports_tools": False,
        "supports_vision": False,
        "system_in_messages": True,
    },
    "llama_cpp": {
        "supports_response_format": True,  # llama.cpp server supports JSON grammar
        "supports_streaming": True,
        "supports_tools": False,
        "supports_vision": False,
        "system_in_messages": True,
    },
}

# Default capabilities for unknown providers (assume OpenAI-compatible)
DEFAULT_CAPABILITIES: dict[str, object] = {
    "supports_response_format": True,
    "supports_streaming": True,
    "supports_tools": False,
    "supports_vision": False,
    "vision_url_supported": True,  # Most OpenAI-compat providers accept image_url URLs
    "system_in_messages": True,
    "has_thinking_tags": False,
    "forced_temperature": None,  # None means no forced value, use requested temperature
}

# Model-specific overrides
# Format: {model_pattern: {capability: value}}
# Patterns are matched with case-insensitive startswith
MODEL_OVERRIDES: dict[str, dict[str, object]] = {
    "deepseek": {
        "supports_response_format": False,
        "has_thinking_tags": True,
        "supports_vision": False,
    },
    "deepseek-reasoner": {
        "supports_response_format": False,
        "has_thinking_tags": True,
        "supports_vision": False,
    },
    # Qwen text models often share the same provider/gateway as Qwen-VL.
    # Keep thinking-tag handling broad, but only mark explicit VL/vision model
    # names as image-capable so RAG image indexing can fail closed.
    # Qwen3.8-Max is natively multimodal despite not using the historical
    # ``-vl`` suffix. Keep this override narrow so other Qwen text models remain
    # fail-closed.
    # https://help.aliyun.com/zh/model-studio/vision-model
    "qwen3.8-max": {"supports_vision": True},
    "qwen/qwen2.5-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen/qwen3-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen/qwen2-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen/qwen-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen2.5-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen3-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen2-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen-vl": {"has_thinking_tags": True, "supports_vision": True},
    "qwen": {
        "has_thinking_tags": True,
        "supports_vision": False,
    },
    "qwq": {
        "has_thinking_tags": True,
    },
    "minimax": {
        "supports_response_format": False,
    },
    # NOTE: supports_response_format and system_in_messages are binding-level
    # capabilities, NOT model-level. When using OpenRouter or other OpenAI-compatible
    # proxies (binding="openai"), they handle response_format translation and expect
    # system prompts in messages. The native Anthropic limitations are already
    # handled by PROVIDER_CAPABILITIES["anthropic"] / ["claude"] above.
    # Only model-intrinsic capabilities (like has_thinking_tags) belong here.
    # Reasoning models - only support temperature=1.0
    # See: https://github.com/HKUDS/DeepTutor/issues/141
    "gpt-5": {
        "forced_temperature": 1.0,
    },
    "o1": {
        "forced_temperature": 1.0,
    },
    "o3": {
        "forced_temperature": 1.0,
    },
    # Vision-capable model families
    "gpt-4o": {"supports_vision": True},
    "gpt-4-turbo": {"supports_vision": True},
    "gpt-4-vision": {"supports_vision": True},
    # Anthropic moved to `claude-<family>-<version>` after Claude 3, so no model id
    # begins with "claude-4" and that prefix matched nothing. Every Claude model from
    # 3 onward is multimodal, so match the vendor prefix rather than enumerating
    # versions that go stale. A future text-only model can be excluded by adding a
    # longer, more specific key (longest prefix wins in get_capability).
    "claude-": {"supports_vision": True},
    "gemini": {"supports_vision": True},
    "gemma": {"supports_vision": False, "supports_response_format": False},
    "llava": {"supports_vision": True},
    "bakllava": {"supports_vision": True},
    "moondream": {"supports_vision": True},
    "minicpm-v": {"supports_vision": True},
    "gpt-3.5": {"supports_vision": False},
    # Moonshot / Kimi vision models
    # https://platform.kimi.com/docs/guide/use-kimi-vision-model
    "moonshot-v1-8k-vision": {"supports_vision": True},
    "moonshot-v1-32k-vision": {"supports_vision": True},
    "moonshot-v1-128k-vision": {"supports_vision": True},
    "kimi-k2.5": {"supports_vision": True},
    "kimi-k2.6": {"supports_vision": True},
    "kimi-k3": {"supports_vision": True},
}


# Per-model overrides typed by the user in Settings > Models, keyed by the
# catalog's user-facing names and translated to capability names here so the
# rest of this module keeps one vocabulary. The table is replaced wholesale on
# every catalog resolution, so an override removed in Settings stops applying
# without a restart. Lookup is by model id first because the runtime often
# asks under a *normalized* binding (an Anthropic-format custom endpoint is
# asked about as ``anthropic``) while the catalog stores the vendor binding.
CATALOG_CAPABILITY_FIELDS: dict[str, str] = {
    "tools": "supports_tools",
    "vision": "supports_vision",
    "json_output": "supports_response_format",
}
_CATALOG_OVERRIDES: dict[str, dict[str, dict[str, bool]]] = {}
_catalog_overrides_lock = threading.Lock()


def set_catalog_capability_overrides(
    entries: Iterable[tuple[str, str, Mapping[str, bool]]],
) -> None:
    """Replace the user-declared overrides with ``(binding, model, caps)`` rows."""
    table: dict[str, dict[str, dict[str, bool]]] = {}
    for binding, model, overrides in entries:
        model_key = (model or "").strip().lower()
        if not model_key:
            continue
        caps = {
            CATALOG_CAPABILITY_FIELDS[key]: bool(value)
            for key, value in overrides.items()
            if key in CATALOG_CAPABILITY_FIELDS and isinstance(value, bool)
        }
        if caps:
            table.setdefault(model_key, {})[(binding or "").strip().lower()] = caps
    with _catalog_overrides_lock:
        _CATALOG_OVERRIDES.clear()
        _CATALOG_OVERRIDES.update(table)


def catalog_capability_override(
    binding: str | None,
    model: str | None,
    capability: str,
) -> bool | None:
    """The user's explicit answer for *capability*, or ``None`` when unset."""
    model_key = (model or "").strip().lower()
    if not model_key:
        return None
    with _catalog_overrides_lock:
        by_binding = _CATALOG_OVERRIDES.get(model_key)
        if not by_binding:
            return None
        caps = by_binding.get((binding or "").strip().lower()) or next(iter(by_binding.values()))
        value = caps.get(capability)
    return value if isinstance(value, bool) else None


def effective_capabilities(binding: str | None, model: str | None) -> dict[str, bool]:
    """What the built-in tables say for *binding*/*model*, ignoring overrides.

    The settings UI shows these as the value "Auto" currently resolves to.
    """
    return {
        key: bool(_static_capability(binding or "openai", capability, model, default=False))
        for key, capability in CATALOG_CAPABILITY_FIELDS.items()
    }


def get_capability(
    binding: str,
    capability: str,
    model: str | None = None,
    default: object = None,
) -> object:
    """
    Get a capability value for a provider/model combination.

    Checks in order:
    0. Explicit per-model overrides from the model catalog
    1. Model-specific overrides (matched by prefix)
    2. Provider/binding capabilities
    3. Default capabilities for unknown providers
    4. Explicit default value

    Args:
        binding: Provider binding name (e.g., "openai", "anthropic", "deepseek")
        capability: Capability name (e.g., "supports_response_format")
        model: Optional model name for model-specific overrides
        default: Default value if capability is not defined

    Returns:
        Capability value or default
    """
    declared = catalog_capability_override(binding, model, capability)
    if declared is not None:
        return declared
    return _static_capability(binding, capability, model, default)


def _static_capability(
    binding: str,
    capability: str,
    model: str | None = None,
    default: object = None,
) -> object:
    binding_lower = (binding or "openai").lower()

    # 1. Check model-specific overrides first
    if model:
        # Google's model list returns resource names ("models/gemini-2.5-flash")
        # while every MODEL_OVERRIDES key is a bare id, so a catalog-supplied id
        # missed each vendor rule and fell through to the binding default. The
        # embedding layer already strips this prefix (see embedding_endpoint.py
        # and embedding/adapters/gemini.py); match the same normalized form here
        # so "Vision: Auto" resolves identically for both spellings (#1579).
        model_lower = model.lower().removeprefix("models/")
        # Sort by pattern length descending to match most specific first
        for pattern, overrides in sorted(MODEL_OVERRIDES.items(), key=lambda x: -len(x[0])):
            if model_lower.startswith(pattern):
                if capability in overrides:
                    return overrides[capability]

    # 2. Check provider capabilities
    provider_caps = PROVIDER_CAPABILITIES.get(binding_lower, {})
    if capability in provider_caps:
        return provider_caps[capability]

    # 3. Check default capabilities for unknown providers
    if capability in DEFAULT_CAPABILITIES:
        return DEFAULT_CAPABILITIES[capability]

    # 4. Return explicit default
    return default


# Runtime cache for response_format incompatibilities discovered at request time.
# Keyed by (binding_lower, model_lower). Populated when a provider rejects a
# request with response_format={"type": "json_object"} (commonly LM Studio /
# Ollama serving Gemma/Qwen-style models that only accept "json_schema" or "text").
# Once a pair is recorded here, subsequent calls skip response_format entirely
# instead of paying the cost of a failed request + retry.
_RUNTIME_DISABLED_RESPONSE_FORMAT: set[tuple[str, str]] = set()


def disable_response_format_at_runtime(binding: str | None, model: str | None) -> None:
    """Mark a (binding, model) pair as not supporting ``response_format``.

    Subsequent calls to :func:`supports_response_format` for the same pair
    will return ``False`` without re-checking the static configuration. This
    is useful when a provider unexpectedly rejects ``response_format`` at
    runtime (e.g. LM Studio + ``gemma-4-e2b`` returning
    ``"'response_format.type' must be 'json_schema' or 'text'"``).
    """
    if not binding or not model:
        return
    _RUNTIME_DISABLED_RESPONSE_FORMAT.add((binding.lower(), model.lower()))


def is_response_format_disabled_at_runtime(binding: str | None, model: str | None) -> bool:
    """Return True if (binding, model) was disabled via :func:`disable_response_format_at_runtime`."""
    if not binding or not model:
        return False
    return (binding.lower(), model.lower()) in _RUNTIME_DISABLED_RESPONSE_FORMAT


# Runtime cache for providers that refuse to be told *which* tool to call.
# Keyed by (binding_lower, model_lower), populated when a request naming a
# function is rejected (DeepSeek V4 with thinking: "Thinking mode does not
# support this tool_choice"). Recorded so the next forced round asks for
# ``"required"`` up front instead of paying for a failed request first.
_RUNTIME_DISABLED_FORCED_TOOL_CHOICE: set[tuple[str, str]] = set()


def disable_forced_tool_choice_at_runtime(binding: str | None, model: str | None) -> None:
    """Mark a (binding, model) pair as unable to have one tool forced."""
    if not binding or not model:
        return
    _RUNTIME_DISABLED_FORCED_TOOL_CHOICE.add((binding.lower(), model.lower()))


def is_forced_tool_choice_disabled_at_runtime(
    binding: str | None,
    model: str | None,
) -> bool:
    """Whether this pair was recorded by :func:`disable_forced_tool_choice_at_runtime`."""
    if not binding or not model:
        return False
    return (binding.lower(), model.lower()) in _RUNTIME_DISABLED_FORCED_TOOL_CHOICE


def supports_response_format(binding: str, model: str | None = None) -> bool:
    """
    Check if the provider/model supports response_format parameter.

    This is a convenience function for the most common capability check.
    A runtime override (set via :func:`disable_response_format_at_runtime`)
    always wins over static capability configuration.

    Args:
        binding: Provider binding name
        model: Optional model name for model-specific overrides

    Returns:
        True if response_format is supported
    """
    if is_response_format_disabled_at_runtime(binding, model):
        return False
    value = get_capability(binding, "supports_response_format", model, default=True)
    return bool(value)


def supports_streaming(binding: str, model: str | None = None) -> bool:
    """
    Check if the provider/model supports streaming responses.

    Args:
        binding: Provider binding name
        model: Optional model name

    Returns:
        True if streaming is supported
    """
    value = get_capability(binding, "supports_streaming", model, default=True)
    return bool(value)


def system_in_messages(binding: str, model: str | None = None) -> bool:
    """
    Check if system prompt should be in messages array (OpenAI style)
    or as a separate parameter (Anthropic style).

    Args:
        binding: Provider binding name
        model: Optional model name

    Returns:
        True if system prompt goes in messages array
    """
    value = get_capability(binding, "system_in_messages", model, default=True)
    return bool(value)


def has_thinking_tags(binding: str, model: str | None = None) -> bool:
    """
    Check if the model output may contain thinking tags (<think>...</think>).

    Args:
        binding: Provider binding name
        model: Optional model name

    Returns:
        True if thinking tags should be filtered
    """
    value = get_capability(binding, "has_thinking_tags", model, default=False)
    return bool(value)


def supports_tools(binding: str, model: str | None = None) -> bool:
    """
    Check if the provider/model supports function calling / tools.

    Args:
        binding: Provider binding name
        model: Optional model name

    Returns:
        True if tools/function calling is supported
    """
    value = get_capability(binding, "supports_tools", model, default=False)
    return bool(value)


def supports_vision(binding: str, model: str | None = None) -> bool:
    """
    Check if the provider/model supports multimodal (image) input.

    Args:
        binding: Provider binding name
        model: Optional model name for model-specific overrides

    Returns:
        True if the model can accept image content in messages
    """
    value = get_capability(binding, "supports_vision", model, default=False)
    return bool(value)


def supports_vision_declared(
    declared: object, binding: str | None, model: str | None = None
) -> bool:
    """Vision support, with a model's own declaration winning over the tables.

    Catalog capability overrides register against the provider the runtime may
    detect from ``base_url``, which is not always the profile's declared
    binding, so the declaration has to be honoured before the lookup. The
    settings picker and the save-time gate both use this rule, otherwise they
    disagree about the same model (#2037 follow-up).
    """
    if type(declared) is bool:
        return declared
    return supports_vision(binding, model)


def supports_vision_url(binding: str, model: str | None = None) -> bool:
    """Whether the provider accepts remote URL image references.

    Some providers (Moonshot, our Anthropic adapter) only accept inline
    base64-encoded image bytes. The multimodal layer consults this flag to
    decide whether url-only attachments need to be resolved to bytes before
    being forwarded.
    """
    value = get_capability(binding, "vision_url_supported", model, default=True)
    return bool(value)


def requires_api_version(binding: str, model: str | None = None) -> bool:
    """
    Check if the provider requires an API version parameter (e.g., Azure OpenAI).

    Args:
        binding: Provider binding name
        model: Optional model name

    Returns:
        True if api_version is required
    """
    value = get_capability(binding, "requires_api_version", model, default=False)
    return bool(value)


def get_effective_temperature(
    binding: str,
    model: str | None = None,
    requested_temp: float = 0.7,
) -> float:
    """
    Get the effective temperature value for a model.

    Some models (e.g., o1, o3, gpt-5) only support a fixed temperature value (1.0).
    This function returns the forced temperature if defined, otherwise the requested value.

    Args:
        binding: Provider binding name
        model: Optional model name for model-specific overrides
        requested_temp: The temperature value requested by the caller (default: 0.7)

    Returns:
        The effective temperature to use for the API call
    """
    forced_temp = get_capability(binding, "forced_temperature", model)
    if isinstance(forced_temp, (int, float)):
        return float(forced_temp)
    return requested_temp


#: Bindings whose upstream tracks a multi-turn conversation by an id the caller
#: supplies, so each request carries the turn's own session id. Stated here
#: rather than tested inline: the chat loop and the explore capability both
#: need it, and neither should have to name a provider to run a turn.
SESSION_SCOPED_BINDINGS: frozenset[str] = frozenset({"codebuddy", "openai_codex"})


def threads_session_id(binding: str | None) -> bool:
    """Whether *binding* expects ``deeptutor_session_id`` on each request."""
    return (binding or "").strip().lower() in SESSION_SCOPED_BINDINGS


__all__ = [
    "CATALOG_CAPABILITY_FIELDS",
    "PROVIDER_CAPABILITIES",
    "SESSION_SCOPED_BINDINGS",
    "threads_session_id",
    "MODEL_OVERRIDES",
    "DEFAULT_CAPABILITIES",
    "catalog_capability_override",
    "effective_capabilities",
    "get_capability",
    "set_catalog_capability_overrides",
    "supports_response_format",
    "supports_streaming",
    "system_in_messages",
    "has_thinking_tags",
    "supports_tools",
    "supports_vision",
    "requires_api_version",
    "get_effective_temperature",
    "disable_response_format_at_runtime",
    "is_response_format_disabled_at_runtime",
    "disable_forced_tool_choice_at_runtime",
    "is_forced_tool_choice_disabled_at_runtime",
]