waste-forecasting-model 2.3.0

Portable waste-prediction model V2 + Federated Learning adapter with S3 support

Waste Forecasting Model

Production-ready waste prediction model for solar salt production facilities.

Features

• 🎯 14 waste output predictions - Total waste, solid components, bittern volume & ion concentrations
• 🚀 High-performance ensemble - Gradient Boosting + Stacked Models + Neural Network (R² = 0.863)
• 🔄 Federated Learning ready - Built-in FL adapter for distributed training
• ☁️ S3 model management - Download and hot-reload models from cloud storage
• 🧵 Thread-safe - Lazy loading with proper locking for multi-threaded servers
• 📦 Type-safe API - Fully typed with dataclass inputs/outputs

Quick Start

Installation

# Basic installation
pip install waste-forecasting-model

# With S3 support
pip install waste-forecasting-model[sqs]

Simple Usage

from model_lib import predict_waste

# Single prediction
result = predict_waste(
    production_volume=50000,      # kg
    rain_sum=200,                 # mm
    temperature_mean=28,          # °C
    humidity_mean=85,             # %
    wind_speed_mean=15,           # km/h
    month=6,
    year=2026
)

print(f"Total Waste: {result['Total_Waste_kg']:.2f} kg")
print(f"Gypsum: {result['Solid_Waste_Gypsum_kg']:.2f} kg")
print(f"Bittern: {result['Liquid_Waste_Bittern_Liters']:.2f} L")

Advanced Usage

from model_lib import WastePredictor

# Create predictor (loads model once)
predictor = WastePredictor()

# Single prediction with typed result
result = predictor.predict(
    production_volume=50000,
    rain_sum=200,
    temperature_mean=28,
    humidity_mean=85,
    wind_speed_mean=15,
    month=6
)

# Access typed fields
print(f"Total Waste: {result.total_waste_kg:.2f} kg")
print(f"Gypsum: {result.solid_waste_gypsum_kg:.2f} kg")
print(f"Mg Concentration: {result.bittern_mg_concentration_gl:.2f} g/L")

# Batch predictions
import pandas as pd
df = pd.DataFrame([...])  # Your input data
predictions = predictor.predict_batch(df)

Model Outputs

The model predicts 14 waste composition metrics:

Solid Waste

• Total Waste (kg)
• Gypsum (kg)
• Limestone (kg)
• Industrial Salt (kg)
• Total Solid Waste (kg)

Liquid Waste (Bittern)

• Bittern Volume (Liters)
• Mg Concentration (g/L)
• K Concentration (g/L)
• SO₄ Concentration (g/L)
• Ca Concentration (g/L)
• Magnesium Mass (kg)
• Potassium Mass (kg)
• Sulfate Mass (kg)
• Calcium Mass (kg)

API Integration Examples

Flask

from flask import Flask, request, jsonify
from model_lib import WastePredictor

app = Flask(__name__)
predictor = WastePredictor()

@app.route('/predict', methods=['POST'])
def predict():
    result = predictor.predict_dict(request.json)
    return jsonify({"success": True, "prediction": result})

FastAPI

from fastapi import FastAPI
from model_lib import WastePredictor, PredictionInput

app = FastAPI()
predictor = WastePredictor()

@app.post("/predict")
async def predict(req: PredictionInput):
    result = predictor.predict_typed(req)
    return result.to_dict()

AWS Lambda

from model_lib import WastePredictor

predictor = WastePredictor()

def lambda_handler(event, context):
    result = predictor.predict_dict(event)
    return {'statusCode': 200, 'body': result}

Model Management

Model File Location

The package searches for waste_predictor_v1.pkl in:

1. $WASTE_PREDICTOR_MODEL_PATH (environment variable)
2. ~/.model_lib/waste_predictor_v1.pkl
3. Package artifacts (bundled with installation)
4. Current working directory

S3 Model Download

from model_lib import WastePredictor

predictor = WastePredictor()

# Download and hot-reload new model
info = predictor.download_and_update_model(
    "s3://my-bucket/models/waste_predictor_v1.pkl"
)
print(f"Updated to version: {info['version']}")

Federated Learning

Built-in adapter for distributed training via SQS:

from model_lib.fl_adapter import WastePredictorFLAdapter

adapter = WastePredictorFLAdapter()

# Local training
params = adapter.local_train(train_df, epochs=50)

# Server-side aggregation
aggregated = WastePredictorFLAdapter.aggregate(
    params_list=[client1_params, client2_params],
    weights=[100, 150]  # num_samples
)

Model Architecture

V2 Ensemble Model:

• Gradient Boosting (XGBoost) - Weight: 0.336
• Stacked Ensemble (XGB + LightGBM + RF + GBR) - Weight: 0.338
• Deep Neural Network (PyTorch) - Weight: 0.326

Performance:

• Overall R²: 0.863
• Solid waste predictions: R² > 0.97
• Bittern volume: R² = 0.975
• Ion concentrations: R² > 0.66

Requirements

• Python 3.10+
• PyTorch 2.0+
• scikit-learn 1.3+
• XGBoost 2.0+
• LightGBM 4.0+
• pandas 2.0+

Development

# Install in editable mode with dev dependencies
pip install -e .[dev,sqs]

# Run tests
pytest

# Format code
black model_lib/
ruff check model_lib/

License

MIT License - See LICENSE file for details

Citation

@software{waste_forecasting_model_2026,
  title={Waste Forecasting Model for Solar Salt Production},
  author={Research Project Team},
  year={2026},
  version={2.2.0}
}

Support

For issues, questions, or contributions, please open an issue on GitHub.