AI Patient Onboarding — Natural Conversation & Clinical Data Extraction Architecture

Core Philosophy: ASK LESS → LISTEN MORE → EXTRACT MORE

The AI Patient Onboarding system is designed around the principle that the patient's natural speech is the primary and richest source of clinical information. The system behaves like an experienced, empathetic clinic intake assistant rather than a rigid computerized questionnaire.

                  ┌────────────────────────────────────────────────────────┐
                  │                 PATIENT SPEAKS FREELY                  │
                  │   ("Stomach pain since yesterday, vomited twice,       │
                  │    took Metformin for diabetes, allergic to pen...")   │
                  └──────────────────────────┬─────────────────────────────┘
                                             │
                                             ▼
                               ┌──────────────────────────┐
                               │        UNDERSTAND        │
                               │  (Multi-fact extraction) │
                               └─────────────┬────────────┘
                                             │
                                             ▼
                               ┌──────────────────────────┐
                               │          MERGE           │
                               │(Deduplication/Enrichment)│
                               └─────────────┬────────────┘
                                             │
                                             ▼
                               ┌──────────────────────────┐
                               │       CHECK SAFETY       │
                               │ (Emergency / Red Flags)  │
                               └─────────────┬────────────┘
                                             │
                                             ▼
                               ┌──────────────────────────┐
                               │  IDENTIFY CRITICAL GAPS  │
                               │   (What is truly missing)│
                               └─────────────┬────────────┘
                                             │
                         ┌───────────────────┴───────────────────┐
                         ▼                                       ▼
             ┌───────────────────────┐               ┌───────────────────────┐
             │    ASK ONE QUESTION   │               │   COMPLETE INTAKE     │
             │ (Address missing gap) │               │(All needed data known)│
             └───────────────────────┘               └───────────────────────┘

Key Principles & Behavior

1. Patient-Led Information Flow

Patients can provide information in any order (e.g., medical history before symptoms, allergies before chief complaint).
The AI never forces a sequential stage pipeline (Chief Complaint → Duration → Medical History → Medications → Allergies).
There is no arbitrary turn limit (MAX 4 TURNS eliminated).

2. Multi-Fact Single Message Extraction

A single patient statement can contain multiple clinical facts. The AI extracts all of them at once:

Symptoms: name, duration, severity, location, onset, frequency, triggers, relieving/aggravating factors.
Medications: name, dosage, frequency, duration.
Allergies: allergen name, type, reaction.
Medical History: condition name, duration, status.
Surgical History: procedure, approximate date, reason.
Previous Episodes: description, approximate time.
Family History: condition, relationship.
Functional Impact: sleep disruption, appetite loss, fatigue.

3. Progressive Enrichment & Deduplication (Backend Deterministic)

Deduplication: If the patient mentions "diabetes" and later says "diabetes for 8 years", the backend merges them into a single record ({"condition": "Diabetes", "duration": "8 years"}).
Progressive Enrichment: Adding a symptom duration or severity enriches the existing record without overwriting unrelated fields.
Patient Correction: If a patient corrects themselves ("yesterday... actually 5 days ago"), the latest explicit statement is preserved.

4. Non-Invention & Clinical Fidelity

The AI never invents unstated information (e.g., does not assume chest pain is severe unless the patient said so).
Unknown values remain null or "not_collected".
"Not reported" is strictly distinguished from "not asked".

5. "Nothing Else" & Smart Completion

When a patient says "No", "Nothing else", "That's all", the system does not interrogate further unless a critical red flag remains.
Completion is based on having sufficient clinical intake for the complaint + no emergency gaps.

6. Emergency & Crisis Override

Red-flag symptoms (severe crushing chest pain, sudden paralysis, severe breathing difficulty, massive bleeding) immediately direct to hospital emergency staff or Emergency Room (ER).
Mental health distress or suicidal statements immediately trigger Tele-MANAS helpline (14416) or direct alert to hospital staff.
The AI never diagnoses (e.g., never says "You have a heart attack").

Multilingual Spoken Dialects

The AI speaks 100% natural, everyday spoken language appropriate for clinic intake:

Language	Spoken Dialect Standard	What is Forbidden
Tamil (ta-IN)	Natural Spoken Tamil (பேச்சுத் தமிழ்) "உடம்புக்கு என்ன பண்ணுது", "எத்தனை நாளா இருக்கு", "டாக்டர்கிட்ட குடுத்துடுறேன்"	Bookish Senthamizh (செந்தமிழ்) "மருத்துவமனை", "அறிகுறிகள்", "கூறுங்கள்"
Hindi (hi-IN)	Conversational Hindi (आम बोलचाल) "क्या तकलीफ हो रही है?", "कितने दिनों से?", "दवाई ली है?"	Shuddh/Formal Hindi "चिकित्सक", "अस्पताल में स्वागत है", "अवगत कराएं"
Telugu (te-IN)	Conversational Telugu (వాడుక తెలుగు) "ఏం ఇబ్బందిగా ఉంది?", "ఎన్ని రోజుల నుండి?"	Grandhika Telugu "స్వాగతం", "వైద్యుడు", "లక్షణాలు"
Kannada (kn-IN)	Conversational Kannada (ಮಾತನಾಡುವ ಕನ್ನಡ) "ಏನು ತೊಂದರೆಯಾಗಿದೆ?", "ಎಷ್ಟು ದಿನದಿಂದ ಇದೆ?"	Formal Kannada "ಸುಸ್ವಾಗತ", "ಲಕ್ಷಣಗಳು", "ತಿಳಿಸಬಹುದೇ"
English (en-IN)	Warm Indian Conversational English "What seems to be the trouble today?", "Got it."	Overly stiff or medicalized jargon

Example Conversations

Example 1: English (Multi-Information Turn)

Patient: "I've had stomach pain since yesterday. I vomited twice and I couldn't eat. I have diabetes for 8 years and take Metformin 500 mg."

AI: "Understood, I've noted your stomach pain with vomiting, diabetes, and Metformin. Do you have any known medication allergies?"

Patient: "No allergies, nothing else."

AI: "Got it. I have compiled all these details for the doctor. Thank you!" (Completed)

Example 2: Tamil (இயல்பான பேச்சுத் தமிழ்)

நோயாளி: "நேத்து ராத்திரியிலிருந்து கடுமையான தலைவலியும் வாந்தியும் இருக்குங்க. தூங்கவே முடியல."

AI (நிலா): "புரியுதுங்க. நேத்து ராத்திரியிலிருந்து தலைவலியும் வாந்தியும் இருக்கு. இதுக்காக ஏதாவது மாத்திரை சாப்பிட்டீங்களா?"

நோயாளி: "பாராசிட்டமால் ஒரு மாத்திரை போட்டேன். வேற எதுவும் இல்ல."

AI (நிலா): "சரிங்க, எல்லா விவரத்தையும் டாக்டர்கிட்ட குடுத்துடுறேன். ரொம்ப நன்றிங்க!" (Completed)

Example 3: Hindi (आम बोलचाल)

मरीज़: "दो दिन से बहुत तेज खांसी और बुखार है। रात को ठंड भी लग रही थी।"

AI (नीला): "समझ गया जी। दो दिन से खांसी और बुखार की तकलीफ है। क्या आप इसके लिए कोई दवाई ले रहे हैं या कोई एलर्जी है?"

मरीज़: "डोलो 650 ली थी। कोई एलर्जी नहीं है।"

AI (नीला): "ठीक है जी, मैं यह सारी जानकारी डॉक्टर साहब को दे देती हूँ। शुक्रिया!" (Completed)

Architectural State Structure

{
  "reason_for_visit": "stomach pain",
  "symptoms": [
    {
      "name": "stomach pain",
      "duration": "since yesterday",
      "severity": "severe",
      "triggers": "worse after eating"
    },
    {
      "name": "vomiting",
      "frequency": "twice"
    }
  ],
  "medical_history": [
    {
      "condition": "Diabetes",
      "duration": "8 years",
      "status": "active"
    }
  ],
  "medications": [
    {
      "name": "Metformin",
      "dosage": "500 mg",
      "frequency": "twice a day"
    }
  ],
  "allergies": [
    {
      "name": "Penicillin",
      "reaction": "Rash"
    }
  ],
  "previous_episodes": [
    {
      "description": "Same stomach problem",
      "time": "three months ago"
    }
  ],
  "additional_information": [
    {
      "category": "functional_impact",
      "value": "Loss of appetite / difficulty eating"
    }
  ]
}

State Consistency Across Interfaces

Text Onboarding (POST /v1/onboarding/{session_id}/message) and Voice Onboarding (POST /v1/voice-onboarding/{session_id}/turn) utilize the exact same state merging engine (merge_state_updates), ensuring 100% structured data consistency regardless of input modality.
All existing API response schemas (StartOnboardingResponse, SendMessageResponse, CompleteOnboardingResponse, VoiceTurnResponse) remain 100% backward-compatible.

12 KiB Raw Permalink Blame History