A production-style, refactored & beautified version of the classic "End To End Data Science Project" tutorial. Predicts a student's Math Score from demographic & academic features through a clean modular pipeline and a colorful animated Flask UI.
Python Flask scikit-learn CatBoost XGBoost License Status
Demo Quick Start API Architecture
- π₯ Data Ingestion β Loads
stud.csv, persists train/test splits toartifacts/ - π οΈ Data Transformation β Numerical scaling + categorical one-hot encoding (
ColumnTransformer) - π§ͺ Model Training β
GridSearchCVacross 8 regressors, best model saved asmodel.pkl
- π Animated gradient background with floating color blobs
- πͺ Glassmorphism cards, smooth fade-up & pop animations
- π― Animated score-meter ring + πͺ confetti on prediction
- π± Fully responsive (mobile β desktop)
- πͺ΅ Custom timestamped logger (file + console handlers)
- π¨ Custom exception class with file & line number
- πΎ Pickled artifacts via
dill - π§±
setup.pybased packaging (-e .install)
GET /β Landing pageGET|POST /predictdataβ Predict math scoreGET /healthβ JSON health & artifact check
ββββββββββββββββββββ ββββββββββββββββββββββ ββββββββββββββββββββββ
β Data Source ββββΆ β Data Ingestion ββββΆ β Data Transformationβ
β stud.csv β β (src/components) β β (ColumnTransformer)β
ββββββββββββββββββββ ββββββββββββββββββββββ βββββββββββ¬βββββββββββ
β
βΌ
ββββββββββββββββββββββ ββββββββββββββββββββββ
β Flask Web App ββββ β Model Trainer β
β (templates + UI) β β (GridSearchCV x8) β
ββββββββββββββββββββββ ββββββββββββββββββββββ
Pick one workflow that fits your machine. Do not create both a Conda
environment and a standard Python venv in the same venv directory.
:: 1) Open the project in VS Code code . :: 2) Create a local Conda env (prefix style, no global registration) conda create -p venv python==3.8 -y :: 3) (One-time) enable 'conda activate' in cmd conda init :: **Close & reopen your terminal** so the changes take effect. :: 4) Activate the env conda activate .\venv :: 5) Install local training dependencies + editable package pip install -r requirements-training.txt pip install -e .
π‘ Conda must be installed and available in the terminal. A trailing
\is not required when activating a prefix environment.
Windows PowerShell:
python -m venv venv .\venv\Scripts\Activate.ps1 pip install -r requirements-training.txt pip install -e .
Windows Command Prompt:
python -m venv venv venv\Scripts\activate.bat pip install -r requirements-training.txt pip install -e .
Windows Git Bash:
python -m venv venv source venv/Scripts/activate pip install -r requirements-training.txt pip install -e .
macOS / Linux:
python3 -m venv venv source venv/bin/activate pip install -r requirements-training.txt pip install -e .
If venv contains conda-meta but the conda command is unavailable, it is a
Conda prefix environment whose Conda installation is missing or not configured.
You can still run the project directly with that environment's Python:
PowerShell:
& .\venv\python.exe .\app.py
Command Prompt:
venv\python.exe app.py
Git Bash:
./venv/python.exe app.py
To restore normal activation, install or repair Conda and then run:
conda activate .\venv python app.py
If you prefer a fully reproducible environment from a YAML file:
conda env create -f environment.yml conda activate mlproject pip install -e .
A ready-to-use environment.yml is provided β see below.
- Windows: double-click
setup-windows.cmd - macOS / Linux:
bash setup.sh
Both scripts create the env, install deps and print the next steps.
# Training runs offline through the CLI, never through a public web endpoint.
pip install -r requirements-training.txt
python -m src.pipeline.train_pipelineThis produces:
artifacts/
βββ data.csv # raw ingested data
βββ train.csv # 80% split
βββ test.csv # 20% split
βββ preprocessor.pkl # ColumnTransformer
βββ model.pkl # best model
python app.py
Then open http://127.0.0.1:5000/ in your browser.
| Method | Route | Description |
|---|---|---|
GET |
/ |
Colorful landing page |
GET |
/predictdata |
Render the prediction form |
POST |
/predictdata |
Predict the math score from form fields |
GET |
/health |
JSON health-check incl. artifact existence |
curl -X POST http://127.0.0.1:5000/predictdata \ -d "gender=female" \ -d "race_ethnicity=group B" \ -d "parental_level_of_education=bachelor's degree" \ -d "lunch=standard" \ -d "test_preparation_course=completed" \ -d "reading_score=88" \ -d "writing_score=92"
Returns the rendered HTML containing the predicted score.
ML_Project/
βββ app.py # Flask entry-point + routes
βββ setup.py # Package configuration
βββ requirements.txt # Production/prediction server
βββ requirements-training.txt # Local training environment
βββ LICENSE
βββ README.md
βββ .env.example
βββ artifacts/ # Generated at train-time
β βββ data.csv
β βββ train.csv / test.csv
β βββ preprocessor.pkl
β βββ model.pkl
βββ logs/ # Timestamped log files
βββ notebook/
β βββ data/stud.csv
β βββ 1 . EDA STUDENT PERFORMANCE .ipynb
β βββ 2. MODEL TRAINING.ipynb
βββ src/
β βββ components/
β β βββ data_ingestion.py
β β βββ data_transformation.py
β β βββ model_trainer.py
β βββ pipeline/
β β βββ train_pipeline.py
β β βββ predict_pipeline.py
β βββ utils.py
β βββ logger.py
β βββ exception.py
βββ static/
β βββ css/style.css # Global styles
β βββ js/main.js # UI polish (confetti, meter)
βββ templates/
βββ index.html # Landing page
βββ home.html # Prediction form
| Model | Tuned? |
|---|---|
| Linear Regression | β |
| Decision Tree | β |
| Random Forest | β |
| Gradient Boosting | β |
| K-Neighbors Regressor | β |
| XGBRegressor | β |
| CatBoosting Regressor | β |
| AdaBoost Regressor | β |
The best model (by R2 on the test set) is auto-selected and serialized to artifacts/model.pkl.
- All exceptions go through
CustomException, which enriches messages with file name and line number. - Logs go to both
logs/<timestamp>.logand the console. - Input validation protects against out-of-range scores and missing artifacts.
Python Flask scikit-learn CatBoost XGBoost Pandas NumPy HTML5 CSS3 JavaScript
- Colorful animated UI with confetti & score meter
- Robust error handling & input validation
- Configurable artifact paths (BASE_DIR-based)
-
/healthAPI route - Dockerize the app
- Add CI (GitHub Actions) β lint + import sanity
- Add SHAP feature importance plot
- Add unit tests with
pytest
- The app trains from
data/stud.csvand writes generated artifacts toartifacts/. - Production/prediction server:
pip install -r requirements.txt. - Local training environment:
pip install -r requirements-training.txt. - Training must be run offline with
python -m src.pipeline.train_pipeline, not through a public web endpoint./healthverifies that required artifacts are present. - The prediction UI is designed for local Flask runs and the bundled setup scripts help reproduce the same environment on Windows, macOS, and Linux.
Contributions, issues and feature requests are welcome! Feel free to open an issue or PR.
Distributed under the MIT License. See LICENSE for the full text.
Made with β€οΈ by Asfi β’ β this repo if you found it useful!