Skip to content

Rollforward API

gaspatchio_core.rollforward.RollforwardBuilder

Immutable builder for rollforward step sequences.

Every method returns a new RollforwardBuilder instance. The internal step list is stored as a tuple[StepDef, ...] to enforce immutability. Labels must be unique across all steps; duplicates raise ValueError immediately.

Parameters

frame : object The ActuarialFrame (or template reference) this rollforward targets. initial : str | None Column name for the single account value (single-state mode). states : dict[str, Any] | None Mapping of state name to column reference (multi-state mode). track_increments : bool Whether to capture per-step increments for diagnostics.

Examples

Single-state usage::

b = (
    RollforwardBuilder(frame=af, initial="av")
    .add("premium", "Premium")
    .charge("admin_rate", "Admin Fee")
    .grow("interest_rate", "Interest Credit")
)

Multi-state usage::

b = (
    RollforwardBuilder(frame=af, states={"av": "av_col", "guar": "guar_col"})
    .on("av")
    .add("premium", "Premium AV")
    .on("guar")
    .add("guar_prem", "Premium Guar")
    .lapse_when(all_non_positive=["av", "guar"])
)

is_multi_state property

Return True if this is a multi-state builder.

labels property

Return a tuple of step labels in order.

steps property

Return the immutable tuple of step definitions.

add(amount, label=None)

Append an Add step: av += amount[t].

Parameters

amount : Column reference or template string for the amount. label : str | None Step label. Auto-generated as Add(<col>) if omitted.

add_if(condition, amount, label=None)

Append a conditional Add step: if condition[t]: av += amount[t].

Parameters

condition : Boolean column reference. amount : Amount column reference. label : str | None Step label. Auto-generated as AddIf(<col>) if omitted.

append(step)

Return a new builder with step appended at the end.

Parameters

step : StepDef The step to append.

Raises

ValueError If step.label already exists.

canonical()

Return a structural dict describing this builder.

Excludes column names and labels. Only includes operation types and structural parameters (floor/cap values, etc.). Suitable for change detection and model governance.

Returns

dict[str, Any] JSON-serialisable dict with keys "num_states", "steps", and "track_increments".

cap(value, label=None)

Append a Cap step: av = min(av, value).

Parameters

value : float Maximum allowable account value. label : str | None Step label. Auto-generated as Cap(<value>) if omitted.

capture(label=None)

Append a Capture step: snapshot the current av value.

Parameters

label : str | None Step label. Defaults to Capture.

charge(rate, label=None)

Append a Charge step: av *= (1 - rate[t]).

Parameters

rate : Column reference or template string for the charge rate. label : str | None Step label. Auto-generated as Charge(<col>) if omitted.

charge_if(condition, rate, label=None)

Append a conditional Charge step: if condition[t]: av *= (1 - rate[t]).

Parameters

condition : Boolean column reference. rate : Rate column reference. label : str | None Step label. Auto-generated as ChargeIf(<col>) if omitted.

deduct_nar(rate, *, death_benefit, label=None)

Append a DeductNAR step: av -= rate[t] * max(0, db[t] - av).

Parameters

rate : COI rate column reference. death_benefit : Death benefit column reference. label : str | None Step label. Auto-generated as DeductNAR(<col>) if omitted.

explain()

Return a formatted table describing all steps in this builder.

Returns

str Multi-line string with a header and one row per step showing step number, operation, label, and formula.

fingerprint()

Return a SHA-256 fingerprint of this builder's canonical form.

Two builders with identical structure but different column names or labels produce the same fingerprint. Useful for detecting structural changes between model versions.

Returns

str A string of the form "sha256:<64 hex chars>".

floor(value, label=None)

Append a Floor step: av = max(av, value).

Parameters

value : float Minimum allowable account value. label : str | None Step label. Auto-generated as Floor(<value>) if omitted.

grow(rate, label=None)

Append a Grow step: av *= (1 + rate[t]).

Parameters

rate : Column reference or template string. label : str | None Step label. Auto-generated as Grow(<col>) if omitted.

grow_capped(rate, *, floor, cap, label=None)

Append a GrowCapped step: av *= (1 + clamp(rate[t], floor, cap)).

Parameters

rate : Column reference or template string. floor : float Minimum growth rate (inclusive). cap : float Maximum growth rate (inclusive). label : str | None Step label. Auto-generated as GrowCapped(<col>) if omitted.

insert_after(label, step)

Return a new builder with step inserted after the step labelled label.

Parameters

label : str Label of the existing step to insert after. step : StepDef The new step to insert.

Raises

KeyError If label is not found. ValueError If step.label already exists in the step list.

insert_before(label, step)

Return a new builder with step inserted before the step labelled label.

Parameters

label : str Label of the existing step to insert before. step : StepDef The new step to insert.

Raises

KeyError If label is not found. ValueError If step.label already exists in the step list.

lapse_if_zero(label=None)

Append a LapseIfZero step: lapse the policy if av ≤ 0.

Parameters

label : str | None Step label. Defaults to LapseIfZero.

lapse_when(*, all_non_positive)

Store a cross-state lapse condition (not added to the step list).

Only valid in multi-state mode. Only one lapse_when per builder.

Parameters

all_non_positive : list[str] State names that must all be non-positive (≤ 0) to trigger lapse.

Raises

ValueError If called on a single-state builder, or if lapse_when has already been set.

on(state_name)

Switch the sticky state target for subsequent steps.

Only valid in multi-state mode.

Parameters

state_name : str Must be a key in the states dict supplied at construction.

Raises

ValueError If called on a single-state builder, or if state_name is not a known state.

prepend(step)

Return a new builder with step inserted at position 0.

Parameters

step : StepDef The step to prepend.

Raises

ValueError If step.label already exists.

pro_rata_with(capture_name, amount, label=None)

Append a ProRataWith step: scale av pro-rata using a captured snapshot.

The pro-rata formula is::

state *= 1 - amount[t] / captured_value

Only valid in multi-state mode.

Parameters

capture_name : str Label of the capture() step whose snapshot to use as denominator. amount : Column reference for the withdrawal/deduction amount. label : str | None Step label. Auto-generated as ProRataWith(<capture_name>) if omitted.

Raises

ValueError If called on a single-state builder.

ratchet_to(other_state, label=None)

Append a RatchetTo step: av = max(av, other_state).

Only valid in multi-state mode.

Parameters

other_state : str Name of the state to ratchet up to. label : str | None Step label. Auto-generated as RatchetTo(<state>) if omitted.

Raises

ValueError If called on a single-state builder.

remove(label)

Return a new builder with the step labelled label removed.

Parameters

label : str Label of the step to remove.

Raises

KeyError If label is not found.

replace(label, step)

Return a new builder with the step labelled label replaced by step.

Parameters

label : str Label of the step to replace. step : StepDef The replacement step.

Raises

KeyError If label is not found. ValueError If step.label already exists (and differs from the one being replaced).

subtract(amount, label=None)

Append a Subtract step: av -= amount[t].

Parameters

amount : Column reference or template string. label : str | None Step label. Auto-generated as Subtract(<col>) if omitted.

gaspatchio_core.rollforward.Step

Factory namespace for creating StepDef objects.

Used with composition methods (insert_before, insert_after, replace, prepend, append). Column arguments accept ColumnProxy, ExpressionProxy, or str (for templates).

Examples

from gaspatchio_core.rollforward import Step

step = Step.charge(af.rider_rate, "Rider Fee")
builder = base.insert_before("Interest", step)

add(amount, label=None) staticmethod

Create an Add step: av += amount[t].

add_if(condition, amount, label=None) staticmethod

Create a conditional Add step: if condition[t]: av += amount[t].

cap(value, label=None) staticmethod

Create a Cap step: av = min(av, value).

charge(rate, label=None) staticmethod

Create a Charge step: av *= (1 - rate[t]).

charge_if(condition, rate, label=None) staticmethod

Create a conditional Charge step: if condition[t]: av *= (1 - rate[t]).

deduct_nar(rate, *, death_benefit, label=None) staticmethod

Create a DeductNAR step: av -= rate[t] * max(0, db[t] - av).

floor(value, label=None) staticmethod

Create a Floor step: av = max(av, value).

grow(rate, label=None) staticmethod

Create a Grow step: av *= (1 + rate[t]).

grow_capped(rate, *, floor, cap, label=None) staticmethod

Create a GrowCapped step: av *= (1 + clamp(rate[t], floor, cap)).

subtract(amount, label=None) staticmethod

Create a Subtract step: av -= amount[t].

gaspatchio_core.rollforward.StepDef dataclass

Internal representation of a single rollforward step.

Immutable. Used by RollforwardBuilder for storage and composition operations. Not part of the public API — users interact through builder methods or the Step factory.