PolicyEngine / PolicyEngine/policyengine-api
Define API behavior for outputs introduced by structural reforms
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 18
- Forks
- 33
- Avg merge
- 23h 40m
- Merged PRs (30d)
- 22
Description
Problem
The household calculation API validates requested output-variable names against the baseline country metadata before constructing the tax-benefit system with the submitted reform. Consequently, a caller cannot request the value of a variable introduced by that reform.
For example, the Family Security Act structural reform adds pregnant_mothers_credit. A calculation requesting only baseline variables succeeds, and the reformed model can use pregnant_mothers_credit internally. Adding this output request to the household, however, produces HTTP 400:
{
"status": "error",
"message": "Unrecognized calculate input(s): Unrecognized household variable `pregnant_mothers_credit` at `household.tax_units.your tax unit.pregnant_mothers_credit`."
}
Cause
HouseholdCalculationService.calculate_household() calls find_unrecognized_inputs() with country.metadata. That metadata describes the unreformed system. The submitted policy is applied only afterward by country.calculate(), so validation cannot recognize variables added by the reform.
This differs from the cloning defect fixed by PolicyEngine/policyengine-core#294: the model can now resolve reform-added variables while calculating formulas, but API clients still cannot name those variables as requested outputs.
Expected behavior
Define and implement the API contract for reform-added output variables as part of the API v2 household-calculation compute cutover:
- If reform-added outputs are supported, validate household output requests against the effective reformed tax-benefit system and return the requested values.
- If they are intentionally unsupported, return a specific error explaining that distinction rather than reporting that a valid reform-added variable does not exist.
- Apply the same behavior to ordinary and axis calculations.
Acceptance coverage
- A structural reform introduces a new variable and uses it successfully as an internal dependency.
- Requesting that variable directly follows the chosen API contract.
- The behavior is covered both without axes and with an earnings axis.
- An actually unknown variable remains rejected.
Related: #1885.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with HouseholdCalculationService.calculate_household(), find_unrecognized_inputs(), and the later country.calculate() call to trace validation versus reform application. Review the API v2 household-calculation compute cutover and related issue #1885 before choosing the contract. Done means ordinary and axis calculations consistently handle reform-added outputs, while truly unknown variables remain rejected and the acceptance cases are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend-api-design, testing-qa
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100