fundedness 0.1.0__py3-none-any.whl

fundedness/__init__.py

@@ -0,0 +1,38 @@
+"""Fundedness: A Python financial planning toolkit.
+
+This package provides tools for:
+- CEFR (Certainty-Equivalent Funded Ratio) calculations
+- Monte Carlo retirement simulations
+- Withdrawal strategy comparison
+- Beautiful Plotly visualizations
+"""
+
+__version__ = "0.1.0"
+
+from fundedness.cefr import CEFRResult, compute_cefr
+from fundedness.models import (
+    Asset,
+    BalanceSheet,
+    Household,
+    Liability,
+    MarketModel,
+    Person,
+    SimulationConfig,
+    TaxModel,
+    UtilityModel,
+)
+
+__all__ = [
+    "__version__",
+    "compute_cefr",
+    "CEFRResult",
+    "Asset",
+    "BalanceSheet",
+    "Household",
+    "Liability",
+    "MarketModel",
+    "Person",
+    "SimulationConfig",
+    "TaxModel",
+    "UtilityModel",
+]

fundedness/allocation/__init__.py

@@ -0,0 +1,12 @@
+"""Asset allocation strategy implementations."""
+
+from fundedness.allocation.base import AllocationPolicy
+from fundedness.allocation.constant import ConstantAllocationPolicy
+from fundedness.allocation.glidepath import AgeBasedGlidepathPolicy, RisingEquityGlidepathPolicy
+
+__all__ = [
+    "AllocationPolicy",
+    "AgeBasedGlidepathPolicy",
+    "ConstantAllocationPolicy",
+    "RisingEquityGlidepathPolicy",
+]

fundedness/allocation/base.py

@@ -0,0 +1,32 @@
+"""Base class for allocation policies."""
+
+from typing import Protocol
+
+import numpy as np
+
+
+class AllocationPolicy(Protocol):
+    """Protocol defining the interface for allocation strategies."""
+
+    @property
+    def name(self) -> str:
+        """Human-readable name for the strategy."""
+        ...
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float | np.ndarray:
+        """Get the stock allocation for the given context.
+
+        Args:
+            wealth: Current portfolio value(s)
+            year: Current year in simulation
+            initial_wealth: Starting portfolio value
+
+        Returns:
+            Stock allocation as decimal (0-1)
+        """
+        ...

fundedness/allocation/constant.py

@@ -0,0 +1,25 @@
+"""Constant allocation policy."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class ConstantAllocationPolicy:
+    """Maintain a constant stock/bond allocation."""
+
+    stock_weight: float = 0.6
+
+    @property
+    def name(self) -> str:
+        return f"{self.stock_weight:.0%} Stocks"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Return constant stock allocation."""
+        return self.stock_weight

fundedness/allocation/glidepath.py

@@ -0,0 +1,111 @@
+"""Glidepath allocation policies."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class AgeBasedGlidepathPolicy:
+    """Traditional declining equity glidepath based on age.
+
+    Classic approach: reduce equity allocation as you age to reduce
+    sequence-of-returns risk.
+    """
+
+    initial_stock_weight: float = 0.7
+    final_stock_weight: float = 0.3
+    years_to_final: int = 30
+
+    @property
+    def name(self) -> str:
+        return f"Glidepath ({self.initial_stock_weight:.0%} → {self.final_stock_weight:.0%})"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Calculate stock allocation based on years into retirement."""
+        progress = min(year / self.years_to_final, 1.0)
+        stock_weight = self.initial_stock_weight - progress * (
+            self.initial_stock_weight - self.final_stock_weight
+        )
+        return stock_weight
+
+
+@dataclass
+class RisingEquityGlidepathPolicy:
+    """Rising equity glidepath (bonds-first approach).
+
+    Start conservative, increase equity over time as sequence-of-returns
+    risk decreases and remaining lifespan shortens.
+
+    Based on research by Wade Pfau and Michael Kitces showing that
+    rising equity glidepaths can improve outcomes in some scenarios.
+    """
+
+    initial_stock_weight: float = 0.3
+    final_stock_weight: float = 0.7
+    years_to_final: int = 20
+
+    @property
+    def name(self) -> str:
+        return f"Rising Equity ({self.initial_stock_weight:.0%} → {self.final_stock_weight:.0%})"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Calculate stock allocation - increasing over time."""
+        progress = min(year / self.years_to_final, 1.0)
+        stock_weight = self.initial_stock_weight + progress * (
+            self.final_stock_weight - self.initial_stock_weight
+        )
+        return stock_weight
+
+
+@dataclass
+class VShapedGlidepathPolicy:
+    """V-shaped glidepath: reduce then increase equity.
+
+    Start moderate, reduce equity in early retirement (highest sequence risk),
+    then increase equity as the portfolio stabilizes and remaining horizon shortens.
+    """
+
+    initial_stock_weight: float = 0.5
+    minimum_stock_weight: float = 0.3
+    final_stock_weight: float = 0.6
+    years_to_minimum: int = 10
+    years_to_final: int = 30
+
+    @property
+    def name(self) -> str:
+        return "V-Shaped Glidepath"
+
+    def get_allocation(
+        self,
+        wealth: float | np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Calculate V-shaped stock allocation."""
+        if year <= self.years_to_minimum:
+            # Declining phase
+            progress = year / self.years_to_minimum
+            stock_weight = self.initial_stock_weight - progress * (
+                self.initial_stock_weight - self.minimum_stock_weight
+            )
+        else:
+            # Rising phase
+            years_in_rising = year - self.years_to_minimum
+            years_remaining = self.years_to_final - self.years_to_minimum
+            progress = min(years_in_rising / years_remaining, 1.0)
+            stock_weight = self.minimum_stock_weight + progress * (
+                self.final_stock_weight - self.minimum_stock_weight
+            )
+
+        return stock_weight

fundedness/cefr.py

@@ -0,0 +1,241 @@
+"""CEFR (Certainty-Equivalent Funded Ratio) calculation engine."""
+
+from dataclasses import dataclass, field
+
+from fundedness.liabilities import calculate_total_liability_pv
+from fundedness.liquidity import get_liquidity_factor
+from fundedness.models.assets import Asset, BalanceSheet
+from fundedness.models.household import Household
+from fundedness.models.liabilities import Liability
+from fundedness.models.tax import TaxModel
+from fundedness.risk import get_reliability_factor
+
+
+@dataclass
+class AssetHaircutDetail:
+    """Detailed haircut breakdown for a single asset."""
+
+    asset: Asset
+    gross_value: float
+    tax_rate: float
+    after_tax_value: float
+    liquidity_factor: float
+    after_liquidity_value: float
+    reliability_factor: float
+    net_value: float
+
+    @property
+    def total_haircut(self) -> float:
+        """Total haircut as decimal (1 - net/gross)."""
+        if self.gross_value == 0:
+            return 0.0
+        return 1 - (self.net_value / self.gross_value)
+
+    @property
+    def tax_haircut(self) -> float:
+        """Tax haircut amount in dollars."""
+        return self.gross_value - self.after_tax_value
+
+    @property
+    def liquidity_haircut(self) -> float:
+        """Liquidity haircut amount in dollars."""
+        return self.after_tax_value - self.after_liquidity_value
+
+    @property
+    def reliability_haircut(self) -> float:
+        """Reliability haircut amount in dollars."""
+        return self.after_liquidity_value - self.net_value
+
+
+@dataclass
+class CEFRResult:
+    """Complete CEFR calculation result with breakdown."""
+
+    # Main ratio
+    cefr: float
+
+    # Numerator components
+    gross_assets: float
+    total_tax_haircut: float
+    total_liquidity_haircut: float
+    total_reliability_haircut: float
+    net_assets: float
+
+    # Denominator
+    liability_pv: float
+
+    # Detailed breakdowns
+    asset_details: list[AssetHaircutDetail] = field(default_factory=list)
+
+    @property
+    def total_haircut(self) -> float:
+        """Total haircut amount."""
+        return self.total_tax_haircut + self.total_liquidity_haircut + self.total_reliability_haircut
+
+    @property
+    def haircut_percentage(self) -> float:
+        """Total haircut as percentage of gross assets."""
+        if self.gross_assets == 0:
+            return 0.0
+        return self.total_haircut / self.gross_assets
+
+    @property
+    def is_funded(self) -> bool:
+        """Whether CEFR >= 1.0 (fully funded)."""
+        return self.cefr >= 1.0
+
+    @property
+    def funding_gap(self) -> float:
+        """Dollar gap if underfunded (positive = gap, negative = surplus)."""
+        return self.liability_pv - self.net_assets
+
+    def get_interpretation(self) -> str:
+        """Get a human-readable interpretation of the CEFR."""
+        if self.cefr >= 2.0:
+            return "Excellent: Very well-funded with significant buffer"
+        elif self.cefr >= 1.5:
+            return "Strong: Well-funded with comfortable margin"
+        elif self.cefr >= 1.0:
+            return "Adequate: Fully funded but limited cushion"
+        elif self.cefr >= 0.8:
+            return "Marginal: Slightly underfunded, minor adjustments needed"
+        elif self.cefr >= 0.5:
+            return "Concerning: Significantly underfunded, action required"
+        else:
+            return "Critical: Severely underfunded, major changes needed"
+
+
+def compute_asset_haircuts(
+    asset: Asset,
+    tax_model: TaxModel,
+) -> AssetHaircutDetail:
+    """Compute all haircuts for a single asset.
+
+    Args:
+        asset: The asset to analyze
+        tax_model: Tax rate assumptions
+
+    Returns:
+        Detailed haircut breakdown
+    """
+    gross_value = asset.value
+
+    # Step 1: Tax haircut
+    cost_basis_ratio = None
+    if asset.cost_basis is not None and asset.value > 0:
+        cost_basis_ratio = asset.cost_basis / asset.value
+
+    tax_rate = tax_model.get_effective_tax_rate(
+        account_type=asset.account_type,
+        cost_basis_ratio=cost_basis_ratio,
+    )
+    after_tax_value = gross_value * (1 - tax_rate)
+
+    # Step 2: Liquidity haircut
+    liquidity_factor = get_liquidity_factor(asset.liquidity_class)
+    after_liquidity_value = after_tax_value * liquidity_factor
+
+    # Step 3: Reliability haircut
+    reliability_factor = get_reliability_factor(
+        concentration_level=asset.concentration_level,
+        asset_class=asset.asset_class,
+    )
+    net_value = after_liquidity_value * reliability_factor
+
+    return AssetHaircutDetail(
+        asset=asset,
+        gross_value=gross_value,
+        tax_rate=tax_rate,
+        after_tax_value=after_tax_value,
+        liquidity_factor=liquidity_factor,
+        after_liquidity_value=after_liquidity_value,
+        reliability_factor=reliability_factor,
+        net_value=net_value,
+    )
+
+
+def compute_cefr(
+    household: Household | None = None,
+    balance_sheet: BalanceSheet | None = None,
+    liabilities: list[Liability] | None = None,
+    tax_model: TaxModel | None = None,
+    planning_horizon: int | None = None,
+    real_discount_rate: float = 0.02,
+    base_inflation: float = 0.025,
+) -> CEFRResult:
+    """Compute the Certainty-Equivalent Funded Ratio (CEFR).
+
+    CEFR = Σ(Asset × (1-τ) × λ × ρ) / PV(Liabilities)
+
+    Where:
+        τ = tax rate
+        λ = liquidity factor
+        ρ = reliability factor
+
+    Args:
+        household: Complete household model (alternative to separate components)
+        balance_sheet: Asset holdings (if household not provided)
+        liabilities: Future spending obligations (if household not provided)
+        tax_model: Tax rate assumptions (defaults to TaxModel())
+        planning_horizon: Years to plan for (defaults to household horizon or 30)
+        real_discount_rate: Real discount rate for liability PV
+        base_inflation: Base inflation assumption
+
+    Returns:
+        CEFRResult with complete breakdown
+    """
+    # Extract components from household or use provided values
+    if household is not None:
+        balance_sheet = household.balance_sheet
+        liabilities = household.liabilities
+        if planning_horizon is None:
+            planning_horizon = household.planning_horizon
+    else:
+        if balance_sheet is None:
+            balance_sheet = BalanceSheet()
+        if liabilities is None:
+            liabilities = []
+
+    if planning_horizon is None:
+        planning_horizon = 30
+
+    if tax_model is None:
+        tax_model = TaxModel()
+
+    # Compute asset haircuts
+    asset_details = [
+        compute_asset_haircuts(asset, tax_model)
+        for asset in balance_sheet.assets
+    ]
+
+    # Aggregate numerator
+    gross_assets = sum(d.gross_value for d in asset_details)
+    total_tax_haircut = sum(d.tax_haircut for d in asset_details)
+    total_liquidity_haircut = sum(d.liquidity_haircut for d in asset_details)
+    total_reliability_haircut = sum(d.reliability_haircut for d in asset_details)
+    net_assets = sum(d.net_value for d in asset_details)
+
+    # Compute liability PV (denominator)
+    liability_pv, _ = calculate_total_liability_pv(
+        liabilities=liabilities,
+        planning_horizon=planning_horizon,
+        real_discount_rate=real_discount_rate,
+        base_inflation=base_inflation,
+    )
+
+    # Calculate CEFR
+    if liability_pv == 0:
+        cefr = float("inf") if net_assets > 0 else 0.0
+    else:
+        cefr = net_assets / liability_pv
+
+    return CEFRResult(
+        cefr=cefr,
+        gross_assets=gross_assets,
+        total_tax_haircut=total_tax_haircut,
+        total_liquidity_haircut=total_liquidity_haircut,
+        total_reliability_haircut=total_reliability_haircut,
+        net_assets=net_assets,
+        liability_pv=liability_pv,
+        asset_details=asset_details,
+    )

fundedness/liabilities.py

@@ -0,0 +1,221 @@
+"""Liability present value calculations."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from fundedness.models.liabilities import Liability
+
+
+@dataclass
+class LiabilityPV:
+    """Present value calculation result for a liability."""
+
+    liability: Liability
+    present_value: float
+    nominal_total: float
+    inflation_adjustment: float
+    discount_factor: float
+
+
+def calculate_annuity_pv(
+    annual_payment: float,
+    n_years: int,
+    discount_rate: float,
+    growth_rate: float = 0.0,
+    start_year: int = 0,
+) -> float:
+    """Calculate present value of a growing annuity.
+
+    Args:
+        annual_payment: Annual payment amount (in today's dollars)
+        n_years: Number of payment years
+        discount_rate: Annual real discount rate (decimal)
+        growth_rate: Annual growth rate of payments (decimal, e.g., for inflation)
+        start_year: Years until first payment (0 = immediate)
+
+    Returns:
+        Present value of the annuity
+    """
+    if n_years <= 0:
+        return 0.0
+
+    if discount_rate == growth_rate:
+        # Special case: growing perpetuity formula doesn't apply
+        # Use simple sum
+        pv = annual_payment * n_years / ((1 + discount_rate) ** start_year)
+        return pv
+
+    # Present value of growing annuity formula
+    # PV = P * [1 - ((1+g)/(1+r))^n] / (r - g)
+    # where P = first payment, g = growth rate, r = discount rate, n = years
+
+    factor = ((1 + growth_rate) / (1 + discount_rate)) ** n_years
+    if abs(discount_rate - growth_rate) < 1e-10:
+        # Avoid division by near-zero
+        pv_factor = n_years / (1 + discount_rate)
+    else:
+        pv_factor = (1 - factor) / (discount_rate - growth_rate)
+
+    pv = annual_payment * pv_factor
+
+    # Discount back to today if payments start in the future
+    if start_year > 0:
+        pv = pv / ((1 + discount_rate) ** start_year)
+
+    return pv
+
+
+def calculate_liability_pv(
+    liability: Liability,
+    planning_horizon: int,
+    real_discount_rate: float = 0.02,
+    base_inflation: float = 0.025,
+) -> LiabilityPV:
+    """Calculate present value of a single liability.
+
+    Args:
+        liability: The liability to value
+        planning_horizon: Total planning horizon in years
+        real_discount_rate: Real discount rate (decimal)
+        base_inflation: Base CPI inflation assumption (decimal)
+
+    Returns:
+        LiabilityPV with calculation details
+    """
+    # Determine duration
+    end_year = liability.end_year if liability.end_year is not None else planning_horizon
+    n_years = max(0, end_year - liability.start_year)
+
+    if n_years <= 0:
+        return LiabilityPV(
+            liability=liability,
+            present_value=0.0,
+            nominal_total=0.0,
+            inflation_adjustment=1.0,
+            discount_factor=1.0,
+        )
+
+    # Get inflation rate for this liability
+    inflation_rate = liability.get_inflation_rate(base_inflation)
+
+    # Calculate PV
+    pv = calculate_annuity_pv(
+        annual_payment=liability.annual_amount,
+        n_years=n_years,
+        discount_rate=real_discount_rate,
+        growth_rate=inflation_rate - base_inflation,  # Real growth above CPI
+        start_year=liability.start_year,
+    )
+
+    # Apply probability adjustment
+    pv *= liability.probability
+
+    # Calculate nominal total for reference
+    nominal_total = liability.annual_amount * n_years
+
+    # Calculate inflation adjustment factor
+    avg_inflation_factor = (1 + inflation_rate) ** (n_years / 2)
+
+    # Calculate average discount factor
+    avg_discount_factor = 1 / ((1 + real_discount_rate) ** (liability.start_year + n_years / 2))
+
+    return LiabilityPV(
+        liability=liability,
+        present_value=pv,
+        nominal_total=nominal_total,
+        inflation_adjustment=avg_inflation_factor,
+        discount_factor=avg_discount_factor,
+    )
+
+
+def calculate_total_liability_pv(
+    liabilities: list[Liability],
+    planning_horizon: int,
+    real_discount_rate: float = 0.02,
+    base_inflation: float = 0.025,
+) -> tuple[float, list[LiabilityPV]]:
+    """Calculate total present value of all liabilities.
+
+    Args:
+        liabilities: List of liabilities to value
+        planning_horizon: Total planning horizon in years
+        real_discount_rate: Real discount rate (decimal)
+        base_inflation: Base CPI inflation assumption (decimal)
+
+    Returns:
+        Tuple of (total_pv, list of LiabilityPV details)
+    """
+    details = [
+        calculate_liability_pv(
+            liability=liability,
+            planning_horizon=planning_horizon,
+            real_discount_rate=real_discount_rate,
+            base_inflation=base_inflation,
+        )
+        for liability in liabilities
+    ]
+
+    total_pv = sum(d.present_value for d in details)
+
+    return total_pv, details
+
+
+def calculate_essential_liability_pv(
+    liabilities: list[Liability],
+    planning_horizon: int,
+    real_discount_rate: float = 0.02,
+    base_inflation: float = 0.025,
+) -> float:
+    """Calculate present value of essential (floor) liabilities only.
+
+    Args:
+        liabilities: List of all liabilities
+        planning_horizon: Total planning horizon in years
+        real_discount_rate: Real discount rate (decimal)
+        base_inflation: Base CPI inflation assumption (decimal)
+
+    Returns:
+        Present value of essential liabilities
+    """
+    essential = [l for l in liabilities if l.is_essential]
+    total_pv, _ = calculate_total_liability_pv(
+        liabilities=essential,
+        planning_horizon=planning_horizon,
+        real_discount_rate=real_discount_rate,
+        base_inflation=base_inflation,
+    )
+    return total_pv
+
+
+def generate_liability_schedule(
+    liabilities: list[Liability],
+    n_years: int,
+    base_inflation: float = 0.025,
+) -> np.ndarray:
+    """Generate year-by-year liability schedule.
+
+    Args:
+        liabilities: List of liabilities
+        n_years: Number of years to project
+        base_inflation: Base CPI inflation assumption
+
+    Returns:
+        Array of shape (n_years,) with total liability per year
+    """
+    schedule = np.zeros(n_years)
+
+    for liability in liabilities:
+        inflation_rate = liability.get_inflation_rate(base_inflation)
+        end_year = min(
+            liability.end_year if liability.end_year is not None else n_years,
+            n_years,
+        )
+
+        for year in range(liability.start_year, end_year):
+            if year < n_years:
+                # Adjust for inflation from year 0
+                inflation_factor = (1 + inflation_rate) ** year
+                schedule[year] += liability.annual_amount * inflation_factor * liability.probability
+
+    return schedule