fix(responses): accept per-request timeout on aresponses

src/any_llm/any_llm.py

@@ -1222,6 +1222,7 @@ async def aresponses(
         prompt_cache_key: str | None = None,
         prompt_cache_retention: str | None = None,
         conversation: str | dict[str, Any] | None = None,
+        timeout: float | None = None,  # noqa: ASYNC109  # forwarded to the provider SDK, which owns the timeout
         extra_body: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> ResponseResource | Response | AsyncIterator[ResponseStreamEvent] | ParsedResponse[Any]:
@@ -1269,6 +1270,11 @@ async def aresponses(
             prompt_cache_key: A key to use when reading from or writing to the prompt cache.
             prompt_cache_retention: How long to retain a prompt cache entry created by this request.
             conversation: The conversation to associate this response with (ID string or ConversationParam object).
+            timeout: Per-request timeout in seconds, passed through to the provider's client/SDK.
+                An explicit ``None`` is treated the same as omitting it (the provider's default
+                applies), so it cannot request an unbounded timeout. Providers that have no
+                per-request timeout raise `UnsupportedParameterError`; set a timeout on their
+                client via `client_args` instead.
             extra_body: Additional fields to merge into an OpenAI-compatible Responses request body.
             **kwargs: Additional provider-specific arguments that will be passed to the provider's API call.
 
@@ -1327,6 +1333,7 @@ async def aresponses(
         )
 
         provider_kwargs: dict[str, Any] = {}
+        self._validate_and_forward_timeout(timeout, provider_kwargs)
         if extra_body is not None:
             provider_kwargs["extra_body"] = extra_body
         result = await self._aresponses(params, **provider_kwargs)

src/any_llm/api.py

@@ -300,6 +300,7 @@ def responses(
     prompt_cache_key: str | None = None,
     prompt_cache_retention: str | None = None,
     conversation: str | dict[str, Any] | None = None,
+    timeout: float | None = None,
     extra_body: dict[str, Any] | None = None,
     client_args: dict[str, Any] | None = None,
     **kwargs: Any,
@@ -354,6 +355,11 @@ def responses(
         prompt_cache_key: A key to use when reading from or writing to the prompt cache.
         prompt_cache_retention: How long to retain a prompt cache entry created by this request.
         conversation: The conversation to associate this response with (ID string or ConversationParam object).
+        timeout: Per-request timeout in seconds, passed through to the provider's client/SDK.
+            An explicit ``None`` is treated the same as omitting it (the provider's default
+            applies), so it cannot request an unbounded timeout. Providers that have no
+            per-request timeout raise `UnsupportedParameterError`; set a timeout on their
+            client via `client_args` instead.
         extra_body: Additional fields to merge into an OpenAI-compatible Responses request body.
         client_args: Additional provider-specific arguments that will be passed to the provider's client instantiation.
         **kwargs: Additional provider-specific arguments that will be passed to the provider's API call.
@@ -410,6 +416,7 @@ def responses(
         prompt_cache_key=prompt_cache_key,
         prompt_cache_retention=prompt_cache_retention,
         conversation=conversation,
+        timeout=timeout,
         extra_body=extra_body,
         **kwargs,
     )
@@ -449,6 +456,7 @@ async def aresponses(
     prompt_cache_key: str | None = None,
     prompt_cache_retention: str | None = None,
     conversation: str | dict[str, Any] | None = None,
+    timeout: float | None = None,  # noqa: ASYNC109  # forwarded to the provider SDK, which owns the timeout
     extra_body: dict[str, Any] | None = None,
     client_args: dict[str, Any] | None = None,
     **kwargs: Any,
@@ -503,6 +511,11 @@ async def aresponses(
         prompt_cache_key: A key to use when reading from or writing to the prompt cache.
         prompt_cache_retention: How long to retain a prompt cache entry created by this request.
         conversation: The conversation to associate this response with (ID string or ConversationParam object).
+        timeout: Per-request timeout in seconds, passed through to the provider's client/SDK.
+            An explicit ``None`` is treated the same as omitting it (the provider's default
+            applies), so it cannot request an unbounded timeout. Providers that have no
+            per-request timeout raise `UnsupportedParameterError`; set a timeout on their
+            client via `client_args` instead.
         extra_body: Additional fields to merge into an OpenAI-compatible Responses request body.
         client_args: Additional provider-specific arguments that will be passed to the provider's client instantiation.
         **kwargs: Additional provider-specific arguments that will be passed to the provider's API call.
@@ -559,6 +572,7 @@ async def aresponses(
         prompt_cache_key=prompt_cache_key,
         prompt_cache_retention=prompt_cache_retention,
         conversation=conversation,
+        timeout=timeout,
         extra_body=extra_body,
         **kwargs,
     )

tests/unit/test_responses.py

@@ -1,11 +1,13 @@
+from inspect import signature
 from typing import Any, cast
 from unittest.mock import AsyncMock, patch
 
 import pytest
 from pydantic import ValidationError
 
 from any_llm import AnyLLM
-from any_llm.api import aresponses
+from any_llm.api import aresponses, responses
+from any_llm.exceptions import UnsupportedParameterError
 from any_llm.types.responses import ResponsesParams
 
 
@@ -115,3 +117,64 @@ def add(a: int, b: int) -> int:
     assert tools[1]["parameters"] == {}
     assert tools[1]["strict"] is True
     assert tools[3] == {"type": "web_search"}
+
+
+def test_responses_exposes_timeout_parameter() -> None:
+    """The Responses entry points advertise timeout the same way the completion ones do."""
+    assert "timeout" in signature(responses).parameters
+    assert "timeout" in signature(aresponses).parameters
+    assert "timeout" in signature(AnyLLM.aresponses).parameters
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(("requested_timeout", "expected"), [(60, 60), (None, None)])
+async def test_timeout_forwarded_to_provider_not_params(
+    requested_timeout: float | None, expected: float | None
+) -> None:
+    """timeout is an SDK request option: it must reach the provider call, never ResponsesParams."""
+    llm = AnyLLM.create("openai", api_key="test-key")
+    with patch.object(type(llm), "_aresponses", new=AsyncMock(return_value=object())) as mock_aresponses:
+        await llm.aresponses("gpt-4.1-mini", "hello", timeout=requested_timeout)
+
+    assert mock_aresponses.call_args.kwargs.get("timeout") == expected
+    params = mock_aresponses.call_args.args[0]
+    assert "timeout" not in params.model_dump(exclude_none=True)
+
+
+@pytest.mark.asyncio
+async def test_aresponses_helper_forwards_timeout_to_provider() -> None:
+    """The public aresponses() helper routes timeout through to the provider call."""
+    provider = AnyLLM.create("openai", api_key="test-key")
+    with (
+        patch("any_llm.any_llm.AnyLLM.create", return_value=provider),
+        patch.object(provider, "_aresponses", new=AsyncMock(return_value=object())) as mock_aresponses,
+    ):
+        await aresponses("gpt-4.1-mini", "hello", provider="openai", api_key="test-key", timeout=60)
+
+    assert mock_aresponses.call_args.kwargs["timeout"] == 60
+
+
+def test_responses_helper_forwards_timeout_to_provider_sync() -> None:
+    """The synchronous responses() helper routes timeout through the same path."""
+    provider = AnyLLM.create("openai", api_key="test-key")
+    with (
+        patch("any_llm.any_llm.AnyLLM.create", return_value=provider),
+        patch.object(provider, "_aresponses", new=AsyncMock(return_value=object())) as mock_aresponses,
+    ):
+        responses("gpt-4.1-mini", "hello", provider="openai", api_key="test-key", timeout=60)
+
+    assert mock_aresponses.call_args.kwargs["timeout"] == 60
+
+
+@pytest.mark.asyncio
+async def test_aresponses_rejects_timeout_for_unsupported_provider() -> None:
+    """A provider declaring no per-request timeout support is rejected before the request is built."""
+    llm = AnyLLM.create("openai", api_key="test-key")
+    llm.TIMEOUT_SUPPORT = "unsupported"
+    with (
+        patch.object(llm, "_aresponses", new=AsyncMock()) as mock_aresponses,
+        pytest.raises(UnsupportedParameterError, match="timeout"),
+    ):
+        await llm.aresponses("gpt-4.1-mini", "hello", timeout=60)
+
+    mock_aresponses.assert_not_called()