Watch the full live demonstration of the Emotion Detection & Learning Support Engine in action here:
👉 View Project Demo Video

emotion-detection/
├── documentation/                   ← Additional project documentation
├── project files/                   ← Main code & assets directory
│   ├── .env                         ← Local environment variables (API keys)
│   ├── .venv/                       ← Virtual environment folder
│   ├── app.py                       ← Streamlit Web Application entrypoint
│   ├── performance_test.py          ← Performance & load testing script
│   ├── requirements.txt             ← Project dependencies
│   ├── emotion_response_examples.csv ← Saved history (auto-created at runtime)
│   ├── emotion_response_mapping.csv  ← Emotion responses (auto-created at runtime)
│   ├── data/
│   │   └── emotion_text_dataset.csv  ← Dataset created by Kaggle notebook
│   ├── models/
│   │   ├── bltsm/
│   │   │   ├── bilstm_student_adaptive.keras
│   │   │   ├── tokenizer.pkl
│   │   │   └── label_classes.npy
│   │   └── bert_emotion_model_final/
│   │       ├── config.json
│   │       ├── model.safetensors
│   │       ├── tokenizer.json
│   │       ├── tokenizer_config.json
│   │       ├── special_tokens_map.json
│   │       └── label_mapping.json
│   ├── notebooks/
│   │   └── kaggle_training.ipynb     ← Model training source code
│   └── src/
│       ├── __init__.py
│       ├── preprocessing.py         ← Text preprocessing & keyword boosting
│       ├── model.py                 ← BiLSTM model loader
│       ├── bert_model.py            ← BERT model loader
│       └── predict.py               ← Model inference pipeline
├── video demo/                      ← Video demonstration folder
│   └── README.md                    ← Demo video link and summary
├── .gitignore                       ← Git ignore rules
├── LICENSE                          ← Project license
└── README.md                        ← Root documentation file

1. Go to Google AI Studio.
2. Sign in with your Google account.
3. Click "Get API Key" and then "Create API Key".
4. Create a .env file inside the project files folder and paste your key:

   GEMINI_API_KEY=your_actual_api_key_here

Open your terminal at the repository root, then execute:

# Navigate to the project directory
cd "project files"

# Create a virtual environment
python -m venv .venv

# Activate the virtual environment
.venv\Scripts\activate

# Install all required packages
pip install -r requirements.txt

# Download necessary NLTK datasets
python -c "import nltk; nltk.download('stopwords'); nltk.download('punkt'); nltk.download('punkt_tab')"

1. Go to Kaggle.
2. Create a new Notebook.
3. Enable GPU T4 x2 accelerator under Settings → Accelerator.
4. Add the following datasets via the "Add Data" sidebar:
   • google-research-datasets/go_emotions
   • atharvjairath/empatheticdialogues
   • kaggle/isear-dataset
5. Copy the code blocks from project files/notebooks/kaggle_training.ipynb into your Kaggle cells.
6. Run the notebook and download the generated output files from /kaggle/working/.
7. Move the downloaded files to their respective local folders:
   • bilstm_student_adaptive.keras → project files/models/bltsm/
   • tokenizer.pkl → project files/models/bltsm/
   • label_classes.npy → project files/models/bltsm/
   • bert_emotion_model_final/ (entire folder) → project files/models/
   • emotion_text_dataset.csv → project files/data/

# Ensure you are in the project files directory and venv is active
cd "project files"
streamlit run app.py

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

To test the server's load capacity and response times:

1. Ensure the Streamlit app (app.py) is running.
2. Open a new terminal, activate the .venv, and run:

   cd "project files"
   python performance_test.py

• 🛡️ Dual-Model Emotion Detection: Leverages a lightweight BiLSTM (for speed and user adaptation) in parallel with a deep BERT model (for semantic nuance).
• 🎭 5 Target Emotion Classes: Specifically trained on Bored, Confident, Confused, Curious, and Frustrated.
• 📊 Mixed Emotion Flagging: Detects and highlights mixed emotions if multiple targets score above the $15%$ threshold.
• ✨ Gemini AI support: Generates highly tailored learning strategies and next steps using the updated Gemini 2.5 Flash model.
• 📈 Live Analytics Dashboard: Track emotion distribution, average confidence over time, and breakdown by academic field.
• 💾 SQLite & CSV Logging: Saves transaction details to SQLite database (app.db) and CSV records for future analysis and training.

• Missing Models: Provides a friendly Streamlit landing warning if model files are missing, giving exact copy-paste paths.
• API Key Fallback: If the Gemini API key is missing or invalid, the app silently falls back to hand-crafted templates corresponding to each emotion class.
• Short Input Protection: Restricts inference on inputs under 3 characters to prevent invalid predictions on empty or short inputs.
• Auto-created storage: Database files and logging CSVs are safely auto-created at runtime on the first interaction.