Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

36.8 KB
Raw Blame
"""Tests for openai_compat_errors helper and its integration with
``ErrorReporter`` (#3878).

These tests construct ``openai`` / ``httpx`` exceptions directly (no network
calls) and check that the rewritten messages and ``Error type: <code>`` tokens
match the spec in the issue.
"""

from __future__ import annotations

import sys

import httpx
import openai
import pytest
from openai import (
    APIConnectionError,
    APITimeoutError,
    AuthenticationError,
    BadRequestError,
    NotFoundError,
    PermissionDeniedError,
    RateLimitError,
)

from local_deep_research.error_handling.error_reporter import (
    ErrorCategory,
    ErrorReporter,
)
from local_deep_research.error_handling.openai_compat_errors import (
    _strip_credentials,
    _walk_cause,
    friendly_openai_compatible_error,
    is_openai_compat_runtime_error,
)


def _req(
    url: str = "http://localhost:9999/v1/chat/completions",
) -> httpx.Request:
    return httpx.Request("POST", url)


def _resp(status: int, body: dict | None = None) -> httpx.Response:
    return httpx.Response(status, request=_req(), json=body or {})


# ---------------------------------------------------------------------------
# Acceptance criterion 4: redaction
# ---------------------------------------------------------------------------


class TestStripCredentials:
    def test_strips_userinfo(self):
        assert (
            _strip_credentials("https://user:[email protected]/v1")
            == "https://example.com/v1"
        )

    def test_strips_userinfo_keeps_port(self):
        assert (
            _strip_credentials("https://u:[email protected]:8443/v1")
            == "https://example.com:8443/v1"
        )

    def test_no_userinfo_passes_through(self):
        assert (
            _strip_credentials("http://localhost:1234/v1")
            == "http://localhost:1234/v1"
        )

    def test_empty_returns_unknown_marker(self):
        assert _strip_credentials("") == "<unknown>"
        assert _strip_credentials(None) == "<unknown>"

    @pytest.mark.parametrize(
        "name",
        [
            "api_key",
            "API_KEY",
            "apikey",
            "key",
            "Key",
            "x-api-key",
            "subscription-key",
            "token",
            "access_token",
            "refresh_token",
            "secret",
            "client_secret",
            "password",
        ],
    )
    def test_redacts_credential_query_values(self, name):
        out = _strip_credentials(f"https://gw.example/v1?{name}=sk-leak123")
        assert "sk-leak123" not in out
        assert out == f"https://gw.example/v1?{name}=REDACTED"

    def test_query_redaction_keeps_other_params_and_strips_userinfo(self):
        out = _strip_credentials(
            "https://u:[email protected]:8443/v1"
            "?api-version=2024-10-01&api_key=sk-leak123&model=m"
        )
        assert out == (
            "https://gw.example:8443/v1"
            "?api-version=2024-10-01&api_key=REDACTED&model=m"
        )

    def test_query_redaction_does_not_touch_lookalike_names(self):
        """Only whole names / trailing segments match: ``monkey`` and
        ``keyboard`` are not credentials."""
        url = "https://gw.example/v1?monkey=a&keyboard=b"
        assert _strip_credentials(url) == url

    def test_query_redaction_without_netloc(self):
        """A scheme-less base URL has no parsed netloc; its query is still
        redacted."""
        out = _strip_credentials("localhost:1234/v1?key=sk-leak123")
        assert "sk-leak123" not in out

    @pytest.mark.parametrize(
        "name",
        [
            "sig",
            "signature",
            "sas",
            "auth",
            "authorization",
            "bearer",
            "pwd",
            "passwd",
            "x-amz-signature",
            "X-Goog-Signature",
            "code",
            "my_token",
            "my_key",
            "my_secret",
            "custom-key",
        ],
    )
    def test_redacts_extended_credential_names(self, name):
        out = _strip_credentials(f"https://gw.example/v1?{name}=sk-leak123")
        assert out == f"https://gw.example/v1?{name}=REDACTED"

    @pytest.mark.parametrize(
        "name", ["monkey", "keyboard", "tokenizer", "error_code", "oauth"]
    )
    def test_lookalike_names_are_not_redacted(self, name):
        url = f"https://gw.example/v1?{name}=visible"
        assert _strip_credentials(url) == url

    def test_semicolon_separates_query_params(self):
        out = _strip_credentials(
            "https://gw.example/v1?a=1;api_key=sk-leak123;b=2"
        )
        assert out == "https://gw.example/v1?a=1;api_key=REDACTED;b=2"

    def test_fragment_params_are_redacted(self):
        out = _strip_credentials(
            "https://gw.example/v1#access_token=sk-leak123&state=x"
        )
        assert out == "https://gw.example/v1#access_token=REDACTED&state=x"

    def test_path_params_are_redacted(self):
        out = _strip_credentials(
            "https://gw.example/v1;api_key=sk-leak123/chat;v=2"
        )
        assert out == "https://gw.example/v1;api_key=REDACTED/chat;v=2"

    def test_long_bare_query_item_is_redacted(self):
        out = _strip_credentials(
            "https://gw.example/v1?sk-leak1234567890abcdef&x=1"
        )
        assert "sk-leak1234567890abcdef" not in out
        assert out == "https://gw.example/v1?REDACTED&x=1"

    def test_short_bare_query_item_is_kept(self):
        """Only value-less items of 17+ characters are treated as bare
        credentials; a short flag stays legible."""
        url = "https://gw.example/v1?debug&x=1"
        assert _strip_credentials(url) == url

    def test_invalid_port_does_not_raise(self):
        """``SplitResult.port`` raises on an out-of-range port. The helper
        runs inside an error handler, so it never parses the port: the
        authority is kept verbatim (minus userinfo) and nothing raises."""
        assert _strip_credentials("http://u:[email protected]:99999/v1") == (
            "http://h.example:99999/v1"
        )

    def test_query_key_redacted_in_friendly_message(self):
        """End to end: the rewritten message never carries the key."""
        exc = APIConnectionError(message="conn", request=_req())
        msg = friendly_openai_compatible_error(
            exc,
            provider="openai_endpoint",
            base_url="https://gw.example/v1?api_key=sk-leak123",
            model="m",
        )
        assert "sk-leak123" not in msg
        assert "https://gw.example/v1?api_key=REDACTED" in msg


# ---------------------------------------------------------------------------
# Cause-chain walker
# ---------------------------------------------------------------------------


class TestWalkCause:
    def test_returns_input_when_no_cause(self):
        exc = RuntimeError("flat")
        assert _walk_cause(exc) is exc

    def test_walks_to_deepest(self):
        root = APIConnectionError(message="conn", request=_req())
        try:
            try:
                raise root
            except Exception as e:
                raise RuntimeError("middle") from e
        except RuntimeError as e:
            try:
                raise ValueError("outer") from e
            except ValueError as outer:
                assert _walk_cause(outer) is root

    def test_cycle_safe(self):
        a = RuntimeError("a")
        b = RuntimeError("b")
        a.__cause__ = b
        b.__cause__ = a
        # Must terminate; the deepest reached before cycle is detected wins.
        assert _walk_cause(a) in (a, b)


# ---------------------------------------------------------------------------
# Acceptance criterion 1: connection-refused naming
# ---------------------------------------------------------------------------


class TestConnectionRefused:
    def test_openai_api_connection_error(self):
        exc = APIConnectionError(message="conn", request=_req())
        msg = friendly_openai_compatible_error(
            exc,
            provider="lmstudio",
            base_url="http://localhost:9999/v1",
            model="qwen2.5-7b",
        )
        assert "Cannot reach lmstudio at http://localhost:9999/v1" in msg
        assert "Error type: openai_connection_refused" in msg
        assert "Details:" in msg

    def test_httpx_connect_error_through_langchain_wrapper(self):
        root = httpx.ConnectError("All connection attempts failed")
        try:
            try:
                raise root
            except Exception as e:
                raise RuntimeError("LangChain wrapped") from e
        except RuntimeError as wrapped:
            msg = friendly_openai_compatible_error(
                wrapped,
                provider="openai_endpoint",
                base_url="http://localhost:1234/v1",
                model="any-model",
            )
        assert "Cannot reach openai_endpoint at http://localhost:1234/v1" in msg
        assert "Error type: openai_connection_refused" in msg


# ---------------------------------------------------------------------------
# Acceptance criterion 2: model-not-found naming
# ---------------------------------------------------------------------------


class TestModelNotFound:
    def test_notfound_names_provider_url_model(self):
        exc = NotFoundError(
            message="model 'typo-model' does not exist",
            response=_resp(404),
            body=None,
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="lmstudio",
            base_url="http://localhost:1234/v1",
            model="typo-model",
        )
        assert "lmstudio at http://localhost:1234/v1" in msg
        assert "'typo-model'" in msg
        assert "Error type: openai_model_not_found" in msg


# ---------------------------------------------------------------------------
# Acceptance criterion 3: auth naming
# ---------------------------------------------------------------------------


class TestAuth:
    def test_auth_names_provider_and_url(self):
        exc = AuthenticationError(
            message="invalid api key",
            response=_resp(401),
            body=None,
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="openai_endpoint",
            base_url="https://api.openai.com/v1",
            model="gpt-4o-mini",
        )
        assert "openai_endpoint rejected the API key" in msg
        assert "https://api.openai.com/v1" in msg
        assert "Error type: openai_auth" in msg


# ---------------------------------------------------------------------------
# Acceptance criterion 4: userinfo never leaks into the surfaced message
# ---------------------------------------------------------------------------


class TestNoCredentialLeak:
    def test_userinfo_stripped_from_friendly_text(self):
        exc = APIConnectionError(message="conn", request=_req())
        leaked_key = "supersecretkey1234567890"
        msg = friendly_openai_compatible_error(
            exc,
            provider="openai_endpoint",
            base_url=f"https://u:{leaked_key}@hosted.example.com/v1",
            model="m",
        )
        # The userinfo segment must NOT survive into the friendly portion of
        # the message. We split on the Details: suffix because the original
        # exception text is preserved there verbatim (and in practice does not
        # carry the URL, but if a future exception did, we'd still want this
        # test to guard the rewritten half).
        friendly_half = msg.split("| Details:")[0]
        assert leaked_key not in friendly_half
        assert "u:" not in friendly_half


# ---------------------------------------------------------------------------
# Acceptance criterion 5: ErrorReporter category mapping
# ---------------------------------------------------------------------------


class TestErrorReporterCategorisation:
    @pytest.fixture
    def reporter(self) -> ErrorReporter:
        return ErrorReporter()

    @pytest.mark.parametrize(
        ("token", "expected"),
        [
            ("openai_connection_refused", ErrorCategory.CONNECTION_ERROR),
            ("openai_timeout", ErrorCategory.CONNECTION_ERROR),
            ("openai_auth", ErrorCategory.MODEL_ERROR),
            ("openai_permission_denied", ErrorCategory.MODEL_ERROR),
            ("openai_model_not_found", ErrorCategory.MODEL_ERROR),
            ("openai_bad_request", ErrorCategory.MODEL_ERROR),
            ("openai_unknown", ErrorCategory.MODEL_ERROR),
            ("openai_rate_limit", ErrorCategory.RATE_LIMIT_ERROR),
        ],
    )
    def test_token_to_category(
        self, reporter: ErrorReporter, token: str, expected: ErrorCategory
    ):
        message = f"Some friendly text. (Error type: {token}) | Details: boom"
        assert reporter.categorize_error(message) == expected


# ---------------------------------------------------------------------------
# Helper-detector
# ---------------------------------------------------------------------------


class TestIsOpenAICompatRuntimeError:
    def test_yes_for_openai_class(self):
        exc = APITimeoutError(request=_req())
        assert is_openai_compat_runtime_error(exc) is True

    def test_yes_for_wrapped_openai_class(self):
        root = NotFoundError(message="missing", response=_resp(404), body=None)
        try:
            try:
                raise root
            except Exception as e:
                raise RuntimeError("wrap") from e
        except RuntimeError as wrapped:
            assert is_openai_compat_runtime_error(wrapped) is True

    def test_yes_for_httpx_connect_error(self):
        assert (
            is_openai_compat_runtime_error(httpx.ConnectError("nope")) is True
        )

    def test_no_for_unrelated_exception(self):
        assert is_openai_compat_runtime_error(ValueError("unrelated")) is False


# ---------------------------------------------------------------------------
# Additional class coverage (the four non-AC tokens still need to round-trip)
# ---------------------------------------------------------------------------


class TestAdditionalDispatch:
    def test_timeout(self):
        exc = APITimeoutError(request=_req())
        msg = friendly_openai_compatible_error(
            exc,
            provider="vllm",
            base_url="http://localhost:8000/v1",
            model="llama-3-8b",
        )
        assert "Error type: openai_timeout" in msg
        assert "did not respond in time" in msg

    def test_permission_denied(self):
        exc = PermissionDeniedError(
            message="forbidden", response=_resp(403), body=None
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="openai_endpoint",
            base_url="https://api.example.com/v1",
            model="gpt-4o",
        )
        assert "Error type: openai_permission_denied" in msg
        assert "'gpt-4o'" in msg

    def test_bad_request(self):
        exc = BadRequestError(message="bad", response=_resp(400), body=None)
        msg = friendly_openai_compatible_error(
            exc,
            provider="lmstudio",
            base_url="http://localhost:1234/v1",
            model="m",
        )
        assert "Error type: openai_bad_request" in msg

    def test_falls_back_to_unknown_for_unrelated(self):
        msg = friendly_openai_compatible_error(
            ValueError("just a value error"),
            provider="lmstudio",
            base_url="http://localhost:1234/v1",
            model="m",
        )
        assert "Error type: openai_unknown" in msg
        assert "Details: just a value error" in msg


# ---------------------------------------------------------------------------
# Edge cases pinned by this PR
# ---------------------------------------------------------------------------


class TestDispatchOrderingTimeoutBeforeConnection:
    """``openai.APITimeoutError`` subclasses ``APIConnectionError`` in
    openai>=1.x, so the dispatch table at openai_compat_errors.py:87 must
    check the timeout branch BEFORE the connection branch — otherwise
    every timeout would be mislabelled as ``openai_connection_refused``.

    The comment at lines 85-86 documents this constraint; this test pins it.

    Mutation: swap the two ``if`` blocks (lines 87-92 and 95-100) so the
    connection branch runs first, and ``APITimeoutError`` instances get the
    wrong token.
    """

    def test_timeout_subclass_dispatches_to_timeout_branch_not_connection(
        self,
    ):
        # Sanity: confirm the subclassing assumption that motivates the
        # ordering. If openai breaks this hierarchy in a future major
        # release, this assertion fails first and the test author can
        # decide whether the ordering rule still applies.
        assert issubclass(APITimeoutError, APIConnectionError)

        exc = APITimeoutError(request=_req())
        msg = friendly_openai_compatible_error(
            exc,
            provider="lmstudio",
            base_url="http://localhost:1234/v1",
            model="m",
        )
        assert "Error type: openai_timeout" in msg
        assert "Error type: openai_connection_refused" not in msg


class TestWalkCauseChainPreference:
    """``_walk_cause`` traverses ``cur.__cause__ or cur.__context__`` —
    i.e. explicit ``raise X from Y`` chains win over implicit
    ``__context__`` chains. Pins the preference.

    Mutation: swap to ``cur.__context__ or cur.__cause__`` at
    openai_compat_errors.py:60 — the test would point at the wrong root.
    """

    def test_cause_preferred_over_context_when_both_set(self):
        explicit_root = APIConnectionError(message="conn", request=_req())
        implicit_root = RuntimeError("implicit context")

        wrapper = RuntimeError("wrapper")
        wrapper.__cause__ = explicit_root
        wrapper.__context__ = implicit_root

        assert _walk_cause(wrapper) is explicit_root


class TestStripCredentialsEdgeCases:
    def test_ipv6_host_brackets_preserved(self):
        # ``urlparse`` returns ``hostname`` without brackets; the
        # implementation reassembles ``netloc`` and must re-add the
        # brackets, or the resulting URL is unparseable downstream —
        # ``http://::1:8080/`` is ambiguous about where the host ends
        # and the port begins.
        result = _strip_credentials("http://[::1]:8080/v1")
        assert result == "http://[::1]:8080/v1"

    def test_userinfo_stripped_with_ipv6_host(self):
        # Combine userinfo and IPv6 host. The key must be removed AND
        # the brackets must survive.
        result = _strip_credentials(
            "http://user:secret-key-12345@[::1]:8080/v1"
        )
        assert "secret-key-12345" not in result
        assert "user:" not in result
        assert result == "http://[::1]:8080/v1"

    def test_url_with_no_netloc_passed_through(self):
        # A bare path (no scheme/netloc) is returned as-is. The function
        # short-circuits at ``if not parsed.netloc:``. Worth pinning so
        # someone "fixing" the path-only case doesn't break it.
        assert _strip_credentials("/v1/chat/completions") == (
            "/v1/chat/completions"
        )


class TestFriendlyErrorNoneArgs:
    """``friendly_openai_compatible_error`` uses ``provider or
    "<unknown provider>"`` and ``model or "<unspecified>"`` to surface a
    legible message even when the caller doesn't know the values. Pin
    both placeholders so future refactors don't drop them.
    """

    def test_none_provider_replaced_with_placeholder(self):
        msg = friendly_openai_compatible_error(
            APIConnectionError(message="conn", request=_req()),
            provider=None,
            base_url="http://localhost:9999/v1",
            model="m",
        )
        assert "<unknown provider>" in msg

    def test_none_model_replaced_with_placeholder(self):
        msg = friendly_openai_compatible_error(
            NotFoundError(
                message="missing",
                response=_resp(404),
                body=None,
            ),
            provider="lmstudio",
            base_url="http://localhost:1234/v1",
            model=None,
        )
        assert "<unspecified>" in msg


# ---------------------------------------------------------------------------
# RateLimitError dispatch (follow-up to #3878)
# ---------------------------------------------------------------------------


class TestRateLimitErrorDispatch:
    """``openai.RateLimitError`` subclasses ``APIError`` via
    ``APIStatusError``.  It must dispatch to ``openai_rate_limit`` (mapped to
    RATE_LIMIT_ERROR) instead of falling through to the ``openai_unknown``
    catch-all (mapped to MODEL_ERROR).

    Without the explicit branch, a 429 is mis-categorised as MODEL_ERROR,
    producing the wrong suggestions and skipping the API_QUOTA_WARNING
    notification.
    """

    def test_rate_limit_dispatches_to_rate_limit_token(self):
        exc = RateLimitError(
            message="Rate limit exceeded",
            response=_resp(429),
            body=None,
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="openrouter",
            base_url="https://openrouter.ai/api/v1",
            model="gpt-4o",
        )
        assert "Error type: openai_rate_limit" in msg
        assert "Error type: openai_unknown" not in msg
        assert "rate-limited" in msg

    def test_rate_limit_categorised_as_rate_limit_error(self):
        reporter = ErrorReporter()
        message = (
            "openrouter at https://openrouter.ai/api/v1 rate-limited the "
            "request for model 'gpt-4o'. (Error type: openai_rate_limit) "
            "| Details: Error code: 429"
        )
        assert (
            reporter.categorize_error(message) == ErrorCategory.RATE_LIMIT_ERROR
        )


# ---------------------------------------------------------------------------
# #5888: the walk overshot the SDK exception, and the transport package moved
# ---------------------------------------------------------------------------


def _chain(*excs: BaseException) -> BaseException:
    """Link ``excs`` outermost-first through ``__cause__``, return the head."""
    for outer, inner in zip(excs, excs[1:]):
        outer.__cause__ = inner
    return excs[0]


def _sdk_transport_module():
    """Return the HTTP package the installed ``openai`` sends requests through.

    Read off the public ``DefaultHttpxClient`` so this stays independent of the
    module under test: ``openai`` 2.x subclasses ``httpx.Client`` and 3.x
    subclasses ``httpx2.Client``.
    """
    for base in openai.DefaultHttpxClient.__mro__[1:]:
        module = sys.modules.get(base.__module__.split(".")[0])
        if module is not None and hasattr(module, "ConnectError"):
            return module
    raise AssertionError("could not identify the openai transport package")


class TestWalkCauseStopsAtTheSDKException:
    """The SDK re-raises transport failures and the transport re-raises from
    ``httpcore`` or a bare ``OSError``, so the end of a real cause chain names
    neither the provider nor the failure kind. The chains below are the ones
    observed driving ``openai.OpenAI`` against a refused port, a socket that
    accepts and never answers, and an endpoint returning 401.

    Mutation: drop the ``_is_dispatchable`` check from the walk and every test
    here reports ``openai_unknown``.
    """

    def test_connection_refused_names_the_provider(self):
        exc = _chain(
            APIConnectionError(message="Connection error.", request=_req()),
            httpx.ConnectError("All connection attempts failed"),
            ConnectionRefusedError(111, "Connection refused"),
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="lmstudio",
            base_url="http://localhost:1234/v1",
            model="qwen3-8b",
        )
        assert "Error type: openai_connection_refused" in msg
        assert "Cannot reach lmstudio" in msg

    def test_read_timeout_reports_the_timeout_token(self):
        exc = _chain(
            APITimeoutError(request=_req()),
            httpx.ReadTimeout("timed out"),
            TimeoutError("timed out"),
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="vllm",
            base_url="http://localhost:8000/v1",
            model="llama-3-8b",
        )
        assert "Error type: openai_timeout" in msg
        assert "did not respond in time" in msg

    def test_auth_failure_survives_its_transport_wrapper(self):
        exc = _chain(
            AuthenticationError(
                message="bad key", response=_resp(401), body=None
            ),
            httpx.HTTPStatusError("401", request=_req(), response=_resp(401)),
        )
        msg = friendly_openai_compatible_error(
            exc,
            provider="openrouter",
            base_url="https://openrouter.ai/api/v1",
            model="gpt-4o",
        )
        assert "Error type: openai_auth" in msg
        assert "rejected the API key" in msg

    def test_detector_sees_the_wrapped_sdk_error(self):
        exc = _chain(
            APIConnectionError(message="Connection error.", request=_req()),
            httpx.ConnectError("All connection attempts failed"),
            ConnectionRefusedError(111, "Connection refused"),
        )
        assert is_openai_compat_runtime_error(exc) is True


class TestTransportPackageOfTheInstalledSDK:
    """``openai`` 3.x moved from ``httpx`` to ``httpx2``, so the transport
    exceptions it raises are not instances of the ``httpx`` classes this
    module imports, and both packages can be installed side by side.

    Mutation: match ``httpx.ConnectError`` alone and both tests fail under
    ``openai`` 3.x while still passing under 2.x.
    """

    def test_connect_error_is_recognised(self):
        transport = _sdk_transport_module()
        assert (
            is_openai_compat_runtime_error(transport.ConnectError("nope"))
            is True
        )

    def test_read_timeout_reports_the_timeout_token(self):
        transport = _sdk_transport_module()
        msg = friendly_openai_compatible_error(
            transport.ReadTimeout("slow"),
            provider="llamacpp",
            base_url="http://localhost:8080/v1",
            model="mistral",
        )
        assert "Error type: openai_timeout" in msg


class TestErrorRewriteProviderSet:
    """Pin the provider set that opts into the friendly error rewrite.

    research_service rewrites OpenAI-compatible runtime failures only for
    providers in ``_OPENAI_COMPAT_RUNTIME_ERROR_PROVIDERS``; a provider
    dropped from the set silently falls back to the generic status-code
    rewrite. Every OpenAI-compatible provider (including newly added ones
    like QwenCloud) must stay enumerated here.
    """

    def test_rewrite_set_membership_is_pinned(self):
        from local_deep_research.web.services.research_service import (
            _OPENAI_COMPAT_RUNTIME_ERROR_PROVIDERS,
        )

        expected = frozenset(
            {
                "openai_endpoint",
                "lmstudio",
                "llamacpp",
                "openai",
                "openrouter",
                "requesty",
                "orcarouter",
                "atlascloud",
                "qwen",
                "deepseek",
                "google",
                "ionos",
                "xai",
            }
        )
        actual = _OPENAI_COMPAT_RUNTIME_ERROR_PROVIDERS
        assert actual == expected, (
            f"error-rewrite provider set drifted: "
            f"missing={sorted(expected - actual)} "
            f"unexpected={sorted(actual - expected)}. Update both the set in "
            f"research_service.py and this pin (and add a changelog entry if "
            f"a provider was removed)."
        )

    def test_every_discovered_openai_compat_provider_is_in_rewrite_set(self):
        """Stronger contract: no discovered cloud provider that inherits the
        stock ``OpenAICompatibleProvider.create_llm`` (i.e., talks through
        ChatOpenAI and raises OpenAI-compatible client errors) may ship
        without its friendly error rewrite. Providers that override
        ``create_llm`` with a different client (Anthropic's Messages SDK,
        Ollama's native client) raise different exception types and are
        excluded. Guards future provider additions from forgetting this
        registration point."""
        from local_deep_research.llm.providers.openai_base import (
            OpenAICompatibleProvider,
        )
        from local_deep_research.llm.providers.auto_discovery import (
            discover_providers,
        )
        from local_deep_research.web.services.research_service import (
            _OPENAI_COMPAT_RUNTIME_ERROR_PROVIDERS,
        )

        discovered = discover_providers()
        assert discovered, "provider auto-discovery returned nothing"
        missing = []
        checked = 0
        for key, info in discovered.items():
            cls = info.provider_class
            if not issubclass(cls, OpenAICompatibleProvider):
                continue
            if not cls.is_cloud:
                continue
            uses_stock_openai_client = (
                getattr(cls.create_llm, "__func__", None)
                is OpenAICompatibleProvider.create_llm.__func__
            )
            if not uses_stock_openai_client:
                continue
            checked += 1
            if key.lower() not in _OPENAI_COMPAT_RUNTIME_ERROR_PROVIDERS:
                missing.append(key.lower())
        # Guard against a silent regression that makes the comparator match
        # nothing (the check would then pass vacuously).
        assert checked >= 5, (
            f"only {checked} providers reached the stock-client check; "
            f"the discriminator is likely broken"
        )
        assert not missing, (
            f"Discovered cloud OpenAI-compatible providers missing from the "
            f"error-rewrite set: {sorted(missing)}"
        )

    def test_rewrite_base_url_falls_back_to_provider_default(self):
        """Hardcoded-endpoint providers must name their real base URL in the
        rewritten message, not "<unknown>"."""
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        assert _resolve_error_rewrite_base_url("qwen", None) == (
            "https://maas.qwencloudapi.com/compatible-mode/v1"
        )
        assert _resolve_error_rewrite_base_url("deepseek", None) == (
            "https://api.deepseek.com/v1"
        )

    def test_rewrite_base_url_ignores_custom_endpoint_for_other_providers(
        self,
    ):
        """``custom_endpoint`` is ``llm.openai_endpoint.url`` (default: the
        OpenRouter URL), which chat/follow-up callers pass regardless of
        provider. For a hardcoded-endpoint provider it must not replace the
        URL the client actually used."""
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        assert _resolve_error_rewrite_base_url(
            "qwen", "https://openrouter.ai/api/v1"
        ) == ("https://maas.qwencloudapi.com/compatible-mode/v1")
        assert _resolve_error_rewrite_base_url(
            "deepseek", "https://openrouter.ai/api/v1"
        ) == ("https://api.deepseek.com/v1")

    def test_rewrite_base_url_stale_custom_endpoint_does_not_mask_url_setting(
        self,
    ):
        """LM Studio with its own configured URL plus a stale
        llm.openai_endpoint.url must report the LM Studio URL."""
        from local_deep_research.settings.manager import (
            SnapshotSettingsContext,
        )
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        ctx = SnapshotSettingsContext(
            {
                "llm.lmstudio.url": "http://nas:1234/v1",
                "llm.openai_endpoint.url": "https://openrouter.ai/api/v1",
            }
        )
        assert (
            _resolve_error_rewrite_base_url(
                "lmstudio", "https://openrouter.ai/api/v1", ctx
            )
            == "http://nas:1234/v1"
        )

    def test_rewrite_base_url_openai_endpoint_uses_custom_endpoint(self):
        """For the openai_endpoint provider the per-run custom endpoint IS
        the client's base URL (any casing of the provider id)."""
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        for provider in ("openai_endpoint", "OPENAI_ENDPOINT"):
            assert (
                _resolve_error_rewrite_base_url(
                    provider, "http://gateway.example/v1"
                )
                == "http://gateway.example/v1"
            )

    @pytest.mark.parametrize("provider", [None, ""])
    def test_rewrite_base_url_missing_provider_is_none(self, provider):
        """No provider to look up: the resolver returns None (which the
        friendly message renders as ``<unknown>``), even with a custom
        endpoint, because that only applies to ``openai_endpoint``."""
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        assert (
            _resolve_error_rewrite_base_url(
                provider, "https://gateway.example/v1"
            )
            is None
        )

    def test_rewrite_base_url_unknown_provider_degrades_to_none(self):
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        assert _resolve_error_rewrite_base_url("no_such_provider", None) is None

    def test_rewrite_message_names_provider_endpoint_and_model(self):
        """End-to-end contract of the fallback for a hardcoded provider."""
        from openai import NotFoundError

        from local_deep_research.error_handling.openai_compat_errors import (
            friendly_openai_compatible_error,
        )
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        try:
            raise NotFoundError(
                message="The model 'qwen3.8-max' does not exist",
                response=_resp(404),
                body=None,
            )
        except NotFoundError as exc:
            msg = friendly_openai_compatible_error(
                exc,
                provider="qwen",
                base_url=_resolve_error_rewrite_base_url("qwen", None),
                model="qwen3.8-max",
            )
        assert "qwen" in msg
        assert "https://maas.qwencloudapi.com/compatible-mode/v1" in msg
        assert "qwen3.8-max" in msg
        assert "<unknown>" not in msg

    def test_rewrite_base_url_prefers_configured_url_setting(self):
        """URL-configurable providers (LM Studio, llama.cpp) must report the
        operator-configured URL, not the localhost class default."""
        from local_deep_research.settings.manager import (
            SnapshotSettingsContext,
        )
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        ctx = SnapshotSettingsContext(
            {"llm.lmstudio.url": "http://nas:1234/v1"}
        )
        assert (
            _resolve_error_rewrite_base_url("lmstudio", "", ctx)
            == "http://nas:1234/v1"
        )

    def test_rewrite_base_url_url_setting_unset_is_not_guessed(self):
        """Without a configured URL, a URL-configurable provider falls back
        to None ("<unknown>") rather than the localhost class default."""
        from local_deep_research.settings.manager import (
            SnapshotSettingsContext,
        )
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        ctx = SnapshotSettingsContext({})
        assert _resolve_error_rewrite_base_url("lmstudio", "", ctx) is None

    def test_rewrite_base_url_url_setting_without_context_is_none(self):
        """A URL-configurable provider with no settings context must not
        fall back to the localhost class default."""
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        assert _resolve_error_rewrite_base_url("lmstudio", "", None) is None

    def test_rewrite_base_url_honors_openai_api_base_override(self):
        """An operator-configured llm.openai.api_base gateway is the URL the
        client actually uses — the rewrite must name it, not the class
        default."""
        from local_deep_research.settings.manager import (
            SnapshotSettingsContext,
        )
        from local_deep_research.web.services.research_service import (
            _resolve_error_rewrite_base_url,
        )

        ctx = SnapshotSettingsContext(
            {"llm.openai.api_base": "https://gateway.example/v1"}
        )
        assert (
            _resolve_error_rewrite_base_url("openai", "", ctx)
            == "https://gateway.example/v1"
        )
        # Without a context (or override) the class default still applies.
        assert _resolve_error_rewrite_base_url("openai", "", None) == (
            "https://api.openai.com/v1"
        )