README.md

metadata

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

---