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
• Stock Compensation - RSU grants with multi-year vesting schedules

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 with COLA and survivor elections
• 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 - Per-state tax packs (progressive brackets or flat rate, retirement/Social Security exemptions, SALT integration) with per-person residency
• FICA Taxes - Social Security and Medicare taxes
• Capital Gains - Short-term and long-term capital gains
• 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 - Part B and Part D premiums with IRMAA income surcharges (two-year MAGI lookback); Part A is premium-free
• Long-Term Care Services - Seeded care-need hazard with care episodes and annual costs, offset by LTC insurance
• Medical Expense Modeling - Age-related healthcare cost increases with medical inflation above CPI
• Chronic Care Management - Ongoing medical conditions and treatment costs (modeled via the age-band cost curve)
• Prescription Drug Coverage - Medicare Part D premium and IRMAA surcharge (modeled via Part D; supplemental plans not itemized)

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, 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)
• End of Life Care - Long-term care facilities and a final-year medical expense spike charged to the estate
• Funeral and Final Expenses - Funeral cost charged against the estate before transfer and estate tax

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 - A reinforcement-learning agent (deepqlearning/) that learns an in-episode financial policy, evaluated against planner heuristics with an outcome-based protocol
• 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 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
}