Upload MzansiScore model artifacts

README.md

@@ -0,0 +1,106 @@
+---
+pipeline_tag: tabular-classification
+library_name: scikit-learn
+tags:
+- credit-risk
+- south-africa
+- xgboost
+- lightgbm
+- tabular-classification
+- fastapi
+- synthetic-data
+model-index:
+- name: Pieter182/mzansiscore-credit-risk
+  results:
+  - task:
+      type: tabular-classification
+      name: Credit default risk prediction
+    dataset:
+      name: Synthetic South African credit applications
+      type: tabular
+    metrics:
+    - type: roc_auc
+      value: 0.9243
+    - type: gini
+      value: 0.8486
+    - type: brier_score
+      value: 0.0883
+---
+
+# MzansiScore Credit Risk Model
+
+MzansiScore is a synthetic South African credit risk model pack for probability-of-default scoring, affordability-aware decisioning, and explainable API deployment.
+
+## Repository contents
+
+This repository is expected to contain:
+
+- `best_tree_model.joblib` — best-performing tree model selected during training
+- `logistic_regression.joblib` — interpretable regulatory baseline
+- `feature_cols.joblib` — ordered feature columns used by the tree model
+- `label_encoders.joblib` — fitted encoders for categorical features
+- `model_meta.json` — metrics, governance metadata, fairness summaries, and rationale catalog
+- `README.md` — this model card
+
+## Model summary
+
+- Primary selected model artifact: **XGBoost**
+- Published scoring artifact summary: **XGBoost_cal**
+- Holdout AUC: **0.9243**
+- Holdout Gini: **0.8486**
+- Holdout Brier score: **0.0883**
+- Training rows: **133108**
+- Holdout rows: **33278**
+- Train default rate: **23.46%**
+- Holdout default rate: **23.46%**
+- Positive-class weighting: **3.26**
+
+## Regulatory and governance context
+
+- Geography: **South Africa**
+- Training data: **synthetic** loan application and affordability data
+- Policy overlay: **nca_affordability_pass**
+- Policy description: Applicants failing affordability are declined outside the model.
+- Proxy score features are excluded from regulated training by default
+- Fairness summaries are recorded in `model_meta.json`
+- Adverse-action rationale templates are recorded in `model_meta.json`
+
+## Top feature drivers
+
+| Feature | Importance |
+|---|---:|
+| affordability_surplus | 0.7421 |
+| combined_risk | 0.5698 |
+| credit_score | 0.3508 |
+| expense_understatement_flag | 0.3242 |
+| worst_status_12m | 0.2179 |
+| affordability_margin | 0.2073 |
+| worst_status_3m | 0.1864 |
+| debit_order_returns_3m | 0.1527 |
+| affordability_surplus_ratio | 0.1526 |
+| age | 0.1197 |
+
+## Intended use
+
+Use this model pack for:
+
+1. Demo scoring APIs
+2. Explainable credit-risk dashboard prototypes
+3. Internal experimentation on calibrated probability-of-default workflows
+
+## Limitations
+
+- The underlying data is synthetic and should not be treated as live production applicant data.
+- This repository is not a substitute for formal model validation, governance approval, or legal review.
+- Production credit decisions should include affordability, compliance, monitoring, and human oversight controls.
+
+## Example deployment flow
+
+1. Download artifacts from the HuggingFace model repository.
+2. Load `best_tree_model.joblib`, `feature_cols.joblib`, and `label_encoders.joblib`.
+3. Rebuild engineered features before inference.
+4. Apply policy rules alongside predicted default probability.
+
+## Training notes
+
+The current training pipeline compares Logistic Regression, XGBoost, calibrated XGBoost, LightGBM, and calibrated LightGBM. Calibration is included because credit decisioning depends on reliable probability-of-default estimates, not only rank ordering.