Credit and Underwriting

APPLICATION
  |
  1. ELIGIBILITY GATE    age, geography, product rules, KYC status
  |                      -> hard rules, no model. Cheap rejects first.
  |
  2. DATA ASSEMBLY       bureau pull(s) + AA bank statements + GST/EPFO
  |                      + device & application signals
  |                      -> each source has a cost. Order them cheapest-first
  |                         and stop early where a decision is already certain.
  |
  3. FEATURE ENGINEERING derive ~50-300 features from raw data
  |                      (this is where most of the model quality lives)
  |
  4. SCORING             PD model -> probability of default
  |
  5. POLICY LAYER        score + hard rules + affordability -> decision
  |                      -> the model gives probability; POLICY gives the answer
  |
  6. LIMIT & PRICING     how much, at what rate, over what tenure
  |
  7. REASON GENERATION   if declined: specific, accurate, deterministic reasons
  |
  8. DECISION LOG        immutable record: inputs, model version, policy
  |                      version, score, reasons, any human override
  |
OUTCOME  approve / decline / refer to human / counter-offer

from collections import defaultdict
from statistics import mean, pstdev

def cashflow_features(txns, months=12):
    """txns: list of {date, amount, narration, type: 'credit'|'debit'}
    Amounts positive. This is the thin-file lender's primary signal set."""
    f = {}
    by_month = defaultdict(lambda: {"in": 0.0, "out": 0.0})
    for t in txns:
        m = t["date"][:7]                      # YYYY-MM
        by_month[m]["in" if t["type"] == "credit" else "out"] += t["amount"]

    ins  = [v["in"]  for v in by_month.values()]
    outs = [v["out"] for v in by_month.values()]
    if not ins:
        return {"insufficient_data": True}

    # --- Income: level and, more importantly, STABILITY ---
    f["avg_monthly_inflow"] = mean(ins)
    f["inflow_volatility"]  = pstdev(ins) / mean(ins) if mean(ins) else 0
    f["months_observed"]    = len(by_month)

    # Salary credits: same-ish amount, same-ish day each month
    sal = [t for t in txns if t["type"] == "credit"
           and any(k in t["narration"].upper()
                   for k in ("SALARY", "SAL ", "NEFT-SAL", "PAYROLL"))]
    f["salary_months"] = len({t["date"][:7] for t in sal})
    f["is_salaried"]   = f["salary_months"] >= max(3, len(by_month) * 0.6)

    # --- Obligations: existing EMIs are the affordability denominator ---
    emi = [t for t in txns if t["type"] == "debit"
           and any(k in t["narration"].upper()
                   for k in ("EMI", "ACH-D", "NACH", "LOAN", "ECS"))]
    emi_by_month = defaultdict(float)
    for t in emi:
        emi_by_month[t["date"][:7]] += t["amount"]
    f["avg_monthly_emi"] = mean(emi_by_month.values()) if emi_by_month else 0.0
    f["foir"] = (f["avg_monthly_emi"] / f["avg_monthly_inflow"]
                 if f["avg_monthly_inflow"] else 1.0)   # fixed-obligation ratio

    # --- Distress signals: the highest-value features in this set ---
    bounces = [t for t in txns if any(k in t["narration"].upper()
               for k in ("RETURN", "BOUNCE", "INSUFFICIENT", "ECS RTN", "CHQ RTN"))]
    f["bounce_count_12m"]  = len(bounces)
    f["bounce_months"]     = len({t["date"][:7] for t in bounces})
    f["has_recent_bounce"] = any(t["date"][:7] in sorted(by_month)[-3:] for t in bounces)

    # --- Buffer: does money survive the month? ---
    f["avg_monthly_surplus"] = mean(ins) - mean(outs)
    f["surplus_ratio"] = f["avg_monthly_surplus"] / mean(ins) if mean(ins) else 0

    return f

# Note what is NOT here: no device model, no contact list, no location,
# no app-usage. Those are either prohibited under the RBI digital lending
# rules or carry serious proxy-discrimination risk. See the Advanced lane.

import numpy as np

# Map each raw feature to a REGULATOR-FACING reason group.
# The group is what the applicant sees. Grouping matters: five features
# about repayment history should surface as one reason, not five.
FEATURE_TO_REASON = {
    "bounce_count_12m":    "RECENT_PAYMENT_RETURNS",
    "bounce_months":       "RECENT_PAYMENT_RETURNS",
    "has_recent_bounce":   "RECENT_PAYMENT_RETURNS",
    "foir":                "EXISTING_OBLIGATIONS_HIGH",
    "avg_monthly_emi":     "EXISTING_OBLIGATIONS_HIGH",
    "avg_monthly_inflow":  "INCOME_BELOW_REQUIREMENT",
    "surplus_ratio":       "INSUFFICIENT_SURPLUS",
    "inflow_volatility":   "INCOME_NOT_STABLE",
    "months_observed":     "INSUFFICIENT_HISTORY",
    "bureau_score":        "CREDIT_BUREAU_HISTORY",
    "bureau_dpd_max":      "CREDIT_BUREAU_HISTORY",
    "enquiries_6m":        "RECENT_CREDIT_SEEKING",
}

REASON_TEXT = {
    "RECENT_PAYMENT_RETURNS":    "Recent returned or bounced payments on your bank account",
    "EXISTING_OBLIGATIONS_HIGH": "Existing loan repayments are high relative to your income",
    "INCOME_BELOW_REQUIREMENT":  "Income is below the level required for this product",
    "INSUFFICIENT_SURPLUS":      "Limited surplus remaining after monthly expenses",
    "INCOME_NOT_STABLE":         "Income received varies significantly month to month",
    "INSUFFICIENT_HISTORY":      "Not enough account history available to assess",
    "CREDIT_BUREAU_HISTORY":     "Repayment history reported by the credit bureau",
    "RECENT_CREDIT_SEEKING":     "Several recent applications for credit",
}

def adverse_action_reasons(shap_values, feature_names, top_n=3):
    """Group SHAP contributions by reason, keep only those pushing
    TOWARD decline, rank, and return the top N.

    DETERMINISM IS A HARD REQUIREMENT. The same applicant with the same
    data must produce the same reasons in the same order, every time.
    Ties are broken by reason code alphabetically, never by dict order."""
    grouped = {}
    for name, sv in zip(feature_names, shap_values):
        reason = FEATURE_TO_REASON.get(name)
        if reason is None:
            continue                      # unmapped feature -> see assertion below
        grouped[reason] = grouped.get(reason, 0.0) + float(sv)

    # Sign convention: positive SHAP = pushes toward higher default risk
    adverse = {r: v for r, v in grouped.items() if v > 0}

    ranked = sorted(adverse.items(), key=lambda kv: (-round(kv[1], 10), kv[0]))
    return [{"code": r, "text": REASON_TEXT[r], "contribution": round(v, 6)}
            for r, v in ranked[:top_n]]

def assert_all_features_mapped(feature_names):
    """Run in CI. An unmapped feature means a decision could be driven by
    something you cannot explain to an applicant or a regulator."""
    missing = [f for f in feature_names if f not in FEATURE_TO_REASON]
    assert not missing, f"Unmapped features cannot be used in a credit model: {missing}"

You are a credit risk head who has built underwriting policy for
Indian NBFCs and fintech lenders.

My product:
- Loan type and ticket size: [e.g. unsecured personal, Rs 25k-2L]
- Target segment: [e.g. salaried tier-2, self-employed, MSME, gig]
- Tenure: [e.g. 6-24 months]
- Expected volume: [applications per month]
- Data I can access: [bureau / AA / GST / EPFO / UPI / none yet]
- Licence position: [own NBFC / partner with an NBFC / unlicensed]

Give me:

1. An underwriting waterfall - which checks in which order, and why
   that order minimises data cost per decision.
2. The 15-20 features I should build first, and which data source
   each comes from.
3. Hard-rule declines that should happen BEFORE any model runs.
4. A starting policy grid: score band x FOIR band -> decision and limit.
5. The adverse action reason codes I will need, mapped to features.
6. What my approval rate and early-delinquency rate should roughly
   look like in months 1-6 if the policy is calibrated sensibly, and
   what it means if they diverge.
7. The three ways this policy will most likely be gamed.

Be specific to the Indian context. Flag where you are uncertain or
where current regulation should be checked with a qualified adviser.

from collections import defaultdict

def disparate_impact(decisions, groups):
    """decisions: list of 'approve'|'decline'
       groups:    list of protected-attribute labels, SAME ORDER

    The four-fifths rule: if the approval rate for any group falls below
    80% of the highest group's rate, that is a flag requiring investigation.
    It is a screening heuristic, not a legal test, and it applies to
    outcomes - not to whether the attribute was an input."""
    tot, appr = defaultdict(int), defaultdict(int)
    for d, g in zip(decisions, groups):
        tot[g] += 1
        if d == "approve":
            appr[g] += 1

    rates = {g: appr[g] / tot[g] for g in tot if tot[g] >= 100}
    if not rates:
        return {"error": "insufficient volume per group"}

    best = max(rates.values())
    return {
        "approval_rates": rates,
        "impact_ratios": {g: (r / best) for g, r in rates.items()},
        "flags": [g for g, r in rates.items() if best and (r / best) < 0.80],
    }

def proxy_strength(feature_values, protected_labels):
    """How well does a single feature predict the protected attribute?
    High AUC here means the feature is carrying demographic signal,
    whether or not you intended it to."""
    from sklearn.linear_model import LogisticRegression
    from sklearn.model_selection import cross_val_score
    import numpy as np
    X = np.array(feature_values).reshape(-1, 1)
    y = np.array(protected_labels)
    auc = cross_val_score(LogisticRegression(max_iter=1000), X, y,
                          cv=5, scoring="roc_auc").mean()
    return {"proxy_auc": auc,
            "assessment": "strong proxy" if auc > 0.70
                          else "moderate proxy" if auc > 0.60
                          else "weak"}

Revenue
  interest earned over expected life
  + processing fee
  - cost of funds

Costs
  - acquisition cost / approval rate        <- declined applicants cost you too
  - data cost per application / approval rate
  - expected credit loss (PD x LGD x EAD)
  - servicing and collections cost
  = contribution per loan

The term everyone underestimates:
  data cost per APPROVAL, not per application.

  At a 20% approval rate, Rs 60 of data pulls per application
  becomes Rs 300 per approved loan. On a Rs 25,000 ticket at
  thin margins, that is not a rounding error.

The lever most teams miss:
  Declining cheaply is worth as much as approving accurately.
  Every rupee of data spent on an applicant you were always
  going to decline is pure loss.

{
  "decision_id": "dec_01HXZ...",
  "application_id": "app_7741",
  "timestamp": "2026-05-22T10:02:11Z",

  "data_sources": [
    {"source": "cibil", "pulled_at": "...", "ref": "enq_9912", "cost_paise": 4500},
    {"source": "aa_bank_statement", "consent_ref": "cons_441a",
     "months": 12, "accounts": 1}
  ],

  "features_snapshot": { "...": "full feature vector as scored" },
  "feature_null_count": 0,

  "model": {
    "name": "pd_unsecured_v3",
    "version": "3.4.2",
    "trained_on": "2026-02-18",
    "score": 0.0731,
    "score_band": "B2"
  },

  "policy": {
    "version": "credit-policy-v11",
    "hard_rules_passed": ["age", "geo", "kyc_complete"],
    "hard_rules_failed": [],
    "foir_computed": 0.41,
    "foir_cap": 0.50
  },

  "decision": {
    "outcome": "approve",
    "limit": 120000, "tenure_months": 18, "apr": 0.24,
    "adverse_reasons": [],
    "human_override": null
  },

  "explainability": {
    "method": "TreeSHAP-exact",
    "reason_codes_computed": true,
    "determinism_hash": "sha256:7c1f..."
  }
}