glidepath 0.2.0__py3-none-any.whl

glidepath/core/entities.py

@@ -0,0 +1,264 @@
+"""Household and person entities (planning §4.4, §5.1 skeleton).
+
+The schema models ``Household{persons: 1..2}`` now — UK tax is individual,
+so computation is per-person anyway, and placing shared economics at
+household level avoids a schema + engine migration when couples activate
+(roadmap 9.4). v1 validates exactly one person via
+:func:`validate_household_v1`.
+
+Wrappers attach to :class:`Person` as of roadmap 3.1, the glide-path
+config as of 3.5, household spending as of 4.1, DB pensions and state
+pension records as of 4.2/4.3, and household planned outflows as of 5.4.
+"""
+
+import uuid
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum, auto
+from typing import TYPE_CHECKING, NewType
+
+from glidepath.core.glide import LifeStage
+from glidepath.core.money import Money
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from datetime import date
+
+    from glidepath.core.annuities import AnnuityPurchase
+    from glidepath.core.glide import GlidePathConfig
+    from glidepath.core.pensions import DBPension
+    from glidepath.core.provenance import Decision, Fact
+    from glidepath.core.state_pension import StatePensionRecord
+    from glidepath.core.wrappers import Wrapper
+
+EntityId = NewType("EntityId", str)
+"""Stable persisted identifier.
+
+Scenario overrides target entities by id + field path (planning §4.3), so
+ids must survive reordering and insertion; couples support needs them too.
+"""
+
+TaxResidencyId = NewType("TaxResidencyId", str)
+"""Opaque region-defined residency id (e.g. ``"uk.ruk"``, ``"uk.scotland"``).
+
+The core never interprets it; the region's tax system does (planning §4.2).
+"""
+
+_MIN_PERSONS = 1
+_MAX_PERSONS = 2
+_ZERO = Money(Decimal(0))
+_ZERO_MULTIPLIER = Decimal(0)
+_RETIREMENT_STAGES = frozenset(
+    {LifeStage.DECUMULATION, LifeStage.GO_GO, LifeStage.SLOW_GO, LifeStage.NO_GO}
+)
+"""The spending-multiplier keys reachable in retirement (planning §5.1)."""
+
+
+def new_entity_id() -> EntityId:
+    """Generate a fresh stable id.
+
+    For plan-edit time only — the engine itself never creates entities
+    during a run (planning §4.6 purity).
+    """
+    return EntityId(str(uuid.uuid4()))
+
+
+class Sex(Enum):
+    """Sex used solely for longevity defaults (planning §5.1)."""
+
+    FEMALE = auto()
+    MALE = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Person:
+    """One person in a household (planning §5.1, Phase 1 skeleton).
+
+    Everything taxed or age-gated hangs off a person; shared economics
+    hang off the household (planning §4.4).
+    """
+
+    id: EntityId
+    date_of_birth: Fact[date]
+    target_retirement_age: Decision[int]
+    tax_residency: TaxResidencyId
+    sex_for_longevity: Fact[Sex] | None = None
+    employment_income: Fact[Money] | None = None
+    mpaa_triggered_on: Fact[date] | None = None
+    """Date pension benefits were first flexibly accessed, if ever.
+
+    A pre-plan fact (planning §5.1): once set, the region's
+    money-purchase contribution limit applies from that date on
+    (roadmap 3.3). An in-plan first flexible access records the
+    trigger in the period results instead (roadmap 5.2); when this
+    fact is present it wins.
+    """
+    lsa_used: Fact[Money] | None = None
+    """Tax-free lump sum allowance already used before the plan.
+
+    A pre-plan fact (planning §5.1): the run's tax-free-cash ledger is
+    seeded with it, reducing the headroom under the region's lifetime
+    cap (roadmap 5.2). ``None`` means none used.
+    """
+    wrappers: tuple[Wrapper, ...] = ()
+    db_pensions: tuple[DBPension, ...] = ()
+    """DB entitlements — deferred or actively accruing (roadmap 4.2, 9.6)."""
+    annuity_purchases: tuple[AnnuityPurchase, ...] = ()
+    """Planned annuity purchases — decision records (roadmap 5.5)."""
+    state_pension: StatePensionRecord | None = None
+    """This person's state pension record (roadmap 4.3).
+
+    ``None`` means no state pension is modelled for this person.
+    """
+    glide_path: GlidePathConfig | None = None
+    """This person's glide path, if they overrode the default.
+
+    ``None`` means the ``glidepath.default_shape`` assumption supplies
+    the factor table (planning §7, roadmap 3.5).
+    """
+
+    def __post_init__(self) -> None:
+        """Require distinct entity ids (they are override targets, §4.3)."""
+        ids = [wrapper.id for wrapper in self.wrappers]
+        ids += [pension.id for pension in self.db_pensions]
+        ids += [purchase.id for purchase in self.annuity_purchases]
+        if len(set(ids)) != len(ids):
+            msg = (
+                "a person's wrappers, DB pensions, and annuity purchases"
+                " must have distinct EntityIds"
+            )
+            raise ValueError(msg)
+        if self.lsa_used is not None and self.lsa_used.value < _ZERO:
+            msg = "Person.lsa_used must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class SpendingPlan:
+    """The household's retirement spending need (planning §5.1, §5.2).
+
+    ``annual_spending_real`` is a *net* (after-tax) need in today's
+    money — the engine inflates it by the run's CPI path and grosses
+    withdrawals up against the tax system (planning §5.2 step 4).
+    ``stage_multipliers`` optionally scales the need across retirement
+    (planning §5.1): the go-go/slow-go/no-go sub-stage keys bind to
+    their decades, ``DECUMULATION`` covers any sub-stage without its
+    own key, and an absent stage means a multiplier of 1. Spending is
+    modelled only in retirement, so accumulation-stage keys — which
+    could never bind — are rejected rather than silently ignored
+    (issue #114).
+    """
+
+    annual_spending_real: Fact[Money]
+    stage_multipliers: Mapping[LifeStage, Decimal] | None = None
+
+    def __post_init__(self) -> None:
+        """Reject negative spending and unusable multipliers."""
+        if self.annual_spending_real.value < _ZERO:
+            msg = "SpendingPlan.annual_spending_real must be non-negative"
+            raise ValueError(msg)
+        multipliers = self.stage_multipliers or {}
+        if any(value <= _ZERO_MULTIPLIER for value in multipliers.values()):
+            msg = "SpendingPlan.stage_multipliers must be positive"
+            raise ValueError(msg)
+        unusable = set(multipliers) - _RETIREMENT_STAGES
+        if unusable:
+            names = ", ".join(sorted(stage.name for stage in unusable))
+            msg = (
+                "SpendingPlan.stage_multipliers bind only in retirement"
+                " (GO_GO, SLOW_GO, NO_GO, or DECUMULATION for the whole);"
+                f" got {names}"
+            )
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class PlannedOutflow:
+    """One dated one-off outflow — wholly a decision (planning §5.1).
+
+    A mortgage payoff, gift, or purchase: a *net* cash need on top of
+    the spending plan, hitting the period in which the referenced
+    person attains the stated age and funded tax-aware through the
+    withdrawal machinery (roadmap 5.4). ``amount_real`` is in today's
+    money; the engine inflates it by the run's CPI path.
+    """
+
+    id: EntityId
+    label: str
+    amount_real: Decision[Money]
+    at_age_of: tuple[EntityId, int]
+
+    def __post_init__(self) -> None:
+        """Reject a negative amount or age."""
+        if self.amount_real.value < _ZERO:
+            msg = "PlannedOutflow.amount_real must be non-negative"
+            raise ValueError(msg)
+        if self.at_age_of[1] < 0:
+            msg = "PlannedOutflow.at_age_of age must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class Household:
+    """One or two persons plus shared economics (planning §4.4, §5.1).
+
+    The 1..2 bound is the schema-level invariant (planning §4.4); the
+    stricter v1 single-person rule is :func:`validate_household_v1`.
+    ``spending`` is the household-level retirement spending need;
+    ``None`` means decumulation spending withdrawals are not modelled.
+    ``planned_outflows`` are household-level dated one-offs (roadmap
+    5.4), funded through the withdrawal machinery whether or not a
+    spending plan is present.
+    """
+
+    persons: tuple[Person, ...]
+    spending: SpendingPlan | None = None
+    planned_outflows: tuple[PlannedOutflow, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Enforce the 1..2 bound, distinct entity ids, and outflow targets.
+
+        Scenario overrides target entities by id + field path (planning
+        §4.3), so ids must be unambiguous across the whole household —
+        two persons' wrappers, DB pensions, annuity purchases, or
+        planned outflows may not share an id, nor may any share one
+        with a person. A planned outflow must reference a person in
+        this household.
+        """
+        if not _MIN_PERSONS <= len(self.persons) <= _MAX_PERSONS:
+            msg = f"a household holds 1 or 2 persons, got {len(self.persons)}"
+            raise ValueError(msg)
+        ids = [person.id for person in self.persons]
+        ids += [wrapper.id for person in self.persons for wrapper in person.wrappers]
+        ids += [pension.id for person in self.persons for pension in person.db_pensions]
+        ids += [
+            purchase.id
+            for person in self.persons
+            for purchase in person.annuity_purchases
+        ]
+        ids += [outflow.id for outflow in self.planned_outflows]
+        if len(set(ids)) != len(ids):
+            msg = (
+                "household entities (persons, wrappers, DB pensions, annuity"
+                " purchases, planned outflows) must have distinct EntityIds"
+            )
+            raise ValueError(msg)
+        person_ids = {person.id for person in self.persons}
+        for outflow in self.planned_outflows:
+            if outflow.at_age_of[0] not in person_ids:
+                msg = (
+                    f"planned outflow {outflow.id} references person"
+                    f" {outflow.at_age_of[0]}, who is not in this household"
+                )
+                raise ValueError(msg)
+
+
+def validate_household_v1(household: Household) -> None:
+    """Enforce the v1 single-person restriction (planning §4.4).
+
+    Raises:
+        ValueError: If the household does not hold exactly one person.
+    """
+    if len(household.persons) != _MIN_PERSONS:
+        msg = "v1 supports exactly one person per household (planning §4.4)"
+        raise ValueError(msg)

glidepath/core/glide.py

@@ -0,0 +1,289 @@
+"""Life stages and glide-path allocation (roadmap 3.5; planning §5.1, §7).
+
+The projection moves a person through ``EARLY_ACCUMULATION →
+MID_ACCUMULATION → PRE_RETIREMENT → GO_GO → SLOW_GO → NO_GO``. Stage is
+*derived* each period from years-to-target-retirement — never stored —
+and the glide path maps years-to-retirement to an asset allocation by
+interpolating a factor table (:class:`GlidePathConfig`).
+
+Stage boundaries (planning §5.1): retirement — the target retirement
+age attained by the period's first day (years-to-retirement ≤ 0,
+matching the §4.1 gate convention) — splits into the go-go/slow-go/no-go
+sub-stages at one and two decades in (the retirement-smile convention;
+``DECUMULATION`` remains their umbrella for whole-retirement spending
+multipliers); ``PRE_RETIREMENT`` inside the table's de-risking window —
+the years at which the allocation starts changing (zero for a constant
+table, which never de-risks); the ``EARLY`` / ``MID`` split falls at
+twice that window.
+
+The default shape ships as the ``glidepath.default_shape`` assumption
+(planning §7), overridable per person; :func:`glide_path_from_shape`
+turns that structured value into a config.
+"""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum, auto
+from itertools import pairwise
+from typing import TYPE_CHECKING
+
+from glidepath.core.investments import AssetAllocation
+from glidepath.core.periods import age_on
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from datetime import date
+
+    from glidepath.core.periods import Period
+
+_ZERO = Decimal(0)
+_ONE = Decimal(1)
+
+_SHAPE_LINEAR = "linear"
+_SHAPE_HOLD = "hold"
+
+_RETIREMENT_STAGE_YEARS = 10
+"""Decade width of the go-go/slow-go retirement sub-stages (planning §5.1)."""
+
+
+class LifeStage(Enum):
+    """The stages a person moves through (planning §5.1); always derived."""
+
+    EARLY_ACCUMULATION = auto()
+    MID_ACCUMULATION = auto()
+    PRE_RETIREMENT = auto()
+    """Inside the glide path's de-risking window."""
+    DECUMULATION = auto()
+    """Retirement as a whole — the go-go/slow-go/no-go umbrella.
+
+    Never derived (the sub-stages partition retirement); retained as
+    the whole-retirement spending-multiplier key (planning §5.1).
+    """
+    GO_GO = auto()
+    """The first decade with the retirement age attained (§4.1 gate)."""
+    SLOW_GO = auto()
+    """The second decade of retirement."""
+    NO_GO = auto()
+    """Retirement beyond its second decade."""
+
+
+@dataclass(frozen=True, slots=True)
+class GlidePathPoint:
+    """One knot of the factor table: the allocation held at this distance."""
+
+    years_to_retirement: int
+    allocation: AssetAllocation
+
+    def __post_init__(self) -> None:
+        """Reject knots after retirement; the 0 knot holds through drawdown."""
+        if self.years_to_retirement < 0:
+            msg = "GlidePathPoint.years_to_retirement must be non-negative"
+            raise ValueError(msg)
+
+
+@dataclass(frozen=True, slots=True)
+class GlidePathConfig:
+    """A years-to-retirement → allocation factor table (planning §5.1).
+
+    Knots are strictly ascending by ``years_to_retirement``. Between
+    knots the allocation interpolates linearly per asset class; beyond
+    the highest knot it holds that knot's allocation, and at or past
+    retirement it holds the lowest knot's — the "held through drawdown"
+    behaviour of the default shape (planning §7).
+    """
+
+    points: tuple[GlidePathPoint, ...]
+
+    def __post_init__(self) -> None:
+        """Require at least one knot, strictly ascending."""
+        if not self.points:
+            msg = "GlidePathConfig requires at least one point"
+            raise ValueError(msg)
+        ascending = all(
+            lower.years_to_retirement < upper.years_to_retirement
+            for lower, upper in pairwise(self.points)
+        )
+        if not ascending:
+            msg = "GlidePathConfig points must strictly ascend by years_to_retirement"
+            raise ValueError(msg)
+
+    @property
+    def derisk_window_years(self) -> int:
+        """Years before retirement at which the allocation starts changing.
+
+        The lowest knot of the top plateau — the run of highest knots
+        sharing the final allocation — since above it the table is
+        constant. Zero when every knot holds the same allocation: a
+        constant table never de-risks.
+        """
+        top = self.points[-1].allocation
+        window = self.points[-1].years_to_retirement
+        for point in reversed(self.points[:-1]):
+            if point.allocation != top:
+                return window
+            window = point.years_to_retirement
+        return 0
+
+    def allocation_at(self, years_to_retirement: int) -> AssetAllocation:
+        """The allocation held at ``years_to_retirement`` (may be negative).
+
+        Clamps beyond the table at both ends; interpolates linearly
+        between knots.
+        """
+        first, last = self.points[0], self.points[-1]
+        if years_to_retirement <= first.years_to_retirement:
+            return first.allocation
+        if years_to_retirement >= last.years_to_retirement:
+            return last.allocation
+        lower, upper = next(
+            pair
+            for pair in pairwise(self.points)
+            if years_to_retirement <= pair[1].years_to_retirement
+        )
+        return _interpolate(lower, upper, years_to_retirement)
+
+    def stage_at(self, years_to_retirement: int) -> LifeStage:
+        """Derive the life stage at ``years_to_retirement`` (planning §5.1).
+
+        A constant-allocation table (a single knot, or knots all holding
+        the same allocation) has a zero de-risking window, so
+        ``PRE_RETIREMENT`` is unreachable and accumulation runs straight
+        into retirement's go-go sub-stage.
+        """
+        if years_to_retirement <= 0:
+            return _retirement_stage_at(years_to_retirement)
+        window = self.derisk_window_years
+        if years_to_retirement <= window:
+            return LifeStage.PRE_RETIREMENT
+        if years_to_retirement <= 2 * window:
+            return LifeStage.MID_ACCUMULATION
+        return LifeStage.EARLY_ACCUMULATION
+
+
+def _retirement_stage_at(years_to_retirement: int) -> LifeStage:
+    """The go-go/slow-go/no-go sub-stage once retirement is attained.
+
+    Sub-stage boundaries fall one and two decades into retirement —
+    for typical retirement ages this lands on the 75/85 boundaries the
+    retirement-smile literature uses. Like the ``EARLY``/``MID`` split,
+    only the spending multipliers bind to the result (planning §5.1),
+    so a simple decade rule suffices.
+    """
+    years_retired = -years_to_retirement
+    if years_retired < _RETIREMENT_STAGE_YEARS:
+        return LifeStage.GO_GO
+    if years_retired < 2 * _RETIREMENT_STAGE_YEARS:
+        return LifeStage.SLOW_GO
+    return LifeStage.NO_GO
+
+
+def _interpolate(
+    lower: GlidePathPoint, upper: GlidePathPoint, years_to_retirement: int
+) -> AssetAllocation:
+    """Linearly interpolate between two knots at an interior year.
+
+    The fraction and weights carry full context precision — factors are
+    never explicitly quantized (planning §4.6, the same convention as
+    ``prorata_fraction``). Cash is derived as the residual so the
+    weights sum to exactly 1 despite any rounding at context precision;
+    interior interpolants sit far enough inside [0, 1] that the residual
+    cannot go negative for a valid table.
+    """
+    span = upper.years_to_retirement - lower.years_to_retirement
+    offset = years_to_retirement - lower.years_to_retirement
+    fraction = Decimal(offset) / Decimal(span)
+
+    def weight(start: Decimal, end: Decimal) -> Decimal:
+        """One class's weight at ``fraction`` of the way from lower to upper."""
+        return start + (end - start) * fraction
+
+    equity = weight(lower.allocation.equity, upper.allocation.equity)
+    bonds = weight(lower.allocation.bonds, upper.allocation.bonds)
+    return AssetAllocation(equity=equity, bonds=bonds, cash=_ONE - equity - bonds)
+
+
+def years_to_target_retirement(
+    date_of_birth: date, target_retirement_age: int, period: Period
+) -> int:
+    """Whole years from ``period``'s first day to the target retirement age.
+
+    Zero or negative once the age is attained by the period's first day
+    — the same gate convention as §4.1, so the retirement period itself
+    is already ``DECUMULATION``.
+    """
+    return target_retirement_age - age_on(date_of_birth, period.start)
+
+
+def _shape_fraction(shape: Mapping[str, object], key: str) -> Decimal:
+    """Take a required fraction in [0, 1] from the shape mapping."""
+    raw = shape[key]
+    if not isinstance(raw, Decimal):
+        msg = f"glide-path shape {key!r} must be a Decimal fraction"
+        raise TypeError(msg)
+    if not _ZERO <= raw <= _ONE:
+        msg = f"glide-path shape {key!r} must lie between 0 and 1"
+        raise ValueError(msg)
+    return raw
+
+
+def _shape_tag(shape: Mapping[str, object], key: str, supported: str) -> None:
+    """Require the shape tag ``key`` to hold the one supported value."""
+    raw = shape[key]
+    if raw != supported:
+        msg = f"glide-path shape {key!r} supports only {supported!r}, got {raw!r}"
+        raise ValueError(msg)
+
+
+def glide_path_from_shape(shape: Mapping[str, object]) -> GlidePathConfig:
+    """Build a config from the ``glidepath.default_shape`` value (planning §7).
+
+    The shape is the structured assumption value: ``equity_start`` held
+    until ``derisk_years_before_retirement`` years out, then a
+    ``linear`` transition to ``equity_at_retirement``, ``hold`` through
+    drawdown — the remainder of each allocation in bonds. Only those
+    tags are supported; anything else here is a data error, not a
+    default.
+
+    Raises:
+        KeyError: If a required shape key is missing.
+        TypeError: If a shape value has the wrong type.
+        ValueError: If keys are unknown or values out of range.
+    """
+    expected = {
+        "equity_start",
+        "derisk_years_before_retirement",
+        "equity_at_retirement",
+        "transition",
+        "in_drawdown",
+    }
+    unknown = set(shape) - expected
+    if unknown:
+        msg = f"unknown glide-path shape keys: {', '.join(sorted(unknown))}"
+        raise ValueError(msg)
+    equity_start = _shape_fraction(shape, "equity_start")
+    equity_at_retirement = _shape_fraction(shape, "equity_at_retirement")
+    _shape_tag(shape, "transition", _SHAPE_LINEAR)
+    _shape_tag(shape, "in_drawdown", _SHAPE_HOLD)
+    derisk_years = shape["derisk_years_before_retirement"]
+    if isinstance(derisk_years, bool) or not isinstance(derisk_years, int):
+        msg = "glide-path shape 'derisk_years_before_retirement' must be an integer"
+        raise TypeError(msg)
+    if derisk_years < 1:
+        msg = "glide-path shape 'derisk_years_before_retirement' must be at least 1"
+        raise ValueError(msg)
+    return GlidePathConfig(
+        points=(
+            GlidePathPoint(
+                years_to_retirement=0,
+                allocation=AssetAllocation(
+                    equity=equity_at_retirement, bonds=_ONE - equity_at_retirement
+                ),
+            ),
+            GlidePathPoint(
+                years_to_retirement=derisk_years,
+                allocation=AssetAllocation(
+                    equity=equity_start, bonds=_ONE - equity_start
+                ),
+            ),
+        )
+    )