fundedness 0.2.4__py3-none-any.whl

fundedness-0.2.4.dist-info/METADATA

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: fundedness
+Version: 0.2.4
+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/)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://engineerinvestor.github.io/financial-health-calculator/)
+[![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://financial-health-calculator.streamlit.app/)
+[![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**: 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
+
+## 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.
+
+## 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.4.dist-info/RECORD

@@ -0,0 +1,43 @@
+fundedness/__init__.py,sha256=5rATL7-dfOIzb43-c3oDYImGu70ezYv2ALfbadhyR20,1678
+fundedness/cefr.py,sha256=hCImRrjz-DCPJsuF3HShDZK5tw1vslakh-DrNBHsh2k,7728
+fundedness/liabilities.py,sha256=uKvEV6JQnQdrd7b6VsCc2qf9S2DJdK0XhEX9qwca2Ws,6662
+fundedness/liquidity.py,sha256=ncZF70AfgoVoYZnozpA_CHemfaHmI4KKCe3vITp5ljM,1713
+fundedness/merton.py,sha256=VUKVxkNimoI0gsQJROb1wrO-SW4ubiNvcYDL2aH69AU,9218
+fundedness/optimize.py,sha256=21ksSkNgtDY_UGTub0KRlIvfaFA363csfSfHnLJrmJs,15567
+fundedness/policies.py,sha256=pyIYz86Z3sMYAW2rNhPLnXQ3PQCDCa-oxf9NhWyawy8,5854
+fundedness/risk.py,sha256=Lpls6Q2wVq5SX4p9ZQwCtTM73AcqrGCm3hE2QcgKuq0,2750
+fundedness/simulate.py,sha256=1undHqkhVGWHK_pXS5KvqlRCpUmBEXQZ7-ujvrEsJkI,21448
+fundedness/allocation/__init__.py,sha256=5p85uRFltSfEwXjengr56FNY1s4KvcMMxuH05I_Omfs,677
+fundedness/allocation/base.py,sha256=kDypu2t86fsn2DyL5an1fPjbPbQWNmqydz3axWUgjLI,763
+fundedness/allocation/constant.py,sha256=6QcUJ0aBQcJcRJtOMhs7uUu13wJtgcPU7ToQzQZhcgw,531
+fundedness/allocation/glidepath.py,sha256=-q6Jb5WpRuZjJ68akT5WgeRIx3QSIDtlNih0_Iz-_cc,3440
+fundedness/allocation/merton_optimal.py,sha256=krRd7sKbvXXxfewLJuF9RWbMLYUHbehvdbdYSjwnczk,7702
+fundedness/models/__init__.py,sha256=EyW6tGUI9T6QMbIfzsG3igqg5--DtZHSTAuMX6foOiA,874
+fundedness/models/assets.py,sha256=ZKgxl4YaqdRVfDErL9weRhh4St_azo8ruN4g15T3IsQ,5013
+fundedness/models/household.py,sha256=t64FjvO0uQJemddLtCPpK3NNYdZCXU6KjA1VZshaqEk,4671
+fundedness/models/liabilities.py,sha256=iqGl5RU841k1clGOwnFParUvxzCJclq2JzNJoNPywuo,3416
+fundedness/models/market.py,sha256=JAUt-MM__yM_v-FsgKwJj7rXC0yh6oFUv5JLoob58OE,6388
+fundedness/models/simulation.py,sha256=0jtIJWISDL-TlKVjr6KxcRfAj5Mrbp-VNyA4Bu7IUfU,2224
+fundedness/models/tax.py,sha256=0XhoBNZqfRqF1_acakrkYgMS5L6Pknq-TloQQBrFw1U,3859
+fundedness/models/utility.py,sha256=0AoJdccTb2hKBrTz5LExm8SrSsaWhhBf7y2NNaUzWQ0,4678
+fundedness/viz/__init__.py,sha256=Om8qlI13w13MfDmyB_xeR6hgr7LpWX1tjAf_x3eDbEQ,1168
+fundedness/viz/colors.py,sha256=kbYyCLvLARoIAMztHjnJZDxMGF9-an5z4obORa6JFEU,3204
+fundedness/viz/comparison.py,sha256=DoQW6xr0r2ko55qyli4ue8ndj__opun97brbbHSnKVA,8530
+fundedness/viz/fan_chart.py,sha256=GqdrOKdW12K7Y8sFQJ853QbYG3ASxvEzfY9cC-EKK70,6102
+fundedness/viz/histogram.py,sha256=i56g330-S84WxUU8GGya40yNUQbnAI2D0vzUbFy51DI,6784
+fundedness/viz/optimal.py,sha256=w5vI2O-4O6F1Dobsfg55pznlfD100SRnSgZqLIpcT9c,16056
+fundedness/viz/survival.py,sha256=xtaAHkJ3jlTUCYnLrTvwWlOlfLao6NC5cRxT5XKWrxM,6515
+fundedness/viz/tornado.py,sha256=1dZzAfKTDCcyyfbDUBE39f44e6k48yviF8kTRee-pwQ,6684
+fundedness/viz/waterfall.py,sha256=6LD0SbZDUzJrA0Zh1Y1qDx0I4BM5ZN_f2eVCXNK5HRc,5586
+fundedness/withdrawals/__init__.py,sha256=FiXfK7QBzUp4Iwf25VK0jbZyguF8bLlZAWWMjg8tFPo,886
+fundedness/withdrawals/base.py,sha256=WXBuo-tJtp4V2Ottp2PC2YtyK3mGVJ9Cgq21zGUWObg,3472
+fundedness/withdrawals/comparison.py,sha256=eiobGMHmeQpGnr0_HcY_EKrv5_Nu7EaVf5Y9DdDNAyg,7833
+fundedness/withdrawals/fixed_swr.py,sha256=2ZgkQ_xZakpcdZQIop46TAFML7ESz7nyTVdVfI-1Z18,5469
+fundedness/withdrawals/guardrails.py,sha256=rZKVojKbl9LLJLi9LlK1I2JXb537MN_AbZfn4hIU8is,5468
+fundedness/withdrawals/merton_optimal.py,sha256=mSxRAKGx8sr_YdlhQMtIvnojqfuG0MiYtBp18xboLHs,9269
+fundedness/withdrawals/rmd_style.py,sha256=E5FfrUYxFJwULKxzxbtZFLoLspLzUUomTQRUWLGLDpg,6373
+fundedness/withdrawals/vpw.py,sha256=aajHLAkHfsxh33uGRgzv0ozVuZREG-EmARJgWOU6mis,4389
+fundedness-0.2.4.dist-info/METADATA,sha256=fEFxniSnE2ymvEo4rIS_q5im2NWZoNQmtd8Bic2vxqA,11017
+fundedness-0.2.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fundedness-0.2.4.dist-info/entry_points.txt,sha256=Oh-Hg08i044YHuSHViCdfoD8CenIGcKrVuUVysvN9sY,51
+fundedness-0.2.4.dist-info/RECORD,,

fundedness-0.2.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fundedness-0.2.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fundedness = fundedness.cli:main