Pricing Engine & Offers

Pricing Engine & Offer Generation

From borrower data to eligible offer: program matching, rate calculation, and fee assembly

How a loan offer is built

Borrower Data

Program Match

Rate & Fee Calc

Eligible Offer

Supported product types

HELOAN

Fixed-rate home equity loan — lump-sum disbursement

HELOC

Variable-rate line of credit — draw as needed

ℹ️

Each product defines its own rate, fee, and eligibility schema

Four Subsystems, One Pipeline

The pricing engine is a standalone service

Public API

Constructs inputs and orchestrates the pipeline

make_input→Builds flat input from borrower + program data

offers→Returns scored, audited offers per program

make_input()→pricing/api.py:103

offers()→pricing/api.py:49

Calculation Pipeline

Runs each pricing step in sequence

Eligibility→Pass/fail gate per program rules

Rate→Base rate plus tier adjustments

APR→Annualized cost including fees

Fees→Origination, third-party, and waiver logic

calc_offer()→pricing/calc/offers.py:22

Program Resolver

Applies conditional adjustments from program schemas

HELOAN→Fixed-rate, lump-sum product rules

HELOC→Variable-rate, draw-based product rules

resolve_program()→pricing/resolver/program.py:36

Schema Definitions

Structs define each program's rules

msgspec→Serializable Python structs for validation

YAML→Human-readable config for rate tiers and fees

HELOAN→pricing/schema/heloan.py

HELOC→pricing/schema/heloc.py

ℹ️

Standalone by design — the pricing engine takes a flat input and returns offers. It never reads the File or triggers reactor events.

Flat Input, Two Product Shapes

The engine takes borrower + property data and matches it against product-specific program schemas

Pricing Input Structure

lc/engines/pricing/input.py — PricingInput

@dataclass(frozen=True, slots=True, kw_only=True)
class PricingInput:
    property_value: int | None
    occupancy: Occupancy | None
    purpose: LoanPurpose | None
    state: State | None
    property_type: PropertyType | None
    credit_score: int | None
    cltv: Decimal | None
    loan_amount: Decimal | None
    lien_position: LienPosition | None
    lien_balance: Decimal | None

ℹ️

Every field is optional. The engine evaluates what it can with available data.

Product schemas

HELOAN

Closed-end amortizing loan, fixed term, single disbursement

Rate→Fixed

Term→30-year

Disbursement→Single draw

HELOANStructure→pricing/schema/heloan.py:11

HELOC

Open-end revolving line with draw period then repayment period

Rate→Variable

Periods→Draw + Repay

Draws→Interest-only during draw period

HELOCStructure→pricing/schema/heloc.py:11

From Input to Offer

Each program runs through a sequential pipeline, every step is audited

DeriveInput extraction

CLTV

Combined loan-to-value from liens + property value

pricing/calc/cltv.py

Max loan

Upper bound from program and LTV limits

pricing/calc/max_loan_amount.py

Prime rate

Current index rate lookup for variable products

pricing/calc/offers.py:28-30

CheckEligibility gate

State

Licensing and regulatory restrictions

pricing/calc/eligibility.py:287

Credit floor

Minimum score per program tier

pricing/calc/eligibility.py:287

LTV cap

Max CLTV for product and occupancy type

pricing/calc/eligibility.py:287

PriceRate + fees

Rate

Index + margin, then credit and LTV adjustments

pricing/calc/rate.py

Payment

PMT formula for amortizing or interest-only

pricing/calc/payment.py

Fees

Origination, third-party, and waiver rules per program

pricing/calc/fees.py

FinalizeOutput assembly

APR

Closed-end vs open-end calculation method

pricing/calc/apr.py

Rounding

Per-field precision rules for rate, payment, fees

pricing/calc/rounding.py

Audit

Every intermediate value logged for compliance

pricing/audit.py

Three Rule Systems Shape Every Offer

Three rule systems, one expression evaluator

Eligibility Gates

Hard constraints that reject a program outright. Credit score range, CLTV cap, allowed states and property types

Pass / Fail Per-program

EligibilitySchema→pricing/schema/eligibility.py:70

resolve_eligibility()→pricing/resolver/eligibility.py:53

Conditional Adjustments

Modify limits and rates based on borrower profile. Each adjustment fires only when its condition matches

Loan limits CLTV caps Rate margin

resolve_rate()→pricing/resolver/rate.py:29

Tri / eval_expr()→pricing/eval/eval_expr.py:25,57

Expressions→pricing/schema/expr.py

Fee Rules

Per-fee calculation with conditional application. Percentage of loan or flat amount, with optional min/cap

Conditional Finance charge

FeeSchema→pricing/schema/fees.py:18

ℹ️

Same tri-logic everywhere: all conditional expressions use True / False / Unknown evaluation. Unknown on a fee aborts pricing; unknown on an adjustment is silently skipped.

Four Outcomes, Always Audited

Every program evaluation produces one of four result types

Eligible

Passed all checks. Includes rate, APR, payment, and fees

Full offer

pricing/offer.py:14

Ineligible

At least one constraint failed. Includes which constraints and why

Fail reasons

pricing/offer.py:27

Abort

Missing required input. Cannot evaluate, includes diagnostic info

Missing data

pricing/offer.py:38

Error

Unexpected exception. Caught and wrapped rather than thrown

Exception

pricing/offer.py:33

Two API surfaces

Admin API

Accepts explicit input fields. Returns full audit trail for debugging

PricingOffers→app/views/pricing/offers.py:13

Borrower API

Pulls from borrower's file. Audit trail stripped for security

BorrowerPricing→app/borrower/views/pricing.py:19

Strip audit→app/borrower/views/pricing.py:92-93

Key Takeaways

Core design principles of the pricing engine

Standalone

Flat input in, offers out. No dependency on the reactor, decision engine, or file system

Auditable

Every adjustment, constraint check, and fee evaluation is recorded. Even failures carry a full trail

Extensible

New products are YAML program schemas. Eligibility, rate, and fee rules are all data-driven

Navigation

Pricing Engine & Offer Generation

Four Subsystems, One Pipeline

Flat Input, Two Product Shapes

From Input to Offer

Three Rule Systems Shape Every Offer

Four Outcomes, Always Audited

Key Takeaways

Keyboard Shortcuts