Move env var validation util to config, refactor to fix linting errors across project

README.md

@@ -39,6 +39,7 @@ Expressive TTS Arena/
 │   ├── app.py                  # Entry file
 │   ├── config.py               # Global config and logger setup
 │   ├── constants.py            # Global constants
+│   ├── custom_types.py         # Global custom types
 │   ├── theme.py                # Custom Gradio Theme
 │   └── utils.py                # Utility functions
 ├── .env.example

pyproject.toml

@@ -29,7 +29,20 @@ line-length = 120
 src = ["src"]
 
 [tool.ruff.lint]
-ignore = ["D100", "D104", "FIX002", "TD002", "TD003"]
+ignore = [
+    "B904",
+    "BLE001",
+    "D100",
+    "D104",
+    "EM101",
+    "EM102",
+    "FIX002",
+    "G004",
+    "PLR0913",
+    "PLR2004",
+    "TD002",
+    "TD003",
+]
 select = [
     "A",
     "ARG",

src/app.py

@@ -9,26 +9,26 @@ Users can compare the outputs and vote for their favorite in an interactive UI.
 """
 
 # Standard Library Imports
-from concurrent.futures import ThreadPoolExecutor
 import time
+from concurrent.futures import ThreadPoolExecutor
 from typing import Tuple, Union
 
 # Third-Party Library Imports
 import gradio as gr
 
 # Local Application Imports
-from src.config import AUDIO_DIR, logger
 from src import constants
+from src.config import AUDIO_DIR, logger
+from src.custom_types import ComparisonType, Option, OptionMap
 from src.integrations import (
     AnthropicError,
     ElevenLabsError,
-    generate_text_with_claude,
     HumeError,
+    generate_text_with_claude,
     text_to_speech_with_elevenlabs,
     text_to_speech_with_hume,
 )
 from src.theme import CustomTheme
-from src.types import ComparisonType, OptionMap
 from src.utils import (
     choose_providers,
     create_shuffled_tts_options,
@@ -66,7 +66,7 @@ def generate_text(
         logger.info(f"Generated text ({len(generated_text)} characters).")
         return gr.update(value=generated_text), generated_text
     except AnthropicError as ae:
-        logger.error(f"AnthropicError while generating text: {str(ae)}")
+        logger.error(f"AnthropicError while generating text: {ae!s}")
         raise gr.Error(
             f'There was an issue communicating with the Anthropic API: "{ae.message}"'
         )
@@ -94,7 +94,8 @@ def synthesize_speech(
     Args:
         character_description (str): The description of the character used for generating the voice.
         text (str): The text content to be synthesized into speech.
-        generated_text_state (str): The previously generated text state, used to determine if the text has been modified.
+        generated_text_state (str): The previously generated text state, used to determine if the text has
+                                    been modified.
 
     Returns:
         Tuple containing:
@@ -118,7 +119,7 @@ def synthesize_speech(
 
     # Select 2 TTS providers based on whether the text has been modified.
     text_modified = text != generated_text_state
-    comparison_type, provider_a, provider_b = choose_providers(
+    provider_a, provider_b = choose_providers(
         text_modified, character_description
     )
 
@@ -151,9 +152,9 @@ def synthesize_speech(
                 generation_id_b, audio_b = future_audio_b.result()
 
         # Shuffle options so that placement of options in the UI will always be random
-        options_map: OptionMap = create_shuffled_tts_options(
-            provider_a, audio_a, generation_id_a, provider_b, audio_b, generation_id_b
-        )
+        option_a = Option(provider=provider_a, audio=audio_a, generation_id=generation_id_a)
+        option_b = Option(provider=provider_b, audio=audio_b, generation_id=generation_id_b)
+        options_map: OptionMap = create_shuffled_tts_options(option_a, option_b)
 
         option_a_audio = options_map["option_a"]["audio_file_path"]
         option_b_audio = options_map["option_b"]["audio_file_path"]
@@ -162,18 +163,17 @@ def synthesize_speech(
             gr.update(value=option_a_audio, visible=True, autoplay=True),
             gr.update(value=option_b_audio, visible=True),
             options_map,
-            comparison_type,
             text_modified,
             text,
             character_description,
         )
     except ElevenLabsError as ee:
-        logger.error(f"ElevenLabsError while synthesizing speech from text: {str(ee)}")
+        logger.error(f"ElevenLabsError while synthesizing speech from text: {ee!s}")
         raise gr.Error(
             f'There was an issue communicating with the Elevenlabs API: "{ee.message}"'
         )
     except HumeError as he:
-        logger.error(f"HumeError while synthesizing speech from text: {str(he)}")
+        logger.error(f"HumeError while synthesizing speech from text: {he!s}")
         raise gr.Error(
             f'There was an issue communicating with the Hume API: "{he.message}"'
         )
@@ -186,7 +186,6 @@ def vote(
     vote_submitted: bool,
     option_map: OptionMap,
     clicked_option_button: str,
-    comparison_type: ComparisonType,
     text_modified: bool,
     character_description: str,
     text: str,
@@ -222,7 +221,6 @@ def vote(
     submit_voting_results(
         option_map,
         selected_option,
-        comparison_type,
         text_modified,
         character_description,
         text,
@@ -272,7 +270,10 @@ def reset_ui() -> Tuple[gr.update, gr.update, gr.update, gr.update, None, bool]:
 
 
 def build_input_section() -> Tuple[gr.Dropdown, gr.Textbox, gr.Button]:
-    """Builds the input section including the sample character description dropdown, character description input, and generate text button"""
+    """
+        Builds the input section including the sample character description dropdown, character
+        description input, and generate text button.
+    """
     sample_character_description_dropdown = gr.Dropdown(
         choices=list(constants.SAMPLE_CHARACTER_DESCRIPTIONS.keys()),
         label="Choose a sample character description",
@@ -298,7 +299,9 @@ def build_input_section() -> Tuple[gr.Dropdown, gr.Textbox, gr.Button]:
 def build_output_section() -> (
     Tuple[gr.Textbox, gr.Button, gr.Audio, gr.Audio, gr.Button, gr.Button]
 ):
-    """Builds the output section including text input, audio players, and vote buttons."""
+    """
+        Builds the output section including text input, audio players, and vote buttons.
+    """
     text_input = gr.Textbox(
         label="Input Text",
         placeholder="Enter or generate text for synthesis...",
@@ -348,11 +351,15 @@ def build_gradio_interface() -> gr.Blocks:
         gr.Markdown("# Expressive TTS Arena")
         gr.Markdown(
             """
-            1. **Choose or enter a character description**: Select a sample from the list or enter your own to guide text and voice generation.
-            2. **Generate text**: Click **"Generate Text"** to create dialogue based on the character. The generated text will appear in the input field automatically—edit it if needed.
-            3. **Synthesize speech**: Click **"Synthesize Speech"** to send your text and character description to two TTS APIs. Each API generates a voice and synthesizes speech in that voice.
+            1. **Choose or enter a character description**: Select a sample from the list or enter your own to guide
+            text and voice generation.
+            2. **Generate text**: Click **"Generate Text"** to create dialogue based on the character. The generated
+            text will appear in the input field automatically—edit it if needed.
+            3. **Synthesize speech**: Click **"Synthesize Speech"** to send your text and character description to two
+            TTS APIs. Each API generates a voice and synthesizes speech in that voice.
             4. **Listen & compare**: Play both audio options and assess their expressiveness.
-            5. **Vote for the best**: Click **"Select Option A"** or **"Select Option B"** to choose the most expressive output.
+            5. **Vote for the best**: Click **"Select Option A"** or **"Select Option B"** to choose the most
+            expressive output.
             """
         )
 
@@ -384,8 +391,6 @@ def build_gradio_interface() -> gr.Blocks:
         # Track whether text that was used was generated or modified/custom
         text_modified_state = gr.State()
 
-        # Track comparison type (which set of providers are being compared)
-        comparison_type_state = gr.State()
         # Track option map (option A and option B are randomized)
         option_map_state = gr.State()
 
@@ -450,7 +455,6 @@ def build_gradio_interface() -> gr.Blocks:
                 option_a_audio_player,
                 option_b_audio_player,
                 option_map_state,
-                comparison_type_state,
                 text_modified_state,
                 text_state,
                 character_description_state,
@@ -472,7 +476,6 @@ def build_gradio_interface() -> gr.Blocks:
                 vote_submitted_state,
                 option_map_state,
                 vote_button_a,
-                comparison_type_state,
                 text_modified_state,
                 character_description_state,
                 text_state,
@@ -490,7 +493,6 @@ def build_gradio_interface() -> gr.Blocks:
                 vote_submitted_state,
                 option_map_state,
                 vote_button_b,
-                comparison_type_state,
                 text_modified_state,
                 character_description_state,
                 text_state,

src/config.py

@@ -13,25 +13,20 @@ Key Features:
 # Standard Library Imports
 import logging
 import os
+from pathlib import Path
 
 # Third-Party Library Imports
 from dotenv import load_dotenv
 
-
 # Determine the environment (defaults to "dev" if not explicitly set)
 APP_ENV = os.getenv("APP_ENV", "dev").lower()
 if APP_ENV not in {"dev", "prod"}:
-    print(f'Warning: Invalid APP_ENV "{APP_ENV}". Defaulting to "dev".')
     APP_ENV = "dev"
 
 
 # In development, load environment variables from .env file (not used in production)
-if APP_ENV == "dev":
-    if os.path.exists(".env"):
-        # Load environment variables
-        load_dotenv(".env", override=True)
-    else:
-        print("Warning: .env file not found. Using system environment variables.")
+if APP_ENV == "dev" and Path(".env").exists():
+    load_dotenv(".env", override=True)
 
 
 # Enable debug mode if in development (or if explicitly set in env variables)
@@ -47,10 +42,42 @@ logger.info(f'App running in "{APP_ENV}" mode.')
 logger.info(f'Debug mode is {"enabled" if DEBUG else "disabled"}.')
 
 if DEBUG:
-    logger.debug(f"DEBUG mode enabled.")
+    logger.debug("DEBUG mode enabled.")
 
 
 # Define the directory for audio files relative to the project root
-AUDIO_DIR = os.path.join(os.getcwd(), "static", "audio")
-os.makedirs(AUDIO_DIR, exist_ok=True)
+AUDIO_DIR = Path.cwd() / "static" / "audio"
+AUDIO_DIR.mkdir(parents=True, exist_ok=True)
 logger.info(f"Audio directory set to {AUDIO_DIR}")
+
+
+def validate_env_var(var_name: str) -> str:
+    """
+    Validates that an environment variable is set and returns its value.
+
+    Args:
+        var_name (str): The name of the environment variable to validate.
+
+    Returns:
+        str: The value of the environment variable.
+
+    Raises:
+        ValueError: If the environment variable is not set.
+
+    Examples:
+        >>> import os
+        >>> os.environ["EXAMPLE_VAR"] = "example_value"
+        >>> validate_env_var("EXAMPLE_VAR")
+        'example_value'
+
+        >>> validate_env_var("MISSING_VAR")
+        Traceback (most recent call last):
+          ...
+        ValueError: MISSING_VAR is not set. Please ensure it is defined in your environment variables.
+    """
+    value = os.environ.get(var_name, "")
+    if not value:
+        raise ValueError(
+            f"{var_name} is not set. Please ensure it is defined in your environment variables."
+        )
+    return value

src/constants.py

@@ -8,8 +8,10 @@ This module defines global constants used throughout the project.
 from typing import List
 
 # Third-Party Library Imports
-from src.types import ComparisonType, OptionKey, OptionLabel, TTSProviderName
+from src.custom_types import ComparisonType, OptionKey, OptionLabel, TTSProviderName
 
+CLIENT_ERROR_CODE = 400
+SERVER_ERROR_CODE = 500
 
 # UI constants
 HUME_AI: TTSProviderName = "Hume AI"
@@ -35,23 +37,28 @@ SELECT_OPTION_B: str = "Select Option B"
 # inspiration for generating creative text for expressive TTS, and generating novel voices.
 SAMPLE_CHARACTER_DESCRIPTIONS: dict = {
     "🚀 Stranded Astronaut": (
-        "A lone astronaut whose voice mirrors the silent vastness of space—a low, steady tone imbued with isolation and quiet wonder. "
-        "It carries the measured resolve of someone sending a final transmission, with an undercurrent of wistful melancholy."
+        "A lone astronaut whose voice mirrors the silent vastness of space—a low, steady tone imbued "
+        "with isolation and quiet wonder. It carries the measured resolve of someone sending a final "
+        "transmission, with an undercurrent of wistful melancholy."
     ),
     "📜 Timeless Poet": (
-        "An ageless poet with a voice that flows like gentle verse—a soft, reflective tone marked by deliberate pauses. "
-        "It speaks with the measured cadence of classic sonnets, evoking both the fragile beauty of time and heartfelt introspection."
+        "An ageless poet with a voice that flows like gentle verse—a soft, reflective tone marked by "
+        "deliberate pauses. It speaks with the measured cadence of classic sonnets, evoking both the "
+        "fragile beauty of time and heartfelt introspection."
     ),
     "🐱 Whimsical Feline": (
-        "A mischievous cat whose voice is playful yet mysterious—light, quick-witted, and infused with an enchanting purr. "
-        "It hints at secret adventures and hidden charm, balancing exuberance with a subtle, smooth allure."
+        "A mischievous cat whose voice is playful yet mysterious—light, quick-witted, and infused with "
+        "an enchanting purr. It hints at secret adventures and hidden charm, balancing exuberance with "
+        "a subtle, smooth allure."
     ),
     "🔥 Revolutionary Orator": (
-        "A defiant orator whose voice builds from quiet determination to passionate fervor—a clear, commanding tone that resonates with conviction. "
-        "It starts measured and resolute, then rises to a crescendo of fervor, punctuated by deliberate pauses that emphasize each rallying cry."
+        "A defiant orator whose voice builds from quiet determination to passionate fervor—a clear, "
+        "commanding tone that resonates with conviction. It starts measured and resolute, then rises "
+        "to a crescendo of fervor, punctuated by deliberate pauses that emphasize each rallying cry."
     ),
     "👻 Haunted Keeper": (
-        "A solitary lighthouse keeper with a voice that carries the weight of forgotten storms—a soft, measured tone with an echo of sorrow. "
-        "It speaks as if whispering long-held secrets in the dark, blending quiet melancholy with an air of enduring mystery."
+        "A solitary lighthouse keeper with a voice that carries the weight of forgotten storms—a soft, "
+        "measured tone with an echo of sorrow. It speaks as if whispering long-held secrets in the dark, "
+        "blending quiet melancholy with an air of enduring mystery."
     ),
 }

src/custom_types.py

@@ -1,5 +1,5 @@
 """
-types.py
+custom_types.py
 
 This module defines custom types for the application.
 """

src/integrations/anthropic_api.py

@@ -19,25 +19,26 @@ Functions:
 """
 
 # Standard Library Imports
-from dataclasses import dataclass
 import logging
+from dataclasses import dataclass
 from typing import List, Optional, Union
 
 # Third-Party Library Imports
-from anthropic import APIError, Anthropic
+from anthropic import Anthropic, APIError
 from anthropic.types import Message, ModelParam, TextBlock
-from tenacity import retry, stop_after_attempt, wait_fixed, before_log, after_log
+from tenacity import after_log, before_log, retry, stop_after_attempt, wait_fixed
 
 # Local Application Imports
-from src.config import logger
-from src.utils import truncate_text, validate_env_var
+from src.config import logger, validate_env_var
+from src.constants import CLIENT_ERROR_CODE, SERVER_ERROR_CODE
+from src.utils import truncate_text
 
 
 @dataclass(frozen=True)
 class AnthropicConfig:
     """Immutable configuration for interacting with the Anthropic API."""
 
-    api_key: str = validate_env_var("ANTHROPIC_API_KEY")
+    api_key: Optional[str] = None
     model: ModelParam = "claude-3-5-sonnet-latest"
     max_tokens: int = 150
     system_prompt: Optional[str] = (
@@ -47,13 +48,16 @@ class AnthropicConfig:
     def __post_init__(self):
         # Validate that required attributes are set
         if not self.api_key:
-            raise ValueError("Anthropic API key is not set.")
+            api_key = validate_env_var("ANTHROPIC_API_KEY")
+            object.__setattr__(self, "api_key", api_key)
         if not self.model:
             raise ValueError("Anthropic Model is not set.")
         if not self.max_tokens:
             raise ValueError("Anthropic Max Tokens is not set.")
         if self.system_prompt is None:
-            system_prompt: str = f"""You are an expert at generating micro-content optimized for text-to-speech synthesis. Your absolute priority is delivering complete, untruncated responses within strict length limits.
+            system_prompt: str = f"""You are an expert at generating micro-content optimized for text-to-speech
+synthesis. Your absolute priority is delivering complete, untruncated responses within strict length limits.
+
 CRITICAL LENGTH CONSTRAINTS:
 
 Maximum length: {self.max_tokens} tokens (approximately 400 characters)
@@ -84,7 +88,8 @@ Opening hook (50-75 characters)
 Emotional journey (200-250 characters)
 Resolution (75-100 characters)
 
-MANDATORY: If you find yourself reaching 300 characters, immediately begin your conclusion regardless of where you are in the narrative.
+MANDATORY: If you find yourself reaching 300 characters, immediately begin your conclusion regardless of where you
+are in the narrative.
 Remember: A shorter, complete response is ALWAYS better than a longer, truncated one."""
             object.__setattr__(self, "system_prompt", system_prompt)
 
@@ -110,12 +115,13 @@ Remember: A shorter, complete response is ALWAYS better than a longer, truncated
         Returns:
             str: The prompt to be passed to the Anthropic API.
         """
-        prompt = (
+        return (
             f"Character Description: {character_description}\n\n"
-            "Based on the above character description, please generate a line of dialogue that captures the character's unique personality, emotional depth, and distinctive tone. "
-            "The response should sound like something the character would naturally say, reflecting their background and emotional state, and be fully developed for text-to-speech synthesis."
+            "Based on the above character description, please generate a line of dialogue that captures the "
+            "character's unique personality, emotional depth, and distinctive tone. The response should sound "
+            "like something the character would naturally say, reflecting their background and emotional state, "
+            "and be fully developed for text-to-speech synthesis."
         )
-        return prompt
 
 
 class AnthropicError(Exception):
@@ -198,12 +204,15 @@ def generate_text_with_claude(character_description: str) -> str:
         return str(blocks or "No content generated.")
 
     except Exception as e:
-        if isinstance(e, APIError):
-            if e.status_code >= 400 and e.status_code < 500:
-                raise UnretryableAnthropicError(
-                    message=f"\"{e.body['error']['message']}\"",
-                    original_exception=e,
-                ) from e
+        if (
+            isinstance(e, APIError)
+            and e.status_code >= CLIENT_ERROR_CODE and e.status_code < SERVER_ERROR_CODE
+        ):
+            raise UnretryableAnthropicError(
+                message=f"\"{e.body['error']['message']}\"",
+                original_exception=e,
+            ) from e
+
         raise AnthropicError(
             message=(f"{e.message}"),
             original_exception=e,

src/integrations/elevenlabs_api.py

@@ -1,8 +1,8 @@
 """
 elevenlabs_api.py
 
-This file defines the interaction with the ElevenLabs text-to-speech (TTS) API using the ElevenLabs Python SDK.
-It includes functionality for API request handling and processing API responses.
+This file defines the interaction with the ElevenLabs text-to-speech (TTS) API using the
+ElevenLabs Python SDK. It includes functionality for API request handling and processing API responses.
 
 Key Features:
 - Encapsulates all logic related to the ElevenLabs TTS API.
@@ -20,32 +20,34 @@ Functions:
 """
 
 # Standard Library Imports
-from dataclasses import dataclass
 import logging
 import random
+from dataclasses import dataclass
 from typing import Optional, Tuple
 
 # Third-Party Library Imports
 from elevenlabs import ElevenLabs, TextToVoiceCreatePreviewsRequestOutputFormat
 from elevenlabs.core import ApiError
-from tenacity import retry, stop_after_attempt, wait_fixed, before_log, after_log
+from tenacity import after_log, before_log, retry, stop_after_attempt, wait_fixed
 
 # Local Application Imports
-from src.config import logger
-from src.utils import save_base64_audio_to_file, validate_env_var
+from src.config import logger, validate_env_var
+from src.constants import CLIENT_ERROR_CODE, SERVER_ERROR_CODE
+from src.utils import save_base64_audio_to_file
 
 
 @dataclass(frozen=True)
 class ElevenLabsConfig:
     """Immutable configuration for interacting with the ElevenLabs TTS API."""
 
-    api_key: str = validate_env_var("ELEVENLABS_API_KEY")
+    api_key: Optional[str] = None
     output_format: TextToVoiceCreatePreviewsRequestOutputFormat = "mp3_44100_128"
 
     def __post_init__(self):
         # Validate that required attributes are set
         if not self.api_key:
-            raise ValueError("ElevenLabs API key is not set.")
+            api_key = validate_env_var("ELEVENLABS_API_KEY")
+            object.__setattr__(self, "api_key", api_key)
 
     @property
     def client(self) -> ElevenLabs:
@@ -97,7 +99,8 @@ def text_to_speech_with_elevenlabs(
 
     Returns:
         Tuple[None, str]: A tuple containing:
-            - generation_id (None): We do not record the generation ID for ElevenLabs, but return None for uniformity across TTS integrations
+            - generation_id (None): We do not record the generation ID for ElevenLabs, but return None for uniformity
+                                    across TTS integrations
             - file_path (str): The relative file path to the audio file where the synthesized speech was saved.
 
     Raises:
@@ -132,12 +135,15 @@ def text_to_speech_with_elevenlabs(
         return None, audio_file_path
 
     except Exception as e:
-        if isinstance(e, ApiError):
-            if e.status_code >= 400 and e.status_code < 500:
-                raise UnretryableElevenLabsError(
-                    message=f"{e.body['detail']['message']}",
-                    original_exception=e,
-                ) from e
+        if (
+            isinstance(e, ApiError)
+            and e.status_code >= CLIENT_ERROR_CODE and 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,

src/integrations/hume_api.py

@@ -19,21 +19,19 @@ Functions:
 """
 
 # Standard Library Imports
-from dataclasses import dataclass
 import logging
-import os
-import random
+from dataclasses import dataclass
 from typing import Any, Dict, Literal, Optional, Tuple, Union
 
 # Third-Party Library Imports
 import requests
 from requests.exceptions import HTTPError
-from tenacity import retry, stop_after_attempt, wait_fixed, before_log, after_log
+from tenacity import after_log, before_log, retry, stop_after_attempt, wait_fixed
 
 # Local Application Imports
-from src.config import logger
-from src.utils import save_base64_audio_to_file, validate_env_var
-
+from src.config import logger, validate_env_var
+from src.constants import CLIENT_ERROR_CODE, SERVER_ERROR_CODE
+from src.utils import save_base64_audio_to_file
 
 HumeSupportedFileFormat = Literal["mp3", "pcm", "wav"]
 """ Support audio file formats for the Hume TTS API"""
@@ -43,7 +41,7 @@ HumeSupportedFileFormat = Literal["mp3", "pcm", "wav"]
 class HumeConfig:
     """Immutable configuration for interacting with the Hume TTS API."""
 
-    api_key: str = validate_env_var("HUME_API_KEY")
+    api_key: Optional[str] = None
     url: str = "https://test-api.hume.ai/v0/tts/octave"
     headers: dict = None
     file_format: HumeSupportedFileFormat = "mp3"
@@ -51,7 +49,8 @@ class HumeConfig:
     def __post_init__(self):
         # Validate required attributes
         if not self.api_key:
-            raise ValueError("Hume API key is not set.")
+            api_key = validate_env_var("HUME_API_KEY")
+            object.__setattr__(self, "api_key", api_key)
         if not self.url:
             raise ValueError("Hume TTS endpoint URL is not set.")
         if not self.file_format:
@@ -118,17 +117,19 @@ def text_to_speech_with_hume(
 
     Returns:
         Union[Tuple[str, str], Tuple[str, str, str, str]]:
-            - If num_generations == 1: A tuple in the form (generation_a_id, audio_a_path).
-            - If num_generations == 2: A tuple in the form (generation_a_id, audio_a_path, generation_b_id, audio_b_path).
+            - 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).
 
     Raises:
         ValueError: If num_generations is not 1 or 2.
         HumeError: If there is an error communicating with the Hume TTS API or parsing its response.
         UnretryableHumeError: If a client-side HTTP error (status code in the 4xx range) is encountered.
-        Exception: Any other exceptions raised during the request or processing will be wrapped and re-raised as HumeError.
+        Exception: Any other exceptions raised during the request or processing will be wrapped and
+                   re-raised as HumeError.
     """
     logger.debug(
-        f"Processing TTS with Hume. Prompt length: {len(character_description)} characters. Text length: {len(text)} characters."
+        f"Processing TTS with Hume. Prompt length: {len(character_description)} characters. "
+        f"Text length: {len(text)} characters."
     )
 
     if num_generations < 1 or num_generations > 2:
@@ -170,12 +171,19 @@ def text_to_speech_with_hume(
         return (generation_a_id, audio_a_path, generation_b_id, audio_b_path)
 
     except Exception as e:
-        if isinstance(e, HTTPError):
-            if e.response.status_code >= 400 and e.response.status_code < 500:
-                raise UnretryableHumeError(
-                    message=f"{e.response.text}", original_exception=e
-                ) from e
-        raise HumeError(message=f"{e}", original_exception=e) from e
+        if (
+            isinstance(e, HTTPError)
+            and CLIENT_ERROR_CODE <= e.response.status_code < SERVER_ERROR_CODE
+        ):
+            raise UnretryableHumeError(
+                message=f"{e.response.text}",
+                original_exception=e,
+            ) from e
+
+        raise HumeError(
+            message=f"{e}",
+            original_exception=e,
+        ) from e
 
 
 def parse_hume_tts_generation(generation: Dict[str, Any]) -> Tuple[str, str]:

src/utils.py

@@ -8,15 +8,15 @@ These functions provide reusable logic to simplify code in other modules.
 # Standard Library Imports
 import base64
 import json
-import os
 import random
 import time
+from pathlib import Path
 from typing import Tuple
 
 # Local Application Imports
 from src import constants
 from src.config import AUDIO_DIR, logger
-from src.types import (
+from src.custom_types import (
     ComparisonType,
     Option,
     OptionKey,
@@ -56,38 +56,6 @@ def truncate_text(text: str, max_length: int = 50) -> str:
     return text[:max_length] + ("..." if is_truncated else "")
 
 
-def validate_env_var(var_name: str) -> str:
-    """
-    Validates that an environment variable is set and returns its value.
-
-    Args:
-        var_name (str): The name of the environment variable to validate.
-
-    Returns:
-        str: The value of the environment variable.
-
-    Raises:
-        ValueError: If the environment variable is not set.
-
-    Examples:
-        >>> import os
-        >>> os.environ["EXAMPLE_VAR"] = "example_value"
-        >>> validate_env_var("EXAMPLE_VAR")
-        'example_value'
-
-        >>> validate_env_var("MISSING_VAR")
-        Traceback (most recent call last):
-          ...
-        ValueError: MISSING_VAR is not set. Please ensure it is defined in your environment variables.
-    """
-    value = os.environ.get(var_name, "")
-    if not value:
-        raise ValueError(
-            f"{var_name} is not set. Please ensure it is defined in your environment variables."
-        )
-    return value
-
-
 def validate_character_description_length(character_description: str) -> None:
     """
     Validates that a voice description is within specified minimum and maximum length limits.
@@ -114,16 +82,20 @@ def validate_character_description_length(character_description: str) -> None:
 
     if character_description_length < constants.CHARACTER_DESCRIPTION_MIN_LENGTH:
         raise ValueError(
-            f"Your character description is too short. Please enter at least {constants.CHARACTER_DESCRIPTION_MIN_LENGTH} characters. "
+            f"Your character description is too short. Please enter at least "
+            f"{constants.CHARACTER_DESCRIPTION_MIN_LENGTH} characters. "
             f"(Current length: {character_description_length})"
         )
     if character_description_length > constants.CHARACTER_DESCRIPTION_MAX_LENGTH:
         raise ValueError(
-            f"Your character description is too long. Please limit it to {constants.CHARACTER_DESCRIPTION_MAX_LENGTH} characters. "
+            f"Your character description is too long. Please limit it to "
+            f"{constants.CHARACTER_DESCRIPTION_MAX_LENGTH} characters. "
             f"(Current length: {character_description_length})"
         )
+
+    truncated_description = truncate_text(stripped_character_description)
     logger.debug(
-        f"Character description length validation passed for character_description: {truncate_text(stripped_character_description)}"
+        f"Character description length validation passed for character_description: {truncated_description}"
     )
 
 
@@ -145,28 +117,29 @@ def delete_files_older_than(directory: str, minutes: int = 30) -> None:
     now = time.time()
     # Convert the minutes threshold to seconds.
     cutoff = now - (minutes * 60)
+    dir_path = Path(directory)
 
     # Iterate over all files in the directory.
-    for filename in os.listdir(directory):
-        file_path = os.path.join(directory, filename)
-        file_mod_time = os.path.getmtime(file_path)
-        # If the file's modification time is older than the cutoff, delete it.
-        if file_mod_time < cutoff:
-            try:
-                os.remove(file_path)
-                print(f"Deleted: {file_path}")
-            except Exception as e:
-                print(f"Error deleting {file_path}: {e}")
+    for file_path in dir_path.iterdir():
+        if file_path.is_file():
+            file_mod_time = file_path.stat().st_mtime
+            # If the file's modification time is older than the cutoff, delete it.
+            if file_mod_time < cutoff:
+                try:
+                    file_path.unlink()
+                    logger.info(f"Deleted: {file_path}")
+                except Exception as e:
+                    logger.exception(f"Error deleting {file_path}: {e}")
 
 
 def save_base64_audio_to_file(base64_audio: str, filename: str) -> str:
     """
     Decode a base64-encoded audio string and write the resulting binary data to a file
     within the preconfigured AUDIO_DIR directory. Prior to writing the bytes to an audio
-    file all files within the directory which are more than 30 minutes old are deleted.
-    This function verifies the file was created, logs the absolute and relative file
-    paths, and returns a path relative to the current working directory (which is what
-    Gradio requires to serve static files).
+    file, all files within the directory that are more than 30 minutes old are deleted.
+    This function verifies the file was created, logs both the absolute and relative
+    file paths, and returns a path relative to the current working directory
+    (as required by Gradio for serving static files).
 
     Args:
         base64_audio (str): The base64-encoded string representing the audio data.
@@ -178,38 +151,38 @@ def save_base64_audio_to_file(base64_audio: str, filename: str) -> str:
         str: The relative file path to the saved audio file.
 
     Raises:
-        Exception: Propagates any exceptions raised during the decoding or file I/O operations.
+        FileNotFoundError: If the audio file was not created.
     """
     # Decode the base64-encoded audio into binary data.
     audio_bytes = base64.b64decode(base64_audio)
 
-    # Construct the full absolute file path within the AUDIO_DIR directory.
-    file_path = os.path.join(AUDIO_DIR, filename)
+    # Construct the full absolute file path within the AUDIO_DIR directory using Path.
+    file_path = Path(AUDIO_DIR) / filename
 
-    # Delete all audio files older than 30 minutes before writing new audio file.
+    # Delete all audio files older than 30 minutes before writing the new audio file.
     num_minutes = 30
     delete_files_older_than(AUDIO_DIR, num_minutes)
 
     # Write the binary audio data to the file.
-    with open(file_path, "wb") as audio_file:
+    with file_path.open("wb") as audio_file:
         audio_file.write(audio_bytes)
 
     # Verify that the file was created.
-    if not os.path.exists(file_path):
+    if not file_path.exists():
         raise FileNotFoundError(f"Audio file was not created at {file_path}")
 
-    # Compute a relative path for Gradio to serve (relative to the project root).
-    relative_path = os.path.relpath(file_path, os.getcwd())
+    # Compute a relative path for Gradio to serve (relative to the current working directory).
+    relative_path = file_path.relative_to(Path.cwd())
     logger.debug(f"Audio file absolute path: {file_path}")
     logger.debug(f"Audio file relative path: {relative_path}")
 
-    return relative_path
+    return str(relative_path)
 
 
 def choose_providers(
     text_modified: bool,
     character_description: str,
-) -> Tuple[ComparisonType, TTSProviderName, TTSProviderName]:
+) -> Tuple[TTSProviderName, TTSProviderName]:
     """
     Select two TTS providers based on whether the text has been modified.
 
@@ -236,69 +209,48 @@ def choose_providers(
         else random.choice(constants.TTS_PROVIDERS)
     )
 
-    match provider_b:
-        case constants.HUME_AI:
-            comparison_type = constants.HUME_TO_HUME
-        case constants.ELEVENLABS:
-            comparison_type = constants.HUME_TO_ELEVENLABS
-
-    return comparison_type, provider_a, provider_b
+    return provider_a, provider_b
 
 
-def create_shuffled_tts_options(
-    provider_a: TTSProviderName,
-    audio_a: str,
-    generation_id_a: str,
-    provider_b: TTSProviderName,
-    audio_b: str,
-    generation_id_b: str,
-) -> OptionMap:
+def create_shuffled_tts_options(option_a: Option, option_b: Option) -> OptionMap:
     """
     Create and shuffle TTS generation options.
 
-    This function creates two Option instances from the provided TTS details, shuffles them,
-    then extracts the providers, audio file paths, and generation IDs from the shuffled options,
-    and finally maps the options to an OptionMap.
+    This function accepts two TTS generation options, shuffles them randomly,
+    and returns an OptionMap with keys 'option_a' and 'option_b' corresponding
+    to the shuffled options.
 
     Args:
-        provider_a (TTSProviderName): The TTS provider for the first generation.
-        audio_a (str): The relative file path to the audio file for the first generation.
-        generation_id_a (str): The generation ID for the first generation.
-        provider_b (TTSProviderName): The TTS provider for the second generation.
-        audio_b (str): The relative file path to the audio file for the second generation.
-        generation_id_b (str): The generation ID for the second generation.
+        option_a (Option): The first TTS generation option.
+        option_b (Option): The second TTS generation option.
 
     Returns:
-        options_map (OptionMap): Mapping of TTS output options.
+        OptionMap: A mapping of shuffled TTS options, where each option includes
+                   its provider, audio file path, and generation ID.
     """
     # Create a list of Option instances for the available providers.
-    options = [
-        Option(provider=provider_a, audio=audio_a, generation_id=generation_id_a),
-        Option(provider=provider_b, audio=audio_b, generation_id=generation_id_b),
-    ]
+    options = [option_a, option_b]
 
     # Randomly shuffle the list of options.
     random.shuffle(options)
 
     # Unpack the two options.
-    option_a, option_b = options
+    shuffled_option_a, shuffled_option_b = options
 
     # Build a mapping from option constants to the corresponding providers.
-    options_map: OptionMap = {
+    return {
         "option_a": {
-            "provider": option_a.provider,
-            "generation_id": option_a.generation_id,
-            "audio_file_path": option_a.audio,
+            "provider": shuffled_option_a.provider,
+            "generation_id": shuffled_option_a.generation_id,
+            "audio_file_path": shuffled_option_a.audio,
         },
         "option_b": {
-            "provider": option_b.provider,
-            "generation_id": option_b.generation_id,
-            "audio_file_path": option_b.audio,
+            "provider": shuffled_option_b.provider,
+            "generation_id": shuffled_option_b.generation_id,
+            "audio_file_path": shuffled_option_b.audio,
         },
     }
 
-    return options_map
-
 
 def determine_selected_option(
     selected_option_button: str,
@@ -324,11 +276,38 @@ def determine_selected_option(
 
     return selected_option, other_option
 
+def determine_comparison_type(
+    provider_a: TTSProviderName,
+    provider_b: TTSProviderName
+) -> ComparisonType:
+    """
+    Determine the comparison type based on the given TTS provider names.
+
+    If both providers are HUME_AI, the comparison type is HUME_TO_HUME.
+    If either provider is ELEVENLABS, the comparison type is HUME_TO_ELEVENLABS.
+
+    Args:
+        provider_a (TTSProviderName): The first TTS provider.
+        provider_b (TTSProviderName): The second TTS provider.
+
+    Returns:
+        ComparisonType: The determined comparison type.
+
+    Raises:
+        ValueError: If the combination of providers is not recognized.
+    """
+    if provider_a == constants.HUME_AI and provider_b == constants.HUME_AI:
+        return constants.HUME_TO_HUME
+
+    if constants.ELEVENLABS in (provider_a, provider_b):
+        return constants.HUME_TO_ELEVENLABS
+
+    raise ValueError(f"Invalid provider combination: {provider_a}, {provider_b}")
+
 
 def submit_voting_results(
     option_map: OptionMap,
     selected_option: str,
-    comparison_type: ComparisonType,
     text_modified: bool,
     character_description: str,
     text: str,
@@ -347,12 +326,16 @@ def submit_voting_results(
     Returns:
         VotingResults: The constructed voting results dictionary.
     """
+    provider_a: TTSProviderName = option_map[constants.OPTION_A_KEY]["provider"]
+    provider_b: TTSProviderName = option_map[constants.OPTION_B_KEY]["provider"]
+    comparison_type: ComparisonType = determine_comparison_type(provider_a, provider_b)
+
     voting_results: VotingResults = {
         "comparison_type": comparison_type,
         "winning_provider": option_map[selected_option]["provider"],
         "winning_option": selected_option,
-        "option_a_provider": option_map[constants.OPTION_A_KEY]["provider"],
-        "option_b_provider": option_map[constants.OPTION_B_KEY]["provider"],
+        "option_a_provider": provider_a,
+        "option_b_provider": provider_b,
         "option_a_generation_id": option_map[constants.OPTION_A_KEY]["generation_id"],
         "option_b_generation_id": option_map[constants.OPTION_B_KEY]["generation_id"],
         "voice_description": character_description,