fundedness 0.1.0__py3-none-any.whl

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

fundedness/models/__init__.py

@@ -0,0 +1,35 @@
+"""Pydantic data models for the fundedness package."""
+
+from fundedness.models.assets import (
+    AccountType,
+    Asset,
+    AssetClass,
+    BalanceSheet,
+    ConcentrationLevel,
+    LiquidityClass,
+)
+from fundedness.models.household import Household, Person
+from fundedness.models.liabilities import InflationLinkage, Liability, LiabilityType
+from fundedness.models.market import MarketModel
+from fundedness.models.simulation import SimulationConfig
+from fundedness.models.tax import TaxModel
+from fundedness.models.utility import UtilityModel
+
+__all__ = [
+    "AccountType",
+    "Asset",
+    "AssetClass",
+    "BalanceSheet",
+    "ConcentrationLevel",
+    "Household",
+    "InflationLinkage",
+    "Liability",
+    "LiabilityClass",
+    "LiabilityType",
+    "LiquidityClass",
+    "MarketModel",
+    "Person",
+    "SimulationConfig",
+    "TaxModel",
+    "UtilityModel",
+]

fundedness/models/assets.py

@@ -0,0 +1,148 @@
+"""Asset and balance sheet models."""
+
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class AccountType(str, Enum):
+    """Tax treatment of an account."""
+
+    TAXABLE = "taxable"
+    TAX_DEFERRED = "tax_deferred"  # Traditional IRA, 401(k)
+    TAX_EXEMPT = "tax_exempt"  # Roth IRA, Roth 401(k)
+    HSA = "hsa"
+
+
+class AssetClass(str, Enum):
+    """Broad asset class categories."""
+
+    CASH = "cash"
+    BONDS = "bonds"
+    STOCKS = "stocks"
+    REAL_ESTATE = "real_estate"
+    ALTERNATIVES = "alternatives"
+
+
+class LiquidityClass(str, Enum):
+    """Liquidity classification for assets."""
+
+    CASH = "cash"  # Immediate liquidity
+    TAXABLE_INDEX = "taxable_index"  # Public securities in taxable accounts
+    RETIREMENT = "retirement"  # Tax-advantaged retirement accounts
+    HOME_EQUITY = "home_equity"  # Primary residence equity
+    PRIVATE_BUSINESS = "private_business"  # Illiquid business interests
+    RESTRICTED = "restricted"  # Restricted stock, vesting schedules
+
+
+class ConcentrationLevel(str, Enum):
+    """Concentration/diversification level."""
+
+    DIVERSIFIED = "diversified"  # Broad index funds
+    SECTOR = "sector"  # Sector-specific concentration
+    SINGLE_STOCK = "single_stock"  # Individual company stock
+    STARTUP = "startup"  # Early-stage company equity
+
+
+class Asset(BaseModel):
+    """A single asset holding."""
+
+    name: str = Field(..., description="Descriptive name for the asset")
+    value: float = Field(..., ge=0, description="Current market value in dollars")
+    account_type: AccountType = Field(
+        default=AccountType.TAXABLE,
+        description="Tax treatment of the account",
+    )
+    asset_class: AssetClass = Field(
+        default=AssetClass.STOCKS,
+        description="Broad asset class category",
+    )
+    liquidity_class: LiquidityClass = Field(
+        default=LiquidityClass.TAXABLE_INDEX,
+        description="Liquidity classification",
+    )
+    concentration_level: ConcentrationLevel = Field(
+        default=ConcentrationLevel.DIVERSIFIED,
+        description="Concentration/diversification level",
+    )
+    cost_basis: Optional[float] = Field(
+        default=None,
+        ge=0,
+        description="Cost basis for tax calculations (taxable accounts only)",
+    )
+    expected_return: Optional[float] = Field(
+        default=None,
+        description="Override expected return (annual, decimal)",
+    )
+    volatility: Optional[float] = Field(
+        default=None,
+        ge=0,
+        description="Override volatility (annual standard deviation, decimal)",
+    )
+
+    @field_validator("cost_basis")
+    @classmethod
+    def validate_cost_basis(cls, v: Optional[float], info) -> Optional[float]:
+        """Warn if cost basis exceeds value (unrealized loss)."""
+        return v
+
+    @property
+    def unrealized_gain(self) -> Optional[float]:
+        """Calculate unrealized gain/loss if cost basis is known."""
+        if self.cost_basis is None:
+            return None
+        return self.value - self.cost_basis
+
+
+class BalanceSheet(BaseModel):
+    """Collection of assets representing a household's balance sheet."""
+
+    assets: list[Asset] = Field(default_factory=list, description="List of asset holdings")
+
+    @property
+    def total_value(self) -> float:
+        """Total market value of all assets."""
+        return sum(asset.value for asset in self.assets)
+
+    @property
+    def by_account_type(self) -> dict[AccountType, float]:
+        """Total value by account type."""
+        result: dict[AccountType, float] = {}
+        for asset in self.assets:
+            result[asset.account_type] = result.get(asset.account_type, 0) + asset.value
+        return result
+
+    @property
+    def by_asset_class(self) -> dict[AssetClass, float]:
+        """Total value by asset class."""
+        result: dict[AssetClass, float] = {}
+        for asset in self.assets:
+            result[asset.asset_class] = result.get(asset.asset_class, 0) + asset.value
+        return result
+
+    @property
+    def by_liquidity_class(self) -> dict[LiquidityClass, float]:
+        """Total value by liquidity class."""
+        result: dict[LiquidityClass, float] = {}
+        for asset in self.assets:
+            result[asset.liquidity_class] = result.get(asset.liquidity_class, 0) + asset.value
+        return result
+
+    def get_stock_allocation(self) -> float:
+        """Calculate percentage allocated to stocks."""
+        if self.total_value == 0:
+            return 0.0
+        stock_value = sum(
+            asset.value for asset in self.assets if asset.asset_class == AssetClass.STOCKS
+        )
+        return stock_value / self.total_value
+
+    def get_bond_allocation(self) -> float:
+        """Calculate percentage allocated to bonds."""
+        if self.total_value == 0:
+            return 0.0
+        bond_value = sum(
+            asset.value for asset in self.assets if asset.asset_class == AssetClass.BONDS
+        )
+        return bond_value / self.total_value

fundedness/models/household.py

@@ -0,0 +1,153 @@
+"""Household and person models."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field, model_validator
+
+from fundedness.models.assets import BalanceSheet
+from fundedness.models.liabilities import Liability
+
+
+class Person(BaseModel):
+    """An individual person in the household."""
+
+    name: str = Field(..., description="Person's name")
+    age: int = Field(..., ge=0, le=120, description="Current age")
+    retirement_age: Optional[int] = Field(
+        default=None,
+        ge=0,
+        le=120,
+        description="Expected retirement age (None if already retired)",
+    )
+    life_expectancy: int = Field(
+        default=95,
+        ge=0,
+        le=120,
+        description="Planning life expectancy",
+    )
+    social_security_age: int = Field(
+        default=67,
+        ge=62,
+        le=70,
+        description="Age to claim Social Security",
+    )
+    social_security_annual: float = Field(
+        default=0,
+        ge=0,
+        description="Expected annual Social Security benefit at claiming age (today's dollars)",
+    )
+    pension_annual: float = Field(
+        default=0,
+        ge=0,
+        description="Expected annual pension benefit (today's dollars)",
+    )
+    pension_start_age: Optional[int] = Field(
+        default=None,
+        ge=0,
+        le=120,
+        description="Age when pension payments begin",
+    )
+    is_primary: bool = Field(
+        default=True,
+        description="Whether this is the primary earner/planner",
+    )
+
+    @model_validator(mode="after")
+    def validate_ages(self) -> "Person":
+        """Validate age relationships."""
+        if self.retirement_age is not None and self.retirement_age < self.age:
+            # Already past retirement age, treat as retired
+            self.retirement_age = None
+        if self.life_expectancy < self.age:
+            raise ValueError("Life expectancy must be greater than current age")
+        return self
+
+    @property
+    def years_to_retirement(self) -> int:
+        """Years until retirement (0 if already retired)."""
+        if self.retirement_age is None:
+            return 0
+        return max(0, self.retirement_age - self.age)
+
+    @property
+    def years_in_retirement(self) -> int:
+        """Expected years in retirement."""
+        retirement_age = self.retirement_age or self.age
+        return max(0, self.life_expectancy - retirement_age)
+
+    @property
+    def planning_horizon(self) -> int:
+        """Total years in planning horizon."""
+        return max(0, self.life_expectancy - self.age)
+
+
+class Household(BaseModel):
+    """A household unit for financial planning."""
+
+    name: str = Field(
+        default="My Household",
+        description="Household name",
+    )
+    members: list[Person] = Field(
+        default_factory=list,
+        description="Household members",
+    )
+    balance_sheet: BalanceSheet = Field(
+        default_factory=BalanceSheet,
+        description="Household balance sheet",
+    )
+    liabilities: list[Liability] = Field(
+        default_factory=list,
+        description="Future spending obligations",
+    )
+    state: str = Field(
+        default="CA",
+        description="State of residence (for tax calculations)",
+    )
+    filing_status: str = Field(
+        default="married_filing_jointly",
+        description="Tax filing status",
+    )
+
+    @property
+    def primary_member(self) -> Optional[Person]:
+        """Get the primary household member."""
+        for member in self.members:
+            if member.is_primary:
+                return member
+        return self.members[0] if self.members else None
+
+    @property
+    def planning_horizon(self) -> int:
+        """Planning horizon based on longest-lived member."""
+        if not self.members:
+            return 30  # Default
+        return max(member.planning_horizon for member in self.members)
+
+    @property
+    def total_assets(self) -> float:
+        """Total asset value."""
+        return self.balance_sheet.total_value
+
+    @property
+    def essential_spending(self) -> float:
+        """Total annual essential spending."""
+        return sum(
+            liability.annual_amount
+            for liability in self.liabilities
+            if liability.is_essential
+        )
+
+    @property
+    def discretionary_spending(self) -> float:
+        """Total annual discretionary spending."""
+        return sum(
+            liability.annual_amount
+            for liability in self.liabilities
+            if not liability.is_essential
+        )
+
+    @property
+    def total_spending(self) -> float:
+        """Total annual spending target."""
+        return self.essential_spending + self.discretionary_spending

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)