Zg/add leaderboard (#11)

Add huggingface configuration and leaderboard UI

.github/workflows/sync-to-huggingface.yml

@@ -0,0 +1,24 @@
+name: Sync to Hugging Face Space
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    environment: huggingface-space
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Push to Hugging Face
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git remote add space https://huggingface.co/spaces/HumeAI/expressive-tts-arena
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git push --force https://username:${{ secrets.HF_TOKEN }}@huggingface.co/spaces/HumeAI/expressive-tts-arena main

.huggingface-space

@@ -0,0 +1,9 @@
+title: Expressive TTS Arena
+emoji: 🎤
+colorFrom: indigo
+colorTo: orange
+sdk: docker
+app_file: src/main.py
+python_version: "3.11"
+pinned: true
+license: mit

README.md

@@ -24,9 +24,8 @@ For support or to join the conversation, visit our [Discord](https://discord.com
 
 ```
 Expressive TTS Arena/
-├── src/
-│   ├── assets/
-│   │   ├── styles.css          # Defines custom css
+├── public/                     # Directory for public assets
+├── src/                        
 │   ├── database/
 │   │   ├── __init__.py         # Makes database a package; expose ORM methods
 │   │   ├── crud.py             # Defines operations for interacting with database
@@ -50,9 +49,12 @@ Expressive TTS Arena/
 │   └── utils.py                # Utility functions
 │── static/
 │   ├── audio/                  # Directory for storing generated audio files
+│   ├── css/
+│   │   ├── styles.css          # Defines custom css
 ├── .dockerignore
 ├── .env.example
 ├── .gitignore
+├── .huggingface-space
 ├── .pre-commit-config.yaml
 ├── Dockerfile
 ├── LICENSE.txt

pyproject.toml

@@ -47,6 +47,7 @@ ignore = [
     "PLR0913",
     "PLR0915",
     "PLR2004",
+    "RET504",
     "RUF006",
     "SIM117",
     "TD002",

src/constants.py

@@ -8,7 +8,12 @@ This module defines global constants used throughout the project.
 from typing import Dict, List
 
 # Third-Party Library Imports
-from src.custom_types import ComparisonType, OptionKey, OptionLabel, TTSProviderName
+from src.custom_types import (
+    ComparisonType,
+    OptionKey,
+    OptionLabel,
+    TTSProviderName,
+)
 
 CLIENT_ERROR_CODE = 400
 SERVER_ERROR_CODE = 500
@@ -18,7 +23,18 @@ RATE_LIMIT_ERROR_CODE = 429
 # UI constants
 HUME_AI: TTSProviderName = "Hume AI"
 ELEVENLABS: TTSProviderName = "ElevenLabs"
+
 TTS_PROVIDERS: List[TTSProviderName] = ["Hume AI", "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",
+    }
+}
 
 HUME_TO_HUME: ComparisonType = "Hume AI - Hume AI"
 HUME_TO_ELEVENLABS: ComparisonType = "Hume AI - ElevenLabs"
@@ -34,8 +50,6 @@ OPTION_B_KEY: OptionKey = "option_b"
 OPTION_A_LABEL: OptionLabel = "Option A"
 OPTION_B_LABEL: OptionLabel = "Option B"
 
-TROPHY_EMOJI: str = "🏆"
-
 SELECT_OPTION_A: str = "Select Option A"
 SELECT_OPTION_B: str = "Select Option B"
 
@@ -143,3 +157,4 @@ META_TAGS: List[Dict[str, str]] = [
         'content': '/static/arena-opengraph-logo.png'
     }
 ]
+

src/custom_types.py

@@ -5,7 +5,7 @@ This module defines custom types for the application.
 """
 
 # Standard Library Imports
-from typing import Literal, NamedTuple, Optional, TypedDict
+from typing import List, Literal, NamedTuple, Optional, TypedDict
 
 TTSProviderName = Literal["Hume AI", "ElevenLabs"]
 """TTSProviderName represents the allowed provider names for TTS services."""
@@ -83,3 +83,24 @@ class OptionMap(TypedDict):
 
     option_a: OptionDetail
     option_b: OptionDetail
+
+
+class LeaderboardEntry(NamedTuple):
+    """A leaderboard entry representing rank, TTS provider, and scores.
+
+    Attributes:
+        rank (int): Rank position on the leaderboard.
+        provider (str): TTS provider's name.
+        model (str): The provider's TTS model.
+        win_rate (str): The provider's win rate as a percentage (e.g., "90%").
+        votes (int): The total number of votes cast for the provider (e.g., 90).
+    """
+    rank: str
+    provider: str
+    model: str
+    win_rate: str
+    votes: str
+
+
+LeaderboardTableEntries = List[LeaderboardEntry]
+"""List of multiple leaderboard entries."""

src/database/crud.py

@@ -6,10 +6,13 @@ Since vote records are never updated or deleted, only functions to create and re
 """
 
 # Third-Party Library Imports
+from sqlalchemy import text
+from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 # Local Application Imports
-from src.custom_types import VotingResults
+from src.config import logger
+from src.custom_types import LeaderboardEntry, LeaderboardTableEntries, VotingResults
 from src.database.models import VoteResult
 
 
@@ -24,23 +27,129 @@ async def create_vote(db: AsyncSession, vote_data: VotingResults) -> VoteResult:
     Returns:
         VoteResult: The newly created vote record.
     """
-    vote = VoteResult(
-        comparison_type=vote_data["comparison_type"],
-        winning_provider=vote_data["winning_provider"],
-        winning_option=vote_data["winning_option"],
-        option_a_provider=vote_data["option_a_provider"],
-        option_b_provider=vote_data["option_b_provider"],
-        option_a_generation_id=vote_data["option_a_generation_id"],
-        option_b_generation_id=vote_data["option_b_generation_id"],
-        voice_description=vote_data["character_description"],
-        text=vote_data["text"],
-        is_custom_text=vote_data["is_custom_text"],
-    )
-    db.add(vote)
     try:
-        await db.commit()
+
+        # Create vote record
+        vote = VoteResult(
+            comparison_type=vote_data["comparison_type"],
+            winning_provider=vote_data["winning_provider"],
+            winning_option=vote_data["winning_option"],
+            option_a_provider=vote_data["option_a_provider"],
+            option_b_provider=vote_data["option_b_provider"],
+            option_a_generation_id=vote_data["option_a_generation_id"],
+            option_b_generation_id=vote_data["option_b_generation_id"],
+            voice_description=vote_data["character_description"],
+            text=vote_data["text"],
+            is_custom_text=vote_data["is_custom_text"],
+        )
+
+        db.add(vote)
+
+        try:
+            await db.commit()
+            await db.refresh(vote)
+            logger.info(f"Vote record created successfully: ID={vote.id}")
+            return vote
+        except SQLAlchemyError as db_error:
+            await db.rollback()
+            logger.error(f"Database error while creating vote: {db_error}")
+            raise
+    except ValueError as val_error:
+        logger.error(f"Invalid vote data: {val_error}")
+        raise
+    except Exception as e:
+        if db:
+            try:
+                await db.rollback()
+            except Exception as rollback_error:
+                logger.error(f"Error during rollback operation: {rollback_error}")
+
+        logger.error(f"Unexpected error creating vote record: {e}")
+        raise
+
+
+async def get_leaderboard_stats(db: AsyncSession) -> LeaderboardTableEntries:
+    """
+    Fetches voting statistics from the database to populate a leaderboard.
+
+    This function calculates voting statistics for TTS providers, excluding Hume-to-Hume
+    comparisons, and returns data structured for a leaderboard display.
+
+    Args:
+        db (AsyncSession): The SQLAlchemy async database session.
+
+    Returns:
+        LeaderboardTableEntries: A list of LeaderboardEntry objects containing rank,
+                                provider name, model name, win rate, and total votes.
+    """
+    default_leaderboard = [
+        LeaderboardEntry("1", "", "", "0%", "0"),
+        LeaderboardEntry("2", "", "", "0%", "0")
+    ]
+
+    try:
+        query = text(
+            """
+            WITH provider_stats AS (
+                -- Get wins for Hume AI
+                SELECT
+                    'Hume AI' as provider,
+                    COUNT(*) as total_comparisons,
+                    SUM(CASE WHEN winning_provider = 'Hume AI' THEN 1 ELSE 0 END) as wins
+                FROM vote_results
+                WHERE comparison_type != 'Hume AI - Hume AI'
+
+                UNION ALL
+
+                -- Get wins for ElevenLabs
+                SELECT
+                    'ElevenLabs' as provider,
+                    COUNT(*) as total_comparisons,
+                    SUM(CASE WHEN winning_provider = 'ElevenLabs' THEN 1 ELSE 0 END) as wins
+                FROM vote_results
+                WHERE comparison_type != 'Hume AI - Hume AI'
+            )
+            SELECT
+                provider,
+                CASE
+                    WHEN provider = 'Hume AI' THEN 'Octave'
+                    WHEN provider = 'ElevenLabs' THEN 'Voice Design'
+                END as model,
+                CASE
+                    WHEN total_comparisons > 0 THEN ROUND((wins * 100.0 / total_comparisons)::numeric, 2)
+                    ELSE 0
+                END as win_rate,
+                wins as total_votes
+            FROM provider_stats
+            ORDER BY win_rate DESC;
+            """
+        )
+
+        result = await db.execute(query)
+        rows = result.fetchall()
+
+        # Format the data for the leaderboard
+        leaderboard_data = []
+        for i, row in enumerate(rows, 1):
+            provider, model, win_rate, total_votes = row
+            leaderboard_entry = LeaderboardEntry(
+                rank=f"{i}",
+                provider=provider,
+                model=model,
+                win_rate=f"{win_rate}%",
+                votes=f"{total_votes}"
+            )
+            leaderboard_data.append(leaderboard_entry)
+
+        # If no data was found, return default entries
+        if not leaderboard_data:
+            return default_leaderboard
+
+        return leaderboard_data
+
+    except SQLAlchemyError as e:
+        logger.error(f"Database error while fetching leaderboard stats: {e}")
+        return default_leaderboard
     except Exception as e:
-        await db.rollback()
-        raise e
-    await db.refresh(vote)
-    return vote
+        logger.error(f"Unexpected error while fetching leaderboard stats: {e}")
+        return default_leaderboard

src/database/database.py

@@ -74,26 +74,19 @@ def init_db(config: Config) -> AsyncDBSessionMaker:
     # ruff doesn't like setting global variables, but this is practical here
     global engine  # noqa
 
-    # Convert standard PostgreSQL URL to async format
-    def convert_to_async_url(url: str) -> str:
-        # Convert postgresql:// to postgresql+asyncpg://
-        if url.startswith('postgresql://'):
-            return url.replace('postgresql://', 'postgresql+asyncpg://', 1)
-        return url
-
     if config.app_env == "prod":
         # In production, a valid DATABASE_URL is required.
         if not config.database_url:
             raise ValueError("DATABASE_URL must be set in production!")
 
-        async_db_url = convert_to_async_url(config.database_url)
+        async_db_url = config.database_url
         engine = create_async_engine(async_db_url)
 
         return async_sessionmaker(bind=engine, expire_on_commit=False, class_=AsyncSession)
 
     # In development, if a DATABASE_URL is provided, use it.
     if config.database_url:
-        async_db_url = convert_to_async_url(config.database_url)
+        async_db_url = config.database_url
         engine = create_async_engine(async_db_url)
 
         return async_sessionmaker(bind=engine, expire_on_commit=False, class_=AsyncSession)

src/frontend.py

@@ -11,7 +11,7 @@ Users can compare the outputs and vote for their favorite in an interactive UI.
 # Standard Library Imports
 import asyncio
 import time
-from typing import Tuple
+from typing import List, Tuple
 
 # Third-Party Library Imports
 import gradio as gr
@@ -32,6 +32,7 @@ from src.integrations import (
 from src.utils import (
     create_shuffled_tts_options,
     determine_selected_option,
+    get_leaderboard_data,
     get_random_provider,
     submit_voting_results,
     validate_character_description_length,
@@ -42,11 +43,19 @@ from src.utils import (
 class Frontend:
     config: Config
     db_session_maker: AsyncDBSessionMaker
+    _leaderboard_data: List[List[str]]
 
     def __init__(self, config: Config, db_session_maker: AsyncDBSessionMaker):
         self.config = config
         self.db_session_maker = db_session_maker
 
+    async def _update_leaderboard_data(self) -> None:
+        """
+        Fetches the latest leaderboard data
+        """
+        latest_leaderboard_data = await get_leaderboard_data(self.db_session_maker)
+        self._leaderboard_data = latest_leaderboard_data
+
     async def _generate_text(self, character_description: str) -> Tuple[gr.Textbox, str]:
         """
         Validates the character_description and generates text using Anthropic API.
@@ -220,12 +229,11 @@ class Frontend:
                 character_description,
                 text,
                 self.db_session_maker,
-                self.config,
             )
         )
 
         # Build button text to display results
-        selected_label = f"{selected_provider} {constants.TROPHY_EMOJI}"
+        selected_label = f"{selected_provider} 🏆"
         other_label = f"{other_provider}"
 
         return (
@@ -267,6 +275,21 @@ class Frontend:
             gr.update(value=character_description), # Update character description
         )
 
+    async def _refresh_leaderboard(self) -> gr.DataFrame:
+        """
+        Asynchronously fetches and formats the latest leaderboard data.
+
+        Returns:
+            gr.DataFrame: A Gradio DataFrame update object containing the formatted leaderboard data,
+                        including rank, provider, model, win rate, and total votes.
+        Raises:
+            gr.Error: If the leaderboard data cannot be retrieved.
+        """
+        await self._update_leaderboard_data()
+        if not self._leaderboard_data:
+            raise gr.Error("Unable to retrieve leaderboard data. Please refresh the page or try again shortly.")
+        return gr.update(value=self._leaderboard_data)
+
     def _disable_ui(self) -> Tuple[
         gr.Button,
         gr.Dropdown,
@@ -345,73 +368,84 @@ class Frontend:
             False, # Reset should_enable_vote_buttons state
         )
 
-    def _build_heading_section(self) -> Tuple[gr.HTML, gr.HTML]:
+    def _build_title_section(self) -> None:
         """
-        Builds heading section including title, randomize all button, and instructions
+        Builds the Title section
         """
-        with gr.Row():
-            with gr.Column(scale=5):
-                title_with_social_links = gr.HTML(
-                    """
-                    <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>
-                    """
-                )
-        instructions = gr.HTML(
+        gr.HTML(
             """
-            <h2 style="font-size: 16px;">Instructions</h2>
-            <ol style="margin-left: 12px;">
-                <li>
-                    Select a sample character, or input a custom character description and click
-                    <strong>"Generate Text"</strong>, to generate your text input.
-                </li>
-                <li>
-                    Click the <strong>"Synthesize Speech"</strong> button to synthesize two TTS outputs based on
-                    your text and character description.
-                </li>
-                <li>
-                    Listen to both audio samples to compare their expressiveness.
-                </li>
-                <li>
-                    Vote for the most expressive result by clicking either <strong>"Select Option A"</strong> or
-                    <strong>"Select Option B"</strong>.
-                </li>
-            </ol>
+            <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>
             """
         )
-        return (title_with_social_links, instructions)
 
-    def _build_input_section(self) -> Tuple[gr.Button, gr.Dropdown, gr.Textbox, gr.Button, gr.Textbox, gr.Button]:
+    def _build_arena_section(self) -> None:
         """
-        Builds the input section including the sample character description dropdown, character
-        description input, and generate text button.
+        Builds the Arena section
         """
-        with gr.Group():
-            randomize_all_button = gr.Button("🎲 Randomize All", variant="primary")
-            sample_character_description_dropdown = gr.Dropdown(
-                choices=list(constants.SAMPLE_CHARACTER_DESCRIPTIONS.keys()),
-                label="Sample Characters",
-                info="Generate text with a sample character description.",
-                value=None,
-                interactive=True,
+        # --- UI components ---
+        with gr.Row():
+            with gr.Column(scale=5):
+                gr.HTML(
+                    """
+                    <h2 class="tab-header">📋 Instructions</h2>
+                    <ol>
+                        <li>
+                            Select a sample character, or input a custom character description and click
+                            <strong>"Generate Text"</strong>, to generate your text input.
+                        </li>
+                        <li>
+                            Click the <strong>"Synthesize Speech"</strong> button to synthesize two TTS outputs based on
+                            your text and character description.
+                        </li>
+                        <li>
+                            Listen to both audio samples to compare their expressiveness.
+                        </li>
+                        <li>
+                            Vote for the most expressive result by clicking either <strong>"Select Option A"</strong> or
+                            <strong>"Select Option B"</strong>.
+                        </li>
+                    </ol>
+                    """
+                )
+            randomize_all_button = gr.Button(
+                "🎲 Randomize All",
+                variant="primary",
+                elem_classes="randomize-btn",
+                scale=1,
             )
+
+        sample_character_description_dropdown = gr.Dropdown(
+            choices=list(constants.SAMPLE_CHARACTER_DESCRIPTIONS.keys()),
+            label="Sample Characters",
+            info="Generate text with a sample character description.",
+            value=None,
+            interactive=True,
+        )
+
         with gr.Group():
             character_description_input = gr.Textbox(
                 label="Character Description",
@@ -422,6 +456,7 @@ class Frontend:
                 show_copy_button=True,
             )
             generate_text_button = gr.Button("Generate Text", variant="secondary")
+
         with gr.Group():
             text_input = gr.Textbox(
                 label="Input Text",
@@ -433,20 +468,8 @@ class Frontend:
                 max_length=constants.CHARACTER_DESCRIPTION_MAX_LENGTH,
                 show_copy_button=True,
             )
-            synthesize_speech_button = gr.Button("Synthesize Speech", variant="primary")
-        return (
-            randomize_all_button,
-            sample_character_description_dropdown,
-            character_description_input,
-            generate_text_button,
-            text_input,
-            synthesize_speech_button,
-        )
 
-    def _build_output_section(self) -> Tuple[gr.Audio, gr.Audio, gr.Button, gr.Button, gr.Textbox, gr.Textbox]:
-        """
-        Builds the output section including text input, audio players, vote buttons, and vote result displays.
-        """
+        synthesize_speech_button = gr.Button("Synthesize Speech", variant="primary")
 
         with gr.Row(equal_height=True):
             with gr.Column():
@@ -481,333 +504,359 @@ class Frontend:
                         text_align="center",
                         container=False,
                     )
-        return (
-            option_a_audio_player,
-            option_b_audio_player,
-            vote_button_a,
-            vote_button_b,
-            vote_result_a,
-            vote_result_b,
+
+        # --- UI state components ---
+        # Track character description used for text and voice generation
+        character_description_state = gr.State("")
+        # Track text used for speech synthesis
+        text_state = gr.State("")
+        # 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()
+        # 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
+        vote_submitted_state = gr.State(False)
+        # Track whether the vote buttons should be enabled
+        should_enable_vote_buttons = gr.State(False)
+
+        # --- Register event handlers ---
+        # "Randomize All" button click event handler chain
+        # 1. Disable interactive UI components
+        # 2. Reset UI state for audio players and voting results
+        # 3. Select random sample character description
+        # 4. Generate text
+        # 5. Synthesize speech
+        # 6. Enable interactive UI components
+        randomize_all_button.click(
+            fn=self._disable_ui,
+            inputs=[],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
+        ).then(
+            fn=self._reset_voting_ui,
+            inputs=[],
+            outputs=[
+                option_a_audio_player,
+                option_b_audio_player,
+                vote_button_a,
+                vote_button_b,
+                vote_result_a,
+                vote_result_b,
+                option_map_state,
+                vote_submitted_state,
+                should_enable_vote_buttons,
+            ],
+        ).then(
+            fn=self._randomize_character_description,
+            inputs=[],
+            outputs=[sample_character_description_dropdown, character_description_input],
+        ).then(
+            fn=self._generate_text,
+            inputs=[character_description_input],
+            outputs=[text_input, generated_text_state],
+        ).then(
+            fn=self._synthesize_speech,
+            inputs=[character_description_input, text_input, generated_text_state],
+            outputs=[
+                option_a_audio_player,
+                option_b_audio_player,
+                option_map_state,
+                text_modified_state,
+                text_state,
+                character_description_state,
+                should_enable_vote_buttons,
+            ],
+        ).then(
+            fn=self._enable_ui,
+            inputs=[should_enable_vote_buttons],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
         )
 
-    def build_gradio_interface(self) -> gr.Blocks:
-        """
-        Builds and configures the Gradio user interface.
+        # "Sample Characters" dropdown select event handler chain:
+        # 1. Update Character Description field with sample
+        # 2. Disable interactive UI components
+        # 3. Generate text
+        # 4. Enable interactive UI components
+        sample_character_description_dropdown.select(
+            fn=lambda choice: constants.SAMPLE_CHARACTER_DESCRIPTIONS.get(choice, ""),
+            inputs=[sample_character_description_dropdown],
+            outputs=[character_description_input],
+        ).then(
+            fn=self._disable_ui,
+            inputs=[],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
+        ).then(
+            fn=self._generate_text,
+            inputs=[character_description_input],
+            outputs=[text_input, generated_text_state],
+        ).then(
+            fn=self._enable_ui,
+            inputs=[should_enable_vote_buttons],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
+        )
 
-        Returns:
-            gr.Blocks: The fully constructed Gradio UI layout.
-        """
-        with gr.Blocks(
-            title="Expressive TTS Arena",
-            css_paths="src/assets/styles.css",
-        ) as demo:
-            # --- UI components ---
+        # "Generate Text" button click event handler chain:
+        # 1. Disable interactive UI components
+        # 2. Generate text
+        # 3. Enable interactive UI components
+        generate_text_button.click(
+            fn=self._disable_ui,
+            inputs=[],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
+        ).then(
+            fn=self._generate_text,
+            inputs=[character_description_input],
+            outputs=[text_input, generated_text_state],
+        ).then(
+            fn=self._enable_ui,
+            inputs=[should_enable_vote_buttons],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
+        )
 
-            (
-                title_with_social_links,
-                instructions,
-            ) = self._build_heading_section()
-            (
+        # "Synthesize Speech" button click event handler chain:
+        # 1. Disable components in the UI
+        # 2. Reset UI state for audio players and voting results
+        # 3. Synthesize speech, load audio players, and display vote button
+        # 4. Enable interactive components in the UI
+        synthesize_speech_button.click(
+            fn=self._disable_ui,
+            inputs=[],
+            outputs=[
                 randomize_all_button,
                 sample_character_description_dropdown,
                 character_description_input,
                 generate_text_button,
                 text_input,
                 synthesize_speech_button,
-            ) = self._build_input_section()
-            (
+                vote_button_a,
+                vote_button_b,
+            ],
+        ).then(
+            fn=self._reset_voting_ui,
+            inputs=[],
+            outputs=[
                 option_a_audio_player,
                 option_b_audio_player,
                 vote_button_a,
                 vote_button_b,
                 vote_result_a,
                 vote_result_b,
-            ) = self._build_output_section()
-
-            # --- UI state components ---
-
-            # Track character description used for text and voice generation
-            character_description_state = gr.State("")
-            # Track text used for speech synthesis
-            text_state = gr.State("")
-            # 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()
-            # 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
-            vote_submitted_state = gr.State(False)
-            # Track whether the vote buttons should be enabled
-            should_enable_vote_buttons = gr.State(False)
-
-            # --- Register event handlers ---
-
-            # "Randomize All" button click event handler chain
-            # 1. Disable interactive UI components
-            # 2. Reset UI state for audio players and voting results
-            # 3. Select random sample character description
-            # 4. Generate text
-            # 5. Synthesize speech
-            # 6. Enable interactive UI components
-            randomize_all_button.click(
-                fn=self._disable_ui,
-                inputs=[],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            ).then(
-                fn=self._reset_voting_ui,
-                inputs=[],
-                outputs=[
-                    option_a_audio_player,
-                    option_b_audio_player,
-                    vote_button_a,
-                    vote_button_b,
-                    vote_result_a,
-                    vote_result_b,
-                    option_map_state,
-                    vote_submitted_state,
-                    should_enable_vote_buttons,
-                ],
-            ).then(
-                fn=self._randomize_character_description,
-                inputs=[],
-                outputs=[sample_character_description_dropdown, character_description_input],
-            ).then(
-                fn=self._generate_text,
-                inputs=[character_description_input],
-                outputs=[text_input, generated_text_state],
-            ).then(
-                fn=self._synthesize_speech,
-                inputs=[character_description_input, text_input, generated_text_state],
-                outputs=[
-                    option_a_audio_player,
-                    option_b_audio_player,
-                    option_map_state,
-                    text_modified_state,
-                    text_state,
-                    character_description_state,
-                    should_enable_vote_buttons,
-                ],
-            ).then(
-                fn=self._enable_ui,
-                inputs=[should_enable_vote_buttons],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            )
+                option_map_state,
+                vote_submitted_state,
+                should_enable_vote_buttons,
+            ],
+        ).then(
+            fn=self._synthesize_speech,
+            inputs=[character_description_input, text_input, generated_text_state],
+            outputs=[
+                option_a_audio_player,
+                option_b_audio_player,
+                option_map_state,
+                text_modified_state,
+                text_state,
+                character_description_state,
+                should_enable_vote_buttons,
+            ],
+        ).then(
+            fn=self._enable_ui,
+            inputs=[should_enable_vote_buttons],
+            outputs=[
+                randomize_all_button,
+                sample_character_description_dropdown,
+                character_description_input,
+                generate_text_button,
+                text_input,
+                synthesize_speech_button,
+                vote_button_a,
+                vote_button_b,
+            ],
+        )
 
-            # "Sample Characters" dropdown select event handler chain:
-            # 1. Update Character Description field with sample
-            # 2. Disable interactive UI components
-            # 3. Generate text
-            # 4. Enable interactive UI components
-            sample_character_description_dropdown.select(
-                fn=lambda choice: constants.SAMPLE_CHARACTER_DESCRIPTIONS.get(choice, ""),
-                inputs=[sample_character_description_dropdown],
-                outputs=[character_description_input],
-            ).then(
-                fn=self._disable_ui,
-                inputs=[],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            ).then(
-                fn=self._generate_text,
-                inputs=[character_description_input],
-                outputs=[text_input, generated_text_state],
-            ).then(
-                fn=self._enable_ui,
-                inputs=[should_enable_vote_buttons],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            )
+        # "Select Option A"  button click event handler chain:
+        vote_button_a.click(
+            fn=lambda _=None: (gr.update(interactive=False), gr.update(interactive=False)),
+            inputs=[],
+            outputs=[vote_button_a, vote_button_b],
+        ).then(
+            fn=self._vote,
+            inputs=[
+                vote_submitted_state,
+                option_map_state,
+                vote_button_a,
+                text_modified_state,
+                character_description_state,
+                text_state,
+            ],
+            outputs=[
+                vote_submitted_state,
+                vote_button_a,
+                vote_button_b,
+                vote_result_a,
+                vote_result_b,
+                synthesize_speech_button,
+            ],
+        )
 
-            # "Generate Text" button click event handler chain:
-            # 1. Disable interactive UI components
-            # 2. Generate text
-            # 3. Enable interactive UI components
-            generate_text_button.click(
-                fn=self._disable_ui,
-                inputs=[],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            ).then(
-                fn=self._generate_text,
-                inputs=[character_description_input],
-                outputs=[text_input, generated_text_state],
-            ).then(
-                fn=self._enable_ui,
-                inputs=[should_enable_vote_buttons],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            )
+        # "Select Option B"  button click event handler chain:
+        vote_button_b.click(
+            fn=lambda _=None: (gr.update(interactive=False), gr.update(interactive=False)),
+            inputs=[],
+            outputs=[vote_button_a, vote_button_b],
+        ).then(
+            fn=self._vote,
+            inputs=[
+                vote_submitted_state,
+                option_map_state,
+                vote_button_b,
+                text_modified_state,
+                character_description_state,
+                text_state,
+            ],
+            outputs=[
+                vote_submitted_state,
+                vote_button_a,
+                vote_button_b,
+                vote_result_a,
+                vote_result_b,
+                synthesize_speech_button,
+            ],
+        )
 
-            # "Synthesize Speech" button click event handler chain:
-            # 1. Disable components in the UI
-            # 2. Reset UI state for audio players and voting results
-            # 3. Synthesize speech, load audio players, and display vote button
-            # 4. Enable interactive components in the UI
-            synthesize_speech_button.click(
-                fn=self._disable_ui,
-                inputs=[],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            ).then(
-                fn=self._reset_voting_ui,
-                inputs=[],
-                outputs=[
-                    option_a_audio_player,
-                    option_b_audio_player,
-                    vote_button_a,
-                    vote_button_b,
-                    vote_result_a,
-                    vote_result_b,
-                    option_map_state,
-                    vote_submitted_state,
-                    should_enable_vote_buttons,
-                ],
-            ).then(
-                fn=self._synthesize_speech,
-                inputs=[character_description_input, text_input, generated_text_state],
-                outputs=[
-                    option_a_audio_player,
-                    option_b_audio_player,
-                    option_map_state,
-                    text_modified_state,
-                    text_state,
-                    character_description_state,
-                    should_enable_vote_buttons,
-                ],
-            ).then(
-                fn=self._enable_ui,
-                inputs=[should_enable_vote_buttons],
-                outputs=[
-                    randomize_all_button,
-                    sample_character_description_dropdown,
-                    character_description_input,
-                    generate_text_button,
-                    text_input,
-                    synthesize_speech_button,
-                    vote_button_a,
-                    vote_button_b,
-                ],
-            )
+        # Audio Player A stop event handler
+        option_a_audio_player.stop(
+            # Workaround to play both audio samples back-to-back
+            fn=lambda option_map: gr.update(
+                value=f"{option_map['option_b']['audio_file_path']}?t={int(time.time())}",
+                autoplay=True,
+            ),
+            inputs=[option_map_state],
+            outputs=[option_b_audio_player],
+        )
 
-            # "Select Option A"  button click event handler chain:
-            vote_button_a.click(
-                fn=lambda _=None: (gr.update(interactive=False), gr.update(interactive=False)),
-                inputs=[],
-                outputs=[vote_button_a, vote_button_b],
-            ).then(
-                fn=self._vote,
-                inputs=[
-                    vote_submitted_state,
-                    option_map_state,
-                    vote_button_a,
-                    text_modified_state,
-                    character_description_state,
-                    text_state,
-                ],
-                outputs=[
-                    vote_submitted_state,
-                    vote_button_a,
-                    vote_button_b,
-                    vote_result_a,
-                    vote_result_b,
-                    synthesize_speech_button,
-                ],
+    def _build_leaderboard_section(self) -> None:
+        """
+        Builds the Leaderboard section
+        """
+        # --- UI components ---
+        with gr.Row():
+            with gr.Column(scale=5):
+                gr.HTML(
+                    """
+                    <h2 class="tab-header">🏆 Leaderboard</h2>
+                    <p>
+                        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>
+                    """
+                )
+            refresh_button = gr.Button(
+                "↻ Refresh",
+                variant="primary",
+                elem_classes="refresh-btn",
+                scale=1,
             )
 
-            # "Select Option B"  button click event handler chain:
-            vote_button_b.click(
-                fn=lambda _=None: (gr.update(interactive=False), gr.update(interactive=False)),
-                inputs=[],
-                outputs=[vote_button_a, vote_button_b],
-            ).then(
-                fn=self._vote,
-                inputs=[
-                    vote_submitted_state,
-                    option_map_state,
-                    vote_button_b,
-                    text_modified_state,
-                    character_description_state,
-                    text_state,
-                ],
-                outputs=[
-                    vote_submitted_state,
-                    vote_button_a,
-                    vote_button_b,
-                    vote_result_a,
-                    vote_result_b,
-                    synthesize_speech_button,
-                ],
+        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"
             )
 
-            # Audio Player A stop event handler
-            option_a_audio_player.stop(
-                # Workaround to play both audio samples back-to-back
-                fn=lambda option_map: gr.update(
-                    value=f"{option_map['option_b']['audio_file_path']}?t={int(time.time())}",
-                    autoplay=True,
-                ),
-                inputs=[option_map_state],
-                outputs=[option_b_audio_player],
-            )
+        # --- Register event handlers ---
+        # Refresh button click event handler
+        refresh_button.click(
+            fn=lambda _=None: (gr.update(interactive=False)),
+            inputs=[],
+            outputs=[refresh_button],
+        ).then(
+            fn=self._refresh_leaderboard,
+            inputs=[],
+            outputs=[leaderboard_table]
+        ).then(
+            fn=lambda _=None: (gr.update(interactive=True)),
+            inputs=[],
+            outputs=[refresh_button],
+        )
+
+    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():
+                with gr.TabItem("Arena"):
+                    self._build_arena_section()
+                with gr.TabItem("Leaderboard"):
+                    self._build_leaderboard_section()
 
         logger.debug("Gradio interface built successfully")
         return demo

src/main.py

@@ -86,19 +86,19 @@ async def main():
     db_session_maker = init_db(config)
 
     frontend = Frontend(config, db_session_maker)
-    demo = frontend.build_gradio_interface()
+    demo = await frontend.build_gradio_interface()
 
     app = FastAPI()
     app.add_middleware(ResponseModifierMiddleware)
 
-    assets_dir = Path("src/assets")
-    app.mount("/static", StaticFiles(directory=assets_dir), name="static")
+    public_dir = Path("public")
+    app.mount("/static", StaticFiles(directory=public_dir), name="static")
 
     gr.mount_gradio_app(
         app=app,
         blocks=demo,
         path="/",
-        allowed_paths=[str(config.audio_dir), "src/assets"]
+        allowed_paths=["static"]
     )
 
     import uvicorn

src/utils.py

@@ -314,41 +314,54 @@ def _log_voting_results(voting_results: VotingResults) -> None:
     logger.info("Voting results:\n%s", json.dumps(voting_results, indent=4))
 
 
-async def _persist_vote(db_session_maker: AsyncDBSessionMaker, voting_results: VotingResults, config: Config) -> None:
+async def _create_db_session(db_session_maker: AsyncDBSessionMaker) -> AsyncSession:
     """
-    Asynchronously persist a vote record in the database and handle potential failures.
-    Designed to work safely in a background task context.
+    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.
-        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
+        AsyncSession: A newly created database session that can be used for database operations.
     """
-    # Create session
     session = db_session_maker()
     is_dummy_session = getattr(session, "is_dummy", False)
 
     if is_dummy_session:
-        logger.info("Vote record created successfully.")
-        _log_voting_results(voting_results)
         await session.close()
-        return
+        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 crud.create_vote(cast(AsyncSession, session), voting_results)
-        logger.info("Vote record created successfully.")
-        if config.app_env == "dev":
-            _log_voting_results(voting_results)
     except Exception as e:
-        # Log the error with traceback in production, without traceback in dev
-        logger.error(f"Failed to create vote record: {e}", exc_info=(config.app_env == "prod"))
-        _log_voting_results(voting_results)
+        # Log the error with traceback
+        logger.error(f"Failed to create vote record: {e}", exc_info=True)
     finally:
         # Always ensure the session is closed
-        await session.close()
+        if session is not None:
+            await session.close()
 
 
 async def submit_voting_results(
@@ -358,7 +371,6 @@ async def submit_voting_results(
     character_description: str,
     text: str,
     db_session_maker: AsyncDBSessionMaker,
-    config: Config,
 ) -> None:
     """
     Asynchronously constructs the voting results dictionary and persists a new vote record.
@@ -395,13 +407,57 @@ async def submit_voting_results(
             "is_custom_text": text_modified,
         }
 
-        await _persist_vote(db_session_maker, voting_results, config)
+        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) -> List[List[str]]:
+    """
+    Fetches leaderboard data from voting results database
+
+    Returns:
+        LeaderboardTableEntries: A list of LeaderboardEntry objects containing rank, provider name anchor tag, model
+                                name anchor tag, win rate, and total votes.
+    """
+    # Create session
+    session = await _create_db_session(db_session_maker)
+    try:
+        leaderboard_data = await crud.get_leaderboard_stats(cast(AsyncSession, session))
+        logger.info("Fetched leaderboard data successfully.")
+        # return data formatted for the UI (adds links and styling)
+        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
+        ]
+    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 validate_env_var(var_name: str) -> str:
     """
     Validates that an environment variable is set and returns its value.

{src/assets → static/css}/styles.css

@@ -1,47 +1,50 @@
-/* Remove Gradio footer */
-footer.svelte-1byz9vf {
+/* Override Gradio vertical scroll bar styling */
+html::-webkit-scrollbar,
+body::-webkit-scrollbar {
   display: none !important;
 }
 
-/* Remove unnecessary padding from HTML containers */
-.html-container.svelte-phx28p.padding {
-  padding: 0px !important;
+html,
+body {
+  -ms-overflow-style: none !important;
+  scrollbar-width: none !important;
+}
+
+/* Remove Gradio footer */
+footer.svelte-1byz9vf {
+  display: none !important;
 }
 
 /* Title container styling */
 .title-container {
   display: flex;
   align-items: center;
-  height: 40px !important;
-  overflow: visible !important;
+  justify-content: space-between;
 }
 
-.title-container h1 {
-  margin: 0 !important;
-  margin-right: auto !important;
+
+.excerpt-container {
+  margin: 8px 0;
 }
 
 /* Social links container */
 .social-links {
   display: flex;
-  align-items: center;
   gap: 12px;
-  margin: 0px 8px;
-  overflow: visible !important;
 }
 
 /* Social media icons common styles */
 #github-link, 
 #discord-link {
-  display: inline-block !important;
-  width: 30px !important;
-  height: 30px !important;
-  background-size: cover !important;
-  background-position: center !important;
-  background-repeat: no-repeat !important;
-  transition: transform 0.2s ease-in-out !important;
-  border-radius: 50% !important;
-  flex-shrink: 0 !important;
+  display: inline-block;
+  width: 30px;
+  height: 30px;
+  background-size: cover;
+  background-position: center;
+  background-repeat: no-repeat;
+  transition: transform 0.2s ease-in-out;
+  border-radius: 50%;
+  flex-shrink: 0;
 }
 
 /* Hover effect for social media icons */
@@ -54,27 +57,40 @@ footer.svelte-1byz9vf {
 #discord-link {
   background-image: url(
     'https://assets-global.website-files.com/6257adef93867e50d84d30e2/636e0a6a49cf127bf92de1e2_icon_clyde_blurple_RGB.png'
-  ) !important;
-  background-size: 90% !important;
+  );
+  background-size: 90%;
 }
-
+  
 /* GitHub icon specific styling */
 #github-link {
   background-image: url(
     'https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png'
-  ) !important;
+    );
+}
+
+.tab-header {
+  font-size: 18px;
 }
 
 /* Vote result styling */
 #vote-result-a textarea,
 #vote-result-b textarea {
-  font-size: 16px !important;
-  font-weight: bold !important;
+  font-size: 16px;
+  font-weight: bold;
 }
 
 /* Winner styling */
 #vote-result-a.winner textarea,
 #vote-result-b.winner textarea {
-  background: #EA580C;
+  background: #F97316;
   color: #FFFFFF;
 }
+    
+.provider-link {
+  color: #F97316;
+  text-decoration: underline;
+}
+
+.provider-link:hover {
+  color: #EA580C;
+}