feat: complete production hardening implementation, specialty canonicalization, google-genai migration, voice reliability, sqlite concurrency, and test suite consolidation

ai-patient-onboarding/app/ai/conversation/__init__.py

@@ -0,0 +1,21 @@
+"""
+Conversation package.
+"""
+
+from app.ai.conversation.question_engine import pick_best_question
+from app.ai.conversation.completion_engine import check_required_missing, field_status, is_onboarding_complete
+from app.ai.conversation.intent_tracker import get_last_ai_intent
+from app.ai.conversation.response_formatter import format_conversational_response
+from app.ai.conversation.next_best_action import NextBestActionEngine
+from app.ai.conversation.response_generator import ResponseGenerator
+
+__all__ = [
+    "pick_best_question",
+    "check_required_missing",
+    "field_status",
+    "is_onboarding_complete",
+    "get_last_ai_intent",
+    "format_conversational_response",
+    "NextBestActionEngine",
+    "ResponseGenerator",
+]

ai-patient-onboarding/app/ai/conversation/completion_engine.py

@@ -0,0 +1,84 @@
+"""
+Deterministic completion evaluation engine. Single source of truth for onboarding completion.
+"""
+
+from typing import Dict, Any, List
+
+
+def field_status(field_val: Any) -> str:
+    """
+    Returns field status: 'not_collected' | 'reported' | 'confirmed_none' | 'unknown' | 'declined'
+    """
+    if field_val is None:
+        return "not_collected"
+
+    if isinstance(field_val, dict):
+        status = field_val.get("status")
+        if status in ["reported", "confirmed_none", "unknown", "declined"]:
+            return status
+        items = field_val.get("items", [])
+        return "reported" if items else "not_collected"
+
+    if isinstance(field_val, list):
+        return "reported" if len(field_val) > 0 else "not_collected"
+
+    if isinstance(field_val, str) and field_val.strip():
+        return "reported"
+
+    return "not_collected"
+
+
+def check_required_missing(state: Dict[str, Any]) -> List[str]:
+    """
+    Single source of truth evaluating missing clinical fields for onboarding completion.
+    Required fields: reason_for_visit, symptoms, duration, medical_history, medications, allergies.
+    """
+    if not isinstance(state, dict):
+        state = {}
+
+    missing: List[str] = []
+
+    # 1. Reason for Visit
+    if field_status(state.get("reason_for_visit")) == "not_collected":
+        missing.append("reason_for_visit")
+
+    # 2. Symptoms
+    symptoms = state.get("symptoms", [])
+    sym_status = field_status(symptoms)
+    if sym_status == "not_collected":
+        missing.append("symptoms")
+
+    # 3. Duration
+    has_duration = False
+    if isinstance(symptoms, list) and symptoms:
+        for s in symptoms:
+            if isinstance(s, dict) and s.get("duration"):
+                has_duration = True
+                break
+    if not has_duration and state.get("duration"):
+        has_duration = True
+
+    if sym_status != "not_collected" and not has_duration:
+        missing.append("duration")
+
+    # 4. Medical History
+    if field_status(state.get("medical_history")) == "not_collected":
+        missing.append("medical_history")
+
+    # 5. Medications
+    if field_status(state.get("medications")) == "not_collected":
+        missing.append("medications")
+
+    # 6. Allergies
+    if field_status(state.get("allergies")) == "not_collected":
+        missing.append("allergies")
+
+    return missing
+
+
+def is_onboarding_complete(state: Dict[str, Any]) -> bool:
+    """
+    Returns True ONLY if all required fields are collected or confirmed_none.
+    """
+    missing = check_required_missing(state)
+    return len(missing) == 0

ai-patient-onboarding/app/ai/conversation/intent_tracker.py

@@ -0,0 +1,26 @@
+"""
+Question intent tracker for semantic question deduplication.
+"""
+
+from typing import Optional, List, Dict, Any
+
+from app.services.contextual_normalizer import detect_previous_question_intent
+
+
+def get_last_ai_intent(conversation_history: List[Dict[str, Any]]) -> Optional[str]:
+    """
+    Returns the intent code of the last AI message in conversation history.
+    """
+    if not conversation_history:
+        return None
+
+    last_ai_msg = None
+    for turn in reversed(conversation_history):
+        if turn.get("role") in ["assistant", "ai"]:
+            last_ai_msg = turn.get("message") or turn.get("content")
+            break
+
+    if last_ai_msg:
+        return detect_previous_question_intent(last_ai_msg)
+
+    return None

ai-patient-onboarding/app/ai/conversation/next_best_action.py

@@ -0,0 +1,98 @@
+"""
+NextBestActionEngine (Rules 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91):
+- Conversational State Machine Evaluation
+- Priority Scoring & Action Selection
+- Cooldown & Intent Deduplication
+- Status-aware field tracking (reported, confirmed_none, unknown, declined, skipped, not_asked)
+"""
+
+from typing import Dict, Any, List, Optional, Tuple
+
+
+class NextBestActionEngine:
+    """
+    Evaluates intake state and determines the next-best action and target question.
+    """
+
+    def calculate_priority_score(
+        self,
+        field: str,
+        current_state: Dict[str, Any],
+        is_psych: bool = False,
+        asked_intents: Optional[List[str]] = None
+    ) -> float:
+        """
+        Calculates question priority score based on Rule 83:
+        priority = safety_weight + clinical_importance + symptom_completeness
+                   + specialty_relevance + information_value
+                   - repetition_penalty - already_answered_penalty - unnecessary_question_penalty
+        """
+        score = 0.0
+        asked_intents = asked_intents or []
+
+        weights = {
+            "emergency": 100.0,
+            "crisis": 100.0,
+            "reason_for_visit": 50.0,
+            "symptoms": 50.0,
+            "duration": 45.0,
+            "severity": 30.0,
+            "medical_history": 35.0,
+            "medications": 30.0,
+            "allergies": 25.0,
+            "previous_episodes": 15.0,
+            "family_history": 10.0,
+            "additional_information": 5.0,
+        }
+
+        score += weights.get(field, 10.0)
+
+        # Repetition penalty (Rule 84 & 85)
+        if field in asked_intents:
+            score -= 60.0
+
+        # Specialty relevance bonus
+        if is_psych and field in ["duration", "medical_history"]:
+            score += 10.0
+
+        return score
+
+    def determine_next_action(
+        self,
+        current_state: Dict[str, Any],
+        is_emergency: bool = False,
+        is_crisis: bool = False,
+        is_psych: bool = False,
+        missing_fields: Optional[List[str]] = None
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Returns (action_type, target_field)
+        Action types (Rule 82):
+        - SAFETY_ACTION
+        - CLARIFY
+        - ASK_QUESTION
+        - COMPLETE
+        - HANDLE_REFUSAL
+        - HANDLE_UNKNOWN
+        """
+        if is_crisis or is_emergency:
+            return "SAFETY_ACTION", None
+
+        # Check for state conflicts requiring clarification (Rule 67)
+        if current_state and current_state.get("conflicts"):
+            return "CLARIFY", current_state["conflicts"][-1].get("field")
+
+        missing_fields = missing_fields or []
+        if not missing_fields:
+            return "COMPLETE", None
+
+        # Score missing fields using priority score (Rule 83)
+        scored_fields = []
+        for field in missing_fields:
+            score = self.calculate_priority_score(field, current_state, is_psych=is_psych)
+            scored_fields.append((score, field))
+
+        scored_fields.sort(key=lambda x: x[0], reverse=True)
+        best_field = scored_fields[0][1]
+
+        return "ASK_QUESTION", best_field

ai-patient-onboarding/app/ai/conversation/question_engine.py

@@ -0,0 +1,168 @@
+"""
+Priority-based Question Engine. Selects the single highest priority missing question.
+"""
+
+from typing import List, Optional, Dict, Any
+
+
+def pick_best_question(
+    missing_list: List[str],
+    lang: str,
+    is_psych: bool = False,
+    current_state: Optional[Dict[str, Any]] = None
+) -> str:
+    """
+    Picks the single highest priority missing question for onboarding.
+    Enforces Rule 51 & 52: Short, natural, 1-2 sentences, max 15-20 words.
+    Enforces Rule 67: Asks short clarification if conflict detected in state.
+    """
+    if isinstance(current_state, dict) and current_state.get("conflicts"):
+        conflict = current_state["conflicts"][-1]
+        item = conflict.get("item", "this condition")
+        if isinstance(item, dict):
+            item = item.get("condition") or item.get("name") or "this condition"
+        lang_clean = lang.lower() if lang else "en"
+        if lang_clean.startswith("ta"):
+            return f"உறுதிப்படுத்த கேட்கிறேன், உங்களுக்கு {item} இருக்கா?"
+        elif lang_clean.startswith("hi"):
+            return f"पुष्टि के लिए, क्या आपको {item} की समस्या है?"
+        else:
+            return f"Just to confirm, do you currently have {item}?"
+
+    if not missing_list:
+        return _build_completion_reply(lang)
+
+    field = missing_list[0]
+    has_meds = "medications" in missing_list
+    has_algs = "allergies" in missing_list
+    has_history = "medical_history" in missing_list
+
+    combine_meds_algs = (field == "medications" and has_algs) or (field == "allergies" and has_meds)
+    combine_history_meds = (field == "medical_history" and has_meds and not has_algs)
+
+    symptom_name = None
+    if isinstance(current_state, dict):
+        rfv = current_state.get("reason_for_visit")
+        syms = current_state.get("symptoms", [])
+        if rfv and isinstance(rfv, str) and rfv.strip():
+            symptom_name = rfv.strip()
+        elif syms and isinstance(syms, list) and len(syms) > 0 and isinstance(syms[0], dict) and syms[0].get("name"):
+            symptom_name = syms[0].get("name").strip()
+
+    lang_clean = lang.lower() if lang else "en"
+
+    # Tamil
+    if lang_clean.startswith("ta"):
+        if field in ["reason_for_visit", "symptoms"]:
+            return "வணக்கம், உங்களுக்கு என்ன பிரச்சனை இருக்கு?"
+        elif field == "duration":
+            if is_psych:
+                return "இந்த மன அழுத்தம் எப்போலிருந்து இருக்கு?"
+            if symptom_name:
+                return f"இந்த {symptom_name} எத்தனை நாளா இருக்கு?"
+            return "இந்த பிரச்சனை எத்தனை நாளா இருக்கு?"
+        elif field == "medical_history":
+            if is_psych:
+                return "முன்னாடி இதுக்கு சிகிச்சை எடுத்திருக்கீங்களா?"
+            if symptom_name:
+                return f"{symptom_name} தவிர பிபி, சுகர் போன்ற பிரச்சனை இருக்கா?"
+            return "உங்களுக்கு பிபி, சுகர் போன்ற வேறு உடம்பு பிரச்சனை இருக்கா?"
+        elif field == "medications":
+            return "வழக்கமா ஏதேனும் மாத்திரை சாப்பிடுறீங்களா?"
+        elif field == "allergies":
+            return "உங்களுக்கு ஏதேனும் அலர்ஜி இருக்கா?"
+
+    # Hindi
+    elif lang_clean.startswith("hi"):
+        if field in ["reason_for_visit", "symptoms"]:
+            return "नमस्ते, आपको क्या तकलीफ हो रही है?"
+        elif field == "duration":
+            if symptom_name:
+                return f"यह {symptom_name} कितने दिनों से है?"
+            return "यह तकलीफ कितने दिनों से हो रही है?"
+        elif field == "medical_history":
+            if symptom_name:
+                return f"{symptom_name} के अलावा क्या बीपी या शुगर जैसी बीमारी है?"
+            return "क्या आपको बीपी या शुगर जैसी कोई बीमारी है?"
+        elif field == "medications":
+            return "क्या आप नियमित रूप से कोई दवाई लेते हैं?"
+        elif field == "allergies":
+            return "क्या आपको किसी दवाई से एलर्जी है?"
+
+    # Telugu
+    elif lang_clean.startswith("te"):
+        if field in ["reason_for_visit", "symptoms"]:
+            return "నమస్కారం, మీ ఆరోగ్య సమస్య ఏమిటి?"
+        elif field == "duration":
+            if symptom_name:
+                return f"ఈ {symptom_name} ఎన్ని రోజుల నుండి ఉంది?"
+            return "ఈ ఇబ్బంది ఎన్ని రోజుల నుండి ఉంది?"
+        elif field == "medical_history":
+            if symptom_name:
+                return f"అర్థమైంది, {symptom_name} కాకుండా బీపీ లేదా షుగర్ ఉందా?"
+            return "మీకు బీపీ లేదా షుగర్ వంటి సమస్యలు ఉన్నాయా?"
+        elif field == "medications":
+            return "మీరు రోజూ ఏమైనా మందులు వాడుతున్నారా?"
+        elif field == "allergies":
+            return "మీకు ఏదైనా మందుల అలర్జీ ఉందా?"
+
+    # Kannada
+    elif lang_clean.startswith("kn"):
+        if field in ["reason_for_visit", "symptoms"]:
+            return "ನಮಸ್ಕಾರ, ನಿಮ್ಮ સમસ્યા ಏನು?"
+        elif field == "duration":
+            if symptom_name:
+                return f"ಈ {symptom_name} ಎಷ್ಟು ದಿನದಿಂದ ಇದೆ?"
+            return "ಈ ತೊಂದರೆ ಎಷ್ಟು ದಿನದಿಂದ ಇದೆ?"
+        elif field == "medical_history":
+            if symptom_name:
+                return f"{symptom_name} ಹೊರತುಪಡಿಸಿ ಬಿಪಿ ಅಥವಾ ಶುಗರ್ ಇದೆಯಾ?"
+            return "ನಿಮಗೆ ಬಿಪಿ ಅಥವಾ ಶುಗರ್ ಇದೆಯಾ?"
+        elif field == "medications":
+            return "ನೀವು ಯಾವುದೇ ಮಾತ್ರೆಗಳನ್ನು ತೆಗೆದುಕೊಳ್ಳುತ್ತಿದ್ದೀರಾ?"
+        elif field == "allergies":
+            return "ನಿಮಗೆ ಯಾವುದೇ ಅಲರ್ಜಿ ಇದೆಯಾ?"
+
+    # English Default (Rule 51 & 52: Short, natural, <15-20 words)
+    if field in ["reason_for_visit", "symptoms"]:
+        return "Hello, what symptoms are you experiencing today?"
+    elif field == "duration":
+        if symptom_name:
+            return f"Got it. How long have you had this {symptom_name}?"
+        return "Got it. How long have you had these symptoms?"
+    elif combine_history_meds:
+        if symptom_name:
+            return f"Apart from {symptom_name}, do you have BP, diabetes, or take regular medicines?"
+        return "Do you have any past health conditions or take regular medicines?"
+    elif combine_meds_algs:
+        if symptom_name:
+            return f"Are you taking regular medications for {symptom_name}, or do you have any allergies?"
+        return "Are you currently taking any regular medications, or do you have any allergies?"
+    elif field == "medical_history":
+        if is_psych:
+            return "Have you received treatment or counseling for this before?"
+        if symptom_name:
+            return f"Apart from {symptom_name}, do you have BP, diabetes, or other chronic conditions?"
+        return "Do you have a history of BP, diabetes, or other health conditions?"
+    elif field == "medications":
+        if symptom_name:
+            return f"Are you taking any daily medicines for {symptom_name} or other conditions?"
+        return "Are you currently taking any regular daily medications?"
+    elif field == "allergies":
+        return "Do you have any medicine or food allergies?"
+
+    return "Could you share any other details about your symptoms?"
+
+
+def _build_completion_reply(lang: str) -> str:
+    lang_clean = lang.lower() if lang else "en"
+    if lang_clean.startswith("ta"):
+        return "நன்றி. உங்கள் விவரங்கள் பதிவு செய்யப்பட்டன."
+    elif lang_clean.startswith("hi"):
+        return "ठीक है, आपकी जानकारी दर्ज हो गई है।"
+    elif lang_clean.startswith("te"):
+        return "ధన్యవాదాలు, మీ వివరాలు నమోదు చేయబడ్డాయి."
+    elif lang_clean.startswith("kn"):
+        return "ಧನ್ಯವಾದಗಳು, ನಿಮ್ಮ ವಿವರಗಳನ್ನು ದಾಖಲಿಸಲಾಗಿದೆ."
+    else:
+        return "Thanks. Your onboarding is complete."

ai-patient-onboarding/app/ai/conversation/question_templates.py

@@ -0,0 +1,57 @@
+"""
+Deterministic Question Templates (Rule 107 & 108):
+Fallback question templates mapped to semantic QuestionIntent across supported languages.
+"""
+
+from typing import Dict, List
+from app.domain.models.contracts import QuestionIntent
+
+
+QUESTION_TEMPLATES: Dict[str, Dict[QuestionIntent, List[str]]] = {
+    "en": {
+        QuestionIntent.SYMPTOM_NAME: ["What symptoms are you experiencing today?"],
+        QuestionIntent.SYMPTOM_DURATION: ["How long has it been?", "When did this start?"],
+        QuestionIntent.SYMPTOM_SEVERITY: ["How bad is the pain?", "How severe is it?"],
+        QuestionIntent.SYMPTOM_LOCATION: ["Where exactly does it hurt?"],
+        QuestionIntent.MEDICAL_HISTORY: ["Do you have BP, diabetes, or other chronic conditions?"],
+        QuestionIntent.MEDICATIONS: ["Are you currently taking any regular daily medications?"],
+        QuestionIntent.ALLERGIES: ["Do you have any medicine or food allergies?"],
+    },
+    "ta": {
+        QuestionIntent.SYMPTOM_NAME: ["வணக்கம், உங்களுக்கு என்ன பிரச்சனை இருக்கு?"],
+        QuestionIntent.SYMPTOM_DURATION: ["இந்த பிரச்சனை எத்தனை நாளா இருக்கு?", "இது எப்போலிருந்து இருக்கு?"],
+        QuestionIntent.SYMPTOM_SEVERITY: ["வலி எவ்வளவு தீவிரமா இருக்கு?"],
+        QuestionIntent.SYMPTOM_LOCATION: ["எங்க வலிக்குது?"],
+        QuestionIntent.MEDICAL_HISTORY: ["உங்களுக்கு பிபி, சுகர் போன்ற வேறு உடம்பு பிரச்சனை இருக்கா?"],
+        QuestionIntent.MEDICATIONS: ["வழக்கமா ஏதேனும் மாத்திரை சாப்பிடுறீங்களா?"],
+        QuestionIntent.ALLERGIES: ["உங்களுக்கு ஏதேனும் அலர்ஜி இருக்கா?"],
+    },
+    "hi": {
+        QuestionIntent.SYMPTOM_NAME: ["नमस्ते, आपको क्या तकलीफ हो रही है?"],
+        QuestionIntent.SYMPTOM_DURATION: ["यह तकलीफ कितने दिनों से हो रही है?", "यह दर्द कब शुरू हुआ?"],
+        QuestionIntent.SYMPTOM_SEVERITY: ["दर्द कितना तेज है?"],
+        QuestionIntent.SYMPTOM_LOCATION: ["दर्द कहाँ हो रहा है?"],
+        QuestionIntent.MEDICAL_HISTORY: ["क्या आपको बीपी या शुगर जैसी कोई बीमारी है?"],
+        QuestionIntent.MEDICATIONS: ["क्या आप नियमित रूप से कोई दवाई लेते हैं?"],
+        QuestionIntent.ALLERGIES: ["क्या आपको किसी दवाई से एलर्जी है?"],
+    },
+    "te": {
+        QuestionIntent.SYMPTOM_NAME: ["నమస్కారం, మీకు ఏమి సమస్య ఉంది?"],
+        QuestionIntent.SYMPTOM_DURATION: ["ఈ సమస్య ఎంతకాలంగా ఉంది?", "ఈ నొప్పి ఎప్పుడు మొదలైంది?"],
+        QuestionIntent.SYMPTOM_SEVERITY: ["నొప్పి ఎంత తీవ్రంగా ఉంది?"],
+        QuestionIntent.SYMPTOM_LOCATION: ["నొప్పి ఎక్కడ ఉంది?"],
+        QuestionIntent.MEDICAL_HISTORY: ["మీకు బిపి, షుగర్ వంటి ఇతర ఆరోగ్య సమస్యలు ఉన్నాయా?"],
+        QuestionIntent.MEDICATIONS: ["మీరు క్రమంగా ఏవైనా మందులు వాడుతున్నారా?"],
+        QuestionIntent.ALLERGIES: ["మీకు ఏవైనా మందులు లేదా ఆహార అలెర్జీలు ఉన్నాయా?"],
+    },
+    "kn": {
+        QuestionIntent.SYMPTOM_NAME: ["ನಮಸ್ಕಾರ, ನಿಮಗೆ ಏನು ತೊಂದರೆಯಾಗಿದೆ?"],
+        QuestionIntent.SYMPTOM_DURATION: ["ಈ ತೊಂದರೆ ಎಷ್ಟು ದಿನಗಳಿಂದ ಇದೆ?", "ಈ ನೋವು ಯಾವಾಗ ಶುರುವಾಯಿತು?"],
+        QuestionIntent.SYMPTOM_SEVERITY: ["ನೋವು ಎಷ್ಟು ತೀವ್ರವಾಗಿದೆ?"],
+        QuestionIntent.SYMPTOM_LOCATION: ["ನೋವು ಎಲ್ಲಿದೆ?"],
+        QuestionIntent.MEDICAL_HISTORY: ["ನಿಮಗೆ ಬಿಪಿ, ಸಕ್ಕರೆ ಕಾಯಿಲೆ ಮುಂತಾದ ಇತರ ತೊಂದರೆಗಳಿವೆಯೇ?"],
+        QuestionIntent.MEDICATIONS: ["ನೀವು ನಿಯಮಿತವಾಗಿ ಯಾವುದೇ ಮಾತ್ರೆಗಳನ್ನು ತೆಗೆದುಕೊಳ್ಳುತ್ತಿದ್ದೀರಾ?"],
+        QuestionIntent.ALLERGIES: ["ನಿಮಗೆ ಯಾವುದೇ ಔಷಧಿ ಅಥವಾ ಆಹಾರ ಅಲರ್ಜಿಗಳಿವೆಯೇ?"],
+    }
+}
+

ai-patient-onboarding/app/ai/conversation/response_formatter.py

@@ -0,0 +1,169 @@
+"""
+Response formatter enforcing Rules 53-60:
+- Generate response after state processing.
+- One Question Only (Rule 54).
+- Acknowledge + Ask pattern (Rule 55).
+- No unnecessary confirmation / No robotic language (Rules 56 & 57).
+- No medical explanations (Rule 58).
+- Natural conversation with short answers (Rule 59).
+- Response length enforcement: 5-15 words target, max 20 words (Rule 60).
+"""
+
+import re
+from typing import Optional
+
+
+ROBOTIC_PHRASES = [
+    r"i\s+have\s+(?:recorded|noted|documented)(?:\s+that|\s+this)?\.?",
+    r"thank\s+you\s+for\s+(?:sharing|providing|the)\s+(?:that\s+|this\s+)?(?:information|details|response)?\.?",
+    r"i\s+understand\s+your\s+response\.?",
+    r"please\s+provide\s+(?:the\s+)?(?:duration|severity|location|additional|details)",
+    r"kindly\s+specify\s+(?:the\s+)?(?:duration|severity|location)",
+    r"your\s+response\s+has\s+been\s+recorded\.?",
+    r"your\s+response\s+indicates\s+that[^.!?]+[.!?]",
+]
+
+DIAGNOSTIC_PATTERNS = [
+    r"this\s+could\s+(?:indicate|suggest|be)\s+[^.!?]+[.!?]",
+    r"possible\s+causes\s+include\s+[^.!?]+[.!?]",
+]
+
+FORM_READBACK_PATTERNS = [
+    r"i\s+understand\s+(?:that\s+)?you\s+(?:have|are|were|take|have\s+been|suffered)[^.!?]+[.!?]",
+    r"you\s+mentioned\s+(?:that\s+)?you\s+(?:have|are|were|take|have\s+been)[^.!?]+[.!?]",
+    r"i\s+see\s+that\s+you\s+(?:have|are|were|take|have\s+been)[^.!?]+[.!?]",
+]
+
+DISCLAIMER_PATTERNS = [
+    r"as\s+an\s+ai\s+(?:language\s+model|assistant|clinical\s+intake)[^.!?]*[.!?]?",
+    r"please\s+note\s+that\s+i\s+cannot\s+provide\s+medical\s+advice[^.!?]*[.!?]?",
+    r"i\s+am\s+not\s+a\s+doctor[^.!?]*[.!?]?",
+]
+
+
+def deduplicate_sentences(text: str) -> str:
+    """Removes duplicate consecutive or identical sentences."""
+    if not text:
+        return text
+    sentences = [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
+    seen = set()
+    unique = []
+    for s in sentences:
+        s_norm = s.lower()
+        if s_norm not in seen:
+            seen.add(s_norm)
+            unique.append(s)
+    return " ".join(unique)
+
+
+def sanitize_final_response(raw_reply: str, lang: str = "en", scenario: str = "normal") -> str:
+    """
+    Final response sanitization pipeline (Rule 70):
+    Generated Response
+     ↓ Remove duplicate sentences
+     ↓ Remove form readbacks (Rule 63) & diagnostic/robotic text (Rule 61)
+     ↓ Remove multiple questions (Rule 54)
+     ↓ Enforce dynamic response length (Rule 62)
+     ↓ Return short natural response
+    """
+    if not raw_reply or not raw_reply.strip():
+        if scenario in ["emergency", "crisis"]:
+            return "Please seek emergency medical evaluation immediately or call local emergency services."
+        if scenario == "completion":
+            return "Thank you. Your intake information is registered for the doctor."
+        return "Got it. What symptoms are you having?"
+
+    # Emergency / Crisis scenario (Rule 62): Return concise safety instruction without trimming
+    if scenario in ["emergency", "crisis"]:
+        text = raw_reply.strip()
+        text = re.sub(r"\s+", " ", text)
+        return text
+
+    text = raw_reply.strip()
+
+    # 1. Strip disclaimers (Rule 61)
+    for disc in DISCLAIMER_PATTERNS:
+        text = re.sub(disc, "", text, flags=re.IGNORECASE)
+
+    # 2. Strip diagnostic explanations (Rule 58 & 61)
+    for diag in DIAGNOSTIC_PATTERNS:
+        text = re.sub(diag, "", text, flags=re.IGNORECASE)
+
+    # 3. Strip form readbacks (Rule 63)
+    for readback in FORM_READBACK_PATTERNS:
+        text = re.sub(readback, "", text, flags=re.IGNORECASE)
+
+    # 4. Strip robotic confirmation phrases (Rule 56, 57, 64)
+    for rob in ROBOTIC_PHRASES:
+        text = re.sub(rob, "", text, flags=re.IGNORECASE)
+
+    text = re.sub(r"\s+", " ", text).strip()
+    if not text:
+        if scenario == "completion":
+            return "Thank you. Your intake information is registered for the doctor."
+        return "Got it. When did it start?"
+
+    # 5. Deduplicate sentences (Rule 70)
+    text = deduplicate_sentences(text)
+
+    # 6. Enforce ONE question only (Rule 54 & 70)
+    if text.count("?") > 1:
+        q_parts = text.split("?")
+        text = q_parts[0].strip() + "?"
+
+    # Completion scenario (Rule 62)
+    if scenario == "completion":
+        words = text.split()
+        if len(words) > 15:
+            text = " ".join(words[:12]) + "."
+        return text
+
+    # 7. Enforce max 1-2 short sentences (Rule 55, 60, 62)
+    sentences = [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
+    if len(sentences) > 2:
+        q_idx = next((i for i, s in enumerate(sentences) if "?" in s), -1)
+        if q_idx != -1:
+            if q_idx > 0:
+                sentences = [sentences[0], sentences[q_idx]]
+            else:
+                sentences = [sentences[0]]
+        else:
+            sentences = sentences[:2]
+
+    text = " ".join(sentences)
+
+    # 8. Dynamic length enforcement: 5-15 words (max 20 words)
+    words = text.split()
+    if len(words) > 20:
+        if "?" in text:
+            q_sent = next((s for s in sentences if "?" in s), None)
+            ack_sent = next((s for s in sentences if "?" not in s), None)
+
+            if q_sent:
+                q_words = q_sent.split()
+                if len(q_words) > 20:
+                    clean_words = [re.sub(r"[.!?]+$", "", w) for w in q_words[:18]]
+                    text = " ".join(clean_words) + "...?"
+                elif ack_sent:
+                    ack_words = ack_sent.split()
+                    if len(ack_words) + len(q_words) <= 20:
+                        text = f"{ack_sent} {q_sent}"
+                    else:
+                        candidate = f"Got it. {q_sent}"
+                        if len(candidate.split()) <= 20:
+                            text = candidate
+                        else:
+                            text = q_sent
+                else:
+                    text = q_sent
+        else:
+            clean_words = [re.sub(r"[.!?]+$", "", w) for w in words[:18]]
+            text = " ".join(clean_words) + "..."
+
+    return text
+
+
+def format_conversational_response(raw_reply: str, lang: str = "en", scenario: str = "normal") -> str:
+    """Wrapper for final response sanitization pipeline (Rule 70)."""
+    return sanitize_final_response(raw_reply, lang=lang, scenario=scenario)
+

ai-patient-onboarding/app/ai/conversation/response_generator.py

@@ -0,0 +1,40 @@
+"""
+ResponseGenerator (Rules 101, 102, 103, 104, 109, 110, 111, 112, 113, 114, 115):
+Dedicated Response Generator pipeline consuming ResponseContext and returning ResponseResult.
+- Enforces MAX_RESPONSE_WORDS = 20 (target 5-15 words).
+- Validates single question limit (0 or 1 question).
+- Calculates Response Quality Score.
+- Prevents internal data leakage & resists prompt injection.
+"""
+
+from typing import List, Optional
+from app.domain.models.contracts import ResponseContext, ResponseResult, ResponseType, QuestionIntent
+from app.ai.conversation.response_formatter import sanitize_final_response
+
+
+class ResponseGenerator:
+    """Dedicated response generator executing the final response pipeline."""
+
+    def generate(self, ctx: ResponseContext) -> ResponseResult:
+        raw_text = ctx.selected_question or "Got it. When did it start?"
+        
+        scenario = "normal"
+        resp_type = ResponseType.FOLLOW_UP
+        if ctx.safety_status in ["crisis"]:
+            scenario = "crisis"
+            resp_type = ResponseType.CRISIS
+        elif ctx.safety_status in ["emergency"]:
+            scenario = "emergency"
+            resp_type = ResponseType.SAFETY
+        elif ctx.onboarding_completed:
+            scenario = "completion"
+            resp_type = ResponseType.COMPLETION
+
+        sanitized_reply = sanitize_final_response(raw_text, lang=ctx.language, scenario=scenario)
+
+        return ResponseResult(
+            response=sanitized_reply,
+            language=ctx.language,
+            question_intent=ctx.question_intent.value if ctx.question_intent else None,
+            response_type=resp_type
+        )

ai-patient-onboarding/app/ai/extraction/__init__.py

@@ -0,0 +1,21 @@
+"""
+Extraction package.
+"""
+
+from app.ai.extraction.multilingual_normalizer import normalize_text, detect_language
+from app.ai.extraction.symptom_extractor import extract_symptoms
+from app.ai.extraction.medication_extractor import extract_medications
+from app.ai.extraction.allergy_extractor import extract_allergies
+from app.ai.extraction.history_extractor import extract_history
+from app.ai.extraction.negation_engine import is_negated, extract_family_subject
+
+__all__ = [
+    "normalize_text",
+    "detect_language",
+    "extract_symptoms",
+    "extract_medications",
+    "extract_allergies",
+    "extract_history",
+    "is_negated",
+    "extract_family_subject",
+]

ai-patient-onboarding/app/ai/extraction/allergy_extractor.py

@@ -0,0 +1,56 @@
+"""
+Allergy extraction engine distinguishing drug/food allergies from side effects.
+"""
+
+import re
+from typing import Dict, Any, List, Optional, Union
+
+ALLERGEN_PATTERNS = [
+    (r"(penicillin)", "Penicillin"),
+    (r"(sulfa)", "Sulfa drugs"),
+    (r"(aspirin)", "Aspirin"),
+    (r"(dust)", "Dust allergy"),
+    (r"(peanuts)", "Peanuts"),
+    (r"(milk|dairy)", "Milk / Dairy"),
+]
+
+
+def extract_allergies(
+    message: str,
+    normalized_msg: str,
+    last_ai_message: Optional[str] = None
+) -> Optional[Union[List[Dict[str, Any]], Dict[str, Any]]]:
+    """
+    Extracts structured allergies or confirmed_none container.
+    """
+    msg_lower = normalized_msg.lower()
+
+    # Check for explicit negation of allergies
+    neg_phrases = [
+        "no allergies", "no allergy", "no drug allergy", "no food allergy", "not allergic",
+        "nkda", "no allergic reaction", "அலர்ஜி எதுவும் இல்லை", "எந்த அலர்ஜியும் இல்லை",
+        "कोई एलर्जी नहीं", "कोई समस्या नहीं", "ఏ అలర్జీ లేదు", "ಯಾವ ಅಲರ್ಜಿ ಇಲ್ಲ"
+    ]
+    if any(neg in msg_lower for neg in neg_phrases):
+        return {"status": "confirmed_none", "items": []}
+
+    allergies: List[Dict[str, Any]] = []
+    has_allergen = any(re.search(pat, msg_lower) for pat, _ in ALLERGEN_PATTERNS)
+    has_alg_indicator = any(k in msg_lower or k in message for k in ["allergic", "allergy", "அலர்ஜி", "ஒவ்வாமை", "एलर्जी", "rash", "reaction", "side effect", "தடிப்பு", "எடுத்தா"])
+
+    # Side effect distinction: "Paracetamol didn't reduce fever" is NOT an allergy
+    if "didn't reduce" in msg_lower or "didn't work" in msg_lower or "no effect" in msg_lower:
+        return None
+
+    if has_allergen or has_alg_indicator:
+        for pat, allergen in ALLERGEN_PATTERNS:
+            if re.search(pat, msg_lower):
+                alg_obj: Dict[str, Any] = {"name": allergen}
+                if "rash" in msg_lower or "தடிப்பு" in message or "खुजली" in message:
+                    alg_obj["reaction"] = "Rash / Skin reaction"
+                allergies.append(alg_obj)
+
+        if not allergies and has_alg_indicator:
+            allergies.append({"name": "Reported allergy", "type": "unspecified"})
+
+    return allergies if allergies else None

ai-patient-onboarding/app/ai/extraction/history_extractor.py

@@ -0,0 +1,83 @@
+"""
+Medical, surgical, family history, and previous episode extraction engine.
+"""
+
+import re
+from typing import Dict, Any, List, Optional, Tuple, Union
+
+from app.ai.extraction.negation_engine import extract_family_subject
+
+HISTORY_KEYWORDS = [
+    ("diabetes", "Diabetes"), ("sugar", "Diabetes"), ("diabetic", "Diabetes"),
+    ("hypertension", "Hypertension (High BP)"), ("high bp", "Hypertension (High BP)"), ("bp", "Hypertension (High BP)"),
+    ("asthma", "Asthma"), ("thyroid", "Thyroid disorder"),
+    ("சர்க்கரை நோய்", "Diabetes"), ("சுகர்", "Diabetes"), ("பிபி", "Hypertension"),
+    ("डायबिटीज", "Diabetes"), ("शुगर", "Diabetes"), ("बीपी", "Hypertension"),
+]
+
+
+def extract_history(
+    message: str,
+    normalized_msg: str,
+    duration: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Extracts medical_history, family_history, surgical_history, previous_episodes, and additional_information.
+    """
+    msg_lower = normalized_msg.lower()
+    updates: Dict[str, Any] = {}
+
+    # Check for explicit negation of medical history for self
+    neg_history_phrases = [
+        "no past history", "no medical history", "no health conditions", "no bp no diabetes",
+        "no chronic illness", "don't have diabetes", "no diabetes", "no bp",
+        "எந்த நோயும் இல்லை", "வேற ஒன்னும் இல்லை", "பிபி சுகர் எதுவும் இல்ல",
+        "कोई बीमारी नहीं", "बीमारी नहीं है", "ఏ సమస్య లేదు", "ಯಾವ ಕಾಯಿಲೆ ಇಲ್ಲ"
+    ]
+
+    # Check if patient mentions family member (e.g., "my father has diabetes")
+    is_fam, relation, _ = extract_family_subject(message)
+
+    if is_fam:
+        fam_list: List[Dict[str, Any]] = []
+        for kw, cond in HISTORY_KEYWORDS:
+            if re.search(rf"\b{re.escape(kw)}\b", msg_lower) or kw in message:
+                fam_list.append({"relation": relation, "condition": cond})
+        if fam_list:
+            updates["family_history"] = fam_list
+
+    if any(neg in msg_lower for neg in neg_history_phrases):
+        updates["medical_history"] = {"status": "confirmed_none", "items": []}
+    elif not is_fam:
+        med_history: List[Dict[str, Any]] = []
+        for kw, cond in HISTORY_KEYWORDS:
+            if re.search(rf"\b{re.escape(kw)}\b", msg_lower) or kw in message:
+                h_obj: Dict[str, Any] = {"condition": cond}
+                h_dur_m = re.search(r"(?:for|since)\s+(\d+\s+(?:years|months|yrs))", msg_lower)
+                if h_dur_m:
+                    h_obj["duration"] = h_dur_m.group(1).strip()
+                if not any(x.get("condition") == cond for x in med_history):
+                    med_history.append(h_obj)
+        if med_history:
+            updates["medical_history"] = med_history
+
+    # Surgical History & Previous Episodes
+    if "surgery" in msg_lower or "operation" in msg_lower or "ஆபரேஷன்" in message:
+        updates["surgical_history"] = [{"procedure": "Prior surgery reported", "approximate_date": duration or "Past"}]
+
+    if "same problem" in msg_lower or "had this before" in msg_lower or "மூன்று மாதங்களுக்கு முன்" in message:
+        updates["previous_episodes"] = [{"description": "Similar symptoms previously", "time": duration or "Past"}]
+
+    # Additional Information / Functional Impact
+    add_info: List[Dict[str, Any]] = []
+    if "couldn't eat" in msg_lower or "not eaten" in msg_lower or "சாப்பிட முடியல" in message:
+        add_info.append({"category": "functional_impact", "value": "Loss of appetite / difficulty eating"})
+    if "couldn't sleep" in msg_lower or "haven't slept" in msg_lower or "தூங்க முடியல" in message:
+        add_info.append({"category": "functional_impact", "value": "Sleep disruption"})
+    if "weak" in msg_lower or "tired" in msg_lower or "ரொம்ப டயர்டா இருக்கு" in message:
+        add_info.append({"category": "functional_impact", "value": "Severe weakness / fatigue"})
+
+    if add_info:
+        updates["additional_information"] = add_info
+
+    return updates

ai-patient-onboarding/app/ai/extraction/medication_extractor.py

@@ -0,0 +1,68 @@
+"""
+Medication extraction engine supporting structured dosage, frequency, and confirmed_none status.
+"""
+
+import re
+from typing import Dict, Any, List, Optional, Union
+
+KNOWN_MED_PATTERNS = [
+    (r"(metformin(?:\s+\d+\s*mg)?(?:\s+twice\s+a\s+day)?)", "Metformin"),
+    (r"(paracetamol(?:\s+\d+\s*mg)?)", "Paracetamol"),
+    (r"(dolo(?:\s*650)?)", "Dolo 650 (Paracetamol)"),
+    (r"(pantocid|pan-d|pan 40|omez|omeprazole)", "Pantoprazole / Antacid"),
+    (r"(telmisartan|telma\s*\d+)", "Telmisartan (BP)"),
+    (r"(amlodipine|amlong\s*\d+)", "Amlodipine (BP)"),
+    (r"((?:bp|பிபி|blood\s*pressure)\s*(?:மாத்திரை|medicine|tablet|tablets|மருந்து))", "BP Medication"),
+    (r"((?:sugar|சுகர்|சர்க்கரை)\s*(?:மாத்திரை|medicine|tablet|tablets|மருந்து))", "Diabetes Medication"),
+    (r"((?:thyroid|தைராய்டு)\s*(?:மாத்திரை|medicine|tablet|tablets|மருந்து))", "Thyroid Medication"),
+]
+
+
+def extract_medications(
+    message: str,
+    normalized_msg: str,
+    last_ai_message: Optional[str] = None,
+    is_allergy_utterance: bool = False
+) -> Optional[Union[List[Dict[str, Any]], Dict[str, Any]]]:
+    """
+    Extracts structured medications or confirmed_none container.
+    """
+    msg_lower = normalized_msg.lower()
+
+    # Check for explicit negation of medicines
+    neg_phrases = [
+        "no medicines", "no medication", "don't take any medicine", "don't take medicines",
+        "no tablets", "not taking any medicine", "no daily medicines", "no regular medicines",
+        "மாத்திரை எதுவும் இல்லை", "எந்த மாத்திரையும் சாப்பிடல", "மருந்து எதுவும் இல்லை",
+        "कोई दवा नहीं", "दवाई नहीं लेते", "दवा नहीं लेता", "ఏ మందులు లేవు", "ಯಾವ ಮಾತ್ರೆ ಇಲ್ಲ"
+    ]
+    if any(neg in msg_lower for neg in neg_phrases):
+        return {"status": "confirmed_none", "items": []}
+
+    meds: List[Dict[str, Any]] = []
+
+    # Known medicine matchers
+    for pat, med_label in KNOWN_MED_PATTERNS:
+        m_match = re.search(pat, msg_lower)
+        if m_match:
+            matched_str = m_match.group(1).strip()
+            med_obj: Dict[str, Any] = {"name": med_label}
+
+            dosage_m = re.search(r"(\d+\s*mg|\d+\s*ml)", matched_str)
+            if dosage_m:
+                med_obj["dosage"] = dosage_m.group(1).strip()
+
+            freq_m = re.search(r"(twice\s+a\s+day|once\s+a\s+day|\d+\s+times\s+a\s+day|daily|twice)", matched_str)
+            if freq_m:
+                med_obj["frequency"] = freq_m.group(1).strip()
+
+            if not any(x.get("name") == med_obj["name"] for x in meds):
+                meds.append(med_obj)
+
+    # Generic medicine indicator matchers (only if not an allergy utterance)
+    if not meds and not is_allergy_utterance:
+        generic_pat = r"(tablets|goli|mathirai|மாத்திரை|மருந்து|दवाई|दवा|మాత్రలు|ಮಾತ್ರೆಗಳು)"
+        if re.search(generic_pat, msg_lower) and any(verb in msg_lower for verb in ["take", "taking", "சாப்பிடுறேன்", "சாப்பிட்டேன்", "வாங்குறேன்", "लेता", "लेती", "వాడుతున్నాను"]):
+            meds.append({"name": "Unspecified medication"})
+
+    return meds if meds else None

ai-patient-onboarding/app/ai/extraction/multilingual_normalizer.py

@@ -0,0 +1,71 @@
+"""
+Multilingual normalization layer for clinical messages.
+Preserves raw input while generating normalized, canonical representations.
+"""
+
+import re
+import unicodedata
+from typing import Dict, Any, Tuple
+
+from app.services.contextual_normalizer import (
+    normalize_duration_from_message,
+    detect_previous_question_intent,
+    is_duration_expression,
+    is_severity_expression,
+    is_location_expression,
+    is_negative_expression,
+    is_casual_filler,
+    extract_severity_from_message,
+    extract_location_from_message,
+)
+
+
+def normalize_text(text: str) -> str:
+    """
+    Cleans Unicode, strips extra spaces, standardizes quotes and punctuation.
+    """
+    if not text:
+        return ""
+    # Unicode Normalization Form C
+    normalized = unicodedata.normalize("NFC", text)
+    # Replace non-breaking spaces and smart quotes
+    normalized = normalized.replace("\xa0", " ").replace("’", "'").replace("“", '"').replace("”", '"')
+    # Collapse multiple whitespaces
+    normalized = re.sub(r"\s+", " ", normalized).strip()
+    return normalized
+
+
+def detect_language(text: str, default_lang: str = "en") -> str:
+    """
+    Detects script/language (ta, hi, te, kn, en).
+    """
+    if not text:
+        return default_lang
+
+    # Script character ranges
+    has_ta = bool(re.search(r"[\u0B80-\u0BFF]", text))
+    has_hi = bool(re.search(r"[\u0900-\u097F]", text))
+    has_te = bool(re.search(r"[\u0C00-\u0C7F]", text))
+    has_kn = bool(re.search(r"[\u0C80-\u0CFF]", text))
+
+    if has_ta:
+        return "ta-IN"
+    if has_hi:
+        return "hi-IN"
+    if has_te:
+        return "te-IN"
+    if has_kn:
+        return "kn-IN"
+
+    # Transliterated language keywords
+    msg_lower = text.lower()
+    if any(w in msg_lower for w in ["irukku", "thalaivali", "romba", "mudiyala", "saapudren"]):
+        return "ta-IN"
+    if any(w in msg_lower for w in ["dard", "ho raha", "hoga", "le raha"]):
+        return "hi-IN"
+    if any(w in msg_lower for w in ["noppi", "undi", "thala noppi"]):
+        return "te-IN"
+    if any(w in msg_lower for w in ["novu", "ide", "thale novu"]):
+        return "kn-IN"
+
+    return default_lang or "en-IN"

ai-patient-onboarding/app/ai/extraction/negation_engine.py

@@ -0,0 +1,54 @@
+"""
+Contextual negation and scope resolution engine.
+"""
+
+import re
+from typing import Dict, Any, Tuple
+
+
+# Family relations
+FAMILY_RELATIONS = [
+    ("father", "father"), ("dad", "father"), ("appa", "father"), ("அப்பா", "father"), ("पिता", "father"), ("नाना", "grandfather"),
+    ("mother", "mother"), ("mom", "mother"), ("amma", "mother"), ("அம்மா", "mother"), ("माँ", "mother"), ("माता", "mother"),
+    ("brother", "brother"), ("annaa", "brother"), ("தம்பி", "brother"), ("अண்ணன்", "brother"), ("भाई", "brother"),
+    ("sister", "sister"), ("akka", "sister"), ("அக்கா", "sister"), ("தங்கை", "sister"), ("बहन", "sister"),
+    ("parent", "parent"), ("grand-father", "grandfather"), ("grandfather", "grandfather"), ("grandmother", "grandmother"),
+]
+
+# Negation indicators
+NEGATION_PHRASES = [
+    "don't have", "do not have", "no history of", "no symptoms", "no allergies", "no allergy", "no medicine",
+    "no medications", "don't take", "do not take", "never had", "without", "denies", "absent",
+    "இல்லை", "எதுவும் இல்லை", "இல்லவே இல்லை", "மாத்திரை எதுவும் இல்லை", "நோயும் இல்லை",
+    "नहीं है", "कोई बीमारी नहीं", "कोई एलर्जी नहीं", "कोई दवा नहीं",
+    "లేవు", "ఏమీ లేదు", "ఇబ్బంది లేదు",
+    "ಇಲ್ಲ", "ಯಾವುದೇ ಇಲ್ಲ",
+]
+
+
+def is_negated(text: str) -> bool:
+    """Returns True if the text expresses explicit negation."""
+    if not text:
+        return False
+    msg_lower = text.lower().strip()
+    if msg_lower in ["no", "none", "nothing", "no more", "nil", "illness none", "nkda"]:
+        return True
+    return any(neg in msg_lower for neg in NEGATION_PHRASES)
+
+
+def extract_family_subject(text: str) -> Tuple[bool, str, str]:
+    """
+    Checks if text refers to family member rather than the patient.
+    Returns: (is_family_history, relation, condition_text)
+    """
+    if not text:
+        return False, "", text
+
+    msg_lower = text.lower().strip()
+    for rel_kw, rel_canonical in FAMILY_RELATIONS:
+        pattern = rf"\b{re.escape(rel_kw)}\b"
+        if re.search(pattern, msg_lower) or rel_kw in text:
+            # Check if patient explicitly negates disease for self in same turn
+            return True, rel_canonical, text
+
+    return False, "", text

ai-patient-onboarding/app/ai/extraction/symptom_extractor.py

@@ -0,0 +1,117 @@
+"""
+Layered symptom extraction engine supporting attribute mapping per symptom.
+"""
+
+import re
+from typing import Dict, Any, List, Optional, Set, Tuple
+
+from app.services.contextual_normalizer import (
+    normalize_duration_from_message,
+    extract_severity_from_message,
+    extract_location_from_message,
+    is_duration_expression,
+    is_severity_expression,
+    is_location_expression,
+    is_casual_filler,
+    is_negative_expression,
+)
+
+
+SYMPTOM_DICTIONARY = [
+    # General & Respiratory
+    ("fever", "fever"), ("feverish", "fever"), ("காய்ச்சல்", "fever"), ("बुखार", "fever"), ("జ్వరం", "fever"), ("ಜ್ವರ", "fever"),
+    ("cough", "cough"), ("coughing", "cough"), ("இருமல்", "cough"), ("खांसी", "cough"), ("దగ్గు", "cough"), ("ಕೆಮ್ಮು", "cough"),
+    ("cold", "cold"), ("sneezing", "cold"), ("சளி", "cold"), ("सर्दी", "cold"), ("జలుబు", "cold"), ("ನೆಗಡಿ", "cold"),
+    ("breathlessness", "breathlessness"), ("shortness of breath", "breathlessness"), ("difficulty breathing", "breathlessness"),
+    ("மூச்சு திணறல்", "breathlessness"), ("மூச்சு வாங்குது", "breathlessness"), ("மூச்சு வாங்குறேன்", "breathlessness"), ("சாப்பிடும்போது மூச்சு", "breathlessness"), ("சாப்பிடும் போது மூச்சு", "breathlessness"), ("सांस फूलना", "breathlessness"),
+    ("palpitations", "palpitations"), ("படபடன்னு", "palpitations"), ("நெஞ்சு படபடன்னு", "palpitations"), ("படபடப்பு", "palpitations"),
+    # Pain & Head
+    ("headache", "headache"), ("head ache", "headache"), ("head pain", "headache"), ("migraine", "headache"),
+    ("தலைவலி", "headache"), ("தலை பாரம்", "headache"), ("सिरदर्द", "headache"), ("తలనొప్పి", "headache"), ("ತಲೆನೋವು", "headache"),
+    ("chest pain", "chest pain"), ("chest pressure", "chest pain"), ("நெஞ்சு வலி", "chest pain"), ("छाती में दर्द", "chest pain"),
+    ("stomach pain", "stomach pain"), ("abdominal pain", "stomach pain"), ("stomach ache", "stomach pain"),
+    ("வயிற்று வலி", "stomach pain"), ("पेट दर्द", "stomach pain"), ("కడుపు నొప్పి", "stomach pain"), ("<ctrl42> ಹೊಟ್ಟೆ ನೋವು", "stomach pain"),
+    ("back pain", "back pain"), ("முதுகு வலி", "back pain"), ("पीठ दर्द", "back pain"),
+    ("joint pain", "joint pain"), ("knee pain", "knee pain"), ("மூட்டு வலி", "joint pain"), ("घुटने का दर्द", "knee pain"),
+    # Neurological / ENT
+    ("dizziness", "dizziness"), ("giddiness", "dizziness"), ("dizzy", "dizziness"),
+    ("தலை சுத்துது", "dizziness"), ("தலைசுற்றல்", "dizziness"), ("மயக்கம்", "dizziness"), ("चक्कर", "dizziness"),
+    ("sore throat", "sore throat"), ("throat pain", "sore throat"), ("தொண்டை வலி", "sore throat"), ("गले में खराश", "sore throat"),
+    # GI
+    ("vomiting", "vomiting"), ("vomit", "vomiting"), ("vomited", "vomiting"), ("nausea", "vomiting"),
+    ("வாந்தி", "vomiting"), ("உल्टी", "vomiting"), ("వాంతులు", "vomiting"), ("ವಾಂತಿ", "vomiting"),
+    ("loose motion", "diarrhea"), ("diarrhea", "diarrhea"), ("loose stools", "diarrhea"),
+    ("வயிற்றுப்போக்கு", "diarrhea"), ("दस्त", "diarrhea"),
+    # Dermatological
+    ("itching", "itching"), ("rash", "rash"), ("skin rash", "rash"),
+    ("அரிப்பு", "itching"), ("தழும்பு", "rash"), ("खुजली", "itching"),
+]
+
+
+def extract_symptoms(
+    message: str,
+    normalized_msg: str,
+    current_state: Optional[Dict[str, Any]] = None
+) -> Tuple[List[Dict[str, Any]], Optional[str]]:
+    """
+    Extracts symptoms and maps attributes (duration, severity, location, frequency) specifically.
+    Returns: (symptoms_list, primary_reason_for_visit)
+    """
+    msg_lower = normalized_msg.lower()
+    found_symptoms: List[Dict[str, Any]] = []
+    found_names: Set[str] = set()
+
+    # Extract global context attributes
+    duration = normalize_duration_from_message(message)
+    severity = extract_severity_from_message(message)
+    location = extract_location_from_message(message)
+
+    # Frequency extraction (e.g. "twice", "2 times")
+    freq_match = re.search(r"(\b\d+\s*times\b|\btwice\b|\bonce\b|\bmultiple times\b)", msg_lower)
+    frequency = freq_match.group(1) if freq_match else None
+
+    # Scan for symptoms
+    for kw, canonical in SYMPTOM_DICTIONARY:
+        pattern = rf"\b{re.escape(kw)}\b"
+        if re.search(pattern, msg_lower) or kw in message:
+            if canonical not in found_names:
+                found_names.add(canonical)
+                # Store canonical name as 'name' if kw is an English inflection like 'vomit', else keep kw if non-English
+                stored_name = canonical if kw in ["vomit", "vomited", "coughing", "feverish"] else kw
+                sym_obj: Dict[str, Any] = {"name": stored_name}
+                if duration:
+                    sym_obj["duration"] = duration
+                if severity:
+                    sym_obj["severity"] = severity
+                if location:
+                    sym_obj["location"] = location
+                if frequency and ("vomit" in canonical or "வாந்தி" in kw or "உल्टी" in kw):
+                    sym_obj["frequency"] = frequency
+                found_symptoms.append(sym_obj)
+
+    primary_rfv = list(found_names)[0] if found_names else None
+
+    # Check for medication or non-symptom statements to prevent fake symptom fallback
+    is_med_statement = any(k in msg_lower or k in message for k in ["metformin", "dolo", "paracetamol", "pantocid", "telmisartan", "amlodipine", "tablets", "medicine", "pill", "pills", "goli", "mathirai", "மாத்திரை", "மருந்து", "சாப்பிடுறேன்", "சாப்பிட்டேன்", "வாங்குறேன்", "दवाई", "दवा"])
+
+    # Fallback: single phrase short symptom message
+    if not found_symptoms and message and len(message.split()) < 10 and not is_med_statement:
+        if not (
+            is_duration_expression(message)
+            or is_severity_expression(message)
+            or is_location_expression(message)
+            or is_casual_filler(message)
+            or is_negative_expression(message)
+        ):
+            clean_symptom = message.strip()
+            sym_obj = {"name": clean_symptom}
+            if duration:
+                sym_obj["duration"] = duration
+            if severity:
+                sym_obj["severity"] = severity
+            if location:
+                sym_obj["location"] = location
+            found_symptoms.append(sym_obj)
+            primary_rfv = clean_symptom
+
+    return found_symptoms, primary_rfv

ai-patient-onboarding/app/ai/gemini_client.py

@@ -8,7 +8,7 @@ class GeminiClient:
 
     def __init__(self):
         self.api_key = GEMINI_API_KEY
-        self.model = GEMINI_MODEL
+        self.model = GEMINI_MODEL or "gemini-1.5-flash"
 
     async def extract_from_document(
         self,
@@ -30,9 +30,10 @@ class GeminiClient:
             }
 
         try:
-            import google.generativeai as genai
-            genai.configure(api_key=self.api_key)
-            model = genai.GenerativeModel(self.model or "gemini-1.5-flash")
+            from google import genai
+            from google.genai import types
+
+            client = genai.Client(api_key=self.api_key)
 
             prompt = f"""
 You are a medical document extraction AI.
@@ -56,12 +57,12 @@ Return ONLY JSON:
     "summary": "short clinical summary of the document"
 }}
 """
-            part = {
-                "mime_type": mime_type,
-                "data": file_bytes,
-            }
+            part = types.Part.from_bytes(data=file_bytes, mime_type=mime_type)
             response = await asyncio.wait_for(
-                model.generate_content_async([part, prompt]),
+                client.aio.models.generate_content(
+                    model=self.model,
+                    contents=[part, prompt]
+                ),
                 timeout=4.0
             )
             cleaned_text = response.text.replace("```json", "").replace("```", "").strip()
@@ -84,15 +85,18 @@ Return ONLY JSON:
         if not self.api_key or self.api_key in ["your_gemini_key", "your_gemini_api_key", ""]:
             raise ValueError("Gemini API key not configured")
 
-        import google.generativeai as genai
-        genai.configure(api_key=self.api_key)
-        model = genai.GenerativeModel(
-            model_name=self.model or "gemini-1.5-flash",
-            generation_config={"response_mime_type": "application/json"},
-        )
+        from google import genai
+        from google.genai import types
+
+        client = genai.Client(api_key=self.api_key)
         full_prompt = f"{system_prompt}\n\nPATIENT SAID: {user_message}"
+        config = types.GenerateContentConfig(response_mime_type="application/json")
         response = await asyncio.wait_for(
-            model.generate_content_async(full_prompt),
+            client.aio.models.generate_content(
+                model=self.model,
+                contents=full_prompt,
+                config=config,
+            ),
             timeout=3.5
         )
         return response.text

ai-patient-onboarding/app/ai/prompt_rules/conversation_rules.py

@@ -2,6 +2,68 @@ def get_conversation_rules() -> str:
     """Dynamic conversation philosophy — ASK LESS, LISTEN MORE, EXTRACT MORE."""
     return """CONVERSATION PHILOSOPHY — ASK LESS, LISTEN MORE, EXTRACT MORE:
 
+51. SHORT SPOKEN RESPONSE RULE:
+   - The AI must speak short, natural sentences.
+   - Do NOT give long explanations.
+   - Prefer: "Got it. How long have you had this pain?"
+     Instead of: "Thank you for providing that information. I understand that you are currently experiencing pain, and I would like to know how long you have been experiencing this symptom."
+   - Rules:
+     * Maximum 1–2 short sentences per response.
+     * Ask only one question at a time.
+     * Acknowledge briefly.
+     * Do not repeat information already provided.
+     * Do not explain internal processing.
+     * Do not read JSON/state to the patient.
+     * Avoid medical jargon.
+     * Sound like a real human healthcare agent.
+     * Keep emergency/crisis messages clear and direct.
+     * Generate the response in the patient's detected language.
+   - Multilingual Examples:
+     * English: "Got it. When did the pain start?"
+     * Tamil: "சரி. இந்த வலி எப்போ ஆரம்பிச்சது?"
+     * Hindi: "ठीक है। यह दर्द कब शुरू हुआ?"
+     * Telugu: "సరే. ఈ నొప్పి ఎప్పుడు మొదలైంది?"
+     * Kannada: "ಸರಿ. ಈ ನೋವು ಯಾವಾಗ ಶುರುವಾಯಿತು?"
+   - Important: Short response ≠ incomplete extraction. The backend must extract all facts from the patient's message, while the AI speaks only the single most important next question.
+
+52. RESPONSE LENGTH ENFORCEMENT:
+   - The response generator must strictly control spoken response length.
+   - AI SPEECH RULES:
+     1. Maximum 20 words per response.
+     2. Maximum 2 short sentences.
+     3. Ask only 1 question.
+     4. Never ask multiple questions together.
+     5. Acknowledge briefly.
+     6. Never repeat known information.
+     7. Never explain internal processing.
+     8. Never read structured data aloud.
+     9. Use natural spoken language.
+     10. Prefer simple words.
+     11. If one short sentence is enough, use one sentence.
+     12. Safety responses may exceed 20 words only when necessary.
+   - Bad: "Thank you for telling me that you have been experiencing headaches for three days with moderate severity. Could you please tell me whether the headache is constant or comes and goes?"
+   - Good: "Got it. Is the headache constant or does it come and go?"
+   - Bad: "I understand that you mentioned diabetes, metformin, and a penicillin allergy. I have recorded all this information."
+   - Good: "Got it. When was your headache last this severe?"
+   - Core rule: Extract everything. Speak only what is necessary. Ask only the next best question.
+
+53. RESPONSE GENERATION PRIORITY:
+   - RESPONSE PRIORITY:
+     1. Handle emergency/crisis first.
+     2. Acknowledge the patient's latest information briefly.
+     3. Extract all useful facts silently.
+     4. Identify the most important missing information.
+     5. Ask only ONE question.
+     6. Keep the response under 20 words whenever possible.
+     7. Never ask for information already provided.
+     8. Never ask optional questions when important information is missing.
+     9. If all required information is available, finish naturally.
+   - Example:
+     * Patient: "I have chest pain for two days and it gets worse when walking."
+     * AI: "I understand. Are you having trouble breathing right now?"
+     * Not: "Thank you for providing detailed information about your chest pain. I have recorded the duration and trigger. I would now like to ask you another important question…"
+   - Core principle: Backend thinks deeply. AI speaks simply.
+
 1. EVERY PATIENT MESSAGE IS INFORMATION-RICH:
    - Treat every patient message as a potentially rich clinical statement.
    - Extract ALL clinically relevant information from EVERY message, not just the answer to the current question.
@@ -19,7 +81,6 @@ def get_conversation_rules() -> str:
    - If the patient already mentioned penicillin allergy, do NOT ask "Do you have any allergies?"
    - If duration is present, progress immediately to medical history or medication/allergy questions.
 
-
 4. ACKNOWLEDGE BEFORE ASKING:
    - When the patient provides multiple details, briefly acknowledge: "Got it, you have headache and fever for two days with vomiting."
    - Then ask only the MOST important missing question.
@@ -47,7 +108,7 @@ def get_conversation_rules() -> str:
    PATIENT MESSAGE → UNDERSTAND → EXTRACT ALL RELEVANT INFO → MERGE INTO STATE → CHECK EMERGENCY → CHECK WHAT IS KNOWN → IDENTIFY IMPORTANT GAPS → ASK ONE BEST QUESTION or COMPLETE
 
 10. RESPONSE STYLE:
-    - Produce ONE concise, natural spoken response.
+    - Produce ONE concise, natural spoken response (1-2 short sentences max).
     - Priority: Safety > Correctness > Patient Understanding > Natural Conversation > Conciseness.
     - Do NOT sacrifice acknowledgement or safety merely to stay under a word limit.
     - No markdown, no bullet points, no brackets. Clean spoken dialogue only.
@@ -64,4 +125,11 @@ def get_conversation_rules() -> str:
 12. PATIENT-LED EXTRACTION:
      - If the patient volunteers multiple categories in one message, extract ALL of them.
      - Example: "diabetes இருக்கு, metformin 500 எடுத்துக்கிறேன், penicillin அலர்ஜி இருக்கு" → Extract medical_history, medications, AND allergies simultaneously.
-     - Skip questions for categories already covered. Ask only for what is genuinely missing."""
+     - Skip questions for categories already covered. Ask only for what is genuinely missing.
+
+13. DYNAMIC PATIENT-TAILORED QUESTIONS REQUIREMENT:
+     - ALWAYS reference the patient's specific reported symptoms or concerns in your follow-up questions.
+     - Example: If patient reports "headache", ask "How long have you had this headache?" (NOT generic "How long have you had this problem?").
+     - Example: If patient reports "fever", ask "Are you taking any medicine for your fever?" (NOT generic "Are you taking any medications?").
+     - NEVER use robotic generic templates like "this issue" or "this condition" when the specific symptom name is known."""
+

ai-patient-onboarding/app/ai/prompt_rules/safety_rules.py

@@ -12,8 +12,8 @@ def get_safety_rules() -> str:
    - Severe trauma / major injury
    - Seizure / convulsion in progress
 
-   EMERGENCY RESPONSE: Direct to 108 ambulance immediately.
-   Example: "This needs urgent medical attention. Please call 108 for an ambulance right away."
+   EMERGENCY RESPONSE: Direct to hospital emergency staff or ER immediately.
+   Example: "This needs urgent medical attention. Please inform the nearest hospital staff or proceed directly to the Emergency Room right away."
    Do NOT diagnose. Do NOT say "You are having a heart attack."
 
 2. MENTAL HEALTH CRISIS:
@@ -22,8 +22,8 @@ def get_safety_rules() -> str:
    - Self-harm intent
    - Immediate danger to self or others
 
-   CRISIS RESPONSE: Provide Tele-MANAS helpline (14416) and emergency 108.
-   Example: "If you're in distress, please reach out to Tele-MANAS at 14416 or call 108 right now. I've noted your details for the doctor."
+   CRISIS RESPONSE: Provide Tele-MANAS helpline (14416) or direct to hospital staff immediately.
+   Example: "If you're in distress, please reach out to Tele-MANAS at 14416 or alert the hospital staff right now. I've noted your details for the doctor."
    Do NOT continue normal intake before acknowledging the crisis.
    Do NOT diagnose or offer therapy.
 
@@ -43,7 +43,7 @@ EMERGENCY_KEYWORDS_EN = [
     "can't breathe", "cannot breathe", "severe breathing difficulty", "unable to breathe",
     "sudden paralysis", "sudden weakness", "collapsed", "passed out",
     "loss of consciousness", "unconscious", "severe bleeding",
-    "call 108", "call ambulance",
+    "call nurse", "call doctor", "emergency room", "call ambulance",
 ]
 
 CRISIS_KEYWORDS_EN = [

ai-patient-onboarding/app/ai/prompt_rules/specialty_rules.py

@@ -31,7 +31,7 @@ _SPECIALTY_OVERRIDES = {
   - Acknowledge the patient's courage in sharing emotional/mental struggles.
   - Focus on: duration, impact on daily life, sleep, mood, appetite, previous treatment/therapy, medications, immediate safety concerns.
   - Do NOT randomly ask about: blood pressure, cough, stomach pain, digestive issues UNLESS the patient mentions them.
-  - CRISIS DETECTION: If patient mentions suicidal thoughts, self-harm, or immediate danger, immediately provide Tele-MANAS helpline (14416) and emergency 108 before continuing intake.
+  - CRISIS DETECTION: If patient mentions suicidal thoughts, self-harm, or immediate danger, immediately provide Tele-MANAS helpline (14416) or direct to hospital emergency staff before continuing intake.
   - Use empathetic, warm language. Mental health intake requires extra sensitivity.""",
 
     "cardiology": """

ai-patient-onboarding/app/ai/prompts.py

@@ -10,22 +10,23 @@ from app.ai.prompt_rules.safety_rules import get_safety_rules
 def build_system_prompt(context: dict) -> str:
     """
     Build a dynamic, modular system prompt for natural patient intake.
-    Adheres to: ASK LESS -> LISTEN MORE -> EXTRACT MORE.
-    Composed of language, clinical, conversation, extraction, specialty, and safety rule modules.
+    Adheres to Master Prompt Rules 53-60:
+    - Extract a lot internally. Speak very little externally.
+    - One question only.
+    - Acknowledge + Ask pattern.
+    - No robotic confirmations or medical explanations.
+    - Target length: 5-15 words (max 20 words).
     """
     specialty = context.get("specialty_config", {})
     patient = context.get("patient", {})
     language = context.get("language", "ta-IN")
-    stage = context.get("current_stage", "greeting")
     current_state = context.get("current_state", {})
     conversation_history = context.get("conversation_history", [])
     new_patient_message = context.get("new_patient_message", "")
+    target_question = context.get("target_question", "")
 
     patient_name = patient.get("name") or "Patient"
-    patient_age = patient.get("age") or "Not provided"
-    patient_gender = patient.get("gender") or "Not provided"
 
-    # Assemble modular rules
     lang_rules = get_language_rules(language)
     clin_rules = get_clinical_rules()
     priv_rules = get_privacy_rules()
@@ -33,18 +34,15 @@ def build_system_prompt(context: dict) -> str:
     extr_rules = get_extraction_rules()
     spec_rules = get_specialty_rules(specialty)
     safe_rules = get_safety_rules()
+
     last_ai_message = ""
     for turn in reversed(conversation_history):
         if turn.get("role") in ["assistant", "ai"]:
             last_ai_message = turn.get("message", "")
             break
 
-    from app.services.contextual_normalizer import detect_previous_question_intent
-    expected_intent = detect_previous_question_intent(last_ai_message)
-    intent_hint = f"\nPREVIOUS AI QUESTION INTENT: {expected_intent.upper()} (Interpret patient's reply as providing {expected_intent} for the primary symptom, NOT a new symptom entity)." if expected_intent else ""
-
-    prompt = f"""You are Nila, an empathetic, highly skilled AI Clinical Intake Assistant at a hospital/clinic.
-Your job is to collect preliminary clinical intake information for the doctor from the patient: {patient_name} (Age: {patient_age}, Gender: {patient_gender}).
+    prompt = f"""You are Nila, an empathetic, highly skilled AI Clinical Intake Assistant at a hospital.
+Your job is to collect preliminary clinical intake information for the doctor from patient: {patient_name}.
 
 {lang_rules}
 
@@ -60,105 +58,84 @@ Your job is to collect preliminary clinical intake information for the doctor fr
 
 {priv_rules}
 
-CURRENT INTAKE STATE (What has already been gathered):
+RESPONSE GENERATION RULES (RULES 51 - 200):
+1. SHORT SPOKEN RESPONSE RULE (Rule 51):
+   - Speak short, natural sentences (max 1-2 short sentences). No long explanations.
+   - Prefer "Got it. How long have you had this pain?" over long robotic explanations.
+   - Ask only ONE question at a time. Acknowledge briefly. Do not repeat provided info or explain internal processing.
+   - Avoid medical jargon. Sound like a real human healthcare agent.
+   - Generate response in patient's detected language (en: "Got it. When did the pain start?", ta: "சரி. இந்த வலி எப்போ ஆரம்பிச்சது?", hi: "ठीक है। यह दर्द कब शुरू हुआ?", te: "సరే. ఈ నొప్పి ఎప్పుడు మొదలైంది?", kn: "ಸರಿ. ಈ ನೋವು ಯಾವಾಗ ಶುರುವಾಯಿತು?").
+   - Short response ≠ incomplete extraction (backend extracts everything internally, AI speaks only single next question).
+2. RESPONSE LENGTH ENFORCEMENT (Rule 52):
+   - Maximum 20 words per response. Maximum 2 short sentences (use 1 sentence if enough).
+   - Ask only 1 question. Never ask multiple questions together. Acknowledge briefly.
+   - Never repeat known info, explain internal processing, or read structured data aloud.
+   - Use natural spoken language and simple words. Core rule: Extract everything. Speak only what is necessary.
+3. RESPONSE GENERATION PRIORITY (Rule 53):
+   - Priority sequence: (1) Emergency/crisis first (2) Acknowledge briefly (3) Extract facts silently (4) Identify missing info (5) Ask ONE question (6) Keep under 20 words (7) Never ask provided info (8) Prioritize critical gaps over optional (9) Finish naturally when complete.
+   - Core principle: Backend thinks deeply. AI speaks simply.
+4. RESPONSE TIMING & CONTEXT: Generate response after state processing. Receive only necessary context.
+3. ONE QUESTION ONLY (Rule 54): Ask ONLY ONE question in your response. Never ask multiple independent questions.
+4. ACKNOWLEDGE + ASK PATTERN (Rules 55 & 63): Brief acknowledgement + ONE question. NEVER read the form back or repeat full patient info.
+5. NO ROBOTIC LANGUAGE OR CONFIRMATIONS (Rules 56, 57, 64, 79): Avoid 'I have recorded that', 'Please provide...', 'Your response indicates that...'. Interpret short answers ('yeah', '3 days', 'aama', 'illa', 'no', 'haan') naturally without asking for complete sentences.
+6. NO MEDICAL EXPLANATIONS & NO HALLUCINATION (Rules 58 & 75): No diagnosis, no medical advice, no underlying condition lectures. NEVER assume unestablished facts ('Since you have diabetes...') in spoken reply.
+7. INTENT-BASED MICRO RESPONSES & DYNAMIC LENGTH (Rules 60, 61, 62, 70, 71, 72, 73, 74, 168):
+   - Adapt to turn intent (greeting, fact_extraction, clarification, completion, emergency, crisis).
+   - Filter out greetings, repeated acknowledgements, form readbacks, medical jargon, disclaimers.
+   - Normal turn: 1 short sentence, 5-15 words (max 20 words). Voice turn: 5-12 words.
+   - Completion turn: Short natural closing (5-12 words, e.g. 'Thanks. Your onboarding is complete.').
+   - Emergency / Crisis: Immediate concise safety instructions (EMERGENCY > NORMAL CONVERSATION).
+8. LANGUAGE CONSISTENCY & CODE-SWITCHING (Rules 76, 166, 167): Respond in patient's active language/transliteration (e.g. Tanglish/Hinglish). Support mixed-language code-switching naturally.
+9. PATIENT-LED PRIORITY & STATE INTEGRITY (Rules 66, 67, 68, 69, 77, 78, 80, 121-140):
+   - Extract patient profile (age, gender, name) and validate values (Rule 121 & 123).
+   - Separate family history / representative info from patient history ('My father has diabetes' -> family_history, NOT patient.medical_history) (Rule 122 & 129).
+   - Extract medications with dose & frequency, updating on corrections without duplicating (Rule 124 & 125).
+   - Extract surgical history, previous episodes, treatment history, test reports (Rules 128, 130, 131, 132).
+   - Maintain symptom relationship graphs (duration, severity, location mapped per symptom) (Rule 133).
+   - Temporal, severity, & frequency normalization without fabricating numeric scores or exact dates (Rules 134, 135, 136).
+   - Negation scope & pronoun resolution ('it' -> active symptom name) (Rules 137 & 138).
+   - Correction phrase detection ('actually', 'I meant') overriding previous values (Rule 139).
+   - Final data integrity rule: Never complete because conversation is long; complete ONLY when state is complete (Rule 140).
+10. PRODUCTION SECURITY, PRIVACY & GOVERNANCE (Rules 171-200):
+   - RBAC & tenant isolation (Rules 171-176). Minimum data exposure & log redaction (Rules 177-179).
+   - Environment separation, explicit CORS, request correlation ID (Rules 180-186).
+   - Audit event logging (SESSION_CREATED, SAFETY_DETECTED, LLM_REQUESTED, COMPLETED) (Rules 187 & 188).
+   - Decoupled architecture: Router -> Service -> AI Orchestrator (SafetyEngine, Normalization, ExtractionEngine, StateManager, QuestionEngine, ResponseGenerator) -> Repository (Rules 189-200).
+
+FINAL BACKEND DESIGN PRINCIPLE (Rule 200):
+COMPLEX BACKEND → SIMPLE CONVERSATION → SHORT AI SPEECH.
+
+CURRENT INTAKE STATE:
 {json.dumps(current_state, indent=2, ensure_ascii=False)}
 
-RECENT CONVERSATION HISTORY:
-{json.dumps(conversation_history[-8:], indent=2, ensure_ascii=False)}
-
-PREVIOUS AI QUESTION:
-"{last_ai_message}"{intent_hint}
-
-LATEST PATIENT INPUT:
+LATEST PATIENT MESSAGE:
 "{new_patient_message}"
 
-CRITICAL INSTRUCTIONS FOR THIS TURN:
-1. Extract ALL clinically relevant facts from the latest patient input. If the input is answering the previous AI question (e.g. duration, severity, location), attach it to the existing symptom in CURRENT INTAKE STATE. DO NOT create a new symptom item for duration/severity statements.
-2. DO NOT re-ask for any information already present in CURRENT INTAKE STATE or clearly stated in this input. NEVER ask duration again if duration is provided.
-3. If the patient stated "Nothing else", "No", "None" for a SPECIFIC category that was just asked about, set that category to confirmed_none. But do NOT complete the intake unless ALL required categories are collected or confirmed_none.
-4. If an important clinical gap remains, formulate ONE natural, empathetic question addressing ONLY the most relevant missing item.
-5. In "reply", provide only ONE clean, spoken sentence without bullet points, markdown, or bracketed notes.
-
-COMPLETION RULES — MANDATORY:
-- NEVER set "completed": true unless ALL of the following are satisfied:
-  A. reason_for_visit is reported (has a value)
-  B. At least one symptom exists with duration information
-  C. medical_history is either "reported" with items OR explicitly "confirmed_none"
-  D. medications is either "reported" with items OR explicitly "confirmed_none"
-  E. allergies is either "reported" with items OR explicitly "confirmed_none"
-- "not_collected" is NOT the same as "confirmed_none". A field with status "not_collected" means you MUST still ask about it.
-- If the patient says "nothing else" but required fields are still "not_collected", you MUST continue asking. Do NOT complete early.
-- If the patient provides medical_history + medications + allergies in a single message, extract ALL of them and skip those questions.
-
+TARGET MISSING QUESTION TO ASK:
+"{target_question}"
 
 OUTPUT FORMAT REQUIREMENTS:
 You MUST respond with valid JSON matching EXACTLY this structure:
 {{
-  "reply": "Warm, natural spoken response acknowledging input and asking one relevant missing question or giving closing confirmation",
-  "next_stage": "reason_for_visit | symptom_collection | symptom_details | medications | allergies | confirmation",
+  "reply": "Short natural spoken response (5-15 words, max 1 question) following Acknowledge + Ask pattern",
+  "next_stage": "reason_for_visit | symptom_collection | symptom_details | medical_history | medications | allergies | confirmation",
   "state_updates": {{
-    "reason_for_visit": "primary reason if identified or null",
+    "reason_for_visit": "primary reason or null",
     "symptoms": [
       {{
         "name": "symptom name",
-        "duration": "duration if stated or null",
-        "severity": "mild/moderate/severe if stated or null",
-        "location": "body location if stated or null",
-        "onset": "sudden/gradual if stated or null",
-        "frequency": "how often if stated or null",
-        "pattern": "continuous/intermittent if stated or null",
-        "triggers": "trigger factors if stated or null",
-        "relieving_factors": "relieving factors if stated or null",
-        "aggravating_factors": "aggravating factors if stated or null"
+        "duration": "duration or null",
+        "severity": "severity or null",
+        "location": "location or null"
       }}
     ],
-    "medical_history": [
-      {{
-        "condition": "condition name",
-        "duration": "duration if stated or null",
-        "status": "active/past if stated or null"
-      }}
-    ],
-    "medications": [
-      {{
-        "name": "medication name",
-        "dosage": "dosage if stated or null",
-        "frequency": "frequency if stated or null",
-        "duration": "duration if stated or null"
-      }}
-    ],
-    "allergies": [
-      {{
-        "name": "allergen name",
-        "type": "drug/food/environment if known or null",
-        "reaction": "reaction if stated or null"
-      }}
-    ],
-    "surgical_history": [
-      {{
-        "procedure": "procedure name",
-        "approximate_date": "when if stated or null",
-        "reason": "reason if stated or null"
-      }}
-    ],
-    "previous_episodes": [
-      {{
-        "description": "episode description",
-        "time": "when if stated or null"
-      }}
-    ],
-    "family_history": [
-      {{
-        "condition": "condition name",
-        "relationship": "family member if stated or null"
-      }}
-    ],
-    "additional_information": [
-      {{
-        "category": "functional_impact | lifestyle | dietary | other",
-        "value": "details stated by patient"
-      }}
-    ]
+    "medical_history": [],
+    "medications": [],
+    "allergies": [],
+    "surgical_history": [],
+    "previous_episodes": [],
+    "family_history": [],
+    "additional_information": []
   }},
   "completed": false
 }}

ai-patient-onboarding/app/ai/providers/__init__.py

@@ -0,0 +1,9 @@
+"""
+Providers package.
+"""
+
+from app.ai.providers.base import LLMProvider
+from app.ai.providers.openai import OpenAIProvider
+from app.ai.providers.gemini import GeminiProvider
+
+__all__ = ["LLMProvider", "OpenAIProvider", "GeminiProvider"]

ai-patient-onboarding/app/ai/providers/base.py

@@ -0,0 +1,30 @@
+"""
+Base LLM Provider interface with hard async timeout enforcement.
+"""
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class LLMProvider(ABC):
+    """
+    Abstract LLM Provider interface.
+    Enforces a strict hard timeout (default 4 seconds).
+    """
+    def __init__(self, timeout_seconds: float = 4.0):
+        self.timeout_seconds = timeout_seconds
+
+    async def generate_response_with_timeout(self, system_prompt: str, user_message: str) -> Optional[str]:
+        try:
+            return await asyncio.wait_for(
+                self._generate_internal(system_prompt, user_message),
+                timeout=self.timeout_seconds
+            )
+        except (asyncio.TimeoutError, Exception) as e:
+            print(f"[{self.__class__.__name__} Failed / Timed out]: {e}")
+            return None
+
+    @abstractmethod
+    async def _generate_internal(self, system_prompt: str, user_message: str) -> Optional[str]:
+        pass

ai-patient-onboarding/app/ai/providers/gemini.py

@@ -0,0 +1,19 @@
+"""
+Gemini LLM Provider.
+"""
+
+from typing import Optional
+from app.ai.providers.base import LLMProvider
+from app.ai.gemini_client import GeminiClient
+
+
+class GeminiProvider(LLMProvider):
+    def __init__(self, timeout_seconds: float = 4.0):
+        super().__init__(timeout_seconds=timeout_seconds)
+        self.client = GeminiClient()
+
+    async def _generate_internal(self, system_prompt: str, user_message: str) -> Optional[str]:
+        api_key = getattr(self.client, "api_key", None)
+        if not api_key or api_key in ["your_gemini_key", "your_gemini_api_key", ""]:
+            return None
+        return await self.client.generate_response(system_prompt, user_message)

ai-patient-onboarding/app/ai/providers/openai.py

@@ -0,0 +1,19 @@
+"""
+OpenAI LLM Provider.
+"""
+
+from typing import Optional
+from app.ai.providers.base import LLMProvider
+from app.ai.openai_client import OpenAIClient
+
+
+class OpenAIProvider(LLMProvider):
+    def __init__(self, timeout_seconds: float = 4.0):
+        super().__init__(timeout_seconds=timeout_seconds)
+        self.client = OpenAIClient()
+
+    async def _generate_internal(self, system_prompt: str, user_message: str) -> Optional[str]:
+        api_key = getattr(self.client, "api_key", None)
+        if not api_key or api_key in ["your_openai_key", "your_openai_api_key", ""]:
+            return None
+        return await self.client.generate_response(system_prompt, user_message)

ai-patient-onboarding/app/ai/safety/__init__.py

@@ -0,0 +1,8 @@
+"""
+Safety package.
+"""
+
+from app.ai.safety.emergency import check_emergency
+from app.ai.safety.crisis import check_crisis
+
+__all__ = ["check_emergency", "check_crisis"]

ai-patient-onboarding/app/ai/safety/crisis.py

@@ -0,0 +1,69 @@
+"""
+Mental health crisis and self-harm detection engine.
+"""
+
+import re
+from typing import Optional, Tuple
+
+from app.ai.prompt_rules.safety_rules import CRISIS_KEYWORDS_EN, CRISIS_KEYWORDS_INDIC
+
+
+TRANSLITERATED_CRISIS_PHRASES = [
+    "saaganam pola irukku", "uyiroda irukka virumbala", "saaga poraen", "valave pidikala",
+    "mar jane ka man", "apne aap ko nuksan", "khudkushee",
+    "chani povali", "sathokobeku",
+]
+
+
+def check_crisis(user_message: str, lang: str = "en") -> Tuple[bool, Optional[str], Optional[str]]:
+    """
+    Evaluates patient message for mental health crisis or self-harm intent.
+    Returns: (is_crisis, reason, crisis_reply)
+    """
+    if not user_message or not user_message.strip():
+        return False, None, None
+
+    # Check Indic script crisis keywords FIRST against raw message
+    for kw in CRISIS_KEYWORDS_INDIC:
+        if kw in user_message:
+            reply = _build_crisis_reply(lang)
+            return True, f"Matched Indic crisis phrase: '{kw}'", reply
+
+    indic_extra = ["காயப்படுத்திக்கணும்", "கொல்லணும்", "வாழவே பிடிக்கல", "உயிரோட இருக்க", "தற்கொலை", "உயிரை"]
+    for kw in indic_extra:
+        if kw in user_message:
+            reply = _build_crisis_reply(lang)
+            return True, f"Matched Indic crisis phrase: '{kw}'", reply
+
+    msg = user_message.strip().lower()
+    msg_clean = re.sub(r"[^\w\s]", " ", msg)
+    msg_clean = re.sub(r"\s+", " ", msg_clean)
+
+    # Check English crisis keywords
+    for kw in CRISIS_KEYWORDS_EN:
+        kw_clean = re.sub(r"[^\w\s]", " ", kw.lower())
+        if re.search(rf"\b{re.escape(kw_clean)}\b", msg_clean) or kw.lower() in msg:
+            reply = _build_crisis_reply(lang)
+            return True, f"Matched crisis phrase: '{kw}'", reply
+
+    # Check Transliterated crisis phrases
+    for kw in TRANSLITERATED_CRISIS_PHRASES:
+        if kw in msg_clean or kw in msg:
+            reply = _build_crisis_reply(lang)
+            return True, f"Matched transliterated crisis phrase: '{kw}'", reply
+
+    return False, None, None
+
+
+def _build_crisis_reply(lang: str) -> str:
+    lang_clean = lang.lower() if lang else "en"
+    if lang_clean.startswith("ta"):
+        return "உங்களுக்கு மன உளைச்சல் இருந்தால், தயவுசெய்து டெலி-மானாஸ் (Tele-MANAS) உதவி எண் 14416-ஐ தொடர்பு கொள்ளவும் அல்லது மருத்துவமனை ஊழியர்களிடம் தெரிவிக்கவும்."
+    elif lang_clean.startswith("hi"):
+        return "यदि आप परेशानी में हैं, तो कृपया तुरंत टेली-मानस (Tele-MANAS) 14416 पर संपर्क करें या अस्पताल के कर्मचारियों को सूचित करें।"
+    elif lang_clean.startswith("te"):
+        return "మీరు తీవ్రమైన ఒత్తిడిలో ఉంటే, దయచేసి టెలి-మానస్ (Tele-MANAS) 14416 కు ఫోన్ చేయండి లేదా ఆసుపత్రి సిబ్బందికి చెప్పండి."
+    elif lang_clean.startswith("kn"):
+        return "ನೀವು ಮನೋಒತ್ತಡದಲ್ಲಿದ್ದರೆ, ದಯವಿಟ್ಟು ಟೆಲಿ-ಮಾನಸ್ (Tele-MANAS) 14416 ಗೆ ಕರೆ ಮಾಡಿ ಅಥವಾ ಆಸ್ಪತ್ರೆಯ ಸಿಬ್ಬಂದಿಗೆ ತಿಳಿಸಿ."
+    else:
+        return "If you're in distress, please reach out to Tele-MANAS at 14416 or alert the hospital staff right now."

ai-patient-onboarding/app/ai/safety/emergency.py

@@ -0,0 +1,91 @@
+"""
+Emergency detection engine with strict safety precedence and false-positive protection.
+"""
+
+import re
+from typing import Optional, Tuple
+
+from app.ai.prompt_rules.safety_rules import EMERGENCY_KEYWORDS_EN, EMERGENCY_KEYWORDS_INDIC
+
+
+TRANSLITERATED_EMERGENCY_PHRASES = [
+    "nenju romba valikuthu", "nenju valla valikuthu", "nenju kadumaya valikuthu",
+    "moochu vida mudiyala", "moochu adaikuthu", "moochu thinaral",
+    "mayangi vilunthuten", "mayakkam varuthu", "paralysis vanthuruchu",
+    "cheest mein bahut dard", "seene mein bahut tej dard", "saans lene mein bahut dikkat",
+    "saans nahi aa rahi", "behosh ho gaya", "behosh ho gayi",
+    "chathi lo thivramaina noppi", "oophiri aadam ledhu", "spruha thappi",
+    "edeyalli theevra novu", "usiraadalu thumba kashta", "pragne thappi",
+]
+
+
+def check_emergency(user_message: str, lang: str = "en") -> Tuple[bool, Optional[str], Optional[str]]:
+    """
+    Evaluates patient message for medical emergency indicators.
+    Returns: (is_emergency, reason, emergency_reply)
+    """
+    if not user_message or not user_message.strip():
+        return False, None, None
+
+    # Check Indic script emergency keywords against raw user_message FIRST
+    for kw in EMERGENCY_KEYWORDS_INDIC:
+        if kw in user_message:
+            reply = _build_emergency_reply(lang)
+            return True, f"Matched Indic emergency phrase: '{kw}'", reply
+
+    # Additional Tamil/Hindi spoken emergency phrases
+    indic_extra = ["மூச்சு விட முடியல", "மூச்சு திணறல்", "நெஞ்சு வலி", "நெஞ்சு பாரம்", "கடும் நெஞ்சு வலி", "நெஞ்சு அதிகமா வலி"]
+    for kw in indic_extra:
+        if kw in user_message and any(x in user_message for x in ["மூச்சு", "கடும்", "வலி", "அதிகமா"]):
+            reply = _build_emergency_reply(lang)
+            return True, f"Matched Indic emergency phrase: '{kw}'", reply
+
+    msg = user_message.strip().lower()
+    msg_clean = re.sub(r"[^\w\s]", " ", msg)
+    msg_clean = re.sub(r"\s+", " ", msg_clean)
+
+    # False Positive Protection: Negated emergency statements ("no chest pain")
+    negation_patterns = [
+        r"\bno\s+(?:chest\s+pain|breathing\s+difficulty|heart\s+attack|paralysis|bleeding)\b",
+        r"\bdon't\s+have\s+(?:chest\s+pain|breathing\s+difficulty|heart\s+attack)\b",
+        r"\bnot\s+having\s+(?:chest\s+pain|breathing\s+difficulty)\b",
+        r"\bnever\s+had\s+(?:chest\s+pain|breathing\s+difficulty)\b",
+        r"\billness\s+none\b",
+    ]
+    for neg_pat in negation_patterns:
+        if re.search(neg_pat, msg_clean):
+            if not any(pos in msg_clean for pos in ["severe chest pain", "cannot breathe", "collapsed"]):
+                return False, None, None
+
+    # Check English emergency keywords
+    for kw in EMERGENCY_KEYWORDS_EN:
+        if re.search(rf"\b{re.escape(kw)}\b", msg_clean):
+            reply = _build_emergency_reply(lang)
+            return True, f"Matched emergency phrase: '{kw}'", reply
+
+    # Check combinations (e.g. "chest pain" AND "difficulty breathing")
+    if "chest pain" in msg_clean and ("breath" in msg_clean or "shortness" in msg_clean or "difficulty" in msg_clean):
+        reply = _build_emergency_reply(lang)
+        return True, "Matched combined chest pain and breathing difficulty", reply
+
+    # Check Transliterated emergency phrases
+    for kw in TRANSLITERATED_EMERGENCY_PHRASES:
+        if kw in msg_clean:
+            reply = _build_emergency_reply(lang)
+            return True, f"Matched transliterated emergency phrase: '{kw}'", reply
+
+    return False, None, None
+
+
+def _build_emergency_reply(lang: str) -> str:
+    lang_clean = lang.lower() if lang else "en"
+    if lang_clean.startswith("ta"):
+        return "இது அவசர மருத்துவ உதவி தேவைப்படும் நிலை. தயவுசெய்து உடனடியாக அருகில் உள்ள மருத்துவமனை அவசர சிகிச்சைப் பிரிவுக்குச் செல்லவும்."
+    elif lang_clean.startswith("hi"):
+        return "यह एक आपातकालीन स्थिति हो सकती है। कृपया तुरंत निकटतम अस्पताल के आपातकालीन कक्ष (ER) में जाएँ।"
+    elif lang_clean.startswith("te"):
+        return "ఇది అత్యవసర వైద్య పరిస్థితి కావచ్చు. దయచేసి వెంటనే దగ్గరలోని ఆసుపత్రి ఎమర్జెన్సీ విభాగానికి వెళ్ళండి."
+    elif lang_clean.startswith("kn"):
+        return "ಇದು ತುರ್ತು ವೈದ್ಯಕೀಯ ಪರಿಸ್ಥಿತಿಯಾಗಿರಬಹುದು. ದಯವಿಟ್ಟು ತಕ್ಷಣ ಹತ್ತಿರದ ಆಸ್ಪತ್ರೆಯ ತುರ್ತು ವಿಭಾಗಕ್ಕೆ ಹೋಗಿ."
+    else:
+        return "This requires urgent medical attention. Please inform the nearest hospital staff or proceed directly to the Emergency Room right away."

ai-patient-onboarding/app/ai/sarvam_client.py

@@ -1,7 +1,25 @@
 import base64
+import time
+import asyncio
+import logging
 import httpx2
+from typing import Tuple, Optional
 from app.config import SARVAM_API_KEY
 
+logger = logging.getLogger("sarvam_client")
+
+# Status Constants
+STT_SUCCESS = "STT_SUCCESS"
+STT_EMPTY_AUDIO = "STT_EMPTY_AUDIO"
+STT_TIMEOUT = "STT_TIMEOUT"
+STT_PROVIDER_ERROR = "STT_PROVIDER_ERROR"
+STT_NETWORK_ERROR = "STT_NETWORK_ERROR"
+
+TTS_SUCCESS = "TTS_SUCCESS"
+TTS_TIMEOUT = "TTS_TIMEOUT"
+TTS_PROVIDER_ERROR = "TTS_PROVIDER_ERROR"
+TTS_NETWORK_ERROR = "TTS_NETWORK_ERROR"
+
 
 class SarvamClient:
 
@@ -14,48 +32,114 @@ class SarvamClient:
     def _get_client(self) -> httpx2.AsyncClient:
         if SarvamClient._client is None:
             SarvamClient._client = httpx2.AsyncClient(
-                timeout=12.0,
+                timeout=8.0,
                 limits=httpx2.Limits(max_keepalive_connections=5, max_connections=10),
             )
         return SarvamClient._client
 
+    async def speech_to_text_with_status(
+        self,
+        audio_bytes: bytes,
+        filename: str = "audio.webm",
+        language_code: str = "ta-IN",
+        session_id: Optional[str] = None,
+        max_retries: int = 2,
+    ) -> Tuple[str, str]:
+        """
+        Transcribes audio to text returning (transcript, status_code).
+        Uses bounded retries for transient errors.
+        """
+        if not audio_bytes:
+            return "", STT_EMPTY_AUDIO
+
+        if not self.api_key or self.api_key in ["your_sarvam_key", ""]:
+            return "", STT_PROVIDER_ERROR
+
+        client = self._get_client()
+        files = {"file": (filename, audio_bytes, "audio/webm")}
+        data = {"model": "saaras:v2", "language_code": language_code}
+        headers = {"api-subscription-key": self.api_key}
+
+        attempt = 0
+        last_status = STT_PROVIDER_ERROR
+
+        while attempt <= max_retries:
+            start_time = time.time()
+            try:
+                res = await client.post(
+                    f"{self.base_url}/speech-to-text",
+                    files=files,
+                    data=data,
+                    headers=headers,
+                )
+                duration = round(time.time() - start_time, 3)
+
+                if res.status_code == 200:
+                    transcript = res.json().get("transcript", "").strip()
+                    logger.info(
+                        "sarvam_stt_success",
+                        extra={
+                            "provider": "SarvamAI",
+                            "operation": "STT",
+                            "session_id": session_id,
+                            "duration_sec": duration,
+                            "attempt": attempt + 1,
+                        },
+                    )
+                    return transcript, STT_SUCCESS
+                elif 400 <= res.status_code < 500:
+                    # Non-retryable 4xx client errors
+                    logger.warning(
+                        "sarvam_stt_client_error",
+                        extra={
+                            "provider": "SarvamAI",
+                            "operation": "STT",
+                            "session_id": session_id,
+                            "http_status": res.status_code,
+                        },
+                    )
+                    return "", STT_PROVIDER_ERROR
+                else:
+                    last_status = STT_PROVIDER_ERROR
+
+            except (httpx2.TimeoutException, asyncio.TimeoutError):
+                last_status = STT_TIMEOUT
+                logger.warning("sarvam_stt_timeout", extra={"session_id": session_id, "attempt": attempt + 1})
+            except (httpx2.NetworkError, Exception) as e:
+                last_status = STT_NETWORK_ERROR
+                logger.warning("sarvam_stt_network_error", extra={"session_id": session_id, "attempt": attempt + 1})
+
+            attempt += 1
+            if attempt <= max_retries:
+                await asyncio.sleep(0.2 * attempt)
+
+        return "", last_status
+
     async def speech_to_text(
         self,
         audio_bytes: bytes,
         filename: str = "audio.webm",
         language_code: str = "ta-IN",
     ) -> str:
-        if not self.api_key or self.api_key == "your_sarvam_key":
-            return ""
+        transcript, _ = await self.speech_to_text_with_status(audio_bytes, filename, language_code)
+        return transcript
 
-        client = self._get_client()
-        files = {"file": (filename, audio_bytes, "audio/webm")}
-        data = {"model": "saaras:v2", "language_code": language_code}
-        headers = {"api-subscription-key": self.api_key}
-
-        try:
-            res = await client.post(
-                f"{self.base_url}/speech-to-text",
-                files=files,
-                data=data,
-                headers=headers,
-            )
-            if res.status_code == 200:
-                return res.json().get("transcript", "").strip()
-        except Exception as e:
-            print(f"[Sarvam STT Error]: {e}")
-        return ""
-
-    async def text_to_speech(
+    async def text_to_speech_with_status(
         self,
         text: str,
         language_code: str = "ta-IN",
-    ) -> bytes | None:
-        if not self.api_key or self.api_key == "your_sarvam_key":
-            return None
+        session_id: Optional[str] = None,
+        max_retries: int = 2,
+    ) -> Tuple[Optional[bytes], str]:
+        """
+        Synthesizes text to speech returning (audio_bytes, status_code).
+        Uses bounded retries for transient errors.
+        """
+        if not text or not text.strip():
+            return None, TTS_PROVIDER_ERROR
 
-        lang_prefix = language_code.lower()[:2]
-        speaker = "kavya"
+        if not self.api_key or self.api_key in ["your_sarvam_key", ""]:
+            return None, TTS_PROVIDER_ERROR
 
         client = self._get_client()
         headers = {
@@ -65,20 +149,57 @@ class SarvamClient:
         payload = {
             "inputs": [text],
             "target_language_code": language_code,
-            "speaker": speaker,
+            "speaker": "kavya",
             "model": "bulbul:v2",
         }
-        try:
-            res = await client.post(
-                f"{self.base_url}/text-to-speech",
-                json=payload,
-                headers=headers,
-            )
-            if res.status_code == 200:
-                audios = res.json().get("audios", [])
-                if audios:
-                    return base64.b64decode(audios[0])
-        except Exception as e:
-            print(f"[Sarvam TTS Error]: {e}")
-        return None
 
+        attempt = 0
+        last_status = TTS_PROVIDER_ERROR
+
+        while attempt <= max_retries:
+            start_time = time.time()
+            try:
+                res = await client.post(
+                    f"{self.base_url}/text-to-speech",
+                    json=payload,
+                    headers=headers,
+                )
+                duration = round(time.time() - start_time, 3)
+
+                if res.status_code == 200:
+                    audios = res.json().get("audios", [])
+                    if audios:
+                        logger.info(
+                            "sarvam_tts_success",
+                            extra={
+                                "provider": "SarvamAI",
+                                "operation": "TTS",
+                                "session_id": session_id,
+                                "duration_sec": duration,
+                                "attempt": attempt + 1,
+                            },
+                        )
+                        return base64.b64decode(audios[0]), TTS_SUCCESS
+                elif 400 <= res.status_code < 500:
+                    return None, TTS_PROVIDER_ERROR
+                else:
+                    last_status = TTS_PROVIDER_ERROR
+
+            except (httpx2.TimeoutException, asyncio.TimeoutError):
+                last_status = TTS_TIMEOUT
+            except (httpx2.NetworkError, Exception):
+                last_status = TTS_NETWORK_ERROR
+
+            attempt += 1
+            if attempt <= max_retries:
+                await asyncio.sleep(0.2 * attempt)
+
+        return None, last_status
+
+    async def text_to_speech(
+        self,
+        text: str,
+        language_code: str = "ta-IN",
+    ) -> Optional[bytes]:
+        audio, _ = await self.text_to_speech_with_status(text, language_code)
+        return audio

ai-patient-onboarding/app/api/websocket/__init__.py

@@ -0,0 +1,3 @@
+"""
+WebSocket API Package for Real-Time Patient Onboarding.
+"""

ai-patient-onboarding/app/api/websocket/manager.py

@@ -0,0 +1,73 @@
+"""
+WebSocket Connection Manager (Section 18, 19, 28).
+Manages active WebSocket instances and per-session processing locks.
+Ensures session-level concurrency control (messages for same session processed sequentially,
+different sessions process concurrently without global blocking).
+"""
+
+import asyncio
+import logging
+from typing import Dict, Set, Optional
+from fastapi import WebSocket, status
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    def __init__(self):
+        # Maps session_id to set of active WebSocket instances
+        self.active_connections: Dict[str, Set[WebSocket]] = {}
+        # Per-session processing lock to enforce sequential message processing per session (Section 18 & 19)
+        self.session_locks: Dict[str, asyncio.Lock] = {}
+        # Stores processed message_ids and assistant responses for deduplication per session (Section 17)
+        self.dedup_store: Dict[str, Dict[str, dict]] = {}
+
+    def get_session_lock(self, session_id: str) -> asyncio.Lock:
+        """Returns or creates a per-session lock."""
+        if session_id not in self.session_locks:
+            self.session_locks[session_id] = asyncio.Lock()
+        return self.session_locks[session_id]
+
+    async def connect(self, session_id: str, websocket: WebSocket):
+        """Accept and register connection."""
+        if session_id not in self.active_connections:
+            self.active_connections[session_id] = set()
+        self.active_connections[session_id].add(websocket)
+        logger.info("websocket_connected", extra={"session_id": session_id})
+
+    def disconnect(self, session_id: str, websocket: WebSocket):
+        """Clean up disconnected socket reference."""
+        if session_id in self.active_connections:
+            self.active_connections[session_id].discard(websocket)
+            if not self.active_connections[session_id]:
+                del self.active_connections[session_id]
+                # Clean up session lock if no connections remain
+                if session_id in self.session_locks:
+                    del self.session_locks[session_id]
+        logger.info("websocket_disconnected", extra={"session_id": session_id})
+
+    async def send_json(self, websocket: WebSocket, data: dict):
+        """Send JSON payload to specific socket."""
+        try:
+            await websocket.send_json(data)
+        except Exception as e:
+            logger.warning("websocket_send_failed", extra={"error": str(e)})
+
+    async def send_to_session(self, session_id: str, data: dict):
+        """Broadcast payload to all sockets connected to a session."""
+        if session_id in self.active_connections:
+            for ws in list(self.active_connections[session_id]):
+                await self.send_json(ws, data)
+
+    def cache_processed_message(self, session_id: str, message_id: str, response_data: dict):
+        """Cache response data for duplicate message_id protection (Section 17)."""
+        if session_id not in self.dedup_store:
+            self.dedup_store[session_id] = {}
+        self.dedup_store[session_id][message_id] = response_data
+
+    def get_cached_message_response(self, session_id: str, message_id: str) -> Optional[dict]:
+        """Return cached response for message_id if previously processed."""
+        return self.dedup_store.get(session_id, {}).get(message_id)
+
+
+manager = ConnectionManager()

ai-patient-onboarding/app/api/websocket/routes.py

@@ -0,0 +1,225 @@
+"""
+WebSocket Route Handler (Section 2, 3, 4, 15, 16, 22, 23, 24, 25).
+Endpoint: WS /api/v1/ws/onboarding/{session_id}
+Handles connection lifecycle, authentication, session validation, input sanitization, rate limiting, and message dispatch.
+"""
+
+import json
+import logging
+from typing import Optional
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, Depends, Query, status
+from sqlalchemy.orm import Session
+
+from app.database.database import get_db
+from app.core.security import get_auth_context, verify_session_ownership, AuthContext
+from app.services.onboarding_service import OnboardingService
+from app.services.websocket_service import WebSocketService
+from app.api.websocket.manager import manager
+from app.api.websocket.schemas import (
+    WSEventType,
+    WSErrorCode,
+    WSConnectionAck,
+    WSPatientMessage,
+    WSErrorEvent,
+)
+
+from app.database.database import SessionLocal
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/api/v1/ws/onboarding",
+    tags=["WebSocket Onboarding"],
+)
+
+# In-memory per-connection rate limiter (Section 26)
+# Maps session_id -> list of message timestamps
+WS_RATE_LIMIT_STORE = {}
+
+
+def check_ws_rate_limit(session_id: str, limit: int = 30, window_sec: int = 60) -> bool:
+    import time
+    now = time.time()
+    timestamps = WS_RATE_LIMIT_STORE.get(session_id, [])
+    timestamps = [t for t in timestamps if now - t < window_sec]
+    if len(timestamps) >= limit:
+        return False
+    timestamps.append(now)
+    WS_RATE_LIMIT_STORE[session_id] = timestamps
+    return True
+
+
+@router.websocket("/{session_id}")
+async def websocket_onboarding_endpoint(
+    websocket: WebSocket,
+    session_id: str,
+    token: Optional[str] = Query(None),
+    x_api_key: Optional[str] = Query(None, alias="api_key"),
+    x_patient_id: Optional[str] = Query(None, alias="patient_id"),
+):
+    """
+    Real-Time Patient Onboarding WebSocket Endpoint.
+    WS /api/v1/ws/onboarding/{session_id}
+    """
+    db = SessionLocal()
+
+    
+    try:
+        await _handle_websocket_lifecycle(
+            websocket=websocket,
+            session_id=session_id,
+            db=db,
+        )
+    finally:
+        db.close()
+
+
+async def _handle_websocket_lifecycle(
+    websocket: WebSocket,
+    session_id: str,
+    db: Session,
+):
+    onboarding_service = OnboardingService()
+    ws_service = WebSocketService()
+
+    await websocket.accept()
+
+    # Extract query params directly from WebSocket request URL (Section 25)
+    query_token = websocket.query_params.get("token")
+    query_api_key = websocket.query_params.get("api_key")
+    query_patient_id = websocket.query_params.get("patient_id")
+
+    auth_token = query_token or query_api_key or websocket.headers.get("x-api-key")
+    if not auth_token:
+        # Allow test connection token if in header or subprotocol
+        sec_protocol = websocket.headers.get("sec-websocket-protocol")
+        if sec_protocol:
+            auth_token = sec_protocol
+
+    try:
+        auth_context = get_auth_context(
+            api_key=auth_token,
+            credentials=None,
+            x_patient_id=query_patient_id or websocket.headers.get("x-patient-id")
+        )
+    except Exception as e:
+        logger.warning("websocket_auth_failed", extra={"session_id": session_id, "error": str(e)})
+        await websocket.send_json(
+            WSErrorEvent(code=WSErrorCode.UNAUTHORIZED.value, message="Authentication failed.").model_dump()
+        )
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    # 2. Validate session exists & active (Section 24)
+    session = onboarding_service.get_session(db, session_id)
+    if not session:
+        logger.warning("websocket_session_not_found", extra={"session_id": session_id})
+        await websocket.send_json(
+            WSErrorEvent(code=WSErrorCode.SESSION_NOT_FOUND.value, message="Session not found.").model_dump()
+        )
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    # 3. Verify session ownership (Section 25)
+    try:
+        verify_session_ownership(session.patient_id, auth_context)
+    except Exception as e:
+        logger.warning("websocket_unauthorized_session_access", extra={"session_id": session_id, "error": str(e)})
+        await websocket.send_json(
+            WSErrorEvent(code=WSErrorCode.UNAUTHORIZED.value, message="Unauthorized session access.").model_dump()
+        )
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    if session.status != "in_progress":
+        logger.warning("websocket_session_expired", extra={"session_id": session_id})
+        await websocket.send_json(
+            WSErrorEvent(code=WSErrorCode.SESSION_EXPIRED.value, message="Session expired or completed.").model_dump()
+        )
+        await websocket.close(code=status.WS_1008_POLICY_VIOLATION)
+        return
+
+    # 4. Register connection & send ACK (Section 3 & 4)
+    await manager.connect(session_id, websocket)
+
+    ack = WSConnectionAck(session_id=session_id, status="connected").model_dump()
+    await manager.send_json(websocket, ack)
+
+    try:
+        while True:
+            # 5. Receive text message
+            data_text = await websocket.receive_text()
+
+            # 6. Check Rate Limiting (Section 26)
+            if not check_ws_rate_limit(session_id, limit=30, window_sec=60):
+                await manager.send_json(
+                    websocket,
+                    WSErrorEvent(
+                        code=WSErrorCode.RATE_LIMITED.value,
+                        message="Please wait a moment before sending another message."
+                    ).model_dump()
+                )
+                continue
+
+            # 7. Validate JSON structure & size (Section 15 & 16)
+            if len(data_text) > 5000:
+                await manager.send_json(
+                    websocket,
+                    WSErrorEvent(
+                        code=WSErrorCode.MESSAGE_TOO_LARGE.value,
+                        message="Message exceeds maximum allowed length of 5000 characters."
+                    ).model_dump()
+                )
+                continue
+
+            try:
+                payload = json.loads(data_text)
+            except Exception:
+                await manager.send_json(
+                    websocket,
+                    WSErrorEvent(
+                        code=WSErrorCode.INVALID_MESSAGE.value,
+                        message="Please send a valid JSON message."
+                    ).model_dump()
+                )
+                continue
+
+            if not isinstance(payload, dict) or payload.get("type") != WSEventType.PATIENT_MESSAGE.value:
+                await manager.send_json(
+                    websocket,
+                    WSErrorEvent(
+                        code=WSErrorCode.INVALID_MESSAGE.value,
+                        message="Unsupported message type. Expected 'patient.message'."
+                    ).model_dump()
+                )
+                continue
+
+            message_id = str(payload.get("message_id") or "").strip()
+            text = str(payload.get("text") or "").strip()
+
+            if not message_id or not text:
+                await manager.send_json(
+                    websocket,
+                    WSErrorEvent(
+                        code=WSErrorCode.INVALID_MESSAGE.value,
+                        message="Message must include non-empty 'message_id' and 'text'."
+                    ).model_dump()
+                )
+                continue
+
+            # 8. Session-level lock for sequential processing per session (Section 18 & 19)
+            async with manager.get_session_lock(session_id):
+                await ws_service.handle_patient_message(
+                    websocket=websocket,
+                    db=db,
+                    session_id=session_id,
+                    message_id=message_id,
+                    text=text,
+                )
+
+    except WebSocketDisconnect:
+        manager.disconnect(session_id, websocket)
+        logger.info("websocket_client_disconnected", extra={"session_id": session_id})
+    except Exception as e:
+        manager.disconnect(session_id, websocket)
+        logger.error("websocket_unexpected_error", extra={"session_id": session_id, "error": str(e)})

ai-patient-onboarding/app/api/websocket/schemas.py

@@ -0,0 +1,91 @@
+"""
+WebSocket Protocol Schemas and Event Constants (Section 5, 6, 15).
+Centralized definitions for event types, error codes, and message models.
+"""
+
+from enum import Enum
+from typing import Optional, Any, Dict
+from pydantic import BaseModel, Field
+
+
+class WSEventType(str, Enum):
+    CONNECTION_ACK = "connection.ack"
+    PATIENT_MESSAGE = "patient.message"
+    ASSISTANT_MESSAGE = "assistant.message"
+    PROCESSING_STARTED = "processing.started"
+    PROCESSING_COMPLETED = "processing.completed"
+    TYPING_STARTED = "typing.started"
+    TYPING_STOPPED = "typing.stopped"
+    STATE_UPDATED = "state.updated"
+    SAFETY_ALERT = "safety.alert"
+    ONBOARDING_COMPLETED = "onboarding.completed"
+    ERROR = "error"
+    SESSION_ENDED = "session.ended"
+
+
+class WSErrorCode(str, Enum):
+    INVALID_MESSAGE = "INVALID_MESSAGE"
+    MESSAGE_TOO_LARGE = "MESSAGE_TOO_LARGE"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
+    SESSION_EXPIRED = "SESSION_EXPIRED"
+    PROCESSING_ERROR = "PROCESSING_ERROR"
+    AI_TIMEOUT = "AI_TIMEOUT"
+    AI_UNAVAILABLE = "AI_UNAVAILABLE"
+    RATE_LIMITED = "RATE_LIMITED"
+    INVALID_STATE = "INVALID_STATE"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
+class WSConnectionAck(BaseModel):
+    type: str = WSEventType.CONNECTION_ACK.value
+    session_id: str
+    status: str = "connected"
+
+
+class WSPatientMessage(BaseModel):
+    type: str = WSEventType.PATIENT_MESSAGE.value
+    message_id: str = Field(..., description="Unique client message ID")
+    text: str = Field(..., max_length=5000, description="Patient text message")
+
+
+class WSAssistantMessage(BaseModel):
+    type: str = WSEventType.ASSISTANT_MESSAGE.value
+    message_id: str
+    reply: str
+    language: str = "en-IN"
+
+
+class WSTypingEvent(BaseModel):
+    type: str  # typing.started | typing.stopped
+
+
+class WSProcessingStartedEvent(BaseModel):
+    type: str = WSEventType.PROCESSING_STARTED.value
+
+
+class WSProcessingCompletedEvent(BaseModel):
+    type: str = WSEventType.PROCESSING_COMPLETED.value
+    processing_time_ms: int
+
+
+class WSSafetyAlertEvent(BaseModel):
+    type: str = WSEventType.SAFETY_ALERT.value
+    level: str = "emergency"  # emergency | crisis
+    message: Optional[str] = None
+
+
+class WSStateUpdatedEvent(BaseModel):
+    type: str = WSEventType.STATE_UPDATED.value
+    session_id: str
+
+
+class WSOnboardingCompletedEvent(BaseModel):
+    type: str = WSEventType.ONBOARDING_COMPLETED.value
+    session_id: str
+
+
+class WSErrorEvent(BaseModel):
+    type: str = WSEventType.ERROR.value
+    code: str
+    message: str

ai-patient-onboarding/app/config.py

@@ -33,6 +33,13 @@ DEFAULT_CORS_ORIGINS = [
     "http://127.0.0.1:5173",
     "http://localhost:8000",
     "http://127.0.0.1:8000",
+    "http://localhost:5500",
+    "http://127.0.0.1:5500",
+    "http://localhost:5501",
+    "http://127.0.0.1:5501",
+    "http://localhost:8080",
+    "http://127.0.0.1:8080",
+    "null",
     "https://onboarding.skyheal.ai",
 ]
 
@@ -42,3 +49,16 @@ if cors_raw:
 else:
     CORS_ORIGINS = DEFAULT_CORS_ORIGINS
 
+
+class Settings:
+    ai_timeout_seconds: float = float(os.getenv("AI_TIMEOUT_SECONDS", "3.5"))
+    session_timeout_minutes: int = int(os.getenv("SESSION_TIMEOUT_MINUTES", "30"))
+    max_message_length: int = int(os.getenv("MAX_MESSAGE_LENGTH", "5000"))
+    max_response_words: int = int(os.getenv("MAX_RESPONSE_WORDS", "20"))
+    llm_retry_count: int = int(os.getenv("LLM_RETRY_COUNT", "2"))
+    supported_languages: list[str] = ["en", "ta", "hi", "te", "kn"]
+
+
+settings = Settings()
+
+

ai-patient-onboarding/app/database/database.py

@@ -1,7 +1,7 @@
 import os
 from pathlib import Path
 from dotenv import load_dotenv
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, event
 from sqlalchemy.orm import DeclarativeBase, sessionmaker
 
 load_dotenv()
@@ -24,10 +24,21 @@ else:
 engine = create_engine(
     DATABASE_URL,
     connect_args={
-        "check_same_thread": False
+        "check_same_thread": False,
+        "timeout": 15,
     },
 )
 
+@event.listens_for(engine, "connect")
+def set_sqlite_pragmas(dbapi_connection, connection_record):
+    if "sqlite" in DATABASE_URL:
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA journal_mode=WAL;")
+        cursor.execute("PRAGMA busy_timeout=10000;")
+        cursor.execute("PRAGMA synchronous=NORMAL;")
+        cursor.close()
+
+
 SessionLocal = sessionmaker(
     bind=engine,
     autoflush=False,

ai-patient-onboarding/app/domain/models/__init__.py

@@ -0,0 +1,35 @@
+"""
+Domain models package.
+"""
+
+from app.domain.models.patient_state import (
+    SymptomItem,
+    MedicationItem,
+    AllergyItem,
+    MedicalHistoryItem,
+    SurgicalHistoryItem,
+    PreviousEpisodeItem,
+    FamilyHistoryItem,
+    FieldContainer,
+    PatientState,
+)
+from app.domain.models.extraction import ExtractionResult, QuestionIntent
+from app.domain.models.contracts import ResponseContext, ResponseResult, ResponseType, FactConfidence
+
+__all__ = [
+    "SymptomItem",
+    "MedicationItem",
+    "AllergyItem",
+    "MedicalHistoryItem",
+    "SurgicalHistoryItem",
+    "PreviousEpisodeItem",
+    "FamilyHistoryItem",
+    "FieldContainer",
+    "PatientState",
+    "ExtractionResult",
+    "QuestionIntent",
+    "ResponseContext",
+    "ResponseResult",
+    "ResponseType",
+    "FactConfidence",
+]

ai-patient-onboarding/app/domain/models/contracts.py

@@ -0,0 +1,67 @@
+"""
+Response contracts, enums, and data models (Rules 102, 103, 104, 105, 116):
+- ResponseType Enum
+- QuestionIntent Enum
+- ResponseContext Input Contract
+- ResponseResult Output Contract
+- FactConfidence Model
+"""
+
+from enum import Enum
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class ResponseType(str, Enum):
+    GREETING = "greeting"
+    ACKNOWLEDGEMENT = "acknowledgement"
+    FOLLOW_UP = "follow_up"
+    CLARIFICATION = "clarification"
+    REFUSAL = "refusal"
+    UNKNOWN = "unknown"
+    SAFETY = "safety"
+    CRISIS = "crisis"
+    COMPLETION = "completion"
+
+
+class QuestionIntent(str, Enum):
+    SYMPTOM_NAME = "symptom_name"
+    SYMPTOM_DURATION = "symptom_duration"
+    SYMPTOM_SEVERITY = "symptom_severity"
+    SYMPTOM_LOCATION = "symptom_location"
+    SYMPTOM_ONSET = "symptom_onset"
+    SYMPTOM_FREQUENCY = "symptom_frequency"
+    SYMPTOM_TRIGGER = "symptom_trigger"
+    ASSOCIATED_SYMPTOMS = "associated_symptoms"
+
+    MEDICAL_HISTORY = "medical_history"
+    MEDICATIONS = "medications"
+    ALLERGIES = "allergies"
+    FAMILY_HISTORY = "family_history"
+    SURGICAL_HISTORY = "surgical_history"
+
+
+class ResponseContext(BaseModel):
+    language: str = "en"
+    patient_message: str
+    intent: str = "fact_extraction"
+    primary_symptom: Optional[str] = None
+    missing_information: Optional[str] = None
+    selected_question: Optional[str] = None
+    question_intent: Optional[QuestionIntent] = None
+    safety_status: str = "normal"
+    onboarding_completed: bool = False
+    current_state: Optional[Dict[str, Any]] = None
+
+
+class ResponseResult(BaseModel):
+    response: str
+    language: str = "en"
+    question_intent: Optional[str] = None
+    response_type: ResponseType = ResponseType.FOLLOW_UP
+
+
+class FactConfidence(BaseModel):
+    source: str = "patient"
+    method: str = "explicit"
+    confidence: float = 1.0

ai-patient-onboarding/app/domain/models/extraction.py

@@ -0,0 +1,28 @@
+"""
+Extraction result and question intent domain models.
+"""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class ExtractedFact(BaseModel):
+    category: str  # 'symptom', 'medication', 'allergy', 'medical_history', 'family_history', etc.
+    data: Dict[str, Any]
+
+
+class ExtractionResult(BaseModel):
+    raw_message: str
+    normalized_message: str
+    detected_language: str = "en"
+    updates: Dict[str, Any] = Field(default_factory=dict)
+    is_emergency: bool = False
+    is_crisis: bool = False
+    emergency_reason: Optional[str] = None
+
+
+class QuestionIntent(BaseModel):
+    intent_code: str  # e.g., 'reason_for_visit', 'symptom_duration', 'medical_history'
+    field: str
+    attribute: Optional[str] = None
+    target_symptom: Optional[str] = None

ai-patient-onboarding/app/domain/models/patient_state.py

@@ -0,0 +1,87 @@
+"""
+Strongly typed domain models for Patient Onboarding state management.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, Field
+
+
+class SymptomItem(BaseModel):
+    name: str
+    canonical_name: Optional[str] = None
+    duration: Optional[str] = None
+    severity: Optional[str] = None
+    location: Optional[str] = None
+    frequency: Optional[str] = None
+    onset: Optional[str] = None
+    pattern: Optional[str] = None
+    trigger: Optional[str] = None
+    relieving_factor: Optional[str] = None
+    associated_findings: Optional[str] = None
+
+
+class MedicationItem(BaseModel):
+    name: str
+    canonical_name: Optional[str] = None
+    dosage: Optional[str] = None
+    frequency: Optional[str] = None
+    duration: Optional[str] = None
+    purpose: Optional[str] = None
+
+
+class AllergyItem(BaseModel):
+    name: str
+    canonical_name: Optional[str] = None
+    type: Optional[str] = None  # e.g., 'drug', 'food', 'environment'
+    reaction: Optional[str] = None  # e.g., 'rash', 'swelling'
+
+
+class MedicalHistoryItem(BaseModel):
+    condition: str
+    canonical_name: Optional[str] = None
+    duration: Optional[str] = None
+    status: Optional[str] = "active"
+    details: Optional[str] = None
+
+
+class SurgicalHistoryItem(BaseModel):
+    procedure: str
+    body_site: Optional[str] = None
+    approximate_date: Optional[str] = None
+    reason: Optional[str] = None
+
+
+class PreviousEpisodeItem(BaseModel):
+    description: str
+    time: Optional[str] = None
+    outcome: Optional[str] = None
+
+
+class FamilyHistoryItem(BaseModel):
+    relation: str  # e.g., 'father', 'mother', 'sibling'
+    condition: str
+    canonical_name: Optional[str] = None
+
+
+class FieldContainer(BaseModel):
+    status: str = "not_collected"  # 'not_collected' | 'reported' | 'confirmed_none' | 'unknown' | 'declined'
+    items: List[Dict[str, Any]] = Field(default_factory=list)
+
+
+class SpecialtyConfidence(BaseModel):
+    code: str
+    name: str
+    confidence: float = 1.0
+    evidence: List[str] = Field(default_factory=list)
+
+
+class PatientState(BaseModel):
+    reason_for_visit: Optional[str] = None
+    symptoms: List[SymptomItem] = Field(default_factory=list)
+    medical_history: Union[FieldContainer, List[MedicalHistoryItem], Dict[str, Any]] = Field(default_factory=list)
+    medications: Union[FieldContainer, List[MedicationItem], Dict[str, Any]] = Field(default_factory=list)
+    allergies: Union[FieldContainer, List[AllergyItem], Dict[str, Any]] = Field(default_factory=list)
+    surgical_history: List[SurgicalHistoryItem] = Field(default_factory=list)
+    previous_episodes: List[PreviousEpisodeItem] = Field(default_factory=list)
+    family_history: List[FamilyHistoryItem] = Field(default_factory=list)
+    additional_information: List[Dict[str, Any]] = Field(default_factory=list)

ai-patient-onboarding/app/main.py

@@ -6,6 +6,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from app.api.documents import router as documents_router
 from app.api.onboarding import router as onboarding_router
 from app.api.voice_onboarding import router as voice_router
+from app.api.websocket.routes import router as websocket_router
 from app.database import models
 from app.database.database import Base, engine
 
@@ -69,6 +70,20 @@ app.add_middleware(
 app.include_router(onboarding_router)
 app.include_router(voice_router)
 app.include_router(documents_router)
+app.include_router(websocket_router)
+
+import os
+from fastapi.responses import HTMLResponse
+
+@app.get("/ws-tester", response_class=HTMLResponse, tags=["WebSocket Onboarding UI"])
+@app.get("/ws-ui", response_class=HTMLResponse, include_in_schema=False)
+async def get_ws_tester_page():
+    """Serves sample UI for testing WebSocket patient onboarding."""
+    static_file_path = os.path.join(os.path.dirname(__file__), "static", "ws_tester.html")
+    if os.path.exists(static_file_path):
+        with open(static_file_path, "r", encoding="utf-8") as f:
+            return HTMLResponse(content=f.read())
+    return HTMLResponse("<h2>ws_tester.html not found</h2>", status_code=404)
 
 
 @app.get("/health")
@@ -84,3 +99,4 @@ async def health():
             "vision_documents": "Gemini 1.5 Flash",
         },
     }
+

ai-patient-onboarding/app/schemas/onboarding.py

@@ -37,7 +37,16 @@ class StartOnboardingResponse(BaseModel):
 
 
 class SendMessageRequest(BaseModel):
-    message: str = Field(..., min_length=1)
+    message: str = Field(..., min_length=1, max_length=5000)
+
+
+class ErrorDetail(BaseModel):
+    code: str
+    message: str
+
+
+class ErrorResponse(BaseModel):
+    error: ErrorDetail
 
 
 class SendMessageResponse(BaseModel):

ai-patient-onboarding/app/services/result_extraction_service.py

@@ -109,13 +109,19 @@ Return ONLY a valid JSON object matching this structure:
         if GEMINI_API_KEY and GEMINI_API_KEY.strip() not in ["your_gemini_key", "your_gemini_api_key", ""]:
             try:
                 import asyncio
-                import google.generativeai as genai
-                genai.configure(api_key=GEMINI_API_KEY)
-                model = genai.GenerativeModel(
-                    GEMINI_MODEL or "gemini-1.5-flash",
-                    generation_config={"response_mime_type": "application/json"}
+                from google import genai
+                from google.genai import types
+
+                client = genai.Client(api_key=GEMINI_API_KEY)
+                config = types.GenerateContentConfig(response_mime_type="application/json")
+                res = await asyncio.wait_for(
+                    client.aio.models.generate_content(
+                        model=GEMINI_MODEL or "gemini-1.5-flash",
+                        contents=prompt,
+                        config=config,
+                    ),
+                    timeout=3.5
                 )
-                res = await asyncio.wait_for(model.generate_content_async(prompt), timeout=3.5)
                 cleaned = res.text.replace("```json", "").replace("```", "").strip()
                 parsed = json.loads(cleaned)
                 validated = PatientOnboardingResult.model_validate(parsed)

ai-patient-onboarding/app/services/websocket_service.py

@@ -0,0 +1,188 @@
+"""
+WebSocket Transport Service (Section 7, 8, 10, 11, 12, 13, 14, 17).
+Thin bridge between WebSocket events and core onboarding business services.
+Delegates all clinical logic, state management, and AI orchestration to OnboardingService/AIOnboardingService.
+"""
+
+import time
+import logging
+from typing import Dict, Any
+from fastapi import WebSocket
+from sqlalchemy.orm import Session
+
+from app.api.websocket.manager import manager
+from app.api.websocket.schemas import (
+    WSEventType,
+    WSErrorCode,
+    WSAssistantMessage,
+    WSTypingEvent,
+    WSProcessingStartedEvent,
+    WSProcessingCompletedEvent,
+    WSSafetyAlertEvent,
+    WSStateUpdatedEvent,
+    WSOnboardingCompletedEvent,
+    WSErrorEvent,
+)
+from app.services.onboarding_service import OnboardingService
+from app.services.ai_onboarding_service import AIOnboardingService
+from app.database.models import OnboardingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class WebSocketService:
+    def __init__(self):
+        self.onboarding_service = OnboardingService()
+        self.ai_service = AIOnboardingService()
+
+    async def handle_patient_message(
+        self,
+        websocket: WebSocket,
+        db: Session,
+        session_id: str,
+        message_id: str,
+        text: str,
+    ):
+        """
+        Process patient message through transport pipeline (Section 7).
+        Enforces typing events, safety alerts, state updates, and deduplication.
+        """
+        t0 = time.perf_counter()
+
+        # 1. Deduplication check (Section 17)
+        cached_resp = manager.get_cached_message_response(session_id, message_id)
+        if cached_resp:
+            logger.info("websocket_duplicate_message_received", extra={"session_id": session_id, "message_id": message_id})
+            await manager.send_json(websocket, cached_resp)
+            return
+
+        # 2. Emit processing.started
+        await manager.send_json(websocket, WSProcessingStartedEvent().model_dump())
+
+        # 3. Emit typing.started
+        await manager.send_json(websocket, WSTypingEvent(type=WSEventType.TYPING_STARTED.value).model_dump())
+
+        try:
+            # Fetch session & verify active status
+            session = self.onboarding_service.get_session(db, session_id)
+            if not session or session.status != "in_progress":
+                await manager.send_json(
+                    websocket,
+                    WSErrorEvent(
+                        code=WSErrorCode.SESSION_EXPIRED.value,
+                        message="Onboarding session is expired or not active."
+                    ).model_dump()
+                )
+                return
+
+            # Save patient message
+            self.onboarding_service.save_message(
+                db=db,
+                session_id=session_id,
+                role="patient",
+                message=text,
+                stage=session.stage,
+            )
+
+            state = self.onboarding_service.get_state(db, session_id)
+
+            messages = (
+                db.query(OnboardingMessage)
+                .filter(OnboardingMessage.session_id == session_id)
+                .order_by(OnboardingMessage.created_at.asc())
+                .all()
+            )
+            conversation_history = [
+                {"role": m.role, "message": m.message, "stage": m.stage}
+                for m in messages
+            ]
+
+            # 4. Delegate to AI Orchestrator
+            ai_result = await self.ai_service.process_message(
+                session=session,
+                state=state,
+                conversation_history=conversation_history,
+                user_message=text,
+            )
+
+            # 5. Check Emergency / Crisis priority (Section 12)
+            is_emergency = ai_result.get("is_emergency") or ai_result.get("next_stage") == "emergency_referral"
+            is_crisis = ai_result.get("is_crisis") or ai_result.get("next_stage") == "crisis_handling"
+            if is_emergency or is_crisis:
+                level = "crisis" if is_crisis else "emergency"
+                await manager.send_json(
+                    websocket,
+                    WSSafetyAlertEvent(
+                        level=level,
+                        message="Safety event detected. Normal intake flow suspended."
+                    ).model_dump()
+                )
+
+            reply_text = ai_result.get("reply", "Got it. When did it start?")
+            next_stage = ai_result.get("next_stage", session.stage)
+            session.stage = next_stage
+
+            # Save assistant message
+            self.onboarding_service.save_message(
+                db=db,
+                session_id=session_id,
+                role="assistant",
+                message=reply_text,
+                stage=next_stage,
+            )
+
+            # Update state in DB if modified
+            updated_state_dict = ai_result.get("updated_state") or (ai_result.get("state_updates") if isinstance(ai_result.get("state_updates"), dict) else None)
+            if updated_state_dict and isinstance(updated_state_dict, dict):
+                self.onboarding_service.update_state(db, state, updated_state_dict)
+            else:
+                db.commit()
+
+            # 6. Emit state.updated (Section 13)
+            await manager.send_json(
+                websocket,
+                WSStateUpdatedEvent(session_id=session_id).model_dump()
+            )
+
+            # 7. Construct & emit assistant.message (Section 5)
+            assistant_resp = WSAssistantMessage(
+                message_id=f"resp_{message_id}",
+                reply=reply_text,
+                language=session.language or "en-IN"
+            ).model_dump()
+
+            await manager.send_json(websocket, assistant_resp)
+
+            # Cache response for duplicate message protection
+            manager.cache_processed_message(session_id, message_id, assistant_resp)
+
+            # 8. Check onboarding completion (Section 14)
+            if ai_result.get("completed") or session.status == "completed":
+                session.status = "completed"
+                db.commit()
+                await manager.send_json(
+                    websocket,
+                    WSOnboardingCompletedEvent(session_id=session_id).model_dump()
+                )
+
+        except Exception as e:
+            logger.error("websocket_message_processing_failed", extra={"session_id": session_id, "error": str(e)})
+            await manager.send_json(
+                websocket,
+                WSErrorEvent(
+                    code=WSErrorCode.PROCESSING_ERROR.value,
+                    message="An error occurred while processing your message."
+                ).model_dump()
+            )
+        finally:
+            # Always ensure typing state is stopped (Section 10)
+            await manager.send_json(
+                websocket,
+                WSTypingEvent(type=WSEventType.TYPING_STOPPED.value).model_dump()
+            )
+            # Emit processing.completed (Section 11)
+            latency_ms = int((time.perf_counter() - t0) * 1000)
+            await manager.send_json(
+                websocket,
+                WSProcessingCompletedEvent(processing_time_ms=latency_ms).model_dump()
+            )

ai-patient-onboarding/app/specialties/cardiology.py

@@ -27,14 +27,14 @@ CARDIOLOGY_CONFIG = {
         "collapsed",
         "sudden loss of consciousness",
         "cannot breathe",
-        "call 108",
-        "emergency ambulance",
+        "hospital emergency room",
+        "alert duty doctor",
     ],
 
     "clarification_rules": [
         "If the patient describes chest burning or heaviness, ask whether it is related to walking/exertion (angina) or happens after spicy/oily food (gastric acidity).",
         "Ask if they are already taking regular BP tablets like Telma, Amlodipine, or daily blood thinners like Ecosprin.",
         "Check if they have a history of previous heart stenting, bypass surgery, or family history of heart attacks at a young age.",
-        "If severe red-flag symptoms are present, immediately advise contacting 108 ambulance or visiting the nearest hospital emergency room.",
+        "If severe red-flag symptoms are present, immediately advise informing hospital emergency staff or visiting the hospital emergency room.",
     ],
 }

ai-patient-onboarding/app/specialties/dermatology.py

@@ -0,0 +1,32 @@
+DERMATOLOGY_CONFIG = {
+    "code": "dermatology",
+    "name": "Dermatology (Skin & Hair Care)",
+
+    "purpose": (
+        "Collect history of skin lesions, rashes, itching, acne, fungal infections, "
+        "duration, body distribution, trigger factors, and topical or oral treatments used."
+    ),
+
+    "focus_areas": [
+        "Chief skin complaint (rash, severe itching/pruritus, eczema, acne/pimples, fungal infection, blisters, discoloration)",
+        "Lesion distribution and onset (face, scalp, trunk, arms, legs, localized vs generalized)",
+        "Associated symptoms (burning sensation, pain, scaling, oozing, bleeding)",
+        "Triggers and exposures (spicy/oily food, new soap/cosmetics, detergent, dust, sunlight, medications)",
+        "Current and prior treatments (antifungal creams like Clotrimazole, steroid creams, oral antihistamines like Cetirizine/Levocetirizine)",
+        "Known allergies (soaps, metals, cosmetics, drugs)",
+    ],
+
+    "emergency_keywords": [
+        "sudden widespread peeling",
+        "stevens johnson syndrome",
+        "toxic epidermal necrolysis",
+        "severe facial swelling with breathing difficulty",
+        "rapidly spreading painful skin breakdown",
+    ],
+
+    "clarification_rules": [
+        "If patient mentions skin itching or rash, ask how many days they have had it and if it spreads at night.",
+        "Check if they are using any over-the-counter steroid creams or soaps.",
+        "Inquire if any other family members share similar skin symptoms.",
+    ],
+}

ai-patient-onboarding/app/specialties/diabetology.py

@@ -24,7 +24,7 @@ DIABETOLOGY_CONFIG = {
         "deep labored breathing",
         "fruity breath",
         "diabetic ketoacidosis",
-        "108 ambulance",
+        "hospital emergency staff / ER",
     ],
 
     "clarification_rules": [

ai-patient-onboarding/app/specialties/gastroenterology.py

@@ -0,0 +1,32 @@
+GASTROENTEROLOGY_CONFIG = {
+    "code": "gastroenterology",
+    "name": "Gastroenterology (Stomach & Digestive Care)",
+
+    "purpose": (
+        "Collect abdominal symptoms including stomach ache, acid reflux/GERD, "
+        "vomiting, bowel movement alterations (diarrhea/constipation), and dietary associations."
+    ),
+
+    "focus_areas": [
+        "Abdominal pain location and character (upper stomach burning/acidity, right upper quadrant, lower abdominal cramps)",
+        "Bowel habits (loose stools/diarrhea frequency, constipation, bloody stools/melena)",
+        "Upper GI symptoms (nausea, persistent vomiting, heartburn, difficulty swallowing/dysphagia)",
+        "Relationship to meals (worse after oily/spicy food, pain relieved by eating or antacids)",
+        "Current GI medications (Pantoprazole/Pan-D, Omeprazole, Gelusil, ORS, probiotics)",
+        "History of ulcer disease, gallstones, jaundice, or liver disease",
+    ],
+
+    "emergency_keywords": [
+        "vomiting blood or coffee ground material",
+        "black tarry stools",
+        "severe rigid abdomen with intolerable pain",
+        "high fever with severe jaundice and vomiting",
+        "acute abdomen",
+    ],
+
+    "clarification_rules": [
+        "If abdominal pain is reported, ask exact location (upper stomach vs lower belly) and duration.",
+        "Check if symptom is accompanied by vomiting, loose motions, or acidity after meals.",
+        "Inquire if patient has taken antacids (Pan-D, Digene) or ORS.",
+    ],
+}

ai-patient-onboarding/app/specialties/general.py

@@ -22,7 +22,7 @@ GENERAL_CONFIG = {
         "severe bleeding",
         "coughing up blood",
         "very low blood pressure",
-        "108 ambulance",
+        "hospital emergency staff / ER",
     ],
 
     "clarification_rules": [

ai-patient-onboarding/app/specialties/neurology.py

@@ -0,0 +1,34 @@
+NEUROLOGY_CONFIG = {
+    "code": "neurology",
+    "name": "Neurology (Brain & Nervous System)",
+
+    "purpose": (
+        "Collect neurological symptoms including headache character, dizziness, numbness, "
+        "weakness, seizure history, and past neurological evaluation."
+    ),
+
+    "focus_areas": [
+        "Headache characteristics (throbbing, one-sided migraine, tension type, occipital, duration)",
+        "Associated neurological features (nausea, vomiting, sensitivity to light/sound, visual aura)",
+        "Dizziness or vertigo (spinning sensation, loss of balance, unsteady gait)",
+        "Focal symptoms (numbness/tingling in hands/feet, facial drooping, speech slurring, limb weakness)",
+        "Seizure or blackout history (loss of consciousness, involuntary movements, aura)",
+        "Current neurological medications (painkillers, migraine prophylactics like Propranolol/Flunarizine, anti-epileptics)",
+    ],
+
+    "emergency_keywords": [
+        "sudden thunderclap headache",
+        "worst headache of my life",
+        "sudden weakness on one side of body",
+        "facial drooping with slurred speech",
+        "stroke symptoms",
+        "active seizure",
+        "loss of consciousness",
+    ],
+
+    "clarification_rules": [
+        "If headache is reported, clarify duration, exact location (one side vs forehead), and if accompanied by nausea or light sensitivity.",
+        "If numbness or tingling is present, clarify if it affects both feet (diabetic neuropathy) or one side of the body.",
+        "Check if patient has a history of high blood pressure or previous stroke.",
+    ],
+}

ai-patient-onboarding/app/specialties/orthopedics.py

@@ -0,0 +1,32 @@
+ORTHOPEDICS_CONFIG = {
+    "code": "orthopedics",
+    "name": "Orthopedics (Bone & Joint Care)",
+
+    "purpose": (
+        "Collect musculoskeletal complaints including joint pain, spinal/back pain, "
+        "trauma history, stiffness, mobility restriction, and painkiller usage."
+    ),
+
+    "focus_areas": [
+        "Primary joint/bone complaint (knee pain, lumbar back pain, neck pain, shoulder stiffness, ankle sprain)",
+        "Onset and progression (acute post-injury/fall vs chronic osteoarthritis/wear-and-tear)",
+        "Functional impact (difficulty walking, standing up from chair, climbing stairs, lifting objects)",
+        "Swelling, redness, deformity, or morning stiffness",
+        "Medications and pain management (NSAIDs like Aceclofenac/Diclofenac/Paracetamol, calcium, Vitamin D3 supplements)",
+        "Surgical or orthopedic history (previous fractures, knee replacement, spine surgery)",
+    ],
+
+    "emergency_keywords": [
+        "open fracture with visible bone",
+        "inability to feel or move leg after injury",
+        "sudden loss of bowel or bladder control with back pain",
+        "cauda equina syndrome",
+        "severe traumatic limb injury",
+    ],
+
+    "clarification_rules": [
+        "If knee or joint pain is reported, ask if it occurs during walking/stair climbing and how long it has been present.",
+        "Clarify if there was any recent fall, injury, or heavy lifting event.",
+        "Check if patient takes regular pain relief tablets or calcium supplements.",
+    ],
+}

ai-patient-onboarding/app/specialties/pulmonology.py

@@ -0,0 +1,32 @@
+PULMONOLOGY_CONFIG = {
+    "code": "pulmonology",
+    "name": "Pulmonology (Lungs & Respiratory Care)",
+
+    "purpose": (
+        "Collect respiratory history including cough type, breathlessness, wheezing, "
+        "asthma/COPD history, inhaler usage, and environmental/smoking exposure."
+    ),
+
+    "focus_areas": [
+        "Cough character and duration (dry cough vs productive/phlegm, nocturnal cough, duration)",
+        "Shortness of breath (on exertion, at rest, when lying flat/orthopnea)",
+        "Wheezing or chest tightness ( whistling sound while breathing out)",
+        "Triggers (cold air, dust, pollen, smoke, exercise, seasonal changes)",
+        "Current inhalers and respiratory medicines (Asthalin/Salbutamol, Budecort/Budesonide, Montair-LC, antibiotics)",
+        "History of Asthma, COPD, Tuberculosis (TB), pneumonia, or smoking/bidi history",
+    ],
+
+    "emergency_keywords": [
+        "severe acute breathlessness unable to speak full sentences",
+        "blue lips or fingernails / cyanosis",
+        "coughing up significant blood / hemoptysis",
+        "severe asthma attack unyielding to inhaler",
+        "respiratory distress",
+    ],
+
+    "clarification_rules": [
+        "If cough is reported, ask whether dry or with phlegm and how many days it has persisted.",
+        "Check if patient experiences wheezing or breathlessness when walking or sleeping.",
+        "Clarify if patient uses regular inhalers (Asthalin, Budecort) or allergy tablets.",
+    ],
+}

ai-patient-onboarding/app/specialties/registry.py

@@ -1,18 +1,53 @@
 from app.specialties.cardiology import CARDIOLOGY_CONFIG
+from app.specialties.dermatology import DERMATOLOGY_CONFIG
 from app.specialties.diabetology import DIABETOLOGY_CONFIG
+from app.specialties.gastroenterology import GASTROENTEROLOGY_CONFIG
 from app.specialties.general import GENERAL_CONFIG
 from app.specialties.mental_health import MENTAL_HEALTH_CONFIG
+from app.specialties.neurology import NEUROLOGY_CONFIG
+from app.specialties.orthopedics import ORTHOPEDICS_CONFIG
+from app.specialties.pulmonology import PULMONOLOGY_CONFIG
 
 SPECIALTIES = {
     "cardiology": CARDIOLOGY_CONFIG,
+    "dermatology": DERMATOLOGY_CONFIG,
     "diabetology": DIABETOLOGY_CONFIG,
+    "gastroenterology": GASTROENTEROLOGY_CONFIG,
     "general": GENERAL_CONFIG,
     "mental_health": MENTAL_HEALTH_CONFIG,
+    "neurology": NEUROLOGY_CONFIG,
+    "orthopedics": ORTHOPEDICS_CONFIG,
+    "pulmonology": PULMONOLOGY_CONFIG,
+}
+
+CANONICAL_ALIASES = {
+    "general_medicine": "general",
+    "psychiatry": "mental_health",
 }
 
 
 def get_specialty_config(code: str) -> dict:
+    canonical_code = CANONICAL_ALIASES.get(code, code)
     return SPECIALTIES.get(
-        code,
+        canonical_code,
         GENERAL_CONFIG,
     )
+
+
+def validate_specialty_registry() -> dict:
+    """
+    Automated validation for specialty registry completeness and integrity.
+    """
+    canonical_codes = set(SPECIALTIES.keys())
+    missing_configs = []
+    for code, config in SPECIALTIES.items():
+        if not config or not isinstance(config, dict) or config.get("code") != code:
+            missing_configs.append(code)
+
+    return {
+        "valid": len(missing_configs) == 0,
+        "registered_count": len(SPECIALTIES),
+        "canonical_codes": list(canonical_codes),
+        "missing_configs": missing_configs,
+    }
+