fundedness 0.2.2__py3-none-any.whl

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

fundedness/liquidity.py

@@ -0,0 +1,49 @@
+"""Liquidity factor mappings for CEFR calculations."""
+
+from fundedness.models.assets import LiquidityClass
+
+# Default liquidity factors by class
+# These represent the fraction of asset value that can be readily accessed
+DEFAULT_LIQUIDITY_FACTORS: dict[LiquidityClass, float] = {
+    LiquidityClass.CASH: 1.0,  # Immediately liquid
+    LiquidityClass.TAXABLE_INDEX: 0.95,  # Small trading costs
+    LiquidityClass.RETIREMENT: 0.85,  # Early withdrawal penalties, RMD constraints
+    LiquidityClass.HOME_EQUITY: 0.50,  # HELOC access, selling costs
+    LiquidityClass.PRIVATE_BUSINESS: 0.30,  # Very illiquid, long sale process
+    LiquidityClass.RESTRICTED: 0.20,  # Vesting constraints, lockups
+}
+
+
+def get_liquidity_factor(
+    liquidity_class: LiquidityClass,
+    custom_factors: dict[LiquidityClass, float] | None = None,
+) -> float:
+    """Get the liquidity factor for an asset class.
+
+    Args:
+        liquidity_class: The liquidity classification of the asset
+        custom_factors: Optional custom factor overrides
+
+    Returns:
+        Liquidity factor between 0 and 1
+    """
+    if custom_factors and liquidity_class in custom_factors:
+        return custom_factors[liquidity_class]
+    return DEFAULT_LIQUIDITY_FACTORS.get(liquidity_class, 1.0)
+
+
+def get_all_liquidity_factors(
+    custom_factors: dict[LiquidityClass, float] | None = None,
+) -> dict[LiquidityClass, float]:
+    """Get all liquidity factors with optional overrides.
+
+    Args:
+        custom_factors: Optional custom factor overrides
+
+    Returns:
+        Dictionary of liquidity class to factor
+    """
+    factors = DEFAULT_LIQUIDITY_FACTORS.copy()
+    if custom_factors:
+        factors.update(custom_factors)
+    return factors