fundedness 0.2.0__tar.gz → 0.2.2__tar.gz

fundedness-0.2.2/CLAUDE.md

@@ -0,0 +1,169 @@
+# 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
+- **Merton Optimal Policies**: Spending and asset allocation policies that maximize expected lifetime utility
+- **Withdrawal Strategy Lab**: Comparison framework for withdrawal strategies (fixed SWR, guardrails, VPW, RMD-style, Merton optimal)
+
+The project includes both a Python package (`fundedness/`) and a Streamlit web application (`streamlit_app/`).
+
+## Development Status
+
+This project is **actively developed** and published on PyPI as `fundedness`.
+
+Current version: **0.2.x**
+
+## Commands
+
+- **Install**: `pip install fundedness` or `pip install "fundedness[all]"` for all extras
+- **Testing**: `pytest` (runs 99+ tests)
+- **Docs**: `mkdocs serve` (local) or auto-deployed to GitHub Pages
+- **Streamlit**: `streamlit run streamlit_app/app.py`
+- **API**: `uvicorn api.main:app --reload`
+
+## Architecture
+
+### Core Package Structure (`fundedness/`)
+
+```
+fundedness/
+├── __init__.py          # Package exports
+├── cefr.py              # CEFR ratio calculation with haircut breakdowns
+├── liabilities.py       # Liability PV calculations with schedules
+├── liquidity.py         # Liquidity factor adjustments
+├── risk.py              # Reliability/concentration haircuts
+├── simulate.py          # Monte Carlo engine with utility tracking
+├── merton.py            # Merton optimal formulas (allocation, spending, CE return)
+├── optimize.py          # Parametric policy optimization
+├── policies.py          # Spending/allocation policy interface
+├── models/              # Pydantic data models
+│   ├── assets.py
+│   ├── household.py
+│   ├── liabilities.py
+│   ├── market.py
+│   ├── simulation.py
+│   ├── tax.py
+│   └── utility.py
+├── withdrawals/         # Withdrawal strategy implementations
+│   ├── base.py
+│   ├── fixed_swr.py
+│   ├── guardrails.py
+│   ├── vpw.py
+│   ├── rmd_style.py
+│   ├── merton_optimal.py
+│   └── comparison.py
+├── allocation/          # Asset allocation strategies
+│   ├── base.py
+│   ├── constant.py
+│   ├── glidepath.py
+│   └── merton_optimal.py
+└── viz/                 # Plotly visualizations
+    ├── colors.py
+    ├── fan_chart.py
+    ├── waterfall.py
+    ├── survival.py
+    ├── comparison.py
+    ├── optimal.py
+    └── ...
+```
+
+### 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)
+```
+
+**Merton Optimal Allocation:**
+```
+k* = (μ - r) / (γ × σ²)
+```
+
+**Merton Optimal Spending Rate:**
+```
+c* = rce - (rce - ρ) / γ
+```
+
+**CRRA Utility with Floor:**
+```
+u(C) = (C - F)^(1-γ) / (1-γ)  where C > F (subsistence floor)
+```
+
+## 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
+- **Utility optimization**: Merton framework for optimal spending and allocation
+
+## 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
+
+- **PyPI**: Published as `fundedness` - releases triggered by GitHub Release
+- **Docs**: MkDocs Material deployed to GitHub Pages via `docs.yml` workflow
+- **Web App**: Streamlit Cloud (free tier)
+- **API**: FastAPI with endpoints in `api/`
+
+## 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
+
+## Documentation Notes
+
+### LaTeX Equations in MkDocs
+
+**Issue**: LaTeX equations using `$$...$$` syntax don't render in MkDocs Material.
+
+**Solution**: Use `pymdownx.arithmatex` extension with MathJax:
+
+1. In `mkdocs.yml`:
+```yaml
+markdown_extensions:
+  - pymdownx.arithmatex:
+      generic: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
+```
+
+2. Create `docs/javascripts/mathjax.js`:
+```javascript
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+```
+
+3. Use `\[...\]` for display math and `\(...\)` for inline math in markdown files.
+
+## References
+
+- Merton, R.C. (1969). Lifetime Portfolio Selection under Uncertainty. *The Review of Economics and Statistics*, 51(3), 247-257.
+- Haghani, V. & White, J. (2023). *The Missing Billionaires: A Guide to Better Financial Decisions*. Wiley.

{fundedness-0.2.0 → fundedness-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fundedness
-Version: 0.2.0
+Version: 0.2.2
 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/
@@ -56,8 +56,6 @@ Description-Content-Type: text/markdown
 
 [![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)
@@ -69,7 +67,7 @@ A comprehensive Python financial planning toolkit with CEFR calculations, Monte
 - **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
+- **Utility Optimization**: Merton optimal spending and allocation based on lifetime utility maximization
 - **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
@@ -260,6 +258,42 @@ MIT License
 
 2. Merton, R. C. (1969). Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case. *The Review of Economics and Statistics*, 51(3), 247-257.
 
+## Citation
+
+If you use this package in academic work, please cite:
+
+```bibtex
+@software{fundedness,
+  title = {Fundedness: A Python Financial Planning Toolkit},
+  author = {Engineer Investor},
+  year = {2024},
+  url = {https://github.com/engineerinvestor/financial-health-calculator},
+  version = {0.2.1}
+}
+```
+
+For the underlying methodology, please also cite:
+
+```bibtex
+@article{merton1969lifetime,
+  title = {Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case},
+  author = {Merton, Robert C.},
+  journal = {The Review of Economics and Statistics},
+  volume = {51},
+  number = {3},
+  pages = {247--257},
+  year = {1969},
+  publisher = {MIT Press}
+}
+
+@book{haghani2023missing,
+  title = {The Missing Billionaires: A Guide to Better Financial Decisions},
+  author = {Haghani, Victor and White, James},
+  year = {2023},
+  publisher = {Wiley}
+}
+```
+
 ## Disclaimer
 
 This tool is for educational purposes only and does not constitute financial advice. Consult a qualified financial advisor for personalized recommendations.

{fundedness-0.2.0 → fundedness-0.2.2}/README.md

@@ -2,8 +2,6 @@
 
 [![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)
@@ -15,7 +13,7 @@ A comprehensive Python financial planning toolkit with CEFR calculations, Monte
 - **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
+- **Utility Optimization**: Merton optimal spending and allocation based on lifetime utility maximization
 - **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
@@ -206,6 +204,42 @@ MIT License
 
 2. Merton, R. C. (1969). Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case. *The Review of Economics and Statistics*, 51(3), 247-257.
 
+## Citation
+
+If you use this package in academic work, please cite:
+
+```bibtex
+@software{fundedness,
+  title = {Fundedness: A Python Financial Planning Toolkit},
+  author = {Engineer Investor},
+  year = {2024},
+  url = {https://github.com/engineerinvestor/financial-health-calculator},
+  version = {0.2.1}
+}
+```
+
+For the underlying methodology, please also cite:
+
+```bibtex
+@article{merton1969lifetime,
+  title = {Lifetime Portfolio Selection under Uncertainty: The Continuous-Time Case},
+  author = {Merton, Robert C.},
+  journal = {The Review of Economics and Statistics},
+  volume = {51},
+  number = {3},
+  pages = {247--257},
+  year = {1969},
+  publisher = {MIT Press}
+}
+
+@book{haghani2023missing,
+  title = {The Missing Billionaires: A Guide to Better Financial Decisions},
+  author = {Haghani, Victor and White, James},
+  year = {2023},
+  publisher = {Wiley}
+}
+```
+
 ## Disclaimer
 
 This tool is for educational purposes only and does not constitute financial advice. Consult a qualified financial advisor for personalized recommendations.

{fundedness-0.2.0 → fundedness-0.2.2}/docs/guide/utility-optimization.md

@@ -18,28 +18,34 @@ Utility optimization provides a rigorous framework for finding the **optimal** s
 
 The Merton formula gives the optimal fraction to invest in risky assets:
 
-$$k^* = \frac{\mu - r}{\gamma \times \sigma^2}$$
+\[
+k^* = \frac{\mu - r}{\gamma \cdot \sigma^2}
+\]
 
 Where:
 
-- $\mu$ = expected stock return
-- $r$ = bond/risk-free return
-- $\gamma$ = risk aversion coefficient
-- $\sigma$ = stock volatility
+- \(\mu\) = expected stock return
+- \(r\) = bond/risk-free return
+- \(\gamma\) = risk aversion coefficient
+- \(\sigma\) = stock volatility
 
 ### Certainty Equivalent Return
 
 The guaranteed return that provides the same utility as the risky portfolio:
 
-$$r_{CE} = r + k^*(\mu - r) - \frac{\gamma \times k^{*2} \times \sigma^2}{2}$$
+\[
+r_{CE} = r + k^*(\mu - r) - \frac{\gamma \cdot (k^*)^2 \cdot \sigma^2}{2}
+\]
 
 ### Optimal Spending Rate
 
 For an infinite horizon:
 
-$$c^* = r_{CE} - \frac{r_{CE} - \rho}{\gamma}$$
+\[
+c^* = r_{CE} - \frac{r_{CE} - \rho}{\gamma}
+\]
 
-Where $\rho$ is your time preference (discount rate).
+Where \(\rho\) is your time preference (discount rate).
 
 ## Quick Start
 
@@ -82,9 +88,11 @@ print(f"Year 1 spending: ${1_000_000 * result.optimal_spending_rate:,.0f}")
 
 Near the subsistence floor, you can't afford to take risk. The wealth-adjusted allocation accounts for this:
 
-$$k_{adj} = k^* \times \frac{W - F}{W}$$
+\[
+k_{adj} = k^* \cdot \frac{W - F}{W}
+\]
 
-Where $W$ is wealth and $F$ is the subsistence floor.
+Where \(W\) is wealth and \(F\) is the subsistence floor.
 
 As wealth approaches the floor, allocation approaches zero. As wealth rises far above the floor, allocation approaches the unconstrained optimal.
 

fundedness-0.2.2/docs/javascripts/mathjax.js

@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache()
+  MathJax.typesetClear()
+  MathJax.texReset()
+  MathJax.typesetPromise()
+})

{fundedness-0.2.0 → fundedness-0.2.2}/fundedness/__init__.py

@@ -8,7 +8,7 @@ This package provides tools for:
 - Beautiful Plotly visualizations
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 from fundedness.cefr import CEFRResult, compute_cefr
 from fundedness.merton import (

{fundedness-0.2.0 → fundedness-0.2.2}/mkdocs.yml

@@ -46,6 +46,12 @@ nav:
 markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
+  - pymdownx.arithmatex:
+      generic: true
   - admonition
   - toc:
       permalink: true
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js

{fundedness-0.2.0 → fundedness-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fundedness"
-version = "0.2.0"
+version = "0.2.2"
 description = "A Python financial planning toolkit with CEFR calculations, Monte Carlo simulations, and beautiful visualizations"
 readme = "README.md"
 license = "MIT"

{fundedness-0.2.0 → fundedness-0.2.2}/streamlit_app/pages/5_Utility_Optimization.py

@@ -1,4 +1,4 @@
-"""Utility Optimization page - Victor Haghani / Elm Wealth methodology."""
+"""Utility Optimization page - Merton optimal spending and allocation."""
 
 import numpy as np
 import streamlit as st

fundedness-0.2.0/CLAUDE.md

@@ -1,98 +0,0 @@
-# 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