Co-Lending: How to Build It

from decimal import Decimal, ROUND_HALF_UP

# ONE rate to the borrower: the weighted average of the partners' rates,
# weighted by their funding share. The hurdle-rate model -- where each lender
# priced separately and the originator kept the difference -- is gone.

def blended_rate(legs) -> Decimal:
    """legs = [{'re':'BANK','share':Decimal('0.80'),'rate':Decimal('9.50')}, ...]"""
    total = sum(l["share"] for l in legs)
    assert total == Decimal("1"), f"shares must sum to 1, got {total}"
    for l in legs:
        # Each partner retains a minimum 10% of EVERY individual loan.
        # 2025 Directions: applies to BOTH sides, not just the NBFC.
        assert l["share"] >= Decimal("0.10"), f"{l['re']} below the 10% floor"
    r = sum(l["share"] * l["rate"] for l in legs)
    return r.quantize(Decimal("0.01"), ROUND_HALF_UP)

def borrower_apr(legs, fees_paise, principal_paise, tenure_months) -> Decimal:
    # Any charge the borrower pays on top of blended interest goes into the APR.
    # A fee that exists anywhere in the journey and is not in the APR makes the
    # APR wrong, and the APR is the binding number.
    return apr_from(principal_paise, fees_paise, blended_rate(legs), tenure_months)

def on_partner_rate_change(loan, re_id, new_rate):
    # A rate move by EITHER partner changes what the borrower pays. Servicing
    # must recompute, reschedule and re-disclose -- this is not a back-office
    # adjustment, it is a change to the customer's contract terms.
    legs = [dict(l, rate=new_rate) if l["re"] == re_id else l for l in loan["legs"]]
    new = blended_rate(legs)
    return {"old_blended": loan["blended_rate"], "new_blended": new,
            "reschedule": new != loan["blended_rate"],
            "fresh_kfs_required": new != loan["blended_rate"],
            "notify_borrower": True}

# WHAT TO CHECK
# [ ] the 10% floor is asserted PER LOAN, not per portfolio. A portfolio at 12%
#     containing individual loans at 4% does not comply
# [ ] shares sum to exactly 1. Use Decimal; a float rounding error here is a
#     mispriced loan
# [ ] blended rate recomputes on ANY partner rate change, and triggers a fresh
#     KFS. Teams build the rate once at origination and never revisit it
# [ ] every borrower charge is in the APR, not just the interest
# [ ] store the LEGS with the loan -- share and rate per partner, at that date.
#     Recomputing from today's rates cannot reproduce a historical instalment
# [ ] the borrower sees ONE rate. Showing two lenders' rates is the model the
#     Directions replaced

from datetime import timedelta

TRANSFER_WINDOW = timedelta(days=15)      # calendar days, not business days

def disburse(loan, escrow, legs):
    # All transactions between the REs and the borrower route through an escrow
    # maintained for the arrangement. Neither lender's own account touches
    # borrower money directly.
    for l in legs:
        escrow.credit(source=l["re"], amount=l["share"] * loan["principal_paise"],
                      ref=loan["common_ref"])
    escrow.debit(to=loan["borrower_account"], amount=loan["principal_paise"],
                 ref=loan["common_ref"])
    return {"transfer_due_by": loan["origination_date"] + TRANSFER_WINDOW}

def book(loan, legs):
    # SEPARATE loan accounts per co-lender, joined by ONE common reference.
    # The common ref is what makes reconciliation and credit bureau reporting
    # possible; without it you have two unrelated loans to the same person.
    return [{"re": l["re"], "account_no": l["re"] + "-" + loan["common_ref"],
             "common_ref": loan["common_ref"], "share": l["share"],
             "rate": l["rate"], "outstanding": l["share"] * loan["principal_paise"]}
            for l in legs]

def classify(loan, views):
    """views = each partner's own SMA/NPA view of this borrower."""
    # UNIFIED BORROWER-LEVEL CLASSIFICATION. The same borrower cannot be
    # standard at the bank and NPA at the NBFC. The partners' internal norms
    # differ, so the CLA must say HOW the single answer is reached.
    worst = max(views.values(), key=lambda v: v["severity"])
    disagreement = len({v["stage"] for v in views.values()}) > 1
    return {"agreed_stage": worst["stage"],
            "partners_disagreed": disagreement,
            "resolution_rule": loan["cla"]["classification_rule"],
            "action": "escalate_to_cla_committee" if disagreement
                      and not loan["cla"].get("classification_rule") else "apply"}

# WHAT TO CHECK
# [ ] the transfer window is 15 CALENDAR days. A 15-business-day assumption is
#     wrong by up to five days in a month with holidays
# [ ] common_ref is generated ONCE, at origination, and used by both partners in
#     their own systems AND in credit bureau reporting
# [ ] the classification rule is written INTO the CLA, not resolved by email
#     each time. Two institutions with different SMA norms will disagree, and
#     the borrower's bureau record depends on the answer
# [ ] ONE customer interface, named in the loan agreement. If it changes during
#     the tenure the borrower is told IN ADVANCE
# [ ] escrow reconciles daily. Two funders, one disbursal, one repayment stream
#     -- see Build Sheet 05 for the control-total discipline
# [ ] DLG between the partners is capped at 5% and disclosed