PolicyEngine / PolicyEngine/policyengine-scorecard
Official-calculator oracles (mode 3): gov.uk and benefits-calculator household cases as a second UK oracle family
@vahid-ahmadi is already working on this.
Since Aug 17, 2026.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6d 12h
- Merged PRs (30d)
- 32
Description
The mode-3 UK lane so far is UKMOD/EUROMOD-shaped: #41 (JRC connector) and the case schema + battery in #49. One oracle family is a single point of comparison — when PE and UKMOD disagree, nothing adjudicates. The UK has something the US mostly lacks: official and production-grade household calculators whose outputs are ground truth or near-ground-truth for a specified household:
- gov.uk estimators: HMRC's income-tax/NICs estimator, the State Pension and Child Benefit tax-charge (HICBC) calculators — official statements of liability for a given input set.
- Policy in Practice's Better Off Calculator / entitledto: production benefit calculators used for real claims, exercising UC (elements, taper, deductions), legacy benefits, and council tax support with local variation.
- Turn2us: a third independent benefits implementation.
Each case result is a per-household oracle diff in exactly the #49 schema — the case battery, closed-schema validation, and adjudication contract (tolerance/annotation requirements just landed in 838cc45) are reused as-is; only the connector and the oracle registration differ.
Why this earns a lane
- Adjudication: PE vs UKMOD vs an official calculator turns two-way disagreements into attributable defects (whose rules encoding is wrong). Feeds the #49 battery's
expected_focusrationale directly. - Coverage where UKMOD is weak: UC deductions and the benefit cap (the #21/#52 family) are modeled by production calculators in operational detail; a case battery over the FRR deduction priority order would validate the exact machinery the UC-deductions scores depend on.
- The two-child pair: the 2025/2026 abolition-boundary cases from #49 get a second, independent expected-value source.
Constraints to respect (why this is scoped, not scraped)
Manual case entry or documented API/terms-compliant access only, one case at a time, provenance per result (calculator version/date screenshotted or archived) — these are oracle readings, not a harvest. Case inputs stay within the #49 closed schema so every oracle answers the identical household.
Steps
- Register the oracle vocabulary (oracle id + version/date per result row) in the #49 schema — one field, no shape change
- 10-case starter battery: HICBC taper, NICs at each band boundary, UC taper + work allowance, two-child pair, benefit-cap binding case — each entered into ≥2 calculators
- Adjudication writeups where the three sides split (the SCHEMA.md contract now requires them)
Depends on #49 (schema, merged fixes). Complements #41; instance of #5.
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.
Assessment
This issue has not been assessed yet.