MindFello : AI-Powered Mental Health Assistant

MindFello is an AI-driven mental health assistant that provides empathetic conversations, suggests licensed therapists, and enables real-time appointment booking with optional email and push notifications.

It is designed as a state-driven conversational system (FSM) powered by LLM agents, with a user-friendly Gradio web interface.

---

Features

Compassionate AI Conversation

• Emotion-aware responses using a dedicated Emotional Support Agent
• Follow-up clarification questions to better understand user needs
• Safe, non-diagnostic, non-medical guidance

Therapist Recommendation

• Suggests therapists based on:

  • Location
  • Language
  • Availability

• Ranks therapists by open slots

• Explains why each therapist is a good fit

Real-Time Booking System

• Slot holding with countdown timer (optimistic locking)
• Prevents double-booking across users
• Confirms appointments instantly

Notifications

• Push notifications via Pushover
• Email confirmations via SendGrid (optional)

Web Interface

• Built with Gradio
• Live countdown timer for slot holds
• Session-aware state management

---

Architecture Overview

User
 └── Gradio UI
      └── FSM Controller
           ├── EmotionalSupportAgent
           ├── FollowUpAgent
           ├── TherapistSuggesterAgent
           ├── BookingAgent
           ├── EmailNotificationAgent
           └── NotificationAgent (Pushover)

Key Concepts

• FSM (Finite State Machine) controls conversation flow
• Agent-based design for clean responsibility separation
• Optimistic locking for booking safety
• Session memory maintained per user

---

Tech Stack

Category	Technology
UI	Gradio
LLM Runtime	Gemini (OpenAI-compatible API)
Agent Orchestration	agents SDK
Backend Language	Python 3.12
Notifications	SendGrid, Pushover
State Management	In-memory FSM
Persistence	JSON (doctors & slots)

---

Setup Instructions

1️ Clone the Repository

git clone https://github.com/your-org/mindfello.git
cd mindfello

2️ Create Virtual Environment

python -m venv .venv
source .venv/bin/activate

3️ Install Dependencies

pip install -r requirements.txt

---

Environment Variables

Create a .env file in the project root:

# LLM (Gemini via OpenAI-compatible API)
GOOGLE_API_KEY_2=your_gemini_api_key
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

# SendGrid Email
SENDGRID_API_KEY=your_sendgrid_api_key
SENDGRID_FROM_EMAIL=verified_sender@example.com

# Pushover Notifications (optional)
PUSHOVER_TOKEN=your_pushover_app_token
PUSHOVER_USER_KEY=your_pushover_user_key

---

Running the App

python app.py

Or if using Jupyter:

demo.launch()

The Gradio UI will open in your browser.

---

Email Notifications (SendGrid)

• Sent only if user provides an email
• Uses verified sender address
• Plain-text confirmation email

Example email content:

Subject: Your MindFello Booking Confirmation

Hi [Name],

Your booking has been confirmed
Therapist: Dr. Ayesha Rahman
Time: 15 Dec 2025 | 10:00 – 11:00

---

Push Notifications (Pushover)

• Instant push notification on successful booking
• Optional — system continues to work without it

---

Data Storage

Doctors & Slots

Stored in:

doctors.json

Structure:

{
  "id": "doc1",
  "name": "Dr. Ayesha Rahman",
  "specialty": "clinical_psychologist",
  "location": "Dhaka",
  "languages": ["English", "Bangla"],
  "slots": [
    {
      "slot_id": "s1",
      "start": "2025-12-15T10:00:00",
      "end": "2025-12-15T11:00:00",
      "booked": false
    }
  ]
}

---

Safety & Ethics

• ❌ No medical diagnosis
• ❌ No medication advice
• ✅ Empathy-first responses
• ✅ Encourages professional help when appropriate

---

Future Improvements

• Database-backed persistence (PostgreSQL / Firebase)
• User authentication
• Rescheduling & cancellation
• Admin dashboard for therapists
• Analytics & monitoring
• Multi-language UI support

---

Author

Tamzid Khan Software Engineer | AI & Agentic Systems Enthusiast

---

License

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