fundedness 0.2.0__tar.gz

fundedness-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install mkdocs mkdocs-material mkdocstrings[python]
+      - run: pip install -e .
+      - run: mkdocs build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/deploy-pages@v4
+        id: deployment

fundedness-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build tools
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

fundedness-0.2.0/.gitignore

@@ -0,0 +1,106 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+secrets.yaml
+config.local.yaml

fundedness-0.2.0/CLAUDE.md

@@ -0,0 +1,98 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Python financial planning toolkit that implements:
+- **CEFR (Certainty-Equivalent Funded Ratio)**: A fundedness metric that applies after-tax, liquidity, and risk haircuts to assets
+- **Victor-style lifetime utility optimization**: Spending and asset allocation policies that maximize expected lifetime utility
+- **Withdrawal Strategy Lab**: Comparison framework for withdrawal strategies (fixed SWR, guardrails, VPW, RMD-style)
+
+The project includes both a Python package (`fundedness/`) and a Streamlit web application (`streamlit_app/`).
+
+## Development Status
+
+This project is in the **specification/planning phase**. The `background_information.md` file contains the complete design spec. No implementation code exists yet.
+
+## Planned Commands
+
+Once implemented, the project will use:
+- **Package manager**: pip
+- **Testing**: pytest (with property tests for monotonicity)
+- **Docs**: MkDocs
+- **CLI**: `fundedness cefr config.yaml`, `fundedness simulate config.yaml`, `fundedness policy-search config.yaml`
+- **Streamlit**: `streamlit run streamlit_app/app.py`
+
+## Architecture
+
+### Core Package Structure (`fundedness/`)
+
+```
+fundedness/
+├── cefr.py              # CEFR ratio calculation with haircut breakdowns
+├── liabilities.py       # Liability PV calculations with schedules
+├── taxes.py             # Tax modeling by account type
+├── liquidity.py         # Liquidity factor adjustments
+├── risk.py              # Reliability/concentration haircuts
+├── markets.py           # Return/covariance/inflation assumptions
+├── simulate.py          # Monte Carlo engine (time-to-floor, time-to-ruin)
+├── utility.py           # CRRA utility with subsistence floor
+├── policies.py          # Spending/allocation policy interface
+├── optimize.py          # Parametric policy search (v0.4+)
+├── withdrawals/         # Withdrawal strategy implementations
+├── allocation/          # Glidepath strategies (constant, rising equity, bucket)
+└── tax/strategy.py      # Tax-aware withdrawal sequencing
+```
+
+### Data Models (Pydantic)
+
+Key models: `Household`, `BalanceSheet`, `Asset`, `Liability`, `MarketModel`, `TaxModel`, `UtilityModel`, `SimulationConfig`
+
+### Core Formulas
+
+**CEFR Calculation:**
+```
+CEFR = Σ(Asset × (1-tax_rate) × liquidity_factor × reliability_factor) / PV(Liabilities)
+```
+
+**CRRA Utility with Floor:**
+```
+u(C) = (C - F)^(1-γ) / (1-γ)  where C > F (subsistence floor)
+```
+
+## Development Tiers
+
+1. **MVP (v0.1-0.3)**: CEFR + Monte Carlo runway with P10/P50/P90 bands
+2. **v0.4-0.7**: Victor-style parametric policy search
+3. **v1.0+**: Tax-aware account flows, Roth conversions
+
+## Key Concepts
+
+- **Haircuts**: Three adjustments to assets—after-tax (τ), liquidity (λ), reliability (ρ)
+- **Floor/Flex spending**: Essential spending floor vs adjustable discretionary
+- **Time metrics**: Time-to-floor-breach, time-to-ruin, max spending drawdown
+- **Confidence intervals**: Scenario percentiles (P10/P50/P90), not statistical CIs
+
+## Default Haircut Assumptions
+
+Liquidity: cash=1.0, taxable_index=0.95, retirement=0.85, home_equity=0.5, private_business=0.3
+Reliability: diversified_bonds=0.95, diversified_equity=0.85, single_stock=0.60, startup=0.30
+
+## Deployment Preferences
+
+- **Web App**: Deploy on Streamlit Cloud (free tier)
+- **API**: Expose core functionality via a REST API (FastAPI recommended) for programmatic access
+- **Tutorials**: Create Jupyter notebooks in `examples/` that run in Google Colab. Include working "Open in Colab" badge links in the README using the format:
+  ```
+  [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/engineerinvestor/financial-health-calculator/blob/main/examples/NOTEBOOK.ipynb)
+  ```
+
+## Visualization Standards
+
+Use **Plotly** as the primary visualization library for beautiful, interactive charts:
+- Clean, professional appearance with `template="plotly_white"`
+- Interactive features: hover tooltips, zoom, pan
+- Consistent color palette: blues (#3498db, #2980b9) for wealth, greens (#27ae60, #2ecc71) for spending/survival
+- Fan charts with gradient opacity for percentile bands (P10-P90)
+- Export capability to HTML/PNG for reports

fundedness-0.2.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: fundedness
+Version: 0.2.0
+Summary: A Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful visualizations
+Project-URL: Homepage, https://github.com/engineerinvestor/financial-health-calculator
+Project-URL: Documentation, https://engineerinvestor.github.io/financial-health-calculator/
+Project-URL: Repository, https://github.com/engineerinvestor/financial-health-calculator
+Author-email: Engineer Investor <egr.investor@gmail.com>
+License-Expression: MIT
+Keywords: CEFR,Monte Carlo,finance,planning,retirement,withdrawal
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: plotly>=5.18.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: scipy>=1.11.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.108.0; extra == 'all'
+Requires-Dist: hypothesis>=6.92.0; extra == 'all'
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'all'
+Requires-Dist: mkdocs>=1.5.0; extra == 'all'
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'all'
+Requires-Dist: mypy>=1.8.0; extra == 'all'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
+Requires-Dist: pytest>=7.4.0; extra == 'all'
+Requires-Dist: ruff>=0.1.9; extra == 'all'
+Requires-Dist: streamlit>=1.29.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.25.0; extra == 'all'
+Provides-Extra: api
+Requires-Dist: fastapi>=0.108.0; extra == 'api'
+Requires-Dist: uvicorn[standard]>=0.25.0; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.92.0; extra == 'dev'
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.9; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
+Provides-Extra: streamlit
+Requires-Dist: streamlit>=1.29.0; extra == 'streamlit'
+Description-Content-Type: text/markdown
+
+# Financial Health Calculator
+
+[![PyPI version](https://img.shields.io/pypi/v/fundedness.svg)](https://pypi.org/project/fundedness/)
+[![Python versions](https://img.shields.io/pypi/pyversions/fundedness.svg)](https://pypi.org/project/fundedness/)
+[![CI](https://github.com/engineerinvestor/financial-health-calculator/actions/workflows/ci.yml/badge.svg)](https://github.com/engineerinvestor/financial-health-calculator/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/engineerinvestor/financial-health-calculator/branch/main/graph/badge.svg)](https://codecov.io/gh/engineerinvestor/financial-health-calculator)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://engineerinvestor.github.io/financial-health-calculator/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/engineerinvestor/financial-health-calculator/blob/main/examples/01_cefr_basics.ipynb)
+
+A comprehensive Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful Plotly visualizations.
+
+## Features
+
+- **CEFR (Certainty-Equivalent Funded Ratio)**: A fundedness metric that accounts for taxes, liquidity, and concentration risk
+- **Monte Carlo Simulations**: Project retirement outcomes with configurable market assumptions
+- **Withdrawal Strategy Lab**: Compare strategies including fixed SWR, guardrails, VPW, RMD-style, and Merton optimal
+- **Utility Optimization**: Victor Haghani / Elm Wealth methodology for optimal spending and allocation
+- **Beautiful Visualizations**: Interactive Plotly charts with fan charts, waterfalls, and survival curves
+- **REST API**: FastAPI backend for programmatic access
+- **Streamlit App**: User-friendly web interface
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install fundedness
+```
+
+For development with all extras:
+```bash
+pip install "fundedness[all]"
+```
+
+### Basic Usage
+
+```python
+from fundedness import Asset, BalanceSheet, Liability, compute_cefr
+from fundedness.models.assets import AccountType, LiquidityClass, ConcentrationLevel
+
+# Define your assets
+assets = [
+    Asset(
+        name="401(k)",
+        value=500_000,
+        account_type=AccountType.TAX_DEFERRED,
+        liquidity_class=LiquidityClass.RETIREMENT,
+        concentration_level=ConcentrationLevel.DIVERSIFIED,
+    ),
+    Asset(
+        name="Roth IRA",
+        value=200_000,
+        account_type=AccountType.TAX_EXEMPT,
+        liquidity_class=LiquidityClass.RETIREMENT,
+        concentration_level=ConcentrationLevel.DIVERSIFIED,
+    ),
+]
+
+# Define your spending
+liabilities = [
+    Liability(name="Living Expenses", annual_amount=50_000, is_essential=True),
+    Liability(name="Travel", annual_amount=20_000, is_essential=False),
+]
+
+# Calculate CEFR
+result = compute_cefr(
+    balance_sheet=BalanceSheet(assets=assets),
+    liabilities=liabilities,
+    planning_horizon=30,
+)
+
+print(f"CEFR: {result.cefr:.2f}")
+print(f"Funded: {result.is_funded}")
+print(result.get_interpretation())
+```
+
+## Tutorials
+
+- [CEFR Basics](https://colab.research.google.com/github/engineerinvestor/financial-health-calculator/blob/main/examples/01_cefr_basics.ipynb) - Introduction to the CEFR metric
+- [Time Distribution Analysis](https://colab.research.google.com/github/engineerinvestor/financial-health-calculator/blob/main/examples/02_time_distribution.ipynb) - Monte Carlo simulations
+- [Withdrawal Strategy Comparison](https://colab.research.google.com/github/engineerinvestor/financial-health-calculator/blob/main/examples/03_withdrawal_comparison.ipynb) - Compare different approaches
+
+## Running the Apps
+
+### Streamlit Web App
+
+```bash
+streamlit run streamlit_app/app.py
+```
+
+### FastAPI REST API
+
+```bash
+uvicorn api.main:app --reload
+```
+
+API documentation available at `http://localhost:8000/docs`
+
+## Key Concepts
+
+### CEFR (Certainty-Equivalent Funded Ratio)
+
+CEFR measures how well-funded your retirement is after accounting for:
+
+- **Tax Haircuts**: What you'll owe when withdrawing from different account types
+- **Liquidity Haircuts**: How easily you can access your assets
+- **Reliability Haircuts**: Risk from concentrated positions
+
+**Formula:**
+```
+CEFR = Σ(Asset × (1-τ) × λ × ρ) / PV(Liabilities)
+```
+
+Where τ = tax rate, λ = liquidity factor, ρ = reliability factor
+
+**Interpretation:**
+- CEFR ≥ 2.0: Excellent - Very well-funded
+- CEFR 1.5-2.0: Strong - Well-funded with margin
+- CEFR 1.0-1.5: Adequate - Fully funded
+- CEFR < 1.0: Underfunded - Action needed
+
+### Withdrawal Strategies
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| Fixed SWR | 4% of initial portfolio, adjusted for inflation | Predictability |
+| % of Portfolio | Fixed % of current value | Market adaptation |
+| Guardrails | Adjustable with floor/ceiling | Balance |
+| VPW | Age-based variable percentage | Maximizing spending |
+| RMD-Style | IRS distribution table based | Tax efficiency |
+| Merton Optimal | Utility-maximizing spending rate | Optimality |
+
+### Utility Optimization
+
+The toolkit includes Merton's optimal consumption and portfolio choice framework, as applied in modern retirement planning research<sup>[1]</sup>:
+
+- **Optimal Equity Allocation**: `k* = (μ - r) / (γ × σ²)`
+- **Wealth-Adjusted Allocation**: Reduces equity as wealth approaches subsistence floor
+- **Optimal Spending Rate**: Increases with age as horizon shortens
+- **Expected Lifetime Utility**: Track utility across Monte Carlo paths
+
+Key insights from this methodology:
+1. Optimal spending starts low (~2-3%) and rises with age
+2. Allocation should decrease as wealth approaches the floor
+3. Risk aversion (gamma) is the critical input parameter
+4. The 4% rule is suboptimal from a utility perspective
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/engineerinvestor/financial-health-calculator.git
+cd financial-health-calculator
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+pytest
+```
+
+### Code Quality
+
+```bash
+ruff check .
+mypy fundedness
+```
+
+## Project Structure
+
+```
+financial-health-calculator/
+├── fundedness/           # Core Python package
+│   ├── models/           # Pydantic data models
+│   ├── viz/              # Plotly visualizations
+│   ├── withdrawals/      # Withdrawal strategies (SWR, guardrails, VPW, Merton)
+│   ├── allocation/       # Asset allocation strategies (constant, glidepath, Merton)
+│   ├── cefr.py           # CEFR calculation
+│   ├── simulate.py       # Monte Carlo engine with utility tracking
+│   ├── merton.py         # Merton optimal formulas
+│   ├── optimize.py       # Policy parameter optimization
+│   └── policies.py       # Spending/allocation policies
+├── api/                  # FastAPI REST API
+├── streamlit_app/        # Streamlit web application
+│   └── pages/            # Includes Utility Optimization page
+├── examples/             # Jupyter notebooks
+└── tests/                # pytest tests
+```
+
+## Contact
+
+- Twitter: [@egr_investor](https://x.com/egr_investor)
+- GitHub: [engineerinvestor](https://github.com/engineerinvestor)
+- Email: egr.investor@gmail.com
+
+## License
+
+MIT License
+
+## References
+
+1. Haghani, V., & White, J. (2023). *The Missing Billionaires: A Guide to Better Financial Decisions*. Wiley. See also [Elm Wealth](https://elmwealth.com/) for related research on optimal spending and allocation.
+
+2. Merton, R. C. (1969). Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case. *The Review of Economics and Statistics*, 51(3), 247-257.
+
+## Disclaimer
+
+This tool is for educational purposes only and does not constitute financial advice. Consult a qualified financial advisor for personalized recommendations.