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 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)
• GitHub

Installation

python -m pip install life-model

Interactive Dashboard

For a web-based interface to run simulations:

pip install -e . -r dashboard/requirements-dash.txt
solara run dashboard/app.py

Then open your browser to http://localhost:8765

Deep Reinforcement Learning

Train AI agents to make optimal financial decisions:

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

• Family & Person Models - Multi-person households with individual financial profiles
• Children - Dependents with education and care costs
• Jobs - Employment with salary progression and benefits

Accounts & Investments

• 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

Insurance & Protection

• 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

Debt Management

• 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)

Tax System

• 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

Housing & Lifestyle

• Home Ownership - Purchase, mortgage, appreciation, and selling
• Rental Housing - Apartment leasing with rent increases
• Life Events - Marriage, retirement, career changes, and mortality (stochastic or fixed-age death)

Healthcare & Aging

• 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

Giving & Legacy

• Charitable Giving - Tax-deductible donations with itemized deduction support
• Donor Advised Funds - Charitable investment accounts with growth, fees, and distributions
• [~] Estate Planning - Mortality-driven death, spousal/beneficiary estate transfer, and estate tax (trusts and the 10-year inherited-account rule are not yet modeled)
• End of Life Care - Long-term care facilities and medical expenses
• Funeral and Final Expenses - End-of-life costs and pre-planning

Advanced Features

• 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

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 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 file for details.

How to Cite

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
}