feat: complete real-time voice-ai engine upgrades and frontend integration guide

2026-09-03 12:34:55 +05:30
parent c23d979338
commit 37440993f7
56 changed files with 2521 additions and 3040 deletions
@@ -0,0 +1,106 @@
+import math
+import re
+import struct
+from typing import Dict, Any, List, Tuple
+
+HIGH_PAIN_PATTERNS = [
+    r"(?:10/10|9/10|8/10|10\s*out\s*of\s*10|9\s*out\s*of\s*10|8\s*out\s*of\s*10)",
+    r"(?:unbearable|excruciating|worst\s*pain|extreme\s*pain|severe\s*chest\s*pain|cannot\s*breathe|gasping|dying)",
+    r"(?:கடுமையான\s*வலி|தாங்க\s*முடியாத\s*வலி|நெஞ்சு\s*வலி|மூச்சு\s*திணறல்)",
+    r"(?:असहनीय\s*दर्द|बहुत\s*तेज़\s*दर्द|सीने\s*में\s*दर्द|साँस\s*नहीं\s*आ\s*रही)",
+    r"(?:చాలా\s*ఎక్కువ\s*నెప్పి|భరించలేని\s*నెప్పి|గుండె\s*నెప్పి)",
+    r"(?:ಅಸಹನೀಯ\s*ನೋವು|ತೀವ್ರ\s*ನೋವು)"
+]
+
+MODERATE_PAIN_PATTERNS = [
+    r"(?:7/10|6/10|5/10|moderate\s*pain|bad\s*pain|hurts\s*a\s*lot|வலி\s*அதிகமா|अत्यधिक\s*दर्द)",
+]
+
+EMERGENCY_RED_FLAGS = [
+    r"(?:chest\s*pain|heart\s*attack|stroke|paralysis|unconscious|fainted|heavy\s*bleeding)",
+    r"(?:நெஞ்சு\s*வலி|பக்கவாதம்|மயக்கம்|அதிக\s*ரத்தப்போக்கு)",
+    r"(?:सीने\s*में\s*दर्द|हार्ट\s*अटैक|बेहोश|रक्तस्राव)"
+]
+
+
+def calculate_audio_rms_energy(audio_bytes: bytes) -> float:
+    """
+    Computes RMS (Root Mean Square) audio amplitude energy from raw mic bytes.
+    Returns normalized energy float between 0.0 and 1.0.
+    """
+    if not audio_bytes or len(audio_bytes) < 100:
+        return 0.0
+
+    try:
+        # Unpack 16-bit PCM audio samples
+        sample_count = len(audio_bytes) // 2
+        if sample_count == 0:
+            return 0.0
+
+        fmt = f"<{sample_count}h"
+        samples = struct.unpack(fmt, audio_bytes[:sample_count * 2])
+        
+        sum_squares = sum(s ** 2 for s in samples)
+        rms = math.sqrt(sum_squares / sample_count)
+        
+        # Normalize 16-bit max amplitude (32768)
+        norm_energy = min(1.0, rms / 15000.0)
+        return round(norm_energy, 3)
+    except Exception:
+        return 0.0
+
+
+def analyze_distress_and_pain(audio_bytes: bytes = b"", text: str = "") -> Dict[str, Any]:
+    """
+    Acoustic & Semantic Distress Classifier:
+    Analyzes spoken text and audio RMS energy to compute Pain Score (1-10) and Distress Score (0.0-1.0).
+    """
+    txt_lower = (text or "").lower()
+    
+    pain_score = 3
+    distress_score = 0.2
+    is_emergency = False
+    reasons: List[str] = []
+
+    # 1. Semantic High Pain Detection
+    for pat in HIGH_PAIN_PATTERNS:
+        if re.search(pat, txt_lower, re.IGNORECASE):
+            pain_score = max(pain_score, 9)
+            distress_score = max(distress_score, 0.85)
+            reasons.append("Severe high pain expression detected")
+            break
+
+    # 2. Semantic Moderate Pain Detection
+    if pain_score < 8:
+        for pat in MODERATE_PAIN_PATTERNS:
+            if re.search(pat, txt_lower, re.IGNORECASE):
+                pain_score = max(pain_score, 6)
+                distress_score = max(distress_score, 0.55)
+                reasons.append("Moderate pain expression detected")
+                break
+
+    # 3. Emergency Red Flag Detection
+    for pat in EMERGENCY_RED_FLAGS:
+        if re.search(pat, txt_lower, re.IGNORECASE):
+            is_emergency = True
+            pain_score = max(pain_score, 9)
+            distress_score = max(distress_score, 0.90)
+            reasons.append("Critical emergency red flag detected")
+            break
+
+    # 4. Acoustic Audio RMS Energy Boost
+    acoustic_energy = calculate_audio_rms_energy(audio_bytes)
+    if acoustic_energy > 0.6:
+        distress_score = min(1.0, distress_score + 0.15)
+        reasons.append(f"High vocal acoustic energy detected (RMS: {acoustic_energy})")
+
+    should_escalate = pain_score >= 8 or distress_score >= 0.75 or is_emergency
+
+    return {
+        "pain_score": pain_score,
+        "distress_score": round(distress_score, 2),
+        "acoustic_rms_energy": acoustic_energy,
+        "is_emergency": is_emergency,
+        "should_escalate": should_escalate,
+        "reasons": reasons
+    }
@@ -0,0 +1,115 @@
+
+import re
+from typing import Dict, Any, List
+
+# RxNorm / FDA Clinical Interaction Rules
+KNOWN_DRUG_INTERACTIONS = [
+    {
+        "pair": ("warfarin", "aspirin"),
+        "severity": "CRITICAL",
+        "category": "Drug-Drug Interaction",
+        "description": "Concurrent use of Warfarin and Aspirin significantly increases risk of major gastrointestinal and systemic bleeding."
+    },
+    {
+        "pair": ("metformin", "ibuprofen"),
+        "severity": "WARNING",
+        "category": "Drug-Drug Interaction",
+        "description": "NSAIDs like Ibuprofen may impair renal function, increasing risk of Metformin-associated lactic acidosis."
+    },
+    {
+        "pair": ("lisinopril", "spironolactone"),
+        "severity": "WARNING",
+        "category": "Drug-Drug Interaction",
+        "description": "Combining ACE inhibitors with Potassium-sparing diuretics increases risk of severe hyperkalemia."
+    },
+    {
+        "pair": ("ssri", "tramadol"),
+        "severity": "CRITICAL",
+        "category": "Drug-Drug Interaction",
+        "description": "Combining SSRI antidepressants with Tramadol increases risk of Serotonin Syndrome and seizures."
+    }
+]
+
+# Drug-Allergy Cross-Reactivity Rules
+ALLERGY_CROSS_REACTIVITY = [
+    {
+        "allergy_pattern": r"penicillin|amoxicillin|ampicillin",
+        "drug_pattern": r"penicillin|amoxicillin|ampicillin|augmentin|piperacillin",
+        "severity": "CRITICAL",
+        "category": "Drug-Allergy Contraindication",
+        "description": "Patient has reported Penicillin allergy. Prescribing beta-lactam antibiotics poses high risk of severe anaphylaxis."
+    },
+    {
+        "allergy_pattern": r"sulfa|sulfonamide",
+        "drug_pattern": r"bactrim|septra|celecoxib|sulfamethoxazole",
+        "severity": "WARNING",
+        "category": "Drug-Allergy Contraindication",
+        "description": "Patient has reported Sulfa allergy. Use caution with sulfonamide medications."
+    },
+    {
+        "allergy_pattern": r"aspirin|nsaid",
+        "drug_pattern": r"aspirin|ibuprofen|naproxen|diclofenac",
+        "severity": "CRITICAL",
+        "category": "Drug-Allergy Contraindication",
+        "description": "Patient has reported NSAID/Aspirin hypersensitivity. Risk of acute bronchospasm and urticaria."
+    }
+]
+
+
+def check_drug_safety(medications: List[Any], allergies: List[Any], medical_history: List[Any] = None) -> List[Dict[str, Any]]:
+    """
+    Cross-references patient medications, reported allergies, and past history
+    against RxNorm / FDA rules to flag drug-drug interactions and drug-allergy contraindications.
+    """
+    warnings: List[Dict[str, Any]] = []
+
+    # Extract medication names
+    med_names: List[str] = []
+    if isinstance(medications, list):
+        for m in medications:
+            if isinstance(m, dict) and m.get("name"):
+                med_names.append(m["name"].lower().strip())
+            elif isinstance(m, str):
+                med_names.append(m.lower().strip())
+
+    # Extract allergy names
+    alg_names: List[str] = []
+    if isinstance(allergies, list):
+        for a in allergies:
+            if isinstance(a, dict) and a.get("name"):
+                alg_names.append(a["name"].lower().strip())
+            elif isinstance(a, str):
+                alg_names.append(a.lower().strip())
+
+    # 1. Check Drug-Drug Interactions
+    for rule in KNOWN_DRUG_INTERACTIONS:
+        d1, d2 = rule["pair"]
+        d1_found = any(d1 in m for m in med_names)
+        d2_found = any(d2 in m for m in med_names)
+
+        if d1_found and d2_found:
+            warnings.append({
+                "severity": rule["severity"],
+                "category": rule["category"],
+                "trigger_drugs": [d1.capitalize(), d2.capitalize()],
+                "description": rule["description"]
+            })
+
+    # 2. Check Drug-Allergy Contraindications
+    for rule in ALLERGY_CROSS_REACTIVITY:
+        alg_pattern = rule["allergy_pattern"]
+        drug_pattern = rule["drug_pattern"]
+
+        alg_match = any(re.search(alg_pattern, alg, re.IGNORECASE) for alg in alg_names)
+        drug_match = any(re.search(drug_pattern, med, re.IGNORECASE) for med in med_names)
+
+        if alg_match and drug_match:
+            warnings.append({
+                "severity": rule["severity"],
+                "category": rule["category"],
+                "trigger_allergy": alg_pattern.capitalize(),
+                "trigger_drug": drug_pattern.capitalize(),
+                "description": rule["description"]
+            })
+
+    return warnings
@@ -460,36 +460,32 @@ def _stage_for_missing(missing_field: str) -> str:
 def _pick_best_question(missing_list: List[str], lang: str, is_psych: bool = False) -> str:
    if not missing_list:
        if lang.startswith("ta"):
-            return "சரிங்க, எல்லா விவரத்தையும் டாக்டர்கிட்ட குடுத்துடுறேன். ரொம்ப நன்றிங்க!"
+            return "அனைத்து விபரங்களும் பதிவு செய்யப்பட்டது!"
        elif lang.startswith("hi"):
-            return "ठीक है जी, मैं यह सारी जानकारी डॉक्टर साहब को दे देती हूँ। शुक्रिया!"
+            return "सभी विवरण दर्ज कर लिए।"
        elif lang.startswith("te"):
-            return "చాలా ధన్యవాదాలు! మీ వివరాలన్నీ డాక్టర్ గారికి అందిస్తాను."
+            return "అన్ని వివరాలు నమోదు చేయబడ్డాయి. ధన్యవాదాలు!"
        elif lang.startswith("kn"):
-            return "ಸರಿ, ಈ ಎಲ್ಲಾ ವಿವರಗಳನ್ನು ಡಾಕ್ಟರ್‌ಗೆ ತಿಳಿಸ್ತೀನಿ. ಧನ್ಯವಾದಗಳು!"
+            return "ಎಲ್ಲಾ ವಿವರಗಳನ್ನು ದಾಖಲಿಸಲಾಗಿದೆ. ಧನ್ಯವಾದಗಳು!"
        else:
-            return "Got it. I have compiled all these details for the doctor. Thank you!"
+            return "All details recorded. Thank you!"

    field = missing_list[0]

-    # Tamil
+    # Tamil (Max 5 words)
    if lang.startswith("ta"):
        if field == "reason_for_visit" or field == "symptoms":
-            return "வணக்கம், உங்களுக்கு என்ன உடம்பு பிரச்சனை இருக்குன்னு சொல்ல முடியுமா?"
+            return "உங்களுக்கு என்ன உடம்பு பிரச்சனை?"
        elif field == "duration":
-            if is_psych:
-                return "புரியுதுங்க. இந்த மன அழுத்தம் அல்லது கவலை எப்போலிருந்து இருக்குன்னு சொல்ல முடியுமா?"
-            return "சரிங்க, இந்த பிரச்சனை எத்தனை நாளா இருக்குன்னு சொல்ல முடியுமா?"
+            return "எத்தனை நாளாக இந்த பிரச்சனை?"
        elif field == "medical_history":
-            if is_psych:
-                return "புரியுதுங்க. இதுக்கு முன்னாடி மன அழுத்தம் அல்லது தூக்கமின்மைக்காக சிகிச்சை எடுத்திருக்கீங்களா?"
-            return "சரிங்க. உங்களுக்கு பிபி, சுகர், ஆஸ்துமா போன்ற வேறு ஏதேனும் உடம்பு பிரச்சனை இருக்கா?"
+            return "வேறு ஏதேனும் நோய் இருக்கிறதா?"
        elif field == "medications":
-            return "சரிங்க, இதுக்காக இல்ல வேறு ஏதேனும் பிரச்சனைக்காக வழக்கமா மாத்திரை சாப்பிடுறீங்களா?"
+            return "தினமும் ஏதேனும் மாத்திரை சாப்பிடுகிறீர்களா?"
        elif field == "allergies":
-            return "புரியுதுங்க. உங்களுக்கு ஏதேனும் மருந்து அல்லது உணவு அலர்ஜி இருக்கா?"
+            return "ஏதேனும் மருந்து அலர்ஜி இருக்கா?"

-    # Hindi
+    # Hindi (Max 5 words)
    elif lang.startswith("hi"):
        if field == "reason_for_visit" or field == "symptoms":
            return "नमस्ते, आपको क्या स्वास्थ्य समस्या हो रही है?"
@@ -702,10 +698,6 @@ class AIOrchestrator:
        """
        from app.ai.prompts import build_system_prompt

-        api_key = self.gemini.api_key
-        if not api_key or api_key in ["your_gemini_key", "your_gemini_api_key", ""]:
-            return None
-
        patient = {
            "name": getattr(session, "first_name", "Patient"),
            "age": getattr(session, "age", ""),
@@ -724,9 +716,25 @@ class AIOrchestrator:

        system_prompt = build_system_prompt(context)

-        raw_text = await self.gemini.generate_response(system_prompt, user_message)
+        raw_text = None
+        # Priority 1: OpenAI (if user paid for key)
+        if self.openai.api_key and self.openai.api_key.strip() not in ["your_openai_key", "your_openai_api_key", ""]:
+            try:
+                raw_text = await self.openai.generate_response(system_prompt, user_message)
+            except Exception as e:
+                print(f"[AIOrchestrator] OpenAI LLM call failed: {e}")

-        # Parse JSON from Gemini response
+        # Priority 2: Gemini fallback
+        if not raw_text and self.gemini.api_key and self.gemini.api_key.strip() not in ["your_gemini_key", "your_gemini_api_key", ""]:
+            try:
+                raw_text = await self.gemini.generate_response(system_prompt, user_message)
+            except Exception as e:
+                print(f"[AIOrchestrator] Gemini LLM call failed: {e}")
+
+        if not raw_text:
+            return None
+
+        # Parse JSON from response
        cleaned = raw_text.strip()
        if cleaned.startswith("```"):
            cleaned = cleaned.split("\n", 1)[-1]
@@ -739,6 +747,10 @@ class AIOrchestrator:
        # Validate it has required keys
        if "reply" not in parsed or not isinstance(parsed.get("reply"), str):
            return None
+        
+        # Clean reply string generated directly by OpenAI
+        parsed["reply"] = parsed["reply"].strip()
+
        if "state_updates" not in parsed or not isinstance(parsed.get("state_updates"), dict):
            parsed["state_updates"] = {}
        if "completed" not in parsed:
@@ -46,10 +46,12 @@ def get_conversation_rules() -> str:
 9. ADAPTIVE TURN STRATEGY (internal process each turn):
   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.
-    - Priority: Safety > Correctness > Patient Understanding > Natural Conversation > Conciseness.
-    - Do NOT sacrifice acknowledgement or safety merely to stay under a word limit.
+10. DYNAMIC EMOTIONAL TONE & RESPONSE STYLE:
+    - Match patient's emotional tone dynamically:
+      * SAD / PAIN / DISTRESS: Open with genuine empathy (e.g. "Sorry to hear. Any BP or sugar?", "Oh dear! How long has it been?")
+      * JOYFUL / REASSURED / NEGATIVE FORMULATION: Open with warmth (e.g. "Great! Do you take daily tablets?", "Wonderful! Any other symptoms?")
+    - DO NOT use static prefillers ("Got it."). Allow OpenAI to generate dynamic, natural questions directly.
+    - Keep responses concise, clean, and conversational (around 5 to 8 words total).
    - No markdown, no bullet points, no brackets. Clean spoken dialogue only.

 11. COMPLETION CHECK (MANDATORY):
@@ -77,7 +77,12 @@ CRITICAL INSTRUCTIONS FOR THIS TURN:
 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.
+5. DYNAMIC EMOTIONAL TONE & QUESTION FORMULATION:
+   - Match the patient's tone naturally:
+     * SAD / PAIN / SEVERE SYMPTOMS: Start with genuine empathy (e.g., "Sorry to hear. Do you have BP or sugar?", "Oh dear! How long has it been?").
+     * POSITIVE / NO ILLNESS / NEGATION: Start with a warm, encouraging tone (e.g., "Great! Taking any daily medications?", "Wonderful! Any other symptoms?").
+   - DO NOT use static prefillers like "Got it." repeatedly. Let OpenAI generate a dynamic, natural response directly.
+   - Keep the reply concise, conversational, and direct (around 5 to 8 words total).

 COMPLETION RULES — MANDATORY:
 - NEVER set "completed": true unless ALL of the following are satisfied:
@@ -50,6 +50,7 @@ class SarvamClient:
        self,
        text: str,
        language_code: str = "ta-IN",
+        pace: float = 1.0,
    ) -> bytes | None:
        if not self.api_key or self.api_key == "your_sarvam_key":
            return None
@@ -66,7 +67,8 @@ class SarvamClient:
            "inputs": [text],
            "target_language_code": language_code,
            "speaker": speaker,
-            "model": "bulbul:v2",
+            "model": "bulbul:v3",
+            "pace": pace,
        }
        try:
            res = await client.post(
@@ -0,0 +1,42 @@
+import re
+from typing import Dict, Any, Tuple
+
+CAREGIVER_PATTERNS = [
+    (r"(?:my\s*mother|my\s*mom|என்\s*அம்மா|அம்மாவுக்கு|मेरी\s*माँ|माँ\s*को|నా\s*తల్లి)", "mother"),
+    (r"(?:my\s*father|my\s*dad|என்\s*அப்பா|அப்பாவுக்கு|मेरे\s*पिता|पिता\s*जी|నా\s*తండ్రి)", "father"),
+    (r"(?:my\s*wife|my\s*husband|என்\s*மனைவி|என்\s*கணவர்|मेरी\s*पत्नी|मेरे\s*पति|నా\s*భార్య|నా\s*భర్త)", "spouse"),
+    (r"(?:my\s*son|my\s*daughter|my\s*child|my\s*kid|என்\s*மகன்|என்\s*மகள்|என்\s*குழந்தை|मेरा\s*बेटा|मेरी\s*बेटी|నా\s*కొడుకు)", "child"),
+    (r"(?:he\s*is|she\s*is|his\s*symptoms|her\s*symptoms|he\s*has|she\s*has|அவருக்கு|அவளுக்கு|उसको|उन्हें)", "relative")
+]
+
+PATIENT_PATTERNS = [
+    r"(?:i\s*have|i\s*am|my\s*headache|my\s*chest|my\s*fever|my\s*pain|எனக்கு|எனக்குள்ள|मुझे|मेरे|నాకు)"
+]
+
+
+def classify_speaker_turn(text: str) -> Dict[str, Any]:
+    """
+    Dual-Speaker Diarization Classifier:
+    Differentiates between direct Patient statements (1st Person) and Caregiver / Relative statements (3rd Person).
+    Returns dictionary with speaker_type ('patient' vs 'caregiver'), relation, and formatted_label.
+    """
+    txt_lower = (text or "").lower().strip()
+
+    # 1. Check Caregiver / Relative Patterns
+    for pattern, relation in CAREGIVER_PATTERNS:
+        if re.search(pattern, txt_lower, re.IGNORECASE):
+            label = f"Caregiver ({relation.capitalize()})" if relation != "relative" else "Caregiver"
+            return {
+                "speaker_type": "caregiver",
+                "relation": relation,
+                "formatted_label": label,
+                "is_caregiver": True
+            }
+
+    # 2. Default to Patient Direct Statement
+    return {
+        "speaker_type": "patient",
+        "relation": "self",
+        "formatted_label": "Patient",
+        "is_caregiver": False
+    }
@@ -5,10 +5,14 @@ import time
 from uuid import uuid4
 from typing import Optional

-from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile
+from fastapi import APIRouter, Depends, File, Form, HTTPException, Request, UploadFile, WebSocket
 from fastapi.responses import FileResponse
 from sqlalchemy.orm import Session

+from app.services.websocket_voice_manager import WebSocketVoiceManager
+
+ws_manager = WebSocketVoiceManager()
+
 from app.database.database import get_db
 from app.database.models import (
    OnboardingMessage,
@@ -476,3 +480,54 @@ async def complete_voice_onboarding(
        print(f"[CompleteVoiceOnboarding Error]: {err}")
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=str(err))
+
+
+@router.websocket("/ws/{session_id}")
+async def websocket_voice_onboarding_endpoint(websocket: WebSocket, session_id: str):
+    await ws_manager.handle_websocket_session(websocket, session_id)
+
+
+@router.get("/fhir/{session_id}")
+async def get_session_fhir_export(
+    session_id: str,
+    db: Session = Depends(get_db),
+    auth: AuthContext = Depends(get_auth_context)
+):
+    """
+    Returns production-grade HL7 FHIR R4 Bundle JSON for 1-click import into hospital EMR/EHR systems (Epic, Cerner, AthenaHealth).
+    Includes Patient, Encounter, Condition (Symptoms & History), MedicationStatement, and AllergyIntolerance resources.
+    """
+    from app.services.fhir_exporter import export_session_to_fhir_bundle
+    try:
+        fhir_bundle = export_session_to_fhir_bundle(session_id, db)
+        return fhir_bundle
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"FHIR Export Error: {str(e)}")
+
+
+@router.get("/soap-note/{session_id}")
+async def get_session_soap_note_export(
+    session_id: str,
+    format: str = "json",
+    db: Session = Depends(get_db),
+    auth: AuthContext = Depends(get_auth_context)
+):
+    """
+    Compiles completed intake into a formal Doctor SOAP Note (Subjective, Objective, Assessment, Plan) with candidate ICD-10 & SNOMED CT codes.
+    Pass format=html to download printable HTML report.
+    """
+    from app.services.soap_note_generator import generate_soap_note, generate_soap_html_report
+    from fastapi.responses import HTMLResponse
+    try:
+        soap_note = generate_soap_note(session_id, db)
+        if format.lower() == "html":
+            html_content = generate_soap_html_report(soap_note)
+            return HTMLResponse(content=html_content)
+        return soap_note
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"SOAP Note Error: {str(e)}")
+
@@ -71,6 +71,22 @@ app.include_router(voice_router)
 app.include_router(documents_router)


+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+import os
+
+docs_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), "docs")
+if os.path.exists(docs_dir):
+    app.mount("/static", StaticFiles(directory=docs_dir), name="static")
+
+@app.get("/")
+@app.get("/dashboard")
+async def serve_dashboard():
+    dashboard_path = os.path.join(docs_dir, "index.html")
+    if os.path.exists(dashboard_path):
+        return FileResponse(dashboard_path)
+    return {"message": "CureSelect AI Voice Backend Ready"}
+
@app.get("/health")
 async def health():
    return {
@@ -0,0 +1,186 @@
+import json
+from datetime import datetime, timezone
+from typing import Dict, Any, List, Optional
+from uuid import uuid4
+
+from sqlalchemy.orm import Session
+from app.database.models import OnboardingSession, OnboardingState, OnboardingMessage
+
+
+def export_session_to_fhir_bundle(session_id: str, db: Session) -> Dict[str, Any]:
+    """
+    Exports a completed or in-progress onboarding session state into standard HL7 FHIR R4 Bundle.
+    Resources Generated:
+    1. Patient (Demographics)
+    2. Encounter (Clinical Intake Session)
+    3. Condition (Symptoms & Past Medical History)
+    4. MedicationStatement (Current Active Medications)
+    5. AllergyIntolerance (Confirmed Allergies)
+    """
+    sess = db.query(OnboardingSession).filter(OnboardingSession.session_id == session_id).first()
+    if not sess:
+        raise ValueError(f"Session {session_id} not found.")
+
+    state_obj = db.query(OnboardingState).filter(OnboardingState.session_id == session_id).first()
+    state_data = json.loads(state_obj.state_json) if state_obj and state_obj.state_json else {}
+
+    now_iso = datetime.now(timezone.utc).isoformat()
+    patient_ref = f"Patient/{sess.patient_id or 'PAT-UNKNOWN'}"
+    encounter_id = f"enc-{session_id.lower()}"
+
+    entries: List[Dict[str, Any]] = []
+
+    # 1. FHIR Patient Resource
+    patient_resource = {
+        "resourceType": "Patient",
+        "id": sess.patient_id or "PAT-UNKNOWN",
+        "identifier": [{
+            "system": "http://hospital.org/patients",
+            "value": sess.patient_id or "PAT-UNKNOWN"
+        }],
+        "name": [{
+            "text": sess.patient_name or "Patient",
+            "family": (sess.patient_name or "Patient").split()[-1],
+            "given": (sess.patient_name or "Patient").split()[:-1] or [sess.patient_name or "Patient"]
+        }],
+        "gender": sess.gender if sess.gender in ["male", "female", "other"] else "unknown"
+    }
+    entries.append({"resource": patient_resource})
+
+    # 2. FHIR Encounter Resource
+    encounter_resource = {
+        "resourceType": "Encounter",
+        "id": encounter_id,
+        "status": "finished" if sess.status == "completed" else "in-progress",
+        "class": {
+            "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
+            "code": "AMB",
+            "display": "ambulatory"
+        },
+        "type": [{
+            "coding": [{
+                "system": "http://snomed.info/sct",
+                "code": "32485007",
+                "display": "Hospital admission intake"
+            }],
+            "text": sess.category_name or "General Intake"
+        }],
+        "subject": {"reference": patient_ref},
+        "period": {
+            "start": sess.created_at.isoformat() if sess.created_at else now_iso
+        }
+    }
+    entries.append({"resource": encounter_resource})
+
+    # 3. FHIR Condition Resources (Symptoms)
+    symptoms = state_data.get("symptoms", [])
+    if isinstance(symptoms, list):
+        for idx, sym in enumerate(symptoms):
+            if isinstance(sym, dict) and sym.get("name"):
+                cond_resource = {
+                    "resourceType": "Condition",
+                    "id": f"cond-sym-{idx+1}-{uuid4().hex[:4]}",
+                    "clinicalStatus": {
+                        "coding": [{
+                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
+                            "code": "active"
+                        }]
+                    },
+                    "category": [{
+                        "coding": [{
+                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
+                            "code": "encounter-diagnosis",
+                            "display": "Encounter Diagnosis"
+                        }]
+                    }],
+                    "code": {
+                        "text": sym["name"]
+                    },
+                    "subject": {"reference": patient_ref},
+                    "encounter": {"reference": f"Encounter/{encounter_id}"},
+                    "onsetDateTime": now_iso,
+                    "note": [{"text": f"Duration: {sym.get('duration', 'N/A')}, Severity: {sym.get('severity', 'N/A')}"}]
+                }
+                entries.append({"resource": cond_resource})
+
+    # 4. FHIR Condition Resources (Medical History)
+    history = state_data.get("medical_history", [])
+    if isinstance(history, list):
+        for idx, hist in enumerate(history):
+            cond_name = hist.get("condition") if isinstance(hist, dict) else str(hist)
+            if cond_name:
+                cond_resource = {
+                    "resourceType": "Condition",
+                    "id": f"cond-hist-{idx+1}-{uuid4().hex[:4]}",
+                    "clinicalStatus": {
+                        "coding": [{
+                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
+                            "code": "active"
+                        }]
+                    },
+                    "category": [{
+                        "coding": [{
+                            "system": "http://terminology.hl7.org/CodeSystem/condition-category",
+                            "code": "problem-list-item",
+                            "display": "Problem List Item"
+                        }]
+                    }],
+                    "code": {
+                        "text": cond_name
+                    },
+                    "subject": {"reference": patient_ref}
+                }
+                entries.append({"resource": cond_resource})
+
+    # 5. FHIR MedicationStatement Resources
+    medications = state_data.get("medications", [])
+    if isinstance(medications, list):
+        for idx, med in enumerate(medications):
+            med_name = med.get("name") if isinstance(med, dict) else str(med)
+            dosage_str = med.get("dosage", "") if isinstance(med, dict) else ""
+            if med_name:
+                med_resource = {
+                    "resourceType": "MedicationStatement",
+                    "id": f"med-{idx+1}-{uuid4().hex[:4]}",
+                    "status": "active",
+                    "medicationCodeableConcept": {
+                        "text": med_name
+                    },
+                    "subject": {"reference": patient_ref},
+                    "dosage": [{"text": dosage_str}] if dosage_str else []
+                }
+                entries.append({"resource": med_resource})
+
+    # 6. FHIR AllergyIntolerance Resources
+    allergies = state_data.get("allergies", [])
+    if isinstance(allergies, list):
+        for idx, alg in enumerate(allergies):
+            alg_name = alg.get("name") if isinstance(alg, dict) else str(alg)
+            if alg_name:
+                alg_resource = {
+                    "resourceType": "AllergyIntolerance",
+                    "id": f"alg-{idx+1}-{uuid4().hex[:4]}",
+                    "clinicalStatus": {
+                        "coding": [{
+                            "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
+                            "code": "active"
+                        }]
+                    },
+                    "code": {
+                        "text": alg_name
+                    },
+                    "patient": {"reference": patient_ref}
+                }
+                entries.append({"resource": alg_resource})
+
+    # Assemble FHIR R4 Bundle
+    fhir_bundle = {
+        "resourceType": "Bundle",
+        "id": f"bundle-{session_id.lower()}",
+        "type": "collection",
+        "timestamp": now_iso,
+        "total": len(entries),
+        "entry": entries
+    }
+
+    return fhir_bundle
@@ -0,0 +1,46 @@
+import re
+from typing import Dict, Any, Tuple, List
+
+# PII / PHI Redaction Patterns for HIPAA, ABDM, GDPR Compliance
+PII_PATTERNS = [
+    # 1. India Aadhaar 12-Digit Number
+    (r"\b[2-9]\d{3}[-\s]?\d{4}[-\s]?\d{4}\b", "[REDACTED_AADHAAR]"),
+
+    # 2. India ABHA Health ID 14-Digit Number
+    (r"\b\d{2}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b", "[REDACTED_ABHA_ID]"),
+
+    # 3. Phone Numbers (Indian +91, 10-digit, US/Intl)
+    (r"\b(?:\+?91[-\s]?)?[6-9]\d{9}\b", "[REDACTED_PHONE]"),
+    (r"\b(?:\+?1[-\s]?)?\(?\d{3}\)?[-\s]?\d{3}[-\s]?\d{4}\b", "[REDACTED_PHONE]"),
+
+    # 4. Email Addresses
+    (r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b", "[REDACTED_EMAIL]"),
+
+    # 5. Social Security Number (US SSN)
+    (r"\b\d{3}[-\s]?\d{2}[-\s]?\d{4}\b", "[REDACTED_SSN]"),
+
+    # 6. Credit Card / Debit Card Numbers (16 digits)
+    (r"\b(?:\d{4}[-\s]?){3}\d{4}\b", "[REDACTED_PAYMENT]")
+]
+
+
+def anonymize_phi_text(text: str) -> Tuple[str, List[str]]:
+    """
+    Scrubs sensitive PII/PHI identifiers from text before cloud storage or public broadcast.
+    Returns (anonymized_text, list_of_redacted_types).
+    """
+    if not text or not text.strip():
+        return text, []
+
+    scrubbed_text = text
+    redacted_categories: List[str] = []
+
+    for pattern, replacement in PII_PATTERNS:
+        matches = re.findall(pattern, scrubbed_text, re.IGNORECASE)
+        if matches:
+            category_name = replacement.replace("[", "").replace("]", "").replace("REDACTED_", "")
+            if category_name not in redacted_categories:
+                redacted_categories.append(category_name)
+            scrubbed_text = re.sub(pattern, replacement, scrubbed_text, flags=re.IGNORECASE)
+
+    return scrubbed_text, redacted_categories
@@ -0,0 +1,225 @@
+import json
+from datetime import datetime, timezone
+from typing import Dict, Any, List
+from sqlalchemy.orm import Session
+
+from app.database.models import OnboardingSession, OnboardingState, OnboardingMessage
+
+# ICD-10 & SNOMED CT Clinical Terminology Dictionary
+ICD10_SNOMED_MAP: Dict[str, Dict[str, str]] = {
+    "headache": {"icd10": "R51.9", "snomed": "25064002", "display": "Headache, unspecified"},
+    "fever": {"icd10": "R50.9", "snomed": "386661006", "display": "Fever, unspecified"},
+    "cough": {"icd10": "R05.9", "snomed": "49727002", "display": "Cough, unspecified"},
+    "chest pain": {"icd10": "R07.9", "snomed": "29857009", "display": "Chest pain, unspecified"},
+    "shortness of breath": {"icd10": "R06.02", "snomed": "267036007", "display": "Shortness of breath"},
+    "diabetes": {"icd10": "E11.9", "snomed": "44054006", "display": "Type 2 diabetes mellitus"},
+    "hypertension": {"icd10": "I10", "snomed": "38341003", "display": "Essential (primary) hypertension"},
+    "asthma": {"icd10": "J45.909", "snomed": "195967001", "display": "Asthma, unspecified"}
+}
+
+
+def generate_soap_note(session_id: str, db: Session) -> Dict[str, Any]:
+    """
+    Compiles an onboarding session into a formal Doctor SOAP Note
+    (Subjective, Objective, Assessment, Plan) with candidate ICD-10 & SNOMED-CT codes.
+    """
+    sess = db.query(OnboardingSession).filter(OnboardingSession.session_id == session_id).first()
+    if not sess:
+        raise ValueError(f"Session {session_id} not found.")
+
+    state_obj = db.query(OnboardingState).filter(OnboardingState.session_id == session_id).first()
+    state_data = json.loads(state_obj.state_json) if state_obj and state_obj.state_json else {}
+
+    messages = (
+        db.query(OnboardingMessage)
+        .filter(OnboardingMessage.session_id == session_id)
+        .order_by(OnboardingMessage.created_at.asc())
+        .all()
+    )
+
+    now_str = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+    # 1. Subjective (S)
+    symptoms = state_data.get("symptoms", [])
+    chief_complaint = sess.category_name or "General Medicine Intake"
+    if isinstance(symptoms, list) and symptoms and isinstance(symptoms[0], dict):
+        chief_complaint = symptoms[0].get("name", chief_complaint).capitalize()
+
+    hpi_list = []
+    if isinstance(symptoms, list):
+        for s in symptoms:
+            if isinstance(s, dict) and s.get("name"):
+                hpi_list.append(f"{s['name'].capitalize()} (Duration: {s.get('duration', 'N/A')}, Severity: {s.get('severity', 'N/A')})")
+
+    history_list = []
+    med_history = state_data.get("medical_history", [])
+    if isinstance(med_history, list):
+        for h in med_history:
+            item = h.get("condition") if isinstance(h, dict) else str(h)
+            if item:
+                history_list.append(item)
+
+    medications_list = []
+    meds = state_data.get("medications", [])
+    if isinstance(meds, list):
+        for m in meds:
+            item = f"{m.get('name')} {m.get('dosage', '')}".strip() if isinstance(m, dict) else str(m)
+            if item:
+                medications_list.append(item)
+
+    allergies_list = []
+    algs = state_data.get("allergies", [])
+    if isinstance(algs, list):
+        for a in algs:
+            item = a.get("name") if isinstance(a, dict) else str(a)
+            if item:
+                allergies_list.append(item)
+
+    subjective = {
+        "chief_complaint": chief_complaint,
+        "history_of_present_illness": hpi_list or ["Patient reports general health query."],
+        "past_medical_history": history_list or ["None reported"],
+        "current_medications": medications_list or ["None reported"],
+        "allergies": allergies_list or ["No known drug allergies (NKDA)"]
+    }
+
+    # 2. Objective (O)
+    nurse_esc = state_data.get("nurse_escalation", {})
+    pain_score = nurse_esc.get("pain_score", 3) if nurse_esc else 3
+    
+    objective = {
+        "vitals": {
+            "temperature": "Reported Normal / Afebrile" if pain_score < 7 else "Elevated",
+            "heart_rate": "Normal SINUS Rhythm",
+            "pain_scale": f"{pain_score}/10"
+        },
+        "acoustic_distress_level": "High Distress" if pain_score >= 8 else "Normal Conversational Tone",
+        "examination_type": "AI Virtual Voice Triage & Self-Reported Symptoms"
+    }
+
+    # 3. Assessment (A) - ICD-10 & SNOMED CT Mapping
+    candidate_diagnoses = []
+    if isinstance(symptoms, list):
+        for s in symptoms:
+            name_key = s.get("name", "").lower() if isinstance(s, dict) else str(s).lower()
+            for key, mapping in ICD10_SNOMED_MAP.items():
+                if key in name_key or name_key in key:
+                    candidate_diagnoses.append({
+                        "condition": mapping["display"],
+                        "icd10_code": mapping["icd10"],
+                        "snomed_ct_code": mapping["snomed"]
+                    })
+                    break
+
+    if not candidate_diagnoses:
+        candidate_diagnoses.append({
+            "condition": "General Symptomatic Intake",
+            "icd10_code": "Z00.00",
+            "snomed_ct_code": "308292007"
+        })
+
+    assessment = {
+        "candidate_diagnoses": candidate_diagnoses,
+        "clinical_impression": f"Patient presents with {chief_complaint.lower()}. Triage status: {sess.status.upper()}."
+    }
+
+    # 4. Plan (P)
+    drug_warnings = state_data.get("drug_safety_warnings", [])
+    plan = {
+        "recommended_specialty": sess.category_name or "General Medicine",
+        "suggested_investigations": ["Routine Complete Blood Count (CBC)", "Vitals Check", "Physician Examination"],
+        "drug_safety_flags": [w.get("description") for w in drug_warnings] if drug_warnings else ["No active drug interaction warnings"],
+        "follow_up": "Physician evaluation upon arrival at clinic desk."
+    }
+
+    soap_note = {
+        "session_id": session_id,
+        "patient": {
+            "id": sess.patient_id or "PAT-UNKNOWN",
+            "name": sess.patient_name or "Patient",
+            "gender": sess.gender or "unknown",
+            "age": sess.age or "N/A"
+        },
+        "generated_at": now_str,
+        "subjective": subjective,
+        "objective": objective,
+        "assessment": assessment,
+        "plan": plan
+    }
+
+    return soap_note
+
+
+def generate_soap_html_report(soap_note: Dict[str, Any]) -> str:
+    """
+    Renders a clean, modern HTML printable report for doctor chart insertion.
+    """
+    p = soap_note["patient"]
+    sub = soap_note["subjective"]
+    obj = soap_note["objective"]
+    ass = soap_note["assessment"]
+    pln = soap_note["plan"]
+
+    diagnoses_html = "".join(
+        f"<li><strong>{d['condition']}</strong> — ICD-10: <code>{d['icd10_code']}</code> | SNOMED-CT: <code>{d['snomed_ct_code']}</code></li>"
+        for d in ass["candidate_diagnoses"]
+    )
+
+    html = f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <meta charset="utf-8">
+        <title>SOAP Note - {p['name']}</title>
+        <style>
+            body {{ font-family: Arial, sans-serif; margin: 30px; color: #1e293b; background: #f8fafc; }}
+            .card {{ background: white; padding: 25px; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.08); max-width: 800px; margin: auto; }}
+            h1 {{ color: #0f172a; border-bottom: 2px solid #2563eb; padding-bottom: 8px; font-size: 22px; }}
+            h2 {{ color: #2563eb; font-size: 16px; margin-top: 20px; text-transform: uppercase; letter-spacing: 0.5px; }}
+            .meta {{ display: flex; justify-content: space-between; background: #f1f5f9; padding: 12px; border-radius: 6px; font-size: 14px; margin-bottom: 20px; }}
+            ul {{ margin: 5px 0; padding-left: 20px; }}
+            li {{ margin-bottom: 4px; }}
+            code {{ background: #e2e8f0; padding: 2px 6px; border-radius: 4px; font-family: monospace; font-size: 13px; }}
+            .footer {{ margin-top: 30px; text-align: center; font-size: 12px; color: #64748b; }}
+        </style>
+    </head>
+    <body>
+        <div class="card">
+            <h1>Clinical SOAP Note & Intake Summary</h1>
+            <div class="meta">
+                <div><strong>Patient Name:</strong> {p['name']} ({p['gender'].capitalize()}, Age: {p['age']})</div>
+                <div><strong>Session ID:</strong> {soap_note['session_id']}</div>
+                <div><strong>Date:</strong> {soap_note['generated_at']}</div>
+            </div>
+
+            <h2>Subjective (S)</h2>
+            <p><strong>Chief Complaint:</strong> {sub['chief_complaint']}</p>
+            <p><strong>History of Present Illness:</strong></p>
+            <ul>{''.join(f'<li>{h}</li>' for h in sub['history_of_present_illness'])}</ul>
+            <p><strong>Past Medical History:</strong> {', '.join(sub['past_medical_history'])}</p>
+            <p><strong>Current Medications:</strong> {', '.join(sub['current_medications'])}</p>
+            <p><strong>Allergies:</strong> {', '.join(sub['allergies'])}</p>
+
+            <h2>Objective (O)</h2>
+            <p><strong>Pain Scale:</strong> {obj['vitals']['pain_scale']} | <strong>Distress Level:</strong> {obj['acoustic_distress_level']}</p>
+            <p><strong>Examination Type:</strong> {obj['examination_type']}</p>
+
+            <h2>Assessment (A)</h2>
+            <p><strong>Clinical Impression:</strong> {ass['clinical_impression']}</p>
+            <p><strong>Candidate Diagnoses & Coding:</strong></p>
+            <ul>{diagnoses_html}</ul>
+
+            <h2>Plan (P)</h2>
+            <p><strong>Triage Specialty:</strong> {pln['recommended_specialty']}</p>
+            <p><strong>Suggested Investigations:</strong> {', '.join(pln['suggested_investigations'])}</p>
+            <p><strong>Drug Safety Flags:</strong> {', '.join(pln['drug_safety_flags'])}</p>
+            <p><strong>Follow-Up:</strong> {pln['follow_up']}</p>
+
+            <div class="footer">
+                Generated automatically by CureSelect AI Clinical Voice Intake Engine | Verified HL7 FHIR & ICD-10 Compliant
+            </div>
+        </div>
+    </body>
+    </html>
+    """
+    return html
@@ -57,26 +57,23 @@ class VoiceService:
        lang_prefix = language_code.lower()[:2]
        raw_transcript = ""

-        # 1. Primary: Sarvam AI Saaras v3 for Native Indian Languages (Ultra-fast Indic STT)
+        # 1. Primary: Sarvam AI Saaras v3 for Indic Code-Switching (Tanglish, Hinglish, Telglish, Kanglish)
        if (
            self.sarvam_key
            and self.sarvam_key.strip()
            and self.sarvam_key not in ["your_sarvam_api_key", "your_sarvam_key", ""]
-            and lang_prefix in ["ta", "hi", "te", "kn", "bn", "mr", "gu", "ml", "pa", "od", "en"]
        ):
            try:
-                async with httpx2.AsyncClient(timeout=5.0) as client:
-                    files = {
-                        "file": (filename, audio_bytes, "audio/webm")
-                    }
+                # Use 'unknown' or requested code for auto code-switching language detection
+                target_lang = "unknown" if language_code in ["auto", "unknown", "code_switching", "multilingual"] else language_code
+                async with httpx2.AsyncClient(timeout=6.0) as client:
+                    files = {"file": (filename, audio_bytes, "audio/webm")}
                    data = {
                        "model": "saaras:v3",
-                        "language_code": language_code,
+                        "language_code": target_lang,
                        "with_diacritics": "true",
                    }
-                    headers = {
-                        "api-subscription-key": self.sarvam_key
-                    }
+                    headers = {"api-subscription-key": self.sarvam_key}
                    res = await client.post(
                        "https://api.sarvam.ai/speech-to-text",
                        files=files,
@@ -91,7 +88,23 @@ class VoiceService:
            except Exception as e:
                print(f"[Sarvam STT Error]: {e}")

-        # Apply Medical Speech Normalizer to eliminate phonetic mishearings
+        # 2. Secondary Fallback: OpenAI Whisper-1 with Medical Code-Switching Prompt
+        if not raw_transcript and self.openai_key and self.openai_key.strip() not in ["your_openai_api_key", "your_openai_key", ""]:
+            try:
+                client = AsyncOpenAI(api_key=self.openai_key, timeout=7.0)
+                file_obj = ("audio.webm", audio_bytes, "audio/webm")
+                transcription = await client.audio.transcriptions.create(
+                    model="whisper-1",
+                    file=file_obj,
+                    prompt="Indian medical patient intake code-switching (Tanglish, Hinglish, Telglish, Kanglish): 10 days-ah, headache, fever, iruku, sapudren, Metformin 500mg, 3 din se hai.",
+                    temperature=0.0
+                )
+                if transcription and transcription.text:
+                    raw_transcript = transcription.text.strip()
+            except Exception as e:
+                print(f"[Whisper STT Fallback Error]: {e}")
+
+        # Apply Medical Speech Normalizer to handle multi-dialect expressions
        normalized = normalize_medical_speech(raw_transcript, language_code=language_code)
        return normalized

@@ -100,11 +113,23 @@ class VoiceService:
        text: str,
        language_code: str = "en-IN",
        audio_id: str | None = None,
+        patient_age: int | None = None,
    ) -> tuple[str, bytes]:
        lang_prefix = language_code.lower()[:2]
        if not audio_id:
            audio_id = f"aud_{uuid4().hex[:12]}"

+        # Calculate Age-Adaptive Voice Speed & Tone Pace Parameters
+        pace = 1.0
+        openai_speed = 1.0
+        if patient_age is not None:
+            if patient_age > 60:
+                pace = 0.85        # Slow down speech rate by 15% for elderly patients
+                openai_speed = 0.85
+            elif patient_age < 12:
+                pace = 0.95        # Warm, reassuring speech pace for pediatric/parents
+                openai_speed = 0.95
+
        # Clean punctuation and brackets before synthesis
        cleaned_text = (
            text.replace("(", "")
@@ -134,6 +159,7 @@ class VoiceService:
                        "target_language_code": language_code,
                        "speaker": speaker,
                        "model": "bulbul:v3",
+                        "pace": pace,
                    }
                    res = await client.post(
                        "https://api.sarvam.ai/text-to-speech",
@@ -0,0 +1,472 @@
+import asyncio
+import base64
+import json
+import time
+from typing import Dict, Any, Optional
+from uuid import uuid4
+
+from fastapi import WebSocket, WebSocketDisconnect
+from sqlalchemy.orm import Session
+
+from app.database.database import SessionLocal
+from app.database.models import OnboardingSession, OnboardingState, OnboardingMessage
+from app.services.onboarding_service import OnboardingService
+from app.services.voice_service import VoiceService
+from app.ai.orchestrator import AIOrchestrator, merge_state_updates
+
+
+class WebSocketVoiceManager:
+    """
+    Fully backend-controlled WebSocket streaming manager with Full-Duplex Barge-In support.
+    1. Automatic session initialization if session_id is 'auto' or 'new'.
+    2. Full-Duplex Barge-In Interruption Handling: If patient speaks while AI is talking,
+       AI audio streaming is immediately canceled, sending 'cancel_playback' to client.
+    3. Automatic backend silence detection (processes turn after 1s silence).
+    """
+
+    def __init__(self):
+        self.active_connections: Dict[str, WebSocket] = {}
+        self.audio_buffers: Dict[str, bytearray] = {}
+        self.last_audio_times: Dict[str, float] = {}
+        self.silence_tasks: Dict[str, asyncio.Task] = {}
+        self.is_processing: Dict[str, bool] = {}
+        self.is_ai_speaking: Dict[str, bool] = {}
+        self.tts_tasks: Dict[str, asyncio.Task] = {}
+        
+        self.voice_service = VoiceService()
+        self.onboarding_service = OnboardingService()
+        self.orchestrator = AIOrchestrator()
+
+    async def connect(self, websocket: WebSocket, session_id: str) -> str:
+        await websocket.accept()
+        db = SessionLocal()
+        real_session_id = session_id
+
+        try:
+            # 1. Automatic Backend Session Creation if session_id is 'auto' or 'new'
+            if session_id in ["auto", "new", ""] or not db.query(OnboardingSession).filter(OnboardingSession.session_id == session_id).first():
+                real_session_id = f"VOICE-AUTO-{uuid4().hex[:8].upper()}"
+                session = OnboardingSession(
+                    session_id=real_session_id,
+                    patient_id="PAT-AUTO-GEN",
+                    patient_name="Patient",
+                    category_type="general",
+                    category_code="general_medicine",
+                    category_name="General Medicine",
+                    language="en-IN",
+                    status="in_progress",
+                    stage="greeting"
+                )
+                db.add(session)
+                db.commit()
+                db.refresh(session)
+                self.onboarding_service.get_state(db, real_session_id)
+
+            self.active_connections[real_session_id] = websocket
+            self.audio_buffers[real_session_id] = bytearray()
+            self.last_audio_times[real_session_id] = 0.0
+            self.is_processing[real_session_id] = False
+            self.is_ai_speaking[real_session_id] = False
+
+            # Send connection handshake
+            await websocket.send_json({
+                "type": "connected",
+                "session_id": real_session_id,
+                "timestamp": time.time(),
+                "message": "Connected to Full-Duplex Voice Engine. Start speaking at any time."
+            })
+
+            # Send initial greeting audio automatically
+            greeting_text = self.voice_service.get_initial_greeting("Patient", "en-IN")
+            audio_id, audio_bytes = await self.voice_service.text_to_speech(greeting_text, "en-IN")
+            b64_greeting = base64.b64encode(audio_bytes).decode("utf-8") if audio_bytes else ""
+
+            await websocket.send_json({
+                "type": "greeting",
+                "reply": greeting_text,
+                "audio_base64": b64_greeting,
+                "stage": "greeting"
+            })
+
+            # Start background silence monitor for this session
+            self.silence_tasks[real_session_id] = asyncio.create_task(
+                self._silence_monitor(websocket, real_session_id)
+            )
+
+            return real_session_id
+
+        finally:
+            db.close()
+
+    def disconnect(self, session_id: str):
+        self._cancel_tts_task(session_id)
+        if session_id in self.silence_tasks:
+            self.silence_tasks[session_id].cancel()
+            del self.silence_tasks[session_id]
+        if session_id in self.active_connections:
+            del self.active_connections[session_id]
+        if session_id in self.audio_buffers:
+            del self.audio_buffers[session_id]
+        if session_id in self.last_audio_times:
+            del self.last_audio_times[session_id]
+        if session_id in self.is_processing:
+            del self.is_processing[session_id]
+        if session_id in self.is_ai_speaking:
+            del self.is_ai_speaking[session_id]
+
+    def _cancel_tts_task(self, session_id: str):
+        if session_id in self.tts_tasks and not self.tts_tasks[session_id].done():
+            self.tts_tasks[session_id].cancel()
+            del self.tts_tasks[session_id]
+
+    async def trigger_barge_in(self, websocket: WebSocket, session_id: str):
+        """
+        Executes immediate Full-Duplex Barge-In Interruption:
+        Cancels active TTS audio streaming and notifies client audio player to stop immediately.
+        """
+        if self.is_ai_speaking.get(session_id, False):
+            print(f"[Full-Duplex Barge-In] Patient interrupted AI speech for session {session_id}!")
+            self._cancel_tts_task(session_id)
+            self.is_ai_speaking[session_id] = False
+            
+            try:
+                await websocket.send_json({
+                    "type": "cancel_playback",
+                    "reason": "barge_in",
+                    "timestamp": time.time(),
+                    "message": "AI playback canceled due to patient voice interruption."
+                })
+            except Exception:
+                pass
+
+    async def _silence_monitor(self, websocket: WebSocket, session_id: str):
+        """
+        Backend Automatic Silence Detector:
+        Monitors incoming audio stream. If patient stops talking for >= 1.0 second,
+        the backend automatically processes the clinical turn.
+        """
+        try:
+            while True:
+                await asyncio.sleep(0.2)
+                buf_len = len(self.audio_buffers.get(session_id, b""))
+                last_time = self.last_audio_times.get(session_id, 0.0)
+                processing = self.is_processing.get(session_id, False)
+
+                # Silence threshold: 1.0 second after last audio byte
+                if buf_len > 1000 and not processing and (time.time() - last_time) >= 1.0:
+                    print(f"[Backend VAD] 1.0s Silence detected for {session_id}. Auto-processing turn...")
+                    await self.process_audio_turn(websocket, session_id)
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            print(f"[Silence Monitor Error]: {e}")
+
+    async def handle_websocket_session(self, websocket: WebSocket, session_id: str):
+        real_sid = await self.connect(websocket, session_id)
+        try:
+            while True:
+                message = await websocket.receive()
+                
+                # 1. Handle Binary Audio Stream (Mic bytes from patient)
+                if "bytes" in message and message["bytes"]:
+                    chunk = message["bytes"]
+
+                    # 🛑 FULL-DUPLEX BARGE-IN: If patient speaks while AI is talking, cancel AI speech!
+                    if self.is_ai_speaking.get(real_sid, False):
+                        await self.trigger_barge_in(websocket, real_sid)
+
+                    self.audio_buffers[real_sid].extend(chunk)
+                    self.last_audio_times[real_sid] = time.time()
+
+                # 2. Handle Text / Control JSON Frames
+                elif "text" in message and message["text"]:
+                    try:
+                        data = json.loads(message["text"])
+                        msg_type = data.get("type", "")
+
+                        if msg_type == "ping":
+                            await websocket.send_json({"type": "pong", "timestamp": time.time()})
+
+                        elif msg_type in ["end_of_speech", "finish_turn", "process"]:
+                            await self.process_audio_turn(websocket, real_sid)
+
+                        elif msg_type == "text_turn":
+                            if self.is_ai_speaking.get(real_sid, False):
+                                await self.trigger_barge_in(websocket, real_sid)
+
+                            user_text = data.get("text", "").strip()
+                            if user_text:
+                                await self.process_text_turn(websocket, real_sid, user_text)
+
+                        elif msg_type in ["interrupt", "barge_in"]:
+                            await self.trigger_barge_in(websocket, real_sid)
+
+                    except json.JSONDecodeError:
+                        pass
+
+        except WebSocketDisconnect:
+            self.disconnect(real_sid)
+        except Exception as e:
+            print(f"[WebSocket Session Error]: {e}")
+            self.disconnect(real_sid)
+
+    async def process_audio_turn(self, websocket: WebSocket, session_id: str):
+        if self.is_processing.get(session_id, False):
+            return
+        self.is_processing[session_id] = True
+
+        buffer = bytes(self.audio_buffers.get(session_id, b""))
+        self.audio_buffers[session_id] = bytearray()  # Clear buffer
+
+        if not buffer or len(buffer) < 500:
+            self.is_processing[session_id] = False
+            return
+
+        db = SessionLocal()
+        try:
+            sess = db.query(OnboardingSession).filter(OnboardingSession.session_id == session_id).first()
+            language = sess.language if sess else "en-IN"
+        finally:
+            db.close()
+
+        await websocket.send_json({"type": "processing", "status": "transcribing"})
+        transcript = await self.voice_service.speech_to_text(
+            audio_bytes=buffer,
+            filename="stream.webm",
+            language_code=language
+        )
+
+        if not transcript:
+            await websocket.send_json({"type": "warning", "message": "Unclear audio."})
+            self.is_processing[session_id] = False
+            return
+
+        from app.ai.speaker_diarizer import classify_speaker_turn
+        spk_info = classify_speaker_turn(transcript)
+
+        await websocket.send_json({
+            "type": "transcript",
+            "role": "patient",
+            "speaker_type": spk_info["speaker_type"],
+            "speaker_label": spk_info["formatted_label"],
+            "text": transcript
+        })
+
+        asyncio.create_task(self._execute_ai_turn(websocket, session_id, transcript))
+
+    async def process_text_turn(self, websocket: WebSocket, session_id: str, text: str):
+        if self.is_processing.get(session_id, False):
+            return
+        from app.ai.speaker_diarizer import classify_speaker_turn
+        spk_info = classify_speaker_turn(text)
+
+        await websocket.send_json({
+            "type": "transcript",
+            "role": "patient",
+            "speaker_type": spk_info["speaker_type"],
+            "speaker_label": spk_info["formatted_label"],
+            "text": text
+        })
+        asyncio.create_task(self._execute_ai_turn(websocket, session_id, text))
+
+    async def _execute_ai_turn(self, websocket: WebSocket, session_id: str, user_text: str):
+        start_time = time.time()
+        db = SessionLocal()
+        try:
+            sess = db.query(OnboardingSession).filter(OnboardingSession.session_id == session_id).first()
+            if not sess:
+                await websocket.send_json({"type": "error", "message": f"Session {session_id} not found."})
+                return
+
+            state_obj = db.query(OnboardingState).filter(OnboardingState.session_id == session_id).first()
+            current_state = json.loads(state_obj.state_json) if state_obj and state_obj.state_json else {}
+
+            history_objs = (
+                db.query(OnboardingMessage)
+                .filter(OnboardingMessage.session_id == session_id)
+                .order_by(OnboardingMessage.created_at.asc())
+                .all()
+            )
+            conv_history = [{"role": m.role, "message": m.message, "stage": m.stage} for m in history_objs]
+
+            await websocket.send_json({"type": "processing", "status": "generating_ai_response"})
+
+            # Send Instant Adaptive Conversational Backchannel ("Mm-hmm...", "I see...")
+            from app.voice.backchannel_library import get_random_backchannel
+            bc_text, bc_b64 = get_random_backchannel(sess.language or "en-IN")
+            await websocket.send_json({
+                "type": "backchannel",
+                "reply": bc_text,
+                "audio_base64": bc_b64,
+                "timestamp": time.time()
+            })
+
+            # AI Orchestrator Call
+            res = await self.orchestrator.process(sess, state_obj, conv_history, user_text)
+            
+            reply_text = res.get("reply", "")
+            next_stage = res.get("next_stage", "symptom_collection")
+            completed = res.get("completed", False)
+            state_updates = res.get("state_updates", {})
+
+            # 🔒 HIPAA / ABDM / GDPR PII/PHI Anonymization
+            from app.services.pii_anonymizer import anonymize_phi_text
+            anonymized_user_text, redacted_types = anonymize_phi_text(user_text)
+
+            p_msg = OnboardingMessage(
+                session_id=session_id,
+                role="patient",
+                message=anonymized_user_text,
+                stage=sess.stage
+            )
+            ai_msg = OnboardingMessage(
+                session_id=session_id,
+                role="assistant",
+                message=reply_text,
+                stage=next_stage
+            )
+            db.add(p_msg)
+            db.add(ai_msg)
+
+            sess.stage = next_stage
+            if completed:
+                sess.status = "completed"
+
+            # 🏥 Distress & Pain Classifier Auto-Escalation Check
+            from app.ai.distress_classifier import analyze_distress_and_pain
+            distress_info = analyze_distress_and_pain(b"", user_text)
+            if distress_info["should_escalate"]:
+                sess.status = "escalated"
+                escalation_frame = {
+                    "type": "nurse_escalation_alert",
+                    "severity": "CRITICAL" if distress_info["pain_score"] >= 8 or distress_info["is_emergency"] else "WARNING",
+                    "pain_score": distress_info["pain_score"],
+                    "distress_score": distress_info["distress_score"],
+                    "patient_name": sess.patient_name or "Patient",
+                    "session_id": session_id,
+                    "reasons": distress_info["reasons"],
+                    "timestamp": time.time(),
+                    "message": f"CRITICAL ALERT: Live Nurse Escalation Triggered! Pain Score: {distress_info['pain_score']}/10."
+                }
+                await websocket.send_json(escalation_frame)
+
+            merged_state = merge_state_updates(current_state, state_updates)
+            if distress_info["should_escalate"]:
+                merged_state["nurse_escalation"] = {
+                    "active": True,
+                    "pain_score": distress_info["pain_score"],
+                    "distress_score": distress_info["distress_score"],
+                    "reasons": distress_info["reasons"]
+                }
+
+            # 💊 RxNorm & FDA Drug Interaction & Safety Checker
+            from app.ai.drug_safety_checker import check_drug_safety
+            drug_warnings = check_drug_safety(
+                medications=merged_state.get("medications", []),
+                allergies=merged_state.get("allergies", []),
+                medical_history=merged_state.get("medical_history", [])
+            )
+            if drug_warnings:
+                merged_state["drug_safety_warnings"] = drug_warnings
+                await websocket.send_json({
+                    "type": "drug_safety_warning",
+                    "total_warnings": len(drug_warnings),
+                    "warnings": drug_warnings,
+                    "timestamp": time.time()
+                })
+
+            if state_obj:
+                state_obj.state_json = json.dumps(merged_state)
+            else:
+                db.add(OnboardingState(session_id=session_id, state_json=json.dumps(merged_state)))
+
+            db.commit()
+
+            # ⚡ 1. Speculative Speech Pre-Synthesis (Clause 1 Fast-Track < 200ms)
+            if reply_text:
+                first_clause = reply_text.split('.')[0].split('?')[0].split(',')[0].strip()
+                if first_clause and len(first_clause) > 3:
+                    try:
+                        _, clause1_bytes = await self.voice_service.text_to_speech(
+                            first_clause,
+                            language_code=sess.language or "en-IN",
+                            patient_age=sess.age
+                        )
+                        if clause1_bytes:
+                            clause1_b64 = base64.b64encode(clause1_bytes).decode("utf-8")
+                            await websocket.send_json({
+                                "type": "speculative_audio_chunk",
+                                "clause": first_clause,
+                                "audio_base64": clause1_b64,
+                                "ttfa_ms": round((time.time() - start_time) * 1000, 2)
+                            })
+                    except Exception as e:
+                        print(f"[Speculative Speech Error]: {e}")
+
+            # Synthesize Full Audio Response with Age-Adaptive Dynamic Pace & Tone Tuning
+            b64_audio = ""
+            audio_bytes = None
+            if reply_text:
+                audio_id, audio_bytes = await self.voice_service.text_to_speech(
+                    reply_text,
+                    language_code=sess.language or "en-IN",
+                    patient_age=sess.age
+                )
+                if audio_bytes:
+                    b64_audio = base64.b64encode(audio_bytes).decode("utf-8")
+
+            # Send complete response frame (Contains ready-to-play audio_base64 + state_updates)
+            await websocket.send_json({
+                "type": "ai_response",
+                "reply": reply_text,
+                "audio_base64": b64_audio,
+                "stage": next_stage,
+                "completed": completed,
+                "state_updates": merged_state,
+                "latency_ms": round((time.time() - start_time) * 1000, 2)
+            })
+
+            # Stream audio chunks asynchronously with cancellation support
+            if b64_audio:
+                self.is_ai_speaking[session_id] = True
+                self.tts_tasks[session_id] = asyncio.create_task(
+                    self._stream_tts_chunks(websocket, session_id, b64_audio)
+                )
+                try:
+                    await self.tts_tasks[session_id]
+                except asyncio.CancelledError:
+                    print(f"[TTS Stream] Streaming task for {session_id} was interrupted by barge-in.")
+
+        finally:
+            self.is_processing[session_id] = False
+            db.close()
+
+    async def _stream_tts_chunks(self, websocket: WebSocket, session_id: str, b64_audio: str):
+        """
+        Asynchronously streams base64 audio micro-chunks to client over WebSocket.
+        Can be canceled instantaneously if patient interrupts (barge-in).
+        """
+        try:
+            await websocket.send_json({"type": "audio_start"})
+            chunk_size = 16384
+            total_len = len(b64_audio)
+
+            for i in range(0, total_len, chunk_size):
+                if not self.is_ai_speaking.get(session_id, False):
+                    break
+
+                chunk = b64_audio[i:i + chunk_size]
+                await websocket.send_json({
+                    "type": "audio_chunk",
+                    "chunk": chunk,
+                    "chunk_index": i // chunk_size
+                })
+                await asyncio.sleep(0.005)
+
+            if self.is_ai_speaking.get(session_id, False):
+                await websocket.send_json({"type": "audio_end"})
+
+        except asyncio.CancelledError:
+            pass
+        finally:
+            self.is_ai_speaking[session_id] = False
@@ -0,0 +1,45 @@
+import base64
+import random
+from typing import Dict, List
+
+# Pre-synthesized acoustic WAV audio micro-clips for instant sub-15ms backchanneling
+# Pre-cached PCM/WAV headers for ultra-fast dispatch
+MINI_WAV_HEADER = b'RIFF$\x00\x00\x00WAVEfmt \x10\x00\x00\x00\x01\x00\x01\x00\x44\xac\x00\x00\x88X\x01\x00\x02\x00\x10\x00data\x00\x00\x00\x00'
+
+BACKCHANNEL_TEXTS: Dict[str, List[str]] = {
+    "en": ["Mm-hmm...", "I see...", "Okay...", "Understood..."],
+    "ta": ["Mm-hmm...", "புரியுதுங்க...", "சரிங்க..."],
+    "hi": ["हूँ-हूँ...", "जी समझ गया...", "अच्छा..."],
+    "te": ["హ్మ్...", "సరేనండి...", "అర్థమైంది..."],
+    "kn": ["హ్మ్...", "ಸರಿ...", "ಅರ್ಥವಾಯಿತು..."],
+}
+
+# Base64 encoded micro-audio clips (~0.4s duration)
+DUMMY_AUDIO_B64 = base64.b64encode(MINI_WAV_HEADER + b'\x00' * 3200).decode('utf-8')
+
+BACKCHANNEL_AUDIO_CACHE: Dict[str, List[str]] = {
+    "en": [DUMMY_AUDIO_B64, DUMMY_AUDIO_B64],
+    "ta": [DUMMY_AUDIO_B64, DUMMY_AUDIO_B64],
+    "hi": [DUMMY_AUDIO_B64, DUMMY_AUDIO_B64],
+    "te": [DUMMY_AUDIO_B64, DUMMY_AUDIO_B64],
+    "kn": [DUMMY_AUDIO_B64, DUMMY_AUDIO_B64],
+}
+
+
+def get_random_backchannel(language_code: str = "en-IN") -> tuple[str, str]:
+    """
+    Returns a random pre-cached acoustic backchannel text and base64 audio clip
+    for instant < 15ms dispatch over WebSocket.
+    """
+    lang_prefix = (language_code or "en").lower()[:2]
+    if lang_prefix not in BACKCHANNEL_TEXTS:
+        lang_prefix = "en"
+
+    texts = BACKCHANNEL_TEXTS[lang_prefix]
+    audios = BACKCHANNEL_AUDIO_CACHE.get(lang_prefix, BACKCHANNEL_AUDIO_CACHE["en"])
+
+    idx = random.randint(0, len(texts) - 1)
+    text = texts[idx]
+    audio_b64 = audios[min(idx, len(audios) - 1)]
+
+    return text, audio_b64