Credit engine//scoring-layers
Scoring layers
How the rules are organised into a top-to-bottom decision pipeline, and how score and knockouts fold into one call.
Scoring layers
Every rule belongs to one of five layers (plus AI). The layers organise the rules engine UI and describe the order in which a file is judged — a knockout stops it before scoring, score adjustments feed the scorecard, affordability sizes the offer. In the UI the layers are numbered over the layers that actually have rules, so there is never a confusing gap.
| Layer | What it does | What routes here |
|---|---|---|
| 2 · Fraud & integrity | Document tampering, name-mismatch, unreconciled rows and mule checks. A hit sends the file to manual review. | The four mandatory safety conditions |
| 3 · Credit knockouts | Bureau red-flags and score floors that stop a file. | Bureau write-off / suit / DPD / loan-stacking rules, the min_approve / min_conditional / max_explained_rise parameters, and any custom condition whose action is a knockout |
| 4 · Scorecard & scenarios | The points each signal adds or removes — this builds the credit score. | Every score adjustment and flag condition, including scenario rules |
| 5 · Affordability & offer | Caps the EMI and loan amount income and balances can support. | FOIR, ABB cover, interest rate, tenure, min loan, cash weight, and all EDI parameters |
| 6 · AI review | The AI reads the statement for anomalies and advises; it never sets the number. | ai_risk_sense_enabled and any ai_* condition |
Score adjustments vs knockouts
The two things a condition can do to the outcome behave very differently, and both fold into the decision in a single coherent pass — so the score, band, FOIR, decision and offer can never disagree:
- A score adjustment (
score_delta) contributes signed points. All enabled adjustments are summed and applied to the final score before the band, decision, FOIR and offer are derived. It is a deterministic policy knob, applied after the AI rise-limit, not an AI claim. The adjusted score then drives everything downstream. - A knockout downgrades the decision stricter-only:
knockout_refersends an approval to manual review,knockout_declineforces Decline. It can never loosen a decision. The most severe knockout wins (decline beats refer), and a knocked-out file has its offer zeroed — no loan is shown.
Reason codes & decision trace
Every rule that fires emits a stable reason code (for example BUREAU_WRITEOFF,
MULE, GAMBLING, LOAN_STACKING). After the single policy pass, LoanPilot records
a decision trace for the analysis containing:
- the reason codes of the rules that fired,
- the matched rule IDs,
- the net score delta applied,
- the knockout (if any),
- and the product + ruleset version the analysis ran under.
The trace is the decision's audit trail. It surfaces in the report as the "Rules that fired" card on the Decision tab, named under the product used, so an officer sees exactly which of your rules changed the call and why.
Eligibility (not shipped by default)
An "Eligibility" layer — minimum age, income floor, employment type, geography — is intentionally empty by default: an age or income cut-off that shipped on would reject real applicants no lender chose to exclude. Eligibility is per-lender; the variables exist (age and gender from the bureau, employment type derived from the statement) so you can add exactly the rules you need.