feat: add Simulation.from_situation for situation-JSON input

[vahid-ahmadi]

Summary

Addresses the smallest, lowest-risk slice of #51: a single classmethod, Simulation.from_situation(situation, year), that accepts a PolicyEngine web-app situation-JSON dict and returns a fully-built Simulation. Pure Python wrapper change — no Rust modifications.

sim = Simulation.from_situation(
    {
        "people":     {"you": {"age": 30, "employment_income": {"2025": 50_000}}},
        "benunits":   {"yours": {"members": ["you"]}},
        "households": {"yours": {"members": ["you"], "region": "LONDON"}},
    },
    year=2025,
)
result = sim.run()

What's included

• Simulation.from_situation(situation, year) classmethod
• _situation_to_dataframes helper that handles:
  • period-keyed values ({"2025": 50000}) and plain scalars
  • members: lists wired up to integer person_ids and ;-separated person_ids / benunit_ids strings
  • implicit benunit when omitted (folds all people into one)
  • implicit is_benunit_head / is_household_head (first member of each entity, unless the situation set it explicitly)
  • region normalisation: accepts both "LONDON" (web-app form) and "London" (wrapper form), normalises to the form src/data/clean.rs::parse_region expects, and propagates is_in_scotland from the household region
  • lowercased gender
• 22 pytest tests covering period resolution, members wiring, region normalisation, gender, multi-benunit households, validation errors, and parity with the existing single_person/couple constructors
• CI step that runs the new Python tests (pytest interfaces/python/tests)
• Changelog fragment under changelog.d/added/

Verified locally

• cargo test: 135 passing
• pytest interfaces/python/tests: 22 passing
• End-to-end smoke tests against the release binary:
  • Single person £50k: from_situation → single_person produces identical income tax (£7,486), NI (£2,994), net income (£39,520)
  • Couple + child: identical to couple() constructor for net income (£55,194) and child benefit (£1,355)

Scope notes

This PR addresses point 1 of issue #51's proposal (situation-JSON entry point). Points 2–4 (build_from_dataframe shorthand, build_from_url, full PE-canonical-name aliasing for variables that diverge from the wrapper's column schema) remain as follow-ups. Variable names in the situation dict map to the wrapper's existing input columns (those listed in PERSON_DEFAULTS / BENUNIT_DEFAULTS / HOUSEHOLD_DEFAULTS), with explicit normalisation only for region and gender.

Test plan

• CI passes (cargo test + pytest interfaces/python/tests)
• Local end-to-end run: from_situation → Simulation.run_microdata() produces sensible numbers for hypothetical households
• Parity check: from_situation matches single_person and couple() output to the penny

🤖 Generated with Claude Code

[nikhilwoodruff]

I am lean no on this. PE-UK originally has had users and AI agents confused by multiple possible input schemas, and I think a single, well documented and enforced point of entry would avoid mistakes.

[vahid-ahmadi]

Rebased onto main (mergeable). Holding on @nikhilwoodruff's design objection — needs a maintainer decision before merge.

The code itself is clean and well-tested (22 hermetic tests; correct entity/id wiring, head-flag logic, region/gender normalisation). The blocker is the design point Nikhil raised: this adds a second public input schema alongside single_person/couple/raw-DataFrame, and the preference is a single, enforced entry point.

Worth noting that the original consumers no longer need this: the parity harness (#53) was reworked to compare FRS microdata directly, and the YAML harness (#54) now inlines the situation→DataFrame conversion as a private helper. So nothing currently depends on the public from_situation classmethod.

Given that, I'd suggest one of:

• Close this PR (the conversion logic now lives privately in feat: add YAML policy-test harness #54), or
• Repurpose it into a single documented/enforced entry point, routing the existing constructors through it rather than adding alongside them.

Happy to take whichever direction you prefer — flagging for your call rather than merging as-is.

[vahid-ahmadi]

Re-verified on latest main (rebased, mergeable):

• Tests: 22/22 pytest pass.
• Correctness: from_situation matches single_person to the penny — £7,486 income tax / £2,994 employee NI / £39,520 net income for the £50k single-adult case.
• Runtime: the situation→DataFrame conversion is ~1.1 ms/call warm (it's pandas DataFrame construction, not the mapping logic); run() itself is subprocess-dominated. Negligible for the single-situation use this targets.

Perf and correctness aren't the open question, though — @nikhilwoodruff's design point is, and it's the blocker. Confirming the dependency picture so the call is clean: nothing depends on the public from_situation anymore — #53's parity harness compares FRS microdata directly, and #54 inlines the situation→DataFrame conversion as a private helper (verified across both branches). So neither resolution loses functionality:

• (a) Close — the conversion already lives privately where it's used (feat: add YAML policy-test harness #54); or
• (b) Repurpose into the single enforced entry point, routing single_person / couple through it so there's one documented schema rather than two.

@nikhilwoodruff — which would you prefer? Happy to do the (b) refactor or close for (a); flagging for your call rather than merging as-is.