Initial commit: NCLEX Practice Question Generator

.github/workflows/sync-to-hf.yml

@@ -0,0 +1,25 @@
+name: Sync to Hugging Face Spaces
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  sync-to-hub:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git config --global user.email "ci@github.com"
+          git config --global user.name "GitHub Actions"
+          git push \
+            https://NurseCitizenDeveloper:$HF_TOKEN@huggingface.co/spaces/NurseCitizenDeveloper/nclex-prep \
+            main --force

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.env
+.venv/
+venv/
+.DS_Store
+*.log

README.md

@@ -0,0 +1,141 @@
+---
+title: NCLEX Practice Question Generator
+emoji: 📋
+colorFrom: purple
+colorTo: indigo
+sdk: streamlit
+sdk_version: 1.32.0
+app_file: streamlit_app.py
+pinned: false
+license: mit
+---
+
+<div align="center">
+
+# 📋 NCLEX Practice Question Generator
+
+**Clinically accurate NCLEX-style questions · Full rationales · Unlimited dosage calculations**
+
+[![Hugging Face](https://img.shields.io/badge/🤗%20Hugging%20Face-Live%20Demo-blue)](https://huggingface.co/spaces/NurseCitizenDeveloper/nclex-prep)
+[![GitHub](https://img.shields.io/badge/GitHub-Clinical--Quality--AI-181717?logo=github)](https://github.com/Clinical-Quality-Artifical-Intelligence/nclex-prep)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![NCLEX: 2023 Test Plan](https://img.shields.io/badge/NCLEX-2023%20Test%20Plan-purple)](https://www.ncsbn.org/nclex-rn)
+
+*No login · No API key · No cost · Built by a nurse, for nurses*
+
+</div>
+
+---
+
+## Overview
+
+The **NCLEX Practice Question Generator** provides student nurses with high-quality, evidence-based practice questions aligned to the **2023 NCLEX-RN Test Plan** (NCSBN). Every question includes a detailed clinical rationale — teaching students not just the correct answer, but the critical thinking process behind it.
+
+Dosage calculation questions are dynamically generated, providing unlimited unique math practice so students never memorise the same problem twice.
+
+---
+
+## Features
+
+### 🎯 Practice Quiz
+- **30+ high-quality questions** across all NCLEX Client Needs categories
+- **Multiple Choice (MCQ)** — single best answer format
+- **Select All That Apply (SATA)** — the most challenging NCLEX question type
+- Filter by **category**, **difficulty**, and **question type**
+- Instant answer reveal with detailed **clinical rationale**
+
+### 💉 Dosage Calculations
+- **Dynamically generated** — unlimited unique problems, never the same set twice
+- Five question types:
+  - Oral tablet calculations
+  - IV infusion rate (mL/hr)
+  - Manual drip rate (gtt/min)
+  - Weight-based IV infusions (mcg/kg/min)
+  - Paediatric oral liquid dosing
+- Step-by-step solution shown in the rationale
+
+### 📊 Results & Performance Tracking
+- Overall score and performance band
+- **Category breakdown** — identify weak areas by NCLEX domain
+- **Difficulty breakdown** — performance across beginner / intermediate / advanced
+
+### 🔁 Wrong Answer Review
+- Every missed question available for focused review
+- NCLEX framework category shown for each question
+- Rationale emphasised to build clinical reasoning
+
+---
+
+## NCLEX Client Needs Categories Covered
+
+| Category | Sub-categories |
+|----------|---------------|
+| **Safe & Effective Care Environment** | Management of Care · Safety & Infection Control |
+| **Health Promotion & Maintenance** | Growth & Development · Preventive Care |
+| **Psychosocial Integrity** | Mental Health · Therapeutic Communication |
+| **Physiological Integrity** | Basic Care · Pharmacology · Risk Reduction · Physiological Adaptation |
+
+---
+
+## Question Types
+
+| Type | Description | NCLEX Relevance |
+|------|-------------|-----------------|
+| MCQ | Single best answer from 4 options | ~50% of NCLEX-RN |
+| SATA | Select all correct options from 5–6 | ~20% of NCLEX-RN |
+| Calculation | Dosage math with step-by-step workings | ~10% of NCLEX-RN |
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Frontend | [Streamlit](https://streamlit.io/) (Python) |
+| Question bank | Curated clinical question library (Python data structures) |
+| Calc generator | Dynamic random question generation (no LLM required) |
+| Hosting | [Hugging Face Spaces](https://huggingface.co/spaces) — free CPU tier |
+| CI/CD | GitHub Actions → auto-deploy on push |
+
+> **No API keys. No paid services. Fully open-source.**
+
+---
+
+## Local Development
+
+```bash
+git clone https://github.com/Clinical-Quality-Artifical-Intelligence/nclex-prep.git
+cd nclex-prep
+pip install -r requirements.txt
+streamlit run streamlit_app.py
+```
+
+Requirements: Python 3.10+ · `streamlit` · `requests`
+
+---
+
+## About — Nursing Citizen Development
+
+Part of the **Nursing Citizen Development** initiative — clinicians building the tools their profession needs.
+
+**Related tools:**
+- [EBP Research Tool](https://huggingface.co/spaces/NurseCitizenDeveloper/nursing-ebp-tool) — PubMed search with nursing summaries & APA citations
+- [Drug Card Generator](https://huggingface.co/spaces/NurseCitizenDeveloper/nursing-drug-cards) — Instant FDA drug reference cards
+
+---
+
+## Disclaimer
+
+For educational purposes only. Questions are designed to simulate NCLEX-style critical thinking but do not represent actual NCLEX examination items. Always study from NCSBN-approved resources and consult your nursing programme's curriculum.
+
+---
+
+## License
+
+[MIT](LICENSE) © Nursing Citizen Development / Clinical Quality Artificial Intelligence
+
+---
+
+<div align="center">
+  <sub>Built with 🩺 by <a href="https://huggingface.co/NurseCitizenDeveloper">Nursing Citizen Development</a></sub>
+</div>

questions/bank.py

@@ -0,0 +1,704 @@
+"""
+NCLEX Question Bank
+Structured by NCLEX Client Needs framework.
+Each question follows NCSBN item-writing guidelines.
+Types: mcq (single answer), sata (select all that apply), priority
+"""
+
+QUESTIONS = [
+
+    # =========================================================
+    # PHARMACOLOGICAL & PARENTERAL THERAPIES
+    # =========================================================
+    {
+        "id": "pharm_001",
+        "category": "Pharmacology",
+        "subcategory": "Cardiac Medications",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A nurse is preparing to administer digoxin 0.125 mg PO to a patient with heart failure. Before administration, the nurse assesses the apical pulse and finds it is 54 beats/min. What is the nurse's priority action?",
+        "options": [
+            "Administer the medication as ordered",
+            "Hold the medication and notify the provider",
+            "Administer half the prescribed dose",
+            "Recheck the pulse in 30 minutes before administering"
+        ],
+        "correct": 1,
+        "rationale": "Digoxin should be held if the apical pulse is below 60 bpm in an adult and the provider notified immediately. Digoxin slows heart rate and conduction — administration with an already bradycardic rate could precipitate life-threatening dysrhythmias. The nurse should NEVER alter doses without a provider order.",
+        "tags": ["digoxin", "cardiac-glycoside", "bradycardia", "medication-safety"]
+    },
+    {
+        "id": "pharm_002",
+        "category": "Pharmacology",
+        "subcategory": "Anticoagulants",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A patient is prescribed warfarin (Coumadin). Which laboratory value does the nurse use to monitor therapeutic effectiveness of this medication?",
+        "options": [
+            "Activated partial thromboplastin time (aPTT)",
+            "Complete blood count (CBC)",
+            "International normalised ratio (INR)",
+            "Serum potassium level"
+        ],
+        "correct": 2,
+        "rationale": "INR (target 2–3 for most indications, 2.5–3.5 for mechanical valves) is the standard monitoring parameter for warfarin. aPTT monitors unfractionated heparin. CBC monitors for bleeding complications but not therapeutic level. Serum potassium is unrelated to warfarin therapy.",
+        "tags": ["warfarin", "anticoagulant", "INR", "lab-monitoring"]
+    },
+    {
+        "id": "pharm_003",
+        "category": "Pharmacology",
+        "subcategory": "Beta Blockers",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "intermediate",
+        "type": "sata",
+        "stem": "A nurse is teaching a patient newly prescribed metoprolol succinate (Toprol-XL). Which instructions should the nurse include? Select all that apply.",
+        "options": [
+            "Do not stop this medication abruptly",
+            "Monitor your pulse before each dose",
+            "This medication may mask signs of hypoglycemia",
+            "Take the medication only when you feel your heart racing",
+            "Report dizziness or shortness of breath to your provider",
+            "You may double the dose if you miss one"
+        ],
+        "correct": [0, 1, 2, 4],
+        "rationale": "Correct: Abrupt discontinuation can cause rebound hypertension or angina. Daily pulse monitoring detects bradycardia. Beta-blockers blunt the tachycardia response to hypoglycemia, masking a key symptom — important for diabetic patients. Dizziness/SOB may indicate dose is too high. Incorrect: Metoprolol is a scheduled daily medication, not PRN. Doubling doses is dangerous and not indicated.",
+        "tags": ["metoprolol", "beta-blocker", "patient-education", "SATA"]
+    },
+    {
+        "id": "pharm_004",
+        "category": "Pharmacology",
+        "subcategory": "Diuretics",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A nurse is caring for a patient receiving furosemide (Lasix) 40 mg IV for acute pulmonary oedema. Which assessment finding requires immediate intervention?",
+        "options": [
+            "Urine output of 200 mL in the first hour",
+            "Serum potassium of 2.8 mEq/L",
+            "Blood pressure decreased from 160/100 to 138/86 mmHg",
+            "Mild thirst reported by the patient"
+        ],
+        "correct": 1,
+        "rationale": "A serum potassium of 2.8 mEq/L (normal 3.5–5.0 mEq/L) indicates hypokalaemia, a dangerous complication of loop diuretics. Hypokalaemia increases the risk of life-threatening dysrhythmias and potentiates digoxin toxicity. This requires immediate provider notification and potassium replacement. The other findings — diuresis, modest BP reduction, and thirst — are expected responses to furosemide.",
+        "tags": ["furosemide", "loop-diuretic", "hypokalaemia", "electrolytes"]
+    },
+    {
+        "id": "pharm_005",
+        "category": "Pharmacology",
+        "subcategory": "Opioids",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A nurse administers morphine sulphate 4 mg IV to a post-operative patient. Thirty minutes later, the patient's respiratory rate is 8 breaths/min and they are difficult to arouse. What is the nurse's first action?",
+        "options": [
+            "Administer naloxone (Narcan) as per protocol",
+            "Stimulate the patient and encourage deep breathing",
+            "Apply oxygen via non-rebreather mask",
+            "Notify the provider and document the findings"
+        ],
+        "correct": 0,
+        "rationale": "The patient is showing signs of opioid-induced respiratory depression (RR < 12, difficult to arouse). The priority action is reversal with naloxone, an opioid antagonist. While stimulation and oxygen are supportive measures, they do not address the underlying cause. Naloxone rapidly reverses opioid effects. Provider notification occurs concurrently but is not the first action.",
+        "tags": ["morphine", "opioid", "respiratory-depression", "naloxone", "emergency"]
+    },
+    {
+        "id": "pharm_006",
+        "category": "Pharmacology",
+        "subcategory": "Antidiabetics",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A nurse is preparing to administer insulin lispro (Humalog) to a patient before breakfast. The patient's blood glucose is 68 mg/dL. What is the nurse's priority action?",
+        "options": [
+            "Administer the insulin as scheduled",
+            "Hold the insulin and provide a carbohydrate snack",
+            "Administer half the prescribed insulin dose",
+            "Recheck the blood glucose in 15 minutes before deciding"
+        ],
+        "correct": 1,
+        "rationale": "A blood glucose of 68 mg/dL is below the normal fasting range (70–100 mg/dL) and indicates hypoglycaemia. Administering insulin would drive the glucose further down, potentially causing a severe hypoglycaemic event. The nurse must hold the rapid-acting insulin, treat the hypoglycaemia with 15g of fast-acting carbohydrates, recheck in 15 minutes, and notify the provider. Never alter insulin doses without an order.",
+        "tags": ["insulin", "hypoglycaemia", "blood-glucose", "medication-safety"]
+    },
+    {
+        "id": "pharm_007",
+        "category": "Pharmacology",
+        "subcategory": "Antibiotics",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A patient is receiving vancomycin 1g IV q12h for MRSA bacteraemia. The nurse notes the patient's serum creatinine has risen from 0.9 to 2.1 mg/dL over 48 hours. Which action is most appropriate?",
+        "options": [
+            "Continue the current dose — creatinine fluctuations are normal",
+            "Increase the dosing interval and notify the provider",
+            "Hold the vancomycin and notify the provider",
+            "Switch to an oral antibiotic per facility protocol"
+        ],
+        "correct": 2,
+        "rationale": "A rise in creatinine from 0.9 to 2.1 mg/dL represents a >50% increase, suggesting vancomycin-induced nephrotoxicity. The nurse should hold the dose and immediately notify the provider. Vancomycin is renally cleared — continued dosing without adjustment in renal impairment leads to toxic drug accumulation. Switching antibiotics requires a provider order and is not the nurse's first action.",
+        "tags": ["vancomycin", "nephrotoxicity", "renal-function", "MRSA"]
+    },
+    {
+        "id": "pharm_008",
+        "category": "Pharmacology",
+        "subcategory": "Corticosteroids",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "intermediate",
+        "type": "sata",
+        "stem": "A nurse is caring for a patient on long-term prednisone therapy. Which nursing assessments are priorities? Select all that apply.",
+        "options": [
+            "Blood glucose levels",
+            "Signs and symptoms of infection",
+            "Blood pressure and fluid status",
+            "Serum sodium levels for hyponatraemia",
+            "Bone density and fall risk",
+            "Urine output for polyuria"
+        ],
+        "correct": [0, 1, 2, 4],
+        "rationale": "Correct: Prednisone causes hyperglycaemia (monitor glucose), immunosuppression (increases infection risk), fluid retention and hypertension (monitor BP/fluid status), and bone loss with long-term use (osteoporosis risk). Incorrect: Corticosteroids cause sodium retention (hypernatraemia risk, not hyponatraemia) and polyuria is more associated with diabetes insipidus, not corticosteroid use.",
+        "tags": ["prednisone", "corticosteroid", "long-term", "side-effects", "SATA"]
+    },
+
+    # =========================================================
+    # SAFETY AND INFECTION CONTROL
+    # =========================================================
+    {
+        "id": "safety_001",
+        "category": "Safety & Infection Control",
+        "subcategory": "Medication Safety",
+        "nclex_framework": "Safety and Infection Control",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "The nurse is preparing to administer medications. Which action best reflects the standard of safe medication administration?",
+        "options": [
+            "Prepare all patients' medications together to save time",
+            "Verify the patient's name verbally without checking the armband",
+            "Compare the medication administration record against the original order at the bedside",
+            "Administer a medication that the patient identifies as their usual tablet"
+        ],
+        "correct": 2,
+        "rationale": "Comparing the MAR against the original order at the bedside is part of the 10 Rights of Medication Administration and represents best practice. Preparing multiple patients' medications together risks mix-ups. Verbal identification alone is insufficient — two identifiers and armband checking are required. Patient identification of a tablet is unreliable and does not satisfy safety standards.",
+        "tags": ["medication-safety", "10-rights", "administration"]
+    },
+    {
+        "id": "safety_002",
+        "category": "Safety & Infection Control",
+        "subcategory": "Infection Control",
+        "nclex_framework": "Safety and Infection Control",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A patient is admitted with confirmed Clostridioides difficile (C. diff) infection. Which personal protective equipment (PPE) should the nurse don before entering the room?",
+        "options": [
+            "Surgical mask and gloves",
+            "N95 respirator, gown, and gloves",
+            "Gown and gloves",
+            "Gloves only — alcohol hand gel is sufficient after removal"
+        ],
+        "correct": 2,
+        "rationale": "C. difficile requires Contact Precautions: gown and gloves. An N95 is not required as C. diff is not airborne. Crucially, alcohol-based hand sanitiser is INEFFECTIVE against C. diff spores — soap and water (friction) is required for hand hygiene. Gloves alone do not protect clothing/skin sufficiently.",
+        "tags": ["C-diff", "contact-precautions", "PPE", "infection-control"]
+    },
+    {
+        "id": "safety_003",
+        "category": "Safety & Infection Control",
+        "subcategory": "Fall Prevention",
+        "nclex_framework": "Safety and Infection Control",
+        "difficulty": "beginner",
+        "type": "sata",
+        "stem": "A nurse completes a fall risk assessment and identifies a patient as high risk for falls. Which interventions should the nurse implement? Select all that apply.",
+        "options": [
+            "Apply a yellow fall-risk armband",
+            "Ensure the call light is within reach at all times",
+            "Keep all four side rails raised at all times",
+            "Place a fall-risk sign on the patient's door",
+            "Educate the patient and family about fall prevention",
+            "Offer toileting every 2 hours"
+        ],
+        "correct": [0, 1, 3, 4, 5],
+        "rationale": "Correct: Armband, signage, call light access, patient/family education, and scheduled toileting are all evidence-based fall prevention strategies. Incorrect: Keeping all four side rails raised constitutes a restraint and is not standard fall prevention — it may cause the patient to climb over rails, increasing injury risk. Two rails may be raised for positioning support per facility policy.",
+        "tags": ["fall-prevention", "safety", "high-risk", "SATA"]
+    },
+    {
+        "id": "safety_004",
+        "category": "Safety & Infection Control",
+        "subcategory": "Airborne Precautions",
+        "nclex_framework": "Safety and Infection Control",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A patient is admitted with suspected active pulmonary tuberculosis (TB). Which precautions should the nurse implement?",
+        "options": [
+            "Contact precautions: gown and gloves in a private room",
+            "Droplet precautions: surgical mask within 3 feet of patient",
+            "Airborne precautions: N95 respirator in a negative pressure room",
+            "Standard precautions only until diagnosis is confirmed"
+        ],
+        "correct": 2,
+        "rationale": "Active pulmonary TB requires Airborne Precautions: N95 respirator (fit-tested), placement in a negative-pressure room, and door kept closed. TB is transmitted via airborne droplet nuclei <5 microns that remain suspended in air. A surgical mask does not filter particles this small. Standard precautions alone are insufficient given the high transmission risk.",
+        "tags": ["tuberculosis", "airborne-precautions", "N95", "negative-pressure"]
+    },
+
+    # =========================================================
+    # MANAGEMENT OF CARE / LEADERSHIP
+    # =========================================================
+    {
+        "id": "mgmt_001",
+        "category": "Leadership & Management",
+        "subcategory": "Delegation",
+        "nclex_framework": "Management of Care",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A registered nurse (RN) is delegating tasks to a nursing assistant (NA). Which task is appropriate for the RN to delegate?",
+        "options": [
+            "Performing an admission assessment on a new patient",
+            "Educating a patient about a new diabetes diagnosis",
+            "Measuring and recording intake and output for a stable patient",
+            "Administering a prescribed oral pain medication"
+        ],
+        "correct": 2,
+        "rationale": "Measuring and recording I&O for a stable patient is within the NA's scope of practice and is an appropriate delegation. Assessment, patient education, and medication administration are within the RN's scope and cannot be delegated to an NA. The RN must use the NCSBN delegation framework: Right Task, Right Circumstance, Right Person, Right Direction, Right Supervision.",
+        "tags": ["delegation", "NA", "scope-of-practice", "management"]
+    },
+    {
+        "id": "mgmt_002",
+        "category": "Leadership & Management",
+        "subcategory": "Priority Setting",
+        "nclex_framework": "Management of Care",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A nurse is assigned four patients. Using priority principles, which patient should the nurse assess first?",
+        "options": [
+            "A patient with COPD reporting SOB rated 4/10, O₂ sat 94% on 2L NC",
+            "A post-op patient 4 hours after hip replacement requesting pain medication",
+            "A patient with heart failure whose urine output was 20 mL over the past 2 hours",
+            "A diabetic patient whose breakfast blood glucose was 210 mg/dL"
+        ],
+        "correct": 2,
+        "rationale": "The patient with heart failure producing only 20 mL urine in 2 hours has oliguria (< 30 mL/hr is critical) — this may indicate worsening cardiac output, acute kidney injury, or haemodynamic compromise requiring immediate assessment. The COPD patient with 94% sat on 2L is stable but requires monitoring. The post-op patient's pain is a priority but not life-threatening. The elevated glucose of 210 mg/dL requires intervention but is not immediately life-threatening.",
+        "tags": ["priority-setting", "ABC", "Maslow", "oliguria", "heart-failure"]
+    },
+    {
+        "id": "mgmt_003",
+        "category": "Leadership & Management",
+        "subcategory": "Advocacy",
+        "nclex_framework": "Management of Care",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A patient tells the nurse they do not understand why they are having surgery tomorrow and feel pressured to sign the consent form. What is the nurse's priority action?",
+        "options": [
+            "Explain the surgical procedure to the patient in detail",
+            "Reassure the patient that the surgeon is highly experienced",
+            "Notify the surgeon that the patient requires further explanation before signing",
+            "Witness the consent signature, as the surgeon has already explained the procedure"
+        ],
+        "correct": 2,
+        "rationale": "Informed consent requires that the patient understands the procedure, risks, benefits, and alternatives — this is the surgeon's legal and ethical responsibility. The nurse's role is patient advocacy: if the patient does not understand or feels coerced, the nurse must notify the surgeon to provide further explanation before consent is obtained. Witnessing a consent that has not been properly informed is unethical and potentially illegal.",
+        "tags": ["informed-consent", "advocacy", "patient-rights", "ethics"]
+    },
+    {
+        "id": "mgmt_004",
+        "category": "Leadership & Management",
+        "subcategory": "SBAR Communication",
+        "nclex_framework": "Management of Care",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A nurse uses SBAR to communicate a change in a patient's condition to the provider. Which component of SBAR includes the nurse's clinical interpretation of the problem?",
+        "options": [
+            "Situation",
+            "Background",
+            "Assessment",
+            "Recommendation"
+        ],
+        "correct": 2,
+        "rationale": "Assessment in SBAR is where the nurse communicates their clinical interpretation of what is happening with the patient (e.g., 'I think the patient may be developing sepsis'). Situation describes what is happening now. Background provides relevant history. Recommendation states what the nurse believes is needed.",
+        "tags": ["SBAR", "communication", "handoff", "clinical-judgement"]
+    },
+
+    # =========================================================
+    # PHYSIOLOGICAL ADAPTATION / MED-SURG
+    # =========================================================
+    {
+        "id": "medsurg_001",
+        "category": "Medical-Surgical",
+        "subcategory": "Cardiac",
+        "nclex_framework": "Physiological Adaptation",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A nurse is caring for a patient who suddenly develops chest pain, diaphoresis, and ST-segment elevation on the monitor. After calling for help, what is the nurse's next priority action?",
+        "options": [
+            "Administer oxygen at 4L via nasal cannula",
+            "Obtain a 12-lead ECG",
+            "Start a second IV line",
+            "Prepare the patient for immediate coronary angiography"
+        ],
+        "correct": 1,
+        "rationale": "Obtaining a 12-lead ECG is the priority — it provides definitive data to confirm STEMI, guide treatment decisions, and establish a baseline time (door-to-balloon time targets <90 minutes). Oxygen is only indicated if SpO₂ < 90% — routine high-flow oxygen in STEMI can be harmful. IV access and cath lab preparation are important but follow ECG confirmation per the ACLS STEMI algorithm.",
+        "tags": ["STEMI", "chest-pain", "ECG", "cardiac-emergency", "ACLS"]
+    },
+    {
+        "id": "medsurg_002",
+        "category": "Medical-Surgical",
+        "subcategory": "Respiratory",
+        "nclex_framework": "Physiological Adaptation",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A patient with COPD is receiving 4L O₂ via nasal cannula. The nurse notes the patient is increasingly somnolent with a respiratory rate of 8/min. What is the most likely cause?",
+        "options": [
+            "Oxygen toxicity causing lung damage",
+            "Hypercapnia from suppressed hypoxic drive",
+            "CO₂ narcosis from excessive oxygen",
+            "Both B and C are correct"
+        ],
+        "correct": 3,
+        "rationale": "In COPD patients who are chronic CO₂ retainers, the primary respiratory drive shifts to hypoxia (hypoxic drive). High-flow oxygen removes this drive, leading to respiratory depression, CO₂ retention (hypercapnia), and eventually CO₂ narcosis — a state of somnolence and CNS depression. Both B and C describe the same pathophysiological process. Target SpO₂ in COPD is typically 88–92%.",
+        "tags": ["COPD", "hypoxic-drive", "O2-therapy", "hypercapnia", "CO2-narcosis"]
+    },
+    {
+        "id": "medsurg_003",
+        "category": "Medical-Surgical",
+        "subcategory": "Fluid & Electrolytes",
+        "nclex_framework": "Physiological Adaptation",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A patient's serum sodium is 122 mEq/L. The nurse anticipates which clinical manifestation?",
+        "options": [
+            "Dry mucous membranes and intense thirst",
+            "Peaked T waves on ECG",
+            "Confusion and seizure risk",
+            "Kussmaul breathing"
+        ],
+        "correct": 2,
+        "rationale": "Severe hyponatraemia (Na < 125 mEq/L) causes cerebral oedema as water shifts into brain cells, leading to neurological manifestations: confusion, headache, lethargy, and seizure risk. Dry mucous membranes/thirst indicate hypernatraemia. Peaked T waves indicate hyperkalaemia. Kussmaul breathing indicates metabolic acidosis.",
+        "tags": ["hyponatraemia", "electrolytes", "neuro-manifestations", "sodium"]
+    },
+    {
+        "id": "medsurg_004",
+        "category": "Medical-Surgical",
+        "subcategory": "Post-operative Care",
+        "nclex_framework": "Reduction of Risk Potential",
+        "difficulty": "intermediate",
+        "type": "sata",
+        "stem": "A nurse is caring for a patient 6 hours post-abdominal surgery. Which findings require immediate intervention? Select all that apply.",
+        "options": [
+            "Blood pressure 88/54 mmHg, HR 118 bpm",
+            "Urine output 25 mL over the past hour",
+            "Patient rates pain as 6/10",
+            "Temperature 38.9°C (102°F)",
+            "Wound dressing with a 2 cm bloodstain unchanged from 1 hour ago",
+            "Absent bowel sounds"
+        ],
+        "correct": [0, 1, 3],
+        "rationale": "Immediate: BP 88/54 with HR 118 suggests haemodynamic instability/hypovolaemic shock. Urine output of 25 mL/hr indicates oliguria (<30 mL/hr) suggesting inadequate perfusion. Temp 38.9°C suggests early infection or systemic response. Not immediate: Pain 6/10 needs management but is not immediately life-threatening. A small stable bloodstain indicates the bleed is not active/expanding. Absent bowel sounds are expected in the first 24–72 hours post-abdominal surgery (post-op ileus).",
+        "tags": ["post-operative", "haemodynamic", "oliguria", "SATA", "shock"]
+    },
+    {
+        "id": "medsurg_005",
+        "category": "Medical-Surgical",
+        "subcategory": "Neurological",
+        "nclex_framework": "Physiological Adaptation",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A patient with a closed head injury has a GCS score that has dropped from 14 to 9 over 2 hours. The nurse notes Cushing's triad: hypertension, bradycardia, and irregular respirations. What does this indicate?",
+        "options": [
+            "Neurogenic shock developing",
+            "Increased intracranial pressure with brain herniation",
+            "Expected improvement in level of consciousness",
+            "Autonomic dysreflexia from a spinal injury"
+        ],
+        "correct": 1,
+        "rationale": "Cushing's triad (hypertension, bradycardia, irregular/Cheyne-Stokes respirations) is a late, ominous sign of severely increased intracranial pressure (ICP) and impending brain herniation. The falling GCS confirms deteriorating neurological status. This is a neurological emergency requiring immediate provider notification and intervention (head of bed 30°, hyperventilation, mannitol, possible surgical decompression). Neurogenic shock causes hypotension, not hypertension.",
+        "tags": ["ICP", "Cushing-triad", "brain-herniation", "GCS", "neurological-emergency"]
+    },
+
+    # =========================================================
+    # MENTAL HEALTH
+    # =========================================================
+    {
+        "id": "mh_001",
+        "category": "Mental Health",
+        "subcategory": "Therapeutic Communication",
+        "nclex_framework": "Psychosocial Integrity",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A patient with depression tells the nurse, 'There's no point in anything anymore. I don't see why I bother.' Which response by the nurse is most therapeutic?",
+        "options": [
+            "'I'm sure things will get better soon.'",
+            "'You sound like you're feeling hopeless. Can you tell me more about what you mean?'",
+            "'Everyone feels that way sometimes — you just need to stay positive.'",
+            "'Have you thought about joining our group therapy sessions?'"
+        ],
+        "correct": 1,
+        "rationale": "Reflecting the patient's feelings and using an open-ended question demonstrates active listening, validates the patient's experience, and invites further communication. This therapeutic response may also allow the nurse to assess for suicidal ideation. The other responses use false reassurance ('things will get better'), minimisation ('everyone feels that way'), or redirect conversation before the patient feels heard — all non-therapeutic techniques.",
+        "tags": ["therapeutic-communication", "depression", "open-ended", "active-listening"]
+    },
+    {
+        "id": "mh_002",
+        "category": "Mental Health",
+        "subcategory": "Suicide Risk",
+        "nclex_framework": "Psychosocial Integrity",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A patient tells the nurse, 'I've decided to give all my belongings away. I feel very peaceful now.' The nurse recognises this as which warning sign?",
+        "options": [
+            "Improved coping and acceptance of illness",
+            "Possible completion of a suicide plan and calm before lethal action",
+            "Spiritual growth and acceptance of mortality",
+            "A positive sign indicating therapeutic progress"
+        ],
+        "correct": 1,
+        "rationale": "Giving away possessions and a sudden sense of calm or peace in a previously depressed/suicidal patient is a critical warning sign — it may indicate the patient has made a decision to act and has resolved the ambivalence around suicide. The calm may reflect relief that a plan has been made. This requires immediate safety assessment (ask directly about suicidal ideation/plan/intent/means) and escalation. This is NOT a sign of improvement.",
+        "tags": ["suicide-risk", "warning-signs", "safety-assessment", "crisis"]
+    },
+    {
+        "id": "mh_003",
+        "category": "Mental Health",
+        "subcategory": "Antipsychotic Medications",
+        "nclex_framework": "Pharmacological and Parenteral Therapies",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A patient on haloperidol (Haldol) develops sudden severe muscle rigidity, high fever (40.1°C), diaphoresis, and altered mental status. The nurse suspects which complication?",
+        "options": [
+            "Tardive dyskinesia",
+            "Serotonin syndrome",
+            "Neuroleptic malignant syndrome (NMS)",
+            "Acute dystonia"
+        ],
+        "correct": 2,
+        "rationale": "Neuroleptic Malignant Syndrome (NMS) is a rare but life-threatening reaction to antipsychotics. The classic tetrad is: hyperthermia, severe muscle rigidity, autonomic instability (diaphoresis, tachycardia), and altered consciousness. Treatment: stop the antipsychotic immediately, supportive care, dantrolene. Tardive dyskinesia involves involuntary movements after long-term use. Serotonin syndrome involves serotonergic agents. Acute dystonia involves muscle spasms, not systemic crisis.",
+        "tags": ["NMS", "haloperidol", "antipsychotic", "emergency", "hyperthermia"]
+    },
+
+    # =========================================================
+    # MATERNAL / NEWBORN
+    # =========================================================
+    {
+        "id": "ob_001",
+        "category": "Maternal / Newborn",
+        "subcategory": "Labour & Delivery",
+        "nclex_framework": "Physiological Adaptation",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A nurse monitoring a patient in labour notes a late deceleration pattern on the fetal monitor. What is the nurse's immediate action?",
+        "options": [
+            "Increase the oxytocin infusion rate",
+            "Reposition the patient to left lateral position and apply oxygen",
+            "Prepare for immediate caesarean section",
+            "Document the finding and continue monitoring"
+        ],
+        "correct": 1,
+        "rationale": "Late decelerations indicate uteroplacental insufficiency and potential fetal hypoxia. Immediate nursing actions: reposition to left lateral (relieve aorto-caval compression, improving placental perfusion), apply O₂ via face mask (8–10 L), stop oxytocin if infusing, increase IV fluids, and notify the provider. Increasing oxytocin would worsen contractions and deepen the deceleration. C-section may be needed but is a provider decision, not the nurse's first action.",
+        "tags": ["fetal-monitoring", "late-deceleration", "uteroplacental", "labour", "priority"]
+    },
+    {
+        "id": "ob_002",
+        "category": "Maternal / Newborn",
+        "subcategory": "Post-partum",
+        "nclex_framework": "Reduction of Risk Potential",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A nurse assesses a patient 1 hour post-vaginal delivery. The fundus is displaced to the right of the midline and the patient has saturated a perineal pad in 30 minutes. What is the priority intervention?",
+        "options": [
+            "Administer oxytocin as prescribed",
+            "Assist the patient to urinate or insert a urinary catheter",
+            "Perform uterine fundal massage",
+            "Notify the provider of haemorrhage"
+        ],
+        "correct": 1,
+        "rationale": "A fundus deviated to the right and a full bladder (the most common cause of uterine displacement) inhibits uterine contraction and causes post-partum haemorrhage. The first intervention is to empty the bladder — this allows the uterus to contract and descend to the midline. Fundal massage is appropriate for a boggy uterus at midline; massaging a displaced uterus without first emptying the bladder is ineffective. Oxytocin and provider notification follow if haemorrhage continues after bladder emptying.",
+        "tags": ["post-partum-haemorrhage", "uterine-atony", "bladder-displacement", "fundus"]
+    },
+
+    # =========================================================
+    # PAEDIATRICS
+    # =========================================================
+    {
+        "id": "peds_001",
+        "category": "Paediatrics",
+        "subcategory": "Respiratory",
+        "nclex_framework": "Physiological Adaptation",
+        "difficulty": "advanced",
+        "type": "mcq",
+        "stem": "A 2-year-old presents with sudden onset of high-pitched inspiratory stridor, drooling, tripod positioning, and refusal to lie down. The child is afebrile and has no cough. What condition does the nurse suspect and what is the priority action?",
+        "options": [
+            "Croup — prepare a cool mist tent and administer nebulised racemic epinephrine",
+            "Epiglottitis — do not examine the throat; notify the provider and keep child calm",
+            "Asthma — administer albuterol nebulisation immediately",
+            "Foreign body aspiration — prepare for emergency Heimlich manoeuvre"
+        ],
+        "correct": 1,
+        "rationale": "The presentation — sudden stridor, drooling, tripod positioning, refusal to lie flat, and absence of cough — is classic for epiglottitis, a life-threatening emergency. NEVER attempt to visualise the throat (can trigger complete obstruction). Keep the child calm and in the position of comfort (sitting upright). Notify the provider/anaesthesia immediately — the airway may need emergency intubation. Croup presents with a barking cough, gradual onset, and low-grade fever. Epiglottitis is now less common due to Hib vaccine.",
+        "tags": ["epiglottitis", "stridor", "paediatric-emergency", "airway", "priority"]
+    },
+    {
+        "id": "peds_002",
+        "category": "Paediatrics",
+        "subcategory": "Growth & Development",
+        "nclex_framework": "Health Promotion and Maintenance",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A parent asks the nurse when their child should walk independently. Which milestone response is developmentally appropriate?",
+        "options": [
+            "6–8 months",
+            "9–11 months",
+            "12–15 months",
+            "18–24 months"
+        ],
+        "correct": 2,
+        "rationale": "Independent walking typically occurs between 12–15 months of age. The range is 9–15 months (some sources extend to 18 months). Walking before 9 months is unusual. Not walking by 18 months warrants further developmental evaluation. Understanding developmental milestones helps the nurse provide accurate anticipatory guidance and identify delays early.",
+        "tags": ["developmental-milestones", "walking", "paediatric", "health-promotion"]
+    },
+
+    # =========================================================
+    # HEALTH PROMOTION / FUNDAMENTALS
+    # =========================================================
+    {
+        "id": "fund_001",
+        "category": "Fundamentals",
+        "subcategory": "Wound Care",
+        "nclex_framework": "Basic Care and Comfort",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A nurse is assessing a patient's pressure injury and notes a shallow open ulcer with a red-pink wound bed and no slough. There is no tunnelling or undermining. How should this wound be staged?",
+        "options": [
+            "Stage I",
+            "Stage II",
+            "Stage III",
+            "Stage IV"
+        ],
+        "correct": 1,
+        "rationale": "A Stage II pressure injury presents as a shallow open ulcer with a red-pink wound bed, without slough or eschar — the dermis is partially exposed. Stage I is intact skin with non-blanchable redness. Stage III involves full-thickness tissue loss (subcutaneous tissue visible). Stage IV involves exposed muscle, tendon, or bone. Accurate staging guides dressing selection and care planning.",
+        "tags": ["pressure-injury", "wound-staging", "NPUAP", "wound-care"]
+    },
+    {
+        "id": "fund_002",
+        "category": "Fundamentals",
+        "subcategory": "Vital Signs",
+        "nclex_framework": "Basic Care and Comfort",
+        "difficulty": "beginner",
+        "type": "mcq",
+        "stem": "A nurse obtains the following vital signs on an adult patient: BP 94/60, HR 122, RR 24, Temp 38.9°C, SpO₂ 96%. Which finding requires the nurse's most immediate attention?",
+        "options": [
+            "Temperature 38.9°C",
+            "SpO₂ 96%",
+            "BP 94/60 with HR 122",
+            "Respiratory rate 24"
+        ],
+        "correct": 2,
+        "rationale": "BP 94/60 with compensatory tachycardia (HR 122) represents haemodynamic instability — potential shock. This combination is the most immediately life-threatening finding as it indicates inadequate tissue perfusion. Using the ABCs/Maslow framework: circulation is compromised. Temperature of 38.9°C combined with tachycardia and hypotension suggests sepsis — a medical emergency. SpO₂ 96% is acceptable. RR 24 is elevated but manageable.",
+        "tags": ["vital-signs", "hypotension", "shock", "sepsis", "priority"]
+    },
+    {
+        "id": "fund_003",
+        "category": "Fundamentals",
+        "subcategory": "NG Tube",
+        "nclex_framework": "Basic Care and Comfort",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A nurse is verifying placement of a nasogastric tube before administering a feeding. Which method is most reliable for confirming tube placement?",
+        "options": [
+            "Auscultating for a 'whoosh' sound when injecting 20 mL of air",
+            "Observing for bubbling when the tube end is submerged in water",
+            "Measuring the pH of aspirated fluid (pH ≤ 5)",
+            "Confirming placement by X-ray"
+        ],
+        "correct": 3,
+        "rationale": "X-ray is the gold standard for confirming NG tube placement, especially for initial placement and when placement is uncertain. pH testing of aspirate (pH ≤ 5.5 suggests gastric placement) is acceptable for ongoing verification per some guidelines. The auscultation method ('whoosh' test) and water submersion are unreliable and no longer recommended by NPSG. Only X-ray provides definitive confirmation of tube position.",
+        "tags": ["NG-tube", "tube-placement", "enteral-feeding", "patient-safety"]
+    },
+    {
+        "id": "fund_004",
+        "category": "Fundamentals",
+        "subcategory": "Hand Hygiene",
+        "nclex_framework": "Safety and Infection Control",
+        "difficulty": "beginner",
+        "type": "sata",
+        "stem": "According to the WHO 'Five Moments for Hand Hygiene', the nurse must perform hand hygiene in which situations? Select all that apply.",
+        "options": [
+            "Before touching a patient",
+            "Before a clean or aseptic procedure",
+            "After body fluid exposure risk",
+            "After touching a patient",
+            "After touching patient surroundings",
+            "Before entering the hospital building"
+        ],
+        "correct": [0, 1, 2, 3, 4],
+        "rationale": "The WHO Five Moments for Hand Hygiene are: (1) Before patient contact, (2) Before a clean/aseptic procedure, (3) After body fluid exposure risk, (4) After patient contact, (5) After contact with patient surroundings. Entering the building is not one of the five moments. Hand hygiene at these five points breaks the chain of infection transmission.",
+        "tags": ["hand-hygiene", "WHO-5-moments", "infection-control", "SATA"]
+    },
+
+    # =========================================================
+    # REDUCTION OF RISK POTENTIAL
+    # =========================================================
+    {
+        "id": "risk_001",
+        "category": "Reduction of Risk Potential",
+        "subcategory": "Lab Values",
+        "nclex_framework": "Reduction of Risk Potential",
+        "difficulty": "intermediate",
+        "type": "mcq",
+        "stem": "A patient receiving heparin infusion has an aPTT result of 180 seconds (therapeutic range 60–100 seconds). What is the nurse's priority action?",
+        "options": [
+            "Continue the infusion and recheck in 6 hours",
+            "Reduce the infusion rate by 25% per protocol",
+            "Stop the heparin infusion and notify the provider",
+            "Administer protamine sulphate immediately"
+        ],
+        "correct": 2,
+        "rationale": "An aPTT of 180 seconds is nearly double the upper therapeutic limit (100 seconds), indicating supratherapeutic anticoagulation and significantly elevated bleeding risk. The nurse should stop the infusion and immediately notify the provider. Protamine sulphate (heparin reversal agent) is administered by provider order if active bleeding is present or clinically indicated — the nurse does not administer it without an order. Protocol-based rate reduction applies within therapeutic ranges, not in supratherapeutic situations.",
+        "tags": ["heparin", "aPTT", "supratherapeutic", "anticoagulant", "bleeding-risk"]
+    },
+    {
+        "id": "risk_002",
+        "category": "Reduction of Risk Potential",
+        "subcategory": "DVT Prevention",
+        "nclex_framework": "Reduction of Risk Potential",
+        "difficulty": "beginner",
+        "type": "sata",
+        "stem": "A nurse is planning care for a patient recovering from total knee replacement surgery. Which interventions reduce the risk of deep vein thrombosis (DVT)? Select all that apply.",
+        "options": [
+            "Apply sequential compression devices (SCDs) when patient is in bed",
+            "Encourage early ambulation as prescribed",
+            "Administer prescribed anticoagulant therapy",
+            "Keep the patient on strict bed rest for 72 hours",
+            "Encourage adequate hydration",
+            "Perform calf massage to promote circulation"
+        ],
+        "correct": [0, 1, 2, 4],
+        "rationale": "Correct: SCDs promote venous return, early ambulation prevents venous stasis, anticoagulants (e.g., enoxaparin) prevent clot formation, and hydration prevents haemoconcentration. Incorrect: Strict bed rest promotes venous stasis and increases DVT risk. Calf massage is CONTRAINDICATED if DVT is suspected — it can dislodge a clot, causing pulmonary embolism.",
+        "tags": ["DVT", "post-operative", "SCDs", "anticoagulation", "SATA"]
+    },
+]
+
+
+def get_all() -> list[dict]:
+    return QUESTIONS
+
+
+def get_by_category(category: str) -> list[dict]:
+    return [q for q in QUESTIONS if q["category"] == category]
+
+
+def get_by_difficulty(difficulty: str) -> list[dict]:
+    return [q for q in QUESTIONS if q["difficulty"] == difficulty]
+
+
+def get_by_type(qtype: str) -> list[dict]:
+    return [q for q in QUESTIONS if q["type"] == qtype]
+
+
+def get_categories() -> list[str]:
+    return sorted(set(q["category"] for q in QUESTIONS))
+
+
+def filter_questions(
+    categories: list[str] | None = None,
+    difficulty: str | None = None,
+    qtype: str | None = None,
+) -> list[dict]:
+    qs = QUESTIONS
+    if categories:
+        qs = [q for q in qs if q["category"] in categories]
+    if difficulty and difficulty != "Any":
+        qs = [q for q in qs if q["difficulty"] == difficulty]
+    if qtype and qtype != "Any":
+        qs = [q for q in qs if q["type"] == qtype]
+    return qs

questions/calculations.py

@@ -0,0 +1,254 @@
+"""
+Dynamic dosage calculation question generator.
+Generates unlimited unique, clinically accurate dosage math problems.
+"""
+
+import random
+
+
+# ---------------------------------------------------------------------------
+# Question templates — (stem_template, unit, solve_fn, distractor_fn)
+# ---------------------------------------------------------------------------
+
+def _round2(n: float) -> float:
+    return round(n, 2)
+
+def _round1(n: float) -> float:
+    return round(n, 1)
+
+
+def gen_oral_tablets() -> dict:
+    """Dose on hand / tablet dose → tablets to give."""
+    drug      = random.choice(["metoprolol", "lisinopril", "metformin", "atorvastatin", "furosemide"])
+    tablet_mg = random.choice([25, 50, 100, 125, 250, 500])
+    tablets   = random.choice([0.5, 1, 1.5, 2, 2.5, 3])
+    ordered   = _round1(tablet_mg * tablets)
+
+    correct = tablets
+    distractors = [
+        _round2(tablet_mg / ordered) if ordered != 0 else 2,
+        _round2(ordered / tablet_mg * 2),
+        _round2(ordered * tablet_mg / 100),
+    ]
+    distractors = [d for d in distractors if d != correct][:3]
+
+    options, correct_idx = _build_options(correct, distractors, unit="tablet(s)")
+
+    return {
+        "id":        f"calc_tablet_{random.randint(1000,9999)}",
+        "category":  "Dosage Calculations",
+        "subcategory": "Oral Medications",
+        "difficulty": "beginner",
+        "type":      "calculation",
+        "stem": (
+            f"A provider orders {drug} {ordered} mg PO daily. "
+            f"The medication is available as {tablet_mg} mg tablets. "
+            f"How many tablets should the nurse administer?"
+        ),
+        "options":   options,
+        "correct":   correct_idx,
+        "rationale": (
+            f"Formula: (Ordered dose ÷ Dose on hand) × Quantity\n"
+            f"= ({ordered} mg ÷ {tablet_mg} mg) × 1 tablet\n"
+            f"= **{correct} tablet(s)**"
+        ),
+        "tags": ["oral", "tablets", "calculation"],
+    }
+
+
+def gen_weight_based_iv() -> dict:
+    """Weight-based IV infusion: mg/kg → mL/hr."""
+    drug    = random.choice(["dopamine", "norepinephrine", "heparin", "amiodarone"])
+    weight  = random.choice(range(50, 101, 5))         # 50–100 kg
+    dose_mcg_kg_min = random.choice([2, 3, 5, 7, 10])  # mcg/kg/min
+    conc_mg_per_ml  = random.choice([1.6, 3.2, 4.0])   # mg/mL standard concentrations
+
+    # Convert: (mcg/kg/min × kg × 60 min) / (conc in mcg/mL) = mL/hr
+    conc_mcg_per_ml = conc_mg_per_ml * 1000
+    rate = _round1((dose_mcg_kg_min * weight * 60) / conc_mcg_per_ml)
+
+    distractors = [
+        _round1(rate * 2),
+        _round1(rate / 2),
+        _round1(dose_mcg_kg_min * weight * conc_mg_per_ml / 60),
+    ]
+    distractors = [d for d in distractors if d != rate][:3]
+    options, correct_idx = _build_options(rate, distractors, unit="mL/hr")
+
+    return {
+        "id":        f"calc_iv_{random.randint(1000,9999)}",
+        "category":  "Dosage Calculations",
+        "subcategory": "IV Infusions",
+        "difficulty": "advanced",
+        "type":      "calculation",
+        "stem": (
+            f"A patient weighing {weight} kg requires {drug} at "
+            f"{dose_mcg_kg_min} mcg/kg/min. The available solution is "
+            f"{conc_mg_per_ml} mg/mL. At what rate (mL/hr) should the nurse set the infusion pump?"
+        ),
+        "options":   options,
+        "correct":   correct_idx,
+        "rationale": (
+            f"Step 1 — Convert concentration: {conc_mg_per_ml} mg/mL × 1000 = {conc_mcg_per_ml} mcg/mL\n"
+            f"Step 2 — Calculate dose/hr: {dose_mcg_kg_min} mcg/kg/min × {weight} kg × 60 min = "
+            f"{dose_mcg_kg_min * weight * 60} mcg/hr\n"
+            f"Step 3 — Calculate rate: {dose_mcg_kg_min * weight * 60} mcg/hr ÷ {conc_mcg_per_ml} mcg/mL\n"
+            f"= **{rate} mL/hr**"
+        ),
+        "tags": ["IV", "weight-based", "infusion-rate", "calculation"],
+    }
+
+
+def gen_iv_drip_rate() -> dict:
+    """Simple IV drip: volume / time → mL/hr."""
+    drug   = random.choice(["Normal Saline", "Lactated Ringer's", "D5W", "0.45% NaCl"])
+    volume = random.choice([250, 500, 1000])
+    hours  = random.choice([4, 6, 8, 10, 12])
+    rate   = _round1(volume / hours)
+
+    distractors = [
+        _round1(rate * 1.5),
+        _round1(rate * 0.5),
+        _round1(volume * hours / 1000),
+    ]
+    distractors = [d for d in distractors if d != rate][:3]
+    options, correct_idx = _build_options(rate, distractors, unit="mL/hr")
+
+    return {
+        "id":        f"calc_drip_{random.randint(1000,9999)}",
+        "category":  "Dosage Calculations",
+        "subcategory": "IV Rate",
+        "difficulty": "beginner",
+        "type":      "calculation",
+        "stem": (
+            f"A provider orders {volume} mL of {drug} to infuse over {hours} hours. "
+            f"At what rate should the nurse set the infusion pump?"
+        ),
+        "options":   options,
+        "correct":   correct_idx,
+        "rationale": (
+            f"Formula: Volume (mL) ÷ Time (hr)\n"
+            f"= {volume} mL ÷ {hours} hr\n"
+            f"= **{rate} mL/hr**"
+        ),
+        "tags": ["IV-rate", "infusion", "calculation"],
+    }
+
+
+def gen_paediatric_weight() -> dict:
+    """Paediatric weight-based dose → mL to give from available solution."""
+    drug      = random.choice(["amoxicillin", "ibuprofen", "paracetamol", "azithromycin"])
+    weight    = round(random.uniform(10, 30), 1)
+    dose_mg_kg = random.choice([10, 15, 20, 25])
+    conc_mg_ml = random.choice([50, 100, 125, 200, 250])
+
+    ordered_mg = _round1(dose_mg_kg * weight)
+    volume_ml  = _round2(ordered_mg / conc_mg_ml)
+
+    distractors = [
+        _round2(volume_ml * 2),
+        _round2(conc_mg_ml / ordered_mg),
+        _round2(ordered_mg * conc_mg_ml / 1000),
+    ]
+    distractors = [d for d in distractors if d != volume_ml][:3]
+    options, correct_idx = _build_options(volume_ml, distractors, unit="mL")
+
+    return {
+        "id":        f"calc_peds_{random.randint(1000,9999)}",
+        "category":  "Dosage Calculations",
+        "subcategory": "Paediatric",
+        "difficulty": "intermediate",
+        "type":      "calculation",
+        "stem": (
+            f"A child weighs {weight} kg. The provider orders {drug} "
+            f"{dose_mg_kg} mg/kg PO. The suspension available is {conc_mg_ml} mg/5 mL. "
+            f"How many mL should the nurse administer?"
+        ),
+        "options":   options,
+        "correct":   correct_idx,
+        "rationale": (
+            f"Step 1 — Calculate ordered dose: {dose_mg_kg} mg/kg × {weight} kg = {ordered_mg} mg\n"
+            f"Step 2 — Convert concentration: {conc_mg_ml} mg/5 mL = {conc_mg_ml/5} mg/mL\n"
+            f"Step 3 — Calculate volume: {ordered_mg} mg ÷ {conc_mg_ml/5} mg/mL\n"
+            f"= **{volume_ml} mL**"
+        ),
+        "tags": ["paediatric", "weight-based", "oral-liquid", "calculation"],
+    }
+
+
+def gen_gtts_per_min() -> dict:
+    """IV drip rate in gtt/min using drop factor."""
+    volume    = random.choice([100, 250, 500, 1000])
+    hours     = random.choice([1, 2, 4, 6, 8])
+    drop_factor = random.choice([10, 15, 20, 60])
+    rate_ml_hr  = volume / hours
+    rate_gtt_min = _round1(rate_ml_hr * drop_factor / 60)
+
+    distractors = [
+        _round1(rate_gtt_min * 2),
+        _round1(rate_ml_hr / drop_factor),
+        _round1(volume / (hours * drop_factor)),
+    ]
+    distractors = [d for d in distractors if d != rate_gtt_min][:3]
+    options, correct_idx = _build_options(rate_gtt_min, distractors, unit="gtt/min")
+
+    return {
+        "id":        f"calc_gtt_{random.randint(1000,9999)}",
+        "category":  "Dosage Calculations",
+        "subcategory": "Drip Rate (Manual)",
+        "difficulty": "intermediate",
+        "type":      "calculation",
+        "stem": (
+            f"A provider orders {volume} mL IV over {hours} hour(s). "
+            f"The IV tubing has a drop factor of {drop_factor} gtt/mL. "
+            f"At how many drops per minute should the nurse regulate the flow?"
+        ),
+        "options":   options,
+        "correct":   correct_idx,
+        "rationale": (
+            f"Formula: (Volume × Drop factor) ÷ (Time in minutes)\n"
+            f"= ({volume} mL × {drop_factor} gtt/mL) ÷ ({hours} hr × 60 min/hr)\n"
+            f"= {volume * drop_factor} ÷ {hours * 60}\n"
+            f"= **{rate_gtt_min} gtt/min**"
+        ),
+        "tags": ["gtt/min", "drip-rate", "manual-IV", "calculation"],
+    }
+
+
+def generate_batch(n: int = 5) -> list[dict]:
+    """Generate a mixed batch of n calculation questions."""
+    generators = [
+        gen_oral_tablets,
+        gen_weight_based_iv,
+        gen_iv_drip_rate,
+        gen_paediatric_weight,
+        gen_gtts_per_min,
+    ]
+    questions = []
+    for i in range(n):
+        gen = generators[i % len(generators)]
+        questions.append(gen())
+    return questions
+
+
+# ---------------------------------------------------------------------------
+# Internal helper
+# ---------------------------------------------------------------------------
+
+def _build_options(correct, distractors: list, unit: str) -> tuple[list[str], int]:
+    """Shuffle correct + distractors and return (options list, correct_index)."""
+    pool = [correct] + distractors[:3]
+    # Remove duplicates
+    seen, unique = set(), []
+    for v in pool:
+        if v not in seen:
+            seen.add(v)
+            unique.append(v)
+    # Pad if needed
+    while len(unique) < 4:
+        unique.append(_round2(correct * random.uniform(1.3, 2.0)))
+
+    random.shuffle(unique)
+    formatted = [f"{v} {unit}" for v in unique]
+    correct_idx = unique.index(correct)
+    return formatted, correct_idx

requirements.txt

@@ -0,0 +1,2 @@
+streamlit>=1.32.0
+requests>=2.31.0

scorer.py

@@ -0,0 +1,96 @@
+"""
+Quiz scoring, progress tracking, and performance feedback.
+"""
+
+from collections import defaultdict
+
+
+def calculate_score(answers: dict, questions: list[dict]) -> dict:
+    """
+    answers: {question_index: user_answer}
+              For MCQ: int (index of chosen option)
+              For SATA: list[int] (indices of chosen options)
+    Returns comprehensive score report.
+    """
+    total       = len(questions)
+    correct     = 0
+    by_category = defaultdict(lambda: {"correct": 0, "total": 0})
+    by_difficulty = defaultdict(lambda: {"correct": 0, "total": 0})
+    wrong_questions = []
+
+    for i, q in enumerate(questions):
+        cat  = q.get("category", "Unknown")
+        diff = q.get("difficulty", "unknown")
+        by_category[cat]["total"]     += 1
+        by_difficulty[diff]["total"]  += 1
+
+        user_ans = answers.get(i)
+        if user_ans is None:
+            wrong_questions.append({"question": q, "user_answer": None, "correct": False})
+            continue
+
+        is_correct = _check_answer(q, user_ans)
+        if is_correct:
+            correct += 1
+            by_category[cat]["correct"]    += 1
+            by_difficulty[diff]["correct"] += 1
+        else:
+            wrong_questions.append({
+                "question":    q,
+                "user_answer": user_ans,
+                "correct":     False,
+            })
+
+    pct = round((correct / total) * 100, 1) if total > 0 else 0
+
+    return {
+        "total":            total,
+        "correct":          correct,
+        "incorrect":        total - correct,
+        "percentage":       pct,
+        "pass":             pct >= 60,
+        "by_category":      dict(by_category),
+        "by_difficulty":    dict(by_difficulty),
+        "wrong_questions":  wrong_questions,
+        "performance_band": _band(pct),
+        "feedback":         _feedback(pct),
+    }
+
+
+def _check_answer(question: dict, user_answer) -> bool:
+    correct = question.get("correct")
+    if question["type"] == "sata":
+        if not isinstance(user_answer, (list, set)):
+            return False
+        return set(user_answer) == set(correct)
+    else:
+        return user_answer == correct
+
+
+def _band(pct: float) -> str:
+    if pct >= 85:  return "Excellent"
+    if pct >= 75:  return "Proficient"
+    if pct >= 60:  return "Borderline — keep practising"
+    if pct >= 45:  return "Developing — review weak areas"
+    return "Needs significant review"
+
+
+def _feedback(pct: float) -> str:
+    if pct >= 85:
+        return "Outstanding performance! You demonstrate strong clinical knowledge across NCLEX domains."
+    if pct >= 75:
+        return "Good work! You're on track for NCLEX success. Focus on your weaker categories."
+    if pct >= 60:
+        return "Borderline pass. Review your missed questions carefully — focus on rationales, not just answers."
+    if pct >= 45:
+        return "Keep studying! Focus on understanding WHY each answer is correct using the rationale."
+    return "Significant review needed. Consider revisiting core nursing content for each category you missed."
+
+
+def category_percentage(score_report: dict) -> dict[str, float]:
+    """Return {category: percentage} for charting."""
+    out = {}
+    for cat, data in score_report["by_category"].items():
+        t = data["total"]
+        out[cat] = round((data["correct"] / t) * 100, 1) if t > 0 else 0
+    return out

streamlit_app.py

@@ -0,0 +1,435 @@
+"""
+NCLEX Practice Question Generator
+Streamlit app — Hugging Face Spaces (free CPU tier)
+"""
+
+import random
+import streamlit as st
+
+from questions.bank        import filter_questions, get_categories, get_all
+from questions.calculations import generate_batch
+from scorer                import calculate_score, category_percentage
+
+# ---------------------------------------------------------------------------
+# Page config
+# ---------------------------------------------------------------------------
+st.set_page_config(
+    page_title="NCLEX Practice — Student Nurses",
+    page_icon="📋",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+# ---------------------------------------------------------------------------
+# CSS
+# ---------------------------------------------------------------------------
+st.markdown("""
+<style>
+.question-card {
+    background:#f8fafc; border:1px solid #d0dae8;
+    border-radius:10px; padding:1.2rem 1.4rem; margin-bottom:1rem;
+}
+.correct-ans  { background:#e8f5e9; border-left:4px solid #2e7d32;
+                padding:0.6rem 1rem; border-radius:4px; margin-top:0.5rem; }
+.wrong-ans    { background:#fce4ec; border-left:4px solid #c62828;
+                padding:0.6rem 1rem; border-radius:4px; margin-top:0.5rem; }
+.rationale    { background:#e3f2fd; border-left:4px solid #1565c0;
+                padding:0.6rem 1rem; border-radius:4px; margin-top:0.5rem; }
+.sata-badge   { background:#fff8e1; color:#e65100; padding:2px 8px;
+                border-radius:4px; font-size:0.75em; font-weight:700; }
+.calc-badge   { background:#f3e5f5; color:#6a1b9a; padding:2px 8px;
+                border-radius:4px; font-size:0.75em; font-weight:700; }
+.score-big    { font-size:3rem; font-weight:800; text-align:center; }
+.diff-easy    { color:#2e7d32; font-weight:600; font-size:0.78em; }
+.diff-inter   { color:#e65100; font-weight:600; font-size:0.78em; }
+.diff-hard    { color:#c62828; font-weight:600; font-size:0.78em; }
+</style>
+""", unsafe_allow_html=True)
+
+# ---------------------------------------------------------------------------
+# Session state
+# ---------------------------------------------------------------------------
+_DEFAULTS = {
+    "quiz_questions":  [],
+    "quiz_answers":    {},
+    "quiz_submitted":  False,
+    "quiz_score":      None,
+    "calc_questions":  [],
+    "calc_answers":    {},
+    "calc_submitted":  False,
+    "current_q_idx":   0,
+    "quiz_mode":       "all",   # "all" or "one-by-one"
+}
+for k, v in _DEFAULTS.items():
+    if k not in st.session_state:
+        st.session_state[k] = v
+
+CATEGORIES = get_categories()
+DIFFICULTY_LABELS = {"beginner": "🟢 Beginner", "intermediate": "🟡 Intermediate", "advanced": "🔴 Advanced"}
+DIFF_CSS   = {"beginner": "diff-easy", "intermediate": "diff-inter", "advanced": "diff-hard"}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _diff_badge(diff: str) -> str:
+    css   = DIFF_CSS.get(diff, "diff-inter")
+    label = DIFFICULTY_LABELS.get(diff, diff.title())
+    return f'<span class="{css}">{label}</span>'
+
+
+def render_question(q: dict, idx: int, key_prefix: str, show_answer: bool = False) -> int | list | None:
+    """Render a question card. Returns the user's answer or None."""
+    qtype = q["type"]
+
+    with st.container():
+        # Header row
+        hcol1, hcol2, hcol3 = st.columns([4, 1, 1])
+        with hcol1:
+            st.markdown(f"**Question {idx + 1}** — {q['category']} › {q['subcategory']}")
+        with hcol2:
+            st.markdown(_diff_badge(q.get("difficulty", "")), unsafe_allow_html=True)
+        with hcol3:
+            if qtype == "sata":
+                st.markdown('<span class="sata-badge">SELECT ALL</span>', unsafe_allow_html=True)
+            elif qtype == "calculation":
+                st.markdown('<span class="calc-badge">CALCULATION</span>', unsafe_allow_html=True)
+
+        # Stem
+        st.markdown(f"**{q['stem']}**")
+
+        # Answer input
+        user_answer = None
+        options     = q["options"]
+
+        if qtype == "sata":
+            st.caption("*Select all that apply*")
+            selected = []
+            for oi, opt in enumerate(options):
+                if show_answer:
+                    is_correct_opt = oi in q["correct"]
+                    icon = "✅" if is_correct_opt else "❌"
+                    st.markdown(f"{icon} {opt}")
+                else:
+                    chk = st.checkbox(opt, key=f"{key_prefix}_q{idx}_o{oi}")
+                    if chk:
+                        selected.append(oi)
+            user_answer = selected
+
+        else:  # mcq or calculation
+            if show_answer:
+                correct_txt = options[q["correct"]]
+                for oi, opt in enumerate(options):
+                    if oi == q["correct"]:
+                        st.markdown(f"✅ **{opt}**")
+                    else:
+                        st.markdown(f"○ {opt}")
+            else:
+                choice = st.radio(
+                    "Select your answer:",
+                    options,
+                    key=f"{key_prefix}_q{idx}",
+                    index=None,
+                    label_visibility="collapsed",
+                )
+                user_answer = options.index(choice) if choice else None
+
+        # Show rationale if reviewing
+        if show_answer:
+            st.markdown(
+                f'<div class="rationale">📖 <b>Rationale:</b> {q["rationale"]}</div>',
+                unsafe_allow_html=True,
+            )
+
+        st.divider()
+        return user_answer
+
+
+# ---------------------------------------------------------------------------
+# Sidebar
+# ---------------------------------------------------------------------------
+with st.sidebar:
+    st.markdown("## 📋 NCLEX Practice")
+    st.divider()
+
+    st.markdown("**Quiz Settings**")
+    sel_cats = st.multiselect(
+        "Categories",
+        CATEGORIES,
+        default=CATEGORIES,
+        help="Select which NCLEX categories to include",
+    )
+    sel_diff = st.selectbox(
+        "Difficulty",
+        ["Any", "beginner", "intermediate", "advanced"],
+        format_func=lambda x: "Any difficulty" if x == "Any" else DIFFICULTY_LABELS[x],
+    )
+    sel_type = st.selectbox(
+        "Question type",
+        ["Any", "mcq", "sata", "calculation"],
+        format_func=lambda x: {
+            "Any": "All types", "mcq": "Multiple Choice (MCQ)",
+            "sata": "Select All That Apply (SATA)", "calculation": "Dosage Calculation"
+        }[x],
+    )
+    n_questions = st.slider("Number of questions", 5, 30, 10)
+
+    st.divider()
+    available = filter_questions(sel_cats, sel_diff, sel_type if sel_type != "calculation" else None)
+    st.caption(f"📚 {len(get_all())} questions in bank · {len(available)} match filters")
+
+    st.divider()
+    st.markdown(
+        """
+**NCLEX-RN Test Plan**
+- Safe & Effective Care Environment
+- Health Promotion & Maintenance
+- Psychosocial Integrity
+- Physiological Integrity
+        """
+    )
+
+
+# ---------------------------------------------------------------------------
+# Header
+# ---------------------------------------------------------------------------
+st.title("📋 NCLEX Practice Question Generator")
+st.caption(
+    "Evidence-based NCLEX-style practice questions · MCQ · Select All That Apply · "
+    "Dosage Calculations · Full rationales for every question"
+)
+
+# ---------------------------------------------------------------------------
+# Tabs
+# ---------------------------------------------------------------------------
+tab_quiz, tab_calc, tab_results, tab_review = st.tabs(
+    ["🎯 Practice Quiz", "💉 Dosage Calculations", "📊 My Results", "🔁 Review Wrong Answers"]
+)
+
+# ========================= PRACTICE QUIZ TAB ==============================
+with tab_quiz:
+    col_start, col_reset = st.columns([3, 1])
+
+    with col_start:
+        if st.button("🎯 Generate New Quiz", type="primary", use_container_width=True):
+            bank = filter_questions(sel_cats, sel_diff, sel_type if sel_type != "calculation" else None)
+            if not bank:
+                st.error("No questions match your filters. Adjust the sidebar settings.")
+            else:
+                sampled = random.sample(bank, min(n_questions, len(bank)))
+                # Mix in calc questions if type is Any or calculation
+                if sel_type in ("Any", "calculation"):
+                    n_calc = max(1, n_questions // 5)
+                    calc_q = generate_batch(n_calc)
+                    if sel_type == "calculation":
+                        sampled = calc_q * ((n_questions // n_calc) + 1)
+                        sampled = sampled[:n_questions]
+                    else:
+                        sampled = sampled[:-n_calc] + calc_q
+                        random.shuffle(sampled)
+
+                st.session_state.quiz_questions  = sampled[:n_questions]
+                st.session_state.quiz_answers    = {}
+                st.session_state.quiz_submitted  = False
+                st.session_state.quiz_score      = None
+                st.rerun()
+
+    with col_reset:
+        if st.button("🔄 Reset", use_container_width=True):
+            for k in ["quiz_questions","quiz_answers","quiz_submitted","quiz_score"]:
+                st.session_state[k] = [] if k == "quiz_questions" else ({} if "answers" in k else (False if "submitted" in k else None))
+            st.rerun()
+
+    questions = st.session_state.quiz_questions
+
+    if not questions:
+        st.info("Click **Generate New Quiz** to start practising.")
+    else:
+        submitted = st.session_state.quiz_submitted
+
+        if not submitted:
+            st.markdown(f"**{len(questions)} questions** — read each carefully, then click Submit.")
+            st.divider()
+
+            # Render all questions
+            for i, q in enumerate(questions):
+                ans = render_question(q, i, "quiz", show_answer=False)
+                if ans is not None and ans != []:
+                    st.session_state.quiz_answers[i] = ans
+
+            if st.button("✅ Submit Quiz", type="primary", use_container_width=False):
+                score = calculate_score(st.session_state.quiz_answers, questions)
+                st.session_state.quiz_score     = score
+                st.session_state.quiz_submitted = True
+                st.rerun()
+
+        else:
+            # Show results summary
+            score = st.session_state.quiz_score
+            pct   = score["percentage"]
+            band  = score["performance_band"]
+            emoji = "🏆" if pct >= 75 else "📚"
+
+            c1, c2, c3 = st.columns(3)
+            c1.metric("Score", f"{score['correct']} / {score['total']}")
+            c2.metric("Percentage", f"{pct}%")
+            c3.metric("Result", band)
+
+            st.progress(pct / 100)
+            st.info(f"{emoji} {score['feedback']}")
+            st.divider()
+
+            # Show all questions with correct answers
+            st.subheader("Question Review")
+            for i, q in enumerate(questions):
+                user_ans = st.session_state.quiz_answers.get(i)
+                correct  = q["correct"]
+                is_right = (set(user_ans) == set(correct)) if q["type"] == "sata" else user_ans == correct
+
+                icon = "✅" if is_right else "❌"
+                with st.expander(f"{icon} Q{i+1}: {q['stem'][:80]}…", expanded=not is_right):
+                    render_question(q, i, "review", show_answer=True)
+
+
+# ========================= DOSAGE CALCULATIONS TAB ========================
+with tab_calc:
+    c_gen, c_rst = st.columns([3, 1])
+    with c_gen:
+        if st.button("💉 Generate Calculation Set", type="primary", use_container_width=True):
+            st.session_state.calc_questions = generate_batch(n_questions)
+            st.session_state.calc_answers   = {}
+            st.session_state.calc_submitted = False
+            st.rerun()
+    with c_rst:
+        if st.button("🔄 Reset ", use_container_width=True, key="calc_rst"):
+            st.session_state.calc_questions = []
+            st.session_state.calc_answers   = {}
+            st.session_state.calc_submitted = False
+            st.rerun()
+
+    calc_qs = st.session_state.calc_questions
+
+    if not calc_qs:
+        st.info(
+            "Click **Generate Calculation Set** for a fresh set of dosage math problems. "
+            "Each set is uniquely generated — unlimited practice!"
+        )
+        with st.expander("📐 Dosage Calculation Formula Reference"):
+            st.markdown("""
+**Oral Tablets:**
+> (Ordered dose ÷ Dose on hand) × Quantity = Tablets to give
+
+**IV Rate (mL/hr):**
+> Volume (mL) ÷ Time (hours) = mL/hr
+
+**Manual Drip Rate (gtt/min):**
+> (Volume × Drop factor) ÷ Time (minutes) = gtt/min
+
+**Weight-based IV Infusion:**
+> (mcg/kg/min × kg × 60) ÷ Concentration (mcg/mL) = mL/hr
+
+**Paediatric Oral Dose:**
+> mg/kg × weight (kg) ÷ concentration (mg/mL) = mL to give
+            """)
+    else:
+        calc_submitted = st.session_state.calc_submitted
+
+        if not calc_submitted:
+            for i, q in enumerate(calc_qs):
+                ans = render_question(q, i, "calc", show_answer=False)
+                if ans is not None and ans != []:
+                    st.session_state.calc_answers[i] = ans
+
+            if st.button("✅ Submit Calculations", type="primary"):
+                score = calculate_score(st.session_state.calc_answers, calc_qs)
+                st.session_state.calc_submitted = True
+                st.session_state.quiz_score     = score
+                st.rerun()
+        else:
+            score = calculate_score(st.session_state.calc_answers, calc_qs)
+            pct   = score["percentage"]
+            c1, c2, c3 = st.columns(3)
+            c1.metric("Correct", f"{score['correct']} / {score['total']}")
+            c2.metric("Percentage", f"{pct}%")
+            c3.metric("Band", score["performance_band"])
+            st.progress(pct / 100)
+            st.divider()
+
+            for i, q in enumerate(calc_qs):
+                user_ans = st.session_state.calc_answers.get(i)
+                is_right = user_ans == q["correct"]
+                icon = "✅" if is_right else "❌"
+                with st.expander(f"{icon} Q{i+1}: {q['stem'][:80]}…", expanded=not is_right):
+                    render_question(q, i, "calc_rev", show_answer=True)
+
+
+# ========================= RESULTS TAB ====================================
+with tab_results:
+    score = st.session_state.quiz_score
+    if not score:
+        st.info("Complete a quiz to see your results here.")
+    else:
+        pct  = score["percentage"]
+        band = score["performance_band"]
+
+        st.markdown(f'<div class="score-big">{pct}%</div>', unsafe_allow_html=True)
+        st.markdown(f"<h3 style='text-align:center'>{band}</h3>", unsafe_allow_html=True)
+        st.markdown(f"<p style='text-align:center'>{score['feedback']}</p>", unsafe_allow_html=True)
+        st.divider()
+
+        # Category breakdown
+        st.subheader("Performance by Category")
+        cat_pct = category_percentage(score)
+        for cat, p in sorted(cat_pct.items(), key=lambda x: x[1]):
+            col_l, col_r = st.columns([3, 1])
+            col_l.write(cat)
+            col_r.write(f"**{p}%**")
+            st.progress(p / 100)
+
+        st.divider()
+
+        # Difficulty breakdown
+        st.subheader("Performance by Difficulty")
+        diff_data = score["by_difficulty"]
+        dcols = st.columns(3)
+        for i, (diff, data) in enumerate(diff_data.items()):
+            t = data["total"]
+            p = round((data["correct"] / t) * 100, 1) if t > 0 else 0
+            dcols[i % 3].metric(
+                DIFFICULTY_LABELS.get(diff, diff.title()),
+                f"{p}%",
+                f"{data['correct']}/{t} correct",
+            )
+
+
+# ========================= REVIEW TAB =====================================
+with tab_review:
+    score = st.session_state.quiz_score
+    wrong = score["wrong_questions"] if score else []
+
+    if not wrong:
+        msg = "No wrong answers to review — great work! 🎉" if score else "Complete a quiz first."
+        st.info(msg)
+    else:
+        st.subheader(f"Review: {len(wrong)} question(s) to revisit")
+        st.caption("Study the rationale for each — understanding WHY is the key to NCLEX success.")
+        st.divider()
+
+        for i, item in enumerate(wrong):
+            q = item["question"]
+            with st.expander(f"❌ {q['category']} | {q['stem'][:70]}…"):
+                st.markdown(f"**Category:** {q['category']} › {q['subcategory']}")
+                st.markdown(f"**NCLEX Framework:** {q.get('nclex_framework','')}")
+                st.markdown(_diff_badge(q.get("difficulty", "")), unsafe_allow_html=True)
+                st.divider()
+                render_question(q, i, "wrong_rev", show_answer=True)
+
+# ---------------------------------------------------------------------------
+# Footer
+# ---------------------------------------------------------------------------
+st.divider()
+st.caption(
+    "Questions aligned to the 2023 NCLEX-RN Test Plan (NCSBN). "
+    "Dosage calculations are dynamically generated — every set is unique. "
+    "For educational purposes only — always apply clinical judgment in practice."
+)