tests/THERAPY_BOOKING_README.md

AIMHSA - AI Mental Health Support Assistant with Automated Therapy Booking

Overview

AIMHSA is an advanced AI-powered mental health support system specifically designed for Rwanda. The system combines conversational AI with automated therapy booking capabilities, providing immediate support and professional intervention when needed.

🚀 New Features: Automated Therapy Booking System

Core Functionality

1. Real-time Risk Assessment: Every user message is analyzed for mental health risk indicators
2. Automated Professional Matching: AI matches users with appropriate mental health professionals
3. Emergency Session Booking: Automatic booking for high-risk cases
4. Professional Dashboard: Complete session management for mental health professionals
5. Admin Dashboard: System monitoring and professional management
6. Notification System: Real-time alerts for professionals and administrators

Risk Detection Levels

• Critical: Immediate professional intervention required (suicidal ideation, self-harm)
• High: Urgent professional support needed (severe depression, crisis)
• Medium: Professional consultation recommended (anxiety, stress)
• Low: General support and monitoring (mild concerns)

🏗️ System Architecture

Backend (Flask API)

• Port: 7060
• Database: SQLite with extended schema
• AI Models: Ollama (llama3.2:3b for chat, nomic-embed-text for embeddings)
• Risk Assessment: Multi-layered analysis (pattern matching + AI analysis)

Frontend Components

• Main Chat Interface: Enhanced with risk assessment display
• Admin Dashboard: Professional and system management
• Professional Dashboard: Session management and notifications
• Professional Login: Secure access for mental health professionals

📊 Database Schema

New Tables Added

1. professionals: Mental health professional profiles
2. risk_assessments: Real-time risk analysis records
3. automated_bookings: Emergency session bookings
4. professional_notifications: Alert system for professionals
5. therapy_sessions: Session records and notes
6. admin_users: Administrative access control

🔧 Installation & Setup

Prerequisites

• Python 3.8+
• Ollama installed and running
• Required Python packages (see requirements.txt)

Setup Steps

1. Install Dependencies

   pip install flask flask-cors ollama python-dotenv sqlite3 werkzeug numpy pytesseract
   

2. Initialize Database

   python app.py
   # This will create all necessary tables
   

3. Create Sample Data

   python create_sample_data.py
   # Creates sample professionals, users, and admin user
   

4. Test Login System

   python test_login.py
   # Verifies all login functionality
   

5. Start Backend

   python app.py
   # Runs on https://prodevroger-ishingiro.hf.space
   

6. Start Frontend

   python run_frontend.py
   # Runs on https://prodevroger-ishingiro.hf.space
   

👥 User Roles & Access

1. Regular Users

• Access: Main chat interface
• Features:
  • AI mental health support
  • Risk assessment display
  • Emergency booking notifications
  • Conversation history

2. Mental Health Professionals

• Access: Professional dashboard
• Login: /professional_login.html
• Features:
  • View assigned sessions
  • Accept/decline bookings
  • Add session notes
  • Manage treatment plans
  • Receive notifications

3. Administrators

• Access: Admin dashboard
• Login: Use admin credentials
• Features:
  • Manage professionals
  • Monitor risk assessments
  • View all bookings
  • System analytics
  • Real-time monitoring

🔐 Default Credentials

Sample Users

• testuser / password123
• john_doe / password123
• jane_smith / password123
• rwanda_user / password123

Sample Professionals

• Dr. Marie Mukamana (Psychiatrist): dr_mukamana / password123
• Jean Ntwari (Counselor): counselor_ntwari / password123
• Grace Umutoni (Psychologist): psychologist_umutoni / password123
• Claudine Nyiraneza (Social Worker): social_worker_nyiraneza / password123

Admin User

• Username: admin
• Password: admin123

🚨 Emergency Response Flow

1. User sends message → Risk assessment triggered
2. High/Critical risk detected → Professional matching algorithm activated
3. Best professional selected → Automated booking created
4. Professional notified → Real-time notification sent
5. Session scheduled → User receives confirmation
6. Professional accepts → Session confirmed
7. Session conducted → Notes and treatment plan recorded

📱 API Endpoints

User Endpoints

• POST /ask - Enhanced with risk assessment
• GET /session - Session management
• GET /history - Conversation history

Professional Endpoints

• POST /professional/login - Professional authentication
• GET /professional/notifications - Get notifications
• PUT /professional/notifications/{id}/read - Mark as read
• GET /professional/sessions - Get assigned sessions
• PUT /professional/sessions/{id}/status - Accept/decline sessions
• POST /professional/sessions/{id}/notes - Add session notes

Admin Endpoints

• POST /admin/professionals - Create professional
• GET /admin/professionals - List professionals
• GET /admin/bookings - View all bookings
• GET /admin/risk-assessments - Risk assessment history

Monitoring Endpoints

• GET /monitor/risk-stats - Real-time risk statistics
• GET /monitor/recent-assessments - Recent assessments

🎯 Key Features

Risk Assessment Engine

• Pattern Matching: Regex-based detection of risk indicators
• AI Analysis: Ollama-powered sentiment and context analysis
• Conversation Patterns: Escalation detection across message history
• Rwanda-Specific: Specialized indicators for local context

Professional Matching Algorithm

• Specialization Mapping: Matches risk types to professional expertise
• Location Proximity: Considers geographical distance
• Availability: Real-time availability checking
• Experience Scoring: Prioritizes experienced professionals

Notification System

• Real-time Alerts: Immediate notifications for professionals
• Priority Levels: Urgent, high, normal priority classification
• Multi-channel: Dashboard notifications with visual indicators
• Auto-refresh: Live updates every 30 seconds

🔧 Configuration

Environment Variables

CHAT_MODEL=llama3.2:3b
EMBED_MODEL=nomic-embed-text
SENT_EMBED_MODEL=nomic-embed-text

Risk Assessment Thresholds

• Critical: ≥ 0.8 risk score
• High: ≥ 0.6 risk score
• Medium: ≥ 0.4 risk score
• Low: < 0.4 risk score

Session Scheduling

• Critical Risk: 1 hour from detection
• High Risk: 24 hours from detection
• Emergency Sessions: Immediate professional contact

📈 Monitoring & Analytics

Real-time Dashboards

• Risk Statistics: Live count by risk level
• Professional Activity: Session acceptance rates
• System Health: Response times and error rates
• Geographic Distribution: Risk patterns by location

Reporting

• Daily Risk Reports: Summary of assessments
• Professional Performance: Session completion rates
• System Usage: User engagement metrics
• Emergency Response: Time-to-intervention tracking

🛡️ Security & Privacy

Data Protection

• Encrypted Storage: Password hashing with Werkzeug
• Session Management: Secure session tokens
• Access Control: Role-based permissions
• Audit Logging: Complete activity tracking

Privacy Compliance

• Anonymized Data: IP-based sessions for guests
• Consent Management: Clear data usage policies
• Data Retention: Configurable retention periods
• Secure Communication: HTTPS-ready architecture

🚀 Deployment

Production Considerations

• Database: Consider PostgreSQL for production
• Caching: Redis for session management
• Load Balancing: Multiple API instances
• Monitoring: Application performance monitoring
• Backup: Automated database backups

Scaling

• Horizontal Scaling: Multiple API servers
• Database Sharding: Partition by region/district
• CDN: Static asset delivery
• Microservices: Split into specialized services

🤝 Contributing

Development Setup

1. Fork the repository
2. Create feature branch
3. Implement changes
4. Add tests
5. Submit pull request

Code Standards

• Python: PEP 8 compliance
• JavaScript: ES6+ standards
• Documentation: Comprehensive docstrings
• Testing: Unit and integration tests

📞 Support & Contact

Technical Support

• Issues: GitHub Issues
• Documentation: This README
• Community: Development discussions

Mental Health Resources

• Rwanda Mental Health Hotline: 105
• CARAES Ndera Hospital: +250 788 305 703
• Emergency Services: 112

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Rwanda Mental Health Community: For guidance and requirements
• Open Source Contributors: For the amazing tools and libraries
• Mental Health Professionals: For their expertise and feedback

---

⚠️ Important: This system is designed to supplement, not replace, professional mental health care. Always encourage users to seek professional help when needed.