policyengine-model-development

PolicyEngine model development

Engineering patterns for the country-model repos — policyengine-us, policyengine-uk, policyengine-canada. These packages encode enacted law (and proposed reforms) as variables (Python formulas) driven by parameters (YAML), validated by YAML tests, all running on the vectorized policyengine-core engine.

This skill is the how-to-write-it layer. To run calculations or score reforms, use the policyengine skill instead. Verified against policyengine-us 1.764.x / policyengine-core 3.30.x (2026-07).

For delegated implementation, test authoring or review, follow agent-loading.md: every worker loads this entrypoint in its own context, reads its task references and reports evidence of the load before work.

Mental model

• Parameters are a YAML tree under parameters/gov/.... Each leaf is a dated value (or a bracket/breakdown table) with required metadata. Accessed in formulas as parameters(period).gov.agency.program.thing. Federal under gov/{agency}/, state under gov/states/{st}/, contributed reforms under gov/contrib/.
• Variables live one-per-file under variables/gov/..., each a Variable subclass with value_type / entity / definition_period / metadata and either a formula or an adds/subtracts list (never both). Formulas run vectorized over the whole population.
• Entities nest: Person → TaxUnit / SPMUnit / Family / MaritalUnit / Household (US); Person → BenUnit / Household (UK). Aggregation across entity levels is automatic via adds/add().
• Tests are YAML files mirroring the variable path under tests/policy/baseline/..., asserting outputs for a described household at a period.

The absolute musts

1. Never hardcode a numeric policy value in a formula. Every threshold, rate, and amount comes from a parameter (p.income_limit, not 2000). Bare 0/1/-1 and MONTHS_IN_YEAR are the only acceptable literals. See references/variables.md.
2. Vectorize everything. No if/elif/else or and/or/not on entity arrays — use where / select / & / | / ~. Python if is allowed only on scalar parameters (if p.flat_applies:). See references/vectorization.md.
3. adds/subtracts XOR formula — never both in one variable. A pure sum uses the adds attribute with no formula; anything else uses a formula (with add() inside). See references/periods-and-aggregation.md.
4. Get the period right. From a MONTH formula, YEAR flow variables (income) use period (auto ÷12); YEAR stocks/counts/ages/booleans use period.this_year (no division). See references/periods-and-aggregation.md.
5. uv run for everything. uv run pytest ..., uv run policyengine-core test .... Never bare pytest. Format with uv run ruff (line length 88, the default — not 79). There is no black in this toolchain.
6. Changelog = a towncrier fragment, never an edit to CHANGELOG.md. Write changelog.d/{branch-name}.{added|fixed|changed}.md with one line.
7. Branch from the PolicyEngine upstream repo, not a fork. Encoding work targets origin/main of PolicyEngine/policyengine-us (etc.).