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.