Problem
The household calculators expose a year argument, but because Python does not enforce the int type hint at runtime, callers can pass monthly period strings such as year="2026-01". In the US path, this reached the underlying country simulation and returned values, but the results were not semantically reliable.
The household wrappers periodize every household input under str(year), so a monthly string causes annual inputs such as employment_income to be stamped onto a monthly period. In local investigation, this produced distorted output: annual inputs disappeared or changed, while monthly variables such as SNAP still returned monthly-looking values.
The helpers also do not support periodized household input values such as:
people=[{"employment_income": {"2026-01": 1000}}]Those values are currently ambiguous because the helpers wrap input values themselves as {year: value}.
Expected behavior
Until monthly household calculations are explicitly designed and tested, household helpers should fail early when callers provide:
- monthly/non-annual
year values such as "2026-01"
- periodized household input values such as
{"2026-01": 1000}
Reform effective-date dictionaries should remain valid, since those are separate from household input values and are already part of the supported reform API.
Scope
This issue is only for an immediate guardrail. It is not intended to implement full monthly household support or redesign the flattened HDF5 dataset format.
Problem
The household calculators expose a
yearargument, but because Python does not enforce theinttype hint at runtime, callers can pass monthly period strings such asyear="2026-01". In the US path, this reached the underlying country simulation and returned values, but the results were not semantically reliable.The household wrappers periodize every household input under
str(year), so a monthly string causes annual inputs such asemployment_incometo be stamped onto a monthly period. In local investigation, this produced distorted output: annual inputs disappeared or changed, while monthly variables such as SNAP still returned monthly-looking values.The helpers also do not support periodized household input values such as:
Those values are currently ambiguous because the helpers wrap input values themselves as
{year: value}.Expected behavior
Until monthly household calculations are explicitly designed and tested, household helpers should fail early when callers provide:
yearvalues such as"2026-01"{"2026-01": 1000}Reform effective-date dictionaries should remain valid, since those are separate from household input values and are already part of the supported reform API.
Scope
This issue is only for an immediate guardrail. It is not intended to implement full monthly household support or redesign the flattened HDF5 dataset format.