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