fairleap-ai/fairleap-v1-earnings-xgboost-11k

<p align="center"> <img src="assets/logo.png"/> <h1 align="center">fairleap-v1-earnings-xgboost-11k</h1> </p>

An XGBoost regressor that forecasts a Gojek/GOTO driver's daily earnings in IDR from their own recent earnings history, calendar context, and a self-reported wellness score.

It is the earnings half of the Fairleap forecasting pair. Its output is also the first input feature of `fairleap-v1-laborsupply-xgboost-2k`, which forecasts hours worked.

📊 Model Details

🎯 Intended Use

Giving an individual driver a short-horizon (roughly one to fourteen day) indication of expected daily income, so that budgeting and savings advice downstream has a number to work from. The model is trained per-driver-history: it reads only that driver's own past daily totals.

Out-of-Scope Use

• —Any real financial decision. The model is trained entirely on synthetic data (see below) and its R² of 0.397 means it explains under 40% of the variance even on that synthetic test split.
• —Determining pay, eligibility, credit, or employment. Do not use these forecasts as an input to anything that decides what a person receives or is entitled to.
• —Fleet-level or market-level forecasting. There is no cross-driver, geographic, or seasonal signal in the feature set beyond day-of-week.
• —Horizons beyond ~14 days. Lag features degrade to constants past the supplied history window.

🔢 Feature Schema

Feature order is load-bearing. This is a plain XGBRegressor with no column-name validation at predict time — passing the right columns in the wrong order produces plausible numbers, not an error.

Rolling statistics are computed once from the tail of the supplied history and are therefore constant across every day in a forecast window — they are not updated recursively as the forecast walks forward. Lags fall back to NaN when they reach before the start of the supplied history; XGBoost handles NaN natively via its default split direction.

🚀 How to Use

Directly

import joblib
import pandas as pd

model = joblib.load("app/earnings_model.pkl")

FEATURES = ["day_of_week", "is_weekend", "wellness_score",
            "rolling_mean_7", "rolling_std_7", "rolling_mean_14"] + \
           [f"lag_{i}" for i in range(1, 15)]

X = pd.DataFrame([{...}], columns=FEATURES)   # order matters
earnings = abs(model.predict(X)[0])

As a service

pip install -r requirements.txt
python wsgi.py                                    # dev, port 5000
gunicorn --bind 0.0.0.0:5000 wsgi:app             # production
docker compose up                                 # container

GET / returns a healthcheck and the route table.

POST /predict/earnings — feature construction from raw daily logs is handled for you by app/regressor_utils.py:

{
  "start": "2025-05-13",
  "end": "2025-05-20",
  "wellness_score": 20,
  "daily_logs": [
    { "day": "2025-03-25", "total_earnings": 155000, "total_distance": 100.0,
      "total_fare": 150000, "total_tip": 5000, "total_trips": 8 }
  ]
}

Supply at least 14 days of daily_logs for the lag features to be populated, and 14 for rolling_mean_14. Response:

{
  "status": "success",
  "currency": "IDR",
  "predictions": [
    { "date": "2025-05-13", "earnings": 171613.640625 }
  ]
}

Predictions are passed through abs(), so the service never returns negative earnings — note this masks rather than fixes a negative prediction.

Configuration

The model is loaded at import time; a failure raises RuntimeError and the process will not start.

📚 Training Data

**fairleap-ai/fairleap-driver-earnings-regression-500** — 500 rows, MIT.

Fully synthetic ride-event records generated by data_gen.py, one row per completed ride:

🔬 Training Procedure

Lags 1–14 and 7/14-day rolling statistics are derived from the earnings column, rows with resulting NaNs are dropped, and the frame is split 80/20 with train_test_split.

XGBRegressor(n_estimators=750, learning_rate=0.3, max_depth=3, random_state=42)

📈 Evaluation

Held-out 20% split of the dataset above.

⚠️ Limitations & Bias

• —Synthetic data only. No claim this model makes about driver income reflects real Gojek/GOTO earnings. It was never validated against real driver data.
• —Weak absolute accuracy. R² = 0.397 on synthetic test data. A mean absolute error of ~52,900 IDR is large relative to the daily earnings being predicted.
• —Train/serve skew. Lags and rolling windows are built at training time over per-ride event rows — the dataset carries hour_of_day and multiple rows per driver per day. At serving time regressor_utils.py builds one row per day with lags over daily totals. lag_1 means "the previous ride" during training and "yesterday" during inference. This is a known defect, not a design choice.
• —Static rolling features. Rolling statistics do not advance across the forecast window, so every day in a multi-day forecast sees the same rolling_mean_7 / rolling_std_7 / rolling_mean_14.
• —`wellness_score` is self-reported and held constant across the window, so any bias in how drivers rate themselves is carried straight into the forecast.
• —No geographic or seasonal signal. location_cluster and preferred_location are in the dataset but not in the feature set. Holidays, weather, promotions and surge are absent entirely.
• —No uncertainty estimate. A single point prediction is returned with no interval, which overstates confidence for a model at this accuracy.

🛠️ Tech Stacks

• —xgboost: An optimized gradient boosting library designed to be highly efficient, flexible, and portable for supervised learning problems.
• —scikit-learn: A robust machine learning library that provides simple and efficient tools for data mining and data analysis.
• —pandas: A powerful data manipulation and analysis library offering labeled data structures and operations for manipulating numerical tables and time series.
• —numpy: A foundational library for numerical computing in Python, supporting large, multi-dimensional arrays and matrices.
• —joblib: A library for lightweight pipelining and efficient serialization of Python objects, often used for persisting machine learning models.
• —flask: A lightweight and flexible WSGI web application framework designed to get applications up and running quickly.
• —gunicorn: A Python WSGI HTTP server for UNIX that's commonly used to serve Flask or Django web applications in production.

⚙️ Installation

git clone https://github.com/Fairleap-AI/fairleap-v1-earnings-xgboost-11k
cd fairleap-v1-earnings-xgboost-11k
docker compose up

📝 License

This project is licensed under the MIT License.