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.

22.0 KB
Raw Blame
"""Tests for ``llm.request_timeout`` / ``llm.max_retries`` wiring.

``llm.request_timeout`` is a *per-operation* bound (connect, write, and
the wait for the next response chunk), not a cap on total response time.
The behavioural consequences of that choice are measured against a real
local server in ``test_request_timeout_behavior.py``; this module pins
resolution and constructor wiring.
"""

from decimal import Decimal
from fractions import Fraction
from unittest.mock import patch

import math

import pytest

from local_deep_research.llm.providers._helpers import (
    CONNECT_TIMEOUT_SECONDS,
    resolve_max_retries,
    resolve_request_timeout,
)
from local_deep_research.llm.providers.implementations.anthropic import (
    AnthropicProvider,
)
from local_deep_research.llm.providers.implementations.custom_anthropic_endpoint import (
    CustomAnthropicEndpointProvider,
)
from local_deep_research.llm.providers.implementations.ollama import (
    OllamaProvider,
)
from local_deep_research.llm.providers.implementations.custom_openai_endpoint import (
    CustomOpenAIEndpointProvider,
)
from local_deep_research.llm.providers.implementations.llamacpp import (
    LlamaCppProvider,
)
from local_deep_research.llm.providers.implementations.lmstudio import (
    LMStudioProvider,
)
from local_deep_research.llm.providers.implementations.openai import (
    OpenAIProvider,
)
from local_deep_research.settings.exceptions import SettingsValueError


_OPENAI_COMPATIBLE_CHAT_PATCH = (
    "local_deep_research.llm.providers.openai_base.ChatOpenAI"
)
_OPENAI_CHAT_PATCH = (
    "local_deep_research.llm.providers.implementations.openai.ChatOpenAI"
)
_OLLAMA_CHAT_PATCH = (
    "local_deep_research.llm.providers.implementations.ollama.ChatOllama"
)
_ANTHROPIC_CHAT_PATCH = (
    "local_deep_research.llm.providers.implementations.anthropic.ChatAnthropic"
)

_CONSTRUCTOR_CASES = (
    (AnthropicProvider, _ANTHROPIC_CHAT_PATCH),
    (CustomAnthropicEndpointProvider, _ANTHROPIC_CHAT_PATCH),
    (CustomOpenAIEndpointProvider, _OPENAI_COMPATIBLE_CHAT_PATCH),
    (LMStudioProvider, _OPENAI_COMPATIBLE_CHAT_PATCH),
    (LlamaCppProvider, _OPENAI_COMPATIBLE_CHAT_PATCH),
    (OpenAIProvider, _OPENAI_CHAT_PATCH),
    (OllamaProvider, _OLLAMA_CHAT_PATCH),
)

_PROVIDER_SETTINGS = {
    AnthropicProvider: {"llm.anthropic.api_key": "test-key"},
    CustomAnthropicEndpointProvider: {
        "llm.anthropic_endpoint.api_key": "test-key",
        "llm.anthropic_endpoint.url": "http://localhost:9090",
    },
    CustomOpenAIEndpointProvider: {
        "llm.openai_endpoint.api_key": "test-key",
        "llm.openai_endpoint.url": "http://localhost:8000/v1",
    },
    LMStudioProvider: {
        "llm.lmstudio.api_key": "test-key",
        "llm.lmstudio.url": "http://localhost:1234/v1",
        "llm.local_context_window_size": 8192,
    },
    LlamaCppProvider: {
        "llm.llamacpp.api_key": "test-key",
        "llm.llamacpp.url": "http://localhost:8080/v1",
        "llm.local_context_window_size": 8192,
    },
    OpenAIProvider: {"llm.openai.api_key": "test-key"},
    OllamaProvider: {
        "llm.ollama.url": "http://localhost:11434",
        "llm.local_context_window_size": 8192,
    },
}


def _base_settings():
    """Minimum snapshot for create_llm to reach ChatOllama construction."""
    return {
        "llm.ollama.url": "http://localhost:11434",
        "llm.local_context_window_size": 8192,
        "llm.supports_max_tokens": True,
        "llm.max_tokens": 4096,
    }


class TestRequestTimeoutResolution:
    @pytest.mark.parametrize(
        "configured_timeout", [1, Fraction(3, 2), Decimal("45"), "60", 1800]
    )
    def test_returns_float_for_finite_values_within_the_configured_range(
        self, configured_timeout
    ):
        # Given
        snapshot = {"llm.request_timeout": configured_timeout}

        # When
        timeout = resolve_request_timeout(snapshot)

        # Then
        assert timeout == float(configured_timeout)
        assert isinstance(timeout, float)

    @pytest.mark.parametrize("snapshot", [{}, {"llm.request_timeout": None}])
    def test_uses_the_default_when_the_setting_is_missing_or_none(
        self, snapshot
    ):
        # Given
        settings_snapshot = snapshot

        # When
        timeout = resolve_request_timeout(settings_snapshot)

        # Then
        assert timeout == 1800
        assert isinstance(timeout, float)

    @pytest.mark.parametrize("configured_timeout", [0, -5, Fraction(1, 2)])
    def test_rejects_out_of_range_values(self, configured_timeout):
        snapshot = {"llm.request_timeout": configured_timeout}

        with pytest.raises(SettingsValueError, match="llm.request_timeout"):
            resolve_request_timeout(snapshot)

    @pytest.mark.parametrize(
        "configured_timeout", [1801, 10**9, Fraction(1800) + Fraction(1, 2**40)]
    )
    def test_large_values_are_honoured_not_clamped(self, configured_timeout):
        """There is no ceiling: a slow local model may need hours.

        These values were previously clamped to a 1800s maximum. The cap was
        removed because any ceiling generous enough for a large model on
        modest hardware is too generous to catch a typo anyway -- the guard
        that actually prevents an unbounded wait is the finite-number check,
        which still rejects ``inf``.
        """
        settings_snapshot = {"llm.request_timeout": configured_timeout}

        timeout = resolve_request_timeout(settings_snapshot)

        assert timeout == pytest.approx(float(configured_timeout))
        assert math.isfinite(timeout)

    @pytest.mark.parametrize(
        "configured_timeout",
        [
            True,
            False,
            float("nan"),
            float("inf"),
            float("-inf"),
            "not-a-number",
            object(),
            [30],
        ],
    )
    def test_rejects_unusable_shapes(self, configured_timeout):
        snapshot = {"llm.request_timeout": configured_timeout}

        with pytest.raises(SettingsValueError, match="llm.request_timeout"):
            resolve_request_timeout(snapshot)

    def test_invalid_value_is_not_exposed_in_the_error_or_its_context(self):
        configured_timeout = "credential-looking-invalid-value"

        with pytest.raises(SettingsValueError) as caught:
            resolve_request_timeout({"llm.request_timeout": configured_timeout})

        assert configured_timeout not in str(caught.value)
        assert caught.value.__context__ is None
        assert caught.value.__cause__ is None

    def test_full_format_snapshot_without_ui_element_still_resolves(self):
        """A full-format entry lacking ``ui_element`` resolves to ``"60"``.

        The value arrives as a string; it must still bound the client
        rather than take down LLM construction.
        """
        # Given
        snapshot = {"llm.request_timeout": {"value": 60}}

        # When
        timeout = resolve_request_timeout(snapshot)

        # Then
        assert timeout == 60.0

    def test_full_format_snapshot_rejects_a_boolean_number_value(self):
        snapshot = {
            "llm.request_timeout": {"value": True, "ui_element": "number"}
        }

        with pytest.raises(SettingsValueError, match="llm.request_timeout"):
            resolve_request_timeout(snapshot)


class TestMaxRetriesResolution:
    @pytest.mark.parametrize(
        ("snapshot", "expected"),
        [
            ({}, 2),
            ({"llm.max_retries": None}, 2),
            ({"llm.max_retries": 0}, 0),
            ({"llm.max_retries": 4}, 4),
            ({"llm.max_retries": "3"}, 3),
            ({"llm.max_retries": 5}, 5),
        ],
    )
    def test_resolves_within_bounds(self, snapshot, expected):
        # When
        retries = resolve_max_retries(snapshot)

        # Then
        assert retries == expected
        assert isinstance(retries, int)

    @pytest.mark.parametrize(
        "configured_retries",
        [1000, -1, True, "nope", float("nan"), float("inf")],
    )
    def test_rejects_invalid_configured_retries(self, configured_retries):
        with pytest.raises(SettingsValueError, match="llm.max_retries"):
            resolve_max_retries({"llm.max_retries": configured_retries})


class TestOllamaClientKwargs:
    """``llm.request_timeout`` and auth headers flow via client_kwargs."""

    def test_configured_timeout_is_passed_via_client_kwargs(self):
        # Given
        snapshot = _base_settings()
        snapshot["llm.request_timeout"] = 37

        def side_effect(key, default=None, *args, **kwargs):
            return snapshot.get(key, default)

        # When
        with patch(
            "local_deep_research.llm.providers.implementations.ollama.get_setting_from_snapshot",
            side_effect=side_effect,
        ):
            with patch(
                "local_deep_research.llm.providers.implementations.ollama.ChatOllama"
            ) as mock_chat:
                OllamaProvider.create_llm(
                    model_name="llama3.1:8b", settings_snapshot=snapshot
                )

        # Then
        timeout = mock_chat.call_args[1]["client_kwargs"]["timeout"]
        assert timeout.read == 37
        assert timeout.write == 37
        assert timeout.pool == 37
        # Literal, not the imported constant: raising CONNECT_TIMEOUT_SECONDS
        # is a behaviour change and must break a test, not ride along.
        assert timeout.connect == 5.0

    def test_missing_setting_falls_back_to_the_default(self):
        # Given — request_timeout deliberately absent
        snapshot = _base_settings()

        def side_effect(key, default=None, *args, **kwargs):
            return snapshot.get(key, default)

        # When
        with patch(
            "local_deep_research.llm.providers.implementations.ollama.get_setting_from_snapshot",
            side_effect=side_effect,
        ):
            with patch(
                "local_deep_research.llm.providers.implementations.ollama.ChatOllama"
            ) as mock_chat:
                OllamaProvider.create_llm(
                    model_name="llama3.1:8b", settings_snapshot=snapshot
                )

        # Then
        assert mock_chat.call_args[1]["client_kwargs"]["timeout"].read == 1800

    def test_auth_headers_are_passed_through_client_kwargs(self):
        """ChatOllama has no ``headers`` field, so a top-level kwarg was dropped.

        Routing them through client_kwargs is the only way the
        Authorization header reaches the underlying httpx clients.
        """
        # Given
        snapshot = _base_settings()
        snapshot["llm.ollama.api_key"] = "secret-token"

        def side_effect(key, default=None, *args, **kwargs):
            return snapshot.get(key, default)

        # When
        with patch(
            "local_deep_research.llm.providers.implementations.ollama.get_setting_from_snapshot",
            side_effect=side_effect,
        ):
            with patch(
                "local_deep_research.llm.providers.implementations.ollama.ChatOllama"
            ) as mock_chat:
                OllamaProvider.create_llm(
                    model_name="llama3.1:8b", settings_snapshot=snapshot
                )

        # Then
        kwargs = mock_chat.call_args[1]
        assert kwargs["client_kwargs"]["headers"] == {
            "Authorization": "Bearer secret-token"
        }
        assert "headers" not in kwargs

    def test_auth_headers_actually_reach_both_httpx_clients(self):
        """End-to-end: the real ChatOllama must put the header on the wire."""
        # Given
        snapshot = _base_settings()
        snapshot["llm.ollama.api_key"] = "secret-token"

        def side_effect(key, default=None, *args, **kwargs):
            return snapshot.get(key, default)

        # When
        with patch(
            "local_deep_research.llm.providers.implementations.ollama.get_setting_from_snapshot",
            side_effect=side_effect,
        ):
            llm = OllamaProvider.create_llm(
                model_name="llama3.1:8b", settings_snapshot=snapshot
            )

        # Then
        for client in (llm._client, llm._async_client):
            assert (
                client._client.headers.get("authorization")
                == "Bearer secret-token"
            )
            assert client._client.timeout.read == 1800
            assert client._client.timeout.connect == 5.0


class TestRequestTimeoutConstructorWiring:
    @pytest.mark.parametrize(
        ("timeout_setting", "expected_timeout"),
        (
            ({"llm.request_timeout": 37}, 37),
            ({}, 1800),
            ({"llm.request_timeout": None}, 1800),
            # Above the old ceiling: honoured, no longer clamped.
            ({"llm.request_timeout": 10**9}, 10**9),
        ),
        ids=(
            "configured",
            "missing",
            "explicit-none",
            "very-high",
        ),
    )
    @pytest.mark.parametrize(
        ("provider", "chat_patch"),
        _CONSTRUCTOR_CASES,
        ids=(
            "anthropic",
            "custom-anthropic-endpoint",
            "custom-openai-endpoint",
            "lmstudio",
            "llamacpp",
            "openai",
            "ollama",
        ),
    )
    def test_passes_the_resolved_timeout_to_each_client_constructor(
        self, provider, chat_patch, timeout_setting, expected_timeout
    ):
        # Given
        snapshot = {
            **_PROVIDER_SETTINGS[provider],
            "llm.supports_max_tokens": False,
            **timeout_setting,
        }

        # When
        with patch(chat_patch) as mock_chat:
            provider.create_llm(
                model_name="test-model", settings_snapshot=snapshot
            )

        # Then
        kwargs = mock_chat.call_args.kwargs
        expected_connect = min(5.0, expected_timeout)
        if provider is OllamaProvider:
            # ollama.Client is per-instance regardless, so the SDK's own
            # Timeout object is used there.
            timeout = kwargs["client_kwargs"]["timeout"]
            assert timeout.read == expected_timeout
            assert timeout.write == expected_timeout
            assert timeout.pool == expected_timeout
            assert timeout.connect == expected_connect
            return
        if issubclass(provider, AnthropicProvider):
            # ChatAnthropic types the field ``float | None`` and builds its
            # httpx client from a cached factory, so only a scalar fits.
            assert kwargs["timeout"] == expected_timeout
            return
        # OpenAI-compatible: a hashable ``(connect, read, write, pool)``
        # tuple, not a Timeout object — see
        # ``TestOpenAIHttpxClientSharing`` for why the shape matters.
        assert kwargs["request_timeout"] == (
            expected_connect,
            expected_timeout,
            expected_timeout,
            expected_timeout,
        )

    @pytest.mark.parametrize(
        ("retries_setting", "expected_retries"),
        (
            ({}, 2),
            ({"llm.max_retries": 0}, 0),
            ({"llm.max_retries": 5}, 5),
        ),
        ids=("default", "disabled", "maximum"),
    )
    @pytest.mark.parametrize(
        ("provider", "chat_patch"),
        [case for case in _CONSTRUCTOR_CASES if case[0] is not OllamaProvider],
        ids=(
            "anthropic",
            "custom-anthropic-endpoint",
            "custom-openai-endpoint",
            "lmstudio",
            "llamacpp",
            "openai",
        ),
    )
    def test_passes_bounded_max_retries_to_each_client_constructor(
        self, provider, chat_patch, retries_setting, expected_retries
    ):
        """Unbounded SDK retries multiply the effective timeout.

        Without an explicit value both SDKs default to 2 internally while
        the langchain field reads ``None``, so the effective wait was
        ~3x the advertised bound with nothing capping a user-set value.
        """
        # Given
        snapshot = {
            **_PROVIDER_SETTINGS[provider],
            "llm.supports_max_tokens": False,
            **retries_setting,
        }

        # When
        with patch(chat_patch) as mock_chat:
            provider.create_llm(
                model_name="test-model", settings_snapshot=snapshot
            )

        # Then
        assert mock_chat.call_args.kwargs["max_retries"] == expected_retries

    @pytest.mark.parametrize(
        "invalid_timeout",
        [
            0,
            True,
            "not-a-number",
            float("inf"),
            {"value": True, "ui_element": "number"},
            {"value": 10**400, "ui_element": "number"},
        ],
        ids=(
            "below-minimum",
            "bool",
            "text",
            "nonfinite",
            "full-bool",
            "full-overflow",
        ),
    )
    @pytest.mark.parametrize(
        ("provider", "chat_patch"),
        _CONSTRUCTOR_CASES,
        ids=(
            "anthropic",
            "custom-anthropic-endpoint",
            "custom-openai-endpoint",
            "lmstudio",
            "llamacpp",
            "openai",
            "ollama",
        ),
    )
    def test_an_invalid_timeout_blocks_client_construction(
        self, provider, chat_patch, invalid_timeout
    ):
        snapshot = {
            **_PROVIDER_SETTINGS[provider],
            "llm.supports_max_tokens": False,
            "llm.request_timeout": invalid_timeout,
        }

        with patch(chat_patch) as mock_chat:
            with pytest.raises(SettingsValueError, match="llm.request_timeout"):
                provider.create_llm(
                    model_name="test-model", settings_snapshot=snapshot
                )

        mock_chat.assert_not_called()

    @pytest.mark.parametrize(
        "invalid_retries",
        [1000, True, {"value": 10**400, "ui_element": "number"}],
        ids=("above-maximum", "bool", "full-overflow"),
    )
    @pytest.mark.parametrize(
        ("provider", "chat_patch"),
        [case for case in _CONSTRUCTOR_CASES if case[0] is not OllamaProvider],
    )
    def test_invalid_retries_block_client_construction(
        self, provider, chat_patch, invalid_retries
    ):
        snapshot = {
            **_PROVIDER_SETTINGS[provider],
            "llm.supports_max_tokens": False,
            "llm.max_retries": invalid_retries,
        }

        with patch(chat_patch) as mock_chat:
            with pytest.raises(SettingsValueError, match="llm.max_retries"):
                provider.create_llm(
                    model_name="test-model", settings_snapshot=snapshot
                )

        mock_chat.assert_not_called()


class TestOpenAIHttpxClientSharing:
    """The timeout's *type* decides whether httpx clients are shared.

    ``langchain_openai`` builds ChatOpenAI's httpx clients through an
    ``@lru_cache``'d factory and quietly falls back to a per-instance
    client when the timeout value is unhashable
    (``_client_utils._get_default_httpx_client``). ``httpx.Timeout``
    defines ``__eq__`` without ``__hash__``, so passing a ``Timeout``
    object here would give every LLM in the process its own connection
    pool — and would falsify ``utilities/llm_utils.py``'s stated reason
    for ``_close_base_llm`` skipping these classes, plus the matching
    invariants in ``docs/developing/resource-cleanup.md``.

    Reverting ``_helpers.build_timeout`` to return
    ``openai.Timeout(connect=..., read=..., write=..., pool=...)`` leaves
    the effective per-operation bounds identical — and fails the
    hashability and sharing tests below.

    No network: the base_url is never contacted, only the client wiring
    that the constructor sets up is inspected.
    """

    _SNAPSHOT = {
        **_PROVIDER_SETTINGS[CustomOpenAIEndpointProvider],
        "llm.supports_max_tokens": False,
        "llm.request_timeout": 1800,
    }

    def _build(self):
        return CustomOpenAIEndpointProvider.create_llm(
            model_name="test-model", settings_snapshot=dict(self._SNAPSHOT)
        )

    def test_the_timeout_reaches_the_constructor_in_a_hashable_shape(self):
        # When
        with patch(_OPENAI_COMPATIBLE_CHAT_PATCH) as mock_chat:
            CustomOpenAIEndpointProvider.create_llm(
                model_name="test-model", settings_snapshot=dict(self._SNAPSHOT)
            )

        # Then — a tuple, and hash() must not raise
        timeout = mock_chat.call_args.kwargs["request_timeout"]
        assert timeout == (5.0, 1800, 1800, 1800)
        hash(timeout)
        # ``build_timeout`` is annotated ``tuple[float, float, float,
        # float]``, so the shape is asserted rather than inferred from the
        # equality above, where ints compare equal to floats. This says
        # nothing about the ``float(seconds)`` coercion: ``seconds`` here
        # comes from ``resolve_request_timeout`` and is already a float,
        # so this passes with or without it. Dropping that coercion is
        # caught by ``test_openai_base.py`` (the discovery path, where
        # ``MODEL_DISCOVERY_TIMEOUT_SECONDS`` is a bare int).
        assert all(type(part) is float for part in timeout)

    def test_two_llms_share_one_httpx_client(self):
        """Same settings -> same pooled sync and async httpx client."""
        # Given / When
        first = self._build()
        second = self._build()

        # Then
        assert first is not second
        assert first.root_client._client is second.root_client._client
        assert (
            first.root_async_client._client is second.root_async_client._client
        )

    def test_the_effective_per_operation_bounds_survive_the_tuple(self):
        """The tuple must expand to exactly the bounds the docs promise."""
        # When
        effective = self._build().root_client._client.timeout

        # Then
        assert effective.connect == 5.0
        assert effective.read == 1800
        assert effective.write == 1800
        assert effective.pool == 1800


class TestConnectTimeoutConstant:
    def test_the_connect_bound_is_five_seconds(self):
        """Pinned as a literal so raising the constant fails here first.

        The user-facing timeout hint in
        ``error_handling/openai_compat_errors.py`` states this number in
        prose; changing it means changing that text too.
        """
        assert CONNECT_TIMEOUT_SECONDS == 5.0