{"id":30663352,"url":"https://github.com/policyengine/finsim","last_synced_at":"2025-08-31T17:10:27.238Z","repository":{"id":309031187,"uuid":"1034943179","full_name":"PolicyEngine/finsim","owner":"PolicyEngine","description":"Financial simulation tool for comparing annuities, investments, and retirement strategies with tax-aware Monte Carlo modeling","archived":false,"fork":false,"pushed_at":"2025-08-19T09:44:24.000Z","size":1700,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-27T20:31:49.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PolicyEngine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-09T10:10:37.000Z","updated_at":"2025-08-11T00:15:06.000Z","dependencies_parsed_at":"2025-08-09T12:18:50.380Z","dependency_job_id":"a5fce7cb-7a6c-4ec1-a54a-3bddcc315390","html_url":"https://github.com/PolicyEngine/finsim","commit_stats":null,"previous_names":["policyengine/finsim"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/PolicyEngine/finsim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Ffinsim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Ffinsim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Ffinsim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Ffinsim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PolicyEngine","download_url":"https://codeload.github.com/PolicyEngine/finsim/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PolicyEngine%2Ffinsim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273010994,"owners_count":25030369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-31T17:10:22.477Z","updated_at":"2025-08-31T17:10:27.229Z","avatar_url":"https://github.com/PolicyEngine.png","language":"Python","readme":"# FinSim by PolicyEngine\n\nA comprehensive financial simulation tool for comparing annuities with index fund investments, accounting for taxes, Social Security benefits, and mortality risk.\n\n## Features\n\n- **Annuity Analysis**: Compare multiple annuity proposals with IRR calculations\n- **Monte Carlo Simulation**: Model index fund performance with customizable parameters\n- **Tax Integration**: Uses PolicyEngine-US for accurate federal and state tax calculations\n- **Social Security**: Includes COLA adjustments based on SSA uprating factors\n- **Interactive Visualizations**: Portfolio paths, depletion probabilities, and tax impacts\n\n## Installation\n\nUsing [uv](https://github.com/astral-sh/uv) (recommended):\n\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone the repository\ngit clone https://github.com/PolicyEngine/finsim\ncd finsim\n\n# Create virtual environment and install\nuv venv\nuv pip install -e \".[app]\"\n```\n\nOr with pip:\n\n```bash\npip install finsim\n# For the Streamlit app:\npip install \"finsim[app]\"\n```\n\n## Usage\n\n### Important: Always Use `uv run`\n\n⚠️ **Always use `uv run` to execute Python commands** to ensure the correct environment and dependencies:\n\n```bash\n# ✅ Correct\nuv run streamlit run app.py\nuv run python script.py\nuv run pytest tests/\n\n# ❌ Wrong - may cause numpy/PolicyEngine compatibility issues\nstreamlit run app.py\npython script.py\npytest tests/\n```\n\nRun the Streamlit app:\n\n```bash\nuv run streamlit run app.py\n```\n\n## Components\n\n### 1. Monte Carlo Simulator (`monte_carlo.py`)\n- Simulates index fund performance (default: VT Total World Stock)\n- Configurable returns, volatility, and dividend yields\n- Calculates depletion probabilities and portfolio percentiles\n- Supports dividend reinvestment strategies\n\n### 2. Tax Calculator (`tax_calculator.py`)\n- Integrates PolicyEngine-US for precise tax modeling\n- Handles:\n  - Long-term capital gains with basis tracking\n  - Social Security benefit taxation\n  - OBBBA senior deduction ($6,000 for 2025)\n  - Federal and state taxes\n- Projects SS benefits with COLA adjustments\n\n### 3. Annuity Calculator (`annuity.py`)\n- Calculates internal rate of return (IRR)\n- Supports both fixed-term and life-contingent annuities\n- Uses CDC mortality tables for survival weighting\n- Handles taxable vs. tax-free (§104(a)(2)) annuities\n\n### 4. Streamlit Interface (`app.py`)\n- Input forms for:\n  - Personal information (age, state, filing status)\n  - Settlement amount\n  - Social Security benefits\n  - Multiple annuity proposals\n- Interactive visualizations:\n  - Monte Carlo simulation paths with percentile bands\n  - Distribution of final portfolio values\n  - Tax impact analysis\n  - Capital gains inclusion ratio over time\n\n## Key Assumptions\n\n- **Default Index Fund**: VT (Vanguard Total World Stock)\n  - Expected return: 8% annually\n  - Volatility: 15.8% annually\n  - Dividend yield: 2% annually\n- **Tax Treatment**:\n  - Personal injury settlements under IRC §104(a)(2) are tax-free\n  - Index fund gains start at ~20% taxable fraction, increasing over time\n  - California state tax applies; no tax on Social Security benefits\n- **Social Security**:\n  - Annual COLA adjustments based on CPI-W\n  - Up to 85% taxable at federal level depending on income\n\n## Example Scenarios\n\n### Your Father's Case\n- Age: 65\n- Settlement: $527,530\n- Social Security: $2,000/month\n- State: California\n- Three annuity proposals with varying terms and IRRs\n\nThe tool shows:\n- Proposal A (life contingent): Lower monthly payment but longevity protection\n- Proposal B (15-year certain): Higher IRR, fixed term\n- Proposal C (10-year certain): Highest monthly payment, shortest term\n- Index fund alternative: Higher expected return but ~20-35% depletion risk\n\n## Data Tracking\n\nThe simulation maintains complete arrays for every simulation path and year:\n\n- **Portfolio Evolution**: Start/end values, cost basis tracking\n- **Income Components**: Dividends, capital gains, Social Security (with COLA), pensions, annuities\n- **Withdrawal Mechanics**: Gross withdrawals, taxable portions, net after-tax amounts\n- **Tax Tracking**: Taxes owed (current year) vs. paid (prior year liability)\n- **Life Events**: Mortality status, portfolio depletion year, estate values\n- **Inflation Adjustments**: SSA COLA (CPI-W) for Social Security, C-CPI-U for consumption\n\nThis comprehensive tracking enables detailed analysis of success rates, tax efficiency, and withdrawal strategies across thousands of Monte Carlo scenarios.\n\n## Limitations\n\n- Mortality tables are simplified (CDC averages, not personalized)\n- Tax calculations assume current law continues\n- Market return assumptions based on historical data\n- Does not model healthcare costs or long-term care needs\n- State tax calculations limited to major states\n\n## Contributing\n\nFeel free to submit issues or pull requests to improve the tool.\n\n## License\n\nMIT","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Ffinsim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpolicyengine%2Ffinsim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpolicyengine%2Ffinsim/lists"}