Skip to content

README.md

Latest commit

 

History

History
320 lines (242 loc) · 8.43 KB

README.md

File metadata and controls

320 lines (242 loc) · 8.43 KB
Raw

EduLens – Smart Academic Performance System

A full-stack machine learning application that predicts student academic performance.

Project Status: ✅ Complete

🎯 Problem Statement

Predicting student academic performance enables personalized learning recommendations.

EduLens demonstrates a complete ML workflow: synthetic data generation → preprocessing → model training → evaluation → visualization.

✨ Key Features

  • ✅ ML Models – Multiple Supervised ML Classifiers
  • ✅ Imbalanced Data Handling – SMOTE for balanced class distribution
  • ✅ Feature Engineering – PCA for dimensionality reduction
  • ✅ Full-Stack Deployment – FastAPI backend + React frontend + SQL Server database
  • ✅ Interactive Visualizations – Confusion matrices, ROC curves, model comparison charts, correlation heatmaps
  • ✅ Automated Reports – PDF performance reports with model insights
  • ✅ Training History – Persistent storage of model metrics and predictions
  • ✅ Real-Time Predictions – Predict student grades with trained models

📊 Model Performance

During Training

Screenshot 2026-08-18 132917

Note: All models trained on balanced student records. SVM achieved best performance after SMOTE optimization and PCA feature reduction.

🛠️ Tech Stack

Component Technology
Backend Python 3.10+, FastAPI, NumPy, Pandas, Scikit-learn
ML Pipeline SMOTE, PCA, Ensemble Approach, Model Evaluation
Frontend React 18, Vite, Plotly (Data Visualization), CSS3
Database Microsoft SQL Server
Deployment REST API, Web Interface

📂 Project Structure

Smart-Academic-Prediction/
│
├── backend/
│   ├── app.py                 # FastAPI application & API routes
│   ├── database.py            # SQL Server connection & queries
│   ├── preprocessing.py       # Data cleaning & feature engineering
│   ├── ml_models.py           # Model training & evaluation
│   ├── generate_dataset.py    # Synthetic data generation
│   ├── requirements.txt       # Python dependencies
│   └── data/
│       └── student_data.csv   # Synthetic dataset (2,000 records)
│
├── frontend/
│   └── edulens/
│       ├── package.json
│       ├── vite.config.js
│       ├── index.html
│       ├── src/
│       │   ├── main.jsx
│       │   ├── App.jsx
│       │   ├── App.css
│       │   ├── components/
│       │   │   ├── Dataset.jsx         # Dataset upload & management
│       │   │   ├── Training.jsx        # Model training interface
│       │   │   ├── Prediction.jsx      # Real-time predictions
│       │   │   ├── Visualization.jsx   # Charts & graphs
│       │   │   ├── Report.jsx          # Performance reports
│       │   │   └── History.jsx         # Training history
│       │   └── utils/
│       │       └── api.js              # API communication
│
├── README.md
└── LICENSE (MIT)

🎬 Video Demo

Watch EduLens in action:

EduLens Demo Video

Click to watch the demo video showing model training, predictions, and visualizations

🚀 Quick Start

Prerequisites

  • Python 3.10+
  • Node.js 16+
  • Microsoft SQL Server (local or cloud)

Installation

1. Clone Repository

git clone https://github.com/mirzaabubakar-mughal/Smart-Academic-Prediction.git
cd Smart-Academic-Prediction

2. Backend Setup

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

pip install -r requirements.txt

3. Generate Dataset

python generate_dataset.py

4. Run Backend

python app.py
# Backend runs on http://localhost:8000

5. Frontend Setup (in new terminal)

cd frontend/edulens
npm install
npm run dev
# Frontend runs on http://localhost:5173

6. Access Application Open browser → http://localhost:5173

📖 How to Use

Dataset Statistics

  1. Go to Dataset tab
  2. Click Load Synthetic Data
  3. Get detailed dataset insights

Training a Model

  1. Go to Training tab
  2. Click Start Training Button
  3. View results with performance metrices

Making Predictions

  1. Go to Prediction tab
  2. Enter student data (study hours, previous CGPA, etc.)
  3. Click Predict
  4. Get predicted grade + confidence score
  5. Final grade is based on ensemble voting of multiple classifiers

Viewing Graphs

  1. Go to Analytics tab
  2. Compare model performance
  3. View evaluation matrices & ROC curves
  4. Download report as PDF

Viewing History

  1. Go to History tab
  2. Get Training & Prediction History from database
  3. View model performance comparison

Download Report

  1. Go to Report tab
  2. Press Generate Report Button
  3. Get report as PDF

🧠 Machine Learning Pipeline

1. DATA LOADING
   ↓
2. DATA PREPROCESSING
   • Handle missing values
   • Normalize features
   • Encode categorical variables
   ↓
3. CLASS IMBALANCE HANDLING (SMOTE)
   • Oversample minority class
   • Balanced dataset for training
   ↓
4. FEATURE REDUCTION (PCA)
   • Reduced training time & improved generalization
   ↓
5. MODEL TRAINING
   • 80/20 train-test split
   ↓
6. MODEL EVALUATION
   • Accuracy, Precision, Recall, F1-Score, ROC-AUC
   ↓
7. PREDICTION & VISUALIZATION
   • Generate reports & charts
   ↓
8. PERSISTENCE
   • Store models in SQL Server
   • Track training history

📊 Dataset

Synthetic Dataset: 2,000 imbalanced student samples

Features (8 attributes):

Screenshot 2026-08-18 133945

Why Synthetic? Allows controlled testing, no privacy concerns, reproducible results.

Dataset is available on Kaggle CSV

🔄 Data Visualization

The application includes:

  • Confusion Matrix – Model prediction accuracy breakdown
  • ROC Curve – Sensitivity vs. specificity analysis
  • Model Comparison Chart – Side-by-side performance metrics
  • Grade Distribution – Target variable distribution
  • Correlation Heatmap – Feature relationships
  • PCA Visualization – Reduced feature space visualization

🚀 Future Improvements

  • Integrate Deep Learning Models – LSTM, Neural Networks for sequential patterns
  • Validate on Real-World Dataset – Integration with actual educational data
  • Add File Upload Feature – Allow users to upload CSV datasets
  • Add User Authentication Feature – Multi-user support with login
  • Add Early intervention for at-risk students – Get early student results before final exams to provide early support and guide
  • Add Automated Model Selection Feature – Auto-choose best model per dataset

🔧 Dependencies

Python (Backend)

fastapi==0.104.1
uvicorn==0.24.0
pandas==2.1.3
numpy==1.26.2
scikit-learn==1.3.2
imbalanced-learn==0.11.0  # SMOTE
plotly==5.18.0
sqlalchemy==2.0.23
pyodbc==5.1.0  # SQL Server connector

Node.js (Frontend)

react==18.2.0
vite==5.0.0
plotly.js==2.26.0
axios==1.6.2

📚 Learning Resources

This project demonstrates:

  • ✅ Complete ML workflow (end-to-end)
  • ✅ Handling imbalanced datasets (SMOTE)
  • ✅ Feature engineering & dimensionality reduction (PCA)
  • ✅ Model comparison & evaluation metrics
  • ✅ Full-stack development (Python + React + SQL)
  • ✅ Data visualization & reporting

🤝 Contributing

Contributions welcome! Feel free to:

  • Report bugs or suggest features (GitHub Issues)
  • Fork and submit pull requests
  • Share improvements or optimizations

📝 License

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

👤 Author

Mirza Abubakar

⭐ If this project helped you, please star it on GitHub!