lifecycle-allocation 0.1.0__tar.gz

lifecycle_allocation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Engineer Investor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lifecycle_allocation-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: lifecycle-allocation
+Version: 0.1.0
+Summary: Lifecycle portfolio allocation framework inspired by Choi et al.
+Author-email: Engineer Investor <egr.investor@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/engineerinvestor/lifecycle-allocation
+Project-URL: Repository, https://github.com/engineerinvestor/lifecycle-allocation
+Project-URL: Documentation, https://engineerinvestor.github.io/lifecycle-allocation
+Project-URL: Issues, https://github.com/engineerinvestor/lifecycle-allocation/issues
+Project-URL: Changelog, https://github.com/engineerinvestor/lifecycle-allocation/blob/main/CHANGELOG.md
+Keywords: finance,portfolio,allocation,lifecycle,human-capital,investment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Financial and Insurance Industry
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Requires-Dist: pandas-stubs>=2.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Dynamic: license-file
+
+# lifecycle-allocation
+
+A Python library implementing a practical lifecycle portfolio choice framework inspired by [Choi et al.](https://www.nber.org/papers/w34166) It combines human capital analysis with visual analytics to produce data-driven stock/bond allocation recommendations.
+
+[![CI](https://github.com/engineerinvestor/lifecycle-allocation/actions/workflows/ci.yml/badge.svg)](https://github.com/engineerinvestor/lifecycle-allocation/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/lifecycle-allocation)](https://pypi.org/project/lifecycle-allocation/)
+[![Python](https://img.shields.io/pypi/pyversions/lifecycle-allocation)](https://pypi.org/project/lifecycle-allocation/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://engineerinvestor.github.io/lifecycle-allocation)
+
+## Why This Matters
+
+Most portfolio allocation "rules" are single-variable heuristics: 60/40, 100-minus-age, target-date funds. They ignore the biggest asset most people own -- their future earning power. A 30-year-old software engineer with $100k in savings and 35 years of income ahead is in a fundamentally different position than a 30-year-old retiree with the same $100k.
+
+This library takes a **balance-sheet** view of your finances. Your investable portfolio is only part of your total wealth. Future earnings (human capital) act like a bond-like asset, and accounting for them changes how much stock risk you should take. The result is a theoretically grounded, personalized allocation that evolves naturally over your lifecycle -- no arbitrary rules required.
+
+## Features
+
+- **Core allocation engine** -- Merton-style optimal risky share adjusted for human capital
+- **4 income models** -- flat, constant-growth, age-profile, and CSV-based
+- **Strategy comparison** -- benchmark against 60/40, 100-minus-age, and target-date funds
+- **Visualization suite** -- balance sheet waterfall, glide paths, sensitivity tornado, heatmaps
+- **CLI interface** -- generate full reports from YAML/JSON profiles
+- **YAML/JSON profiles** -- declarative investor configuration
+- **Leverage support** -- two-tier borrowing rate model with configurable constraints
+- **Mortality adjustment** -- survival probability discounting for human capital
+
+## Install
+
+```bash
+pip install lifecycle-allocation
+```
+
+For development:
+
+```bash
+git clone https://github.com/engineerinvestor/lifecycle-allocation.git
+cd lifecycle-allocation
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+.
+
+## Quick Start (Python)
+
+```python
+from lifecycle_allocation import (
+    InvestorProfile,
+    MarketAssumptions,
+    recommended_stock_share,
+    compare_strategies,
+)
+
+profile = InvestorProfile(
+    age=30,
+    retirement_age=67,
+    investable_wealth=100_000,
+    after_tax_income=70_000,
+    risk_tolerance=5,
+)
+market = MarketAssumptions(mu=0.05, r=0.02, sigma=0.18)
+
+result = recommended_stock_share(profile, market)
+print(f"Recommended stock allocation: {result.alpha_recommended:.1%}")
+print(f"Human capital: ${result.human_capital:,.0f}")
+print(result.explain)
+
+# Compare against heuristic strategies
+df = compare_strategies(profile, market)
+print(df.to_string(index=False))
+```
+
+## Quick Start (CLI)
+
+```bash
+lifecycle-allocation alloc \
+    --profile examples/profiles/young_saver.yaml \
+    --out ./output \
+    --report
+```
+
+This produces `allocation.json`, `summary.md`, and charts in `output/charts/`.
+
+## How It Works
+
+1. Compute a **baseline risky share** (Merton-style): `alpha* = (mu - r) / (gamma * sigma^2)`
+2. Estimate **human capital** H as the present value of future earnings + retirement benefits, discounted by survival probability and a term structure
+3. Adjust: `alpha = alpha* x (1 + H/W)`, clamped to [0, 1] (or [0, L_max] with leverage)
+
+Young workers with high H/W ratios get higher equity allocations. As you age and accumulate financial wealth, H shrinks relative to W and the allocation naturally declines -- producing a lifecycle glide path from first principles rather than arbitrary rules.
+
+## Example Output
+
+| Archetype | Age | Income | Wealth | H/W Ratio | Recommended Equity |
+|---|---|---|---|---|---|
+| Young saver | 30 | $70k | $100k | ~15x | ~90%+ |
+| Mid-career | 45 | $120k | $500k | ~4x | ~65% |
+| Near-retirement | 60 | $90k | $1.2M | ~0.5x | ~40% |
+
+*Values depend on market assumptions and risk tolerance. These are illustrative.*
+
+## Tutorial
+
+Explore the interactive tutorial notebook for a guided walkthrough:
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/engineerinvestor/lifecycle-allocation/blob/main/examples/notebooks/tutorial.ipynb)
+
+Or run locally:
+
+```bash
+jupyter notebook examples/notebooks/tutorial.ipynb
+```
+
+## Documentation
+
+Full documentation is available at [engineerinvestor.github.io/lifecycle-allocation](https://engineerinvestor.github.io/lifecycle-allocation).
+
+## Roadmap
+
+| Version | Milestone |
+|---|---|
+| **v0.1** | Core allocation engine, CLI, YAML profiles, strategy comparison, charts |
+| **v0.5** | Monte Carlo simulation, CRRA utility evaluation, Social Security modeling |
+| **v1.0** | Full documentation, tax-aware optimization, couples modeling |
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.
+
+## Citation
+
+If you use this library in academic work, please cite both the underlying research and the software:
+
+```bibtex
+@techreport{choi2025practical,
+  title={Practical Finance: An Approximate Solution to Lifecycle Portfolio Choice},
+  author={Choi, James J. and Liu, Canyao and Liu, Pengcheng},
+  year={2025},
+  institution={National Bureau of Economic Research},
+  type={Working Paper},
+  number={34166},
+  doi={10.3386/w34166},
+  url={https://www.nber.org/papers/w34166}
+}
+
+@software{engineerinvestor2025lifecycle,
+  title={lifecycle-allocation: A Lifecycle Portfolio Choice Framework},
+  author={{Engineer Investor}},
+  year={2025},
+  url={https://github.com/engineerinvestor/lifecycle-allocation},
+  version={0.1.0},
+  license={MIT}
+}
+```
+
+## Disclaimer
+
+**This library is for education and research purposes only. It is not investment advice.** The authors are not financial advisors. Consult a qualified professional before making investment decisions. Past performance and model outputs do not guarantee future results.
+
+## License
+
+[MIT](LICENSE)

lifecycle_allocation-0.1.0/README.md

@@ -0,0 +1,162 @@
+# lifecycle-allocation
+
+A Python library implementing a practical lifecycle portfolio choice framework inspired by [Choi et al.](https://www.nber.org/papers/w34166) It combines human capital analysis with visual analytics to produce data-driven stock/bond allocation recommendations.
+
+[![CI](https://github.com/engineerinvestor/lifecycle-allocation/actions/workflows/ci.yml/badge.svg)](https://github.com/engineerinvestor/lifecycle-allocation/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/lifecycle-allocation)](https://pypi.org/project/lifecycle-allocation/)
+[![Python](https://img.shields.io/pypi/pyversions/lifecycle-allocation)](https://pypi.org/project/lifecycle-allocation/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://engineerinvestor.github.io/lifecycle-allocation)
+
+## Why This Matters
+
+Most portfolio allocation "rules" are single-variable heuristics: 60/40, 100-minus-age, target-date funds. They ignore the biggest asset most people own -- their future earning power. A 30-year-old software engineer with $100k in savings and 35 years of income ahead is in a fundamentally different position than a 30-year-old retiree with the same $100k.
+
+This library takes a **balance-sheet** view of your finances. Your investable portfolio is only part of your total wealth. Future earnings (human capital) act like a bond-like asset, and accounting for them changes how much stock risk you should take. The result is a theoretically grounded, personalized allocation that evolves naturally over your lifecycle -- no arbitrary rules required.
+
+## Features
+
+- **Core allocation engine** -- Merton-style optimal risky share adjusted for human capital
+- **4 income models** -- flat, constant-growth, age-profile, and CSV-based
+- **Strategy comparison** -- benchmark against 60/40, 100-minus-age, and target-date funds
+- **Visualization suite** -- balance sheet waterfall, glide paths, sensitivity tornado, heatmaps
+- **CLI interface** -- generate full reports from YAML/JSON profiles
+- **YAML/JSON profiles** -- declarative investor configuration
+- **Leverage support** -- two-tier borrowing rate model with configurable constraints
+- **Mortality adjustment** -- survival probability discounting for human capital
+
+## Install
+
+```bash
+pip install lifecycle-allocation
+```
+
+For development:
+
+```bash
+git clone https://github.com/engineerinvestor/lifecycle-allocation.git
+cd lifecycle-allocation
+pip install -e ".[dev]"
+```
+
+Requires Python 3.10+.
+
+## Quick Start (Python)
+
+```python
+from lifecycle_allocation import (
+    InvestorProfile,
+    MarketAssumptions,
+    recommended_stock_share,
+    compare_strategies,
+)
+
+profile = InvestorProfile(
+    age=30,
+    retirement_age=67,
+    investable_wealth=100_000,
+    after_tax_income=70_000,
+    risk_tolerance=5,
+)
+market = MarketAssumptions(mu=0.05, r=0.02, sigma=0.18)
+
+result = recommended_stock_share(profile, market)
+print(f"Recommended stock allocation: {result.alpha_recommended:.1%}")
+print(f"Human capital: ${result.human_capital:,.0f}")
+print(result.explain)
+
+# Compare against heuristic strategies
+df = compare_strategies(profile, market)
+print(df.to_string(index=False))
+```
+
+## Quick Start (CLI)
+
+```bash
+lifecycle-allocation alloc \
+    --profile examples/profiles/young_saver.yaml \
+    --out ./output \
+    --report
+```
+
+This produces `allocation.json`, `summary.md`, and charts in `output/charts/`.
+
+## How It Works
+
+1. Compute a **baseline risky share** (Merton-style): `alpha* = (mu - r) / (gamma * sigma^2)`
+2. Estimate **human capital** H as the present value of future earnings + retirement benefits, discounted by survival probability and a term structure
+3. Adjust: `alpha = alpha* x (1 + H/W)`, clamped to [0, 1] (or [0, L_max] with leverage)
+
+Young workers with high H/W ratios get higher equity allocations. As you age and accumulate financial wealth, H shrinks relative to W and the allocation naturally declines -- producing a lifecycle glide path from first principles rather than arbitrary rules.
+
+## Example Output
+
+| Archetype | Age | Income | Wealth | H/W Ratio | Recommended Equity |
+|---|---|---|---|---|---|
+| Young saver | 30 | $70k | $100k | ~15x | ~90%+ |
+| Mid-career | 45 | $120k | $500k | ~4x | ~65% |
+| Near-retirement | 60 | $90k | $1.2M | ~0.5x | ~40% |
+
+*Values depend on market assumptions and risk tolerance. These are illustrative.*
+
+## Tutorial
+
+Explore the interactive tutorial notebook for a guided walkthrough:
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/engineerinvestor/lifecycle-allocation/blob/main/examples/notebooks/tutorial.ipynb)
+
+Or run locally:
+
+```bash
+jupyter notebook examples/notebooks/tutorial.ipynb
+```
+
+## Documentation
+
+Full documentation is available at [engineerinvestor.github.io/lifecycle-allocation](https://engineerinvestor.github.io/lifecycle-allocation).
+
+## Roadmap
+
+| Version | Milestone |
+|---|---|
+| **v0.1** | Core allocation engine, CLI, YAML profiles, strategy comparison, charts |
+| **v0.5** | Monte Carlo simulation, CRRA utility evaluation, Social Security modeling |
+| **v1.0** | Full documentation, tax-aware optimization, couples modeling |
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.
+
+## Citation
+
+If you use this library in academic work, please cite both the underlying research and the software:
+
+```bibtex
+@techreport{choi2025practical,
+  title={Practical Finance: An Approximate Solution to Lifecycle Portfolio Choice},
+  author={Choi, James J. and Liu, Canyao and Liu, Pengcheng},
+  year={2025},
+  institution={National Bureau of Economic Research},
+  type={Working Paper},
+  number={34166},
+  doi={10.3386/w34166},
+  url={https://www.nber.org/papers/w34166}
+}
+
+@software{engineerinvestor2025lifecycle,
+  title={lifecycle-allocation: A Lifecycle Portfolio Choice Framework},
+  author={{Engineer Investor}},
+  year={2025},
+  url={https://github.com/engineerinvestor/lifecycle-allocation},
+  version={0.1.0},
+  license={MIT}
+}
+```
+
+## Disclaimer
+
+**This library is for education and research purposes only. It is not investment advice.** The authors are not financial advisors. Consult a qualified professional before making investment decisions. Past performance and model outputs do not guarantee future results.
+
+## License
+
+[MIT](LICENSE)

lifecycle_allocation-0.1.0/lifecycle_allocation/__init__.py

@@ -0,0 +1,34 @@
+"""Lifecycle portfolio allocation framework inspired by Choi et al."""
+
+__version__ = "0.1.0"
+
+from lifecycle_allocation.core.allocation import alpha_star, recommended_stock_share
+from lifecycle_allocation.core.human_capital import human_capital_pv
+from lifecycle_allocation.core.models import (
+    AllocationResult,
+    BenefitModelSpec,
+    ConstraintsSpec,
+    DiscountCurveSpec,
+    IncomeModelSpec,
+    InvestorProfile,
+    MarketAssumptions,
+    MortalitySpec,
+    risk_tolerance_to_gamma,
+)
+from lifecycle_allocation.core.strategies import compare_strategies
+
+__all__ = [
+    "AllocationResult",
+    "BenefitModelSpec",
+    "ConstraintsSpec",
+    "DiscountCurveSpec",
+    "IncomeModelSpec",
+    "InvestorProfile",
+    "MarketAssumptions",
+    "MortalitySpec",
+    "alpha_star",
+    "compare_strategies",
+    "human_capital_pv",
+    "recommended_stock_share",
+    "risk_tolerance_to_gamma",
+]

lifecycle_allocation-0.1.0/lifecycle_allocation/cli/main.py

@@ -0,0 +1,141 @@
+"""CLI entry point for lifecycle-allocation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from lifecycle_allocation.core.allocation import recommended_stock_share
+from lifecycle_allocation.core.models import ConstraintsSpec, MarketAssumptions
+from lifecycle_allocation.core.strategies import compare_strategies
+from lifecycle_allocation.io.loaders import load_profile
+from lifecycle_allocation.viz.charts import plot_balance_sheet, plot_strategy_bars
+
+
+@click.group()
+def cli() -> None:
+    """lifecycle-allocation: Lifecycle portfolio allocation framework."""
+
+
+@cli.command()
+@click.option("--profile", "profile_path", required=True, type=click.Path(exists=True))
+@click.option("--out", "out_dir", required=True, type=click.Path())
+@click.option("--report", is_flag=True, default=False, help="Generate charts")
+@click.option("--mu", type=float, default=None, help="Expected stock return")
+@click.option("--r", "risk_free", type=float, default=None, help="Risk-free rate")
+@click.option("--sigma", type=float, default=None, help="Stock volatility")
+@click.option("--tmax", type=int, default=100, help="Maximum age for computation")
+@click.option("--allow-leverage", is_flag=True, default=False)
+@click.option("--max-leverage", type=float, default=1.0)
+@click.option("--borrowing-spread", type=float, default=None)
+@click.option("--format", "img_format", type=click.Choice(["png", "svg"]), default="png")
+@click.option("--real/--nominal", default=True)
+def alloc(
+    profile_path: str,
+    out_dir: str,
+    report: bool,
+    mu: float | None,
+    risk_free: float | None,
+    sigma: float | None,
+    tmax: int,
+    allow_leverage: bool,
+    max_leverage: float,
+    borrowing_spread: float | None,
+    img_format: str,
+    real: bool,
+) -> None:
+    """Compute lifecycle allocation from a profile."""
+    profile, market, curve, constraints = load_profile(profile_path)
+
+    # CLI overrides
+    if mu is not None:
+        market = MarketAssumptions(
+            mu=mu,
+            r=market.r,
+            sigma=market.sigma,
+            real=market.real,
+            borrowing_spread=market.borrowing_spread,
+        )
+    if risk_free is not None:
+        market = MarketAssumptions(
+            mu=market.mu,
+            r=risk_free,
+            sigma=market.sigma,
+            real=market.real,
+            borrowing_spread=market.borrowing_spread,
+        )
+    if sigma is not None:
+        market = MarketAssumptions(
+            mu=market.mu,
+            r=market.r,
+            sigma=sigma,
+            real=market.real,
+            borrowing_spread=market.borrowing_spread,
+        )
+    if borrowing_spread is not None:
+        market = MarketAssumptions(
+            mu=market.mu,
+            r=market.r,
+            sigma=market.sigma,
+            real=market.real,
+            borrowing_spread=borrowing_spread,
+        )
+    market = MarketAssumptions(
+        mu=market.mu,
+        r=market.r,
+        sigma=market.sigma,
+        real=real,
+        borrowing_spread=market.borrowing_spread,
+    )
+
+    if allow_leverage or constraints.allow_leverage:
+        constraints = ConstraintsSpec(
+            allow_leverage=True,
+            max_leverage=max_leverage if max_leverage > 1.0 else constraints.max_leverage,
+            allow_short=constraints.allow_short,
+            min_allocation=constraints.min_allocation,
+        )
+
+    # Compute
+    result = recommended_stock_share(profile, market, curve, constraints, t_max=tmax)
+    comparison_df = compare_strategies(profile, market, curve, constraints)
+
+    # Create output directory
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    # Write allocation.json
+    alloc_data = {
+        "alpha_star": result.alpha_star,
+        "alpha_unconstrained": result.alpha_unconstrained,
+        "alpha_recommended": result.alpha_recommended,
+        "human_capital": result.human_capital,
+        "leverage_applied": result.leverage_applied,
+        "borrowing_cost_drag": result.borrowing_cost_drag,
+        "components": {
+            k: v for k, v in result.components.items() if isinstance(v, (int, float, bool, str))
+        },
+    }
+    with open(out / "allocation.json", "w") as f:
+        json.dump(alloc_data, f, indent=2)
+
+    # Write summary.md
+    with open(out / "summary.md", "w") as f:
+        f.write("# Lifecycle Allocation Summary\n\n")
+        f.write(result.explain)
+        f.write("\n\n## Strategy Comparison\n\n")
+        f.write("| Strategy | Allocation |\n|---|---|\n")
+        for _, row in comparison_df.iterrows():
+            f.write(f"| {row['strategy']} | {row['allocation']:.1%} |\n")
+
+    click.echo(f"Recommended stock allocation: {result.alpha_recommended:.1%}")
+    click.echo(f"Results written to {out}")
+
+    if report:
+        charts_dir = out / "charts"
+        charts_dir.mkdir(exist_ok=True)
+        plot_balance_sheet(result, profile, save_path=charts_dir / f"balance_sheet.{img_format}")
+        plot_strategy_bars(comparison_df, save_path=charts_dir / f"strategy_bars.{img_format}")
+        click.echo(f"Charts written to {charts_dir}")