README.md

---
title: Reframe Cognitive Reframing Assistant
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.47.2
python_version: "3.10"
app_file: app.py
pinned: false
license: mit
hf_oauth: true
---

# 🧠 reframe: Cognitive Reframing Assistant

A tool inspired by CBT (Cognitive Behavioral Therapy) designed to help identify and reframe cognitive distortions.

## 🎯 Features

- **Educational Landing Page**: Learn about CBT and cognitive reframing
- **Interactive Chat**: Share thoughts and receive balanced perspectives
- **Pattern Recognition**: Identifies cognitive distortions in thinking patterns
- **Similar Situations**: Shows relatable examples with reframed perspectives
- **Learning Center**: Explore 13+ cognitive distortions with examples
- **Multilingual**: Support for English and Spanish
- **Privacy-First**: No message content stored; only pseudonymous usage counters
- **Agentic LLM**: Uses Hugging Face Inference API (required for chat)
- **Streaming Chat**: Incremental assistant messages for a smoother UX
- **Lightweight Memory**: Assistant considers the last N turns (default 6)

## 📁 Project Structure

```
re-frame-gradio/
├── app.py                     # Main Gradio application
├── requirements.txt           # Python dependencies
├── README.md                  # This file
├── cbt_knowledge/             # CBT knowledge base
│   ├── __init__.py
│   ├── distortions.py        # Cognitive distortions database
│   └── reframing_tools.py    # Reframing strategies
├── ui_components/             # UI components
│   ├── __init__.py
│   ├── landing.py            # Landing page
│   └── learn.py              # Learning center
└── locales/                   # Translations (optional)
    ├── en.json               # English
    └── es.json               # Spanish
```

## 🧩 Cognitive Distortions Covered

1. **All-or-Nothing Thinking** - Black and white thinking
2. **Fortune Telling** - Negative predictions
3. **Catastrophizing** - Expecting the worst
4. **Mind Reading** - Assuming others' thoughts
5. **Mental Filter** - Focusing on negatives
6. **Should Statements** - Rigid rules
7. **Labeling** - Global negative labels
8. **Personalization** - Self-blame
9. **Emotional Reasoning** - Feelings as facts
10. **Discounting Positives** - Dismissing good things
11. **Jumping to Conclusions** - Assumptions without evidence
12. **Magnification/Minimization** - Distorting importance
13. **Overgeneralization** - Broad conclusions from single events


## 🤝 How It Works

1. **Share Your Thoughts**: Type what's on your mind in the chat
2. **Pattern Detection**: The system identifies thinking patterns
3. **Balanced Perspectives**: Get alternative ways to view the situation
4. **Similar Examples**: See how others reframed similar thoughts
5. **Learn More**: Explore specific distortions in the Learn tab

## ⚠️ Important Disclaimers

- This is intended to be a **helpful tool**, **NEVER** a replacement for professional therapy
- **NOT** intended for crisis situations or medical advice
- If you're in crisis, please contact emergency services or a crisis helpline
- No message content is stored. For quotas and observability, the app records per-user interaction counters using salted hashes and aggregated metrics (no raw usernames, emails, or IPs).

## 🔐 Login, Quotas, and Owner Controls

This Space supports "Login with Hugging Face" for stable and secure per-user quotas.

- The UI includes a Login button. Once logged in, the app receives an OAuth profile and derives a pseudonymous, salted user id.
- Per-user daily interactions are capped via `HF_AGENT_MAX_INTERACTIONS_PER_USER` (default: 12).
- An Owner tab is visible only to the Space owner.
- Environment variables:
  - `HUGGINGFACEHUB_API_TOKEN` — required: Inference API token (set as a Secret). `HF_TOKEN` is also accepted, but prefer this name.
  - `HF_AGENT_MAX_INTERACTIONS_PER_USER` — per-user daily cap (default: 12)
  - `USAGE_SALT` — required: random salt for hashing user identifiers
  - `AGENT_CALL_LOG_PATH` — path to persist counters (e.g., `/data/agent_calls.json`)
  - `APP_METRICS_PATH` — path to privacy-preserving metrics (e.g., `/data/app_metrics.json`)
  - `HF_HOME` — recommended: set to `/data/.huggingface` to persist cache across restarts

Notes:
- The app never stores raw usernames, emails, IPs, or message content.
- Configure persistent storage for those JSON files if you want counters to survive Space restarts. If using persistent storage, set `HF_HOME=/data/.huggingface` so model/cache downloads persist too.

### Owner-only Admin

Set the environment variable `OWNER_USER` to your Hugging Face username. The Owner tab will only be shown when the logged-in user matches this username.

- `OWNER_USER` — required to enable Owner tab (e.g., `carlos`)


## 🙏 Acknowledgments

- Inspired by CBT principles
- Original prototype built with Google ADK 
- Built with Gradio and Hugging Face

## 📄 License

MIT License - See LICENSE file for details

---