PatientHub

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

📚 Documentation | 🚀 Quick Start | 📦 Supported Agents

Quick Start

1. 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]

2. Running simulations

Run the following script for simulation (with default configs)

uv run python -m examples.simulate

You can also run the following script to run customized simulations.

uv run python -m examples.simulate client=[client] therapist=[therapist] evaluator=evaluator evaluator.eval_type=[eval_type]

3. 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
CBT Therapist	CBT	Cognitive Behavioral Therapy therapist
Eliza	eliza	Classic pattern-matching therapist
Bad Therapist	bad	Deliberately poor therapist for training
User	user	Human-in-the-loop therapist

Evaluators

Evaluator	Key	Description
LLM Judge	llm_judge	LLM-based evaluation of therapy sessions

3. Creating new agents

You can run the following command to create the necessary files for a new agent:

uv run python -m examples.create generator.gen_agent_type=[client|therapist] generator.gen_agent_name=<agent_name>

For example

uv run python -m examples.create generator.gen_agent_type=client generator.gen_agent_name=test

Project Structure

patienthub/
├── base/           # Base classes (ChatAgent, etc.)
├── clients/        # Client agent implementations + configs
├── therapists/     # Therapist agent implementations + configs
├── evaluators/     # Evaluation modules
├── generators/     # Character/file/event generators
├── npcs/           # Non-player character agents
├── configs/        # Shared config utilities
├── events/         # Session management
└── utils/          # Helpers

examples/           # CLI entry points
data/
├── characters/     # Character profiles (JSON)
├── prompts/        # Prompt templates (YAML)
├── sessions/       # Session logs
└── resources/      # Source datasets

docs/               # Documentation (Docusaurus)

License

See LICENSE for details.