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!
The package provides comprehensive models of people, jobs, accounts, insurance, debt, and more within a time step-based simulation framework. Built on the 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.
- 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
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.
Check out the example simulation notebook:
python -m pip install life-modelFor a web-based interface to run simulations:
pip install -e . -r dashboard/requirements-dash.txt
solara run dashboard/app.pyThen open your browser to http://localhost:8765
Train AI agents to make optimal financial decisions:
pip install -r deepqlearning/requirements-rl.txt
python deepqlearning/train_financial_agent.py --scenario basic --episodes 1000This package supports a comprehensive range of financial modeling components:
- Family & Person Models - Multi-person households with individual financial profiles
- Children - Dependents with education and care costs
- Jobs - Employment with salary progression and benefits
- Bank Accounts - Checking/savings with interest
- 401k Plans - Traditional and Roth with employer matching
- Traditional & Roth IRAs - Individual retirement accounts
- HSA - Health Savings Accounts
- 529 Plans - Education savings accounts
- Brokerage Accounts - Taxable investment accounts
- Pensions - Defined benefit retirement plans
- Trust Accounts - Revocable and irrevocable trusts for estate planning
- Life Insurance - Term and whole life policies with loans
- General Insurance - Health, auto, home, umbrella insurance
- Long Term Care Insurance - Coverage for nursing home, assisted living, and in-home care
- Annuities - Fixed and variable annuities with various payout options
- Social Security - Comprehensive benefit calculations with timing strategies
- Student Loans - Education debt with various repayment options
- Car Loans - Auto financing
- Credit Cards - Revolving debt with interest calculations
- Mortgages - Home loans (integrated with housing model)
- Federal Taxes - Complete income tax calculations with brackets
- State Taxes - Configurable state tax rates (basic flat rate only)
- FICA Taxes - Social Security and Medicare taxes
- Required Minimum Distributions (RMDs) - Retirement account distributions
- Home Ownership - Purchase, mortgage, appreciation, and selling
- Rental Housing - Apartment leasing with rent increases
- Life Events - Marriage, retirement, career changes
- Medicare Coverage - Parts A, B, C, D with premium calculations
- Long-Term Care Services - Nursing homes, assisted living, home health aides
- Medical Expense Modeling - Age-related healthcare cost increases
- Chronic Care Management - Ongoing medical conditions and treatment costs
- Prescription Drug Coverage - Medicare Part D and supplemental insurance
- Charitable Giving - Tax-deductible donations with itemized deduction support
- Donor Advised Funds - Charitable investment accounts with growth, fees, and distributions
- Estate Planning - Wills, trusts, and inheritance tax modeling
- End of Life Care - Long-term care facilities and medical expenses
- Funeral and Final Expenses - End-of-life costs and pre-planning
- Economic Scenarios - Configurable market conditions (recession, inflation, etc.)
- Payment Services - Intelligent bill payment with account prioritization
- Tax Optimization - Strategic withdrawal and contribution planning
- Deep Q-Learning - AI-driven financial decision optimization
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
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
YAML-based configuration files in /config/scenarios/ allow modeling of different economic conditions:
conservative.yaml- Low growth, stable conditionsaggressive.yaml- High growth, volatile marketsrecession.yaml- Economic downturn scenarioshigh_inflation.yaml- Inflationary environment modeling
This project is open source and welcomes contributions. Please see the test suite in src/life_model/tests/ for examples of expected functionality and to ensure your changes don't break existing features.
This project is licensed under the MIT License. See the LICENSE file for details.
If you use this package in your research, please cite it as follows:
@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
}