Add database for persisting votes, and functions to write to db, update submit_voting_results function to write results to DB

src/database/__init__.py

@@ -0,0 +1,11 @@
+from .crud import create_vote
+from .database import Base, SessionLocal, engine
+from .models import VoteResult
+
+__all__ = [
+    "Base",
+    "SessionLocal",
+    "VoteResult",
+    "create_vote",
+    "engine"
+]

src/database/crud.py

@@ -0,0 +1,46 @@
+"""
+crud.py
+
+This module defines the core CRUD 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.
+"""
+
+# Third-Party Library Imports
+from sqlalchemy.orm import Session
+
+# Local Application Imports
+from src.custom_types import VotingResults
+from src.database.models import VoteResult
+
+
+def create_vote(db: Session, vote_data: VotingResults) -> VoteResult:
+    """
+    Create a new vote record in the database based on the given VotingResults data.
+
+    Args:
+        db (Session): The SQLAlchemy database session.
+        vote_data (VotingResults): The vote data to persist.
+
+    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["voice_description"],
+        text=vote_data["text"],
+        is_custom_text=vote_data["is_custom_text"],
+    )
+    db.add(vote)
+    try:
+        db.commit()
+    except Exception as e:
+        db.rollback()
+        raise e
+    db.refresh(vote)
+    return vote

src/database/database.py

@@ -0,0 +1,26 @@
+"""
+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.
+"""
+
+# Third-Party Library Imports
+from sqlalchemy import create_engine
+from sqlalchemy.orm import declarative_base, sessionmaker
+
+# Local Application Imports
+from src.config import validate_env_var
+
+# Validate and retrieve the database URL from environment variables
+DATABASE_URL = validate_env_var("DATABASE_URL")
+
+# Create the database engine using the validated URL
+engine = create_engine(DATABASE_URL)
+
+# Create a session factory for database transactions
+SessionLocal = sessionmaker(bind=engine)
+
+# Declarative base class for ORM models
+Base = declarative_base()

src/database/models.py

@@ -0,0 +1,63 @@
+"""
+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
+
+# Third-Party Library Imports
+from sqlalchemy import (
+    Boolean,
+    Column,
+    DateTime,
+    Index,
+    Integer,
+    String,
+    Text,
+    func,
+)
+from sqlalchemy import (
+    Enum as saEnum,
+)
+from sqlalchemy import (
+    text as sa_text,
+)
+
+# Local Application Imports
+from src.database.database import Base
+
+
+class OptionEnum(str, Enum):
+    OPTION_A = "option_a"
+    OPTION_B = "option_b"
+
+class VoteResult(Base):
+    __tablename__ = "vote_results"
+
+    id = Column(Integer, primary_key=True, autoincrement=True)
+    created_at = Column(DateTime, nullable=False, server_default=func.now())
+    comparison_type = Column(String(50), nullable=False)
+    winning_provider = Column(String(50), nullable=False)
+    winning_option = Column(saEnum(OptionEnum), nullable=False)
+    option_a_provider = Column(String(50), nullable=False)
+    option_b_provider = Column(String(50), nullable=False)
+    option_a_generation_id = Column(String(100), nullable=True)
+    option_b_generation_id = Column(String(100), nullable=True)
+    voice_description = Column(Text, nullable=False)
+    text = Column(Text, nullable=False)
+    is_custom_text = Column(Boolean, nullable=False, server_default=sa_text("false"))
+
+    __table_args__ = (
+        Index("idx_created_at", "created_at"),
+        Index("idx_comparison_type", "comparison_type"),
+        Index("idx_winning_provider", "winning_provider"),
+    )
+
+    def __repr__(self):
+        return (
+            f"<VoteResult(id={self.id}, created_at={self.created_at}, "
+            f"comparison_type={self.comparison_type}, winning_provider={self.winning_provider})>"
+        )

src/integrations/__init__.py

@@ -1,3 +1,12 @@
-from .anthropic_api import generate_text_with_claude, AnthropicError
-from .elevenlabs_api import text_to_speech_with_elevenlabs, ElevenLabsError
-from .hume_api import text_to_speech_with_hume, HumeError
+from .anthropic_api import AnthropicError, generate_text_with_claude
+from .elevenlabs_api import ElevenLabsError, text_to_speech_with_elevenlabs
+from .hume_api import HumeError, text_to_speech_with_hume
+
+__all__ = [
+    "AnthropicError",
+    "ElevenLabsError",
+    "HumeError",
+    "generate_text_with_claude",
+    "text_to_speech_with_elevenlabs",
+    "text_to_speech_with_hume"
+]

src/scripts/__init__.py

@@ -0,0 +1,3 @@
+"""
+This package contains standalone utility scripts.
+"""

src/scripts/init_db.py

@@ -0,0 +1,20 @@
+"""
+init_db.py
+
+This script initializes the database by creating all tables defined in the ORM models.
+Run this script once to create your tables in the PostgreSQL database.
+"""
+
+# Local Application Imports
+from src.config import logger
+from src.database.database import engine
+from src.database.models import Base
+
+
+def init_db():
+    Base.metadata.create_all(bind=engine)
+    logger.info("Database tables created successfully.")
+
+
+if __name__ == "__main__":
+    init_db()

src/scripts/test_db.py

@@ -0,0 +1,41 @@
+"""
+test_db.py
+
+This script verifies the database connection for the Expressive TTS Arena project.
+It attempts to connect to the PostgreSQL database using SQLAlchemy and executes a simple query.
+
+Functionality:
+- Loads the database connection from `database.py`.
+- Attempts to establish a connection to the database.
+- Executes a test query (`SELECT 1`) to confirm connectivity.
+- Prints a success message if the connection is valid.
+- Prints an error message if the connection fails.
+
+Usage:
+    python src/test_db.py
+
+Expected Output:
+    Database connection successful!  (if the database is reachable)
+    Database connection failed: <error message> (if there are connection issues)
+
+Troubleshooting:
+- Ensure the `.env` file contains a valid `DATABASE_URL`.
+- Check that the database server is running and accessible.
+- Verify PostgreSQL credentials and network settings.
+
+"""
+
+# Third-Party Library Imports
+from sqlalchemy import text
+from sqlalchemy.exc import OperationalError
+
+# Local Application Imports
+from src.config import logger
+from src.database import engine
+
+try:
+    with engine.connect() as conn:
+        result = conn.execute(text("SELECT 1"))
+        logger.info("Database connection successful!")
+except OperationalError as e:
+    logger.error(f"Database connection failed: {e}")

src/utils.py

@@ -24,6 +24,7 @@ from src.custom_types import (
     TTSProviderName,
     VotingResults,
 )
+from src.database import SessionLocal, VoteResult, crud
 
 
 def truncate_text(text: str, max_length: int = 50) -> str:
@@ -311,20 +312,20 @@ def submit_voting_results(
     text_modified: bool,
     character_description: str,
     text: str,
-) -> VotingResults:
+) -> VoteResult:
     """
-    Constructs the voting results dictionary from the provided inputs and logs it.
+    Constructs the voting results dictionary from the provided inputs,
+    logs it, persists a new vote record in the database, and returns the record.
 
     Args:
         option_map (OptionMap): Mapping of comparison data and TTS options.
         selected_option (str): The option selected by the user.
-        comparison_type (ComparisonType): The type of comparison between providers.
         text_modified (bool): Indicates whether the text was modified.
         character_description (str): Description of the voice/character.
         text (str): The text associated with the TTS generation.
 
     Returns:
-        VotingResults: The constructed voting results dictionary.
+        VoteResult: The newly created vote record from the database.
     """
     provider_a: TTSProviderName = option_map[constants.OPTION_A_KEY]["provider"]
     provider_b: TTSProviderName = option_map[constants.OPTION_B_KEY]["provider"]
@@ -342,6 +343,15 @@ def submit_voting_results(
         "text": text,
         "is_custom_text": text_modified,
     }
-    # TODO: Currently logging the results until we hook the API for writing results to DB
+
     logger.info("Voting results:\n%s", json.dumps(voting_results, indent=4))
-    return voting_results
+
+    # Create a new database session, persist the vote record, and then close the session.
+    db = SessionLocal()
+    try:
+        vote_record = crud.create_vote(db, voting_results)
+        logger.info("Vote record created successfully")
+    finally:
+        db.close()
+
+    return vote_record