Decision Engine Deep Dive

The Engine That Drives Every Loan Decision

Reads loan data, evaluates policy rules, and tells the UI and vendors what to do next.

File Data

Borrower + property + loan details

Decision Engine

Reads data Runs YAML policy Verdict per requirement

Entry point→engines/decision/api.py:318

Tri-logic enum→engines/decision/eval/eval_expr.py:43

Policy evaluator→engines/decision/eval/eval_policy.py:19

Borrower UI

What's still needed

Vendor Integrations

What to order next

ℹ️

Each requirement resolves to True, False, or Unknown — unknown triggers async vendor dispatch and re-evaluation when results arrive.

Four Subsystems, One Evaluation Pipeline

Each subsystem owns a distinct phase of the decision lifecycle.

Evaluation

Runs tri-logic expressions against borrower data — resolves each requirement to True, False, or Unknown

Core logic

Source→engines/decision/eval/

Schema

Defines the shape of policies, predicates, strategies, and expressions as typed structures

Type system

Source→engines/decision/schema/

Conditions

Tracks pending vendor orders — dispatches async work and triggers re-evaluation on completion

Async dispatch

Source→engines/decision/conditions/

Policies

Per-company YAML definitions — the business rules that drive every evaluation

Configuration

Source→engines/decision/policies/

ℹ️

The workflow engine orchestrates stage progression — it calls into the decision engine once per stage, feeding updated data each time.

From File to Verdict in Three Steps

The decision engine routes, loads, and evaluates.

Borrower File

Company config determines which rules apply

LRU loader→engines/decision/api.py:116

Example YAML→engines/decision/policies/PATTERSON_FCU/dispatch.yaml

Route & Load

Picks the right manifest and loads policy stages

Dispatch→engines/decision/api.py:97

Dispatch schema→engines/decision/schema/dispatch.py

Manifest schema→engines/decision/schema/manifest.py

Evaluate Each Stage

Runs YAML policy against File data — tri-logic verdict per requirement

Stage Result

Each stage resolves to one of two outcomes

Pass

Advance to next stage

Fail

Hold — return what's still needed

What the Engine Does

Build input, load policy, evaluate, cache, and dispatch.

Input Construction

Transforms a File into a frozen input snapshot and loads condition state

File → DecisionInput

Builder→engines/decision/api.py:209

Policy Loading

Resolves and caches manifests and policy definitions per company

LRU-cached

LRU cache→engines/decision/api.py:51

Evaluation

Routes to the right manifest, then evaluates policy against input data

Core entry points

Serialization

Encodes and decodes results for caching between evaluation runs

Binary format

Serialize→engines/decision/api.py:348

Condition Management

Checks whether a vendor condition already exists, and creates new ones when the engine needs async resolution

Async vendor dispatch

Conditions→engines/decision/api.py:356

Consumer→app/borrower/views/decision_result.py

Every Evaluation Starts With a Snapshot

The engine freezes all borrower, loan, and property data into a single immutable input.

People

Borrower and coborrower identity, demographics, employment, and income

Borrower Coborrower

DecisionInput→engines/decision/input.py

Financials

Credit score, DTI, assets, liabilities, and consent flags

Credit Income

FieldEnum→engines/decision/enums.py:197

Property

Address, type, valuation, occupancy, and lien position

Subject property

Loan

Amount, type, purpose, and program parameters

Loan details

Satisfy Codes Are the Engine's Vocabulary

Named codes map borrower data to policy rules.

Identity

Borrower & coborrower names, SSN, date of birth

_present + _supported

SatisfyCodesEnum→engines/decision/enums.py:27

Credit & Financials

Score, DTI, assets, liabilities, consent

Employment & Income

Borrower and coborrower jobs, income verification

Property & Loan

Address, valuation, occupancy, loan amount, type, purpose

Demographics

Race, ethnicity, sex — HMDA compliance fields

Conditions

Vendor orders: flood, title, appraisal, credit pull, govt ID

Async dispatch

ConditionTypeEnum→engines/decision/enums.py:173

ℹ️

Codes follow a _present / _supported pattern — "present" checks if data exists, "supported" checks if the value is within policy bounds.

Two Phases Decide Every Requirement

First check if the requirement applies, then check if it's satisfied.

Phase 1 — Applicability

Has a when guard?

eval_req()→engines/decision/eval/eval_req.py:46

Req schema→engines/decision/schema/policy.py:35

No

Always applies

Yes

Evaluate the guard → T / F / U

Phase 2 — Satisfaction

Has satisfied_when?

No

Auto-satisfied

Yes

Evaluate → T / F / U

ℹ️

If satisfaction fails, the engine checks for strategies — vendor orders or document requests that could resolve the requirement.

Failed Requirements Trigger Strategies

Unsatisfied requirements get a resolution strategy.

Strategy Flow

Requirement Failed

Satisfied = False

EvalReqResult→engines/decision/eval/eval_req.py:24

Walk Strategy List

First match wins

determine_strategy()→engines/decision/eval/eval_req.py:33

Match

Execute strategy

No Match

Stays unresolved

Result Structure

class EvalReqResult:
    code: SatisfyCodesEnum
    applies: Tri
    satisfied: Tri
    missing: frozenset[FieldEnum]
    strategy: StrategyTypes | None
    ui: UIResult | None  # deprecated

Two Ways to Resolve a Failed Requirement

Strategies either request documents or order vendor work.

Unsatisfied Requirement

Satisfied = False — engine looks for a resolution path

Request Strategies

Ask the borrower to upload a document — the condition resolves when the file arrives

Govt ID Mortgage statement Insurance

StrategyTypes→engines/decision/schema/strategy.py:174

StrategyEnum→engines/decision/enums.py:149

Order Strategies

Place a vendor integration automatically — the condition resolves when results come back

Credit pull AVM Flood VOE / VOI Title

create_condition()→engines/decision/conditions/utils.py:128

ℹ️

Both families create a condition record in the database — when the condition resolves, the engine automatically re-evaluates the requirement.

Conditions Flow Through an Async Pipeline

Queued, prepped, ordered, and re-evaluated on completion.

Condition Queued

Strategy dispatch creates a condition record

Queue worker→engines/decision/tasks.py:16

Context→engines/decision/conditions/context.py:9

Prep & Order

Worker prepares vendor-specific data and places the order

Credit AVM Flood Title VOE / VOI

Runner→engines/decision/conditions/run.py

Vendor prep→engines/decision/conditions/prep/

Results Arrive

Vendor callback triggers re-evaluation

Condition Status Progression

Waiting

Submitted

Working

Complete

StatusEnum→engines/decision/enums.py:140

Where To Go Next

This deck covered the evaluation core. Related deep dives:

💡

Key Takeaways

Unknown ≠ Failed — Unknown means "not enough data yet," it keeps the form open without triggering a strategy.
Strategy dispatch is async — conditions queue through a background worker before vendor orders are placed.

Navigation

Borrower UI - Application