🎥 Watch Video Demo • 🚀 Quick Start • 📊 Empirical Benchmarks • 🏗️ Architecture • 🎭 Emotion Taxonomy • 💻 Python SDK

---

💡 Why MindLearn AI?

Traditional e-learning platforms treat every student query as a dry, factual database search. When a student is stuck and says "I've spent 4 hours on this recursion bug and nothing works!", traditional search engines respond with technical documentation—completely missing the student's affective learning friction.

MindLearn AI (v2.0) bridges the gap between Natural Language Understanding (NLU) and Empathetic Pedagogical Support:

Capability	Traditional E-Learning / Search	🧠 MindLearn AI (v2.0)
Affective Understanding	❌ None (ignores tone & sentiment)	✅ Real-time 5-Class Emotion Classification
Mixed Emotions	❌ Flat single-intent lookup	✅ Flags secondary emotions with $\ge 15%$ probability
Inference Efficiency	❌ Heavy cloud models ($>1.5\text{s}$)	✅ Fine-Tuned Compact Transformer ($\le 60\text{ms}$ CPU)
Pedagogical Strategy	❌ Generic answer dumping	✅ 3-Part empathetic coaching via Google Gemini 2.5 Flash
Resilience & Offline	❌ Hard crash on API disconnect	✅ Graceful degradation to offline pedagogical matrix
Benchmarking & Audit	❌ Black-box guessing	✅ Built-in evaluation lab with Radar & Confusion heatmaps

---

⚡ Multi-Tier Model Zoo & Performance

MindLearn AI features a modular 3-Tier Model Zoo managed via a decoupled ModelRegistry pattern:

                                  ┌───────────────────────────────────────────────────────────┐
                                  │                🧠 UNIFIED MODEL REGISTRY                  │
                                  └─────────────────────────────┬─────────────────────────────┘
                                                                │
                 ┌──────────────────────────────────────────────┼──────────────────────────────────────────────┐
                 ▼                                              ▼                                              ▼
  ┌─────────────────────────────┐                ┌─────────────────────────────┐                ┌─────────────────────────────┐
  │  ⚡ COMPACT TRANSFORMER v2   │                │   🧠 BERT-BASE BASELINE     │                │     ⏱️ BiLSTM BASELINE      │
  │   (DistilBERT / MiniLM)     │                │    (Contextual Baseline)    │                │      (Keras + RNN Tier)     │
  │  • 66.9M Parameters         │                │  • 109.5M Parameters        │                │  • 3.92M Parameters         │
  │  • 255 MB Disk Footprint    │                │  • 438 MB Disk Footprint    │                │  • 4.2 MB Disk Footprint    │
  │  • ~58.5 ms Latency (p50)   │                │  • ~126.9 ms Latency (p50)  │                │  • ~100.9 ms Latency (p50)  │
  │  • 17.0 Req / Sec           │                │  • 7.9 Req / Sec            │                │  • 9.3 Req / Sec            │
  └─────────────────────────────┘                └─────────────────────────────┘                └─────────────────────────────┘

---

📊 Empirical Benchmarks

Evaluated over a curated 50-sample multi-domain gold evaluation dataset on single-core CPU hardware:

Model Tier	Architecture	Accuracy	Macro F1	Latency ($p_{50}$)	Throughput	Model Size	Speedup vs BERT
Baseline 1 (RNN)	BiLSTM + Focal Loss	40.0%	0.380	100.9 ms	9.3 req/s	4.2 MB	1.3×
Baseline 2 (Transformer)	bert-base-uncased	64.0%	0.587	126.9 ms	7.9 req/s	438.0 MB	1.0× (Baseline)
MindLearn v2 (Compact)	DistilBERT v2	52.0%	0.536	58.5 ms	17.0 req/s	255.0 MB	⚡ 2.2× Faster

Latency Comparison (Median p50):
┌──────────────────────────────────────┬──────────────────────────────────┐
│ Model Tier                           │ Latency (ms)                     │
├──────────────────────────────────────┼──────────────────────────────────┤
│ BERT-Base Baseline (v1)              │ ████████████████████ 126.9 ms    │
│ BiLSTM Student Adaptive              │ ███████████████ 100.9 ms         │
│ MindLearn Compact Transformer (v2)   │ █████████ 58.5 ms ⚡ (2.2x Fast) │
└──────────────────────────────────────┴──────────────────────────────────┘

Tip

Key Architectural Takeaway: The fine-tuned Compact Transformer v2 achieves a 2.2× reduction in latency and 42% smaller memory footprint with 2.15× higher throughput, eliminating memory-exhaustion SIGKILL risks on cost-efficient cloud instances.

---

🏗️ System Architecture

graph TD
    User([👨‍🎓 Student Input]) --> UI[Streamlit Multi-Page Web App]
    UI --> Prep[Text Sanitization & Soft Bayesian Keyword Fusion]
    Prep --> Reg[Unified Model Registry]
    
    subgraph Model_Zoo ["Multi-Tier Model Zoo"]
        Reg --> Distil["⚡ MindLearn Compact v2 (67M Params)"]
        Reg --> BERT["🧠 BERT-Base Baseline (110M Params)"]
        Reg --> BiLSTM["⏱️ BiLSTM RNN Baseline (3.9M Params)"]
    end
    
    Distil --> LatencyEngine[Live Microsecond Latency Profiler]
    BERT --> LatencyEngine
    BiLSTM --> LatencyEngine
    
    LatencyEngine --> MixedCheck{Probability >= 15%?}
    MixedCheck -->|Primary & Secondary Emotions| GenAI[Google Gemini 2.5 Flash API]
    MixedCheck -->|Offline / API Fallback| Fallback[Static Pedagogical Templates]
    
    GenAI --> Output[Empathy Banner + Action Cards + Model Scores]
    Fallback --> Output
    
    Output --> DB[(SQLite app.db - WAL Mode)]
    Output --> CSV[CSV Audit Log]
    
    subgraph Benchmarking ["Model Benchmark & Evaluation Lab"]
        BenchEngine[Benchmark Engine & Gold Test Suite] --> Radar[Radar Charts & Confusion Matrices]
        Radar --> BenchUI[4_Model_Benchmark.py Page]
    end

Loading

---

🎭 5-Class Affective Taxonomy

MindLearn AI maps student emotional friction into 5 actionable learning states:

Emotion	Sentiment	Key Linguistic Cues	AI Pedagogical Intervention Strategy
Confused 😕	Negative Friction	"don't understand", "lost", "puzzled", "unclear"	Deconstructs the concept into first-principles analogies & step-by-step visual models.
Frustrated 😤	High Friction	"impossible", "stuck", "bug keeps failing", "annoying"	Validates frustration, recommends stepping away, and suggests a simplified baseline challenge.
Bored 😑	Low Arousal	"dry", "monotonous", "repetitive", "too simple"	Introduces gamified learning techniques, competitive challenges, and real-world applications.
Curious 🤩	High Engagement	"why does", "how to connect", "fascinated", "wonder"	Provides deep-dive research links, architectural insights, and exploratory challenge questions.
Confident 🎉	Mastery	"easy", "mastered", "solved", "crystal clear"	Suggests peer-teaching exercises, advanced edge-case problems, and synthesis challenges.

---

🖥️ Multi-Page Experience

pages/
├── 1_Home.py                  🏠 Interactive emotion analysis & real-time AI guidance
├── 2_Analytics.py             📊 Longitudinal affective analytics & progress charts
├── 3_History.py               📋 Searchable, filterable SQL audit log with CSV export
└── 4_🔬_Model_Benchmark.py    🔬 Empirical evaluation lab (Radar charts & Confusion heatmaps)

1. 🏠 Home (Emotion Analysis):

   • Empathy-first hero banner with dynamic color-coding.
   • 1-Click quick examples for rapid testing.
   • Live latency metering badging forward-pass execution time.
   • Step-by-step AI coaching plan powered by Google Gemini 2.5 Flash.

2. 📊 Analytics (Learning Insights):

   • Multi-metric summary cards (Total sessions, Avg confidence, Top emotion).
   • Interactive Plotly emotional distribution over time.
   • Discipline-specific breakdown across fields of study.

3. 📋 History (Interaction Log):

   • Full database audit trail backed by SQLite (app.db).
   • Multi-filter search (by keyword, emotion, academic discipline, date range).
   • One-click CSV export.

4. 🔬 Model Benchmark Lab:

   • Interactive 5-axis Plotly Radar Chart.
   • Normalized Confusion Matrix heatmaps for error analysis.
   • Live Head-to-Head Model Arena for side-by-side comparative inference.

---

📁 Repository Organization

emotionDetectionLearningSupportEngine/
├── HLD.md                             ← High-Level Design Document (v2.0)
├── LLD.md                             ← Low-Level Design Document (v2.0)
├── PRD.md                             ← Product Requirements Document (v2.0)
├── README.md                          ← Main Project Showcase & Documentation
├── requirements.txt                   ← Global Python dependencies
├── documentation/                     ← 8-Phase Engineering Process Documentation
│   ├── 1. Brainstorming & Ideation/
│   ├── 2. Requirement Analysis/
│   ├── 3. Project Design Phase/
│   ├── 4. Project Planning Phase/
│   ├── 5. Project Development Phase/
│   ├── 6. Project Testing/
│   ├── 7. Project Documentation/
│   └── 8. Project Demonstration/
└── project_files/
    ├── app.py                         ← Main Streamlit application entry point
    ├── benchmark.py                   ← CLI benchmark runner & latency profiler
    ├── benchmark_results.json         ← Cached empirical benchmark metrics
    ├── performance_test.py            ← Concurrency & stress testing script
    ├── emotion_response_examples.csv  ← Dataset audit log
    ├── data/
    │   └── app.db                     ← SQLite database (WAL mode enabled)
    ├── models/
    │   ├── bltsm/                     ← BiLSTM weights (.keras) & tokenizer
    │   └── bert_emotion_model_final/  ← Fine-tuned BERT-Base weights & configs
    ├── notebooks/
    │   ├── kaggle_training.ipynb      ← Kaggle GPU training pipeline (v1)
    │   └── v2_compact_transformer_training.ipynb ← Compact Transformer distillation (v2)
    ├── pages/                         ← Streamlit multi-page interface
    ├── src/                           ← Core engine modules
    │   ├── compact_transformer.py     ← Compact Transformer loader & calibration
    │   ├── registry.py                ← Unified ModelRegistry & BaseClassifier
    │   ├── benchmark_engine.py        ← Benchmark suite & latency profiler
    │   ├── bert_model.py              ← BERT-Base inference engine
    │   ├── model.py                   ← BiLSTM RNN inference engine
    │   ├── preprocessing.py           ← Text sanitization & keyword fusion
    │   ├── predict.py                 ← Prediction coordinator (v1 & v2)
    │   ├── database.py                ← SQLAlchemy persistence & ORM models
    │   ├── gamification.py            ← XP, streaks & achievement engine
    │   ├── components.py              ← UI primitives & empathy banners
    │   └── styles.py                  ← Glassmorphic dark CSS design system
    └── tests/                         ← Automated Pytest test suite
        ├── test_engine.py             ← Unit & regression tests
        └── test_v2_engine.py          ← v2 Model registry & benchmark tests

---

🚀 Quick Start

1. Clone & Set Up Environment

# Clone the repository
git clone https://github.com/UdeepChowdary/emotionDetectionLearningSupportEngine.git
cd emotionDetectionLearningSupportEngine/project_files

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate          # On Windows
# source .venv/bin/activate     # On Linux / macOS

# Install dependencies
pip install -r requirements.txt
python -c "import nltk; nltk.download('stopwords'); nltk.download('punkt'); nltk.download('punkt_tab')"

2. Configure API Keys

Create a .env file in project_files/:

GEMINI_API_KEY=your_gemini_api_key_here

(If no API key is provided, MindLearn AI automatically engages its offline pedagogical fallback matrix!)

3. Run the Application

streamlit run app.py

Open http://localhost:8501 in your browser.

4. Run Automated Benchmarks & Tests

# Execute standalone CLI benchmark
python benchmark.py

# Run the complete test suite
pytest -v tests/

---

💻 Programmatic Python SDK

You can easily integrate MindLearn AI into any existing learning platform or backend service:

from src.registry import model_registry
from src.predict import run_v2_prediction

# Run inference with Compact Transformer (v2)
response = run_v2_prediction(
    "I don't understand how Dijkstra's priority queue prevents cycles, I am totally confused.",
    selected_model="compact_transformer"
)

primary = response["primary_result"]
print(f"🎯 Emotion:    {primary['emotion']}")       # Confused
print(f"📈 Confidence: {primary['confidence']:.1%}")  # 91.2%
print(f"⚡ Latency:    {primary['latency_ms']:.1f} ms") # 58.5 ms
print(f"🎭 Mixed:      {response['primary_mixed']}") # [('Confused', 0.91), ('Frustrated', 0.18)]

---

🛡️ License & Acknowledgements

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

_{Built with ❤️ by Udeep Chowdary • Developed during the Google Cloud Internship}