---
library_name: sklearn
tags:
  - fairrelay
  - logistics
  - xgboost
  - sklearn
  - tabular-regression
  - delivery-time
  - eta-prediction
datasets:
  - Cainiao-AI/LaDe-D
license: mit
---

# FairRelay — Delivery Time Estimation Model (v2)

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

## Model Description

Predicts total delivery time (in minutes) for a courier's daily route based on package count, stops, distance, and temporal features. Trained on real last-mile delivery data from **Cainiao-AI/LaDe-D** (KDD 2023, Shanghai + Hangzhou, ~70K courier-days) combined with physics-informed synthetic data calibrated to FairRelay's `estimate_route_time()` formula.

**Type**: XGBRegressor Pipeline (StandardScaler + XGBoost)
**Task**: Regression (delivery time in minutes)

## Performance

- **R²**: 0.6206
- **MAE**: 73.01 minutes
- **RMSE**: 105.68 minutes
- **Median AE**: 46.03 minutes
- **MAPE**: 33.4%
- **CV R² (5-fold)**: 0.5580 ± 0.2773

## Input Features

| Feature | Importance |
|---------|-----------|
| `num_packages` | 0.1579 |
| `num_stops` | 0.2307 |
| `total_distance_km` | 0.1216 |
| `avg_distance_km` | 0.0709 |
| `spatial_spread_km` | 0.1569 |
| `start_hour` | 0.0713 |
| `active_hours` | 0.0852 |
| `packages_per_stop` | 0.1055 |


## Usage

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

# Download and load
model_path = hf_hub_download(repo_id="muthuk1/fairrelay-delivery-time", filename="model.skops")
untrusted = sio.get_untrusted_types(file=model_path)
model = sio.load(model_path, trusted=untrusted)

# Predict: [num_packages, num_stops, total_distance_km, avg_distance_km,
#            spatial_spread_km, start_hour, active_hours, packages_per_stop]
features = np.array([[25, 15, 12.5, 0.83, 5.2, 9, 6, 1.67]])
predicted_minutes = model.predict(features)
print(f"Estimated delivery time: {predicted_minutes[0]:.0f} minutes")
```

## Training Data

- **Cainiao-AI/LaDe-D**: Real last-mile delivery data (Shanghai + Hangzhou splits, ~70K courier-days from 1.5M+ individual deliveries)
- **FairRelay Synthetic**: 20K samples with physics-informed noise, calibrated to `estimate_route_time()` formula

## Part of FairRelay

FairRelay is an AI-powered logistics platform for fair load consolidation and dispatch:
- 🚚 5-agent load consolidation pipeline (KMeans + OR-Tools CP-SAT)
- ⚖️ 8-agent fair dispatch pipeline (Gini optimization)
- 📊 XGBoost effort prediction + Thompson Sampling bandit
- 🌱 EV-aware routing with battery constraints

Built for **LogisticsNow Hackathon 2026** — Challenge #5: AI Load Consolidation

## License

MIT