Metadata-Version: 2.4
Name: life-model
Version: 0.3.2
Summary: Modeling life events and how they impact finances
Author-email: Spencer Williams <sw23@users.noreply.github.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sw23/life-model
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: mesa>=3.3
Requires-Dist: networkx
Requires-Dist: pyyaml
Requires-Dist: pydantic>=2
Requires-Dist: jinja2
Provides-Extra: docs
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# life-model (beta)
Python package for performing time step-based simulations of personal finances. Note that this package is still early in development and likely contains bugs. Use at your own risk!

## Overview
The package provides comprehensive models of people, jobs, accounts, insurance, debt, and more within a time step-based simulation framework. Built on the [Mesa](https://github.com/projectmesa/mesa) agent-based modeling framework, it includes an interactive dashboard, an example Jupyter Notebook, deep reinforcement learning capabilities for AI-driven financial planning, and can be used programmatically for in-depth financial studies.

## Key Features
- **Comprehensive Financial Modeling**: Model families, individuals, jobs, various account types, insurance policies, debt, taxes, and more
- **Interactive Dashboard**: Web-based interface using Solara for real-time financial simulations and visualizations
- **Deep Learning Integration**: Train AI agents using deep Q-learning to optimize financial decision-making
- **Flexible Configuration**: YAML-based configuration system for different economic scenarios

## Motivation
While impossible to predict the future, the goal of this package is to provide a robust framework for modeling financial outcomes based on various inputs. The best way to use this model is to change one variable at a time and evaluate how it impacts the outcome.

## Getting Started

### Quick Start
Check out the example simulation notebook:
- [Google Colab (interactive)](https://colab.research.google.com/github/sw23/life-model/blob/main/ExampleSimulation.ipynb)
- [GitHub](https://github.com/sw23/life-model/blob/main/ExampleSimulation.ipynb)

![Training Statistics](https://raw.githubusercontent.com/sw23/life-model/main/img/stats.png)

### Installation
```bash
python -m pip install life-model
```

### Interactive Dashboard
For a web-based interface to run simulations:
```bash
pip install -e . -r dashboard/requirements-dash.txt
solara run dashboard/app.py
```
Then open your browser to http://localhost:8765

![Dashboard Overview](https://raw.githubusercontent.com/sw23/life-model/main/img/dashboard.png)

### Deep Reinforcement Learning
Train AI agents to make optimal financial decisions:
```bash
pip install -r deepqlearning/requirements-rl.txt
python deepqlearning/train_financial_agent.py --scenario basic --episodes 1000
```

## Modeling Status
This package supports a comprehensive range of financial modeling components:

### Core Components
- [x] **Family & Person Models** - Multi-person households with individual financial profiles
- [x] **Children** - Dependents with education and care costs
- [x] **Jobs** - Employment with salary progression and benefits
- [x] **Stock Compensation** - RSU grants with multi-year vesting schedules

### Accounts & Investments
- [x] **Bank Accounts** - Checking/savings with interest
- [x] **401k Plans** - Traditional and Roth with employer matching
- [x] **Traditional & Roth IRAs** - Individual retirement accounts
- [x] **HSA** - Health Savings Accounts
- [x] **529 Plans** - Education savings accounts
- [x] **Brokerage Accounts** - Taxable investment accounts
- [x] **Pensions** - Defined benefit retirement plans with COLA and survivor elections
- [x] **Trust Accounts** - Revocable and irrevocable trusts for estate planning

### Insurance & Protection
- [x] **Life Insurance** - Term and whole life policies with loans
- [x] **General Insurance** - Health, auto, home, umbrella insurance
- [x] **Long Term Care Insurance** - Coverage for nursing home, assisted living, and in-home care
- [x] **Annuities** - Fixed and variable annuities with various payout options
- [x] **Social Security** - Comprehensive benefit calculations with timing strategies

### Debt Management
- [x] **Student Loans** - Education debt with various repayment options
- [x] **Car Loans** - Auto financing
- [x] **Credit Cards** - Revolving debt with interest calculations
- [x] **Mortgages** - Home loans (integrated with housing model)

### Tax System
- [x] **Federal Taxes** - Complete income tax calculations with brackets
- [x] **State Taxes** - Per-state tax packs (progressive brackets or flat rate, retirement/Social Security exemptions, SALT integration) with per-person residency
- [x] **FICA Taxes** - Social Security and Medicare taxes
- [x] **Capital Gains** - Short-term and long-term capital gains
- [x] **Required Minimum Distributions (RMDs)** - Retirement account distributions

### Housing & Lifestyle
- [x] **Home Ownership** - Purchase, mortgage, appreciation, and selling
- [x] **Rental Housing** - Apartment leasing with rent increases
- [x] **Life Events** - Marriage, retirement, career changes, and mortality (stochastic or fixed-age death)

### Healthcare & Aging
- [x] **Medicare Coverage** - Part B and Part D premiums with IRMAA income surcharges (two-year MAGI lookback); Part A is premium-free
- [x] **Long-Term Care Services** - Seeded care-need hazard with care episodes and annual costs, offset by LTC insurance
- [x] **Medical Expense Modeling** - Age-related healthcare cost increases with medical inflation above CPI
- [x] **Chronic Care Management** - Ongoing medical conditions and treatment costs (modeled via the age-band cost curve)
- [x] **Prescription Drug Coverage** - Medicare Part D premium and IRMAA surcharge (modeled via Part D; supplemental plans not itemized)

### Giving & Legacy
- [x] **Charitable Giving** - Tax-deductible donations with itemized deduction support
- [x] **Donor Advised Funds** - Charitable investment accounts with growth, fees, and distributions
- [x] **Estate Planning** - Mortality-driven death, spousal/beneficiary estate transfer, per-account beneficiary designations, estate tax, revocable/irrevocable trusts, and the SECURE Act 10-year inherited-account rule (trust income is untaxed until distributed — no compressed trust brackets; annuity two-life survivor factor still backlog)
- [x] **End of Life Care** - Long-term care facilities and a final-year medical expense spike charged to the estate
- [x] **Funeral and Final Expenses** - Funeral cost charged against the estate before transfer and estate tax

### Advanced Features
- [x] **Economic Scenarios** - Configurable market conditions (recession, inflation, etc.)
- [x] **Payment Services** - Intelligent bill payment with account prioritization
- [x] **Tax Optimization** - Strategic withdrawal and contribution planning
- [x] **Deep Q-Learning** - A reinforcement-learning agent (`deepqlearning/`) that learns an in-episode financial policy, evaluated against planner heuristics with an outcome-based protocol
- [x] **Simulation-Grounded Adviser** - A language-model adviser (`slm/`) that maps a household to a recommended plan-level strategy with a Monte-Carlo-certified rationale (educational decision support, not financial advice; see `slm/README.md`)

## Examples and Documentation

### Dashboard
The interactive dashboard provides real-time visualization of financial simulations with parameter controls for:
- Family member configuration (age, salary, retirement age)
- Economic factors (inflation, salary growth)
- Account balances and debt management
- Tax and spending analysis

### Reinforcement Learning
The deep learning module includes:
- Pre-configured training scenarios (basic, high_earner, low_earner)
- 20+ financial actions for AI agents to learn
- Customizable reward functions for different objectives
- Training visualization and model evaluation tools

### Configuration System
YAML-based configuration files packaged with life-model (in `src/life_model/config/data/scenarios/`) allow modeling of different economic conditions:
- `conservative.yaml` - Low growth, stable conditions
- `aggressive.yaml` - High growth, volatile markets
- `recession.yaml` - Economic downturn scenarios
- `high_inflation.yaml` - Inflationary environment modeling

## Contributing
This project is open source and welcomes contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the tox targets used by CI, and the `pre-commit install` step. The test suite in `src/life_model/tests/` shows examples of expected functionality.

## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## How to Cite
If you use this package in your research, please cite it as follows:
```bibtex
@software{life_model,
  author = {Spencer Williams},
  title = {life-model: Personal Finance Simulation Framework},
  url = {https://github.com/sw23/life-model},
  version = {0.0.0},
  year = 2025
}
```
