Skip to content

Add country situation preprocessing and supplied membership provenance - #600

Draft
hua7450 wants to merge 3 commits into
masterfrom
marital-unit-construction-hook
Draft

hua7450 wants to merge 3 commits into
masterfrom
marital-unit-construction-hook

Conversation

@hua7450

@hua7450 hua7450 commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Country models cannot currently supply missing entity groups consistently across the household API and YAML runner. Add an opt-in TaxBenefitSystem.preprocess_situation hook before entity construction, and record Simulation.input_group_entities so formulas can distinguish supplied memberships from generated defaults. The default hook leaves other countries' behavior unchanged; datasets bypass it and retain their supplied membership provenance. A Reform delegates the hook to its baseline, so reformed systems and the YAML runner's inline-parameter and reforms: cases run the country's hook too.

Prerequisite for PolicyEngine/policyengine-us#9999; consumer implementation: PolicyEngine/policyengine-us#10000. Keep in draft while the US consumer and integration are reviewed.

Validation (head with master merged in): 163 focused tests pass across the simulation builder, IndividualSim, dataset loading, reforms, the YAML runner and axes; ruff format and ruff check pass. New tests cover reform delegation (directly and through the YAML runner's system builder), partially supplied groups in a multi-group system, flat files that declare a group only through its ID column, array datasets, IndividualSim placeholder groups, and a hook that returns a non-dict. No country package or real microdata is required. The full core suite was not run.

Documentation review: added the hook/provenance contract to the simulation API reference and source docstrings. Impact: medium (public extension point, opt-in default). Confidence: high for the focused paths; downstream US integration is being tested in the companion draft.

hua7450 and others added 2 commits October 30, 2026 21:06
…uction-hook

# Conflicts:
#	tests/core/test_simulation_builder.py
A Reform inherited TaxBenefitSystem's no-op preprocess_situation, so
reformed systems, including the YAML runner's inline-parameter and
reforms: cases, skipped the country's hook. Reform now delegates to its
baseline.

Flat files that declare a group only through its ID column now record
it as supplied, matching the loader. IndividualSim's placeholder and
default groups are no longer recorded as supplied. A hook that returns
something other than a dict raises a TypeError naming the hook. The docs
describe dataset provenance, axes and default_period accurately.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
hua7450 added a commit to hua7450/policyengine-us that referenced this pull request Oct 31, 2026
PolicyEngine/policyengine-core#600 now includes Core's main (3.34.0) and
delegates the hook through reforms, so main's policyengine-us imports
against it.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant