README.md

---
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.