microsim-runner

Microsim Runner

Runs a single reform through PolicyEngine and returns structured impact results.

Two execution paths — pick based on environment:

1. API path (default, no install required): call api.policyengine.org.
2. Local path (heavy, more flexible): install the policyengine package (latest, >=5.0.1) and run through its managed pe.{us,uk} surfaces (see "Process — Local path").

Inputs

• reform_dict: PolicyEngine parameter changes (from parameter-locator)
• jurisdiction: {country, state?} (e.g., {country: us, state: ri} or {country: us} for federal)
• year: simulation year (default 2026)
• mode: api (default) or local

Process — API path

Load the policyengine-python-client skill for current endpoint shapes.

Step 1: Create the policy

import requests
response = requests.post(
    "https://api.policyengine.org/us/policy",
    json={"data": reform_dict},
)
policy_id = response.json()["result"]["policy_id"]

Step 2: Request economy-wide impacts

Critical: the URL is /economy/{reform_policy_id}/over/{baseline_policy_id}, NOT /over/1. The over/{N} segment is the baseline policy ID to diff against, not a year count. Common baseline IDs:

Country	Current-law baseline policy_id
US	2
UK	(verify per-environment; typically 1 or 2)

Calling /over/1 against an arbitrary reform usually returns a misleading parse error or computes against a stale baseline. Always use the documented current-law baseline.

region = state.lower() if state else "us"
baseline_id = 2  # US current law — verify
url = f"https://api.policyengine.org/us/economy/{policy_id}/over/{baseline_id}"
response = requests.get(url, params={
    "region": region,
    "time_period": str(year),
    "dataset": "enhanced_cps",  # advertised name; backed by populace-us-2024 as of PE-US 1.729.0
})

Dataset naming — IMPORTANT:

The deployed API advertises only two dataset names at /us/metadata/economy_options/datasets: