260260# ---------------------------------------------------------------------------
261261
262262
263+ def _should_retry_exception (exc : Exception ) -> bool :
264+ """Determine whether an exception is retryable (transient error).
265+
266+ Returns True for temporary API/network errors that may succeed on retry:
267+ - Timeout (client-side or server-side)
268+ - APIError 5xx (server errors)
269+ - RateLimitError (429)
270+ - ConnectionError / ServiceUnavailableError
271+
272+ Returns False for permanent errors that won't be fixed by retry:
273+ - TruncatedResponseError (model hit max_tokens)
274+ - ValueError, TypeError (malformed input/output)
275+ - AuthenticationError (credentials issue)
276+ - BadRequestError (invalid parameters)
277+ - Unknown error types (conservative approach)
278+ """
279+ exc_type_name = type (exc ).__name__
280+
281+ # ===== RETRYABLE (transient errors) =====
282+
283+ # Timeout (network/gateway timeout)
284+ if "Timeout" in exc_type_name :
285+ return True
286+
287+ # Generic API errors (5xx range, but not 4xx)
288+ if "APIError" in exc_type_name :
289+ # Don't retry if it's a BadRequest/Invalid error (4xx)
290+ if "Invalid" not in exc_type_name and "BadRequest" not in exc_type_name :
291+ return True
292+
293+ # Rate limiting (429)
294+ if "RateLimitError" in exc_type_name or "Rate" in exc_type_name :
295+ return True
296+
297+ # Connection errors
298+ if "ConnectionError" in exc_type_name :
299+ return True
300+
301+ # Service unavailable
302+ if "ServiceUnavailable" in exc_type_name :
303+ return True
304+
305+ # ===== NOT RETRYABLE (permanent errors) =====
306+
307+ # Model hit max_tokens limit
308+ if isinstance (exc , TruncatedResponseError ):
309+ return False
310+
311+ # Content validation failures
312+ if "ValueError" in exc_type_name or "TypeError" in exc_type_name :
313+ return False
314+
315+ # Authentication failures
316+ if "Auth" in exc_type_name or "Permission" in exc_type_name :
317+ return False
318+
319+ # Bad parameters/requests
320+ if "BadRequest" in exc_type_name or "Invalid" in exc_type_name :
321+ return False
322+
323+ # ===== UNKNOWN: Conservative approach =====
324+ # Don't retry errors we don't recognize
325+ return False
326+
327+
263328def _cached_text (text : str ) -> list [dict ]:
264329 """Wrap a text payload into a content-block list with an Anthropic
265330 ephemeral cache_control marker.
@@ -406,7 +471,11 @@ def _llm_call(
406471 bundle = None ,
407472 ** kwargs ,
408473) -> str :
409- """Single LLM call with animated progress and debug logging."""
474+ """Single LLM call with animated progress, debug logging, and retry support.
475+
476+ Transient errors (Timeout, 5xx, 429) are automatically retried by LiteLLM.
477+ Permanent errors (4xx, truncation, validation) are raised immediately.
478+ """
410479 messages = _prepare_messages (model , messages )
411480 extra_headers = bundle .extra_headers if bundle is not None else get_extra_headers ()
412481 if extra_headers :
@@ -417,6 +486,10 @@ def _llm_call(
417486 if bundle is not None :
418487 kwargs .setdefault ("api_key" , bundle .api_key )
419488 kwargs .setdefault ("base_url" , bundle .base_url )
489+
490+ # NEW: Retry configuration for transient errors (fixed: 2 retries, base 2)
491+ kwargs .setdefault ("retries" , 2 )
492+
420493 logger .debug ("LLM request [%s]:\n %s" , step_name , _fmt_messages (messages ))
421494 if kwargs :
422495 logger .debug ("LLM kwargs [%s]: %s" , step_name , kwargs )
@@ -425,7 +498,27 @@ def _llm_call(
425498 spinner .start ()
426499 t0 = time .time ()
427500
428- response = litellm .completion (model = model , messages = messages , ** kwargs )
501+ try :
502+ response = litellm .completion (model = model , messages = messages , ** kwargs )
503+ except Exception as exc :
504+ # NEW: Better error logging with retry context
505+ if _should_retry_exception (exc ):
506+ logger .warning (
507+ "LLM [%s] failed with transient error (retries applied by LiteLLM): %s" ,
508+ step_name ,
509+ exc ,
510+ exc_info = False , # Don't spam stack traces for known transient errors
511+ )
512+ else :
513+ logger .warning (
514+ "LLM [%s] failed with permanent error (no retry): %s" ,
515+ step_name ,
516+ exc ,
517+ exc_info = True , # Full trace for unexpected errors
518+ )
519+ spinner .stop ("[FAILED]" )
520+ raise
521+
429522 content = response .choices [0 ].message .content or ""
430523 truncated = _warn_if_truncated (response , step_name , kwargs .get ("max_tokens" ))
431524
@@ -449,7 +542,11 @@ async def _llm_call_async(
449542 bundle = None ,
450543 ** kwargs ,
451544) -> str :
452- """Async LLM call with timing output and debug logging."""
545+ """Async LLM call with timing output, debug logging, and retry support.
546+
547+ Transient errors (Timeout, 5xx, 429) are automatically retried by LiteLLM.
548+ Permanent errors (4xx, truncation, validation) are raised immediately.
549+ """
453550 messages = _prepare_messages (model , messages )
454551 extra_headers = bundle .extra_headers if bundle is not None else get_extra_headers ()
455552 if extra_headers :
@@ -460,13 +557,36 @@ async def _llm_call_async(
460557 if bundle is not None :
461558 kwargs .setdefault ("api_key" , bundle .api_key )
462559 kwargs .setdefault ("base_url" , bundle .base_url )
560+
561+ # NEW: Retry configuration for transient errors (fixed: 2 retries, base 2)
562+ kwargs .setdefault ("retries" , 2 )
563+
463564 logger .debug ("LLM request [%s]:\n %s" , step_name , _fmt_messages (messages ))
464565 if kwargs :
465566 logger .debug ("LLM kwargs [%s]: %s" , step_name , kwargs )
466567
467568 t0 = time .time ()
468569
469- response = await litellm .acompletion (model = model , messages = messages , ** kwargs )
570+ try :
571+ response = await litellm .acompletion (model = model , messages = messages , ** kwargs )
572+ except Exception as exc :
573+ # NEW: Better error logging with retry context
574+ if _should_retry_exception (exc ):
575+ logger .warning (
576+ "LLM [%s] failed with transient error (retries applied by LiteLLM): %s" ,
577+ step_name ,
578+ exc ,
579+ exc_info = False ,
580+ )
581+ else :
582+ logger .warning (
583+ "LLM [%s] failed with permanent error (no retry): %s" ,
584+ step_name ,
585+ exc ,
586+ exc_info = True ,
587+ )
588+ raise
589+
470590 content = response .choices [0 ].message .content or ""
471591 truncated = _warn_if_truncated (response , step_name , kwargs .get ("max_tokens" ))
472592
0 commit comments