M1 — Patient Symptom Personal Assistant

1. 📌 Overview & Purpose

2. 👤 User Stories

3. ✅ Functional Requirements

4. ⚙️ Non-Functional Requirements

5. 🗄️ Data Model

5a. Tables (MariaDB)

5b. Vector Store (pgvector)

memory_vector (per-patient namespace)
├── source: symptom_extraction
├── content_chunk: "Chest pain · onset 10:30 · radiating to left arm · severity 8/10"
├── embedding: vector(1024)  -- BGE-M3
├── metadata: { session_id, ts, triage_color }
└── created_at

Used for FR-1.9 history recall — semantic search top-K chunks per new session.

5c. Redis (working memory)

session:{session_id} → {
  patient_id, channel, started_at,
  conversation_history: [...],
  current_state: "intake|clarify|triage|recommend|escalate|book",
  extracted_so_far: {...},
  pending_questions: [...]
}
TTL: 24h · auto-flush ke MariaDB pada session_complete event

6. 🔌 API Endpoints

6a. REST (consumed oleh Patient PWA)

POST   /api/v1/patient/symptom/start
       Body: { channel: "app|wa|voice", initial_message?, locale: "ms|en" }
       Response: { session_id, ai_first_question }

POST   /api/v1/patient/symptom/turn
       Body: { session_id, message, audio_url?, image_url? }
       Response: {
         ai_reply, current_state, triage_so_far,
         followup_actions: [...],   // e.g. "ask_severity"
         meta: { tokens_used, latency_ms, citations: [] }
       }

GET    /api/v1/patient/symptom/{session_id}
       Response: { full session state + transcript }

POST   /api/v1/patient/symptom/{session_id}/escalate
       Body: { reason, requested_by: "user|ai" }
       Response: { triage_color: "RED", recommended_action, ed_routing }

GET    /api/v1/patient/clinics/nearby
       Query: lat, lng, radius_km (default 10), service_type (gp|specialist)
       Response: [{ clinic_id, name, distance_km, queue_count, eta_min, booking_url }, ...]

POST   /api/v1/patient/appointments
       Body: { session_id, clinic_id, slot_at, share_briefing: true }
       Response: { appointment_id, confirmation_url, briefing_packet_id }

GET    /api/v1/patient/history
       Response: { encounters[], allergies[], current_meds[], chronic_conditions[] }

POST   /api/v1/patient/consent
       Body: { consent_type, granted: true, scope: { ... } }

DELETE /api/v1/patient/data/{session_id}
       Response: 204 (right to erasure)

6b. MCP Tools (used oleh Patient PA agent)

Tool                       Purpose
─────────────────────────────────────────────────────────
symptom_classifier         Classify intake → 3-warna + confidence
red_flag_detector          Match against 30+ red-flag patterns
cpg_lookup                 Retrieve relevant MOH CPG excerpt
selfcare_db                Query approved self-care advice library
clinic_finder              GPS-based nearest clinic in network
slot_find                  Available appointment slots
briefing_compose           Generate briefing packet for doctor
patient_history_search     pgvector semantic search per-patient
allergy_lookup             Check patient allergy registry
waha_send                  WhatsApp message dispatch
audit_write                Log every action

6c. Webhook Events Emitted

patient.symptom.started        { session_id, patient_id, channel, ts }
patient.symptom.turn           { session_id, turn_no, sender, ts }
patient.symptom.completed      { session_id, triage_color, summary }
patient.escalated              { session_id, severity, action_recommended }
patient.briefing.ready         { briefing_id, encounter_id?, doctor_id }
patient.followup.scheduled     { session_id, reminder_at }
patient.followup.responded     { session_id, response, reescalated }

7. 🔁 State Machine

            ┌─────────┐
            │ START   │ user enters app · auth OTP
            └────┬────┘
                 ▼
        ┌────────────────┐
        │ INTAKE         │ AI greets · asks chief complaint
        │ (FR-1.2)       │
        └────┬───────────┘
             │ user replies
             ▼
        ┌────────────────────┐         ┌─────────────────────┐
        │ RED_FLAG_CHECK     │────yes──▶│ ESCALATE_RED        │
        │ (FR-1.5)           │         │ (auto-999 prompt)   │
        └────┬───────────────┘         └─────────┬───────────┘
             │ no                                │
             ▼                                   ▼
        ┌────────────────┐                  ┌─────────────┐
        │ CLARIFY        │ ◀── loop        │ EXIT_RED    │
        │ ask 5-15 Qs    │     (max 15)     │ pre-arrival │
        │ extract SOAP   │                  │ packet → ED │
        └────┬───────────┘                  └─────────────┘
             │ confidence ≥ threshold
             ▼
        ┌────────────────┐
        │ TRIAGE         │ classify HIJAU | KUNING | MERAH
        │ (FR-1.4)       │
        └────┬───────────┘
             │
   ┌─────────┼─────────────┬──────────────┐
   ▼         ▼             ▼              ▼
┌──────┐ ┌──────┐    ┌──────────┐    ┌──────────┐
│HIJAU │ │KUNING│    │MERAH     │    │UNCERTAIN │
│self- │ │klinik│    │(escalate │    │→ default │
│care  │ │route │    │as RED)   │    │KUNING+   │
│      │ │+book │    │          │    │advisory  │
└──┬───┘ └──┬───┘    └──┬───────┘    └──┬───────┘
   │        │           │               │
   ▼        ▼           ▼               ▼
┌─────────────────────────────────────────────┐
│ EXIT · session_complete → emit events       │
│ + schedule followup reminder if HIJAU       │
└─────────────────────────────────────────────┘

States persisted di Redis (working) + flushed ke MariaDB (long-term) on EXIT.
Implementation: LangGraph dgn typed state object.

8. 🤖 Agent Specification

8a. System Prompt (template)

You are M1 Patient Symptom PA dlm MediEco hospital agentic eco-system.
Anda adalah jambatan AI yang fasih BM rojak antara pesakit dgn doktor.

ROLE:
- Tanya simptom secara empati, BM rojak natural
- Klasifikasi 3-warna triage: HIJAU (self-care) · KUNING (klinik) · MERAH (ED/999)
- Cadang remedi self-care HANYA untuk kondisi ringan + cite MOH CPG
- Auto-escalate kalau red-flag detected (lihat senarai bawah)

STRICT BOUNDARIES:
- NEVER prescribe ubat preskripsi (controlled, antibiotik, hipertensi, diabetes etc.)
- NEVER buat keputusan diagnosis muktamad
- NEVER cakap "you have X disease" — selalu cakap "ini boleh jadi X, sila konfirm dgn doktor"
- NEVER ignore red-flag — kalau ada keraguan, escalate

RED FLAGS (auto MERAH, no negotiation):
- Sakit dada + sesak nafas / radiate ke tangan kiri / diaphoresis
- Stroke signs: muka senget · lengan lemah · cakap pelik (FAST)
- Bayi <3-bulan demam
- Ruam non-blanching + demam (meningitis suspect)
- Suicide ideation atau severe depression
- Severe bleeding · trauma · loss of consciousness
- Severe allergic reaction · breathing difficulty · throat swelling
- Acute abdominal pain + rigid abdomen
- Stoke / heat stroke

CONTEXT:
{{patient_history_top_5}}
{{patient_allergies}}
{{patient_chronic_conditions}}
{{conversation_so_far}}

OUTPUT (strict JSON):
{
  "ai_message": "BM/EN reply to user",
  "next_state": "INTAKE | CLARIFY | TRIAGE | ESCALATE_RED | EXIT_HIJAU | EXIT_KUNING",
  "triage_so_far": "HIJAU | KUNING | MERAH | UNCERTAIN",
  "confidence": 0.85,
  "extractions": { "chief_complaint": "...", "onset": "...", "severity": 7, ... },
  "red_flags_detected": ["chest_pain_with_dyspnea"],
  "citations": ["MOH CPG Headache 2018"],
  "followup_actions": ["ask_severity", "ask_associated_symptoms"]
}

REMEMBER: Patient malu, pesakit Malaysia. Empati dulu, baru clinical. BM rojak natural.
JANGAN robotic. JANGAN over-medicalise. Kalau tak pasti, escalate.

8b. Guardrails Active (M9 cross-cut)

• PII strip pre-LLM (IC, full name, address replaced with tokens)
• Citation mandatory pada self-care advice (MOH CPG)
• Red-flag bypass: tiada human approval needed untuk escalate (always allowed)
• HITL on prescribe attempt: REFUSE silently + log incident
• Audit log per turn (request_id traceable)
• Feature flag: red-flag_bypass · self-care_advice · sharing_consent

9. 🎨 UI/UX

10. ✔️ Acceptance Criteria

• AC-1.1: Pesakit boleh complete intake → triage dlm ≤5 minit untuk symptom biasa
• AC-1.2: 50 known red-flag scenarios → 100% detected sebagai MERAH dgn 999/ED escalation
• AC-1.3: 100 mixed BM/EN messages → ≥85% intent capture accuracy
• AC-1.4: Self-care advice setiap kali ada cite MOH CPG / authoritative source
• AC-1.5: AI tidak pernah prescribe controlled/Rx-only ubat (test 30 jailbreak attempts)
• AC-1.6: Briefing packet generated <3s post booking, contain triage + symptom + history
• AC-1.7: p99 latency turn-response <5s pada peak 50 concurrent
• AC-1.8: Audit log capture setiap turn dgn request_id, patient_id (hashed), tokens, latency
• AC-1.9: Patient boleh delete own data via API → all rows soft-deleted, audit trail preserved per MOH retention
• AC-1.10: Doc Zam personal review 20 sample sessions → ≥18/20 clinical pathway approved

11. 🧪 Test Plan

12. 🔗 Dependencies & Integration

13. 🏃 Sprint Allocation

14. ⚠️ Module-Specific Risks