Simulator Documentation
Everything you need to master the TherapyPod Simulator. Test patient scenarios, refine care pathways, and build confidence in your AI.
Quick Start
Simulator Quick Start
30-Second Overview
Test your clinic's AI by simulating patient conversations before they happen with real patients.
First Simulation (2 minutes)
- Go to Dashboard → Simulator
- Click "Create Profile" or select a preset
- Click "Start Simulation"
- Click "Run Turn" repeatedly to advance the conversation
- Watch for red triage badges—these indicate escalation moments
What Each Button Does
| Button | Action | |--------|--------| | Run Turn | AI and patient exchange one message each | | Pause | Freeze simulation (resume anytime) | | End Simulation | Stop and save to history | | Create Profile | Build a new patient persona |
Reading the Dashboard
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐ │ Patient Profiles│ Active Sims │ Completed │ Triage Alerts │ │ 4 │ 1 │ 12 │ 8 │ │ personas │ running now │ total runs │ across all runs │ └─────────────────┴─────────────────┴─────────────────┴─────────────────┘
Profile Presets
| Preset | Best For Testing | |--------|------------------| | Anxious but Cooperative | Reassurance quality, detailed explanations | | Skeptical Researcher | Evidence-based responses, handling pushback | | Overwhelmed Caregiver | Patience, clear next steps, flexibility | | Tech-Savvy Senior | Concise info, digital tool references |
When to Use the Simulator
- After creating a new care pathway
- Before launching automated outreach
- When onboarding to understand AI capabilities
- After patient complaints to reproduce the scenario
Need Help?
- Full guide:
/docs/simulator/SIMULATOR_GUIDE.md - Technical issues: Contact your clinic admin
For Doctors
Why Use This?
You design care pathways. The Simulator shows you how patients with different personalities will actually experience them.
Example: You've created a post-surgery follow-up sequence. Will an anxious patient feel supported? Will a skeptical patient disengage? Run it through the Simulator to find out.
What You Bring
| Input | Purpose | |-------|---------| | Clinical scenarios | Situations you want to stress-test (medication adherence, symptom escalation, appointment booking) | | Patient archetypes | Personality types common in your practice | | Edge cases | Difficult situations where AI response quality matters most |
What You Do
-
Create Patient Profiles (5 minutes)
- Navigate to Dashboard → Simulator → Create Profile
- Describe the patient persona in plain language
- Set behavioral parameters:
- Emotional Volatility: How quickly mood shifts (calm → volatile)
- Treatment Adherence: Likelihood of following recommendations
- Trigger Keywords: Words that cause anxiety or withdrawal
-
Run Simulations
- Select a profile and start the simulation
- Watch the AI-patient conversation unfold turn by turn
- Each simulation runs for a configurable number of "virtual days"
-
Review Outcomes
- See when triage alerts were triggered
- Identify where the AI response fell short
- Note patterns across different patient types
What You Get
| Output | Value | |--------|-------| | Triage accuracy | Did the AI escalate appropriately when it should have? | | Communication gaps | Where did patients disengage or express frustration? | | Protocol validation | Confidence that your care pathways work for diverse patients |
How You Help This Project
Your clinical expertise makes the Simulator realistic:
- Share real archetypes: "Many of my chronic pain patients are skeptical of new treatments" → we build better default profiles
- Flag AI failures: When the simulated response would be clinically inappropriate, tell us
- Suggest trigger keywords: Domain-specific terms that should prompt careful handling
For Clinic Staff
Why Use This?
You handle patient communication daily. The Simulator lets you preview how the AI assistant will respond to patients—and catch problems before they reach real people.
Example: A new patient intake flow was just configured. Run a few simulations to verify the AI handles common questions correctly.
What You Bring
| Input | Purpose | |-------|---------| | Common patient questions | What do patients actually ask about? | | Difficult interactions | Scenarios where human staff usually need to step in | | Workflow knowledge | How appointments, refills, and escalations should work |
What You Do
-
Select or Create a Patient Profile
Quick Start: Use a preset template
- Anxious but Cooperative
- Skeptical Researcher
- Overwhelmed Caregiver
- Tech-Savvy Senior
Custom: Create profiles matching patients you've encountered
-
Start a Simulation Session
- Click "Start Simulation" on any profile
- The synthetic patient and AI will begin conversing
- Click "Run Turn" to advance the conversation
-
Monitor the Conversation
- Watch for triage alerts (red badges)
- Note if the AI provides incorrect information
- Check if the tone matches your clinic's standards
-
Control the Session | Action | When to Use | |--------|-------------| | Pause | Need to consult with a colleague | | Resume | Continue after a break | | End Simulation | Finished reviewing or found a critical issue |
What You Get
| Output | Value | |--------|-------| | Conversation transcript | Full record of AI-patient interaction | | Triage count | Number of escalation-worthy moments | | Day-by-day progression | How the relationship evolves over time |
What the Stats Mean
| Metric | Reading | |--------|---------| | Day X of Y | Virtual time progression (5 turns = 1 day) | | Triage Alerts | Times the AI flagged urgent patient needs | | Turn Count | Total back-and-forth exchanges |
How You Help This Project
Your frontline experience is invaluable:
- Report confusing responses: If you wouldn't say it to a patient, flag it
- Suggest missing scenarios: "We get a lot of questions about insurance that the AI doesn't handle well"
- Test edge cases: Try unusual inputs—patients don't always follow the script
Quick Reference
Creating Effective Patient Profiles
Good persona description:
"A 45-year-old managing Type 2 diabetes who has tried multiple medications without success. Skeptical of new treatments but willing to try if given clear evidence. Gets frustrated when asked to repeat information."
Weak persona description:
"Difficult patient"
Profile Settings Guide
| Setting | Low Value | High Value | |---------|-----------|------------| | Emotional Volatility | Calm, steady responses | Mood shifts quickly, unpredictable | | Treatment Adherence | Often skips medications, misses appointments | Follows all recommendations reliably |
Trigger Keywords
Add words that should change patient behavior:
| Keyword | Reaction | Example Use | |---------|----------|-------------| | "surgery" | Escalate (anxiety) | Patient becomes worried, asks many questions | | "wait" | Withdraw | Patient disengages, gives short answers | | "side effects" | Escalate | Patient expresses concern, may resist treatment |
Feedback Loop
Found something? Here's what helps:
| What You Found | What to Share | |----------------|---------------| | AI said something wrong | The exact message and what it should have said | | Patient persona felt unrealistic | What was off and how real patients behave | | Missing feature | The scenario you couldn't test and why it matters | | Triage missed or false alarm | The conversation context and expected behavior |
Share feedback through your clinic admin or directly at the escalation review in the History tab.
Data & Privacy
- All simulations use synthetic patients only
- No real patient data enters the Simulator
- Simulation conversations are isolated from production systems
- Escalations logged separately for analysis without affecting real triage queues