feat: Implement user management service with Supabase integration, including user registration, retrieval, and name update endpoints.

config.py

@@ -39,6 +39,10 @@ GROQ_TTS_FORMAT = "wav"
 # **Chat Model**
 GROQ_CHAT_MODEL = "llama3-70b-8192"
 
+# ============ SUPABASE ============
+SUPABASE_URL = os.getenv("SUPABASE_URL", "")
+SUPABASE_KEY = os.getenv("SUPABASE_KEY", "")
+
 # ============ API META ============
 API_TITLE = "NLP Debater - Voice Chatbot"
 API_DESCRIPTION = "NLP stance detection, KPA, and Groq STT/TTS chatbot"
@@ -80,4 +84,5 @@ logger.info(f"  HF Label Model  : {HUGGINGFACE_LABEL_MODEL_ID}")
 logger.info(f"  GROQ STT Model  : {GROQ_STT_MODEL}")
 logger.info(f"  GROQ TTS Model  : {GROQ_TTS_MODEL}")
 logger.info(f"  GROQ Chat Model : {GROQ_CHAT_MODEL}")
+logger.info(f"  Supabase URL    : {'✓ Configured' if SUPABASE_URL else '✗ Not configured'}")
 logger.info("="*60)

models/__init__.py

@@ -36,6 +36,14 @@ from .topic import (
     BatchTopicResponse,
 )
 
+# Import user-related schemas
+from .user import (
+    UserRegisterRequest,
+    UserResponse,
+    UserUpdateNameRequest,
+    UserGetRequest,
+)
+
 # Import MCP-related schemas
 from .mcp_models import (
     ToolCallRequest,
@@ -72,6 +80,11 @@ __all__ = [
     "TopicResponse",
     "BatchTopicRequest",
     "BatchTopicResponse",
+    # User schemas
+    "UserRegisterRequest",
+    "UserResponse",
+    "UserUpdateNameRequest",
+    "UserGetRequest",
     # MCP schemas
     "ToolCallRequest",
     "ToolCallResponse",

models/user.py

@@ -0,0 +1,80 @@
+"""Pydantic models for user endpoints"""
+
+from pydantic import BaseModel, Field, ConfigDict
+from typing import Optional
+from datetime import datetime
+
+
+class UserRegisterRequest(BaseModel):
+    """Request model for user registration"""
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "unique_id": "550e8400-e29b-41d4-a716-446655440000",
+                "name": "John Doe"
+            }
+        }
+    )
+    
+    unique_id: str = Field(
+        ..., min_length=1, max_length=255,
+        description="Browser-generated unique identifier (stored in localStorage)"
+    )
+    name: Optional[str] = Field(
+        None, min_length=1, max_length=100,
+        description="User's display name (optional, will generate random if not provided)"
+    )
+
+
+class UserResponse(BaseModel):
+    """Response model for user data"""
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "unique_id": "550e8400-e29b-41d4-a716-446655440000",
+                "name": "John Doe",
+                "created_at": "2024-01-01T12:00:00Z",
+                "updated_at": "2024-01-01T12:00:00Z"
+            }
+        }
+    )
+    
+    id: str = Field(..., description="User UUID")
+    unique_id: str = Field(..., description="Browser-generated unique identifier")
+    name: str = Field(..., description="User's display name")
+    created_at: str = Field(..., description="User creation timestamp")
+    updated_at: str = Field(..., description="User last update timestamp")
+
+
+class UserUpdateNameRequest(BaseModel):
+    """Request model for updating user name"""
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "name": "Jane Doe"
+            }
+        }
+    )
+    
+    name: str = Field(
+        ..., min_length=1, max_length=100,
+        description="New display name"
+    )
+
+
+class UserGetRequest(BaseModel):
+    """Request model for getting user by unique_id"""
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "unique_id": "550e8400-e29b-41d4-a716-446655440000"
+            }
+        }
+    )
+    
+    unique_id: str = Field(
+        ..., min_length=1, max_length=255,
+        description="Browser-generated unique identifier"
+    )
+

requirements.txt

@@ -7,6 +7,7 @@ pydantic>=2.5.0
 # API Clients
 requests>=2.31.0
 groq>=0.9.0
+supabase>=2.0.0
 
 # LangChain
 langchain>=0.1.0

routes/__init__.py

@@ -1,7 +1,7 @@
 """API route handlers"""
 
 from fastapi import APIRouter
-from . import root, health, stance, label, generate, topic
+from . import root, health, stance, label, generate, topic, user
 from routes.tts_routes import router as audio_router
 # Create main router
 api_router = APIRouter()
@@ -13,6 +13,7 @@ api_router.include_router(stance.router, prefix="/stance")
 api_router.include_router(label.router, prefix="/label")
 api_router.include_router(generate.router, prefix="/generate")
 api_router.include_router(topic.router, prefix="/topic")
+api_router.include_router(user.router, prefix="/user")
 api_router.include_router(audio_router)
 
 __all__ = ["api_router"]

routes/user.py

@@ -0,0 +1,128 @@
+"""User management endpoints"""
+
+from fastapi import APIRouter, HTTPException, Header
+from typing import Optional
+import logging
+
+from services.user_service import user_service
+from models.user import (
+    UserRegisterRequest,
+    UserResponse,
+    UserUpdateNameRequest,
+    UserGetRequest,
+)
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+@router.post("/register", response_model=UserResponse, tags=["Users"])
+async def register_user(request: UserRegisterRequest):
+    """
+    Register a new user or get existing user by unique_id
+    
+    - **unique_id**: Browser-generated unique identifier (from localStorage)
+    - **name**: Optional display name (will generate random if not provided)
+    
+    Returns user data including the user_id to store in localStorage
+    """
+    try:
+        user = user_service.register_or_get_user(
+            unique_id=request.unique_id,
+            name=request.name
+        )
+        
+        logger.info(f"User registered/retrieved: {user.get('id')}")
+        return UserResponse(**user)
+        
+    except ValueError as e:
+        logger.error(f"Validation error: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Registration error: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Registration failed: {str(e)}")
+
+
+@router.get("/me", response_model=UserResponse, tags=["Users"])
+async def get_current_user(x_user_id: Optional[str] = Header(None, alias="X-User-ID")):
+    """
+    Get current user by user_id from header
+    
+    - **X-User-ID**: User UUID (sent in request header)
+    
+    Returns user data
+    """
+    if not x_user_id:
+        raise HTTPException(status_code=400, detail="X-User-ID header is required")
+    
+    try:
+        user = user_service.get_user_by_id(x_user_id)
+        
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+        
+        return UserResponse(**user)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting user: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Failed to get user: {str(e)}")
+
+
+@router.get("/by-unique-id", response_model=UserResponse, tags=["Users"])
+async def get_user_by_unique_id(unique_id: str):
+    """
+    Get user by unique_id (query parameter)
+    
+    - **unique_id**: Browser-generated unique identifier
+    
+    Returns user data
+    """
+    try:
+        user = user_service.get_user_by_unique_id(unique_id)
+        
+        if not user:
+            raise HTTPException(status_code=404, detail="User not found")
+        
+        return UserResponse(**user)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error getting user: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Failed to get user: {str(e)}")
+
+
+@router.patch("/me/name", response_model=UserResponse, tags=["Users"])
+async def update_user_name(
+    request: UserUpdateNameRequest,
+    x_user_id: Optional[str] = Header(None, alias="X-User-ID")
+):
+    """
+    Update user's display name
+    
+    - **X-User-ID**: User UUID (sent in request header)
+    - **name**: New display name
+    
+    Returns updated user data
+    """
+    if not x_user_id:
+        raise HTTPException(status_code=400, detail="X-User-ID header is required")
+    
+    try:
+        user = user_service.update_user_name(
+            user_id=x_user_id,
+            name=request.name
+        )
+        
+        logger.info(f"Updated user name: {x_user_id}")
+        return UserResponse(**user)
+        
+    except ValueError as e:
+        logger.error(f"Validation error: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Update error: {str(e)}")
+        raise HTTPException(status_code=500, detail=f"Update failed: {str(e)}")
+

services/__init__.py

@@ -8,6 +8,8 @@ from .generate_model_manager import GenerateModelManager, generate_model_manager
 from .stt_service import speech_to_text
 from .tts_service import text_to_speech
 from .topic_service import TopicService, topic_service
+from .database_service import DatabaseService, database_service
+from .user_service import UserService, user_service
 
 __all__ = [
     "StanceModelManager",
@@ -18,6 +20,10 @@ __all__ = [
     "generate_model_manager",
     "TopicService",
     "topic_service",
+    "DatabaseService",
+    "database_service",
+    "UserService",
+    "user_service",
 
     # NEW exports
     "speech_to_text",

services/database_service.py

@@ -0,0 +1,48 @@
+"""Database service for Supabase connection"""
+
+import logging
+from supabase import create_client, Client
+from config import SUPABASE_URL, SUPABASE_KEY
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseService:
+    """Service for managing Supabase database connection"""
+    
+    def __init__(self):
+        self.client: Client | None = None
+        self.connected = False
+    
+    def connect(self):
+        """Initialize Supabase client connection"""
+        if self.connected and self.client:
+            logger.info("Database already connected")
+            return
+        
+        if not SUPABASE_URL or not SUPABASE_KEY:
+            raise ValueError("SUPABASE_URL and SUPABASE_KEY must be set in environment variables")
+        
+        try:
+            logger.info("Connecting to Supabase...")
+            self.client = create_client(SUPABASE_URL, SUPABASE_KEY)
+            self.connected = True
+            logger.info("✓ Successfully connected to Supabase")
+        except Exception as e:
+            logger.error(f"Error connecting to Supabase: {str(e)}")
+            raise RuntimeError(f"Failed to connect to Supabase: {str(e)}")
+    
+    def get_client(self) -> Client:
+        """Get Supabase client instance"""
+        if not self.connected or not self.client:
+            self.connect()
+        return self.client
+    
+    def is_connected(self) -> bool:
+        """Check if database is connected"""
+        return self.connected and self.client is not None
+
+
+# Initialize singleton instance
+database_service = DatabaseService()
+

services/user_service.py

@@ -0,0 +1,167 @@
+"""User service for managing user operations"""
+
+import logging
+import uuid
+from typing import Optional, Dict
+from datetime import datetime
+
+from services.database_service import database_service
+
+logger = logging.getLogger(__name__)
+
+
+class UserService:
+    """Service for user CRUD operations"""
+    
+    def __init__(self):
+        self.table_name = "users"
+    
+    def _get_client(self):
+        """Get Supabase client"""
+        return database_service.get_client()
+    
+    def create_user(self, unique_id: str, name: str) -> Dict:
+        """
+        Create a new user or get existing user by unique_id
+        
+        Args:
+            unique_id: Browser-generated unique identifier
+            name: User's display name
+            
+        Returns:
+            User dictionary with id, unique_id, name, created_at, updated_at
+        """
+        try:
+            client = self._get_client()
+            
+            # Check if user already exists
+            existing_user = self.get_user_by_unique_id(unique_id)
+            if existing_user:
+                logger.info(f"User already exists with unique_id: {unique_id}")
+                return existing_user
+            
+            # Create new user
+            user_data = {
+                "unique_id": unique_id,
+                "name": name,
+                "created_at": datetime.utcnow().isoformat(),
+                "updated_at": datetime.utcnow().isoformat()
+            }
+            
+            result = client.table(self.table_name).insert(user_data).execute()
+            
+            if result.data and len(result.data) > 0:
+                logger.info(f"Created new user: {result.data[0].get('id')}")
+                return result.data[0]
+            else:
+                raise RuntimeError("Failed to create user: no data returned")
+                
+        except Exception as e:
+            logger.error(f"Error creating user: {str(e)}")
+            raise RuntimeError(f"Failed to create user: {str(e)}")
+    
+    def get_user_by_unique_id(self, unique_id: str) -> Optional[Dict]:
+        """
+        Get user by unique_id
+        
+        Args:
+            unique_id: Browser-generated unique identifier
+            
+        Returns:
+            User dictionary or None if not found
+        """
+        try:
+            client = self._get_client()
+            
+            result = client.table(self.table_name).select("*").eq("unique_id", unique_id).execute()
+            
+            if result.data and len(result.data) > 0:
+                return result.data[0]
+            return None
+                
+        except Exception as e:
+            logger.error(f"Error getting user by unique_id: {str(e)}")
+            raise RuntimeError(f"Failed to get user: {str(e)}")
+    
+    def get_user_by_id(self, user_id: str) -> Optional[Dict]:
+        """
+        Get user by id (UUID)
+        
+        Args:
+            user_id: User UUID
+            
+        Returns:
+            User dictionary or None if not found
+        """
+        try:
+            client = self._get_client()
+            
+            result = client.table(self.table_name).select("*").eq("id", user_id).execute()
+            
+            if result.data and len(result.data) > 0:
+                return result.data[0]
+            return None
+                
+        except Exception as e:
+            logger.error(f"Error getting user by id: {str(e)}")
+            raise RuntimeError(f"Failed to get user: {str(e)}")
+    
+    def update_user_name(self, user_id: str, name: str) -> Dict:
+        """
+        Update user's name
+        
+        Args:
+            user_id: User UUID
+            name: New display name
+            
+        Returns:
+            Updated user dictionary
+        """
+        try:
+            client = self._get_client()
+            
+            update_data = {
+                "name": name,
+                "updated_at": datetime.utcnow().isoformat()
+            }
+            
+            result = client.table(self.table_name).update(update_data).eq("id", user_id).execute()
+            
+            if result.data and len(result.data) > 0:
+                logger.info(f"Updated user name: {user_id}")
+                return result.data[0]
+            else:
+                raise RuntimeError("Failed to update user: user not found")
+                
+        except Exception as e:
+            logger.error(f"Error updating user name: {str(e)}")
+            raise RuntimeError(f"Failed to update user: {str(e)}")
+    
+    def register_or_get_user(self, unique_id: str, name: Optional[str] = None) -> Dict:
+        """
+        Register a new user or get existing user by unique_id
+        If name is not provided, generates a random one
+        
+        Args:
+            unique_id: Browser-generated unique identifier
+            name: Optional user's display name (generates random if not provided)
+            
+        Returns:
+            User dictionary
+        """
+        # Generate random name if not provided
+        if not name:
+            name = f"User_{uuid.uuid4().hex[:8]}"
+        
+        # Check if user exists
+        existing_user = self.get_user_by_unique_id(unique_id)
+        if existing_user:
+            return existing_user
+        
+        # Create new user
+        return self.create_user(unique_id, name)
+
+
+# Initialize singleton instance
+user_service = UserService()
+