Read retirement limits from policyengine-us parameters (#566)

* Read retirement limits from policyengine-us parameters

Replace hard-coded RETIREMENT_LIMITS dict with a shared utility that
reads from policyengine-us's parameter tree at runtime. This ensures
limits stay in sync as policyengine-us is updated, and eliminates a
maintenance risk when the same dict is duplicated in puf_impute.py
(PR #554).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fixup! Read retirement limits from policyengine-us parameters

* Revert test formatting to match CI Black version

The fixup reformatted SQL strings in test_database_build.py using
a newer Black version that disagrees with CI's lgeiger/black-action.
Revert to the original formatting that CI accepts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add tests for retirement limits utility

Verifies get_retirement_limits returns correct IRS contribution
limits for 2020, 2023, and 2025 by comparing against known values.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Handle both old and new policyengine-us catch-up parameter layouts

The SECURE 2.0 update (merged to pe-us main, not yet released)
renames children["401k"] to children["k401"] and changes it from
a simple int to an age-bracketed scale. Handle both layouts so the
code works with the current release and future releases.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Use k401 parameter directly, bump policyengine-us>=1.572.5

Drop dual-path handling in favor of the current parameter layout
(k401 scale with age brackets from SECURE 2.0). Bump the minimum
policyengine-us version to 1.572.5 which introduced this parameter.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: MaxGhenis

changelog.d/use-pe-us-retirement-limits.changed.md

@@ -0,0 +1 @@
+Read IRS retirement contribution limits from policyengine-us parameters instead of hard-coding them.

policyengine_us_data/datasets/cps/cps.py

@@ -649,51 +649,11 @@ def add_personal_income_variables(
     # Disregard reported pension contributions from people who report neither wage and salary
     # nor self-employment income.
     # Assume no 403(b) or 457 contributions for now.
-    # IRS retirement contribution limits by year.
-    RETIREMENT_LIMITS = {
-        2020: {
-            "401k": 19_500,
-            "401k_catch_up": 6_500,
-            "ira": 6_000,
-            "ira_catch_up": 1_000,
-        },
-        2021: {
-            "401k": 19_500,
-            "401k_catch_up": 6_500,
-            "ira": 6_000,
-            "ira_catch_up": 1_000,
-        },
-        2022: {
-            "401k": 20_500,
-            "401k_catch_up": 6_500,
-            "ira": 6_000,
-            "ira_catch_up": 1_000,
-        },
-        2023: {
-            "401k": 22_500,
-            "401k_catch_up": 7_500,
-            "ira": 6_500,
-            "ira_catch_up": 1_000,
-        },
-        2024: {
-            "401k": 23_000,
-            "401k_catch_up": 7_500,
-            "ira": 7_000,
-            "ira_catch_up": 1_000,
-        },
-        2025: {
-            "401k": 23_500,
-            "401k_catch_up": 7_500,
-            "ira": 7_000,
-            "ira_catch_up": 1_000,
-        },
-    }
-    # Clamp to the nearest available year for out-of-range values.
-    clamped_year = max(
-        min(year, max(RETIREMENT_LIMITS)),
-        min(RETIREMENT_LIMITS),
+    from policyengine_us_data.utils.retirement_limits import (
+        get_retirement_limits,
     )
-    limits = RETIREMENT_LIMITS[clamped_year]
+
+    limits = get_retirement_limits(year)
     LIMIT_401K = limits["401k"]
     LIMIT_401K_CATCH_UP = limits["401k_catch_up"]
     LIMIT_IRA = limits["ira"]

policyengine_us_data/tests/test_retirement_limits.py

@@ -0,0 +1,35 @@
+"""Tests for retirement contribution limits utility."""
+
+import pytest
+from policyengine_us_data.utils.retirement_limits import (
+    get_retirement_limits,
+)
+
+# Expected values sourced from IRS announcements and policyengine-us
+# parameter tree.
+EXPECTED = {
+    2020: {
+        "401k": 19_500,
+        "401k_catch_up": 6_500,
+        "ira": 6_000,
+        "ira_catch_up": 1_000,
+    },
+    2023: {
+        "401k": 22_500,
+        "401k_catch_up": 7_500,
+        "ira": 6_500,
+        "ira_catch_up": 1_000,
+    },
+    2025: {
+        "401k": 23_500,
+        "401k_catch_up": 7_500,
+        "ira": 7_000,
+        "ira_catch_up": 1_000,
+    },
+}
+
+
+@pytest.mark.parametrize("year", EXPECTED.keys())
+def test_retirement_limits(year):
+    limits = get_retirement_limits(year)
+    assert limits == EXPECTED[year]

policyengine_us_data/utils/retirement_limits.py

@@ -0,0 +1,36 @@
+"""Retirement contribution limits from policyengine-us parameters.
+
+Reads IRS contribution limits from the policyengine-us parameter tree
+instead of hard-coding them.
+"""
+
+from functools import lru_cache
+
+
+@lru_cache(maxsize=16)
+def get_retirement_limits(year: int) -> dict:
+    """Return contribution limits for the given tax year.
+
+    Reads from policyengine-us parameters at:
+      gov.irs.gross_income.retirement_contributions.limit.{401k, ira}
+      gov.irs.gross_income.retirement_contributions.catch_up.limit.{k401, ira}
+
+    The k401 catch-up parameter is a SingleAmountTaxScale with age
+    brackets (SECURE 2.0); we use the age-50 bracket for the standard
+    catch-up amount.
+
+    Returns:
+        Dict with keys: 401k, 401k_catch_up, ira, ira_catch_up.
+    """
+    from policyengine_us import CountryTaxBenefitSystem
+
+    tbs = CountryTaxBenefitSystem()
+    p = tbs.parameters.gov.irs.gross_income.retirement_contributions
+    d = f"{year}-01-01"
+
+    return {
+        "401k": int(p.limit.children["401k"](d)),
+        "401k_catch_up": int(p.catch_up.limit.children["k401"](d).calc(50)),
+        "ira": int(p.limit.ira(d)),
+        "ira_catch_up": int(p.catch_up.limit.ira(d)),
+    }

pyproject.toml

@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "policyengine-us>=1.516.0",
+    "policyengine-us>=1.572.5",
     "policyengine-core>=3.23.6",
     "pandas>=2.3.1",
     "requests>=2.25.0",