Credit engine//credit-rules-engine
Credit rules engine
Your team's scoring brain — configurable, versioned rules per loan product, with a complete variable catalog.
Credit rules engine
The rules engine is where your team defines how a bank statement becomes a score and a decision. It is declarative — no code, no free-text to evaluate — so every rule is a value you can read, toggle and audit. The engine is per team and per loan product, every edit publishes a new immutable version, and the version that scored an analysis is recorded in its decision trace.
Per team, per product
Rules live at the team level. Each team ships on day one with two default products — a Monthly EMI loan and a Daily EDI loan — and can rename, clone (start from a template), add and turn products on or off. A monthly-EMI product carries only EMI + shared parameters; a daily-EDI product only EDI + shared parameters — a product never shows the other loan type's knobs.
Only a team admin can change rules; any member may read them. Because API keys are per user and scoped to that user's org/team, every org configures and runs analyses under its own ruleset automatically — there is no shared global policy.
Two kinds of rule
A ruleset is an ordered list of rules of two kinds.
Parameter rules
A parameter sets a named policy value the decision consumes. Examples:
| Parameter | What it sets |
|---|---|
foir | FOIR limit — EMIs as a share of income |
min_approve / min_conditional | Score floors for approve / conditional approve |
max_explained_rise | Most the AI may raise the scorecard score |
interest_rate, tenure_months, min_loan_amount | How a repayable EMI becomes a loan offer (EMI product) |
abb_emi_cover, cash_weight, implied_emi_rate | How affordability and income are computed |
bureau_enabled, bureau_required, bureau_weight, bureau_repull_days | Credit-bureau behaviour |
edi_daily_share, edi_min_covered_days, edi_tenure_days, edi_rate, … | The daily-loan (EDI) collection model |
ai_risk_sense_enabled | Whether the AI risk-sense second opinion runs |
Numeric parameters can be amount-tiered — the value changes with the requested loan amount.
Condition rules
A condition is feature operator value → action, evaluated against the finished
analysis through the variable catalog below. For example bureau shows a written-off
account → send to manual review, or gambling detected → flag. Operators are a
closed set chosen by the feature's data type:
| Data type | Operators |
|---|---|
| number / money / percent / count | gt gte lt lte eq ne between |
| bool | is true / is false |
| enum | eq ne in not in |
The four actions
A condition can do exactly one of four things — a closed set the engine actually enforces:
| Action | In the UI | Effect |
|---|---|---|
knockout_decline | Decline | Forces the decision to Decline. |
knockout_refer | Send to manual review | Sends the file to a human. |
score_delta | Adjust the score | Adds or removes signed points from the score. |
flag | Flag it for the officer | Raises a note; no change to score or decision. |
Mandatory, optional and locked
Every rule carries three platform flags:
- Mandatory — always enforced, cannot be switched off. The four safety checks — document-tamper, unreconciled rows, name-mismatch and mule pattern — are mandatory in every product.
- Optional — ships enabled at a sensible default; the admin may toggle it off or re-tune it (for example 90+ DPD → flag, loan stacking ≥ 5 lenders → flag).
- Value-locked — the on/off toggle works but the value is fixed by the platform.
A Changed badge marks any rule whose value or on/off state differs from its shipped default, so you can see at a glance what your team has tuned.
Configuring rules (admin UI)
In Rules engine (admin only) each product shows its rules grouped into scoring layers. You can:
- Toggle a rule on or off (mandatory rules stay on).
- Edit a value — unless it is locked.
- Amount bands — switch a numeric parameter from a flat value to "by amount" tiers, and back with "use one flat value".
- Add a rule — pick any variable from the catalog, a comparison and a value, then an action. Choose "Adjust the score" and enter signed points (negative = penalty, positive = bonus). Custom rules you add can be removed; shipped defaults and parameters cannot.
- Reset — restore the product to its shipped default ruleset, behind a confirm. A reset is itself a new version, so the change stays in the audit trail.
How a rule actually changes the outcome
Configured rules fold into the decision in one coherent pass, so the score, band, FOIR, decision and offer never contradict each other:
- The scorecard + AI committee produce a baseline score.
- Every enabled "Adjust the score" rule contributes its signed points
(
score_delta), applied to the final score before the band, decision, FOIR and offer are derived — a deterministic knob, not an AI claim. - Any knockout downgrades the decision stricter-only and zeroes the offer, so a knocked-out file shows no loan.
- The fired rules, their reason codes and the net score delta are stored as the decision trace for audit, under the product and ruleset version that ran.
See scoring layers for the full pipeline and reason-code trace.
The variable catalog
Every condition tests a variable from this catalog — the single source of truth the rule builder reads for its feature dropdown, data types and operators. Adding a new variable server-side makes it appear in the UI automatically; nothing here is hand-maintained in two places.
Score & document
| Variable | Meaning | Type |
|---|---|---|
| Final credit score | The committee's final score after policy (300–900) | number |
| Scorecard score | The score before the AI and policy adjust it | number |
| Document tampering risk | Whether the PDF looks edited (High) or genuine (Low) | enum |
| Unreconciled rows (share) | Share of transactions that don't add up to the printed running balance | percent |
Capacity & affordability
| Variable | Meaning | Type |
|---|---|---|
| Average monthly income | Average monthly inflow used for affordability | money |
| Existing EMIs / month | Monthly obligations already being paid | money |
| FOIR headroom / month | Room left under the FOIR limit each month | money |
| Average bank balance | ABB across the statement period | money |
| Max new EMI / month | Largest new EMI the statement can support | money |
| Minimum end-of-day balance | The lowest end-of-day balance in the period — liquidity floor | money |
Obligations (bureau ⇄ statement merge)
| Variable | Meaning | Type |
|---|---|---|
| Merged obligations / month | Reconciled bureau + statement EMIs that drive FOIR | money |
| Hidden loans (not in bureau) | Loan EMIs seen in the statement the bureau doesn't report | count |
Risk
| Variable | Meaning | Type |
|---|---|---|
| Serious warning signs | How many red risk warnings the statement analysis raised | count |
| Active lenders (6 months) | Lenders being actively repaid in the last 6 months (loan stacking) | count |
| Pass-through (mule) pattern | Money from many unrelated people leaving the same day | bool |
| Payment bounces / returns | Total bounced / returned transactions across the period | count |
Identity
| Variable | Meaning | Type |
|---|---|---|
| Statement name matches applicant | Whether the account holder is the applicant | bool |
| Name match score | How closely the names match | percent |
Applicant (derived, not asked on a form)
| Variable | Meaning | Type |
|---|---|---|
| Employment type | Salaried if a regular salary drives affordability, else self-employed | enum |
| Applicant age | From the bureau's date of birth (only when a bureau report was fetched) | number |
| Applicant gender | From the bureau (only when a bureau report was fetched) | enum |
Bureau
| Variable | Meaning | Type |
|---|---|---|
| Bureau score | The credit bureau's score | number |
| Bureau active loans | Open loans on the credit report | count |
| Bureau monthly EMI total | Total monthly EMI across bureau loans | money |
| Bureau amount overdue | Amount currently overdue on the bureau | money |
| Bureau written-off accounts | Loans never fully repaid (written off) | count |
| Bureau settled accounts | Loans closed for less than the full amount owed | count |
| Bureau suit-filed accounts | Loans a lender has taken to court over | count |
| Bureau worst days-past-due | Most days ever late on a loan | count |
| Bureau enquiries (90 days) | Lenders who checked this applicant's credit in 90 days | count |
| Bureau enquiries (30 days) | Credit enquiries in the last 30 days — short-window credit hunger | count |
| Bureau total accounts | All loan/card accounts, open + closed | count |
| Bureau total outstanding | Total current balance owed across active accounts | money |
| Credit history length (months) | Months since the oldest tradeline opened — thin-file / stability | count |
| Accounts ever 90+ DPD | Bureau accounts ever 90+ days past due — serious delinquency | count |
| Accounts currently delinquent | Active accounts with an overdue amount or live DPD | count |
| New loans opened (6 months) | Accounts opened in the last 6 months — recent leverage | count |
| Overdue ÷ outstanding (%) | Share of the outstanding balance that is overdue | number |
| Debt-to-income (%) | Total bureau outstanding ÷ annual income (from the statement) | number |
AI review
| Variable | Meaning | Type |
|---|---|---|
| AI risk-sense concern | An AI reviewer's overall concern (none / low / medium / high) | enum |
| AI risk-sense findings | How many extra concerns the AI raised beyond the standard checks | count |
Application & LTV
Per-loan anchors the officer enters at upload — data a statement can't provide.
| Variable | Meaning | Type |
|---|---|---|
| Requested loan amount | The amount asked for — drives LTV and amount tiers | money |
| Collateral value — gold / property | Market value of the pledged asset | money |
| Annual GST turnover | Business turnover for MSME / working-capital sizing | money |
| Down payment | Upfront amount (vehicle / consumer-durable loans) | money |
| Loan-to-value (LTV %) | Requested amount ÷ collateral value, as a percent | number |
Scenarios
LoanPilot detects 26 spending scenarios in the statement; each is auto-registered as two catalog variables you can write rules on:
… detected— bool, true when the scenario is present.… — share of outflow (%)— number (0–100), its share of total outflow.
Scenarios are grouped by their signal — risk (gambling, crypto, private lending, legal/fines), stress (medical, digital-lending apps, gold loan/pawn), stability (salary, insurance, staff wages, taxes, utilities), and informational (the rest). Adding a scenario server-side auto-registers its variables here, so the rule builder lists them without any further change.