PatientHub

A unified hub to create, simulate, and evaluate methods for patient/client simulation.

📚 Documentation | 🚀 Quick Start | 📄 Paper

Quick Start

Setting up the environment

Set up and activate the virtual environment (after installing uv)

uv sync
source .venv/bin/activate

Create a file named .env and fill it with your API credentials:

OPENAI_API_KEY=<your API key>
OPENAI_BASE_URL=<your API base URL> # Optional

Running simulations

Run the following script for simulation (with default configs):

uv run python -m examples.simulate

You can also override any configuration via the command line:

uv run python -m examples.simulate client=patientPsi therapist=basic evaluator=conv_judge evaluator.prompt_path=data/prompts/evaluator/client_conv.yaml

Other examples

Create scaffolding for a new agent:

uv run python -m examples.create agent_type=client agent_name=myClient

Evaluate a recorded session:

uv run python -m examples.evaluate evaluator=conv_judge evaluator.prompt_path=data/prompts/evaluator/client_conv.yaml input_dir=data/sessions/default/badtherapist.json

Generate a character profile:

uv run python -m examples.generate generator=psyche

Run the web demo (requires dev dependencies):

uv run chainlit run examples/chainlit.py

Supported Agents

Clients (Patients)

Source / Description	Venue	Focus	Agent
Automatic Interactive Evaluation for Large Language Models with State Aware Patient Simulator	ArXiv	General (Clinical Diagnosis)	saps
Consistent Client Simulation for Motivational Interviewing-based Counseling	ACL 2025 (Main)	General (MI)	consistentMI
Eeyore: Realistic Depression Simulation via Expert-in-the-Loop Supervised and Preference Optimization	ACL 2025 (Findings)	Depression (Screening/General)	eeyore
AnnaAgent: Dynamic Evolution Agent System with Multi-Session Memory for Realistic Seeker Simulation	ACL 2025 (Findings)	General (Multi-session Counseling)	annaAgent
Adaptive-VP: A Framework for LLM-Based Virtual Patients that Adapts to Trainees’ Dialogue to Facilitate Nurse Communication Training	ACL 2025 (Findings)	General (Nurse Communication Training)	adaptiveVP
Scaffolding Empathy: Training Counselors with Simulated Patients and Utterance-level Performance Visualizations	CHI 2025	Alcohol Misuse (MI)	simPatient
TalkDep: Clinically Grounded LLM Personas for Conversation-Centric Depression Screening	CIKM 2025	Depression (Diagnosis)	talkDep
Towards a Client-Centered Assessment of LLM Therapists by Client Simulation	Arxiv	General (Psychotherapy)	clientCast
PSYCHE: A Multi-faceted Patient Simulation Framework for Evaluation of Psychiatric Assessment Conversational Agents	ArXiv	General (Psychiatric Assessment)	psyche
PATIENT-Ψ: Using Large Language Models to Simulate Patients for Training Mental Health Professionals	EMNLP 2024 (Main)	General (CBT)	patientPsi
Roleplay-doh: Enabling Domain-Experts to Create LLM-simulated Patients via Eliciting and Adhering to Principles	EMNLP 2024 (Main)	General (Counseling)	roleplayDoh

Therapists

Therapist	Key	Description
Basic (CBT)	basic	Cognitive Behavioral Therapy therapist (with optional chain-of-thought)
CAMI	cami	Motivational Interviewing therapist with topic-graph guidance
PSYCHE Therapist	psyche	Therapist from the PSYCHE psychiatric assessment framework
Eliza	eliza	Classic pattern-matching Rogerian therapist
User	user	Human-in-the-loop therapist

Evaluators

Evaluator	Key	Description
LLM Judge (Conversation)	conv_judge	LLM-based evaluation of therapy conversations
LLM Judge (Profile)	profile_judge	LLM-based evaluation of generated client profiles

Generators

Generator	Key	Description
PSYCHE	psyche	Character generation for PSYCHE
ClientCast	clientCast	Character generation for ClientCast
AnnaAgent	annaAgent	Character generation for AnnaAgent

Project Structure

patienthub/
├── clients/        # Client (patient) agent implementations
├── therapists/     # Therapist agent implementations
├── evaluators/     # Evaluation modules
├── generators/     # Character profile generators
├── events/         # Session orchestration (Burr-based)
├── npcs/           # Non-player character agents
├── configs/        # Hydra config utilities
└── utils/          # File I/O, model helpers

examples/           # CLI entry points (simulate, evaluate, generate, create, interview)
data/
├── characters/     # Character profiles (JSON)
├── prompts/        # Prompt templates (YAML, per agent)
├── sessions/       # Saved session logs
└── resources/      # Source datasets and auxiliary files

docs/               # Documentation site (Docusaurus)

License

See LICENSE for details.

Citation

If you find our work useful for your research, please kindly cite our paper as follows:

@misc{sabour2026patienthub,
      title={PatientHub: A Unified Framework for Patient Simulation},
      author={Sahand Sabour and TszYam NG and Minlie Huang},
      year={2026},
      eprint={2602.11684},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2602.11684},
}