fundedness 0.1.0__py3-none-any.whl

fundedness/models/simulation.py

@@ -0,0 +1,80 @@
+"""Simulation configuration model."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from fundedness.models.market import MarketModel
+from fundedness.models.tax import TaxModel
+from fundedness.models.utility import UtilityModel
+
+
+class SimulationConfig(BaseModel):
+    """Configuration for Monte Carlo simulations."""
+
+    # Simulation parameters
+    n_simulations: int = Field(
+        default=10000,
+        ge=100,
+        le=100000,
+        description="Number of Monte Carlo paths",
+    )
+    n_years: int = Field(
+        default=50,
+        ge=1,
+        le=100,
+        description="Simulation horizon in years",
+    )
+    random_seed: int | None = Field(
+        default=None,
+        description="Random seed for reproducibility (None = random)",
+    )
+
+    # Model components
+    market_model: MarketModel = Field(
+        default_factory=MarketModel,
+        description="Market return and risk assumptions",
+    )
+    tax_model: TaxModel = Field(
+        default_factory=TaxModel,
+        description="Tax rate assumptions",
+    )
+    utility_model: UtilityModel = Field(
+        default_factory=UtilityModel,
+        description="Utility function parameters",
+    )
+
+    # Return generation
+    return_model: Literal["lognormal", "t_distribution", "bootstrap"] = Field(
+        default="lognormal",
+        description="Model for generating returns",
+    )
+
+    # Output options
+    percentiles: list[int] = Field(
+        default=[10, 25, 50, 75, 90],
+        description="Percentiles to report (0-100)",
+    )
+    track_spending: bool = Field(
+        default=True,
+        description="Track spending paths in simulation",
+    )
+    track_allocation: bool = Field(
+        default=False,
+        description="Track allocation changes over time",
+    )
+
+    # Performance
+    use_vectorized: bool = Field(
+        default=True,
+        description="Use vectorized numpy operations for speed",
+    )
+    chunk_size: int = Field(
+        default=1000,
+        ge=100,
+        description="Chunk size for memory-efficient simulation",
+    )
+
+    def get_percentile_labels(self) -> list[str]:
+        """Get formatted percentile labels."""
+        return [f"P{p}" for p in self.percentiles]

fundedness/models/tax.py

@@ -0,0 +1,125 @@
+"""Tax model for after-tax calculations."""
+
+from pydantic import BaseModel, Field
+
+from fundedness.models.assets import AccountType
+
+
+class TaxModel(BaseModel):
+    """Tax rates and assumptions."""
+
+    # Federal marginal rates
+    federal_ordinary_rate: float = Field(
+        default=0.24,
+        ge=0,
+        le=1,
+        description="Federal marginal tax rate on ordinary income",
+    )
+    federal_ltcg_rate: float = Field(
+        default=0.15,
+        ge=0,
+        le=1,
+        description="Federal long-term capital gains rate",
+    )
+    federal_stcg_rate: float = Field(
+        default=0.24,
+        ge=0,
+        le=1,
+        description="Federal short-term capital gains rate (usually = ordinary)",
+    )
+
+    # State rates
+    state_ordinary_rate: float = Field(
+        default=0.093,
+        ge=0,
+        le=1,
+        description="State marginal tax rate on ordinary income",
+    )
+    state_ltcg_rate: float = Field(
+        default=0.093,
+        ge=0,
+        le=1,
+        description="State long-term capital gains rate",
+    )
+
+    # Other
+    niit_rate: float = Field(
+        default=0.038,
+        ge=0,
+        le=1,
+        description="Net Investment Income Tax rate (3.8%)",
+    )
+    niit_applies: bool = Field(
+        default=True,
+        description="Whether NIIT applies to this household",
+    )
+
+    # Cost basis assumptions
+    default_cost_basis_ratio: float = Field(
+        default=0.5,
+        ge=0,
+        le=1,
+        description="Default cost basis as fraction of value (for unrealized gains)",
+    )
+
+    @property
+    def total_ordinary_rate(self) -> float:
+        """Combined federal + state ordinary income tax rate."""
+        return self.federal_ordinary_rate + self.state_ordinary_rate
+
+    @property
+    def total_ltcg_rate(self) -> float:
+        """Combined federal + state + NIIT long-term capital gains rate."""
+        base = self.federal_ltcg_rate + self.state_ltcg_rate
+        if self.niit_applies:
+            base += self.niit_rate
+        return base
+
+    def get_effective_tax_rate(
+        self,
+        account_type: AccountType,
+        cost_basis_ratio: float | None = None,
+    ) -> float:
+        """Get the effective tax rate for withdrawals from an account type.
+
+        Args:
+            account_type: Type of account
+            cost_basis_ratio: Cost basis as fraction of value (for taxable accounts)
+
+        Returns:
+            Effective tax rate as decimal (0-1)
+        """
+        match account_type:
+            case AccountType.TAX_EXEMPT:
+                # Roth: no tax on withdrawals
+                return 0.0
+
+            case AccountType.TAX_DEFERRED:
+                # Traditional IRA/401k: taxed as ordinary income
+                return self.total_ordinary_rate
+
+            case AccountType.HSA:
+                # HSA: no tax if used for medical expenses
+                return 0.0
+
+            case AccountType.TAXABLE:
+                # Taxable: only gains are taxed
+                if cost_basis_ratio is None:
+                    cost_basis_ratio = self.default_cost_basis_ratio
+
+                # Gains portion = (1 - cost_basis_ratio)
+                gains_portion = 1 - cost_basis_ratio
+                return gains_portion * self.total_ltcg_rate
+
+    def get_haircut_by_account_type(self) -> dict[AccountType, float]:
+        """Get tax haircut factors by account type.
+
+        Returns:
+            Dictionary mapping account type to (1 - tax_rate)
+        """
+        return {
+            AccountType.TAXABLE: 1 - self.get_effective_tax_rate(AccountType.TAXABLE),
+            AccountType.TAX_DEFERRED: 1 - self.get_effective_tax_rate(AccountType.TAX_DEFERRED),
+            AccountType.TAX_EXEMPT: 1 - self.get_effective_tax_rate(AccountType.TAX_EXEMPT),
+            AccountType.HSA: 1 - self.get_effective_tax_rate(AccountType.HSA),
+        }

fundedness/models/utility.py

@@ -0,0 +1,154 @@
+"""Utility model for lifetime utility optimization."""
+
+import numpy as np
+from pydantic import BaseModel, Field
+
+
+class UtilityModel(BaseModel):
+    """CRRA utility model with subsistence floor."""
+
+    gamma: float = Field(
+        default=3.0,
+        gt=0,
+        description="Coefficient of relative risk aversion (CRRA parameter)",
+    )
+    subsistence_floor: float = Field(
+        default=30000,
+        ge=0,
+        description="Minimum annual spending floor in dollars",
+    )
+    bequest_weight: float = Field(
+        default=0.0,
+        ge=0,
+        le=1,
+        description="Weight on bequest utility (0 = no bequest motive)",
+    )
+    time_preference: float = Field(
+        default=0.02,
+        ge=0,
+        description="Pure rate of time preference (discount rate for utility)",
+    )
+
+    def utility(self, consumption: float) -> float:
+        """Calculate CRRA utility of consumption.
+
+        Args:
+            consumption: Annual consumption in dollars
+
+        Returns:
+            Utility value (can be negative)
+
+        Raises:
+            ValueError: If consumption is below subsistence floor
+        """
+        excess = consumption - self.subsistence_floor
+
+        if excess <= 0:
+            # Below floor: large negative utility
+            return -1e10
+
+        if self.gamma == 1.0:
+            # Log utility special case
+            return np.log(excess)
+
+        return (excess ** (1 - self.gamma)) / (1 - self.gamma)
+
+    def marginal_utility(self, consumption: float) -> float:
+        """Calculate marginal utility of consumption.
+
+        Args:
+            consumption: Annual consumption in dollars
+
+        Returns:
+            Marginal utility value
+        """
+        excess = consumption - self.subsistence_floor
+
+        if excess <= 0:
+            return 1e10  # Very high marginal utility when below floor
+
+        return excess ** (-self.gamma)
+
+    def inverse_marginal_utility(self, mu: float) -> float:
+        """Calculate consumption from marginal utility (for optimization).
+
+        Args:
+            mu: Marginal utility value
+
+        Returns:
+            Consumption that produces this marginal utility
+        """
+        excess = mu ** (-1 / self.gamma)
+        return excess + self.subsistence_floor
+
+    def certainty_equivalent(
+        self,
+        consumption_samples: np.ndarray,
+    ) -> float:
+        """Calculate certainty equivalent consumption.
+
+        The certainty equivalent is the guaranteed consumption that
+        provides the same expected utility as the risky consumption stream.
+
+        Args:
+            consumption_samples: Array of consumption outcomes
+
+        Returns:
+            Certainty equivalent consumption value
+        """
+        # Calculate expected utility
+        utilities = np.array([self.utility(c) for c in consumption_samples])
+        expected_utility = np.mean(utilities)
+
+        # Invert to find certainty equivalent
+        if self.gamma == 1.0:
+            return np.exp(expected_utility) + self.subsistence_floor
+
+        # For CRRA: CE = (EU * (1-gamma))^(1/(1-gamma)) + floor
+        ce_excess = (expected_utility * (1 - self.gamma)) ** (1 / (1 - self.gamma))
+        return ce_excess + self.subsistence_floor
+
+    def lifetime_utility(
+        self,
+        consumption_path: np.ndarray,
+        survival_probabilities: np.ndarray | None = None,
+    ) -> float:
+        """Calculate discounted lifetime utility.
+
+        Args:
+            consumption_path: Array of annual consumption values
+            survival_probabilities: Probability of being alive at each year (optional)
+
+        Returns:
+            Discounted expected lifetime utility
+        """
+        n_years = len(consumption_path)
+
+        if survival_probabilities is None:
+            survival_probabilities = np.ones(n_years)
+
+        total_utility = 0.0
+        for t, (consumption, survival_prob) in enumerate(
+            zip(consumption_path, survival_probabilities)
+        ):
+            discount = (1 + self.time_preference) ** (-t)
+            total_utility += discount * survival_prob * self.utility(consumption)
+
+        return total_utility
+
+    def risk_tolerance(self, wealth: float) -> float:
+        """Calculate risk tolerance at a given wealth level.
+
+        Risk tolerance = 1 / (gamma * wealth) for CRRA utility.
+
+        Args:
+            wealth: Current wealth level
+
+        Returns:
+            Risk tolerance as decimal
+        """
+        if wealth <= self.subsistence_floor:
+            return 0.0  # No risk tolerance below floor
+
+        excess_wealth = wealth - self.subsistence_floor
+        return 1 / (self.gamma * excess_wealth) * excess_wealth

fundedness/policies.py

@@ -0,0 +1,204 @@
+"""Spending and allocation policy implementations."""
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass
+class FixedRealSpending:
+    """Fixed real (inflation-adjusted) spending policy."""
+
+    annual_spending: float
+    inflation_rate: float = 0.025
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get spending, capped at available wealth."""
+        nominal_spending = self.annual_spending * (1 + self.inflation_rate) ** year
+        return np.minimum(nominal_spending, np.maximum(wealth, 0))
+
+
+@dataclass
+class PercentOfPortfolio:
+    """Spend a fixed percentage of current portfolio value."""
+
+    percentage: float = 0.04  # 4% rule
+    floor: float | None = None
+    ceiling: float | None = None
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Get spending as percentage of current wealth."""
+        spending = wealth * self.percentage
+
+        if self.floor is not None:
+            spending = np.maximum(spending, self.floor)
+
+        if self.ceiling is not None:
+            spending = np.minimum(spending, self.ceiling)
+
+        return np.minimum(spending, np.maximum(wealth, 0))
+
+
+@dataclass
+class ConstantAllocation:
+    """Constant stock/bond allocation."""
+
+    stock_weight: float = 0.6
+
+    def get_allocation(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> float:
+        """Return constant stock allocation."""
+        return self.stock_weight
+
+
+@dataclass
+class AgeBasedGlidepath:
+    """Age-based declining equity glidepath.
+
+    Classic rule: stock_weight = 100 - age (or similar)
+    """
+
+    initial_stock_weight: float = 0.8
+    final_stock_weight: float = 0.3
+    years_to_final: int = 30
+    starting_age: int = 65
+
+    def get_allocation(
+        self,
+        wealth: 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 RisingEquityGlidepath:
+    """Rising equity glidepath (bonds-first spending).
+
+    Start conservative, increase equity over time as sequence risk decreases.
+    """
+
+    initial_stock_weight: float = 0.3
+    final_stock_weight: float = 0.7
+    years_to_final: int = 20
+
+    def get_allocation(
+        self,
+        wealth: 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 FundednessBasedAllocation:
+    """Adjust allocation based on current fundedness level.
+
+    Higher fundedness = can take more risk
+    Lower fundedness = reduce risk to protect floor
+    """
+
+    target_fundedness: float = 1.2  # Target CEFR
+    max_stock_weight: float = 0.8
+    min_stock_weight: float = 0.2
+    liability_pv: float = 1_000_000  # PV of future spending
+
+    def get_allocation(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Calculate allocation based on current fundedness."""
+        # Simple fundedness estimate (wealth / liability PV)
+        # In practice, would recalculate full CEFR
+        fundedness = wealth / self.liability_pv
+
+        # Linear interpolation based on fundedness
+        # At target fundedness, use moderate allocation
+        # Above target, can increase stocks
+        # Below target, reduce stocks
+
+        relative_fundedness = fundedness / self.target_fundedness
+
+        # Map to allocation range
+        stock_weight = self.min_stock_weight + (self.max_stock_weight - self.min_stock_weight) * (
+            np.clip(relative_fundedness, 0.5, 1.5) - 0.5
+        )
+
+        return np.clip(stock_weight, self.min_stock_weight, self.max_stock_weight)
+
+
+@dataclass
+class FloorCeilingSpending:
+    """Spending policy with floor and ceiling guardrails.
+
+    Attempts to maintain target spending but:
+    - Never spends below floor (essential spending)
+    - Never spends above ceiling (luxury cap)
+    - Adjusts based on portfolio performance
+    """
+
+    target_spending: float
+    floor_spending: float
+    ceiling_spending: float
+    adjustment_rate: float = 0.05  # How fast to adjust toward target
+
+    def __post_init__(self):
+        self._previous_spending = None
+
+    def get_spending(
+        self,
+        wealth: np.ndarray,
+        year: int,
+        initial_wealth: float,
+    ) -> np.ndarray:
+        """Calculate spending with guardrails."""
+        if self._previous_spending is None:
+            self._previous_spending = np.full_like(wealth, self.target_spending)
+
+        # Calculate sustainable spending estimate (simplified)
+        sustainable_rate = 0.04  # Simple 4% estimate
+        sustainable_spending = wealth * sustainable_rate
+
+        # Target is previous spending (smoothing)
+        target = self._previous_spending
+
+        # Adjust target toward sustainable level
+        target = target + self.adjustment_rate * (sustainable_spending - target)
+
+        # Apply floor and ceiling
+        spending = np.clip(target, self.floor_spending, self.ceiling_spending)
+
+        # Can't spend more than wealth
+        spending = np.minimum(spending, np.maximum(wealth, 0))
+
+        self._previous_spending = spending
+
+        return spending

fundedness/risk.py

@@ -0,0 +1,72 @@
+"""Reliability/risk factor mappings for CEFR calculations."""
+
+from fundedness.models.assets import AssetClass, ConcentrationLevel
+
+# Default reliability factors by concentration level
+# These represent the certainty-equivalent haircut for concentration risk
+DEFAULT_RELIABILITY_FACTORS: dict[ConcentrationLevel, float] = {
+    ConcentrationLevel.DIVERSIFIED: 0.85,  # Broad market index
+    ConcentrationLevel.SECTOR: 0.70,  # Sector concentration
+    ConcentrationLevel.SINGLE_STOCK: 0.60,  # Individual company
+    ConcentrationLevel.STARTUP: 0.30,  # Early-stage, high uncertainty
+}
+
+# Additional reliability adjustments by asset class
+ASSET_CLASS_RELIABILITY: dict[AssetClass, float] = {
+    AssetClass.CASH: 1.0,  # No reliability haircut for cash
+    AssetClass.BONDS: 0.95,  # Slight credit/duration risk
+    AssetClass.STOCKS: 1.0,  # Base reliability (modified by concentration)
+    AssetClass.REAL_ESTATE: 0.90,  # Valuation uncertainty
+    AssetClass.ALTERNATIVES: 0.80,  # Higher uncertainty
+}
+
+
+def get_reliability_factor(
+    concentration_level: ConcentrationLevel,
+    asset_class: AssetClass | None = None,
+    custom_factors: dict[ConcentrationLevel, float] | None = None,
+) -> float:
+    """Get the reliability factor for an asset.
+
+    The reliability factor combines concentration risk with asset class risk.
+
+    Args:
+        concentration_level: The concentration level of the asset
+        asset_class: Optional asset class for additional adjustment
+        custom_factors: Optional custom concentration factor overrides
+
+    Returns:
+        Reliability factor between 0 and 1
+    """
+    # Get concentration-based factor
+    if custom_factors and concentration_level in custom_factors:
+        concentration_factor = custom_factors[concentration_level]
+    else:
+        concentration_factor = DEFAULT_RELIABILITY_FACTORS.get(concentration_level, 1.0)
+
+    # Apply asset class adjustment if provided
+    if asset_class is not None:
+        asset_adjustment = ASSET_CLASS_RELIABILITY.get(asset_class, 1.0)
+        # Cash and bonds don't need concentration haircut
+        if asset_class in (AssetClass.CASH, AssetClass.BONDS):
+            return asset_adjustment
+        return concentration_factor * asset_adjustment
+
+    return concentration_factor
+
+
+def get_all_reliability_factors(
+    custom_factors: dict[ConcentrationLevel, float] | None = None,
+) -> dict[ConcentrationLevel, float]:
+    """Get all reliability factors with optional overrides.
+
+    Args:
+        custom_factors: Optional custom factor overrides
+
+    Returns:
+        Dictionary of concentration level to factor
+    """
+    factors = DEFAULT_RELIABILITY_FACTORS.copy()
+    if custom_factors:
+        factors.update(custom_factors)
+    return factors