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

---

## Example Conversations

### Example 1: English (Multi-Information Turn)
```text
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 (இயல்பான பேச்சுத் தமிழ்)
```text
நோயாளி: "நேத்து ராத்திரியிலிருந்து கடுமையான தலைவலியும் வாந்தியும் இருக்குங்க. தூங்கவே முடியல."

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

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

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

### Example 3: Hindi (आम बोलचाल)
```text
मरीज़: "दो दिन से बहुत तेज खांसी और बुखार है। रात को ठंड भी लग रही थी।"

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

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

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

---

## Architectural State Structure

```json
{
  "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**.