Estimate a loan applicant's probability of default.

Use this to get a single risk number for one borrower. Describe the applicant in plain terms — only annual income and loan amount are required; every other field falls back to the population median when omitted.

Returns a dict with:

• default_probability: estimated probability of default (0-1)

• risk_tier: "low" / "moderate" / "elevated" / "high"

• flag_default: True if the probability is at or above the 0.15 decision threshold (this model is tuned for recall, not a 50% cutoff)

• threshold_used: the decision threshold (0.15)

• fields_defaulted: which optional fields fell back to medians

Educational model trained on a Kaggle dataset — not real lending advice.

Explain a default-risk prediction: which factors push risk up or down.

Use this when the user wants the "why" behind a score, not just the number. Runs SHAP on the single applicant and returns the strongest contributing features with human-readable names.

Args: profile: the applicant to explain. top_n: how many contributing factors to return (default 8).

Returns a dict with default_probability, risk_tier, and top_factors — a list of {feature, friendly_name, value, shap_contribution, direction} ordered by impact, where direction is "increases risk" or "decreases risk".

Educational model — not real lending advice.

Describe the model itself: type, performance, and limitations.

Use this to answer questions about how good the model is or how it should be used — no borrower needed. Returns model type, feature count, training size, AUC-ROC, precision/recall at the 0.50 and 0.15 thresholds, the recommended threshold, and an honest limitations note (educational, not real lending advice).

Return the model's globally most important features (by mean |SHAP|).

Use this for "what drives this model overall?" questions, as opposed to the reasons behind one borrower's score. Returns {"top_features": [...]} ranked by average absolute SHAP impact across a sample, each entry carrying its raw name, a friendly name, and its importance score.

Args: top_n: how many features to return (default 10).

Score several applicants at once and rank them from most to least risky.

Use this to compare a batch of borrowers side by side. Each profile is scored exactly like score_borrower.

Args: profiles: two or more applicants to compare.

Returns {"ranked": [...]} sorted by default_probability descending. Each entry has: rank (1 = riskiest), index (position in the input list), default_probability, and risk_tier.

Educational model — not real lending advice.