⚡ EY ML Playground: Automated Machine Learning Platform

Welcome to the EY ML Playground! This application allows users to upload standard business spreadsheets (such as CSV or Excel files) and automatically train, evaluate, and deploy machine learning models without writing a single line of code.

Whether you want to forecast revenue, predict customer churn, or classify data categories, the EY ML Playground handles data preprocessing, model selection, hyperparameter tuning, and real-time scenario predictions automatically.

---

📋 Prerequisites

Before running the application, ensure you have one of the following setups:

• Option A (Recommended): Docker Desktop (Works on Windows, macOS, and Linux).
• Option B (Manual Setup):
  • Python 3.10+
  • Node.js 18+ and npm

---

🚀 Quick Start: How to Run the App

🐳 Method 1: Running with Docker (Recommended)

The easiest way to run the entire application (Backend + Frontend) on any computer is using Docker Compose:

1. Open your terminal or command prompt and navigate to the project directory:

   cd ML_Inventory_Jul14

2. Start the application with Docker Compose:

   docker compose up --build

3. Open your browser:

   • 🎨 Web Dashboard: http://localhost:5173
   • ⚡ Backend API Documentation: http://localhost:7860/docs

For more details on Docker configurations, see DOCKER_GUIDE.md.

---

🛠️ Method 2: Running Manually (Without Docker)

If you prefer running the backend and frontend services directly on your system, open two separate terminal windows:

Terminal 1 — Backend Server (FastAPI)

1. Navigate to the project root folder:

   cd ML_Inventory_Jul14

2. Set up and activate a Python virtual environment:

   • macOS / Linux:

     python3 -m venv venv
     source venv/bin/activate

   • Windows (PowerShell):

     python -m venv venv
     .\venv\Scripts\Activate.ps1

3. Install required Python packages:

   pip install -r requirements.txt

4. Start the FastAPI backend server:

   python -m uvicorn api.main:app --reload --port 7860

   (Keep this terminal running. The API runs at http://127.0.0.1:7860)

---

Terminal 2 — Frontend Interface (Vite / React)

1. Open a new terminal tab/window and navigate to the ml folder:

   cd ML_Inventory_Jul14/ml

2. Install Node.js dependencies (first time only):

   npm install

3. Start the Vite React development server:

   npm run dev

4. Open the link displayed in the terminal (typically http://localhost:5173).

---

💡 Core Machine Learning Concepts

If you are new to Machine Learning, here are the key concepts used in the dashboard:

• Target Column: The specific column you want to predict (e.g., Sales, Churn, or Price). The target detector automatically suggests the target column and task type (Classification, Regression, or Forecasting).
• Features: The input columns used by the model to make predictions (e.g., Marketing_Budget, Region, Customer_Age).
• Train / Test Split: Data is divided into two sets:
  • Training Set (e.g., 80%): Used by the machine learning algorithm to learn patterns.
  • Test Set (e.g., 20%): Held back to evaluate model performance on unseen data.
• Data Quality Audit & Anomalies: The app automatically flags missing values, statistical outliers, and quality scores to clean data before training.

---

🗺️ Step-by-Step Dashboard Walkthrough

📂 Stage 1: Data Ingestion & Quality Audit

1. Upload Dataset: Import any .csv or .xlsx file.
2. Audit Data Quality: View the automated Data Quality Score, missing value indicators, and outlier flags.
3. Select Target Column: Choose what you want to predict. The app auto-detects whether the problem is Regression, Classification, or Forecasting.

⚙️ Stage 2: Feature Engineering & Preprocessing

1. Select Features: Include or exclude specific variables from training.
2. Configure Train/Test Split: Adjust split percentages (e.g., 80/20) and choose between random or chronological splitting.
3. Cyclical & DateTime Normalization: Automatically extract month, day, quarter, and sin/cos cyclical transformations for time series data.

📊 Stage 3: Training & Interactive Prediction Playground

1. Train Models: Click Execute Target Model Tasks to train multiple algorithms (XGBoost, LightGBM, CatBoost, Scikit-learn models) with automated hyperparameter optimization.
2. Leaderboard Comparison: Compare models by R² score, RMSE, accuracy, and training duration.
3. Interactive "What-If" Predictions: Input scenario parameters directly in the UI to generate real-time predictions with confidence intervals.
4. Bulk Scenario Testing: Upload secondary spreadsheets to generate predictions across hundreds of rows simultaneously.

---

🛠️ Troubleshooting

Issue	Cause	Solution
Connection Error (Unable to connect to server)	Backend server is not running on port 7860.	Ensure uvicorn (or Docker container) is active on port 7860.
Frontend running on Port 5174 instead of 5173	Port 5173 was busy on host system.	Vite automatically uses the next open port (5174/5175). Check terminal output for exact URL.
Module Not Found / Rollup Errors (Node.js)	Platform-specific optional dependency missing.	Run npm install inside the ml/ directory.
Invalid Login Credentials	No user account created yet.	Click the Sign Up tab on the login screen to register a local user account.

---

📄 License & System Requirements

Designed for cross-platform deployment on macOS, Linux, and Windows systems.