A production-ready machine learning service for forecasting Air Quality Index (AQI) values using gradient boosting regression.

• ✅ Real-time Data: Fetches live data from Zephra API
• 🧠 ML Model: Gradient Boosting Regressor with robust error handling
• 📊 Forecasting: Single-hour and 24-hour AQI predictions
• 🌐 REST API: FastAPI with CORS support and health checks
• 🐳 Docker Ready: Containerization for easy deployment
• ☁️ Render Deploy: One-click deployment to Render platform

zephra-ml/
├── data/                   # (optional) store local datasets if needed
├── models/
│   └── gbr_model.pkl       # trained model
├── src/
│   ├── data_loader.py      # fetch from /api/dashboard
│   ├── train.py            # training + save model
│   └── forecast.py         # 24h recursive forecast
├── api/
│   └── app.py              # FastAPI/Flask app
├── requirements.txt        # dependencies
├── Dockerfile              # for deployment
├── run.sh                  # deployment script
└── README.md               # usage instructions

• Python 3.9+
• pip

1. Clone or download the project
2. Install dependencies:

   pip install -r requirements.txt

For Windows:

.\run.bat

For Linux/Mac:

./run.sh

This will automatically:

1. Install all dependencies
2. Train the model with fresh data from the Zephra API
3. Start the API server on http://localhost:8080

Test the API:

python test_api.py

First, train the model with the latest data:

python src/train.py

This will:

• Fetch data from the Zephra API
• Train a Gradient Boosting Regressor
• Save the model to models/gbr_model.pkl
• Display training RMSE

uvicorn api.app:app --host 0.0.0.0 --port 8080 --reload

docker build -t zephra-ml .
docker run -p 8080:8080 zephra-ml

Use the provided script:

./run.sh

Returns API information and version.

Returns AQI prediction for the next hour.

Response:

{
  "next_hour_AQI": 85.3
}

Returns 24-hour AQI forecast.

Response:

{
  "forecast_24h": [85.3, 87.1, 89.2, ...]
}

• Algorithm: Gradient Boosting Regressor
• Parameters:
  • n_estimators: 200
  • learning_rate: 0.05
  • max_depth: 5
  • subsample: 0.8
• Features: All columns except AQI, timestamp, and location
• Target: AQI values

1. Push code to your repository
2. Connect to Render/Heroku
3. Use the run.sh script as your start command
4. Set environment variables if needed

docker build -t zephra-ml .
docker run -p 8080:8080 zephra-ml

The model's performance is evaluated using RMSE (Root Mean Square Error) on the test set. Training metrics are displayed during model training.

• Data Source: https://zephra.onrender.com/api/dashboard
• Model Storage: models/gbr_model.pkl
• API Port: 8080
• Host: 0.0.0.0 (for Docker compatibility)

• The model assumes the last feature in the dataset is the lag AQI value for recursive forecasting
• Adjust the column names in data_loader.py and training scripts based on your actual API response structure
• The forecast uses recursive prediction where each prediction becomes input for the next step