Skip to main content

Quick Start

This guide will get you running your first patient simulation in under 5 minutes.

Run a Simulation​

The simplest way to start is with the CLI:

uv run python -m examples.simulate

This runs a therapy session with default settings (talkDep client, user therapist).

Customize the Simulation​

Change the Patient Type​

uv run python -m examples.simulate client=patientPsi

Use an AI Therapist​

uv run python -m examples.simulate client=patientPsi therapist=basic

Python API​

For more control, use the Python API directly:

from omegaconf import OmegaConf
from patienthub.clients import get_client

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

# Load the client
client = get_client(configs=config, lang='en')

# Generate responses
response = client.generate_response("Hello, how are you feeling today?")
print(response)

Interactive Web Demo​

Launch the Chainlit web interface:

chainlit run app.py

Then open http://localhost:8000 in your browser.

Output Files​

Session data is saved to data/sessions/ by default. You can customize this:

uv run python -m examples.simulate event.output_dir=outputs/my_session.json
TIPS

Session data is only saved when the event reaches its “end” action (i.e., it writes to event.output_dir).

All ways to trigger saving:

  • The therapist’s output is exactly END / end / exit ⇒ session_ended=True ⇒ end and save
  • The conversation reaches event.max_turns (num_turns >= max_turns) ⇒ end and save

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_name=[client|therapist] generator.gen_agent_name=<agent_name>

For example

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

What's Next?​