🌿 MindfulAI — Gemini-Powered Mental Health Companion

A private, empathetic terminal-based mental health companion powered by the Google Gemini API.

MindfulAI is a compassionate CLI companion that listens, supports, tracks your mood over time, guides breathing and grounding exercises, and detects crisis signals. Now updated to run on Google's state-of-the-art Gemini 2.5 Flash model for lightning-fast, highly-capable response generation.

---

✨ Features

Feature	Details
💬 Conversational AI	Empathic and supportive responses powered by Gemini 2.5 Flash
📊 Mood Tracking	Automatically extracts user mood levels and visualizes history using ASCII charts
🆘 Crisis Detection	Recognizes distress signals and instantly provides resource lifelines (988, etc.)
🛡️ Privacy First	Your data is saved locally on your disk in data/session.json
📁 Session Export	Export your entire conversation history to a formatted .txt file at any time
🎭 Therapy Persona	Toggle therapy style personas (/persona) like CBT, Venting, and Mindfulness

---

🔄 Data Flow Architecture

graph TD
    %% Styling Definitions
    classDef user fill:#3B82F6,stroke:#1D4ED8,stroke-width:2px,color:#fff;
    classDef core fill:#10B981,stroke:#047857,stroke-width:2px,color:#fff;
    classDef logic fill:#F59E0B,stroke:#D97706,stroke-width:2px,color:#fff;
    classDef ai fill:#8B5CF6,stroke:#6D28D9,stroke-width:2px,color:#fff;
    classDef db fill:#6B7280,stroke:#374151,stroke-width:2px,color:#fff;

    %% User Input Flow
    User([User CLI Terminal]):::user -->|1. Type text / input| App[App Orchestrator - core/app.py]:::core

    %% Input Routing
    App -->|2. Check for slash commands| Router{Command Router?}:::core
    
    %% Branch A: Slash Command
    Router -->|Yes: starts with '/'| CmdHandler[Command Handler - utils/commands.py]:::logic
    CmdHandler -->|Execute action / format response| App

    %% Branch B: Natural Language Conversation
    Router -->|No: natural language text| CrisisCheck[Crisis Detection - core/crisis.py]:::logic
    
    %% Crisis Detection Routing
    CrisisCheck -->|If crisis signals found| CrisisResponse[Generate Critical Resources Response]:::logic
    CrisisCheck -->|If safe| MoodTracker[Mood Tracker - core/mood.py]:::logic
    
    %% Mood Tracking
    MoodTracker -->|Extract emotional keywords & scores| SessionManager[Session Manager - core/session.py]:::logic
    SessionManager -->|Log mood data & timestamp| DiskDB[(Local Disk - data/session.json)]:::db

    %% LLM Connection Flow
    MoodTracker -->|3. Pass conversation history| Client[Gemini Client - models/ollama_client.py]:::ai
    Client -->|4. Build prompt + API Key| GeminiAPI[Google Gemini API - gemini-2.5-flash]:::ai
    GeminiAPI -->|5. Streams back tokens| Client
    Client -->|6. Print text in real-time| App
    
    %% Save to Disk
    App -->|7. Append AI response to chat history| SessionManager
    SessionManager -->|Save conversation state| DiskDB
    App -->|8. Ready for next input| User

Loading

---

🗂 Project Structure

MindfulCare/
├── main.py                    # Entry point & CLI argument parser
├── requirements.txt           # Python dependencies
├── setup.py                   # Package install config
│
├── core/                      # Application logic
│   ├── app.py                 # Main orchestrator / run loop
│   ├── session.py             # Session persistence & mood log
│   ├── mood.py                # Mood keyword extraction & ASCII chart
│   ├── prompts.py             # System prompt, exercises, crisis copy
│   └── crisis.py              # Crisis signal detection & response
│
├── models/                    # LLM client
│   ├── ollama_client.py       # Gemini API client wrapper
│
├── utils/                     # Shared utilities
│   ├── display.py             # Terminal colors & formatted output
│   ├── banner.py              # ASCII banner
│   └── commands.py            # Slash command handler
│
├── data/                      # Auto-created session history
│   └── session.json           # Persisted session & mood history
│
└── logs/                      # Auto-created rotating application logs
    └── mindfulai.log          # Application log file

---

🚀 Quick Start

1. Prerequisites

• Python 3.8+
• Gemini API Key: Get your API key from Google AI Studio

2. Set Your API Key

You can export your Gemini API key as an environment variable:

# On Windows (Command Prompt)
set GEMINI_API_KEY=your_api_key_here

# On Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key_here"

# On macOS/Linux
export GEMINI_API_KEY="your_api_key_here"

Note: The application will automatically fall back to your configured workspace keys if this environment variable is not explicitly set.

3. Install Python Dependencies

pip install -r requirements.txt
pip install google-generativeai

4. Run the App

Start the companion in text mode:

python -Xutf8 main.py --mode text

---

🖥 Slash Commands

Type these commands directly into the prompt during your session:

Command	Description
/help	Show all available commands
/mood	Rate and log your mood (1–10 scale)
/chart	View an ASCII chart of your mood history
/breathe	Guide you through a box-breathing exercise
/ground	Launch the 5-4-3-2-1 grounding technique
/export	Save the current session conversation to a .txt file
/stats	View session and mood statistics
/persona <style>	Change therapy styles (balanced, cbt, venting, motivational, mindfulness)
/quit	Save and exit the application

---

📄 License

MIT License — free to use, modify, and distribute.