Metadata-Version: 2.4
Name: waste-forecasting-model
Version: 2.3.1
Summary: Portable waste-prediction model V2 + Federated Learning adapter with S3 support
Author: Research Project Team
License: MIT
Keywords: machine-learning,federated-learning,waste-prediction,ensemble,sqs
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: xgboost>=2.0.0
Requires-Dist: lightgbm>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pandas-stubs; extra == "dev"
Provides-Extra: sqs
Requires-Dist: boto3>=1.34; extra == "sqs"
Dynamic: license-file

# Waste Forecasting Model

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://badge.fury.io/py/waste-forecasting-model.svg)](https://badge.fury.io/py/waste-forecasting-model)

## 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

```bash
# Basic installation
pip install waste-forecasting-model

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

### Simple Usage

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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:

```python
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

```bash
# 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

```bibtex
@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.
