insurance.excess-apply Unreviewed

def apply_excess(loss: Money, compulsory_excess: Money, voluntary_excess: Money, policy_limit: Optional[Money], excess_within_limit: bool) -> ExcessSettlement

@dataclass(frozen=True)
class ExcessSettlement:
    """What the insurer pays and what the policyholder bears."""

    #: compulsory plus voluntary
    total_excess: Money
    #: the part of the excess the loss used up, never more than the loss
    excess_applied: Money
    payout: Money
    #: true when the policy limit reduced the payout
    limit_applied: bool
    #: loss minus payout: what the policyholder bears
    uninsured: Money

from fune.insurance.excess_apply import apply_excess  # insurance.excess-apply@^1

from typing import Optional

from .insurance_excess_apply_types import ExcessSettlement
from .money_amount import Money, assert_same_currency, money  ← from money.amount ^1.0.0 · built alongside by fune


def apply_excess(
    loss: Money,
    compulsory_excess: Money,
    voluntary_excess: Money,
    policy_limit: Optional[Money],
    excess_within_limit: bool,
) -> ExcessSettlement:
    """The claim payout after the excess, capped at the policy limit.

    The excess is the compulsory and voluntary excess together, and a loss
    smaller than it pays nothing. Where the limit sits relative to the excess
    is a policy wording question, so the caller says which: by default the
    limit caps what is paid after the excess; with excess_within_limit the
    excess is taken off the loss after the limit, so it erodes the limit.
    """
    assert_same_currency(loss, compulsory_excess)
    assert_same_currency(loss, voluntary_excess)
    if policy_limit is not None:
        assert_same_currency(loss, policy_limit)
    if loss.minor < 0:
        raise ValueError("loss must not be negative, received %d" % (loss.minor,))
    if compulsory_excess.minor < 0 or voluntary_excess.minor < 0:
        raise ValueError("excess must not be negative")
    if policy_limit is not None and policy_limit.minor < 0:
        raise ValueError("policyLimit must not be negative, received %d" % (policy_limit.minor,))
    excess = compulsory_excess.minor + voluntary_excess.minor
    limit_applied = False
    if excess_within_limit:
        covered = loss.minor
        if policy_limit is not None and policy_limit.minor < covered:
            covered = policy_limit.minor
            limit_applied = True
        payout = max(covered - excess, 0)
    else:
        payout = max(loss.minor - excess, 0)
        if policy_limit is not None and policy_limit.minor < payout:
            payout = policy_limit.minor
            limit_applied = True
    c = loss.currency
    return ExcessSettlement(
        total_excess=money(excess, c),
        excess_applied=money(min(excess, loss.minor), c),
        payout=money(payout, c),
        limit_applied=limit_applied,
        uninsured=money(loss.minor - payout, c),
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add insurance.excess-apply

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./insurance.excess-apply-1.0.1-python.fune, or fetch it from a terminal with fune pull insurance.excess-apply@1.0.1:python.

The whole function, every language, is one file too: insurance.excess-apply-1.0.1.fune, 22,577 bytes, sha256 7c4367145a5a64ec36e9208bdc8f7522251b18bf68a78e588c94314952f4e6b1. It installs into a project of any language.

# fune: before insurance.excess-apply

# fune: after insurance.excess-apply

# fune: replace money.amount in insurance.excess-apply

# fune: step insurance.excess-apply after <n|label>

More from the author

The excess is the compulsory excess (set by the insurer) plus the voluntary excess (chosen by the policyholder for a lower premium); UK motor and home policies quote them separately but apply them together. A loss smaller than the excess pays nothing, and `excessApplied` is only the part of the excess the loss used up.

## Where the limit sits

Policies differ on whether the limit is applied before or after the excess, so the caller says which:

- `excessWithinLimit = false` (the usual "the most we will pay" wording): the excess comes off the loss, then the payout is capped at the limit. payout = min(loss - excess, limit). - `excessWithinLimit = true` (the excess erodes the limit): the loss is capped at the limit, then the excess comes off it. payout = min(loss, limit) - excess.

They differ whenever the loss is above the limit: a 10,400.00 loss with a 500.00 excess and a 10,000.00 limit pays 9,900.00 the first way and 9,500.00 the second. `limitApplied` is true only when the limit actually reduced what is paid.

No rounding happens: every figure is a whole number of minor units already. For underinsurance, see `insurance.sum-insured-average`; whether average comes before or after the excess is a policy wording question too.

## Before you rely on this

**Not professional advice.** This capability calculates insurance figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have an actuary review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified actuary has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files