Integrate OG-USA through the common OLG adapter contract

[vahid-ahmadi]

Objective

Add OG-USA as a separate US overlapping-generations member, following the integration pattern already established for OG-UK while preserving the differences in policy vocabulary, calibration data, units, runtime, and validation.

This is not a fork or reimplementation. The model stays upstream at PSLmodels/OG-USA; PolicyEngine Macro supplies a thin, tested adapter, common result metadata, CLI/MCP discovery, and documentation.

Upstream feasibility baseline

• Package: ogusa 0.4.0, Python 3.12–3.13.
• Source: PSLmodels/OG-USA, CC0-1.0.
• Core solver: PSLmodels/OG-Core.
• Public packaged calibration assets include default parameter JSON, CPS, SCF and PSID files.
• Optional/restricted profiles include PUF/TMD inputs; some calibration paths require a FRED API key.
• Upstream states that a full baseline/reform transition-path run can exceed two hours. Hosted synchronous execution must not be promised before measurement.
• Documentation: https://pslmodels.github.io/OG-USA/content/intro/intro.html

Integration design

1. Keep the UK and US models distinct

• Add canonical registry ID og-us; retain og-uk.
• Let score_reform(country="us", model="og") route explicitly to OG-USA and country="uk" to OG-UK, or expose unambiguous og-us / og-uk selectors. Test whichever public contract is chosen.
• Never label OG-UK as UK + US or treat the two calibrations as interchangeable.
• Record ogusa, ogcore, adapter, tax-calculator and calibration-data versions separately in provenance.

2. Start with a public-data profile

• Establish a clean installation using pip install ogusa==0.4.0 (or a reviewed commit pin).
• Run the baseline from packaged/public CPS calibration without PUF, TMD or private credentials.
• State exactly which CPS, SCF, PSID, demographic, FRED and Tax-Calculator inputs are read, including dates and hashes where feasible.
• Keep PUF/TMD profiles optional and local; tests requiring restricted data must be separated from the public acceptance gate.
• Fail with actionable errors when an optional API key or restricted dataset is requested.

3. Build the adapter beside the OG-UK adapter

Use the existing OG-UK section in integration/src/policyengine_macro/core.py and integration/tests/test_og.py as the structural reference, not as code to generalize prematurely.

• Add lazy _import_ogusa() loading with an exact installation error.
• Add a cached US baseline keyed by every result-changing input: start year, dataset profile, model dimensions, solver configuration, policy baseline and source revision.
• Implement an initial steady-state-only adapter; expose transition paths only after runtime, storage and schema review.
• Return baseline and reform solver residuals/convergence status. A non-converged solve must fail, not serialize a plausible-looking result.
• Map OG-USA/OG-Core outputs into the common ScoreResult without dropping native output.
• Declare USD units, price basis, annual/steady-state time basis, geography, baseline definition, uncertainty and comparability on every quantity.
• Preserve GDP, consumption, investment, wages, interest rates, government debt and tax-revenue outputs where supported; do not invent a quantity merely to match OG-UK.

4. Use a reviewed reform bridge

OG-USA currently calibrates federal taxes through Tax-Calculator, while PolicyEngine Macro accepts PolicyEngine reform objects. Similar names do not establish equivalent definitions.

• Create a small, versioned catalogue of reviewed PolicyEngine-US → OG-USA/Tax-Calculator mappings.
• For each mapping, declare source path, destination parameter, units, effective date, federal/state scope, transformation and tests.
• Initially support only reforms whose semantics can be shown equivalent. Reject every unsupported path with an explanation and list of supported examples.
• Do not use an LLM or fuzzy name matching to invent mappings or unit conversions.
• Provide a separate expert escape hatch for direct OG-Core specification overrides; label these structural scenarios rather than PolicyEngine reform scores.
• Do not pass state or local tax reforms into a federal OG-USA calibration unless an explicit model channel exists.

5. Access and runtime policy

• Benchmark cold import, calibration, baseline steady state, reform steady state and full TPI separately on representative hardware.
• Launch as local/experimental unless a steady-state pair fits hosted limits with safe memory, timeout and cost headroom.
• If custom hosted runs exceed synchronous limits, use asynchronous jobs or precomputed reviewed scenarios; do not raise Modal timeout indefinitely.
• Cache only immutable, provenance-keyed baselines. Never share a baseline across vintages or calibration profiles.

Verification and acceptance gates

Fast contract tests

• Mocked baseline/reform calls verify routing, caching, schema, units and provenance.
• Tests reject unsupported reforms, wrong geography, missing data, failed convergence and mismatched units.
• Capability registry, CLI, MCP and website claims are generated from or tested against the same metadata.
• og-uk behavior remains unchanged.

Real public-data benchmark

• In a clean Python 3.12 environment, install the documented dependencies and run one CPS-profile baseline plus one small reviewed reform.
• Reproduce a frozen upstream OG-USA example or published fixture at declared tolerances.
• Store immutable expected outputs, upstream commit/package versions, data manifests, runtime and solver residuals.
• Run this benchmark on a scheduled/manual workflow where failure fails rather than skips.

Economic validation

• Publish achieved-versus-target calibration moments.
• Label matched targets as calibration by construction, not outcome validation.
• Add at least one independent published US reform benchmark before promoting beyond experimental.
• Report sensitivity to closure rule, Frisch elasticity, discount factors, tax-function profile and foreign-capital assumptions.
• Do not claim forecasting validity: OG-USA is a structural fiscal counterfactual model.

Product and documentation

• Add OG-USA to the capability registry with US geography, supported questions, unsupported uses, access, runtime, data vintage and validation status.
• Present OG-UK and OG-USA as two country calibrations in the OLG family, not one cross-country model.
• Add CLI examples for the public baseline, one reviewed PolicyEngine-US reform and one direct structural scenario.
• Document private-data boundaries and reproducibility differences between public CPS and restricted PUF/TMD profiles.
• Update model, comparison, validation and paper surfaces only after the corresponding executable capability exists.

Definition of done

• A clean public-data installation executes an OG-USA baseline and one reviewed reform.
• The output satisfies the common result/provenance schema with explicit USD units and steady-state horizon.
• Unsupported PolicyEngine-US reforms are refused rather than guessed.
• Solver convergence, calibration targets, source versions and runtime are visible.
• A frozen upstream replication and an independent US benchmark are published.
• OG-UK remains intact and country routing is unambiguous.
• Access is labelled local/experimental unless hosted feasibility is demonstrated.

Related: #69, #71. This implements the OG-USA direction originally suggested during the PolicyEngine Macro architecture review.