README.md

metadata

title: Mental Health Patient Environment
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 8000
tags:
  - openenv
  - reinforcement-learning
  - mental-health
  - simulation
base_path: /web

MentalHealthPatientEnv - Hugging Face Space User Manual

Overview

This Hugging Face Space hosts the MentalHealthPatientEnv, an interactive simulation environment designed for training and evaluating conversational AI agents in mental health scenarios.

The environment mimics a patient with dynamic psychological states, allowing agents to practice:

• Asking questions
• Building trust
• Detecting risk
• Making diagnoses

---

How It Works

The system follows a reinforcement learning loop:

1. Agent sends an action (question, reflection, etc.)
2. Environment generates a patient response
3. Reward is calculated
4. Conversation continues until completion

---

Available Actions

Action	Description
ask_open	Open-ended question
ask_direct	Specific question
ask_risk	Safety-related question
reflect	Show empathy
diagnose	Final diagnosis

---

Input Format

Each step requires:

{
  "action_type": "ask_open",
  "message": "How have you been feeling lately?"
}

---

Output Format

The environment returns:

{
  "response": "I’ve just been feeling really tired lately...",
  "clarity": 0.72,
  "emotional_state": "sad",
  "trust_level": 0.45,
  "risk_flag": false,
  "reward": 0.63,
  "done": false
}

---

Difficulty Levels

Easy

• Focus: Correct diagnosis

Medium

• Focus: Questioning strategy

Hard

• Focus:

  • Empathy
  • Safety (risk detection)
  • Depth of conversation

---

Scoring System

• Rewards are normalized between 0 and 1
• Final score = average reward over steps

Score Range	Meaning
0.8 – 1.0	Excellent
0.5 – 0.8	Good
< 0.5	Needs improvement

---

API Usage (HF Space Endpoint)

Base URL

https://<your-space-name>.hf.space

Health Check

GET /health

Reset Environment

POST /reset

Step

POST /step

---

LLM Configuration (IMPORTANT)

The patient response is generated using an external LLM.

File Location

server/response_generator.py

---

Change Model

Find:

"model": "liquid/lfm-2.5-1.2b-instruct:free"

Replace with any supported model:

• liquid/lfm-2.5-1.2b-instruct:free (fastest)
• minimax/minimax-m2.5:free
• google/gemma-4-31b-it:free (slower)

---

Change API Provider

Find:

OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"

You can replace it with:

• Custom API endpoint
• Proxy server

---

API Key Setup (HF Space)

Go to:

Space Settings → Variables

Add:

OPENROUTER_API_KEY=your_key_here

---

Performance Tips

To improve speed:

• Use smaller models
• Reduce max_tokens to 50
• Use hybrid responses (rule-based + LLM)

Example:

if action_type == "ask_open":
    return "I’m not sure… just feeling low."

---

Example Interaction

Step 1

Input:

ask_open | How are you feeling?

Output:

"I don’t really know… just tired all the time."

---

Notes

• Do not hardcode API keys
• Always use environment variables
• Ensure dataset is included

---

Troubleshooting

Issue	Solution
Slow response	Use smaller model
No response	Check API key
Import errors	Fix PYTHONPATH

---

Conclusion

This HF Space provides a flexible platform to test and evaluate conversational AI in mental health scenarios.

You can customize:

• LLM models
• Reward functions
• Patient behavior

for research, experimentation, or production use.