94 lines
6.8 KiB
Markdown
94 lines
6.8 KiB
Markdown
# AI Patient Onboarding — Conversation Flow Fix & Audit Report
|
|
|
|
## 1. Executive Summary
|
|
|
|
The complete conversational onboarding flow for the AI Patient Onboarding system has been audited, refactored, and verified. The primary objective was to resolve premature intake completion bugs and transition the system from a rigid turn-based interaction to an intelligent, state-driven patient intake assistant operating on the philosophy:
|
|
|
|
> **ASK LESS → LISTEN MORE → EXTRACT EVERYTHING PATIENT VOLUNTARILY PROVIDES → ASK ONLY THE MOST IMPORTANT MISSING QUESTION → NEVER REPEAT → NEVER COMPLETE TOO EARLY.**
|
|
|
|
All **81 automated tests** across the entire backend suite (including 20 newly added end-to-end conversational test scenarios) passed with 100% success rate.
|
|
|
|
---
|
|
|
|
## 2. Root Cause Analysis of Previous Bugs
|
|
|
|
| Issue | Root Cause | Fix Applied |
|
|
|---|---|---|
|
|
| **Premature Completion After Duration** | Fallback intake engine marked `completed=True` once `duration` was extracted, without verifying whether `medical_history`, `medications`, or `allergies` had been collected. | Centralized completion validation into `check_required_missing(state)` as the single source of truth across all engines and LLM post-processing. |
|
|
| **Fake Symptoms from Non-Symptom Messages** | Fallback symptom extraction treated any unmatched utterance (e.g., `"Metformin சாப்பிடுறேன்"`) as a symptom name. | Added strict exclusion checks for medication names, medical conditions, and allergy statements before fallback symptom assignment. |
|
|
| **Cross-Lingual Symptom Duplication** | Mentioning `"தலைவலி"` in Turn 1 and `"headache 3 days"` in Turn 3 created two separate symptom entries. | Implemented `CANONICAL_SYMPTOM_MAP` and multilingual normalization in `_normalize_key()` to unify synonymous terms across Indic languages and English. |
|
|
| **Missing Indic Spoken Emergency/Crisis Overrides** | Emergency detection keywords only covered literal formal terms, missing conversational phrases like `"மூச்சு விட முடியல"` or `"காயப்படுத்திக்கணும்"`. | Expanded `EMERGENCY_KEYWORDS_INDIC` and `CRISIS_KEYWORDS_INDIC` with spoken Tamil, Hindi, Telugu, Kannada phrases; executed safety checks at the very entry of `process()`. |
|
|
| **Missing Telugu & Kannada Duration Parsing** | Regexes only supported Tamil, Tanglish, Hindi, and English number tokens. | Added `TELUGU_NUMBER_MAP`, `KANNADA_NUMBER_MAP`, and spoken duration regexes (`"రోజుల నుండి"`, `"ದಿನದಿಂದ"`). |
|
|
| **Punctuation Failure in Negation Detection** | Sentences ending with periods/commas (e.g., `"எனக்கு வேற எதுவும் இல்ல."`) failed word-boundary negation regexes. | Added unicode-aware punctuation stripping to `is_negative_expression()`. |
|
|
|
|
---
|
|
|
|
## 3. Core Architecture Implemented
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[Patient Message Received] --> B{Emergency or Crisis Check?}
|
|
B -- Yes --> C[Immediate Life Safety Override\nAdvise 108 / Tele-MANAS 14416\nCompleted=True]
|
|
B -- No --> D[Deterministic Entity Extractor\nExtract all volunteered facts]
|
|
D --> E[merge_state_updates\nCross-lingual deduplication + progressive enrichment]
|
|
E --> F[check_required_missing\nEvaluate Reason for Visit, Symptoms, Duration,\nMedical History, Medications, Allergies]
|
|
F -- All Required Satisfied --> G[Wrap Up Intake\nConclusion Text + Completed=True]
|
|
F -- Missing Categories Exist --> H[Pick Highest-Priority Missing Field\nSelect Specialty-Aware Natural Question\nCompleted=False]
|
|
```
|
|
|
|
### Required Intake Categories (Single Source of Truth)
|
|
An intake session is complete **if and only if** all of the following conditions are satisfied:
|
|
1. `reason_for_visit`: Reported
|
|
2. `symptoms`: At least one meaningful symptom
|
|
3. `duration`: At least one symptom has duration
|
|
4. `medical_history`: Reported OR `confirmed_none`
|
|
5. `medications`: Reported OR `confirmed_none`
|
|
6. `allergies`: Reported OR `confirmed_none`
|
|
|
|
---
|
|
|
|
## 4. Test Matrix & Verification Results
|
|
|
|
```
|
|
============================= test session starts =============================
|
|
platform win32 -- Python 3.13.5, pytest-9.0.2, pluggy-1.6.0
|
|
collected 81 items
|
|
|
|
tests/production/test_production_security.py::test_reject_unauthenticated_request PASSED
|
|
tests/production/test_production_security.py::test_authenticated_session_creation PASSED
|
|
tests/production/test_production_security.py::test_idor_prevention_cross_session_access PASSED
|
|
tests/production/test_production_security.py::test_security_headers_and_request_id PASSED
|
|
tests/production/test_production_security.py::test_schema_validation_negative_age_rejection PASSED
|
|
tests/test_complete_conversation_flow.py::test_1_patient_provides_all_info_in_one_message PASSED
|
|
tests/test_complete_conversation_flow.py::test_2_patient_gives_symptoms_first PASSED
|
|
tests/test_complete_conversation_flow.py::test_3_patient_gives_duration_no_fake_symptom PASSED
|
|
tests/test_complete_conversation_flow.py::test_4_tamil_tanglish_duration PASSED
|
|
tests/test_complete_conversation_flow.py::test_5_telugu_duration PASSED
|
|
tests/test_complete_conversation_flow.py::test_6_kannada_duration PASSED
|
|
tests/test_complete_conversation_flow.py::test_7_medication_first_no_fake_symptom PASSED
|
|
tests/test_complete_conversation_flow.py::test_8_cross_language_symptom_deduplication PASSED
|
|
tests/test_complete_conversation_flow.py::test_9_progressive_enrichment PASSED
|
|
tests/test_complete_conversation_flow.py::test_10_patient_correction PASSED
|
|
tests/test_complete_conversation_flow.py::test_11_emergency_override_tamil PASSED
|
|
tests/test_complete_conversation_flow.py::test_12_mental_health_crisis_override_tamil PASSED
|
|
tests/test_complete_conversation_flow.py::test_13_nothing_else_handling PASSED
|
|
tests/test_complete_conversation_flow.py::test_14_mental_health_specialty PASSED
|
|
tests/test_complete_conversation_flow.py::test_15_cardiology_specialty PASSED
|
|
tests/test_complete_conversation_flow.py::test_16_multiple_symptoms_extraction PASSED
|
|
tests/test_complete_conversation_flow.py::test_17_no_false_symptom_from_medication PASSED
|
|
tests/test_complete_conversation_flow.py::test_18_session_isolation PASSED
|
|
tests/test_complete_conversation_flow.py::test_19_20_api_backward_compatibility PASSED
|
|
tests/test_complete_conversation_flow.py::test_21_exact_bug_regression PASSED
|
|
tests/test_conversation_behavior.py (50 tests) PASSED
|
|
tests/test_cors.py (6 tests) PASSED
|
|
|
|
======================= 81 passed in 30.15s ========================
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Backward Compatibility & Integrity Assurance
|
|
- **API Contracts Preserved**: No breaking changes to `/v1/voice-onboarding/turn`, `/v1/onboarding/message`, or `/v1/voice-onboarding/start`.
|
|
- **Database Schema**: Fully preserved with SQLite authoritative state isolation.
|
|
- **Frontend / Audio Integration**: Voice generation and response payloads (`audio_url`, `response_time_ms`, `stage`, `completed`) remain 100% compliant.
|