Skip to content

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

8.6 KB
Raw Blame
"""Provider-error classifiers used by retry and graceful-degradation paths."""

from __future__ import annotations

import re

import httpx

from .exceptions import LLMProviderTransportError, LLMTimeoutError


def _exception_chain(exc: Exception):
    """Yield an exception and its wrapped causes without looping forever."""
    pending = [exc]
    seen: set[int] = set()
    while pending:
        current = pending.pop()
        if id(current) in seen:
            continue
        seen.add(id(current))
        yield current
        nested = getattr(current, "exceptions", ())
        if isinstance(nested, tuple):
            pending.extend(item for item in nested if isinstance(item, Exception))
        cause = current.__cause__ or current.__context__
        if isinstance(cause, Exception):
            pending.append(cause)


_MAX_LOGGED_ERROR_CHARS = 2000


def logged_error_text(exc: Exception) -> str:
    """``error_text`` bounded for a log line.

    The compat predicates only scan this text, but a log line is different:
    ``data/user/logs/deeptutor.jsonl`` is what a user is asked to attach to a
    bug report, and some providers echo the rejected request back — the tool
    schemas, occasionally the messages themselves. The parameter a provider
    objects to is always near the front, so cap it rather than ship an
    unbounded copy of the request into a file destined for a public issue.
    """
    text = error_text(exc)
    if len(text) <= _MAX_LOGGED_ERROR_CHARS:
        return text
    dropped = len(text) - _MAX_LOGGED_ERROR_CHARS
    return f"{text[:_MAX_LOGGED_ERROR_CHARS]}… (+{dropped} chars)"


def error_text(exc: Exception) -> str:
    """Return the best available lowercase provider error body."""
    response = getattr(exc, "response", None)
    body = (
        getattr(exc, "body", None)
        or getattr(exc, "doc", None)
        or getattr(response, "text", None)
        or getattr(exc, "message", None)
        or str(exc)
    )
    return str(body).lower()


def is_stream_options_unsupported(exc: Exception) -> bool:
    """Whether a provider rejected OpenAI's ``stream_options`` parameter."""
    text = error_text(exc)
    return any(
        marker in text
        for marker in (
            "stream_options",
            "stream options",
            "unknown parameter",
            "unrecognized request argument",
            "unsupported parameter",
            "extra inputs are not permitted",
            "unexpected keyword",
        )
    )


def is_response_format_unsupported(exc: Exception) -> bool:
    """Whether a provider rejected OpenAI's ``response_format`` parameter.

    Seen from LM Studio + Gemma (``'response_format.type' must be 'json_schema'
    or 'text'``) and DashScope (``'json_object' is not supported by this
    model``). One predicate for every execution path, so the graceful
    drop-and-retry behaves the same wherever the request was made.
    """
    text = error_text(exc)
    if "response_format" not in text and "response format" not in text:
        return False
    return any(
        marker in text
        for marker in (
            "not supported",
            "unsupported",
            "json_object",
            "json_schema",
            "not valid",
            "must be 'json_schema' or 'text'",
            "specified for 'response_format.type' is not valid",
        )
    )


def is_forced_tool_choice_unsupported(exc: Exception) -> bool:
    """Whether a provider rejected *naming* the tool it must call.

    Distinct from :func:`is_tool_schema_unsupported`: the provider is happy to
    receive tools, it just will not be told which one to use. DeepSeek V4 with
    thinking enabled answers ``"Thinking mode does not support this
    tool_choice"`` — so Ask Questions, whose whole first round is a forced
    ``ask_user``, failed the turn outright. Downgrading to ``"required"``
    keeps "you must call a tool" and lets the loop's own fallback wrap the
    model's question into a local card if it still writes prose.

    A malformed choice is deliberately not matched: a shape the endpoint
    cannot deserialize is a bug on our side to fix, not a capability to
    degrade around.
    """
    text = error_text(exc)
    if "tool_choice" not in text and "tool choice" not in text:
        return False
    if "missing field" in text or "failed to deserialize" in text:
        return False
    return any(
        marker in text
        for marker in (
            "does not support",
            "not supported",
            "unsupported",
            "not allowed",
            "cannot be used",
        )
    )


def is_tool_schema_unsupported(exc: Exception) -> bool:
    """Whether a provider rejected native tool/function-calling schemas.

    Deliberately avoids matching the bare substring ``\"tool\"``. Any 400 that
    merely mentions tools — or echoes the outbound request body — used to trip
    the chat loop's silent strip-and-retry path and leave the model answering
    in prose with no tools (#708). Keep markers tied to schema/parameter
    rejections; ``logged_error_text`` already captures unknowns for follow-up.
    """
    text = error_text(exc)
    rejected_schema = any(
        marker in text
        for marker in (
            "function_declaration",
            "function declaration",
            "function_declarations",
            "tool_choice",
            "parameters.properties",
            "unsupported parameter: tools",
            "unknown parameter: tools",
            "unknown parameter 'tools'",
            'unknown parameter "tools"',
            "unexpected keyword argument 'tools'",
            "tools is not supported",
            "tools are not supported",
            "does not support tools",
            "does not support function calling",
            "function calling is not supported",
            "tool use is not supported",
            "tool calling is not supported",
        )
    )
    if rejected_schema:
        return True
    not_found = "404_not_found" in text or "404 not_found" in text
    return not_found and any(
        marker in text
        for marker in (
            "tool schema",
            "function schema",
            "function declaration",
            "function_declaration",
            "function calling",
            "tool calling",
            "tool_choice",
        )
    )


def is_image_input_unsupported(exc: Exception) -> bool:
    """Whether a provider or model rejected multimodal message content."""
    text = error_text(exc)
    # GLM's dotted-path validation only indicates unsupported image content
    # when the message content type explicitly permits text and nothing else.
    text_only_content = re.search(
        r"messages(?:\[\d+\])?\.content(?:\[\d+\])?\.type"
        r"[^\n]*取值范围\s*[::]?\s*\[\s*['\"]text['\"]\s*\]",
        text,
    )
    return bool(text_only_content) or any(
        marker in text
        for marker in (
            "image",
            "vision",
            "multimodal",
            "image_url",
            "content type",
            "must be a string",
            "expected a string",
            "expected string",
            "invalid type for 'messages",
        )
    )


def is_transient_transport_error(exc: Exception) -> bool:
    """Return whether retrying can recover a provider transport failure.

    Authentication, rate-limit, HTTP-status and response-shape errors are
    intentionally excluded. OpenAI-compatible clients wrap httpx/httpcore
    failures, so the complete exception chain is inspected.
    """
    for current in _exception_chain(exc):
        if isinstance(
            current,
            (
                httpx.TransportError,
                LLMProviderTransportError,
                LLMTimeoutError,
                TimeoutError,
                ConnectionError,
            ),
        ):
            return True
        error_type = type(current)
        module = error_type.__module__
        name = error_type.__name__
        if module.startswith("openai") and name in {
            "APIConnectionError",
            "APITimeoutError",
        }:
            return True
        if module.startswith("httpcore") and name in {
            "ConnectError",
            "ConnectTimeout",
            "ReadError",
            "ReadTimeout",
            "RemoteProtocolError",
            "WriteError",
            "WriteTimeout",
        }:
            return True
    return False


__all__ = [
    "error_text",
    "is_image_input_unsupported",
    "is_response_format_unsupported",
    "is_stream_options_unsupported",
    "is_transient_transport_error",
    "is_forced_tool_choice_unsupported",
    "is_tool_schema_unsupported",
]