196 lines
12 KiB
Markdown
196 lines
12 KiB
Markdown
# 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**.
|