Alternative Credit Scoring: How to Build It

from datetime import date, timedelta

# STEP 2. CLASSIFY EVERY FIELD BEFORE IT REACHES A FEATURE STORE.
# An unknown field defaults to the STRICTEST class, never the loosest -- the
# same rule as cross-border classification in Build Sheet 08. The difference
# here is that "prohibited" means prohibited, not "needs a stronger consent".

PROHIBITED = {"contacts", "call_logs", "media_files", "installed_apps_list",
              "sms_inbox"}          # Digital Lending Directions 2025

def admit(field, consents):
    if field["name"] in PROHIBITED:
        raise ValueError("prohibited source: %s" % field["name"])
    c = consents.get(field["name"])
    if c is None:
        return {"admit": False, "why": "no_consent_on_record"}
    if c["purpose"] != field["purpose"]:
        # Consent given to assess a loan does not cover marketing, collections
        # scoring, or a model you build next year.
        return {"admit": False, "why": "purpose_mismatch"}
    if c["expires_on"] < date.today():
        return {"admit": False, "why": "consent_expired"}
    return {"admit": True, "consent_id": c["id"]}

# STEP 3. TWO CLOCKS AND ONE SIDE EFFECT.
# A bureau pull is visible to the customer: CICs must alert the consumer by
# SMS or email whenever a specified user accesses their credit information
# report. "Pull everything and decide later" is not a silent design.

def pull_plan(applicant, ticket_paise):
    plan = ["own_records"]                    # free, silent, already consented
    if ticket_paise > 2_500_000:              # only then is a hard pull earned
        plan.append("bureau_full")
    else:
        plan.append("bureau_soft")
    if applicant["has_bank_consent"]:
        plan.append("aa_statements")          # verify the artefact SIGNATURE
    if applicant["is_business"]:
        plan.append("gst_returns")
    return plan

# STEP 4. LINEAGE. A feature that cannot name its field and its consent is a
# feature you cannot defend, retire or explain.

def build_feature(name, value, field, consent_id, window_days):
    return {"name": name, "value": value,
            "source_field": field,            # what it came from
            "consent_id": consent_id,         # under which permission
            "window_days": window_days,       # over what period
            "computed_on": date.today().isoformat(),
            "retire_on": (date.today() + timedelta(days=window_days)).isoformat()}

# WHAT TO CHECK
# [ ] every feature resolves to a field AND a consent id. No exceptions, no
#     "derived so it does not count" -- a score computed from a field IS that
#     field for purpose and residency
# [ ] an unrecognised field is refused, not admitted with a warning
# [ ] a soft pull and a hard pull are different products with different
#     customer-visible consequences. Decide which one each journey earns
# [ ] bureau data is processed and stored in India and not transferred out
# [ ] the AA consent artefact signature is VERIFIED, not assumed
# [ ] retention is per-feature, not one global sweep. Your warehouse, feature
#     store, training set and backups all received a copy within the hour

# STEP 7. THE DECISION. THIS IS THE STEP THAT CARRIES THE OBLIGATION.
# Under the credit information framework a lender must inform the customer the
# reasons for rejection. Under the draft MRM guidance, credit underwriting is
# material decision-making and attracts a higher explainability threshold.
#
# You cannot reconstruct a reason later. Six months from now the model has
# been retrained, the thresholds have moved and the feature set has changed.
# The question is always: why did you decline THIS person on THAT day.

THREE_OUTCOMES = ("APPROVE", "REFER", "DECLINE")   # never two

def decide(applicant, score, features, model, policy):
    outcome = ("APPROVE" if score >= policy["approve_at"]
               else "REFER" if score >= policy["refer_at"]
               else "DECLINE")
    record = {
        "applicant_id": applicant["id"],
        "outcome": outcome,
        "score": score,
        "model_id": model["id"],                 # the RESOLVED version
        "model_version": model["version"],       # never the alias
        "policy_version": policy["version"],
        "thresholds": dict(policy),              # as they were TODAY
        "top_reasons": top_reasons(features, model),   # human-readable, ranked
        "features_snapshot": features,           # the blob, not a recipe
        "decided_at_ist": now_ist(),
    }
    if outcome == "DECLINE":
        # Must be sayable to the customer in plain words, and must be TRUE of
        # this decision -- not a generic list of things that usually matter.
        assert record["top_reasons"], "a decline with no stated reason is not shippable"
    return record

# A model that cannot explain itself is not banned. It is EXPENSIVE: the draft
# guidance requires enhanced validation, output verification, more frequent
# monitoring and USAGE RESTRICTIONS to compensate. Price that before choosing
# the architecture, because it is a permanent operating cost and not a one-off.

def explainability_budget(model):
    if model["explainable"]:
        return {"validation": "standard", "monitoring": "quarterly"}
    return {"validation": "enhanced", "output_verification": True,
            "monitoring": "monthly", "usage_restrictions": True}

# STEP 8. AFTER THE DECISION.
def monitor(model, window):
    return {
        "psi_by_feature": population_stability(window),     # drift
        "approval_rate_by_district": rate_by(window, "district"),
        "override_rate": rate_of_human_overrides(window),
        "decline_reasons_distribution": reasons_hist(window),
        "kill_switch": model["runtime_flag"],   # a flag, not a deploy
        "fallback_share": share_that_fell_back_to_rules(window),
    }

# WHAT TO CHECK
# [ ] three outcomes, never two. An automatic decline on a thin file is
#     usually wrong -- route to a human and let a person decline
# [ ] the stored reason is the reason for THIS decision, not a template
# [ ] log the RESOLVED model version. A vendor moving an alias changes your
#     decisions with no deploy on your side
# [ ] the kill switch is a runtime flag, and someone other than the model
#     owner can pull it
# [ ] human override rate under ~1% is a rubber stamp and worse than no human,
#     because it manufactures the appearance of oversight
# [ ] plot the share of decisions that FELL BACK to rules. Zero means the
#     fallback has never run and you do not know that it works
# [ ] reconcile and aggregate in IST. A UTC day boundary moves 5.5 hours of
#     decisions into the wrong reporting day, every day