Upload 70 files

Dockerfile

@@ -0,0 +1,70 @@
+# =============================================================================
+# VoiceAuth API Dockerfile
+# =============================================================================
+# Multi-stage build for optimized production image
+
+# -----------------------------------------------------------------------------
+# Stage 1: Builder
+# -----------------------------------------------------------------------------
+FROM python:3.11-slim AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install Python dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# -----------------------------------------------------------------------------
+# Stage 2: Production
+# -----------------------------------------------------------------------------
+FROM python:3.11-slim AS production
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    libsndfile1 \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user
+RUN useradd --create-home --uid 1000 appuser
+
+# Copy virtual environment from builder
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Set working directory
+WORKDIR /app
+
+# Copy application code
+COPY --chown=appuser:appuser . .
+
+# Create directories for models and logs
+RUN mkdir -p /app/models /app/logs && \
+    chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PORT=7860
+
+# Expose port
+EXPOSE 7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/api/health || exit 1
+
+# Run application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

app/__init__.py

@@ -0,0 +1,4 @@
+"""VoiceAuth - AI Voice Detection API."""
+
+__version__ = "1.0.0"
+__author__ = "VoiceAuth Team"

app/api/__init__.py

@@ -0,0 +1,9 @@
+"""API package."""
+
+from app.api.routes import health
+from app.api.routes import voice_detection
+
+__all__ = [
+    "health",
+    "voice_detection",
+]

app/api/dependencies.py

@@ -0,0 +1,143 @@
+"""
+FastAPI dependency injection.
+
+Provides dependencies for route handlers.
+"""
+
+from typing import Annotated
+
+from fastapi import Depends
+from fastapi import Header
+from fastapi import HTTPException
+from fastapi import Request
+from fastapi import status
+
+from app.config import Settings
+from app.config import get_settings
+from app.ml.model_loader import ModelLoader
+from app.services.voice_detector import VoiceDetector
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_model_loader(request: Request) -> ModelLoader:
+    """
+    Get ModelLoader from app state.
+
+    Args:
+        request: FastAPI request object
+
+    Returns:
+        ModelLoader instance from app state
+    """
+    if hasattr(request.app.state, "model_loader"):
+        return request.app.state.model_loader
+    return ModelLoader()
+
+
+def get_voice_detector(
+    model_loader: Annotated[ModelLoader, Depends(get_model_loader)],
+) -> VoiceDetector:
+    """
+    Get VoiceDetector instance.
+
+    Args:
+        model_loader: ModelLoader from dependency
+
+    Returns:
+        Configured VoiceDetector instance
+    """
+    return VoiceDetector(model_loader=model_loader)
+
+
+async def validate_api_key(
+    x_api_key: Annotated[
+        str | None,
+        Header(
+            alias="x-api-key",
+            description="API key for authentication",
+        ),
+    ] = None,
+    settings: Annotated[Settings, Depends(get_settings)] = None,  # type: ignore
+) -> str:
+    """
+    Validate API key from request header.
+
+    Args:
+        x_api_key: API key from x-api-key header
+        settings: Application settings
+
+    Returns:
+        Validated API key
+
+    Raises:
+        HTTPException: 401 if API key is missing or invalid
+    """
+    if settings is None:
+        settings = get_settings()
+
+    if not x_api_key:
+        logger.warning("Request without API key")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="API key is required. Provide it in the x-api-key header.",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+
+    # Get valid API keys
+    valid_keys = settings.api_keys_list
+
+    if not valid_keys:
+        logger.error("No API keys configured on server")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Server configuration error",
+        )
+
+    # Constant-time comparison to prevent timing attacks
+    key_valid = False
+    for valid_key in valid_keys:
+        if _constant_time_compare(x_api_key, valid_key):
+            key_valid = True
+            break
+
+    if not key_valid:
+        logger.warning(
+            "Invalid API key attempt",
+            key_prefix=x_api_key[:8] + "..." if len(x_api_key) > 8 else "***",
+        )
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid API key",
+            headers={"WWW-Authenticate": "ApiKey"},
+        )
+
+    return x_api_key
+
+
+def _constant_time_compare(val1: str, val2: str) -> bool:
+    """
+    Constant-time string comparison to prevent timing attacks.
+
+    Args:
+        val1: First string
+        val2: Second string
+
+    Returns:
+        True if strings are equal
+    """
+    if len(val1) != len(val2):
+        return False
+
+    result = 0
+    for x, y in zip(val1, val2):
+        result |= ord(x) ^ ord(y)
+
+    return result == 0
+
+
+# Type aliases for cleaner route signatures
+ValidatedApiKey = Annotated[str, Depends(validate_api_key)]
+VoiceDetectorDep = Annotated[VoiceDetector, Depends(get_voice_detector)]
+SettingsDep = Annotated[Settings, Depends(get_settings)]

app/api/middleware/__init__.py

@@ -0,0 +1,13 @@
+"""Middleware package."""
+
+from app.api.middleware.auth import APIKeyMiddleware
+from app.api.middleware.error_handler import setup_exception_handlers
+from app.api.middleware.rate_limiter import get_limiter
+from app.api.middleware.rate_limiter import limiter
+
+__all__ = [
+    "APIKeyMiddleware",
+    "setup_exception_handlers",
+    "limiter",
+    "get_limiter",
+]

app/api/middleware/auth.py

@@ -0,0 +1,107 @@
+"""
+API Key authentication middleware.
+
+Provides middleware for API key validation.
+"""
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from app.config import get_settings
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class APIKeyMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware for API key authentication.
+
+    This middleware checks for valid API keys on protected endpoints.
+    Public endpoints (health, docs) are excluded from authentication.
+    """
+
+    # Endpoints that don't require authentication
+    PUBLIC_PATHS: set[str] = {
+        "/api/health",
+        "/api/ready",
+        "/api/languages",
+        "/api/",
+        "/docs",
+        "/redoc",
+        "/openapi.json",
+        "/",
+    }
+
+    async def dispatch(self, request: Request, call_next):
+        """
+        Process request and validate API key for protected endpoints.
+
+        Args:
+            request: Incoming request
+            call_next: Next middleware/handler
+
+        Returns:
+            Response from next handler or 401 error
+        """
+        # Skip authentication for public paths
+        path = request.url.path.rstrip("/") or "/"
+
+        # Check if path is public
+        is_public = path in self.PUBLIC_PATHS or any(
+            path.startswith(public.rstrip("/")) for public in self.PUBLIC_PATHS if public != "/"
+        )
+
+        if is_public:
+            return await call_next(request)
+
+        # Get API key from header
+        api_key = request.headers.get("x-api-key")
+
+        if not api_key:
+            logger.warning(
+                "Request without API key",
+                path=path,
+                method=request.method,
+            )
+            return JSONResponse(
+                status_code=401,
+                content={
+                    "status": "error",
+                    "message": "API key is required",
+                },
+                headers={"WWW-Authenticate": "ApiKey"},
+            )
+
+        # Validate API key
+        settings = get_settings()
+        valid_keys = settings.api_keys_list
+
+        if not valid_keys:
+            logger.error("No API keys configured")
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "status": "error",
+                    "message": "Server configuration error",
+                },
+            )
+
+        if api_key not in valid_keys:
+            logger.warning(
+                "Invalid API key",
+                path=path,
+                key_prefix=api_key[:8] + "..." if len(api_key) > 8 else "***",
+            )
+            return JSONResponse(
+                status_code=401,
+                content={
+                    "status": "error",
+                    "message": "Invalid API key",
+                },
+                headers={"WWW-Authenticate": "ApiKey"},
+            )
+
+        # Continue to next handler
+        return await call_next(request)

app/api/middleware/error_handler.py

@@ -0,0 +1,130 @@
+"""
+Global error handling for FastAPI application.
+
+Provides exception handlers for consistent error responses.
+"""
+
+from fastapi import FastAPI
+from fastapi import HTTPException
+from fastapi import Request
+from fastapi.exceptions import RequestValidationError
+from starlette.responses import JSONResponse
+
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+async def validation_exception_handler(
+    request: Request,
+    exc: RequestValidationError,
+) -> JSONResponse:
+    """
+    Handle Pydantic validation errors.
+
+    Formats validation errors into a consistent response format.
+
+    Args:
+        request: Incoming request
+        exc: Validation exception
+
+    Returns:
+        JSON response with error details
+    """
+    errors = exc.errors()
+
+    # Format error messages
+    error_messages = []
+    for error in errors:
+        loc = " -> ".join(str(x) for x in error.get("loc", []))
+        msg = error.get("msg", "Validation error")
+        error_messages.append(f"{loc}: {msg}")
+
+    logger.warning(
+        "Validation error",
+        path=request.url.path,
+        errors=error_messages,
+    )
+
+    return JSONResponse(
+        status_code=422,
+        content={
+            "status": "error",
+            "message": "Validation error",
+            "details": {
+                "errors": error_messages,
+            },
+        },
+    )
+
+
+async def http_exception_handler(
+    request: Request,
+    exc: HTTPException,
+) -> JSONResponse:
+    """
+    Handle HTTP exceptions.
+
+    Formats HTTP exceptions into a consistent response format.
+
+    Args:
+        request: Incoming request
+        exc: HTTP exception
+
+    Returns:
+        JSON response with error details
+    """
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "status": "error",
+            "message": exc.detail,
+        },
+        headers=exc.headers,
+    )
+
+
+async def general_exception_handler(
+    request: Request,
+    exc: Exception,
+) -> JSONResponse:
+    """
+    Handle unexpected exceptions.
+
+    Logs the exception and returns a generic error response.
+
+    Args:
+        request: Incoming request
+        exc: Unexpected exception
+
+    Returns:
+        JSON response with generic error message
+    """
+    logger.exception(
+        "Unhandled exception",
+        path=request.url.path,
+        method=request.method,
+        error=str(exc),
+    )
+
+    return JSONResponse(
+        status_code=500,
+        content={
+            "status": "error",
+            "message": "Internal server error",
+        },
+    )
+
+
+def setup_exception_handlers(app: FastAPI) -> None:
+    """
+    Register all exception handlers with the FastAPI app.
+
+    Args:
+        app: FastAPI application instance
+    """
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(Exception, general_exception_handler)
+
+    logger.debug("Exception handlers registered")

app/api/middleware/rate_limiter.py

@@ -0,0 +1,90 @@
+"""
+Rate limiting middleware using SlowAPI.
+
+Provides request rate limiting per API key.
+"""
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from starlette.requests import Request
+
+from app.config import get_settings
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_api_key_or_ip(request: Request) -> str:
+    """
+    Extract rate limit key from request.
+
+    Uses API key if present, otherwise falls back to IP address.
+
+    Args:
+        request: Incoming request
+
+    Returns:
+        Rate limit key (API key or IP)
+    """
+    api_key = request.headers.get("x-api-key")
+
+    if api_key:
+        # Use API key for per-key rate limiting
+        return f"key:{api_key}"
+
+    # Fall back to IP address
+    return f"ip:{get_remote_address(request)}"
+
+
+def get_limiter() -> Limiter:
+    """
+    Create and configure rate limiter.
+
+    Returns:
+        Configured Limiter instance
+    """
+    settings = get_settings()
+
+    # Build default limit string
+    default_limit = f"{settings.RATE_LIMIT_REQUESTS}/minute"
+
+    return Limiter(
+        key_func=get_api_key_or_ip,
+        default_limits=[default_limit],
+        # Note: Redis storage will be configured in main.py if available
+    )
+
+
+# Global limiter instance
+limiter = get_limiter()
+
+
+def rate_limit_exceeded_handler(request: Request, exc: Exception):
+    """
+    Handle rate limit exceeded errors.
+
+    Args:
+        request: Request that exceeded the limit
+        exc: Rate limit exception
+
+    Returns:
+        JSON response with 429 status
+    """
+    from starlette.responses import JSONResponse
+
+    logger.warning(
+        "Rate limit exceeded",
+        path=request.url.path,
+        client=get_api_key_or_ip(request),
+    )
+
+    return JSONResponse(
+        status_code=429,
+        content={
+            "status": "error",
+            "message": "Rate limit exceeded. Please try again later.",
+        },
+        headers={
+            "Retry-After": "60",
+        },
+    )

app/api/routes/__init__.py

@@ -0,0 +1,9 @@
+"""Routes package."""
+
+from app.api.routes import health
+from app.api.routes import voice_detection
+
+__all__ = [
+    "health",
+    "voice_detection",
+]

app/api/routes/federated.py

@@ -0,0 +1,100 @@
+"""
+Federated Learning API endpoints.
+
+Provides endpoints for FL operations:
+- Client registration
+- Contribution submission
+- Federation status
+"""
+
+from fastapi import APIRouter
+from fastapi import HTTPException
+from fastapi import status
+from pydantic import BaseModel
+from pydantic import Field
+
+from app.api.dependencies import ValidatedApiKey
+from app.services.federated_learning import fl_manager
+
+router = APIRouter()
+
+
+class ClientRegistrationRequest(BaseModel):
+    """Request to register as FL client."""
+    
+    client_id: str = Field(..., min_length=3, max_length=64)
+    organization: str | None = Field(None, max_length=128)
+
+
+class ContributionRequest(BaseModel):
+    """Request to submit a training contribution."""
+    
+    client_id: str = Field(..., min_length=3, max_length=64)
+    gradient_hash: str = Field(..., min_length=16, max_length=128)
+    samples_trained: int = Field(..., ge=1, le=100000)
+    local_accuracy: float = Field(..., ge=0.0, le=1.0)
+
+
+@router.post(
+    "/federated/register",
+    summary="Register as Federated Client",
+    description="Register as a federated learning participant.",
+)
+async def register_client(
+    request: ClientRegistrationRequest,
+    api_key: ValidatedApiKey,
+) -> dict:
+    """Register a new federated learning client."""
+    client = fl_manager.register_client(
+        client_id=request.client_id,
+        organization=request.organization,
+    )
+    
+    return {
+        "status": "registered",
+        "client_id": client.client_id,
+        "organization": client.organization,
+        "registered_at": client.registered_at,
+    }
+
+
+@router.post(
+    "/federated/contribute",
+    summary="Submit Training Contribution",
+    description="Submit model gradients from local training.",
+)
+async def submit_contribution(
+    request: ContributionRequest,
+    api_key: ValidatedApiKey,
+) -> dict:
+    """Submit a training contribution."""
+    result = fl_manager.submit_contribution(
+        client_id=request.client_id,
+        gradient_hash=request.gradient_hash,
+        samples_trained=request.samples_trained,
+        local_accuracy=request.local_accuracy,
+    )
+    
+    return result
+
+
+@router.get(
+    "/federated/status",
+    summary="Federation Status",
+    description="Get current federated learning status.",
+)
+async def federation_status() -> dict:
+    """Get federation status."""
+    return fl_manager.get_federation_status()
+
+
+@router.post(
+    "/federated/aggregate",
+    summary="Trigger Aggregation",
+    description="Trigger federated model aggregation (admin only).",
+)
+async def trigger_aggregation(
+    api_key: ValidatedApiKey,
+) -> dict:
+    """Trigger model aggregation."""
+    return fl_manager.simulate_aggregation()

app/api/routes/health.py

@@ -0,0 +1,101 @@
+"""
+Health check endpoints.
+
+Provides health, readiness, and information endpoints.
+"""
+
+from fastapi import APIRouter
+
+from app.api.dependencies import VoiceDetectorDep
+from app.models.enums import SupportedLanguage
+from app.models.response import HealthResponse
+from app.models.response import LanguagesResponse
+
+router = APIRouter()
+
+
+@router.get(
+    "/health",
+    response_model=HealthResponse,
+    summary="Health Check",
+    description="Check the health status of the API and ML model.",
+)
+async def health_check(
+    voice_detector: VoiceDetectorDep,
+) -> HealthResponse:
+    """
+    Get health status of the API.
+
+    Returns model loading status, device info, and supported languages.
+    """
+    health = voice_detector.health_check()
+
+    return HealthResponse(
+        status=health["status"],
+        version=health["version"],
+        model_loaded=health["model_loaded"],
+        model_name=health.get("model_name"),
+        device=health.get("device"),
+        supported_languages=health["supported_languages"],
+    )
+
+
+@router.get(
+    "/ready",
+    summary="Readiness Check",
+    description="Check if the API is ready to accept requests.",
+)
+async def readiness_check(
+    voice_detector: VoiceDetectorDep,
+) -> dict:
+    """
+    Check if API is ready to accept requests.
+
+    Returns ready status based on model availability.
+    """
+    health = voice_detector.health_check()
+
+    if health["model_loaded"]:
+        return {"status": "ready", "message": "API is ready to accept requests"}
+    else:
+        return {"status": "not_ready", "message": "Model is still loading"}
+
+
+@router.get(
+    "/languages",
+    response_model=LanguagesResponse,
+    summary="Supported Languages",
+    description="Get the list of supported languages for voice detection.",
+)
+async def supported_languages() -> LanguagesResponse:
+    """
+    Get list of supported languages.
+
+    Returns all languages supported by the voice detection API.
+    """
+    languages = SupportedLanguage.values()
+
+    return LanguagesResponse(
+        languages=languages,
+        count=len(languages),
+    )
+
+
+@router.get(
+    "/",
+    summary="API Info",
+    description="Get basic API information.",
+)
+async def api_info() -> dict:
+    """
+    Get basic API information.
+
+    Returns API name, version, and documentation links.
+    """
+    return {
+        "name": "VoiceAuth API",
+        "description": "AI-Generated Voice Detection API",
+        "version": "1.0.0",
+        "documentation": "/docs",
+        "supported_languages": SupportedLanguage.values(),
+    }

app/api/routes/voice_detection.py

@@ -0,0 +1,150 @@
+"""
+Voice detection API endpoint.
+
+Main endpoint for detecting AI-generated vs human voice.
+"""
+
+from fastapi import APIRouter
+from fastapi import HTTPException
+from fastapi import status
+
+from app.api.dependencies import ValidatedApiKey
+from app.api.dependencies import VoiceDetectorDep
+from app.models.request import VoiceDetectionRequest
+from app.models.response import ErrorResponse
+from app.models.response import VoiceDetectionResponse
+from app.utils.exceptions import AudioDecodeError
+from app.utils.exceptions import AudioDurationError
+from app.utils.exceptions import AudioFormatError
+from app.utils.exceptions import AudioProcessingError
+from app.utils.exceptions import InferenceError
+from app.utils.exceptions import ModelNotLoadedError
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter()
+
+
+@router.post(
+    "/voice-detection",
+    response_model=VoiceDetectionResponse,
+    response_model_include={"status", "language", "classification", "confidenceScore", "explanation"},
+    responses={
+        200: {
+            "description": "Successful voice detection",
+            "model": VoiceDetectionResponse,
+        },
+        400: {
+            "description": "Invalid audio data",
+            "model": ErrorResponse,
+        },
+        401: {
+            "description": "Invalid or missing API key",
+            "model": ErrorResponse,
+        },
+        422: {
+            "description": "Validation error",
+            "model": ErrorResponse,
+        },
+        429: {
+            "description": "Rate limit exceeded",
+            "model": ErrorResponse,
+        },
+        500: {
+            "description": "Internal server error",
+            "model": ErrorResponse,
+        },
+        503: {
+            "description": "Model not loaded",
+            "model": ErrorResponse,
+        },
+    },
+    summary="Detect AI-Generated Voice",
+    description="""
+Analyze a voice sample to determine if it's AI-generated or spoken by a human.
+
+**Supported Languages:** Tamil, English, Hindi, Malayalam, Telugu
+
+**Input Requirements:**
+- Audio must be Base64-encoded MP3
+- Duration: 0.5s to 30s
+- One audio sample per request
+
+**Response:**
+- Classification: AI_GENERATED or HUMAN
+- Confidence score: 0.0 to 1.0
+- Human-readable explanation
+    """,
+)
+async def detect_voice(
+    request: VoiceDetectionRequest,
+    voice_detector: VoiceDetectorDep,
+    api_key: ValidatedApiKey,
+) -> VoiceDetectionResponse:
+    """
+    Detect whether a voice sample is AI-generated or human.
+
+    Args:
+        request: Voice detection request with audio data
+        voice_detector: VoiceDetector service dependency
+        api_key: Validated API key from header
+
+    Returns:
+        VoiceDetectionResponse with classification result
+    """
+    try:
+        result = await voice_detector.detect(
+            audio_base64=request.audioBase64,
+            language=request.language,
+        )
+        return result
+
+    except AudioDecodeError as e:
+        logger.warning("Audio decode error", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Failed to decode audio: {e.message}",
+        ) from e
+
+    except AudioFormatError as e:
+        logger.warning("Audio format error", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid audio format: {e.message}",
+        ) from e
+
+    except AudioDurationError as e:
+        logger.warning("Audio duration error", error=str(e), details=e.details)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=e.message,
+        ) from e
+
+    except AudioProcessingError as e:
+        logger.error("Audio processing error", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Audio processing failed: {e.message}",
+        ) from e
+
+    except ModelNotLoadedError as e:
+        logger.error("Model not loaded", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Voice detection model is not available. Please try again later.",
+        ) from e
+
+    except InferenceError as e:
+        logger.error("Inference error", error=str(e))
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Voice analysis failed. Please try again.",
+        ) from e
+
+    except Exception as e:
+        logger.exception("Unexpected error in voice detection")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Internal server error",
+        ) from e

app/config.py

@@ -0,0 +1,124 @@
+"""
+Application configuration using Pydantic Settings.
+
+Loads configuration from environment variables and .env file.
+"""
+
+from functools import lru_cache
+from typing import Literal
+
+import torch
+from pydantic import Field
+from pydantic import field_validator
+from pydantic_settings import BaseSettings
+from pydantic_settings import SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # -------------------------------------------------------------------------
+    # Application Settings
+    # -------------------------------------------------------------------------
+    APP_NAME: str = "VoiceAuth API"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = False
+    HOST: str = "0.0.0.0"
+    PORT: int = 8000
+
+    # -------------------------------------------------------------------------
+    # Security Settings
+    # -------------------------------------------------------------------------
+    API_KEYS: str = Field(
+        default="",
+        description="Comma-separated list of valid API keys",
+    )
+    CORS_ORIGINS: str = Field(
+        default="http://localhost:3000,http://localhost:8000",
+        description="Comma-separated list of allowed CORS origins",
+    )
+    RATE_LIMIT_REQUESTS: int = Field(default=100, ge=1)
+    RATE_LIMIT_PERIOD: int = Field(default=60, ge=1, description="Period in seconds")
+
+    # -------------------------------------------------------------------------
+    # ML Model Settings
+    # -------------------------------------------------------------------------
+    MODEL_NAME: str = "facebook/wav2vec2-base"
+    MODEL_PATH: str = ""
+    DEVICE: str = "auto"
+    MAX_AUDIO_DURATION: float = Field(default=30.0, ge=1.0)
+    MIN_AUDIO_DURATION: float = Field(default=0.5, ge=0.1)
+    SAMPLE_RATE: int = Field(default=16000, ge=8000, le=48000)
+
+    # -------------------------------------------------------------------------
+    # Redis Settings
+    # -------------------------------------------------------------------------
+    REDIS_URL: str = "redis://localhost:6379"
+    REDIS_DB: int = 0
+
+    # -------------------------------------------------------------------------
+    # Logging Settings
+    # -------------------------------------------------------------------------
+    LOG_LEVEL: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+    LOG_FORMAT: Literal["json", "console"] = "json"
+
+    # -------------------------------------------------------------------------
+    # Computed Properties
+    # -------------------------------------------------------------------------
+    @property
+    def api_keys_list(self) -> list[str]:
+        """Parse comma-separated API keys into a list."""
+        if not self.API_KEYS:
+            return []
+        return [key.strip() for key in self.API_KEYS.split(",") if key.strip()]
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        """Parse comma-separated CORS origins into a list."""
+        if not self.CORS_ORIGINS:
+            return []
+        return [origin.strip() for origin in self.CORS_ORIGINS.split(",") if origin.strip()]
+
+    @property
+    def torch_device(self) -> str:
+        """Determine the appropriate torch device."""
+        if self.DEVICE == "auto":
+            return "cuda" if torch.cuda.is_available() else "cpu"
+        return self.DEVICE
+
+    @property
+    def model_identifier(self) -> str:
+        """Get the model path or name to load."""
+        return self.MODEL_PATH if self.MODEL_PATH else self.MODEL_NAME
+
+    # -------------------------------------------------------------------------
+    # Validators
+    # -------------------------------------------------------------------------
+    @field_validator("DEVICE")
+    @classmethod
+    def validate_device(cls, v: str) -> str:
+        """Validate device configuration."""
+        valid_devices = {"auto", "cpu", "cuda", "mps"}
+        # Allow cuda:N format
+        if v.startswith("cuda:"):
+            return v
+        if v not in valid_devices:
+            raise ValueError(f"Device must be one of {valid_devices} or 'cuda:N' format")
+        return v
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """
+    Get cached settings instance.
+
+    Uses lru_cache to ensure settings are only loaded once.
+    """
+    return Settings()

app/main.py

@@ -0,0 +1,182 @@
+"""
+VoiceAuth API - Main Application Entry Point.
+
+FastAPI application for AI-generated voice detection.
+"""
+
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from slowapi import _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+
+from app.api.middleware.error_handler import setup_exception_handlers
+from app.api.middleware.rate_limiter import limiter
+from app.api.routes import health
+from app.api.routes import voice_detection
+from app.config import get_settings
+from app.ml.model_loader import ModelLoader
+from app.utils.logger import get_logger
+from app.utils.logger import setup_logging
+
+# Initialize logging first
+setup_logging()
+logger = get_logger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifespan manager.
+
+    Handles startup and shutdown events:
+    - Startup: Load ML model, run warmup
+    - Shutdown: Unload model, cleanup
+    """
+    # =========================================================================
+    # STARTUP
+    # =========================================================================
+    logger.info("Starting VoiceAuth API...")
+
+    # Initialize model loader
+    model_loader = ModelLoader()
+    app.state.model_loader = model_loader
+
+    # Load ML model
+    logger.info("Loading ML model...")
+    try:
+        await model_loader.load_model_async()
+        logger.info("ML model loaded successfully")
+
+        # Run warmup inference
+        logger.info("Running model warmup...")
+        model_loader.warmup()
+        logger.info("Model warmup complete")
+
+    except Exception as e:
+        logger.error("Failed to load ML model", error=str(e))
+        # Continue without model for health checks
+        # Actual detection will fail with proper error
+
+    logger.info("VoiceAuth API is ready!")
+
+    yield
+
+    # =========================================================================
+    # SHUTDOWN
+    # =========================================================================
+    logger.info("Shutting down VoiceAuth API...")
+
+    # Unload model
+    if hasattr(app.state, "model_loader"):
+        app.state.model_loader.unload_model()
+
+    logger.info("Shutdown complete")
+
+
+def create_app() -> FastAPI:
+    """
+    Create and configure the FastAPI application.
+
+    Returns:
+        Configured FastAPI application
+    """
+    settings = get_settings()
+
+    # Create FastAPI app
+    app = FastAPI(
+        title=settings.APP_NAME,
+        version=settings.APP_VERSION,
+        description="""
+# VoiceAuth - AI Voice Detection API
+
+Detect whether a voice sample is **AI-generated** or **human-spoken** across 5 languages.
+
+## Supported Languages
+- Tamil
+- English
+- Hindi
+- Malayalam
+- Telugu
+
+## Authentication
+All detection requests require an API key in the `x-api-key` header.
+
+## Rate Limiting
+Default: 100 requests per minute per API key.
+        """,
+        lifespan=lifespan,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/openapi.json",
+    )
+
+    # =========================================================================
+    # MIDDLEWARE
+    # =========================================================================
+
+    # CORS
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins_list or ["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Rate limiting
+    app.state.limiter = limiter
+    app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+    # =========================================================================
+    # EXCEPTION HANDLERS
+    # =========================================================================
+    setup_exception_handlers(app)
+
+    # =========================================================================
+    # ROUTES
+    # =========================================================================
+    app.include_router(
+        health.router,
+        prefix="/api",
+        tags=["Health"],
+    )
+    app.include_router(
+        voice_detection.router,
+        prefix="/api",
+        tags=["Voice Detection"],
+    )
+    
+    # Federated Learning routes (Phase 2)
+    from app.api.routes import federated
+    app.include_router(
+        federated.router,
+        prefix="/api",
+        tags=["Federated Learning"],
+    )
+
+    return app
+
+
+# Create application instance
+app = create_app()
+
+
+def main() -> None:
+    """Run the application using uvicorn."""
+    import uvicorn
+
+    settings = get_settings()
+
+    uvicorn.run(
+        "app.main:app",
+        host=settings.HOST,
+        port=settings.PORT,
+        reload=settings.DEBUG,
+        log_level=settings.LOG_LEVEL.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

app/ml/__init__.py

@@ -0,0 +1,11 @@
+"""Machine Learning pipeline package."""
+
+from app.ml.inference import InferenceEngine
+from app.ml.model_loader import ModelLoader
+from app.ml.preprocessing import AudioPreprocessor
+
+__all__ = [
+    "ModelLoader",
+    "InferenceEngine",
+    "AudioPreprocessor",
+]

app/ml/inference.py

@@ -0,0 +1,235 @@
+"""
+Inference engine for voice classification.
+
+Handles model inference and result processing.
+"""
+
+import time
+from typing import TYPE_CHECKING
+
+import torch
+import torch.nn.functional as F
+
+from app.models.enums import Classification
+from app.utils.constants import ID_TO_LABEL
+from app.utils.exceptions import InferenceError
+from app.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from transformers import Wav2Vec2ForSequenceClassification
+    from transformers import Wav2Vec2Processor
+
+logger = get_logger(__name__)
+
+
+class InferenceEngine:
+    """
+    Inference engine for Wav2Vec2 voice classification.
+
+    Handles running model inference and converting outputs
+    to classification results.
+    """
+
+    def __init__(
+        self,
+        model: "Wav2Vec2ForSequenceClassification",
+        processor: "Wav2Vec2Processor",
+        device: str = "cpu",
+    ) -> None:
+        """
+        Initialize InferenceEngine.
+
+        Args:
+            model: Loaded Wav2Vec2ForSequenceClassification model
+            processor: Wav2Vec2Processor for preprocessing
+            device: Device to run inference on
+        """
+        self.model = model
+        self.processor = processor
+        self.device = device
+
+    def predict(
+        self,
+        input_tensors: dict[str, torch.Tensor],
+    ) -> tuple[Classification, float]:
+        """
+        Run inference and return classification result.
+
+        Args:
+            input_tensors: Preprocessed input tensors with input_values
+
+        Returns:
+            Tuple of (Classification, confidence_score)
+
+        Raises:
+            InferenceError: If inference fails
+        """
+        try:
+            start_time = time.perf_counter()
+
+            # Ensure model is in eval mode
+            self.model.eval()
+
+            # Run inference without gradient computation
+            with torch.no_grad():
+                outputs = self.model(**input_tensors)
+
+            # Get logits
+            logits = outputs.logits
+
+            # Apply softmax to get probabilities
+            probabilities = F.softmax(logits, dim=-1)
+
+            # Get predicted class and confidence
+            confidence, predicted_class = torch.max(probabilities, dim=-1)
+
+            # Convert to Python types
+            predicted_class_id = predicted_class.item()
+            confidence_score = confidence.item()
+
+            # Get label from model's config or fallback to our mapping
+            if hasattr(self.model.config, 'id2label') and self.model.config.id2label:
+                model_label = self.model.config.id2label.get(predicted_class_id, "HUMAN")
+                # Convert pretrained model labels to standard format
+                model_label_lower = str(model_label).lower()
+                
+                ai_keywords = ["fake", "spoof", "synthetic", "ai", "deepfake", "generated"]
+                is_ai = any(keyword in model_label_lower for keyword in ai_keywords)
+                
+                if is_ai:
+                    label = "AI_GENERATED"
+                else:
+                    label = "HUMAN"
+            else:
+                label = ID_TO_LABEL.get(predicted_class_id, "HUMAN")
+            
+            classification = Classification(label)
+
+            inference_time_ms = (time.perf_counter() - start_time) * 1000
+
+            logger.info(
+                "Inference complete",
+                classification=classification.value,
+                confidence=round(confidence_score, 4),
+                inference_time_ms=round(inference_time_ms, 2),
+            )
+
+            return classification, confidence_score
+
+        except Exception as e:
+            logger.error("Inference failed", error=str(e))
+            raise InferenceError(
+                f"Model inference failed: {e}",
+                details={"error": str(e)},
+            ) from e
+
+    def predict_with_probabilities(
+        self,
+        input_tensors: dict[str, torch.Tensor],
+    ) -> dict:
+        """
+        Run inference and return full probability distribution.
+
+        Args:
+            input_tensors: Preprocessed input tensors
+
+        Returns:
+            Dictionary with classification, confidence, and all probabilities
+        """
+        try:
+            self.model.eval()
+
+            with torch.no_grad():
+                outputs = self.model(**input_tensors)
+
+            logits = outputs.logits
+            probabilities = F.softmax(logits, dim=-1)
+
+            # Get all probabilities
+            probs = probabilities.squeeze().cpu().numpy()
+
+            # Get predicted class
+            confidence, predicted_class = torch.max(probabilities, dim=-1)
+            predicted_class_id = predicted_class.item()
+            label = ID_TO_LABEL.get(predicted_class_id, "HUMAN")
+
+            return {
+                "classification": Classification(label),
+                "confidence": float(confidence.item()),
+                "probabilities": {
+                    "HUMAN": float(probs[0]) if len(probs) > 0 else 0.0,
+                    "AI_GENERATED": float(probs[1]) if len(probs) > 1 else 0.0,
+                },
+            }
+
+        except Exception as e:
+            logger.error("Inference with probabilities failed", error=str(e))
+            raise InferenceError(
+                f"Model inference failed: {e}",
+                details={"error": str(e)},
+            ) from e
+
+    def batch_predict(
+        self,
+        input_tensors: dict[str, torch.Tensor],
+    ) -> list[tuple[Classification, float]]:
+        """
+        Run batch inference.
+
+        Args:
+            input_tensors: Batched preprocessed input tensors
+
+        Returns:
+            List of (Classification, confidence) tuples
+        """
+        try:
+            self.model.eval()
+
+            with torch.no_grad():
+                outputs = self.model(**input_tensors)
+
+            logits = outputs.logits
+            probabilities = F.softmax(logits, dim=-1)
+
+            results = []
+            for i in range(probabilities.shape[0]):
+                confidence, predicted_class = torch.max(probabilities[i], dim=-1)
+                predicted_class_id = predicted_class.item()
+                label = ID_TO_LABEL.get(predicted_class_id, "HUMAN")
+                results.append((Classification(label), float(confidence.item())))
+
+            return results
+
+        except Exception as e:
+            logger.error("Batch inference failed", error=str(e))
+            raise InferenceError(
+                f"Batch inference failed: {e}",
+                details={"error": str(e)},
+            ) from e
+
+    def get_hidden_states(
+        self,
+        input_tensors: dict[str, torch.Tensor],
+    ) -> torch.Tensor:
+        """
+        Extract hidden states for explainability.
+
+        Args:
+            input_tensors: Preprocessed input tensors
+
+        Returns:
+            Hidden state tensor from last layer
+        """
+        self.model.eval()
+
+        with torch.no_grad():
+            outputs = self.model(
+                **input_tensors,
+                output_hidden_states=True,
+            )
+
+        # Return last hidden state
+        if hasattr(outputs, "hidden_states") and outputs.hidden_states:
+            return outputs.hidden_states[-1]
+
+        return torch.tensor([])

app/ml/model_loader.py

@@ -0,0 +1,246 @@
+"""
+Model loader for Wav2Vec2 voice classification model.
+
+Handles loading, caching, and management of the ML model.
+"""
+
+import gc
+import threading
+from typing import TYPE_CHECKING
+
+import torch
+from transformers import Wav2Vec2ForSequenceClassification
+from transformers import Wav2Vec2Processor
+
+from app.config import get_settings
+from app.utils.constants import ID_TO_LABEL
+from app.utils.constants import LABEL_TO_ID
+from app.utils.exceptions import ModelNotLoadedError
+from app.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from transformers import PreTrainedModel
+
+logger = get_logger(__name__)
+
+
+class ModelLoader:
+    """
+    Singleton model loader for Wav2Vec2 classification model.
+
+    Handles lazy loading, caching, and memory management of the ML model.
+    Thread-safe for production use.
+    """
+
+    _instance: "ModelLoader | None" = None
+    _lock: threading.Lock = threading.Lock()
+
+    def __new__(cls) -> "ModelLoader":
+        """Ensure only one instance exists (Singleton pattern)."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize ModelLoader if not already initialized."""
+        if getattr(self, "_initialized", False):
+            return
+
+        self.settings = get_settings()
+        self.model: Wav2Vec2ForSequenceClassification | None = None
+        self.processor: Wav2Vec2Processor | None = None
+        self.device: str = self.settings.torch_device
+        self._model_lock = threading.Lock()
+        self._initialized = True
+
+        logger.info(
+            "ModelLoader initialized",
+            device=self.device,
+            model_identifier=self.settings.model_identifier,
+        )
+
+    @property
+    def is_loaded(self) -> bool:
+        """Check if model is loaded and ready for inference."""
+        return self.model is not None and self.processor is not None
+
+    def load_model(self) -> None:
+        """
+        Load the Wav2Vec2 model and processor.
+
+        Thread-safe loading with proper error handling.
+
+        Raises:
+            Exception: If model loading fails
+        """
+        with self._model_lock:
+            if self.is_loaded:
+                logger.debug("Model already loaded, skipping")
+                return
+
+            model_identifier = self.settings.model_identifier
+
+            logger.info("Loading Wav2Vec2 model", model=model_identifier, device=self.device)
+
+            try:
+                # Load processor - try model first, fallback to base wav2vec2
+                try:
+                    self.processor = Wav2Vec2Processor.from_pretrained(
+                        model_identifier,
+                        trust_remote_code=False,
+                    )
+                except Exception:
+                    # Fine-tuned models often don't have processor, use base
+                    logger.info("Using base wav2vec2 processor")
+                    self.processor = Wav2Vec2Processor.from_pretrained(
+                        "facebook/wav2vec2-base",
+                        trust_remote_code=False,
+                    )
+
+                # Load model with classification head
+                # For pretrained deepfake models, use their existing configuration
+                self.model = Wav2Vec2ForSequenceClassification.from_pretrained(
+                    model_identifier,
+                    trust_remote_code=False,
+                    ignore_mismatched_sizes=True,  # Allow different classifier sizes
+                )
+
+                # Move model to device
+                self.model = self.model.to(self.device)
+
+                # Set to evaluation mode
+                self.model.eval()
+
+                # Log memory usage
+                if self.device.startswith("cuda"):
+                    memory_allocated = torch.cuda.memory_allocated() / (1024**3)
+                    logger.info(
+                        "Model loaded successfully",
+                        device=self.device,
+                        gpu_memory_gb=round(memory_allocated, 2),
+                    )
+                else:
+                    logger.info("Model loaded successfully", device=self.device)
+
+            except Exception as e:
+                self.model = None
+                self.processor = None
+                logger.error("Failed to load model", error=str(e))
+                raise
+
+    async def load_model_async(self) -> None:
+        """
+        Async wrapper for model loading.
+
+        Useful for FastAPI lifespan context.
+        """
+        # Run in thread pool to avoid blocking
+        import asyncio
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, self.load_model)
+
+    def get_model(self) -> tuple[Wav2Vec2ForSequenceClassification, Wav2Vec2Processor]:
+        """
+        Get the loaded model and processor.
+
+        Returns:
+            Tuple of (model, processor)
+
+        Raises:
+            ModelNotLoadedError: If model is not loaded
+        """
+        if not self.is_loaded:
+            raise ModelNotLoadedError(
+                "Model not loaded. Call load_model() first.",
+                details={"model_identifier": self.settings.model_identifier},
+            )
+
+        return self.model, self.processor  # type: ignore
+
+    def unload_model(self) -> None:
+        """
+        Unload model and free memory.
+
+        Useful for memory management in constrained environments.
+        """
+        with self._model_lock:
+            if self.model is not None:
+                del self.model
+                self.model = None
+
+            if self.processor is not None:
+                del self.processor
+                self.processor = None
+
+            # Force garbage collection
+            gc.collect()
+
+            # Clear CUDA cache if using GPU
+            if torch.cuda.is_available():
+                torch.cuda.empty_cache()
+
+            logger.info("Model unloaded, memory freed")
+
+    def warmup(self) -> None:
+        """
+        Run a warmup inference to initialize CUDA kernels.
+
+        This reduces latency on the first real inference.
+        """
+        if not self.is_loaded:
+            logger.warning("Cannot warmup - model not loaded")
+            return
+
+        logger.info("Running model warmup...")
+
+        try:
+            # Create dummy input
+            dummy_audio = torch.randn(1, 16000)  # 1 second of audio
+
+            model, processor = self.get_model()
+
+            # Preprocess dummy audio
+            inputs = processor(
+                dummy_audio.squeeze().numpy(),
+                sampling_rate=16000,
+                return_tensors="pt",
+                padding=True,
+            )
+
+            inputs = {k: v.to(self.device) for k, v in inputs.items()}
+
+            # Run warmup inference
+            with torch.no_grad():
+                _ = model(**inputs)
+
+            logger.info("Model warmup complete")
+
+        except Exception as e:
+            logger.warning("Warmup failed (non-critical)", error=str(e))
+
+    def health_check(self) -> dict:
+        """
+        Get model health status.
+
+        Returns:
+            Dictionary with health information
+        """
+        status = {
+            "model_loaded": self.is_loaded,
+            "device": self.device,
+            "model_identifier": self.settings.model_identifier,
+        }
+
+        if self.device.startswith("cuda") and torch.cuda.is_available():
+            status["gpu_memory_allocated_gb"] = round(
+                torch.cuda.memory_allocated() / (1024**3), 2
+            )
+            status["gpu_memory_reserved_gb"] = round(
+                torch.cuda.memory_reserved() / (1024**3), 2
+            )
+
+        return status

app/ml/preprocessing.py

@@ -0,0 +1,155 @@
+"""
+Audio preprocessing for Wav2Vec2 model.
+
+Handles conversion from audio arrays to model input tensors.
+"""
+
+import numpy as np
+import torch
+from transformers import Wav2Vec2Processor
+
+from app.utils.constants import TARGET_SAMPLE_RATE
+from app.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class AudioPreprocessor:
+    """
+    Preprocessor for preparing audio data for Wav2Vec2 model.
+
+    Converts numpy audio arrays into the tensor format expected
+    by the Wav2Vec2ForSequenceClassification model.
+    """
+
+    def __init__(
+        self,
+        processor: Wav2Vec2Processor,
+        device: str = "cpu",
+    ) -> None:
+        """
+        Initialize AudioPreprocessor.
+
+        Args:
+            processor: Wav2Vec2Processor instance
+            device: Target device for tensors (cpu/cuda)
+        """
+        self.processor = processor
+        self.device = device
+        self.sample_rate = TARGET_SAMPLE_RATE
+
+    def validate_input(self, audio_array: np.ndarray) -> bool:
+        """
+        Validate audio array for processing.
+
+        Args:
+            audio_array: Input audio array
+
+        Returns:
+            True if valid
+
+        Raises:
+            ValueError: If validation fails
+        """
+        if not isinstance(audio_array, np.ndarray):
+            raise ValueError(f"Expected numpy array, got {type(audio_array)}")
+
+        if audio_array.ndim != 1:
+            raise ValueError(f"Expected 1D array, got {audio_array.ndim}D")
+
+        if len(audio_array) == 0:
+            raise ValueError("Audio array is empty")
+
+        if np.isnan(audio_array).any():
+            raise ValueError("Audio array contains NaN values")
+
+        if np.isinf(audio_array).any():
+            raise ValueError("Audio array contains infinite values")
+
+        return True
+
+    def preprocess(
+        self,
+        audio_array: np.ndarray,
+        return_attention_mask: bool = True,
+    ) -> dict[str, torch.Tensor]:
+        """
+        Preprocess audio array for model inference.
+
+        Args:
+            audio_array: 1D numpy array of audio samples (16kHz, normalized)
+            return_attention_mask: Whether to return attention mask
+
+        Returns:
+            Dictionary with input_values and optionally attention_mask
+        """
+        # Validate input
+        self.validate_input(audio_array)
+
+        # Ensure float32
+        audio_array = audio_array.astype(np.float32)
+
+        # Process through Wav2Vec2Processor
+        inputs = self.processor(
+            audio_array,
+            sampling_rate=self.sample_rate,
+            return_tensors="pt",
+            padding=True,
+            return_attention_mask=return_attention_mask,
+        )
+
+        # Move to target device
+        inputs = {key: value.to(self.device) for key, value in inputs.items()}
+
+        logger.debug(
+            "Audio preprocessed for model",
+            input_length=inputs["input_values"].shape[-1],
+            device=self.device,
+        )
+
+        return inputs
+
+    def preprocess_batch(
+        self,
+        audio_arrays: list[np.ndarray],
+        return_attention_mask: bool = True,
+    ) -> dict[str, torch.Tensor]:
+        """
+        Preprocess a batch of audio arrays.
+
+        Args:
+            audio_arrays: List of 1D numpy arrays
+            return_attention_mask: Whether to return attention mask
+
+        Returns:
+            Dictionary with batched input_values and optionally attention_mask
+        """
+        # Validate all inputs
+        for i, audio in enumerate(audio_arrays):
+            try:
+                self.validate_input(audio)
+            except ValueError as e:
+                raise ValueError(f"Invalid audio at index {i}: {e}") from e
+
+        # Ensure float32
+        audio_arrays = [audio.astype(np.float32) for audio in audio_arrays]
+
+        # Process batch through Wav2Vec2Processor
+        inputs = self.processor(
+            audio_arrays,
+            sampling_rate=self.sample_rate,
+            return_tensors="pt",
+            padding=True,
+            return_attention_mask=return_attention_mask,
+        )
+
+        # Move to target device
+        inputs = {key: value.to(self.device) for key, value in inputs.items()}
+
+        logger.debug(
+            "Batch preprocessed for model",
+            batch_size=len(audio_arrays),
+            device=self.device,
+        )
+
+        return inputs

app/models/__init__.py

@@ -0,0 +1,19 @@
+"""Pydantic models package."""
+
+from app.models.enums import AudioFormat
+from app.models.enums import Classification
+from app.models.enums import SupportedLanguage
+from app.models.request import VoiceDetectionRequest
+from app.models.response import ErrorResponse
+from app.models.response import HealthResponse
+from app.models.response import VoiceDetectionResponse
+
+__all__ = [
+    "SupportedLanguage",
+    "Classification",
+    "AudioFormat",
+    "VoiceDetectionRequest",
+    "VoiceDetectionResponse",
+    "ErrorResponse",
+    "HealthResponse",
+]

app/models/enums.py

@@ -0,0 +1,57 @@
+"""
+Enumeration types for VoiceAuth API.
+
+Defines supported languages, classification results, and audio formats.
+"""
+
+from enum import Enum
+
+
+class SupportedLanguage(str, Enum):
+    """
+    Supported languages for voice detection.
+
+    The API supports these 5 Indian languages for AI voice detection.
+    """
+
+    TAMIL = "Tamil"
+    ENGLISH = "English"
+    HINDI = "Hindi"
+    MALAYALAM = "Malayalam"
+    TELUGU = "Telugu"
+
+    @classmethod
+    def values(cls) -> list[str]:
+        """Get all language values as a list."""
+        return [lang.value for lang in cls]
+
+
+class Classification(str, Enum):
+    """
+    Voice classification result.
+
+    Indicates whether the detected voice is AI-generated or human.
+    """
+
+    AI_GENERATED = "AI_GENERATED"
+    HUMAN = "HUMAN"
+
+    @property
+    def is_synthetic(self) -> bool:
+        """Check if classification indicates synthetic voice."""
+        return self == Classification.AI_GENERATED
+
+
+class AudioFormat(str, Enum):
+    """
+    Supported audio input formats.
+
+    Currently only MP3 is supported as per competition requirements.
+    """
+
+    MP3 = "mp3"
+
+    @classmethod
+    def values(cls) -> list[str]:
+        """Get all format values as a list."""
+        return [fmt.value for fmt in cls]

app/models/request.py

@@ -0,0 +1,99 @@
+"""
+Request models for VoiceAuth API.
+
+Defines Pydantic models for API request validation.
+"""
+
+import base64
+import re
+from typing import Annotated
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import field_validator
+
+from app.models.enums import AudioFormat
+from app.models.enums import SupportedLanguage
+
+
+class VoiceDetectionRequest(BaseModel):
+    """
+    Request model for voice detection endpoint.
+
+    Accepts Base64-encoded MP3 audio in one of 5 supported languages.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "language": "Tamil",
+                "audioFormat": "mp3",
+                "audioBase64": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU2LjM2LjEwMAAAAAAA...",
+            }
+        }
+    )
+
+    language: Annotated[
+        SupportedLanguage,
+        Field(
+            description="Language of the audio content. Must be one of: Tamil, English, Hindi, Malayalam, Telugu"
+        ),
+    ]
+
+    audioFormat: Annotated[
+        AudioFormat,
+        Field(
+            default=AudioFormat.MP3,
+            description="Format of the audio file. Currently only 'mp3' is supported",
+        ),
+    ] = AudioFormat.MP3
+
+    audioBase64: Annotated[
+        str,
+        Field(
+            min_length=100,
+            description="Base64-encoded MP3 audio data. Minimum 100 characters for valid audio",
+        ),
+    ]
+
+    @field_validator("audioBase64")
+    @classmethod
+    def validate_base64(cls, v: str) -> str:
+        """
+        Validate that the string is valid Base64.
+
+        Args:
+            v: The base64 string to validate
+
+        Returns:
+            The validated base64 string
+
+        Raises:
+            ValueError: If the string is not valid base64
+        """
+        # Remove any whitespace
+        v = v.strip()
+
+        # Check for valid base64 characters
+        base64_pattern = re.compile(r"^[A-Za-z0-9+/]*={0,2}$")
+        if not base64_pattern.match(v):
+            raise ValueError("Invalid Base64 encoding: contains invalid characters")
+
+        # Try to decode to verify it's valid base64
+        try:
+            # Add padding if needed
+            padding = 4 - len(v) % 4
+            if padding != 4:
+                v += "=" * padding
+
+            decoded = base64.b64decode(v)
+            if len(decoded) < 100:
+                raise ValueError("Decoded audio data is too small to be a valid MP3 file")
+
+        except Exception as e:
+            if "Invalid Base64" in str(e) or "too small" in str(e):
+                raise
+            raise ValueError(f"Invalid Base64 encoding: {e}") from e
+
+        return v.rstrip("=") + "=" * (4 - len(v.rstrip("=")) % 4) if len(v.rstrip("=")) % 4 else v

app/models/response.py

@@ -0,0 +1,264 @@
+"""
+Response models for VoiceAuth API.
+
+Defines Pydantic models for API responses.
+
+PHASE 1 ENHANCED: Includes Risk Score, Quality Score, Temporal Analysis.
+"""
+
+from typing import Annotated
+from typing import Any
+from typing import Literal
+from typing import Optional
+
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+
+from app.models.enums import Classification
+
+
+class VoiceDetectionResponse(BaseModel):
+    """
+    Successful voice detection response.
+
+    Contains classification result, confidence score, explanation,
+    and comprehensive analysis data.
+    
+    PHASE 1 FEATURES:
+    - deepfakeRiskScore: Business-friendly risk rating
+    - audioQuality: Input quality assessment
+    - temporalAnalysis: Breathing, pauses, rhythm analysis
+    - audioForensics: Spectral and energy analysis
+    - performanceMetrics: Processing time breakdown
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "status": "success",
+                "language": "Tamil",
+                "classification": "AI_GENERATED",
+                "confidenceScore": 0.91,
+                "explanation": "Strong evidence of AI-generated speech: absence of natural breathing sounds and mechanically consistent pause patterns detected",
+                "deepfakeRiskScore": {
+                    "score": 87,
+                    "level": "HIGH",
+                    "recommendation": "Manual review required before approval",
+                },
+                "audioQuality": {
+                    "score": 85,
+                    "rating": "GOOD",
+                    "reliability": "High confidence in detection results",
+                },
+                "temporalAnalysis": {
+                    "breathingDetected": False,
+                    "breathingNaturalness": 0.0,
+                    "pauseMechanicalScore": 0.78,
+                    "rhythmConsistency": 0.85,
+                    "anomalyScore": 0.72,
+                    "verdict": "HIGH_ANOMALY",
+                },
+                "audioForensics": {
+                    "spectralCentroid": 1523.45,
+                    "pitchStability": 0.89,
+                    "jitter": 0.0021,
+                    "energyConsistency": 0.92,
+                    "silenceRatio": 0.08,
+                    "aiLikelihood": 0.76,
+                },
+                "performanceMetrics": {
+                    "audioProcessingMs": 45.23,
+                    "forensicsAnalysisMs": 12.87,
+                    "temporalAnalysisMs": 8.45,
+                    "modelInferenceMs": 127.45,
+                    "totalProcessingMs": 193.00,
+                },
+            }
+        }
+    )
+
+    status: Annotated[
+        Literal["success"],
+        Field(description="Response status, always 'success' for successful detections"),
+    ] = "success"
+
+    language: Annotated[
+        str,
+        Field(description="Language of the analyzed audio"),
+    ]
+
+    classification: Annotated[
+        Classification,
+        Field(description="Classification result: AI_GENERATED or HUMAN"),
+    ]
+
+    confidenceScore: Annotated[
+        float,
+        Field(
+            ge=0.0,
+            le=1.0,
+            description="Calibrated confidence score between 0.0 and 1.0",
+        ),
+    ]
+
+    explanation: Annotated[
+        str,
+        Field(
+            max_length=250,
+            description="Human-readable explanation based on comprehensive analysis",
+        ),
+    ]
+
+    # NEW: Deepfake Risk Score
+    deepfakeRiskScore: Annotated[
+        Optional[dict[str, Any]],
+        Field(
+            default=None,
+            description="Business-friendly risk score (0-100) with level and recommendation",
+        ),
+    ] = None
+
+    # NEW: Audio Quality Score
+    audioQuality: Annotated[
+        Optional[dict[str, Any]],
+        Field(
+            default=None,
+            description="Input audio quality assessment affecting detection reliability",
+        ),
+    ] = None
+
+    # NEW: Temporal Analysis
+    temporalAnalysis: Annotated[
+        Optional[dict[str, Any]],
+        Field(
+            default=None,
+            description="Temporal anomaly analysis (breathing, pauses, rhythm)",
+        ),
+    ] = None
+
+    # Audio Forensics
+    audioForensics: Annotated[
+        Optional[dict[str, float]],
+        Field(
+            default=None,
+            description="Detailed audio forensics analysis metrics",
+        ),
+    ] = None
+
+    # Performance Metrics
+    performanceMetrics: Annotated[
+        Optional[dict[str, float]],
+        Field(
+            default=None,
+            description="Performance timing breakdown",
+        ),
+    ] = None
+
+
+class ErrorResponse(BaseModel):
+    """
+    Error response model.
+
+    Returned when the API encounters an error.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "status": "error",
+                "message": "Invalid API key or malformed request",
+            }
+        }
+    )
+
+    status: Annotated[
+        Literal["error"],
+        Field(description="Response status, always 'error' for error responses"),
+    ] = "error"
+
+    message: Annotated[
+        str,
+        Field(description="Human-readable error message"),
+    ]
+
+    details: Annotated[
+        Optional[dict[str, Any]],
+        Field(default=None, description="Additional error details if available"),
+    ] = None
+
+
+class HealthResponse(BaseModel):
+    """
+    Health check response model.
+
+    Returned by health check endpoints.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "status": "healthy",
+                "version": "1.0.0",
+                "model_loaded": True,
+                "model_name": "facebook/wav2vec2-base",
+                "device": "cuda",
+                "supported_languages": ["Tamil", "English", "Hindi", "Malayalam", "Telugu"],
+                "features": [
+                    "audio_forensics",
+                    "temporal_anomaly_detection",
+                    "deepfake_risk_score",
+                    "audio_quality_score",
+                ],
+            }
+        }
+    )
+
+    status: Annotated[
+        str,
+        Field(description="Health status: 'healthy' or 'unhealthy'"),
+    ]
+
+    version: Annotated[
+        str,
+        Field(description="API version"),
+    ]
+
+    model_loaded: Annotated[
+        bool,
+        Field(description="Whether the ML model is loaded and ready"),
+    ]
+
+    model_name: Annotated[
+        Optional[str],
+        Field(default=None, description="Name of the loaded model"),
+    ] = None
+
+    device: Annotated[
+        Optional[str],
+        Field(default=None, description="Device used for inference (cpu/cuda)"),
+    ] = None
+
+    supported_languages: Annotated[
+        list[str],
+        Field(description="List of supported languages"),
+    ]
+
+    features: Annotated[
+        Optional[list[str]],
+        Field(default=None, description="List of enabled features"),
+    ] = None
+
+
+class LanguagesResponse(BaseModel):
+    """Response model for supported languages endpoint."""
+
+    languages: Annotated[
+        list[str],
+        Field(description="List of supported language names"),
+    ]
+
+    count: Annotated[
+        int,
+        Field(description="Number of supported languages"),
+    ]

app/services/__init__.py

@@ -0,0 +1,19 @@
+"""Services package."""
+
+from app.services.audio_forensics import AudioForensicsAnalyzer
+from app.services.audio_processor import AudioProcessor
+from app.services.explainability import ExplainabilityService
+from app.services.score_calculators import AudioQualityScorer
+from app.services.score_calculators import RiskScoreCalculator
+from app.services.temporal_detector import TemporalAnomalyDetector
+from app.services.voice_detector import VoiceDetector
+
+__all__ = [
+    "AudioProcessor",
+    "AudioForensicsAnalyzer",
+    "ExplainabilityService",
+    "TemporalAnomalyDetector",
+    "RiskScoreCalculator",
+    "AudioQualityScorer",
+    "VoiceDetector",
+]