app/utils/constants.py

"""
Application constants for VoiceAuth API.

Defines constant values used throughout the application.
"""

# =============================================================================
# Audio Processing Constants
# =============================================================================

# Target sample rate for Wav2Vec2 model (16kHz)
TARGET_SAMPLE_RATE: int = 16000

# Audio channel configuration (mono)
AUDIO_CHANNELS: int = 1

# Audio bit depth
AUDIO_BIT_DEPTH: int = 16

# Supported audio MIME types
SUPPORTED_AUDIO_MIME_TYPES: set[str] = {
    "audio/mpeg",
    "audio/mp3",
    "audio/x-mpeg",
}

# MP3 magic bytes (ID3 or frame sync)
MP3_MAGIC_BYTES: tuple[bytes, ...] = (
    b"ID3",  # ID3v2 tag
    b"\xff\xfb",  # MPEG Audio Layer 3, no CRC
    b"\xff\xfa",  # MPEG Audio Layer 3, CRC
    b"\xff\xf3",  # MPEG Audio Layer 3, no CRC (MPEG 2.5)
    b"\xff\xf2",  # MPEG Audio Layer 3, CRC (MPEG 2.5)
)

# =============================================================================
# Model Constants
# =============================================================================

# Model label mappings
LABEL_TO_ID: dict[str, int] = {
    "HUMAN": 0,
    "AI_GENERATED": 1,
}

ID_TO_LABEL: dict[int, str] = {
    0: "HUMAN",
    1: "AI_GENERATED",
}

# Classification thresholds
CONFIDENCE_THRESHOLD_HIGH: float = 0.85
CONFIDENCE_THRESHOLD_MEDIUM: float = 0.65
CONFIDENCE_THRESHOLD_LOW: float = 0.50

# =============================================================================
# Explainability Constants
# =============================================================================

# AI-generated voice indicators
AI_INDICATORS: list[str] = [
    "unnatural pitch consistency",
    "robotic speech patterns",
    "synthetic formant transitions",
    "irregular breathing patterns",
    "mechanical prosody",
    "uniform spectral distribution",
    "absence of micro-variations",
    "artificial voice modulation",
    "synthetic vibrato patterns",
    "digital compression artifacts",
]

# Human voice indicators
HUMAN_INDICATORS: list[str] = [
    "natural speech variations",
    "authentic prosody",
    "organic voice characteristics",
    "natural breathing patterns",
    "dynamic pitch modulation",
    "genuine emotional inflections",
    "natural micro-pauses",
    "authentic formant patterns",
    "organic vibrato characteristics",
    "natural voice timbre",
]

# Confidence level descriptors
CONFIDENCE_DESCRIPTORS: dict[str, str] = {
    "very_high": "Strong evidence of",
    "high": "Clear indicators of",
    "medium": "Likely signs of",
    "low": "Possible characteristics of",
}

# =============================================================================
# API Constants
# =============================================================================

# Request ID header
REQUEST_ID_HEADER: str = "X-Request-ID"

# Rate limit headers
RATE_LIMIT_LIMIT_HEADER: str = "X-RateLimit-Limit"
RATE_LIMIT_REMAINING_HEADER: str = "X-RateLimit-Remaining"
RATE_LIMIT_RESET_HEADER: str = "X-RateLimit-Reset"

# API key prefix
API_KEY_PREFIX: str = "sk_"