Skip to content

Commit 4d4a4f8

Browse files
w1z1x0w1z1x0
committed
Merge remote-tracking branch 'origin/master' into feature/patientZero
2 parents dff4ab5 + 64e08e1 commit 4d4a4f8

102 files changed

Lines changed: 2338 additions & 3856 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/client_tests.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Client Smoke Tests
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches:
7+
- master
8+
paths:
9+
- 'patienthub/clients/**'
10+
- 'patienthub/configs/**'
11+
- 'data/prompts/**'
12+
- 'patienthub/tests/clients.py'
13+
pull_request:
14+
branches:
15+
- master
16+
paths:
17+
- 'patienthub/clients/**'
18+
- 'patienthub/configs/**'
19+
- 'data/prompts/**'
20+
- 'patienthub/tests/clients.py'
21+
22+
jobs:
23+
test:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- uses: astral-sh/setup-uv@v5
29+
with:
30+
python-version: "3.12"
31+
32+
- name: Install dependencies
33+
run: |
34+
uv venv --python 3.12 --clear
35+
uv pip install -e . --no-deps
36+
uv pip install pydantic omegaconf hydra-core litellm instructor jinja2 python-dotenv rich pytest
37+
38+
- name: Run client smoke tests
39+
run: uv run pytest patienthub/tests/clients.py -v

‎.github/workflows/schema_tests.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Schema Validation Tests
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
branches:
7+
- master
8+
paths:
9+
- 'patienthub/clients/**'
10+
- 'patienthub/schemas/**'
11+
- 'data/characters/**'
12+
- 'patienthub/tests/schemas.py'
13+
pull_request:
14+
branches:
15+
- master
16+
paths:
17+
- 'patienthub/clients/**'
18+
- 'patienthub/schemas/**'
19+
- 'data/characters/**'
20+
- 'patienthub/tests/schemas.py'
21+
22+
jobs:
23+
test:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- uses: actions/checkout@v4
27+
28+
- uses: astral-sh/setup-uv@v5
29+
with:
30+
python-version: "3.12"
31+
32+
- name: Install dependencies
33+
run: |
34+
uv venv --python 3.12 --clear
35+
uv pip install -e . --no-deps
36+
uv pip install pydantic omegaconf hydra-core litellm instructor jinja2 python-dotenv rich pytest
37+
38+
- name: Run schema validation tests
39+
run: uv run pytest patienthub/tests/schemas.py -v

‎README.md‎

Lines changed: 37 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -27,58 +27,65 @@ OPENAI_BASE_URL=<your API base URL> # Optional
2727
Run the following script for simulation (with default configs):
2828

2929
```bash
30-
uv run python -m examples.simulate
30+
patienthub simulate
3131
```
3232

3333
You can also override any configuration via the command line:
3434

3535
```bash
36-
uv run python -m examples.simulate client=patientPsi therapist=basic evaluator=conv_judge evaluator.prompt_path=data/prompts/evaluator/client_conv.yaml
36+
patienthub simulate client=patientPsi therapist=basic evaluator=conv_judge evaluator.prompt_path=data/prompts/evaluator/client_conv.yaml
3737
```
3838

3939
### Other examples
4040

4141
**Create** scaffolding for a new agent:
4242

4343
```bash
44-
uv run python -m examples.create agent_type=client agent_name=myClient
44+
patienthub create agent_type=client agent_name=myClient
4545
```
4646

4747
**Evaluate** a recorded session:
4848

4949
```bash
50-
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
50+
patienthub evaluate evaluator=conv_judge evaluator.prompt_path=data/prompts/evaluator/client_conv.yaml input_dir=data/sessions/default/badtherapist.json
5151
```
5252

5353
**Generate** a character profile:
5454

5555
```bash
56-
uv run python -m examples.generate generator=psyche
56+
patienthub generate generator=psyche
57+
```
58+
59+
**Adapt** a character profile from one client format to another:
60+
61+
```bash
62+
patienthub adapt input_path=data/characters/PatientPsi.json target_client=roleplayDoh
5763
```
5864

5965
**Run the web demo** (requires `dev` dependencies):
6066

6167
```bash
62-
uv run chainlit run examples/chainlit.py
68+
uv sync --extra dev
69+
uv run python -m chainlit run examples/chainlit.py
6370
```
6471

6572
## Supported Agents
6673

6774
### Clients (Patients)
6875

69-
| Source / Description | Venue | Focus | Agent |
70-
| :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------- | ------------------------------------------------------ |
71-
| [Automatic Interactive Evaluation for Large Language Models with State Aware Patient Simulator](https://arxiv.org/pdf/2403.08495) | ArXiv | General (Clinical Diagnosis) | [`saps`](./patienthub/clients/saps.py) |
72-
| [Consistent Client Simulation for Motivational Interviewing-based Counseling](https://aclanthology.org/2025.acl-long.1021/) | ACL 2025 (Main) | General (MI) | [`consistentMI`](./patienthub/clients/consistentMI.py) |
73-
| [Eeyore: Realistic Depression Simulation via Expert-in-the-Loop Supervised and Preference Optimization](https://aclanthology.org/2025.findings-acl.707/) | ACL 2025 (Findings) | Depression (Screening/General) | [`eeyore`](./patienthub/clients/eeyore.py) |
74-
| [AnnaAgent: Dynamic Evolution Agent System with Multi-Session Memory for Realistic Seeker Simulation](https://aclanthology.org/2025.findings-acl.1192/) | ACL 2025 (Findings) | General (Multi-session Counseling) | [`annaAgent`](./patienthub/clients/annaAgent.py) |
75-
| [ Adaptive-VP: A Framework for LLM-Based Virtual Patients that Adapts to Trainees’ Dialogue to Facilitate Nurse Communication Training](https://aclanthology.org/2025.findings-acl.118/) | ACL 2025 (Findings) | General (Nurse Communication Training) | [`adaptiveVP`](./patienthub/clients/adaptiveVP.py) |
76-
| [Scaffolding Empathy: Training Counselors with Simulated Patients and Utterance-level Performance Visualizations](https://dl.acm.org/doi/full/10.1145/3706598.3714014) | CHI 2025 | Alcohol Misuse (MI) | [`simPatient`](./patienthub/clients/simPatient.py) |
77-
| [TalkDep: Clinically Grounded LLM Personas for Conversation-Centric Depression Screening](https://dl.acm.org/doi/10.1145/3746252.3761617) | CIKM 2025 | Depression (Diagnosis) | [`talkDep`](./patienthub/clients/talkDep.py) |
78-
| [Towards a Client-Centered Assessment of LLM Therapists by Client Simulation](https://github.com/wangjs9/ClientCAST) | Arxiv | General (Psychotherapy) | [`clientCast`](./patienthub/clients/clientCast.py) |
79-
| [PSYCHE: A Multi-faceted Patient Simulation Framework for Evaluation of Psychiatric Assessment Conversational Agents](https://arxiv.org/pdf/2501.01594) | ArXiv | General (Psychiatric Assessment) | [`psyche`](./patienthub/clients/psyche.py) |
80-
| [PATIENT-Ψ: Using Large Language Models to Simulate Patients for Training Mental Health Professionals](https://aclanthology.org/2024.emnlp-main.711/) | EMNLP 2024 (Main) | General (CBT) | [`patientPsi`](./patienthub/clients/patientPsi.py) |
81-
| [Roleplay-doh: Enabling Domain-Experts to Create LLM-simulated Patients via Eliciting and Adhering to Principles](https://aclanthology.org/2024.emnlp-main.591/) | EMNLP 2024 (Main) | General (Counseling) | [`roleplayDoh`](./patienthub/clients/roleplayDoh.py) |
76+
| Source / Description | Venue | Focus | Agent |
77+
| :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------- | ------------------------------------------------------ |
78+
| [Automatic Interactive Evaluation for Large Language Models with State Aware Patient Simulator](https://arxiv.org/pdf/2403.08495) | ArXiv | General (Clinical Diagnosis) | [`saps`](./patienthub/clients/saps.py) |
79+
| [Consistent Client Simulation for Motivational Interviewing-based Counseling](https://aclanthology.org/2025.acl-long.1021/) | ACL 2025 (Main) | General (MI) | [`consistentMI`](./patienthub/clients/consistentMI.py) |
80+
| [Eeyore: Realistic Depression Simulation via Expert-in-the-Loop Supervised and Preference Optimization](https://aclanthology.org/2025.findings-acl.707/) | ACL 2025 (Findings) | Depression (Screening/General) | [`eeyore`](./patienthub/clients/eeyore.py) |
81+
| [AnnaAgent: Dynamic Evolution Agent System with Multi-Session Memory for Realistic Seeker Simulation](https://aclanthology.org/2025.findings-acl.1192/) | ACL 2025 (Findings) | General (Multi-session Counseling) | [`annaAgent`](./patienthub/clients/annaAgent.py) |
82+
| [Adaptive-VP: A Framework for LLM-Based Virtual Patients that Adapts to Trainees’ Dialogue to Facilitate Nurse Communication Training](https://aclanthology.org/2025.findings-acl.118/) | ACL 2025 (Findings) | General (Nurse Communication Training) | [`adaptiveVP`](./patienthub/clients/adaptiveVP.py) |
83+
| [Scaffolding Empathy: Training Counselors with Simulated Patients and Utterance-level Performance Visualizations](https://dl.acm.org/doi/full/10.1145/3706598.3714014) | CHI 2025 | Alcohol Misuse (MI) | [`simPatient`](./patienthub/clients/simPatient.py) |
84+
| [TalkDep: Clinically Grounded LLM Personas for Conversation-Centric Depression Screening](https://dl.acm.org/doi/10.1145/3746252.3761617) | CIKM 2025 | Depression (Diagnosis) | [`talkDep`](./patienthub/clients/talkDep.py) |
85+
| [Towards a Client-Centered Assessment of LLM Therapists by Client Simulation](https://github.com/wangjs9/ClientCAST) | Arxiv | General (Psychotherapy) | [`clientCast`](./patienthub/clients/clientCast.py) |
86+
| [PSYCHE: A Multi-faceted Patient Simulation Framework for Evaluation of Psychiatric Assessment Conversational Agents](https://arxiv.org/pdf/2501.01594) | ArXiv | General (Psychiatric Assessment) | [`psyche`](./patienthub/clients/psyche.py) |
87+
| [PATIENT-Ψ: Using Large Language Models to Simulate Patients for Training Mental Health Professionals](https://aclanthology.org/2024.emnlp-main.711/) | EMNLP 2024 (Main) | General (CBT) | [`patientPsi`](./patienthub/clients/patientPsi.py) |
88+
| [Roleplay-doh: Enabling Domain-Experts to Create LLM-simulated Patients via Eliciting and Adhering to Principles](https://aclanthology.org/2024.emnlp-main.591/) | EMNLP 2024 (Main) | General (Counseling) | [`roleplayDoh`](./patienthub/clients/roleplayDoh.py) |
8289

8390
### Therapists
8491

@@ -107,7 +114,15 @@ uv run chainlit run examples/chainlit.py
107114

108115
## Project Structure
109116

110-
```
117+
```text
118+
docs/ # Documentation site (Docusaurus)
119+
120+
data/
121+
├── characters/ # Character profiles (JSON)
122+
├── prompts/ # Prompt templates (YAML, per agent)
123+
├── sessions/ # Saved session logs
124+
└── resources/ # Source datasets and auxiliary files
125+
111126
patienthub/
112127
├── clients/ # Client (patient) agent implementations
113128
├── therapists/ # Therapist agent implementations
@@ -116,16 +131,9 @@ patienthub/
116131
├── events/ # Session orchestration (Burr-based)
117132
├── npcs/ # Non-player character agents
118133
├── configs/ # Hydra config utilities
134+
├── cli/ # CLI entry points
119135
└── utils/ # File I/O, model helpers
120136
121-
examples/ # CLI entry points (simulate, evaluate, generate, create, interview)
122-
data/
123-
├── characters/ # Character profiles (JSON)
124-
├── prompts/ # Prompt templates (YAML, per agent)
125-
├── sessions/ # Saved session logs
126-
└── resources/ # Source datasets and auxiliary files
127-
128-
docs/ # Documentation site (Docusaurus)
129137
```
130138

131139
## License
@@ -136,7 +144,7 @@ See [LICENSE](./LICENSE) for details.
136144

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

139-
```
147+
```bibtex
140148
@misc{sabour2026patienthub,
141149
title={PatientHub: A Unified Framework for Patient Simulation},
142150
author={Sahand Sabour and TszYam NG and Minlie Huang},

‎data/characters/SimPatient.json‎

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
1-
{
2-
"persona": {
3-
"age": 34,
4-
"gender": "male",
5-
"ethnicity": "Asian",
6-
"occupation": "software engineer",
7-
"mbti": "INTJ-A"
8-
},
9-
"cognitive_model": {
10-
"patient_control": 3,
11-
"patient_efficacy": 4,
12-
"patient_awareness": 7,
13-
"patient_reward": 8
14-
},
15-
"between_session_event": "After a stressful day at work, the patient received a call from a college friend inviting him to a small get-together. He hesitated but decided to go, thinking he could handle it. However, once there, the sight and smell of alcohol triggered his cravings. Despite his initial resolve, he ended up drinking several beers, feeling momentarily relaxed but later regretting his lack of control. The event left him questioning his ability to maintain sobriety in social settings and motivated him to discuss strategies for handling similar situations in his next therapy session."
16-
}
1+
[
2+
{
3+
"persona": {
4+
"age": 34,
5+
"gender": "male",
6+
"ethnicity": "Asian",
7+
"occupation": "software engineer",
8+
"mbti": "INTJ-A"
9+
},
10+
"cognitive_model": {
11+
"patient_control": 3,
12+
"patient_efficacy": 4,
13+
"patient_awareness": 7,
14+
"patient_reward": 8
15+
},
16+
"between_session_event": "After a stressful day at work, the patient received a call from a college friend inviting him to a small get-together. He hesitated but decided to go, thinking he could handle it. However, once there, the sight and smell of alcohol triggered his cravings. Despite his initial resolve, he ended up drinking several beers, feeling momentarily relaxed but later regretting his lack of control. The event left him questioning his ability to maintain sobriety in social settings and motivated him to discuss strategies for handling similar situations in his next therapy session."
17+
}
18+
]

‎data/characters/roleplayDoh.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[
2+
{
3+
"description": "Alex is a male patient with a history of substance abuse and childhood obesity, which has deeply affected his self-esteem and body image. He grew up feeling emotionally neglected and rejected by his mother, and has struggled with feelings of being trapped, unlovable, and out of control. He copes by avoiding family and stressful situations. He is currently dealing with anxiety and sadness after being invited to his cousin's wedding, which he has avoided by ignoring the invitation and cutting off contact with family."
4+
}
5+
]

0 commit comments

Comments
 (0)