M4 — Doctor Personal Assistant

1. 📌 Overview & Purpose

2. 👤 User Stories

3. ✅ Functional Requirements

4. ⚙️ Non-Functional Requirements

5. 🗄️ Data Model

6. 🔌 API Endpoints

GET    /api/v1/doctor/encounters                        # today's queue (assigned to me)
GET    /api/v1/doctor/encounters/{id}                   # full encounter detail
POST   /api/v1/doctor/encounters                        # create new (manual / walk-in)
PATCH  /api/v1/doctor/encounters/{id}                   # update SOAP fields
POST   /api/v1/doctor/encounters/{id}/scribe/start      # begin audio capture
POST   /api/v1/doctor/encounters/{id}/scribe/chunk      # WebRTC audio chunk upload
POST   /api/v1/doctor/encounters/{id}/scribe/stop       # finalise · trigger SOAP gen
GET    /api/v1/doctor/encounters/{id}/soap              # current SOAP draft
PATCH  /api/v1/doctor/encounters/{id}/soap              # doctor edits

GET    /api/v1/doctor/encounters/{id}/cdss              # AI suggestions (auto-fired)
POST   /api/v1/doctor/encounters/{id}/cdss/feedback     # accept/reject/modify per item

POST   /api/v1/doctor/encounters/{id}/orders            # create order set
PATCH  /api/v1/doctor/orders/{order_id}                 # status update (sent · resulted)

POST   /api/v1/doctor/encounters/{id}/prescription      # create RX (DRAFT)
POST   /api/v1/doctor/prescriptions/{rx_id}/sign        # final sign + dispatch ke M5
GET    /api/v1/doctor/prescriptions/templates           # common RX templates

POST   /api/v1/doctor/encounters/{id}/referral          # specialist referral letter
POST   /api/v1/doctor/encounters/{id}/sign-off          # finalise encounter

GET    /api/v1/doctor/patients/{patient_id}/history     # full patient timeline
POST   /api/v1/doctor/history/search                    # semantic Q over history
       Body: { patient_id, query: "demam macam ni masa lepas apa berkesan" }

# 6-tab Quick Access aggregate endpoints
GET    /api/v1/doctor/patients/{id}/profile             # tab 1
GET    /api/v1/doctor/patients/{id}/medical-history     # tab 2
GET    /api/v1/doctor/patients/{id}/prescriptions       # tab 3
GET    /api/v1/doctor/patients/{id}/lab-results         # tab 4
GET    /api/v1/doctor/patients/{id}/imaging             # tab 5
GET    /api/v1/doctor/patients/{id}/billing             # tab 6

6a. MCP Tools (Doctor PA agent)

ambient_scribe        Audio → SOAP draft (Whisper + Llama 70B chained)
cdss                  Symptom + vitals + history → DDx top-5 + citations
ddx                   Differential diagnosis enumerator
order_set_suggest     CPG-based order set per dx hypothesis
cpg_lookup            MOH CPG retrieval (vector search)
history_search        pgvector semantic Q per-patient
icd10_coder           SOAP → ICD-10 codes top-3
referral_compose      Generate referral letter from encounter
patient_edu_compose   Patient instruction in BM + EN

7. 🔁 State Machine

            ┌─────────────────────┐
            │ ENCOUNTER_CREATED   │ ENC-YYYY-MMDD-NNN
            └─────────┬───────────┘
                      ▼
            ┌─────────────────────┐
            │ BRIEFING_LOADED     │ FR-4.2 from M2/M1
            └─────────┬───────────┘
                      ▼
   ┌──────────────────────────────────┐
   │ IN_CONSULTATION                  │
   │  ├── Tab navigation (6 tabs)     │
   │  ├── Vitals entry (manual or M1) │
   │  ├── Scribe ON ◀─loop─ chunk_in  │
   │  └── CDSS panel updates live     │
   └─────────┬────────────────────────┘
             ▼
   ┌─────────────────────────┐
   │ SOAP_DRAFTED            │ post scribe_stop
   │ AI generated S/O/A/P    │
   └─────────┬───────────────┘
             ▼
   ┌─────────────────────────┐
   │ DOCTOR_REVIEW           │ doctor edits SOAP
   │ + decides orders/RX     │
   └─────────┬───────────────┘
             ▼
   ┌─────────────────────────┐
   │ ORDERS_PRESCRIBED       │ HITL approval each
   │ (parallel actions)      │
   └─────────┬───────────────┘
             ▼
   ┌─────────────────────────┐
   │ SIGN_OFF                │ FR-4.10 single tap
   │ - SOAP locked            │
   │ - RX → M5 queue          │
   │ - billing → M7 trigger   │
   │ - patient instruction PDF│
   │ - audit log final        │
   └─────────────────────────┘

8. 🤖 Agent Specification

8a. Model Routing

• SOAP generation: Llama 70B Q5 (clinical reasoning quality)
• CDSS / DDx: Llama 70B Q5
• ASR: Whisper-Large v3 (BM/EN auto-detect)
• Cloud burst: gpt-4o (peak overflow only · clinical)
• Embedding (history search): BGE-M3
• ICD-10 coding: Llama 8B (lightweight rule-based)

8b. System Prompt (SOAP scribe)

You are M4 Doctor PA, a clinical co-pilot for licensed Malaysian medical practitioners.

ROLE:
- Generate structured SOAP notes from doctor-patient ambient audio transcripts
- Suggest differential diagnoses with citations from MOH CPG / WHO / NPRA
- Draft order sets and prescriptions per clinical pathway
- ALWAYS defer final clinical judgement to the licensed physician

STRICT BOUNDARIES:
- You DO NOT make final diagnoses. You suggest "considerations" with citations.
- You DO NOT execute orders. All orders require explicit doctor approval (HITL).
- You DO NOT prescribe controlled substances or paeds doses >2× standard without
  explicit doctor confirmation prompt.
- Citations REQUIRED for every dx/dose/CPG suggestion. No citation = no output.

INPUT:
- Audio transcript (BM/EN/rojak)
- Patient context (allergies, current meds, chronic conditions, recent vitals)
- Encounter type (OPD/follow-up/walk-in)

OUTPUT (JSON):
{
  "soap": {
    "subjective": "...",
    "objective": "...",
    "assessment": "Suggested DDx: ... (cite: MOH CPG ...)",
    "plan": "..."
  },
  "ddx_top5": [
    { "dx": "...", "icd10": "...", "confidence": 0.7, "citations": [...], "supporting": "...", "against": "..." }
  ],
  "suggested_orders": [...],
  "suggested_rx": [...],
  "human_approval_required": true,
  "safety_flags": []
}

REMEMBER: Doctor in front of you knows the patient. You are advisory only.
Highlight uncertainty. Always show DDx alternatives. Cite primary sources.

8c. Memory Tier

• Working: current encounter state (Redis · 24h TTL)
• Long-term per-patient: pgvector chunks of past encounters / SOAP / RX / labs
• Episodic (population): de-identified similar cases for "pesakit serupa pernah..." advisory only
• Procedural: MOH CPG library + hospital SOP (versioned, vector + structured)

8d. Guardrails (M9 active)

• PII strip pre-LLM untuk transcript (IC, full name, address)
• Citation mandatory on all clinical suggestions
• HITL gate untuk orders/RX/sign-off (no auto-execute)
• Drug DDI check via M5 cross-call before RX dispatch
• Allergy alert if conflict dgn patient registry
• Audit log per click (which suggestion accepted/rejected)

9. 🎨 UI/UX (6-tab Quick Access)

Per Doc Zam canonical mock — Encounter detail screen dgn 6 tabs left-rail.

9a. Right rail (always-visible)

• Briefing packet card (collapsed default)
• Scribe button (Start/Stop · status indicator · live transcript preview)
• CDSS panel (DDx top-5 · citations · accept/reject)
• SOAP editor (S/O/A/P fields · markdown · auto-save)
• Order set composer (checkbox + send)
• Sign-off button (sticky bottom)

9b. Filament 3 implementation notes

• Custom Filament page EncounterDetail.php
• Tab component (Filament built-in or custom Livewire)
• WebRTC integration via Alpine.js + native browser API
• Live updates via Livewire wire:poll atau WebSocket
• Mobile responsive — tablet (iPad) usage common di klinik

10. ✔️ Acceptance Criteria

• AC-4.1: Doktor boleh complete encounter (briefing → consult → SOAP → orders → sign-off) dlm ≤8 minit untuk OPD biasa
• AC-4.2: Ambient SOAP draft akurat — Doc Zam clinical review 20 sample, ≥18/20 acceptable dgn ≤3 line edit
• AC-4.3: CDSS DDx top-5 includes correct dx ≥85% pada 50 known scenarios
• AC-4.4: 100% suggestions ada citation visible dlm UI
• AC-4.5: HITL enforced — 30 jailbreak attempts utk auto-prescribe controlled substance → 0 success
• AC-4.6: 6-tab Quick Access load <1s setiap tab
• AC-4.7: History semantic search returns ≥85% relevant top-3 chunks
• AC-4.8: Sign-off triggers 4 downstream actions (M5 RX · M7 billing · patient PDF · audit log) dlm <5s
• AC-4.9: Dose paeds >2× standard → mandatory confirmation prompt with override reason
• AC-4.10: Doc Zam personal sign-off pada full M4 demo (Q3 clinical safety review)

11. 🧪 Test Plan

12. 🔗 Dependencies & Integration

• Hard: M9 audit · auth/RBAC · 11-section Patient model — Sprint 1.1 must finish first
• Soft (graceful degradation): M1 PSPA briefing source (fallback: doctor enter chief complaint manually)
• External: NPRA drug DB · MOH CPG library (vector indexed) · Whisper-Large weights · Llama 70B serving stack (vLLM)
• Downstream: M5 Pharmacy (RX dispatch) · M7 Admin (billing trigger) — built Sprint 2.1/2.2 — Sprint 1.3 emit events, downstream consume later

13. 🏃 Sprint Allocation

14. ⚠️ Module-Specific Risks