Zg/codebase refactor (#20)

* Decomposes frontend UI code
* Encapsulates TTS to a new TTSService
* Encapsulates interaction with voting DB to a VotingService
* Composed frontend code in frontend directory
* Services defined in core directory
* Shared utils, types, config, and constants in common directory
* Middleware in middleware directory
* Clean up type annotations and docstrings

README.md

@@ -36,33 +36,48 @@ For support or to join the conversation, visit our [Discord](https://discord.com
 
 ```
 Expressive TTS Arena/
-├── public/                     # Directory for public assets
-├── src/                        
-│   ├── database/
-│   │   ├── __init__.py         # Makes database a package; expose ORM methods
-│   │   ├── crud.py             # Defines operations for interacting with database
-│   │   ├── database.py         # Sets up SQLAlchemy database connection
-│   │   └── models.py           # SQLAlchemy database models
-│   ├── integrations/
-│   │   ├── __init__.py         # Makes integrations a package; exposes API clients
-│   │   ├── anthropic_api.py    # Anthropic API integration
-│   │   ├── elevenlabs_api.py   # ElevenLabs API integration
-│   │   └── hume_api.py         # Hume API integration
+├── public/
+├── src/
+│   ├── common/
+│   │   ├── __init__.py
+│   │   ├── common_types.py         # Application-wide custom type aliases and definitions.
+│   │   ├── config.py               # Manages application config (Singleton) loaded from env vars.
+│   │   ├── constants.py            # Application-wide constant values.
+│   │   ├── utils.py                # General-purpose utility functions used across modules.
+│   ├── core/
+│   │   ├── __init__.py
+│   │   ├── tts_service.py          # Service handling Text-to-Speech provider selection and API calls.
+│   │   ├── voting_service.py       # Service managing database operations for votes and leaderboards.
+│   ├── database/                   # Database access layer using SQLAlchemy.
+│   │   ├── __init__.py
+│   │   ├── crud.py                 # Data Access Objects (DAO) / CRUD operations for database models.
+│   │   ├── database.py             # Database connection setup (engine, session management).
+│   │   └── models.py               # SQLAlchemy ORM models defining database tables.
+│   ├── frontend/
+│   │   ├── components/
+│   │   │   │   ├── __init__.py     
+│   │   │   │   ├── arena.py        # UI definition and logic for the 'Arena' tab.
+│   │   │   │   ├── leaderboard.py  # UI definition and logic for the 'Leaderboard' tab.
+│   │   ├── __init__.py
+│   │   ├── frontend.py             # Main Gradio application class; orchestrates UI components and layout.
+│   ├── integrations/               # Modules for interacting with external third-party APIs.
+│   │   ├── __init__.py
+│   │   ├── anthropic_api.py        # Integration logic for the Anthropic API.
+│   │   ├── elevenlabs_api.py       # Integration logic for the ElevenLabs API.
+│   │   └── hume_api.py             # Integration logic for the Hume API.
+│   ├── middleware/
+│   │   ├── __init__.py
+│   │   ├── meta_tag_injection.py   # Middleware for injecting custom HTML meta tags into the Gradio page.
 │   ├── scripts/
-│   │   ├── __init__.py         # Makes scripts a package
-│   │   ├── init_db.py          # Script for initializing database
-│   │   ├── test_db.py          # Script for testing database connection
-│   ├── __init__.py             # Makes src a package
-│   ├── config.py               # Global config and logger setup
-│   ├── constants.py            # Global constants
-│   ├── custom_types.py         # Global custom types
-│   ├── frontend.py             # Gradio UI components
-│   ├── main.py                 # Entry file
-│   └── utils.py                # Utility functions
+│   │   ├── __init__.py
+│   │   ├── init_db.py              # Script to create database tables based on models.
+│   │   ├── test_db.py              # Script for testing the database connection configuration.
+│   ├── __init__.py
+│   ├── main.py                     # Main script to configure and run the Gradio application.
 │── static/
-│   ├── audio/                  # Directory for storing generated audio files
+│   ├── audio/                      # Temporary storage for generated audio files served to the UI.
 │   ├── css/
-│   │   ├── styles.css          # Defines custom css
+│   │   ├── styles.css              # Custom CSS overrides and styling for the Gradio UI.
 ├── .dockerignore
 ├── .env.example
 ├── .gitignore

pyproject.toml

@@ -88,7 +88,7 @@ select = [
     "TID",
     "W",
 ]
-per-file-ignores = { "src/constants.py" = ["E501"], "src/frontend.py" = ["E501"] }
+per-file-ignores = { "src/frontend/components/arena.py" = ["E501"], "src/frontend/components/leaderboard.py" = ["E501"], "src/middleware/meta_tag_injection.py" = ["E501"] }
 
 [tool.ruff.lint.pycodestyle]
 max-line-length = 120

src/common/__init__.py

@@ -0,0 +1,34 @@
+from . import constants
+from .common_types import (
+    ComparisonType,
+    LeaderboardEntry,
+    LeaderboardTableEntries,
+    Option,
+    OptionDetail,
+    OptionKey,
+    OptionLabel,
+    OptionMap,
+    TTSProviderName,
+    VotingResults,
+)
+from .config import Config, logger
+from .utils import save_base64_audio_to_file, validate_env_var
+
+__all__ = [
+    "ComparisonType",
+    "Config",
+    "LeaderboardEntry",
+    "LeaderboardTableEntries",
+    "Option",
+    "OptionDetail",
+    "OptionKey",
+    "OptionLabel",
+    "OptionMap",
+    "TTSProviderName",
+    "VotingResults",
+    "constants",
+    "logger",
+    "save_base64_audio_to_file",
+    "utils",
+    "validate_env_var",
+]

src/{custom_types.py → common/common_types.py}

@@ -1,9 +1,3 @@
-"""
-custom_types.py
-
-This module defines custom types for the application.
-"""
-
 # Standard Library Imports
 from typing import List, Literal, NamedTuple, Optional, TypedDict
 
@@ -12,8 +6,8 @@ TTSProviderName = Literal["Hume AI", "ElevenLabs", "OpenAI"]
 
 
 ComparisonType = Literal[
-    "Hume AI - Hume AI", 
-    "Hume AI - ElevenLabs", 
+    "Hume AI - Hume AI",
+    "Hume AI - ElevenLabs",
     "Hume AI - OpenAI",
     "OpenAI - ElevenLabs"
 ]
@@ -41,7 +35,6 @@ class Option(NamedTuple):
         audio (str): The relative file path to the audio file produced by the TTS provider.
         generation_id (str): The unique identifier for this TTS generation.
     """
-
     provider: TTSProviderName
     audio: str
     generation_id: str
@@ -49,7 +42,6 @@ class Option(NamedTuple):
 
 class VotingResults(TypedDict):
     """Voting results data structure representing values we want to persist to the votes DB"""
-
     comparison_type: ComparisonType
     winning_provider: TTSProviderName
     winning_option: OptionKey
@@ -71,7 +63,6 @@ class OptionDetail(TypedDict):
         generation_id (Optional[str]): The unique identifier for this TTS generation, or None if not available.
         audio_file_path (str): The relative file path to the generated audio file.
     """
-
     provider: TTSProviderName
     generation_id: Optional[str]
     audio_file_path: str
@@ -85,7 +76,6 @@ class OptionMap(TypedDict):
         option_a: OptionDetail,
         option_b: OptionDetail
     """
-
     option_a: OptionDetail
     option_b: OptionDetail
 

src/{config.py → common/config.py}

@@ -1,15 +1,3 @@
-"""
-config.py
-
-Global configuration and logger setup for the project.
-
-Key Features:
-- Uses environment variables defined in the system (Docker in production).
-- Loads a `.env` file only in development to simulate production variables locally.
-- Configures the logger for consistent logging across all modules.
-- Dynamically enables DEBUG logging in development and INFO logging in production (unless overridden).
-"""
-
 # Standard Library Imports
 import logging
 import os
@@ -75,7 +63,7 @@ class Config:
         audio_dir = Path.cwd() / "static" / "audio"
         audio_dir.mkdir(parents=True, exist_ok=True)
 
-        logger.info(f"Audio directory set to {audio_dir}")
+        logger.debug(f"Audio directory set to {audio_dir}")
 
         if debug:
             logger.debug("DEBUG mode enabled.")

src/common/constants.py

@@ -0,0 +1,49 @@
+# Standard Library Imports
+from typing import List
+
+# Third-Party Library Imports
+from .common_types import ComparisonType, OptionKey, TTSProviderName
+
+HUME_AI: TTSProviderName = "Hume AI"
+ELEVENLABS: TTSProviderName = "ElevenLabs"
+OPENAI: TTSProviderName = "OpenAI"
+
+TTS_PROVIDERS: List[TTSProviderName] = [HUME_AI, OPENAI, ELEVENLABS]
+
+HUME_TO_HUME: ComparisonType = "Hume AI - Hume AI"
+HUME_TO_ELEVENLABS: ComparisonType = "Hume AI - ElevenLabs"
+HUME_TO_OPENAI: ComparisonType = "Hume AI - OpenAI"
+OPENAI_TO_ELEVENLABS: ComparisonType = "OpenAI - ElevenLabs"
+
+TTS_PROVIDER_LINKS = {
+    "Hume AI": {
+        "provider_link": "https://hume.ai/",
+        "model_link": "https://www.hume.ai/blog/octave-the-first-text-to-speech-model-that-understands-what-its-saying"
+    },
+    "ElevenLabs": {
+        "provider_link": "https://elevenlabs.io/",
+        "model_link": "https://elevenlabs.io/blog/rvg",
+    },
+    "OpenAI": {
+        "provider_link": "https://openai.com/",
+        "model_link": "https://platform.openai.com/docs/models/gpt-4o-mini-tts",
+    }
+}
+
+CHARACTER_DESCRIPTION_MIN_LENGTH: int = 20
+CHARACTER_DESCRIPTION_MAX_LENGTH: int = 400
+
+TEXT_MIN_LENGTH: int = 100
+TEXT_MAX_LENGTH: int = 400
+
+OPTION_A_KEY: OptionKey = "option_a"
+OPTION_B_KEY: OptionKey = "option_b"
+
+SELECT_OPTION_A: str = "Select Option A"
+SELECT_OPTION_B: str = "Select Option B"
+
+CLIENT_ERROR_CODE = 400
+SERVER_ERROR_CODE = 500
+RATE_LIMIT_ERROR_CODE = 429
+
+GENERIC_API_ERROR_MESSAGE: str = "An unexpected error occurred while processing your request. Please try again shortly."

src/common/utils.py

@@ -0,0 +1,103 @@
+# Standard Library Imports
+import base64
+import os
+import time
+from pathlib import Path
+
+# Local Application Imports
+from .config import Config, logger
+
+
+def _delete_files_older_than(directory: Path, minutes: int = 30) -> None:
+    """
+    Delete all files in the specified directory that are older than a given number of minutes.
+
+    This function checks each file in the given directory and removes it if its last modification
+    time is older than the specified threshold. By default, the threshold is set to 30 minutes.
+
+    Args:
+        directory (str): The path to the directory where files will be checked and possibly deleted.
+        minutes (int, optional): The age threshold in minutes. Files older than this will be deleted.
+                                 Defaults to 30 minutes.
+
+    Returns: None
+    """
+    # Get the current time in seconds since the epoch.
+    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 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, config: Config) -> 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 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.
+        filename (str): The name of the file (including extension, e.g.,
+                        'b4a335da-9786-483a-b0a5-37e6e4ad5fd1.mp3') where the decoded
+                        audio will be saved.
+
+    Returns:
+        str: The relative file path to the saved audio file.
+
+    Raises:
+        FileNotFoundError: If the audio file was not created.
+    """
+
+    audio_bytes = base64.b64decode(base64_audio)
+    file_path = Path(config.audio_dir) / filename
+    num_minutes = 30
+
+    _delete_files_older_than(config.audio_dir, num_minutes)
+
+    # Write the binary audio data to the file.
+    with file_path.open("wb") as audio_file:
+        audio_file.write(audio_bytes)
+
+    # Verify that the file was created.
+    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 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 str(relative_path)
+
+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.
+    """
+    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

@@ -1,170 +0,0 @@
-"""
-constants.py
-
-This module defines global constants used throughout the project.
-"""
-
-# Standard Library Imports
-from typing import Dict, List
-
-# Third-Party Library Imports
-from src.custom_types import (
-    ComparisonType,
-    OptionKey,
-    OptionLabel,
-    TTSProviderName,
-)
-
-CLIENT_ERROR_CODE = 400
-SERVER_ERROR_CODE = 500
-RATE_LIMIT_ERROR_CODE = 429
-
-
-# UI constants
-HUME_AI: TTSProviderName = "Hume AI"
-ELEVENLABS: TTSProviderName = "ElevenLabs"
-OPENAI: TTSProviderName = "OpenAI"
-
-TTS_PROVIDERS: List[TTSProviderName] = ["Hume AI", "OpenAI", "ElevenLabs"]
-TTS_PROVIDER_LINKS = {
-    "Hume AI": {
-        "provider_link": "https://hume.ai/",
-        "model_link": "https://www.hume.ai/blog/octave-the-first-text-to-speech-model-that-understands-what-its-saying"
-    },
-    "ElevenLabs": {
-        "provider_link": "https://elevenlabs.io/",
-        "model_link": "https://elevenlabs.io/blog/rvg",
-    },
-    "OpenAI": {
-        "provider_link": "https://openai.com/",
-        "model_link": "https://platform.openai.com/docs/models/gpt-4o-mini-tts",
-    }
-}
-
-HUME_TO_HUME: ComparisonType = "Hume AI - Hume AI"
-HUME_TO_ELEVENLABS: ComparisonType = "Hume AI - ElevenLabs"
-HUME_TO_OPENAI: ComparisonType = "Hume AI - OpenAI"
-OPENAI_TO_ELEVENLABS: ComparisonType = "OpenAI - ElevenLabs"
-
-CHARACTER_DESCRIPTION_MIN_LENGTH: int = 20
-CHARACTER_DESCRIPTION_MAX_LENGTH: int = 400
-
-TEXT_MIN_LENGTH: int = 100
-TEXT_MAX_LENGTH: int = 400
-
-OPTION_A_KEY: OptionKey = "option_a"
-OPTION_B_KEY: OptionKey = "option_b"
-OPTION_A_LABEL: OptionLabel = "Option A"
-OPTION_B_LABEL: OptionLabel = "Option B"
-
-SELECT_OPTION_A: str = "Select Option A"
-SELECT_OPTION_B: str = "Select Option B"
-
-GENERIC_API_ERROR_MESSAGE: str = "An unexpected error occurred while processing your request. Please try again shortly."
-
-# A collection of pre-defined character descriptions categorized by theme, used to provide users with
-# inspiration for generating creative, expressive text inputs for TTS, and generating novel voices.
-SAMPLE_CHARACTER_DESCRIPTIONS: dict = {
-    "🦘 Australian Naturalist": (
-        "The speaker has a contagiously enthusiastic Australian accent, with the relaxed, sun-kissed vibe of a "
-        "wildlife expert fresh off the outback, delivering an amazing, laid-back narration."
-    ),
-    "🧘 Meditation Guru": (
-        "A mindfulness instructor with a gentle, soothing voice that flows at a slow, measured pace with natural "
-        "pauses. Their consistently calm, low-pitched tone has minimal variation, creating a peaceful auditory "
-        "experience."
-    ),
-    "🎬 Noir Detective": (
-        "A 1940s private investigator narrating with a gravelly voice and deliberate pacing. "
-        "Speaks with a cynical, world-weary tone that drops lower when delivering key observations."
-    ),
-    "🕯️ Victorian Ghost Storyteller": (
-        "The speaker is a Victorian-era raconteur speaking with a refined English accent and formal, precise diction. Voice "
-        "modulates between hushed, tense whispers and dramatic declarations when describing eerie occurrences."
-    ),
-    "🌿 English Naturalist": (
-        "Speaker is a wildlife documentarian speaking with a crisp, articulate English accent and clear enunciation. Voice "
-        "alternates between hushed, excited whispers and enthusiastic explanations filled with genuine wonder."
-    ),
-    "🌟 Texan Storyteller": (
-        "A speaker from rural Texas speaking with a warm voice and distinctive Southern drawl featuring elongated "
-        "vowels. Talks unhurriedly with a musical quality and occasional soft laughter."
-    ),
-    "🏄 Chill Surfer": (
-        "The speaker is a California surfer talking with a casual, slightly nasal voice and laid-back rhythm. Uses rising "
-        "inflections at sentence ends and bursts into spontaneous laughter when excited."
-    ),
-    "📢 Old-School Radio Announcer": (
-        "The speaker has the voice of a seasoned horse race announcer, with a booming, energetic voice, a touch of "
-        "old-school radio charm, and the enthusiastic delivery of a viral commentator."
-    ),
-    "👑 Obnoxious Royal": (
-        "Speaker is a member of the English royal family speaks in a smug and authoritative voice in an obnoxious, proper "
-        "English accent. They are insecure, arrogant, and prone to tantrums."
-    ),
-    "🏰 Medieval Peasant": (
-        "A film portrayal of a medieval peasant speaking with a thick cockney accent and a worn voice, "
-        "dripping with sarcasm and self-effacing humor."
-    ),
-}
-
-
-# HTML and social media metadata for the Gradio application
-# These tags define SEO-friendly content and provide rich previews when shared on social platforms
-META_TAGS: List[Dict[str, str]] = [
-    # HTML Meta Tags (description)
-    {
-        'name': 'description',
-        'content': 'An open-source web application for comparing and evaluating the expressiveness of different text-to-speech models, including Hume AI and ElevenLabs.'
-    },
-    # Facebook Meta Tags
-    {
-        'property': 'og:url',
-        'content': 'https://hume.ai'
-    },
-    {
-        'property': 'og:type',
-        'content': 'website'
-    },
-    {
-        'property': 'og:title',
-        'content': 'Expressive TTS Arena'
-    },
-    {
-        'property': 'og:description',
-        'content': 'An open-source web application for comparing and evaluating the expressiveness of different text-to-speech models, including Hume AI and ElevenLabs.'
-    },
-    {
-        'property': 'og:image',
-        'content': '/static/arena-opengraph-logo.png'
-    },
-    # Twitter Meta Tags
-    {
-        'name': 'twitter:card',
-        'content': 'summary_large_image'
-    },
-    {
-        'property': 'twitter:domain',
-        'content': 'hume.ai'
-    },
-    {
-        'property': 'twitter:url',
-        'content': 'https://hume.ai'
-    },
-    {
-        'name': 'twitter:creator',
-        'content': '@hume_ai'
-    },
-    {
-        'name': 'twitter:title',
-        'content': 'Expressive TTS Arena'
-    },
-    {
-        'name': 'twitter:description',
-        'content': 'An open-source web application for comparing and evaluating the expressiveness of different text-to-speech models, including Hume AI and ElevenLabs.'
-    },
-    {
-        'name': 'twitter:image',
-        'content': '/static/arena-opengraph-logo.png'
-    }
-]

src/core/__init__.py

@@ -0,0 +1,4 @@
+from .tts_service import TTSService
+from .voting_service import VotingService
+
+__all__ = ["TTSService", "VotingService"]

src/core/tts_service.py

@@ -0,0 +1,120 @@
+# Standard Library Imports
+import asyncio
+import random
+from typing import Tuple
+
+# Local Application Imports
+from src.common import Config, Option, OptionMap, TTSProviderName, logger
+from src.common.constants import ELEVENLABS, HUME_AI, OPENAI
+from src.integrations import (
+    text_to_speech_with_elevenlabs,
+    text_to_speech_with_hume,
+    text_to_speech_with_openai,
+)
+
+
+class TTSService:
+    """
+    Service for coordinating text-to-speech generation across different providers.
+
+    This class handles the logic for selecting TTS providers, making concurrent API calls,
+    and processing the responses into a unified format for the frontend.
+    """
+
+    def __init__(self, config: Config):
+        """
+        Initialize the TTS service with application configuration.
+
+        Args:
+            config (Config): Application configuration containing API settings
+        """
+        self.config = config
+        self.tts_provider_functions = {
+            HUME_AI: text_to_speech_with_hume,
+            ELEVENLABS: text_to_speech_with_elevenlabs,
+            OPENAI: text_to_speech_with_openai,
+        }
+
+    def __select_providers(self, text_modified: bool) -> Tuple[TTSProviderName, TTSProviderName]:
+        """
+        Select 2 TTS providers based on whether the text has been modified.
+
+        Probabilities:
+         - 50% HUME_AI, OPENAI
+         - 25% OPENAI, ELEVENLABS
+         - 20% HUME_AI, ELEVENLABS
+         - 5% HUME_AI, HUME_AI
+
+        If the `text_modified` argument is `True`, then 100% HUME_AI, HUME_AI
+
+        Args:
+            text_modified (bool): A flag indicating whether the text has been modified
+
+        Returns:
+            tuple: A tuple (TTSProviderName, TTSProviderName)
+        """
+        if text_modified:
+            return HUME_AI, HUME_AI
+
+        # When modifying the probability distribution, make sure the weights match the order of provider pairs
+        provider_pairs = [
+            (HUME_AI, OPENAI),
+            (OPENAI, ELEVENLABS),
+            (HUME_AI, ELEVENLABS),
+            (HUME_AI, HUME_AI)
+        ]
+        weights = [0.5, 0.25, 0.2, 0.05]
+
+        return random.choices(provider_pairs, weights=weights, k=1)[0]
+
+    async def synthesize_speech(
+        self,
+        character_description: str,
+        text: str,
+        text_modified: bool
+    ) -> OptionMap:
+        """
+        Generate speech for the given text using two different TTS providers.
+
+        This method selects appropriate providers based on the text modification status,
+        makes concurrent API calls to those providers, and returns the results.
+
+        Args:
+            character_description (str): Description of the character/voice for synthesis
+            text (str): The text to synthesize into speech
+            text_modified (bool): Whether the text has been modified from the original
+
+        Returns:
+            OptionMap: A mapping of shuffled TTS options, where each option includes
+                    its provider, audio file path, and generation ID.
+        """
+        provider_a, provider_b = self.__select_providers(text_modified)
+
+        logger.info(f"Starting speech synthesis with providers: {provider_a} and {provider_b}")
+
+        task_a = self.tts_provider_functions[provider_a](character_description, text, self.config)
+        task_b = self.tts_provider_functions[provider_b](character_description, text, self.config)
+
+        (generation_id_a, audio_a), (generation_id_b, audio_b) = await asyncio.gather(task_a, task_b)
+
+        logger.info(f"Synthesis succeeded for providers: {provider_a} and {provider_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 = [option_a, option_b]
+        random.shuffle(options)
+        shuffled_option_a, shuffled_option_b = options
+
+        return {
+            "option_a": {
+                "provider": shuffled_option_a.provider,
+                "generation_id": shuffled_option_a.generation_id,
+                "audio_file_path": shuffled_option_a.audio,
+            },
+            "option_b": {
+                "provider": shuffled_option_b.provider,
+                "generation_id": shuffled_option_b.generation_id,
+                "audio_file_path": shuffled_option_b.audio,
+            },
+        }

src/core/voting_service.py

@@ -0,0 +1,281 @@
+# Standard Library Imports
+import json
+from typing import List, Tuple
+
+# Third-Party Library Imports
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# Local Application Imports
+from src.common import (
+    ComparisonType,
+    LeaderboardEntry,
+    OptionKey,
+    OptionMap,
+    TTSProviderName,
+    VotingResults,
+    constants,
+    logger,
+)
+from src.database import (
+    AsyncDBSessionMaker,
+    create_vote,
+    get_head_to_head_battle_stats,
+    get_head_to_head_win_rate_stats,
+    get_leaderboard_stats,
+)
+
+
+class VotingService:
+    """
+    Service for handling all database interactions related to voting and leaderboards.
+
+    Encapsulates logic for submitting votes and retrieving formatted leaderboard statistics.
+    """
+
+    def __init__(self, db_session_maker: AsyncDBSessionMaker):
+        """
+        Initializes the VotingService.
+
+        Args:
+            db_session_maker: An asynchronous database session factory.
+        """
+        self.db_session_maker: AsyncDBSessionMaker = db_session_maker
+        logger.debug("VotingService initialized.")
+
+    async def _create_db_session(self) -> AsyncSession | None:
+        """
+        Creates a new database session, returning None if it's a dummy session.
+
+        Returns:
+            An active AsyncSession or None if using a dummy session factory.
+        """
+        session = self.db_session_maker()
+        # Check for a dummy session marker if your factory provides one
+        is_dummy_session = getattr(session, "is_dummy", False)
+
+        if is_dummy_session:
+            logger.debug("Using dummy DB session; operations will be skipped.")
+            # Ensure dummy sessions are also closed if they have resources
+            if hasattr(session, "close"):
+                await session.close()
+            return None
+
+        logger.debug("Created new DB session.")
+        return session
+
+    def _determine_comparison_type(self, provider_a: TTSProviderName, provider_b: TTSProviderName) -> ComparisonType:
+        """
+        Determine the comparison type based on the given TTS provider names.
+
+        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
+
+        providers = (provider_a, provider_b)
+
+        if constants.HUME_AI in providers and constants.ELEVENLABS in providers:
+            return constants.HUME_TO_ELEVENLABS
+
+        if constants.HUME_AI in providers and constants.OPENAI in providers:
+            return constants.HUME_TO_OPENAI
+
+        if constants.ELEVENLABS in providers and constants.OPENAI in providers:
+            return constants.OPENAI_TO_ELEVENLABS
+
+        raise ValueError(f"Invalid provider combination: {provider_a}, {provider_b}")
+
+    async def _persist_vote(self, voting_results: VotingResults) -> None:
+        """
+        Persists a vote record in the database using a dedicated session.
+
+        Handles session creation, commit, rollback, and closure. Logs errors internally.
+
+        Args:
+            voting_results: A dictionary containing the vote details.
+        """
+        session = await self._create_db_session()
+        if session is None:
+            logger.info("Skipping vote persistence (dummy session).")
+            self._log_voting_results(voting_results)
+            return
+
+        try:
+            self._log_voting_results(voting_results)
+            await create_vote(session, voting_results)
+            logger.info("Vote successfully persisted.")
+        except Exception as e:
+            logger.error(f"Failed to persist vote record: {e}", exc_info=True)
+        finally:
+            await session.close()
+            logger.debug("DB session closed after persisting vote.")
+
+    def _log_voting_results(self, voting_results: VotingResults) -> None:
+        """Logs the full voting results dictionary."""
+        try:
+            logger.info("Voting results:\n%s", json.dumps(voting_results, indent=4, default=str))
+        except TypeError:
+            logger.error("Could not serialize voting results for logging.")
+            logger.info(f"Voting results (raw): {voting_results}")
+
+    def _format_leaderboard_data(self, leaderboard_data_raw: List[LeaderboardEntry]) -> List[List[str]]:
+        """Formats raw leaderboard entries into HTML strings for the UI table."""
+        formatted_data = []
+        for rank, provider, model, win_rate, votes in leaderboard_data_raw:
+            provider_info = constants.TTS_PROVIDER_LINKS.get(provider, {})
+            provider_link = provider_info.get("provider_link", "#")
+            model_link = provider_info.get("model_link", "#")
+
+            formatted_data.append([
+                f'<p style="text-align: center;">{rank}</p>',
+                f'<a href="{provider_link}" target="_blank" class="provider-link">{provider}</a>',
+                f'<a href="{model_link}" target="_blank" class="provider-link">{model}</a>',
+                f'<p style="text-align: center;">{win_rate}</p>',
+                f'<p style="text-align: center;">{votes}</p>',
+            ])
+        return formatted_data
+
+
+    def _format_battle_counts_data(self, battle_counts_data_raw: List[List[str]]) -> List[List[str]]:
+        """Formats raw battle counts into an HTML matrix for the UI."""
+        battle_counts_dict = {item[0]: str(item[1]) for item in battle_counts_data_raw}
+        providers = constants.TTS_PROVIDERS
+
+        formatted_matrix: List[List[str]] = []
+        for row_provider in providers:
+            row = [f'<p style="padding-left: 8px;"><strong>{row_provider}</strong></p>']
+            for col_provider in providers:
+                if row_provider == col_provider:
+                    cell_value = "-"
+                else:
+                    comparison_key = self._determine_comparison_type(row_provider, col_provider)
+                    cell_value = battle_counts_dict.get(comparison_key, "0")
+                row.append(f'<p style="text-align: center;">{cell_value}</p>')
+            formatted_matrix.append(row)
+        return formatted_matrix
+
+
+    def _format_win_rate_data(self, win_rate_data_raw: List[List[str]]) -> List[List[str]]:
+        """Formats raw win rates into an HTML matrix for the UI."""
+        # win_rate_data_raw expected as [comparison_type, first_win_rate_str, second_win_rate_str]
+        win_rates = {}
+        for comparison_type, first_win_rate, second_win_rate in win_rate_data_raw:
+            # Comparison type should already be canonical 'ProviderA - ProviderB'
+            try:
+                provider1, provider2 = comparison_type.split(" - ")
+                win_rates[(provider1, provider2)] = first_win_rate
+                win_rates[(provider2, provider1)] = second_win_rate
+            except ValueError:
+                logger.warning(f"Could not parse comparison_type '{comparison_type}' in win rate data.")
+                continue # Skip malformed entry
+
+        providers = constants.TTS_PROVIDERS
+        formatted_matrix: List[List[str]] = []
+        for row_provider in providers:
+            row = [f'<p style="padding-left: 8px;"><strong>{row_provider}</strong></p>']
+            for col_provider in providers:
+                cell_value = "-" if row_provider == col_provider else win_rates.get((row_provider, col_provider), "0%")
+                row.append(f'<p style="text-align: center;">{cell_value}</p>')
+            formatted_matrix.append(row)
+        return formatted_matrix
+
+    async def get_formatted_leaderboard_data(self) -> Tuple[
+        List[List[str]],
+        List[List[str]],
+        List[List[str]],
+    ]:
+        """
+        Fetches raw leaderboard stats and formats them for UI display.
+
+        Retrieves overall rankings, battle counts, and win rates, then formats
+        them into HTML strings suitable for Gradio DataFrames.
+
+        Returns:
+            A tuple containing formatted lists of lists for:
+            - Leaderboard rankings table
+            - Battle counts matrix
+            - Win rate matrix
+            Returns empty lists ([[]], [[]], [[]]) on failure.
+        """
+        session = await self._create_db_session()
+        if session is None:
+            logger.info("Skipping leaderboard fetch (dummy session).")
+            return [[]], [[]], [[]]
+
+        try:
+            # Fetch raw data using underlying CRUD functions
+            leaderboard_data_raw = await get_leaderboard_stats(session)
+            battle_counts_data_raw = await get_head_to_head_battle_stats(session)
+            win_rate_data_raw = await get_head_to_head_win_rate_stats(session)
+            logger.debug("Fetched raw leaderboard data successfully.")
+
+            # Format the data
+            leaderboard_data = self._format_leaderboard_data(leaderboard_data_raw)
+            battle_counts_data = self._format_battle_counts_data(battle_counts_data_raw)
+            win_rate_data = self._format_win_rate_data(win_rate_data_raw)
+
+            return leaderboard_data, battle_counts_data, win_rate_data
+
+        except Exception as e:
+            logger.error(f"Failed to fetch and format leaderboard data: {e}", exc_info=True)
+            return [[]], [[]], [[]] # Return empty structure on error
+        finally:
+            await session.close()
+            logger.debug("DB session closed after fetching leaderboard data.")
+
+    async def submit_vote(
+        self,
+        option_map: OptionMap,
+        selected_option: OptionKey,
+        text_modified: bool,
+        character_description: str,
+        text: str,
+    ) -> None:
+        """
+        Constructs and persists a vote record based on user selection and context.
+
+        This method is designed to be called safely from background tasks, handling all internal exceptions.
+
+        Args:
+            option_map: Mapping of comparison data and TTS options.
+            selected_option: The option key ('option_a' or 'option_b') selected by the user.
+            text_modified: Indicates if the text was custom vs. generated.
+            character_description: Description used for TTS generation.
+            text: The text synthesized.
+        """
+        try:
+            provider_a: TTSProviderName = option_map[constants.OPTION_A_KEY]["provider"]
+            provider_b: TTSProviderName = option_map[constants.OPTION_B_KEY]["provider"]
+
+            comparison_type: ComparisonType = self._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": 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"],
+                "character_description": character_description,
+                "text": text,
+                "is_custom_text": text_modified,
+            }
+
+            await self._persist_vote(voting_results)
+
+        except KeyError as e:
+            logger.error(
+                f"Missing key in option_map during vote submission: {e}. OptionMap: {option_map}",
+                exc_info=True
+            )
+        except Exception as e:
+            logger.error(f"Unexpected error in submit_vote: {e}", exc_info=True)

src/database/crud.py

@@ -1,10 +1,3 @@
-"""
-crud.py
-
-This module defines the operations for the Expressive TTS Arena project's database.
-Since vote records are never updated or deleted, only functions to create and read votes are provided.
-"""
-
 # Standard Library Imports
 from typing import List
 
@@ -14,9 +7,9 @@ from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 # Local Application Imports
-from src.config import logger
-from src.custom_types import LeaderboardEntry, LeaderboardTableEntries, VotingResults
-from src.database.models import VoteResult
+from src.common import LeaderboardEntry, LeaderboardTableEntries, VotingResults, logger
+
+from .models import VoteResult
 
 
 async def create_vote(db: AsyncSession, vote_data: VotingResults) -> VoteResult:
@@ -31,7 +24,6 @@ async def create_vote(db: AsyncSession, vote_data: VotingResults) -> VoteResult:
         VoteResult: The newly created vote record.
     """
     try:
-
         # Create vote record
         vote = VoteResult(
             comparison_type=vote_data["comparison_type"],

src/database/database.py

@@ -1,13 +1,3 @@
-"""
-database.py
-
-This module sets up the SQLAlchemy database connection for the Expressive TTS Arena project.
-It initializes the PostgreSQL engine, creates a session factory for handling database transactions,
-and defines a declarative base class for ORM models.
-
-If no DATABASE_URL environment variable is set, then create a dummy database to fail gracefully.
-"""
-
 # Standard Library Imports
 from typing import Callable, Optional, TypeAlias, Union
 
@@ -16,14 +6,13 @@ from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
 from sqlalchemy.orm import DeclarativeBase
 
 # Local Application Imports
-from src.config import Config, logger
+from src.common import Config, logger
 
 
 # Define the SQLAlchemy Base
 class Base(DeclarativeBase):
     pass
 
-
 class DummyAsyncSession:
     is_dummy = True  # Flag to indicate this is a dummy session.
 
@@ -53,11 +42,9 @@ class DummyAsyncSession:
         # No-op: nothing to close.
         pass
 
-
 AsyncDBSessionMaker: TypeAlias = Union[async_sessionmaker[AsyncSession], Callable[[], DummyAsyncSession]]
 engine: Optional[AsyncEngine] = None
 
-
 def init_db(config: Config) -> AsyncDBSessionMaker:
     """
     Initialize the database engine and return a session factory based on the provided configuration.
@@ -99,4 +86,3 @@ def init_db(config: Config) -> AsyncDBSessionMaker:
         return DummyAsyncSession()
 
     return async_dummy_session_factory
-

src/database/models.py

@@ -1,10 +1,3 @@
-"""
-models.py
-
-This module defines the SQLAlchemy ORM models for the Expressive TTS Arena project.
-It currently defines the VoteResult model representing the vote_results table.
-"""
-
 # Standard Library Imports
 from enum import Enum
 
@@ -27,14 +20,13 @@ from sqlalchemy import (
 )
 
 # Local Application Imports
-from src.database.database import Base
+from .database import Base
 
 
 class OptionEnum(str, Enum):
     OPTION_A = "option_a"
     OPTION_B = "option_b"
 
-
 class VoteResult(Base):
     __tablename__ = "vote_results"
 

src/frontend/__init__.py

@@ -0,0 +1,3 @@
+from .frontend import Frontend
+
+__all__ = ["Frontend"]

src/frontend/components/__init__.py

@@ -0,0 +1,4 @@
+from .arena import Arena
+from .leaderboard import Leaderboard
+
+__all__ = ["Arena", "Leaderboard"]

src/{frontend.py → frontend/components/arena.py}

@@ -1,125 +1,170 @@
-"""
-frontend.py
-
-Gradio UI for interacting with the Anthropic API, Hume TTS API, and ElevenLabs TTS API.
-
-Users enter a character description, which is processed using Claude by Anthropic to generate text.
-The text is then synthesized into speech using different TTS provider APIs.
-Users can compare the outputs and vote for their favorite in an interactive UI.
-"""
-
 # Standard Library Imports
 import asyncio
-import hashlib
-import json
+import random
 import time
-from typing import List, Optional, Tuple
+from typing import Tuple, Union
 
 # Third-Party Library Imports
 import gradio as gr
 
 # Local Application Imports
-from src import constants
-from src.config import Config, logger
-from src.custom_types import Option, OptionMap
-from src.database import AsyncDBSessionMaker
-from src.integrations import (
-    AnthropicError,
-    ElevenLabsError,
-    HumeError,
-    OpenAIError,
-    generate_text_with_claude,
-    text_to_speech_with_elevenlabs,
-    text_to_speech_with_hume,
-    text_to_speech_with_openai,
-)
-from src.utils import (
-    create_shuffled_tts_options,
-    determine_selected_option,
-    get_leaderboard_data,
-    get_random_providers,
-    submit_voting_results,
-    validate_character_description_length,
-    validate_text_length,
-)
-
-
-class Frontend:
-    config: Config
-    db_session_maker: AsyncDBSessionMaker
-
-    def __init__(self, config: Config, db_session_maker: AsyncDBSessionMaker):
-        self.config = config
-        self.db_session_maker = db_session_maker
-
-        # leaderboard update state
-        self._leaderboard_data: List[List[str]] = [[]]
-        self._battle_counts_data: List[List[str]] = [[]]
-        self._win_rates_data: List[List[str]] = [[]]
-        self._leaderboard_cache_hash: Optional[str] = None
-        self._last_leaderboard_update_time: float = 0.0
-        self._min_refresh_interval = 30
-
-    async def _update_leaderboard_data(self, force: bool = False) -> bool:
+from src.common import Config, OptionKey, OptionLabel, OptionMap, constants, logger
+from src.core import TTSService, VotingService
+from src.integrations import AnthropicError, ElevenLabsError, HumeError, OpenAIError, generate_text_with_claude
+
+OPTION_A_LABEL: OptionLabel = "Option A"
+OPTION_B_LABEL: OptionLabel = "Option B"
+
+# A collection of pre-defined character descriptions categorized by theme, used to provide users with
+# inspiration for generating creative, expressive text inputs for TTS, and generating novel voices.
+SAMPLE_CHARACTER_DESCRIPTIONS: dict = {
+    "🦘 Australian Naturalist": (
+        "The speaker has a contagiously enthusiastic Australian accent, with the relaxed, sun-kissed vibe of a "
+        "wildlife expert fresh off the outback, delivering an amazing, laid-back narration."
+    ),
+    "🧘 Meditation Guru": (
+        "A mindfulness instructor with a gentle, soothing voice that flows at a slow, measured pace with natural "
+        "pauses. Their consistently calm, low-pitched tone has minimal variation, creating a peaceful auditory "
+        "experience."
+    ),
+    "🎬 Noir Detective": (
+        "A 1940s private investigator narrating with a gravelly voice and deliberate pacing. "
+        "Speaks with a cynical, world-weary tone that drops lower when delivering key observations."
+    ),
+    "🕯️ Victorian Ghost Storyteller": (
+        "The speaker is a Victorian-era raconteur speaking with a refined English accent and formal, precise diction. Voice "
+        "modulates between hushed, tense whispers and dramatic declarations when describing eerie occurrences."
+    ),
+    "🌿 English Naturalist": (
+        "Speaker is a wildlife documentarian speaking with a crisp, articulate English accent and clear enunciation. Voice "
+        "alternates between hushed, excited whispers and enthusiastic explanations filled with genuine wonder."
+    ),
+    "🌟 Texan Storyteller": (
+        "A speaker from rural Texas speaking with a warm voice and distinctive Southern drawl featuring elongated "
+        "vowels. Talks unhurriedly with a musical quality and occasional soft laughter."
+    ),
+    "🏄 Chill Surfer": (
+        "The speaker is a California surfer talking with a casual, slightly nasal voice and laid-back rhythm. Uses rising "
+        "inflections at sentence ends and bursts into spontaneous laughter when excited."
+    ),
+    "📢 Old-School Radio Announcer": (
+        "The speaker has the voice of a seasoned horse race announcer, with a booming, energetic voice, a touch of "
+        "old-school radio charm, and the enthusiastic delivery of a viral commentator."
+    ),
+    "👑 Obnoxious Royal": (
+        "Speaker is a member of the English royal family speaks in a smug and authoritative voice in an obnoxious, proper "
+        "English accent. They are insecure, arrogant, and prone to tantrums."
+    ),
+    "🏰 Medieval Peasant": (
+        "A film portrayal of a medieval peasant speaking with a thick cockney accent and a worn voice, "
+        "dripping with sarcasm and self-effacing humor."
+    ),
+}
+
+class Arena:
+    """
+    Handles the user interface logic, state management, and event handling
+    for the 'Arena' tab where users generate, synthesize, and compare TTS audio.
+    """
+    def __init__(self, config: Config, tts_service: TTSService, voting_service: VotingService):
         """
-        Fetches the latest leaderboard data only if needed based on cache and time constraints.
+        Initializes the Arena component.
 
         Args:
-            force (bool): If True, bypass the time-based throttling.
+            config: The application configuration object.
+            tts_service: The service for TTS operations.
+            voting_service: The service for voting/leaderboard DB operations.
+        """
+        self.config: Config = config
+        self.tts_service = tts_service
+        self.voting_service = voting_service
 
-        Returns:
-            bool: True if the leaderboard was updated, False otherwise.
+    def _validate_input_length(
+        self,
+        input_value: str,
+        min_length: int,
+        max_length: int,
+        input_name: str,
+    ) -> None:
+        """
+        Validates input string length against minimum and maximum limits.
+
+        Args:
+            input_value: The string value to validate.
+            min_length: The minimum required length (inclusive).
+            max_length: The maximum allowed length (inclusive).
+            input_name: A descriptive name of the input field (e.g., "character description")
+                        used for error messages.
+
+        Raises:
+            ValueError: If the input length is outside the specified bounds.
+        """
+        stripped_value = input_value.strip()
+        value_length = len(stripped_value)
+        logger.debug(f"Validating length for '{input_name}': {value_length} characters")
+
+        if value_length < min_length:
+            raise ValueError(
+                f"Your {input_name} is too short. Please enter at least "
+                f"{min_length} characters. (Current length: {value_length})"
+            )
+        if value_length > max_length:
+            raise ValueError(
+                f"Your {input_name} is too long. Please limit it to "
+                f"{max_length} characters. (Current length: {value_length})"
+            )
+
+    def _validate_character_description_length(self, character_description: str) -> None:
+        """
+        Validates the character description length using predefined constants.
+
+        Args:
+            character_description: The input character description to validate.
+
+        Raises:
+            ValueError: If the character description length is invalid.
         """
-        current_time = time.time()
-        time_since_last_update = current_time - self._last_leaderboard_update_time
-
-        # Skip update if it's been less than min_refresh_interval seconds and not forced
-        if not force and time_since_last_update < self._min_refresh_interval:
-            logger.debug(f"Skipping leaderboard update: last updated {time_since_last_update:.1f}s ago.")
-            return False
-
-        # Fetch the latest data
-        (
-            latest_leaderboard_data,
-            latest_battle_counts_data,
-            latest_win_rates_data
-        ) = await get_leaderboard_data(self.db_session_maker)
-
-        # Generate a hash of the new data to check if it's changed
-        data_str = json.dumps(str(latest_leaderboard_data))
-        data_hash = hashlib.md5(data_str.encode()).hexdigest()
-
-        # Check if the data has changed
-        if data_hash == self._leaderboard_cache_hash and not force:
-            logger.debug("Leaderboard data unchanged since last fetch.")
-            return False
-
-        # Update the cache and timestamp
-        self._leaderboard_data = latest_leaderboard_data
-        self._battle_counts_data = latest_battle_counts_data
-        self._win_rates_data = latest_win_rates_data
-        self._leaderboard_cache_hash = data_hash
-        self._last_leaderboard_update_time = current_time
-        logger.info("Leaderboard data updated successfully.")
-        return True
-
-    async def _generate_text(self, character_description: str) -> Tuple[gr.Textbox, str]:
+        self._validate_input_length(
+            character_description,
+            constants.CHARACTER_DESCRIPTION_MIN_LENGTH,
+            constants.CHARACTER_DESCRIPTION_MAX_LENGTH,
+            "character description",
+        )
+
+    def _validate_text_length(self, text: str) -> None:
         """
-        Validates the character_description and generates text using Anthropic API.
+        Validates the input text length using predefined constants.
 
         Args:
-            character_description (str): The user-provided text for character description.
+            text: The input text to validate.
+
+        Raises:
+            ValueError: If the text length is invalid.
+        """
+        self._validate_input_length(
+            text,
+            constants.TEXT_MIN_LENGTH,
+            constants.TEXT_MAX_LENGTH,
+            "text",
+        )
+
+    async def _generate_text(self, character_description: str) -> Tuple[dict, str]:
+        """
+        Validates the character description and generates text using the Anthropic API.
+
+        Args:
+            character_description: The user-provided text for character description.
 
         Returns:
-            Tuple containing:
-              - The generated text update (as a dict from gr.update).
-              - The generated text string.
+            A tuple containing:
+              - A Gradio update dictionary for the text input component.
+              - The generated text string (also used for state).
 
         Raises:
-            gr.Error: On validation or API errors.
+            gr.Error: On validation failure or Anthropic API errors.
         """
         try:
-            validate_character_description_length(character_description)
+            self._validate_character_description_length(character_description)
         except ValueError as ve:
             logger.warning(f"Validation error: {ve}")
             raise gr.Error(str(ve))
@@ -132,100 +177,78 @@ class Frontend:
             logger.error(f"Text Generation Failed: AnthropicError while generating text: {ae!s}")
             raise gr.Error(f'There was an issue communicating with the Anthropic API: "{ae.message}"')
         except Exception as e:
-            logger.error(f"Text Generation Failed: Unexpected error while generating text: {e!s}")
+            logger.error(f"Text Generation Failed: Unexpected error while generating text: {e!s}", exc_info=True)
             raise gr.Error("Failed to generate text. Please try again shortly.")
 
     def _warn_user_about_custom_text(self, text: str, generated_text: str) -> None:
         """
-        Shows a warning to the user if they have modified the generated text.
-
-        When users edit the generated text instead of using it as-is, only Hume Octave
-        outputs will be generated for comparison rather than comparing against other
-        providers. This function displays a warning to inform users of this limitation.
+        Displays a Gradio warning if the input text differs from the generated text state.
+        This informs the user that using custom text limits the comparison to only Hume outputs.
 
         Args:
-            text (str): The current text that will be used for synthesis.
-            generated_text (str): The original text that was generated by the system.
-
-        Returns:
-            None: This function displays a warning but does not return any value.
+            text: The current text in the input component.
+            generated_text: The original text generated by the system (stored in state).
         """
         if text != generated_text:
-            gr.Warning("When custom text is used, only Hume Octave outputs are generated.")
+            gr.Warning("When custom text is used, only Hume Octave outputs are generated for comparison.")
 
     async def _synthesize_speech(
         self,
         character_description: str,
         text: str,
         generated_text_state: str,
-    ) -> Tuple[gr.Audio, gr.Audio, OptionMap, bool, str, str, bool]:
+    ) -> Tuple[dict, dict, OptionMap, bool, str, str, bool]:
         """
-        Synthesizes two text-to-speech outputs, updates UI state components, and returns additional TTS metadata.
-
-        This function generates TTS outputs using different providers based on the input text and its modification
-        state.
+        Validates inputs and synthesizes two TTS outputs for comparison.
 
-        The outputs are processed and shuffled, and the corresponding UI components for two audio players are updated.
-        Additional metadata such as the comparison type, generation IDs, and state information are also returned.
+        Generates TTS audio using different providers (or only Hume if text was
+        modified), updates UI state, and returns audio paths and metadata.
 
         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.
+            character_description: The description used for voice generation.
+            text: The text content to synthesize.
+            generated_text_state: The previously generated text state to check for modifications.
 
         Returns:
-            Tuple containing:
-                - gr.Audio: Update for the first audio player (with autoplay enabled).
-                - gr.Audio: Update for the second audio player.
-                - OptionMap: A mapping of option constants to their corresponding TTS providers.
-                - bool: Flag indicating whether the text was modified.
-                - str: The original text that was synthesized.
-                - str: The original character description.
-                - bool: Flag indicating whether the vote buttons should be enabled
+            A tuple containing:
+                - dict: Gradio update for the first audio player (Option A).
+                - dict: Gradio update for the second audio player (Option B).
+                - OptionMap: Mapping of options ('option_a', 'option_b') to provider details.
+                - bool: Flag indicating if the input text was modified from the generated state.
+                - str: The text string that was synthesized (for state).
+                - str: The character description used (for state).
+                - bool: Flag indicating whether the vote buttons should be enabled.
 
         Raises:
-            gr.Error: If any API or unexpected errors occur during the TTS synthesis process.
+            gr.Error: On validation failure or errors during TTS synthesis API calls.
         """
         try:
-            validate_character_description_length(character_description)
-            validate_text_length(text)
+            self._validate_character_description_length(character_description)
+            self._validate_text_length(text)
         except ValueError as ve:
-            logger.warning(f"Validation error: {ve}")
+            logger.error(f"Validation error during speech synthesis: {ve}")
             raise gr.Error(str(ve))
 
-        text_modified = text != generated_text_state
-        provider_a, provider_b = get_random_providers(text_modified)
-
-        tts_provider_funcs = {
-            constants.HUME_AI: text_to_speech_with_hume,
-            constants.OPENAI: text_to_speech_with_openai,
-            constants.ELEVENLABS: text_to_speech_with_elevenlabs,
-        }
-
         try:
-            logger.info(f"Starting speech synthesis with providers: {provider_a} and {provider_b}")
-
-            # Create two tasks for concurrent execution
-            task_a = tts_provider_funcs[provider_a](character_description, text, self.config)
-            task_b = tts_provider_funcs[provider_b](character_description, text, self.config)
+            text_modified = text != generated_text_state
+            options_map: OptionMap = await self.tts_service.synthesize_speech(character_description, text, text_modified)
 
-            # Await both tasks concurrently using asyncio.gather()
-            (generation_id_a, audio_a), (generation_id_b, audio_b) = await asyncio.gather(task_a, task_b)
-            logger.info(f"Synthesis succeeded for providers: {provider_a} and {provider_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)
+            # Ensure options_map has the expected keys before accessing
+            if "option_a" not in options_map or "option_b" not in options_map:
+                 logger.error(f"Invalid options_map received from TTS service: {options_map}")
+                 raise gr.Error("Internal error: Failed to retrieve synthesis results correctly.")
+            if not options_map.get("option_a") or not options_map.get("option_b"):
+                 logger.error(f"Missing data in options_map from TTS service: {options_map}")
+                 raise gr.Error("Internal error: Missing synthesis results.")
 
             return (
                 gr.update(value=options_map["option_a"]["audio_file_path"], autoplay=True),
                 gr.update(value=options_map["option_b"]["audio_file_path"]),
                 options_map,
                 text_modified,
-                text,
-                character_description,
-                True,
+                text, # text_state update
+                character_description, # character_description_state update
+                True, # should_enable_vote_buttons update
             )
         except HumeError as he:
             logger.error(f"Synthesis failed with HumeError during TTS generation: {he!s}")
@@ -237,157 +260,171 @@ class Frontend:
             logger.error(f"Synthesis failed with ElevenLabsError during TTS generation: {ee!s}")
             raise gr.Error(f'There was an issue communicating with the Elevenlabs API: "{ee.message}"')
         except Exception as e:
-            logger.error(f"Synthesis failed with an unexpected error during TTS generation: {e!s}")
+            logger.error(f"Synthesis failed with an unexpected error during TTS generation: {e!s}", exc_info=True)
             raise gr.Error("An unexpected error occurred. Please try again shortly.")
 
-    async def _vote(
+    def _determine_selected_option(self, selected_option_button_value: str) -> Tuple[OptionKey, OptionKey]:
+        """
+        Determines the selected option key ('option_a'/'option_b') based on the button value.
+
+        Args:
+            selected_option_button_value: The value property of the clicked vote button
+                                         (e.g., constants.SELECT_OPTION_A).
+
+        Returns:
+            A tuple (selected_option_key, other_option_key).
+
+        Raises:
+            ValueError: If the button value is not one of the expected constants.
+        """
+        if selected_option_button_value == constants.SELECT_OPTION_A:
+            selected_option, other_option = constants.OPTION_A_KEY, constants.OPTION_B_KEY
+        elif selected_option_button_value == constants.SELECT_OPTION_B:
+            selected_option, other_option = constants.OPTION_B_KEY, constants.OPTION_A_KEY
+        else:
+            logger.error(f"Invalid selected button value received: {selected_option_button_value}")
+            raise ValueError(f"Invalid selected button: {selected_option_button_value}")
+
+        return selected_option, other_option
+
+    async def _submit_vote(
         self,
         vote_submitted: bool,
         option_map: OptionMap,
-        clicked_option_button: str,
+        clicked_option_button_value: str, # Renamed for clarity (it's the button's value, not the component)
         text_modified: bool,
         character_description: str,
         text: str,
     ) -> Tuple[
-        bool,
-        gr.Button,
-        gr.Button,
-        gr.Textbox,
-        gr.Textbox,
-        gr.Button
+        Union[bool, gr.skip],
+        Union[dict, gr.skip],
+        Union[dict, gr.skip],
+        Union[dict, gr.skip],
+        Union[dict, gr.skip],
+        Union[dict, gr.skip]
     ]:
         """
-        Handles user voting and updates the UI to display vote results.
+        Handles user voting, submits results asynchronously, and updates the UI.
+
+        Prevents duplicate votes and updates button visibility and result textboxes.
 
         Args:
-            vote_submitted (bool): True if a vote was already submitted.
-            option_map (OptionMap): A dictionary mapping option labels to their details.
-            clicked_option_button (str): The button that was clicked.
-            text_modified (bool): Whether the text was modified by the user.
-            character_description (str): The character description.
-            text (str): The text used for synthesis.
+            vote_submitted: Boolean state indicating if a vote was already submitted for this pair.
+            option_map: The OptionMap dictionary containing details of the two options.
+            clicked_option_button_value: The value of the button that was clicked (e.g., constants.SELECT_OPTION_A).
+            text_modified: Boolean state indicating if the text was modified by the user.
+            character_description: The character description used for synthesis (from state).
+            text: The text used for synthesis (from state).
 
         Returns:
-            A tuple of:
-            - bool: A boolean indicating if the vote was accepted.
-            - A dict update for hiding vote button A.
-            - A dict update for hiding vote button B.
-            - A dict update for showing vote result A textbox.
-            - A dict update for showing vote result B textbox.
-            - A dict update for enabling the synthesize speech button.
+            A tuple of updates for various UI components and state variables,
+            or multiple gr.skip() objects if the vote is ignored (e.g., duplicate).
+            Elements are:
+            - bool | gr.skip: Update for vote_submitted_state (True if vote processed).
+            - dict | gr.skip: Update for vote_button_a (visibility).
+            - dict | gr.skip: Update for vote_button_b (visibility).
+            - dict | gr.skip: Update for vote_result_a (visibility, value, style).
+            - dict | gr.skip: Update for vote_result_b (visibility, value, style).
+            - dict | gr.skip: Update for synthesize_speech_button (interactivity).
         """
-        if not option_map or vote_submitted:
+        # If option_map is empty/invalid or vote already submitted, do nothing
+        if not isinstance(option_map, dict) or not option_map or vote_submitted:
+            logger.warning(f"Vote submission skipped. Option map valid: {isinstance(option_map, dict) and bool(option_map)}, Vote submitted: {vote_submitted}")
+            # Return gr.skip() for all outputs
             return gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip()
 
-        selected_option, other_option = determine_selected_option(clicked_option_button)
-        selected_provider = option_map[selected_option]["provider"]
-        other_provider = option_map[other_option]["provider"]
-
-        # Process vote in the background without blocking the UI
-        asyncio.create_task(
-            submit_voting_results(
-                option_map,
-                selected_option,
-                text_modified,
-                character_description,
-                text,
-                self.db_session_maker,
+        try:
+            selected_option, other_option = self._determine_selected_option(clicked_option_button_value)
+
+            # Ensure keys exist before accessing
+            if selected_option not in option_map or other_option not in option_map:
+                logger.error(f"Selected/Other option key missing in option_map: {selected_option}, {other_option}, Map: {option_map}")
+                raise gr.Error("Internal error: Could not process vote due to inconsistent data.")
+            if "provider" not in option_map[selected_option] or "provider" not in option_map[other_option]:
+                 logger.error(f"Provider missing in option_map entry: Map: {option_map}")
+                 raise gr.Error("Internal error: Could not process vote due to missing provider data.")
+
+            selected_provider = option_map[selected_option]["provider"]
+            other_provider = option_map[other_option]["provider"]
+
+            # Process vote in the background without blocking the UI
+            asyncio.create_task(
+                self.voting_service.submit_vote(
+                    option_map,
+                    selected_option,
+                    text_modified,
+                    character_description,
+                    text,
+                )
             )
-        )
+            logger.info(f"Vote submitted: Selected '{selected_provider}', Other '{other_provider}'")
 
-        # Build button text to display results
-        selected_label = f"{selected_provider} 🏆"
-        other_label = f"{other_provider}"
+            # Build result labels
+            selected_label = f"{selected_provider} 🏆"
+            other_label = f"{other_provider}"
 
-        return (
-            True,
-            gr.update(visible=False),
-            gr.update(visible=False),
-            (
-                gr.update(value=selected_label, visible=True, elem_classes="winner")
-                if selected_option == constants.OPTION_A_KEY
-                else gr.update(value=other_label, visible=True)
-            ),
-            (
-                gr.update(value=other_label, visible=True)
-                if selected_option == constants.OPTION_A_KEY
-                else gr.update(value=selected_label, visible=True, elem_classes="winner")
-            ),
-            gr.update(interactive=True),
-        )
+            # Determine which result box gets which label
+            result_a_update = gr.update(value=other_label, visible=True)
+            result_b_update = gr.update(value=selected_label, visible=True, elem_classes="winner")
+            if selected_option == constants.OPTION_A_KEY:
+                 result_a_update = gr.update(value=selected_label, visible=True, elem_classes="winner")
+                 result_b_update = gr.update(value=other_label, visible=True)
 
-    async def _randomize_character_description(self) -> Tuple[gr.Dropdown, gr.Textbox]:
+
+            return (
+                True, # Update vote_submitted_state to True
+                gr.update(visible=False), # Hide vote button A
+                gr.update(visible=False), # Hide vote button B
+                result_a_update, # Show/update result textbox A
+                result_b_update, # Show/update result textbox B
+                gr.update(interactive=True), # Re-enable synthesize speech button
+            )
+        except ValueError as ve: # Catch error from _determine_selected_option
+             logger.error(f"Vote submission failed due to invalid button value: {ve}", exc_info=True)
+             # Optionally raise gr.Error or just skip updates
+             gr.Error("An internal error occurred while processing your vote.")
+             return gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip()
+        except Exception as e:
+            logger.error(f"Vote submission failed unexpectedly: {e!s}", exc_info=True)
+            gr.Error("An unexpected error occurred while submitting your vote.")
+            # Still return skips to avoid partial UI updates
+            return gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip(), gr.skip()
+
+    async def _randomize_character_description(self) -> Tuple[dict, dict]:
         """
-        Randomly selects a character description, generates text, and synthesizes speech.
+        Selects a random character description from the predefined samples.
 
         Returns:
-            Tuple containing updates for:
-                - sample_character_description_dropdown (select random)
-                - character_description_input (update value)
+            A tuple containing Gradio update dictionaries for:
+                - The sample character dropdown component.
+                - The character description input component.
         """
-        import random
+        # Ensure SAMPLE_CHARACTER_DESCRIPTIONS is not empty
+        if not SAMPLE_CHARACTER_DESCRIPTIONS:
+             logger.warning("SAMPLE_CHARACTER_DESCRIPTIONS is empty. Cannot randomize.")
+             # Return updates that clear the fields or do nothing
+             return gr.update(value=None), gr.update(value="")
 
-        sample_keys = list(constants.SAMPLE_CHARACTER_DESCRIPTIONS.keys())
+        sample_keys = list(SAMPLE_CHARACTER_DESCRIPTIONS.keys())
         random_sample = random.choice(sample_keys)
-        character_description = constants.SAMPLE_CHARACTER_DESCRIPTIONS[random_sample]
+        character_description = SAMPLE_CHARACTER_DESCRIPTIONS[random_sample]
 
         logger.info(f"Randomize All: Selected '{random_sample}'")
 
         return (
-            gr.update(value=random_sample), # Update dropdown
-            gr.update(value=character_description), # Update character description
+            gr.update(value=random_sample), # Update dropdown selection
+            gr.update(value=character_description), # Update character description text
         )
 
-    async def _refresh_leaderboard(self, force: bool = False) -> Tuple[gr.DataFrame, gr.DataFrame, gr.DataFrame]:
-        """
-        Asynchronously fetches and formats the latest leaderboard data.
-
-        Args:
-            force (bool): If True, bypass time-based throttling.
-
-        Returns:
-            tuple: Updated DataFrames or gr.skip() if no update needed
-        """
-        data_updated = await self._update_leaderboard_data(force=force)
-
-        if not self._leaderboard_data:
-            raise gr.Error("Unable to retrieve leaderboard data. Please refresh the page or try again shortly.")
-
-        if data_updated or force:
-            return (
-                gr.update(value=self._leaderboard_data),
-                gr.update(value=self._battle_counts_data),
-                gr.update(value=self._win_rates_data)
-            )
-        return gr.skip(), gr.skip(), gr.skip()
-
-    async def _handle_tab_select(self, evt: gr.SelectData):
+    def _disable_ui(self) -> Tuple[dict, dict, dict, dict, dict, dict, dict, dict]:
         """
-        Handles tab selection events and refreshes the leaderboard if the Leaderboard tab is selected.
-
-        Args:
-            evt (gr.SelectData): Event data containing information about the selected tab
+        Disables interactive UI components during processing.
 
         Returns:
-            tuple: Updates for the three tables if data changed, otherwise skip
-        """
-        if evt.value == "Leaderboard":
-            return await self._refresh_leaderboard(force=False)
-        return gr.skip(), gr.skip(), gr.skip()
-
-    def _disable_ui(self) -> Tuple[
-        gr.Button,
-        gr.Dropdown,
-        gr.Textbox,
-        gr.Button,
-        gr.Textbox,
-        gr.Button,
-        gr.Button,
-        gr.Button
-    ]:
-        """
-        Disables all interactive components in the UI (except audio players)
+            A tuple of Gradio update dictionaries to set interactive=False
+            for relevant buttons, dropdowns, and textboxes.
         """
+        logger.debug("Disabling UI components.")
         return(
             gr.update(interactive=False), # disable Randomize All button
             gr.update(interactive=False), # disable Character Description dropdown
@@ -399,19 +436,20 @@ class Frontend:
             gr.update(interactive=False), # disable Select B Button
         )
 
-    def _enable_ui(self, should_enable_vote_buttons) -> Tuple[
-        gr.Button,
-        gr.Dropdown,
-        gr.Textbox,
-        gr.Button,
-        gr.Textbox,
-        gr.Button,
-        gr.Button,
-        gr.Button
-    ]:
+    def _enable_ui(self, should_enable_vote_buttons: bool) -> Tuple[dict, dict, dict, dict, dict, dict, dict, dict]:
         """
-        Enables all interactive components in the UI (except audio players)
+        Enables interactive UI components after processing.
+
+        Args:
+            should_enable_vote_buttons: Boolean indicating if the voting buttons
+                                         should be enabled (based on synthesis success).
+
+        Returns:
+            A tuple of Gradio update dictionaries to set interactive=True
+            for relevant buttons, dropdowns, and textboxes. Vote buttons'
+            interactivity depends on the input argument.
         """
+        logger.debug(f"Enabling UI components. Enable vote buttons: {should_enable_vote_buttons}")
         return(
             gr.update(interactive=True), # enable Randomize All button
             gr.update(interactive=True), # enable Character Description dropdown
@@ -419,78 +457,55 @@ class Frontend:
             gr.update(interactive=True), # enable Generate Text button
             gr.update(interactive=True), # enable Input Text input
             gr.update(interactive=True), # enable Synthesize Speech Button
-            gr.update(interactive=should_enable_vote_buttons), # enable Select A Button
-            gr.update(interactive=should_enable_vote_buttons), # enable Select B Button
+            gr.update(interactive=should_enable_vote_buttons), # enable/disable Select A Button
+            gr.update(interactive=should_enable_vote_buttons), # enable/disable Select B Button
         )
 
-    def _reset_voting_ui(self) -> Tuple[
-        gr.Audio,
-        gr.Audio,
-        gr.Button,
-        gr.Button,
-        gr.Textbox,
-        gr.Textbox,
-        OptionMap,
-        bool,
-        bool,
-    ]:
+    def _reset_voting_ui(self) -> Tuple[dict, dict, dict, dict, dict, dict, OptionMap, bool, bool]:
         """
-        Resets voting UI state and clear audio players
+        Resets the voting UI elements to their initial state before new synthesis.
+
+        Clears audio players, makes vote buttons visible, hides result textboxes,
+        and resets associated state variables.
+
+        Returns:
+            A tuple containing updates for UI components and state variables:
+            - dict: Update for audio player A (clear value).
+            - dict: Update for audio player B (clear value, disable autoplay).
+            - dict: Update for vote button A (make visible).
+            - dict: Update for vote button B (make visible).
+            - dict: Update for vote result A (hide, clear style).
+            - dict: Update for vote result B (hide, clear style).
+            - OptionMap: Reset option_map_state to a default placeholder.
+            - bool: Reset vote_submitted_state to False.
+            - bool: Reset should_enable_vote_buttons state to False.
         """
+        logger.debug("Resetting voting UI.")
         default_option_map: OptionMap = {
             "option_a": {"provider": constants.HUME_AI, "generation_id": None, "audio_file_path": ""},
             "option_b": {"provider": constants.HUME_AI, "generation_id": None, "audio_file_path": ""},
         }
         return (
-            gr.update(value=None),  # clear audio for audio player A
-            gr.update(value=None, autoplay=False), # clear audio and disable autoplay for audio player B
-            gr.update(visible=True), # show vote button A
-            gr.update(visible=True), # show vote button B
-            gr.update(visible=False, elem_classes=[]), # hide vote result A and clear custom styling
-            gr.update(visible=False, elem_classes=[]), # hide vote result B and clear custom styling
-            default_option_map, # Reset option_map_state as a default OptionMap
+            gr.update(value=None, label=OPTION_A_LABEL),  # clear audio player A, reset label
+            gr.update(value=None, autoplay=False, label=OPTION_B_LABEL), # clear audio player B, ensure autoplay off, reset label
+            gr.update(visible=True, interactive=False), # show vote button A, ensure non-interactive until enabled
+            gr.update(visible=True, interactive=False), # show vote button B, ensure non-interactive until enabled
+            gr.update(value="", visible=False, elem_classes=[]), # hide vote result A, clear text/style
+            gr.update(value="", visible=False, elem_classes=[]), # hide vote result B, clear text/style
+            default_option_map, # Reset option_map_state
             False, # Reset vote_submitted_state
             False, # Reset should_enable_vote_buttons state
         )
 
-    def _build_title_section(self) -> None:
-        """
-        Builds the Title section
+    def build_arena_section(self) -> None:
         """
-        gr.HTML(
-            value="""
-            <div class="title-container">
-                <h1>Expressive TTS Arena</h1>
-                <div class="social-links">
-                    <a
-                        href="https://discord.com/invite/humeai"
-                        target="_blank"
-                        id="discord-link"
-                        title="Join our Discord"
-                        aria-label="Join our Discord server"
-                    ></a>
-                    <a
-                        href="https://github.com/HumeAI/expressive-tts-arena"
-                        target="_blank"
-                        id="github-link"
-                        title="View on GitHub"
-                        aria-label="View project on GitHub"
-                    ></a>
-                </div>
-            </div>
-            <div class="excerpt-container">
-                <p>
-                    Join the community in evaluating text-to-speech models, and vote for the AI voice that best
-                    captures the emotion, nuance, and expressiveness of human speech.
-                </p>
-            </div>
-            """
-        )
+        Constructs the Gradio UI layout for the Arena tab and registers event handlers.
 
-    def _build_arena_section(self) -> None:
-        """
-        Builds the Arena section
+        This method defines all the components within the Arena tab and connects
+        button clicks, dropdown selections, etc., to their corresponding handler functions.
         """
+        logger.debug("Building Arena UI section...")
+
         # --- UI components ---
         with gr.Row():
             with gr.Column(scale=5):
@@ -525,7 +540,7 @@ class Frontend:
             )
 
         sample_character_description_dropdown = gr.Dropdown(
-            choices=list(constants.SAMPLE_CHARACTER_DESCRIPTIONS.keys()),
+            choices=list(SAMPLE_CHARACTER_DESCRIPTIONS.keys()),
             label="Sample Characters",
             info="Generate text with a sample character description.",
             value=None,
@@ -561,12 +576,12 @@ class Frontend:
             with gr.Column():
                 with gr.Group():
                     option_a_audio_player = gr.Audio(
-                        label=constants.OPTION_A_LABEL,
+                        label=OPTION_A_LABEL,
                         type="filepath",
                         interactive=False,
                         show_download_button=False,
                     )
-                    vote_button_a = gr.Button(constants.SELECT_OPTION_A, interactive=False)
+                    vote_button_a = gr.Button(value=constants.SELECT_OPTION_A, interactive=False)
                     vote_result_a = gr.Textbox(
                         interactive=False,
                         visible=False,
@@ -577,12 +592,12 @@ class Frontend:
             with gr.Column():
                 with gr.Group():
                     option_b_audio_player = gr.Audio(
-                        label=constants.OPTION_B_LABEL,
+                        label=OPTION_B_LABEL,
                         type="filepath",
                         interactive=False,
                         show_download_button=False,
                     )
-                    vote_button_b = gr.Button(constants.SELECT_OPTION_B, interactive=False)
+                    vote_button_b = gr.Button(value=constants.SELECT_OPTION_B, interactive=False)
                     vote_result_b = gr.Textbox(
                         interactive=False,
                         visible=False,
@@ -599,7 +614,7 @@ class Frontend:
         # Track generated text state
         generated_text_state = gr.State("")
         # Track whether text that was used was generated or modified/custom
-        text_modified_state = gr.State()
+        text_modified_state = gr.State(False)
         # Track option map (option A and option B are randomized)
         option_map_state = gr.State({})  # OptionMap state as a dictionary
         # Track whether the user has voted for an option
@@ -683,7 +698,7 @@ class Frontend:
         # 3. Generate text
         # 4. Enable interactive UI components
         sample_character_description_dropdown.select(
-            fn=lambda choice: constants.SAMPLE_CHARACTER_DESCRIPTIONS.get(choice, ""),
+            fn=lambda choice: SAMPLE_CHARACTER_DESCRIPTIONS.get(choice, ""),
             inputs=[sample_character_description_dropdown],
             outputs=[character_description_input],
         ).then(
@@ -826,7 +841,7 @@ class Frontend:
             inputs=[],
             outputs=[vote_button_a, vote_button_b],
         ).then(
-            fn=self._vote,
+            fn=self._submit_vote,
             inputs=[
                 vote_submitted_state,
                 option_map_state,
@@ -851,7 +866,7 @@ class Frontend:
             inputs=[],
             outputs=[vote_button_a, vote_button_b],
         ).then(
-            fn=self._vote,
+            fn=self._submit_vote,
             inputs=[
                 vote_submitted_state,
                 option_map_state,
@@ -881,178 +896,4 @@ class Frontend:
             outputs=[option_b_audio_player],
         )
 
-    def _build_leaderboard_section(self) -> gr.DataFrame:
-        """
-        Builds the Leaderboard section
-        """
-        # --- UI components ---
-        with gr.Row():
-            with gr.Column(scale=5):
-                gr.HTML(
-                    value="""
-                    <h2 class="tab-header">🏆 Leaderboard</h2>
-                    <p style="padding-left: 8px;">
-                        This leaderboard presents community voting results for different TTS providers, showing which
-                        ones users found more expressive and natural-sounding. The win rate reflects how often each
-                        provider was selected as the preferred option in head-to-head comparisons. Click the refresh
-                        button to see the most up-to-date voting results.
-                    </p>
-                    """,
-                    padding=False,
-                )
-            refresh_button = gr.Button(
-                "↻ Refresh",
-                variant="primary",
-                elem_classes="refresh-btn",
-                scale=1,
-            )
-
-        with gr.Column(elem_id="leaderboard-table-container"):
-            leaderboard_table = gr.DataFrame(
-                headers=["Rank", "Provider", "Model", "Win Rate", "Votes"],
-                datatype=["html", "html", "html", "html", "html"],
-                column_widths=[80, 300, 180, 120, 116],
-                value=self._leaderboard_data,
-                min_width=680,
-                interactive=False,
-                render=True,
-                elem_id="leaderboard-table"
-            )
-
-        with gr.Column():
-            gr.HTML(
-                value="""
-                <h2 style="padding-top: 12px;" class="tab-header">📊 Head-to-Head Matchups</h2>
-                <p style="padding-left: 8px; width: 80%;">
-                    These tables show how each provider performs against others in direct comparisons.
-                    The first table shows the total number of comparisons between each pair of providers.
-                    The second table shows the win rate (percentage) of the row provider against the column provider.
-                </p>
-                """,
-                padding=False
-            )
-
-        with gr.Row(equal_height=True):
-            with gr.Column(min_width=420):
-                battle_counts_table = gr.DataFrame(
-                    headers=["", "Hume AI", "OpenAI", "ElevenLabs"],
-                    datatype=["html", "html", "html", "html"],
-                    column_widths=[132, 132, 132, 132],
-                    value=self._battle_counts_data,
-                    interactive=False,
-                )
-            with gr.Column(min_width=420):
-                win_rates_table = gr.DataFrame(
-                    headers=["", "Hume AI", "OpenAI", "ElevenLabs"],
-                    datatype=["html", "html", "html", "html"],
-                    column_widths=[132, 132, 132, 132],
-                    value=self._win_rates_data,
-                    interactive=False,
-                )
-
-        with gr.Accordion(label="Citation", open=False):
-            with gr.Column(variant="panel"):
-                with gr.Column(variant="panel"):
-                    gr.HTML(
-                        value="""
-                        <h2>Citation</h2>
-                        <p style="padding: 0 8px;">
-                            When referencing this leaderboard or its dataset in academic publications, please cite:
-                        </p>
-                        """,
-                        padding=False,
-                    )
-                    gr.Markdown(
-                        value="""
-                        **BibTeX**
-                        ```BibTeX
-                        @misc{expressive-tts-arena,
-                            title = {Expressive TTS Arena: An Open Platform for Evaluating Text-to-Speech Expressiveness by Human Preference},
-                            author = {Alan Cowen, Zachary Greathouse, Richard Marmorstein, Jeremy Hadfield},
-                            year = {2025},
-                            publisher = {Hugging Face},
-                            howpublished = {\\url{https://huggingface.co/spaces/HumeAI/expressive-tts-arena}}
-                        }
-                        ```
-                        """
-                    )
-                    gr.HTML(
-                        value="""
-                        <h2>Terms of Use</h2>
-                        <p style="padding: 0 8px;">
-                            Users are required to agree to the following terms before using the service:
-                        </p>
-                        <p style="padding: 0 8px;">
-                            All generated audio clips are provided for research and evaluation purposes only.
-                            The audio content may not be redistributed or used for commercial purposes without
-                            explicit permission. Users should not upload any private or personally identifiable
-                            information. Please report any bugs, issues, or concerns to our
-                            <a href="https://discord.com/invite/humeai" target="_blank" class="provider-link">
-                                Discord community
-                            </a>.
-                        </p>
-                        """,
-                        padding=False,
-                    )
-                    gr.HTML(
-                        value="""
-                        <h2>Acknowledgements</h2>
-                        <p style="padding: 0 8px;">
-                            We thank all participants who contributed their votes to help build this leaderboard.
-                        </p>
-                        """,
-                        padding=False,
-                    )
-
-        # Wrapper for the async refresh function
-        async def async_refresh_handler():
-            leaderboard_update, battle_counts_update, win_rates_update = await self._refresh_leaderboard(force=True)
-            return leaderboard_update, battle_counts_update, win_rates_update
-
-        # Handler to re-enable the button after a refresh
-        def reenable_button():
-            time.sleep(3) # wait 3 seconds before enabling to prevent excessive data fetching
-            return gr.update(interactive=True)
-
-        # Refresh button click event handler
-        refresh_button.click(
-            fn=lambda _=None: (gr.update(interactive=False)),
-            inputs=[],
-            outputs=[refresh_button],
-        ).then(
-            fn=async_refresh_handler,
-            inputs=[],
-            outputs=[leaderboard_table, battle_counts_table, win_rates_table]  # Update all three tables
-        ).then(
-            fn=reenable_button,
-            inputs=[],
-            outputs=[refresh_button]
-        )
-
-        return leaderboard_table, battle_counts_table, win_rates_table
-
-    async def build_gradio_interface(self) -> gr.Blocks:
-        """
-        Builds and configures the fully constructed Gradio UI layout.
-        """
-        with gr.Blocks(
-            title="Expressive TTS Arena",
-            css_paths="static/css/styles.css",
-        ) as demo:
-            await self._update_leaderboard_data()
-            self._build_title_section()
-
-            with gr.Tabs() as tabs:
-                with gr.TabItem("Arena"):
-                    self._build_arena_section()
-                with gr.TabItem("Leaderboard"):
-                    leaderboard_table, battle_counts_table, win_rates_table = self._build_leaderboard_section()
-
-            tabs.select(
-                fn=self._handle_tab_select,
-                inputs=[],
-                outputs=[leaderboard_table, battle_counts_table, win_rates_table],
-            )
-
-        logger.debug("Gradio interface built successfully")
-        return demo
+        logger.debug("Arena UI section built.")

src/frontend/components/leaderboard.py

@@ -0,0 +1,298 @@
+# Standard Library Imports
+import hashlib
+import json
+import time
+from typing import List, Optional, Tuple, Union
+
+# Third-Party Library Imports
+import gradio as gr
+
+# Local Application Imports
+from src.common import logger
+from src.core import VotingService
+
+
+class Leaderboard:
+    """
+    Manages the state, data fetching, and UI construction for the Leaderboard tab.
+
+    Includes caching and throttling for leaderboard data updates.
+    """
+    def __init__(self, voting_service: VotingService):
+        """
+        Initializes the Leaderboard component.
+
+        Args:
+            voting_service: The service for voting/leaderboard DB operations.
+        """
+        self.voting_service = voting_service
+
+        # leaderboard update state
+        self.leaderboard_data: List[List[str]] = [[]]
+        self.battle_counts_data: List[List[str]] = [[]]
+        self.win_rates_data: List[List[str]] = [[]]
+        self.leaderboard_cache_hash: Optional[str] = None
+        self.last_leaderboard_update_time: float = 0.0
+        self.min_refresh_interval: int = 30
+
+    async def _update_leaderboard_data(self, force: bool = False) -> bool:
+        """
+        Fetches leaderboard data from the source if cache is stale or force=True.
+
+        Updates internal state variables (leaderboard_data, battle_counts_data,
+        win_rates_data, cache_hash, last_update_time) if new data is fetched.
+        Uses time-based throttling defined by `min_refresh_interval`.
+
+        Args:
+            force: If True, bypasses cache hash check and time throttling.
+
+        Returns:
+            True if the leaderboard data state was updated, False otherwise.
+        """
+        current_time = time.time()
+        time_since_last_update = current_time - self.last_leaderboard_update_time
+
+        # Skip update if throttled and not forced
+        if not force and time_since_last_update < self.min_refresh_interval:
+            logger.debug(f"Skipping leaderboard update (throttled): last updated {time_since_last_update:.1f}s ago.")
+            return False
+
+        try:
+            # Fetch the latest data
+            (
+                latest_leaderboard_data,
+                latest_battle_counts_data,
+                latest_win_rates_data
+            ) = await self.voting_service.get_formatted_leaderboard_data()
+
+            # Check if data is valid before proceeding
+            if not latest_leaderboard_data or not latest_leaderboard_data[0]:
+                logger.error("Invalid data received from get_leaderboard_data.")
+                return False
+
+            # Generate a hash of the primary leaderboard data to check for changes
+            # Use a stable serialization format (sort_keys=True)
+            data_str = json.dumps(latest_leaderboard_data, sort_keys=True)
+            new_data_hash = hashlib.md5(data_str.encode()).hexdigest()
+
+            # Skip if data hasn't changed and not forced
+            if not force and new_data_hash == self.leaderboard_cache_hash:
+                logger.debug("Leaderboard data unchanged since last fetch.")
+                return False
+
+            # Update the state and cache
+            self.leaderboard_data = latest_leaderboard_data
+            self.battle_counts_data = latest_battle_counts_data
+            self.win_rates_data = latest_win_rates_data
+            self.leaderboard_cache_hash = new_data_hash
+            self.last_leaderboard_update_time = current_time
+            logger.info("Leaderboard data updated successfully.")
+            return True
+
+        except Exception as e:
+             logger.error(f"Failed to update leaderboard data: {e!s}", exc_info=True)
+             return False
+
+    async def refresh_leaderboard(
+        self, force: bool = False
+    ) -> Tuple[Union[dict, gr.skip], Union[dict, gr.skip], Union[dict, gr.skip]]:
+        """
+        Refreshes leaderboard data state and returns Gradio updates for the tables.
+
+        Calls `_update_leaderboard_data` and returns updates only if data changed
+        or `force` is True. Returns gr.skip() otherwise.
+
+        Args:
+            force: If True, forces `_update_leaderboard_data` to bypass throttling/cache.
+
+        Returns:
+            A tuple of Gradio update dictionaries for the leaderboard, battle counts,
+            and win rates tables, or gr.skip() for each if no update is needed.
+
+        Raises:
+            gr.Error: If leaderboard data is empty/invalid after attempting an update.
+                      (Changed from previous: now raises only if data is *still* bad)
+        """
+        data_updated = await self._update_leaderboard_data(force=force)
+
+        if not self.leaderboard_data or not isinstance(self.leaderboard_data[0], list):
+            logger.error("Leaderboard data is empty or invalid after update attempt.")
+            raise gr.Error("Unable to retrieve leaderboard data. Please refresh the page or try again shortly.")
+
+        if data_updated or force:
+            logger.debug("Returning leaderboard table updates.")
+            return (
+                gr.update(value=self.leaderboard_data),
+                gr.update(value=self.battle_counts_data),
+                gr.update(value=self.win_rates_data)
+            )
+        logger.debug("Skipping leaderboard table updates (no data change).")
+        return gr.skip(), gr.skip(), gr.skip()
+
+    async def build_leaderboard_section(self) -> Tuple[gr.DataFrame, gr.DataFrame, gr.DataFrame]:
+        """
+        Constructs the Gradio UI layout for the Leaderboard tab.
+
+        Defines the DataFrames, HTML descriptions, and refresh button logic.
+
+        Returns:
+            A tuple containing the Gradio DataFrame components for:
+            - Main Leaderboard table
+            - Battle Counts table
+            - Win Rates table
+            These components are needed by the main Frontend class to wire up events.
+        """
+        logger.debug("Building Leaderboard UI section...")
+        # Pre-load leaderboard data before building UI that depends on it
+        await self._update_leaderboard_data(force=True)
+
+        # --- UI components ---
+        with gr.Row():
+            with gr.Column(scale=5):
+                gr.HTML(
+                    value="""
+                    <h2 class="tab-header">🏆 Leaderboard</h2>
+                    <p style="padding-left: 8px;">
+                        This leaderboard presents community voting results for different TTS providers, showing which
+                        ones users found more expressive and natural-sounding. The win rate reflects how often each
+                        provider was selected as the preferred option in head-to-head comparisons. Click the refresh
+                        button to see the most up-to-date voting results.
+                    </p>
+                    """,
+                    padding=False,
+                )
+            refresh_button = gr.Button(
+                "↻ Refresh",
+                variant="primary",
+                elem_classes="refresh-btn",
+                scale=1,
+            )
+
+        with gr.Column(elem_id="leaderboard-table-container"):
+            leaderboard_table = gr.DataFrame(
+                headers=["Rank", "Provider", "Model", "Win Rate", "Votes"],
+                datatype=["html", "html", "html", "html", "html"],
+                column_widths=[80, 300, 180, 120, 116],
+                value=self.leaderboard_data,
+                min_width=680,
+                interactive=False,
+                render=True,
+                elem_id="leaderboard-table"
+            )
+
+        with gr.Column():
+            gr.HTML(
+                value="""
+                <h2 style="padding-top: 12px;" class="tab-header">📊 Head-to-Head Matchups</h2>
+                <p style="padding-left: 8px; width: 80%;">
+                    These tables show how each provider performs against others in direct comparisons.
+                    The first table shows the total number of comparisons between each pair of providers.
+                    The second table shows the win rate (percentage) of the row provider against the column provider.
+                </p>
+                """,
+                padding=False
+            )
+
+        with gr.Row(equal_height=True):
+            with gr.Column(min_width=420):
+                battle_counts_table = gr.DataFrame(
+                    headers=["", "Hume AI", "OpenAI", "ElevenLabs"],
+                    datatype=["html", "html", "html", "html"],
+                    column_widths=[132, 132, 132, 132],
+                    value=self.battle_counts_data,
+                    interactive=False,
+                )
+            with gr.Column(min_width=420):
+                win_rates_table = gr.DataFrame(
+                    headers=["", "Hume AI", "OpenAI", "ElevenLabs"],
+                    datatype=["html", "html", "html", "html"],
+                    column_widths=[132, 132, 132, 132],
+                    value=self.win_rates_data,
+                    interactive=False,
+                )
+
+        with gr.Accordion(label="Citation", open=False):
+            with gr.Column(variant="panel"):
+                with gr.Column(variant="panel"):
+                    gr.HTML(
+                        value="""
+                        <h2>Citation</h2>
+                        <p style="padding: 0 8px;">
+                            When referencing this leaderboard or its dataset in academic publications, please cite:
+                        </p>
+                        """,
+                        padding=False,
+                    )
+                    gr.Markdown(
+                        value="""
+                        **BibTeX**
+                        ```BibTeX
+                        @misc{expressive-tts-arena,
+                            title = {Expressive TTS Arena: An Open Platform for Evaluating Text-to-Speech Expressiveness by Human Preference},
+                            author = {Alan Cowen, Zachary Greathouse, Richard Marmorstein, Jeremy Hadfield},
+                            year = {2025},
+                            publisher = {Hugging Face},
+                            howpublished = {\\url{https://huggingface.co/spaces/HumeAI/expressive-tts-arena}}
+                        }
+                        ```
+                        """
+                    )
+                    gr.HTML(
+                        value="""
+                        <h2>Terms of Use</h2>
+                        <p style="padding: 0 8px;">
+                            Users are required to agree to the following terms before using the service:
+                        </p>
+                        <p style="padding: 0 8px;">
+                            All generated audio clips are provided for research and evaluation purposes only.
+                            The audio content may not be redistributed or used for commercial purposes without
+                            explicit permission. Users should not upload any private or personally identifiable
+                            information. Please report any bugs, issues, or concerns to our
+                            <a href="https://discord.com/invite/humeai" target="_blank" class="provider-link">
+                                Discord community
+                            </a>.
+                        </p>
+                        """,
+                        padding=False,
+                    )
+                    gr.HTML(
+                        value="""
+                        <h2>Acknowledgements</h2>
+                        <p style="padding: 0 8px;">
+                            We thank all participants who contributed their votes to help build this leaderboard.
+                        </p>
+                        """,
+                        padding=False,
+                    )
+
+        # Wrapper for the async refresh function
+        async def async_refresh_handler() -> Tuple[Union[dict, gr.skip], Union[dict, gr.skip], Union[dict, gr.skip]]:
+            """Async helper to call refresh_leaderboard and handle its tuple return."""
+            logger.debug("Refresh button clicked, calling async_refresh_handler.")
+            return await self.refresh_leaderboard(force=True)
+
+        # Handler to re-enable the button after a short delay
+        def reenable_button() -> dict: # Returns a Gradio update dict
+            """Waits briefly and returns an update to re-enable the refresh button."""
+            throttle_delay = 3 # seconds
+            time.sleep(throttle_delay) # Okay in Gradio event handlers (runs in thread)
+            return gr.update(interactive=True)
+
+        # Refresh button click event handler
+        refresh_button.click(
+            fn=lambda _=None: (gr.update(interactive=False)), # Disable button immediately
+            inputs=[],
+            outputs=[refresh_button],
+        ).then(
+            fn=async_refresh_handler,
+            inputs=[],
+            outputs=[leaderboard_table, battle_counts_table, win_rates_table]  # Update all three tables
+        ).then(
+            fn=reenable_button, # Re-enable the button after a delay
+            inputs=[],
+            outputs=[refresh_button]
+        )
+
+        logger.debug("Leaderboard UI section built.")
+        # Return the component instances needed by the Frontend class
+        return leaderboard_table, battle_counts_table, win_rates_table

src/frontend/frontend.py

@@ -0,0 +1,127 @@
+# Standard Library Imports
+from typing import Tuple, Union
+
+# Third-Party Library Imports
+import gradio as gr
+
+# Local Application Imports
+from src.common import Config, logger
+from src.core import TTSService, VotingService
+from src.database import AsyncDBSessionMaker
+
+from .components import Arena, Leaderboard
+
+
+class Frontend:
+    """
+    Main frontend class orchestrating the Gradio UI application.
+
+    Initializes and manages the Arena and Leaderboard components, builds the overall UI structure (Tabs, HTML),
+    and handles top-level events like tab selection.
+    """
+    def __init__(self, config: Config, db_session_maker: AsyncDBSessionMaker):
+        """
+        Initializes the Frontend application controller.
+
+        Args:
+            config: The application configuration object.
+            db_session_maker: An asynchronous database session factory.
+        """
+        self.config = config
+
+        # Instantiate services
+        self.tts_service: TTSService = TTSService(config)
+        self.voting_service: VotingService = VotingService(db_session_maker)
+        logger.debug("Frontend initialized with TTSService and VotingService.")
+
+        # Initialize components with dependencies
+        self.arena = Arena(config, self.tts_service, self.voting_service)
+        self.leaderboard = Leaderboard(self.voting_service)
+        logger.debug("Frontend initialized with Arena and Leaderboard components.")
+
+    async def _handle_tab_select(self, evt: gr.SelectData) -> Tuple[
+        Union[dict, gr.skip],
+        Union[dict, gr.skip],
+        Union[dict, gr.skip],
+    ]:
+        """
+        Handles tab selection events. Refreshes leaderboard if its tab is selected.
+
+        Args:
+            evt: Gradio SelectData event, containing the selected tab's value (label).
+
+        Returns:
+            A tuple of Gradio update dictionaries for the leaderboard tables if the Leaderboard tab was selected
+            and data needed refreshing, otherwise a tuple of gr.skip() objects.
+        """
+        selected_tab = evt.value
+        if selected_tab == "Leaderboard":
+            # Refresh leaderboard, but don't force it (allow cache/throttle)
+            return await self.leaderboard.refresh_leaderboard(force=False)
+        # Return skip updates for other tabs
+        return gr.skip(), gr.skip(), gr.skip()
+
+    async def build_gradio_interface(self) -> gr.Blocks:
+        """
+        Builds and configures the complete Gradio Blocks UI.
+
+        Pre-loads initial leaderboard data, defines layout (HTML, Tabs), integrates Arena and Leaderboard sections,
+        and sets up tab selection handler.
+
+        Returns:
+            The fully constructed Gradio Blocks application instance.
+        """
+        logger.info("Building Gradio interface...")
+
+        with gr.Blocks(title="Expressive TTS Arena", css_paths="static/css/styles.css") as demo:
+            # --- Header HTML ---
+            gr.HTML(
+                value="""
+                <div class="title-container">
+                    <h1>Expressive TTS Arena</h1>
+                    <div class="social-links">
+                        <a
+                            href="https://discord.com/invite/humeai"
+                            target="_blank"
+                            id="discord-link"
+                            title="Join our Discord"
+                            aria-label="Join our Discord server"
+                        ></a>
+                        <a
+                            href="https://github.com/HumeAI/expressive-tts-arena"
+                            target="_blank"
+                            id="github-link"
+                            title="View on GitHub"
+                            aria-label="View project on GitHub"
+                        ></a>
+                    </div>
+                </div>
+                <div class="excerpt-container">
+                    <p>
+                        Join the community in evaluating text-to-speech models, and vote for the AI voice that best
+                        captures the emotion, nuance, and expressiveness of human speech.
+                    </p>
+                </div>
+                """
+            )
+
+            # --- Tabs ---
+            with gr.Tabs() as tabs:
+                with gr.TabItem("Arena"):
+                    self.arena.build_arena_section()
+                with gr.TabItem("Leaderboard"):
+                    (
+                        leaderboard_table,
+                        battle_counts_table,
+                        win_rates_table
+                    ) = await self.leaderboard.build_leaderboard_section()
+
+            # --- Top-level Event Handlers ---
+            tabs.select(
+                fn=self._handle_tab_select,
+                inputs=[],
+                outputs=[leaderboard_table, battle_counts_table, win_rates_table],
+            )
+
+        logger.debug("Gradio interface built successfully")
+        return demo

src/integrations/__init__.py

@@ -1,7 +1,7 @@
-from .anthropic_api import AnthropicConfig, AnthropicError, generate_text_with_claude
-from .elevenlabs_api import ElevenLabsConfig, ElevenLabsError, text_to_speech_with_elevenlabs
-from .hume_api import HumeConfig, HumeError, text_to_speech_with_hume
-from .openai_api import OpenAIConfig, OpenAIError, text_to_speech_with_openai
+from .anthropic import AnthropicConfig, AnthropicError, generate_text_with_claude
+from .elevenlabs import ElevenLabsConfig, ElevenLabsError, text_to_speech_with_elevenlabs
+from .hume import HumeConfig, HumeError, text_to_speech_with_hume
+from .openai import OpenAIConfig, OpenAIError, text_to_speech_with_openai
 
 __all__ = [
     "AnthropicConfig",

src/integrations/{anthropic_api.py → anthropic.py}

@@ -1,18 +1,6 @@
-"""
-anthropic_api.py
-
-This file defines the asynchronous interaction with the Anthropic API, focusing on generating text using the Claude
-model. It includes functionality for input validation, asynchronous API request handling, and processing API responses.
-
-Key Features:
-- Encapsulates all logic related to the Anthropic API.
-- Implements asynchronous retry logic for handling transient API errors.
-- Validates the response content to ensure API compatibility.
-- Provides detailed logging for debugging and error tracking.
-"""
-
 # Standard Library Imports
 import logging
+import time
 from dataclasses import dataclass, field
 from typing import List, Optional, Union
 
@@ -22,11 +10,11 @@ from anthropic.types import Message, ModelParam, TextBlock, ToolUseBlock
 from tenacity import after_log, before_log, retry, retry_if_exception, stop_after_attempt, wait_exponential
 
 # Local Application Imports
-from src.config import Config, logger
-from src.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, SERVER_ERROR_CODE
-from src.utils import truncate_text, validate_env_var
+from src.common import Config, logger
+from src.common.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, RATE_LIMIT_ERROR_CODE, SERVER_ERROR_CODE
+from src.common.utils import validate_env_var
 
-PROMPT_TEMPLATE: str = """
+SYSTEM_PROMPT: str = """
 <role>
 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.
@@ -54,7 +42,7 @@ Your absolute priority is delivering complete, untruncated responses within stri
 class AnthropicConfig:
     """Immutable configuration for interacting with the Anthropic API using the asynchronous client."""
     api_key: str = field(init=False)
-    system_prompt: str = field(init=False)
+    system_prompt: str = SYSTEM_PROMPT
     model: ModelParam = "claude-3-5-sonnet-latest"
     max_tokens: int = 300
 
@@ -64,15 +52,13 @@ class AnthropicConfig:
             raise ValueError("Anthropic Model is not set.")
         if not self.max_tokens:
             raise ValueError("Anthropic Max Tokens is not set.")
+        if not self.system_prompt:
+            raise ValueError("Anthropic system prompt is not set.")
 
         # Compute the API key from the environment.
         computed_api_key = validate_env_var("ANTHROPIC_API_KEY")
         object.__setattr__(self, "api_key", computed_api_key)
 
-        # Compute the system prompt using max_tokens and other logic.
-        computed_prompt = PROMPT_TEMPLATE.format(max_tokens=self.max_tokens)
-        object.__setattr__(self, "system_prompt", computed_prompt)
-
     @property
     def client(self):
         """
@@ -181,20 +167,21 @@ async def generate_text_with_claude(character_description: str, config: Config)
         UnretryableAnthropicError: For unretryable API errors.
         AnthropicError: For other errors communicating with the Anthropic API.
     """
+    logger.debug("Generating text with Anthropic.")
+    anthropic_config = config.anthropic_config
+    client = anthropic_config.client
+    start_time = time.time()
     try:
-        anthropic_config = config.anthropic_config
         prompt = anthropic_config.build_expressive_prompt(character_description)
-        logger.debug(f"Generating text with Claude. Character description length: {len(prompt)} characters.")
-
-        assert anthropic_config.system_prompt is not None, "system_prompt must be set."
-
-        response: Message = await anthropic_config.client.messages.create(
+        response: Message = await client.messages.create(
             model=anthropic_config.model,
             max_tokens=anthropic_config.max_tokens,
             system=anthropic_config.system_prompt,
             messages=[{"role": "user", "content": prompt}],
         )
-        logger.debug(f"API response received: {truncate_text(str(response))}")
+
+        elapsed_time = time.time() - start_time
+        logger.info(f"Anthropic API request completed in {elapsed_time:.2f} seconds.")
 
         if not hasattr(response, "content") or response.content is None:
             logger.error("Response is missing 'content'. Response: %s", response)
@@ -204,26 +191,25 @@ async def generate_text_with_claude(character_description: str, config: Config)
 
         if isinstance(blocks, list):
             result = "\n\n".join(block.text for block in blocks if isinstance(block, TextBlock))
-            logger.debug(f"Processed response from list: {truncate_text(result)}")
             return result
 
         if isinstance(blocks, TextBlock):
-            logger.debug(f"Processed response from single TextBlock: {truncate_text(blocks.text)}")
             return blocks.text
 
         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)
+        elapsed_time = time.time() - start_time
+        logger.error(f"Anthropic API request failed after {elapsed_time:.2f} seconds: {e!s}")
+        logger.error(f"Full Anthropic API error: {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
+        if hasattr(e, 'status_code') and e.status_code is not None:
+            if e.status_code == RATE_LIMIT_ERROR_CODE:
+                raise AnthropicError(message=clean_message, original_exception=e) from e
+            if 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
 
@@ -236,7 +222,7 @@ async def generate_text_with_claude(character_description: str, config: Config)
         raise AnthropicError(message=clean_message, original_exception=e) from e
 
 
-def _extract_anthropic_error_message(e: APIError) -> str:
+def __extract_anthropic_error_message(e: APIError) -> str:
     """
     Extracts a clean, user-friendly error message from an Anthropic API error response.
 

src/integrations/{elevenlabs_api.py → elevenlabs.py}

@@ -1,17 +1,3 @@
-"""
-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.
-
-Key Features:
-- Encapsulates all logic related to the ElevenLabs TTS API.
-- Implements retry logic using Tenacity for handling transient API errors.
-- Handles received audio and processes it for playback on the web.
-- Provides detailed logging for debugging and error tracking.
-- Utilizes robust error handling (EAFP) to validate API responses.
-"""
-
 # Standard Library Imports
 import logging
 import random
@@ -25,9 +11,8 @@ from elevenlabs.core import ApiError
 from tenacity import after_log, before_log, retry, retry_if_exception, stop_after_attempt, wait_fixed
 
 # Local Application Imports
-from src.config import Config, logger
-from src.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, SERVER_ERROR_CODE
-from src.utils import save_base64_audio_to_file, validate_env_var
+from src.common import Config, logger, save_base64_audio_to_file, validate_env_var
+from src.common.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, RATE_LIMIT_ERROR_CODE, SERVER_ERROR_CODE
 
 
 @dataclass(frozen=True)
@@ -55,7 +40,6 @@ class ElevenLabsConfig:
         """
         return AsyncElevenLabs(api_key=self.api_key)
 
-
 class ElevenLabsError(Exception):
     """Custom exception for errors related to the ElevenLabs TTS API."""
 
@@ -64,7 +48,6 @@ class ElevenLabsError(Exception):
         self.original_exception = original_exception
         self.message = message
 
-
 class UnretryableElevenLabsError(ElevenLabsError):
     """Custom exception for errors related to the ElevenLabs TTS API that should not be retried."""
 
@@ -73,7 +56,6 @@ class UnretryableElevenLabsError(ElevenLabsError):
         self.original_exception = original_exception
         self.message = message
 
-
 @retry(
     retry=retry_if_exception(lambda e: not isinstance(e, UnretryableElevenLabsError)),
     stop=stop_after_attempt(2),
@@ -113,7 +95,7 @@ async def text_to_speech_with_elevenlabs(
         )
 
         elapsed_time = time.time() - start_time
-        logger.info(f"Elevenlabs API request completed in {elapsed_time:.2f} seconds")
+        logger.info(f"Elevenlabs API request completed in {elapsed_time:.2f} seconds.")
 
         previews = response.previews
         if not previews:
@@ -129,10 +111,13 @@ async def text_to_speech_with_elevenlabs(
 
     except ApiError as e:
         logger.error(f"ElevenLabs API request failed: {e!s}")
-        clean_message = _extract_elevenlabs_error_message(e)
+        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
+        if hasattr(e, 'status_code') and  e.status_code is not None:
+            if e.status_code == RATE_LIMIT_ERROR_CODE:
+                raise ElevenLabsError(message=clean_message, original_exception=e) from e
+            if 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
 
@@ -144,8 +129,7 @@ async def text_to_speech_with_elevenlabs(
 
         raise ElevenLabsError(message=error_message, original_exception=e) from e
 
-
-def _extract_elevenlabs_error_message(e: ApiError) -> str:
+def __extract_elevenlabs_error_message(e: ApiError) -> str:
     """
     Extracts a clean, user-friendly error message from an ElevenLabs API error response.
 

src/integrations/{hume_api.py → hume.py}

@@ -1,16 +1,3 @@
-"""
-hume_api.py
-
-This file defines the interaction with the Hume text-to-speech (TTS) API using the
-Hume Python SDK. It includes functionality for API request handling and processing API responses.
-
-Key Features:
-- Encapsulates all logic related to the Hume TTS API.
-- Implements retry logic for handling transient API errors.
-- Handles received audio and processes it for playback on the web.
-- Provides detailed logging for debugging and error tracking.
-"""
-
 # Standard Library Imports
 import logging
 import time
@@ -24,9 +11,8 @@ from hume.tts.types import Format, FormatMp3, PostedUtterance, ReturnTts
 from tenacity import after_log, before_log, retry, retry_if_exception, stop_after_attempt, wait_fixed
 
 # Local Application Imports
-from src.config import Config, logger
-from src.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, RATE_LIMIT_ERROR_CODE, SERVER_ERROR_CODE
-from src.utils import save_base64_audio_to_file, validate_env_var
+from src.common import Config, logger, save_base64_audio_to_file, validate_env_var
+from src.common.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, RATE_LIMIT_ERROR_CODE, SERVER_ERROR_CODE
 
 
 @dataclass(frozen=True)
@@ -58,7 +44,6 @@ class HumeConfig:
             timeout=self.request_timeout
         )
 
-
 class HumeError(Exception):
     """Custom exception for errors related to the Hume TTS API."""
 
@@ -67,7 +52,6 @@ class HumeError(Exception):
         self.original_exception = original_exception
         self.message = message
 
-
 class UnretryableHumeError(HumeError):
     """Custom exception for errors related to the Hume TTS API that should not be retried."""
 
@@ -76,7 +60,6 @@ class UnretryableHumeError(HumeError):
         self.original_exception = original_exception
         self.message = message
 
-
 @retry(
     retry=retry_if_exception(lambda e: not isinstance(e, UnretryableHumeError)),
     stop=stop_after_attempt(2),
@@ -123,7 +106,7 @@ async def text_to_speech_with_hume(
         )
 
         elapsed_time = time.time() - start_time
-        logger.info(f"Hume API request completed in {elapsed_time:.2f} seconds")
+        logger.info(f"Hume API request completed in {elapsed_time:.2f} seconds.")
 
         generations = response.generations
         if not generations:
@@ -140,10 +123,10 @@ async def text_to_speech_with_hume(
     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)
+        clean_message = __extract_hume_api_error_message(e)
         logger.error(f"Full Hume API error: {e!s}")
 
-        if e.status_code is not None:
+        if hasattr(e, 'status_code') and e.status_code is not None:
             if e.status_code == RATE_LIMIT_ERROR_CODE:
                 rate_limit_error_message = "We're working on scaling capacity. Please try again in a few seconds."
                 raise HumeError(message=rate_limit_error_message, original_exception=e) from e
@@ -160,8 +143,7 @@ async def text_to_speech_with_hume(
 
         raise HumeError(message=clean_message, original_exception=e) from e
 
-
-def _extract_hume_api_error_message(e: ApiError) -> str:
+def __extract_hume_api_error_message(e: ApiError) -> str:
     """
     Extracts a clean, user-friendly error message from a Hume API error response.
 

src/integrations/{openai_api.py → openai.py}

@@ -1,17 +1,3 @@
-"""
-openai_api.py
-
-This file defines the interaction with the OpenAI text-to-speech (TTS) API using the
-OpenAI Python SDK. It includes functionality for API request handling and processing API responses.
-
-Key Features:
-- Encapsulates all logic related to the OpenAI TTS API.
-- Implements retry logic using Tenacity for handling transient API errors.
-- Handles received audio and processes it for playback on the web.
-- Provides detailed logging for debugging and error tracking.
-- Utilizes robust error handling (EAFP) to validate API responses.
-"""
-
 # Standard Library Imports
 import logging
 import random
@@ -25,9 +11,9 @@ from openai import APIError, AsyncOpenAI
 from tenacity import after_log, before_log, retry, retry_if_exception, stop_after_attempt, wait_fixed
 
 # Local Application Imports
-from src.config import Config, logger
-from src.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, SERVER_ERROR_CODE
-from src.utils import validate_env_var
+from src.common import Config, logger
+from src.common.constants import CLIENT_ERROR_CODE, GENERIC_API_ERROR_MESSAGE, RATE_LIMIT_ERROR_CODE, SERVER_ERROR_CODE
+from src.common.utils import validate_env_var
 
 
 @dataclass(frozen=True)
@@ -68,7 +54,6 @@ class OpenAIConfig:
         openai_base_voices = ["alloy", "ash", "coral", "echo", "fable", "onyx", "nova", "sage", "shimmer"]
         return random.choice(openai_base_voices)
 
-
 class OpenAIError(Exception):
     """Custom exception for errors related to the OpenAI TTS API."""
 
@@ -77,7 +62,6 @@ class OpenAIError(Exception):
         self.original_exception = original_exception
         self.message = message
 
-
 class UnretryableOpenAIError(OpenAIError):
     """Custom exception for errors related to the OpenAI TTS API that should not be retried."""
 
@@ -86,7 +70,6 @@ class UnretryableOpenAIError(OpenAIError):
         self.original_exception = original_exception
         self.message = message
 
-
 @retry(
     retry=retry_if_exception(lambda e: not isinstance(e, UnretryableOpenAIError)),
     stop=stop_after_attempt(2),
@@ -135,7 +118,7 @@ async def text_to_speech_with_openai(
             voice=voice, # OpenAI requires a base voice to be specified
         ) as response:
             elapsed_time = time.time() - start_time
-            logger.info(f"OpenAI API request completed in {elapsed_time:.2f} seconds")
+            logger.info(f"OpenAI API request completed in {elapsed_time:.2f} seconds.")
 
             filename = f"openai_{voice}_{start_time}"
             audio_file_path = Path(config.audio_dir) / filename
@@ -148,14 +131,13 @@ async def text_to_speech_with_openai(
         elapsed_time = time.time() - start_time
         logger.error(f"OpenAI API request failed after {elapsed_time:.2f} seconds: {e!s}")
         logger.error(f"Full OpenAI API error: {e!s}")
-        clean_message = _extract_openai_error_message(e)
+        clean_message = __extract_openai_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 UnretryableOpenAIError(message=clean_message, original_exception=e) from e
+        if hasattr(e, 'status_code') and  e.status_code is not None:
+            if e.status_code == RATE_LIMIT_ERROR_CODE:
+                raise OpenAIError(message=clean_message, original_exception=e) from e
+            if CLIENT_ERROR_CODE <= e.status_code < SERVER_ERROR_CODE:
+                raise UnretryableOpenAIError(message=clean_message, original_exception=e) from e
 
         raise OpenAIError(message=clean_message, original_exception=e) from e
 
@@ -167,8 +149,7 @@ async def text_to_speech_with_openai(
 
         raise OpenAIError(message=clean_message, original_exception=e) from e
 
-
-def _extract_openai_error_message(e: APIError) -> str:
+def __extract_openai_error_message(e: APIError) -> str:
     """
     Extracts a clean, user-friendly error message from an OpenAI API error response.
 

src/main.py

@@ -1,80 +1,17 @@
-"""
-main.py
-
-This module is the entry point for the app. It loads configuration and starts the Gradio app.
-"""
-
 # Standard Library Imports
 import asyncio
 from pathlib import Path
-from typing import Awaitable, Callable
 
 # Third-Party Library Imports
 import gradio as gr
-from fastapi import FastAPI, Request
-from fastapi.responses import Response
+from fastapi import FastAPI
 from fastapi.staticfiles import StaticFiles
-from starlette.middleware.base import BaseHTTPMiddleware
-
-from src.config import Config, logger
-from src.constants import META_TAGS
-from src.database import init_db
 
 # Local Application Imports
+from src.common import Config, logger
+from src.database import init_db
 from src.frontend import Frontend
-from src.utils import update_meta_tags
-
-
-class ResponseModifierMiddleware(BaseHTTPMiddleware):
-    """
-    FastAPI middleware that safely intercepts and modifies the HTML response from the root endpoint
-    to inject custom meta tags into the document head.
-
-    This middleware specifically targets the root path ('/') and leaves all other endpoint
-    responses unmodified. It uses BeautifulSoup to properly parse and modify the HTML,
-    ensuring that JavaScript functionality remains intact.
-    """
-    async def dispatch(
-        self,
-        request: Request,
-        call_next: Callable[[Request], Awaitable[Response]]
-    ) -> Response:
-        # Process the request and get the response
-        response = await call_next(request)
-
-        # Only intercept responses from the root endpoint and HTML content
-        if request.url.path == "/" and response.headers.get("content-type", "").startswith("text/html"):
-            # Get the response body
-            response_body = b""
-            async for chunk in response.body_iterator:
-                response_body += chunk
-
-            try:
-                # Decode, modify, and re-encode the content
-                content = response_body.decode("utf-8")
-                modified_content = update_meta_tags(content, META_TAGS).encode("utf-8")
-
-                # Update content-length header to reflect modified content size
-                headers = dict(response.headers)
-                headers["content-length"] = str(len(modified_content))
-
-                # Create a new response with the modified content
-                return Response(
-                    content=modified_content,
-                    status_code=response.status_code,
-                    headers=headers,
-                    media_type=response.media_type
-                )
-            except Exception:
-                # If there's an error, return the original response
-                return Response(
-                    content=response_body,
-                    status_code=response.status_code,
-                    headers=dict(response.headers),
-                    media_type=response.media_type
-                )
-
-        return response
+from src.middleware import MetaTagInjectionMiddleware
 
 
 async def main():
@@ -89,7 +26,7 @@ async def main():
     demo = await frontend.build_gradio_interface()
 
     app = FastAPI()
-    app.add_middleware(ResponseModifierMiddleware)
+    app.add_middleware(MetaTagInjectionMiddleware)
 
     public_dir = Path("public")
     app.mount("/static", StaticFiles(directory=public_dir), name="static")

src/middleware/__init__.py

@@ -0,0 +1,3 @@
+from src.middleware.meta_tag_injection import MetaTagInjectionMiddleware
+
+__all__ = ["MetaTagInjectionMiddleware"]

src/middleware/meta_tag_injection.py

@@ -0,0 +1,155 @@
+# Standard Library Imports
+from typing import Awaitable, Callable, Dict, List
+
+# Third-Party Library Imports
+from bs4 import BeautifulSoup
+from fastapi import Request
+from fastapi.responses import Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+# HTML and social media metadata for the Gradio application
+# These tags define SEO-friendly content and provide rich previews when shared on social platforms
+META_TAGS: List[Dict[str, str]] = [
+    # HTML Meta Tags (description)
+    {
+        'name': 'description',
+        'content': 'An open-source web application for comparing and evaluating the expressiveness of different text-to-speech models, including Hume AI and ElevenLabs.'
+    },
+    # Facebook Meta Tags
+    {
+        'property': 'og:url',
+        'content': 'https://hume.ai'
+    },
+    {
+        'property': 'og:type',
+        'content': 'website'
+    },
+    {
+        'property': 'og:title',
+        'content': 'Expressive TTS Arena'
+    },
+    {
+        'property': 'og:description',
+        'content': 'An open-source web application for comparing and evaluating the expressiveness of different text-to-speech models, including Hume AI and ElevenLabs.'
+    },
+    {
+        'property': 'og:image',
+        'content': '/static/arena-opengraph-logo.png'
+    },
+    # Twitter Meta Tags
+    {
+        'name': 'twitter:card',
+        'content': 'summary_large_image'
+    },
+    {
+        'property': 'twitter:domain',
+        'content': 'hume.ai'
+    },
+    {
+        'property': 'twitter:url',
+        'content': 'https://hume.ai'
+    },
+    {
+        'name': 'twitter:creator',
+        'content': '@hume_ai'
+    },
+    {
+        'name': 'twitter:title',
+        'content': 'Expressive TTS Arena'
+    },
+    {
+        'name': 'twitter:description',
+        'content': 'An open-source web application for comparing and evaluating the expressiveness of different text-to-speech models, including Hume AI and ElevenLabs.'
+    },
+    {
+        'name': 'twitter:image',
+        'content': '/static/arena-opengraph-logo.png'
+    }
+]
+
+def __update_meta_tags(html_content: str, meta_tags: List[Dict[str, str]]) -> str:
+    """
+    Safely updates the HTML content by adding or replacing meta tags in the head section
+    without affecting other elements, especially scripts and event handlers.
+
+    Args:
+        html_content: The original HTML content as a string
+        meta_tags: A list of dictionaries with meta tag attributes to add
+
+    Returns:
+        The modified HTML content with updated meta tags
+    """
+    # Parse the HTML
+    soup = BeautifulSoup(html_content, 'html.parser')
+    head = soup.head
+
+    # Remove existing meta tags that would conflict with our new ones
+    for meta_tag in meta_tags:
+        # Determine if we're looking for 'name' or 'property' attribute
+        attr_type = 'name' if 'name' in meta_tag else 'property'
+        attr_value = meta_tag.get(attr_type)
+
+        # Find and remove existing meta tags with the same name/property
+        existing_tags = head.find_all('meta', attrs={attr_type: attr_value})
+        for tag in existing_tags:
+            tag.decompose()
+
+    # Add the new meta tags to the head section
+    for meta_info in meta_tags:
+        new_meta = soup.new_tag('meta')
+        for attr, value in meta_info.items():
+            new_meta[attr] = value
+        head.append(new_meta)
+
+    return str(soup)
+
+class MetaTagInjectionMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI middleware that safely intercepts and modifies the HTML response from the root endpoint
+    to inject custom meta tags into the document head.
+
+    This middleware specifically targets the root path ('/') and leaves all other endpoint
+    responses unmodified. It uses BeautifulSoup to properly parse and modify the HTML,
+    ensuring that JavaScript functionality remains intact.
+    """
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        # Process the request and get the response
+        response = await call_next(request)
+
+        # Only intercept responses from the root endpoint and HTML content
+        if request.url.path == "/" and response.headers.get("content-type", "").startswith("text/html"):
+            # Get the response body
+            response_body = b""
+            async for chunk in response.body_iterator:
+                response_body += chunk
+
+            try:
+                # Decode, modify, and re-encode the content
+                content = response_body.decode("utf-8")
+                modified_content = __update_meta_tags(content, META_TAGS).encode("utf-8")
+
+                # Update content-length header to reflect modified content size
+                headers = dict(response.headers)
+                headers["content-length"] = str(len(modified_content))
+
+                # Create a new response with the modified content
+                return Response(
+                    content=modified_content,
+                    status_code=response.status_code,
+                    headers=headers,
+                    media_type=response.media_type
+                )
+            except Exception:
+                # If there's an error, return the original response
+                return Response(
+                    content=response_body,
+                    status_code=response.status_code,
+                    headers=dict(response.headers),
+                    media_type=response.media_type
+                )
+
+        return response

src/scripts/init_db.py

@@ -12,7 +12,7 @@ import sys
 from sqlalchemy.ext.asyncio import create_async_engine
 
 # Local Application Imports
-from src.config import Config, logger
+from src.common import Config, logger
 from src.database import Base
 
 

src/scripts/test_db.py

@@ -33,7 +33,7 @@ import sys
 from sqlalchemy import text
 
 # Local Application Imports
-from src.config import Config, logger
+from src.common import Config, logger
 from src.database import engine, init_db
 
 

src/utils.py

@@ -1,650 +0,0 @@
-"""
-utils.py
-
-This file contains utility functions that are shared across the project.
-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 Dict, List, Tuple, cast
-
-# Third-Party Library Imports
-from bs4 import BeautifulSoup
-from sqlalchemy.ext.asyncio import AsyncSession
-
-# Local Application Imports
-from src import constants
-from src.config import Config, logger
-from src.custom_types import (
-    ComparisonType,
-    LeaderboardEntry,
-    Option,
-    OptionKey,
-    OptionMap,
-    TTSProviderName,
-    VotingResults,
-)
-from src.database import (
-    AsyncDBSessionMaker,
-    create_vote,
-    get_head_to_head_battle_stats,
-    get_head_to_head_win_rate_stats,
-    get_leaderboard_stats,
-)
-
-
-def truncate_text(text: str, max_length: int = 50) -> str:
-    """
-    Truncate a string to the specified length, appending ellipses if necessary.
-
-    Args:
-        text (str): The text to truncate.
-        max_length (int): The maximum length of the truncated string.
-
-    Returns:
-        str: The truncated text.
-
-    Examples:
-        >>> truncate_text("Hello, World!", 5)
-        'Hello...'
-        >>> truncate_text("Short string", 20)
-        'Short string'
-        >>> truncate_text("Edge case with zero length", 0)
-        ''
-    """
-    if max_length <= 0:
-        logger.warning(f"Invalid max_length={max_length}. Returning empty string.")
-        return ""
-
-    is_truncated = len(text) > max_length
-    if is_truncated:
-        logger.debug(f"Truncated text to {max_length} characters.")
-
-    return text[:max_length] + ("..." if is_truncated else "")
-
-
-def validate_character_description_length(character_description: str) -> None:
-    """
-    Validates that a voice description is within specified minimum and maximum length limits.
-
-    Args:
-        character_description (str): The input character description to validate.
-
-    Raises:
-        ValueError: If the character description is empty, too short, or exceeds max length.
-    """
-    stripped_character_description = character_description.strip()
-    character_description_length = len(stripped_character_description)
-
-    logger.debug(f"Voice description length being validated: {character_description_length} characters")
-
-    if character_description_length < constants.CHARACTER_DESCRIPTION_MIN_LENGTH:
-        raise ValueError(
-            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 "
-            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: {truncated_description}")
-
-
-def validate_text_length(text: str) -> None:
-    """
-    Validates that a text input is within specified minimum and maximum length limits.
-
-    Args:
-        text (str): The input text to validate.
-
-    Raises:
-        ValueError: If the text is empty, too short, or exceeds max length.
-    """
-    stripped_text = text.strip()
-    text_length = len(stripped_text)
-
-    logger.debug(f"Voice description length being validated: {text_length} characters")
-
-    if text_length < constants.TEXT_MIN_LENGTH:
-        raise ValueError(
-            f"Your text is too short. Please enter at least "
-            f"{constants.TEXT_MIN_LENGTH} characters. "
-            f"(Current length: {text_length})"
-        )
-    if text_length > constants.TEXT_MAX_LENGTH:
-        raise ValueError(
-            f"Your text is too long. Please limit it to "
-            f"{constants.TEXT_MAX_LENGTH} characters. "
-            f"(Current length: {text_length})"
-        )
-
-    truncated_text = truncate_text(stripped_text)
-    logger.debug(f"Character description length validation passed for text: {truncated_text}")
-
-
-def _delete_files_older_than(directory: Path, minutes: int = 30) -> None:
-    """
-    Delete all files in the specified directory that are older than a given number of minutes.
-
-    This function checks each file in the given directory and removes it if its last modification
-    time is older than the specified threshold. By default, the threshold is set to 30 minutes.
-
-    Args:
-        directory (str): The path to the directory where files will be checked and possibly deleted.
-        minutes (int, optional): The age threshold in minutes. Files older than this will be deleted.
-                                 Defaults to 30 minutes.
-
-    Returns: None
-    """
-    # Get the current time in seconds since the epoch.
-    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 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, config: Config) -> 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 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.
-        filename (str): The name of the file (including extension, e.g.,
-                        'b4a335da-9786-483a-b0a5-37e6e4ad5fd1.mp3') where the decoded
-                        audio will be saved.
-
-    Returns:
-        str: The relative file path to the saved audio file.
-
-    Raises:
-        FileNotFoundError: If the audio file was not created.
-    """
-
-    audio_bytes = base64.b64decode(base64_audio)
-    file_path = Path(config.audio_dir) / filename
-    num_minutes = 30
-
-    _delete_files_older_than(config.audio_dir, num_minutes)
-
-    # Write the binary audio data to the file.
-    with file_path.open("wb") as audio_file:
-        audio_file.write(audio_bytes)
-
-    # Verify that the file was created.
-    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 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 str(relative_path)
-
-
-def get_random_providers(text_modified: bool) -> Tuple[TTSProviderName, TTSProviderName]:
-    """
-    Select 2 TTS providers based on whether the text has been modified.
-
-    Probabilities:
-     - 50% HUME_AI, OPENAI
-     - 25% OPENAI, ELEVENLABS
-     - 20% HUME_AI, ELEVENLABS
-     - 5% HUME_AI, HUME_AI
-
-    If the `text_modified` argument is `True`, then 100% HUME_AI, HUME_AI
-
-    Args:
-        text_modified (bool): A flag indicating whether the text has been modified, indicating a custom text input.
-
-    Returns:
-        tuple: A tuple (TTSProviderName, TTSProviderName)
-    """
-    if text_modified:
-        return constants.HUME_AI, constants.HUME_AI
-
-    # When modifying the probability distribution, make sure the weights match the order of provider pairs
-    provider_pairs = [
-        (constants.HUME_AI, constants.OPENAI),
-        (constants.OPENAI, constants.ELEVENLABS),
-        (constants.HUME_AI, constants.ELEVENLABS),
-        (constants.HUME_AI, constants.HUME_AI)
-    ]
-    weights = [0.5, 0.25, 0.2, 0.05]
-
-    return random.choices(provider_pairs, weights=weights, k=1)[0]
-
-
-def create_shuffled_tts_options(option_a: Option, option_b: Option) -> OptionMap:
-    """
-    Create and shuffle TTS generation options.
-
-    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:
-        option_a (Option): The first TTS generation option.
-        option_b (Option): The second TTS generation option.
-
-    Returns:
-        OptionMap: A mapping of shuffled TTS options, where each option includes
-                   its provider, audio file path, and generation ID.
-    """
-
-    options = [option_a, option_b]
-    random.shuffle(options)
-    shuffled_option_a, shuffled_option_b = options
-
-    return {
-        "option_a": {
-            "provider": shuffled_option_a.provider,
-            "generation_id": shuffled_option_a.generation_id,
-            "audio_file_path": shuffled_option_a.audio,
-        },
-        "option_b": {
-            "provider": shuffled_option_b.provider,
-            "generation_id": shuffled_option_b.generation_id,
-            "audio_file_path": shuffled_option_b.audio,
-        },
-    }
-
-
-def determine_selected_option(selected_option_button: str) -> Tuple[OptionKey, OptionKey]:
-    """
-    Determines the selected option and the alternative option based on the user's selection.
-
-    Args:
-        selected_option_button (str): The option selected by the user, expected to be either
-            constants.OPTION_A_KEY or constants.OPTION_B_KEY.
-
-    Returns:
-        tuple: A tuple (selected_option, other_option) where:
-            - selected_option is the same as the selected_option.
-            - other_option is the alternative option.
-    """
-
-    if selected_option_button == constants.SELECT_OPTION_A:
-        selected_option, other_option = constants.OPTION_A_KEY, constants.OPTION_B_KEY
-    elif selected_option_button == constants.SELECT_OPTION_B:
-        selected_option, other_option = constants.OPTION_B_KEY, constants.OPTION_A_KEY
-    else:
-        raise ValueError(f"Invalid selected button: {selected_option_button}")
-
-    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.
-
-    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
-
-    providers = (provider_a, provider_b)
-
-    if constants.HUME_AI in providers and constants.ELEVENLABS in providers:
-        return constants.HUME_TO_ELEVENLABS
-
-    if constants.HUME_AI in providers and constants.OPENAI in providers:
-        return constants.HUME_TO_OPENAI
-
-    if constants.ELEVENLABS in providers and constants.OPENAI in providers:
-        return constants.OPENAI_TO_ELEVENLABS
-
-    raise ValueError(f"Invalid provider combination: {provider_a}, {provider_b}")
-
-
-def _log_voting_results(voting_results: VotingResults) -> None:
-    """Log the full voting results."""
-
-    logger.info("Voting results:\n%s", json.dumps(voting_results, indent=4))
-
-
-async def _create_db_session(db_session_maker: AsyncDBSessionMaker) -> AsyncSession:
-    """
-    Creates a new database session using the provided session maker and checks if it's a dummy session.
-
-    A dummy session might be used in development or testing environments where database operations
-    should be simulated but not actually performed.
-
-    Args:
-        db_session_maker (AsyncDBSessionMaker): A callable that returns a new async database session.
-
-    Returns:
-        AsyncSession: A newly created database session that can be used for database operations.
-    """
-    session = db_session_maker()
-    is_dummy_session = getattr(session, "is_dummy", False)
-
-    if is_dummy_session:
-        await session.close()
-        return None
-
-    return session
-
-
-async def _persist_vote(db_session_maker: AsyncDBSessionMaker, voting_results: VotingResults) -> None:
-    """
-    Asynchronously persist a vote record in the database and handle potential failures.
-    Designed to work safely in a background task context.
-
-    Args:
-        db_session_maker (AsyncDBSessionMaker): A callable that returns a new async database session.
-        voting_results (VotingResults): A dictionary containing the details of the vote to persist.
-        config (Config): The application configuration, used to determine environment-specific behavior.
-
-    Returns:
-        None
-    """
-    # Create session
-    session = await _create_db_session(db_session_maker)
-    _log_voting_results(voting_results)
-    try:
-        await create_vote(cast(AsyncSession, session), voting_results)
-    except Exception as e:
-        # Log the error with traceback
-        logger.error(f"Failed to create vote record: {e}", exc_info=True)
-    finally:
-        # Always ensure the session is closed
-        if session is not None:
-            await session.close()
-
-
-async def submit_voting_results(
-    option_map: OptionMap,
-    selected_option: OptionKey,
-    text_modified: bool,
-    character_description: str,
-    text: str,
-    db_session_maker: AsyncDBSessionMaker,
-) -> None:
-    """
-    Asynchronously constructs the voting results dictionary and persists a new vote record.
-    Designed to run as a background task, handling all exceptions internally.
-
-    Args:
-        option_map (OptionMap): Mapping of comparison data and TTS options.
-        selected_option (OptionKey): The option selected by the user.
-        text_modified (bool): Indicates whether the text was modified from the original generated text.
-        character_description (str): Description of the voice/character used for TTS generation.
-        text (str): The text that was synthesized into speech.
-        db_session_maker (AsyncDBSessionMaker): Factory function for creating async database sessions.
-        config (Config): Application configuration containing environment settings.
-
-    Returns:
-        None
-    """
-    try:
-        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": 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"],
-            "character_description": character_description,
-            "text": text,
-            "is_custom_text": text_modified,
-        }
-
-        await _persist_vote(db_session_maker, voting_results)
-
-    # Catch exceptions at the top level of the background task to prevent unhandled exceptions in background tasks
-    except Exception as e:
-        logger.error(f"Background task error in submit_voting_results: {e}", exc_info=True)
-
-
-async def get_leaderboard_data(
-    db_session_maker: AsyncDBSessionMaker
-) -> Tuple[List[List[str]], List[List[str]], List[List[str]]]:
-    """
-    Fetches and formats all leaderboard data from the voting results database.
-
-    This function retrieves three different datasets:
-    1. Provider rankings with overall performance metrics
-    2. Head-to-head battle counts between providers
-    3. Win rate percentages for each provider against others
-
-    Args:
-        db_session_maker (AsyncDBSessionMaker): Factory function for creating async database sessions.
-
-    Returns:
-        Tuple containing three datasets, each as List[List[str]]:
-            - leaderboard_data: Provider rankings with performance metrics
-            - battle_counts_data: Number of comparisons between each provider pair
-            - win_rate_data: Win percentages in head-to-head matchups
-    """
-    # Create session
-    session = await _create_db_session(db_session_maker)
-    try:
-        leaderboard_data_raw = await get_leaderboard_stats(cast(AsyncSession, session))
-        battle_counts_data_raw = await get_head_to_head_battle_stats(cast(AsyncSession, session))
-        win_rate_data_raw = await get_head_to_head_win_rate_stats(cast(AsyncSession, session))
-
-        logger.info("Fetched leaderboard data successfully.")
-
-        leaderboard_data = _format_leaderboard_data(leaderboard_data_raw)
-        battle_counts_data = _format_battle_counts_data(battle_counts_data_raw)
-        win_rate_data = _format_win_rate_data(win_rate_data_raw)
-
-        return leaderboard_data, battle_counts_data, win_rate_data
-    except Exception as e:
-        # Log the error with traceback
-        logger.error(f"Failed to fetch leaderboard data: {e}", exc_info=True)
-        return [[]], [[]], [[]]
-    finally:
-        # Always ensure the session is closed
-        if session is not None:
-            await session.close()
-
-def _format_leaderboard_data(leaderboard_data_raw: List[LeaderboardEntry]) -> List[List[str]]:
-    """
-    Formats raw leaderboard data for display in the UI.
-
-    Converts LeaderboardEntry objects into HTML-formatted strings with appropriate
-    styling and links for provider and model information.
-
-    Args:
-        leaderboard_data_raw (List[LeaderboardEntry]): Raw leaderboard data from the database.
-
-    Returns:
-        List[List[str]]: Formatted HTML strings for each cell in the leaderboard table.
-    """
-    return [
-        [
-            f'<p style="text-align: center;">{row[0]}</p>',
-            f"""<a href="{constants.TTS_PROVIDER_LINKS[row[1]]["provider_link"]}"
-                target="_blank"
-                class="provider-link"
-            >{row[1]}</a>
-            """,
-            f"""<a href="{constants.TTS_PROVIDER_LINKS[row[1]]["model_link"]}"
-                target="_blank"
-                class="provider-link"
-            >{row[2]}</a>
-            """,
-            f'<p style="text-align: center;">{row[3]}</p>',
-            f'<p style="text-align: center;">{row[4]}</p>',
-        ] for row in leaderboard_data_raw
-    ]
-
-
-def _format_battle_counts_data(battle_counts_data_raw: List[List[str]]) -> List[List[str]]:
-    """
-    Formats battle count data into a matrix format for the UI.
-
-    Creates a provider-by-provider matrix showing the number of direct comparisons
-    between each pair of providers. Diagonal cells show dashes as providers aren't
-    compared against themselves.
-
-    Args:
-        battle_counts_data_raw (List[List[str]]): Raw battle count data from the database,
-            where each inner list contains [comparison_type, count].
-
-    Returns:
-        List[List[str]]: HTML-formatted matrix of battle counts between providers.
-    """
-    battle_counts_dict = {item[0]: item[1] for item in battle_counts_data_raw}
-    # Create canonical comparison keys based on your expected database formats
-    comparison_keys = {
-        ("Hume AI", "OpenAI"): "Hume AI - OpenAI",
-        ("Hume AI", "ElevenLabs"): "Hume AI - ElevenLabs",
-        ("OpenAI", "ElevenLabs"): "OpenAI - ElevenLabs"
-    }
-    return [
-        [
-            f'<p style="padding-left: 8px;"><strong>{row_provider}</strong></p>'
-        ] + [
-            f"""
-            <p style="text-align: center;">
-                {"-" if row_provider == col_provider
-                    else battle_counts_dict.get(
-                        comparison_keys.get((row_provider, col_provider)) or
-                        comparison_keys.get((col_provider, row_provider), "unknown"),
-                        "0"
-                    )
-                }
-            </p>
-            """ for col_provider in constants.TTS_PROVIDERS
-        ]
-        for row_provider in constants.TTS_PROVIDERS
-    ]
-
-
-def _format_win_rate_data(win_rate_data_raw: List[List[str]]) -> List[List[str]]:
-    """
-    Formats win rate data into a matrix format for the UI.
-
-    Creates a provider-by-provider matrix showing the percentage of times the row
-    provider won against the column provider. Diagonal cells show dashes as
-    providers aren't compared against themselves.
-
-    Args:
-        win_rate_data_raw (List[List[str]]): Raw win rate data from the database,
-            where each inner list contains [comparison_type, first_win_rate, second_win_rate].
-
-    Returns:
-        List[List[str]]: HTML-formatted matrix of win rates between providers.
-    """
-    # Create a clean lookup dictionary with provider pairs as keys
-    win_rates = {}
-    for comparison_type, first_win_rate, second_win_rate in win_rate_data_raw:
-        provider1, provider2 = comparison_type.split(" - ")
-        win_rates[(provider1, provider2)] = first_win_rate
-        win_rates[(provider2, provider1)] = second_win_rate
-
-    return [
-        [
-            f'<p style="padding-left: 8px;"><strong>{row_provider}</strong></p>'
-        ] + [
-            f"""
-                <p style="text-align: center;">
-                    {"-" if row_provider == col_provider else win_rates.get((row_provider, col_provider), "0%")}
-                </p>
-            """
-            for col_provider in constants.TTS_PROVIDERS
-        ]
-        for row_provider in constants.TTS_PROVIDERS
-    ]
-
-
-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.
-    """
-    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 update_meta_tags(html_content: str, meta_tags: List[Dict[str, str]]) -> str:
-    """
-    Safely updates the HTML content by adding or replacing meta tags in the head section
-    without affecting other elements, especially scripts and event handlers.
-
-    Args:
-        html_content: The original HTML content as a string
-        meta_tags: A list of dictionaries with meta tag attributes to add
-
-    Returns:
-        The modified HTML content with updated meta tags
-    """
-    # Parse the HTML
-    soup = BeautifulSoup(html_content, 'html.parser')
-    head = soup.head
-
-    # Remove existing meta tags that would conflict with our new ones
-    for meta_tag in meta_tags:
-        # Determine if we're looking for 'name' or 'property' attribute
-        attr_type = 'name' if 'name' in meta_tag else 'property'
-        attr_value = meta_tag.get(attr_type)
-
-        # Find and remove existing meta tags with the same name/property
-        existing_tags = head.find_all('meta', attrs={attr_type: attr_value})
-        for tag in existing_tags:
-            tag.decompose()
-
-    # Add the new meta tags to the head section
-    for meta_info in meta_tags:
-        new_meta = soup.new_tag('meta')
-        for attr, value in meta_info.items():
-            new_meta[attr] = value
-        head.append(new_meta)
-
-    return str(soup)