the model artifact is removed to be deployed separately

.dockerignore

@@ -0,0 +1,5 @@
+fly.toml
+.git/
+__pycache__/
+.envrc
+.venv/

.gitignore copy

@@ -0,0 +1,3 @@
+catboost_info/
+api/__pycache__/
+api/catboost_info/

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12.12 AS builder
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
+WORKDIR /app
+
+
+RUN python -m venv .venv
+COPY requirements.txt ./
+RUN .venv/bin/pip install -r requirements.txt
+
+FROM python:3.12.12-slim
+WORKDIR /app
+
+# Native libs required by xgboost / scikit-learn wheels
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libgomp1 libopenblas0-pthread \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/.venv .venv/
+COPY . .
+CMD ["/app/.venv/bin/uvicorn", "api.app:app", "--host", "0.0.0.0", "--port", "7860"]

README copy.md

@@ -0,0 +1 @@
+# frankscore-deployment

api/app.py

@@ -0,0 +1,337 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import joblib
+import numpy as np
+import pandas as pd
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, Field
+import xgboost as xgb
+# Compatibility shim for pickles created with newer sklearn that include _RemainderColsList
+import sklearn.compose._column_transformer as _ct  # type: ignore
+if not hasattr(_ct, "_RemainderColsList"):
+    class _RemainderColsList(list):  # type: ignore
+        pass
+    _ct._RemainderColsList = _RemainderColsList
+
+ROOT = Path(__file__).resolve().parents[1]
+MODEL_DIR = Path(__file__).resolve().parent / "model"
+MODEL_PATH = MODEL_DIR / "xgboost_pipeline.pkl"
+BOOSTER_PATH = MODEL_DIR / "xgboost_booster.json"
+META_PATH = MODEL_DIR / "explain_meta.json"
+
+if not MODEL_PATH.exists():
+    raise FileNotFoundError(f"Model file missing at {MODEL_PATH}")
+if not META_PATH.exists():
+    raise FileNotFoundError(f"Explainability meta missing at {META_PATH}")
+if not BOOSTER_PATH.exists():
+    raise FileNotFoundError(f"Booster file missing at {BOOSTER_PATH}")
+
+PIPELINE = joblib.load(MODEL_PATH)
+META = json.loads(META_PATH.read_text())
+
+EXPECTED_FEATURES = list(getattr(PIPELINE, "feature_names_in_", []))
+PREPROCESS = PIPELINE.named_steps.get("preprocess") if hasattr(PIPELINE, "named_steps") else None
+if PREPROCESS is None:
+    raise RuntimeError("Pipeline missing 'preprocess' step; cannot infer columns.")
+
+if not EXPECTED_FEATURES:
+    EXPECTED_FEATURES = list(getattr(PREPROCESS, "feature_names_in_", []))
+    if not EXPECTED_FEATURES:
+        raise RuntimeError("Unable to determine expected feature names from the pipeline.")
+
+_col_map = {name: cols for name, _, cols in getattr(PREPROCESS, "transformers_", [])}
+NUM_FEATURES = list(_col_map.get("num", []))
+CAT_FEATURES = list(_col_map.get("cat", []))
+PRE_FEATURE_NAMES = META.get("pre_feature_names") or list(getattr(PREPROCESS, "get_feature_names_out", lambda: [])())
+RAW_FEATURE_SET = set((META.get("raw_num_cols") or []) + (META.get("raw_cat_cols") or []))
+FEATURE_GROUPS = {
+    "Borrowing History & Maturity": [
+        "account_age_days",
+        "avg_past_amount",
+        "avg_past_daily_burden",
+        "avg_time_bw_loans",
+        "borrower_history_strength",
+        "days_since_last_loan",
+        "loan_frequency_per_year",
+        "num_previous_loans",
+        "std_past_amount",
+        "std_past_daily_burden",
+        "trend_in_amount",
+        "trend_in_burden",
+    ],
+    "Repayment Speed & Delinquency": [
+        "num_previous_defaults",
+        "past_default_rate",
+        "repayment_consistency",
+    ],
+    "Current Loan Size, Pricing & Burden": [
+        "Total_Amount",
+        "Total_Amount_to_Repay",
+        "amount_bucket",
+        "burden_percentile",
+        "daily_burden",
+        "duration",
+        "duration_bucket",
+        "interest_rate",
+    ],
+    "Affordability & Risk Ratios": [
+        "amount_ratio",
+        "burden_ratio",
+        "repayment_intensity",
+    ],
+    "Seasonality & Timing": [
+        "days_to_local_festival",
+        "days_to_salary_day",
+        "month",
+        "quarter",
+        "week_of_year",
+    ],
+    "Operational, Referral & Lender Signals": [
+        "lender_exposure_ratio",
+        "lender_id",
+        "lender_risk_profile",
+    ],
+    "Time-based Trends & Volatility": [
+        "latest_amount_ma3",
+    ],
+}
+FEATURE_GROUP_LOOKUP: Dict[str, str] = {}
+for group, variables in FEATURE_GROUPS.items():
+    for var in variables:
+        FEATURE_GROUP_LOOKUP[var] = group
+
+app = FastAPI(title="FrankScore", version="1.0.0")
+
+
+class PredictionRequest(BaseModel):
+    records: List[Dict[str, Any]] = Field(..., description="List of borrower feature dictionaries")
+
+
+class PredictionResponse(BaseModel):
+    probabilities: List[float]
+
+
+class ScoreRequest(BaseModel):
+    probabilities: List[float] = Field(..., description="Probabilities of default (0-1)")
+
+
+class ScoreResponse(BaseModel):
+    scores: List[float]
+
+
+class ExplainRequest(BaseModel):
+    records: List[Dict[str, Any]]
+    top_k: Optional[int] = Field(default=10, ge=1, le=100, description="Number of top features to return per record")
+
+
+class FeatureContribution(BaseModel):
+    feature: str
+    shap_value: float
+
+
+class GroupContribution(BaseModel):
+    group: str
+    total_shap_value: float
+    features: List[FeatureContribution]
+
+
+class ExplainItem(BaseModel):
+    probability: float
+    base_value: float
+    group_contributions: List[GroupContribution]
+
+
+class ExplainResponse(BaseModel):
+    explanations: List[ExplainItem]
+
+
+class PredictExplainItem(BaseModel):
+    probability: float
+    score: float
+    base_value: float
+    group_contributions: List[GroupContribution]
+
+
+class PredictExplainResponse(BaseModel):
+    results: List[PredictExplainItem]
+
+
+def prepare_frame(records: List[Dict[str, Any]]) -> pd.DataFrame:
+    if not records:
+        raise HTTPException(status_code=400, detail="No records provided.")
+    df = pd.DataFrame(records)
+    for col in EXPECTED_FEATURES:
+        if col not in df.columns:
+            df[col] = np.nan
+    df = df[EXPECTED_FEATURES]
+    if NUM_FEATURES:
+        df[NUM_FEATURES] = df[NUM_FEATURES].apply(pd.to_numeric, errors="coerce")
+    if CAT_FEATURES:
+        df[CAT_FEATURES] = df[CAT_FEATURES].astype("object")
+    return df
+
+
+def pd_to_score(p: np.ndarray, base_score: float = 50, base_odds: float = 9, pdo: float = 20) -> np.ndarray:
+    p = np.clip(p, 1e-6, 1 - 1e-6)
+    B = pdo / np.log(2)
+    A = base_score - B * np.log(base_odds)
+    odds = (1 - p) / p
+    score = A + B * np.log(odds)
+    return np.clip(score, 0, 100)
+
+
+def _sanitize_feature_name(name: str) -> str:
+    sanitized = name
+    for ch, repl in {"[": "", "]": "", "<": "lt", ">": "gt", " ": "_", ",": "_", "=": "_"}.items():
+        sanitized = sanitized.replace(ch, repl)
+    return sanitized
+
+
+def _base_feature_name(name: str) -> str:
+    base = name
+    if "__" in base:
+        base = base.split("__", 1)[1]
+    if base in RAW_FEATURE_SET:
+        return base
+    parts = base.split("_")
+    while len(parts) > 1:
+        candidate = "_".join(parts[:-1])
+        if candidate in RAW_FEATURE_SET:
+            return candidate
+        parts = parts[:-1]
+    return base
+
+
+def get_booster():
+    if not hasattr(get_booster, "_booster"):
+        booster = xgb.Booster()
+        booster.load_model(str(BOOSTER_PATH))
+        base_score = booster.attr("base_score")
+        if base_score:
+            try:
+                float(base_score)
+            except ValueError:
+                cleaned = base_score.strip("[]")
+                try:
+                    cleaned_val = str(float(cleaned))
+                except Exception:
+                    cleaned_val = "0.5"
+                booster.set_param({"base_score": cleaned_val})
+                booster.set_attr(base_score=cleaned_val)
+        get_booster._booster = booster
+    return get_booster._booster
+
+
+@app.post("/predict", response_model=PredictionResponse)
+def predict(req: PredictionRequest) -> PredictionResponse:
+    frame = prepare_frame(req.records)
+    probas = PIPELINE.predict_proba(frame)[:, 1]
+    return PredictionResponse(probabilities=probas.tolist())
+
+
+@app.get("/health")
+def health() -> Dict[str, str]:
+    return {"status": "ok", "model_path": str(MODEL_PATH)}
+
+
+@app.post("/score", response_model=ScoreResponse)
+def score(req: ScoreRequest) -> ScoreResponse:
+    if not req.probabilities:
+        raise HTTPException(status_code=400, detail="No probabilities provided.")
+    arr = np.array(req.probabilities, dtype=float)
+    scores = pd_to_score(arr)
+    return ScoreResponse(scores=scores.tolist())
+
+
+@app.post("/explain", response_model=ExplainResponse)
+def explain(req: ExplainRequest) -> ExplainResponse:
+    if not req.records:
+        raise HTTPException(status_code=400, detail="No records provided.")
+    frame = prepare_frame(req.records)
+    probas = PIPELINE.predict_proba(frame)[:, 1]
+    booster = get_booster()
+    X_proc = PREPROCESS.transform(frame)
+    feat_names = np.array(PRE_FEATURE_NAMES) if PRE_FEATURE_NAMES else np.array([f"f{i}" for i in range(X_proc.shape[1])])
+    sanitized_names = [_sanitize_feature_name(n) for n in feat_names]
+    dmat = xgb.DMatrix(X_proc, feature_names=sanitized_names)
+    contribs = booster.predict(dmat, pred_contribs=True)
+    if contribs.shape[1] != X_proc.shape[1] + 1:
+        raise HTTPException(status_code=500, detail="Unexpected contribution shape from booster.")
+    base_vals = contribs[:, -1]
+    feat_contribs = contribs[:, :-1]
+    explanations: List[ExplainItem] = []
+    for i in range(feat_contribs.shape[0]):
+        row_vals = feat_contribs[i]
+        group_totals: Dict[str, float] = {}
+        group_details: Dict[str, List[FeatureContribution]] = {}
+        for name, val in zip(feat_names, row_vals):
+            base = _base_feature_name(str(name))
+            group = FEATURE_GROUP_LOOKUP.get(base, "Other")
+            group_totals[group] = group_totals.get(group, 0.0) + float(val)
+            group_details.setdefault(group, []).append(
+                FeatureContribution(feature=str(name), shap_value=float(val))
+            )
+        group_contribs: List[GroupContribution] = []
+        for grp, total in sorted(group_totals.items(), key=lambda kv: abs(kv[1]), reverse=True):
+            feats = sorted(group_details.get(grp, []), key=lambda fc: abs(fc.shap_value), reverse=True)
+            if req.top_k:
+                feats = feats[:req.top_k]
+            group_contribs.append(GroupContribution(group=grp, total_shap_value=total, features=feats))
+        explanations.append(
+            ExplainItem(
+                probability=float(probas[i]),
+                base_value=float(base_vals[i]),
+                group_contributions=group_contribs,
+            )
+        )
+    return ExplainResponse(explanations=explanations)
+
+
+@app.post("/predict_explain", response_model=PredictExplainResponse)
+def predict_explain(req: ExplainRequest) -> PredictExplainResponse:
+    if not req.records:
+        raise HTTPException(status_code=400, detail="No records provided.")
+    frame = prepare_frame(req.records)
+    probas = PIPELINE.predict_proba(frame)[:, 1]
+    booster = get_booster()
+    X_proc = PREPROCESS.transform(frame)
+    feat_names = np.array(PRE_FEATURE_NAMES) if PRE_FEATURE_NAMES else np.array([f"f{i}" for i in range(X_proc.shape[1])])
+    sanitized_names = [_sanitize_feature_name(n) for n in feat_names]
+    dmat = xgb.DMatrix(X_proc, feature_names=sanitized_names)
+    contribs = booster.predict(dmat, pred_contribs=True)
+    if contribs.shape[1] != X_proc.shape[1] + 1:
+        raise HTTPException(status_code=500, detail="Unexpected contribution shape from booster.")
+    base_vals = contribs[:, -1]
+    feat_contribs = contribs[:, :-1]
+    items: List[PredictExplainItem] = []
+    for i in range(feat_contribs.shape[0]):
+        row_vals = feat_contribs[i]
+        group_totals: Dict[str, float] = {}
+        group_details: Dict[str, List[FeatureContribution]] = {}
+        for name, val in zip(feat_names, row_vals):
+            base = _base_feature_name(str(name))
+            group = FEATURE_GROUP_LOOKUP.get(base, "Other")
+            group_totals[group] = group_totals.get(group, 0.0) + float(val)
+            group_details.setdefault(group, []).append(
+                FeatureContribution(feature=str(name), shap_value=float(val))
+            )
+        group_contribs: List[GroupContribution] = []
+        for grp, total in sorted(group_totals.items(), key=lambda kv: abs(kv[1]), reverse=True):
+            feats = sorted(group_details.get(grp, []), key=lambda fc: abs(fc.shap_value), reverse=True)
+            if req.top_k:
+                feats = feats[:req.top_k]
+            group_contribs.append(GroupContribution(group=grp, total_shap_value=total, features=feats))
+        score_val = int(round(float(pd_to_score(np.array([probas[i]]))[0])))
+        items.append(
+            PredictExplainItem(
+                probability=float(probas[i]),
+                score=score_val,
+                base_value=float(base_vals[i]),
+                group_contributions=group_contribs,
+            )
+        )
+    return PredictExplainResponse(results=items)

api/model/explain_meta.json

@@ -0,0 +1,92 @@
+{
+  "dataset": "full",
+  "target_col": "target",
+  "raw_num_cols": [
+    "num_previous_loans",
+    "num_previous_defaults",
+    "past_default_rate",
+    "days_since_last_loan",
+    "avg_time_bw_loans",
+    "avg_past_amount",
+    "avg_past_daily_burden",
+    "std_past_amount",
+    "std_past_daily_burden",
+    "trend_in_amount",
+    "trend_in_burden",
+    "Total_Amount",
+    "Total_Amount_to_Repay",
+    "duration",
+    "daily_burden",
+    "amount_ratio",
+    "burden_ratio",
+    "burden_percentile",
+    "borrower_history_strength",
+    "month",
+    "quarter",
+    "week_of_year",
+    "days_to_salary_day",
+    "days_to_local_festival",
+    "lender_id",
+    "lender_exposure_ratio",
+    "account_age_days",
+    "loan_frequency_per_year",
+    "repayment_consistency",
+    "latest_amount_ma3"
+  ],
+  "raw_cat_cols": [
+    "duration_bucket",
+    "amount_bucket"
+  ],
+  "pre_feature_names": [
+    "num__num_previous_loans",
+    "num__num_previous_defaults",
+    "num__past_default_rate",
+    "num__days_since_last_loan",
+    "num__avg_time_bw_loans",
+    "num__avg_past_amount",
+    "num__avg_past_daily_burden",
+    "num__std_past_amount",
+    "num__std_past_daily_burden",
+    "num__trend_in_amount",
+    "num__trend_in_burden",
+    "num__Total_Amount",
+    "num__Total_Amount_to_Repay",
+    "num__duration",
+    "num__daily_burden",
+    "num__amount_ratio",
+    "num__burden_ratio",
+    "num__burden_percentile",
+    "num__borrower_history_strength",
+    "num__month",
+    "num__quarter",
+    "num__week_of_year",
+    "num__days_to_salary_day",
+    "num__days_to_local_festival",
+    "num__lender_id",
+    "num__lender_exposure_ratio",
+    "num__account_age_days",
+    "num__loan_frequency_per_year",
+    "num__repayment_consistency",
+    "num__latest_amount_ma3",
+    "cat__duration_bucket_<=1m",
+    "cat__duration_bucket_<=1w",
+    "cat__duration_bucket_<=2m",
+    "cat__duration_bucket_<=2w",
+    "cat__duration_bucket_>2m",
+    "cat__amount_bucket_q1",
+    "cat__amount_bucket_q2",
+    "cat__amount_bucket_q3",
+    "cat__amount_bucket_q4"
+  ],
+  "id_cols": [
+    "customer_id",
+    "tbl_loan_id"
+  ],
+  "dropped_features": [
+    "interest_rate",
+    "lender_risk_profile",
+    "pseudo_disb_date",
+    "repayment_intensity"
+  ],
+  "split_used": "time_split(pseudo_disb_date)"
+}

api/model_training/train_model.py

@@ -0,0 +1,364 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+import matplotlib
+matplotlib.use("Agg")  # Use non-GUI backend to avoid Tkinter cleanup warnings
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+import seaborn as sns
+import joblib
+from catboost import CatBoostClassifier
+from lightgbm import LGBMClassifier
+from sklearn.compose import ColumnTransformer
+from sklearn.ensemble import RandomForestClassifier
+from sklearn.impute import SimpleImputer
+from sklearn.metrics import (
+    accuracy_score,
+    average_precision_score,
+    classification_report,
+    confusion_matrix,
+    f1_score,
+    precision_recall_curve,
+    precision_score,
+    recall_score,
+    roc_auc_score,
+    roc_curve,
+)
+from sklearn.model_selection import GroupShuffleSplit, train_test_split
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import OneHotEncoder
+from xgboost import XGBClassifier
+import xgboost as xgb
+
+
+RANDOM_STATE = 42
+# Repository root (two levels up from this file: code/model/train_models.py -> repo root)
+ROOT = Path(__file__).resolve().parents[2]
+DATA_BASE = Path(
+    "/home/name-1/AI-Agent/frankscore/kenyan-dataset-issue/data/feature-generated"
+)
+
+DATASETS: Dict[str, Path] = {
+    "full": DATA_BASE / "kenya_engineered_features.csv",
+    "borrower": DATA_BASE / "kenya_engineered_features_borrower_side.csv",
+}
+OUTPUT_DIR = ROOT / "code" / "model" / "outputs_for_demo"
+TARGET_COL = "target"
+ID_COLS = ["customer_id", "tbl_loan_id"]
+GROUP_COL_CANDIDATES = ["customer_id", "customerId", "client_id"]
+DATE_COL_CANDIDATES = ["pseudo_disb_date", "disb_date", "disbursement_date", "application_date", "loan_date"]
+FEATURES_TO_DROP = {
+    "interest_rate",
+    "repayment_intensity",
+    "lender_risk_profile",
+    "pseudo_disb_date",
+}
+
+
+def build_preprocessor(
+    feature_frame: pd.DataFrame,
+) -> Tuple[ColumnTransformer, List[str], List[str]]:
+    cat_cols = feature_frame.select_dtypes(include=["object"]).columns.tolist()
+    num_cols = [c for c in feature_frame.columns if c not in cat_cols]
+
+    num_pipe = Pipeline(
+        steps=[
+            ("imputer", SimpleImputer(strategy="median")),
+        ]
+    )
+    cat_pipe = Pipeline(
+        steps=[
+            ("imputer", SimpleImputer(strategy="most_frequent")),
+            ("encoder", OneHotEncoder(handle_unknown="ignore", sparse_output=False)),
+        ]
+    )
+    preprocessor = ColumnTransformer(
+        transformers=[
+            ("num", num_pipe, num_cols),
+            ("cat", cat_pipe, cat_cols),
+        ]
+    )
+    return preprocessor, num_cols, cat_cols
+
+
+def find_first_existing_col(df: pd.DataFrame, candidates: List[str]) -> str | None:
+    for c in candidates:
+        if c in df.columns:
+            return c
+    return None
+
+
+def split_data_leakage_safe(
+    df: pd.DataFrame, X: pd.DataFrame, y: pd.Series
+) -> Tuple[pd.DataFrame, pd.DataFrame, pd.Series, pd.Series, str]:
+    """
+    Priority:
+    1) time split if a date column exists
+    2) group split on customer id
+    3) stratified fallback
+    """
+    date_col = find_first_existing_col(df, DATE_COL_CANDIDATES)
+    group_col = find_first_existing_col(df, GROUP_COL_CANDIDATES)
+
+    if date_col is not None:
+        tmp = df[[date_col]].copy()
+        tmp[date_col] = pd.to_datetime(tmp[date_col], errors="coerce")
+        if tmp[date_col].notna().mean() > 0.8:
+            order = tmp[date_col].sort_values().index
+            cutoff = int(len(order) * 0.8)
+            train_idx = order[:cutoff]
+            test_idx = order[cutoff:]
+            return (
+                X.loc[train_idx],
+                X.loc[test_idx],
+                y.loc[train_idx],
+                y.loc[test_idx],
+                f"time_split({date_col})",
+            )
+
+    if group_col is not None:
+        groups = df[group_col]
+        gss = GroupShuffleSplit(n_splits=1, test_size=0.2, random_state=RANDOM_STATE)
+        train_idx, test_idx = next(gss.split(X, y, groups=groups))
+        return (
+            X.iloc[train_idx],
+            X.iloc[test_idx],
+            y.iloc[train_idx],
+            y.iloc[test_idx],
+            f"group_split({group_col})",
+        )
+
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=0.2, stratify=y, random_state=RANDOM_STATE
+    )
+    return X_train, X_test, y_train, y_test, "stratified_random_split"
+
+
+def get_models(scale_pos_weight: float) -> Dict[str, object]:
+    # Using moderate defaults to keep runtime reasonable.
+    return {
+        "random_forest": RandomForestClassifier(
+            n_estimators=300,
+            max_depth=None,
+            n_jobs=-1,
+            class_weight="balanced",
+            random_state=RANDOM_STATE,
+        ),
+        "xgboost": XGBClassifier(
+            n_estimators=300,
+            max_depth=6,
+            learning_rate=0.05,
+            subsample=0.8,
+            colsample_bytree=0.8,
+            eval_metric="logloss",
+            n_jobs=-1,
+            random_state=RANDOM_STATE,
+            scale_pos_weight=scale_pos_weight,
+        ),
+        "lightgbm": LGBMClassifier(
+            n_estimators=400,
+            learning_rate=0.05,
+            max_depth=-1,
+            subsample=0.9,
+            colsample_bytree=0.9,
+            random_state=RANDOM_STATE,
+            n_jobs=-1,
+            class_weight="balanced",
+        ),
+        "catboost": CatBoostClassifier(
+            iterations=400,
+            depth=8,
+            learning_rate=0.05,
+            loss_function="Logloss",
+            eval_metric="AUC",
+            verbose=0,
+            random_seed=RANDOM_STATE,
+        ),
+    }
+
+
+def plot_roc(y_true: np.ndarray, y_score: np.ndarray, title: str, path: Path) -> None:
+    fpr, tpr, _ = roc_curve(y_true, y_score)
+    auc_val = roc_auc_score(y_true, y_score)
+    plt.figure()
+    plt.plot(fpr, tpr, label=f"AUC = {auc_val:.3f}")
+    plt.plot([0, 1], [0, 1], linestyle="--", color="grey")
+    plt.xlabel("False Positive Rate")
+    plt.ylabel("True Positive Rate")
+    plt.title(title)
+    plt.legend(loc="lower right")
+    plt.tight_layout()
+    plt.savefig(path, dpi=150)
+    plt.close()
+
+
+def plot_pr(y_true: np.ndarray, y_score: np.ndarray, title: str, path: Path) -> None:
+    precision, recall, _ = precision_recall_curve(y_true, y_score)
+    ap = average_precision_score(y_true, y_score)
+    plt.figure()
+    plt.plot(recall, precision, label=f"AP = {ap:.3f}")
+    plt.xlabel("Recall")
+    plt.ylabel("Precision")
+    plt.title(title)
+    plt.legend(loc="lower left")
+    plt.tight_layout()
+    plt.savefig(path, dpi=150)
+    plt.close()
+
+
+def plot_confusion(y_true: np.ndarray, y_pred: np.ndarray, title: str, path: Path) -> None:
+    cm = confusion_matrix(y_true, y_pred)
+    plt.figure()
+    sns.heatmap(cm, annot=True, fmt="d", cmap="Blues", cbar=False)
+    plt.xlabel("Predicted")
+    plt.ylabel("Actual")
+    plt.title(title)
+    plt.tight_layout()
+    plt.savefig(path, dpi=150)
+    plt.close()
+
+
+def evaluate_models(dataset_name: str, data_path: Path) -> None:
+    print(f"=== Training on {dataset_name} dataset ===")
+    df = pd.read_csv(data_path)
+    if TARGET_COL not in df.columns:
+        raise SystemExit(f"target column missing in {data_path}")
+
+    X = df.drop(columns=[TARGET_COL] + ID_COLS, errors="ignore")
+    X = X.drop(columns=[c for c in FEATURES_TO_DROP if c in X.columns], errors="ignore")
+    y = df[TARGET_COL]
+
+    preprocessor, num_cols, cat_cols = build_preprocessor(X)
+
+    X_train, X_test, y_train, y_test, split_tag = split_data_leakage_safe(df, X, y)
+    print(f"Split used: {split_tag}")
+    pos = y_train.sum()
+    neg = len(y_train) - pos
+    scale_pos_weight = float(neg / pos) if pos > 0 else 1.0
+
+    models = get_models(scale_pos_weight)
+    ds_out = OUTPUT_DIR / dataset_name
+    ds_out.mkdir(parents=True, exist_ok=True)
+
+    # Save a small background sample for downstream explainability tooling.
+    background_path = ds_out / "explain_background.csv"
+    df.sample(min(len(df), 200), random_state=RANDOM_STATE).to_csv(background_path, index=False)
+
+    metrics_rows = []
+    report_manifest = {}
+    pre_feature_names = None
+
+    for model_name, model in models.items():
+        print(f"Training {model_name}...")
+        clf = Pipeline(steps=[("preprocess", preprocessor), ("model", model)])
+        clf.fit(X_train, y_train)
+        if pre_feature_names is None:
+            pre_feature_names = clf.named_steps["preprocess"].get_feature_names_out().tolist()
+        probas = clf.predict_proba(X_test)[:, 1]
+        preds = (probas >= 0.5).astype(int)
+
+        metrics = {
+            "dataset": dataset_name,
+            "split": split_tag,
+            "model": model_name,
+            "auc_roc": roc_auc_score(y_test, probas),
+            "auc_pr": average_precision_score(y_test, probas),
+            "accuracy": accuracy_score(y_test, preds),
+            "precision": precision_score(y_test, preds, zero_division=0),
+            "recall": recall_score(y_test, preds, zero_division=0),
+            "f1": f1_score(y_test, preds, zero_division=0),
+        }
+        metrics_rows.append(metrics)
+
+        # Classification report
+        cls_report = classification_report(
+            y_test,
+            preds,
+            target_names=["non_default", "default"],
+            digits=3,
+            zero_division=0,
+        )
+        report_path = ds_out / f"classification_report_{model_name}.txt"
+        report_path.write_text(cls_report)
+        report_manifest[f"classification_report_{model_name}"] = str(report_path)
+
+        # Plots
+        roc_path = ds_out / f"roc_{model_name}.png"
+        pr_path = ds_out / f"pr_{model_name}.png"
+        cm_path = ds_out / f"confusion_matrix_{model_name}.png"
+        model_path = ds_out / f"{model_name}_pipeline.pkl"
+
+        plot_roc(y_test, probas, f"{dataset_name.upper()} - {model_name} ROC", roc_path)
+        plot_pr(y_test, probas, f"{dataset_name.upper()} - {model_name} PR", pr_path)
+        plot_confusion(
+            y_test, preds, f"{dataset_name.upper()} - {model_name} Confusion", cm_path
+        )
+        joblib.dump(clf, model_path)
+
+        report_manifest[f"roc_{model_name}"] = str(roc_path)
+        report_manifest[f"pr_{model_name}"] = str(pr_path)
+        report_manifest[f"confusion_{model_name}"] = str(cm_path)
+        report_manifest[f"model_{model_name}"] = str(model_path)
+
+        if model_name == "xgboost":
+            booster = clf.named_steps["model"].get_booster()
+            base_score = booster.attr("base_score")
+            if base_score:
+                try:
+                    float(base_score)
+                except ValueError:
+                    cleaned = base_score.strip("[]")
+                    try:
+                        cleaned_val = str(float(cleaned))
+                    except Exception:
+                        cleaned_val = "0.5"
+                    booster.set_param({"base_score": cleaned_val})
+                    booster.set_attr(base_score=cleaned_val)
+            booster_path = ds_out / f"{model_name}_booster.json"
+            booster.save_model(str(booster_path))
+            report_manifest[f"booster_{model_name}"] = str(booster_path)
+
+    if pre_feature_names is None:
+        pre_feature_names = []
+
+    explain_meta = {
+        "dataset": dataset_name,
+        "target_col": TARGET_COL,
+        "raw_num_cols": num_cols,
+        "raw_cat_cols": cat_cols,
+        "pre_feature_names": pre_feature_names,
+        "id_cols": ID_COLS,
+        "dropped_features": sorted(list(FEATURES_TO_DROP)),
+        "split_used": split_tag,
+    }
+    meta_path = ds_out / "explain_meta.json"
+    meta_path.write_text(json.dumps(explain_meta, indent=2))
+    report_manifest["explain_meta"] = str(meta_path)
+    report_manifest["explain_background"] = str(background_path)
+
+    metrics_df = pd.DataFrame(metrics_rows).sort_values(
+        ["dataset", "auc_roc"], ascending=[True, False]
+    )
+    metrics_path = ds_out / "metrics_summary.csv"
+    metrics_df.to_csv(metrics_path, index=False)
+    print(f"Saved metrics -> {metrics_path}")
+
+    manifest_path = ds_out / "artifacts.json"
+    manifest_path.write_text(json.dumps(report_manifest, indent=2))
+
+
+def main() -> None:
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+    for name, path in DATASETS.items():
+        if not path.exists():
+            print(f"Skipping {name}, missing file: {path}")
+            continue
+        evaluate_models(name, path)
+
+
+if __name__ == "__main__":
+    main()

requirements.txt

@@ -0,0 +1,15 @@
+# API runtime dependencies
+fastapi[standard]
+uvicorn[standard]
+pydantic
+numpy
+pandas
+scikit-learn==1.6.1  # match model pickling version; avoids SimpleImputer _fill_dtype errors
+joblib
+xgboost
+
+# Model training extras
+catboost
+lightgbm
+matplotlib
+seaborn

test.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+Test script for /v1/predict endpoint.
+
+This script demonstrates the correct request format:
+- inputId: required string
+- payload: object containing the feature data
+"""
+
+import hmac
+import hashlib
+import time
+import uuid
+import requests
+
+# ============================================
+# CONFIGURATION (from tenant creation)
+# ============================================
+CLIENT_ID = "acme-bank-463edc0a"
+CLIENT_SECRET = "yPqsrtBizHgDvnK-NpkgVXMXw3WbV_s_JGK-c2pWr3U"
+HMAC_SECRET = "OSSBJgx2QToeQhGtQgzwS_8Kf1QvTraq6M67uNrBKEo"
+
+BASE_URL = "https://frankscore-backend.onrender.com"
+
+# ============================================
+# STEP 1: Login as Tenant
+# ============================================
+print("Step 1: Logging in...")
+login_response = requests.post(
+    f"{BASE_URL}/auth/login",
+    json={
+        "clientId": CLIENT_ID,
+        "clientSecret": CLIENT_SECRET
+    }
+)
+
+if login_response.status_code != 200:
+    print(f"❌ Login failed: {login_response.status_code}")
+    print(login_response.text)
+    exit(1)
+
+login_data = login_response.json()
+jwt_token = login_data["access_token"]  # Note: camelCase, not snake_case
+print(f"✅ Logged in. JWT: {jwt_token[:20]}...")
+
+# ============================================
+# STEP 2: Prepare End-User Identity
+# ============================================
+end_user_id = "user-alice-123"  # Your customer
+timestamp = str(int(time.time()))
+request_id = str(uuid.uuid4())
+
+# ============================================
+# STEP 3: Compute HMAC Signature
+# ============================================
+signing_string = f"{end_user_id}|{timestamp}|{request_id}"
+signature = hmac.new(
+    HMAC_SECRET.encode('utf-8'),      # SECRET KEY (never sent!)
+    signing_string.encode('utf-8'),
+    hashlib.sha256
+).hexdigest()
+
+print(f"📝 Signing string: {signing_string}")
+print(f"🔐 Signature: {signature[:20]}...")
+
+# ============================================
+# STEP 4: Make Prediction Request
+# ============================================
+print("\nStep 4: Making prediction request...")
+
+# IMPORTANT: The request format is:
+# {
+#   "inputId": "string",  # REQUIRED
+#   "payload": { ... }    # The features go here
+# }
+
+request_body = {
+    "inputId": "loan-app-78945",  # REQUIRED - unique identifier for this request
+    "payload": {
+      "num_previous_loans": 9,
+      "num_previous_defaults": 4,
+      "past_default_rate": 0.44,
+      "days_since_last_loan": 2,
+      "avg_time_bw_loans": 20,
+      "avg_past_amount": 26000,
+      "avg_past_daily_burden": 950,
+      "std_past_amount": 4000,
+      "std_past_daily_burden": 180,
+      "trend_in_amount": 1.3,
+      "trend_in_burden": 1.35,
+      "Total_Amount": 30000,
+      "Total_Amount_to_Repay": 36000,
+      "duration": 20,
+      "daily_burden": 1500,
+      "amount_ratio": 2.0,
+      "burden_ratio": 1.8,
+      "duration_bucket": "20",
+      "amount_bucket": "high",
+      "burden_percentile": 0.95,
+      "borrower_history_strength": "weak",
+      "month": 1,
+      "quarter": 1,
+      "week_of_year": 3,
+      "days_to_salary_day": 28,
+      "days_to_local_festival": 2,
+      "lender_id": "L_high3",
+      "lender_exposure_ratio": 0.4,
+      "account_age_days": 150,
+      "loan_frequency_per_year": 12,
+      "repayment_consistency": 0.4,
+      "latest_amount_ma3": 28000
+    }
+}
+
+response = requests.post(
+    f"{BASE_URL}/v1/predict_explain",
+    headers={
+        "Authorization": f"Bearer {jwt_token}",
+        "Content-Type": "application/json",
+        "X-End-User-Id": end_user_id,
+        "X-End-User-Timestamp": timestamp,
+        "X-Request-Id": request_id,
+        "X-End-User-Signature": signature
+    },
+    json=request_body
+)
+
+print(f"\nResponse Status: {response.status_code}")
+
+if response.status_code == 200:
+    result = response.json()
+    print("✅ Prediction successful!")
+    print(f"   Input ID: {result.get('inputId')}")
+    print(f"   Score: {result.get('score')}")
+    if result.get('topFeatures'):
+        print(f"   Top Features: {len(result.get('topFeatures'))} features")
+    print(f"\nFull response: {result}")
+else:
+    print(f"❌ Prediction failed: {response.status_code}")
+    print(response.text)

test_data.json

@@ -0,0 +1,243 @@
+
+{
+  "records": [
+    {
+      "num_previous_loans": 8,
+      "num_previous_defaults": 0,
+      "past_default_rate": 0.0,
+      "days_since_last_loan": 40,
+      "avg_time_bw_loans": 120,
+      "avg_past_amount": 8000,
+      "avg_past_daily_burden": 200,
+      "std_past_amount": 500,
+      "std_past_daily_burden": 20,
+      "trend_in_amount": 1.05,
+      "trend_in_burden": 0.9,
+      "Total_Amount": 6000,
+      "Total_Amount_to_Repay": 7200,
+      "duration": 45,
+      "daily_burden": 160,
+      "amount_ratio": 0.4,
+      "burden_ratio": 0.25,
+      "duration_bucket": "45",
+      "amount_bucket": "low",
+      "burden_percentile": 0.15,
+      "borrower_history_strength": "strong",
+      "month": 5,
+      "quarter": 2,
+      "week_of_year": 18,
+      "days_to_salary_day": 5,
+      "days_to_local_festival": 40,
+      "lender_id": "L_low1",
+      "lender_exposure_ratio": 0.05,
+      "account_age_days": 900,
+      "loan_frequency_per_year": 3,
+      "repayment_consistency": 0.98,
+      "latest_amount_ma3": 5500
+    },
+    {
+      "num_previous_loans": 6,
+      "num_previous_defaults": 0,
+      "past_default_rate": 0.0,
+      "days_since_last_loan": 25,
+      "avg_time_bw_loans": 90,
+      "avg_past_amount": 12000,
+      "avg_past_daily_burden": 300,
+      "std_past_amount": 700,
+      "std_past_daily_burden": 30,
+      "trend_in_amount": 1.0,
+      "trend_in_burden": 0.95,
+      "Total_Amount": 10000,
+      "Total_Amount_to_Repay": 11500,
+      "duration": 60,
+      "daily_burden": 190,
+      "amount_ratio": 0.55,
+      "burden_ratio": 0.35,
+      "duration_bucket": "60",
+      "amount_bucket": "mid",
+      "burden_percentile": 0.25,
+      "borrower_history_strength": "strong",
+      "month": 7,
+      "quarter": 3,
+      "week_of_year": 27,
+      "days_to_salary_day": 12,
+      "days_to_local_festival": 25,
+      "lender_id": "L_low2",
+      "lender_exposure_ratio": 0.08,
+      "account_age_days": 750,
+      "loan_frequency_per_year": 4,
+      "repayment_consistency": 0.95,
+      "latest_amount_ma3": 10500
+    },
+    {
+      "num_previous_loans": 4,
+      "num_previous_defaults": 0,
+      "past_default_rate": 0.0,
+      "days_since_last_loan": 15,
+      "avg_time_bw_loans": 60,
+      "avg_past_amount": 15000,
+      "avg_past_daily_burden": 450,
+      "std_past_amount": 1200,
+      "std_past_daily_burden": 40,
+      "trend_in_amount": 1.05,
+      "trend_in_burden": 1.0,
+      "Total_Amount": 15000,
+      "Total_Amount_to_Repay": 17500,
+      "duration": 45,
+      "daily_burden": 389,
+      "amount_ratio": 0.8,
+      "burden_ratio": 0.55,
+      "duration_bucket": "45",
+      "amount_bucket": "mid",
+      "burden_percentile": 0.45,
+      "borrower_history_strength": "medium",
+      "month": 2,
+      "quarter": 1,
+      "week_of_year": 8,
+      "days_to_salary_day": 18,
+      "days_to_local_festival": 50,
+      "lender_id": "L_mid1",
+      "lender_exposure_ratio": 0.12,
+      "account_age_days": 500,
+      "loan_frequency_per_year": 5,
+      "repayment_consistency": 0.88,
+      "latest_amount_ma3": 16000
+    },
+    {
+      "num_previous_loans": 3,
+      "num_previous_defaults": 0,
+      "past_default_rate": 0.0,
+      "days_since_last_loan": 10,
+      "avg_time_bw_loans": 45,
+      "avg_past_amount": 17000,
+      "avg_past_daily_burden": 520,
+      "std_past_amount": 1500,
+      "std_past_daily_burden": 60,
+      "trend_in_amount": 1.1,
+      "trend_in_burden": 1.05,
+      "Total_Amount": 20000,
+      "Total_Amount_to_Repay": 23000,
+      "duration": 30,
+      "daily_burden": 750,
+      "amount_ratio": 1.2,
+      "burden_ratio": 0.9,
+      "duration_bucket": "30",
+      "amount_bucket": "mid",
+      "burden_percentile": 0.65,
+      "borrower_history_strength": "medium",
+      "month": 5,
+      "quarter": 2,
+      "week_of_year": 18,
+      "days_to_salary_day": 10,
+      "days_to_local_festival": 40,
+      "lender_id": "L_mid2",
+      "lender_exposure_ratio": 0.18,
+      "account_age_days": 400,
+      "loan_frequency_per_year": 6,
+      "repayment_consistency": 0.82,
+      "latest_amount_ma3": 18000
+    },
+    {
+      "num_previous_loans": 5,
+      "num_previous_defaults": 1,
+      "past_default_rate": 0.2,
+      "days_since_last_loan": 7,
+      "avg_time_bw_loans": 40,
+      "avg_past_amount": 18000,
+      "avg_past_daily_burden": 600,
+      "std_past_amount": 2200,
+      "std_past_daily_burden": 90,
+      "trend_in_amount": 1.15,
+      "trend_in_burden": 1.1,
+      "Total_Amount": 22000,
+      "Total_Amount_to_Repay": 26000,
+      "duration": 30,
+      "daily_burden": 867,
+      "amount_ratio": 1.35,
+      "burden_ratio": 1.05,
+      "duration_bucket": "30",
+      "amount_bucket": "high",
+      "burden_percentile": 0.75,
+      "borrower_history_strength": "weak",
+      "month": 9,
+      "quarter": 3,
+      "week_of_year": 36,
+      "days_to_salary_day": 20,
+      "days_to_local_festival": 10,
+      "lender_id": "L_high1",
+      "lender_exposure_ratio": 0.25,
+      "account_age_days": 300,
+      "loan_frequency_per_year": 8,
+      "repayment_consistency": 0.7,
+      "latest_amount_ma3": 21000
+    },
+    {
+      "num_previous_loans": 7,
+      "num_previous_defaults": 2,
+      "past_default_rate": 0.29,
+      "days_since_last_loan": 5,
+      "avg_time_bw_loans": 30,
+      "avg_past_amount": 22000,
+      "avg_past_daily_burden": 750,
+      "std_past_amount": 3000,
+      "std_past_daily_burden": 120,
+      "trend_in_amount": 1.2,
+      "trend_in_burden": 1.2,
+      "Total_Amount": 25000,
+      "Total_Amount_to_Repay": 30000,
+      "duration": 25,
+      "daily_burden": 1200,
+      "amount_ratio": 1.6,
+      "burden_ratio": 1.3,
+      "duration_bucket": "25",
+      "amount_bucket": "high",
+      "burden_percentile": 0.85,
+      "borrower_history_strength": "weak",
+      "month": 11,
+      "quarter": 4,
+      "week_of_year": 46,
+      "days_to_salary_day": 25,
+      "days_to_local_festival": 5,
+      "lender_id": "L_high2",
+      "lender_exposure_ratio": 0.32,
+      "account_age_days": 250,
+      "loan_frequency_per_year": 9,
+      "repayment_consistency": 0.6,
+      "latest_amount_ma3": 24000
+    },
+    {
+      "num_previous_loans": 9,
+      "num_previous_defaults": 4,
+      "past_default_rate": 0.44,
+      "days_since_last_loan": 2,
+      "avg_time_bw_loans": 20,
+      "avg_past_amount": 26000,
+      "avg_past_daily_burden": 950,
+      "std_past_amount": 4000,
+      "std_past_daily_burden": 180,
+      "trend_in_amount": 1.3,
+      "trend_in_burden": 1.35,
+      "Total_Amount": 30000,
+      "Total_Amount_to_Repay": 36000,
+      "duration": 20,
+      "daily_burden": 1500,
+      "amount_ratio": 2.0,
+      "burden_ratio": 1.8,
+      "duration_bucket": "20",
+      "amount_bucket": "high",
+      "burden_percentile": 0.95,
+      "borrower_history_strength": "weak",
+      "month": 1,
+      "quarter": 1,
+      "week_of_year": 3,
+      "days_to_salary_day": 28,
+      "days_to_local_festival": 2,
+      "lender_id": "L_high3",
+      "lender_exposure_ratio": 0.4,
+      "account_age_days": 150,
+      "loan_frequency_per_year": 12,
+      "repayment_consistency": 0.4,
+      "latest_amount_ma3": 28000
+    }
+  ]
+}