🎓 StudyMind AI Assistant

A real-time, voice-enabled AI study companion that monitors your behavior, tracks academic progress, detects emotions, and provides personalized guidance — all running 100% locally for privacy.

---

🏗️ Architecture

study_assistant/
│
├── config.py                   # Global configuration & constants
├── assistant.py                # Main coordinator (Phase 8: Integration)
├── dashboard.py                # Streamlit UI (Phase 9)
├── requirements.txt
│
├── modules/
│   ├── storage.py              # SQLite + JSON storage (Phase 4)
│   ├── user_profile.py         # Profile management (Phase 6)
│   ├── voice.py                # STT + TTS + command parser (Phase 1)
│   ├── emotion.py              # Webcam emotion detection (Phase 3)
│   ├── academic.py             # Academic tracker (Phase 2)
│   ├── session_tracker.py      # Session & behavior tracking (Phase 4)
│   └── decision_engine.py      # AI suggestion engine (Phase 5)
│
└── data/                       # Auto-created on first run
    ├── studymind.db            # SQLite database
    ├── user_profile.json       # User profile & adaptive data
    └── session_logs.json       # Session history

---

🚀 Quick Start

1. Install Dependencies

cd study_assistant

# Core install
pip install -r requirements.txt

# macOS (for microphone support)
brew install portaudio

# Ubuntu/Debian
sudo apt install portaudio19-dev python3-pyaudio espeak

# Windows: use pipwin for PyAudio
pip install pipwin && pipwin install pyaudio

2. Launch Streamlit Dashboard (Recommended)

streamlit run dashboard.py

Opens at http://localhost:8501 — full dashboard with voice command center.

3. Launch Full Voice Mode

# First time: set up profile and load sample data
python assistant.py --setup --seed

# Normal launch (voice enabled)
python assistant.py

# Disable voice (text-only mode)
python assistant.py --no-voice

# Disable emotion detection
python assistant.py --no-emotion

---

🎙️ Voice Commands

Say this...	Action
"Start session"	Begin study session
"End session"	End and summarize session
"Take a break" / "Pause"	Start break timer
"I'm back" / "Resume"	End break, continue studying
"What tasks are pending?"	List pending assignments
"What topics are left?"	List incomplete study topics
"Upcoming exams"	Show exam schedule
"What should I study?"	AI priority recommendation
"Session status" / "How long?"	Current session duration
"Today's stats"	Daily study summary
"Motivate me"	Get an encouraging message
"Help"	List all commands

---

📊 Features by Phase

Phase 1: Voice Foundation ✅

• SpeechRecognition for STT (Google API, works offline with Vosk)
• pyttsx3 for offline TTS, gTTS as online fallback
• Natural command parsing with intent detection
• Continuous voice loop with optional wake-word mode

Phase 2: Academic Tracker ✅

• Subjects, topics, assignments, exams stored in SQLite
• Priority-based task suggestions
• Smart voice queries ("what's overdue?", "what to study?")
• Syllabus progress tracking per subject

Phase 3: Emotion Detection ✅

• DeepFace (primary) — 7-emotion classification from webcam
• MediaPipe fallback — landmark-based EAR/MAR estimation
• Mock mode for development/testing without webcam
• Periodic sampling (default: every 30 seconds) to reduce CPU load
• Emotion history tracking within session

Phase 4: Session & Behavior Tracking ✅

• Session start/end with timestamps
• Real-time study vs. break time accumulation
• Inactivity detection (5-minute threshold)
• Automatic break suggestions (every 50 minutes)
• All data persisted to SQLite

Phase 5: Decision Engine ✅

• Rule-based system with 10 suggestion types
• Priority scoring: Inactivity > Overdue > Tired/Stressed > Exams > Breaks...
• Cooldown system prevents suggestion spam
• Extensible to ML/adaptive logic in future

Phase 6: User Profile ✅

• JSON-based profile with personal info + preferences
• Adaptive statistics (avg session duration, common emotion)
• Preference-aware suggestions (session length, study time)
• Incremental learning from session data

Phase 7: Real-Time Voice Feedback ✅

• Proactive suggestion loop (checks every 60 seconds)
• Emotion → voice alerts
• Inactivity → refocus prompts
• Break time → gentle reminders

Phase 8: Integration ✅

• StudyMindAssistant class coordinates all modules
• Thread-safe operation
• Graceful cleanup on exit

Phase 9: Streamlit Dashboard ✅

• Dark-themed analytics dashboard
• Subject progress bars
• Live session status with auto-refresh
• Voice command center (text-based)
• Academic management UI
• Profile editor
• Session history

---

⚙️ Configuration

Edit config.py to customize:

EMOTION_CHECK_INTERVAL = 30    # seconds between emotion checks
INACTIVITY_THRESHOLD = 300     # 5 minutes inactivity alert
BREAK_SUGGESTION_INTERVAL = 50 # minutes before suggesting break
TTS_RATE = 160                 # words per minute for TTS

---

🔮 Future Extensions (Phase 9+)

Wake Word Detection

# Install: pip install openwakeword
# Add to voice.py:
from openwakeword.model import Model

Adaptive ML Engine

The DecisionEngine._generate_candidates() method is designed to be replaced with an ML model. Suggested approach:

• Collect (emotion, time, task_state) → suggestion outcome data
• Train a simple classifier (sklearn LogisticRegression or RandomForest)
• Replace rule weights with model predictions

ElevenLabs Neural TTS

# In voice.py TTSEngine, add:
from elevenlabs import generate, play
# More natural-sounding voice output

Pomodoro Timer Integration

# Add to session_tracker.py:
POMODORO_WORK = 25   # minutes
POMODORO_BREAK = 5   # minutes

---

🔒 Privacy

All data is stored locally:

• data/studymind.db — SQLite database (no cloud sync)
• data/user_profile.json — Profile data
• Webcam frames are never saved — only emotion labels are logged
• Voice is processed via Google STT (optional) or Vosk (fully offline)

For fully offline operation:

1. Use pip install vosk and download a Vosk model
2. Replace recognize_google with Vosk in modules/voice.py
3. Use pyttsx3 (already offline) for TTS

---

🧪 Testing Without Hardware

# Run without microphone or webcam
python assistant.py --no-voice --no-emotion --seed

# Or use Streamlit (no hardware needed)
streamlit run dashboard.py
# Then click "Load Sample Data" in the Academic → Quick Add tab