README.md

---
title: VibeCheck MentalBERT API
emoji: 🧠
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# VibeCheck MentalBERT API

FastAPI proxy serving two fine-tuned MentalBERT models for mental health text classification: a fast flat 8-class head ("Quick Vibe") and a 5-stage hierarchical cascade ("Deep Dive") with optional sensitive-mode calibration.

## Endpoint

**POST** `/classify`

Request body:
```json
{ "text": "i have been feeling really overwhelmed lately", "model": "mentalbert", "sensitive_mode": false }
```

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `text` | string | yes | — | Input text. Max 4096 chars (configurable via `MAX_INPUT_CHARS`). |
| `model` | `"mentalbert" \| "longformer"` | no | `"mentalbert"` | `mentalbert` = Quick Vibe (single forward pass). `longformer` = Deep Dive (5-stage cascade). |
| `sensitive_mode` | bool | no | `false` | Only honored when `model="longformer"`. Lowers the cascade's Stage 0 / Stage 1A thresholds for higher crisis recall. |

Response:
```json
{ "classification": "stress", "confidence": 0.8731 }
```

## Classes (8)
`anxiety` · `bipolar` · `depression` · `normal` · `personality_disorder` · `stress` · `suicidal` · `unhinged`

(`unhinged` is the display key for the model label "Directed Aggression" — threats toward others.)

## Pre-filter
A small regex pre-filter short-circuits the model for unambiguous explicit threats (modal verb + violent verb + 2nd/3rd-person target). It only fires forward (never reroutes self-directed language to aggression) and returns `unhinged` at confidence `0.99`.

## Health check
**GET** `/` → `{ "status": "ok", "loaded": [...], "pid": ... }`

## Environment variables (Space secrets)

| Name | Default | Purpose |
|---|---|---|
| `HF_TOKEN` | — | **Required.** HuggingFace Read token, used by `snapshot_download` to pull the model repos. |
| `QUICK_VIBE_MODEL` | `itsLu/mentalbert-v6-flat` | Override the Quick Vibe model repo. |
| `DEEP_DIVE_MODEL` | `itsLu/mentalbert-v6-hierarchical` | Override the Deep Dive model repo. |
| `ALLOWED_ORIGINS` | `localhost:3000,localhost:3001,https://vibecheck-eosin.vercel.app,https://checkmyvibe.me,https://www.checkmyvibe.me` | Comma-separated CORS allowlist. |
| `MAX_INPUT_CHARS` | `4096` | Reject requests longer than this with HTTP 413. |
| `DEBUG_ENDPOINTS` | `false` | When `"true"`, registers `/diag` and `/debug_classify` for inspection. Off in prod. |

## Deployment

```bash
git push origin main
```

The Space rebuilds the Docker image and starts the container. Models are pulled lazily on first classify request (~30–60 s download per model, cached for the container's lifetime).