raise friendlier error message to UI from integration code

src/integrations/anthropic_api.py

@@ -14,7 +14,7 @@ Key Features:
 # Standard Library Imports
 import logging
 from dataclasses import dataclass, field
-from typing import Any, Dict, List, Optional, Union, cast
+from typing import List, Optional, Union
 
 # Third-Party Library Imports
 from anthropic import APIError
@@ -214,22 +214,47 @@ async def generate_text_with_claude(character_description: str, config: Config)
         logger.warning(f"Unexpected response type: {type(blocks)}")
         return str(blocks or "No content generated.")
 
+    except APIError as e:
+        logger.error(f"Anthropic API request failed: {e!s}")
+        clean_message = _extract_anthropic_error_message(e)
+
+        if (
+            hasattr(e, 'status_code')
+            and e.status_code is not None
+            and CLIENT_ERROR_CODE <= e.status_code < SERVER_ERROR_CODE
+        ):
+            raise UnretryableAnthropicError(message=clean_message, original_exception=e) from e
+
+        raise AnthropicError(message=clean_message, original_exception=e) from e
+
     except Exception as e:
-        # If the error is an APIError, check if it's unretryable.
-        if isinstance(e, APIError):
-            status_code: Optional[int] = getattr(e, "status_code", None)
-            if status_code is not None and CLIENT_ERROR_CODE <= status_code < SERVER_ERROR_CODE:
-                error_body: Any = e.body
-                error_message: str = "Unknown error"
-                if isinstance(error_body, dict):
-                    error_message = cast(Dict[str, Any], error_body).get("error", {}).get("message", "Unknown error")
-                raise UnretryableAnthropicError(
-                    message=f'"{error_message}"',
-                    original_exception=e,
-                ) from e
-
-        # For all other errors, wrap them in an AnthropicError.
-        raise AnthropicError(
-            message=str(e),
-            original_exception=e,
-        ) from e
+        error_type = type(e).__name__
+        error_message = str(e) if str(e) else f"An error of type {error_type} occurred"
+        logger.error(f"Error during Anthropic API call: {error_type} - {error_message}")
+        clean_message = "An unexpected error occurred while processing your request. Please try again later."
+
+        raise AnthropicError(message=clean_message, original_exception=e) from e
+
+
+def _extract_anthropic_error_message(e: APIError) -> str:
+    """
+    Extracts a clean, user-friendly error message from an Anthropic API error response.
+
+    Args:
+        e (APIError): The Anthropic API error exception containing response information.
+
+    Returns:
+        str: A clean, user-friendly error message suitable for display to end users.
+    """
+    clean_message = "An unknown error has occurred. Please try again later."
+
+    if hasattr(e, 'body') and isinstance(e.body, dict):
+        error_body = e.body
+        if (
+            'error' in error_body
+            and isinstance(error_body['error'], dict)
+            and 'message' in error_body['error']
+        ):
+            clean_message = error_body['error']['message']
+
+    return clean_message

src/integrations/elevenlabs_api.py

@@ -128,18 +128,44 @@ async def text_to_speech_with_elevenlabs(
 
         return None, audio_file_path
 
+    except ApiError as e:
+        logger.error(f"ElevenLabs API request failed: {e!s}")
+        clean_message = _extract_elevenlabs_error_message(e)
+
+        if e.status_code is not None and CLIENT_ERROR_CODE <= e.status_code < SERVER_ERROR_CODE:
+            raise UnretryableElevenLabsError(message=clean_message, original_exception=e) from e
+
+        raise ElevenLabsError(message=clean_message, original_exception=e) from e
+
     except Exception as e:
-        if (
-            isinstance(e, ApiError)
-            and e.status_code is not None
-            and CLIENT_ERROR_CODE <= e.status_code < SERVER_ERROR_CODE
-        ):
-            raise UnretryableElevenLabsError(
-                message=f"{e.body['detail']['message']}",
-                original_exception=e,
-            ) from e
-
-        raise ElevenLabsError(
-            message=f"{e}",
-            original_exception=e,
-        ) from e
+        error_type = type(e).__name__
+        error_message = str(e) if str(e) else f"An error of type {error_type} occurred"
+        logger.error(f"Error during ElevenLabs API call: {error_type} - {error_message}")
+        clean_message = "An unexpected error occurred while processing your speech request. Please try again later."
+
+        raise ElevenLabsError(message=error_message, original_exception=e) from e
+
+
+def _extract_elevenlabs_error_message(e: ApiError) -> str:
+    """
+    Extracts a clean, user-friendly error message from an ElevenLabs API error response.
+
+    Args:
+        e (ApiError): The ElevenLabs API error exception containing response information.
+
+    Returns:
+        str: A clean, user-friendly error message suitable for display to end users.
+    """
+    clean_message = "An unknown error has occurred. Please try again later."
+
+    if (
+        hasattr(e, 'body') and e.body
+        and isinstance(e.body, dict)
+        and 'detail' in e.body
+        and isinstance(e.body['detail'], dict)
+    ):
+        detail = e.body['detail']
+        if 'message' in detail:
+            clean_message = detail['message']
+
+    return clean_message

src/integrations/hume_api.py

@@ -77,30 +77,26 @@ class UnretryableHumeError(HumeError):
 async def text_to_speech_with_hume(
     character_description: str,
     text: str,
-    num_generations: int,
     config: Config,
-) -> Union[Tuple[str, str], Tuple[str, str, str, str]]:
+) -> Tuple[str, str]:
     """
     Asynchronously synthesizes speech using the Hume TTS API, processes audio data, and writes audio to a file.
 
     This function uses the Hume Python SDK to send a request to the Hume TTS API with a character description
-    and text to be converted to speech. Depending on the specified number of generations (1 or 2), the API
-    returns one or two generations. For each generation, the function extracts the base64-encoded audio
-    and generation ID, saves the audio as an MP3 file, and returns the relevant details.
+    and text to be converted to speech. It extracts the base64-encoded audio and generation ID from the response,
+    saves the audio as an MP3 file, and returns the relevant details.
 
     Args:
         character_description (str): Description used for voice synthesis.
         text (str): Text to be converted to speech.
-        num_generations (int): Number of audio generations to request (1 or 2).
         config (Config): Application configuration containing Hume API settings.
 
     Returns:
-        Union[Tuple[str, str], Tuple[str, str, str, str]]:
-            - If num_generations == 1: (generation_a_id, audio_a_path).
-            - If num_generations == 2: (generation_a_id, audio_a_path, generation_b_id, audio_b_path).
+        Tuple[str, str]: A tuple containing:
+            - generation_id (str): Unique identifier for the generated audio.
+            - audio_file_path (str): Path to the saved audio file.
 
     Raises:
-        ValueError: If num_generations is not 1 or 2.
         HumeError: For errors communicating with the Hume API.
         UnretryableHumeError: For client-side HTTP errors (status code 4xx).
     """
@@ -110,30 +106,23 @@ async def text_to_speech_with_hume(
         f"Text length: {len(text)}."
     )
 
-    if num_generations < 1 or num_generations > 2:
-        raise ValueError("Invalid number of generations specified. Must be 1 or 2.")
-
     hume_config = config.hume_config
 
     start_time = time.time()
     try:
-        # Initialize the client for this request
         hume_client = AsyncHumeClient(
             api_key=hume_config.api_key,
             timeout=hume_config.request_timeout
         )
 
-        # Create the utterance with the character description and text
         utterance = PostedUtterance(
             text=text,
             description=character_description or None
         )
 
-        # Call the TTS API through the SDK
         response: ReturnTts = await hume_client.tts.synthesize_json(
             utterances=[utterance],
             format=hume_config.file_format,
-            num_generations=num_generations
         )
 
         elapsed_time = time.time() - start_time
@@ -148,31 +137,22 @@ async def text_to_speech_with_hume(
         generation_a = generations[0]
         generation_a_id, audio_a_path = _parse_hume_tts_generation(generation_a, config)
 
-        if num_generations == 1:
-            return (generation_a_id, audio_a_path)
-
-        generation_b = generations[1]
-        generation_b_id, audio_b_path = _parse_hume_tts_generation(generation_b, config)
-        return (generation_a_id, audio_a_path, generation_b_id, audio_b_path)
+        return (generation_a_id, audio_a_path)
 
     except ApiError as e:
         elapsed_time = time.time() - start_time
         logger.error(f"Hume API request failed after {elapsed_time:.2f} seconds: {e!s}")
+        clean_message = _extract_hume_api_error_message(e)
+        logger.error(f"Full Hume API error: {e!s}")
 
-        if hasattr(e, 'status_code') and e.status_code is not None:
-            if CLIENT_ERROR_CODE <= e.status_code < SERVER_ERROR_CODE:
-                error_message = f"HTTP Error {e.status_code}: {e!s}"
-                logger.error(error_message)
-                raise UnretryableHumeError(message=error_message, original_exception=e) from e
-            error_message = f"HTTP Error {e.status_code}: {e!s}"
-        else:
-            error_message = str(e)
-
-        logger.error(error_message)
-        raise HumeError(
-            message=error_message,
-            original_exception=e,
-        ) from e
+        if (
+            hasattr(e, 'status_code')
+            and e.status_code is not None
+            and CLIENT_ERROR_CODE <= e.status_code < SERVER_ERROR_CODE
+        ):
+            raise UnretryableHumeError(message=clean_message, original_exception=e) from e
+
+        raise HumeError(message=clean_message, original_exception=e) from e
 
     except Exception as e:
         error_type = type(e).__name__
@@ -205,3 +185,21 @@ def _parse_hume_tts_generation(generation: ReturnGeneration, config: Config) ->
     filename = f"{generation.generation_id}.mp3"
     audio_file_path = save_base64_audio_to_file(generation.audio, filename, config)
     return generation.generation_id, audio_file_path
+
+
+def _extract_hume_api_error_message(e: ApiError) -> str:
+    """
+    Extracts a clean, user-friendly error message from a Hume API error response.
+
+    Args:
+        e (ApiError): The Hume API error exception containing response information.
+
+    Returns:
+        str: A clean, user-friendly error message suitable for display to end users.
+    """
+    clean_message = "An unknown error has occurred. Please try again later."
+
+    if hasattr(e, 'body') and isinstance(e.body, dict) and 'message' in e.body:
+            clean_message = e.body['message']
+
+    return clean_message