fundedness 0.2.2__py3-none-any.whl

fundedness/models/liabilities.py

@@ -0,0 +1,99 @@
+"""Liability models for future spending obligations."""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class LiabilityType(str, Enum):
+    """Type of liability/spending obligation."""
+
+    ESSENTIAL_SPENDING = "essential_spending"  # Non-negotiable living expenses
+    DISCRETIONARY_SPENDING = "discretionary_spending"  # Flexible lifestyle spending
+    LEGACY_GOAL = "legacy_goal"  # Bequest target
+    MORTGAGE = "mortgage"  # Home loan payments
+    DEBT = "debt"  # Other debt obligations
+    HEALTHCARE = "healthcare"  # Healthcare/long-term care costs
+    TAXES = "taxes"  # Future tax obligations
+
+
+class InflationLinkage(str, Enum):
+    """How the liability is linked to inflation."""
+
+    NONE = "none"  # Fixed nominal amount
+    CPI = "cpi"  # Linked to Consumer Price Index
+    WAGE = "wage"  # Linked to wage growth
+    HEALTHCARE = "healthcare"  # Linked to healthcare inflation (typically higher)
+    CUSTOM = "custom"  # Custom inflation rate
+
+
+class Liability(BaseModel):
+    """A future spending obligation or liability."""
+
+    name: str = Field(..., description="Descriptive name for the liability")
+    liability_type: LiabilityType = Field(
+        default=LiabilityType.ESSENTIAL_SPENDING,
+        description="Category of liability",
+    )
+    annual_amount: float = Field(
+        ...,
+        ge=0,
+        description="Annual spending amount in today's dollars",
+    )
+    start_year: int = Field(
+        default=0,
+        ge=0,
+        description="Years from now when liability begins (0 = now)",
+    )
+    end_year: Optional[int] = Field(
+        default=None,
+        ge=0,
+        description="Years from now when liability ends (None = until death)",
+    )
+    inflation_linkage: InflationLinkage = Field(
+        default=InflationLinkage.CPI,
+        description="How the liability adjusts for inflation",
+    )
+    custom_inflation_rate: Optional[float] = Field(
+        default=None,
+        description="Custom inflation rate if inflation_linkage is CUSTOM (decimal)",
+    )
+    probability: float = Field(
+        default=1.0,
+        ge=0,
+        le=1,
+        description="Probability this liability occurs (1.0 = certain)",
+    )
+    is_essential: bool = Field(
+        default=True,
+        description="Whether this is essential (floor) vs discretionary (flex) spending",
+    )
+
+    @property
+    def duration_years(self) -> Optional[int]:
+        """Duration of the liability in years, if end_year is specified."""
+        if self.end_year is None:
+            return None
+        return self.end_year - self.start_year
+
+    def get_inflation_rate(self, base_cpi: float = 0.025) -> float:
+        """Get the effective inflation rate for this liability.
+
+        Args:
+            base_cpi: Base CPI inflation rate assumption
+
+        Returns:
+            Effective annual inflation rate as decimal
+        """
+        match self.inflation_linkage:
+            case InflationLinkage.NONE:
+                return 0.0
+            case InflationLinkage.CPI:
+                return base_cpi
+            case InflationLinkage.WAGE:
+                return base_cpi + 0.01  # Assume 1% real wage growth
+            case InflationLinkage.HEALTHCARE:
+                return base_cpi + 0.02  # Assume 2% excess healthcare inflation
+            case InflationLinkage.CUSTOM:
+                return self.custom_inflation_rate or base_cpi

fundedness/models/market.py

@@ -0,0 +1,188 @@
+"""Market assumptions model."""
+
+from typing import Optional
+
+import numpy as np
+from pydantic import BaseModel, Field, field_validator
+
+
+class MarketModel(BaseModel):
+    """Market return and risk assumptions."""
+
+    # Expected returns (annual, real)
+    stock_return: float = Field(
+        default=0.05,
+        description="Expected real return for stocks (decimal)",
+    )
+    bond_return: float = Field(
+        default=0.015,
+        description="Expected real return for bonds (decimal)",
+    )
+    cash_return: float = Field(
+        default=0.0,
+        description="Expected real return for cash (decimal)",
+    )
+    real_estate_return: float = Field(
+        default=0.03,
+        description="Expected real return for real estate (decimal)",
+    )
+
+    # Volatility (annual standard deviation)
+    stock_volatility: float = Field(
+        default=0.16,
+        ge=0,
+        description="Annual volatility for stocks (decimal)",
+    )
+    bond_volatility: float = Field(
+        default=0.06,
+        ge=0,
+        description="Annual volatility for bonds (decimal)",
+    )
+    cash_volatility: float = Field(
+        default=0.01,
+        ge=0,
+        description="Annual volatility for cash (decimal)",
+    )
+    real_estate_volatility: float = Field(
+        default=0.12,
+        ge=0,
+        description="Annual volatility for real estate (decimal)",
+    )
+
+    # Correlations
+    stock_bond_correlation: float = Field(
+        default=0.0,
+        ge=-1,
+        le=1,
+        description="Correlation between stocks and bonds",
+    )
+    stock_real_estate_correlation: float = Field(
+        default=0.5,
+        ge=-1,
+        le=1,
+        description="Correlation between stocks and real estate",
+    )
+
+    # Inflation
+    inflation_mean: float = Field(
+        default=0.025,
+        description="Expected long-term inflation rate (decimal)",
+    )
+    inflation_volatility: float = Field(
+        default=0.015,
+        ge=0,
+        description="Volatility of inflation (decimal)",
+    )
+
+    # Discount rate
+    real_discount_rate: float = Field(
+        default=0.02,
+        description="Real discount rate for liability PV calculations (decimal)",
+    )
+
+    # Fat tails
+    use_fat_tails: bool = Field(
+        default=False,
+        description="Use t-distribution for fatter tails",
+    )
+    degrees_of_freedom: int = Field(
+        default=5,
+        ge=3,
+        description="Degrees of freedom for t-distribution (lower = fatter tails)",
+    )
+
+    @field_validator("degrees_of_freedom")
+    @classmethod
+    def validate_dof(cls, v: int) -> int:
+        """Ensure degrees of freedom is reasonable."""
+        if v < 3:
+            raise ValueError("Degrees of freedom must be at least 3")
+        return v
+
+    def get_correlation_matrix(self) -> np.ndarray:
+        """Get the correlation matrix for asset classes.
+
+        Returns:
+            4x4 correlation matrix for [stocks, bonds, cash, real_estate]
+        """
+        return np.array([
+            [1.0, self.stock_bond_correlation, 0.0, self.stock_real_estate_correlation],
+            [self.stock_bond_correlation, 1.0, 0.1, 0.2],
+            [0.0, 0.1, 1.0, 0.0],
+            [self.stock_real_estate_correlation, 0.2, 0.0, 1.0],
+        ])
+
+    def get_covariance_matrix(self) -> np.ndarray:
+        """Get the covariance matrix for asset classes.
+
+        Returns:
+            4x4 covariance matrix for [stocks, bonds, cash, real_estate]
+        """
+        volatilities = np.array([
+            self.stock_volatility,
+            self.bond_volatility,
+            self.cash_volatility,
+            self.real_estate_volatility,
+        ])
+        corr = self.get_correlation_matrix()
+        # Covariance = outer product of volatilities * correlation
+        return np.outer(volatilities, volatilities) * corr
+
+    def get_cholesky_decomposition(self) -> np.ndarray:
+        """Get Cholesky decomposition for correlated returns generation.
+
+        Returns:
+            Lower triangular Cholesky matrix
+        """
+        cov = self.get_covariance_matrix()
+        return np.linalg.cholesky(cov)
+
+    def expected_portfolio_return(
+        self,
+        stock_weight: float,
+        bond_weight: Optional[float] = None,
+    ) -> float:
+        """Calculate expected return for a portfolio.
+
+        Args:
+            stock_weight: Weight in stocks (0-1)
+            bond_weight: Weight in bonds (remainder is cash if not specified)
+
+        Returns:
+            Expected annual real return
+        """
+        if bond_weight is None:
+            bond_weight = 1 - stock_weight
+
+        cash_weight = max(0, 1 - stock_weight - bond_weight)
+
+        return (
+            stock_weight * self.stock_return
+            + bond_weight * self.bond_return
+            + cash_weight * self.cash_return
+        )
+
+    def portfolio_volatility(
+        self,
+        stock_weight: float,
+        bond_weight: Optional[float] = None,
+    ) -> float:
+        """Calculate portfolio volatility.
+
+        Args:
+            stock_weight: Weight in stocks (0-1)
+            bond_weight: Weight in bonds (remainder is cash if not specified)
+
+        Returns:
+            Annual portfolio volatility
+        """
+        if bond_weight is None:
+            bond_weight = 1 - stock_weight
+
+        cash_weight = max(0, 1 - stock_weight - bond_weight)
+        weights = np.array([stock_weight, bond_weight, cash_weight, 0])
+
+        cov = self.get_covariance_matrix()
+        portfolio_variance = weights @ cov @ weights
+
+        return np.sqrt(portfolio_variance)

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