README.md

---
library_name: sklearn
tags:
  - fairrelay
  - logistics
  - xgboost
  - sklearn
  - tabular-regression
  - workload
  - route-optimization
license: mit
---

# FairRelay — Workload Scoring Model (v2)

Part of the **[FairRelay](https://github.com/MUTHUKUMARAN-K-1/FairRelay)** AI logistics platform.

## Model Description

Predicts delivery route workload score based on package count, weight, stops, distance, difficulty, and fragility. The workload score quantifies how demanding a route is for a driver.

**Version**: v2 — Retrained with realistic data including hidden confounders, heteroscedastic noise, non-linear interactions, and measurement error. Properly regularized to prevent overfitting.

**Type**: XGBRegressor Pipeline (StandardScaler + XGBoost)
**Task**: Regression

### v2 vs v1

| Metric | v1 | v2 |
|--------|----|----|
| Test R² | 0.9969 (suspiciously high) | **0.7577** (realistic) |
| Train-Test Gap | 0.0010 | **0.0156** |
| Why | Clean formula + 5% noise | Hidden confounders, noise, interactions |

## Performance

- **R²**: 0.7577
- **MAE**: 66.13
- **RMSE**: 86.85
- **Train-Test R² Gap**: 0.0156 (no overfitting)
- **CV R² (5-fold)**: 0.7614 ± 0.0036

## Input Features

| Feature | Importance |
|---------|-----------|
| `num_packages` | 0.1573 |
| `total_weight_kg` | 0.0183 |
| `num_stops` | 0.4728 |
| `avg_fragility` | 0.0110 |
| `total_distance_km` | 0.0080 |
| `route_difficulty_score` | 0.2582 |
| `estimated_time_minutes` | 0.0420 |
| `packages_per_stop` | 0.0212 |
| `weight_per_package` | 0.0069 |
| `distance_per_stop` | 0.0044 |


## Usage

```python
from skops import io as sio
from huggingface_hub import hf_hub_download
import numpy as np

model_path = hf_hub_download(repo_id="muthuk1/fairrelay-workload-scoring", filename="model.skops")
untrusted = sio.get_untrusted_types(file=model_path)
model = sio.load(model_path, trusted=untrusted)

# [num_packages, total_weight_kg, num_stops, avg_fragility, total_distance_km,
#  route_difficulty_score, estimated_time_minutes, packages_per_stop,
#  weight_per_package, distance_per_stop]
features = np.array([[25, 50.0, 15, 2.5, 12.0, 10.5, 120.0, 1.67, 2.0, 0.8]])
workload = model.predict(features)
print(f"Workload score: {workload[0]:.1f}")
```

## License

MIT