Add '_' prefix to private methods throughout project, cleans up formatting and comments/docstrings

src/app.py

@@ -47,7 +47,7 @@ class App:
         self.config = config
         self.db_session_maker = db_session_maker
 
-    def generate_text(
+    def _generate_text(
         self,
         character_description: str,
     ) -> Tuple[Union[str, gr.update], gr.update]:
@@ -65,6 +65,7 @@ class App:
         Raises:
             gr.Error: On validation or API errors.
         """
+
         try:
             validate_character_description_length(character_description)
         except ValueError as ve:
@@ -82,7 +83,7 @@ class App:
             logger.error(f"Unexpected error while generating text: {e}")
             raise gr.Error("Failed to generate text. Please try again later.")
 
-    def synthesize_speech(
+    def _synthesize_speech(
         self,
         character_description: str,
         text: str,
@@ -121,6 +122,7 @@ class App:
         Raises:
             gr.Error: If any API or unexpected errors occur during the TTS synthesis process.
         """
+
         if not text:
             logger.warning("Skipping text-to-speech due to empty text.")
             raise gr.Error("Please generate or enter text to synthesize.")
@@ -185,7 +187,7 @@ class App:
             logger.error(f"Unexpected error during TTS generation: {e}")
             raise gr.Error("An unexpected error ocurred. Please try again later.")
 
-    def vote(
+    def _vote(
         self,
         vote_submitted: bool,
         option_map: OptionMap,
@@ -214,6 +216,7 @@ class App:
              - An update for the unselected vote button (showing provider).
              - An update for enabling vote interactions.
         """
+
         if not option_map or vote_submitted:
             return gr.skip(), gr.skip(), gr.skip(), gr.skip()
 
@@ -251,7 +254,7 @@ class App:
             gr.update(interactive=True),
         )
 
-    def reset_ui(self) -> Tuple[gr.update, gr.update, gr.update, gr.update, None, bool]:
+    def _reset_ui(self) -> Tuple[gr.update, gr.update, gr.update, gr.update, None, bool]:
         """
         Resets UI state before generating new text.
 
@@ -264,6 +267,7 @@ class App:
              - option_map_state (reset option map state)
              - vote_submitted_state (reset submitted vote state)
         """
+
         return (
             gr.update(value=None),
             gr.update(value=None, autoplay=False),
@@ -273,11 +277,12 @@ class App:
             False,
         )
 
-    def build_input_section(self) -> Tuple[gr.Dropdown, gr.Textbox, gr.Button]:
+    def _build_input_section(self) -> Tuple[gr.Dropdown, gr.Textbox, gr.Button]:
         """
         Builds the input section including the sample character description dropdown, character
         description input, and generate text button.
         """
+
         sample_character_description_dropdown = gr.Dropdown(
             choices=list(constants.SAMPLE_CHARACTER_DESCRIPTIONS.keys()),
             label="Choose a sample character description",
@@ -299,10 +304,11 @@ class App:
             generate_text_button,
         )
 
-    def build_output_section(self) -> Tuple[gr.Textbox, gr.Button, gr.Audio, gr.Audio, gr.Button, gr.Button]:
+    def _build_output_section(self) -> Tuple[gr.Textbox, gr.Button, gr.Audio, gr.Audio, gr.Button, gr.Button]:
         """
         Builds the output section including text input, audio players, and vote buttons.
         """
+
         text_input = gr.Textbox(
             label="Input Text",
             placeholder="Enter or generate text for synthesis...",
@@ -336,6 +342,7 @@ class App:
         Returns:
             gr.Blocks: The fully constructed Gradio UI layout.
         """
+
         custom_theme = CustomTheme()
         with gr.Blocks(
             title="Expressive TTS Arena",
@@ -364,7 +371,7 @@ class App:
                 sample_character_description_dropdown,
                 character_description_input,
                 generate_text_button,
-            ) = self.build_input_section()
+            ) = self._build_input_section()
 
             # Build synthesize speech section
             (
@@ -374,7 +381,7 @@ class App:
                 option_b_audio_player,
                 vote_button_a,
                 vote_button_b,
-            ) = self.build_output_section()
+            ) = self._build_output_section()
 
             # --- UI state components ---
 
@@ -411,7 +418,7 @@ class App:
                 inputs=[],
                 outputs=[generate_text_button],
             ).then(
-                fn=self.generate_text,
+                fn=self._generate_text,
                 inputs=[character_description_input],
                 outputs=[text_input, generated_text_state],
             ).then(
@@ -434,7 +441,7 @@ class App:
                 inputs=[],
                 outputs=[synthesize_speech_button, vote_button_a, vote_button_b],
             ).then(
-                fn=self.reset_ui,
+                fn=self._reset_ui,
                 inputs=[],
                 outputs=[
                     option_a_audio_player,
@@ -445,7 +452,7 @@ class App:
                     vote_submitted_state,
                 ],
             ).then(
-                fn=self.synthesize_speech,
+                fn=self._synthesize_speech,
                 inputs=[character_description_input, text_input, generated_text_state],
                 outputs=[
                     option_a_audio_player,
@@ -474,7 +481,7 @@ class App:
                 inputs=[],
                 outputs=[vote_button_a, vote_button_b],
             ).then(
-                fn=self.vote,
+                fn=self._vote,
                 inputs=[
                     vote_submitted_state,
                     option_map_state,

src/config.py

@@ -23,6 +23,7 @@ from dotenv import load_dotenv
 if TYPE_CHECKING:
     from src.integrations import AnthropicConfig, ElevenLabsConfig, HumeConfig
 
+
 logger: logging.Logger = logging.getLogger("tts_arena")
 
 

src/constants.py

@@ -13,6 +13,7 @@ from src.custom_types import ComparisonType, OptionKey, OptionLabel, TTSProvider
 CLIENT_ERROR_CODE = 400
 SERVER_ERROR_CODE = 500
 
+
 # UI constants
 HUME_AI: TTSProviderName = "Hume AI"
 ELEVENLABS: TTSProviderName = "ElevenLabs"
@@ -28,13 +29,15 @@ OPTION_A_KEY: OptionKey = "option_a"
 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"
 
 
 # A collection of pre-defined character descriptions categorized by theme, used to provide users with
-# inspiration for generating creative text for expressive TTS, and generating novel voices.
+# inspiration for generating creative, expressive text inputs for TTS, and generating novel voices.
 SAMPLE_CHARACTER_DESCRIPTIONS: dict = {
     "🚀 Stranded Astronaut": (
         "A lone astronaut whose voice mirrors the silent vastness of space—a low, steady tone imbued "

src/database/database.py

@@ -52,6 +52,7 @@ class DummySession:
 Base = declarative_base()
 engine: Optional[Engine] = None
 
+
 DBSessionMaker = sessionmaker | Callable[[], DummySession]
 
 

src/integrations/anthropic_api.py

@@ -69,6 +69,7 @@ where you are in the narrative.
 Remember: A shorter, complete response is ALWAYS better than a longer, truncated one."""
 )
 
+
 @dataclass(frozen=True)
 class AnthropicConfig:
     """Immutable configuration for interacting with the Anthropic API."""
@@ -166,6 +167,7 @@ def generate_text_with_claude(character_description: str, config: Config) -> str
         UnretryableAnthropicError: For errors that should not be retried.
         AnthropicError: For other errors communicating with the Anthropic API.
     """
+
     try:
         anthropic_config = config.anthropic_config
         prompt = anthropic_config.build_expressive_prompt(character_description)

src/integrations/elevenlabs_api.py

@@ -105,6 +105,7 @@ def text_to_speech_with_elevenlabs(
     Raises:
         ElevenLabsError: If there is an error communicating with the ElevenLabs API or processing the response.
     """
+
     logger.debug(f"Synthesizing speech with ElevenLabs. Text length: {len(text)} characters.")
 
     elevenlabs_config = config.elevenlabs_config

src/integrations/hume_api.py

@@ -128,6 +128,7 @@ def text_to_speech_with_hume(
         Exception: Any other exceptions raised during the request or processing will be wrapped and
                    re-raised as HumeError.
     """
+
     logger.debug(
         f"Processing TTS with Hume. Prompt length: {len(character_description)} characters. "
         f"Text length: {len(text)} characters."
@@ -161,13 +162,13 @@ def text_to_speech_with_hume(
 
         # Extract the base64 encoded audio and generation ID from the generation.
         generation_a = generations[0]
-        generation_a_id, audio_a_path = parse_hume_tts_generation(generation_a, config)
+        generation_a_id, audio_a_path = _parse_hume_tts_generation(generation_a, config)
 
         if num_generations == 1:
             return (generation_a_id, audio_a_path)
 
         generation_b = generations[1]
-        generation_b_id, audio_b_path = parse_hume_tts_generation(generation_b, config)
+        generation_b_id, audio_b_path = _parse_hume_tts_generation(generation_b, config)
         return (generation_a_id, audio_a_path, generation_b_id, audio_b_path)
 
     except Exception as e:
@@ -187,7 +188,7 @@ def text_to_speech_with_hume(
         ) from e
 
 
-def parse_hume_tts_generation(generation: Dict[str, Any], config: Config) -> Tuple[str, str]:
+def _parse_hume_tts_generation(generation: Dict[str, Any], config: Config) -> Tuple[str, str]:
     """
     Parse a Hume TTS generation response and save the decoded audio as an MP3 file.
 

src/main.py

@@ -4,9 +4,10 @@ main.py
 This module is the entry point for the app. It loads configuration and starts the Gradio app.
 """
 
+# Local Application Imports
 from src.app import App
 from src.config import Config, logger
-from src.database.database import init_db
+from src.database import init_db
 
 if __name__ == "__main__":
     config = Config.get()

src/utils.py

@@ -100,7 +100,7 @@ def validate_character_description_length(character_description: str) -> None:
     logger.debug(f"Character description length validation passed for character_description: {truncated_description}")
 
 
-def delete_files_older_than(directory: Path, minutes: int = 30) -> None:
+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.
 
@@ -154,15 +154,12 @@ def save_base64_audio_to_file(base64_audio: str, filename: str, config: Config)
     Raises:
         FileNotFoundError: If the audio file was not created.
     """
-    # Decode the base64-encoded audio into binary data.
-    audio_bytes = base64.b64decode(base64_audio)
 
-    # Construct the full absolute file path within the AUDIO_DIR directory using Path.
+    audio_bytes = base64.b64decode(base64_audio)
     file_path = Path(config.audio_dir) / filename
-
-    # Delete all audio files older than 30 minutes before writing the new audio file.
     num_minutes = 30
-    delete_files_older_than(config.audio_dir, num_minutes)
+
+    _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:
@@ -201,6 +198,7 @@ def choose_providers(
         where the first is always "Hume AI" and the second is determined by the text_modified
         flag and random selection.
     """
+
     hume_comparison_only = text_modified or not character_description
 
     provider_a = constants.HUME_AI
@@ -225,16 +223,11 @@ def create_shuffled_tts_options(option_a: Option, option_b: Option) -> OptionMap
         OptionMap: A mapping of shuffled TTS options, where each option includes
                    its provider, audio file path, and generation ID.
     """
-    # Create a list of Option instances for the available providers.
-    options = [option_a, option_b]
 
-    # Randomly shuffle the list of options.
+    options = [option_a, option_b]
     random.shuffle(options)
-
-    # Unpack the two options.
     shuffled_option_a, shuffled_option_b = options
 
-    # Build a mapping from option constants to the corresponding providers.
     return {
         "option_a": {
             "provider": shuffled_option_a.provider,
@@ -264,6 +257,7 @@ def determine_selected_option(
             - 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:
@@ -291,6 +285,7 @@ def _determine_comparison_type(provider_a: TTSProviderName, provider_b: TTSProvi
     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
 
@@ -302,6 +297,7 @@ def _determine_comparison_type(provider_a: TTSProviderName, provider_b: TTSProvi
 
 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))
 
 
@@ -321,6 +317,7 @@ def _handle_vote_failure(
     In development with a dummy session:
       - Only logs the voting results.
     """
+
     if config.app_env == "prod" or (config.app_env == "dev" and not is_dummy_db_session):
         logger.error("Failed to create vote record: %s", e, exc_info=(config.app_env == "prod"))
         _log_voting_results(voting_results)
@@ -332,6 +329,23 @@ def _handle_vote_failure(
 
 
 def _persist_vote(db_session_maker: DBSessionMaker, voting_results: VotingResults, config: Config) -> None:
+    """
+    Persist a vote record in the database and handle potential failures.
+
+    This function obtains a database session using the provided session maker and attempts
+    to create a vote record using the specified voting results. If the session is identified
+    as a dummy session, it logs a success message and outputs the voting results. If an error
+    occurs during vote creation, the function delegates error handling to _handle_vote_failure.
+    On successful vote creation, it logs the success and, when running in a development environment,
+    logs the full voting results for debugging purposes. In all cases, the database session is
+    properly closed after the operation.
+
+    Args:
+        db_session_maker (DBSessionMaker): A callable that returns a new 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.
+    """
+
     db = db_session_maker()
     is_dummy_db_session = getattr(db, "is_dummy", False)
     if is_dummy_db_session:
@@ -369,6 +383,7 @@ def submit_voting_results(
         character_description (str): Description of the voice/character.
         text (str): The text associated with the TTS generation.
     """
+
     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)