PatientHub

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

Read the Docs 📚

Papers

• PatientHub: A Unified Framework for Patient Simulation → EMNLP 2026 Demo
• PatientAct: Theory-Grounded Mental Health Client Simulation → EMNLP 2026 Findings

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):

patienthub simulate

You can also override any configuration via the command line:

patienthub simulate client=patientPsi therapist=basic

Other examples

Create scaffolding for a new agent:

patienthub create agent_type=client agent_name=myClient

Evaluate a recorded session:

patienthub evaluate evaluator=conv_judge evaluator.prompt_path=data/prompts/evaluator/client_conv.yaml input_dir=data/sessions/default/badtherapist.json

Generate a character profile:

patienthub generate generator=psyche

Adapt a character profile from one client format to another:

patienthub adapt input_path=data/characters/patientPsi.json target_client=roleplayDoh

Run the web demo (requires dev dependencies):

uv sync --extra dev
uv run python -m chainlit run examples/chainlit.py

Visit the Documentation for more examples!

Project Structure

docs/               # Documentation site (Docusaurus)

data/
├── characters/     # Character profiles (JSON)
├── prompts/        # Prompt templates (YAML, per agent)
├── sessions/       # Saved session logs
└── resources/      # Source datasets and auxiliary files

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
├── cli/            # CLI entry points
└── utils/          # File I/O, model helpers

License

See LICENSE for details.

Cite us!

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},
}

@misc{sabour2026patientact,
      title={PatientAct: Theory-Grounded Mental Health Client Simulation}, 
      author={Sahand Sabour and TszYam NG and Yaqian Chen and Guanqun Bi and Jialu Zhao and Minlie Huang},
      year={2026},
      eprint={2608.12750},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2608.12750}, 
}