BigMart Sales Prediction - ML Deployment System

Crafted by Vijay Kumar Kushwaha

A production-ready machine learning system for predicting retail sales, featuring a REST API, modern web interface, comprehensive monitoring, and detailed documentation.

⚡ Features

• 🤖 ML-Powered Predictions: Gradient Boosting model with 60% R² accuracy
• 🚀 FastAPI Backend: RESTful API with automatic documentation
• 💎 Modern Web UI: Premium dark-mode interface with glassmorphism
• 📊 Real-time Analytics: Model performance metrics and API statistics
• 📝 Comprehensive Logging: Structured JSON logs with rotation
• 📈 Prometheus Metrics: Production-ready monitoring
• 📦 Batch Processing: Upload CSV for bulk predictions
• ✅ Input Validation: Pydantic schemas ensure data quality

🏗️ Architecture

graph LR
    A[Web Frontend] -->|HTTP| B[FastAPI Server]
    B --> C[ML Service]
    C --> D[Trained Model]
    B --> E[Logger]
    B --> F[Metrics Collector]
    E --> G[Log Files]
    F --> H[Prometheus]

Loading

🚀 Quick Start

Prerequisites

• Python 3.8+
• 4GB RAM
• Modern web browser

Installation

1. Clone and Navigate

cd BigMart_dataset

2. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate  # Windows

3. Install Dependencies

pip install -r requirements.txt

4. Train the Model

python train_model.py

Expected output:

🏆 Best Model: Gradient Boosting
   Test R²: 0.6049
   RMSE: 1036.29
✅ Model training completed!

5. Start API Server

uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

6. Open Frontend

# In a new terminal
cd frontend
python3 -m http.server 8080

Then open: http://localhost:8080

📚 Project Structure

BigMart_dataset/
├── api/                      # FastAPI application
│   ├── main.py              # App entry point
│   ├── endpoints.py         # API routes
│   ├── schemas.py           # Pydantic models
│   ├── ml_service.py        # ML inference
│   ├── logger.py            # Logging config
│   └── monitoring.py        # Metrics collection
├── frontend/                 # Web interface
│   ├── index.html           # Main page
│   ├── styles.css           # Premium CSS
│   └── script.js            # API integration
├── docs/                     # Documentation
│   ├── MODEL_PIPELINE.md    # ML pipeline details
│   ├── API_DOCUMENTATION.md # API reference
│   ├── DEPLOYMENT_GUIDE.md  # Deployment instructions
│   └── USER_GUIDE.md        # End-user guide
├── logs/                     # Application logs
├── train_model.py           # Model training script
├── app.py                   # Streamlit app (legacy)
├── bigmart.csv              # Training dataset
├── requirements.txt         # Dependencies
└── README.md                # This file

🎯 Usage

Single Prediction

Via Web UI:

1. Open http://localhost:8080
2. Fill in product and outlet details
3. Click "Predict Sales"

Via API (curl):

curl -X POST http://localhost:8000/api/v1/predict \
  -H "Content-Type: application/json" \
  -d '{
    "Item_Weight": 9.3,
    "Item_Visibility": 0.016,
    "Item_MRP": 249.81,
    "Outlet_Age": 26,
    "Item_Fat_Content": "Low Fat",
    "Item_Type": "Dairy",
    "Outlet_Size": "Medium",
    "Outlet_Location_Type": "Tier 2",
    "Outlet_Type": "Supermarket Type1"
  }'

Via Python:

import requests

response = requests.post(
    "http://localhost:8000/api/v1/predict",
    json={
        "Item_Weight": 9.3,
        "Item_Visibility": 0.016,
        "Item_MRP": 249.81,
        "Outlet_Age": 26,
        "Item_Fat_Content": "Low Fat",
        "Item_Type": "Dairy",
        "Outlet_Size": "Medium",
        "Outlet_Location_Type": "Tier 2",
        "Outlet_Type": "Supermarket Type1"
    }
)
print(response.json())

Batch Prediction

Upload a CSV file via the web UI or use the API:

import requests

with open('products.csv', 'rb') as f:
    response = requests.post(
        "http://localhost:8000/api/v1/batch-predict",
        files={'file': f}
    )
print(response.json())

📊 Model Performance

Metric	Value	Description
R² Score	0.6049	Explains 60% of sales variance
RMSE	₹1,036	Root mean squared error
MAE	₹722	Mean absolute error
Model	Gradient Boosting	100 estimators
Features	32	4 numerical + 28 categorical
Training Samples	6,818	80% of dataset

🔍 API Endpoints

Endpoint	Method	Description
/api/v1/predict	POST	Single prediction
/api/v1/batch-predict	POST	Batch predictions
/api/v1/health	GET	Health check
/api/v1/model-info	GET	Model metadata
/api/v1/metrics	GET	Prometheus metrics
/api/v1/stats	GET	API statistics
/docs	GET	Swagger UI
/redoc	GET	ReDoc UI

📝 Documentation

• Model Pipeline: Data preprocessing, feature engineering, model training
• API Documentation: Complete API reference with examples
• Deployment Guide: Local and production deployment
• User Guide: Step-by-step user instructions

🛠️ Development

Running Tests

# Test API health
curl http://localhost:8000/api/v1/health

# View logs
tail -f logs/api.log
tail -f logs/predictions.log

# View metrics
curl http://localhost:8000/api/v1/metrics

Monitoring

Access real-time metrics:

• API Stats: http://localhost:8000/api/v1/stats
• Prometheus: http://localhost:8000/api/v1/metrics
• Logs: logs/ directory

🚢 Deployment

Docker

docker build -t bigmart-api .
docker run -p 8000:8000 bigmart-api

Systemd Service

sudo cp bigmart-api.service /etc/systemd/system/
sudo systemctl enable bigmart-api
sudo systemctl start bigmart-api

See Deployment Guide for detailed instructions.

🎨 Screenshots

Web Interface

• Modern dark-mode design with glassmorphism
• Responsive layout for mobile and desktop
• Real-time prediction results with animations
• Batch upload with drag-and-drop
• Analytics dashboard with live metrics

API Documentation

• Auto-generated Swagger UI at /docs
• Interactive API testing
• Complete request/response schemas

🔧 Technology Stack

• Backend: FastAPI, Uvicorn, Python 3.11
• ML: scikit-learn, XGBoost, pandas, NumPy
• Frontend: HTML5, CSS3 (Vanilla), JavaScript (ES6+)
• Monitoring: Prometheus, structured JSON logging
• Validation: Pydantic v2
• Deployment: Docker, systemd, cloud-ready

📈 Future Enhancements

• Add authentication (API keys, JWT)
• Implement rate limiting
• Add model retraining pipeline
• Create mobile app
• Add A/B testing for model versions
• Implement caching (Redis)
• Add more visualizations
• Export predictions to Excel/PDF

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

This project is open source and available under the MIT License.

👤 About the Author

Vijay Kumar Kushwaha

I am a passionate learner exploring AI, machine learning, and data science. This project demonstrates end-to-end ML deployment from data exploration to production-ready APIs. I'm always open to collaboration and feedback!

---

📞 Contact & Support

• Issues: Open a GitHub issue
• Documentation: See docs/ directory
• Email: Contact through GitHub profile

---

⭐ If you found this project helpful, please consider starring the repository!

Last Updated: December 18, 2025
Version: 1.0.0