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.
| 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 |
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)
| 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) |
- Python 3.9 or higher
- pip (Python package manager)
git clone https://github.com/httpshanu/student-performance-tracker.git
cd student-performance-trackerpython -m venv venv
# Windows
venv\Scripts\activate
# macOS / Linux
source venv/bin/activatepip install -r requirements.txtpython setup.pyThis 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
streamlit run app.py| 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) |
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
- Push this repository to GitHub
- Go to share.streamlit.io
- Connect your GitHub account and select this repository
- Set the main file path as
app.py - Add a pre-run script or use
setup.pyto generate data on first run - Click Deploy
Note: For Streamlit Cloud deployment, the data and models are generated fresh on each deployment since they are gitignored.
Run the dashboard locally to see the full UI with charts, risk tables, student profiles, and more.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
Sanid — GitHub
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