Ten scikit-learn models for retail and consumer analytics framed around Kuwait and the GCC: customer lifetime value, loyalty churn, Ramadan sales, basket size, mall footfall, price sensitivity, product returns, luxury demand, flash-sale conversion and omnichannel revenue attribution. One script, gcc_retail_ai.py, generates a synthetic dataset for each task (12,000 rows each). It then compares five candidate algorithms with 3-fold cross-validation and saves the best one per task as a joblib pickle. The models are trained only on simulated data. They are demonstrations and templates, not validated business tools.
Author: AgenThink, Kuwait City
Test metrics are on a 20% held-out split of the same synthetic data (random_state=42). CV is the mean 3-fold cross-validation score on the 80% training split. All numbers come from automl_results.json. Money values are in KWD.
| # | File | Task | Type | Selected algorithm | CV score | Test score | Test MAE |
|---|---|---|---|---|---|---|---|
| 1 | model_clv.pkl |
Customer Lifetime Value | Regression | RandomForest | R² 0.9976 | R² 0.9983 | 460.53 KWD |
| 2 | model_loyalty_churn.pkl |
Loyalty Program Churn Prediction | Classification | GradientBoosting | Acc 0.9524 | Acc 0.9554 | – |
| 3 | model_ramadan_sales.pkl |
Ramadan Sales Forecasting | Regression | Ridge | R² 0.8549 | R² 0.8788 | 847.57 KWD |
| 4 | model_basket_size.pkl |
Basket Size Prediction | Regression | Ridge | R² 0.9800 | R² 0.9787 | 7.91 KWD |
| 5 | model_mall_footfall.pkl |
Mall Footfall Forecasting | Regression | GradientBoosting | R² 0.9184 | R² 0.9187 | 1,680.01 visitors |
| 6 | model_price_sensitivity.pkl |
Price Sensitivity Scoring | Regression | Ridge | R² 0.7822 | R² 0.778 | 0.082 (elasticity) |
| 7 | model_product_return.pkl |
Product Return Prediction | Classification | LogisticRegression | Acc 0.9611 | Acc 0.9571 | – |
| 8 | model_luxury_demand.pkl |
Luxury Goods Demand Forecasting | Regression | GradientBoosting | R² 0.8256 | R² 0.8289 | 6.19 (index) |
| 9 | model_flash_sale.pkl |
Flash Sale Conversion Rate | Regression | Ridge | R² 0.9303 | R² 0.9356 | 0.024 (rate) |
| 10 | model_attribution.pkl |
Omnichannel Revenue Attribution | Regression | GradientBoosting | R² 0.9354 | R² 0.935 | 17.35 KWD |
The candidates were RandomForest, GradientBoosting, ExtraTrees, DecisionTree, and either Ridge (for regression) or LogisticRegression (for classification). The CV score of every candidate is stored under all_scores in automl_results.json. The saved estimator classes match the best_algo values in the JSON. The script's docstring lists Flash Sale Conversion as a classification task, but it is trained and saved as a regressor that predicts a conversion rate.
The script generates this dashboard. It shows the test score for each model, plots of the synthetic data, feature importances and a heatmap of the algorithm comparison.
| File | Description |
|---|---|
README.md |
This model card |
gcc_retail_ai.py |
Full pipeline: synthetic data generation, AutoML selection, evaluation, dashboard, and saving of models and results |
automl_results.json |
For each model: task, type, selected algorithm, CV and test metrics, CV scores of all candidates, ordered feature list, feature importances, and a free-text gcc_note |
gcc_retail_ai_dashboard.png |
Performance and data dashboard (about 1 MB) |
model_*.pkl (10 files) |
Fitted scikit-learn estimators saved with joblib. model_clv.pkl is about 10 MB (a random forest); the others are small. The pickles record scikit-learn 1.8.0 as the training version |
All training data is synthetic. The script generates it with NumPy (np.random.seed(42)) from hand-chosen distributions. It does not ship the data; running the script recreates it. Each task has 12,000 independent rows and 20 input features.
1 if its score is at or above a quantile: 0.78 for churn, giving about 22% positives, and 0.82 for returns, about 18%.category, store_type, customer_segment, channel and payment_type are integer codes (for example 1–8). Their mapping to real categories is not documented.gcc_note strings in the JSON are the author's contextual remarks, for example "Post-Iftar 8-11pm is GCC retail's peak window". They are not derived from or validated by data.Feature order matters. The order below matches features in automl_results.json and model.feature_names_in_.
clv_kwd (50–50,000). Features: age, is_national, monthly_income_kwd, tenure_months, purchase_freq_mo, avg_order_kwd, category_diversity, loyalty_tier, online_pct, ramadan_spend_boost, eid_spend_boost, referred_friends, app_engagement, returns_rate, credit_card_user, family_size, nps_score, social_media_influence, subscription_holder, years_in_gccchurns (0/1). Features: tenure_months, loyalty_tier, points_balance, points_expiring_soon, months_inactive, purchase_freq_drop, competitor_offer, app_logins_mo, email_open_rate, complaint_count, last_redemption_days, is_national, age, family_account, ramadan_engagement, nps_score, avg_order_kwd, channel_shift, price_sensitivity, vip_event_attendedsales_kwd (200–300,000). Features: day_of_ramadan, hour, category, store_type, year, is_weekend, is_last_10_days, prev_year_sales_kwd, temperature_c, promotions_active, discount_depth, competitor_promo, staff_level, inventory_level, online_share, footfall_idx, expat_pct, iftar_time_hr, suhoor_spike, charity_giving_spikebasket_kwd (5–1,500). Features: customer_segment, store_format, hour, day_of_week, is_ramadan, is_eid, is_weekend, loyalty_tier, income_tier, family_size, promotion_active, discount_kwd, prev_basket_kwd, items_count, fresh_food_pct, private_label_pct, time_in_store_min, uses_list, payment_type, temperature_cfootfall (500–120,000). Features: mall_tier, hour, day_of_week, month, is_ramadan, is_eid, is_summer, temperature_c, is_weekend, event_happening, school_holiday, prayer_time, rain, sandstorm, anchor_store_promo, parking_capacity_pct, new_store_opened, competitor_mall_event, public_holiday, prev_week_footfallprice_elasticity (−1.5 to 0). Features: income_tier, is_national, age, category, brand_loyalty_score, price_comparison_freq, coupon_usage, private_label_affinity, oil_economy_phase, household_size, has_children, monthly_spend_kwd, deals_app_user, impulse_buyer, bulk_buyer, luxury_affinity, online_shopper, subscription_user, expat_remittance, recession_worriedreturned (0/1). Features: category, price_kwd, channel, customer_tier, days_to_return, size_issue, quality_complaint, gift_purchase, impulse_purchase, description_mismatch, is_ramadan, is_eid, prev_return_rate, free_return_policy, influencer_purchase, size_chart_viewed, reviews_read, payment_type, first_purchase, luxury_brandluxury_demand_idx (10–200). Features: brand_tier, category, month, is_eid, is_ramadan, oil_price_usd, gcc_gdp_growth, tourist_arrivals_k, national_income_idx, social_media_buzz, celebrity_endorsement, new_collection, gifting_season, gold_price_idx, youth_bulge, female_consumer_pct, duty_free_competition, counterfeit_pressure, store_experience, loyalty_vip_countconversion_rate (0.01–0.95). Features: discount_depth, sale_duration_hr, category, original_price_kwd, stock_units, customer_segment, notification_sent, email_push, sms_push, social_promotion, hour_launched, is_ramadan, is_eid, day_of_week, prev_sale_conversion, influencer_amplified, loyalty_exclusive, app_only, bundle_offer, free_shippingonline_revenue_attributed (KWD, 1–5,000). Features: touchpoints_count, instagram_touch, snapchat_touch, tiktok_touch, whatsapp_touch, email_touch, sms_touch, store_visit, app_browse, web_browse, influencer_touch, paid_search, days_to_purchase, is_ramadan, is_eid, customer_age, order_value_kwd, first_touch_channel, last_touch_channel, device_typeFor the Ridge and LogisticRegression models, the feature_importance values in the JSON are normalized absolute coefficients on unscaled inputs. They depend on feature scale.
The models are plain scikit-learn estimators saved with joblib. Use scikit-learn 1.8.x to avoid unpickling problems.
# pip install scikit-learn==1.8.* pandas joblib huggingface_hub
import json, joblib, pandas as pd
from huggingface_hub import hf_hub_download
repo = "agenthinkmesh/gcc_retail_ai"
results = json.load(open(hf_hub_download(repo, "automl_results.json"), encoding="utf-8"))
model = joblib.load(hf_hub_download(repo, "model_loyalty_churn.pkl"))
features = results["loyalty_churn"]["features"] # same order as model.feature_names_in_
row = {
"tenure_months": 14.0, "loyalty_tier": 2, "points_balance": 1200.0, "points_expiring_soon": 1,
"months_inactive": 6.0, "purchase_freq_drop": 0.5, "competitor_offer": 1, "app_logins_mo": 0,
"email_open_rate": 0.2, "complaint_count": 2, "last_redemption_days": 240.0, "is_national": 0,
"age": 34, "family_account": 0, "ramadan_engagement": 0, "nps_score": 4.0,
"avg_order_kwd": 45.0, "channel_shift": 1, "price_sensitivity": 4, "vip_event_attended": 0,
}
X = pd.DataFrame([row], columns=features)
print("churn probability:", model.predict_proba(X)[0, 1])
Regression models work the same way: build a one-row DataFrame with that model's features and call model.predict(X). Loading a pickle can execute arbitrary code, so only load files from sources you trust.
pip install numpy pandas matplotlib scikit-learn joblib
# The output directory is hard-coded: edit OUT = "/home/claude/gcc_retail_ai" near the top of the script first
python gcc_retail_ai.py
The script regenerates the data, all 10 models, automl_results.json, the dashboard and a short README.md. It will overwrite a README in the output directory.
Out of scope: real pricing, credit, marketing-targeting or customer-treatment decisions without retraining and validation on real data.
is_national in CLV, churn and price sensitivity; expat_remittance in price sensitivity; expat_pct in Ramadan sales. Using such scores to set prices, offers or service levels for individuals could be discriminatory or unlawful. Any real use needs a legal and fairness review and human oversight.MIT
@misc{agenthink2026gccretail,
author = {AgenThink},
title = {GCC Retail \& Consumer AI},
year = {2026},
publisher = {Hugging Face},
howpublished = {\url{https://huggingface.co/agenthinkmesh/gcc_retail_ai}}
}