🎥 Watch Video Demo • 🚀 Quick Start • 📊 Empirical Benchmarks • 🏗️ Architecture • 🎭 Emotion Taxonomy • 💻 Python SDK
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 |
| Inference Efficiency | ❌ Heavy cloud models ( |
✅ Fine-Tuned Compact Transformer ( |
| 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 |
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 │
└─────────────────────────────┘ └─────────────────────────────┘ └─────────────────────────────┘
Evaluated over a curated 50-sample multi-domain gold evaluation dataset on single-core CPU hardware:
| Model Tier | Architecture | Accuracy | Macro F1 | Latency ( |
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.
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
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. |
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)
-
🏠 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.
-
📊 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.
-
📋 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.
- Full database audit trail backed by SQLite (
-
🔬 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.
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
# 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')"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!)
streamlit run app.pyOpen http://localhost:8501 in your browser.
# Execute standalone CLI benchmark
python benchmark.py
# Run the complete test suite
pytest -v tests/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)]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