~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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