M5 — Pharmacy Personal Assistant

1. 📌 Overview & Purpose

Goal: Setiap preskripsi sampai kaunter farmasi di-validate AI dlm <3s — DDI, allergy, dose paeds/renal/hepatic, halal status, NPRA stock. Farmasis verify visual + barcode → dispense. Closed-loop verify untuk safety zero compromise.

Per Doc Zam mock (slide 7): Prescription Queue (8 prescriptions visible) · Verification panel · Print Label · Counsel checklist.

HITL gate: AI propose check, pharmacist final approve. Tiada auto-dispense.

2. 👤 User Stories

3. ✅ Functional Requirements

4. ⚙️ Non-Functional Requirements

5. 🗄️ Data Model

6. 🔌 API + MCP

GET    /api/v1/pharmacy/queue                   # ready/verifying/pending
POST   /api/v1/pharmacy/{rx_id}/verify          # AI run all checks
       Returns: { ddi_alerts, allergy_alerts, dose_warnings, halal_flags, generic_suggestions }

POST   /api/v1/pharmacy/{rx_id}/approve         # pharmacist HITL approve
       Body: { line_decisions: [{ line_no, action: "dispense"|"substitute"|"hold"|"cancel", reason }] }

POST   /api/v1/pharmacy/{rx_id}/dispense        # post barcode scan
       Body: { line_no, barcode, quantity }
       Returns: { dispense_id, label_pdf_url }

POST   /api/v1/pharmacy/{rx_id}/print-label     # generate label PDF
POST   /api/v1/pharmacy/{rx_id}/counsel-done    # close encounter

GET    /api/v1/pharmacy/inventory/check/{drug_code}
POST   /api/v1/pharmacy/inventory/reorder

# MCP Tools
ddi_check              Drug-drug interaction · severity + alternatives
allergy_lookup         Patient allergy registry cross-ref
dose_calc              Paeds/eGFR/hepatic adjusted
halal_filter           NPRA halal index check
generic_suggest        Substitution + cost compare
npra_stock             Drug DB lookup
barcode_verify         Match scanned barcode vs RX

7. 🔁 State Machine

┌──────────────────┐
│ RX_RECEIVED      │ from M4 sign-off
└────────┬─────────┘
         ▼
┌──────────────────┐
│ AI_VERIFYING     │ DDI · allergy · dose · halal · stock parallel
└────────┬─────────┘
         ▼
┌──────────────────┐         ┌──────────────────┐
│ ALERTS_RAISED    │────────►│ HITL_REVIEW      │ pharmacist decide
└────────┬─────────┘         └────────┬─────────┘
         │ no alerts                  │
         ▼                            ▼
┌──────────────────┐         ┌──────────────────┐
│ READY_TO_DISPENSE│         │ APPROVED/HOLD/   │
└────────┬─────────┘         │ SUB/CANCEL       │
         │                   └────────┬─────────┘
         ▼                            │ approved
┌──────────────────┐                  │
│ BARCODE_SCAN     │◄─────────────────┘
└────────┬─────────┘
         ▼ match
┌──────────────────┐
│ DISPENSED        │ label print · counsel · log
└────────┬─────────┘
         ▼
┌──────────────────┐
│ COUNSEL_COMPLETE │
└────────┬─────────┘
         ▼
┌──────────────────┐
│ CLOSED           │ → emit event for M6 monitoring
└──────────────────┘

8. 🤖 Agent Specification

M5 mostly rule-based + structured DB lookup. LLM hanya untuk: (a) generate counsel checklist explanation BM/EN, (b) explain DDI severity to patient (kalau pesakit tanya).

• Model: Llama 8B (rule-based heavy + light explanation)
• Memory: NPRA drug DB · DDI matrix (in-memory) · patient allergy registry
• Guardrails: HITL pharmacist final approve · dispense block on CONTRAINDICATED · audit per click

9. 🎨 UI/UX

Per Doc Zam mock slide 7: Prescription Queue + Verification panel.

• Filament 3 Pharmacy panel · 2-column layout
• Left: queue list (Ready · Verifying · Pending · Completed)
• Right: verification detail card · per-line item · alerts color-coded
• DDI alert: red banner · severity · alternatives card
• Halal flag: green/red icon · capsule source disclosure
• Approve/Substitute/Hold/Cancel buttons per-line
• Barcode scan input · confirmation chime
• Print Label button · counsel checklist modal
• Bottom stats: Total Today · Average Time · Pending Approvals

10. ✔️ Acceptance Criteria

• AC-5.1: 50 RX clinical safety scenarios → 100% MAJOR/CONTRA DDI detected
• AC-5.2: 30 paeds dose scenarios → 100% under/over-dose flagged
• AC-5.3: Halal flag accuracy ≥95% pada 100 sample drugs
• AC-5.4: Barcode mismatch detection 100% (10 swap test)
• AC-5.5: Generic substitution cost saving ≥20% on average
• AC-5.6: HITL pharmacist gate enforced — 0 auto-dispense on CONTRA
• AC-5.7: Label print BM/EN dual format · scannable barcode included
• AC-5.8: Adverse loop M6 trigger working — block re-dispense within 5 min
• AC-5.9: Counsel checklist completion required before close encounter
• AC-5.10: Doc Zam clinical pharmacist review 20 sample RX → ≥18 acceptable

11. 🧪 Test Plan

12. 🔗 Dependencies

• Hard: M9 (audit + HITL gate) · M4 DRPA (RX source · sign-off event)
• Soft: M6 ARXL (adverse loop) · M7 ADPA (billing trigger) · M1 PSPA (allergy intake)
• External: NPRA drug DB · NPRA halal index · Lexicomp DDI (or MIMS Malaysia) · Zebra/BPL label printer SDK · USB barcode scanner driver

13. 🏃 Sprint Allocation

14. ⚠️ Module-Specific Risks