v2-final: model card

README.md

@@ -7,8 +7,7 @@ tags:
   - sklearn
   - tabular-regression
   - workload
-datasets:
-  - Cainiao-AI/LaDe-D
+  - route-optimization
 license: mit
 ---
 
@@ -18,45 +17,43 @@ Part of the **[FairRelay](https://github.com/MUTHUKUMARAN-K-1/FairRelay)** AI lo
 
 ## Model Description
 
-Workload Scoring Model
+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, harder data to prevent overfitting and improve real-world robustness.
+**Version**: v2 — Retrained with realistic data including hidden confounders, heteroscedastic noise, non-linear interactions, and measurement error. Properly regularized to prevent overfitting.
 
-**Type**: XGBoost Pipeline (StandardScaler + XGBoost)
+**Type**: XGBRegressor Pipeline (StandardScaler + XGBoost)
 **Task**: Regression
 
-### v2 Improvements Over v1
+### v2 vs v1
 
-- **Hidden confounders**: Weather, traffic, building access affect ground truth but aren't in features
-- **Heteroscedastic noise**: Harder cases have more unpredictable outcomes
-- **Non-linear interactions**: Weight × stairs, packages × rain compound effects
-- **Measurement error**: Features have ±5-15% sensor/estimation noise
-- **Boundary ambiguity**: Near-threshold cases have noisy labels (simulating dispatcher disagreement)
-- **Diverse distributions**: Normal, skewed, bimodal, heavy-tail effort patterns
+| 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.7536
-- **MAE**: 66.52
-- **RMSE**: 87.59
-- **Train-Test Gap**: 0.0746
-- **CV R² (5-fold)**: 0.7582 ± 0.0031
-
+- **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.0373 |
-| `total_weight_kg` | 0.0161 |
-| `num_stops` | 0.7064 |
-| `avg_fragility` | 0.0145 |
-| `total_distance_km` | 0.0103 |
-| `route_difficulty_score` | 0.1742 |
-| `estimated_time_minutes` | 0.0101 |
-| `packages_per_stop` | 0.0101 |
-| `weight_per_package` | 0.0116 |
-| `distance_per_stop` | 0.0094 |
+| `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
@@ -70,14 +67,14 @@ model_path = hf_hub_download(repo_id="muthuk1/fairrelay-workload-scoring", filen
 untrusted = sio.get_untrusted_types(file=model_path)
 model = sio.load(model_path, trusted=untrusted)
 
-prediction = model.predict(features)
+# [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}")
 ```
 
-## Part of FairRelay
-
-FairRelay is an AI-powered logistics platform for fair load consolidation and dispatch.
-Built for **LogisticsNow Hackathon 2026** — Challenge #5: AI Load Consolidation.
-
 ## License
 
 MIT