Skip to content

README.md

Latest commit

 

History

History
200 lines (151 loc) · 7.6 KB

README.md

File metadata and controls

200 lines (151 loc) · 7.6 KB

🎓 Student Performance Tracker — AI-Powered EdTech Dashboard

An enterprise-grade, AI-powered student performance tracking and risk prediction dashboard built for Indian college counselors, HODs, and administrators. It uses Machine Learning to identify at-risk students early and provides actionable intervention plans.

Python Streamlit scikit-learn License

✨ Key Features

Feature Description
🔒 Role-Based Access Control Login system with Admin, HOD (department-filtered), and Counselor roles
📊 Risk Prediction Engine Random Forest classifier predicting Low / Moderate / High / Critical risk
🧠 Explainable AI (XAI) SHAP-based reasoning for why a student is flagged at-risk
🧪 What-If Simulator Simulate how changes in attendance/marks affect risk score
📉 Subject-Wise Failure Prediction Per-subject (Math, Physics, Programming) failure alerts
📈 Historical Risk Tracking 6-month trend line showing improvement or decline
🤖 Chatbot Assistant Natural language queries like "Show high-risk students from CSE 4th semester"
⚖️ Fairness & Bias Report Gender and department parity analysis to detect model bias
📑 CSV & PDF Export Download action lists, full reports, and individual student report cards
📤 ERP Upload Upload CSV files to ingest new student data
🔥 Burnout Detection Flags students showing burnout patterns (marks drop + low attendance + low activity)
📝 Counselor Notes & Interventions Log parent calls, counseling sessions, mentor assignments with follow-ups

🏗️ Project Structure

student-performance-tracker/
├── app.py                          # Main Streamlit dashboard (login + overview)
├── setup.py                        # One-click setup script
├── requirements.txt                # Python dependencies
├── .streamlit/
│   └── config.toml                 # Streamlit theme configuration
├── src/
│   ├── generate_data.py            # Synthetic Indian student data generator (Faker en_IN)
│   ├── db.py                       # SQLite database layer (CRUD + auth)
│   ├── train_model.py              # ML training pipeline (Random Forest + SHAP)
│   └── recommendations.py          # Rule-based action plan generator
├── pages/
│   ├── 1_Risk_Table.py             # Filterable student risk table
│   ├── 2_Student_Profile.py        # Deep-dive student profile with XAI + What-If
│   ├── 3_Analytics.py              # Advanced charts & correlations
│   ├── 4_Reports.py                # CSV export for counselor action lists
│   ├── 5_Chatbot_Assistant.py      # NLP chatbot for quick queries
│   └── 6_Fairness_Report.py        # Bias & fairness audit (Admin only)
├── data/                           # Generated at runtime (gitignored)
│   ├── .gitkeep                    # Preserves directory in Git
│   ├── synthetic_students.csv      # (generated)
│   ├── historical_risk.csv         # (generated)
│   └── students.db                 # (generated)
└── models/                         # Generated at runtime (gitignored)
    ├── .gitkeep                    # Preserves directory in Git
    ├── best_model.pkl              # (generated)
    ├── scaler.pkl                  # (generated)
    ├── features.pkl                # (generated)
    └── shap_explainer.pkl          # (generated)

🛠️ Tech Stack

Layer Technology
Frontend Streamlit, Plotly
ML/AI scikit-learn, Random Forest, SHAP, XGBoost
Data Pandas, NumPy, Faker (Indian locale)
Database SQLite
Reports FPDF2 (PDF generation)

🚀 Quick Start

Prerequisites

  • Python 3.9 or higher
  • pip (Python package manager)

1. Clone the Repository

git clone https://github.com/httpshanu/student-performance-tracker.git
cd student-performance-tracker

2. Create Virtual Environment (Recommended)

python -m venv venv

# Windows
venv\Scripts\activate

# macOS / Linux
source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Run Setup (Generate Data + Train Model)

python setup.py

This single command will:

  • Generate 2,000 synthetic Indian student records with realistic names, roll numbers, and academic data
  • Load everything into a SQLite database
  • Train a Random Forest model with SHAP explainability

5. Launch the Dashboard

streamlit run app.py

🔐 Default Login Credentials

Username Password Role Access
admin admin123 Admin Full access (all departments + fairness report)
hod_cse hod123 HOD Computer Science & Engineering only
hod_mech hod123 HOD Mechanical Engineering only
hod_civil hod123 HOD Civil Engineering only
hod_eee hod123 HOD Electrical & Electronics only
hod_bba hod123 HOD Business Administration only
hod_arts hod123 HOD Arts & Humanities only
counselor1 counselor123 Counselor All departments (no fairness report)

📊 Data Generation

The synthetic data generator (src/generate_data.py) creates realistic Indian college student data:

  • Indian names via Faker('en_IN') — e.g., Aarav Sharma, Priya Patel, Rohit Kumar
  • Indian roll numbers — format: 26CSE0001, 26MECH0042
  • 6 departments — CSE, Mechanical, Civil, EEE, BBA, Arts & Humanities
  • Indian syllabus subjects — Maths, Physics, Programming, EVS, Communication
  • Academic features — attendance, internal marks, midterms, assignments, lab scores
  • Behavioral features — library visits, consecutive absences, Monday/Friday bunk patterns, burnout flags
  • Risk scoring — weighted formula producing Low / Moderate / High / Critical labels
  • Historical data — 6 months of risk score history per student

☁️ Deploy on Streamlit Cloud

  1. Push this repository to GitHub
  2. Go to share.streamlit.io
  3. Connect your GitHub account and select this repository
  4. Set the main file path as app.py
  5. Add a pre-run script or use setup.py to generate data on first run
  6. Click Deploy

Note: For Streamlit Cloud deployment, the data and models are generated fresh on each deployment since they are gitignored.

📸 Screenshots

Run the dashboard locally to see the full UI with charts, risk tables, student profiles, and more.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

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

👤 Author

Sanid — GitHub

⚠️ Disclaimer

This project uses 100% synthetic data generated via the Faker library. No real student information is used or stored. The application is intended for demonstration and educational purposes only.

Built with ❤️ for Indian educational institutions