The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""Phase-specific one-liners for transport-timeout API errors.
A timeout that survives the retry loop otherwise surfaces as the SDK's bare
text: ``Request timed out.`` (openai ``APITimeoutError``) or ``timed out`` (a
raw httpx ``ReadTimeout`` mid-stream). Neither says whether a connection was
ever made, nor which setting to raise. The openai SDK wraps EVERY httpx
timeout, connect included, in ``APITimeoutError``, so the phase is read from
the most specific timeout in the explicit ``__cause__`` chain. ``__context__``
is not followed: an HTTP error raised while a timeout was being handled is a
different failure and keeps its own summary.
"""
from __future__ import annotations
from typing import Optional
# No TCP/TLS connection was established: raising the read timeout will not help.
_CONNECT_TIMEOUT_TYPES = frozenset({"ConnectTimeout", "ConnectTimeoutError"})
# The request was sent (or a stream was open) but no bytes arrived in time.
# ``APITimeoutError`` without a transport cause also lands here.
_READ_TIMEOUT_TYPES = frozenset({
"ReadTimeout", "TimeoutException", "ReadTimeoutError", "APITimeoutError",
})
# Waiting for a pooled connection or while uploading the request: the provider
# never got to answer, so neither hint applies and the existing summary stays.
_OTHER_TIMEOUT_TYPES = frozenset({"PoolTimeout", "WriteTimeout"})
def _timeout_phase(error: BaseException) -> Optional[str]:
"""``"connect"``, ``"read"``, or ``None`` when no timeout is in the chain."""
phase = None
current: Optional[BaseException] = error
seen: set[int] = set()
while current is not None and id(current) not in seen:
seen.add(id(current))
name = type(current).__name__
if name in _CONNECT_TIMEOUT_TYPES:
return "connect"
if name in _OTHER_TIMEOUT_TYPES:
return None
if name not in _READ_TIMEOUT_TYPES:
break
phase = "read"
current = current.__cause__
return phase
def summarize_timeout_error(error: BaseException, provider: Optional[str] = None) -> Optional[str]:
"""Timeout summary naming the phase and the setting to change, or ``None``
for any other error (the caller's existing summary handling then applies).
Both lines keep the "timed out" wording: cron failure notices and the error
classifier re-read this summary as text and match on it.
"""
phase = _timeout_phase(error)
if phase == "connect":
return ("Connection to the provider timed out before it was established "
"(check the base_url and network path)")
if phase == "read":
key = provider.strip() if isinstance(provider, str) and provider.strip() else "<provider>"
return ("Request timed out waiting for the provider to respond (if the model needs "
f"longer, raise providers.{key}.request_timeout_seconds in config.yaml)")
return None