Add FastAPI application

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.9
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

api/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

api/config.py

@@ -0,0 +1,29 @@
+import os
+
+from dotenv import load_dotenv
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+load_dotenv()
+
+
+# Otherwise, the root path will be the local host. ROOT_PATH is an env var configured in Vercel deployment.
+# The value for production is equal to the root path of the deployment URL in Vercel.
+ROOT_PATH = os.getenv("ROOT_PATH", "/")
+
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "FastAPI App"
+    PROJECT_DESCRIPTION: str = "A simple FastAPI app"
+    ENVIRONMENT: str = os.getenv("ENVIRONMENT", "development")
+    CLERK_JWKS_URL: str = os.getenv("CLERK_JWKS_URL")
+    CLERK_PEM_PUBLIC_KEY: str = os.getenv("CLERK_PEM_PUBLIC_KEY")
+    OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
+    GITHUB_TOKEN: str = os.getenv("GITHUB_TOKEN", "")  # For GitHub Models GPT-4o
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+    openapi_url: str = "/openapi.json"
+    API_VERSION: str = "/v1"
+    ROOT: str = ROOT_PATH
+
+
+settings = Settings()

api/endpoints/v1/analytics/__init__.py

@@ -0,0 +1 @@
+"""Analytics module - Progress tracking and metrics."""

api/endpoints/v1/api.py

@@ -0,0 +1,31 @@
+from fastapi import APIRouter
+
+from api.endpoints.v1.routers import health, upload, therapy, analytics
+
+api_router = APIRouter()
+
+
+api_router.include_router(
+    health.router,
+    prefix="/health",
+    tags=["health"],
+    responses={404: {"description": "Not found"}},
+)
+api_router.include_router(
+    upload.router,
+    prefix="/upload",
+    tags=["upload"],
+    responses={404: {"description": "Not found"}},
+)
+api_router.include_router(
+    therapy.router,
+    prefix="/therapy",
+    tags=["therapy"],
+    responses={404: {"description": "Not found"}},
+)
+api_router.include_router(
+    analytics.router,
+    prefix="/analytics",
+    tags=["analytics"],
+    responses={404: {"description": "Not found"}},
+)

api/endpoints/v1/auth/verify.py

@@ -0,0 +1,122 @@
+import logging
+from datetime import datetime, timezone
+from typing import Optional, List
+
+import requests
+from fastapi import HTTPException, Security
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from jose import exceptions, jwk, jwt
+from jose.utils import base64url_decode
+
+from api.config import settings
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+ALGORITHM = "RS256"
+security = HTTPBearer()
+
+# Define the allowed origins for the azp claim
+ALLOWED_ORIGINS = [
+    "http://localhost:3000",
+    "com.ubumuntu.app",
+]
+
+def get_jwks(jwks_url: str):
+    """Fetch the JWKS from the given URL."""
+    response = requests.get(jwks_url)
+    response.raise_for_status()
+    return response.json()
+
+
+def get_public_key(token: str, jwks_url: str):
+    """Get the public key for the given token from the JWKS."""
+    jwks = get_jwks(jwks_url)
+    header = jwt.get_unverified_header(token)
+    rsa_key = {}
+    for key in jwks["keys"]:
+        if key["kid"] == header["kid"]:
+            rsa_key = {
+                "kty": key["kty"],
+                "kid": key["kid"],
+                "use": key["use"],
+                "n": key["n"],
+                "e": key["e"],
+            }
+            break
+    if not rsa_key:
+        raise HTTPException(status_code=401, detail="Unable to find appropriate key")
+    return jwk.construct(rsa_key, algorithm=ALGORITHM)
+
+
+def decode_jwt(token: str, jwks_url: str, allowed_origins: List[str]) -> Optional[dict]:
+    """Decode a JWT token and verify its expiration and azp claim using JWKS."""
+    try:
+        logging.info("Attempting to decode the JWT token.")
+        public_key = get_public_key(token, jwks_url)
+        message, encoded_signature = token.rsplit(".", 1)
+        decoded_signature = base64url_decode(encoded_signature.encode("utf-8"))
+
+        if not public_key.verify(message.encode("utf-8"), decoded_signature):
+            logging.warning("Invalid token signature.")
+            return None
+
+        payload = jwt.decode(
+            token,
+            public_key.to_pem().decode("utf-8"),
+            algorithms=[ALGORITHM],
+            audience="authenticated",
+        )
+
+        # Validate expiration (exp) and not before (nbf) claims
+        now = datetime.now(tz=timezone.utc)
+        exp = payload.get("exp")
+        nbf = payload.get("nbf")
+
+        if exp and datetime.fromtimestamp(exp, tz=timezone.utc) < now:
+            logging.warning("Token has expired.")
+            return None
+
+        if nbf and datetime.fromtimestamp(nbf, tz=timezone.utc) > now:
+            logging.warning("Token not yet valid.")
+            return None
+
+        # Validate authorized parties by the azp claim
+        azp = payload.get("azp")
+        logging.debug(f"azp: {azp}")
+
+        if azp and azp not in allowed_origins:
+            logging.warning(f"Unauthorized party: {azp}")
+            return None
+
+        logging.info("JWT successfully decoded.")
+        return payload
+
+    except exceptions.ExpiredSignatureError:
+        logging.error("JWT has expired.")
+        return None
+    except exceptions.JWTClaimsError:
+        logging.error("JWT claims error.")
+        return None
+    except exceptions.JWTError as e:
+        logging.error(f"JWT decoding error: {e}")
+        return None
+
+
+def verify_token(credentials: HTTPAuthorizationCredentials = Security(security)):
+    """Verify the incoming token using the `decode_jwt` function."""
+    token = credentials.credentials
+
+    credentials_exception = HTTPException(
+        status_code=401,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+
+    payload = decode_jwt(token, settings.CLERK_JWKS_URL, ALLOWED_ORIGINS)
+    if not payload or "sub" not in payload:
+        raise credentials_exception
+
+    return payload["sub"]

api/endpoints/v1/processing/ai_feedback.py

@@ -0,0 +1,239 @@
+"""
+AI Feedback Module - GPT-4o powered speech therapy feedback.
+
+Uses GitHub Models API for GPT-4o access.
+"""
+
+import os
+import json
+import logging
+from typing import Optional, List
+from dataclasses import dataclass
+
+from openai import OpenAI
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AIFeedbackResult:
+    """AI-generated feedback for speech therapy."""
+    feedback: str
+    encouragement: str
+    specific_tips: List[str]
+    recommended_exercises: List[str]
+    difficulty_adjustment: Optional[str]  # "easier", "same", "harder"
+
+
+class AIFeedbackGenerator:
+    """
+    Generate personalized speech therapy feedback using GPT-4o.
+
+    Uses GitHub Models API (free for GitHub users).
+    """
+
+    def __init__(self):
+        self.client: Optional[OpenAI] = None
+        self.model = "gpt-4o"
+        self._initialize_client()
+
+    def _initialize_client(self):
+        """Initialize the OpenAI client with GitHub Models."""
+        github_token = os.getenv("GITHUB_TOKEN")
+
+        if not github_token:
+            raise ValueError(
+                "GITHUB_TOKEN not found. Please set it in your .env file. "
+                "Get your token at: https://github.com/settings/tokens"
+            )
+
+        # Use GitHub Models (free GPT-4o access)
+        self.client = OpenAI(
+            base_url="https://models.inference.ai.azure.com",
+            api_key=github_token,
+        )
+        self.model = "gpt-4o"
+        logger.info("AI Feedback: Using GitHub Models (GPT-4o)")
+
+    async def generate_feedback(
+        self,
+        target_text: str,
+        transcription: str,
+        overall_score: float,
+        clarity_score: float,
+        pace_score: float,
+        fluency_score: float,
+        errors: List[dict],
+        user_context: Optional[dict] = None
+    ) -> AIFeedbackResult:
+        """
+        Generate personalized feedback for a speech exercise attempt.
+
+        Args:
+            target_text: The text the user was supposed to say
+            transcription: What the ASR heard
+            overall_score: 0-100 overall score
+            clarity_score: 0-100 clarity score
+            pace_score: 0-100 pace score
+            fluency_score: 0-100 fluency score
+            errors: List of pronunciation errors detected
+            user_context: Optional user profile info (speech condition, etc.)
+
+        Returns:
+            AIFeedbackResult with personalized feedback
+        """
+        # Build context about user if available
+        user_info = ""
+        if user_context:
+            condition = user_context.get("speech_condition", "")
+            severity = user_context.get("severity_level", "")
+            if condition:
+                user_info = f"\nUser has {condition}"
+                if severity:
+                    user_info += f" (severity: {severity}/5)"
+                user_info += ". Adjust feedback accordingly."
+
+        # Format errors for the prompt
+        error_summary = ""
+        if errors:
+            error_items = []
+            for e in errors[:5]:  # Limit to 5 errors
+                error_items.append(
+                    f"- '{e.get('expected', '')}' → '{e.get('actual', '')}' ({e.get('error_type', '')})"
+                )
+            error_summary = "\n".join(error_items)
+
+        system_prompt = """You are a supportive, encouraging speech therapist helping users improve their speech clarity.
+
+Your feedback should be:
+- Warm and encouraging, never discouraging
+- Specific and actionable
+- Age-appropriate and easy to understand
+- Focused on progress, not perfection
+
+Always acknowledge effort and provide constructive guidance."""
+
+        user_prompt = f"""Please provide feedback for this speech exercise attempt:
+
+**Target phrase:** "{target_text}"
+**User said:** "{transcription}"
+
+**Scores:**
+- Overall: {overall_score:.0f}/100
+- Clarity: {clarity_score:.0f}/100
+- Pace: {pace_score:.0f}/100
+- Fluency: {fluency_score:.0f}/100
+
+**Pronunciation differences:**
+{error_summary if error_summary else "No major differences detected"}
+{user_info}
+
+Please respond in this JSON format:
+{{
+    "feedback": "2-3 sentences of overall feedback",
+    "encouragement": "A short encouraging message",
+    "specific_tips": ["tip 1", "tip 2", "tip 3"],
+    "recommended_exercises": ["exercise 1", "exercise 2"],
+    "difficulty_adjustment": "easier" or "same" or "harder"
+}}"""
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": user_prompt}
+            ],
+            temperature=0.7,
+            max_tokens=500,
+            response_format={"type": "json_object"}
+        )
+
+        # Parse the response
+        result = json.loads(response.choices[0].message.content)
+
+        return AIFeedbackResult(
+            feedback=result.get("feedback", "Good effort! Keep practicing."),
+            encouragement=result.get("encouragement", "You're making progress!"),
+            specific_tips=result.get("specific_tips", []),
+            recommended_exercises=result.get("recommended_exercises", []),
+            difficulty_adjustment=result.get("difficulty_adjustment", "same")
+        )
+
+    async def generate_session_summary(
+        self,
+        session_stats: dict,
+        attempts: List[dict]
+    ) -> str:
+        """Generate an AI summary of a therapy session."""
+        prompt = f"""Summarize this speech therapy session for the user:
+
+**Session Stats:**
+- Duration: {session_stats.get('duration_minutes', 0)} minutes
+- Exercises completed: {session_stats.get('exercise_count', 0)}
+- Average score: {session_stats.get('average_score', 0):.0f}/100
+- Best score: {session_stats.get('best_score', 0):.0f}/100
+
+**Exercise Types Practiced:** {', '.join(session_stats.get('exercise_types', []))}
+
+Please provide a brief, encouraging 2-3 sentence summary of their session."""
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": "You are a supportive speech therapist providing session summaries."},
+                {"role": "user", "content": prompt}
+            ],
+            temperature=0.7,
+            max_tokens=150
+        )
+
+        return response.choices[0].message.content
+
+    async def generate_weekly_insights(
+        self,
+        weekly_data: dict
+    ) -> dict:
+        """Generate AI-powered weekly progress insights."""
+        prompt = f"""Analyze this user's weekly speech therapy progress:
+
+**This Week:**
+- Sessions: {weekly_data.get('sessions_this_week', 0)}
+- Total practice time: {weekly_data.get('practice_minutes', 0)} minutes
+- Average score: {weekly_data.get('avg_score', 0):.0f}/100
+- Score change from last week: {weekly_data.get('score_change', 0):+.1f}%
+
+**Strengths:** {', '.join(weekly_data.get('strengths', ['Consistent practice']))}
+**Areas to improve:** {', '.join(weekly_data.get('weaknesses', ['Continue practicing']))}
+
+Provide a JSON response with:
+{{
+    "summary": "2-3 sentence progress summary",
+    "celebration": "Something specific to celebrate",
+    "focus_area": "One specific thing to focus on next week",
+    "goal": "A realistic goal for next week"
+}}"""
+
+        response = self.client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": "You are an encouraging speech therapist analyzing weekly progress."},
+                {"role": "user", "content": prompt}
+            ],
+            temperature=0.7,
+            max_tokens=300,
+            response_format={"type": "json_object"}
+        )
+
+        return json.loads(response.choices[0].message.content)
+
+
+# Singleton instance
+_feedback_generator: Optional[AIFeedbackGenerator] = None
+
+
+def get_ai_feedback_generator() -> AIFeedbackGenerator:
+    """Get or create AIFeedbackGenerator singleton."""
+    global _feedback_generator
+    if _feedback_generator is None:
+        _feedback_generator = AIFeedbackGenerator()
+    return _feedback_generator

api/endpoints/v1/processing/audio.py

@@ -0,0 +1,31 @@
+import io
+import logging
+
+from openai import OpenAI
+
+from api.config import settings
+
+client = OpenAI(api_key=settings.OPENAI_API_KEY)
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+
+def transcribe_with_whisper(
+    filename: str, file_like: io.BytesIO, content_type: str
+) -> str:
+    """Helper function to transcribe audio using OpenAI Whisper."""
+    logging.info("Transcribing with whisper")
+
+    # Prepare the file data as a tuple
+    file_data = (filename, file_like.read(), content_type)
+
+    # Call the OpenAI API to transcribe the audio file
+    transcription = client.audio.transcriptions.create(
+        model="whisper-1", file=file_data
+    )
+
+    logging.debug(f"Transcription: {transcription.text}")
+    return transcription

api/endpoints/v1/processing/pronunciation_analysis.py

@@ -0,0 +1,468 @@
+"""
+Pronunciation Analysis Module - Speech clarity and pronunciation feedback.
+
+Provides:
+- Pronunciation scoring (PCC - Percent Consonants Correct)
+- Clarity assessment
+- Pace analysis
+- Per-word feedback
+- Improvement suggestions
+"""
+
+import io
+import logging
+from typing import Optional, List
+from dataclasses import dataclass, field
+from enum import Enum
+
+from api.config import settings
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+
+class ErrorType(str, Enum):
+    """Types of pronunciation errors."""
+    SUBSTITUTION = "substitution"  # Wrong sound
+    OMISSION = "omission"          # Missing sound
+    ADDITION = "addition"          # Extra sound
+    DISTORTION = "distortion"      # Unclear sound
+
+
+@dataclass
+class PhonemeError:
+    """Individual phoneme-level error."""
+    word: str
+    position: int  # Position in word
+    expected: str
+    actual: Optional[str]
+    error_type: ErrorType
+    suggestion: str
+
+
+@dataclass
+class WordScore:
+    """Per-word pronunciation score."""
+    word: str
+    score: float  # 0-100
+    start_time: Optional[float] = None
+    end_time: Optional[float] = None
+    errors: List[PhonemeError] = field(default_factory=list)
+
+
+@dataclass
+class AIFeedback:
+    """AI-generated personalized feedback."""
+    feedback: str
+    encouragement: str
+    specific_tips: List[str]
+    recommended_exercises: List[str]
+    difficulty_adjustment: Optional[str] = None  # "easier", "same", "harder"
+
+
+@dataclass
+class PronunciationFeedback:
+    """Complete pronunciation analysis result."""
+    overall_score: float           # 0-100
+    clarity_score: float           # 0-100
+    pace_score: float              # 0-100
+    fluency_score: float           # 0-100
+    word_scores: List[WordScore]
+    suggestions: List[str]
+    phoneme_errors: List[PhonemeError]
+    transcription: str
+    target_text: str
+    duration_seconds: Optional[float] = None
+    ai_feedback: Optional[AIFeedback] = None  # GPT-4o powered feedback
+
+
+class PronunciationAnalyzer:
+    """
+    Analyze pronunciation against target text.
+
+    Uses ASR with forced alignment to compare user speech
+    against expected pronunciation. Integrates GPT-4o for
+    personalized feedback via GitHub Models API.
+    """
+
+    def __init__(self):
+        self._asr = None
+        self._ai_feedback = None
+
+    def _get_ai_feedback_generator(self):
+        """Get AI feedback generator instance."""
+        if self._ai_feedback is None:
+            from api.endpoints.v1.processing.ai_feedback import get_ai_feedback_generator
+            self._ai_feedback = get_ai_feedback_generator()
+        return self._ai_feedback
+
+    def _get_asr(self):
+        """Get ASR instance for transcription."""
+        if self._asr is None:
+            from api.endpoints.v1.processing.therapy_asr import get_therapy_asr
+            self._asr = get_therapy_asr()
+        return self._asr
+
+    async def analyze(
+        self,
+        audio_bytes: bytes,
+        target_text: str,
+        user_baseline: Optional[dict] = None,
+        user_context: Optional[dict] = None,
+        include_ai_feedback: bool = True
+    ) -> PronunciationFeedback:
+        """
+        Analyze pronunciation of audio against target text.
+
+        Args:
+            audio_bytes: User's recorded audio
+            target_text: Expected text/phrase
+            user_baseline: Optional baseline metrics for comparison
+            user_context: Optional user profile (speech condition, severity)
+            include_ai_feedback: Whether to generate GPT-4o feedback
+
+        Returns:
+            PronunciationFeedback with scores, suggestions, and AI feedback
+        """
+        logging.info(f"Analyzing pronunciation for target: {target_text}")
+
+        # 1. Transcribe the audio
+        asr = self._get_asr()
+        result = asr.transcribe(audio_bytes)
+        transcription = result.text.strip().lower()
+        target_clean = target_text.strip().lower()
+
+        logging.debug(f"Transcription: {transcription}")
+        logging.debug(f"Target: {target_clean}")
+
+        # 2. Compare transcription to target
+        word_scores, phoneme_errors = self._compare_texts(
+            transcription, target_clean
+        )
+
+        # 3. Calculate scores
+        overall_score = self._calculate_overall_score(word_scores)
+        clarity_score = self._calculate_clarity_score(word_scores, phoneme_errors)
+        pace_score = self._calculate_pace_score(result.word_timestamps)
+        fluency_score = self._calculate_fluency_score(transcription, target_clean)
+
+        # 4. Generate rule-based suggestions
+        suggestions = self._generate_suggestions(phoneme_errors, word_scores)
+
+        # 5. Generate AI-powered feedback (GPT-4o via GitHub Models)
+        ai_feedback = None
+        if include_ai_feedback:
+            try:
+                ai_generator = self._get_ai_feedback_generator()
+                # Convert phoneme errors to dict format for AI
+                errors_dict = [
+                    {
+                        "word": e.word,
+                        "expected": e.expected,
+                        "actual": e.actual,
+                        "error_type": e.error_type.value
+                    }
+                    for e in phoneme_errors
+                ]
+
+                ai_result = await ai_generator.generate_feedback(
+                    target_text=target_text,
+                    transcription=transcription,
+                    overall_score=overall_score,
+                    clarity_score=clarity_score,
+                    pace_score=pace_score,
+                    fluency_score=fluency_score,
+                    errors=errors_dict,
+                    user_context=user_context
+                )
+
+                ai_feedback = AIFeedback(
+                    feedback=ai_result.feedback,
+                    encouragement=ai_result.encouragement,
+                    specific_tips=ai_result.specific_tips,
+                    recommended_exercises=ai_result.recommended_exercises,
+                    difficulty_adjustment=ai_result.difficulty_adjustment
+                )
+                logging.info("AI feedback generated successfully")
+            except Exception as e:
+                logging.warning(f"AI feedback generation failed: {e}")
+                ai_feedback = None
+
+        return PronunciationFeedback(
+            overall_score=overall_score,
+            clarity_score=clarity_score,
+            pace_score=pace_score,
+            fluency_score=fluency_score,
+            word_scores=word_scores,
+            suggestions=suggestions,
+            phoneme_errors=phoneme_errors,
+            transcription=transcription,
+            target_text=target_text,
+            ai_feedback=ai_feedback
+        )
+
+    def _compare_texts(
+        self,
+        transcription: str,
+        target: str
+    ) -> tuple[List[WordScore], List[PhonemeError]]:
+        """Compare transcribed text to target text."""
+        trans_words = transcription.split()
+        target_words = target.split()
+
+        word_scores = []
+        phoneme_errors = []
+
+        # Simple word-level comparison (can be enhanced with phoneme alignment)
+        max_len = max(len(trans_words), len(target_words))
+
+        for i in range(max_len):
+            target_word = target_words[i] if i < len(target_words) else ""
+            trans_word = trans_words[i] if i < len(trans_words) else ""
+
+            if not target_word:
+                # Extra word in transcription
+                phoneme_errors.append(PhonemeError(
+                    word=trans_word,
+                    position=i,
+                    expected="",
+                    actual=trans_word,
+                    error_type=ErrorType.ADDITION,
+                    suggestion=f"Extra word '{trans_word}' detected"
+                ))
+                continue
+
+            if not trans_word:
+                # Missing word
+                word_scores.append(WordScore(
+                    word=target_word,
+                    score=0.0,
+                    errors=[PhonemeError(
+                        word=target_word,
+                        position=i,
+                        expected=target_word,
+                        actual=None,
+                        error_type=ErrorType.OMISSION,
+                        suggestion=f"Try to include the word '{target_word}'"
+                    )]
+                ))
+                phoneme_errors.append(word_scores[-1].errors[0])
+                continue
+
+            # Compare words
+            score, errors = self._compare_words(target_word, trans_word, i)
+            word_scores.append(WordScore(
+                word=target_word,
+                score=score,
+                errors=errors
+            ))
+            phoneme_errors.extend(errors)
+
+        return word_scores, phoneme_errors
+
+    def _compare_words(
+        self,
+        target_word: str,
+        trans_word: str,
+        position: int
+    ) -> tuple[float, List[PhonemeError]]:
+        """Compare two words and return score and errors."""
+        errors = []
+
+        # Exact match
+        if target_word == trans_word:
+            return 100.0, []
+
+        # Calculate similarity (simple Levenshtein-based)
+        similarity = self._word_similarity(target_word, trans_word)
+        score = similarity * 100
+
+        # Detect error type
+        if len(trans_word) > len(target_word):
+            error_type = ErrorType.ADDITION
+            suggestion = f"'{trans_word}' has extra sounds, expected '{target_word}'"
+        elif len(trans_word) < len(target_word):
+            error_type = ErrorType.OMISSION
+            suggestion = f"Some sounds missing in '{trans_word}', expected '{target_word}'"
+        else:
+            error_type = ErrorType.SUBSTITUTION
+            suggestion = f"'{trans_word}' should be '{target_word}'"
+
+        if score < 100:
+            errors.append(PhonemeError(
+                word=target_word,
+                position=position,
+                expected=target_word,
+                actual=trans_word,
+                error_type=error_type,
+                suggestion=suggestion
+            ))
+
+        return score, errors
+
+    def _word_similarity(self, word1: str, word2: str) -> float:
+        """Calculate similarity between two words (0-1)."""
+        if word1 == word2:
+            return 1.0
+
+        # Levenshtein distance normalized
+        len1, len2 = len(word1), len(word2)
+        if len1 == 0 or len2 == 0:
+            return 0.0
+
+        # Create distance matrix
+        dp = [[0] * (len2 + 1) for _ in range(len1 + 1)]
+
+        for i in range(len1 + 1):
+            dp[i][0] = i
+        for j in range(len2 + 1):
+            dp[0][j] = j
+
+        for i in range(1, len1 + 1):
+            for j in range(1, len2 + 1):
+                cost = 0 if word1[i-1] == word2[j-1] else 1
+                dp[i][j] = min(
+                    dp[i-1][j] + 1,      # deletion
+                    dp[i][j-1] + 1,      # insertion
+                    dp[i-1][j-1] + cost  # substitution
+                )
+
+        distance = dp[len1][len2]
+        max_len = max(len1, len2)
+
+        return 1.0 - (distance / max_len)
+
+    def _calculate_overall_score(self, word_scores: List[WordScore]) -> float:
+        """Calculate overall pronunciation score."""
+        if not word_scores:
+            return 0.0
+        return sum(ws.score for ws in word_scores) / len(word_scores)
+
+    def _calculate_clarity_score(
+        self,
+        word_scores: List[WordScore],
+        errors: List[PhonemeError]
+    ) -> float:
+        """Calculate speech clarity score."""
+        if not word_scores:
+            return 0.0
+
+        # Penalize based on error types
+        error_penalties = {
+            ErrorType.DISTORTION: 15,
+            ErrorType.SUBSTITUTION: 10,
+            ErrorType.OMISSION: 20,
+            ErrorType.ADDITION: 5,
+        }
+
+        base_score = 100.0
+        for error in errors:
+            base_score -= error_penalties.get(error.error_type, 10)
+
+        return max(0.0, base_score)
+
+    def _calculate_pace_score(
+        self,
+        word_timestamps: Optional[List[dict]]
+    ) -> float:
+        """Calculate pace/timing score."""
+        if not word_timestamps or len(word_timestamps) < 2:
+            return 75.0  # Default score if no timestamps
+
+        # Calculate words per minute
+        total_duration = word_timestamps[-1].get("end", 0) - word_timestamps[0].get("start", 0)
+        if total_duration <= 0:
+            return 75.0
+
+        wpm = (len(word_timestamps) / total_duration) * 60
+
+        # Ideal range: 100-150 WPM for clear speech
+        if 100 <= wpm <= 150:
+            return 100.0
+        elif 80 <= wpm < 100 or 150 < wpm <= 180:
+            return 85.0
+        elif 60 <= wpm < 80 or 180 < wpm <= 200:
+            return 70.0
+        else:
+            return 50.0
+
+    def _calculate_fluency_score(self, transcription: str, target: str) -> float:
+        """Calculate fluency based on text similarity."""
+        return self._word_similarity(transcription, target) * 100
+
+    def _generate_suggestions(
+        self,
+        errors: List[PhonemeError],
+        word_scores: List[WordScore]
+    ) -> List[str]:
+        """Generate actionable improvement suggestions."""
+        suggestions = []
+
+        # Group errors by type
+        error_types = {}
+        for error in errors:
+            error_types.setdefault(error.error_type, []).append(error)
+
+        # Generate suggestions based on error patterns
+        if ErrorType.OMISSION in error_types:
+            omissions = error_types[ErrorType.OMISSION]
+            words = [e.word for e in omissions[:3]]
+            suggestions.append(
+                f"Try to pronounce all sounds in: {', '.join(words)}"
+            )
+
+        if ErrorType.SUBSTITUTION in error_types:
+            subs = error_types[ErrorType.SUBSTITUTION]
+            if subs:
+                suggestions.append(
+                    f"Focus on the correct sound in '{subs[0].word}'"
+                )
+
+        if ErrorType.ADDITION in error_types:
+            suggestions.append("Speak more clearly without adding extra sounds")
+
+        # Low scoring words
+        low_scores = [ws for ws in word_scores if ws.score < 70]
+        if low_scores:
+            words = [ws.word for ws in low_scores[:3]]
+            suggestions.append(
+                f"Practice these words: {', '.join(words)}"
+            )
+
+        # General encouragement if few errors
+        if len(errors) <= 2:
+            suggestions.append("Good job! Keep practicing for even better clarity.")
+
+        return suggestions[:5]  # Limit to 5 suggestions
+
+
+# Singleton instance
+_analyzer_instance: Optional[PronunciationAnalyzer] = None
+
+
+def get_pronunciation_analyzer() -> PronunciationAnalyzer:
+    """Get or create PronunciationAnalyzer singleton."""
+    global _analyzer_instance
+    if _analyzer_instance is None:
+        _analyzer_instance = PronunciationAnalyzer()
+    return _analyzer_instance
+
+
+async def analyze_pronunciation(
+    audio_bytes: bytes,
+    target_text: str,
+    user_baseline: Optional[dict] = None,
+    user_context: Optional[dict] = None,
+    include_ai_feedback: bool = True
+) -> PronunciationFeedback:
+    """Convenience function for pronunciation analysis with AI feedback."""
+    analyzer = get_pronunciation_analyzer()
+    return await analyzer.analyze(
+        audio_bytes,
+        target_text,
+        user_baseline,
+        user_context,
+        include_ai_feedback
+    )

api/endpoints/v1/processing/soap.py

@@ -0,0 +1,119 @@
+import json
+import logging
+import textwrap
+
+from openai import OpenAI
+
+from api.config import settings
+
+client = OpenAI(api_key=settings.OPENAI_API_KEY)
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+
+def generate_soap(transcript: str) -> str:
+    """Helper function to generate soap note from transcript using OpenAI Chat Completions API."""
+    logging.info("Generating soap note")
+
+    sample_transcript = textwrap.dedent("""
+    The patient is a 25-year-old right-handed Caucasian female who presented to the emergency department with sudden onset of headache occurring at approximately 11 a.m. on the morning of the July 31, 2008. She described the headache as the worst in her life and it was also accompanied by blurry vision and scotoma. The patient also perceived some swelling in her face. Once in the Emergency Department, the patient underwent a very thorough evaluation and examination. She was given the migraine cocktail. Also was given morphine a total of 8 mg while in the Emergency Department. For full details on the history of present illness, please see the previous history and physical.
+
+    Doctor: How're you feeling today?
+    Patient: Terrible. I'm having the worst headache of my life.
+    Doctor: I'm so sorry. Well you are only twenty-five, so let's hope this is the last of the worst. Let's see how we can best help you. When did it start?
+    Patient: Around eleven in the morning.
+    Doctor: Today?
+    Patient: Um no yesterday. July thirty-first.
+    Doctor: July thirty-first O eight. Got it. Did it come on suddenly?
+    Patient: Yeah.
+    Doctor: Are you having any symptoms with it, such as blurry vision, light sensitivity, dizziness, lightheadedness, or nausea?
+    Patient: I'm having blurry vision and lightheadedness. I also can't seem to write well. It looks so messy. I am naturally right-handed but my writing looks like I am trying with my left.
+    Doctor: How would you describe the lightheadedness?
+    Patient: Like there are blind spots.
+    Doctor: Okay. How about any vomiting?
+    Patient: Um no. I feel like my face is pretty swollen though. I don't know if it's related to the headache but it started around the same time.
+    Doctor: Here in the ER, we'll do a thorough exam and eval to make sure nothing serious is going on. While we're waiting for your CT results, I'm going to order a migraine cocktail and some Morphine.
+    Patient: Thanks. Will the nurse be in soon?
+    Doctor: Yes, she'll be right in as soon as the order is placed. It shouldn't be more than a few minutes. If it takes longer, then please ring the call bell.
+    """)
+
+    # Example format for Tiptap editor as a JSON string
+    example_format = {
+        "type": "doc",
+        "content": [
+            {
+                "type": "heading",
+                "attrs": {"level": 2},
+                "content": [{"type": "text", "text": "Example heading"}],
+            },
+            {
+                "type": "paragraph",
+                "content": [{"type": "text", "text": "example paragraph"}],
+            },
+            {
+                "type": "heading",
+                "attrs": {"level": 3},
+                "content": [{"type": "text", "text": "Features"}],
+            },
+            {
+                "type": "orderedList",
+                "attrs": {"tight": True, "start": 1},
+                "content": [
+                    {
+                        "type": "listItem",
+                        "content": [
+                            {
+                                "type": "paragraph",
+                                "content": [
+                                    {"type": "text", "text": "Example list item"}
+                                ],
+                            },
+                        ],
+                    },
+                    {
+                        "type": "listItem",
+                        "content": [
+                            {
+                                "type": "paragraph",
+                                "content": [
+                                    {"type": "text", "text": "AI autocomplete (type "},
+                                    {
+                                        "type": "text",
+                                        "marks": [{"type": "code"}],
+                                        "text": "++",
+                                    },
+                                    {
+                                        "type": "text",
+                                        "text": " to activate, or select from slash menu)",
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    }
+    example_format_str = json.dumps(example_format)
+
+    # Call the OpenAI Chat Completions API
+    completion = client.chat.completions.create(
+        model="gpt-4o",  # gpt-4o, gpt-3.5-turbo
+        response_format={"type": "json_object"},
+        messages=[
+            {
+                "role": "system",
+                "content": "You are a helpful assistant designed to output JSON.",
+            },
+            {
+                "role": "user",
+                "content": f"Generate a SOAP note from the following transcript and return it in JSON format for a Tiptap editor. This is the example format: {example_format_str}. The first heading can be the subjective section. The text fields can not be left blank, so try your best to fill them out. Transcript: {transcript}",
+            },
+        ],
+    )
+
+    logging.debug(f"SOAP: {completion.choices[0].message.content}")
+    return completion.choices[0].message.content

api/endpoints/v1/processing/therapy_asr.py

@@ -0,0 +1,305 @@
+"""
+Therapy ASR Module - Multi-engine speech recognition for therapy applications.
+
+Supports:
+- Local Whisper (general speech, privacy-focused)
+- SpeechBrain (fine-tuned for atypical speech)
+- OpenAI Whisper API (fallback)
+"""
+
+import io
+import logging
+from enum import Enum
+from typing import Optional
+from dataclasses import dataclass
+
+from api.config import settings
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+
+class ASREngine(str, Enum):
+    """Available ASR engines."""
+    WHISPER_LOCAL = "whisper_local"
+    SPEECHBRAIN = "speechbrain"
+    WHISPER_API = "whisper_api"
+    AUTO = "auto"  # Automatically select based on user profile
+
+
+@dataclass
+class TranscriptionResult:
+    """Structured transcription result."""
+    text: str
+    engine_used: ASREngine
+    confidence: Optional[float] = None
+    word_timestamps: Optional[list] = None
+    language: Optional[str] = None
+
+
+class TherapyASR:
+    """
+    Multi-engine ASR for therapy applications.
+
+    Supports automatic engine selection based on user speech profile,
+    with fallback chain for reliability.
+    """
+
+    def __init__(self, default_engine: ASREngine = ASREngine.AUTO):
+        self.default_engine = default_engine
+        self._whisper_local_model = None
+        self._speechbrain_model = None
+        self._openai_client = None
+
+    def _get_openai_client(self):
+        """Lazy load OpenAI client."""
+        if self._openai_client is None:
+            from openai import OpenAI
+            self._openai_client = OpenAI(api_key=settings.OPENAI_API_KEY)
+        return self._openai_client
+
+    def _get_whisper_local(self):
+        """Lazy load local Whisper model."""
+        if self._whisper_local_model is None:
+            try:
+                import torch
+                from transformers import WhisperProcessor, WhisperForConditionalGeneration
+
+                model_name = "openai/whisper-base"  # Start with base, upgrade as needed
+                logging.info(f"Loading local Whisper model: {model_name}")
+
+                self._whisper_processor = WhisperProcessor.from_pretrained(model_name)
+                self._whisper_local_model = WhisperForConditionalGeneration.from_pretrained(model_name)
+
+                # Use GPU if available
+                if torch.cuda.is_available():
+                    self._whisper_local_model = self._whisper_local_model.to("cuda")
+                elif torch.backends.mps.is_available():
+                    self._whisper_local_model = self._whisper_local_model.to("mps")
+
+                logging.info("Local Whisper model loaded successfully")
+            except ImportError as e:
+                logging.warning(f"Local Whisper not available: {e}")
+                raise
+        return self._whisper_local_model
+
+    def _get_speechbrain(self):
+        """Lazy load SpeechBrain model for atypical speech."""
+        if self._speechbrain_model is None:
+            try:
+                import speechbrain as sb
+
+                # Use pre-trained model, can be swapped for fine-tuned version
+                model_source = "speechbrain/asr-wav2vec2-commonvoice-en"
+                logging.info(f"Loading SpeechBrain model: {model_source}")
+
+                self._speechbrain_model = sb.pretrained.EncoderASR.from_hparams(
+                    source=model_source,
+                    savedir="models/speechbrain_asr"
+                )
+                logging.info("SpeechBrain model loaded successfully")
+            except ImportError as e:
+                logging.warning(f"SpeechBrain not available: {e}")
+                raise
+        return self._speechbrain_model
+
+    def _select_engine(self, user_profile: Optional[dict] = None) -> ASREngine:
+        """Select appropriate ASR engine based on user profile."""
+        if self.default_engine != ASREngine.AUTO:
+            return self.default_engine
+
+        if user_profile:
+            # Use SpeechBrain for users with speech conditions
+            speech_condition = user_profile.get("speech_condition")
+            if speech_condition in ["dysarthria", "apraxia", "autism", "stuttering"]:
+                return ASREngine.SPEECHBRAIN
+
+            # Use local Whisper for privacy-focused users
+            if user_profile.get("privacy_mode") == "local":
+                return ASREngine.WHISPER_LOCAL
+
+        # Default to API for best accuracy
+        return ASREngine.WHISPER_API
+
+    def transcribe(
+        self,
+        audio_data: bytes,
+        filename: str = "audio.wav",
+        content_type: str = "audio/wav",
+        user_profile: Optional[dict] = None,
+        engine: Optional[ASREngine] = None
+    ) -> TranscriptionResult:
+        """
+        Transcribe audio using the most appropriate engine.
+
+        Args:
+            audio_data: Raw audio bytes
+            filename: Original filename
+            content_type: MIME type of audio
+            user_profile: Optional user profile for engine selection
+            engine: Force specific engine (overrides auto-selection)
+
+        Returns:
+            TranscriptionResult with text and metadata
+        """
+        selected_engine = engine or self._select_engine(user_profile)
+        logging.info(f"Transcribing with engine: {selected_engine.value}")
+
+        # Try selected engine with fallback chain
+        fallback_order = [selected_engine]
+        if selected_engine != ASREngine.WHISPER_API:
+            fallback_order.append(ASREngine.WHISPER_API)
+
+        last_error = None
+        for eng in fallback_order:
+            try:
+                if eng == ASREngine.WHISPER_API:
+                    return self._transcribe_whisper_api(audio_data, filename, content_type)
+                elif eng == ASREngine.WHISPER_LOCAL:
+                    return self._transcribe_whisper_local(audio_data)
+                elif eng == ASREngine.SPEECHBRAIN:
+                    return self._transcribe_speechbrain(audio_data)
+            except Exception as e:
+                logging.warning(f"Engine {eng.value} failed: {e}")
+                last_error = e
+                continue
+
+        raise RuntimeError(f"All ASR engines failed. Last error: {last_error}")
+
+    def _transcribe_whisper_api(
+        self,
+        audio_data: bytes,
+        filename: str,
+        content_type: str
+    ) -> TranscriptionResult:
+        """Transcribe using OpenAI Whisper API."""
+        logging.info("Transcribing with OpenAI Whisper API")
+
+        client = self._get_openai_client()
+        file_data = (filename, audio_data, content_type)
+
+        transcription = client.audio.transcriptions.create(
+            model="whisper-1",
+            file=file_data,
+            response_format="verbose_json",
+            timestamp_granularities=["word"]
+        )
+
+        # Extract word timestamps if available
+        word_timestamps = None
+        if hasattr(transcription, 'words'):
+            word_timestamps = [
+                {"word": w.word, "start": w.start, "end": w.end}
+                for w in transcription.words
+            ]
+
+        return TranscriptionResult(
+            text=transcription.text,
+            engine_used=ASREngine.WHISPER_API,
+            language=getattr(transcription, 'language', None),
+            word_timestamps=word_timestamps
+        )
+
+    def _transcribe_whisper_local(self, audio_data: bytes) -> TranscriptionResult:
+        """Transcribe using local Whisper model."""
+        logging.info("Transcribing with local Whisper")
+
+        import torch
+        import librosa
+        import numpy as np
+
+        model = self._get_whisper_local()
+
+        # Load audio from bytes
+        audio_array, sr = librosa.load(io.BytesIO(audio_data), sr=16000)
+
+        # Process audio
+        input_features = self._whisper_processor(
+            audio_array,
+            sampling_rate=16000,
+            return_tensors="pt"
+        ).input_features
+
+        # Move to same device as model
+        device = next(model.parameters()).device
+        input_features = input_features.to(device)
+
+        # Generate transcription
+        with torch.no_grad():
+            predicted_ids = model.generate(input_features)
+
+        transcription = self._whisper_processor.batch_decode(
+            predicted_ids,
+            skip_special_tokens=True
+        )[0]
+
+        return TranscriptionResult(
+            text=transcription.strip(),
+            engine_used=ASREngine.WHISPER_LOCAL
+        )
+
+    def _transcribe_speechbrain(self, audio_data: bytes) -> TranscriptionResult:
+        """Transcribe using SpeechBrain (optimized for atypical speech)."""
+        logging.info("Transcribing with SpeechBrain")
+
+        import tempfile
+        import os
+
+        model = self._get_speechbrain()
+
+        # SpeechBrain requires file path, write temp file
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+            f.write(audio_data)
+            temp_path = f.name
+
+        try:
+            transcription = model.transcribe_file(temp_path)
+
+            # Handle different return types
+            if isinstance(transcription, list):
+                text = transcription[0] if transcription else ""
+            else:
+                text = str(transcription)
+
+            return TranscriptionResult(
+                text=text.strip(),
+                engine_used=ASREngine.SPEECHBRAIN
+            )
+        finally:
+            os.unlink(temp_path)
+
+
+# Singleton instance for reuse
+_therapy_asr_instance: Optional[TherapyASR] = None
+
+
+def get_therapy_asr() -> TherapyASR:
+    """Get or create TherapyASR singleton."""
+    global _therapy_asr_instance
+    if _therapy_asr_instance is None:
+        _therapy_asr_instance = TherapyASR()
+    return _therapy_asr_instance
+
+
+def transcribe_for_therapy(
+    audio_data: bytes,
+    filename: str = "audio.wav",
+    content_type: str = "audio/wav",
+    user_profile: Optional[dict] = None,
+    engine: Optional[ASREngine] = None
+) -> TranscriptionResult:
+    """
+    Convenience function to transcribe audio for therapy.
+
+    This is the main entry point for therapy transcription.
+    """
+    asr = get_therapy_asr()
+    return asr.transcribe(
+        audio_data=audio_data,
+        filename=filename,
+        content_type=content_type,
+        user_profile=user_profile,
+        engine=engine
+    )

api/endpoints/v1/processing/therapy_tts.py

@@ -0,0 +1,354 @@
+"""
+Therapy TTS Module - Text-to-speech for therapy and AAC applications.
+
+Supports:
+- WhisperSpeech (fast, voice cloning)
+- OpenAI TTS API (fallback)
+- Edge TTS (lightweight fallback)
+"""
+
+import io
+import logging
+from enum import Enum
+from typing import Optional
+from dataclasses import dataclass
+
+from api.config import settings
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+
+class TTSEngine(str, Enum):
+    """Available TTS engines."""
+    WHISPERSPEECH = "whisperspeech"
+    OPENAI_TTS = "openai_tts"
+    EDGE_TTS = "edge_tts"
+    AUTO = "auto"
+
+
+class TTSVoice(str, Enum):
+    """Preset voice options."""
+    NEUTRAL = "neutral"
+    WARM = "warm"
+    CLEAR = "clear"
+    SLOW = "slow"  # For therapy exercises
+    CUSTOM = "custom"  # Voice cloning
+
+
+@dataclass
+class TTSResult:
+    """TTS synthesis result."""
+    audio_bytes: bytes
+    format: str  # wav, mp3
+    sample_rate: int
+    engine_used: TTSEngine
+    duration_seconds: Optional[float] = None
+
+
+class TherapyTTS:
+    """
+    TTS engine for therapy applications.
+
+    Features:
+    - Voice cloning from reference audio
+    - Adjustable speed for therapy exercises
+    - Multiple engine support with fallback
+    """
+
+    def __init__(self, default_engine: TTSEngine = TTSEngine.AUTO):
+        self.default_engine = default_engine
+        self._whisperspeech_pipe = None
+        self._openai_client = None
+
+    def _get_openai_client(self):
+        """Lazy load OpenAI client."""
+        if self._openai_client is None:
+            from openai import OpenAI
+            self._openai_client = OpenAI(api_key=settings.OPENAI_API_KEY)
+        return self._openai_client
+
+    def _get_whisperspeech(self):
+        """Lazy load WhisperSpeech pipeline."""
+        if self._whisperspeech_pipe is None:
+            try:
+                from whisperspeech.pipeline import Pipeline
+                logging.info("Loading WhisperSpeech pipeline...")
+                self._whisperspeech_pipe = Pipeline(
+                    s2a_ref='collabora/whisperspeech:s2a-q4-tiny-en+pl.model'
+                )
+                logging.info("WhisperSpeech loaded successfully")
+            except ImportError as e:
+                logging.warning(f"WhisperSpeech not available: {e}")
+                raise
+        return self._whisperspeech_pipe
+
+    def _select_engine(self, voice_reference: Optional[bytes] = None) -> TTSEngine:
+        """Select TTS engine based on requirements."""
+        if self.default_engine != TTSEngine.AUTO:
+            return self.default_engine
+
+        # Use WhisperSpeech for voice cloning
+        if voice_reference:
+            return TTSEngine.WHISPERSPEECH
+
+        # Default to OpenAI for quality
+        return TTSEngine.OPENAI_TTS
+
+    def synthesize(
+        self,
+        text: str,
+        voice: TTSVoice = TTSVoice.NEUTRAL,
+        speed: float = 1.0,
+        voice_reference: Optional[bytes] = None,
+        engine: Optional[TTSEngine] = None,
+        output_format: str = "wav"
+    ) -> TTSResult:
+        """
+        Synthesize speech from text.
+
+        Args:
+            text: Text to synthesize
+            voice: Voice preset to use
+            speed: Speech rate (0.5 = slow, 1.0 = normal, 2.0 = fast)
+            voice_reference: Audio bytes for voice cloning
+            engine: Force specific engine
+            output_format: Output format (wav, mp3)
+
+        Returns:
+            TTSResult with audio bytes
+        """
+        selected_engine = engine or self._select_engine(voice_reference)
+        logging.info(f"Synthesizing with engine: {selected_engine.value}")
+
+        # Fallback chain
+        fallback_order = [selected_engine]
+        if selected_engine != TTSEngine.OPENAI_TTS:
+            fallback_order.append(TTSEngine.OPENAI_TTS)
+
+        last_error = None
+        for eng in fallback_order:
+            try:
+                if eng == TTSEngine.OPENAI_TTS:
+                    return self._synthesize_openai(text, voice, speed, output_format)
+                elif eng == TTSEngine.WHISPERSPEECH:
+                    return self._synthesize_whisperspeech(
+                        text, voice_reference, speed, output_format
+                    )
+                elif eng == TTSEngine.EDGE_TTS:
+                    return self._synthesize_edge_tts(text, voice, speed, output_format)
+            except Exception as e:
+                logging.warning(f"Engine {eng.value} failed: {e}")
+                last_error = e
+                continue
+
+        raise RuntimeError(f"All TTS engines failed. Last error: {last_error}")
+
+    def _synthesize_openai(
+        self,
+        text: str,
+        voice: TTSVoice,
+        speed: float,
+        output_format: str
+    ) -> TTSResult:
+        """Synthesize using OpenAI TTS API."""
+        logging.info("Synthesizing with OpenAI TTS")
+
+        client = self._get_openai_client()
+
+        # Map voice presets to OpenAI voices
+        voice_map = {
+            TTSVoice.NEUTRAL: "alloy",
+            TTSVoice.WARM: "nova",
+            TTSVoice.CLEAR: "onyx",
+            TTSVoice.SLOW: "alloy",  # Use speed parameter
+            TTSVoice.CUSTOM: "alloy",
+        }
+
+        response = client.audio.speech.create(
+            model="tts-1",
+            voice=voice_map.get(voice, "alloy"),
+            input=text,
+            speed=speed,
+            response_format="wav" if output_format == "wav" else "mp3"
+        )
+
+        audio_bytes = response.content
+
+        return TTSResult(
+            audio_bytes=audio_bytes,
+            format=output_format,
+            sample_rate=24000,
+            engine_used=TTSEngine.OPENAI_TTS
+        )
+
+    def _synthesize_whisperspeech(
+        self,
+        text: str,
+        voice_reference: Optional[bytes],
+        speed: float,
+        output_format: str
+    ) -> TTSResult:
+        """Synthesize using WhisperSpeech with optional voice cloning."""
+        logging.info("Synthesizing with WhisperSpeech")
+
+        import torch
+        import numpy as np
+
+        pipe = self._get_whisperspeech()
+
+        # Generate audio
+        if voice_reference:
+            # Voice cloning mode
+            import tempfile
+            import os
+
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                f.write(voice_reference)
+                ref_path = f.name
+
+            try:
+                audio = pipe.generate(text, speaker=ref_path)
+            finally:
+                os.unlink(ref_path)
+        else:
+            audio = pipe.generate(text)
+
+        # Convert to bytes
+        if isinstance(audio, torch.Tensor):
+            audio_np = audio.cpu().numpy()
+        else:
+            audio_np = np.array(audio)
+
+        # Ensure correct shape
+        if audio_np.ndim > 1:
+            audio_np = audio_np.squeeze()
+
+        # Apply speed adjustment if needed
+        if speed != 1.0:
+            import librosa
+            audio_np = librosa.effects.time_stretch(audio_np, rate=speed)
+
+        # Convert to wav bytes
+        import soundfile as sf
+        buffer = io.BytesIO()
+        sf.write(buffer, audio_np, 24000, format='WAV')
+        buffer.seek(0)
+
+        return TTSResult(
+            audio_bytes=buffer.read(),
+            format="wav",
+            sample_rate=24000,
+            engine_used=TTSEngine.WHISPERSPEECH,
+            duration_seconds=len(audio_np) / 24000
+        )
+
+    def _synthesize_edge_tts(
+        self,
+        text: str,
+        voice: TTSVoice,
+        speed: float,
+        output_format: str
+    ) -> TTSResult:
+        """Synthesize using Edge TTS (lightweight fallback)."""
+        logging.info("Synthesizing with Edge TTS")
+
+        import asyncio
+        import edge_tts
+
+        # Map voice presets to Edge TTS voices
+        voice_map = {
+            TTSVoice.NEUTRAL: "en-US-JennyNeural",
+            TTSVoice.WARM: "en-US-AriaNeural",
+            TTSVoice.CLEAR: "en-US-GuyNeural",
+            TTSVoice.SLOW: "en-US-JennyNeural",
+            TTSVoice.CUSTOM: "en-US-JennyNeural",
+        }
+
+        async def _generate():
+            communicate = edge_tts.Communicate(
+                text,
+                voice_map.get(voice, "en-US-JennyNeural"),
+                rate=f"{int((speed - 1) * 100):+d}%"
+            )
+            buffer = io.BytesIO()
+            async for chunk in communicate.stream():
+                if chunk["type"] == "audio":
+                    buffer.write(chunk["data"])
+            return buffer.getvalue()
+
+        audio_bytes = asyncio.run(_generate())
+
+        return TTSResult(
+            audio_bytes=audio_bytes,
+            format="mp3",
+            sample_rate=24000,
+            engine_used=TTSEngine.EDGE_TTS
+        )
+
+    def generate_therapy_prompt(
+        self,
+        exercise_type: str,
+        target_text: str,
+        **kwargs
+    ) -> TTSResult:
+        """
+        Generate therapy exercise audio prompt.
+
+        Args:
+            exercise_type: Type of exercise (repeat_after_me, pronunciation, etc.)
+            target_text: The text to practice
+            **kwargs: Additional synthesis parameters
+
+        Returns:
+            TTSResult with exercise audio
+        """
+        prompts = {
+            "repeat_after_me": f"Please repeat after me: {target_text}",
+            "pronunciation": f"Let's practice saying: {target_text}. Listen carefully.",
+            "slower": f"Now try saying it more slowly: {target_text}",
+            "word_by_word": f"Let's break it down. {target_text}",
+            "encouragement": f"Great try! Let's practice {target_text} again.",
+        }
+
+        prompt_text = prompts.get(exercise_type, target_text)
+
+        # Use slower speed for therapy prompts
+        speed = kwargs.pop("speed", 0.9)
+
+        return self.synthesize(
+            text=prompt_text,
+            speed=speed,
+            voice=TTSVoice.CLEAR,
+            **kwargs
+        )
+
+
+# Singleton instance
+_therapy_tts_instance: Optional[TherapyTTS] = None
+
+
+def get_therapy_tts() -> TherapyTTS:
+    """Get or create TherapyTTS singleton."""
+    global _therapy_tts_instance
+    if _therapy_tts_instance is None:
+        _therapy_tts_instance = TherapyTTS()
+    return _therapy_tts_instance
+
+
+def synthesize_speech(
+    text: str,
+    voice: TTSVoice = TTSVoice.NEUTRAL,
+    speed: float = 1.0,
+    voice_reference: Optional[bytes] = None
+) -> TTSResult:
+    """Convenience function for TTS synthesis."""
+    tts = get_therapy_tts()
+    return tts.synthesize(
+        text=text,
+        voice=voice,
+        speed=speed,
+        voice_reference=voice_reference
+    )

api/endpoints/v1/routers/analytics.py

@@ -0,0 +1,364 @@
+"""
+Analytics Router - Progress tracking and reporting endpoints.
+
+Endpoints:
+- GET /analytics/summary - User progress summary
+- GET /analytics/detailed - Detailed metrics for therapist view
+- GET /analytics/trends - Progress trends over time
+- GET /analytics/recommendations - AI-powered recommendations
+"""
+
+import logging
+from datetime import datetime, timedelta
+from typing import Optional
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel, Field
+
+from api.config import settings
+from api.endpoints.v1.auth.verify import verify_token
+
+router = APIRouter()
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+
+# ============================================================================
+# Response Models
+# ============================================================================
+
+class ProgressSummary(BaseModel):
+    """Summary of user's therapy progress."""
+    total_sessions: int
+    total_exercises: int
+    total_practice_minutes: int
+    current_streak_days: int
+    average_score: float
+    improvement_percent: float
+    last_session_date: Optional[str]
+    top_achievements: list[str]
+
+
+class MetricTrend(BaseModel):
+    """Single metric trend data point."""
+    date: str
+    value: float
+    metric_type: str
+
+
+class DetailedProgress(BaseModel):
+    """Detailed progress for therapist view."""
+    user_id: str
+    period_days: int
+
+    # Core metrics
+    pcc_current: float  # Percent Consonants Correct
+    pcc_baseline: float
+    pcc_improvement: float
+
+    pwc_current: float  # Percent Words Correct
+    pwc_baseline: float
+    pwc_improvement: float
+
+    clarity_current: float
+    clarity_baseline: float
+    clarity_improvement: float
+
+    # Session stats
+    sessions_completed: int
+    exercises_completed: int
+    total_practice_minutes: int
+
+    # Problem areas
+    problem_phonemes: list[str]
+    improving_phonemes: list[str]
+
+    # Recommendations
+    recommendations: list[str]
+
+
+class ExerciseStats(BaseModel):
+    """Statistics for a specific exercise type."""
+    exercise_type: str
+    attempts: int
+    average_score: float
+    best_score: float
+    improvement: float
+    last_attempted: Optional[str]
+
+
+class Recommendation(BaseModel):
+    """AI-generated recommendation."""
+    category: str  # exercise, frequency, focus_area
+    title: str
+    description: str
+    priority: int  # 1=high, 2=medium, 3=low
+    action_type: Optional[str]  # specific exercise to try
+
+
+# ============================================================================
+# Mock Data Functions (Replace with DB queries)
+# ============================================================================
+
+def _get_mock_summary(user_id: str, days: int) -> ProgressSummary:
+    """Generate mock summary data. Replace with DB queries."""
+    return ProgressSummary(
+        total_sessions=23,
+        total_exercises=156,
+        total_practice_minutes=287,
+        current_streak_days=5,
+        average_score=72.5,
+        improvement_percent=15.3,
+        last_session_date=datetime.now().strftime("%Y-%m-%d"),
+        top_achievements=[
+            "Completed 20+ sessions",
+            "5-day practice streak",
+            "Mastered 'S' sound"
+        ]
+    )
+
+
+def _get_mock_detailed(user_id: str, days: int) -> DetailedProgress:
+    """Generate mock detailed data. Replace with DB queries."""
+    return DetailedProgress(
+        user_id=user_id,
+        period_days=days,
+        pcc_current=78.5,
+        pcc_baseline=65.0,
+        pcc_improvement=13.5,
+        pwc_current=82.0,
+        pwc_baseline=70.0,
+        pwc_improvement=12.0,
+        clarity_current=75.0,
+        clarity_baseline=62.0,
+        clarity_improvement=13.0,
+        sessions_completed=23,
+        exercises_completed=156,
+        total_practice_minutes=287,
+        problem_phonemes=["th", "r", "l"],
+        improving_phonemes=["s", "ch", "sh"],
+        recommendations=[
+            "Focus on 'th' sound with tongue placement exercises",
+            "Increase practice frequency to 15 min/day",
+            "Try minimal pairs: 'think/sink', 'three/free'"
+        ]
+    )
+
+
+def _get_mock_trends(user_id: str, days: int, metric: str) -> list[MetricTrend]:
+    """Generate mock trend data. Replace with DB queries."""
+    trends = []
+    base_date = datetime.now()
+    base_value = 65.0
+
+    for i in range(min(days, 30)):
+        date = base_date - timedelta(days=days - i - 1)
+        # Simulate gradual improvement
+        value = base_value + (i * 0.5) + (i % 3 - 1)
+        trends.append(MetricTrend(
+            date=date.strftime("%Y-%m-%d"),
+            value=round(min(100, max(0, value)), 1),
+            metric_type=metric
+        ))
+
+    return trends
+
+
+def _get_mock_exercise_stats(user_id: str) -> list[ExerciseStats]:
+    """Generate mock exercise stats. Replace with DB queries."""
+    return [
+        ExerciseStats(
+            exercise_type="repeat_after_me",
+            attempts=45,
+            average_score=74.5,
+            best_score=92.0,
+            improvement=12.3,
+            last_attempted=datetime.now().strftime("%Y-%m-%d")
+        ),
+        ExerciseStats(
+            exercise_type="minimal_pairs",
+            attempts=32,
+            average_score=68.0,
+            best_score=85.0,
+            improvement=8.5,
+            last_attempted=(datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
+        ),
+        ExerciseStats(
+            exercise_type="tongue_twisters",
+            attempts=18,
+            average_score=62.5,
+            best_score=78.0,
+            improvement=5.2,
+            last_attempted=(datetime.now() - timedelta(days=2)).strftime("%Y-%m-%d")
+        ),
+    ]
+
+
+def _generate_recommendations(user_id: str) -> list[Recommendation]:
+    """Generate AI-powered recommendations. Replace with ML model."""
+    return [
+        Recommendation(
+            category="focus_area",
+            title="Focus on 'TH' Sound",
+            description="Your 'th' pronunciation scores are 15% below average. Try placing your tongue between your teeth.",
+            priority=1,
+            action_type="minimal_pairs"
+        ),
+        Recommendation(
+            category="frequency",
+            title="Increase Practice Time",
+            description="Users who practice 15+ minutes daily see 2x faster improvement. You're averaging 10 minutes.",
+            priority=2,
+            action_type=None
+        ),
+        Recommendation(
+            category="exercise",
+            title="Try Tongue Twisters",
+            description="Tongue twisters can help with your 'S' and 'SH' sounds. Start with 'She sells seashells'.",
+            priority=2,
+            action_type="tongue_twisters"
+        ),
+    ]
+
+
+# ============================================================================
+# Endpoints
+# ============================================================================
+
+@router.get("/summary", response_model=ProgressSummary, tags=["analytics"])
+async def get_progress_summary(
+    days: int = Query(default=30, ge=1, le=365, description="Period in days"),
+    user: str = Depends(verify_token),
+):
+    """
+    Get user's progress summary.
+
+    Returns high-level stats suitable for the user dashboard.
+    """
+    logging.info(f"Progress summary request for user: {user}, days: {days}")
+
+    # TODO: Replace with actual DB query
+    return _get_mock_summary(user, days)
+
+
+@router.get("/detailed", response_model=DetailedProgress, tags=["analytics"])
+async def get_detailed_progress(
+    days: int = Query(default=30, ge=1, le=365),
+    user: str = Depends(verify_token),
+):
+    """
+    Get detailed progress metrics.
+
+    Returns comprehensive metrics suitable for therapist review.
+    Includes PCC, PWC, clarity scores, and improvement tracking.
+    """
+    logging.info(f"Detailed progress request for user: {user}")
+
+    # TODO: Replace with actual DB query
+    return _get_mock_detailed(user, days)
+
+
+@router.get("/trends", response_model=list[MetricTrend], tags=["analytics"])
+async def get_progress_trends(
+    metric: str = Query(
+        default="overall",
+        description="Metric type: overall, clarity, pace, pcc, pwc"
+    ),
+    days: int = Query(default=30, ge=7, le=365),
+    user: str = Depends(verify_token),
+):
+    """
+    Get progress trends over time.
+
+    Returns time-series data for charting progress.
+    """
+    logging.info(f"Trends request for user: {user}, metric: {metric}")
+
+    valid_metrics = ["overall", "clarity", "pace", "pcc", "pwc", "fluency"]
+    if metric not in valid_metrics:
+        metric = "overall"
+
+    # TODO: Replace with actual DB query
+    return _get_mock_trends(user, days, metric)
+
+
+@router.get("/exercises", response_model=list[ExerciseStats], tags=["analytics"])
+async def get_exercise_stats(
+    user: str = Depends(verify_token),
+):
+    """
+    Get statistics for each exercise type.
+
+    Shows which exercises the user has tried and their performance.
+    """
+    logging.info(f"Exercise stats request for user: {user}")
+
+    # TODO: Replace with actual DB query
+    return _get_mock_exercise_stats(user)
+
+
+@router.get("/recommendations", response_model=list[Recommendation], tags=["analytics"])
+async def get_recommendations(
+    user: str = Depends(verify_token),
+):
+    """
+    Get AI-powered recommendations.
+
+    Analyzes user's progress and suggests focus areas, exercises, and practice tips.
+    """
+    logging.info(f"Recommendations request for user: {user}")
+
+    # TODO: Replace with ML model
+    return _generate_recommendations(user)
+
+
+@router.get("/streak", tags=["analytics"])
+async def get_streak_info(
+    user: str = Depends(verify_token),
+):
+    """
+    Get practice streak information.
+
+    Returns current streak, best streak, and streak history.
+    """
+    logging.info(f"Streak info request for user: {user}")
+
+    # TODO: Replace with actual DB query
+    return {
+        "current_streak": 5,
+        "best_streak": 12,
+        "streak_history": [
+            {"start": "2024-11-20", "end": "2024-12-01", "days": 12},
+            {"start": "2024-12-03", "end": "2024-12-05", "days": 3},
+            {"start": "2024-12-01", "end": None, "days": 5},  # Current
+        ],
+        "next_milestone": 7,
+        "days_to_milestone": 2
+    }
+
+
+@router.get("/leaderboard", tags=["analytics"])
+async def get_leaderboard(
+    period: str = Query(default="week", description="week, month, all"),
+    user: str = Depends(verify_token),
+):
+    """
+    Get anonymized leaderboard.
+
+    Optional gamification feature showing relative standing.
+    """
+    logging.info(f"Leaderboard request for period: {period}")
+
+    # TODO: Replace with actual DB query
+    return {
+        "user_rank": 15,
+        "total_users": 127,
+        "percentile": 88,
+        "top_10": [
+            {"rank": 1, "score": 95.2, "exercises": 234},
+            {"rank": 2, "score": 93.8, "exercises": 198},
+            {"rank": 3, "score": 91.5, "exercises": 212},
+        ]
+    }

api/endpoints/v1/routers/health.py

@@ -0,0 +1,24 @@
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import JSONResponse
+
+from api.endpoints.v1.auth.verify import verify_token
+
+router = APIRouter()
+
+
+@router.get("", status_code=200)
+async def check(user: str = Depends(verify_token)):
+    """Secured health check endpoint."""
+    if not user:
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+    return JSONResponse(
+        status_code=200,
+        content={
+            "message": "Service is running smoothly",
+            "batches_processed": 0,
+            "title": "title",
+            "content": "content",
+            "transcript": "hi",
+        },
+    )

api/endpoints/v1/routers/therapy.py

@@ -0,0 +1,639 @@
+"""
+Therapy Router - API endpoints for speech therapy features.
+
+Endpoints:
+- POST /therapy/transcribe - Transcribe audio with therapy-optimized ASR
+- POST /therapy/tts - Text-to-speech synthesis
+- POST /therapy/analyze - Pronunciation analysis
+- POST /therapy/exercise - Generate and evaluate exercises
+"""
+
+import io
+import logging
+from typing import Optional
+from fastapi import APIRouter, BackgroundTasks, Depends, File, HTTPException, UploadFile, Query
+from fastapi.responses import JSONResponse, StreamingResponse
+from pydantic import BaseModel, Field
+
+from api.config import settings
+from api.endpoints.v1.auth.verify import verify_token
+from api.endpoints.v1.processing.therapy_asr import (
+    transcribe_for_therapy,
+    ASREngine,
+    TranscriptionResult
+)
+from api.endpoints.v1.processing.therapy_tts import (
+    synthesize_speech,
+    get_therapy_tts,
+    TTSVoice,
+    TTSEngine
+)
+from api.endpoints.v1.processing.pronunciation_analysis import (
+    analyze_pronunciation,
+    PronunciationFeedback,
+    AIFeedback
+)
+from api.endpoints.v1.processing.ai_feedback import get_ai_feedback_generator
+
+router = APIRouter()
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+# Allowed audio types
+ALLOWED_AUDIO_TYPES = [
+    "audio/mpeg", "audio/mp4", "audio/m4a", "audio/x-m4a",
+    "audio/wav", "audio/x-wav", "audio/webm"
+]
+FILE_SIZE_LIMIT = 25 * 1024 * 1024  # 25 MB
+
+
+# Request/Response Models
+class TranscribeRequest(BaseModel):
+    """Request model for transcription."""
+    engine: Optional[ASREngine] = Field(None, description="ASR engine to use")
+    user_profile: Optional[dict] = Field(None, description="User speech profile")
+
+
+class TranscriptionResponse(BaseModel):
+    """Response model for transcription."""
+    text: str
+    engine_used: str
+    confidence: Optional[float] = None
+    word_timestamps: Optional[list] = None
+
+
+class TTSRequest(BaseModel):
+    """Request model for TTS."""
+    text: str = Field(..., min_length=1, max_length=5000)
+    voice: TTSVoice = Field(default=TTSVoice.NEUTRAL)
+    speed: float = Field(default=1.0, ge=0.5, le=2.0)
+    engine: Optional[TTSEngine] = None
+
+
+class PronunciationRequest(BaseModel):
+    """Request model for pronunciation analysis."""
+    target_text: str = Field(..., min_length=1, max_length=500)
+
+
+class AIFeedbackResponse(BaseModel):
+    """AI-generated feedback from GPT-4o."""
+    feedback: str
+    encouragement: str
+    specific_tips: list[str]
+    recommended_exercises: list[str]
+    difficulty_adjustment: Optional[str] = None
+
+
+class PronunciationResponse(BaseModel):
+    """Response model for pronunciation analysis."""
+    overall_score: float
+    clarity_score: float
+    pace_score: float
+    fluency_score: float
+    transcription: str
+    target_text: str
+    suggestions: list[str]
+    word_scores: list[dict]
+    ai_feedback: Optional[AIFeedbackResponse] = None  # GPT-4o powered feedback
+
+
+class ExerciseRequest(BaseModel):
+    """Request model for exercise generation."""
+    exercise_type: str = Field(..., description="Type: repeat_after_me, minimal_pairs, etc.")
+    difficulty: int = Field(default=1, ge=1, le=5)
+    focus_phonemes: Optional[list[str]] = None
+
+
+class ExerciseResponse(BaseModel):
+    """Response model for exercise."""
+    exercise_id: str
+    exercise_type: str
+    target_text: str
+    instructions: str
+    audio_prompt_available: bool
+
+
+# Endpoints
+
+@router.post("/transcribe", response_model=TranscriptionResponse, tags=["therapy"])
+async def transcribe_therapy_audio(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(...),
+    engine: Optional[ASREngine] = Query(None, description="ASR engine"),
+    user: str = Depends(verify_token),
+):
+    """
+    Transcribe audio using therapy-optimized ASR.
+
+    Supports multiple engines:
+    - whisper_api: OpenAI Whisper API (best accuracy)
+    - whisper_local: Local Whisper (privacy-focused)
+    - speechbrain: SpeechBrain (optimized for atypical speech)
+    - auto: Automatic selection based on user profile
+    """
+    logging.info(f"Therapy transcription request from user: {user}")
+
+    # Validate file
+    if file.content_type not in ALLOWED_AUDIO_TYPES:
+        raise HTTPException(status_code=400, detail="Invalid audio file type")
+
+    contents = await file.read()
+    if len(contents) > FILE_SIZE_LIMIT:
+        raise HTTPException(status_code=400, detail="File size exceeds 25 MB limit")
+
+    try:
+        result = transcribe_for_therapy(
+            audio_data=contents,
+            filename=file.filename or "audio.wav",
+            content_type=file.content_type,
+            engine=engine
+        )
+
+        return TranscriptionResponse(
+            text=result.text,
+            engine_used=result.engine_used.value,
+            confidence=result.confidence,
+            word_timestamps=result.word_timestamps
+        )
+
+    except Exception as e:
+        logging.error(f"Transcription failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Transcription failed: {str(e)}")
+
+
+@router.post("/tts", tags=["therapy"])
+async def text_to_speech(
+    request: TTSRequest,
+    user: str = Depends(verify_token),
+):
+    """
+    Convert text to speech.
+
+    Returns audio stream (WAV format).
+    """
+    logging.info(f"TTS request from user: {user}")
+
+    try:
+        result = synthesize_speech(
+            text=request.text,
+            voice=request.voice,
+            speed=request.speed
+        )
+
+        return StreamingResponse(
+            io.BytesIO(result.audio_bytes),
+            media_type=f"audio/{result.format}",
+            headers={
+                "Content-Disposition": f"attachment; filename=speech.{result.format}",
+                "X-Engine-Used": result.engine_used.value
+            }
+        )
+
+    except Exception as e:
+        logging.error(f"TTS failed: {e}")
+        raise HTTPException(status_code=500, detail=f"TTS failed: {str(e)}")
+
+
+@router.post("/tts/prompt", tags=["therapy"])
+async def generate_therapy_prompt(
+    exercise_type: str = Query(..., description="Type: repeat_after_me, pronunciation, slower"),
+    target_text: str = Query(..., description="Text to practice"),
+    user: str = Depends(verify_token),
+):
+    """
+    Generate audio prompt for therapy exercise.
+
+    Pre-built prompts like "Please repeat after me: [text]"
+    """
+    logging.info(f"Therapy prompt request: {exercise_type}")
+
+    try:
+        tts = get_therapy_tts()
+        result = tts.generate_therapy_prompt(exercise_type, target_text)
+
+        return StreamingResponse(
+            io.BytesIO(result.audio_bytes),
+            media_type=f"audio/{result.format}",
+            headers={
+                "Content-Disposition": f"attachment; filename=prompt.{result.format}"
+            }
+        )
+
+    except Exception as e:
+        logging.error(f"Prompt generation failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Prompt generation failed: {str(e)}")
+
+
+@router.post("/analyze", response_model=PronunciationResponse, tags=["therapy"])
+async def analyze_pronunciation_endpoint(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(...),
+    target_text: str = Query(..., description="Expected text/phrase"),
+    include_ai_feedback: bool = Query(True, description="Include GPT-4o AI feedback"),
+    user: str = Depends(verify_token),
+):
+    """
+    Analyze pronunciation against target text.
+
+    Returns scores for:
+    - Overall pronunciation
+    - Clarity
+    - Pace
+    - Fluency
+    Plus per-word feedback, improvement suggestions, and AI-powered personalized feedback.
+
+    AI feedback uses GPT-4o via GitHub Models API for free testing.
+    """
+    logging.info(f"Pronunciation analysis for user: {user}")
+
+    # Validate file
+    if file.content_type not in ALLOWED_AUDIO_TYPES:
+        raise HTTPException(status_code=400, detail="Invalid audio file type")
+
+    contents = await file.read()
+    if len(contents) > FILE_SIZE_LIMIT:
+        raise HTTPException(status_code=400, detail="File size exceeds 25 MB limit")
+
+    try:
+        # Now async with AI feedback integration
+        feedback = await analyze_pronunciation(
+            audio_bytes=contents,
+            target_text=target_text,
+            include_ai_feedback=include_ai_feedback
+        )
+
+        # Build AI feedback response if available
+        ai_feedback_response = None
+        if feedback.ai_feedback:
+            ai_feedback_response = AIFeedbackResponse(
+                feedback=feedback.ai_feedback.feedback,
+                encouragement=feedback.ai_feedback.encouragement,
+                specific_tips=feedback.ai_feedback.specific_tips,
+                recommended_exercises=feedback.ai_feedback.recommended_exercises,
+                difficulty_adjustment=feedback.ai_feedback.difficulty_adjustment
+            )
+
+        return PronunciationResponse(
+            overall_score=feedback.overall_score,
+            clarity_score=feedback.clarity_score,
+            pace_score=feedback.pace_score,
+            fluency_score=feedback.fluency_score,
+            transcription=feedback.transcription,
+            target_text=feedback.target_text,
+            suggestions=feedback.suggestions,
+            word_scores=[
+                {
+                    "word": ws.word,
+                    "score": ws.score,
+                    "errors": [
+                        {
+                            "type": e.error_type.value,
+                            "expected": e.expected,
+                            "actual": e.actual,
+                            "suggestion": e.suggestion
+                        }
+                        for e in ws.errors
+                    ]
+                }
+                for ws in feedback.word_scores
+            ],
+            ai_feedback=ai_feedback_response
+        )
+
+    except Exception as e:
+        logging.error(f"Pronunciation analysis failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")
+
+
+# ============================================================================
+# Demo/Test Endpoints (no auth required)
+# ============================================================================
+
+@router.get("/demo/exercises", tags=["therapy-demo"])
+async def demo_list_exercises():
+    """[DEMO] List exercises without auth - returns actual practice exercises."""
+    return {
+        "exercises": [
+            {
+                "id": "ex-001",
+                "title": "Simple Greetings",
+                "category": "repeat_after_me",
+                "difficulty": "easy",
+                "target_text": "Hello, how are you today?",
+                "instructions": "Listen carefully, then repeat the greeting clearly and naturally."
+            },
+            {
+                "id": "ex-002",
+                "title": "S Sound Practice",
+                "category": "minimal_pairs",
+                "difficulty": "medium",
+                "target_text": "She sells seashells by the seashore",
+                "instructions": "Focus on the 'S' and 'SH' sounds. Speak slowly at first."
+            },
+            {
+                "id": "ex-003",
+                "title": "R Sound Challenge",
+                "category": "tongue_twisters",
+                "difficulty": "hard",
+                "target_text": "Red lorry, yellow lorry",
+                "instructions": "Practice the 'R' and 'L' sounds. Start slow, then speed up."
+            },
+            {
+                "id": "ex-004",
+                "title": "Daily Introduction",
+                "category": "repeat_after_me",
+                "difficulty": "easy",
+                "target_text": "My name is... and I am learning to speak clearly.",
+                "instructions": "Replace '...' with your name. Speak with confidence!"
+            },
+            {
+                "id": "ex-005",
+                "title": "TH Sound Practice",
+                "category": "minimal_pairs",
+                "difficulty": "medium",
+                "target_text": "Think through these three things thoroughly",
+                "instructions": "Place your tongue between your teeth for the 'TH' sound."
+            },
+            {
+                "id": "ex-006",
+                "title": "Peter Piper",
+                "category": "tongue_twisters",
+                "difficulty": "hard",
+                "target_text": "Peter Piper picked a peck of pickled peppers",
+                "instructions": "Focus on the 'P' sounds. Keep your lips together firmly."
+            },
+            {
+                "id": "ex-007",
+                "title": "Counting Practice",
+                "category": "repeat_after_me",
+                "difficulty": "easy",
+                "target_text": "One, two, three, four, five",
+                "instructions": "Count clearly and pause briefly between each number."
+            },
+            {
+                "id": "ex-008",
+                "title": "W vs V Sounds",
+                "category": "minimal_pairs",
+                "difficulty": "medium",
+                "target_text": "Very well, we will wait",
+                "instructions": "Notice the difference: 'V' uses teeth on lip, 'W' uses rounded lips."
+            }
+        ]
+    }
+
+
+@router.post("/demo/feedback", tags=["therapy-demo"])
+async def demo_ai_feedback(
+    target_text: str = Query(..., description="Text to practice"),
+    transcription: str = Query(..., description="What user said"),
+    score: float = Query(75.0, description="Overall score 0-100"),
+):
+    """[DEMO] Get AI feedback without auth - for testing GPT-4o integration."""
+    generator = get_ai_feedback_generator()
+
+    feedback = await generator.generate_feedback(
+        target_text=target_text,
+        transcription=transcription,
+        overall_score=score,
+        clarity_score=score - 5,
+        pace_score=score + 5,
+        fluency_score=score,
+        errors=[{
+            "word": target_text.split()[0] if target_text else "word",
+            "expected": target_text.split()[0] if target_text else "word",
+            "actual": transcription.split()[0] if transcription else "word",
+            "error_type": "substitution"
+        }] if target_text != transcription else [],
+        user_context=None
+    )
+
+    return {
+        "target_text": target_text,
+        "transcription": transcription,
+        "scores": {
+            "overall": score,
+            "clarity": score - 5,
+            "pace": score + 5,
+            "fluency": score
+        },
+        "ai_feedback": {
+            "feedback": feedback.feedback,
+            "encouragement": feedback.encouragement,
+            "specific_tips": feedback.specific_tips,
+            "recommended_exercises": feedback.recommended_exercises,
+            "difficulty_adjustment": feedback.difficulty_adjustment
+        }
+    }
+
+
+@router.get("/demo/session-summary", tags=["therapy-demo"])
+async def demo_session_summary():
+    """[DEMO] Get AI session summary without auth."""
+    generator = get_ai_feedback_generator()
+
+    summary = await generator.generate_session_summary(
+        session_stats={
+            "duration_minutes": 12,
+            "exercise_count": 6,
+            "average_score": 78,
+            "best_score": 92,
+            "exercise_types": ["repeat_after_me", "minimal_pairs"]
+        },
+        attempts=[]
+    )
+
+    return {"summary": summary}
+
+
+@router.get("/demo/weekly-insights", tags=["therapy-demo"])
+async def demo_weekly_insights():
+    """[DEMO] Get AI weekly insights without auth."""
+    generator = get_ai_feedback_generator()
+
+    insights = await generator.generate_weekly_insights(
+        weekly_data={
+            "sessions_this_week": 5,
+            "practice_minutes": 40,
+            "avg_score": 76,
+            "score_change": 6.5,
+            "strengths": ["Consistent daily practice", "Good pace control"],
+            "weaknesses": ["S sounds", "Word endings"]
+        }
+    )
+
+    return insights
+
+
+# ============================================================================
+# Authenticated Endpoints
+# ============================================================================
+
+@router.get("/exercises", tags=["therapy"])
+async def list_exercise_types(
+    user: str = Depends(verify_token),
+):
+    """List available therapy exercise types."""
+    return {
+        "exercises": [
+            {
+                "type": "repeat_after_me",
+                "name": "Repeat After Me",
+                "description": "Listen and repeat the target phrase"
+            },
+            {
+                "type": "minimal_pairs",
+                "name": "Minimal Pairs",
+                "description": "Practice similar-sounding words (e.g., ship/chip)"
+            },
+            {
+                "type": "tongue_twisters",
+                "name": "Tongue Twisters",
+                "description": "Practice challenging phrases for fluency"
+            },
+            {
+                "type": "word_chains",
+                "name": "Word Chains",
+                "description": "Build vocabulary with connected words"
+            },
+            {
+                "type": "sentence_building",
+                "name": "Sentence Building",
+                "description": "Progress from words to full sentences"
+            }
+        ]
+    }
+
+
+@router.post("/exercise/evaluate", response_model=PronunciationResponse, tags=["therapy"])
+async def evaluate_exercise(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(...),
+    exercise_type: str = Query(...),
+    target_text: str = Query(...),
+    include_ai_feedback: bool = Query(True),
+    user: str = Depends(verify_token),
+):
+    """
+    Evaluate user's exercise attempt.
+
+    Same as /analyze but tracks exercise context.
+    Includes GPT-4o AI feedback for personalized improvement tips.
+    """
+    # Reuse pronunciation analysis
+    return await analyze_pronunciation_endpoint(
+        background_tasks=background_tasks,
+        file=file,
+        target_text=target_text,
+        include_ai_feedback=include_ai_feedback,
+        user=user
+    )
+
+
+# Session Summary Models
+class SessionSummaryRequest(BaseModel):
+    """Request for session summary."""
+    duration_minutes: int = Field(..., ge=1)
+    exercise_count: int = Field(..., ge=1)
+    average_score: float = Field(..., ge=0, le=100)
+    best_score: float = Field(..., ge=0, le=100)
+    exercise_types: list[str] = Field(default_factory=list)
+
+
+class SessionSummaryResponse(BaseModel):
+    """AI-generated session summary."""
+    summary: str
+
+
+class WeeklyInsightsRequest(BaseModel):
+    """Request for weekly insights."""
+    sessions_this_week: int = Field(..., ge=0)
+    practice_minutes: int = Field(..., ge=0)
+    avg_score: float = Field(..., ge=0, le=100)
+    score_change: float = Field(default=0)  # Percentage change from last week
+    strengths: list[str] = Field(default_factory=list)
+    weaknesses: list[str] = Field(default_factory=list)
+
+
+class WeeklyInsightsResponse(BaseModel):
+    """AI-generated weekly insights."""
+    summary: str
+    celebration: str
+    focus_area: str
+    goal: str
+
+
+@router.post("/session/summary", response_model=SessionSummaryResponse, tags=["therapy"])
+async def get_session_summary(
+    request: SessionSummaryRequest,
+    user: str = Depends(verify_token),
+):
+    """
+    Generate AI-powered session summary.
+
+    Uses GPT-4o via GitHub Models to create personalized,
+    encouraging session summaries.
+    """
+    logging.info(f"Session summary request from user: {user}")
+
+    try:
+        ai_generator = get_ai_feedback_generator()
+        summary = await ai_generator.generate_session_summary(
+            session_stats={
+                "duration_minutes": request.duration_minutes,
+                "exercise_count": request.exercise_count,
+                "average_score": request.average_score,
+                "best_score": request.best_score,
+                "exercise_types": request.exercise_types
+            },
+            attempts=[]  # Can be extended to include attempt history
+        )
+
+        return SessionSummaryResponse(summary=summary)
+
+    except Exception as e:
+        logging.error(f"Session summary generation failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Summary generation failed: {str(e)}")
+
+
+@router.post("/insights/weekly", response_model=WeeklyInsightsResponse, tags=["therapy"])
+async def get_weekly_insights(
+    request: WeeklyInsightsRequest,
+    user: str = Depends(verify_token),
+):
+    """
+    Generate AI-powered weekly progress insights.
+
+    Uses GPT-4o to analyze weekly practice data and provide:
+    - Progress summary
+    - Celebration of achievements
+    - Focus area for next week
+    - Realistic goal setting
+    """
+    logging.info(f"Weekly insights request from user: {user}")
+
+    try:
+        ai_generator = get_ai_feedback_generator()
+        insights = await ai_generator.generate_weekly_insights(
+            weekly_data={
+                "sessions_this_week": request.sessions_this_week,
+                "practice_minutes": request.practice_minutes,
+                "avg_score": request.avg_score,
+                "score_change": request.score_change,
+                "strengths": request.strengths,
+                "weaknesses": request.weaknesses
+            }
+        )
+
+        return WeeklyInsightsResponse(
+            summary=insights.get("summary", ""),
+            celebration=insights.get("celebration", ""),
+            focus_area=insights.get("focus_area", ""),
+            goal=insights.get("goal", "")
+        )
+
+    except Exception as e:
+        logging.error(f"Weekly insights generation failed: {e}")
+        raise HTTPException(status_code=500, detail=f"Insights generation failed: {str(e)}")

api/endpoints/v1/routers/upload.py

@@ -0,0 +1,82 @@
+import io
+import logging
+
+from fastapi import APIRouter, BackgroundTasks, Depends, File, HTTPException, UploadFile
+from fastapi.responses import JSONResponse
+
+from api.config import settings
+from api.endpoints.v1.auth.verify import verify_token
+from api.endpoints.v1.processing.audio import transcribe_with_whisper
+from api.endpoints.v1.processing.soap import generate_soap
+
+router = APIRouter()
+
+if settings.ENVIRONMENT == "development":
+    logging.basicConfig(level=logging.DEBUG)
+else:
+    logging.basicConfig(level=logging.WARNING)
+
+# OpenAI Whisper supports the following file types
+ALLOWED_FILE_TYPES = [
+    "audio/mpeg",
+    "audio/mp4",
+    "audio/m4a",
+    "audio/x-m4a",
+    "audio/wav",
+    "audio/x-wav",
+    "audio/webm",
+    "video/mp4",
+    "video/mpeg",
+]
+# OpenAI Whisper file uploads are currently limited to 25 MB
+FILE_SIZE_LIMIT = 25 * 1024 * 1024  # 25 MB in bytes
+
+
+@router.post("", status_code=200)
+async def transcribe_audio(
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(...),
+    user: str = Depends(verify_token),
+):
+    """Endpoint to upload and process audio files with OpenAI Whisper."""
+
+    logging.info(f"Transcribing audio file: {file.filename}")
+    logging.debug(f"Audio file mime type: {file.content_type}")
+
+    # Check file type
+    if file.content_type not in ALLOWED_FILE_TYPES:
+        raise HTTPException(status_code=400, detail="Invalid file type")
+
+    # Check file size
+    contents = await file.read()
+    logging.debug(f"size: {len(contents)} bytes")
+    if len(contents) > FILE_SIZE_LIMIT:
+        raise HTTPException(status_code=400, detail="File size exceeds 25 MB limit")
+
+    try:
+        # Use BytesIO to handle the file in-memory
+        file_like = io.BytesIO(contents)
+
+        # Reset the buffer's position to the start (not needed with await?)
+        file_like.seek(0)
+
+        # Add a background task to close the buffer after processing
+        background_tasks.add_task(file_like.close)
+
+        # Pass the file-like object to the transcription function
+        transcription = transcribe_with_whisper(
+            file.filename, file_like, file.content_type
+        )
+
+        # Generate a SOAP note from the transcription
+        soap_note = generate_soap(transcription.text)
+
+        return JSONResponse(
+            content={
+                "message": f"File processed successfully by user {user}",
+                "content": soap_note,
+                "transcription": transcription.text,
+            }
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"An error occurred: {str(e)}")

api/endpoints/v1/therapy/__init__.py

@@ -0,0 +1 @@
+"""Therapy module - Speech therapy exercises and analysis."""

api/endpoints/v1/utils.py

@@ -0,0 +1,7 @@
+from datetime import datetime, timezone
+
+
+# Function to parse RFC 3339 datetime and convert to epoch time
+def parse_rfc3339(time_str):
+    dt = datetime.fromisoformat(time_str.replace("Z", "+00:00"))
+    return dt.replace(tzinfo=timezone.utc).timestamp()

api/index.py

@@ -0,0 +1,5 @@
+# Vercel serverless entry point
+from api.main import app
+
+# Handler for Vercel
+handler = app

api/main.py

@@ -0,0 +1,63 @@
+import logging
+
+from fastapi import APIRouter, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.routing import APIRoute
+
+from api.config import settings
+from api.endpoints.v1.api import api_router
+
+info_router = APIRouter()
+
+
+@info_router.get("/", status_code=200, include_in_schema=False)
+async def info():
+    return [{"Status": "API Running"}]
+
+
+@info_router.get("/health", status_code=200, tags=["health"])
+async def health_check():
+    """Health check endpoint for Railway deployment"""
+    return {"status": "healthy", "service": "ubumuntu-api"}
+
+
+def custom_generate_unique_id(route: APIRoute):
+    """Generates a custom ID when using the TypeScript Generator Client
+
+    Args:
+        route (APIRoute): The route to be customised
+
+    Returns:
+        str: tag-route_name, e.g. items-CreateItem
+    """
+    return f"{route.tags[0]}-{route.name}"
+
+
+def get_application():
+    _app = FastAPI(
+        title=settings.PROJECT_NAME,
+        description=settings.PROJECT_DESCRIPTION,
+        generate_unique_id_function=custom_generate_unique_id,
+        root_path=settings.ROOT,
+        root_path_in_servers=True,
+        openapi_url=settings.openapi_url,
+    )
+
+    # Allow all origins for demo - in production, restrict to specific domains
+    logger = logging.getLogger("uvicorn")
+    logger.info("Enabling CORS for all origins (demo mode)")
+    _app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    _app.include_router(api_router, prefix=settings.API_VERSION)
+    _app.include_router(info_router, tags=[""])
+
+    return _app
+
+
+app = get_application()

app.py

@@ -0,0 +1,5 @@
+# HuggingFace Spaces entry point
+from api.main import app
+
+# Re-export for uvicorn
+__all__ = ["app"]

requirements.txt

@@ -0,0 +1,10 @@
+fastapi
+uvicorn[standard]
+pydantic
+pydantic-settings
+python-dotenv
+python-jose[cryptography]
+python-multipart
+openai
+httpx
+requests