Client Agents API

Client agents simulate patients/clients in therapy interactions.

Available Clients

Client	Key	Description
SAPS	saps	State-aware medical patient
ConsistentMI	consistentMI	MI client with stage transitions (ACL 2025)
Eeyore	eeyore	Depression simulation (ACL 2025)
AnnaAgent	annaAgent	Multi-session with memory (ACL 2025)
AdaptiveVP	adaptiveVP	Nurse training simulation (ACL 2025)
SimPatient	simPatient	Cognitive model updates (CHI 2025)
TalkDep	talkDep	Depression screening (CIKM 2025)
ClientCast	clientCast	Psychotherapy assessment
Psyche	psyche	Psychiatric assessment
PatientPsi	patientPsi	CBT-focused patient (EMNLP 2024)
RoleplayDoh	roleplayDoh	Principle-based simulation (EMNLP 2024)
User	user	Human input client

Listing Available Clients

from patienthub.clients import CLIENT_REGISTRY, CLIENT_CONFIG_REGISTRY

# List all client types
print("Available clients:", list(CLIENT_REGISTRY.keys()))

# Get config class for a client
config_class = CLIENT_CONFIG_REGISTRY['patientPsi']
print(config_class)

Loading a Client

from patienthub.clients import get_client

client = get_client(agent_name='patientPsi', lang='en')

Loading a Client with Custom Configurations

from omegaconf import OmegaConf
from patienthub.clients import get_client

config = OmegaConf.create({
    'agent_name': 'patientPsi',
    'model_type': 'OPENAI',
    'model_name': 'gpt-4o',
    'temperature': 0.7,
    'max_tokens': 8192,
    'max_retries': 3,
    'prompt_path': 'data/prompts/client/patientPsi.yaml',
    'data_path': 'data/characters/PatientPsi.json',
    'data_idx': 0,
    'patient_type': 'upset',
})

client = get_client(agent_name='patientPsi', configs=config, lang='en')

Response Generation

response = client.generate_response("How have you been feeling lately?")
print(f"Response: {response.content}")

Data Format

• Prompt Data is stored in data/prompts/client.
• Character data (profiles) is stored in files under data/characters
• Each file is a JSON list; data_idx selects the entry to be simulated

Configuration Options

Common Options

Option	Type	Default	Description
agent_name	str	required	Client identifier
model_type	str	"OPENAI"	Model provider key (used to read ${MODEL_TYPE}_API_KEY / ${MODEL_TYPE}_BASE_URL)
model_name	str	"gpt-4o"	Model identifier
temperature	float	0.7	Sampling temperature (0-1)
max_tokens	int	8192	Max response tokens
max_retries	int	3	API retry attempts
prompt_path	str	varies	Path to method prompts
data_path	str	varies	Path to character JSON file
data_idx	int	0	Index of character in file
lang	str	"en"	Language code

Response Format

Most clients return a structured response:

from pydantic import BaseModel, Field

class Response(BaseModel):
    content: str = Field(
        description="The content of the patient's response"
    )

Some clients include additional fields:

# PatientPsi response
class Response(BaseModel):
    content: str
    # Internal reasoning (not shown to therapist)

# ConsistentMI response
class Response(BaseModel):
    content: str
    action: str  # Selected action type

By Focus Area

Depression & Mood Disorders

• Eeyore: Realistic depression simulation with expert validation
• TalkDep: Clinically grounded personas for depression screening

Motivational Interviewing

• ConsistentMI: Stage-of-change model with consistent behavior
• SimPatient: Cognitive model with internal state tracking

General Psychotherapy

• PatientPsi: CBT-focused with cognitive distortions
• RoleplayDoh: Domain-expert created principles
• ClientCast: Assessment-focused simulation

Specialized Training

• AdaptiveVP: Nurse communication training
• SAPS: Medical diagnosis training
• Psyche: Psychiatric assessment training

Create New Clients

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

uv run python -m examples.create generator.gen_agent_name=client generator.gen_agent_name=<agent_name>

This creates the following two files and registers the client in __init__.py:

• patienthub/clients/<agent_name>.py
• data/prompts/client/<agent_name>.yaml

All clients implement the BaseClient abstract base class (see patienthub/clients/base.py).

See Also

• Creating Custom Therapists