Skip to content

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

12.3 KB
Raw Blame
"""Reasoning/thinking parameters for OpenAI-compatible provider calls."""

from __future__ import annotations

from typing import Any

#: Reasoning level to ask for on a second attempt, after a first one spent its
#: whole ``max_tokens`` budget thinking and returned no answer. ``"low"``
#: rather than ``"minimal"``: local/Qwen models served via vLLM reject
#: ``"minimal"``, and it disables thinking outright rather than trimming it.
RETRY_REASONING_EFFORT = "low"

_THINKING_STYLE_MAP = {
    "thinking_type": lambda enabled: {"thinking": {"type": "enabled" if enabled else "disabled"}},
    "enable_thinking": lambda enabled: {"enable_thinking": enabled},
    "reasoning_split": lambda enabled: {"reasoning_split": enabled},
}
# These values are used by callers that need a guaranteed reader-facing
# response.  ``minimal``/``minimum`` are retained as off sentinels for
# provider-native thinking controls for backwards compatibility; OpenRouter
# receives the canonical ``none`` value below.
_THINKING_OFF_EFFORTS = frozenset({"none", "minimal", "minimum"})
_PROVIDER_THINKING_STYLES = {
    "deepseek": "thinking_type",
    "volcengine": "thinking_type",
    "volcengine_coding_plan": "thinking_type",
    "byteplus": "thinking_type",
    "byteplus_coding_plan": "thinking_type",
    "dashscope": "enable_thinking",
    "minimax": "reasoning_split",
}
_PROVIDER_REASONING_PATTERNS = {
    "deepseek": ("deepseek-v4-pro", "deepseek-reasoner"),
    "dashscope": ("qwen3", "qwen-3", "qwq", "qwen-plus"),
}
# Models that ship with thinking enabled by default and burn the entire
# `max_tokens` budget on reasoning unless we explicitly turn it off via the
# top-level ``reasoning_effort`` field. Substring match — also catches the
# ``models/<id>`` prefix some clients use.
_PROVIDER_DEFAULT_OFF_PATTERNS: dict[str, tuple[str, ...]] = {
    "gemini": ("gemini-2.5", "gemini-3"),
}
# Models matched above that cannot turn thinking off at all: they reject
# ``reasoning_effort="none"`` with a 400, and "minimal" is the lowest level
# they accept (#734). Kept beside the patterns it narrows so adding a family
# to one table is an obvious prompt to check the other.
_MINIMAL_NOT_OFF_PATTERNS: dict[str, tuple[str, ...]] = {
    "gemini": ("gemini-3", "gemini-2.5-pro"),
}
_CUSTOM_MODEL_THINKING_STYLES: tuple[tuple[tuple[str, ...], str], ...] = (
    (("qwen3", "qwen-3", "qwq", "qwen-plus"), "enable_thinking"),
    (("deepseek-v4-pro", "deepseek-reasoner", "deepseek-r1"), "thinking_type"),
)
# Models we send an explicit "thinking off" to, by model substring and by
# (provider, model) pair. Both are deliberately EMPTY.
#
# ``deepseek-v4-flash`` used to be listed here to dodge the mid-conversation
# ``reasoning_content must be passed back`` 400 (#1058). That is not what fixes
# it — echoing the previous round's reasoning on the assistant turn that issued
# the tool calls is, and that landed in the same change (see
# ``assistant_message_with_tool_calls``). Keeping the switch off as well bought
# nothing and cost every flash user their entire reasoning stream: the model
# emits reasoning happily, and we were the ones suppressing it.
#
# Add a model here only when the provider itself cannot be made to work with
# thinking on — not to work around a payload we control.
_THINKING_DISABLED_BY_DEFAULT_MODELS: tuple[str, ...] = ()
_THINKING_DISABLED_BY_DEFAULT: tuple[tuple[str, str], ...] = ()


def minimax_reasoning_kwargs(
    model: str, effort: str, *, anthropic: bool = False
) -> dict[str, Any] | None:
    """Map current MiniMax models without changing saved legacy/custom requests.

    See https://platform.minimax.io/docs/api-reference/text-openai-api and
    https://platform.minimax.io/docs/api-reference/text-anthropic-api.
    """
    name = model.lower()
    if name not in {"minimax-m3.1-flash", "minimax-m3"}:
        return None
    if name == "minimax-m3":
        if not effort and not anthropic:
            # Omission retains each protocol's own default, including when an
            # agentic OpenAI facade forwards this request to Anthropic Messages.
            return {}
        enabled = effort not in {"none", "minimal", "minimum"} if effort else not anthropic
        thinking = {"type": "adaptive" if enabled else "disabled"}
        return {"thinking": thinking} if anthropic else {"extra_body": {"thinking": thinking}}
    # Flash always uses adaptive reasoning. Saved off/binary values fall back
    # to the vendor default effort rather than sending an unsupported mode.
    thinking = {"type": "adaptive"}
    result: dict[str, Any] = (
        {"thinking": thinking}
        if anthropic
        else {"extra_body": {"thinking": thinking, "reasoning_split": True}}
    )
    if effort in {"low", "medium", "high", "xhigh", "max"}:
        if anthropic:
            result["output_config"] = {"effort": effort}
        else:
            result["reasoning_effort"] = effort
    return result


def _spec_name(spec: Any, binding: str | None) -> str:
    return str(getattr(spec, "name", None) or binding or "").strip().lower()


def _matches(model_name: str, patterns: tuple[str, ...]) -> bool:
    model_lower = model_name.lower()
    return any(pattern.lower() in model_lower for pattern in patterns)


def _custom_thinking_style(model_name: str) -> tuple[str, tuple[str, ...]]:
    for patterns, style in _CUSTOM_MODEL_THINKING_STYLES:
        if _matches(model_name, patterns):
            return style, patterns
    # A model listed as thinking-off needs a style to express that in, but it
    # must NOT inherit the high-effort patterns used by pro/reasoner.
    if any(pattern in model_name.lower() for pattern in _THINKING_DISABLED_BY_DEFAULT_MODELS):
        return "thinking_type", ()
    return "", ()


def _disable_thinking_by_default(provider_name: str, model_name: str) -> bool:
    normalized = model_name.strip().lower()
    if any(pattern in normalized for pattern in _THINKING_DISABLED_BY_DEFAULT_MODELS):
        return True
    return any(
        provider_name == provider and pattern in normalized
        for provider, pattern in _THINKING_DISABLED_BY_DEFAULT
    )


def default_reasoning_effort_for(provider: str | None, model: str | None) -> str | None:
    """Return the implicit ``reasoning_effort`` for ``provider``/``model``, if any.

    Used by callers that don't go through :func:`build_openai_compatible_reasoning_kwargs`.
    Returns ``None`` when no default applies — the caller should leave the field
    unset in that case.

    The single source of truth is :data:`_PROVIDER_DEFAULT_OFF_PATTERNS` so every
    execution path agrees on which models need thinking disabled by default.
    """
    provider_name = (provider or "").strip().lower()
    off_patterns = _PROVIDER_DEFAULT_OFF_PATTERNS.get(provider_name)
    if off_patterns and _matches(model or "", off_patterns):
        if _matches(model or "", _MINIMAL_NOT_OFF_PATTERNS.get(provider_name, ())):
            return "minimal"
        return "none"
    return None


def thinking_off_effort_for(provider: str | None, model: str | None) -> str:
    """The lowest effort *model* actually accepts as "thinking off".

    ``"none"`` for almost everything, ``"minimal"`` for the families that
    answer HTTP 400 to it (#734). The rule already existed inside
    :func:`default_reasoning_effort_for`, but that function is consulted only
    when the caller says nothing — so a caller that asks for ``"none"``
    itself, as the reader-facing book blocks do, skipped the narrowing and got
    the 400 the table exists to prevent. Naming it here keeps it beside
    :data:`_MINIMAL_NOT_OFF_PATTERNS`, so adding a family to that table is
    still an obvious prompt to check this one.
    """
    provider_name = (provider or "").strip().lower()
    if _matches(model or "", _MINIMAL_NOT_OFF_PATTERNS.get(provider_name, ())):
        return "minimal"
    return "none"


def build_openai_compatible_reasoning_kwargs(
    *,
    spec: Any,
    binding: str | None,
    model: str | None,
    reasoning_effort: str | None,
) -> dict[str, Any]:
    """Return reasoning kwargs for OpenAI-compatible Chat Completions calls.

    Some OpenAI-compatible providers expose thinking controls through
    ``extra_body`` instead of the top-level ``reasoning_effort`` field.  Direct
    ``custom`` bindings need model-family inference because their endpoint is
    user supplied and therefore cannot be identified by provider name alone.
    """
    provider_name = _spec_name(spec, binding)
    model_name = model or ""
    if provider_name == "minimax":
        minimax = minimax_reasoning_kwargs(model_name, (reasoning_effort or "").strip().lower())
        if minimax is not None:
            return minimax
    if (
        provider_name == "openrouter"
        and model_name.lower() == "minimax/minimax-m3.1-flash:free"
        and reasoning_effort in {"none", "minimal", "minimum"}
    ):
        return {}
    if reasoning_effort == "":
        return {}
    thinking_style = str(getattr(spec, "thinking_style", "") or "")
    patterns = tuple(getattr(spec, "reasoning_model_patterns", ()) or ())

    if not thinking_style:
        thinking_style = _PROVIDER_THINKING_STYLES.get(provider_name, "")
    if not patterns:
        patterns = _PROVIDER_REASONING_PATTERNS.get(provider_name, ())
    # Infer style from the model id when the binding has none of its own —
    # covers ``custom`` endpoints and ``openai`` bindings aimed at DeepSeek /
    # Qwen gateways (#1058).
    if not thinking_style:
        custom_style, custom_patterns = _custom_thinking_style(model_name)
        if custom_style:
            thinking_style = custom_style
            if not patterns:
                patterns = custom_patterns

    # Qwen Instruct variants do not implement thinking controls, even when a
    # caller explicitly requests an effort. Do not replace the unsupported
    # native parameter with the equally unsupported top-level effort field.
    model_tokens = model_name.lower().replace("_", "-").split("-")
    if thinking_style == "enable_thinking" and "instruct" in model_tokens:
        return {}

    resolved_effort = reasoning_effort
    if resolved_effort is None:
        if patterns and _matches(model_name, patterns):
            resolved_effort = "high"
        else:
            resolved_effort = default_reasoning_effort_for(provider_name, model_name)
    elif str(resolved_effort).strip().lower() == "none":
        # An explicit "off" is subject to the same vendor limit as an inferred
        # one — see ``thinking_off_effort_for``.
        resolved_effort = thinking_off_effort_for(provider_name, model_name)

    semantic_effort: str | None = None
    if isinstance(resolved_effort, str):
        semantic_effort = resolved_effort.lower()
        if semantic_effort == "minimum":
            semantic_effort = "minimal"

    kwargs: dict[str, Any] = {}
    # OpenRouter exposes a provider-neutral reasoning object.  Keep the
    # explicit off request and exclude any reasoning trace from the response;
    # this is important for models whose gateway response otherwise uses the
    # ``reasoning`` field alongside ``content``.
    if provider_name == "openrouter" and semantic_effort == "none":
        kwargs["extra_body"] = {
            "reasoning": {"effort": "none", "exclude": True},
        }
    if resolved_effort:
        suppress_top_level = bool(
            thinking_style
            and (semantic_effort in _THINKING_OFF_EFFORTS or thinking_style == "enable_thinking")
        )
        if not suppress_top_level and not (
            provider_name == "openrouter" and semantic_effort == "none"
        ):
            kwargs["reasoning_effort"] = resolved_effort

    if (
        thinking_style
        and resolved_effort is not None
        and not (provider_name == "openrouter" and semantic_effort == "none")
    ):
        thinking_enabled = semantic_effort not in _THINKING_OFF_EFFORTS
        extra = _THINKING_STYLE_MAP.get(thinking_style, lambda _enabled: None)(thinking_enabled)
        if extra:
            kwargs.setdefault("extra_body", {}).update(extra)
    elif thinking_style and _disable_thinking_by_default(provider_name, model_name):
        extra = _THINKING_STYLE_MAP.get(thinking_style, lambda _enabled: None)(False)
        if extra:
            kwargs.setdefault("extra_body", {}).update(extra)

    return kwargs


__all__ = [
    "RETRY_REASONING_EFFORT",
    "build_openai_compatible_reasoning_kwargs",
    "default_reasoning_effort_for",
]