diff --git a/.github/workflows/v2-integration-check.yml b/.github/workflows/v2-integration-check.yml index 0894c0ff4..58b557758 100644 --- a/.github/workflows/v2-integration-check.yml +++ b/.github/workflows/v2-integration-check.yml @@ -73,12 +73,12 @@ jobs: run: uv run --frozen --extra dev python scripts/reconcile_v2_privileges.py apply --create-missing-roles - name: Verify the managed v2 roles hold their declared privileges run: uv run --frozen --extra dev python scripts/reconcile_v2_privileges.py verify - - name: Test v2 metadata publication, resource routes and the countries list - run: uv run --frozen --extra dev coverage run --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_catalog_publication_time_periods.py tests/integration/test_v2_catalog_publication_pruning.py tests/integration/test_v2_catalog_spm_availability.py tests/integration/test_v2_metadata_routes.py tests/integration/test_v2_country_routes.py + - name: Test v2 metadata publication, resource routes, the countries list, reports and simulations + run: uv run --frozen --extra dev coverage run --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_catalog_publication_time_periods.py tests/integration/test_v2_catalog_publication_pruning.py tests/integration/test_v2_catalog_spm_availability.py tests/integration/test_v2_metadata_routes.py tests/integration/test_v2_country_routes.py tests/integration/test_v2_report_reads.py tests/integration/test_v2_report_creation.py - name: Test v2 policy persistence and immediate v1 mirroring run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_policy_persistence.py tests/integration/test_v1_policy_dual_write.py tests/integration/test_mysql_policy_dual_write.py tests/integration/test_v2_user_policy_mirroring.py tests/integration/test_v1_user_policy_dual_write.py - - name: Test signed-in identity provisioning, user associations and user types - run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_user_identity_persistence.py tests/integration/test_v2_user_type_persistence.py + - name: Test signed-in identity provisioning, user associations, saved detailed-save records and user types + run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_user_identity_persistence.py tests/integration/test_v2_user_type_persistence.py tests/integration/test_v2_saved_detailed_save_records.py - name: Test comparison-run persistence, the simulation API's roles and privilege reconciliation as the managed roles run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_stage12_comparison_persistence.py tests/integration/test_v2_simulation_role_privileges.py tests/integration/test_v2_privilege_reconciliation.py - name: Test v2 household persistence, immediate v1 copying and household calculation reads diff --git a/changelog.d/v2-simulations-and-reports.added.md b/changelog.d/v2-simulations-and-reports.added.md new file mode 100644 index 000000000..08170aa49 --- /dev/null +++ b/changelog.d/v2-simulations-and-reports.added.md @@ -0,0 +1 @@ +Add `/v2/reports` and `/v2/simulations`: create economy reports and simulations through the simulation service, read a report with its newest run, that run's economy result and the versions the Public API runs, list up to 25 named reports, and read a simulation with its newest run. A create answers 422 when the simulation service refuses the caller's data: its 422, or its 400 with code `unknown_region`, `unknown_dataset` or `unknown_dynamic`. It answers 502 when the simulation service may have created the record but gave no usable answer: its 500, an answer lost after the request may have reached it, a proxy's 502 or 504 in its place, a 503 that cannot be read or that names only another record, any status the Public API does not expect (such as 200, 204 or 409, which the simulation service's route may answer after writing rows), or a created answer that cannot be read. For all but the last, the message asks the caller to submit again and says that this creates a second record if the first request went through. A created record that cannot be read back also answers 502, with its `report_id` or `simulation_id`. It answers 503, and the simulation service has created nothing, when the request was never sent (no connection made, no gateway token, or the simulation service not configured); when the simulation service answers a readable 503 naming no record, a 400 with any other code or none, a 400 or 422 that cannot be read, or 401, 403, 404, 405, 413 or 429, which are sent before its route runs; and when the v2 database is not configured or cannot be read for the checks. A readable 400's or 422's message gives the simulation service's code, when it has one, and its reason, but not its status. The message for any other answer gives the simulation service's status and code, as in `503 modal_call_refused`, but never its reason, since a 500's or 503's may be an exception's text; a code that isn't a fixed identifier (lower-case letters, digits and underscores, starting with a letter, at most 64 characters) is left out. A 503 for a record the service created and whose run it then failed gives that record's `report_id` or `simulation_id`. Saved reports and simulations now also take a detailed-save `report_id` or `simulation_id`, but not together with a v1 number. diff --git a/docs/engineering/migration-contracts.md b/docs/engineering/migration-contracts.md index 1529b4d14..d9f04b4bd 100644 --- a/docs/engineering/migration-contracts.md +++ b/docs/engineering/migration-contracts.md @@ -7,8 +7,8 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | Metric | Count | | --- | ---: | | route group count | 9 | -| workflow count | 17 | -| request count | 92 | +| workflow count | 18 | +| request count | 97 | | db entity count | 6 | | sim flow count | 3 | @@ -23,7 +23,7 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | `household` | `household`, `households`, `household-calculations`, `user-household`, `user-households`, `calculate`, `calculate-full` | `household` | `household` | | `economy` | `economy` | `simulation` | `economy` | | `simulation` | `simulation`, `simulations`, `user-simulations` | `simulation` | `economy` | -| `report` | `report`, `user-reports`, `shared-reports` | `report` | `report` | +| `report` | `report`, `reports`, `user-reports`, `shared-reports` | `report` | `report` | | `user_profile` | `user-profile`, `me`, `admin` | `user` | `none` | ## App V2 Workflow Contracts @@ -126,12 +126,12 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | `POST` | `/v2/user-simulations?country_id=us` | 201 | `simulation` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.simulation_id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-simulations/{association_id}?country_id=us` | 200 | `simulation` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.simulation_id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-simulations?country_id=us` | 200 | `simulation` | `Authorization` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` | -| `PATCH` | `/v2/user-simulations/{association_id}?country_id=us` | 200 | `simulation` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` | +| `PATCH` | `/v2/user-simulations/{association_id}?country_id=us` | 200 | `simulation` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.simulation_id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` | | `DELETE` | `/v2/user-simulations/{association_id}?country_id=us` | 204 | `simulation` | `Authorization` | | | `POST` | `/v2/user-simulations?country_id=us` | 201 | `simulation` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.simulation_id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-simulations/{association_id}?country_id=us` | 200 | `simulation` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.simulation_id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-simulations?country_id=us` | 200 | `simulation` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` | -| `PATCH` | `/v2/user-simulations/{association_id}?country_id=us` | 200 | `simulation` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` | +| `PATCH` | `/v2/user-simulations/{association_id}?country_id=us` | 200 | `simulation` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.simulation_id`, `result.item.legacy_simulation_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` | | `DELETE` | `/v2/user-simulations/{association_id}?country_id=us` | 204 | `simulation` | `PolicyEngine-Unauthenticated-User` | | ### `user_report_associations_v2` @@ -144,14 +144,14 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | `POST` | `/v2/user-reports?country_id=us` | 201 | `report` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-reports/{association_id}?country_id=us` | 200 | `report` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-reports?country_id=us` | 200 | `report` | `Authorization` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` | -| `PATCH` | `/v2/user-reports/{association_id}?country_id=us` | 200 | `report` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.updated_at` | +| `PATCH` | `/v2/user-reports/{association_id}?country_id=us` | 200 | `report` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.updated_at` | | `DELETE` | `/v2/user-reports/{association_id}?country_id=us` | 204 | `report` | `Authorization` | | | `POST` | `/v2/user-reports?country_id=us` | 201 | `report` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-reports/{association_id}?country_id=us` | 200 | `report` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.created_at`, `result.item.updated_at` | | `GET` | `/v2/user-reports?country_id=us` | 200 | `report` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` | -| `PATCH` | `/v2/user-reports/{association_id}?country_id=us` | 200 | `report` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.updated_at` | +| `PATCH` | `/v2/user-reports/{association_id}?country_id=us` | 200 | `report` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.description`, `result.item.user_policy_id`, `result.item.baseline_user_policy_id`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.last_run_at`, `result.item.updated_at` | | `DELETE` | `/v2/user-reports/{association_id}?country_id=us` | 204 | `report` | `PolicyEngine-Unauthenticated-User` | | -| `GET` | `/v2/shared-reports/{association_id}?country_id=us` | 200 | `report` | none | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.baseline_reform`, `result.item.last_run_at`, `result.item.created_at`, `result.item.updated_at` | +| `GET` | `/v2/shared-reports/{association_id}?country_id=us` | 200 | `report` | none | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.report_id`, `result.item.legacy_report_id`, `result.item.name`, `result.item.source_note`, `result.item.provisions`, `result.item.validation`, `result.item.budget_window_years`, `result.item.baseline_reform`, `result.item.last_run_at`, `result.item.created_at`, `result.item.updated_at` | ### `user_account_v2` @@ -197,6 +197,19 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | --- | --- | ---: | --- | --- | --- | | `GET` | `/v2/countries` | 200 | `metadata` | none | `status`, `message`, `result.items` | +### `detailed_save_reports_v2` + +- Current contract: `typed_v2_resources` +- Future owner: C1 · 8: v2 simulations and economy reports + +| Method | Path | Status | Route group | Required headers | Stable response fields | +| --- | --- | ---: | --- | --- | --- | +| `POST` | `/v2/reports?country_id=us` | 201 | `report` | none | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.kind`, `result.item.status`, `result.item.run`, `result.item.current_versions`, `result.item.result` | +| `GET` | `/v2/reports?country_id=us&report_id={report_id}` | 200 | `report` | none | `status`, `message`, `result.items` | +| `GET` | `/v2/reports/{report_id}?country_id=us` | 200 | `report` | none | `status`, `message`, `result.item.id`, `result.item.status`, `result.item.run`, `result.item.current_versions`, `result.item.result` | +| `POST` | `/v2/simulations?country_id=us` | 201 | `simulation` | none | `status`, `message`, `result.item.id`, `result.item.kind`, `result.item.status`, `result.item.run` | +| `GET` | `/v2/simulations/{simulation_id}?country_id=us` | 200 | `simulation` | none | `status`, `message`, `result.item.id`, `result.item.status`, `result.item.run`, `result.item.current_versions` | + ### `metadata_resources_v2_preview` - Current contract: `typed_v2_resources` diff --git a/docs/generated/migration_contracts.json b/docs/generated/migration_contracts.json index 15e622f8d..6eca98bb9 100644 --- a/docs/generated/migration_contracts.json +++ b/docs/generated/migration_contracts.json @@ -1,10 +1,10 @@ { "metadata": { "db_entity_count": 6, - "request_count": 92, + "request_count": 97, "route_group_count": 9, "sim_flow_count": 3, - "workflow_count": 17 + "workflow_count": 18 }, "route_groups": [ { @@ -93,6 +93,7 @@ "name": "report", "path_segments": [ "report", + "reports", "user-reports", "shared-reports" ], @@ -800,6 +801,7 @@ "status", "message", "result.item.id", + "result.item.simulation_id", "result.item.legacy_simulation_id", "result.item.name", "result.item.description", @@ -889,6 +891,7 @@ "status", "message", "result.item.id", + "result.item.simulation_id", "result.item.legacy_simulation_id", "result.item.name", "result.item.description", @@ -999,6 +1002,7 @@ "status", "message", "result.item.id", + "result.item.report_id", "result.item.legacy_report_id", "result.item.name", "result.item.description", @@ -1109,6 +1113,7 @@ "status", "message", "result.item.id", + "result.item.report_id", "result.item.legacy_report_id", "result.item.name", "result.item.description", @@ -1143,6 +1148,7 @@ "message", "result.item.id", "result.item.country_id", + "result.item.report_id", "result.item.legacy_report_id", "result.item.name", "result.item.source_note", @@ -1366,6 +1372,89 @@ } ] }, + { + "current_contract": "typed_v2_resources", + "future_owner_pr": "C1 \u00b7 8: v2 simulations and economy reports", + "name": "detailed_save_reports_v2", + "requests": [ + { + "expected_status": 201, + "headers": [], + "method": "POST", + "path": "/v2/reports?country_id=us", + "route_group": "report", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.country_id", + "result.item.kind", + "result.item.status", + "result.item.run", + "result.item.current_versions", + "result.item.result" + ] + }, + { + "expected_status": 200, + "headers": [], + "method": "GET", + "path": "/v2/reports?country_id=us&report_id={report_id}", + "route_group": "report", + "stable_response_fields": [ + "status", + "message", + "result.items" + ] + }, + { + "expected_status": 200, + "headers": [], + "method": "GET", + "path": "/v2/reports/{report_id}?country_id=us", + "route_group": "report", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.status", + "result.item.run", + "result.item.current_versions", + "result.item.result" + ] + }, + { + "expected_status": 201, + "headers": [], + "method": "POST", + "path": "/v2/simulations?country_id=us", + "route_group": "simulation", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.kind", + "result.item.status", + "result.item.run" + ] + }, + { + "expected_status": 200, + "headers": [], + "method": "GET", + "path": "/v2/simulations/{simulation_id}?country_id=us", + "route_group": "simulation", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.status", + "result.item.run", + "result.item.current_versions" + ] + } + ] + }, { "current_contract": "typed_v2_resources", "future_owner_pr": "Later metadata read cutover and v2 route-prefix removal", diff --git a/docs/migration/stage-12a-user-login.md b/docs/migration/stage-12a-user-login.md index 00102d271..7d6f00d1d 100644 --- a/docs/migration/stage-12a-user-login.md +++ b/docs/migration/stage-12a-user-login.md @@ -404,9 +404,9 @@ contract shared with `policyengine-app-v2`. The generated route inventory is in A saved report's ID is its shareable link, so `GET /v2/shared-reports/{id}` takes no credential and sits outside the authenticated user-report router. It -never provisions a user. Its item is `{id, country_id, legacy_report_id, name, -source_note, provisions, validation, budget_window_years, baseline_reform, -last_run_at, created_at, updated_at}`: +never provisions a user. Its item is `{id, country_id, report_id, +legacy_report_id, name, source_note, provisions, validation, +budget_window_years, baseline_reform, last_run_at, created_at, updated_at}`: - `user_id`, `user_policy_id`, and `baseline_user_policy_id` are left out; the owner and the owner's saved reforms stay private. @@ -417,6 +417,26 @@ last_run_at, created_at, updated_at}`: provisions. There is no shared list or search, and the owner routes stay owner-scoped. +### Saved detailed-save simulations and reports + +`POST` and `PATCH` on `/v2/user-simulations` and `/v2/user-reports` take a +detailed-save `simulation_id` or `report_id` beside the v1 +`legacy_simulation_id` and `legacy_report_id`: + +- A saved report names a report stored in its country (`reports.country`), + and a saved simulation a simulation of its country's model + (`policyengine-`); any other is 404. The check is a `SELECT` in the + write's own transaction. B1 · 11's `RESTRICT` foreign keys refuse a record + deleted between the check and the write, and that SQLSTATE 23503 on the key + is answered as 404 too. +- v1 report and simulation numbers are not connected to detailed-save + records, so a request naming both kinds of reference, or an update that + would leave a saved record naming both, is 400. Only the production + migration writes saved records holding both. A record holding both can + still be renamed. +- Neither reference can be cleared. No route looks a detailed-save record up + by its v1 number, and no read starts a run. + `MeItem` is `{id, user_type, primary_country, first_name, last_name, email, created_at}`; `user_type` is `unauthenticated` or the signed-in user's stored type (`standard`, `author` or `admin`), and @@ -861,5 +881,5 @@ The disposable-Postgres suite proves the following: - A retention policy for unauthenticated users whose browsers never return. Nothing expires them today. - An explicit claim flow for legacy-app users (`POST /v2/me/legacy-claims`). -- Accepting v2 `simulation_id` / `report_id` once the Simulation Entrypoint owns - those records. +- Saved simulations and reports have accepted detailed-save `simulation_id` and + `report_id` since C1 · 8; see "Saved detailed-save simulations and reports". diff --git a/policyengine_api/fastapi_routes/dependencies.py b/policyengine_api/fastapi_routes/dependencies.py index da87826aa..8b016dd70 100644 --- a/policyengine_api/fastapi_routes/dependencies.py +++ b/policyengine_api/fastapi_routes/dependencies.py @@ -10,6 +10,7 @@ from fastapi import Depends, Request from fastapi.security import APIKeyHeader, HTTPAuthorizationCredentials, HTTPBearer +from policyengine_api.constants import COUNTRY_PACKAGE_VERSIONS, POLICYENGINE_VERSION from policyengine_api.fastapi_routes.metadata_protocols import ( MetadataReader, V2MetadataResourceReader, @@ -20,6 +21,8 @@ V2HouseholdCalculationResourceService, V2HouseholdResourceService, V2PolicyResourceService, + V2StoredReportResourceService, + V2StoredSimulationResourceService, V2UserHouseholdResourceService, V2UserPolicyResourceService, V2UserReportResourceService, @@ -44,6 +47,7 @@ from policyengine_api.services.v2.metadata.process_state import ( SelectedCatalogStore, ) +from policyengine_api.services.v2.simulation_service.types import PackageVersions from policyengine_api.services.v2.user_types.types import UserProfileSource if TYPE_CHECKING: @@ -55,6 +59,9 @@ from policyengine_api.services.v2.identity.types import ( AccountPrincipal, ) + from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceClient, + ) __all__ = [ "MetadataReader", @@ -66,6 +73,8 @@ "V2HouseholdResourceService", "V2MetadataResourceReader", "V2PolicyResourceService", + "V2StoredReportResourceService", + "V2StoredSimulationResourceService", "V2UserHouseholdResourceService", "V2UserPolicyResourceService", "V2UserReportResourceService", @@ -201,6 +210,68 @@ def _default_v2_household_calculation_service_factory() -> ( ) +def _current_package_versions(country_id: str) -> PackageVersions: + """Return the country package and .py versions this process runs.""" + return PackageVersions( + country_package_version=COUNTRY_PACKAGE_VERSIONS[country_id], + policyengine_version=POLICYENGINE_VERSION, + ) + + +def _default_simulation_submissions() -> SimulationServiceClient: + """Check submissions, then send them to the configured simulation service.""" + from policyengine_api.libs.simulation_reports import ( + process_simulation_service_client, + ) + from policyengine_api.services.v2.simulation_service.services import ( + SimulationSubmissionService, + ) + + return SimulationSubmissionService( + countries=_default_v2_country_service_factory(), + policies=_default_v2_policy_service_factory(), + client_factory=process_simulation_service_client, + ) + + +def _default_v2_stored_report_service_factory() -> V2StoredReportResourceService: + from policyengine_api.data.v2.database import ( + get_v2_session_factory, + ) + from policyengine_api.services.v2.stored_reports.database_session import ( + StoredReportDatabaseSession, + ) + from policyengine_api.services.v2.stored_reports.services import ( + V2StoredReportService, + ) + + return V2StoredReportService( + StoredReportDatabaseSession(get_v2_session_factory()), + current_versions=_current_package_versions, + submissions=_default_simulation_submissions(), + ) + + +def _default_v2_stored_simulation_service_factory() -> ( + V2StoredSimulationResourceService +): + from policyengine_api.data.v2.database import ( + get_v2_session_factory, + ) + from policyengine_api.services.v2.stored_simulations.database_session import ( + StoredSimulationDatabaseSession, + ) + from policyengine_api.services.v2.stored_simulations.services import ( + V2StoredSimulationService, + ) + + return V2StoredSimulationService( + StoredSimulationDatabaseSession(get_v2_session_factory()), + current_versions=_current_package_versions, + submissions=_default_simulation_submissions(), + ) + + _user_bearer_scheme = HTTPBearer( auto_error=False, scheme_name="UserAccessToken", @@ -398,6 +469,12 @@ class NativeRouteDependencies: v2_household_calculation_service_factory: ( Callable[[], V2HouseholdCalculationResourceService] | None ) = None + v2_stored_report_service_factory: ( + Callable[[], V2StoredReportResourceService] | None + ) = None + v2_stored_simulation_service_factory: ( + Callable[[], V2StoredSimulationResourceService] | None + ) = None v2_user_policy_service_factory: Callable[[], V2UserPolicyResourceService] | None = ( None ) @@ -436,6 +513,10 @@ def defaults(cls) -> NativeRouteDependencies: v2_household_calculation_service_factory=( _default_v2_household_calculation_service_factory ), + v2_stored_report_service_factory=_default_v2_stored_report_service_factory, + v2_stored_simulation_service_factory=( + _default_v2_stored_simulation_service_factory + ), v2_user_policy_service_factory=(_default_v2_user_policy_service_factory), v2_user_household_service_factory=( _default_v2_user_household_service_factory diff --git a/policyengine_api/fastapi_routes/resource_service_protocols.py b/policyengine_api/fastapi_routes/resource_service_protocols.py index 9c9e116c3..a82265a82 100644 --- a/policyengine_api/fastapi_routes/resource_service_protocols.py +++ b/policyengine_api/fastapi_routes/resource_service_protocols.py @@ -5,6 +5,7 @@ from typing import TYPE_CHECKING, Protocol if TYPE_CHECKING: + from collections.abc import Sequence from uuid import UUID from policyengine_api.data.v2.models import UserType @@ -30,6 +31,15 @@ NativePolicyCreation, NativePolicyCreationInput, ) + from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + ) + from policyengine_api.services.v2.stored_reports.types import ( + ReportRead, + ReportSummaryRead, + ) + from policyengine_api.services.v2.stored_simulations.types import SimulationRead from policyengine_api.services.v2.user_accounts.types import ( AccountDeletion, AccountExport, @@ -177,6 +187,55 @@ def get_calculation(self, calculation_id: UUID) -> HouseholdCalculationRead: ... +class V2StoredReportResourceService(Protocol): + """Route-independent report operations for one request.""" + + def get_report(self, *, country_id: str, report_id: UUID) -> ReportRead: + """Return the country's economy report, its newest run and that run's result. + + Raise ``StoredReportNotFoundError`` when the country has no such + report, ``ReportKindUnsupportedError`` for a household report or + budget window, and ``EconomyResultUnreadableError`` when a succeeded + run's result cannot be read. + """ + ... + + def list_reports( + self, *, country_id: str, report_ids: Sequence[UUID] + ) -> tuple[ReportSummaryRead, ...]: + """Return the country's economy reports among ``report_ids``, in that order.""" + ... + + def create_report(self, report_input: EconomyReportCreationInput) -> ReportRead: + """Create the report through the simulation service; return it as stored. + + Raise ``EconomyCalculationsUnsupportedError`` for a country without + economy reports, ``PolicyNotFoundError`` for a policy the country + does not store, and the simulation service's errors. + """ + ... + + +class V2StoredSimulationResourceService(Protocol): + """Route-independent simulation operations for one request.""" + + def get_simulation(self, *, country_id: str, simulation_id: UUID) -> SimulationRead: + """Return the country's simulation and its newest run. + + Raise ``StoredSimulationNotFoundError`` when there is none. + """ + ... + + def create_simulation( + self, simulation_input: EconomySimulationCreationInput + ) -> SimulationRead: + """Create the simulation through the simulation service; return it as stored. + + Raise as ``V2StoredReportResourceService.create_report`` does. + """ + ... + + class V2UserPolicyResourceService(Protocol): """Route-independent user-policy operations for one request.""" diff --git a/policyengine_api/fastapi_routes/v2/household_calculations/routes.py b/policyengine_api/fastapi_routes/v2/household_calculations/routes.py index 74ed0ebec..f78611256 100644 --- a/policyengine_api/fastapi_routes/v2/household_calculations/routes.py +++ b/policyengine_api/fastapi_routes/v2/household_calculations/routes.py @@ -39,12 +39,6 @@ ) from policyengine_api.observability.identifiers import OBSERVABILITY_ID_HEADER from policyengine_api.request_context import current_observability_id -from policyengine_api.services.v2.household_calculations.types import ( - SimulationServiceAnswerUnreadableError, - SimulationServiceInternalError, - SimulationServiceInvalidRequestError, - SimulationServiceUnavailableError, -) from policyengine_api.services.v2.household_calculations.validators import ( HouseholdCalculationCountryError, HouseholdCalculationNotFoundError, @@ -57,6 +51,12 @@ PolicyNotFoundError, PolicyParametersMissingError, ) +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceAnswerUnreadableError, + SimulationServiceInternalError, + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, +) if TYPE_CHECKING: from collections.abc import Callable diff --git a/policyengine_api/fastapi_routes/v2/reports/__init__.py b/policyengine_api/fastapi_routes/v2/reports/__init__.py new file mode 100644 index 000000000..1eb60c589 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/reports/__init__.py @@ -0,0 +1 @@ +"""FastAPI adapters for v2 reports.""" diff --git a/policyengine_api/fastapi_routes/v2/reports/request_models.py b/policyengine_api/fastapi_routes/v2/reports/request_models.py new file mode 100644 index 000000000..836d8106b --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/reports/request_models.py @@ -0,0 +1,14 @@ +"""Strict HTTP request models for v2 reports.""" + +from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, +) + + +class ReportCreateRequest(EconomyReportCreationInput): + """An economy report to create; ``country_id`` must match the query's. + + Each simulation's empty object is current law. No field names a + PolicyEngine.py version: the simulation service runs its default + worker's. + """ diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py new file mode 100644 index 000000000..10f80261a --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -0,0 +1,230 @@ +"""Strict HTTP response models for v2 reports.""" + +from __future__ import annotations + +from datetime import datetime +from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, JsonValue + +from policyengine_api.fastapi_routes.v2.errors_support import V2ErrorResponse +from policyengine_api.fastapi_routes.v2.simulation_resources_support import ( + error_response, +) +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResult, +) + +if TYPE_CHECKING: + from policyengine_api.services.v2.stored_reports.types import ( + ReportRead, + ReportSummaryRead, + ) + + +class StrictReportAPIModel(BaseModel): + """Strict response base that converts the service's dataclass reads.""" + + model_config = ConfigDict(extra="forbid", from_attributes=True) + + +class PackageVersionsItem(StrictReportAPIModel): + """A country package version and the PolicyEngine.py version beside it.""" + + country_package_version: str + policyengine_version: str + + +class ReportRunItem(StrictReportAPIModel): + """One calculation of a report, on one country package and .py version. + + ``status`` is ``pending``, ``running``, ``succeeded`` or ``failed``, and + ``error_message`` says why a failed run failed. ``trigger`` is + ``initial`` for the run the report's creation started. + """ + + id: UUID + status: Literal["pending", "running", "succeeded", "failed"] + trigger: Literal["initial", "manual", "system"] + country_package_version: str + policyengine_version: str + baseline_simulation_run_id: UUID + reform_simulation_run_id: UUID | None + error_message: str | None + created_at: datetime + started_at: datetime | None + completed_at: datetime | None + + +class ReportSimulationItem(StrictReportAPIModel): + """A simulation a report compares; a null policy or dynamic is current law.""" + + id: UUID + policy_id: UUID | None + dynamic_id: UUID | None + + +class ReportSummaryItem(StrictReportAPIModel): + """An economy report comparing a baseline and a reform simulation. + + ``status`` is the newest run's, or ``not_run`` for a report with no run. + ``run`` is the newest run, whatever its status and versions; + ``current_versions`` are the versions the Public API runs now, so a + newest run on other versions is out of date. ``options`` are the options + the report was created with. + """ + + id: UUID + country_id: str + kind: Literal["economy"] + label: str + description: str | None + year: int | None + region_code: str | None + dataset_name: str | None + baseline_simulation: ReportSimulationItem | None + reform_simulation: ReportSimulationItem | None + options: dict[str, JsonValue] + created_at: datetime + status: Literal["not_run", "pending", "running", "succeeded", "failed"] + run: ReportRunItem | None + current_versions: PackageVersionsItem + + @classmethod + def from_summary(cls, read: ReportSummaryRead) -> ReportSummaryItem: + """Build the summary from the service's read, without a result.""" + return cls.model_validate(read) + + +class ReportItem(ReportSummaryItem): + """An economy report with its newest run's result. + + ``result`` is the single-year economy result, in the format the app reads + today, once the newest run has succeeded, and null otherwise. + """ + + result: EconomyResult | None + + @classmethod + def from_read(cls, read: ReportRead) -> ReportItem: + """Build the item from the service's read, with its result.""" + return cls.model_validate(read) + + +class ReportDetailResult(StrictReportAPIModel): + """Result holding one report in ``item``.""" + + item: ReportItem + + +class ReportListResult(StrictReportAPIModel): + """The listed reports in ``items``, in the order named, without results.""" + + items: list[ReportSummaryItem] + + +ResultT = TypeVar("ResultT") + + +class ReportSuccessResponse(StrictReportAPIModel, Generic[ResultT]): + """Success envelope: ``status`` "ok", a null ``message`` and the ``result``.""" + + status: Literal["ok"] = "ok" + message: None = None + result: ResultT + + +class ReportDetailResponse(ReportSuccessResponse[ReportDetailResult]): + """Success response holding one report.""" + + +class ReportListResponse(ReportSuccessResponse[ReportListResult]): + """Success response holding the listed reports.""" + + +class CreatedReportUnreadableResponse(V2ErrorResponse): + """The 502 answer when the created report cannot be read back. + + The simulation service created ``report_id``, so the caller reads it + with ``GET /v2/reports/{report_id}`` rather than submitting it again. + """ + + report_id: UUID + + +class UnavailableAfterReportCreatedResponse(V2ErrorResponse): + """The 503 answer when the simulation service failed a new report's run. + + The message gives the service's status and code. ``report_id`` names the + report, which ``GET /v2/reports/{report_id}`` reads with its failed run. + """ + + report_id: UUID + + +# Every report route can answer these. +REPORT_ERROR_RESPONSES: dict[int | str, dict[str, Any]] = { + 422: error_response("The request does not match the schema."), + 500: error_response("The operation could not be completed."), + 503: error_response("The v2 database or the simulation service is unavailable."), +} +READ_RESPONSES: dict[int | str, dict[str, Any]] = { + 404: error_response("No report has this ID in this country."), + 422: error_response( + "The request does not match the schema, or the report is a household " + "report or a budget window, which this route does not read yet." + ), + 500: error_response( + "The newest run succeeded but its stored result cannot be read, or the " + "operation could not be completed." + ), +} +CREATE_RESPONSES: dict[int | str, dict[str, Any]] = { + 400: error_response("The body and query name different countries."), + 404: error_response("A policy the report names is not stored in the country."), + 413: error_response("The request body exceeds 16 KiB."), + 422: error_response( + "The request does not match the schema, the country has no economy " + "reports (such as a household-only country), or the simulation service " + "cannot run the report: its 422, or its 400 for a region, dataset or " + "dynamic it does not have. The message says which; for the simulation " + "service's refusal, it gives the service's code, when it gave one, and " + "its reason, but not its status." + ), + 502: { + "model": V2ErrorResponse | CreatedReportUnreadableResponse, + "description": ( + "The simulation service may have created the report, but its answer does " + "not say so. The answer was lost after the request may have reached it, or " + "a proxy in front of it answered 502 or 504 in its place: the message says " + "the service may have received the request, but its answer was lost. Or it " + "failed (500), answered 503 in a shape the Public API cannot read or " + "naming only another record, or answered a status the Public API does not " + "expect, which its route may answer after writing rows: the message says " + "it may have created the report, but failed, with its status and code but " + "not its reason. Either message asks the caller to submit the report " + "again, which creates a second report if the first request went through. " + "Or it created the report, but its answer cannot be read. Or it created " + "the report, but the report cannot be read back: the answer gives its " + "report_id, to read with GET /v2/reports/{report_id} rather than " + "submitting it again." + ), + }, + 503: { + "model": V2ErrorResponse | UnavailableAfterReportCreatedResponse, + "description": ( + "The simulation service created nothing: it cannot be reached or is not " + "configured; it answered a readable 503 naming no record, and the message " + "gives its status and code; it answered a 400 naming no region, dataset or " + "dynamic of the caller's (such as a catalog version missing while a " + "release deploys), and the message gives its code and reason; it " + "answered 400 or 422 in a shape the Public API cannot read; or it answered " + "401, 403, 404, 405, 413 or 429, which are sent before its route runs. Or " + "the v2 database is unavailable. Or the service created the report, then " + "Modal refused the run's call and the service failed the run: its 503 " + "named the report, with its status and code, and the answer gives its " + "report_id." + ), + }, +} diff --git a/policyengine_api/fastapi_routes/v2/reports/routes.py b/policyengine_api/fastapi_routes/v2/reports/routes.py new file mode 100644 index 000000000..89daf7673 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/reports/routes.py @@ -0,0 +1,265 @@ +"""Native FastAPI routes for v2 reports. + +The routes need no user credential: a user keeps a report through +``/v2/user-reports``. Reports, their runs and results are read from the +detailed-save tables the simulation service and its Modal workers write; +reading never calls the simulation service and never starts a run. Creating +a report checks it, has the simulation service create and start it, and +reads it back. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Annotated, TypeVar +from uuid import UUID + +from fastapi import APIRouter, Depends +from starlette.responses import JSONResponse + +from policyengine_api.fastapi_routes.dependencies import ( + _default_v2_stored_report_service_factory, +) +from policyengine_api.fastapi_routes.query_parameters import query_dependency +from policyengine_api.fastapi_routes.v2.errors_support import ( + V2ErrorMapping, + v2_error_response, +) +from policyengine_api.fastapi_routes.v2.reports.request_models import ( + ReportCreateRequest, +) +from policyengine_api.fastapi_routes.v2.reports.response_models import ( + CREATE_RESPONSES, + READ_RESPONSES, + REPORT_ERROR_RESPONSES, + CreatedReportUnreadableResponse, + ReportDetailResponse, + ReportDetailResult, + ReportItem, + ReportListResponse, + ReportListResult, + ReportSummaryItem, + UnavailableAfterReportCreatedResponse, +) +from policyengine_api.fastapi_routes.v2.simulation_resources_support import ( + SUBMISSION_ERROR_MAPPINGS, + SUBMISSION_REFUSALS, + created_record_unreadable_answer, + simulation_resource_operation, + unavailable_after_creation_answer, +) +from policyengine_api.fastapi_routes.v2.user_resources_support import ( + request_size_limit, +) +from policyengine_api.query_parameters import ( + ReportCollectionQuery, + ReportCreateQuery, + ReportDetailQuery, +) +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceUnavailableError, +) +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResultUnreadableError, +) +from policyengine_api.services.v2.stored_reports.validators import ( + CreatedReportUnreadableError, + ReportKindUnsupportedError, + ReportStorageError, + StoredReportNotFoundError, +) + +if TYPE_CHECKING: + from collections.abc import Callable + + from policyengine_api.fastapi_routes.dependencies import ( + NativeRouteDependencies, + V2StoredReportResourceService, + ) + +MAXIMUM_REPORT_REQUEST_BYTES = 16 * 1024 +enforce_report_request_size = request_size_limit( + MAXIMUM_REPORT_REQUEST_BYTES, label="16 KiB" +) +ReportCreateQueryDependency = Annotated[ + ReportCreateQuery, Depends(query_dependency(ReportCreateQuery)) +] +ReportCollectionQueryDependency = Annotated[ + ReportCollectionQuery, Depends(query_dependency(ReportCollectionQuery)) +] +ReportDetailQueryDependency = Annotated[ + ReportDetailQuery, Depends(query_dependency(ReportDetailQuery)) +] + +# Refusals a caller can act on carry their own message and are not logged. +REPORT_REFUSALS: tuple[type[Exception], ...] = ( + StoredReportNotFoundError, + ReportKindUnsupportedError, + *SUBMISSION_REFUSALS, +) +REPORT_ERROR_MAPPINGS = ( + V2ErrorMapping((StoredReportNotFoundError,), 404), + V2ErrorMapping((ReportKindUnsupportedError,), 422), + *SUBMISSION_ERROR_MAPPINGS, + V2ErrorMapping( + (EconomyResultUnreadableError,), + 500, + "The report's stored result cannot be read", + ), + # SUBMISSION_ERROR_MAPPINGS answers a missing v2 database configuration. + V2ErrorMapping((ReportStorageError,), 503, "V2 report storage is unavailable"), +) + + +def _service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2StoredReportResourceService]: + if dependencies.v2_stored_report_service_factory is not None: + return dependencies.v2_stored_report_service_factory + return _default_v2_stored_report_service_factory + + +OperationT = TypeVar("OperationT") + + +def _report_operation( + operation: Callable[[], OperationT], +) -> OperationT | JSONResponse: + return simulation_resource_operation( + operation, + REPORT_ERROR_MAPPINGS, + refusals=REPORT_REFUSALS, + event="v2_report_operation_failed", + fallback_message="V2 report operation failed", + ) + + +def _create_report( + service: V2StoredReportResourceService, body: ReportCreateRequest +) -> ReportDetailResponse | JSONResponse: + """Create the report and answer it as stored. + + A report the simulation service created answers with its ``report_id`` + when it cannot be read back (502), and when the service failed its run + and answered 503. Every other failure is raised, for the route's error + mappings to answer. + """ + try: + report = service.create_report(body) + except CreatedReportUnreadableError as error: + return created_record_unreadable_answer( + "v2_created_report_unreadable", + error, + CreatedReportUnreadableResponse( + message=( + f"The simulation service created report {error.report_id}, " + "but it could not be read back. Read it with GET " + f"/v2/reports/{error.report_id}?country_id={error.country_id} " + "rather than submitting it again." + ), + report_id=error.report_id, + ), + ) + except SimulationServiceUnavailableError as error: + if error.created_record_id is None: + raise + return unavailable_after_creation_answer( + "v2_report_unavailable_after_creation", + error, + UnavailableAfterReportCreatedResponse( + message=str(error), report_id=error.created_record_id + ), + ) + return ReportDetailResponse( + result=ReportDetailResult(item=ReportItem.from_read(report)) + ) + + +def build_v2_report_router(dependencies: NativeRouteDependencies) -> APIRouter: + """Build the report routes without opening a connection.""" + router = APIRouter(prefix="/v2", responses=REPORT_ERROR_RESPONSES) + service_factory = _service_factory(dependencies) + + @router.post( + "/reports", + response_model=ReportDetailResponse, + status_code=201, + responses=CREATE_RESPONSES, + summary="Create an economy report", + description=( + "Checks that the country has economy reports and stores each named " + "policy, then has the simulation service create the report, its two " + "simulations and their runs on its default worker's PolicyEngine.py " + "version, and start the run. Answers the report as stored, with its " + "pending run; read it again to follow the run. A created report " + "that cannot be read back answers 502 with its report_id, and one " + "whose run the simulation service failed before answering 503 " + "answers 503 with its report_id." + ), + ) + def create_report( + body: ReportCreateRequest, + query: ReportCreateQueryDependency, + _size: Annotated[None, Depends(enforce_report_request_size)], + ) -> ReportDetailResponse | JSONResponse: + if body.country_id != query.country_id: + return v2_error_response(400, "Body country_id must match query country_id") + + def create() -> ReportDetailResponse | JSONResponse: + return _create_report(service_factory(), body) + + return _report_operation(create) + + @router.get( + "/reports", + response_model=ReportListResponse, + summary="List chosen economy reports", + description=( + "Lists the country's economy reports among the report_id values (at " + "most 25), in the order named and once each, with their newest runs " + "but without results, read in one query. Unknown reports, other " + "countries' and reports of other kinds are left out." + ), + ) + def list_reports( + query: ReportCollectionQueryDependency, + ) -> ReportListResponse | JSONResponse: + def read() -> ReportListResponse: + reports = service_factory().list_reports( + country_id=query.country_id, report_ids=query.report_id + ) + return ReportListResponse( + result=ReportListResult( + items=[ReportSummaryItem.from_summary(report) for report in reports] + ) + ) + + return _report_operation(read) + + @router.get( + "/reports/{report_id}", + response_model=ReportDetailResponse, + responses=READ_RESPONSES, + summary="Read an economy report", + description=( + "Returns the report, its newest run whatever its status and " + "versions, the versions the Public API runs now, and, once the " + "newest run has succeeded, its result in today's economy result " + "format. A report with no run, such as one migrated from v1, " + "answers its definition with no result; reading starts no run." + ), + ) + def get_report( + report_id: UUID, + query: ReportDetailQueryDependency, + ) -> ReportDetailResponse | JSONResponse: + def read() -> ReportDetailResponse: + report = service_factory().get_report( + country_id=query.country_id, report_id=report_id + ) + return ReportDetailResponse( + result=ReportDetailResult(item=ReportItem.from_read(report)) + ) + + return _report_operation(read) + + return router diff --git a/policyengine_api/fastapi_routes/v2/routes.py b/policyengine_api/fastapi_routes/v2/routes.py index 1153588af..1878b690f 100644 --- a/policyengine_api/fastapi_routes/v2/routes.py +++ b/policyengine_api/fastapi_routes/v2/routes.py @@ -34,6 +34,10 @@ build_v2_metadata_parameter_router, ) from policyengine_api.fastapi_routes.v2.policies.routes import build_v2_policy_router +from policyengine_api.fastapi_routes.v2.reports.routes import build_v2_report_router +from policyengine_api.fastapi_routes.v2.simulations.routes import ( + build_v2_simulation_router, +) from policyengine_api.fastapi_routes.v2.user_households.routes import ( build_v2_user_household_router, ) @@ -67,6 +71,8 @@ def build_v2_router( router.include_router(build_v2_household_router(dependencies)) router.include_router(build_v2_household_calculation_router(dependencies)) router.include_router(build_v2_policy_router(dependencies)) + router.include_router(build_v2_report_router(dependencies)) + router.include_router(build_v2_simulation_router(dependencies)) router.include_router(build_v2_country_router(dependencies)) router.include_router(build_v2_metadata_model_router(dependencies)) router.include_router(build_v2_metadata_parameter_router(dependencies)) diff --git a/policyengine_api/fastapi_routes/v2/simulation_resources_support.py b/policyengine_api/fastapi_routes/v2/simulation_resources_support.py new file mode 100644 index 000000000..bb153ccbc --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/simulation_resources_support.py @@ -0,0 +1,151 @@ +"""HTTP conventions the v2 report and simulation routes share. + +Both read the detailed-save tables and create through the simulation +service. A failure the caller can act on is answered with its own message; +any other is logged by type and the locations of its innermost frames, never +by its message, which can carry bound SQL parameters. +""" + +from __future__ import annotations + +import contextlib +import logging +import traceback +from typing import TYPE_CHECKING, Any, TypeVar + +from starlette.responses import JSONResponse + +from policyengine_api.data.v2.settings import V2ConfigurationError +from policyengine_api.fastapi_routes.v2.errors_support import ( + V2ErrorMapping, + V2ErrorResponse, + run_v2_operation, +) +from policyengine_api.services.v2.policies.validators import PolicyNotFoundError +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceAnswerUnreadableError, + SimulationServiceInternalError, + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, +) +from policyengine_api.services.v2.simulation_service.validators import ( + EconomyCalculationsUnsupportedError, + SubmissionStorageError, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Sequence + + +logger = logging.getLogger(__name__) + +# A submission's refusals a caller can act on carry their own message and are +# not logged. +SUBMISSION_REFUSALS: tuple[type[Exception], ...] = ( + PolicyNotFoundError, + EconomyCalculationsUnsupportedError, + SimulationServiceInvalidRequestError, +) +# How the simulation service's answers and the submission checks are answered. +# The service's failure (500), an unreadable created answer, an answer lost +# after sending, a proxy's 502 or 504, a 503 that cannot be read or names +# only another record, and any status the client does not expect are a 502, +# as for household calculations: the record exists, or may, and a 503 says +# the service created nothing. The message of each but the unreadable +# created answer asks the caller to submit again, and says this creates a +# second record if the first request went through. The service's 503 naming +# the record it created and failed is still a 503, and each create route +# answers it with the record's ID (``unavailable_after_creation_answer``). +SUBMISSION_ERROR_MAPPINGS = ( + V2ErrorMapping((PolicyNotFoundError,), 404), + V2ErrorMapping( + (EconomyCalculationsUnsupportedError, SimulationServiceInvalidRequestError), 422 + ), + V2ErrorMapping( + (SimulationServiceInternalError, SimulationServiceAnswerUnreadableError), 502 + ), + V2ErrorMapping((SimulationServiceUnavailableError,), 503), + V2ErrorMapping( + (V2ConfigurationError, SubmissionStorageError), + 503, + "V2 storage is unavailable", + ), +) + +OperationT = TypeVar("OperationT") + + +def error_response(description: str) -> dict[str, Any]: + """Return an OpenAPI response entry for an API v2 error.""" + return {"model": V2ErrorResponse, "description": description} + + +def _log_failure(event: str, error: Exception) -> None: + """Record a failure's type and innermost frames; logging never fails a request.""" + with contextlib.suppress(Exception): + frames = traceback.extract_tb(error.__traceback__)[-8:] + logger.error( + event, + extra={ + "policyengine_attributes": { + "error_type": type(error).__name__, + "error_frames": "; ".join( + f"{frame.filename.rsplit('/', 1)[-1]}:{frame.lineno} " + f"in {frame.name}" + for frame in frames + ), + } + }, + ) + + +def created_record_unreadable_answer( + event: str, error: Exception, answer: V2ErrorResponse +) -> JSONResponse: + """Log why a created record could not be read back, and answer 502. + + The simulation service created the record, so ``answer`` names it for the + caller to read rather than submit again. The failure logged is the read's + own, ``error``'s cause. + """ + cause = error.__cause__ + _log_failure(event, cause if isinstance(cause, Exception) else error) + return JSONResponse(status_code=502, content=answer.model_dump(mode="json")) + + +def unavailable_after_creation_answer( + event: str, error: Exception, answer: V2ErrorResponse +) -> JSONResponse: + """Log the simulation service's 503 that names a record it created, and answer 503. + + The service created the record, then failed its run, so ``answer`` gives + the record's ID with the service's status and code, but not its reason, + which may be an exception's text. + """ + _log_failure(event, error) + return JSONResponse(status_code=503, content=answer.model_dump(mode="json")) + + +def simulation_resource_operation( + operation: Callable[[], OperationT], + error_mappings: Sequence[V2ErrorMapping], + *, + refusals: tuple[type[Exception], ...], + event: str, + fallback_message: str, +) -> OperationT | JSONResponse: + """Run one service call and answer its failure with a typed v2 error. + + A failure of a type in ``refusals`` is the caller's to act on and is not + logged; any other is logged under ``event``. + """ + + def logged() -> OperationT: + try: + return operation() + except Exception as error: + if not isinstance(error, refusals): + _log_failure(event, error) + raise + + return run_v2_operation(logged, error_mappings, fallback_message=fallback_message) diff --git a/policyengine_api/fastapi_routes/v2/simulations/__init__.py b/policyengine_api/fastapi_routes/v2/simulations/__init__.py new file mode 100644 index 000000000..ef3350fb9 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/simulations/__init__.py @@ -0,0 +1 @@ +"""FastAPI adapters for v2 simulations.""" diff --git a/policyengine_api/fastapi_routes/v2/simulations/request_models.py b/policyengine_api/fastapi_routes/v2/simulations/request_models.py new file mode 100644 index 000000000..610a06a0b --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/simulations/request_models.py @@ -0,0 +1,13 @@ +"""Strict HTTP request models for v2 simulations.""" + +from policyengine_api.services.v2.simulation_service.types import ( + EconomySimulationCreationInput, +) + + +class SimulationCreateRequest(EconomySimulationCreationInput): + """An economy simulation to create; ``country_id`` must match the query's. + + No field names a PolicyEngine.py version: the simulation service runs its + default worker's. + """ diff --git a/policyengine_api/fastapi_routes/v2/simulations/response_models.py b/policyengine_api/fastapi_routes/v2/simulations/response_models.py new file mode 100644 index 000000000..b1b3f75be --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/simulations/response_models.py @@ -0,0 +1,172 @@ +"""Strict HTTP response models for v2 simulations.""" + +from __future__ import annotations + +from datetime import datetime +from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar +from uuid import UUID + +from pydantic import BaseModel, ConfigDict + +from policyengine_api.fastapi_routes.v2.errors_support import V2ErrorResponse +from policyengine_api.fastapi_routes.v2.reports.response_models import ( + PackageVersionsItem, +) +from policyengine_api.fastapi_routes.v2.simulation_resources_support import ( + error_response, +) + +if TYPE_CHECKING: + from policyengine_api.services.v2.stored_simulations.types import SimulationRead + + +class StrictSimulationAPIModel(BaseModel): + """Strict response base that converts the service's dataclass reads.""" + + model_config = ConfigDict(extra="forbid", from_attributes=True) + + +class SimulationRunItem(StrictSimulationAPIModel): + """One calculation of a simulation, for one year on one package version pair.""" + + id: UUID + year: int + status: Literal["pending", "running", "succeeded", "failed"] + country_package_version: str + policyengine_version: str + error_message: str | None + created_at: datetime + started_at: datetime | None + completed_at: datetime | None + + +class SimulationItem(StrictSimulationAPIModel): + """A simulation, its newest run and the versions the Public API runs now. + + A null ``policy_id`` or ``dynamic_id`` is current law. An economy + simulation names its region and dataset, a household simulation its + household. ``status`` is the newest run's, or ``not_run``; a newest run + on other versions than ``current_versions`` is out of date. + """ + + id: UUID + country_id: str + kind: Literal["economy", "household"] + policy_id: UUID | None + dynamic_id: UUID | None + household_id: UUID | None + year: int | None + region_code: str | None + dataset_name: str | None + created_at: datetime + status: Literal["not_run", "pending", "running", "succeeded", "failed"] + run: SimulationRunItem | None + current_versions: PackageVersionsItem + + @classmethod + def from_read(cls, read: SimulationRead) -> SimulationItem: + """Build the item from the service's read.""" + return cls.model_validate(read) + + +class SimulationDetailResult(StrictSimulationAPIModel): + """Result holding one simulation in ``item``.""" + + item: SimulationItem + + +ResultT = TypeVar("ResultT") + + +class SimulationSuccessResponse(StrictSimulationAPIModel, Generic[ResultT]): + """Success envelope: ``status`` "ok", a null ``message`` and the ``result``.""" + + status: Literal["ok"] = "ok" + message: None = None + result: ResultT + + +class SimulationDetailResponse(SimulationSuccessResponse[SimulationDetailResult]): + """Success response holding one simulation.""" + + +class CreatedSimulationUnreadableResponse(V2ErrorResponse): + """The 502 answer when the created simulation cannot be read back. + + The simulation service created ``simulation_id``, so the caller reads it + with ``GET /v2/simulations/{simulation_id}`` rather than submitting it + again. + """ + + simulation_id: UUID + + +class UnavailableAfterSimulationCreatedResponse(V2ErrorResponse): + """The 503 answer when the simulation service failed a new simulation's run. + + The message gives the service's status and code. ``simulation_id`` names + the simulation, which ``GET /v2/simulations/{simulation_id}`` reads with + its failed run. + """ + + simulation_id: UUID + + +SIMULATION_ERROR_RESPONSES: dict[int | str, dict[str, Any]] = { + 422: error_response("The request does not match the schema."), + 500: error_response("The operation could not be completed."), + 503: error_response("The v2 database or the simulation service is unavailable."), +} +READ_RESPONSES: dict[int | str, dict[str, Any]] = { + 404: error_response("No simulation of this country's model has this ID."), +} +CREATE_RESPONSES: dict[int | str, dict[str, Any]] = { + 400: error_response("The body and query name different countries."), + 404: error_response( + "The policy the simulation names is not stored in the country." + ), + 413: error_response("The request body exceeds 16 KiB."), + 422: error_response( + "The request does not match the schema, the country has no economy " + "calculations, or the simulation service cannot run the simulation: " + "its 422, or its 400 for a region, dataset or dynamic it does not " + "have. The message says which; for the simulation service's refusal, " + "it gives the service's code, when it gave one, and its reason, but " + "not its status." + ), + 502: { + "model": V2ErrorResponse | CreatedSimulationUnreadableResponse, + "description": ( + "The simulation service may have created the simulation, but its answer " + "does not say so. The answer was lost after the request may have reached " + "it, or a proxy in front of it answered 502 or 504 in its place: the " + "message says the service may have received the request, but its answer " + "was lost. Or it failed (500), answered 503 in a shape the Public API " + "cannot read or naming only another record, or answered a status the " + "Public API does not expect, which its route may answer after writing " + "rows: the message says it may have created the simulation, but failed, " + "with its status and code but not its reason. Either message asks the " + "caller to submit the simulation again, which creates a second simulation " + "if the first request went through. Or it created the simulation, but its " + "answer cannot be read. Or it created the simulation, but the simulation " + "cannot be read back: the answer gives its simulation_id, to read with GET " + "/v2/simulations/{simulation_id} rather than submitting it again." + ), + }, + 503: { + "model": V2ErrorResponse | UnavailableAfterSimulationCreatedResponse, + "description": ( + "The simulation service created nothing: it cannot be reached or is not " + "configured; it answered a readable 503 naming no record, and the message " + "gives its status and code; it answered a 400 naming no region, dataset or " + "dynamic of the caller's (such as a catalog version missing while a " + "release deploys), and the message gives its code and reason; it " + "answered 400 or 422 in a shape the Public API cannot read; or it answered " + "401, 403, 404, 405, 413 or 429, which are sent before its route runs. Or " + "the v2 database is unavailable. Or the service created the simulation, " + "then Modal refused the run's call and the service failed the run: its 503 " + "named the simulation, with its status and code, and the answer gives its " + "simulation_id." + ), + }, +} diff --git a/policyengine_api/fastapi_routes/v2/simulations/routes.py b/policyengine_api/fastapi_routes/v2/simulations/routes.py new file mode 100644 index 000000000..ceadeaf4c --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/simulations/routes.py @@ -0,0 +1,221 @@ +"""Native FastAPI routes for v2 simulations. + +The routes need no user credential: a user keeps a simulation through +``/v2/user-simulations``. Simulations and their runs are read from the +detailed-save tables the simulation service writes; reading never calls it. +Creating a simulation checks it, has the simulation service create and start +it, and reads it back. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Annotated, TypeVar +from uuid import UUID + +from fastapi import APIRouter, Depends +from starlette.responses import JSONResponse + +from policyengine_api.fastapi_routes.dependencies import ( + _default_v2_stored_simulation_service_factory, +) +from policyengine_api.fastapi_routes.query_parameters import query_dependency +from policyengine_api.fastapi_routes.v2.errors_support import ( + V2ErrorMapping, + v2_error_response, +) +from policyengine_api.fastapi_routes.v2.simulation_resources_support import ( + SUBMISSION_ERROR_MAPPINGS, + SUBMISSION_REFUSALS, + created_record_unreadable_answer, + simulation_resource_operation, + unavailable_after_creation_answer, +) +from policyengine_api.fastapi_routes.v2.simulations.request_models import ( + SimulationCreateRequest, +) +from policyengine_api.fastapi_routes.v2.simulations.response_models import ( + CREATE_RESPONSES, + READ_RESPONSES, + SIMULATION_ERROR_RESPONSES, + CreatedSimulationUnreadableResponse, + SimulationDetailResponse, + SimulationDetailResult, + SimulationItem, + UnavailableAfterSimulationCreatedResponse, +) +from policyengine_api.fastapi_routes.v2.user_resources_support import ( + request_size_limit, +) +from policyengine_api.query_parameters import ( + SimulationCreateQuery, + SimulationDetailQuery, +) +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceUnavailableError, +) +from policyengine_api.services.v2.stored_simulations.validators import ( + CreatedSimulationUnreadableError, + SimulationStorageError, + StoredSimulationNotFoundError, +) + +if TYPE_CHECKING: + from collections.abc import Callable + + from policyengine_api.fastapi_routes.dependencies import ( + NativeRouteDependencies, + V2StoredSimulationResourceService, + ) + +MAXIMUM_SIMULATION_REQUEST_BYTES = 16 * 1024 +enforce_simulation_request_size = request_size_limit( + MAXIMUM_SIMULATION_REQUEST_BYTES, label="16 KiB" +) +SimulationCreateQueryDependency = Annotated[ + SimulationCreateQuery, Depends(query_dependency(SimulationCreateQuery)) +] +SimulationDetailQueryDependency = Annotated[ + SimulationDetailQuery, Depends(query_dependency(SimulationDetailQuery)) +] + +# Refusals a caller can act on carry their own message and are not logged. +SIMULATION_REFUSALS: tuple[type[Exception], ...] = ( + StoredSimulationNotFoundError, + *SUBMISSION_REFUSALS, +) +SIMULATION_ERROR_MAPPINGS = ( + V2ErrorMapping((StoredSimulationNotFoundError,), 404), + *SUBMISSION_ERROR_MAPPINGS, + # SUBMISSION_ERROR_MAPPINGS answers a missing v2 database configuration. + V2ErrorMapping( + (SimulationStorageError,), 503, "V2 simulation storage is unavailable" + ), +) + +OperationT = TypeVar("OperationT") + + +def _service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2StoredSimulationResourceService]: + if dependencies.v2_stored_simulation_service_factory is not None: + return dependencies.v2_stored_simulation_service_factory + return _default_v2_stored_simulation_service_factory + + +def _simulation_operation( + operation: Callable[[], OperationT], +) -> OperationT | JSONResponse: + return simulation_resource_operation( + operation, + SIMULATION_ERROR_MAPPINGS, + refusals=SIMULATION_REFUSALS, + event="v2_simulation_operation_failed", + fallback_message="V2 simulation operation failed", + ) + + +def _create_simulation( + service: V2StoredSimulationResourceService, body: SimulationCreateRequest +) -> SimulationDetailResponse | JSONResponse: + """Create the simulation and answer it as stored. + + A simulation the simulation service created answers with its + ``simulation_id`` when it cannot be read back (502), and when the service + failed its run and answered 503. Every other failure is raised, for the + route's error mappings to answer. + """ + try: + simulation = service.create_simulation(body) + except CreatedSimulationUnreadableError as error: + return created_record_unreadable_answer( + "v2_created_simulation_unreadable", + error, + CreatedSimulationUnreadableResponse( + message=( + f"The simulation service created simulation " + f"{error.simulation_id}, but it could not be read back. Read " + f"it with GET /v2/simulations/{error.simulation_id}" + f"?country_id={error.country_id} rather than submitting it " + "again." + ), + simulation_id=error.simulation_id, + ), + ) + except SimulationServiceUnavailableError as error: + if error.created_record_id is None: + raise + return unavailable_after_creation_answer( + "v2_simulation_unavailable_after_creation", + error, + UnavailableAfterSimulationCreatedResponse( + message=str(error), simulation_id=error.created_record_id + ), + ) + return SimulationDetailResponse( + result=SimulationDetailResult(item=SimulationItem.from_read(simulation)) + ) + + +def build_v2_simulation_router(dependencies: NativeRouteDependencies) -> APIRouter: + """Build the simulation routes without opening a connection.""" + router = APIRouter(prefix="/v2", responses=SIMULATION_ERROR_RESPONSES) + service_factory = _service_factory(dependencies) + + @router.post( + "/simulations", + response_model=SimulationDetailResponse, + status_code=201, + responses=CREATE_RESPONSES, + summary="Create an economy simulation", + description=( + "Checks that the country has economy calculations and stores the " + "named policy, then has the simulation service create the " + "simulation and its first run on its default worker's " + "PolicyEngine.py version, and start the run. Answers the simulation " + "as stored, with its pending run. A created simulation that cannot " + "be read back answers 502 with its simulation_id, and one whose run " + "the simulation service failed before answering 503 answers 503 " + "with its simulation_id." + ), + ) + def create_simulation( + body: SimulationCreateRequest, + query: SimulationCreateQueryDependency, + _size: Annotated[None, Depends(enforce_simulation_request_size)], + ) -> SimulationDetailResponse | JSONResponse: + if body.country_id != query.country_id: + return v2_error_response(400, "Body country_id must match query country_id") + + def create() -> SimulationDetailResponse | JSONResponse: + return _create_simulation(service_factory(), body) + + return _simulation_operation(create) + + @router.get( + "/simulations/{simulation_id}", + response_model=SimulationDetailResponse, + responses=READ_RESPONSES, + summary="Read a simulation", + description=( + "Returns the simulation, its newest run whatever its year, status " + "and versions, and the versions the Public API runs now. A " + "simulation belongs to the country whose model its catalog version " + "is of; reading starts no run." + ), + ) + def get_simulation( + simulation_id: UUID, + query: SimulationDetailQueryDependency, + ) -> SimulationDetailResponse | JSONResponse: + def read() -> SimulationDetailResponse: + simulation = service_factory().get_simulation( + country_id=query.country_id, simulation_id=simulation_id + ) + return SimulationDetailResponse( + result=SimulationDetailResult(item=SimulationItem.from_read(simulation)) + ) + + return _simulation_operation(read) + + return router diff --git a/policyengine_api/fastapi_routes/v2/user_reports/response_models.py b/policyengine_api/fastapi_routes/v2/user_reports/response_models.py index de4be2d19..eaf66b19d 100644 --- a/policyengine_api/fastapi_routes/v2/user_reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/user_reports/response_models.py @@ -127,7 +127,9 @@ class ReportValidationItem(StoredSnapshotItem): class UserReportItem(StrictUserReportAPIModel): """A report saved by a user, with the user's name, notes and saved presentation. - ``legacy_report_id`` is the v1 report output it shows. ``user_policy_id`` is + ``report_id`` is the detailed-save report it shows, and + ``legacy_report_id`` the v1 report output; one of them is set, and only + saved reports the production migration wrote hold both. ``user_policy_id`` is the user's saved reform the report was run from, and ``baseline_user_policy_id`` the saved reform it was compared with instead of current law; each is null when not set or once that reform is deleted. @@ -164,10 +166,15 @@ class SharedBaselineReformItem(StrictUserReportAPIModel): class SharedUserReportItem(StrictUserReportAPIModel): - """A saved report as anyone holding its link reads it.""" + """A saved report as anyone holding its link reads it. + + ``report_id`` is the detailed-save report it shows, and + ``legacy_report_id`` the v1 report output; one of them is set. + """ id: UUID country_id: CountryId + report_id: UUID | None legacy_report_id: int | None name: str | None source_note: str | None diff --git a/policyengine_api/fastapi_routes/v2/user_reports/routes.py b/policyengine_api/fastapi_routes/v2/user_reports/routes.py index 44b7f607b..71dcc56f6 100644 --- a/policyengine_api/fastapi_routes/v2/user_reports/routes.py +++ b/policyengine_api/fastapi_routes/v2/user_reports/routes.py @@ -121,13 +121,16 @@ def build_v2_user_report_router( "/user-reports", response_model=UserReportDetailResponse, status_code=201, - summary="Save a v1 report for the current user", + summary="Save a report for the current user", description=( "Requires a bearer access token or the PolicyEngine-Unauthenticated-User " - "header; the owner is taken from that credential. " - "Stage 12A accepts legacy_report_id only (the requested v1 report " - "output ID), checked in the v1 database. An optional user_policy_id " - "must name the same user's saved policy in the same country." + "header; the owner is taken from that credential. Names a " + "detailed-save report (report_id), which must be stored in the " + "country (404 otherwise), or a v1 report output (legacy_report_id), " + "checked in the v1 database; naming both is refused with 400, since " + "v1 report numbers are not connected to detailed-save reports. An " + "optional user_policy_id must name the same user's saved policy in " + "the same country." ), ) def create_user_report( diff --git a/policyengine_api/fastapi_routes/v2/user_resources_support.py b/policyengine_api/fastapi_routes/v2/user_resources_support.py index c862ed405..81859a384 100644 --- a/policyengine_api/fastapi_routes/v2/user_resources_support.py +++ b/policyengine_api/fastapi_routes/v2/user_resources_support.py @@ -43,6 +43,12 @@ from policyengine_api.services.v2.user_policies.validators import ( AssociationPolicyNotFoundError, ) +from policyengine_api.services.v2.user_reports.validators import ( + AssociationReportNotFoundError, +) +from policyengine_api.services.v2.user_simulations.validators import ( + AssociationSimulationNotFoundError, +) from policyengine_api.services.v2.user_types.validators import ( AdminUserEmailSearchRefusedError, AdminUserProfilesUnavailableError, @@ -214,6 +220,8 @@ class UserResourceFailure(NamedTuple): AssociationNotFoundError, AssociationPolicyNotFoundError, AssociationHouseholdNotFoundError, + AssociationReportNotFoundError, + AssociationSimulationNotFoundError, AccountNotFoundError, SignedInUserNotFoundError, ), diff --git a/policyengine_api/fastapi_routes/v2/user_simulations/response_models.py b/policyengine_api/fastapi_routes/v2/user_simulations/response_models.py index 70df6f78a..7d1dc5f65 100644 --- a/policyengine_api/fastapi_routes/v2/user_simulations/response_models.py +++ b/policyengine_api/fastapi_routes/v2/user_simulations/response_models.py @@ -26,8 +26,14 @@ class StrictUserSimulationAPIModel(BaseModel): class UserSimulationItem(StrictUserSimulationAPIModel): """A simulation saved by a user, with the user's name and description for it. - ``legacy_simulation_id`` is the v1 simulation it saves. Associations can be - renamed, pointed at another v1 simulation of the same country, or deleted. + ``simulation_id`` is the detailed-save simulation it saves, and + ``legacy_simulation_id`` the v1 simulation; one of them is set, and only + saved simulations the production migration wrote hold both. Associations + can be renamed or deleted, and pointed at another simulation of the same + country through the reference they hold: another detailed-save simulation + through ``simulation_id``, another v1 simulation through + ``legacy_simulation_id``. An update that would leave both set is refused, + and the simulation's own kind (economy or household) is not checked. """ id: UUID diff --git a/policyengine_api/fastapi_routes/v2/user_simulations/routes.py b/policyengine_api/fastapi_routes/v2/user_simulations/routes.py index fbb98c51d..9327fbf7a 100644 --- a/policyengine_api/fastapi_routes/v2/user_simulations/routes.py +++ b/policyengine_api/fastapi_routes/v2/user_simulations/routes.py @@ -98,12 +98,14 @@ def build_v2_user_simulation_router( "/user-simulations", response_model=UserSimulationDetailResponse, status_code=201, - summary="Save a v1 simulation for the current user", + summary="Save a simulation for the current user", description=( "Requires a bearer access token or the PolicyEngine-Unauthenticated-User " - "header; the owner is taken from that credential. " - "Stage 12A accepts legacy_simulation_id only, checked in the v1 " - "database." + "header; the owner is taken from that credential. Names a " + "detailed-save simulation (simulation_id), which must be of the " + "country's model (404 otherwise), or a v1 simulation " + "(legacy_simulation_id), checked in the v1 database; naming both " + "is refused with 400." ), ) def create_user_simulation( diff --git a/policyengine_api/libs/simulation_household_calculations.py b/policyengine_api/libs/simulation_household_calculations.py index da32ba573..467f097db 100644 --- a/policyengine_api/libs/simulation_household_calculations.py +++ b/policyengine_api/libs/simulation_household_calculations.py @@ -60,6 +60,11 @@ characters). The 400 and 422 refusals keep the service's reasons, which name the caller's own household, policy and fields. +The HTTP client, the sorting of transport errors, the refusal's reason, the +status and code a message gives, and the lost-answer and failure messages +come from ``policyengine_api.libs.simulation_service_answers``, which the +report and simulation client shares. + Each submission carries the request's ID and observability ID headers. The observability ID is the request's own, else the caller's, else a new one, which ``submit`` binds in the current context once the Public API's checks @@ -81,22 +86,35 @@ from __future__ import annotations -import re from dataclasses import dataclass from functools import lru_cache from http import HTTPStatus from typing import TYPE_CHECKING, Any from uuid import UUID -import httpx -from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError - -from policyengine_api.libs.gateway_auth import GatewayAuthError -from policyengine_api.libs.simulation_entrypoint import SimulationEntrypointClient +from pydantic import ValidationError + +from policyengine_api.libs.simulation_service_answers import ( + PROXY_STAND_IN_STATUSES, + AnswerModel, + Refusal, + SimulationAnswer, + answer_lost, + created_but_failed, + fixed_identifier_code, + parsed_body, + refusal_reason, + send_to_simulation_service, + simulation_service_http_client, + status_and_code, + submit_again, +) from policyengine_api.request_context import start_observability_id from policyengine_api.services.v2.household_calculations.types import ( HouseholdCalculationAccepted, HouseholdJobStatusName, +) +from policyengine_api.services.v2.simulation_service.types import ( SimulationServiceAnswerUnreadableError, SimulationServiceInternalError, SimulationServiceInvalidRequestError, @@ -106,22 +124,14 @@ if TYPE_CHECKING: from collections.abc import Callable + import httpx + from policyengine_api.services.v2.household_calculations.types import ( HouseholdCalculationInput, ) HOUSEHOLD_CALCULATIONS_PATH = "/household-calculations" -CLOUD_RUN_SIMULATION_ENTRYPOINT = "cloud_run_simulation_entrypoint" UNREADABLE_ANSWER = "The simulation service's answer could not be read." -# The service never answers 502 or 504 itself: a proxy in front of it, such as -# Cloud Run's front end, answers them in its place, possibly after the -# service created the job. -PROXY_STAND_IN_STATUSES = frozenset( - {HTTPStatus.BAD_GATEWAY, HTTPStatus.GATEWAY_TIMEOUT} -) -# Transport errors raised before the request could reach the service. After -# any other, the service may have received the submission and created the job. -CONNECTION_NEVER_MADE = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) # Statuses after which no job of the submission runs: the service's # authentication, routing, body-size and rate limits answer them before its # route runs, and its own 503 comes before it creates the job, or after it @@ -139,81 +149,36 @@ HTTPStatus.SERVICE_UNAVAILABLE, } ) -# A code the service names may reach the caller only when it is a fixed -# identifier, never text that could hold stored data. -FIXED_IDENTIFIER = re.compile(r"[a-z][a-z0-9_]{0,63}") -# Any JSON value, parsed by pydantic's parser, which has a depth limit. -ANY_JSON: TypeAdapter[Any] = TypeAdapter(Any) -SUBMIT_AGAIN = ( - "Submit the household calculation again; if the first request went " - "through, this creates a second job." -) +# The service may have created the job, and no route finds a household job +# without its ID, so each message after which the job may exist ends with +# this. +SUBMIT_AGAIN = submit_again("household calculation", "job") def _lost_answer(what_happened: str) -> str: """Return the message for an answer lost after the request may have arrived. - The service may have created the job, and no route finds a household job - without its ID, so the message says that submitting again creates a - second job if the first request went through. ``what_happened`` names - what came in place of a readable answer. + ``what_happened`` names what came in place of a readable answer. """ - return ( - "The simulation service may have received the request, but its answer " - f"was lost ({what_happened}). {SUBMIT_AGAIN}" - ) + return answer_lost(what_happened, SUBMIT_AGAIN) -def _created_but_failed(status_and_code: str) -> str: +def _created_but_failed(status_and_code_text: str) -> str: """Return the message for an answer the service sent once the job may exist. - ``status_and_code`` is the service's status, and its code when that is - a fixed identifier. + ``status_and_code_text`` is the service's status, and its code when that + is a fixed identifier. """ - return ( - "The simulation service may have created the household job, but it " - f"failed ({status_and_code}). {SUBMIT_AGAIN}" - ) - - -@dataclass(frozen=True) -class SimulationAnswer: - """The simulation service's answer: its HTTP status and body.""" - - status_code: int - content: bytes - - -class _AnswerModel(BaseModel): - """Base for the simulation service's answers; fields it adds are ignored.""" + return created_but_failed("household job", status_and_code_text, SUBMIT_AGAIN) - model_config = ConfigDict(extra="ignore", frozen=True) - -class _AcceptedJob(_AnswerModel): +class _AcceptedJob(AnswerModel): """The 202 body: the job the simulation service inserted, and its status.""" job_id: UUID status: HouseholdJobStatusName -class _RefusedField(_AnswerModel): - """One request field the simulation service refuses, and why.""" - - loc: list[str | int] - msg: str - - -class _Refusal(_AnswerModel): - """A refusal's body: a reason, or each refused request field. - - Its ``code`` is read on its own (``_read_answer``), so a code of another - type never makes the reason unreadable. - """ - - detail: str | list[_RefusedField] - - def household_calculation_request( calculation: HouseholdCalculationInput, ) -> dict[str, Any]: @@ -264,22 +229,12 @@ def post_household_calculation( return SimulationAnswer(status_code=response.status_code, content=response.content) -def _invalid_request_reason(refusal: _Refusal) -> str: - """Return the service's reason, or each refused field and why. - - A field's location is given without the request's ``body`` prefix. - """ - if isinstance(refusal.detail, str): - reason = refusal.detail - else: - reasons = [] - for refused_field in refusal.detail: - location = [str(part) for part in refused_field.loc] - if location[:1] == ["body"]: - location = location[1:] - reasons.append(f"{'.'.join(location)}: {refused_field.msg}") - reason = "; ".join(reasons) or "the request is invalid" - return f"The simulation service cannot calculate this household: {reason}" +def _invalid_request_reason(refusal: Refusal) -> str: + """Return the service's reason, or each refused field and why.""" + return ( + "The simulation service cannot calculate this household: " + f"{refusal_reason(refusal)}" + ) @dataclass(frozen=True) @@ -292,36 +247,26 @@ class _ReadAnswer: status_code: int code: str | None - refusal: _Refusal | None + refusal: Refusal | None @property def status_and_code(self) -> str: """The status, and the code when there is one; never the service's text.""" - if self.code is None: - return str(self.status_code) - return f"{self.status_code} {self.code}" + return status_and_code(self.status_code, self.code) def _read_answer(answer: SimulationAnswer) -> _ReadAnswer: """Parse the answer's body once; a body that is not JSON reads as none. - pydantic's parser reports a body nested past its depth limit, or bytes - that are not UTF-8, as a ValidationError, so no body can raise anything - else. + Its ``code`` is read on its own, so a code of another type never makes + the reason unreadable. """ + body = parsed_body(answer) try: - body = ANY_JSON.validate_json(answer.content) - except ValidationError: - body = None - code = body.get("code") if isinstance(body, dict) else None - fixed_code = ( - code if isinstance(code, str) and FIXED_IDENTIFIER.fullmatch(code) else None - ) - try: - refusal = _Refusal.model_validate(body) + refusal = Refusal.model_validate(body) except ValidationError: refusal = None - return _ReadAnswer(answer.status_code, fixed_code, refusal) + return _ReadAnswer(answer.status_code, fixed_identifier_code(body), refusal) def _answered_by_a_proxy(read: _ReadAnswer) -> bool: @@ -383,16 +328,7 @@ def from_environment( is missing or invalid, or gateway auth is partly configured or required but unset. """ - try: - entrypoint = SimulationEntrypointClient( - CLOUD_RUN_SIMULATION_ENTRYPOINT, transport=transport - ) - except (ValueError, GatewayAuthError) as error: - msg = "The simulation service is not configured." - raise SimulationServiceUnavailableError(msg) from error - http_client = entrypoint.client - http_client.base_url = httpx.URL(entrypoint.base_url) - return cls(http_client) + return cls(simulation_service_http_client(transport=transport)) def submit( self, calculation: HouseholdCalculationInput @@ -411,17 +347,12 @@ def submit( or a proxy in front of it answered in its place. """ start_observability_id() - try: - answer = self._send( - self._http_client, household_calculation_request(calculation) - ) - except (*CONNECTION_NEVER_MADE, GatewayAuthError) as error: - msg = "The simulation service could not be reached." - raise SimulationServiceUnavailableError(msg) from error - except httpx.HTTPError as error: - raise SimulationServiceAnswerUnreadableError( - _lost_answer(type(error).__name__) - ) from error + answer = send_to_simulation_service( + self._send, + self._http_client, + household_calculation_request(calculation), + submit_again_sentence=SUBMIT_AGAIN, + ) return _accepted_job(answer) diff --git a/policyengine_api/libs/simulation_reports.py b/policyengine_api/libs/simulation_reports.py new file mode 100644 index 000000000..13740cec6 --- /dev/null +++ b/policyengine_api/libs/simulation_reports.py @@ -0,0 +1,506 @@ +"""Create simulations and reports through the simulation service. + +``SimulationServiceReportClient`` is the ``SimulationServiceClient`` of the +v2 simulation and report routes. It posts to the Cloud Run simulation +service's ``POST /simulations`` and ``POST /reports``, at +``SIMULATION_ENTRYPOINT_URL`` whatever ``SIM_ENTRYPOINT`` selects for the v1 +economy routes, through the HTTP client ``SimulationEntrypointClient`` +builds: the same gateway credentials (``GATEWAY_AUTH_*``), request and +observability ID headers, transport and instrumentation as every other +simulation call. + +A simulation request names the country, ``simulation_type`` (``economy``), +the year, the region code, the dataset name (null for the region's default), +and the stored policy and dynamic (null for current law). A report request +names the country, ``report_type`` (``economy``), the label and description, +the year, region and dataset its two simulations share, each simulation's +policy and dynamic, ``include_cliffs``, and the SPM settings only when the +caller gave them. Neither names a PolicyEngine.py version: the simulation +service runs its default worker's. The simulation service answers: + +- 201 or 202 with the created record's ID and its first run's ID. One whose + body cannot be read is SimulationServiceAnswerUnreadableError: the record + exists; +- 422 with its reasons when it refuses the caller's data, as text or one + per field as FastAPI writes them, and 400 with a code in + ``CALLER_ROW_REFUSAL_CODES`` and its reason when a region, dataset or + dynamic the caller named does not exist (the Public API checks the country + and policies first): SimulationServiceInvalidRequestError, with the code + and reasons; +- 400 with any other code, or none: a state of the service rather than the + caller's error, such as ``unknown_catalog_version`` while a release + deploys, or a row the Public API already checked. The service is + unavailable (SimulationServiceUnavailableError), with its code and reason; +- 503 with its code when it cannot read its manifest or database, before + creating anything: SimulationServiceUnavailableError, with the status and + code. When Modal refuses the run's call, the service has created the + record and failed its run, and its 503 names the record (``report_id`` or + ``simulation_id``): SimulationServiceUnavailableError, with the status, + the code and the record's ID; +- 401, 403, 404, 405, 413 or 429, which the gateway, Cloud Run or the + service's framework answers before the service's route runs: the service + is unavailable (SimulationServiceUnavailableError), with the status and + code, as it is for no answer, a 400 or 422 that cannot be read, a gateway + token that cannot be fetched and missing configuration. No answer means a + connection never made (``ConnectError``, ``ConnectTimeout``, + ``PoolTimeout``). + +A readable 400's or 422's message gives the service's code, when it gave +one, and its reason, but not the service's status, since the route answers +with its own. A 422's reason, and a 400's with a code in +``CALLER_ROW_REFUSAL_CODES``, describes the caller's own request; any other +400's describes the service's state. A 500's or 503's ``detail`` may hold an +exception's text, which can carry stored data, so it never reaches the +caller. The message of a 500, a 503 or any status other than a readable 400 +or 422 gives the service's status and code instead, such as +``503 modal_call_refused``, and gives the code only when it is a fixed +identifier (``FIXED_IDENTIFIER`` in +``policyengine_api.libs.simulation_service_answers``), which an exception's +text is not. + +Some answers may follow a record the service created, so they are never +SimulationServiceUnavailableError, whose 503 says nothing was created: + +- an answer lost once the request may have been sent (a read timeout, a + dropped connection), and a 502 or 504 a proxy in front of the service + answers in its place: SimulationServiceAnswerUnreadableError, saying the + service may have received the request, but its answer was lost; +- 500 (``internal_error``) when the service failed, possibly after creating + the record: SimulationServiceInternalError; a 503 that cannot be read, + which Cloud Run's front end also answers in the service's place, or whose + ``report_id`` or ``simulation_id`` is not a UUID, or that names a record + other than the submission's own, which shows the service wrote rows; and + any other status, which the service's route may answer after writing + rows: SimulationServiceAnswerUnreadableError. Each says the service may + have created the record, but failed, with the status and code. + +Each of these asks the caller to submit again, and says that this creates a +second record if the first request went through. + +The HTTP client, the sorting of transport errors, the refusal's reason, the +status and code a message gives, and the lost-answer and failure messages +come from ``policyengine_api.libs.simulation_service_answers``, which the +household calculation client shares. + +Wiring the generated simulation client: ``post_simulation`` and +``post_report`` are the only code that sends a request, and each returns the +status and body, which the rest of this module reads. Once a +``policyengine-api-simulation-client`` release has the two routes, depend on +that release and make each function call the generated operation, as its +docstring says. +""" + +from __future__ import annotations + +from functools import lru_cache +from http import HTTPStatus +from typing import TYPE_CHECKING, Any, Literal, NoReturn +from uuid import UUID + +from pydantic import ValidationError + +from policyengine_api.libs.simulation_service_answers import ( + PROXY_STAND_IN_STATUSES, + AnswerModel, + Refusal, + SimulationAnswer, + answer_lost, + created_but_failed, + fixed_identifier_code, + parsed_body, + refusal_reason, + send_to_simulation_service, + simulation_service_http_client, + status_and_code, + submit_again, +) +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceAnswerUnreadableError, + SimulationServiceInternalError, + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, + SubmittedReport, + SubmittedSimulation, +) + +if TYPE_CHECKING: + from collections.abc import Callable + + import httpx + + from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + PolicyChoice, + ) + +SIMULATIONS_PATH = "/simulations" +REPORTS_PATH = "/reports" +CREATED_STATUSES = frozenset({HTTPStatus.CREATED, HTTPStatus.ACCEPTED}) +REFUSAL_STATUSES = frozenset({HTTPStatus.BAD_REQUEST, HTTPStatus.UNPROCESSABLE_ENTITY}) +# The codes of the simulation service's 400 that name a row the caller chose +# and the Public API does not check: the region, the dataset, or a dynamic +# the catalog version its default worker runs does not have. Each is the +# caller's error and answers 422. Any other 400 is a state of the service, +# such as a catalog version missing while a release deploys, or a row the +# Public API already checked, and answers 503. +CALLER_ROW_REFUSAL_CODES = frozenset( + {"unknown_region", "unknown_dataset", "unknown_dynamic"} +) +# Statuses the gateway, Cloud Run or the service's framework answers before +# the service's route runs, so the service has created nothing: a call not +# authenticated or not allowed, a route or method the service does not have, +# a body over the size limit, and too many requests. The route may have +# written rows before answering any other status the client does not expect. +SENT_BEFORE_ROUTE_STATUSES = frozenset( + { + HTTPStatus.UNAUTHORIZED, + HTTPStatus.FORBIDDEN, + HTTPStatus.NOT_FOUND, + HTTPStatus.METHOD_NOT_ALLOWED, + HTTPStatus.REQUEST_ENTITY_TOO_LARGE, + HTTPStatus.TOO_MANY_REQUESTS, + } +) + + +# What a submission creates. +RecordName = Literal["report", "simulation"] + + +class _CreatedSimulation(AnswerModel): + simulation_id: UUID + simulation_run_id: UUID + + +class _CreatedReport(AnswerModel): + report_id: UUID + report_run_id: UUID + + +class _Refusal(Refusal): + """A refusal's or failure's body: a reason, or each refused request field. + + It may also name its ``code``, and a 503 after Modal refused the run's + call names the record the service created and failed. A 503 is the + service's own only in this shape, but its reason is never passed on. + """ + + code: str | None = None + report_id: UUID | None = None + simulation_id: UUID | None = None + + def created_record_id(self, record: RecordName) -> UUID | None: + """Return the ID the body gives the submission's own record, if any.""" + return self.report_id if record == "report" else self.simulation_id + + def names_only_another_record(self, record: RecordName) -> bool: + """Return whether the body names a record, but not the submission's own.""" + names_a_record = self.report_id is not None or self.simulation_id is not None + return names_a_record and self.created_record_id(record) is None + + +def _policy_choice(choice: PolicyChoice) -> dict[str, str | None]: + return { + "policy_id": None if choice.policy_id is None else str(choice.policy_id), + "dynamic_id": None if choice.dynamic_id is None else str(choice.dynamic_id), + } + + +def simulation_request(simulation: EconomySimulationCreationInput) -> dict[str, Any]: + """Return the simulation service's request body for the simulation.""" + return { + "country": simulation.country_id, + "simulation_type": simulation.kind, + "year": simulation.year, + "region_code": simulation.region_code, + "dataset_name": simulation.dataset_name, + **_policy_choice(simulation), + } + + +def report_request(report: EconomyReportCreationInput) -> dict[str, Any]: + """Return the simulation service's request body for the report. + + ``spm`` is sent only when the caller gave it. + """ + body: dict[str, Any] = { + "country": report.country_id, + "report_type": report.kind, + "label": report.label, + "description": report.description, + "year": report.year, + "region_code": report.region_code, + "dataset_name": report.dataset_name, + "baseline": _policy_choice(report.baseline), + "reform": _policy_choice(report.reform), + "include_cliffs": report.include_cliffs, + } + if report.spm is not None: + body["spm"] = report.spm.model_dump(mode="json") + return body + + +def post_simulation( + http_client: httpx.Client, body: dict[str, Any] +) -> SimulationAnswer: + """Send one simulation to the simulation service and return its answer. + + Raise httpx.HTTPError when no answer arrives, and GatewayAuthError when + the gateway token cannot be fetched. ``http_client`` has the service's + base URL. To send through the generated client instead, this body + becomes (the operation and model names are those the simulation + service's OpenAPI document gives the route):: + + client = Client(base_url=str(http_client.base_url)) + client.set_httpx_client(http_client) + response = create_simulation.sync_detailed( + client=client, body=SimulationRequest.from_dict(body) + ) + return SimulationAnswer(int(response.status_code), response.content) + """ + response = http_client.post(SIMULATIONS_PATH, json=body) + return SimulationAnswer(status_code=response.status_code, content=response.content) + + +def post_report(http_client: httpx.Client, body: dict[str, Any]) -> SimulationAnswer: + """Send one report to the simulation service and return its answer. + + As ``post_simulation``; with the generated client, the operation is the + report route's (``create_report.sync_detailed`` with + ``ReportRequest.from_dict(body)``). + """ + response = http_client.post(REPORTS_PATH, json=body) + return SimulationAnswer(status_code=response.status_code, content=response.content) + + +def _refusal(answer: SimulationAnswer) -> _Refusal | None: + try: + return _Refusal.model_validate_json(answer.content) + except ValidationError: + return None + + +def _status_and_code(answer: SimulationAnswer) -> str: + """Return the answer's status and code, such as ``503 modal_call_refused``. + + Return the status alone when the body is not a JSON object with a text + code, or its code is not a fixed identifier, such as an empty code or an + exception's text. Never the body's reason. + """ + return status_and_code( + answer.status_code, fixed_identifier_code(parsed_body(answer)) + ) + + +def _submit_again(record: RecordName) -> str: + """Ask the caller to submit the ``record`` again, which may create a second.""" + return submit_again(record, record) + + +def _failed_after_possible_creation( + answer: SimulationAnswer, record: RecordName +) -> str: + """Say the service may have created the ``record``, but failed. + + The message gives the answer's status and code, never its reason, which + may be an exception's text. + """ + return created_but_failed(record, _status_and_code(answer), _submit_again(record)) + + +def _code_and_reason(refusal: _Refusal) -> str: + """Return `` (code): reason``, or ``: reason`` when the service gave no code.""" + code = "" if refusal.code is None else f" ({refusal.code})" + return f"{code}: {refusal_reason(refusal)}" + + +def _raise_for_refused_request( + answer: SimulationAnswer, refusal: _Refusal, record: RecordName +) -> NoReturn: + """Raise the error the service's readable 400 or 422 means. + + A 422, or a 400 with a code in ``CALLER_ROW_REFUSAL_CODES``, is the + caller's error, and its reason describes the caller's own request. Any + other 400 is the service's state, so it is unavailable, and its reason + describes that state. Either message gives the service's code and + reason, but not its status, since the route answers with its own. + """ + code_and_reason = _code_and_reason(refusal) + if ( + answer.status_code == HTTPStatus.UNPROCESSABLE_ENTITY + or refusal.code in CALLER_ROW_REFUSAL_CODES + ): + msg = f"The simulation service cannot run this request{code_and_reason}" + raise SimulationServiceInvalidRequestError(msg) + msg = f"The simulation service refused the {record}{code_and_reason}" + raise SimulationServiceUnavailableError(msg) + + +def _raise_for_unavailable( + answer: SimulationAnswer, refusal: _Refusal | None, record: RecordName +) -> NoReturn: + """Raise the error the service's 503 means. + + A 503 that cannot be read, such as Cloud Run's own or one naming an ID + that is not a UUID, and one naming only a record other than ``record`` + may follow a record the service created: + SimulationServiceAnswerUnreadableError. Any other is the service's own + unavailability, naming the ``record`` it created when it names one. + Each message gives the status and code, never the reason. + """ + if refusal is None or refusal.names_only_another_record(record): + msg = _failed_after_possible_creation(answer, record) + raise SimulationServiceAnswerUnreadableError(msg) + status_and_code = _status_and_code(answer) + created_record_id = refusal.created_record_id(record) + if created_record_id is None: + msg = f"The simulation service is unavailable ({status_and_code})." + raise SimulationServiceUnavailableError(msg) + msg = ( + f"The simulation service created {record} {created_record_id}, but is " + f"unavailable ({status_and_code})." + ) + raise SimulationServiceUnavailableError(msg, created_record_id=created_record_id) + + +def _raise_for_refusal(answer: SimulationAnswer, record: RecordName) -> NoReturn: + """Raise the error a refusal, a failure or another answer means. + + ``record`` names what the submission creates. A status this module does + not expect may follow rows the service's route wrote, unless it is one + of ``SENT_BEFORE_ROUTE_STATUSES``. + """ + status_code = answer.status_code + if status_code in REFUSAL_STATUSES: + refusal = _refusal(answer) + if refusal is None: + msg = f"The simulation service answered {status_code} unreadably." + raise SimulationServiceUnavailableError(msg) + _raise_for_refused_request(answer, refusal, record) + if status_code in PROXY_STAND_IN_STATUSES: + msg = answer_lost( + f"a proxy answered {status_code} in its place", _submit_again(record) + ) + raise SimulationServiceAnswerUnreadableError(msg) + if status_code == HTTPStatus.SERVICE_UNAVAILABLE: + _raise_for_unavailable(answer, _refusal(answer), record) + if status_code in SENT_BEFORE_ROUTE_STATUSES: + msg = f"The simulation service is unavailable ({_status_and_code(answer)})." + raise SimulationServiceUnavailableError(msg) + msg = _failed_after_possible_creation(answer, record) + if status_code == HTTPStatus.INTERNAL_SERVER_ERROR: + raise SimulationServiceInternalError(msg) + raise SimulationServiceAnswerUnreadableError(msg) + + +class SimulationServiceReportClient: + """Create simulations and reports through the simulation service.""" + + def __init__( + self, + http_client: httpx.Client, + *, + send_simulation: Callable[ + [httpx.Client, dict[str, Any]], SimulationAnswer + ] = post_simulation, + send_report: Callable[ + [httpx.Client, dict[str, Any]], SimulationAnswer + ] = post_report, + ) -> None: + """Send through ``send_simulation`` and ``send_report`` on ``http_client``. + + ``http_client`` has the service's base URL. + """ + self._http_client = http_client + self._send_simulation = send_simulation + self._send_report = send_report + + @classmethod + def from_environment( + cls, *, transport: httpx.BaseTransport | None = None + ) -> SimulationServiceReportClient: + """Call the configured Cloud Run simulation service with gateway auth. + + ``transport`` replaces the simulation transport, for tests. Raise + SimulationServiceUnavailableError when ``SIMULATION_ENTRYPOINT_URL`` + is missing or invalid, or gateway auth is partly configured or + required but unset. + """ + return cls(simulation_service_http_client(transport=transport)) + + def _answer( + self, + send: Callable[[httpx.Client, dict[str, Any]], SimulationAnswer], + body: dict[str, Any], + *, + record: RecordName, + ) -> SimulationAnswer: + """Send ``body`` and return the answer, which may be a refusal. + + Raise SimulationServiceUnavailableError when the connection was never + made or the gateway token cannot be fetched, and + SimulationServiceAnswerUnreadableError when the answer was lost after + the submission may have reached the service, which may then have + created the ``record``. + """ + return send_to_simulation_service( + send, self._http_client, body, submit_again_sentence=_submit_again(record) + ) + + def submit_simulation( + self, simulation: EconomySimulationCreationInput + ) -> SubmittedSimulation: + """Create the simulation and its first run; return their IDs. + + Raise the errors ``SimulationServiceClient`` names. + """ + answer = self._answer( + self._send_simulation, simulation_request(simulation), record="simulation" + ) + if answer.status_code not in CREATED_STATUSES: + _raise_for_refusal(answer, "simulation") + try: + created = _CreatedSimulation.model_validate_json(answer.content) + except ValidationError as error: + msg = ( + "The simulation service created the simulation, but its answer " + "could not be read." + ) + raise SimulationServiceAnswerUnreadableError(msg) from error + return SubmittedSimulation( + simulation_id=created.simulation_id, + simulation_run_id=created.simulation_run_id, + ) + + def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: + """Create the report, its simulations and runs; return the report's IDs. + + Raise the errors ``SimulationServiceClient`` names. + """ + answer = self._answer( + self._send_report, report_request(report), record="report" + ) + if answer.status_code not in CREATED_STATUSES: + _raise_for_refusal(answer, "report") + try: + created = _CreatedReport.model_validate_json(answer.content) + except ValidationError as error: + msg = ( + "The simulation service created the report, but its answer could " + "not be read." + ) + raise SimulationServiceAnswerUnreadableError(msg) from error + return SubmittedReport( + report_id=created.report_id, report_run_id=created.report_run_id + ) + + +@lru_cache(maxsize=1) +def process_simulation_service_client() -> SimulationServiceReportClient: + """Return the process's client, built from the environment on first use. + + Its connections and gateway token are reused across requests. A + configuration error is raised again on the next call, not kept. + """ + return SimulationServiceReportClient.from_environment() diff --git a/policyengine_api/libs/simulation_service_answers.py b/policyengine_api/libs/simulation_service_answers.py new file mode 100644 index 000000000..b54667121 --- /dev/null +++ b/policyengine_api/libs/simulation_service_answers.py @@ -0,0 +1,242 @@ +"""Send requests to the simulation service, and read what every v2 route reads alike. + +The Public API's v2 household calculation, report and simulation routes call +the Cloud Run simulation service's v2 routes +(``policyengine_api.libs.simulation_household_calculations`` and +``policyengine_api.libs.simulation_reports``). Each of those modules decides +what each of its route's answers means; this module holds what they share: + +- the HTTP client, built by ``simulation_service_http_client`` from + ``SimulationEntrypointClient`` at ``SIMULATION_ENTRYPOINT_URL``, with the + gateway credentials (``GATEWAY_AUTH_*``), request and observability ID + headers, transport and instrumentation of every other simulation call; +- the sorting of transport errors (``send_to_simulation_service``): a + connection never made (``CONNECTION_NEVER_MADE``) or a gateway token that + cannot be fetched means the service created nothing, so it is + SimulationServiceUnavailableError; any other transport error may follow a + request the service received, so it is + SimulationServiceAnswerUnreadableError, asking the caller to submit again; +- the answer's status and body (``SimulationAnswer``), and the models its + bodies are read with (``AnswerModel``, ``Refusal``, ``RefusedField``); +- the refusal's reason (``refusal_reason``), and the status and code a + message gives in place of the service's reason (``status_and_code``), with + the code only when it is a fixed identifier (``FIXED_IDENTIFIER``); +- the statuses a proxy in front of the service answers in its place + (``PROXY_STAND_IN_STATUSES``); +- the messages for an answer lost after the request may have arrived + (``answer_lost``) and for a failure after the service may have created + what was submitted (``created_but_failed``), each ending with + ``submit_again``'s sentence. + +Each client still builds its own refusal messages, and its own message for +a 400 or 422 it cannot read, since the two routes answer them differently: +the household calculation client names a refusal's code only when it is a +fixed identifier, and the report and simulation client names any text +code. +""" + +from __future__ import annotations + +import re +from dataclasses import dataclass +from http import HTTPStatus +from typing import TYPE_CHECKING, Any + +import httpx +from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError + +from policyengine_api.libs.gateway_auth import GatewayAuthError +from policyengine_api.libs.simulation_entrypoint import SimulationEntrypointClient +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceAnswerUnreadableError, + SimulationServiceUnavailableError, +) + +if TYPE_CHECKING: + from collections.abc import Callable + +CLOUD_RUN_SIMULATION_ENTRYPOINT = "cloud_run_simulation_entrypoint" +UNREACHABLE = "The simulation service could not be reached." +NOT_CONFIGURED = "The simulation service is not configured." +# The service never answers 502 or 504 itself: a proxy in front of it, such as +# Cloud Run's front end, answers them in its place, possibly after the +# service created what was submitted. +PROXY_STAND_IN_STATUSES = frozenset( + {HTTPStatus.BAD_GATEWAY, HTTPStatus.GATEWAY_TIMEOUT} +) +# Transport errors raised before the request could reach the service. After +# any other, the service may have received the submission and created what +# it asks for. +CONNECTION_NEVER_MADE = (httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout) +# A code the service names may reach the caller without its reason only when +# it is a fixed identifier: lower-case letters, digits and underscores, +# starting with a letter, at most 64 characters. Any other, such as an +# exception's text, which could hold stored data, is left out. +FIXED_IDENTIFIER = re.compile(r"[a-z][a-z0-9_]{0,63}") +# Any JSON value, parsed by pydantic's parser, which has a depth limit. +ANY_JSON: TypeAdapter[Any] = TypeAdapter(Any) + + +@dataclass(frozen=True) +class SimulationAnswer: + """The simulation service's answer: its HTTP status and body.""" + + status_code: int + content: bytes + + +class AnswerModel(BaseModel): + """Base for the simulation service's answers; fields it adds are ignored.""" + + model_config = ConfigDict(extra="ignore", frozen=True) + + +class RefusedField(AnswerModel): + """One request field the simulation service refuses, and why.""" + + loc: list[str | int] + msg: str + + +class Refusal(AnswerModel): + """A refusal's body: a reason, or each refused request field.""" + + detail: str | list[RefusedField] + + +def simulation_service_http_client( + *, transport: httpx.BaseTransport | None = None +) -> httpx.Client: + """Return an HTTP client for the configured Cloud Run simulation service. + + The client has the service's base URL and gateway auth. ``transport`` + replaces the simulation transport, for tests. Raise + SimulationServiceUnavailableError when ``SIMULATION_ENTRYPOINT_URL`` is + missing or invalid, or gateway auth is partly configured or required but + unset. + """ + try: + entrypoint = SimulationEntrypointClient( + CLOUD_RUN_SIMULATION_ENTRYPOINT, transport=transport + ) + except (ValueError, GatewayAuthError) as error: + raise SimulationServiceUnavailableError(NOT_CONFIGURED) from error + http_client = entrypoint.client + http_client.base_url = httpx.URL(entrypoint.base_url) + return http_client + + +def submit_again(submission: str, second: str) -> str: + """Ask the caller to submit the ``submission`` again, which may create a second. + + No route finds what a submission created by what it was submitted with, + so the caller cannot check whether the first request created a + ``second``. + """ + return ( + f"Submit the {submission} again; if the first request went through, " + f"this creates a second {second}." + ) + + +def answer_lost(what_happened: str, submit_again_sentence: str) -> str: + """Say the service may have received the request, but its answer was lost. + + ``what_happened`` names what came in place of a readable answer, such as + the transport error's type or what a proxy answered. + """ + return ( + "The simulation service may have received the request, but its answer " + f"was lost ({what_happened}). {submit_again_sentence}" + ) + + +def created_but_failed( + created: str, status_and_code_text: str, submit_again_sentence: str +) -> str: + """Say the service may have created the ``created``, but failed. + + ``status_and_code_text`` is the service's status, and its code when that + is a fixed identifier (``status_and_code``), never its reason, which may + be an exception's text. + """ + return ( + f"The simulation service may have created the {created}, but it failed " + f"({status_and_code_text}). {submit_again_sentence}" + ) + + +def send_to_simulation_service( + send: Callable[[httpx.Client, dict[str, Any]], SimulationAnswer], + http_client: httpx.Client, + body: dict[str, Any], + *, + submit_again_sentence: str, +) -> SimulationAnswer: + """Send ``body`` through ``send`` and return the answer, whatever its status. + + Raise SimulationServiceUnavailableError when the connection was never + made or the gateway token cannot be fetched, and + SimulationServiceAnswerUnreadableError when the answer was lost after the + request may have reached the service, whose message ends with + ``submit_again_sentence``. + """ + try: + return send(http_client, body) + except (*CONNECTION_NEVER_MADE, GatewayAuthError) as error: + raise SimulationServiceUnavailableError(UNREACHABLE) from error + except httpx.HTTPError as error: + raise SimulationServiceAnswerUnreadableError( + answer_lost(type(error).__name__, submit_again_sentence) + ) from error + + +def parsed_body(answer: SimulationAnswer) -> object: + """Return the answer's body as parsed JSON, or None when it is not JSON. + + pydantic's parser reports a body nested past its depth limit, or bytes + that are not UTF-8, as a ValidationError, so no body can raise anything + else. + """ + try: + return ANY_JSON.validate_json(answer.content) + except ValidationError: + return None + + +def fixed_identifier_code(body: object) -> str | None: + """Return the body's ``code`` when it is a fixed identifier, else None. + + The body is parsed JSON (``parsed_body``); one that is not an object + names no code. + """ + code = body.get("code") if isinstance(body, dict) else None + if isinstance(code, str) and FIXED_IDENTIFIER.fullmatch(code): + return code + return None + + +def status_and_code(status_code: int, code: str | None) -> str: + """Return the status, and the code when there is one: ``503 manifest_unavailable``. + + Never the service's reason, which may be an exception's text. + """ + if code is None: + return str(status_code) + return f"{status_code} {code}" + + +def refusal_reason(refusal: Refusal) -> str: + """Return the service's reason, or each refused field and why. + + A field's location is given without the request's ``body`` prefix. + """ + if isinstance(refusal.detail, str): + return refusal.detail + reasons = [] + for refused_field in refusal.detail: + location = [str(part) for part in refused_field.loc] + if location[:1] == ["body"]: + location = location[1:] + reasons.append(f"{'.'.join(location)}: {refused_field.msg}") + return "; ".join(reasons) or "the request is invalid" diff --git a/policyengine_api/migration_logging.py b/policyengine_api/migration_logging.py index bf9de3d7b..c1aa4868c 100644 --- a/policyengine_api/migration_logging.py +++ b/policyengine_api/migration_logging.py @@ -74,15 +74,19 @@ "admin", } ) -# /v2/household-calculations reads only Supabase and computes only on the -# Cloud Run simulation service's v2 household functions, whatever the -# household route group's database, entrypoint and compute flags select: a -# submission reads the countries row, household and policy and sends the -# calculation there, and a read reads the job and calls nothing. It reads -# none of those flags, so none of them is checked for its log record. -V2_HOUSEHOLD_CALCULATION_SEGMENT = "household-calculations" -V2_HOUSEHOLD_CALCULATION_ENTRYPOINT = "cloud_run_simulation_entrypoint" -V2_HOUSEHOLD_CALCULATION_COMPUTE = "v2_primary" +# /v2/household-calculations, /v2/reports and /v2/simulations read only +# Supabase, and compute or create only through the Cloud Run simulation +# service's v2 routes, whatever their route groups' database, entrypoint and +# compute flags select. A household calculation's submission reads the +# countries row, household and policy and sends the calculation there; a +# report's or simulation's create checks the country and policies and sends +# the request there; a read reads the tables and calls nothing. They read none +# of those flags, so none of them is checked for their log records. +V2_SIMULATION_SERVICE_SEGMENTS = frozenset( + {"household-calculations", "reports", "simulations"} +) +V2_SIMULATION_SERVICE_ENTRYPOINT = "cloud_run_simulation_entrypoint" +V2_SIMULATION_SERVICE_COMPUTE = "v2_primary" V2_RESOURCE_METHODS = frozenset({"GET", "POST", "PATCH", "DELETE"}) # A v2 resource path has at least the "v2" segment and the resource segment. V2_RESOURCE_PATH_MINIMUM_SEGMENTS = 2 @@ -266,25 +270,31 @@ def log_migration_request(served_request: ServedRequest) -> None: ) -def _household_calculation_context( +def _simulation_service_context( route_group: str, *, method: str, route_impl: RouteImplementation | None ) -> dict[str, str | None]: - """Return a household calculation's log record from what it actually uses.""" + """Return a household calculation's, report's or simulation's log record. + + The record names what the request actually uses, not its route group's + flags. + """ try: selected_route_impl = route_impl or get_route_impl(route_group) except ValueError as error: return {"route_group": route_group, "migration_flag_error": str(error)} route_config = ROUTE_GROUP_CONFIG_BY_NAME[route_group] - submits = method == "POST" + sends_to_simulation_service = method == "POST" return MigrationContext( route_group=route_group, route_impl=selected_route_impl, db_entity=route_config.db_entity, db_write=None, db_read="supabase", - sim_flow=route_config.sim_flow if submits else None, - sim_entrypoint=V2_HOUSEHOLD_CALCULATION_ENTRYPOINT, - sim_compute=V2_HOUSEHOLD_CALCULATION_COMPUTE if submits else None, + sim_flow=route_config.sim_flow if sends_to_simulation_service else None, + sim_entrypoint=V2_SIMULATION_SERVICE_ENTRYPOINT, + sim_compute=( + V2_SIMULATION_SERVICE_COMPUTE if sends_to_simulation_service else None + ), ).to_log_dict() @@ -295,8 +305,8 @@ def _migration_context( route_impl: RouteImplementation | None, ) -> dict[str, str | None]: route_group = infer_route_group(path) - if _v2_resource_segment(path) == V2_HOUSEHOLD_CALCULATION_SEGMENT: - return _household_calculation_context( + if _v2_resource_segment(path) in V2_SIMULATION_SERVICE_SEGMENTS: + return _simulation_service_context( route_group, method=method, route_impl=route_impl ) is_v2_metadata_read = _is_v2_metadata_resource_read(method, path) diff --git a/policyengine_api/migration_registry.py b/policyengine_api/migration_registry.py index 58234964c..93c5874b5 100644 --- a/policyengine_api/migration_registry.py +++ b/policyengine_api/migration_registry.py @@ -87,7 +87,7 @@ class RouteGroupConfig: ), RouteGroupConfig( name="report", - path_segments=("report", "user-reports", "shared-reports"), + path_segments=("report", "reports", "user-reports", "shared-reports"), db_entity="report", sim_flow="report", ), diff --git a/policyengine_api/query_parameters.py b/policyengine_api/query_parameters.py index 8d8aad15e..82456d4c7 100644 --- a/policyengine_api/query_parameters.py +++ b/policyengine_api/query_parameters.py @@ -46,6 +46,8 @@ from collections.abc import Iterable, Mapping DEFAULT_QUERY_LIMIT = 100 +# A report list reads every named report and its newest run in one query. +MAXIMUM_LISTED_REPORTS = 25 MAXIMUM_QUERY_LIMIT = 500 MAXIMUM_USER_ID_LENGTH = 255 @@ -423,6 +425,35 @@ class UserReportCollectionQuery(CountryQuery, PaginationQuery): legacy_report_id: LegacyResourceId | None = None +class ReportCreateQuery(CountryQuery): + """Query contract for creating a report; the body names the same country.""" + + +class ReportDetailQuery(CountryQuery): + """Query contract for reading one report in a country.""" + + +class ReportCollectionQuery(CountryQuery): + """Query contract for listing chosen reports of a country. + + ``report_id`` is repeated once per report, at most 25 times. + """ + + report_id: list[ResourceId] = Field( + min_length=1, + max_length=MAXIMUM_LISTED_REPORTS, + description="A report to list; repeat the key for each report", + ) + + +class SimulationCreateQuery(CountryQuery): + """Query contract for creating a simulation; the body names the same country.""" + + +class SimulationDetailQuery(CountryQuery): + """Query contract for reading one simulation in a country.""" + + QueryParametersT = TypeVar("QueryParametersT", bound=StrictQueryParameters) diff --git a/policyengine_api/services/v2/associations/validators.py b/policyengine_api/services/v2/associations/validators.py index a5cff660e..c3b501275 100644 --- a/policyengine_api/services/v2/associations/validators.py +++ b/policyengine_api/services/v2/associations/validators.py @@ -52,3 +52,34 @@ def require_not_mirror_owned(*, mirror_owned: bool, association_id: UUID) -> Non "and cannot be changed here" ) raise MirrorOwnedAssociationError(msg) + + +def require_one_reference( + kind: str, *, detailed_save_id: UUID | None, legacy_id: int | None +) -> None: + """Raise AssociationReferenceConflictError when both references are named. + + v1 report and simulation numbers are not connected to detailed-save + records, so a saved ``kind`` names one or the other; only the + production migration writes records holding both. + """ + if detailed_save_id is not None and legacy_id is not None: + msg = ( + f"A saved {kind} names a detailed-save {kind} or a v1 {kind} " + "number, not both" + ) + raise AssociationReferenceConflictError(msg) + + +def violates_foreign_key(error: Exception, constraint_name: str) -> bool: + """Return whether a database error is a violation of the named foreign key. + + That is SQLSTATE 23503 (``foreign_key_violation``) on ``constraint_name``, + as psycopg reports it on the error SQLAlchemy wraps. + """ + driver_error = getattr(error, "orig", None) + diagnostics = getattr(driver_error, "diag", None) + return ( + getattr(driver_error, "sqlstate", None) == "23503" + and getattr(diagnostics, "constraint_name", None) == constraint_name + ) diff --git a/policyengine_api/services/v2/household_calculations/types.py b/policyengine_api/services/v2/household_calculations/types.py index fe76edd33..99d40e3c6 100644 --- a/policyengine_api/services/v2/household_calculations/types.py +++ b/policyengine_api/services/v2/household_calculations/types.py @@ -316,8 +316,10 @@ def submit( ) -> HouseholdCalculationAccepted: """Submit the calculation and return the job the service created. - Raise SimulationServiceInvalidRequestError when the service refuses - the caller's data, with its reasons; + Raise, with the error types of + ``policyengine_api.services.v2.simulation_service.types``, + SimulationServiceInvalidRequestError when the service refuses the + caller's data, with its reasons; SimulationServiceUnavailableError when no job of the submission will run; SimulationServiceInternalError when it failed (500), possibly after @@ -328,47 +330,3 @@ def submit( in its place. """ ... - - -class SimulationServiceUnavailableError(RuntimeError): - """The simulation service could not be reached, or refused so no job runs. - - It covers a connection never made, a gateway token that cannot be - fetched, missing configuration, and every answer after which no job of - the submission runs: a household, policy or catalog version it cannot - find (which the Public API checks first), its authentication, routing, - body-size and rate limits, and its own 503 when it is not configured, - cannot read a database or manifest, or cannot start a Modal call, after - which it fails the job it had created. - """ - - -class SimulationServiceAnswerUnreadableError(RuntimeError): - """The simulation service may have created the job, but no usable answer came. - - It answered 202, so it has already created the job and started its call, - but its answer is unreadable; it answered a status the Public API does not - expect, possibly after creating the job; its answer was lost after the - submission may have reached it; or a proxy answered in its place. The - message asks the caller to submit again, and says this creates a second - job if the first request went through. - """ - - -class SimulationServiceInternalError(RuntimeError): - """The simulation service failed (500), possibly after creating the job. - - The job may already exist, so submitting again may create a second one; - this is why it is not reported as the service being unavailable. Like - SimulationServiceAnswerUnreadableError, its message asks the caller to - submit again and says this creates a second job if the first request went - through. - """ - - -class SimulationServiceInvalidRequestError(ValueError): - """The simulation service refuses the caller's data; the message says why. - - Such as a stored household or policy value its household contract cannot - take, or an option it refuses. - """ diff --git a/policyengine_api/services/v2/simulation_service/__init__.py b/policyengine_api/services/v2/simulation_service/__init__.py new file mode 100644 index 000000000..810eba404 --- /dev/null +++ b/policyengine_api/services/v2/simulation_service/__init__.py @@ -0,0 +1 @@ +"""What the Public API sends the simulation service, and what it answers.""" diff --git a/policyengine_api/services/v2/simulation_service/services.py b/policyengine_api/services/v2/simulation_service/services.py new file mode 100644 index 000000000..97f7870e1 --- /dev/null +++ b/policyengine_api/services/v2/simulation_service/services.py @@ -0,0 +1,95 @@ +"""Check simulations and reports, then ask the simulation service to create them. + +Every submission to the simulation service's ``POST /simulations`` and +``POST /reports`` goes through ``SimulationSubmissionService``, so checks +that apply to both live in one place. It checks, in order, that the +country's ``countries`` row allows economy calculations (a household-only +country does not) and that each policy the submission names is stored in the +country, through the same service as ``/v2/policies``; current law names +none. Only then is the simulation service asked. The dynamics a submission +names, its region and its dataset are checked by the simulation service, +which reads them in the catalog version its default worker runs. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlalchemy.exc import SQLAlchemyError + +from policyengine_api.services.v2.simulation_service.validators import ( + SubmissionStorageError, + require_economy_country, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Iterable + from uuid import UUID + + from policyengine_api.services.v2.simulation_service.types import ( + CountrySource, + EconomyReportCreationInput, + EconomySimulationCreationInput, + PolicySource, + SimulationServiceClient, + SubmittedReport, + SubmittedSimulation, + ) + + +class SimulationSubmissionService: + """Check submissions, then send them to the simulation service.""" + + def __init__( + self, + *, + countries: CountrySource, + policies: PolicySource, + client_factory: Callable[[], SimulationServiceClient], + ) -> None: + """Check through these sources; send through ``client_factory``'s client. + + The client is built only once a submission passes the checks, so a + refused submission gets its own answer even when the simulation + service is not configured. + """ + self._countries = countries + self._policies = policies + self._client_factory = client_factory + + def _check(self, country_id: str, policy_ids: Iterable[UUID | None]) -> None: + """Raise unless the country has economy calculations and stores the policies. + + Raise EconomyCalculationsUnsupportedError, then PolicyNotFoundError, + and SubmissionStorageError when the database cannot be read. + """ + try: + require_economy_country(self._countries.list_countries(), country_id) + for policy_id in dict.fromkeys(policy_ids): + if policy_id is not None: + self._policies.get_policy( + country_id=country_id, policy_id=policy_id + ) + except SQLAlchemyError as error: + msg = "V2 storage is unavailable to check the submission" + raise SubmissionStorageError(msg) from error + + def submit_simulation( + self, simulation: EconomySimulationCreationInput + ) -> SubmittedSimulation: + """Check the simulation, then have the simulation service create and start it. + + Raise the checks' errors, then the simulation service's. + """ + self._check(simulation.country_id, (simulation.policy_id,)) + return self._client_factory().submit_simulation(simulation) + + def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: + """Check the report, then have the simulation service create and start it. + + Raise the checks' errors, then the simulation service's. + """ + self._check( + report.country_id, (report.baseline.policy_id, report.reform.policy_id) + ) + return self._client_factory().submit_report(report) diff --git a/policyengine_api/services/v2/simulation_service/types.py b/policyengine_api/services/v2/simulation_service/types.py new file mode 100644 index 000000000..da92249eb --- /dev/null +++ b/policyengine_api/services/v2/simulation_service/types.py @@ -0,0 +1,274 @@ +"""What the Public API asks the simulation service, and how the service answers. + +The simulation service creates simulations, reports and their runs in the +detailed-save tables, and starts their calculation on Modal. Its +``POST /simulations`` and ``POST /reports`` are reached through +``SimulationServiceClient``; ``policyengine_api.libs.simulation_reports`` +implements it over HTTP, and tests replace it with a stand-in. Reading what +it created needs no call: the Public API reads the tables. + +The simulation service runs every calculation on its default worker's +PolicyEngine.py version, so no request names a version. + +The ``SimulationService*Error`` types are the simulation service's failures +for every v2 route that calls it: household calculations +(``policyengine_api.libs.simulation_household_calculations``) as well as +reports and simulations. Each client's module docstring lists which of its +service's answers it raises as which. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Annotated, Any, Literal, Protocol + +from pydantic import BaseModel, ConfigDict, Field, StrictBool, field_validator +from pydantic.json_schema import SkipJsonSchema + +from policyengine_api.query_parameters import CountryId, ResourceId +from policyengine_api.spm import SPMSelection + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.services.v2.countries.types import CountryRead + from policyengine_api.services.v2.policies.types import CheckedPolicyRead + +# The bounds the simulation service and the tables accept. +SimulationYear = Annotated[int, Field(ge=1900, le=2200, description="The year")] +CatalogKey = Annotated[str, Field(min_length=1, max_length=255, pattern=r"^\S+$")] +ReportLabel = Annotated[str, Field(min_length=1, max_length=255)] +ReportDescription = Annotated[str, Field(max_length=10_000)] + + +class SimulationServiceUnavailableError(RuntimeError): + """The simulation service could not be asked, or cannot serve the request now. + + It covers a connection never made, a gateway token that cannot be + fetched, missing configuration, and every answer after which nothing the + submission asked for runs: a 401, 403, 404, 405, 413 or 429, which the + gateway, Cloud Run or the service's framework answers before the + service's route runs; the service's own readable 503; a 400 that + describes the service's state, or a row the Public API checks first, + rather than the caller's request (such as a catalog version missing + while a release deploys); and a 400 or 422 the client cannot read. The + route answers 503. + + A message gives the service's reason only for a readable 400. For any + other answer it gives the status, and the code when that is a fixed + identifier, but never the reason, which for a 503 may be an exception's + text. + + Unless ``created_record_id`` is set, the service has created nothing + that will run, and submitting again creates one record or job. + ``created_record_id`` is the report or simulation the service's readable + 503 names as the submission's own: when Modal refuses the run's call, + the service creates the record, fails its run and answers 503 with the + record's ID. Submitting again then creates a second record, but starts + no second calculation: the record named has no running calculation. A + 503 that may follow a record the service created without naming it is + SimulationServiceAnswerUnreadableError instead. A household + calculation's 503 never names its job, which the service fails at once. + """ + + def __init__(self, message: str, *, created_record_id: UUID | None = None) -> None: + """Say why, and name the record the service created, if it names one.""" + super().__init__(message) + self.created_record_id = created_record_id + + +class SimulationServiceAnswerUnreadableError(RuntimeError): + """The service created what was submitted, or may have, but gave no usable answer. + + It answered that it created the household job, simulation or report, + but its answer cannot be read; or its answer was lost after the + submission may have reached it; or a proxy in front of it answered in + its place (a 502 or 504, or a 503 the client reads as a proxy's). Despite + the name, it also covers answers that can be read but leave open whether + something was created: any status the Public API does not expect, which + the service's route may answer after writing rows, and a report's or + simulation's 503 naming only another record, which shows the service + wrote rows. Submitting again could create another, so the route answers + 502. A message naming the service's status gives its code only when that + is a fixed identifier, and never its reason. + """ + + +class SimulationServiceInternalError(RuntimeError): + """The simulation service failed (500), possibly after creating what was submitted. + + The household job, simulation or report may already exist, so submitting + again may create a second one; this is why it is not reported as the + service being unavailable, and the route answers 502. The message gives + the status, and the code when that is a fixed identifier, but never the + service's reason, which may be an exception's text, and asks the caller + to submit again. + """ + + +class SimulationServiceInvalidRequestError(ValueError): + """The simulation service refused the caller's data, and said why. + + Such as a stored household or policy value its household contract cannot + take, an option it refuses, or a region, dataset or dynamic the catalog + version its default worker runs does not have. The message gives the + service's reasons, which describe the caller's own request, and, for a + report or simulation, the code the service gave, but not the service's + status. The route answers 422. + """ + + +@dataclass(frozen=True) +class PackageVersions: + """A country package version and the PolicyEngine.py version beside it.""" + + country_package_version: str + policyengine_version: str + + +class StrictSubmissionModel(BaseModel): + """Base for submissions: no unknown fields, finite numbers, immutable.""" + + model_config = ConfigDict(extra="forbid", allow_inf_nan=False, frozen=True) + + +class PolicyChoice(StrictSubmissionModel): + """A simulation's stored policy and dynamic; neither means current law.""" + + policy_id: ResourceId | None = None + dynamic_id: ResourceId | None = None + + +class EconomySimulationFields(PolicyChoice): + """An economy simulation: a policy and dynamic applied to one region's data. + + ``region_code`` is a region of the country's current catalog version + (``us``, ``state/ca``, ``country/wales``), and ``dataset_name`` one of its + datasets; without it the region's default dataset is used. + """ + + kind: Literal["economy"] + year: SimulationYear + region_code: CatalogKey + dataset_name: CatalogKey | None = None + + +class EconomySimulationCreationInput(EconomySimulationFields): + """An economy simulation to create in the country.""" + + country_id: CountryId + + +def _omit_spm_default(schema: dict[str, Any]) -> None: + # Omitting spm sends no SPM settings; an explicit null is not a selection. + schema.pop("default", None) + + +class EconomyReportFields(StrictSubmissionModel): + """An economy report: a baseline and a reform simulation of one region's data. + + Both simulations use the report's year, region and dataset, as + ``EconomySimulationFields`` describes them. ``include_cliffs`` also + calculates the baseline's and reform's cliff impact. ``spm`` selects the + SPM forecast scenario and geography; omit it, rather than sending null, + to use the simulation service's default. + """ + + kind: Literal["economy"] + label: ReportLabel + description: ReportDescription | None = None + year: SimulationYear + region_code: CatalogKey + dataset_name: CatalogKey | None = None + baseline: PolicyChoice + reform: PolicyChoice + include_cliffs: StrictBool = False + spm: SPMSelection | SkipJsonSchema[None] = Field( + default=None, json_schema_extra=_omit_spm_default + ) + + @field_validator("spm", mode="before") + @classmethod + def require_spm_object(cls, value: object) -> object: + """Refuse an explicit null ``spm``; omit the field to send no settings.""" + if value is None: + msg = "spm must be an object when supplied" + raise ValueError(msg) + return value + + +class EconomyReportCreationInput(EconomyReportFields): + """An economy report to create in the country.""" + + country_id: CountryId + + +@dataclass(frozen=True) +class SubmittedSimulation: + """The simulation the simulation service created, and the run it started.""" + + simulation_id: UUID + simulation_run_id: UUID + + +@dataclass(frozen=True) +class SubmittedReport: + """The report the simulation service created, and the run it started.""" + + report_id: UUID + report_run_id: UUID + + +class SimulationServiceClient(Protocol): + """The simulation service's routes that create and start calculations. + + Each raises: + + - SimulationServiceInvalidRequestError when the service refuses the + request's data (its 422, or its 400 for a region, dataset or dynamic it + cannot find), with its code and reasons; + - SimulationServiceInternalError when it failed (500), possibly after + creating the record; + - SimulationServiceAnswerUnreadableError when it created the record but + its answer cannot be read, its answer was lost after the submission may + have reached it, a proxy answered 502 or 504 in its place, it answered + 503 in a shape that cannot be read or naming only another record, or + it answered a status the client does not expect, which its route may + answer after writing rows; + - SimulationServiceUnavailableError otherwise: a connection never made, a + gateway token that cannot be fetched, missing configuration, a 400 or + 422 that cannot be read, any other 400, its readable 503, or a 401, + 403, 404, 405, 413 or 429, sent before its route runs. It names the + record the service created when the service's 503 names the + submission's own. + + ``SimulationSubmissionService``, which checks a submission before sending + it through a client, also raises EconomyCalculationsUnsupportedError, + PolicyNotFoundError and SubmissionStorageError from its checks. + """ + + def submit_simulation( + self, simulation: EconomySimulationCreationInput + ) -> SubmittedSimulation: + """Create the simulation and its first run, and start the run.""" + ... + + def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: + """Create the report, its simulations and their runs, and start them.""" + ... + + +class CountrySource(Protocol): + """The countries list a submission checks first.""" + + def list_countries(self) -> list[CountryRead]: + """Return every served country and what it supports.""" + ... + + +class PolicySource(Protocol): + """The stored policies a submission names.""" + + def get_policy(self, *, country_id: str, policy_id: UUID) -> CheckedPolicyRead: + """Return the country's policy, or raise ``PolicyNotFoundError``.""" + ... diff --git a/policyengine_api/services/v2/simulation_service/validators.py b/policyengine_api/services/v2/simulation_service/validators.py new file mode 100644 index 000000000..f7239ed23 --- /dev/null +++ b/policyengine_api/services/v2/simulation_service/validators.py @@ -0,0 +1,31 @@ +"""Database-independent checks of what is sent to the simulation service.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Iterable + + from policyengine_api.services.v2.countries.types import CountryRead + + +class EconomyCalculationsUnsupportedError(ValueError): + """The country has no economy (society-wide) simulations or reports. + + Its countries row leaves ``society_wide_enabled`` unset, as for a + household-only country, or it has no row. + """ + + +class SubmissionStorageError(RuntimeError): + """The countries or policies a submission is checked against could not be read.""" + + +def require_economy_country(countries: Iterable[CountryRead], country_id: str) -> None: + """Raise EconomyCalculationsUnsupportedError unless the row allows economy runs.""" + for country in countries: + if country.id == country_id and country.society_wide_enabled: + return + msg = f"Economy calculations are not available for country {country_id!r}" + raise EconomyCalculationsUnsupportedError(msg) diff --git a/policyengine_api/services/v2/stored_reports/__init__.py b/policyengine_api/services/v2/stored_reports/__init__.py new file mode 100644 index 000000000..34bf27268 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/__init__.py @@ -0,0 +1 @@ +"""Native v2 reports: create them through the simulation service, and read them.""" diff --git a/policyengine_api/services/v2/stored_reports/database_connectors/__init__.py b/policyengine_api/services/v2/stored_reports/database_connectors/__init__.py new file mode 100644 index 000000000..174f5e3a1 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/database_connectors/__init__.py @@ -0,0 +1 @@ +"""SQL-only connector functions for reading v2 reports and their results.""" diff --git a/policyengine_api/services/v2/stored_reports/database_connectors/reads.py b/policyengine_api/services/v2/stored_reports/database_connectors/reads.py new file mode 100644 index 000000000..a664b3e13 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/database_connectors/reads.py @@ -0,0 +1,96 @@ +"""Database reads of v2 reports and their newest runs.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlalchemy import and_, func, select +from sqlalchemy.orm import aliased +from sqlmodel import col + +from policyengine_api.data.v2.models import ( + Dataset, + Region, + Report, + ReportRun, + Simulation, +) +from policyengine_api.services.v2.stored_reports.types import StoredReportRows + +if TYPE_CHECKING: + from collections.abc import Collection + from uuid import UUID + + from sqlmodel import Session + + +def read_report_rows( + session: Session, *, country_id: str, report_ids: Collection[UUID] +) -> list[StoredReportRows]: + """Return the country's reports among ``report_ids``, in one query. + + Each comes with its region's code, its dataset's name, its two simulations + and its newest run: the run created last (ties broken by the larger ID), + whatever its status and versions. Runs of a budget window's years are not + the report's own runs, so they are left out. Reports of other countries, + and IDs no report has, are absent from the list, which has no set order. + """ + run_rank = ( + func.row_number() + .over( + partition_by=col(ReportRun.report_id), + order_by=(col(ReportRun.created_at).desc(), col(ReportRun.id).desc()), + ) + .label("newest_first") + ) + ranked_runs = ( + select(ReportRun, run_rank) + .where( + col(ReportRun.report_id).in_(report_ids), + col(ReportRun.budget_window_run_id).is_(None), + ) + .subquery("ranked_report_runs") + ) + newest_run = aliased(ReportRun, ranked_runs) + baseline_simulation = aliased(Simulation) + reform_simulation = aliased(Simulation) + statement = ( + select( + Report, + col(Region.code), + col(Dataset.name), + baseline_simulation, + reform_simulation, + newest_run, + ) + .outerjoin(Region, col(Region.id) == Report.region_id) + .outerjoin(Dataset, col(Dataset.id) == Report.dataset_id) + .outerjoin( + baseline_simulation, + col(baseline_simulation.id) == Report.baseline_simulation_id, + ) + .outerjoin( + reform_simulation, col(reform_simulation.id) == Report.reform_simulation_id + ) + .outerjoin( + newest_run, + and_( + col(newest_run.report_id) == Report.id, + ranked_runs.c.newest_first == 1, + ), + ) + .where(col(Report.country) == country_id, col(Report.id).in_(report_ids)) + ) + return [ + StoredReportRows( + report=report, + region_code=region_code, + dataset_name=dataset_name, + baseline_simulation=baseline, + reform_simulation=reform, + newest_run=run, + ) + for report, region_code, dataset_name, baseline, reform, run in session.execute( + statement + ).all() + ] diff --git a/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py b/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py new file mode 100644 index 000000000..adae01e21 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py @@ -0,0 +1,140 @@ +"""Database reads of one report run's result rows.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlmodel import col, select + +from policyengine_api.data.v2.models import ( + BudgetSummary, + CongressionalDistrictImpact, + ConstituencyImpact, + DecileImpact, + Inequality, + IntraDecileImpact, + LaborSupplyDecileResponse, + LaborSupplyResponse, + LocalAuthorityImpact, + Poverty, + ProgramStatistics, +) +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResultRows, + ReportRunResultColumns, +) + +if TYPE_CHECKING: + from uuid import UUID + + from sqlmodel import Session + + from policyengine_api.data.v2.models import ReportRun + + +def read_economy_result_rows( + session: Session, + *, + country_id: str, + report_run: ReportRun, + reform_simulation_run_id: UUID, +) -> EconomyResultRows: + """Return every result row of ``report_run``, one query per result table. + + The comparison tables' rows are the report run's; the poverty and + inequality rows are those of its baseline and reform simulation runs. + """ + report_run_id = report_run.id + simulation_run_ids = ( + report_run.baseline_simulation_run_id, + reform_simulation_run_id, + ) + return EconomyResultRows( + country_id=country_id, + report_run=ReportRunResultColumns( + country_package_version=report_run.country_package_version, + data_version=report_run.data_version, + spm_provenance=report_run.spm_provenance, + baseline_cliff_gap=report_run.baseline_cliff_gap, + baseline_cliff_share=report_run.baseline_cliff_share, + reform_cliff_gap=report_run.reform_cliff_gap, + reform_cliff_share=report_run.reform_cliff_share, + ), + baseline_simulation_run_id=report_run.baseline_simulation_run_id, + reform_simulation_run_id=reform_simulation_run_id, + budget_summary=tuple( + session.exec( + select(BudgetSummary).where( + BudgetSummary.report_run_id == report_run_id + ) + ) + ), + program_statistics=tuple( + session.exec( + select(ProgramStatistics).where( + ProgramStatistics.report_run_id == report_run_id + ) + ) + ), + decile_impacts=tuple( + session.exec( + select(DecileImpact).where(DecileImpact.report_run_id == report_run_id) + ) + ), + intra_decile_impacts=tuple( + session.exec( + select(IntraDecileImpact).where( + IntraDecileImpact.report_run_id == report_run_id + ) + ) + ), + poverty=tuple( + session.exec( + select(Poverty).where( + col(Poverty.simulation_run_id).in_(simulation_run_ids) + ) + ) + ), + inequality=tuple( + session.exec( + select(Inequality).where( + col(Inequality.simulation_run_id).in_(simulation_run_ids) + ) + ) + ), + labor_supply_responses=tuple( + session.exec( + select(LaborSupplyResponse).where( + LaborSupplyResponse.report_run_id == report_run_id + ) + ) + ), + labor_supply_decile_responses=tuple( + session.exec( + select(LaborSupplyDecileResponse).where( + LaborSupplyDecileResponse.report_run_id == report_run_id + ) + ) + ), + congressional_district_impacts=tuple( + session.exec( + select(CongressionalDistrictImpact).where( + CongressionalDistrictImpact.report_run_id == report_run_id + ) + ) + ), + constituency_impacts=tuple( + session.exec( + select(ConstituencyImpact).where( + ConstituencyImpact.report_run_id == report_run_id + ) + ) + ), + local_authority_impacts=tuple( + session.exec( + select(LocalAuthorityImpact).where( + LocalAuthorityImpact.report_run_id == report_run_id + ) + ) + ), + ) diff --git a/policyengine_api/services/v2/stored_reports/database_session.py b/policyengine_api/services/v2/stored_reports/database_session.py new file mode 100644 index 000000000..f17c0f14a --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/database_session.py @@ -0,0 +1,30 @@ +"""Database session lifetime management for v2 report reads.""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy.orm import sessionmaker + from sqlmodel import Session + + +class StoredReportDatabaseSession: + """Open the read sessions V2StoredReportService uses. + + The Public API only reads reports, their runs and results; the simulation + service and its Modal workers write them. + """ + + def __init__(self, session_factory: sessionmaker[Session]) -> None: + """Use ``session_factory`` to open every session.""" + self._session_factory = session_factory + + @contextmanager + def read(self) -> Iterator[Session]: + """Yield a session for reads; nothing is committed.""" + with self._session_factory() as session: + yield session diff --git a/policyengine_api/services/v2/stored_reports/economy_results/__init__.py b/policyengine_api/services/v2/stored_reports/economy_results/__init__.py new file mode 100644 index 000000000..2e690f0ee --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/economy_results/__init__.py @@ -0,0 +1 @@ +"""Economy results rebuilt from a report run's result rows.""" diff --git a/policyengine_api/services/v2/stored_reports/economy_results/transformations.py b/policyengine_api/services/v2/stored_reports/economy_results/transformations.py new file mode 100644 index 000000000..c23a67612 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/economy_results/transformations.py @@ -0,0 +1,594 @@ +"""Rebuild a report run's economy result from its result rows. + +This reverses the simulation service's writer +(``policyengine_stage12_persistence.report_run_results``), part by part: + +- ``budget`` from ``budget_summary``'s household totals: the tax, benefit and + US state income tax changes, the baseline net income and the household + count. ``budgetary_impact`` is tax minus benefits, and a country with no + state income tax row reports 0. +- ``detailed_budget`` from ``program_statistics``, one program per row. +- ``decile`` and ``wealth_decile`` from ``decile_impacts``: income deciles + name no ranking variable, wealth deciles ``household_wealth_decile``. The + rows hold relative changes as percentages, the result as fractions. +- ``intra_decile`` and ``intra_wealth_decile`` from ``intra_decile_impacts``, + deciles 1 to 10; each category's ``all`` is the mean of its deciles. +- ``poverty``, ``poverty_by_gender`` and ``poverty_by_race`` from each + simulation run's ``poverty`` rows, and ``inequality`` from its + ``inequality`` row: the baseline value from the baseline run's row, the + reform value from the reform run's. +- ``labor_supply_response`` from ``labor_supply_responses`` and + ``labor_supply_decile_responses``. +- ``congressional_district_impact``, ``constituency_impact`` and + ``local_authority_impact`` from their tables, in district or area code + order. +- ``cliff_impact``, ``spm_provenance``, ``data_version`` and + ``model_version`` from the report run's own columns; the SPM receipts are + read as ``SPMComparisonProvenance``. + +An optional part with no rows is null. The writer stores no rows for an empty +list either, so a UK result whose areas were all withheld reads back with +null areas, and a UK wealth breakdown without deciles as no breakdown. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any, Literal + +from pydantic import ValidationError + +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + AgePoverty, + BaselineReformValue, + BudgetaryImpact, + CliffImpact, + CliffImpactInSimulation, + CongressionalDistrictImpact, + CongressionalDistrictImpacts, + ConstituencyImpact, + DecileChange, + EconomyResult, + EconomyResultUnreadableError, + GenderPoverty, + InequalityChange, + IntraDecileShares, + LaborSupplyDeciles, + LaborSupplyDecileValues, + LaborSupplyHours, + LaborSupplyRelativeResponse, + LaborSupplyResponse, + LocalAuthorityImpact, + PovertyByAge, + PovertyByGender, + PovertyByRace, + ProgramBudget, + RacePoverty, +) +from policyengine_api.spm import SPMComparisonProvenance + +if TYPE_CHECKING: + from collections.abc import Iterable, Sequence + from uuid import UUID + + from pydantic import JsonValue + + from policyengine_api.data.v2.models import ( + CongressionalDistrictImpact as CongressionalDistrictImpactRow, + ) + from policyengine_api.data.v2.models import DecileImpact as DecileImpactRow + from policyengine_api.data.v2.models import ( + IntraDecileImpact as IntraDecileImpactRow, + ) + from policyengine_api.data.v2.models import Poverty as PovertyRow + from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResultRows, + ReportRunResultColumns, + ) + +# .py's poverty types behind the result's "poverty" and "deep_poverty". +POVERTY_TYPES = { + "us": {"poverty": "spm", "deep_poverty": "spm_deep"}, + "uk": {"poverty": "relative_bhc", "deep_poverty": "absolute_bhc"}, +} +# The income each country's inequality measures rank households by. +INEQUALITY_INCOME_VARIABLES = { + "us": "household_net_income", + "uk": "equiv_hbai_household_net_income", +} +RACE_GROUPS = ("white", "black", "hispanic", "other") +WEALTH_DECILE_VARIABLE = "household_wealth_decile" +INTRA_DECILE_COLUMNS = { + "Lose more than 5%": "lose_more_than_5pct", + "Lose less than 5%": "lose_less_than_5pct", + "No change": "no_change", + "Gain less than 5%": "gain_less_than_5pct", + "Gain more than 5%": "gain_more_than_5pct", +} +STATE_INCOME_TAX_VARIABLE = "household_state_income_tax" +# The Census FIPS code of each state and the District of Columbia, which a +# district row stores in place of the state's abbreviation. +US_STATE_ABBREVIATIONS_BY_FIPS = { + 1: "AL", + 2: "AK", + 4: "AZ", + 5: "AR", + 6: "CA", + 8: "CO", + 9: "CT", + 10: "DE", + 11: "DC", + 12: "FL", + 13: "GA", + 15: "HI", + 16: "ID", + 17: "IL", + 18: "IN", + 19: "IA", + 20: "KS", + 21: "KY", + 22: "LA", + 23: "ME", + 24: "MD", + 25: "MA", + 26: "MI", + 27: "MN", + 28: "MS", + 29: "MO", + 30: "MT", + 31: "NE", + 32: "NV", + 33: "NH", + 34: "NJ", + 35: "NM", + 36: "NY", + 37: "NC", + 38: "ND", + 39: "OH", + 40: "OK", + 41: "OR", + 42: "PA", + 44: "RI", + 45: "SC", + 46: "SD", + 47: "TN", + 48: "TX", + 49: "UT", + 50: "VT", + 51: "VA", + 53: "WA", + 54: "WV", + 55: "WI", + 56: "WY", +} +DISCLOSURE_FIELDS = ( + "disclosure_tier", + "average_household_income_change_lower", + "average_household_income_change_upper", + "relative_household_income_change_lower", + "relative_household_income_change_upper", +) +Side = Literal["baseline", "reform"] + + +def _figure(value: float | None, *, name: str) -> float: + """Return a stored figure every result has, or raise if the row holds none.""" + if value is None: + msg = f"the stored {name} is null" + raise EconomyResultUnreadableError(msg) + return value + + +def _spm_provenance( + stored: dict[str, JsonValue] | None, +) -> SPMComparisonProvenance | None: + """Return the report run's stored SPM receipts, or None without any. + + Raise EconomyResultUnreadableError for receipts of another shape, such as + a baseline and reform whose receipts differ. + """ + if stored is None: + return None + try: + return SPMComparisonProvenance.model_validate(stored) + except ValidationError as error: + msg = "the report run's SPM receipts are of another shape" + raise EconomyResultUnreadableError(msg) from error + + +def economy_result(rows: EconomyResultRows) -> EconomyResult: + """Return the economy result ``rows`` hold. + + Raise EconomyResultUnreadableError when the rows lack a part every + economy result has, the stored SPM receipts are of another shape, or the + country has no known poverty measures. + """ + country_id = rows.country_id + if country_id not in POVERTY_TYPES: + msg = f"no poverty measures are known for country {country_id!r}" + raise EconomyResultUnreadableError(msg) + report_run = rows.report_run + if report_run.data_version is None: + msg = "the report run stores no data version" + raise EconomyResultUnreadableError(msg) + poverty = _PovertyRates(rows) + income_deciles, wealth_deciles = _decile_rows_by_type(rows.decile_impacts) + if not income_deciles: + msg = "the result has no income decile rows" + raise EconomyResultUnreadableError(msg) + has_wealth_shares = any( + row.decile_type == "wealth" for row in rows.intra_decile_impacts + ) + return EconomyResult( + spm_provenance=_spm_provenance(report_run.spm_provenance), + model_version=report_run.country_package_version, + data_version=report_run.data_version, + budget=_budget(rows), + detailed_budget=_detailed_budget(rows), + decile=_deciles(income_deciles), + inequality=_inequality(rows), + poverty=PovertyByAge( + poverty=poverty.by_age("poverty"), + deep_poverty=poverty.by_age("deep_poverty"), + ), + poverty_by_gender=PovertyByGender( + poverty=poverty.by_gender("poverty"), + deep_poverty=poverty.by_gender("deep_poverty"), + ), + poverty_by_race=poverty.by_race(), + intra_decile=_intra_decile(rows.intra_decile_impacts, "income"), + wealth_decile=_deciles(wealth_deciles) if wealth_deciles else None, + intra_wealth_decile=( + _intra_decile(rows.intra_decile_impacts, "wealth") + if has_wealth_shares + else None + ), + labor_supply_response=_labor_supply_response(rows), + constituency_impact=_constituencies(rows), + local_authority_impact=_local_authorities(rows), + congressional_district_impact=_districts(rows.congressional_district_impacts), + cliff_impact=_cliff_impact(report_run), + ) + + +def _budget(rows: EconomyResultRows) -> BudgetaryImpact: + household_totals = { + row.variable_name: row + for row in rows.budget_summary + if row.entity == "household" + } + + def figure(variable: str, column: Literal["change", "baseline_total"]) -> float: + row = household_totals.get(variable) + if row is None: + msg = f"the budget summary has no {variable} row" + raise EconomyResultUnreadableError(msg) + return _figure(getattr(row, column), name=f"{variable} {column}") + + tax = figure("household_tax", "change") + benefits = figure("household_benefits", "change") + state_income_tax = ( + figure(STATE_INCOME_TAX_VARIABLE, "change") + if rows.country_id == "us" or STATE_INCOME_TAX_VARIABLE in household_totals + else 0.0 + ) + return BudgetaryImpact( + tax_revenue_impact=tax, + state_tax_revenue_impact=state_income_tax, + benefit_spending_impact=benefits, + budgetary_impact=tax - benefits, + households=figure("household_weight", "baseline_total"), + baseline_net_income=figure("household_net_income", "baseline_total"), + ) + + +def _detailed_budget(rows: EconomyResultRows) -> dict[str, ProgramBudget]: + return { + row.program_name: ProgramBudget( + baseline=_figure(row.baseline_total, name=f"{row.program_name} baseline"), + reform=_figure(row.reform_total, name=f"{row.program_name} reform"), + difference=_figure(row.change, name=f"{row.program_name} change"), + is_tax=row.is_tax, + ) + for row in sorted(rows.program_statistics, key=lambda row: row.program_name) + } + + +def _decile_rows_by_type( + decile_rows: Iterable[DecileImpactRow], +) -> tuple[list[DecileImpactRow], list[DecileImpactRow]]: + """Return household net income's income-decile rows and wealth-decile rows.""" + income: list[DecileImpactRow] = [] + wealth: list[DecileImpactRow] = [] + for row in sorted(decile_rows, key=lambda row: row.decile): + if row.income_variable != "household_net_income" or row.entity != "household": + continue + if row.decile_variable is None: + income.append(row) + elif row.decile_variable == WEALTH_DECILE_VARIABLE: + wealth.append(row) + return income, wealth + + +def _deciles(decile_rows: Sequence[DecileImpactRow]) -> DecileChange: + return DecileChange( + average={ + str(row.decile): _figure(row.absolute_change, name="decile change") + for row in decile_rows + }, + relative={ + str(row.decile): ( + _figure(row.relative_change, name="relative decile change") / 100 + ) + for row in decile_rows + }, + ) + + +def _intra_decile( + shares: Iterable[IntraDecileImpactRow], decile_type: str +) -> IntraDecileShares: + """Return each category's share by decile, and its mean over the deciles. + + Every category is listed, as the simulation service lists them, with no + shares when the rows hold none. + """ + decile_rows = sorted( + (row for row in shares if row.decile_type == decile_type and row.decile > 0), + key=lambda row: row.decile, + ) + deciles: dict[str, list[float]] = {} + for label, column in INTRA_DECILE_COLUMNS.items(): + values = [getattr(row, column) for row in decile_rows] + deciles[label] = [value for value in values if value is not None] + return IntraDecileShares( + deciles=deciles, + all={ + label: sum(values) / len(values) if values else 0.0 + for label, values in deciles.items() + }, + ) + + +class _PovertyRates: + """Each simulation run's poverty rates, by measure and group.""" + + def __init__(self, rows: EconomyResultRows) -> None: + self._poverty_types = POVERTY_TYPES[rows.country_id] + self._run_ids: dict[Side, UUID] = { + "baseline": rows.baseline_simulation_run_id, + "reform": rows.reform_simulation_run_id, + } + self._rates: dict[tuple[UUID, str, str | None, str | None], PovertyRow] = { + ( + row.simulation_run_id, + row.poverty_type, + row.filter_variable, + row.filter_group, + ): row + for row in rows.poverty + if row.entity == "person" + } + + def has_rate(self, measure: str, filter_variable: str, filter_group: str) -> bool: + """Return whether either run has the measure's rate for the group.""" + poverty_type = self._poverty_types[measure] + return any( + (run_id, poverty_type, filter_variable, filter_group) in self._rates + for run_id in self._run_ids.values() + ) + + def rate( + self, measure: str, filter_variable: str | None, filter_group: str | None + ) -> BaselineReformValue: + """Return both runs' rates, or raise if either run has none.""" + poverty_type = self._poverty_types[measure] + values: dict[str, float] = {} + for side, run_id in self._run_ids.items(): + row = self._rates.get((run_id, poverty_type, filter_variable, filter_group)) + if row is None: + group = filter_group or "everyone" + msg = f"the {side} run has no {poverty_type} poverty rate for {group}" + raise EconomyResultUnreadableError(msg) + values[side] = _figure(row.rate, name=f"{poverty_type} poverty rate") + return BaselineReformValue(**values) + + def by_age(self, measure: str) -> AgePoverty: + return AgePoverty( + child=self.rate(measure, "age", "child"), + adult=self.rate(measure, "age", "adult"), + senior=self.rate(measure, "age", "senior"), + all=self.rate(measure, None, None), + ) + + def by_gender(self, measure: str) -> GenderPoverty: + return GenderPoverty( + male=self.rate(measure, "is_male", "male"), + female=self.rate(measure, "is_male", "female"), + ) + + def by_race(self) -> PovertyByRace | None: + """Return poverty by race, or None when no run has a race breakdown.""" + if not any(self.has_rate("poverty", "race", group) for group in RACE_GROUPS): + return None + return PovertyByRace( + poverty=RacePoverty( + white=self.rate("poverty", "race", "white"), + black=self.rate("poverty", "race", "black"), + hispanic=self.rate("poverty", "race", "hispanic"), + other=self.rate("poverty", "race", "other"), + ) + ) + + +def _inequality(rows: EconomyResultRows) -> InequalityChange: + income_variable = INEQUALITY_INCOME_VARIABLES[rows.country_id] + by_run = { + row.simulation_run_id: row + for row in rows.inequality + if row.income_variable == income_variable and row.entity == "household" + } + measures: dict[str, dict[str, float]] = { + "gini": {}, + "top_10_pct_share": {}, + "top_1_pct_share": {}, + } + for side, run_id in ( + ("baseline", rows.baseline_simulation_run_id), + ("reform", rows.reform_simulation_run_id), + ): + row = by_run.get(run_id) + if row is None: + msg = f"the {side} run has no inequality row" + raise EconomyResultUnreadableError(msg) + measures["gini"][side] = _figure(row.gini, name="gini") + measures["top_10_pct_share"][side] = _figure( + row.top_10_share, name="top 10% share" + ) + measures["top_1_pct_share"][side] = _figure( + row.top_1_share, name="top 1% share" + ) + return InequalityChange( + gini=BaselineReformValue(**measures["gini"]), + top_10_pct_share=BaselineReformValue(**measures["top_10_pct_share"]), + top_1_pct_share=BaselineReformValue(**measures["top_1_pct_share"]), + ) + + +def _labor_supply_response(rows: EconomyResultRows) -> LaborSupplyResponse | None: + if not rows.labor_supply_responses: + return None + response = rows.labor_supply_responses[0] + deciles = sorted(rows.labor_supply_decile_responses, key=lambda row: row.decile) + + def by_decile(column: str) -> dict[int, float]: + return { + row.decile: getattr(row, column) + for row in deciles + if getattr(row, column) is not None + } + + return LaborSupplyResponse( + substitution_lsr=response.substitution_effect_earnings_change, + income_lsr=response.income_effect_earnings_change, + relative_lsr=LaborSupplyRelativeResponse( + income=response.relative_income_effect, + substitution=response.relative_substitution_effect, + ), + total_change=response.total_earnings_change, + revenue_change=response.revenue_change, + decile=LaborSupplyDeciles( + average=LaborSupplyDecileValues( + income=by_decile("average_income_effect"), + substitution=by_decile("average_substitution_effect"), + ), + relative=LaborSupplyDecileValues( + income=by_decile("relative_income_effect"), + substitution=by_decile("relative_substitution_effect"), + ), + ), + hours=LaborSupplyHours( + baseline=response.baseline_weekly_hours, + reform=response.reform_weekly_hours, + change=response.weekly_hours_change, + income_effect=response.weekly_hours_income_effect, + substitution_effect=response.weekly_hours_substitution_effect, + ), + ) + + +def _area_values(row: object) -> dict[str, Any]: + """Return a UK area row's income changes, population and disclosure fields.""" + return { + field: getattr(row, field) + for field in ( + "average_household_income_change", + "relative_household_income_change", + "population", + *DISCLOSURE_FIELDS, + ) + } + + +def _constituencies(rows: EconomyResultRows) -> list[ConstituencyImpact] | None: + if not rows.constituency_impacts: + return None + return [ + ConstituencyImpact( + constituency_code=row.constituency_code, + constituency_name=row.constituency_name, + **_area_values(row), + ) + for row in sorted( + rows.constituency_impacts, key=lambda row: row.constituency_code + ) + ] + + +def _local_authorities(rows: EconomyResultRows) -> list[LocalAuthorityImpact] | None: + if not rows.local_authority_impacts: + return None + return [ + LocalAuthorityImpact( + local_authority_code=row.local_authority_code, + local_authority_name=row.local_authority_name, + **_area_values(row), + ) + for row in sorted( + rows.local_authority_impacts, key=lambda row: row.local_authority_code + ) + ] + + +def _district_name(row: CongressionalDistrictImpactRow) -> str: + """Return the district as ``ST-NN``; an at-large district (number 0) is ``01``.""" + state = US_STATE_ABBREVIATIONS_BY_FIPS.get(row.state_fips) + if state is None: + msg = f"a congressional district names unknown state FIPS {row.state_fips}" + raise EconomyResultUnreadableError(msg) + number = 1 if row.district_number == 0 else row.district_number + return f"{state}-{number:02d}" + + +def _districts( + district_rows: Sequence[CongressionalDistrictImpactRow], +) -> CongressionalDistrictImpacts | None: + if not district_rows: + return None + return CongressionalDistrictImpacts( + districts=[ + CongressionalDistrictImpact( + district=_district_name(row), + average_household_income_change=row.average_household_income_change, + relative_household_income_change=row.relative_household_income_change, + winner_percentage=row.winner_percentage, + loser_percentage=row.loser_percentage, + no_change_percentage=row.no_change_percentage, + population=row.population, + ) + for row in sorted(district_rows, key=lambda row: row.district_geoid) + ] + ) + + +def _cliff_impact(report_run: ReportRunResultColumns) -> CliffImpact | None: + """Return the cliff impact, or None when the run stores none. + + The database keeps the four columns all set or all null. + """ + if ( + report_run.baseline_cliff_gap is None + or report_run.baseline_cliff_share is None + or report_run.reform_cliff_gap is None + or report_run.reform_cliff_share is None + ): + return None + return CliffImpact( + baseline=CliffImpactInSimulation( + cliff_gap=report_run.baseline_cliff_gap, + cliff_share=report_run.baseline_cliff_share, + ), + reform=CliffImpactInSimulation( + cliff_gap=report_run.reform_cliff_gap, + cliff_share=report_run.reform_cliff_share, + ), + ) diff --git a/policyengine_api/services/v2/stored_reports/economy_results/types.py b/policyengine_api/services/v2/stored_reports/economy_results/types.py new file mode 100644 index 000000000..4160a85ad --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/economy_results/types.py @@ -0,0 +1,376 @@ +"""The single-year economy result a report run's result rows hold. + +``EconomyResult`` has the fields and nesting of the simulation service's +``SingleYearMacroOutput`` (``policyengine_simulation_contract.macro_output``), +the result format the app reads today. The simulation service's Modal workers +store each result as rows of the result tables +(``policyengine_stage12_persistence.report_run_results``); +``EconomyResultRows`` holds the rows of one report run, and +``economy_results.transformations`` builds the result from them again. + +The UK local-area breakdown (``LocalAreaBreakdownOutput``), the result of a +separate run that computes only constituency and local-authority impacts, is +not part of it. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal + +from pydantic import BaseModel, ConfigDict, JsonValue + +from policyengine_api.spm import SPMComparisonProvenance + +if TYPE_CHECKING: + from uuid import UUID + + # The tables' models, named apart from the result parts they hold. + from policyengine_api.data.v2.models import BudgetSummary as BudgetSummaryRow + from policyengine_api.data.v2.models import ( + CongressionalDistrictImpact as CongressionalDistrictImpactRow, + ) + from policyengine_api.data.v2.models import ( + ConstituencyImpact as ConstituencyImpactRow, + ) + from policyengine_api.data.v2.models import DecileImpact as DecileImpactRow + from policyengine_api.data.v2.models import Inequality as InequalityRow + from policyengine_api.data.v2.models import ( + IntraDecileImpact as IntraDecileImpactRow, + ) + from policyengine_api.data.v2.models import ( + LaborSupplyDecileResponse as LaborSupplyDecileResponseRow, + ) + from policyengine_api.data.v2.models import ( + LaborSupplyResponse as LaborSupplyResponseRow, + ) + from policyengine_api.data.v2.models import ( + LocalAuthorityImpact as LocalAuthorityImpactRow, + ) + from policyengine_api.data.v2.models import Poverty as PovertyRow + from policyengine_api.data.v2.models import ( + ProgramStatistics as ProgramStatisticsRow, + ) + + +class EconomyResultUnreadableError(ValueError): + """A succeeded report run's rows lack a part every economy result has. + + The message names the missing part, never a row's values. + """ + + +class EconomyResultModel(BaseModel): + """Base of the economy result's parts: closed, immutable objects.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + +class BudgetaryImpact(EconomyResultModel): + """The reform's headline budget effect in the simulated year. + + Impacts are reform minus baseline totals in the country's currency; + ``budgetary_impact`` is ``tax_revenue_impact`` minus + ``benefit_spending_impact``, and ``state_tax_revenue_impact`` is US state + income tax (0 for the UK). ``households`` is the weighted number of + households and ``baseline_net_income`` their total baseline net income. + """ + + tax_revenue_impact: float + state_tax_revenue_impact: float + benefit_spending_impact: float + budgetary_impact: float + households: float + baseline_net_income: float + + +class ProgramBudget(EconomyResultModel): + """One program's baseline and reform totals, and reform minus baseline. + + ``is_tax`` says whether the program is a tax or a benefit, and is null for + results stored before the flag was recorded. + """ + + baseline: float + reform: float + difference: float + is_tax: bool | None + + +class DecileChange(EconomyResultModel): + """The change in average household net income in each decile, ``"1"`` to ``"10"``. + + ``average`` is the absolute change and ``relative`` the change as a + fraction of the decile's baseline average. + """ + + average: dict[str, float] + relative: dict[str, float] + + +class IntraDecileShares(EconomyResultModel): + """Shares of people in each decile who gain or lose, by size of the change. + + ``deciles`` lists each category's share for deciles 1 to 10 in order, and + ``all`` is each category's mean over those deciles. + """ + + deciles: dict[str, list[float]] + all: dict[str, float] + + +class BaselineReformValue(EconomyResultModel): + """A measure's value under the baseline and under the reform.""" + + baseline: float + reform: float + + +class AgePoverty(EconomyResultModel): + """Poverty rates for children, adults, seniors and everyone.""" + + child: BaselineReformValue + adult: BaselineReformValue + senior: BaselineReformValue + all: BaselineReformValue + + +class GenderPoverty(EconomyResultModel): + """Poverty rates for males and females.""" + + male: BaselineReformValue + female: BaselineReformValue + + +class RacePoverty(EconomyResultModel): + """US poverty rates by race and ethnicity.""" + + white: BaselineReformValue + black: BaselineReformValue + hispanic: BaselineReformValue + other: BaselineReformValue + + +class PovertyByAge(EconomyResultModel): + """Poverty and deep poverty rates by age group. + + In the US these are the SPM poverty and deep SPM poverty rates; in the UK, + relative and absolute poverty before housing costs. + """ + + poverty: AgePoverty + deep_poverty: AgePoverty + + +class PovertyByGender(EconomyResultModel): + """Poverty and deep poverty rates by gender.""" + + poverty: GenderPoverty + deep_poverty: GenderPoverty + + +class PovertyByRace(EconomyResultModel): + """US poverty rates by race; there is no deep poverty breakdown.""" + + poverty: RacePoverty + + +class InequalityChange(EconomyResultModel): + """The Gini coefficient and the top 10% and top 1% income shares.""" + + gini: BaselineReformValue + top_10_pct_share: BaselineReformValue + top_1_pct_share: BaselineReformValue + + +class LaborSupplyRelativeResponse(EconomyResultModel): + """Income- and substitution-effect responses relative to baseline earnings.""" + + income: float + substitution: float + + +class LaborSupplyDecileValues(EconomyResultModel): + """Income- and substitution-effect responses by income decile number.""" + + income: dict[int, float] + substitution: dict[int, float] + + +class LaborSupplyDeciles(EconomyResultModel): + """Labour supply responses by decile: per household, and relative to earnings.""" + + average: LaborSupplyDecileValues + relative: LaborSupplyDecileValues + + +class LaborSupplyHours(EconomyResultModel): + """Total weekly hours under the baseline and reform, and the change's effects.""" + + baseline: float + reform: float + change: float + income_effect: float + substitution_effect: float + + +class LaborSupplyResponse(EconomyResultModel): + """The behavioural labour supply response to the reform. + + ``income_lsr`` and ``substitution_lsr`` are the earnings changes from the + two effects, and ``total_change`` their sum. + """ + + substitution_lsr: float + income_lsr: float + relative_lsr: LaborSupplyRelativeResponse + total_change: float + revenue_change: float + decile: LaborSupplyDeciles + hours: LaborSupplyHours + + +class CliffImpactInSimulation(EconomyResultModel): + """Net income lost to a small earnings rise, and the share of adults on a cliff.""" + + cliff_gap: float + cliff_share: float + + +class CliffImpact(EconomyResultModel): + """Exposure to tax-benefit cliffs under the baseline and under the reform.""" + + baseline: CliffImpactInSimulation + reform: CliffImpactInSimulation + + +class UKAreaImpact(EconomyResultModel): + """The change in household net income in one published UK area. + + ``disclosure_tier`` is ``reported``, or ``approximate`` when the area's + sample is thin; the ``_lower`` and ``_upper`` fields bound each change's + 90% interval. They are null for results stored before disclosure control. + """ + + average_household_income_change: float + relative_household_income_change: float + population: float + disclosure_tier: Literal["reported", "approximate"] | None + average_household_income_change_lower: float | None + average_household_income_change_upper: float | None + relative_household_income_change_lower: float | None + relative_household_income_change_upper: float | None + + +class ConstituencyImpact(UKAreaImpact): + """The reform's impact in one UK parliamentary constituency.""" + + constituency_code: str + constituency_name: str + + +class LocalAuthorityImpact(UKAreaImpact): + """The reform's impact in one UK local authority.""" + + local_authority_code: str + local_authority_name: str + + +class CongressionalDistrictImpact(EconomyResultModel): + """The reform's impact in one US congressional district. + + ``district`` is the state and two-digit number, such as ``"CA-12"``; an + at-large district is ``01``. The percentages are the shares of people + whose household net income rises, falls or stays the same. + """ + + district: str + average_household_income_change: float + relative_household_income_change: float + winner_percentage: float + loser_percentage: float + no_change_percentage: float + population: float + + +class CongressionalDistrictImpacts(EconomyResultModel): + """The reform's impact in each congressional district of a US state report.""" + + districts: list[CongressionalDistrictImpact] + + +class EconomyResult(EconomyResultModel): + """A report run's single-year economy result, in the format the app reads. + + ``model_version`` is the country package version the run used, and + ``data_version`` the data release. ``spm_provenance`` is the baseline's + and reform's SPM calculation receipts the simulation service stored, as + the Public API's ``SPMComparisonProvenance`` (serialized, as the Public + API serializes it elsewhere, with package names as its runtime version + keys), or null. ``wealth_decile`` and ``intra_wealth_decile`` are UK-only; + ``poverty_by_race`` and ``congressional_district_impact`` US-only; the + constituency and local-authority impacts are UK-only and null when the + run did not compute them. ``labor_supply_response`` and ``cliff_impact`` + are null when the run did not compute them. + """ + + spm_provenance: SPMComparisonProvenance | None + model_version: str + data_version: str + budget: BudgetaryImpact + detailed_budget: dict[str, ProgramBudget] + decile: DecileChange + inequality: InequalityChange + poverty: PovertyByAge + poverty_by_gender: PovertyByGender + poverty_by_race: PovertyByRace | None + intra_decile: IntraDecileShares + wealth_decile: DecileChange | None + intra_wealth_decile: IntraDecileShares | None + labor_supply_response: LaborSupplyResponse | None + constituency_impact: list[ConstituencyImpact] | None + local_authority_impact: list[LocalAuthorityImpact] | None + congressional_district_impact: CongressionalDistrictImpacts | None + cliff_impact: CliffImpact | None + + +@dataclass(frozen=True) +class ReportRunResultColumns: + """The result columns of the report run itself. + + ``country_package_version`` is the run's; the four cliff columns are all + set or all null. + """ + + country_package_version: str + data_version: str | None + spm_provenance: dict[str, JsonValue] | None + baseline_cliff_gap: float | None + baseline_cliff_share: float | None + reform_cliff_gap: float | None + reform_cliff_share: float | None + + +@dataclass(frozen=True) +class EconomyResultRows: + """Every result row of one report run, as the database connectors read them. + + The comparison tables' rows are the report run's; the poverty and + inequality rows are those of its baseline and reform simulation runs. + """ + + country_id: str + report_run: ReportRunResultColumns + baseline_simulation_run_id: UUID + reform_simulation_run_id: UUID + budget_summary: tuple[BudgetSummaryRow, ...] + program_statistics: tuple[ProgramStatisticsRow, ...] + decile_impacts: tuple[DecileImpactRow, ...] + intra_decile_impacts: tuple[IntraDecileImpactRow, ...] + poverty: tuple[PovertyRow, ...] + inequality: tuple[InequalityRow, ...] + labor_supply_responses: tuple[LaborSupplyResponseRow, ...] + labor_supply_decile_responses: tuple[LaborSupplyDecileResponseRow, ...] + congressional_district_impacts: tuple[CongressionalDistrictImpactRow, ...] + constituency_impacts: tuple[ConstituencyImpactRow, ...] + local_authority_impacts: tuple[LocalAuthorityImpactRow, ...] diff --git a/policyengine_api/services/v2/stored_reports/services.py b/policyengine_api/services/v2/stored_reports/services.py new file mode 100644 index 000000000..dee832101 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/services.py @@ -0,0 +1,191 @@ +"""Create economy reports through the simulation service, and read them. + +Reading a report reads it within its country (``reports.country``), with its +newest run: the run created last, whatever its status and versions. That +differs from ``policyengine_api.data.v2.report_runs.select_current_report_run``, +which picks the newest succeeded run on the versions the Public API runs: a +report whose newest run used an older PolicyEngine.py version still answers +that run's result, beside the versions the Public API runs now, so the caller +can show the stored result and say a newer model version exists. Nothing is +calculated again on a read. A report with no run, as a report migrated from +v1 has none, answers its definition with no result. + +The result is rebuilt from the newest run's result rows once it has +succeeded. Lists name at most 25 reports and read them, with their newest +runs, in one query, without results. + +Creating a report checks the country and the policies the report names, asks +the simulation service to create and start it, then reads it back from the +tables. Once the simulation service has answered with the report's ID, the +report exists: a failure to read it back raises CreatedReportUnreadableError, +which names it, so the caller reads it rather than submitting it again. +Re-runs and run lists are not here. +""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING + +from sqlalchemy.exc import SQLAlchemyError + +from policyengine_api.data.v2.models import ReportRunStatus +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceUnavailableError, +) +from policyengine_api.services.v2.stored_reports.database_connectors import ( + reads_results as result_reads, +) +from policyengine_api.services.v2.stored_reports.database_connectors.reads import ( + read_report_rows, +) +from policyengine_api.services.v2.stored_reports.economy_results import ( + transformations as result_transformations, +) +from policyengine_api.services.v2.stored_reports.transformations import ( + listed_economy_reports, + report_read, + report_summary_read, +) +from policyengine_api.services.v2.stored_reports.validators import ( + CreatedReportUnreadableError, + ReportStorageError, + require_economy_report, + require_reform_run, + require_report, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Iterator, Sequence + from uuid import UUID + + from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + PackageVersions, + SimulationServiceClient, + ) + from policyengine_api.services.v2.stored_reports.database_session import ( + StoredReportDatabaseSession, + ) + from policyengine_api.services.v2.stored_reports.types import ( + ReportRead, + ReportSummaryRead, + ) + + +class SubmissionsNotConfiguredError(SimulationServiceUnavailableError): + """The service was built without a way to submit to the simulation service.""" + + +@contextmanager +def _storage_failures() -> Iterator[None]: + """Raise ReportStorageError for a failed database read.""" + try: + yield + except SQLAlchemyError as error: + msg = "V2 report storage is unavailable" + raise ReportStorageError(msg) from error + + +class V2StoredReportService: + """Read v2 reports and their results, and create economy reports.""" + + def __init__( + self, + database_session: StoredReportDatabaseSession, + *, + current_versions: Callable[[str], PackageVersions], + submissions: SimulationServiceClient | None = None, + ) -> None: + """Read through ``database_session``; create through ``submissions``. + + ``current_versions`` returns the country package and PolicyEngine.py + versions the Public API runs for a country. ``submissions`` is the + checking ``SimulationSubmissionService``; without it, creating a + report raises SubmissionsNotConfiguredError. + """ + self._database_session = database_session + self._current_versions = current_versions + self._submissions = submissions + + def get_report(self, *, country_id: str, report_id: UUID) -> ReportRead: + """Return the country's economy report, its newest run and that run's result. + + Raise StoredReportNotFoundError when the country has no such report, + ReportKindUnsupportedError for a household report or budget window, + EconomyResultUnreadableError when a succeeded run's rows lack a part + every result has, and ReportStorageError when the database cannot be + read. + """ + with _storage_failures(), self._database_session.read() as session: + stored = require_report( + next( + iter( + read_report_rows( + session, country_id=country_id, report_ids=(report_id,) + ) + ), + None, + ), + report_id=report_id, + country_id=country_id, + ) + require_economy_report(stored) + run = stored.newest_run + result = None + if run is not None and run.status is ReportRunStatus.SUCCEEDED: + result = result_transformations.economy_result( + result_reads.read_economy_result_rows( + session, + country_id=country_id, + report_run=run, + reform_simulation_run_id=require_reform_run(run), + ) + ) + return report_read( + stored, + current_versions=self._current_versions(country_id), + result=result, + ) + + def list_reports( + self, *, country_id: str, report_ids: Sequence[UUID] + ) -> tuple[ReportSummaryRead, ...]: + """Return the country's economy reports among ``report_ids``, without results. + + They are in the order named, each once; unknown reports, other + countries' and reports of other kinds are left out. Raise + ReportStorageError when the database cannot be read. + """ + with _storage_failures(), self._database_session.read() as session: + rows = read_report_rows( + session, country_id=country_id, report_ids=report_ids + ) + current_versions = self._current_versions(country_id) + return tuple( + report_summary_read(stored, current_versions=current_versions) + for stored in listed_economy_reports(rows, report_ids=report_ids) + ) + + def create_report(self, report_input: EconomyReportCreationInput) -> ReportRead: + """Create the report through the simulation service and return it as stored. + + Raise the submission's errors (see ``SimulationSubmissionService``), + and CreatedReportUnreadableError, caused by the read's own error, when + the report the simulation service created cannot be read back in the + country: not stored there, the database unavailable, or any other + failure of the read. + """ + if self._submissions is None: + msg = "The simulation service is not configured here" + raise SubmissionsNotConfiguredError(msg) + submitted = self._submissions.submit_report(report_input) + try: + return self.get_report( + country_id=report_input.country_id, report_id=submitted.report_id + ) + except Exception as error: + # The report exists whatever failed, so the caller gets its ID. + raise CreatedReportUnreadableError( + report_id=submitted.report_id, country_id=report_input.country_id + ) from error diff --git a/policyengine_api/services/v2/stored_reports/transformations.py b/policyengine_api/services/v2/stored_reports/transformations.py new file mode 100644 index 000000000..ff3c505e2 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/transformations.py @@ -0,0 +1,121 @@ +"""Convert stored report rows to the reads the report service returns.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.stored_reports.types import ( + ReportRead, + ReportRunRead, + ReportSimulationRead, + ReportSummaryRead, +) + +if TYPE_CHECKING: + from collections.abc import Iterable, Sequence + from uuid import UUID + + from policyengine_api.data.v2.models import Report, ReportRun, Simulation + from policyengine_api.services.v2.simulation_service.types import ( + PackageVersions, + ) + from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResult, + ) + from policyengine_api.services.v2.stored_reports.types import ( + ReportKind, + StoredReportRows, + ) + + +def report_kind(report: Report) -> ReportKind: + """Return what the report compares, from the columns its kind sets.""" + if report.household_id is not None: + return "household" + if report.budget_window_size is not None: + return "budget_window" + return "economy" + + +def report_run_read(run: ReportRun) -> ReportRunRead: + """Return the run's status, trigger, versions and times.""" + return ReportRunRead( + id=run.id, + status=run.status.value, + trigger=run.trigger.value, + country_package_version=run.country_package_version, + policyengine_version=run.policyengine_version, + baseline_simulation_run_id=run.baseline_simulation_run_id, + reform_simulation_run_id=run.reform_simulation_run_id, + error_message=run.error_message, + created_at=run.created_at, + started_at=run.started_at, + completed_at=run.completed_at, + ) + + +def _simulation(simulation: Simulation | None) -> ReportSimulationRead | None: + if simulation is None: + return None + return ReportSimulationRead( + id=simulation.id, + policy_id=simulation.policy_id, + dynamic_id=simulation.dynamic_id, + ) + + +def report_summary_read( + rows: StoredReportRows, *, current_versions: PackageVersions +) -> ReportSummaryRead: + """Return an economy report's definition and newest run, without a result.""" + report = rows.report + run = rows.newest_run + return ReportSummaryRead( + id=report.id, + country_id=report.country, + kind="economy", + label=report.label, + description=report.description, + year=report.year, + region_code=rows.region_code, + dataset_name=rows.dataset_name, + baseline_simulation=_simulation(rows.baseline_simulation), + reform_simulation=_simulation(rows.reform_simulation), + options=dict(report.inputs), + created_at=report.created_at, + status="not_run" if run is None else run.status.value, + run=None if run is None else report_run_read(run), + current_versions=current_versions, + ) + + +def report_read( + rows: StoredReportRows, + *, + current_versions: PackageVersions, + result: EconomyResult | None, +) -> ReportRead: + """Return an economy report with its newest run's result, if it has one.""" + summary = report_summary_read(rows, current_versions=current_versions) + return ReportRead(**vars(summary), result=result) + + +def listed_economy_reports( + rows: Iterable[StoredReportRows], *, report_ids: Sequence[UUID] +) -> list[StoredReportRows]: + """Return the economy reports among ``rows`` in the order of ``report_ids``. + + A report named twice is listed once, where it is first named; reports of + other kinds are left out. + """ + by_id = { + stored.report.id: stored + for stored in rows + if report_kind(stored.report) == "economy" + } + listed: list[StoredReportRows] = [] + for report_id in dict.fromkeys(report_ids): + stored = by_id.get(report_id) + if stored is not None: + listed.append(stored) + return listed diff --git a/policyengine_api/services/v2/stored_reports/types.py b/policyengine_api/services/v2/stored_reports/types.py new file mode 100644 index 000000000..9245ab1dd --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/types.py @@ -0,0 +1,115 @@ +"""Framework-independent data exchanged by the v2 report layers. + +A report compares a baseline and a reform simulation; each calculation of it +is a report run. The simulation service creates reports and their runs, and +its Modal workers store each run's result in the result tables; the Public +API reads all of them directly. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal + +if TYPE_CHECKING: + from datetime import datetime + from uuid import UUID + + from pydantic import JsonValue + + from policyengine_api.data.v2.models import Report, ReportRun, Simulation + from policyengine_api.services.v2.simulation_service.types import ( + PackageVersions, + ) + from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResult, + ) + +# A report's status is its newest run's, or not_run while it has none, as a +# report migrated from v1 has none. +ReportStatusName = Literal["not_run", "pending", "running", "succeeded", "failed"] +# What a report compares: two economy simulations, two household simulations, +# or two economy simulations in each year of a budget window. +ReportKind = Literal["economy", "household", "budget_window"] +ReportRunTriggerName = Literal["initial", "manual", "system"] + + +@dataclass(frozen=True) +class ReportRunRead: + """One calculation of a report, and the package versions it ran on. + + ``trigger`` is ``initial`` for the run the report's creation started. + ``error_message`` says why a failed run failed. + """ + + id: UUID + status: Literal["pending", "running", "succeeded", "failed"] + trigger: ReportRunTriggerName + country_package_version: str + policyengine_version: str + baseline_simulation_run_id: UUID + reform_simulation_run_id: UUID | None + error_message: str | None + created_at: datetime + started_at: datetime | None + completed_at: datetime | None + + +@dataclass(frozen=True) +class ReportSimulationRead: + """A simulation a report compares: its policy and dynamic, null for current law.""" + + id: UUID + policy_id: UUID | None + dynamic_id: UUID | None + + +@dataclass(frozen=True) +class ReportSummaryRead: + """A report's definition, its newest run and the versions the Public API runs. + + ``current_versions`` are the country package and PolicyEngine.py versions + the Public API serves now; a newest run on other versions is out of date. + ``options`` are the options the report was created with, as stored. + """ + + id: UUID + country_id: str + kind: Literal["economy"] + label: str + description: str | None + year: int | None + region_code: str | None + dataset_name: str | None + baseline_simulation: ReportSimulationRead | None + reform_simulation: ReportSimulationRead | None + options: dict[str, JsonValue] + created_at: datetime + status: ReportStatusName + run: ReportRunRead | None + current_versions: PackageVersions + + +@dataclass(frozen=True) +class ReportRead(ReportSummaryRead): + """A report with its newest run's result, once that run has succeeded.""" + + result: EconomyResult | None + + +@dataclass(frozen=True) +class StoredReportRows: + """A report's row, its newest run and the catalog and simulation rows it names. + + ``region_code`` and ``dataset_name`` are those of the report's region and + dataset, and null when it names none; a simulation is None once deleted. + ``newest_run`` is the report run created last, whatever its status and + versions, or None. + """ + + report: Report + region_code: str | None + dataset_name: str | None + baseline_simulation: Simulation | None + reform_simulation: Simulation | None + newest_run: ReportRun | None diff --git a/policyengine_api/services/v2/stored_reports/validators.py b/policyengine_api/services/v2/stored_reports/validators.py new file mode 100644 index 000000000..d74413c2b --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/validators.py @@ -0,0 +1,86 @@ +"""Database-independent checks of v2 reports and their runs.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResultUnreadableError, +) +from policyengine_api.services.v2.stored_reports.transformations import report_kind + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.data.v2.models import ReportRun + from policyengine_api.services.v2.stored_reports.types import StoredReportRows + +READABLE_KIND = "economy" +KIND_NAMES = {"household": "a household report", "budget_window": "a budget window"} + + +class StoredReportNotFoundError(LookupError): + """No report has this ID in the requested country.""" + + +class ReportStorageError(RuntimeError): + """The detailed-save database could not be read.""" + + +class CreatedReportUnreadableError(RuntimeError): + """The simulation service created the report, but it could not be read back. + + The simulation service answered with the report's ID, so the report + exists and submitting it again would create another. ``report_id`` and + ``country_id`` say where to read it; the error's cause says why reading + it back failed. + """ + + def __init__(self, *, report_id: UUID, country_id: str) -> None: + """Name the created report and its country.""" + super().__init__( + f"The simulation service created report {report_id} in country " + f"{country_id!r}, but it could not be read back" + ) + self.report_id = report_id + self.country_id = country_id + + +class ReportKindUnsupportedError(ValueError): + """The report is of a kind these routes do not read yet. + + Household reports and budget windows are stored in the same tables, and + are read once their own routes exist. + """ + + +def require_report( + rows: StoredReportRows | None, *, report_id: UUID, country_id: str +) -> StoredReportRows: + """Return the report's rows, or raise StoredReportNotFoundError for None.""" + if rows is None: + msg = f"Report {report_id} was not found in country {country_id!r}" + raise StoredReportNotFoundError(msg) + return rows + + +def require_economy_report(rows: StoredReportRows) -> None: + """Raise ReportKindUnsupportedError unless the report is an economy report.""" + kind = report_kind(rows.report) + if kind != READABLE_KIND: + msg = ( + f"Report {rows.report.id} is {KIND_NAMES[kind]}, which this route " + "cannot read yet" + ) + raise ReportKindUnsupportedError(msg) + + +def require_reform_run(report_run: ReportRun) -> UUID: + """Return the reform simulation run an economy report run compares. + + Raise EconomyResultUnreadableError for a run with only a baseline. + """ + if report_run.reform_simulation_run_id is None: + msg = "the report run names no reform simulation run" + raise EconomyResultUnreadableError(msg) + return report_run.reform_simulation_run_id diff --git a/policyengine_api/services/v2/stored_simulations/__init__.py b/policyengine_api/services/v2/stored_simulations/__init__.py new file mode 100644 index 000000000..f3ce7cde8 --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/__init__.py @@ -0,0 +1 @@ +"""Native v2 simulations: create them through the simulation service, and read them.""" diff --git a/policyengine_api/services/v2/stored_simulations/database_connectors/__init__.py b/policyengine_api/services/v2/stored_simulations/database_connectors/__init__.py new file mode 100644 index 000000000..2654f059c --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/database_connectors/__init__.py @@ -0,0 +1 @@ +"""SQL-only connector functions for reading v2 simulations.""" diff --git a/policyengine_api/services/v2/stored_simulations/database_connectors/reads.py b/policyengine_api/services/v2/stored_simulations/database_connectors/reads.py new file mode 100644 index 000000000..1e97891f8 --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/database_connectors/reads.py @@ -0,0 +1,88 @@ +"""Database reads of v2 simulations and their newest runs.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlalchemy import and_, func, select +from sqlalchemy.orm import aliased +from sqlmodel import col + +from policyengine_api.data.v2.models import ( + Dataset, + Region, + Simulation, + SimulationRun, + TaxBenefitModel, + TaxBenefitModelVersion, +) +from policyengine_api.services.v2.stored_simulations.types import ( + StoredSimulationRows, +) + +if TYPE_CHECKING: + from uuid import UUID + + from sqlmodel import Session + + +def read_simulation_rows( + session: Session, *, country_id: str, simulation_id: UUID +) -> StoredSimulationRows | None: + """Return the simulation if it is of the country's model, in one query. + + A simulation has no country column: its catalog version's model is the + country's (``policyengine-``). It comes with its region's code, + its dataset's name and its newest run: the run created last (ties broken + by the larger ID), whatever its year, status and versions. + """ + run_rank = ( + func.row_number() + .over( + partition_by=col(SimulationRun.simulation_id), + order_by=( + col(SimulationRun.created_at).desc(), + col(SimulationRun.id).desc(), + ), + ) + .label("newest_first") + ) + ranked_runs = ( + select(SimulationRun, run_rank) + .where(col(SimulationRun.simulation_id) == simulation_id) + .subquery("ranked_simulation_runs") + ) + newest_run = aliased(SimulationRun, ranked_runs) + statement = ( + select(Simulation, col(Region.code), col(Dataset.name), newest_run) + .join( + TaxBenefitModelVersion, + col(TaxBenefitModelVersion.id) == Simulation.tax_benefit_model_version_id, + ) + .join( + TaxBenefitModel, col(TaxBenefitModel.id) == TaxBenefitModelVersion.model_id + ) + .outerjoin(Region, col(Region.id) == Simulation.region_id) + .outerjoin(Dataset, col(Dataset.id) == Simulation.dataset_id) + .outerjoin( + newest_run, + and_( + col(newest_run.simulation_id) == Simulation.id, + ranked_runs.c.newest_first == 1, + ), + ) + .where( + col(Simulation.id) == simulation_id, + col(TaxBenefitModel.name) == f"policyengine-{country_id}", + ) + ) + row = session.execute(statement).one_or_none() + if row is None: + return None + simulation, region_code, dataset_name, run = row + return StoredSimulationRows( + simulation=simulation, + region_code=region_code, + dataset_name=dataset_name, + newest_run=run, + ) diff --git a/policyengine_api/services/v2/stored_simulations/database_session.py b/policyengine_api/services/v2/stored_simulations/database_session.py new file mode 100644 index 000000000..091d0a3ca --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/database_session.py @@ -0,0 +1,30 @@ +"""Database session lifetime management for v2 simulation reads.""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy.orm import sessionmaker + from sqlmodel import Session + + +class StoredSimulationDatabaseSession: + """Open the read sessions V2StoredSimulationService uses. + + The Public API only reads simulations and their runs; the simulation + service and its Modal workers write them. + """ + + def __init__(self, session_factory: sessionmaker[Session]) -> None: + """Use ``session_factory`` to open every session.""" + self._session_factory = session_factory + + @contextmanager + def read(self) -> Iterator[Session]: + """Yield a session for reads; nothing is committed.""" + with self._session_factory() as session: + yield session diff --git a/policyengine_api/services/v2/stored_simulations/services.py b/policyengine_api/services/v2/stored_simulations/services.py new file mode 100644 index 000000000..f891dd2ff --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/services.py @@ -0,0 +1,134 @@ +"""Create economy simulations through the simulation service, and read simulations. + +A simulation is read within the country whose model its catalog version +belongs to, with its newest run: the run created last, whatever its year, +status and versions, beside the versions the Public API runs now. Results +are not part of it: an economy run's output is a file, and a household +run's result is read with household reports. + +Creating a simulation checks the country and its policy, asks the +simulation service to create and start it, then reads it back. Once the +simulation service has answered with the simulation's ID, the simulation +exists: a failure to read it back raises CreatedSimulationUnreadableError, +which names it, so the caller reads it rather than submitting it again. +""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING + +from sqlalchemy.exc import SQLAlchemyError + +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceUnavailableError, +) +from policyengine_api.services.v2.stored_simulations.database_connectors.reads import ( + read_simulation_rows, +) +from policyengine_api.services.v2.stored_simulations.transformations import ( + simulation_read, +) +from policyengine_api.services.v2.stored_simulations.validators import ( + CreatedSimulationUnreadableError, + SimulationStorageError, + require_simulation, +) + +if TYPE_CHECKING: + from collections.abc import Callable, Iterator + from uuid import UUID + + from policyengine_api.services.v2.simulation_service.types import ( + EconomySimulationCreationInput, + PackageVersions, + SimulationServiceClient, + ) + from policyengine_api.services.v2.stored_simulations.database_session import ( + StoredSimulationDatabaseSession, + ) + from policyengine_api.services.v2.stored_simulations.types import SimulationRead + + +class SimulationSubmissionsNotConfiguredError(SimulationServiceUnavailableError): + """The service was built without a way to submit to the simulation service.""" + + +@contextmanager +def _storage_failures() -> Iterator[None]: + """Raise SimulationStorageError for a failed database read.""" + try: + yield + except SQLAlchemyError as error: + msg = "V2 simulation storage is unavailable" + raise SimulationStorageError(msg) from error + + +class V2StoredSimulationService: + """Read v2 simulations and their newest runs, and create economy simulations.""" + + def __init__( + self, + database_session: StoredSimulationDatabaseSession, + *, + current_versions: Callable[[str], PackageVersions], + submissions: SimulationServiceClient | None = None, + ) -> None: + """Read through ``database_session``; create through ``submissions``. + + ``current_versions`` returns the country package and PolicyEngine.py + versions the Public API runs for a country. ``submissions`` is the + checking ``SimulationSubmissionService``; without it, creating a + simulation raises SimulationSubmissionsNotConfiguredError. + """ + self._database_session = database_session + self._current_versions = current_versions + self._submissions = submissions + + def get_simulation(self, *, country_id: str, simulation_id: UUID) -> SimulationRead: + """Return the country's simulation and its newest run. + + Raise StoredSimulationNotFoundError when no simulation of the + country's model has this ID, and SimulationStorageError when the + database cannot be read. + """ + with _storage_failures(), self._database_session.read() as session: + stored = require_simulation( + read_simulation_rows( + session, country_id=country_id, simulation_id=simulation_id + ), + simulation_id=simulation_id, + country_id=country_id, + ) + return simulation_read( + stored, + country_id=country_id, + current_versions=self._current_versions(country_id), + ) + + def create_simulation( + self, simulation_input: EconomySimulationCreationInput + ) -> SimulationRead: + """Create the simulation through the simulation service; return it as stored. + + Raise the submission's errors (see ``SimulationSubmissionService``), + and CreatedSimulationUnreadableError, caused by the read's own error, + when the simulation the simulation service created cannot be read + back in the country: not stored there, the database unavailable, or + any other failure of the read. + """ + if self._submissions is None: + msg = "The simulation service is not configured here" + raise SimulationSubmissionsNotConfiguredError(msg) + submitted = self._submissions.submit_simulation(simulation_input) + try: + return self.get_simulation( + country_id=simulation_input.country_id, + simulation_id=submitted.simulation_id, + ) + except Exception as error: + # The simulation exists whatever failed, so the caller gets its ID. + raise CreatedSimulationUnreadableError( + simulation_id=submitted.simulation_id, + country_id=simulation_input.country_id, + ) from error diff --git a/policyengine_api/services/v2/stored_simulations/transformations.py b/policyengine_api/services/v2/stored_simulations/transformations.py new file mode 100644 index 000000000..2962bc788 --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/transformations.py @@ -0,0 +1,60 @@ +"""Convert stored simulation rows to the reads the simulation read service returns.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.stored_simulations.types import ( + SimulationRead, + SimulationRunRead, +) + +if TYPE_CHECKING: + from policyengine_api.data.v2.models import SimulationRun + from policyengine_api.services.v2.simulation_service.types import ( + PackageVersions, + ) + from policyengine_api.services.v2.stored_simulations.types import ( + StoredSimulationRows, + ) + + +def simulation_run_read(run: SimulationRun) -> SimulationRunRead: + """Return the run's year, status, versions and times.""" + return SimulationRunRead( + id=run.id, + year=run.year, + status=run.status.value, + country_package_version=run.country_package_version, + policyengine_version=run.policyengine_version, + error_message=run.error_message, + created_at=run.created_at, + started_at=run.started_at, + completed_at=run.completed_at, + ) + + +def simulation_read( + rows: StoredSimulationRows, + *, + country_id: str, + current_versions: PackageVersions, +) -> SimulationRead: + """Return a simulation's definition and newest run in its country.""" + simulation = rows.simulation + run = rows.newest_run + return SimulationRead( + id=simulation.id, + country_id=country_id, + kind=simulation.simulation_type.value, + policy_id=simulation.policy_id, + dynamic_id=simulation.dynamic_id, + household_id=simulation.household_id, + year=simulation.year, + region_code=rows.region_code, + dataset_name=rows.dataset_name, + created_at=simulation.created_at, + status="not_run" if run is None else run.status.value, + run=None if run is None else simulation_run_read(run), + current_versions=current_versions, + ) diff --git a/policyengine_api/services/v2/stored_simulations/types.py b/policyengine_api/services/v2/stored_simulations/types.py new file mode 100644 index 000000000..e622e65d3 --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/types.py @@ -0,0 +1,79 @@ +"""Framework-independent data exchanged by the v2 simulation layers. + +A simulation applies a policy and dynamic to one household or one dataset; +each calculation of it, for one year on one PolicyEngine.py version, is a +simulation run. The simulation service creates both; the Public API reads +them directly. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING, Literal + +if TYPE_CHECKING: + from datetime import datetime + from uuid import UUID + + from policyengine_api.data.v2.models import Simulation, SimulationRun + from policyengine_api.services.v2.simulation_service.types import ( + PackageVersions, + ) + +SimulationKind = Literal["economy", "household"] +# A simulation's status is its newest run's, or not_run while it has none. +SimulationStatusName = Literal["not_run", "pending", "running", "succeeded", "failed"] + + +@dataclass(frozen=True) +class SimulationRunRead: + """One calculation of a simulation, for one year on one package version pair.""" + + id: UUID + year: int + status: Literal["pending", "running", "succeeded", "failed"] + country_package_version: str + policyengine_version: str + error_message: str | None + created_at: datetime + started_at: datetime | None + completed_at: datetime | None + + +@dataclass(frozen=True) +class SimulationRead: + """A simulation's definition, its newest run and the versions the Public API runs. + + ``policy_id`` and ``dynamic_id`` are null for current law. An economy + simulation names its region and dataset, a household simulation its + household. ``current_versions`` are the versions the Public API serves + now; a newest run on other versions is out of date. + """ + + id: UUID + country_id: str + kind: SimulationKind + policy_id: UUID | None + dynamic_id: UUID | None + household_id: UUID | None + year: int | None + region_code: str | None + dataset_name: str | None + created_at: datetime + status: SimulationStatusName + run: SimulationRunRead | None + current_versions: PackageVersions + + +@dataclass(frozen=True) +class StoredSimulationRows: + """A simulation's row, its region's code, its dataset's name and its newest run. + + ``newest_run`` is the run created last, whatever its year, status and + versions, or None. + """ + + simulation: Simulation + region_code: str | None + dataset_name: str | None + newest_run: SimulationRun | None diff --git a/policyengine_api/services/v2/stored_simulations/validators.py b/policyengine_api/services/v2/stored_simulations/validators.py new file mode 100644 index 000000000..a3a7bdb5d --- /dev/null +++ b/policyengine_api/services/v2/stored_simulations/validators.py @@ -0,0 +1,49 @@ +"""Database-independent checks of v2 simulations.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.services.v2.stored_simulations.types import ( + StoredSimulationRows, + ) + + +class CreatedSimulationUnreadableError(RuntimeError): + """The simulation service created the simulation, but it could not be read back. + + The simulation service answered with the simulation's ID, so the + simulation exists and submitting it again would create another. + ``simulation_id`` and ``country_id`` say where to read it; the error's + cause says why reading it back failed. + """ + + def __init__(self, *, simulation_id: UUID, country_id: str) -> None: + """Name the created simulation and its country.""" + super().__init__( + f"The simulation service created simulation {simulation_id} in " + f"country {country_id!r}, but it could not be read back" + ) + self.simulation_id = simulation_id + self.country_id = country_id + + +class StoredSimulationNotFoundError(LookupError): + """No simulation of the country's model has this ID.""" + + +class SimulationStorageError(RuntimeError): + """The detailed-save database could not be read.""" + + +def require_simulation( + rows: StoredSimulationRows | None, *, simulation_id: UUID, country_id: str +) -> StoredSimulationRows: + """Return the simulation's rows, or raise StoredSimulationNotFoundError.""" + if rows is None: + msg = f"Simulation {simulation_id} was not found in country {country_id!r}" + raise StoredSimulationNotFoundError(msg) + return rows diff --git a/policyengine_api/services/v2/user_reports/database_connectors/creates.py b/policyengine_api/services/v2/user_reports/database_connectors/creates.py index 2dc5d838e..c128707b0 100644 --- a/policyengine_api/services/v2/user_reports/database_connectors/creates.py +++ b/policyengine_api/services/v2/user_reports/database_connectors/creates.py @@ -4,7 +4,14 @@ from typing import TYPE_CHECKING +from sqlalchemy.exc import IntegrityError + from policyengine_api.data.v2.models import UserReportAssociation +from policyengine_api.services.v2.associations.validators import violates_foreign_key +from policyengine_api.services.v2.user_reports.validators import ( + SAVED_REPORT_FOREIGN_KEY, + report_not_found, +) if TYPE_CHECKING: from sqlmodel import Session @@ -16,9 +23,25 @@ def create_user_report( session: Session, association_input: UserReportCreationInput, ) -> UserReportAssociation: - """Insert an association and return it with its database-generated fields loaded.""" + """Insert an association and return it with its database-generated fields loaded. + + Raise AssociationReportNotFoundError when the report's foreign key refuses + the insert: the service checked the report in this transaction, so it was + deleted after that check. The error names the input's report and + country, the ones the service checked. + """ association = UserReportAssociation(**association_input.model_dump()) session.add(association) - session.flush() + try: + session.flush() + except IntegrityError as error: + report_id = association_input.report_id + if report_id is not None and violates_foreign_key( + error, SAVED_REPORT_FOREIGN_KEY + ): + raise report_not_found( + report_id=report_id, country_id=association_input.country_id + ) from error + raise session.refresh(association) return association diff --git a/policyengine_api/services/v2/user_reports/database_connectors/reads.py b/policyengine_api/services/v2/user_reports/database_connectors/reads.py index e39a1afe4..0d78598f3 100644 --- a/policyengine_api/services/v2/user_reports/database_connectors/reads.py +++ b/policyengine_api/services/v2/user_reports/database_connectors/reads.py @@ -6,7 +6,11 @@ from sqlmodel import Session, col, select -from policyengine_api.data.v2.models import UserPolicy, UserReportAssociation +from policyengine_api.data.v2.models import ( + Report, + UserPolicy, + UserReportAssociation, +) if TYPE_CHECKING: from uuid import UUID @@ -127,3 +131,15 @@ def read_owned_user_policy_exists( ).one_or_none() is not None ) + + +def read_report_exists(session: Session, *, country_id: str, report_id: UUID) -> bool: + """Return whether a detailed-save report with this id is stored in the country.""" + return ( + session.exec( + select(Report.id).where( + Report.id == report_id, Report.country == country_id + ) + ).one_or_none() + is not None + ) diff --git a/policyengine_api/services/v2/user_reports/database_connectors/updates.py b/policyengine_api/services/v2/user_reports/database_connectors/updates.py index 4089c3373..557d8c8d6 100644 --- a/policyengine_api/services/v2/user_reports/database_connectors/updates.py +++ b/policyengine_api/services/v2/user_reports/database_connectors/updates.py @@ -4,7 +4,14 @@ from typing import TYPE_CHECKING, Any +from sqlalchemy.exc import IntegrityError + from policyengine_api.data.v2.models.base import utc_now +from policyengine_api.services.v2.associations.validators import violates_foreign_key +from policyengine_api.services.v2.user_reports.validators import ( + SAVED_REPORT_FOREIGN_KEY, + report_not_found, +) if TYPE_CHECKING: from collections.abc import Mapping @@ -19,11 +26,28 @@ def update_user_report( association: UserReportAssociation, values: Mapping[str, Any], ) -> UserReportAssociation: - """Set the given column values, bump ``updated_at`` and return the row.""" + """Set the given column values, bump ``updated_at`` and return the row. + + Raise AssociationReportNotFoundError when the report's foreign key refuses + the row's new ``report_id``: the service checked the report in this + transaction, so it was deleted after that check. The report and country + are read before the flush, which expires the row when it fails. + """ for field_name, value in values.items(): setattr(association, field_name, value) association.updated_at = utc_now() + report_id = association.report_id + country_id = association.country_id session.add(association) - session.flush() + try: + session.flush() + except IntegrityError as error: + if report_id is not None and violates_foreign_key( + error, SAVED_REPORT_FOREIGN_KEY + ): + raise report_not_found( + report_id=report_id, country_id=country_id + ) from error + raise session.refresh(association) return association diff --git a/policyengine_api/services/v2/user_reports/services.py b/policyengine_api/services/v2/user_reports/services.py index 8b1961eda..7fb276577 100644 --- a/policyengine_api/services/v2/user_reports/services.py +++ b/policyengine_api/services/v2/user_reports/services.py @@ -1,9 +1,14 @@ """Application services for native v2 user-report associations. -Stage 12A anchors saved reports on the requested v1 report output ID. The -owner always comes from the verified session principal (a signed-in user or a -signed-out browser), and v1 references are checked in a short read-only v1 -transaction before the v2 transaction opens. Reads never provision a +A saved report names a detailed-save report (``report_id``) or a v1 report +output (``legacy_report_id``), never both: v1 report numbers are not +connected to detailed-save reports, and only the production migration writes +saved reports holding both. A detailed-save report is checked with a SELECT +in the write's own transaction; one deleted before the write commits is +refused by the ``RESTRICT`` foreign key, which is answered as not found too. +The owner always comes from the verified session principal (a signed-in user +or a signed-out browser), and v1 references are checked in a short read-only +v1 transaction before the v2 transaction opens. Reads never provision a browser's unauthenticated user; one that does not exist yet owns no records. An optional ``user_policy_id`` (the saved reform the report was run from) and an optional ``baseline_user_policy_id`` (the saved reform it was compared with) @@ -20,6 +25,9 @@ from policyengine_api.services.v2.associations.services import ( require_legacy_reference, ) +from policyengine_api.services.v2.associations.validators import ( + require_one_reference, +) from policyengine_api.services.v2.identity.services import ( resolve_principal_user_for_read_in_session, resolve_principal_user_in_session, @@ -36,6 +44,7 @@ read_owned_user_policy_exists, read_owned_user_policy_row, read_owned_user_report_row, + read_report_exists, read_user_report_row, read_user_report_rows, ) @@ -52,6 +61,7 @@ from policyengine_api.services.v2.user_reports.types import UserReportListing from policyengine_api.services.v2.user_reports.validators import ( require_owned_user_policy, + require_stored_report, require_user_report, ) @@ -120,6 +130,48 @@ def validate_linked_user_policy( ) +def validate_stored_report( + session: Session, *, country_id: str, report_id: UUID | None +) -> None: + """Check, in the write's transaction, that a named report is stored in the country. + + A None ``report_id`` passes; otherwise raise AssociationReportNotFoundError. + """ + if report_id is None: + return + require_stored_report( + stored=read_report_exists(session, country_id=country_id, report_id=report_id), + report_id=report_id, + country_id=country_id, + ) + + +def require_one_report_after_update( + association: UserReportAssociation, association_input: UserReportUpdateInput +) -> None: + """Raise AssociationReferenceConflictError if the update leaves both references. + + Only an update that names a reference is checked, so a record the + production migration saved with both can still be renamed. + """ + supplied = association_input.model_fields_set + if not supplied.intersection({"report_id", "legacy_report_id"}): + return + require_one_reference( + "report", + detailed_save_id=( + association_input.report_id + if "report_id" in supplied + else association.report_id + ), + legacy_id=( + association_input.legacy_report_id + if "legacy_report_id" in supplied + else association.legacy_report_id + ), + ) + + def read_all_user_reports( session: Session, *, user_id: UUID ) -> tuple[UserReportRead, ...]: @@ -161,22 +213,36 @@ def create_user_report( principal: AccountPrincipal, association_input: UserReportCreateFields, ) -> UserReportRead: - """Save a v1 report for the principal, provisioning its v2 user if needed. + """Save a report for the principal, provisioning its v2 user if needed. - The v1 report is checked first, in a read-only v1 transaction, and - LegacyReferenceNotFoundError is raised if it does not exist in the - country. Each saved-reform link must name the owner's saved policy in - the same country, or AssociationLinkNotFoundError is raised. + A request naming both a report_id and a legacy_report_id raises + AssociationReferenceConflictError. A v1 report is checked first, in a + read-only v1 transaction, and LegacyReferenceNotFoundError is raised + if it does not exist in the country; a detailed-save report is + checked in the write's transaction, and + AssociationReportNotFoundError is raised if the country has none. + Each saved-reform link must name the owner's saved policy in the same + country, or AssociationLinkNotFoundError is raised. """ - self._require_legacy_report( - country_id=association_input.country_id, - legacy_report_id=association_input.legacy_report_id, + country_id = association_input.country_id + require_one_reference( + "report", + detailed_save_id=association_input.report_id, + legacy_id=association_input.legacy_report_id, ) + if association_input.legacy_report_id is not None: + self._require_legacy_report( + country_id=country_id, + legacy_report_id=association_input.legacy_report_id, + ) with self._database_session.transaction() as session: owner = resolve_principal_user_in_session( session, principal, - country_id=association_input.country_id, + country_id=country_id, + ) + validate_stored_report( + session, country_id=country_id, report_id=association_input.report_id ) for linked_user_policy_id in ( association_input.user_policy_id, @@ -294,11 +360,18 @@ def patch_user_report( ) -> UserReportRead: """Update the supplied fields of one of the principal's saved reports. - A new ``legacy_report_id`` is checked in v1 first, as on create, and a - supplied saved-reform link must name the owner's saved policy in this - country. Raise UserReportNotFoundError if the principal has no such - report in this country. + A new ``legacy_report_id`` is checked in v1 first and a new + ``report_id`` in the write's transaction, as on create, and a supplied + saved-reform link must name the owner's saved policy in this country. + Raise AssociationReferenceConflictError when the update would leave + the saved report naming both, and UserReportNotFoundError if the + principal has no such report in this country. """ + require_one_reference( + "report", + detailed_save_id=association_input.report_id, + legacy_id=association_input.legacy_report_id, + ) if association_input.legacy_report_id is not None: self._require_legacy_report( country_id=country_id, @@ -314,6 +387,10 @@ def patch_user_report( country_id=country_id, association_id=association_id, ) + require_one_report_after_update(association, association_input) + validate_stored_report( + session, country_id=country_id, report_id=association_input.report_id + ) for link_field in ("user_policy_id", "baseline_user_policy_id"): if link_field in association_input.model_fields_set: validate_linked_user_policy( diff --git a/policyengine_api/services/v2/user_reports/transformations.py b/policyengine_api/services/v2/user_reports/transformations.py index b029e0727..422990839 100644 --- a/policyengine_api/services/v2/user_reports/transformations.py +++ b/policyengine_api/services/v2/user_reports/transformations.py @@ -58,6 +58,7 @@ def shared_user_report_read( return SharedUserReportRead( id=association.id, country_id=association.country_id, + report_id=association.report_id, legacy_report_id=association.legacy_report_id, name=association.name, source_note=association.source_note, diff --git a/policyengine_api/services/v2/user_reports/types.py b/policyengine_api/services/v2/user_reports/types.py index 5cc0574e9..5170bbdc5 100644 --- a/policyengine_api/services/v2/user_reports/types.py +++ b/policyengine_api/services/v2/user_reports/types.py @@ -187,21 +187,43 @@ def bound_provisions(self) -> _ReportPresentationFields: return self +def _require_report_reference( + report_id: object | None, legacy_report_id: object | None +) -> None: + if report_id is None and legacy_report_id is None: + msg = "A saved report needs a report_id or legacy_report_id" + raise ValueError(msg) + + class UserReportCreateFields(_ReportPresentationFields): - """Caller-supplied fields; Stage 12A accepts only v1 report references.""" + """Caller-supplied fields; the owner comes from the request credential. + + The saved report names a detailed-save report of the country + (``report_id``) or a v1 report output (``legacy_report_id``); a request + naming both is refused, since v1 report numbers are not connected to + detailed-save reports. + """ country_id: CountryId - legacy_report_id: LegacyRecordId + report_id: ResourceId | None = None + legacy_report_id: LegacyRecordId | None = None user_policy_id: ResourceId | None = None baseline_user_policy_id: ResourceId | None = None + @model_validator(mode="after") + def require_report_reference(self) -> UserReportCreateFields: + """Require a report_id or a legacy_report_id.""" + _require_report_reference(self.report_id, self.legacy_report_id) + return self + class UserReportCreationInput(StrictUserReportModel): """Complete persisted association values, including the resolved owner.""" country_id: CountryId user_id: UserId - legacy_report_id: LegacyRecordId + report_id: ResourceId | None = None + legacy_report_id: LegacyRecordId | None = None name: AssociationName | None = None description: str | None = None user_policy_id: ResourceId | None = None @@ -216,19 +238,22 @@ class UserReportCreationInput(StrictUserReportModel): class UserReportUpdateInput(_ReportPresentationFields): """A partial update of a saved report; only supplied fields change. - At least one field must be supplied. ``legacy_report_id`` repoints the saved - report to another v1 report output and cannot be cleared; the saved-reform - links are cleared with null. + At least one field must be supplied. ``report_id`` repoints the saved + report to another detailed-save report and ``legacy_report_id`` to another + v1 report output; neither can be cleared, and a saved report never comes + to name both. The saved-reform links are cleared with null. """ + report_id: ResourceId | None = None legacy_report_id: LegacyRecordId | None = None user_policy_id: ResourceId | None = None baseline_user_policy_id: ResourceId | None = None @model_validator(mode="after") def require_valid_supplied_field(self) -> UserReportUpdateInput: - """Require a supplied field and reject a null ``legacy_report_id``.""" + """Require a supplied field and reject a null report reference.""" mutable_fields = { + "report_id", "legacy_report_id", "name", "description", @@ -244,9 +269,10 @@ def require_valid_supplied_field(self) -> UserReportUpdateInput: if not supplied: msg = "At least one mutable user-report field must be supplied" raise ValueError(msg) - if "legacy_report_id" in supplied and self.legacy_report_id is None: - msg = "legacy_report_id must not be null" - raise ValueError(msg) + for reference in ("report_id", "legacy_report_id"): + if reference in supplied and getattr(self, reference) is None: + msg = f"{reference} must not be null" + raise ValueError(msg) return self @@ -293,6 +319,7 @@ class SharedUserReportRead: id: UUID country_id: str + report_id: UUID | None legacy_report_id: int | None name: str | None source_note: str | None diff --git a/policyengine_api/services/v2/user_reports/validators.py b/policyengine_api/services/v2/user_reports/validators.py index 7d670ed35..4495c8495 100644 --- a/policyengine_api/services/v2/user_reports/validators.py +++ b/policyengine_api/services/v2/user_reports/validators.py @@ -19,6 +19,29 @@ class UserReportNotFoundError(AssociationNotFoundError): """Raised when an association is absent for the caller and country.""" +class AssociationReportNotFoundError(LookupError): + """A saved report names a detailed-save report the country does not have.""" + + +# The foreign key from saved reports to reports (``RESTRICT``). +SAVED_REPORT_FOREIGN_KEY = "fk_user_report_associations_report_id_reports" + + +def report_not_found( + *, report_id: UUID, country_id: str +) -> AssociationReportNotFoundError: + """Return the error for a detailed-save report the country does not have.""" + return AssociationReportNotFoundError( + f"Report {report_id} was not found in country {country_id!r}" + ) + + +def require_stored_report(*, stored: bool, report_id: UUID, country_id: str) -> None: + """Raise AssociationReportNotFoundError unless the report is ``stored``.""" + if not stored: + raise report_not_found(report_id=report_id, country_id=country_id) + + def require_user_report( association: UserReportAssociation | None, *, diff --git a/policyengine_api/services/v2/user_simulations/database_connectors/creates.py b/policyengine_api/services/v2/user_simulations/database_connectors/creates.py index 9f91e6604..1ce2fb883 100644 --- a/policyengine_api/services/v2/user_simulations/database_connectors/creates.py +++ b/policyengine_api/services/v2/user_simulations/database_connectors/creates.py @@ -4,7 +4,14 @@ from typing import TYPE_CHECKING +from sqlalchemy.exc import IntegrityError + from policyengine_api.data.v2.models import UserSimulationAssociation +from policyengine_api.services.v2.associations.validators import violates_foreign_key +from policyengine_api.services.v2.user_simulations.validators import ( + SAVED_SIMULATION_FOREIGN_KEY, + simulation_not_found, +) if TYPE_CHECKING: from sqlmodel import Session @@ -18,9 +25,26 @@ def create_user_simulation( session: Session, association_input: UserSimulationCreationInput, ) -> UserSimulationAssociation: - """Insert an association and return it with its database-generated fields loaded.""" + """Insert an association and return it with its database-generated fields loaded. + + Raise AssociationSimulationNotFoundError when the simulation's foreign key + refuses the insert: the service checked the simulation in this + transaction, so it was deleted after that check. The error names the + input's simulation and country, the ones the service checked. + """ association = UserSimulationAssociation(**association_input.model_dump()) session.add(association) - session.flush() + try: + session.flush() + except IntegrityError as error: + simulation_id = association_input.simulation_id + if simulation_id is not None and violates_foreign_key( + error, SAVED_SIMULATION_FOREIGN_KEY + ): + raise simulation_not_found( + simulation_id=simulation_id, + country_id=association_input.country_id, + ) from error + raise session.refresh(association) return association diff --git a/policyengine_api/services/v2/user_simulations/database_connectors/reads.py b/policyengine_api/services/v2/user_simulations/database_connectors/reads.py index 64609e364..b5ff39e4c 100644 --- a/policyengine_api/services/v2/user_simulations/database_connectors/reads.py +++ b/policyengine_api/services/v2/user_simulations/database_connectors/reads.py @@ -6,7 +6,12 @@ from sqlmodel import Session, col, select -from policyengine_api.data.v2.models import UserSimulationAssociation +from policyengine_api.data.v2.models import ( + Simulation, + TaxBenefitModel, + TaxBenefitModelVersion, + UserSimulationAssociation, +) if TYPE_CHECKING: from uuid import UUID @@ -78,3 +83,32 @@ def read_all_user_simulation_rows( ) ).all() ) + + +def read_simulation_exists( + session: Session, *, country_id: str, simulation_id: UUID +) -> bool: + """Return whether a detailed-save simulation of the country's model has this id. + + A simulation has no country column: its catalog version's model is the + country's (``policyengine-``). + """ + return ( + session.exec( + select(Simulation.id) + .join( + TaxBenefitModelVersion, + col(TaxBenefitModelVersion.id) + == Simulation.tax_benefit_model_version_id, + ) + .join( + TaxBenefitModel, + col(TaxBenefitModel.id) == TaxBenefitModelVersion.model_id, + ) + .where( + Simulation.id == simulation_id, + TaxBenefitModel.name == f"policyengine-{country_id}", + ) + ).one_or_none() + is not None + ) diff --git a/policyengine_api/services/v2/user_simulations/database_connectors/updates.py b/policyengine_api/services/v2/user_simulations/database_connectors/updates.py index 2e11cb6fe..acf0ad8a7 100644 --- a/policyengine_api/services/v2/user_simulations/database_connectors/updates.py +++ b/policyengine_api/services/v2/user_simulations/database_connectors/updates.py @@ -4,7 +4,14 @@ from typing import TYPE_CHECKING +from sqlalchemy.exc import IntegrityError + from policyengine_api.data.v2.models.base import utc_now +from policyengine_api.services.v2.associations.validators import violates_foreign_key +from policyengine_api.services.v2.user_simulations.validators import ( + SAVED_SIMULATION_FOREIGN_KEY, + simulation_not_found, +) if TYPE_CHECKING: from sqlmodel import Session @@ -20,11 +27,29 @@ def update_user_simulation( association: UserSimulationAssociation, association_input: UserSimulationUpdateInput, ) -> UserSimulationAssociation: - """Apply only the supplied fields, bump ``updated_at`` and return the row.""" + """Apply only the supplied fields, bump ``updated_at`` and return the row. + + Raise AssociationSimulationNotFoundError when the simulation's foreign key + refuses the row's new ``simulation_id``: the service checked the + simulation in this transaction, so it was deleted after that check. The + simulation and country are read before the flush, which expires the row + when it fails. + """ for field_name, value in association_input.model_dump(exclude_unset=True).items(): setattr(association, field_name, value) association.updated_at = utc_now() + simulation_id = association.simulation_id + country_id = association.country_id session.add(association) - session.flush() + try: + session.flush() + except IntegrityError as error: + if simulation_id is not None and violates_foreign_key( + error, SAVED_SIMULATION_FOREIGN_KEY + ): + raise simulation_not_found( + simulation_id=simulation_id, country_id=country_id + ) from error + raise session.refresh(association) return association diff --git a/policyengine_api/services/v2/user_simulations/services.py b/policyengine_api/services/v2/user_simulations/services.py index 8e2682aa5..9f6981d45 100644 --- a/policyengine_api/services/v2/user_simulations/services.py +++ b/policyengine_api/services/v2/user_simulations/services.py @@ -1,10 +1,15 @@ """Application services for native v2 user-simulation associations. -Stage 12A anchors saved simulations on v1 simulation IDs. The owner always -comes from the verified session principal (a signed-in user or a signed-out -browser), and v1 references are checked in a short read-only v1 transaction -before the v2 transaction opens. Reads never provision a browser's -unauthenticated user; one that does not exist yet owns no records. +A saved simulation names a detailed-save simulation (``simulation_id``) or a +v1 simulation (``legacy_simulation_id``), never both; only the production +migration writes saved simulations holding both. A detailed-save simulation +is checked with a SELECT in the write's own transaction; one deleted before +the write commits is refused by the ``RESTRICT`` foreign key, which is +answered as not found too. The owner always comes from the verified session +principal (a signed-in user or a signed-out browser), and v1 references are +checked in a short read-only v1 transaction before the v2 transaction opens. +Reads never provision a browser's unauthenticated user; one that does not +exist yet owns no records. """ from __future__ import annotations @@ -14,6 +19,9 @@ from policyengine_api.services.v2.associations.services import ( require_legacy_reference, ) +from policyengine_api.services.v2.associations.validators import ( + require_one_reference, +) from policyengine_api.services.v2.identity.services import ( resolve_principal_user_for_read_in_session, resolve_principal_user_in_session, @@ -28,6 +36,7 @@ from policyengine_api.services.v2.user_simulations.database_connectors.reads import ( read_all_user_simulation_rows, read_owned_user_simulation_row, + read_simulation_exists, read_user_simulation_rows, ) from policyengine_api.services.v2.user_simulations.database_connectors.updates import ( @@ -40,6 +49,7 @@ ) from policyengine_api.services.v2.user_simulations.types import UserSimulationListing from policyengine_api.services.v2.user_simulations.validators import ( + require_stored_simulation, require_user_simulation, ) @@ -83,6 +93,52 @@ def read_owned_user_simulation( ) +def validate_stored_simulation( + session: Session, *, country_id: str, simulation_id: UUID | None +) -> None: + """Check, in the write's transaction, that a named simulation is the country's. + + A None ``simulation_id`` passes; otherwise raise + AssociationSimulationNotFoundError. + """ + if simulation_id is None: + return + require_stored_simulation( + stored=read_simulation_exists( + session, country_id=country_id, simulation_id=simulation_id + ), + simulation_id=simulation_id, + country_id=country_id, + ) + + +def require_one_simulation_after_update( + association: UserSimulationAssociation, + association_input: UserSimulationUpdateInput, +) -> None: + """Raise AssociationReferenceConflictError if the update leaves both references. + + Only an update that names a reference is checked, so a record the + production migration saved with both can still be renamed. + """ + supplied = association_input.model_fields_set + if not supplied.intersection({"simulation_id", "legacy_simulation_id"}): + return + require_one_reference( + "simulation", + detailed_save_id=( + association_input.simulation_id + if "simulation_id" in supplied + else association.simulation_id + ), + legacy_id=( + association_input.legacy_simulation_id + if "legacy_simulation_id" in supplied + else association.legacy_simulation_id + ), + ) + + def read_all_user_simulations( session: Session, *, user_id: UUID ) -> tuple[UserSimulationRead, ...]: @@ -126,21 +182,36 @@ def create_user_simulation( principal: AccountPrincipal, association_input: UserSimulationCreateFields, ) -> UserSimulationRead: - """Save a v1 simulation for the principal, provisioning its v2 user if needed. + """Save a simulation for the principal, provisioning its v2 user if needed. - The v1 simulation is checked first, in a read-only v1 transaction, and - LegacyReferenceNotFoundError is raised if it does not exist in the - country. + A request naming both a simulation_id and a legacy_simulation_id + raises AssociationReferenceConflictError. A v1 simulation is checked + first, in a read-only v1 transaction, and LegacyReferenceNotFoundError + is raised if it does not exist in the country; a detailed-save + simulation is checked in the write's transaction, and + AssociationSimulationNotFoundError is raised if the country's model + has none. """ - self._require_legacy_simulation( - country_id=association_input.country_id, - legacy_simulation_id=association_input.legacy_simulation_id, + country_id = association_input.country_id + simulation_id = association_input.simulation_id + require_one_reference( + "simulation", + detailed_save_id=simulation_id, + legacy_id=association_input.legacy_simulation_id, ) + if association_input.legacy_simulation_id is not None: + self._require_legacy_simulation( + country_id=country_id, + legacy_simulation_id=association_input.legacy_simulation_id, + ) with self._database_session.transaction() as session: owner = resolve_principal_user_in_session( session, principal, - country_id=association_input.country_id, + country_id=country_id, + ) + validate_stored_simulation( + session, country_id=country_id, simulation_id=simulation_id ) return user_simulation_read( create_user_simulation( @@ -220,10 +291,17 @@ def patch_user_simulation( ) -> UserSimulationRead: """Update the supplied fields of one of the principal's associations. - A new ``legacy_simulation_id`` is checked in v1 first, as on create. Raise - UserSimulationNotFoundError if the principal has no such association in - this country. + A new ``legacy_simulation_id`` is checked in v1 first and a new + ``simulation_id`` in the write's transaction, as on create. Raise + AssociationReferenceConflictError when the update would leave the + saved simulation naming both, and UserSimulationNotFoundError if the + principal has no such association in this country. """ + require_one_reference( + "simulation", + detailed_save_id=association_input.simulation_id, + legacy_id=association_input.legacy_simulation_id, + ) if association_input.legacy_simulation_id is not None: self._require_legacy_simulation( country_id=country_id, @@ -233,17 +311,20 @@ def patch_user_simulation( owner = resolve_principal_user_in_session( session, principal, country_id=country_id ) + association = read_owned_user_simulation( + session, + user_id=owner.user_id, + country_id=country_id, + association_id=association_id, + ) + require_one_simulation_after_update(association, association_input) + validate_stored_simulation( + session, + country_id=country_id, + simulation_id=association_input.simulation_id, + ) return user_simulation_read( - update_user_simulation( - session, - read_owned_user_simulation( - session, - user_id=owner.user_id, - country_id=country_id, - association_id=association_id, - ), - association_input, - ) + update_user_simulation(session, association, association_input) ) def delete_user_simulation( diff --git a/policyengine_api/services/v2/user_simulations/types.py b/policyengine_api/services/v2/user_simulations/types.py index 26798a10d..489d82a88 100644 --- a/policyengine_api/services/v2/user_simulations/types.py +++ b/policyengine_api/services/v2/user_simulations/types.py @@ -7,7 +7,7 @@ from pydantic import model_validator -from policyengine_api.query_parameters import CountryId, UserId +from policyengine_api.query_parameters import CountryId, ResourceId, UserId from policyengine_api.services.v2.associations.types import ( AssociationDescription, AssociationName, @@ -24,21 +24,42 @@ class StrictUserSimulationInput(StrictAssociationModel): """Reject fields outside the reviewed user-simulation contract.""" +def _require_simulation_reference( + simulation_id: object | None, legacy_simulation_id: object | None +) -> None: + if simulation_id is None and legacy_simulation_id is None: + msg = "A saved simulation needs a simulation_id or legacy_simulation_id" + raise ValueError(msg) + + class UserSimulationCreateFields(StrictUserSimulationInput): - """Caller-supplied fields; Stage 12A accepts only v1 simulation references.""" + """Caller-supplied fields; the owner comes from the request credential. + + The saved simulation names a detailed-save simulation of the country's + model (``simulation_id``) or a v1 simulation (``legacy_simulation_id``); + a request naming both is refused. + """ country_id: CountryId - legacy_simulation_id: LegacyRecordId + simulation_id: ResourceId | None = None + legacy_simulation_id: LegacyRecordId | None = None name: AssociationName | None = None description: AssociationDescription | None = None + @model_validator(mode="after") + def require_simulation_reference(self) -> UserSimulationCreateFields: + """Require a simulation_id or a legacy_simulation_id.""" + _require_simulation_reference(self.simulation_id, self.legacy_simulation_id) + return self + class UserSimulationCreationInput(StrictUserSimulationInput): """Complete persisted association values, including the resolved owner.""" country_id: CountryId user_id: UserId - legacy_simulation_id: LegacyRecordId + simulation_id: ResourceId | None = None + legacy_simulation_id: LegacyRecordId | None = None name: AssociationName | None = None description: str | None = None @@ -46,29 +67,33 @@ class UserSimulationCreationInput(StrictUserSimulationInput): class UserSimulationUpdateInput(StrictUserSimulationInput): """A partial update of a saved simulation; only supplied fields change. - At least one field must be supplied. ``legacy_simulation_id`` repoints the - saved simulation to another v1 simulation and cannot be cleared. + At least one field must be supplied. ``simulation_id`` repoints the saved + simulation to another detailed-save simulation and + ``legacy_simulation_id`` to another v1 simulation; neither can be + cleared, and a saved simulation never comes to name both. """ + simulation_id: ResourceId | None = None legacy_simulation_id: LegacyRecordId | None = None name: AssociationName | None = None description: AssociationDescription | None = None @model_validator(mode="after") def require_valid_supplied_field(self) -> UserSimulationUpdateInput: - """Require a supplied field and reject a null ``legacy_simulation_id``.""" + """Require a supplied field and reject a null simulation reference.""" supplied = self.model_fields_set.intersection( - {"legacy_simulation_id", "name", "description"} + {"simulation_id", "legacy_simulation_id", "name", "description"} ) if not supplied: msg = ( - "At least one of legacy_simulation_id, name, or description must " - "be supplied" + "At least one of simulation_id, legacy_simulation_id, name, or " + "description must be supplied" ) raise ValueError(msg) - if "legacy_simulation_id" in supplied and self.legacy_simulation_id is None: - msg = "legacy_simulation_id must not be null" - raise ValueError(msg) + for reference in ("simulation_id", "legacy_simulation_id"): + if reference in supplied and getattr(self, reference) is None: + msg = f"{reference} must not be null" + raise ValueError(msg) return self @@ -76,9 +101,9 @@ def require_valid_supplied_field(self) -> UserSimulationUpdateInput: class UserSimulationRead: """A stored user-simulation association as the service returns it to routes. - Stage 12A saves only v1 simulations, so ``legacy_simulation_id`` names the - simulation. ``simulation_id``, when set, names a stored v2 simulation (a - foreign key). + ``simulation_id`` names a detailed-save simulation (a foreign key) and + ``legacy_simulation_id`` a v1 simulation; only the production migration + saves records naming both. """ id: UUID diff --git a/policyengine_api/services/v2/user_simulations/validators.py b/policyengine_api/services/v2/user_simulations/validators.py index 661cc82a4..4d28d9fca 100644 --- a/policyengine_api/services/v2/user_simulations/validators.py +++ b/policyengine_api/services/v2/user_simulations/validators.py @@ -18,6 +18,33 @@ class UserSimulationNotFoundError(AssociationNotFoundError): """Raised when an association is absent for the caller and country.""" +class AssociationSimulationNotFoundError(LookupError): + """A saved simulation names a detailed-save simulation the country lacks.""" + + +# The foreign key from saved simulations to simulations (``RESTRICT``). +SAVED_SIMULATION_FOREIGN_KEY = ( + "fk_user_simulation_associations_simulation_id_simulations" +) + + +def simulation_not_found( + *, simulation_id: UUID, country_id: str +) -> AssociationSimulationNotFoundError: + """Return the error for a detailed-save simulation the country does not have.""" + return AssociationSimulationNotFoundError( + f"Simulation {simulation_id} was not found in country {country_id!r}" + ) + + +def require_stored_simulation( + *, stored: bool, simulation_id: UUID, country_id: str +) -> None: + """Raise AssociationSimulationNotFoundError unless the simulation is ``stored``.""" + if not stored: + raise simulation_not_found(simulation_id=simulation_id, country_id=country_id) + + def require_user_simulation( association: UserSimulationAssociation | None, *, diff --git a/pyproject.toml b/pyproject.toml index 2831f1d0c..b5615395c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -396,6 +396,7 @@ banned-module-level-imports = [ "policyengine_api.data.v2.database", "policyengine_api.libs.auth0_management", "policyengine_api.libs.simulation_household_calculations", + "policyengine_api.libs.simulation_reports", "policyengine_api.services.v2.countries.database_session", "policyengine_api.services.v2.countries.services", "policyengine_api.services.v2.household_calculations.database_session", @@ -408,6 +409,11 @@ banned-module-level-imports = [ "policyengine_api.services.v2.metadata.services", "policyengine_api.services.v2.policies.database_session", "policyengine_api.services.v2.policies.services", + "policyengine_api.services.v2.simulation_service.services", + "policyengine_api.services.v2.stored_reports.database_session", + "policyengine_api.services.v2.stored_reports.services", + "policyengine_api.services.v2.stored_simulations.database_session", + "policyengine_api.services.v2.stored_simulations.services", "policyengine_api.services.v2.user_accounts.database_session", "policyengine_api.services.v2.user_accounts.services", "policyengine_api.services.v2.user_households.database_session", @@ -433,6 +439,7 @@ runtime-evaluated-base-classes = [ "policyengine_api.data.v2.models.comparison_runs.Stage12RunTimestamps", "policyengine_api.data.v2.models.run_results.GeographicImpactBase", "policyengine_api.data.v2.models.run_results.UKAreaImpactBase", + "policyengine_api.fastapi_routes.v2.errors_support.V2ErrorResponse", "policyengine_api.fastapi_routes.v2.households.document_models.HouseholdEntityRecord", "policyengine_api.fastapi_routes.v2.households.document_models.StrictHouseholdDocumentModel", "policyengine_api.fastapi_routes.v2.households.response_models.HouseholdSuccessResponse", @@ -442,6 +449,10 @@ runtime-evaluated-base-classes = [ "policyengine_api.fastapi_routes.v2.metadata.response_models.MetadataResourceSuccessResponse", "policyengine_api.fastapi_routes.v2.policies.response_models.PolicySuccessResponse", "policyengine_api.fastapi_routes.v2.policies.response_models.StrictPolicyAPIModel", + "policyengine_api.fastapi_routes.v2.reports.response_models.ReportSuccessResponse", + "policyengine_api.fastapi_routes.v2.reports.response_models.StrictReportAPIModel", + "policyengine_api.fastapi_routes.v2.simulations.response_models.SimulationSuccessResponse", + "policyengine_api.fastapi_routes.v2.simulations.response_models.StrictSimulationAPIModel", "policyengine_api.fastapi_routes.v2.user_households.response_models.StrictUserHouseholdAPIModel", "policyengine_api.fastapi_routes.v2.user_households.response_models.UserHouseholdSuccessResponse", "policyengine_api.fastapi_routes.v2.user_policies.response_models.StrictUserPolicyAPIModel", @@ -451,6 +462,8 @@ runtime-evaluated-base-classes = [ "policyengine_api.fastapi_routes.v2.user_reports.response_models.UserReportSuccessResponse", "policyengine_api.fastapi_routes.v2.user_simulations.response_models.StrictUserSimulationAPIModel", "policyengine_api.fastapi_routes.v2.user_simulations.response_models.UserSimulationSuccessResponse", + "policyengine_api.libs.simulation_service_answers.AnswerModel", + "policyengine_api.libs.simulation_service_answers.Refusal", "policyengine_api.query_parameters.CatalogQuery", "policyengine_api.query_parameters.CountryQuery", "policyengine_api.query_parameters.EconomyQuery", @@ -464,7 +477,11 @@ runtime-evaluated-base-classes = [ "policyengine_api.services.v2.metadata.types.StrictResponseModel", "policyengine_api.services.v2.policies.types.PolicyCreationInput", "policyengine_api.services.v2.policies.types.StrictPolicyInput", + "policyengine_api.services.v2.simulation_service.types.EconomyReportCreationInput", + "policyengine_api.services.v2.simulation_service.types.EconomySimulationCreationInput", + "policyengine_api.services.v2.simulation_service.types.StrictSubmissionModel", "policyengine_api.services.v2.simulations.types.StrictContractModel", + "policyengine_api.services.v2.stored_reports.economy_results.types.EconomyResultModel", "policyengine_api.services.v2.user_accounts.types.AccountUpdateInput", "policyengine_api.services.v2.user_accounts.types.StrictAccountInput", "policyengine_api.services.v2.user_households.types.StrictUserHouseholdInput", diff --git a/scripts/generate_economy_result_golden.py b/scripts/generate_economy_result_golden.py new file mode 100644 index 000000000..8a46deba2 --- /dev/null +++ b/scripts/generate_economy_result_golden.py @@ -0,0 +1,233 @@ +r"""Store economy results with the simulation service's own writer, as test data. + +The Public API rebuilds a report run's economy result from the rows the +simulation service writes (``policyengine_api.services.v2.stored_reports. +economy_results``). This script runs that writer, ``report_run_result`` in +PolicyEngine/policyengine-sim-api's ``libs/policyengine-stage12-persistence``, +at one commit of a local clone, on the economy results +``tests.fixtures.economy_results`` builds and on variants of them. It writes +each result, as the writer's own model serializes it, with the report run +columns and table rows the writer returns, to +``tests/fixtures/economy_result_rows_golden.json``, which names the commit. +``tests/unit/v2/test_economy_result_rebuild.py`` rebuilds every result from +those rows, so a change in the writer fails that test once this file is +generated again from a newer commit. + +Run it from the repository root, naming the clone and the commit:: + + uv run --frozen --extra dev python scripts/generate_economy_result_golden.py \ + --simulation-repository ../policyengine-sim-api --commit origin/main + +The writer's modules are read with ``git show`` at the commit into a +temporary directory; the clone itself is not changed. US districts are +numbered with .py's state FIPS codes and at-large states, as the simulation +service numbers them. Row IDs, which the writer draws at random, are left +out. +""" + +from __future__ import annotations + +import argparse +import copy +import importlib +import json +import subprocess +import sys +import tempfile +from pathlib import Path +from types import SimpleNamespace +from typing import Any +from uuid import UUID + +REPO_ROOT = Path(__file__).resolve().parent.parent +if str(REPO_ROOT) not in sys.path: + sys.path.insert(0, str(REPO_ROOT)) + +from tests.fixtures.economy_results import ( # noqa: E402 # the repository root is on the path only from here + uk_economy_result, + us_economy_result, +) + +OUTPUT = REPO_ROOT / "tests" / "fixtures" / "economy_result_rows_golden.json" +WRITER = ( + "libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/" + "report_run_results.py" +) +# Each module the writer imports, by its path in the simulation service's +# repository; each package gets an empty ``__init__.py``. +WRITER_MODULES = { + "policyengine_stage12_persistence/report_run_results.py": WRITER, + "policyengine_stage12_persistence/report_run_tables.py": ( + "libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/" + "report_run_tables.py" + ), + **{ + f"policyengine_simulation_contract/{module}.py": ( + "libs/policyengine-simulation-contract/src/" + f"policyengine_simulation_contract/{module}.py" + ) + for module in ("macro_output", "spm", "json_types") + }, +} +RUN_IDS = { + "report_run_id": UUID("00000000-0000-4000-8000-00000000c001"), + "baseline_simulation_run_id": UUID("00000000-0000-4000-8000-00000000c002"), + "reform_simulation_run_id": UUID("00000000-0000-4000-8000-00000000c003"), +} + + +def _git(repository: Path, *arguments: str) -> str: + return subprocess.run( + ["git", "-C", str(repository), *arguments], + check=True, + capture_output=True, + text=True, + ).stdout + + +def _district(name: str, **values: float) -> dict[str, Any]: + return { + "district": name, + "average_household_income_change": values.get("average", 5.0), + "relative_household_income_change": values.get("relative", 0.0004), + "winner_percentage": 0.25, + "loser_percentage": 0.25, + "no_change_percentage": 0.5, + "population": values.get("population", 700_000.0), + } + + +def us_labour_supply_deciles_and_at_large_districts() -> dict[str, Any]: + """Return a US result shaped as .py reports some states and deciles. + + .py's labour supply averages also cover deciles -1 and 0, which have no + relative response, and DC and Wyoming each have one at-large district, + which the writer stores as district 0. Districts are in GEOID order, the + order the rebuild returns them in. + """ + output = us_economy_result() + average = output["labor_supply_response"]["decile"]["average"] + average["income"] = {-1: 0.5, 0: 0.7, **average["income"]} + average["substitution"] = {-1: -0.5, 0: -0.7, **average["substitution"]} + districts = output["congressional_district_impact"]["districts"] + california = [district["district"] for district in districts].index("CA-12") + districts.insert(california + 1, _district("DC-01", average=-1.5)) + districts.append(_district("WY-01", population=580_000.0)) + return output + + +def us_negative_budget() -> dict[str, Any]: + """Return a US result whose reform loses revenue and raises spending.""" + output = us_economy_result() + output["budget"].update( + tax_revenue_impact=-1500.0, + state_tax_revenue_impact=-250.0, + benefit_spending_impact=500.0, + budgetary_impact=-2000.0, + ) + return output + + +CASES = ( + ("us", "us", us_economy_result), + ("uk", "uk", uk_economy_result), + ( + "us-labour-supply-deciles-and-at-large-districts", + "us", + us_labour_supply_deciles_and_at_large_districts, + ), + ("us-negative-budget", "us", us_negative_budget), +) + + +def _json_value(value: object) -> object: + """Return a row's value as JSON holds it: a UUID as its string.""" + if isinstance(value, UUID): + return str(value) + return value + + +def generate(repository: Path, commit: str) -> dict[str, Any]: + """Run the writer at ``commit`` on every case; return what it stored.""" + resolved = _git(repository, "rev-parse", f"{commit}^{{commit}}").strip() + writer_changed = _git( + repository, "log", "-1", "--format=%H", resolved, "--", WRITER + ).strip() + with tempfile.TemporaryDirectory() as source: + for module, path in WRITER_MODULES.items(): + target = Path(source) / module + target.parent.mkdir(parents=True, exist_ok=True) + (target.parent / "__init__.py").touch() + target.write_text(_git(repository, "show", f"{resolved}:{path}")) + sys.path.insert(0, source) + writer = importlib.import_module( + "policyengine_stage12_persistence.report_run_results" + ) + contract = importlib.import_module( + "policyengine_simulation_contract.macro_output" + ) + # .py's US data, as the simulation service's district codes use it. + us_data = importlib.import_module("policyengine.countries.us.data") + district_codes = writer.DistrictCodes( + state_fips={ + state: int(fips) for state, fips in us_data.US_STATE_FIPS.items() + }, + at_large_states=frozenset(us_data.AT_LARGE_STATES), + ) + cases = [] + for name, country, build in CASES: + output = build() + stored = writer.report_run_result( + copy.deepcopy(output), + # The writer reads only the three IDs of its ReportRunIds. + run_ids=SimpleNamespace(**RUN_IDS), + country=country, + district_codes=district_codes if country == "us" else None, + ) + cases.append( + { + "name": name, + "country": country, + "output": contract.SingleYearMacroOutput.model_validate( + output + ).model_dump(mode="json"), + "report_run_columns": dict(stored.report_run_columns), + "rows": { + rows.table.name: [ + { + column: _json_value(value) + for column, value in row.items() + if column != "id" + } + for row in rows.rows + ] + for rows in stored.rows + }, + } + ) + return { + "generated_by": "scripts/generate_economy_result_golden.py", + "writer": { + "repository": "PolicyEngine/policyengine-sim-api", + "commit": resolved, + "path": WRITER, + "last_changed_in": writer_changed, + }, + "run_ids": {key: str(value) for key, value in RUN_IDS.items()}, + "cases": cases, + } + + +def main() -> None: + """Generate the fixture from the named clone and commit.""" + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--simulation-repository", type=Path, required=True) + parser.add_argument("--commit", default="origin/main") + arguments = parser.parse_args() + payload = generate(arguments.simulation_repository, arguments.commit) + OUTPUT.write_text(json.dumps(payload, indent=2) + "\n") + print(f"Wrote {len(payload['cases'])} results from {payload['writer']['commit']}") + + +if __name__ == "__main__": + main() diff --git a/tests/contract/registry.py b/tests/contract/registry.py index 5c2df6b72..a35ea84b5 100644 --- a/tests/contract/registry.py +++ b/tests/contract/registry.py @@ -391,7 +391,12 @@ class WorkflowContract: "name", "description", ), - patch_fields=("legacy_simulation_id", "name", "description"), + patch_fields=( + "simulation_id", + "legacy_simulation_id", + "name", + "description", + ), ), ), WorkflowContract( @@ -416,6 +421,7 @@ class WorkflowContract: "last_run_at", ), patch_fields=( + "report_id", "legacy_report_id", "name", "description", @@ -439,6 +445,7 @@ class WorkflowContract: "message", "result.item.id", "result.item.country_id", + "result.item.report_id", "result.item.legacy_report_id", "result.item.name", "result.item.source_note", @@ -607,6 +614,80 @@ class WorkflowContract: ), ), ), + WorkflowContract( + name="detailed_save_reports_v2", + current_contract="typed_v2_resources", + future_owner_pr="C1 · 8: v2 simulations and economy reports", + requests=( + ContractRequest( + method="POST", + path="/v2/reports?country_id=us", + expected_status=201, + stable_response_fields=( + "status", + "message", + "result.item.id", + "result.item.country_id", + "result.item.kind", + "result.item.status", + "result.item.run", + "result.item.current_versions", + "result.item.result", + ), + route_group="report", + ), + ContractRequest( + method="GET", + path="/v2/reports?country_id=us&report_id={report_id}", + expected_status=200, + stable_response_fields=("status", "message", "result.items"), + route_group="report", + ), + ContractRequest( + method="GET", + path="/v2/reports/{report_id}?country_id=us", + expected_status=200, + stable_response_fields=( + "status", + "message", + "result.item.id", + "result.item.status", + "result.item.run", + "result.item.current_versions", + "result.item.result", + ), + route_group="report", + ), + ContractRequest( + method="POST", + path="/v2/simulations?country_id=us", + expected_status=201, + stable_response_fields=( + "status", + "message", + "result.item.id", + "result.item.kind", + "result.item.status", + "result.item.run", + ), + route_group="simulation", + ), + ContractRequest( + method="GET", + path="/v2/simulations/{simulation_id}?country_id=us", + expected_status=200, + stable_response_fields=( + "status", + "message", + "result.item.id", + "result.item.status", + "result.item.run", + "result.item.current_versions", + ), + route_group="simulation", + ), + ), + ), WorkflowContract( name="metadata_resources_v2_preview", current_contract="typed_v2_resources", diff --git a/tests/contract/test_app_v2_workflow_contracts.py b/tests/contract/test_app_v2_workflow_contracts.py index 20c6733d3..bd0192898 100644 --- a/tests/contract/test_app_v2_workflow_contracts.py +++ b/tests/contract/test_app_v2_workflow_contracts.py @@ -21,6 +21,7 @@ def test_app_v2_workflow_contract_registry_is_complete(): "household_calculate", "region_selection", "country_selection_v2", + "detailed_save_reports_v2", "metadata_resources_v2_preview", "simulation_submit_poll", "report_create_poll", @@ -33,6 +34,7 @@ def test_app_v2_workflow_contract_registry_is_complete(): if workflow.name in { "country_selection_v2", + "detailed_save_reports_v2", "metadata_resources_v2_preview", "policy_resources_v2", "user_policy_associations_v2", diff --git a/tests/fixtures/economy_result_rows_golden.json b/tests/fixtures/economy_result_rows_golden.json new file mode 100644 index 000000000..195d5968f --- /dev/null +++ b/tests/fixtures/economy_result_rows_golden.json @@ -0,0 +1,4892 @@ +{ + "generated_by": "scripts/generate_economy_result_golden.py", + "writer": { + "repository": "PolicyEngine/policyengine-sim-api", + "commit": "cb1264a595f703f9989b8ee0cac124e031671c37", + "path": "libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/report_run_results.py", + "last_changed_in": "c02145fd696e5c7b78c757cf18873507994672a9" + }, + "run_ids": { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003" + }, + "cases": [ + { + "name": "us", + "country": "us", + "output": { + "spm_provenance": { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + }, + "reform": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + } + }, + "model_version": "1.0.0", + "data_version": "enhanced_cps_2024@1.2.3", + "budget": { + "tax_revenue_impact": 1500.0, + "state_tax_revenue_impact": 250.0, + "benefit_spending_impact": -500.0, + "budgetary_impact": 2000.0, + "households": 130000000.0, + "baseline_net_income": 9500000000000.0 + }, + "detailed_budget": { + "income_tax": { + "baseline": 1000.0, + "reform": 2500.0, + "difference": 1500.0, + "is_tax": true + }, + "snap": { + "baseline": 800.0, + "reform": 300.0, + "difference": -500.0, + "is_tax": false + }, + "state_income_tax": { + "baseline": 10.0, + "reform": 260.0, + "difference": 250.0, + "is_tax": null + } + }, + "decile": { + "average": { + "1": 10.0, + "2": 20.0, + "3": 30.0, + "4": 40.0, + "5": 50.0, + "6": 60.0, + "7": 70.0, + "8": 80.0, + "9": 90.0, + "10": 100.0 + }, + "relative": { + "1": 0.015625, + "2": 0.03125, + "3": 0.046875, + "4": 0.0625, + "5": 0.078125, + "6": 0.09375, + "7": 0.109375, + "8": 0.125, + "9": 0.140625, + "10": 0.15625 + } + }, + "inequality": { + "gini": { + "baseline": 0.41, + "reform": 0.4 + }, + "top_10_pct_share": { + "baseline": 0.32, + "reform": 0.31 + }, + "top_1_pct_share": { + "baseline": 0.11, + "reform": 0.105 + } + }, + "poverty": { + "poverty": { + "child": { + "baseline": 0.1, + "reform": 0.09000000000000001 + }, + "adult": { + "baseline": 0.12000000000000001, + "reform": 0.11 + }, + "senior": { + "baseline": 0.13, + "reform": 0.14 + }, + "all": { + "baseline": 0.14, + "reform": 0.12000000000000001 + } + }, + "deep_poverty": { + "child": { + "baseline": 0.04, + "reform": 0.03 + }, + "adult": { + "baseline": 0.06, + "reform": 0.05 + }, + "senior": { + "baseline": 0.07, + "reform": 0.08 + }, + "all": { + "baseline": 0.08, + "reform": 0.06 + } + } + }, + "poverty_by_gender": { + "poverty": { + "male": { + "baseline": 0.11, + "reform": 0.1 + }, + "female": { + "baseline": 0.13, + "reform": 0.12 + } + }, + "deep_poverty": { + "male": { + "baseline": 0.04, + "reform": 0.035 + }, + "female": { + "baseline": 0.05, + "reform": 0.045 + } + } + }, + "poverty_by_race": { + "poverty": { + "white": { + "baseline": 0.08, + "reform": 0.07 + }, + "black": { + "baseline": 0.18, + "reform": 0.16 + }, + "hispanic": { + "baseline": 0.16, + "reform": 0.15 + }, + "other": { + "baseline": 0.12, + "reform": 0.11 + } + } + }, + "intra_decile": { + "deciles": { + "Lose more than 5%": [ + 0.05, + 0.06, + 0.07, + 0.08, + 0.09, + 0.1, + 0.11, + 0.12, + 0.13, + 0.14 + ], + "Lose less than 5%": [ + 0.051, + 0.061, + 0.071, + 0.081, + 0.091, + 0.101, + 0.111, + 0.121, + 0.131, + 0.141 + ], + "No change": [ + 0.052, + 0.062, + 0.072, + 0.082, + 0.092, + 0.102, + 0.112, + 0.122, + 0.132, + 0.142 + ], + "Gain less than 5%": [ + 0.053, + 0.063, + 0.073, + 0.083, + 0.093, + 0.103, + 0.113, + 0.123, + 0.133, + 0.143 + ], + "Gain more than 5%": [ + 0.054, + 0.064, + 0.074, + 0.084, + 0.094, + 0.104, + 0.114, + 0.124, + 0.134, + 0.144 + ] + }, + "all": { + "Lose more than 5%": 0.095, + "Lose less than 5%": 0.096, + "No change": 0.097, + "Gain less than 5%": 0.098, + "Gain more than 5%": 0.099 + } + }, + "wealth_decile": null, + "intra_wealth_decile": null, + "labor_supply_response": { + "substitution_lsr": -120.0, + "income_lsr": 45.0, + "relative_lsr": { + "income": 0.001, + "substitution": -0.002 + }, + "total_change": -75.0, + "revenue_change": -30.0, + "decile": { + "average": { + "income": { + "1": 1.5, + "2": 3.0, + "3": 4.5, + "4": 6.0, + "5": 7.5, + "6": 9.0, + "7": 10.5, + "8": 12.0, + "9": 13.5, + "10": 15.0 + }, + "substitution": { + "1": -2.0, + "2": -4.0, + "3": -6.0, + "4": -8.0, + "5": -10.0, + "6": -12.0, + "7": -14.0, + "8": -16.0, + "9": -18.0, + "10": -20.0 + } + }, + "relative": { + "income": { + "2": 0.0002, + "3": 0.00030000000000000003, + "4": 0.0004, + "5": 0.0005, + "6": 0.0006000000000000001, + "7": 0.0007, + "8": 0.0008, + "9": 0.0009000000000000001, + "10": 0.001 + }, + "substitution": { + "2": -0.0004, + "3": -0.0006000000000000001, + "4": -0.0008, + "5": -0.001, + "6": -0.0012000000000000001, + "7": -0.0014, + "8": -0.0016, + "9": -0.0018000000000000002, + "10": -0.002 + } + } + }, + "hours": { + "baseline": 1000000000.0, + "reform": 999000000.0, + "change": -1000000.0, + "income_effect": 200000.0, + "substitution_effect": -1200000.0 + } + }, + "constituency_impact": null, + "local_authority_impact": null, + "congressional_district_impact": { + "districts": [ + { + "district": "AK-01", + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300000.0 + }, + { + "district": "CA-05", + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290000.0 + }, + { + "district": "CA-12", + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310000.0 + }, + { + "district": "UT-03", + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280000.0 + } + ] + }, + "cliff_impact": { + "baseline": { + "cliff_gap": 1200000000.0, + "cliff_share": 0.04 + }, + "reform": { + "cliff_gap": 1100000000.0, + "cliff_share": 0.035 + } + } + }, + "report_run_columns": { + "baseline_cliff_gap": 1200000000.0, + "baseline_cliff_share": 0.04, + "reform_cliff_gap": 1100000000.0, + "reform_cliff_share": 0.035, + "spm_provenance": { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + }, + "reform": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + } + }, + "data_version": "enhanced_cps_2024@1.2.3" + }, + "rows": { + "labor_supply_responses": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "income_effect_earnings_change": 45.0, + "substitution_effect_earnings_change": -120.0, + "total_earnings_change": -75.0, + "revenue_change": -30.0, + "relative_income_effect": 0.001, + "relative_substitution_effect": -0.002, + "baseline_weekly_hours": 1000000000.0, + "reform_weekly_hours": 999000000.0, + "weekly_hours_change": -1000000.0, + "weekly_hours_income_effect": 200000.0, + "weekly_hours_substitution_effect": -1200000.0 + } + ], + "labor_supply_decile_responses": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 1, + "average_income_effect": 1.5, + "average_substitution_effect": -2.0, + "relative_income_effect": null, + "relative_substitution_effect": null + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 2, + "average_income_effect": 3.0, + "average_substitution_effect": -4.0, + "relative_income_effect": 0.0002, + "relative_substitution_effect": -0.0004 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 3, + "average_income_effect": 4.5, + "average_substitution_effect": -6.0, + "relative_income_effect": 0.00030000000000000003, + "relative_substitution_effect": -0.0006000000000000001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 4, + "average_income_effect": 6.0, + "average_substitution_effect": -8.0, + "relative_income_effect": 0.0004, + "relative_substitution_effect": -0.0008 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 5, + "average_income_effect": 7.5, + "average_substitution_effect": -10.0, + "relative_income_effect": 0.0005, + "relative_substitution_effect": -0.001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 6, + "average_income_effect": 9.0, + "average_substitution_effect": -12.0, + "relative_income_effect": 0.0006000000000000001, + "relative_substitution_effect": -0.0012000000000000001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 7, + "average_income_effect": 10.5, + "average_substitution_effect": -14.0, + "relative_income_effect": 0.0007, + "relative_substitution_effect": -0.0014 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 8, + "average_income_effect": 12.0, + "average_substitution_effect": -16.0, + "relative_income_effect": 0.0008, + "relative_substitution_effect": -0.0016 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 9, + "average_income_effect": 13.5, + "average_substitution_effect": -18.0, + "relative_income_effect": 0.0009000000000000001, + "relative_substitution_effect": -0.0018000000000000002 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 10, + "average_income_effect": 15.0, + "average_substitution_effect": -20.0, + "relative_income_effect": 0.001, + "relative_substitution_effect": -0.002 + } + ], + "budget_summary": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_tax", + "entity": "household", + "change": 1500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_benefits", + "entity": "household", + "change": -500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_state_income_tax", + "entity": "household", + "change": 250.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_net_income", + "entity": "household", + "baseline_total": 9500000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_weight", + "entity": "household", + "baseline_total": 130000000.0 + } + ], + "decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 1, + "quantiles": 10, + "absolute_change": 10.0, + "relative_change": 1.5625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 2, + "quantiles": 10, + "absolute_change": 20.0, + "relative_change": 3.125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 3, + "quantiles": 10, + "absolute_change": 30.0, + "relative_change": 4.6875 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 4, + "quantiles": 10, + "absolute_change": 40.0, + "relative_change": 6.25 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 5, + "quantiles": 10, + "absolute_change": 50.0, + "relative_change": 7.8125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 6, + "quantiles": 10, + "absolute_change": 60.0, + "relative_change": 9.375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 7, + "quantiles": 10, + "absolute_change": 70.0, + "relative_change": 10.9375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 8, + "quantiles": 10, + "absolute_change": 80.0, + "relative_change": 12.5 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 9, + "quantiles": 10, + "absolute_change": 90.0, + "relative_change": 14.0625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 10, + "quantiles": 10, + "absolute_change": 100.0, + "relative_change": 15.625 + } + ], + "intra_decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 1, + "lose_more_than_5pct": 0.05, + "lose_less_than_5pct": 0.051, + "no_change": 0.052, + "gain_less_than_5pct": 0.053, + "gain_more_than_5pct": 0.054 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 2, + "lose_more_than_5pct": 0.06, + "lose_less_than_5pct": 0.061, + "no_change": 0.062, + "gain_less_than_5pct": 0.063, + "gain_more_than_5pct": 0.064 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 3, + "lose_more_than_5pct": 0.07, + "lose_less_than_5pct": 0.071, + "no_change": 0.072, + "gain_less_than_5pct": 0.073, + "gain_more_than_5pct": 0.074 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 4, + "lose_more_than_5pct": 0.08, + "lose_less_than_5pct": 0.081, + "no_change": 0.082, + "gain_less_than_5pct": 0.083, + "gain_more_than_5pct": 0.084 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 5, + "lose_more_than_5pct": 0.09, + "lose_less_than_5pct": 0.091, + "no_change": 0.092, + "gain_less_than_5pct": 0.093, + "gain_more_than_5pct": 0.094 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 6, + "lose_more_than_5pct": 0.1, + "lose_less_than_5pct": 0.101, + "no_change": 0.102, + "gain_less_than_5pct": 0.103, + "gain_more_than_5pct": 0.104 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 7, + "lose_more_than_5pct": 0.11, + "lose_less_than_5pct": 0.111, + "no_change": 0.112, + "gain_less_than_5pct": 0.113, + "gain_more_than_5pct": 0.114 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 8, + "lose_more_than_5pct": 0.12, + "lose_less_than_5pct": 0.121, + "no_change": 0.122, + "gain_less_than_5pct": 0.123, + "gain_more_than_5pct": 0.124 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 9, + "lose_more_than_5pct": 0.13, + "lose_less_than_5pct": 0.131, + "no_change": 0.132, + "gain_less_than_5pct": 0.133, + "gain_more_than_5pct": 0.134 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 10, + "lose_more_than_5pct": 0.14, + "lose_less_than_5pct": 0.141, + "no_change": 0.142, + "gain_less_than_5pct": 0.143, + "gain_more_than_5pct": 0.144 + } + ], + "poverty": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.14 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.12000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.04 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.06 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.07 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.04 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.05 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "white", + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "black", + "rate": 0.18 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "hispanic", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "other", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.12000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.09000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.14 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.06 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.03 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.05 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.035 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.045 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "white", + "rate": 0.07 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "black", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "hispanic", + "rate": 0.15 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "other", + "rate": 0.11 + } + ], + "inequality": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "income_variable": "household_net_income", + "entity": "household", + "gini": 0.41, + "top_10_share": 0.32, + "top_1_share": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "entity": "household", + "gini": 0.4, + "top_10_share": 0.31, + "top_1_share": 0.105 + } + ], + "program_statistics": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "income_tax", + "entity": null, + "is_tax": true, + "baseline_total": 1000.0, + "reform_total": 2500.0, + "change": 1500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "snap", + "entity": null, + "is_tax": false, + "baseline_total": 800.0, + "reform_total": 300.0, + "change": -500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "state_income_tax", + "entity": null, + "is_tax": null, + "baseline_total": 10.0, + "reform_total": 260.0, + "change": 250.0 + } + ], + "congressional_district_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 200, + "state_fips": 2, + "district_number": 0, + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 605, + "state_fips": 6, + "district_number": 5, + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 612, + "state_fips": 6, + "district_number": 12, + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 4903, + "state_fips": 49, + "district_number": 3, + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280000.0 + } + ], + "constituency_impacts": [], + "local_authority_impacts": [] + } + }, + { + "name": "uk", + "country": "uk", + "output": { + "spm_provenance": null, + "model_version": "2.0.0", + "data_version": "enhanced_frs_2023_24@1.0.0", + "budget": { + "tax_revenue_impact": 4000000000.0, + "state_tax_revenue_impact": 0.0, + "benefit_spending_impact": 1000000000.0, + "budgetary_impact": 3000000000.0, + "households": 28000000.0, + "baseline_net_income": 1200000000000.0 + }, + "detailed_budget": { + "income_tax": { + "baseline": 200000000000.0, + "reform": 204000000000.0, + "difference": 4000000000.0, + "is_tax": true + }, + "universal_credit": { + "baseline": 60000000000.0, + "reform": 61000000000.0, + "difference": 1000000000.0, + "is_tax": false + } + }, + "decile": { + "average": { + "1": -5.0, + "2": -10.0, + "3": -15.0, + "4": -20.0, + "5": -25.0, + "6": -30.0, + "7": -35.0, + "8": -40.0, + "9": -45.0, + "10": -50.0 + }, + "relative": { + "1": 0.015625, + "2": 0.03125, + "3": 0.046875, + "4": 0.0625, + "5": 0.078125, + "6": 0.09375, + "7": 0.109375, + "8": 0.125, + "9": 0.140625, + "10": 0.15625 + } + }, + "inequality": { + "gini": { + "baseline": 0.36, + "reform": 0.355 + }, + "top_10_pct_share": { + "baseline": 0.27, + "reform": 0.265 + }, + "top_1_pct_share": { + "baseline": 0.08, + "reform": 0.079 + } + }, + "poverty": { + "poverty": { + "child": { + "baseline": 0.17, + "reform": 0.16 + }, + "adult": { + "baseline": 0.19, + "reform": 0.18000000000000002 + }, + "senior": { + "baseline": 0.2, + "reform": 0.21000000000000002 + }, + "all": { + "baseline": 0.21000000000000002, + "reform": 0.19 + } + }, + "deep_poverty": { + "child": { + "baseline": 0.12, + "reform": 0.11 + }, + "adult": { + "baseline": 0.13999999999999999, + "reform": 0.13 + }, + "senior": { + "baseline": 0.15, + "reform": 0.16 + }, + "all": { + "baseline": 0.16, + "reform": 0.13999999999999999 + } + } + }, + "poverty_by_gender": { + "poverty": { + "male": { + "baseline": 0.16, + "reform": 0.15 + }, + "female": { + "baseline": 0.18, + "reform": 0.17 + } + }, + "deep_poverty": { + "male": { + "baseline": 0.11, + "reform": 0.1 + }, + "female": { + "baseline": 0.13, + "reform": 0.12 + } + } + }, + "poverty_by_race": null, + "intra_decile": { + "deciles": { + "Lose more than 5%": [ + 0.02, + 0.03, + 0.04, + 0.05, + 0.06, + 0.07, + 0.08, + 0.09, + 0.1, + 0.11 + ], + "Lose less than 5%": [ + 0.021, + 0.031, + 0.041, + 0.051, + 0.061, + 0.071, + 0.081, + 0.091, + 0.101, + 0.111 + ], + "No change": [ + 0.022, + 0.032, + 0.042, + 0.052, + 0.062, + 0.072, + 0.082, + 0.092, + 0.102, + 0.112 + ], + "Gain less than 5%": [ + 0.023, + 0.033, + 0.043, + 0.053, + 0.063, + 0.073, + 0.083, + 0.093, + 0.103, + 0.113 + ], + "Gain more than 5%": [ + 0.024, + 0.034, + 0.044, + 0.054, + 0.064, + 0.074, + 0.084, + 0.094, + 0.104, + 0.114 + ] + }, + "all": { + "Lose more than 5%": 0.065, + "Lose less than 5%": 0.066, + "No change": 0.067, + "Gain less than 5%": 0.06799999999999999, + "Gain more than 5%": 0.06899999999999999 + } + }, + "wealth_decile": { + "average": { + "1": -8.0, + "2": -16.0, + "3": -24.0, + "4": -32.0, + "5": -40.0, + "6": -48.0, + "7": -56.0, + "8": -64.0, + "9": -72.0, + "10": -80.0 + }, + "relative": { + "1": 0.015625, + "2": 0.03125, + "3": 0.046875, + "4": 0.0625, + "5": 0.078125, + "6": 0.09375, + "7": 0.109375, + "8": 0.125, + "9": 0.140625, + "10": 0.15625 + } + }, + "intra_wealth_decile": { + "deciles": { + "Lose more than 5%": [ + 0.03, + 0.04, + 0.05, + 0.06, + 0.07, + 0.08, + 0.09, + 0.1, + 0.11, + 0.12 + ], + "Lose less than 5%": [ + 0.031, + 0.041, + 0.051, + 0.061, + 0.071, + 0.081, + 0.091, + 0.101, + 0.111, + 0.121 + ], + "No change": [ + 0.032, + 0.042, + 0.052, + 0.062, + 0.072, + 0.082, + 0.092, + 0.102, + 0.112, + 0.122 + ], + "Gain less than 5%": [ + 0.033, + 0.043, + 0.053, + 0.063, + 0.073, + 0.083, + 0.093, + 0.103, + 0.113, + 0.123 + ], + "Gain more than 5%": [ + 0.034, + 0.044, + 0.054, + 0.064, + 0.074, + 0.084, + 0.094, + 0.104, + 0.114, + 0.124 + ] + }, + "all": { + "Lose more than 5%": 0.075, + "Lose less than 5%": 0.076, + "No change": 0.077, + "Gain less than 5%": 0.078, + "Gain more than 5%": 0.079 + } + }, + "labor_supply_response": null, + "constituency_impact": [ + { + "disclosure_tier": "reported", + "average_household_income_change_lower": 8.0, + "average_household_income_change_upper": 12.0, + "relative_household_income_change_lower": 0.0008, + "relative_household_income_change_upper": 0.0012, + "constituency_code": "E14001063", + "constituency_name": "Aldershot", + "average_household_income_change": 10.0, + "relative_household_income_change": 0.001, + "population": 40000.0 + }, + { + "disclosure_tier": "approximate", + "average_household_income_change_lower": 8.0, + "average_household_income_change_upper": 12.0, + "relative_household_income_change_lower": 0.0008, + "relative_household_income_change_upper": 0.0012, + "constituency_code": "W07000081", + "constituency_name": "Aberafan Maesteg", + "average_household_income_change": -2.5, + "relative_household_income_change": 0.001, + "population": 40000.0 + } + ], + "local_authority_impact": [ + { + "disclosure_tier": "reported", + "average_household_income_change_lower": 8.0, + "average_household_income_change_upper": 12.0, + "relative_household_income_change_lower": 0.0008, + "relative_household_income_change_upper": 0.0012, + "local_authority_code": "E06000001", + "local_authority_name": "Hartlepool", + "average_household_income_change": 4.0, + "relative_household_income_change": 0.001, + "population": 40000.0 + }, + { + "disclosure_tier": null, + "average_household_income_change_lower": null, + "average_household_income_change_upper": null, + "relative_household_income_change_lower": null, + "relative_household_income_change_upper": null, + "local_authority_code": "E06000002", + "local_authority_name": "Middlesbrough", + "average_household_income_change": -3.0, + "relative_household_income_change": 0.001, + "population": 40000.0 + } + ], + "congressional_district_impact": null, + "cliff_impact": null + }, + "report_run_columns": { + "baseline_cliff_gap": null, + "baseline_cliff_share": null, + "reform_cliff_gap": null, + "reform_cliff_share": null, + "spm_provenance": null, + "data_version": "enhanced_frs_2023_24@1.0.0" + }, + "rows": { + "labor_supply_responses": [], + "labor_supply_decile_responses": [], + "budget_summary": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_tax", + "entity": "household", + "change": 4000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_benefits", + "entity": "household", + "change": 1000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_net_income", + "entity": "household", + "baseline_total": 1200000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_weight", + "entity": "household", + "baseline_total": 28000000.0 + } + ], + "decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 1, + "quantiles": 10, + "absolute_change": -5.0, + "relative_change": 1.5625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 2, + "quantiles": 10, + "absolute_change": -10.0, + "relative_change": 3.125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 3, + "quantiles": 10, + "absolute_change": -15.0, + "relative_change": 4.6875 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 4, + "quantiles": 10, + "absolute_change": -20.0, + "relative_change": 6.25 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 5, + "quantiles": 10, + "absolute_change": -25.0, + "relative_change": 7.8125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 6, + "quantiles": 10, + "absolute_change": -30.0, + "relative_change": 9.375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 7, + "quantiles": 10, + "absolute_change": -35.0, + "relative_change": 10.9375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 8, + "quantiles": 10, + "absolute_change": -40.0, + "relative_change": 12.5 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 9, + "quantiles": 10, + "absolute_change": -45.0, + "relative_change": 14.0625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 10, + "quantiles": 10, + "absolute_change": -50.0, + "relative_change": 15.625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 1, + "quantiles": 10, + "absolute_change": -8.0, + "relative_change": 1.5625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 2, + "quantiles": 10, + "absolute_change": -16.0, + "relative_change": 3.125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 3, + "quantiles": 10, + "absolute_change": -24.0, + "relative_change": 4.6875 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 4, + "quantiles": 10, + "absolute_change": -32.0, + "relative_change": 6.25 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 5, + "quantiles": 10, + "absolute_change": -40.0, + "relative_change": 7.8125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 6, + "quantiles": 10, + "absolute_change": -48.0, + "relative_change": 9.375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 7, + "quantiles": 10, + "absolute_change": -56.0, + "relative_change": 10.9375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 8, + "quantiles": 10, + "absolute_change": -64.0, + "relative_change": 12.5 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 9, + "quantiles": 10, + "absolute_change": -72.0, + "relative_change": 14.0625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": "household_wealth_decile", + "entity": "household", + "decile": 10, + "quantiles": 10, + "absolute_change": -80.0, + "relative_change": 15.625 + } + ], + "intra_decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 1, + "lose_more_than_5pct": 0.02, + "lose_less_than_5pct": 0.021, + "no_change": 0.022, + "gain_less_than_5pct": 0.023, + "gain_more_than_5pct": 0.024 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 2, + "lose_more_than_5pct": 0.03, + "lose_less_than_5pct": 0.031, + "no_change": 0.032, + "gain_less_than_5pct": 0.033, + "gain_more_than_5pct": 0.034 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 3, + "lose_more_than_5pct": 0.04, + "lose_less_than_5pct": 0.041, + "no_change": 0.042, + "gain_less_than_5pct": 0.043, + "gain_more_than_5pct": 0.044 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 4, + "lose_more_than_5pct": 0.05, + "lose_less_than_5pct": 0.051, + "no_change": 0.052, + "gain_less_than_5pct": 0.053, + "gain_more_than_5pct": 0.054 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 5, + "lose_more_than_5pct": 0.06, + "lose_less_than_5pct": 0.061, + "no_change": 0.062, + "gain_less_than_5pct": 0.063, + "gain_more_than_5pct": 0.064 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 6, + "lose_more_than_5pct": 0.07, + "lose_less_than_5pct": 0.071, + "no_change": 0.072, + "gain_less_than_5pct": 0.073, + "gain_more_than_5pct": 0.074 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 7, + "lose_more_than_5pct": 0.08, + "lose_less_than_5pct": 0.081, + "no_change": 0.082, + "gain_less_than_5pct": 0.083, + "gain_more_than_5pct": 0.084 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 8, + "lose_more_than_5pct": 0.09, + "lose_less_than_5pct": 0.091, + "no_change": 0.092, + "gain_less_than_5pct": 0.093, + "gain_more_than_5pct": 0.094 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 9, + "lose_more_than_5pct": 0.1, + "lose_less_than_5pct": 0.101, + "no_change": 0.102, + "gain_less_than_5pct": 0.103, + "gain_more_than_5pct": 0.104 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 10, + "lose_more_than_5pct": 0.11, + "lose_less_than_5pct": 0.111, + "no_change": 0.112, + "gain_less_than_5pct": 0.113, + "gain_more_than_5pct": 0.114 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 1, + "lose_more_than_5pct": 0.03, + "lose_less_than_5pct": 0.031, + "no_change": 0.032, + "gain_less_than_5pct": 0.033, + "gain_more_than_5pct": 0.034 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 2, + "lose_more_than_5pct": 0.04, + "lose_less_than_5pct": 0.041, + "no_change": 0.042, + "gain_less_than_5pct": 0.043, + "gain_more_than_5pct": 0.044 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 3, + "lose_more_than_5pct": 0.05, + "lose_less_than_5pct": 0.051, + "no_change": 0.052, + "gain_less_than_5pct": 0.053, + "gain_more_than_5pct": 0.054 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 4, + "lose_more_than_5pct": 0.06, + "lose_less_than_5pct": 0.061, + "no_change": 0.062, + "gain_less_than_5pct": 0.063, + "gain_more_than_5pct": 0.064 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 5, + "lose_more_than_5pct": 0.07, + "lose_less_than_5pct": 0.071, + "no_change": 0.072, + "gain_less_than_5pct": 0.073, + "gain_more_than_5pct": 0.074 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 6, + "lose_more_than_5pct": 0.08, + "lose_less_than_5pct": 0.081, + "no_change": 0.082, + "gain_less_than_5pct": 0.083, + "gain_more_than_5pct": 0.084 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 7, + "lose_more_than_5pct": 0.09, + "lose_less_than_5pct": 0.091, + "no_change": 0.092, + "gain_less_than_5pct": 0.093, + "gain_more_than_5pct": 0.094 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 8, + "lose_more_than_5pct": 0.1, + "lose_less_than_5pct": 0.101, + "no_change": 0.102, + "gain_less_than_5pct": 0.103, + "gain_more_than_5pct": 0.104 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 9, + "lose_more_than_5pct": 0.11, + "lose_less_than_5pct": 0.111, + "no_change": 0.112, + "gain_less_than_5pct": 0.113, + "gain_more_than_5pct": 0.114 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "wealth", + "decile": 10, + "lose_more_than_5pct": 0.12, + "lose_less_than_5pct": 0.121, + "no_change": 0.122, + "gain_less_than_5pct": 0.123, + "gain_more_than_5pct": 0.124 + } + ], + "poverty": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.21000000000000002 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.17 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.19 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.2 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.18 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.13999999999999999 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.15 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.19 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.18000000000000002 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.21000000000000002 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.15 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "relative_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.17 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.13999999999999999 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "absolute_bhc", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.12 + } + ], + "inequality": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "income_variable": "equiv_hbai_household_net_income", + "entity": "household", + "gini": 0.36, + "top_10_share": 0.27, + "top_1_share": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "equiv_hbai_household_net_income", + "entity": "household", + "gini": 0.355, + "top_10_share": 0.265, + "top_1_share": 0.079 + } + ], + "program_statistics": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "income_tax", + "entity": null, + "is_tax": true, + "baseline_total": 200000000000.0, + "reform_total": 204000000000.0, + "change": 4000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "universal_credit", + "entity": null, + "is_tax": false, + "baseline_total": 60000000000.0, + "reform_total": 61000000000.0, + "change": 1000000000.0 + } + ], + "congressional_district_impacts": [], + "constituency_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "constituency_code": "E14001063", + "constituency_name": "Aldershot", + "average_household_income_change": 10.0, + "relative_household_income_change": 0.001, + "population": 40000.0, + "disclosure_tier": "reported", + "average_household_income_change_lower": 8.0, + "average_household_income_change_upper": 12.0, + "relative_household_income_change_lower": 0.0008, + "relative_household_income_change_upper": 0.0012 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "constituency_code": "W07000081", + "constituency_name": "Aberafan Maesteg", + "average_household_income_change": -2.5, + "relative_household_income_change": 0.001, + "population": 40000.0, + "disclosure_tier": "approximate", + "average_household_income_change_lower": 8.0, + "average_household_income_change_upper": 12.0, + "relative_household_income_change_lower": 0.0008, + "relative_household_income_change_upper": 0.0012 + } + ], + "local_authority_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "local_authority_code": "E06000001", + "local_authority_name": "Hartlepool", + "average_household_income_change": 4.0, + "relative_household_income_change": 0.001, + "population": 40000.0, + "disclosure_tier": "reported", + "average_household_income_change_lower": 8.0, + "average_household_income_change_upper": 12.0, + "relative_household_income_change_lower": 0.0008, + "relative_household_income_change_upper": 0.0012 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "local_authority_code": "E06000002", + "local_authority_name": "Middlesbrough", + "average_household_income_change": -3.0, + "relative_household_income_change": 0.001, + "population": 40000.0, + "disclosure_tier": null, + "average_household_income_change_lower": null, + "average_household_income_change_upper": null, + "relative_household_income_change_lower": null, + "relative_household_income_change_upper": null + } + ] + } + }, + { + "name": "us-labour-supply-deciles-and-at-large-districts", + "country": "us", + "output": { + "spm_provenance": { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + }, + "reform": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + } + }, + "model_version": "1.0.0", + "data_version": "enhanced_cps_2024@1.2.3", + "budget": { + "tax_revenue_impact": 1500.0, + "state_tax_revenue_impact": 250.0, + "benefit_spending_impact": -500.0, + "budgetary_impact": 2000.0, + "households": 130000000.0, + "baseline_net_income": 9500000000000.0 + }, + "detailed_budget": { + "income_tax": { + "baseline": 1000.0, + "reform": 2500.0, + "difference": 1500.0, + "is_tax": true + }, + "snap": { + "baseline": 800.0, + "reform": 300.0, + "difference": -500.0, + "is_tax": false + }, + "state_income_tax": { + "baseline": 10.0, + "reform": 260.0, + "difference": 250.0, + "is_tax": null + } + }, + "decile": { + "average": { + "1": 10.0, + "2": 20.0, + "3": 30.0, + "4": 40.0, + "5": 50.0, + "6": 60.0, + "7": 70.0, + "8": 80.0, + "9": 90.0, + "10": 100.0 + }, + "relative": { + "1": 0.015625, + "2": 0.03125, + "3": 0.046875, + "4": 0.0625, + "5": 0.078125, + "6": 0.09375, + "7": 0.109375, + "8": 0.125, + "9": 0.140625, + "10": 0.15625 + } + }, + "inequality": { + "gini": { + "baseline": 0.41, + "reform": 0.4 + }, + "top_10_pct_share": { + "baseline": 0.32, + "reform": 0.31 + }, + "top_1_pct_share": { + "baseline": 0.11, + "reform": 0.105 + } + }, + "poverty": { + "poverty": { + "child": { + "baseline": 0.1, + "reform": 0.09000000000000001 + }, + "adult": { + "baseline": 0.12000000000000001, + "reform": 0.11 + }, + "senior": { + "baseline": 0.13, + "reform": 0.14 + }, + "all": { + "baseline": 0.14, + "reform": 0.12000000000000001 + } + }, + "deep_poverty": { + "child": { + "baseline": 0.04, + "reform": 0.03 + }, + "adult": { + "baseline": 0.06, + "reform": 0.05 + }, + "senior": { + "baseline": 0.07, + "reform": 0.08 + }, + "all": { + "baseline": 0.08, + "reform": 0.06 + } + } + }, + "poverty_by_gender": { + "poverty": { + "male": { + "baseline": 0.11, + "reform": 0.1 + }, + "female": { + "baseline": 0.13, + "reform": 0.12 + } + }, + "deep_poverty": { + "male": { + "baseline": 0.04, + "reform": 0.035 + }, + "female": { + "baseline": 0.05, + "reform": 0.045 + } + } + }, + "poverty_by_race": { + "poverty": { + "white": { + "baseline": 0.08, + "reform": 0.07 + }, + "black": { + "baseline": 0.18, + "reform": 0.16 + }, + "hispanic": { + "baseline": 0.16, + "reform": 0.15 + }, + "other": { + "baseline": 0.12, + "reform": 0.11 + } + } + }, + "intra_decile": { + "deciles": { + "Lose more than 5%": [ + 0.05, + 0.06, + 0.07, + 0.08, + 0.09, + 0.1, + 0.11, + 0.12, + 0.13, + 0.14 + ], + "Lose less than 5%": [ + 0.051, + 0.061, + 0.071, + 0.081, + 0.091, + 0.101, + 0.111, + 0.121, + 0.131, + 0.141 + ], + "No change": [ + 0.052, + 0.062, + 0.072, + 0.082, + 0.092, + 0.102, + 0.112, + 0.122, + 0.132, + 0.142 + ], + "Gain less than 5%": [ + 0.053, + 0.063, + 0.073, + 0.083, + 0.093, + 0.103, + 0.113, + 0.123, + 0.133, + 0.143 + ], + "Gain more than 5%": [ + 0.054, + 0.064, + 0.074, + 0.084, + 0.094, + 0.104, + 0.114, + 0.124, + 0.134, + 0.144 + ] + }, + "all": { + "Lose more than 5%": 0.095, + "Lose less than 5%": 0.096, + "No change": 0.097, + "Gain less than 5%": 0.098, + "Gain more than 5%": 0.099 + } + }, + "wealth_decile": null, + "intra_wealth_decile": null, + "labor_supply_response": { + "substitution_lsr": -120.0, + "income_lsr": 45.0, + "relative_lsr": { + "income": 0.001, + "substitution": -0.002 + }, + "total_change": -75.0, + "revenue_change": -30.0, + "decile": { + "average": { + "income": { + "-1": 0.5, + "0": 0.7, + "1": 1.5, + "2": 3.0, + "3": 4.5, + "4": 6.0, + "5": 7.5, + "6": 9.0, + "7": 10.5, + "8": 12.0, + "9": 13.5, + "10": 15.0 + }, + "substitution": { + "-1": -0.5, + "0": -0.7, + "1": -2.0, + "2": -4.0, + "3": -6.0, + "4": -8.0, + "5": -10.0, + "6": -12.0, + "7": -14.0, + "8": -16.0, + "9": -18.0, + "10": -20.0 + } + }, + "relative": { + "income": { + "2": 0.0002, + "3": 0.00030000000000000003, + "4": 0.0004, + "5": 0.0005, + "6": 0.0006000000000000001, + "7": 0.0007, + "8": 0.0008, + "9": 0.0009000000000000001, + "10": 0.001 + }, + "substitution": { + "2": -0.0004, + "3": -0.0006000000000000001, + "4": -0.0008, + "5": -0.001, + "6": -0.0012000000000000001, + "7": -0.0014, + "8": -0.0016, + "9": -0.0018000000000000002, + "10": -0.002 + } + } + }, + "hours": { + "baseline": 1000000000.0, + "reform": 999000000.0, + "change": -1000000.0, + "income_effect": 200000.0, + "substitution_effect": -1200000.0 + } + }, + "constituency_impact": null, + "local_authority_impact": null, + "congressional_district_impact": { + "districts": [ + { + "district": "AK-01", + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300000.0 + }, + { + "district": "CA-05", + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290000.0 + }, + { + "district": "CA-12", + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310000.0 + }, + { + "district": "DC-01", + "average_household_income_change": -1.5, + "relative_household_income_change": 0.0004, + "winner_percentage": 0.25, + "loser_percentage": 0.25, + "no_change_percentage": 0.5, + "population": 700000.0 + }, + { + "district": "UT-03", + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280000.0 + }, + { + "district": "WY-01", + "average_household_income_change": 5.0, + "relative_household_income_change": 0.0004, + "winner_percentage": 0.25, + "loser_percentage": 0.25, + "no_change_percentage": 0.5, + "population": 580000.0 + } + ] + }, + "cliff_impact": { + "baseline": { + "cliff_gap": 1200000000.0, + "cliff_share": 0.04 + }, + "reform": { + "cliff_gap": 1100000000.0, + "cliff_share": 0.035 + } + } + }, + "report_run_columns": { + "baseline_cliff_gap": 1200000000.0, + "baseline_cliff_share": 0.04, + "reform_cliff_gap": 1100000000.0, + "reform_cliff_share": 0.035, + "spm_provenance": { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + }, + "reform": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + } + }, + "data_version": "enhanced_cps_2024@1.2.3" + }, + "rows": { + "labor_supply_responses": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "income_effect_earnings_change": 45.0, + "substitution_effect_earnings_change": -120.0, + "total_earnings_change": -75.0, + "revenue_change": -30.0, + "relative_income_effect": 0.001, + "relative_substitution_effect": -0.002, + "baseline_weekly_hours": 1000000000.0, + "reform_weekly_hours": 999000000.0, + "weekly_hours_change": -1000000.0, + "weekly_hours_income_effect": 200000.0, + "weekly_hours_substitution_effect": -1200000.0 + } + ], + "labor_supply_decile_responses": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": -1, + "average_income_effect": 0.5, + "average_substitution_effect": -0.5, + "relative_income_effect": null, + "relative_substitution_effect": null + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 0, + "average_income_effect": 0.7, + "average_substitution_effect": -0.7, + "relative_income_effect": null, + "relative_substitution_effect": null + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 1, + "average_income_effect": 1.5, + "average_substitution_effect": -2.0, + "relative_income_effect": null, + "relative_substitution_effect": null + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 2, + "average_income_effect": 3.0, + "average_substitution_effect": -4.0, + "relative_income_effect": 0.0002, + "relative_substitution_effect": -0.0004 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 3, + "average_income_effect": 4.5, + "average_substitution_effect": -6.0, + "relative_income_effect": 0.00030000000000000003, + "relative_substitution_effect": -0.0006000000000000001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 4, + "average_income_effect": 6.0, + "average_substitution_effect": -8.0, + "relative_income_effect": 0.0004, + "relative_substitution_effect": -0.0008 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 5, + "average_income_effect": 7.5, + "average_substitution_effect": -10.0, + "relative_income_effect": 0.0005, + "relative_substitution_effect": -0.001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 6, + "average_income_effect": 9.0, + "average_substitution_effect": -12.0, + "relative_income_effect": 0.0006000000000000001, + "relative_substitution_effect": -0.0012000000000000001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 7, + "average_income_effect": 10.5, + "average_substitution_effect": -14.0, + "relative_income_effect": 0.0007, + "relative_substitution_effect": -0.0014 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 8, + "average_income_effect": 12.0, + "average_substitution_effect": -16.0, + "relative_income_effect": 0.0008, + "relative_substitution_effect": -0.0016 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 9, + "average_income_effect": 13.5, + "average_substitution_effect": -18.0, + "relative_income_effect": 0.0009000000000000001, + "relative_substitution_effect": -0.0018000000000000002 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 10, + "average_income_effect": 15.0, + "average_substitution_effect": -20.0, + "relative_income_effect": 0.001, + "relative_substitution_effect": -0.002 + } + ], + "budget_summary": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_tax", + "entity": "household", + "change": 1500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_benefits", + "entity": "household", + "change": -500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_state_income_tax", + "entity": "household", + "change": 250.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_net_income", + "entity": "household", + "baseline_total": 9500000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_weight", + "entity": "household", + "baseline_total": 130000000.0 + } + ], + "decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 1, + "quantiles": 10, + "absolute_change": 10.0, + "relative_change": 1.5625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 2, + "quantiles": 10, + "absolute_change": 20.0, + "relative_change": 3.125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 3, + "quantiles": 10, + "absolute_change": 30.0, + "relative_change": 4.6875 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 4, + "quantiles": 10, + "absolute_change": 40.0, + "relative_change": 6.25 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 5, + "quantiles": 10, + "absolute_change": 50.0, + "relative_change": 7.8125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 6, + "quantiles": 10, + "absolute_change": 60.0, + "relative_change": 9.375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 7, + "quantiles": 10, + "absolute_change": 70.0, + "relative_change": 10.9375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 8, + "quantiles": 10, + "absolute_change": 80.0, + "relative_change": 12.5 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 9, + "quantiles": 10, + "absolute_change": 90.0, + "relative_change": 14.0625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 10, + "quantiles": 10, + "absolute_change": 100.0, + "relative_change": 15.625 + } + ], + "intra_decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 1, + "lose_more_than_5pct": 0.05, + "lose_less_than_5pct": 0.051, + "no_change": 0.052, + "gain_less_than_5pct": 0.053, + "gain_more_than_5pct": 0.054 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 2, + "lose_more_than_5pct": 0.06, + "lose_less_than_5pct": 0.061, + "no_change": 0.062, + "gain_less_than_5pct": 0.063, + "gain_more_than_5pct": 0.064 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 3, + "lose_more_than_5pct": 0.07, + "lose_less_than_5pct": 0.071, + "no_change": 0.072, + "gain_less_than_5pct": 0.073, + "gain_more_than_5pct": 0.074 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 4, + "lose_more_than_5pct": 0.08, + "lose_less_than_5pct": 0.081, + "no_change": 0.082, + "gain_less_than_5pct": 0.083, + "gain_more_than_5pct": 0.084 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 5, + "lose_more_than_5pct": 0.09, + "lose_less_than_5pct": 0.091, + "no_change": 0.092, + "gain_less_than_5pct": 0.093, + "gain_more_than_5pct": 0.094 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 6, + "lose_more_than_5pct": 0.1, + "lose_less_than_5pct": 0.101, + "no_change": 0.102, + "gain_less_than_5pct": 0.103, + "gain_more_than_5pct": 0.104 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 7, + "lose_more_than_5pct": 0.11, + "lose_less_than_5pct": 0.111, + "no_change": 0.112, + "gain_less_than_5pct": 0.113, + "gain_more_than_5pct": 0.114 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 8, + "lose_more_than_5pct": 0.12, + "lose_less_than_5pct": 0.121, + "no_change": 0.122, + "gain_less_than_5pct": 0.123, + "gain_more_than_5pct": 0.124 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 9, + "lose_more_than_5pct": 0.13, + "lose_less_than_5pct": 0.131, + "no_change": 0.132, + "gain_less_than_5pct": 0.133, + "gain_more_than_5pct": 0.134 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 10, + "lose_more_than_5pct": 0.14, + "lose_less_than_5pct": 0.141, + "no_change": 0.142, + "gain_less_than_5pct": 0.143, + "gain_more_than_5pct": 0.144 + } + ], + "poverty": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.14 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.12000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.04 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.06 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.07 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.04 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.05 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "white", + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "black", + "rate": 0.18 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "hispanic", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "other", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.12000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.09000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.14 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.06 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.03 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.05 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.035 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.045 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "white", + "rate": 0.07 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "black", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "hispanic", + "rate": 0.15 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "other", + "rate": 0.11 + } + ], + "inequality": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "income_variable": "household_net_income", + "entity": "household", + "gini": 0.41, + "top_10_share": 0.32, + "top_1_share": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "entity": "household", + "gini": 0.4, + "top_10_share": 0.31, + "top_1_share": 0.105 + } + ], + "program_statistics": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "income_tax", + "entity": null, + "is_tax": true, + "baseline_total": 1000.0, + "reform_total": 2500.0, + "change": 1500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "snap", + "entity": null, + "is_tax": false, + "baseline_total": 800.0, + "reform_total": 300.0, + "change": -500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "state_income_tax", + "entity": null, + "is_tax": null, + "baseline_total": 10.0, + "reform_total": 260.0, + "change": 250.0 + } + ], + "congressional_district_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 200, + "state_fips": 2, + "district_number": 0, + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 605, + "state_fips": 6, + "district_number": 5, + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 612, + "state_fips": 6, + "district_number": 12, + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 1100, + "state_fips": 11, + "district_number": 0, + "average_household_income_change": -1.5, + "relative_household_income_change": 0.0004, + "winner_percentage": 0.25, + "loser_percentage": 0.25, + "no_change_percentage": 0.5, + "population": 700000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 4903, + "state_fips": 49, + "district_number": 3, + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 5600, + "state_fips": 56, + "district_number": 0, + "average_household_income_change": 5.0, + "relative_household_income_change": 0.0004, + "winner_percentage": 0.25, + "loser_percentage": 0.25, + "no_change_percentage": 0.5, + "population": 580000.0 + } + ], + "constituency_impacts": [], + "local_authority_impacts": [] + } + }, + { + "name": "us-negative-budget", + "country": "us", + "output": { + "spm_provenance": { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + }, + "reform": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + } + }, + "model_version": "1.0.0", + "data_version": "enhanced_cps_2024@1.2.3", + "budget": { + "tax_revenue_impact": -1500.0, + "state_tax_revenue_impact": -250.0, + "benefit_spending_impact": 500.0, + "budgetary_impact": -2000.0, + "households": 130000000.0, + "baseline_net_income": 9500000000000.0 + }, + "detailed_budget": { + "income_tax": { + "baseline": 1000.0, + "reform": 2500.0, + "difference": 1500.0, + "is_tax": true + }, + "snap": { + "baseline": 800.0, + "reform": 300.0, + "difference": -500.0, + "is_tax": false + }, + "state_income_tax": { + "baseline": 10.0, + "reform": 260.0, + "difference": 250.0, + "is_tax": null + } + }, + "decile": { + "average": { + "1": 10.0, + "2": 20.0, + "3": 30.0, + "4": 40.0, + "5": 50.0, + "6": 60.0, + "7": 70.0, + "8": 80.0, + "9": 90.0, + "10": 100.0 + }, + "relative": { + "1": 0.015625, + "2": 0.03125, + "3": 0.046875, + "4": 0.0625, + "5": 0.078125, + "6": 0.09375, + "7": 0.109375, + "8": 0.125, + "9": 0.140625, + "10": 0.15625 + } + }, + "inequality": { + "gini": { + "baseline": 0.41, + "reform": 0.4 + }, + "top_10_pct_share": { + "baseline": 0.32, + "reform": 0.31 + }, + "top_1_pct_share": { + "baseline": 0.11, + "reform": 0.105 + } + }, + "poverty": { + "poverty": { + "child": { + "baseline": 0.1, + "reform": 0.09000000000000001 + }, + "adult": { + "baseline": 0.12000000000000001, + "reform": 0.11 + }, + "senior": { + "baseline": 0.13, + "reform": 0.14 + }, + "all": { + "baseline": 0.14, + "reform": 0.12000000000000001 + } + }, + "deep_poverty": { + "child": { + "baseline": 0.04, + "reform": 0.03 + }, + "adult": { + "baseline": 0.06, + "reform": 0.05 + }, + "senior": { + "baseline": 0.07, + "reform": 0.08 + }, + "all": { + "baseline": 0.08, + "reform": 0.06 + } + } + }, + "poverty_by_gender": { + "poverty": { + "male": { + "baseline": 0.11, + "reform": 0.1 + }, + "female": { + "baseline": 0.13, + "reform": 0.12 + } + }, + "deep_poverty": { + "male": { + "baseline": 0.04, + "reform": 0.035 + }, + "female": { + "baseline": 0.05, + "reform": 0.045 + } + } + }, + "poverty_by_race": { + "poverty": { + "white": { + "baseline": 0.08, + "reform": 0.07 + }, + "black": { + "baseline": 0.18, + "reform": 0.16 + }, + "hispanic": { + "baseline": 0.16, + "reform": 0.15 + }, + "other": { + "baseline": 0.12, + "reform": 0.11 + } + } + }, + "intra_decile": { + "deciles": { + "Lose more than 5%": [ + 0.05, + 0.06, + 0.07, + 0.08, + 0.09, + 0.1, + 0.11, + 0.12, + 0.13, + 0.14 + ], + "Lose less than 5%": [ + 0.051, + 0.061, + 0.071, + 0.081, + 0.091, + 0.101, + 0.111, + 0.121, + 0.131, + 0.141 + ], + "No change": [ + 0.052, + 0.062, + 0.072, + 0.082, + 0.092, + 0.102, + 0.112, + 0.122, + 0.132, + 0.142 + ], + "Gain less than 5%": [ + 0.053, + 0.063, + 0.073, + 0.083, + 0.093, + 0.103, + 0.113, + 0.123, + 0.133, + 0.143 + ], + "Gain more than 5%": [ + 0.054, + 0.064, + 0.074, + 0.084, + 0.094, + 0.104, + 0.114, + 0.124, + 0.134, + 0.144 + ] + }, + "all": { + "Lose more than 5%": 0.095, + "Lose less than 5%": 0.096, + "No change": 0.097, + "Gain less than 5%": 0.098, + "Gain more than 5%": 0.099 + } + }, + "wealth_decile": null, + "intra_wealth_decile": null, + "labor_supply_response": { + "substitution_lsr": -120.0, + "income_lsr": 45.0, + "relative_lsr": { + "income": 0.001, + "substitution": -0.002 + }, + "total_change": -75.0, + "revenue_change": -30.0, + "decile": { + "average": { + "income": { + "1": 1.5, + "2": 3.0, + "3": 4.5, + "4": 6.0, + "5": 7.5, + "6": 9.0, + "7": 10.5, + "8": 12.0, + "9": 13.5, + "10": 15.0 + }, + "substitution": { + "1": -2.0, + "2": -4.0, + "3": -6.0, + "4": -8.0, + "5": -10.0, + "6": -12.0, + "7": -14.0, + "8": -16.0, + "9": -18.0, + "10": -20.0 + } + }, + "relative": { + "income": { + "2": 0.0002, + "3": 0.00030000000000000003, + "4": 0.0004, + "5": 0.0005, + "6": 0.0006000000000000001, + "7": 0.0007, + "8": 0.0008, + "9": 0.0009000000000000001, + "10": 0.001 + }, + "substitution": { + "2": -0.0004, + "3": -0.0006000000000000001, + "4": -0.0008, + "5": -0.001, + "6": -0.0012000000000000001, + "7": -0.0014, + "8": -0.0016, + "9": -0.0018000000000000002, + "10": -0.002 + } + } + }, + "hours": { + "baseline": 1000000000.0, + "reform": 999000000.0, + "change": -1000000.0, + "income_effect": 200000.0, + "substitution_effect": -1200000.0 + } + }, + "constituency_impact": null, + "local_authority_impact": null, + "congressional_district_impact": { + "districts": [ + { + "district": "AK-01", + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300000.0 + }, + { + "district": "CA-05", + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290000.0 + }, + { + "district": "CA-12", + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310000.0 + }, + { + "district": "UT-03", + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280000.0 + } + ] + }, + "cliff_impact": { + "baseline": { + "cliff_gap": 1200000000.0, + "cliff_share": 0.04 + }, + "reform": { + "cliff_gap": 1100000000.0, + "cliff_share": 0.035 + } + } + }, + "report_run_columns": { + "baseline_cliff_gap": 1200000000.0, + "baseline_cliff_share": 0.04, + "reform_cliff_gap": 1100000000.0, + "reform_cliff_share": 0.035, + "spm_provenance": { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + }, + "reform": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "scenario": "baseline", + "geography_kind": "county", + "geography_id": null, + "county_vintage": "2020", + "as_of": null, + "years": [ + "2026" + ], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0" + } + }, + "execution_count": 1 + } + }, + "data_version": "enhanced_cps_2024@1.2.3" + }, + "rows": { + "labor_supply_responses": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "income_effect_earnings_change": 45.0, + "substitution_effect_earnings_change": -120.0, + "total_earnings_change": -75.0, + "revenue_change": -30.0, + "relative_income_effect": 0.001, + "relative_substitution_effect": -0.002, + "baseline_weekly_hours": 1000000000.0, + "reform_weekly_hours": 999000000.0, + "weekly_hours_change": -1000000.0, + "weekly_hours_income_effect": 200000.0, + "weekly_hours_substitution_effect": -1200000.0 + } + ], + "labor_supply_decile_responses": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 1, + "average_income_effect": 1.5, + "average_substitution_effect": -2.0, + "relative_income_effect": null, + "relative_substitution_effect": null + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 2, + "average_income_effect": 3.0, + "average_substitution_effect": -4.0, + "relative_income_effect": 0.0002, + "relative_substitution_effect": -0.0004 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 3, + "average_income_effect": 4.5, + "average_substitution_effect": -6.0, + "relative_income_effect": 0.00030000000000000003, + "relative_substitution_effect": -0.0006000000000000001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 4, + "average_income_effect": 6.0, + "average_substitution_effect": -8.0, + "relative_income_effect": 0.0004, + "relative_substitution_effect": -0.0008 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 5, + "average_income_effect": 7.5, + "average_substitution_effect": -10.0, + "relative_income_effect": 0.0005, + "relative_substitution_effect": -0.001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 6, + "average_income_effect": 9.0, + "average_substitution_effect": -12.0, + "relative_income_effect": 0.0006000000000000001, + "relative_substitution_effect": -0.0012000000000000001 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 7, + "average_income_effect": 10.5, + "average_substitution_effect": -14.0, + "relative_income_effect": 0.0007, + "relative_substitution_effect": -0.0014 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 8, + "average_income_effect": 12.0, + "average_substitution_effect": -16.0, + "relative_income_effect": 0.0008, + "relative_substitution_effect": -0.0016 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 9, + "average_income_effect": 13.5, + "average_substitution_effect": -18.0, + "relative_income_effect": 0.0009000000000000001, + "relative_substitution_effect": -0.0018000000000000002 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "decile": 10, + "average_income_effect": 15.0, + "average_substitution_effect": -20.0, + "relative_income_effect": 0.001, + "relative_substitution_effect": -0.002 + } + ], + "budget_summary": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_tax", + "entity": "household", + "change": -1500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_benefits", + "entity": "household", + "change": 500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_state_income_tax", + "entity": "household", + "change": -250.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_net_income", + "entity": "household", + "baseline_total": 9500000000000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "variable_name": "household_weight", + "entity": "household", + "baseline_total": 130000000.0 + } + ], + "decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 1, + "quantiles": 10, + "absolute_change": 10.0, + "relative_change": 1.5625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 2, + "quantiles": 10, + "absolute_change": 20.0, + "relative_change": 3.125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 3, + "quantiles": 10, + "absolute_change": 30.0, + "relative_change": 4.6875 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 4, + "quantiles": 10, + "absolute_change": 40.0, + "relative_change": 6.25 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 5, + "quantiles": 10, + "absolute_change": 50.0, + "relative_change": 7.8125 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 6, + "quantiles": 10, + "absolute_change": 60.0, + "relative_change": 9.375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 7, + "quantiles": 10, + "absolute_change": 70.0, + "relative_change": 10.9375 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 8, + "quantiles": 10, + "absolute_change": 80.0, + "relative_change": 12.5 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 9, + "quantiles": 10, + "absolute_change": 90.0, + "relative_change": 14.0625 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "decile_variable": null, + "entity": "household", + "decile": 10, + "quantiles": 10, + "absolute_change": 100.0, + "relative_change": 15.625 + } + ], + "intra_decile_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 1, + "lose_more_than_5pct": 0.05, + "lose_less_than_5pct": 0.051, + "no_change": 0.052, + "gain_less_than_5pct": 0.053, + "gain_more_than_5pct": 0.054 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 2, + "lose_more_than_5pct": 0.06, + "lose_less_than_5pct": 0.061, + "no_change": 0.062, + "gain_less_than_5pct": 0.063, + "gain_more_than_5pct": 0.064 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 3, + "lose_more_than_5pct": 0.07, + "lose_less_than_5pct": 0.071, + "no_change": 0.072, + "gain_less_than_5pct": 0.073, + "gain_more_than_5pct": 0.074 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 4, + "lose_more_than_5pct": 0.08, + "lose_less_than_5pct": 0.081, + "no_change": 0.082, + "gain_less_than_5pct": 0.083, + "gain_more_than_5pct": 0.084 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 5, + "lose_more_than_5pct": 0.09, + "lose_less_than_5pct": 0.091, + "no_change": 0.092, + "gain_less_than_5pct": 0.093, + "gain_more_than_5pct": 0.094 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 6, + "lose_more_than_5pct": 0.1, + "lose_less_than_5pct": 0.101, + "no_change": 0.102, + "gain_less_than_5pct": 0.103, + "gain_more_than_5pct": 0.104 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 7, + "lose_more_than_5pct": 0.11, + "lose_less_than_5pct": 0.111, + "no_change": 0.112, + "gain_less_than_5pct": 0.113, + "gain_more_than_5pct": 0.114 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 8, + "lose_more_than_5pct": 0.12, + "lose_less_than_5pct": 0.121, + "no_change": 0.122, + "gain_less_than_5pct": 0.123, + "gain_more_than_5pct": 0.124 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 9, + "lose_more_than_5pct": 0.13, + "lose_less_than_5pct": 0.131, + "no_change": 0.132, + "gain_less_than_5pct": 0.133, + "gain_more_than_5pct": 0.134 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "decile_type": "income", + "decile": 10, + "lose_more_than_5pct": 0.14, + "lose_less_than_5pct": 0.141, + "no_change": 0.142, + "gain_less_than_5pct": 0.143, + "gain_more_than_5pct": 0.144 + } + ], + "poverty": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.14 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.12000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.13 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.04 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.06 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.07 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.04 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.05 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "white", + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "black", + "rate": 0.18 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "hispanic", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "other", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.12000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.09000000000000001 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.14 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.1 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.12 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": null, + "filter_group": null, + "rate": 0.06 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "child", + "rate": 0.03 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "adult", + "rate": 0.05 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "age", + "filter_group": "senior", + "rate": 0.08 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "male", + "rate": 0.035 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm_deep", + "entity": "person", + "filter_variable": "is_male", + "filter_group": "female", + "rate": 0.045 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "white", + "rate": 0.07 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "black", + "rate": 0.16 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "hispanic", + "rate": 0.15 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "poverty_type": "spm", + "entity": "person", + "filter_variable": "race", + "filter_group": "other", + "rate": 0.11 + } + ], + "inequality": [ + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "income_variable": "household_net_income", + "entity": "household", + "gini": 0.41, + "top_10_share": 0.32, + "top_1_share": 0.11 + }, + { + "simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "income_variable": "household_net_income", + "entity": "household", + "gini": 0.4, + "top_10_share": 0.31, + "top_1_share": 0.105 + } + ], + "program_statistics": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "income_tax", + "entity": null, + "is_tax": true, + "baseline_total": 1000.0, + "reform_total": 2500.0, + "change": 1500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "snap", + "entity": null, + "is_tax": false, + "baseline_total": 800.0, + "reform_total": 300.0, + "change": -500.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "program_name": "state_income_tax", + "entity": null, + "is_tax": null, + "baseline_total": 10.0, + "reform_total": 260.0, + "change": 250.0 + } + ], + "congressional_district_impacts": [ + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 200, + "state_fips": 2, + "district_number": 0, + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 605, + "state_fips": 6, + "district_number": 5, + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 612, + "state_fips": 6, + "district_number": 12, + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310000.0 + }, + { + "report_run_id": "00000000-0000-4000-8000-00000000c001", + "baseline_simulation_run_id": "00000000-0000-4000-8000-00000000c002", + "reform_simulation_run_id": "00000000-0000-4000-8000-00000000c003", + "district_geoid": 4903, + "state_fips": 49, + "district_number": 3, + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280000.0 + } + ], + "constituency_impacts": [], + "local_authority_impacts": [] + } + } + ] +} diff --git a/tests/fixtures/economy_results.py b/tests/fixtures/economy_results.py new file mode 100644 index 000000000..a47b68547 --- /dev/null +++ b/tests/fixtures/economy_results.py @@ -0,0 +1,656 @@ +"""Economy results, and the result rows the simulation service stores them as. + +``economy_result_rows`` follows the simulation service's writer, +``libs/policyengine-stage12-persistence/src/policyengine_stage12_persistence/ +report_run_results.py`` in PolicyEngine/policyengine-sim-api (last changed in +``c02145fd``), field for field, so the Public API's rebuild of a result from +its rows is tested against the same mapping. Each row is a dict of the +table's columns; ``id`` and ``created_at`` are left for the caller. +""" + +from __future__ import annotations + +import copy +from dataclasses import dataclass +from typing import TYPE_CHECKING, Any + +if TYPE_CHECKING: + from uuid import UUID + +# .py's poverty types behind the result's "poverty" and "deep_poverty". +POVERTY_TYPES = { + "us": {"poverty": "spm", "deep_poverty": "spm_deep"}, + "uk": {"poverty": "relative_bhc", "deep_poverty": "absolute_bhc"}, +} +POVERTY_GROUPS = { + "age": ("child", "adult", "senior"), + "is_male": ("male", "female"), + "race": ("white", "black", "hispanic", "other"), +} +INEQUALITY_INCOME_VARIABLES = { + "us": "household_net_income", + "uk": "equiv_hbai_household_net_income", +} +INTRA_DECILE_COLUMNS = { + "Lose more than 5%": "lose_more_than_5pct", + "Lose less than 5%": "lose_less_than_5pct", + "No change": "no_change", + "Gain less than 5%": "gain_less_than_5pct", + "Gain more than 5%": "gain_more_than_5pct", +} +DISCLOSURE_FIELDS = ( + "disclosure_tier", + "average_household_income_change_lower", + "average_household_income_change_upper", + "relative_household_income_change_lower", + "relative_household_income_change_upper", +) +# The states the sample districts are in, and .py's at-large states. +STATE_FIPS = {"AK": 2, "CA": 6, "UT": 49} +AT_LARGE_STATES = frozenset({"AK"}) + + +@dataclass(frozen=True) +class RunIds: + """The report run, and the two simulation runs it compares.""" + + report_run_id: UUID + baseline_simulation_run_id: UUID + reform_simulation_run_id: UUID + + +def _pair(baseline: float, reform: float) -> dict[str, float]: + return {"baseline": baseline, "reform": reform} + + +def _age_poverty(start: float) -> dict[str, Any]: + return { + "child": _pair(start, start - 0.01), + "adult": _pair(start + 0.02, start + 0.01), + "senior": _pair(start + 0.03, start + 0.04), + "all": _pair(start + 0.04, start + 0.02), + } + + +def _intra_decile(offset: float) -> dict[str, Any]: + deciles = { + label: [ + round(offset + index * 0.01 + position * 0.001, 6) for index in range(10) + ] + for position, label in enumerate(INTRA_DECILE_COLUMNS) + } + return { + "deciles": deciles, + "all": {label: sum(values) / len(values) for label, values in deciles.items()}, + } + + +def _deciles(scale: float) -> dict[str, Any]: + return { + "average": {str(decile): scale * decile for decile in range(1, 11)}, + # Fractions a hundredfold change keeps exactly, as the rows hold + # percentages. + "relative": {str(decile): decile / 64 for decile in range(1, 11)}, + } + + +SPM_PROVENANCE = { + "schema_version": "canonical-spm-comparison-v2", + "baseline": { + "receipt": { + "schema_version": "canonical-spm-provenance-v2", + "forecast_id": "spm-forecast-2026", + "forecast_sha256": "a" * 64, + "scenario": "baseline", + "geography_kind": "county", + "geography_id": None, + "county_vintage": "2020", + "as_of": None, + "years": ["2026"], + "runtime_versions": { + "policyengine": "4.0.0", + "policyengine-core": "3.0.0", + "policyengine-us": "1.0.0", + "spm-calculator": "0.5.0", + }, + }, + "execution_count": 1, + }, +} +SPM_PROVENANCE["reform"] = copy.deepcopy(SPM_PROVENANCE["baseline"]) + + +def us_economy_result() -> dict[str, Any]: + """Return a US state report's economy result with every US-only part.""" + return { + "spm_provenance": copy.deepcopy(SPM_PROVENANCE), + "model_version": "1.0.0", + "data_version": "enhanced_cps_2024@1.2.3", + "budget": { + "tax_revenue_impact": 1500.0, + "state_tax_revenue_impact": 250.0, + "benefit_spending_impact": -500.0, + "budgetary_impact": 2000.0, + "households": 130_000_000.0, + "baseline_net_income": 9.5e12, + }, + "detailed_budget": { + "income_tax": { + "baseline": 1000.0, + "reform": 2500.0, + "difference": 1500.0, + "is_tax": True, + }, + "snap": { + "baseline": 800.0, + "reform": 300.0, + "difference": -500.0, + "is_tax": False, + }, + "state_income_tax": { + "baseline": 10.0, + "reform": 260.0, + "difference": 250.0, + "is_tax": None, + }, + }, + "decile": _deciles(10.0), + "inequality": { + "gini": _pair(0.41, 0.4), + "top_10_pct_share": _pair(0.32, 0.31), + "top_1_pct_share": _pair(0.11, 0.105), + }, + "poverty": {"poverty": _age_poverty(0.1), "deep_poverty": _age_poverty(0.04)}, + "poverty_by_gender": { + "poverty": {"male": _pair(0.11, 0.1), "female": _pair(0.13, 0.12)}, + "deep_poverty": {"male": _pair(0.04, 0.035), "female": _pair(0.05, 0.045)}, + }, + "poverty_by_race": { + "poverty": { + "white": _pair(0.08, 0.07), + "black": _pair(0.18, 0.16), + "hispanic": _pair(0.16, 0.15), + "other": _pair(0.12, 0.11), + } + }, + "intra_decile": _intra_decile(0.05), + "wealth_decile": None, + "intra_wealth_decile": None, + "labor_supply_response": { + "substitution_lsr": -120.0, + "income_lsr": 45.0, + "relative_lsr": {"income": 0.001, "substitution": -0.002}, + "total_change": -75.0, + "revenue_change": -30.0, + "decile": { + "average": { + "income": {decile: 1.5 * decile for decile in range(1, 11)}, + "substitution": {decile: -2.0 * decile for decile in range(1, 11)}, + }, + # .py reports relative responses only for deciles above zero. + "relative": { + "income": {decile: 0.0001 * decile for decile in range(2, 11)}, + "substitution": { + decile: -0.0002 * decile for decile in range(2, 11) + }, + }, + }, + "hours": { + "baseline": 1.0e9, + "reform": 0.999e9, + "change": -1.0e6, + "income_effect": 2.0e5, + "substitution_effect": -1.2e6, + }, + }, + "constituency_impact": None, + "local_authority_impact": None, + "congressional_district_impact": { + "districts": [ + { + "district": "AK-01", + "average_household_income_change": 12.0, + "relative_household_income_change": 0.001, + "winner_percentage": 0.3, + "loser_percentage": 0.2, + "no_change_percentage": 0.5, + "population": 300_000.0, + }, + { + "district": "CA-05", + "average_household_income_change": -4.0, + "relative_household_income_change": -0.0005, + "winner_percentage": 0.1, + "loser_percentage": 0.6, + "no_change_percentage": 0.3, + "population": 290_000.0, + }, + { + "district": "CA-12", + "average_household_income_change": 7.5, + "relative_household_income_change": 0.0008, + "winner_percentage": 0.4, + "loser_percentage": 0.1, + "no_change_percentage": 0.5, + "population": 310_000.0, + }, + { + "district": "UT-03", + "average_household_income_change": 3.0, + "relative_household_income_change": 0.0002, + "winner_percentage": 0.2, + "loser_percentage": 0.2, + "no_change_percentage": 0.6, + "population": 280_000.0, + }, + ] + }, + "cliff_impact": { + "baseline": {"cliff_gap": 1.2e9, "cliff_share": 0.04}, + "reform": {"cliff_gap": 1.1e9, "cliff_share": 0.035}, + }, + } + + +def _area(code: str, name: str, kind: str, **values: Any) -> dict[str, Any]: + return { + f"{kind}_code": code, + f"{kind}_name": name, + "average_household_income_change": values.get("average", 10.0), + "relative_household_income_change": values.get("relative", 0.001), + "population": values.get("population", 40_000.0), + "disclosure_tier": values.get("tier", "reported"), + "average_household_income_change_lower": values.get("average_lower", 8.0), + "average_household_income_change_upper": values.get("average_upper", 12.0), + "relative_household_income_change_lower": values.get("relative_lower", 0.0008), + "relative_household_income_change_upper": values.get("relative_upper", 0.0012), + } + + +def uk_economy_result() -> dict[str, Any]: + """Return a UK report's economy result with wealth deciles and area impacts. + + One constituency is approximate, and one local authority was stored + before disclosure control, with no tier or intervals. + """ + stored_before_disclosure = _area( + "E06000002", "Middlesbrough", "local_authority", average=-3.0 + ) + for field in DISCLOSURE_FIELDS: + stored_before_disclosure[field] = None + return { + "spm_provenance": None, + "model_version": "2.0.0", + "data_version": "enhanced_frs_2023_24@1.0.0", + "budget": { + "tax_revenue_impact": 4.0e9, + "state_tax_revenue_impact": 0.0, + "benefit_spending_impact": 1.0e9, + "budgetary_impact": 3.0e9, + "households": 28_000_000.0, + "baseline_net_income": 1.2e12, + }, + "detailed_budget": { + "income_tax": { + "baseline": 2.0e11, + "reform": 2.04e11, + "difference": 4.0e9, + "is_tax": True, + }, + "universal_credit": { + "baseline": 6.0e10, + "reform": 6.1e10, + "difference": 1.0e9, + "is_tax": False, + }, + }, + "decile": _deciles(-5.0), + "inequality": { + "gini": _pair(0.36, 0.355), + "top_10_pct_share": _pair(0.27, 0.265), + "top_1_pct_share": _pair(0.08, 0.079), + }, + "poverty": {"poverty": _age_poverty(0.17), "deep_poverty": _age_poverty(0.12)}, + "poverty_by_gender": { + "poverty": {"male": _pair(0.16, 0.15), "female": _pair(0.18, 0.17)}, + "deep_poverty": {"male": _pair(0.11, 0.1), "female": _pair(0.13, 0.12)}, + }, + "poverty_by_race": None, + "intra_decile": _intra_decile(0.02), + "wealth_decile": _deciles(-8.0), + "intra_wealth_decile": _intra_decile(0.03), + "labor_supply_response": None, + "constituency_impact": [ + _area("E14001063", "Aldershot", "constituency"), + _area( + "W07000081", + "Aberafan Maesteg", + "constituency", + average=-2.5, + tier="approximate", + ), + ], + "local_authority_impact": [ + _area("E06000001", "Hartlepool", "local_authority", average=4.0), + stored_before_disclosure, + ], + "congressional_district_impact": None, + "cliff_impact": None, + } + + +@dataclass(frozen=True) +class StoredEconomyResult: + """What an economy result is stored as: report run columns and table rows.""" + + report_run_columns: dict[str, Any] + rows: dict[str, list[dict[str, Any]]] + + +def economy_result_rows( + output: dict[str, Any], *, run_ids: RunIds, country: str +) -> StoredEconomyResult: + """Return the rows the simulation service's writer stores ``output`` as.""" + report_keys = { + "report_run_id": run_ids.report_run_id, + "baseline_simulation_run_id": run_ids.baseline_simulation_run_id, + "reform_simulation_run_id": run_ids.reform_simulation_run_id, + } + cliffs = output.get("cliff_impact") + report_run_columns = { + "baseline_cliff_gap": None + if cliffs is None + else cliffs["baseline"]["cliff_gap"], + "baseline_cliff_share": ( + None if cliffs is None else cliffs["baseline"]["cliff_share"] + ), + "reform_cliff_gap": None if cliffs is None else cliffs["reform"]["cliff_gap"], + "reform_cliff_share": None + if cliffs is None + else cliffs["reform"]["cliff_share"], + "spm_provenance": output.get("spm_provenance"), + "data_version": output["data_version"], + } + return StoredEconomyResult( + report_run_columns=report_run_columns, + rows={ + "labor_supply_responses": _labor_supply_rows(output, run_ids), + "labor_supply_decile_responses": _labor_supply_decile_rows(output, run_ids), + "budget_summary": _budget_rows(output, report_keys, country), + "decile_impacts": _decile_rows(output, report_keys), + "intra_decile_impacts": _intra_decile_rows(output, report_keys), + "poverty": _poverty_rows(output, run_ids, country), + "inequality": _inequality_rows(output, run_ids, country), + "program_statistics": _program_rows(output, report_keys), + "congressional_district_impacts": _district_rows(output, report_keys), + "constituency_impacts": _area_rows( + output.get("constituency_impact"), report_keys, "constituency" + ), + "local_authority_impacts": _area_rows( + output.get("local_authority_impact"), report_keys, "local_authority" + ), + }, + ) + + +def _labor_supply_rows(output: dict[str, Any], run_ids: RunIds) -> list[dict[str, Any]]: + response = output.get("labor_supply_response") + if response is None: + return [] + hours = response["hours"] + return [ + { + "report_run_id": run_ids.report_run_id, + "income_effect_earnings_change": response["income_lsr"], + "substitution_effect_earnings_change": response["substitution_lsr"], + "total_earnings_change": response["total_change"], + "revenue_change": response["revenue_change"], + "relative_income_effect": response["relative_lsr"]["income"], + "relative_substitution_effect": response["relative_lsr"]["substitution"], + "baseline_weekly_hours": hours["baseline"], + "reform_weekly_hours": hours["reform"], + "weekly_hours_change": hours["change"], + "weekly_hours_income_effect": hours["income_effect"], + "weekly_hours_substitution_effect": hours["substitution_effect"], + } + ] + + +def _labor_supply_decile_rows( + output: dict[str, Any], run_ids: RunIds +) -> list[dict[str, Any]]: + response = output.get("labor_supply_response") + if response is None: + return [] + by_decile = response["decile"] + values = { + "average_income_effect": by_decile["average"]["income"], + "average_substitution_effect": by_decile["average"]["substitution"], + "relative_income_effect": by_decile["relative"]["income"], + "relative_substitution_effect": by_decile["relative"]["substitution"], + } + deciles = sorted({int(decile) for column in values.values() for decile in column}) + return [ + { + "report_run_id": run_ids.report_run_id, + "decile": decile, + **{ + column: column_values.get(decile) + for column, column_values in values.items() + }, + } + for decile in deciles + ] + + +def _budget_rows( + output: dict[str, Any], keys: dict[str, Any], country: str +) -> list[dict[str, Any]]: + figures = ( + ("tax_revenue_impact", "household_tax", "change"), + ("benefit_spending_impact", "household_benefits", "change"), + ("state_tax_revenue_impact", "household_state_income_tax", "change"), + ("baseline_net_income", "household_net_income", "baseline_total"), + ("households", "household_weight", "baseline_total"), + ) + return [ + { + **keys, + "variable_name": variable, + "entity": "household", + column: output["budget"][figure], + } + for figure, variable, column in figures + if variable != "household_state_income_tax" or country == "us" + ] + + +def _decile_rows(output: dict[str, Any], keys: dict[str, Any]) -> list[dict[str, Any]]: + rows = _decile_type_rows(output["decile"], None, keys) + if output.get("wealth_decile") is not None: + rows += _decile_type_rows( + output["wealth_decile"], "household_wealth_decile", keys + ) + return rows + + +def _decile_type_rows( + deciles: dict[str, Any], decile_variable: str | None, keys: dict[str, Any] +) -> list[dict[str, Any]]: + return [ + { + **keys, + "income_variable": "household_net_income", + "decile_variable": decile_variable, + "entity": "household", + "decile": int(decile), + "quantiles": 10, + "absolute_change": average, + "relative_change": deciles["relative"][decile] * 100, + } + for decile, average in deciles["average"].items() + ] + + +def _intra_decile_rows( + output: dict[str, Any], keys: dict[str, Any] +) -> list[dict[str, Any]]: + rows = _intra_decile_type_rows(output["intra_decile"], "income", keys) + if output.get("intra_wealth_decile") is not None: + rows += _intra_decile_type_rows(output["intra_wealth_decile"], "wealth", keys) + return rows + + +def _intra_decile_type_rows( + shares: dict[str, Any], decile_type: str, keys: dict[str, Any] +) -> list[dict[str, Any]]: + deciles = shares["deciles"] + decile_count = max((len(values) for values in deciles.values()), default=0) + return [ + { + **keys, + "decile_type": decile_type, + "decile": index + 1, + **{ + column: deciles[label][index] + for label, column in INTRA_DECILE_COLUMNS.items() + if index < len(deciles.get(label, ())) + }, + } + for index in range(decile_count) + ] + + +def _poverty_rates( + output: dict[str, Any], +) -> list[tuple[str, str | None, str | None, Any]]: + rates: list[tuple[str, str | None, str | None, Any]] = [] + for measure in ("poverty", "deep_poverty"): + by_age = output["poverty"][measure] + rates.append((measure, None, None, by_age["all"])) + rates += [ + (measure, "age", group, by_age[group]) for group in POVERTY_GROUPS["age"] + ] + by_gender = output["poverty_by_gender"][measure] + rates += [ + (measure, "is_male", group, by_gender[group]) + for group in POVERTY_GROUPS["is_male"] + ] + if output.get("poverty_by_race") is not None: + by_race = output["poverty_by_race"]["poverty"] + rates += [ + ("poverty", "race", group, by_race[group]) + for group in POVERTY_GROUPS["race"] + ] + return rates + + +def _sides(run_ids: RunIds) -> tuple[tuple[str, UUID], ...]: + return ( + ("baseline", run_ids.baseline_simulation_run_id), + ("reform", run_ids.reform_simulation_run_id), + ) + + +def _poverty_rows( + output: dict[str, Any], run_ids: RunIds, country: str +) -> list[dict[str, Any]]: + poverty_types = POVERTY_TYPES[country] + return [ + { + "simulation_run_id": simulation_run_id, + "poverty_type": poverty_types[measure], + "entity": "person", + "filter_variable": filter_variable, + "filter_group": filter_group, + "rate": rates[side], + } + for side, simulation_run_id in _sides(run_ids) + for measure, filter_variable, filter_group, rates in _poverty_rates(output) + ] + + +def _inequality_rows( + output: dict[str, Any], run_ids: RunIds, country: str +) -> list[dict[str, Any]]: + inequality = output["inequality"] + return [ + { + "simulation_run_id": simulation_run_id, + "income_variable": INEQUALITY_INCOME_VARIABLES[country], + "entity": "household", + "gini": inequality["gini"][side], + "top_10_share": inequality["top_10_pct_share"][side], + "top_1_share": inequality["top_1_pct_share"][side], + } + for side, simulation_run_id in _sides(run_ids) + ] + + +def _program_rows(output: dict[str, Any], keys: dict[str, Any]) -> list[dict[str, Any]]: + return [ + { + **keys, + "program_name": program_name, + "entity": None, + "is_tax": program.get("is_tax"), + "baseline_total": program["baseline"], + "reform_total": program["reform"], + "change": program["difference"], + } + for program_name, program in output["detailed_budget"].items() + ] + + +def _district_rows( + output: dict[str, Any], keys: dict[str, Any] +) -> list[dict[str, Any]]: + impact = output.get("congressional_district_impact") + if impact is None: + return [] + rows = [] + for district in impact["districts"]: + state, _, number = district["district"].partition("-") + state_fips = STATE_FIPS[state] + district_number = 0 if state in AT_LARGE_STATES else int(number) + rows.append( + { + **keys, + "district_geoid": state_fips * 100 + district_number, + "state_fips": state_fips, + "district_number": district_number, + **{ + field: district[field] + for field in ( + "average_household_income_change", + "relative_household_income_change", + "winner_percentage", + "loser_percentage", + "no_change_percentage", + "population", + ) + }, + } + ) + return rows + + +def _area_rows( + areas: list[dict[str, Any]] | None, keys: dict[str, Any], kind: str +) -> list[dict[str, Any]]: + if areas is None: + return [] + return [ + { + **keys, + f"{kind}_code": area[f"{kind}_code"], + f"{kind}_name": area[f"{kind}_name"], + "average_household_income_change": area["average_household_income_change"], + "relative_household_income_change": area[ + "relative_household_income_change" + ], + "population": area["population"], + **{field: area.get(field) for field in DISCLOSURE_FIELDS}, + } + for area in areas + ] diff --git a/tests/integration/stored_report_rows.py b/tests/integration/stored_report_rows.py new file mode 100644 index 000000000..9a29558bb --- /dev/null +++ b/tests/integration/stored_report_rows.py @@ -0,0 +1,333 @@ +"""Store reports, simulations and their runs' results for the read integration tests. + +The simulation service and its Modal workers write these tables in staging +and production; here the disposable database's owner writes them, commits +them so the Public API's runtime role can read them, and deletes them again. +Results are stored through the port of the simulation service's writer in +``tests.fixtures.economy_results``. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field, replace +from datetime import UTC, datetime, timedelta +from typing import TYPE_CHECKING, Any +from uuid import UUID, uuid4 + +from sqlalchemy import text +from sqlalchemy.dialects.postgresql import JSONB +from sqlalchemy.sql import bindparam + +from tests.fixtures.economy_results import RunIds, economy_result_rows +from tests.integration.simulation_rows import insert_row + +if TYPE_CHECKING: + from sqlalchemy import Connection + +REGION_CODES = {"us": "state/ca", "uk": "country/wales"} +DATASET_NAMES = {"us": "enhanced_cps_2024", "uk": "enhanced_frs_2023_24"} +STARTED_AT = datetime(2026, 11, 1, 9, tzinfo=UTC) + + +@dataclass +class CatalogRows: + """A country's model, a catalog version of it, a dataset, a region and a policy. + + ``created_model`` says whether the model row was stored here, so cleanup + leaves a model another test stored. + """ + + country: str + model_id: UUID + version_id: UUID + dataset_id: UUID + region_id: UUID + policy_id: UUID + created_model: bool + report_ids: list[UUID] = field(default_factory=list) + simulation_ids: list[UUID] = field(default_factory=list) + household_ids: list[UUID] = field(default_factory=list) + + +def store_catalog(connection: Connection, country: str) -> CatalogRows: + """Store a catalog version, dataset, region and policy of the country's model.""" + model_name = f"policyengine-{country}" + model_id = connection.execute( + text("SELECT id FROM tax_benefit_models WHERE name = :name"), + {"name": model_name}, + ).scalar_one_or_none() + created_model = model_id is None + if model_id is None: + model_id = uuid4() + insert_row(connection, "tax_benefit_models", id=model_id, name=model_name) + rows = CatalogRows( + country=country, + model_id=model_id, + version_id=uuid4(), + dataset_id=uuid4(), + region_id=uuid4(), + policy_id=uuid4(), + created_model=created_model, + ) + insert_row( + connection, + "tax_benefit_model_versions", + id=rows.version_id, + model_id=model_id, + version=f"reads-{rows.version_id.hex[:12]}", + current_law_id=1, + metadata_time_periods="[2026]", + ) + insert_row( + connection, + "datasets", + id=rows.dataset_id, + name=DATASET_NAMES[country], + year=2026, + is_output_dataset=False, + tax_benefit_model_version_id=rows.version_id, + ) + insert_row( + connection, + "regions", + id=rows.region_id, + code=REGION_CODES[country], + label=REGION_CODES[country], + region_type="state" if country == "us" else "country", + requires_filter=False, + tax_benefit_model_version_id=rows.version_id, + default_dataset_id=rows.dataset_id, + ) + insert_row( + connection, + "policies", + id=rows.policy_id, + country_id=country, + tax_benefit_model_id=model_id, + tax_benefit_model_version_id=rows.version_id, + canonicalization_version=1, + content_hash=uuid4().hex * 2, + ) + return rows + + +def store_simulation( + connection: Connection, catalog: CatalogRows, *, policy_id: UUID | None +) -> UUID: + """Store an economy simulation of the catalog's dataset and region.""" + simulation_id = uuid4() + insert_row( + connection, + "simulations", + id=simulation_id, + simulation_type="economy", + dataset_id=catalog.dataset_id, + policy_id=policy_id, + tax_benefit_model_version_id=catalog.version_id, + region_id=catalog.region_id, + year=2026, + ) + catalog.simulation_ids.append(simulation_id) + return simulation_id + + +@dataclass(frozen=True) +class RunSettings: + """A run's package versions, status, creation time and failure message. + + ``run_id`` is the run's ID, a new one when None; a report run's + simulation runs always get new ones. + """ + + versions: dict[str, str] + status: str = "succeeded" + created_at: datetime = STARTED_AT + error_message: str | None = None + run_id: UUID | None = None + + @property + def finished(self) -> bool: + return self.status in {"succeeded", "failed"} + + +def store_simulation_run( + connection: Connection, + catalog: CatalogRows, + simulation_id: UUID, + settings: RunSettings, +) -> UUID: + """Store one run of the simulation; a finished one has a completion time.""" + run_id = uuid4() if settings.run_id is None else settings.run_id + created_at = settings.created_at + insert_row( + connection, + "simulation_runs", + id=run_id, + created_at=created_at, + simulation_id=simulation_id, + year=2026, + tax_benefit_model_version_id=catalog.version_id, + dataset_id=catalog.dataset_id, + region_id=catalog.region_id, + status=settings.status, + started_at=created_at, + completed_at=created_at + timedelta(minutes=5) if settings.finished else None, + **settings.versions, + ) + return run_id + + +@dataclass(frozen=True) +class StoredReport: + """A stored economy report and the simulations it compares.""" + + report_id: UUID + baseline_simulation_id: UUID + reform_simulation_id: UUID + + +def store_report( + connection: Connection, + catalog: CatalogRows, + *, + household_id: UUID | None = None, + budget_window_size: int | None = None, +) -> StoredReport: + """Store a report comparing current law with the catalog's policy.""" + report = StoredReport( + report_id=uuid4(), + baseline_simulation_id=store_simulation(connection, catalog, policy_id=None), + reform_simulation_id=store_simulation( + connection, catalog, policy_id=catalog.policy_id + ), + ) + connection.execute( + text( + "INSERT INTO reports (id, label, description, country, type, " + "tax_benefit_model_id, policy_id, baseline_simulation_id, " + "reform_simulation_id, household_id, dataset_id, region_id, year, " + "budget_window_size, inputs) VALUES (:id, :label, :description, " + ":country, :type, :model_id, :policy_id, :baseline, :reform, " + ":household_id, :dataset_id, :region_id, 2026, :budget_window_size, " + "CAST(:inputs AS JSON))" + ), + { + "id": report.report_id, + "label": f"{catalog.country} reform", + "description": "A stored report", + "country": catalog.country, + "type": "economy", + "model_id": catalog.model_id, + "policy_id": catalog.policy_id, + "baseline": report.baseline_simulation_id, + "reform": report.reform_simulation_id, + "household_id": household_id, + "dataset_id": catalog.dataset_id, + "region_id": catalog.region_id, + "budget_window_size": budget_window_size, + "inputs": '{"include_cliffs": true}', + }, + ) + catalog.report_ids.append(report.report_id) + return report + + +def store_report_run( + connection: Connection, + catalog: CatalogRows, + report: StoredReport, + settings: RunSettings, + result: dict[str, Any] | None = None, +) -> RunIds: + """Store a run of the report and its two simulation runs. + + With ``result``, the run's result columns and rows are stored as the + simulation service's writer stores that economy result. + """ + simulation_run_settings = replace(settings, run_id=None) + run_ids = RunIds( + report_run_id=uuid4() if settings.run_id is None else settings.run_id, + baseline_simulation_run_id=store_simulation_run( + connection, catalog, report.baseline_simulation_id, simulation_run_settings + ), + reform_simulation_run_id=store_simulation_run( + connection, catalog, report.reform_simulation_id, simulation_run_settings + ), + ) + stored = ( + None + if result is None + else economy_result_rows(result, run_ids=run_ids, country=catalog.country) + ) + result_columns: dict[str, Any] = ( + {} if stored is None else dict(stored.report_run_columns) + ) + spm_provenance = result_columns.pop("spm_provenance", None) + created_at = settings.created_at + connection.execute( + text( + "INSERT INTO report_runs (id, created_at, report_id, " + "baseline_simulation_run_id, reform_simulation_run_id, " + "country_package_version, policyengine_version, status, trigger, " + "started_at, completed_at, error_message, spm_provenance" + + "".join(f", {column}" for column in result_columns) + + ") VALUES (:id, :created_at, :report_id, :baseline_run, " + ":reform_run, :country_package_version, :policyengine_version, " + ":status, 'initial', :started_at, :completed_at, :error_message, " + ":spm_provenance" + + "".join(f", :{column}" for column in result_columns) + + ")" + ).bindparams(bindparam("spm_provenance", type_=JSONB)), + { + "id": run_ids.report_run_id, + "created_at": created_at, + "report_id": report.report_id, + "baseline_run": run_ids.baseline_simulation_run_id, + "reform_run": run_ids.reform_simulation_run_id, + "status": settings.status, + "started_at": created_at, + "completed_at": ( + created_at + timedelta(minutes=10) if settings.finished else None + ), + "error_message": settings.error_message, + "spm_provenance": spm_provenance, + **settings.versions, + **result_columns, + }, + ) + if stored is not None: + for table, rows in stored.rows.items(): + for row in rows: + insert_row(connection, table, id=uuid4(), **row) + return run_ids + + +def delete_catalog(connection: Connection, catalog: CatalogRows) -> None: + """Delete the reports, simulations, households and catalog rows of ``catalog``. + + A report's runs and results go with it, and a simulation's runs with it. + """ + for report_id in catalog.report_ids: + connection.execute( + text("DELETE FROM reports WHERE id = :id"), {"id": report_id} + ) + for simulation_id in catalog.simulation_ids: + connection.execute( + text("DELETE FROM simulations WHERE id = :id"), {"id": simulation_id} + ) + for household_id in catalog.household_ids: + connection.execute( + text("DELETE FROM households WHERE id = :id"), {"id": household_id} + ) + for table, row_id in ( + ("policies", catalog.policy_id), + ("regions", catalog.region_id), + ("datasets", catalog.dataset_id), + ("tax_benefit_model_versions", catalog.version_id), + ): + connection.execute(text(f"DELETE FROM {table} WHERE id = :id"), {"id": row_id}) + if catalog.created_model: + connection.execute( + text("DELETE FROM tax_benefit_models WHERE id = :id"), + {"id": catalog.model_id}, + ) diff --git a/tests/integration/test_v2_report_creation.py b/tests/integration/test_v2_report_creation.py new file mode 100644 index 000000000..4e5f64807 --- /dev/null +++ b/tests/integration/test_v2_report_creation.py @@ -0,0 +1,331 @@ +"""Create v2 reports and simulations, then read them back from migrated PostgreSQL. + +A stand-in for the simulation service's client stores the rows the +simulation service would create and answers with their IDs; the routes run +as the Public API's runtime role, checking the country and policies and +reading the created records back. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import TYPE_CHECKING, Any +from uuid import UUID, uuid4 + +import pytest +from alembic import command +from alembic.config import Config +from fastapi.testclient import TestClient +from flask import Flask +from sqlalchemy import create_engine +from sqlalchemy.orm import sessionmaker +from sqlalchemy.pool import NullPool +from sqlmodel import Session + +from policyengine_api.asgi_factory import create_asgi_app +from policyengine_api.constants import REPO +from policyengine_api.fastapi_routes.dependencies import NativeRouteDependencies +from policyengine_api.migration_flags import ( + RouteImplementation, + RouteImplementationSettings, +) +from policyengine_api.services.v2.countries.database_session import ( + CountryDatabaseSession, +) +from policyengine_api.services.v2.countries.services import V2CountryService +from policyengine_api.services.v2.policies.database_session import ( + PolicyDatabaseSession, +) +from policyengine_api.services.v2.policies.services import V2PolicyService +from policyengine_api.services.v2.simulation_service.services import ( + SimulationSubmissionService, +) +from policyengine_api.services.v2.simulation_service.types import ( + PackageVersions, + SubmittedReport, + SubmittedSimulation, +) +from policyengine_api.services.v2.stored_reports.database_session import ( + StoredReportDatabaseSession, +) +from policyengine_api.services.v2.stored_reports.services import V2StoredReportService +from policyengine_api.services.v2.stored_simulations.database_session import ( + StoredSimulationDatabaseSession, +) +from policyengine_api.services.v2.stored_simulations.services import ( + V2StoredSimulationService, +) +from tests.integration.stored_report_rows import ( + RunSettings, + delete_catalog, + store_catalog, + store_report, + store_report_run, + store_simulation, + store_simulation_run, +) + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Engine + + from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + ) + from tests.integration.stored_report_rows import CatalogRows + +CURRENT_VERSIONS = {"country_package_version": "1.5.0", "policyengine_version": "4.2.0"} + + +def current_versions(country_id: str) -> PackageVersions: + return PackageVersions(**CURRENT_VERSIONS) + + +@dataclass +class StoringSimulationService: + """Store what the simulation service would create, and answer with its IDs. + + With ``answer_unstored``, it answers with IDs it stored nothing for, and + keeps them in ``unstored_ids``. + """ + + engine: Engine + catalog: CatalogRows + answer_unstored: bool = False + reports: list[EconomyReportCreationInput] = field(default_factory=list) + simulations: list[EconomySimulationCreationInput] = field(default_factory=list) + unstored_ids: list[UUID] = field(default_factory=list) + + def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: + self.reports.append(report) + if self.answer_unstored: + self.unstored_ids.append(uuid4()) + return SubmittedReport( + report_id=self.unstored_ids[-1], report_run_id=uuid4() + ) + with self.engine.begin() as connection: + stored = store_report(connection, self.catalog) + run_ids = store_report_run( + connection, + self.catalog, + stored, + RunSettings(versions=CURRENT_VERSIONS, status="pending"), + ) + return SubmittedReport( + report_id=stored.report_id, report_run_id=run_ids.report_run_id + ) + + def submit_simulation( + self, simulation: EconomySimulationCreationInput + ) -> SubmittedSimulation: + self.simulations.append(simulation) + if self.answer_unstored: + self.unstored_ids.append(uuid4()) + return SubmittedSimulation( + simulation_id=self.unstored_ids[-1], simulation_run_id=uuid4() + ) + with self.engine.begin() as connection: + simulation_id = store_simulation( + connection, self.catalog, policy_id=simulation.policy_id + ) + run_id = store_simulation_run( + connection, + self.catalog, + simulation_id, + RunSettings(versions=CURRENT_VERSIONS, status="pending"), + ) + return SubmittedSimulation( + simulation_id=simulation_id, simulation_run_id=run_id + ) + + +@pytest.fixture +def owner_engine(disposable_v2_database_url: str) -> Iterator[Engine]: + command.upgrade(Config(str(REPO / "alembic-v2.ini")), "head") + engine = create_engine(disposable_v2_database_url, poolclass=NullPool) + yield engine + engine.dispose() + + +@pytest.fixture +def catalog(owner_engine: Engine) -> Iterator[CatalogRows]: + with owner_engine.begin() as connection: + stored = store_catalog(connection, "us") + yield stored + with owner_engine.begin() as connection: + delete_catalog(connection, stored) + + +@pytest.fixture +def runtime_sessions(managed_v2_roles, v2_engine_as_role) -> Iterator[Any]: + engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) + yield sessionmaker(engine, class_=Session) + engine.dispose() + + +def client_for( + sessions: Any, simulation_service: StoringSimulationService +) -> TestClient: + """Serve the routes as the runtime role, creating through ``simulation_service``.""" + submissions = SimulationSubmissionService( + countries=V2CountryService(CountryDatabaseSession(sessions)), + policies=V2PolicyService( + PolicyDatabaseSession(sessions), running_policyengine_version="4.2.0" + ), + client_factory=lambda: simulation_service, + ) + dependencies = NativeRouteDependencies( + readiness_probe=lambda: True, + gateway_client_factory=lambda: None, + metadata_reader_factory=lambda: None, + v2_stored_report_service_factory=lambda: V2StoredReportService( + StoredReportDatabaseSession(sessions), + current_versions=current_versions, + submissions=submissions, + ), + v2_stored_simulation_service_factory=lambda: V2StoredSimulationService( + StoredSimulationDatabaseSession(sessions), + current_versions=current_versions, + submissions=submissions, + ), + ) + settings = RouteImplementationSettings( + health=RouteImplementation.FLASK_FALLBACK, + specification=RouteImplementation.FLASK_FALLBACK, + metadata=RouteImplementation.FLASK_FALLBACK, + ) + return TestClient( + create_asgi_app( + Flask(__name__), dependencies=dependencies, route_settings=settings + ) + ) + + +def report_body(policy_id: UUID) -> dict[str, Any]: + return { + "country_id": "us", + "kind": "economy", + "label": "Expanded child tax credit", + "year": 2026, + "region_code": "state/ca", + "baseline": {}, + "reform": {"policy_id": str(policy_id)}, + "include_cliffs": True, + } + + +def test_a_created_report_is_answered_as_the_tables_hold_it( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + simulation_service = StoringSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/reports?country_id=us", json=report_body(catalog.policy_id) + ) + + assert response.status_code == 201, response.text + item = response.json()["result"]["item"] + assert item["id"] == str(catalog.report_ids[0]) + assert item["status"] == "pending" + assert item["run"]["trigger"] == "initial" + assert item["run"]["policyengine_version"] == "4.2.0" + assert item["result"] is None + assert item["current_versions"] == CURRENT_VERSIONS + (sent,) = simulation_service.reports + assert sent.reform.policy_id == catalog.policy_id + assert sent.include_cliffs is True + + +def test_a_report_naming_a_policy_the_country_does_not_store_is_not_sent( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + simulation_service = StoringSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/reports?country_id=us", json=report_body(uuid4()) + ) + + assert response.status_code == 404 + assert simulation_service.reports == [] + + +def test_a_created_report_that_cannot_be_read_back_answers_its_id( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + # The simulation service answered that it created the report, so the + # record exists: the caller gets its ID and is not invited to submit again. + simulation_service = StoringSimulationService( + owner_engine, catalog, answer_unstored=True + ) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/reports?country_id=us", json=report_body(catalog.policy_id) + ) + + assert response.status_code == 502 + (report_id,) = simulation_service.unstored_ids + assert response.json() == { + "status": "error", + "message": ( + f"The simulation service created report {report_id}, but it could " + f"not be read back. Read it with GET /v2/reports/{report_id}" + "?country_id=us rather than submitting it again." + ), + "report_id": str(report_id), + } + + +def test_a_created_simulation_that_cannot_be_read_back_answers_its_id( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + simulation_service = StoringSimulationService( + owner_engine, catalog, answer_unstored=True + ) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/simulations?country_id=us", + json={ + "country_id": "us", + "kind": "economy", + "year": 2026, + "region_code": "state/ca", + }, + ) + + assert response.status_code == 502 + (simulation_id,) = simulation_service.unstored_ids + assert response.json() == { + "status": "error", + "message": ( + f"The simulation service created simulation {simulation_id}, but it " + f"could not be read back. Read it with GET /v2/simulations/" + f"{simulation_id}?country_id=us rather than submitting it again." + ), + "simulation_id": str(simulation_id), + } + + +def test_a_created_simulation_is_answered_as_the_tables_hold_it( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + simulation_service = StoringSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/simulations?country_id=us", + json={ + "country_id": "us", + "kind": "economy", + "year": 2026, + "region_code": "state/ca", + "policy_id": str(catalog.policy_id), + }, + ) + + assert response.status_code == 201, response.text + item = response.json()["result"]["item"] + assert item["id"] == str(catalog.simulation_ids[0]) + assert item["policy_id"] == str(catalog.policy_id) + assert item["status"] == "pending" + assert item["run"]["country_package_version"] == "1.5.0" diff --git a/tests/integration/test_v2_report_reads.py b/tests/integration/test_v2_report_reads.py new file mode 100644 index 000000000..457dcf37e --- /dev/null +++ b/tests/integration/test_v2_report_reads.py @@ -0,0 +1,491 @@ +"""Read v2 reports, their results and simulations from migrated PostgreSQL. + +The routes run as the Public API's runtime role, so the tests prove the +role's declared privileges cover every read (rule +``api.v2.runtime-privileges-tested-as-runtime-role``). The rows are stored as +the simulation service and its Modal workers store them, committed, and +deleted after each test. +""" + +from __future__ import annotations + +import json +from datetime import timedelta +from typing import TYPE_CHECKING, Any +from uuid import UUID, uuid4 + +import pytest +from alembic import command +from alembic.config import Config +from fastapi.testclient import TestClient +from flask import Flask +from sqlalchemy import create_engine +from sqlalchemy.orm import sessionmaker +from sqlalchemy.pool import NullPool +from sqlmodel import Session + +from policyengine_api.asgi_factory import create_asgi_app +from policyengine_api.constants import REPO +from policyengine_api.fastapi_routes.dependencies import NativeRouteDependencies +from policyengine_api.migration_flags import ( + RouteImplementation, + RouteImplementationSettings, +) +from policyengine_api.services.v2.simulation_service.types import PackageVersions +from policyengine_api.services.v2.stored_reports.database_session import ( + StoredReportDatabaseSession, +) +from policyengine_api.services.v2.stored_reports.services import V2StoredReportService +from policyengine_api.services.v2.stored_simulations.database_session import ( + StoredSimulationDatabaseSession, +) +from policyengine_api.services.v2.stored_simulations.services import ( + V2StoredSimulationService, +) +from tests.fixtures.economy_results import uk_economy_result, us_economy_result +from tests.integration.simulation_rows import insert_row +from tests.integration.stored_report_rows import ( + REGION_CODES, + STARTED_AT, + RunSettings, + delete_catalog, + store_catalog, + store_report, + store_report_run, + store_simulation, + store_simulation_run, +) + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Engine + + from tests.integration.stored_report_rows import CatalogRows + +CURRENT_VERSIONS = {"country_package_version": "1.5.0", "policyengine_version": "4.2.0"} +OLDER_VERSIONS = {"country_package_version": "1.4.0", "policyengine_version": "4.1.0"} +# Two run IDs: of two runs created at the same time, the one with the larger +# ID is the newest, whichever was stored first. +LARGER_RUN_ID = UUID("ffffffff-0000-4000-8000-000000000001") +SMALLER_RUN_ID = UUID("00000000-0000-4000-8000-000000000001") + + +def current_versions(country_id: str) -> PackageVersions: + return PackageVersions(**CURRENT_VERSIONS) + + +@pytest.fixture +def owner_engine(disposable_v2_database_url: str) -> Iterator[Engine]: + command.upgrade(Config(str(REPO / "alembic-v2.ini")), "head") + engine = create_engine(disposable_v2_database_url, poolclass=NullPool) + yield engine + engine.dispose() + + +@pytest.fixture +def catalogs(owner_engine: Engine) -> Iterator[dict[str, CatalogRows]]: + """Store a US and a UK catalog, and delete them and their reports after.""" + with owner_engine.begin() as connection: + stored = { + country: store_catalog(connection, country) for country in ("us", "uk") + } + yield stored + with owner_engine.begin() as connection: + for catalog in stored.values(): + delete_catalog(connection, catalog) + + +@pytest.fixture +def client(managed_v2_roles, v2_engine_as_role) -> Iterator[TestClient]: + """Serve the report and simulation routes as the runtime role.""" + runtime_engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) + sessions = sessionmaker(runtime_engine, class_=Session) + dependencies = NativeRouteDependencies( + readiness_probe=lambda: True, + gateway_client_factory=lambda: None, + metadata_reader_factory=lambda: None, + v2_stored_report_service_factory=lambda: V2StoredReportService( + StoredReportDatabaseSession(sessions), current_versions=current_versions + ), + v2_stored_simulation_service_factory=lambda: V2StoredSimulationService( + StoredSimulationDatabaseSession(sessions), + current_versions=current_versions, + ), + ) + settings = RouteImplementationSettings( + health=RouteImplementation.FLASK_FALLBACK, + specification=RouteImplementation.FLASK_FALLBACK, + metadata=RouteImplementation.FLASK_FALLBACK, + ) + yield TestClient( + create_asgi_app( + Flask(__name__), dependencies=dependencies, route_settings=settings + ) + ) + runtime_engine.dispose() + + +def _as_json(value: Any) -> Any: + return json.loads(json.dumps(value)) + + +@pytest.mark.parametrize( + ("country", "output"), + [("us", us_economy_result()), ("uk", uk_economy_result())], + ids=["us", "uk"], +) +def test_a_report_reads_its_newest_run_and_that_runs_result( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + client: TestClient, + country: str, + output: dict[str, Any], +) -> None: + catalog = catalogs[country] + older_output = json.loads(json.dumps(output)) + older_output["budget"]["tax_revenue_impact"] = 1.0 + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + store_report_run( + connection, + catalog, + report, + RunSettings(versions=OLDER_VERSIONS), + result=older_output, + ) + newest = store_report_run( + connection, + catalog, + report, + RunSettings( + versions=OLDER_VERSIONS, created_at=STARTED_AT + timedelta(days=1) + ), + result=output, + ) + + response = client.get(f"/v2/reports/{report.report_id}?country_id={country}") + + assert response.status_code == 200, response.text + item = response.json()["result"]["item"] + # A result's model version is the country package version its run used. + expected = _as_json(output) + expected["model_version"] = OLDER_VERSIONS["country_package_version"] + assert item["result"] == expected + assert item["status"] == "succeeded" + assert item["run"]["id"] == str(newest.report_run_id) + assert item["run"]["country_package_version"] == "1.4.0" + assert item["run"]["policyengine_version"] == "4.1.0" + assert item["run"]["baseline_simulation_run_id"] == str( + newest.baseline_simulation_run_id + ) + assert item["current_versions"] == CURRENT_VERSIONS + assert item["region_code"] == REGION_CODES[country] + assert item["baseline_simulation"] == { + "id": str(report.baseline_simulation_id), + "policy_id": None, + "dynamic_id": None, + } + assert item["reform_simulation"]["policy_id"] == str(catalog.policy_id) + assert item["options"] == {"include_cliffs": True} + assert item["kind"] == "economy" + + +def test_a_newest_run_still_running_has_no_result_even_after_an_older_success( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + store_report_run( + connection, + catalog, + report, + RunSettings(versions=OLDER_VERSIONS), + result=us_economy_result(), + ) + store_report_run( + connection, + catalog, + report, + RunSettings( + versions=CURRENT_VERSIONS, + status="running", + created_at=STARTED_AT + timedelta(days=1), + ), + ) + + item = client.get(f"/v2/reports/{report.report_id}?country_id=us").json()["result"][ + "item" + ] + + assert item["status"] == "running" + assert item["run"]["completed_at"] is None + assert item["result"] is None + + +def test_a_failed_newest_run_says_why_without_a_result( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + store_report_run( + connection, + catalog, + report, + RunSettings( + versions=CURRENT_VERSIONS, + status="failed", + error_message="simulation_failed: the worker ran out of memory", + ), + ) + + item = client.get(f"/v2/reports/{report.report_id}?country_id=us").json()["result"][ + "item" + ] + + assert item["status"] == "failed" + assert item["run"]["error_message"] == ( + "simulation_failed: the worker ran out of memory" + ) + assert item["result"] is None + + +def test_a_report_with_no_run_answers_its_definition( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["uk"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + + response = client.get(f"/v2/reports/{report.report_id}?country_id=uk") + + assert response.status_code == 200 + item = response.json()["result"]["item"] + assert item["status"] == "not_run" + assert item["run"] is None + assert item["result"] is None + assert item["label"] == "uk reform" + assert item["year"] == 2026 + assert item["dataset_name"] == "enhanced_frs_2023_24" + + +def test_a_report_is_not_found_in_another_country( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + + response = client.get(f"/v2/reports/{report.report_id}?country_id=uk") + + assert response.status_code == 404 + assert response.json()["status"] == "error" + + +def test_a_succeeded_run_without_result_rows_is_unreadable( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + store_report_run( + connection, catalog, report, RunSettings(versions=CURRENT_VERSIONS) + ) + + response = client.get(f"/v2/reports/{report.report_id}?country_id=us") + + assert response.status_code == 500 + assert response.json() == { + "status": "error", + "message": "The report's stored result cannot be read", + } + + +def test_a_household_report_cannot_be_read_here_yet( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + household_id = uuid4() + with owner_engine.begin() as connection: + insert_row( + connection, + "households", + id=household_id, + country_id="us", + household_data="{}", + canonicalization_version=1, + content_hash=uuid4().hex * 2, + ) + catalog.household_ids.append(household_id) + report = store_report(connection, catalog, household_id=household_id) + + response = client.get(f"/v2/reports/{report.report_id}?country_id=us") + + assert response.status_code == 422 + assert "household report" in response.json()["message"] + + +def test_listing_reads_named_economy_reports_in_the_order_asked( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + first = store_report(connection, catalog) + store_report_run( + connection, + catalog, + first, + RunSettings(versions=CURRENT_VERSIONS), + result=us_economy_result(), + ) + second = store_report(connection, catalog) + budget_window = store_report(connection, catalog, budget_window_size=3) + other_country = store_report(connection, catalogs["uk"]) + named = ( + second.report_id, + uuid4(), + first.report_id, + budget_window.report_id, + other_country.report_id, + second.report_id, + ) + + response = client.get( + "/v2/reports?country_id=us&" + + "&".join(f"report_id={report_id}" for report_id in named) + ) + + assert response.status_code == 200, response.text + items = response.json()["result"]["items"] + assert [item["id"] for item in items] == [ + str(second.report_id), + str(first.report_id), + ] + assert [item["status"] for item in items] == ["not_run", "succeeded"] + assert all("result" not in item for item in items) + assert items[1]["run"]["country_package_version"] == "1.5.0" + + +def test_a_simulation_reads_its_newest_run_in_its_country( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["uk"] + with owner_engine.begin() as connection: + simulation_id = store_simulation( + connection, catalog, policy_id=catalog.policy_id + ) + store_simulation_run( + connection, catalog, simulation_id, RunSettings(versions=OLDER_VERSIONS) + ) + newest_run_id = store_simulation_run( + connection, + catalog, + simulation_id, + RunSettings( + versions=CURRENT_VERSIONS, + status="pending", + created_at=STARTED_AT + timedelta(hours=1), + ), + ) + + response = client.get(f"/v2/simulations/{simulation_id}?country_id=uk") + elsewhere = client.get(f"/v2/simulations/{simulation_id}?country_id=us") + + assert response.status_code == 200, response.text + item = response.json()["result"]["item"] + assert item["id"] == str(simulation_id) + assert item["country_id"] == "uk" + assert item["kind"] == "economy" + assert item["policy_id"] == str(catalog.policy_id) + assert item["region_code"] == "country/wales" + assert item["dataset_name"] == "enhanced_frs_2023_24" + assert item["status"] == "pending" + assert item["run"]["id"] == str(newest_run_id) + assert item["run"]["policyengine_version"] == "4.2.0" + assert item["current_versions"] == CURRENT_VERSIONS + assert elsewhere.status_code == 404 + + +def test_a_simulation_with_no_run_answers_its_definition( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + simulation_id = store_simulation(connection, catalog, policy_id=None) + + item = client.get(f"/v2/simulations/{simulation_id}?country_id=us").json()[ + "result" + ]["item"] + + assert item["status"] == "not_run" + assert item["run"] is None + assert item["policy_id"] is None + assert item["year"] == 2026 + + +def test_of_two_report_runs_created_together_the_larger_id_is_the_newest( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + store_report_run( + connection, + catalog, + report, + RunSettings( + versions=CURRENT_VERSIONS, + status="failed", + error_message="The worker stopped", + run_id=LARGER_RUN_ID, + ), + ) + store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS, run_id=SMALLER_RUN_ID), + result=us_economy_result(), + ) + + read = client.get(f"/v2/reports/{report.report_id}?country_id=us") + listed = client.get(f"/v2/reports?country_id=us&report_id={report.report_id}") + + assert read.status_code == 200, read.text + item = read.json()["result"]["item"] + assert item["run"]["id"] == str(LARGER_RUN_ID) + assert item["status"] == "failed" + assert item["result"] is None + assert listed.status_code == 200, listed.text + (summary,) = listed.json()["result"]["items"] + assert summary["run"]["id"] == str(LARGER_RUN_ID) + + +def test_of_two_simulation_runs_created_together_the_larger_id_is_the_newest( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + simulation_id = store_simulation(connection, catalog, policy_id=None) + store_simulation_run( + connection, + catalog, + simulation_id, + RunSettings( + versions=CURRENT_VERSIONS, status="pending", run_id=LARGER_RUN_ID + ), + ) + store_simulation_run( + connection, + catalog, + simulation_id, + RunSettings(versions=OLDER_VERSIONS, run_id=SMALLER_RUN_ID), + ) + + response = client.get(f"/v2/simulations/{simulation_id}?country_id=us") + + assert response.status_code == 200, response.text + item = response.json()["result"]["item"] + assert item["run"]["id"] == str(LARGER_RUN_ID) + assert item["status"] == "pending" diff --git a/tests/integration/test_v2_saved_detailed_save_records.py b/tests/integration/test_v2_saved_detailed_save_records.py new file mode 100644 index 000000000..f73b63abc --- /dev/null +++ b/tests/integration/test_v2_saved_detailed_save_records.py @@ -0,0 +1,477 @@ +"""Save detailed-save reports and simulations in migrated PostgreSQL. + +The saved-record services run as the Public API's runtime role. A saved +report or simulation names a stored record of its country, checked with a +SELECT in the write's own transaction; the database's ``RESTRICT`` foreign +keys refuse one deleted between the check and the write, which is answered +as not found too. A request naming both a detailed-save ID and a v1 number +is refused. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING +from uuid import uuid4 + +import pytest +from alembic import command +from alembic.config import Config +from sqlalchemy import create_engine, delete +from sqlalchemy.orm import sessionmaker +from sqlalchemy.pool import NullPool +from sqlmodel import Session + +from policyengine_api.constants import REPO +from policyengine_api.data.v2.models import User +from policyengine_api.services.v2.associations.validators import ( + AssociationReferenceConflictError, +) +from policyengine_api.services.v2.identity.types import UnauthenticatedPrincipal +from policyengine_api.services.v2.user_reports import services as report_services +from policyengine_api.services.v2.user_reports.database_session import ( + UserReportDatabaseSession, +) +from policyengine_api.services.v2.user_reports.services import V2UserReportService +from policyengine_api.services.v2.user_reports.types import ( + UserReportCreateFields, + UserReportUpdateInput, +) +from policyengine_api.services.v2.user_reports.validators import ( + AssociationReportNotFoundError, +) +from policyengine_api.services.v2.user_simulations import ( + services as simulation_services, +) +from policyengine_api.services.v2.user_simulations.database_session import ( + UserSimulationDatabaseSession, +) +from policyengine_api.services.v2.user_simulations.services import ( + V2UserSimulationService, +) +from policyengine_api.services.v2.user_simulations.types import ( + UserSimulationCreateFields, + UserSimulationUpdateInput, +) +from policyengine_api.services.v2.user_simulations.validators import ( + AssociationSimulationNotFoundError, +) +from tests.integration.stored_report_rows import ( + delete_catalog, + store_catalog, + store_report, + store_simulation, +) +from tests.unit.v2.user_service_support import default_legacy_references + +if TYPE_CHECKING: + from collections.abc import Iterator + from uuid import UUID + + from sqlalchemy import Engine + + from tests.integration.stored_report_rows import CatalogRows + + +@pytest.fixture +def owner_engine(disposable_v2_database_url: str) -> Iterator[Engine]: + command.upgrade(Config(str(REPO / "alembic-v2.ini")), "head") + engine = create_engine(disposable_v2_database_url, poolclass=NullPool) + yield engine + engine.dispose() + + +@pytest.fixture +def browsers(owner_engine: Engine) -> Iterator[list[UUID]]: + """Signed-out browsers' user IDs; their users and saved records go afterwards.""" + user_ids: list[UUID] = [] + yield user_ids + with owner_engine.begin() as connection: + connection.execute(delete(User).where(User.id.in_(user_ids))) + + +@pytest.fixture +def catalogs( + owner_engine: Engine, browsers: list[UUID] +) -> Iterator[dict[str, CatalogRows]]: + """Store a US and a UK catalog; delete them after the records that name them.""" + with owner_engine.begin() as connection: + stored = { + country: store_catalog(connection, country) for country in ("us", "uk") + } + yield stored + with owner_engine.begin() as connection: + connection.execute(delete(User).where(User.id.in_(browsers))) + for catalog in stored.values(): + delete_catalog(connection, catalog) + + +@pytest.fixture +def runtime_sessions(managed_v2_roles, v2_engine_as_role) -> Iterator[sessionmaker]: + engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) + yield sessionmaker(engine, class_=Session, expire_on_commit=False) + engine.dispose() + + +def browser(browsers: list[UUID]) -> UnauthenticatedPrincipal: + user_id = uuid4() + browsers.append(user_id) + return UnauthenticatedPrincipal(user_id=user_id) + + +def report_service(sessions: sessionmaker) -> V2UserReportService: + return V2UserReportService( + UserReportDatabaseSession(sessions), default_legacy_references() + ) + + +def simulation_service(sessions: sessionmaker) -> V2UserSimulationService: + return V2UserSimulationService( + UserSimulationDatabaseSession(sessions), default_legacy_references() + ) + + +def test_a_saved_report_names_a_stored_report_of_its_country( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + service = report_service(runtime_sessions) + + saved = service.create_user_report( + principal=browser(browsers), + association_input=UserReportCreateFields( + country_id="us", report_id=report.report_id, name="My reform" + ), + ) + shared = service.get_shared_user_report(country_id="us", association_id=saved.id) + + assert saved.report_id == report.report_id + assert saved.legacy_report_id is None + assert shared.report_id == report.report_id + + +def test_a_saved_report_naming_a_missing_or_foreign_report_is_not_found( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + uk_report = store_report(connection, catalogs["uk"]) + service = report_service(runtime_sessions) + principal = browser(browsers) + + for report_id in (uuid4(), uk_report.report_id): + with pytest.raises(AssociationReportNotFoundError, match=str(report_id)): + service.create_user_report( + principal=principal, + association_input=UserReportCreateFields( + country_id="us", report_id=report_id + ), + ) + + +def test_a_saved_report_naming_both_references_is_refused( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + + with pytest.raises(AssociationReferenceConflictError, match="not both"): + report_service(runtime_sessions).create_user_report( + principal=browser(browsers), + association_input=UserReportCreateFields( + country_id="us", report_id=report.report_id, legacy_report_id=615 + ), + ) + + +def test_a_saved_report_cannot_come_to_name_both_references( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + service = report_service(runtime_sessions) + principal = browser(browsers) + by_number = service.create_user_report( + principal=principal, + association_input=UserReportCreateFields(country_id="us", legacy_report_id=615), + ) + by_report = service.create_user_report( + principal=principal, + association_input=UserReportCreateFields( + country_id="us", report_id=report.report_id + ), + ) + + for association_id, change in ( + (by_number.id, {"report_id": report.report_id}), + (by_report.id, {"legacy_report_id": 616}), + (by_report.id, {"report_id": report.report_id, "legacy_report_id": 616}), + ): + with pytest.raises(AssociationReferenceConflictError, match="not both"): + service.patch_user_report( + principal=principal, + country_id="us", + association_id=association_id, + association_input=UserReportUpdateInput(**change), + ) + + +def test_a_saved_report_is_repointed_only_to_a_stored_report( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + first = store_report(connection, catalogs["us"]) + second = store_report(connection, catalogs["us"]) + service = report_service(runtime_sessions) + principal = browser(browsers) + saved = service.create_user_report( + principal=principal, + association_input=UserReportCreateFields( + country_id="us", report_id=first.report_id + ), + ) + + repointed = service.patch_user_report( + principal=principal, + country_id="us", + association_id=saved.id, + association_input=UserReportUpdateInput(report_id=second.report_id), + ) + with pytest.raises(AssociationReportNotFoundError): + service.patch_user_report( + principal=principal, + country_id="us", + association_id=saved.id, + association_input=UserReportUpdateInput(report_id=uuid4()), + ) + + assert repointed.report_id == second.report_id + + +def test_a_report_gone_after_the_check_is_refused_by_its_foreign_key( + monkeypatch: pytest.MonkeyPatch, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + # As if the report were deleted between the check and the insert. + monkeypatch.setattr( + report_services, "read_report_exists", lambda *_args, **_kwargs: True + ) + missing_report_id = uuid4() + + with pytest.raises(AssociationReportNotFoundError, match=str(missing_report_id)): + report_service(runtime_sessions).create_user_report( + principal=browser(browsers), + association_input=UserReportCreateFields( + country_id="us", report_id=missing_report_id + ), + ) + + +def test_a_report_gone_before_a_repoint_is_refused_by_its_foreign_key( + monkeypatch: pytest.MonkeyPatch, + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + service = report_service(runtime_sessions) + principal = browser(browsers) + saved = service.create_user_report( + principal=principal, + association_input=UserReportCreateFields( + country_id="us", report_id=report.report_id + ), + ) + # As if the new report were deleted between the check and the update. + monkeypatch.setattr( + report_services, "read_report_exists", lambda *_args, **_kwargs: True + ) + missing_report_id = uuid4() + + with pytest.raises( + AssociationReportNotFoundError, + match=f"Report {missing_report_id} was not found in country 'us'", + ): + service.patch_user_report( + principal=principal, + country_id="us", + association_id=saved.id, + association_input=UserReportUpdateInput(report_id=missing_report_id), + ) + assert ( + service.get_shared_user_report(country_id="us", association_id=saved.id) + ).report_id == report.report_id + + +def test_a_saved_simulation_names_a_stored_simulation_of_its_country( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + simulation_id = store_simulation(connection, catalogs["uk"], policy_id=None) + other_simulation_id = store_simulation( + connection, catalogs["uk"], policy_id=None + ) + service = simulation_service(runtime_sessions) + principal = browser(browsers) + + saved = service.create_user_simulation( + principal=principal, + association_input=UserSimulationCreateFields( + country_id="uk", simulation_id=simulation_id + ), + ) + repointed = service.patch_user_simulation( + principal=principal, + country_id="uk", + association_id=saved.id, + association_input=UserSimulationUpdateInput(simulation_id=other_simulation_id), + ) + + assert saved.simulation_id == simulation_id + assert saved.legacy_simulation_id is None + assert repointed.simulation_id == other_simulation_id + + +def test_a_saved_simulation_of_another_country_or_none_is_not_found( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + uk_simulation_id = store_simulation(connection, catalogs["uk"], policy_id=None) + service = simulation_service(runtime_sessions) + principal = browser(browsers) + + for simulation_id in (uuid4(), uk_simulation_id): + with pytest.raises( + AssociationSimulationNotFoundError, match=str(simulation_id) + ): + service.create_user_simulation( + principal=principal, + association_input=UserSimulationCreateFields( + country_id="us", simulation_id=simulation_id + ), + ) + + +def test_a_saved_simulation_never_names_both_references( + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + simulation_id = store_simulation(connection, catalogs["us"], policy_id=None) + service = simulation_service(runtime_sessions) + principal = browser(browsers) + by_number = service.create_user_simulation( + principal=principal, + association_input=UserSimulationCreateFields( + country_id="us", legacy_simulation_id=613 + ), + ) + + with pytest.raises(AssociationReferenceConflictError, match="not both"): + service.create_user_simulation( + principal=principal, + association_input=UserSimulationCreateFields( + country_id="us", simulation_id=simulation_id, legacy_simulation_id=613 + ), + ) + with pytest.raises(AssociationReferenceConflictError, match="not both"): + service.patch_user_simulation( + principal=principal, + country_id="us", + association_id=by_number.id, + association_input=UserSimulationUpdateInput(simulation_id=simulation_id), + ) + + +def test_a_simulation_gone_after_the_check_is_refused_by_its_foreign_key( + monkeypatch: pytest.MonkeyPatch, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + monkeypatch.setattr( + simulation_services, + "read_simulation_exists", + lambda *_args, **_kwargs: True, + ) + missing_simulation_id = uuid4() + + with pytest.raises( + AssociationSimulationNotFoundError, match=str(missing_simulation_id) + ): + simulation_service(runtime_sessions).create_user_simulation( + principal=browser(browsers), + association_input=UserSimulationCreateFields( + country_id="us", simulation_id=missing_simulation_id + ), + ) + + +def test_a_simulation_gone_before_a_repoint_is_refused_by_its_foreign_key( + monkeypatch: pytest.MonkeyPatch, + owner_engine: Engine, + catalogs: dict[str, CatalogRows], + browsers: list[UUID], + runtime_sessions: sessionmaker, +) -> None: + with owner_engine.begin() as connection: + simulation_id = store_simulation(connection, catalogs["uk"], policy_id=None) + service = simulation_service(runtime_sessions) + principal = browser(browsers) + saved = service.create_user_simulation( + principal=principal, + association_input=UserSimulationCreateFields( + country_id="uk", simulation_id=simulation_id + ), + ) + # As if the new simulation were deleted between the check and the update. + monkeypatch.setattr( + simulation_services, + "read_simulation_exists", + lambda *_args, **_kwargs: True, + ) + missing_simulation_id = uuid4() + + with pytest.raises( + AssociationSimulationNotFoundError, + match=f"Simulation {missing_simulation_id} was not found in country 'uk'", + ): + service.patch_user_simulation( + principal=principal, + country_id="uk", + association_id=saved.id, + association_input=UserSimulationUpdateInput( + simulation_id=missing_simulation_id + ), + ) + assert ( + service.get_user_simulation( + principal=principal, country_id="uk", association_id=saved.id + ) + ).simulation_id == simulation_id diff --git a/tests/unit/libs/test_simulation_household_calculations.py b/tests/unit/libs/test_simulation_household_calculations.py index c343a2f9a..502e70f55 100644 --- a/tests/unit/libs/test_simulation_household_calculations.py +++ b/tests/unit/libs/test_simulation_household_calculations.py @@ -14,12 +14,14 @@ from policyengine_api.libs.gateway_auth import GatewayAuthError from policyengine_api.libs.simulation_household_calculations import ( HOUSEHOLD_CALCULATIONS_PATH, - SimulationAnswer, SimulationHouseholdCalculationClient, ) +from policyengine_api.libs.simulation_service_answers import SimulationAnswer from policyengine_api.request_context import _asgi_observability_id from policyengine_api.services.v2.household_calculations.types import ( HouseholdCalculationAccepted, +) +from policyengine_api.services.v2.simulation_service.types import ( SimulationServiceAnswerUnreadableError, SimulationServiceInternalError, SimulationServiceInvalidRequestError, diff --git a/tests/unit/libs/test_simulation_reports.py b/tests/unit/libs/test_simulation_reports.py new file mode 100644 index 000000000..6a1ff57ab --- /dev/null +++ b/tests/unit/libs/test_simulation_reports.py @@ -0,0 +1,784 @@ +"""Create simulations and reports through the simulation service; read its answers.""" + +from __future__ import annotations + +import json +from typing import Any +from uuid import UUID + +import httpx +import pytest + +from policyengine_api.fastapi_routes.v2.reports.routes import REPORT_ERROR_MAPPINGS +from policyengine_api.fastapi_routes.v2.simulations.routes import ( + SIMULATION_ERROR_MAPPINGS, +) +from policyengine_api.libs.gateway_auth import GatewayAuthError +from policyengine_api.libs.simulation_reports import ( + REPORTS_PATH, + SIMULATIONS_PATH, + SimulationServiceReportClient, +) +from policyengine_api.libs.simulation_service_answers import SimulationAnswer +from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + SimulationServiceAnswerUnreadableError, + SimulationServiceInternalError, + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, + SubmittedReport, + SubmittedSimulation, +) +from policyengine_api.spm import SPMSelection +from tests.unit.v2.simulation_service_messages import ( + answer_lost_message, + possibly_created_message, +) + +SIMULATION_URL = "https://simulation.example.test" +ENVIRONMENT_VARIABLES = ( + "GATEWAY_AUTH_ISSUER", + "GATEWAY_AUTH_AUDIENCE", + "GATEWAY_AUTH_CLIENT_ID", + "GATEWAY_AUTH_CLIENT_SECRET", + "GATEWAY_AUTH_CLIENT_SECRET_RESOURCE", + "GATEWAY_AUTH_REQUIRED", + "SIM_ENTRYPOINT", + "OLD_SIMULATION_GATEWAY_URL", + "SIMULATION_ENTRYPOINT_URL", +) +REPORT_ID = UUID("00000000-0000-0000-0000-00000000b001") +REPORT_RUN_ID = UUID("00000000-0000-0000-0000-00000000b002") +SIMULATION_ID = UUID("00000000-0000-0000-0000-00000000b003") +SIMULATION_RUN_ID = UUID("00000000-0000-0000-0000-00000000b004") +POLICY_ID = UUID("00000000-0000-0000-0000-00000000b005") +DYNAMIC_ID = UUID("00000000-0000-0000-0000-00000000b006") +REPORT_CREATED = { + "report_id": str(REPORT_ID), + "report_run_id": str(REPORT_RUN_ID), + "status": "pending", +} +SIMULATION_CREATED = { + "simulation_id": str(SIMULATION_ID), + "simulation_run_id": str(SIMULATION_RUN_ID), + "status": "pending", +} + + +@pytest.fixture(autouse=True) +def configured_simulation_service(monkeypatch): + """Name the Cloud Run simulation service; set no gateway credentials.""" + for name in ENVIRONMENT_VARIABLES: + monkeypatch.delenv(name, raising=False) + monkeypatch.setenv("SIMULATION_ENTRYPOINT_URL", f"{SIMULATION_URL}/") + # The report routes exist only on the Cloud Run simulation service, + # whatever the v1 economy routes select. + monkeypatch.setenv("SIM_ENTRYPOINT", "old_gateway_direct") + monkeypatch.setenv("OLD_SIMULATION_GATEWAY_URL", "https://old.example.test") + + +def report_input(**changes: Any) -> EconomyReportCreationInput: + values: dict[str, Any] = { + "country_id": "us", + "kind": "economy", + "label": "Expanded child tax credit", + "year": 2026, + "region_code": "state/ca", + "baseline": {}, + "reform": {"policy_id": str(POLICY_ID)}, + } + return EconomyReportCreationInput.model_validate({**values, **changes}) + + +def simulation_input(**changes: Any) -> EconomySimulationCreationInput: + values: dict[str, Any] = { + "country_id": "uk", + "kind": "economy", + "year": 2027, + "region_code": "country/wales", + "policy_id": str(POLICY_ID), + } + return EconomySimulationCreationInput.model_validate({**values, **changes}) + + +def _report_route_status(error: Exception) -> int: + """Return the status the report route answers ``error`` with.""" + return next( + mapping.status_code + for mapping in REPORT_ERROR_MAPPINGS + if isinstance(error, mapping.error_types) + ) + + +def _simulation_route_status(error: Exception) -> int: + """Return the status the simulation route answers ``error`` with.""" + return next( + mapping.status_code + for mapping in SIMULATION_ERROR_MAPPINGS + if isinstance(error, mapping.error_types) + ) + + +def submit_report(client: SimulationServiceReportClient) -> object: + return client.submit_report(report_input()) + + +def submit_simulation(client: SimulationServiceReportClient) -> object: + return client.submit_simulation(simulation_input()) + + +# The field naming each record in the simulation service's answers, and the +# record's ID in these tests. +CREATED_RECORD_IDS = { + "report": ("report_id", REPORT_ID), + "simulation": ("simulation_id", SIMULATION_ID), +} +# The field and ID of a record other than the submission's own. +OTHER_RECORD_IDS = { + "report": ("simulation_id", SIMULATION_ID), + "simulation": ("report_id", REPORT_ID), +} + + +# Each submission, the record it creates and the status its route answers with. +SUBMISSIONS = [ + pytest.param(submit_report, "report", _report_route_status, id="report"), + pytest.param( + submit_simulation, "simulation", _simulation_route_status, id="simulation" + ), +] + + +class RecordingService: + """The simulation service, answering every request with one scripted answer.""" + + def __init__(self, status_code: int = 201, body: object = REPORT_CREATED) -> None: + self.status_code = status_code + self.body = body + self.requests: list[httpx.Request] = [] + + def answer(self, request: httpx.Request) -> httpx.Response: + self.requests.append(request) + if isinstance(self.body, bytes): + return httpx.Response(self.status_code, content=self.body) + return httpx.Response(self.status_code, json=self.body) + + def client(self) -> SimulationServiceReportClient: + return SimulationServiceReportClient.from_environment( + transport=httpx.MockTransport(self.answer) + ) + + def sent_body(self) -> dict[str, object]: + (request,) = self.requests + return json.loads(request.content) + + +def test_a_report_is_posted_and_the_created_report_returned() -> None: + service = RecordingService() + + submitted = service.client().submit_report(report_input()) + + assert submitted == SubmittedReport( + report_id=REPORT_ID, report_run_id=REPORT_RUN_ID + ) + (request,) = service.requests + assert request.method == "POST" + assert str(request.url) == f"{SIMULATION_URL}{REPORTS_PATH}" + assert service.sent_body() == { + "country": "us", + "report_type": "economy", + "label": "Expanded child tax credit", + "description": None, + "year": 2026, + "region_code": "state/ca", + "dataset_name": None, + "baseline": {"policy_id": None, "dynamic_id": None}, + "reform": {"policy_id": str(POLICY_ID), "dynamic_id": None}, + "include_cliffs": False, + } + + +def test_a_report_sends_its_options_and_spm_settings_only_when_given() -> None: + service = RecordingService() + + service.client().submit_report( + report_input( + include_cliffs=True, + dataset_name="enhanced_cps_2024", + description="Doubles the credit", + reform={"policy_id": str(POLICY_ID), "dynamic_id": str(DYNAMIC_ID)}, + spm={"geography_kind": "national"}, + ) + ) + + body = service.sent_body() + assert body["include_cliffs"] is True + assert body["dataset_name"] == "enhanced_cps_2024" + assert body["description"] == "Doubles the credit" + assert body["reform"] == { + "policy_id": str(POLICY_ID), + "dynamic_id": str(DYNAMIC_ID), + } + assert body["spm"] == SPMSelection(geography_kind="national").model_dump( + mode="json" + ) + + +def test_a_simulation_is_posted_and_the_created_simulation_returned() -> None: + service = RecordingService(status_code=202, body=SIMULATION_CREATED) + + submitted = service.client().submit_simulation(simulation_input()) + + assert submitted == SubmittedSimulation( + simulation_id=SIMULATION_ID, simulation_run_id=SIMULATION_RUN_ID + ) + (request,) = service.requests + assert str(request.url) == f"{SIMULATION_URL}{SIMULATIONS_PATH}" + assert service.sent_body() == { + "country": "uk", + "simulation_type": "economy", + "year": 2027, + "region_code": "country/wales", + "dataset_name": None, + "policy_id": str(POLICY_ID), + "dynamic_id": None, + } + + +def test_an_answer_with_fields_the_public_api_does_not_read_is_accepted() -> None: + service = RecordingService(body={**REPORT_CREATED, "modal_call_id": "fc-1"}) + + assert service.client().submit_report(report_input()).report_id == REPORT_ID + + +def test_data_the_service_refuses_is_reported_with_its_reason() -> None: + service = RecordingService( + status_code=422, body={"detail": "spm settings apply only to the US"} + ) + + with pytest.raises(SimulationServiceInvalidRequestError) as refused: + service.client().submit_report(report_input()) + + assert str(refused.value) == ( + "The simulation service cannot run this request: " + "spm settings apply only to the US" + ) + + +def test_request_fields_the_service_refuses_are_reported_one_by_one() -> None: + service = RecordingService( + status_code=422, + body={ + "detail": [ + {"loc": ["body", "year"], "msg": "too late", "type": "value_error"}, + {"loc": ["body", "reform", "policy_id"], "msg": "bad", "type": "x"}, + ] + }, + ) + + with pytest.raises(SimulationServiceInvalidRequestError) as refused: + service.client().submit_report(report_input()) + + assert str(refused.value) == ( + "The simulation service cannot run this request: " + "year: too late; reform.policy_id: bad" + ) + + +def test_a_refusal_names_the_services_code_when_it_gives_one() -> None: + service = RecordingService( + status_code=422, + body={ + "code": "spm_unsupported", + "detail": "spm settings apply only to the US", + }, + ) + + with pytest.raises(SimulationServiceInvalidRequestError) as refused: + service.client().submit_report(report_input()) + + assert str(refused.value) == ( + "The simulation service cannot run this request (spm_unsupported): " + "spm settings apply only to the US" + ) + + +@pytest.mark.parametrize( + ("code", "reason"), + [ + ("unknown_region", "Region state/zz is not in the catalog version."), + ("unknown_dataset", "Dataset cps_1999 is not in the catalog version."), + ("unknown_dynamic", f"Dynamic {DYNAMIC_ID} is not stored in the country."), + ], + ids=["region", "dataset", "dynamic"], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_row_the_caller_named_that_the_service_cannot_find_is_refused( + submit, record: str, route_status, code: str, reason: str +) -> None: + # The Public API does not check regions, datasets or dynamics: the caller + # named one the simulation service's catalog version does not have. + service = RecordingService(status_code=400, body={"code": code, "detail": reason}) + + with pytest.raises(SimulationServiceInvalidRequestError) as refused: + submit(service.client()) + + assert route_status(refused.value) == 422 + assert str(refused.value) == ( + f"The simulation service cannot run this request ({code}): {reason}" + ) + + +@pytest.mark.parametrize( + ("body", "stated_code"), + [ + pytest.param( + { + "code": "unknown_catalog_version", + "detail": "Country us has no catalog version for .py 4.2.0.", + }, + " (unknown_catalog_version)", + id="catalog-version-during-a-release", + ), + pytest.param( + {"code": "unknown_policy", "detail": "There is no policy p."}, + " (unknown_policy)", + id="policy-the-public-api-checked", + ), + pytest.param( + {"code": "missing_reference", "detail": "A row was deleted."}, + " (missing_reference)", + id="row-deleted-after-the-checks", + ), + pytest.param( + {"detail": "Region state/zz is not in the catalog version."}, + "", + id="no-code", + ), + ], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_400_naming_none_of_the_callers_rows_is_unavailable( + submit, record: str, route_status, body: dict[str, str], stated_code: str +) -> None: + # A 400 the caller cannot act on is a state of the simulation service, + # such as a catalog version missing while a release deploys. + service = RecordingService(status_code=400, body=body) + + with pytest.raises(SimulationServiceUnavailableError) as unavailable: + submit(service.client()) + + assert route_status(unavailable.value) == 503 + assert str(unavailable.value) == ( + f"The simulation service refused the {record}{stated_code}: {body['detail']}" + ) + assert unavailable.value.created_record_id is None + + +@pytest.mark.parametrize( + "body", + [b"not json", {"detail": {"nested": True}}, {"other": "shape"}], + ids=["not-json", "nested-detail", "no-detail"], +) +def test_a_refusal_of_another_shape_is_unavailable(body: object) -> None: + service = RecordingService(status_code=422, body=body) + + with pytest.raises(SimulationServiceUnavailableError): + service.client().submit_report(report_input()) + + +@pytest.mark.parametrize( + ("body", "status_and_code"), + [ + pytest.param( + {"code": "internal_error", "detail": "The run could not be started."}, + "500 internal_error", + id="internal-error", + ), + pytest.param({"detail": "The run could not be started."}, "500", id="no-code"), + pytest.param(b"", "500", id="unreadable"), + ], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_an_internal_error_is_not_unavailable( + submit, record: str, route_status, body: object, status_and_code: str +) -> None: + # A 500 may come after the service created the record, so it is not a + # 503, which says the service created nothing. + service = RecordingService(status_code=500, body=body) + + with pytest.raises(SimulationServiceInternalError) as failed: + submit(service.client()) + + assert route_status(failed.value) == 502 + assert str(failed.value) == possibly_created_message(status_and_code, record) + + +@pytest.mark.parametrize("status_code", [502, 504]) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_proxys_answer_in_place_of_the_services_is_not_unavailable( + submit, record: str, route_status, status_code: int +) -> None: + # A proxy in front of the service, such as Cloud Run's front end, may + # answer 502 or 504 after the service created the record. + service = RecordingService(status_code=status_code, body=b"upstream timeout") + + with pytest.raises(SimulationServiceAnswerUnreadableError) as lost: + submit(service.client()) + + assert route_status(lost.value) == 502 + assert str(lost.value) == answer_lost_message( + f"a proxy answered {status_code} in its place", record + ) + + +@pytest.mark.parametrize("status_code", [401, 403, 404, 405, 413, 429]) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_status_sent_before_the_services_route_runs_is_unavailable( + submit, record: str, route_status, status_code: int +) -> None: + # The gateway, Cloud Run or the service's framework answers these before + # the service's route runs, so nothing was created. + service = RecordingService(status_code=status_code, body={"detail": "Not Found"}) + + with pytest.raises(SimulationServiceUnavailableError) as unavailable: + submit(service.client()) + + assert route_status(unavailable.value) == 503 + assert str(unavailable.value) == ( + f"The simulation service is unavailable ({status_code})." + ) + assert unavailable.value.created_record_id is None + + +@pytest.mark.parametrize( + ("status_and_body", "status_and_code"), + [ + pytest.param((200, REPORT_CREATED), "200", id="200-naming-a-record"), + pytest.param((204, b""), "204", id="204"), + pytest.param((302, b""), "302", id="302"), + pytest.param((408, {"detail": "busy"}), "408", id="408"), + pytest.param( + (409, {"code": "label_taken", "detail": "The label is taken."}), + "409 label_taken", + id="409-with-a-code", + ), + pytest.param((501, b"Not Implemented"), "501", id="501"), + ], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_an_unexpected_status_may_have_created_the_record( + submit, + record: str, + route_status, + status_and_body: tuple[int, object], + status_and_code: str, +) -> None: + # The service's route may have written rows before answering a status + # the Public API does not expect, so the answer is not a 503, which says + # it created nothing. + status_code, body = status_and_body + service = RecordingService(status_code=status_code, body=body) + + with pytest.raises(SimulationServiceAnswerUnreadableError) as unexpected: + submit(service.client()) + + assert route_status(unexpected.value) == 502 + assert str(unexpected.value) == possibly_created_message(status_and_code, record) + + +@pytest.mark.parametrize( + ("body", "status_and_code"), + [ + pytest.param( + { + "code": "manifest_unavailable", + "detail": "The v2 version manifest could not be read.", + }, + "503 manifest_unavailable", + id="with-a-code", + ), + pytest.param( + {"detail": "The v2 version manifest could not be read."}, + "503", + id="no-code", + ), + ], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_the_services_unavailability_is_passed_on_with_its_code( + submit, record: str, route_status, body: object, status_and_code: str +) -> None: + service = RecordingService(status_code=503, body=body) + + with pytest.raises(SimulationServiceUnavailableError) as unavailable: + submit(service.client()) + + assert route_status(unavailable.value) == 503 + assert str(unavailable.value) == ( + f"The simulation service is unavailable ({status_and_code})." + ) + assert unavailable.value.created_record_id is None + + +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_record_the_unavailable_service_created_is_named( + submit, record: str, route_status +) -> None: + # The service created the record, then Modal refused the call and the + # service failed its run: the caller gets the record's ID. + id_field, record_id = CREATED_RECORD_IDS[record] + service = RecordingService( + status_code=503, + body={ + "code": "modal_call_refused", + "detail": "Modal refused the call, and the run was failed.", + id_field: str(record_id), + }, + ) + + with pytest.raises(SimulationServiceUnavailableError) as unavailable: + submit(service.client()) + + assert route_status(unavailable.value) == 503 + assert str(unavailable.value) == ( + f"The simulation service created {record} {record_id}, but is " + "unavailable (503 modal_call_refused)." + ) + assert unavailable.value.created_record_id == record_id + + +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_503_naming_only_another_records_id_may_have_created_the_record( + submit, record: str, route_status +) -> None: + # A report's 503 naming only a simulation shows the service wrote rows, + # so the answer is not a 503, which says it created nothing. + other_id_field, other_record_id = OTHER_RECORD_IDS[record] + service = RecordingService( + status_code=503, + body={ + "code": "modal_call_refused", + "detail": "Modal refused the call.", + other_id_field: str(other_record_id), + }, + ) + + with pytest.raises(SimulationServiceAnswerUnreadableError) as lost: + submit(service.client()) + + assert route_status(lost.value) == 502 + assert str(lost.value) == possibly_created_message("503 modal_call_refused", record) + + +@pytest.mark.parametrize( + ("body", "status_and_code"), + [ + pytest.param( + b"upstream connect error or disconnect/reset before headers", + "503", + id="proxy-text", + ), + pytest.param({"other": "shape"}, "503", id="no-detail"), + pytest.param( + {"code": "modal_call_refused"}, + "503 modal_call_refused", + id="no-detail-with-a-code", + ), + ], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_503_that_cannot_be_read_may_have_created_the_record( + submit, record: str, route_status, body: object, status_and_code: str +) -> None: + # Cloud Run's front end answers 503 in the service's place when the + # service's answer is malformed or the connection to its instance fails, + # which can follow a request the service received. + service = RecordingService(status_code=503, body=body) + + with pytest.raises(SimulationServiceAnswerUnreadableError) as lost: + submit(service.client()) + + assert route_status(lost.value) == 502 + assert str(lost.value) == possibly_created_message(status_and_code, record) + + +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_503_naming_a_malformed_record_id_may_have_created_the_record( + submit, record: str, route_status +) -> None: + # The body names a record, but not one the Public API can use. + id_field, _record_id = CREATED_RECORD_IDS[record] + service = RecordingService( + status_code=503, + body={ + "code": "modal_call_refused", + "detail": "Modal refused the call.", + id_field: "not-a-uuid", + }, + ) + + with pytest.raises(SimulationServiceAnswerUnreadableError) as lost: + submit(service.client()) + + assert route_status(lost.value) == 502 + assert str(lost.value) == possibly_created_message("503 modal_call_refused", record) + + +@pytest.mark.parametrize( + ("body", "submit", "record", "route_status"), + [ + pytest.param(b"not json", submit_report, "report", _report_route_status), + pytest.param( + {"report_id": "not-a-uuid", "report_run_id": str(REPORT_RUN_ID)}, + submit_report, + "report", + _report_route_status, + ), + pytest.param( + {"status": "pending"}, submit_report, "report", _report_route_status + ), + pytest.param( + b"not json", submit_simulation, "simulation", _simulation_route_status + ), + pytest.param( + {"simulation_id": str(SIMULATION_ID)}, + submit_simulation, + "simulation", + _simulation_route_status, + ), + ], + ids=[ + "report-not-json", + "report-malformed-id", + "report-no-id", + "simulation-not-json", + "simulation-no-run-id", + ], +) +def test_a_created_answer_that_cannot_be_read_is_not_unavailable( + body: object, submit, record: str, route_status +) -> None: + # The service has created the record and started its run, so the caller + # is told the answer was unreadable rather than to try again. + service = RecordingService(status_code=201, body=body) + + with pytest.raises(SimulationServiceAnswerUnreadableError) as unreadable: + submit(service.client()) + + assert route_status(unreadable.value) == 502 + assert str(unreadable.value) == ( + f"The simulation service created the {record}, but its answer could not " + "be read." + ) + + +def _client_raising( + error_type: type[httpx.TransportError], +) -> SimulationServiceReportClient: + """Return a client whose every request fails with ``error_type``.""" + + def fail(request: httpx.Request) -> httpx.Response: + msg = "the transport failed" + raise error_type(msg, request=request) + + return SimulationServiceReportClient.from_environment( + transport=httpx.MockTransport(fail) + ) + + +@pytest.mark.parametrize( + "error_type", [httpx.ConnectError, httpx.ConnectTimeout, httpx.PoolTimeout] +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_a_connection_never_made_is_unavailable( + submit, record: str, route_status, error_type: type[httpx.TransportError] +) -> None: + with pytest.raises( + SimulationServiceUnavailableError, match="could not be reached" + ) as unavailable: + submit(_client_raising(error_type)) + + assert route_status(unavailable.value) == 503 + + +@pytest.mark.parametrize( + "error_type", + [ + httpx.ReadTimeout, + httpx.WriteTimeout, + httpx.ReadError, + httpx.WriteError, + httpx.RemoteProtocolError, + ], +) +@pytest.mark.parametrize(("submit", "record", "route_status"), SUBMISSIONS) +def test_an_answer_lost_after_sending_is_not_unavailable( + submit, record: str, route_status, error_type: type[httpx.TransportError] +) -> None: + # The service may have received the submission and created the record, + # so the answer is not a 503, which says it created nothing. + with pytest.raises(SimulationServiceAnswerUnreadableError) as lost: + submit(_client_raising(error_type)) + + assert route_status(lost.value) == 502 + assert str(lost.value) == answer_lost_message(error_type.__name__, record) + + +def test_a_gateway_token_that_cannot_be_fetched_is_unavailable() -> None: + def refuse_token( + http_client: httpx.Client, body: dict[str, Any] + ) -> SimulationAnswer: + msg = "Auth0 refused the client credentials" + raise GatewayAuthError(msg) + + client = SimulationServiceReportClient( + httpx.Client(base_url=SIMULATION_URL), send_report=refuse_token + ) + + with pytest.raises( + SimulationServiceUnavailableError, match="could not be reached" + ) as unavailable: + client.submit_report(report_input()) + + assert _report_route_status(unavailable.value) == 503 + + +def test_each_request_is_sent_through_its_one_replaceable_send_function() -> None: + sent: list[tuple[str, dict[str, Any]]] = [] + + def send_to(path: str, answer: dict[str, str]): + def send(http_client: httpx.Client, body: dict[str, Any]) -> SimulationAnswer: + assert str(http_client.base_url).rstrip("/") == SIMULATION_URL + sent.append((path, body)) + return SimulationAnswer( + status_code=201, content=json.dumps(answer).encode() + ) + + return send + + client = SimulationServiceReportClient( + httpx.Client(base_url=SIMULATION_URL), + send_report=send_to(REPORTS_PATH, REPORT_CREATED), + send_simulation=send_to(SIMULATIONS_PATH, SIMULATION_CREATED), + ) + + client.submit_report(report_input()) + client.submit_simulation(simulation_input()) + + assert [path for path, _body in sent] == [REPORTS_PATH, SIMULATIONS_PATH] + + +def test_a_missing_service_url_is_unavailable(monkeypatch) -> None: + monkeypatch.delenv("SIMULATION_ENTRYPOINT_URL") + + with pytest.raises(SimulationServiceUnavailableError, match="not configured"): + SimulationServiceReportClient.from_environment() + + +def test_partly_configured_gateway_credentials_are_unavailable(monkeypatch) -> None: + monkeypatch.setenv("GATEWAY_AUTH_ISSUER", "https://tenant.example.test/") + + with pytest.raises(SimulationServiceUnavailableError, match="not configured"): + SimulationServiceReportClient.from_environment() diff --git a/tests/unit/routes/test_migration_context_logging.py b/tests/unit/routes/test_migration_context_logging.py index dafa447fa..37540124d 100644 --- a/tests/unit/routes/test_migration_context_logging.py +++ b/tests/unit/routes/test_migration_context_logging.py @@ -607,6 +607,85 @@ def test_signed_in_user_resources_log_supabase_sources( } +class _SimulationResourceRequest(NamedTuple): + method: str + path: str + route_group: str + sim_flow: str | None + sim_compute: str | None + + +_SIMULATION_RESOURCE_REQUESTS = ( + _SimulationResourceRequest("GET", "/v2/reports", "report", None, None), + _SimulationResourceRequest( + "GET", "/v2/reports/00000000-0000-0000-0000-000000000001", "report", None, None + ), + _SimulationResourceRequest("POST", "/v2/reports", "report", "report", "v2_primary"), + _SimulationResourceRequest( + "GET", + "/v2/simulations/00000000-0000-0000-0000-000000000001", + "simulation", + None, + None, + ), + _SimulationResourceRequest( + "POST", "/v2/simulations", "simulation", "economy", "v2_primary" + ), +) + + +@pytest.mark.parametrize( + "request_case", + [ + pytest.param(case, id=f"{case.method}-{case.path}") + for case in _SIMULATION_RESOURCE_REQUESTS + ], +) +def test_v2_reports_and_simulations_log_what_they_use( + monkeypatch, request_case: _SimulationResourceRequest +): + """They read Supabase and create only through the Cloud Run simulation service. + + The route groups' database, entrypoint and compute flags select none of + it, so an invalid flag is not read. + """ + for name in ( + "DB_READ_SIMULATION", + "DB_WRITE_SIMULATION", + "DB_READ_REPORT", + "DB_WRITE_REPORT", + "SIM_ENTRYPOINT", + "SIM_COMPUTE_ECONOMY", + "SIM_COMPUTE_REPORT", + ): + monkeypatch.setenv(name, "invalid-for-native-v2") + + with patch("policyengine_api.migration_logging.logger") as mock_logger: + log_migration_request( + ServedRequest( + request_id="request", + method=request_case.method, + path=request_case.path, + status_code=200, + started_at=None, + country_id="us", + route_impl=RouteImplementation.FASTAPI_NATIVE, + ) + ) + + context = mock_logger.log_struct.call_args.args[0]["migration"] + assert context == { + "route_group": request_case.route_group, + "route_impl": "fastapi_native", + "db_entity": request_case.route_group, + "db_write": None, + "db_read": "supabase", + "sim_flow": request_case.sim_flow, + "sim_entrypoint": "cloud_run_simulation_entrypoint", + "sim_compute": request_case.sim_compute, + } + + def test_native_route_failure_logs_country_and_actual_implementation(): dependencies = NativeRouteDependencies( readiness_probe=lambda: True, diff --git a/tests/unit/test_alembic_workflows.py b/tests/unit/test_alembic_workflows.py index c4a493253..feeea74e4 100644 --- a/tests/unit/test_alembic_workflows.py +++ b/tests/unit/test_alembic_workflows.py @@ -243,6 +243,9 @@ def test_reusable_v2_integration_check_uses_disposable_databases_and_coverage(): assert "test_v2_catalog_spm_availability.py" in workflow assert "test_v2_metadata_routes.py" in workflow assert "test_v2_country_routes.py" in workflow + assert "test_v2_report_reads.py" in workflow + assert "test_v2_report_creation.py" in workflow + assert "test_v2_saved_detailed_save_records.py" in workflow assert "test_v2_policy_persistence.py" in workflow assert "test_v1_policy_dual_write.py" in workflow assert "test_mysql_policy_dual_write.py" in workflow diff --git a/tests/unit/test_migration_contract_artifacts.py b/tests/unit/test_migration_contract_artifacts.py index 12b96afae..e8f5bcc1a 100644 --- a/tests/unit/test_migration_contract_artifacts.py +++ b/tests/unit/test_migration_contract_artifacts.py @@ -13,8 +13,8 @@ def test_migration_contract_payload_summarizes_route_contracts(): assert payload["version"] == 1 assert payload["metadata"] == { "route_group_count": 9, - "workflow_count": 17, - "request_count": 92, + "workflow_count": 18, + "request_count": 97, "db_entity_count": 6, "sim_flow_count": 3, } @@ -32,6 +32,7 @@ def test_migration_contract_payload_summarizes_route_contracts(): "household_calculate", "region_selection", "country_selection_v2", + "detailed_save_reports_v2", "metadata_resources_v2_preview", "simulation_submit_poll", "report_create_poll", diff --git a/tests/unit/v2/simulation_service_messages.py b/tests/unit/v2/simulation_service_messages.py new file mode 100644 index 000000000..cc9b49c75 --- /dev/null +++ b/tests/unit/v2/simulation_service_messages.py @@ -0,0 +1,39 @@ +"""The messages for a simulation service answer that may follow a created record. + +The route tests and the simulation service client's tests both import these. +This module imports nothing from the app, so the client's tests don't build +the app to read them. +""" + +from __future__ import annotations + + +def submit_again(record: str) -> str: + """Return the sentence asking the caller to submit the ``record`` again.""" + return ( + f"Submit the {record} again; if the first request went through, this " + f"creates a second {record}." + ) + + +def answer_lost_message(error: str, record: str) -> str: + """Return the message for an answer lost after the request may have arrived. + + ``error`` is the transport error's type or what a proxy answered. + """ + return ( + "The simulation service may have received the request, but its answer " + f"was lost ({error}). {submit_again(record)}" + ) + + +def possibly_created_message(status_and_code: str, record: str) -> str: + """Return the message for a failure that may follow a created ``record``. + + ``status_and_code`` is the service's status and, when it gave one, its + code, such as ``503 modal_call_refused``. + """ + return ( + f"The simulation service may have created the {record}, but it failed " + f"({status_and_code}). {submit_again(record)}" + ) diff --git a/tests/unit/v2/stored_report_support.py b/tests/unit/v2/stored_report_support.py new file mode 100644 index 000000000..f182529fe --- /dev/null +++ b/tests/unit/v2/stored_report_support.py @@ -0,0 +1,226 @@ +"""Builders and stand-in services for the v2 report and simulation route tests.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from datetime import UTC, datetime +from typing import TYPE_CHECKING, Any +from uuid import UUID + +from fastapi.testclient import TestClient +from flask import Flask + +from policyengine_api.asgi_factory import create_asgi_app +from policyengine_api.fastapi_routes.dependencies import NativeRouteDependencies +from policyengine_api.migration_flags import ( + RouteImplementation, + RouteImplementationSettings, +) +from policyengine_api.services.v2.simulation_service.types import PackageVersions +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResult, +) +from policyengine_api.services.v2.stored_reports.types import ( + ReportRead, + ReportRunRead, + ReportSimulationRead, + ReportSummaryRead, +) +from policyengine_api.services.v2.stored_simulations.types import ( + SimulationRead, + SimulationRunRead, +) +from tests.fixtures.economy_results import us_economy_result + +if TYPE_CHECKING: + from collections.abc import Callable, Sequence + + from policyengine_api.fastapi_routes.resource_service_protocols import ( + V2StoredReportResourceService, + V2StoredSimulationResourceService, + ) + from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + ) + +REPORT_ID = UUID("00000000-0000-0000-0000-00000000a001") +REPORT_RUN_ID = UUID("00000000-0000-0000-0000-00000000a002") +BASELINE_SIMULATION_ID = UUID("00000000-0000-0000-0000-00000000a003") +REFORM_SIMULATION_ID = UUID("00000000-0000-0000-0000-00000000a004") +BASELINE_RUN_ID = UUID("00000000-0000-0000-0000-00000000a005") +REFORM_RUN_ID = UUID("00000000-0000-0000-0000-00000000a006") +POLICY_ID = UUID("00000000-0000-0000-0000-00000000a007") +SIMULATION_RUN_ID = UUID("00000000-0000-0000-0000-00000000a008") +CREATED_AT = datetime(2026, 11, 1, 9, tzinfo=UTC) +CURRENT_VERSIONS = PackageVersions( + country_package_version="1.5.0", policyengine_version="4.2.0" +) + + +def report_run_read(**changes: Any) -> ReportRunRead: + values: dict[str, Any] = { + "id": REPORT_RUN_ID, + "status": "succeeded", + "trigger": "initial", + "country_package_version": "1.4.0", + "policyengine_version": "4.1.0", + "baseline_simulation_run_id": BASELINE_RUN_ID, + "reform_simulation_run_id": REFORM_RUN_ID, + "error_message": None, + "created_at": CREATED_AT, + "started_at": CREATED_AT, + "completed_at": CREATED_AT, + } + return ReportRunRead(**{**values, **changes}) + + +def report_summary_fields(**changes: Any) -> dict[str, Any]: + values: dict[str, Any] = { + "id": REPORT_ID, + "country_id": "us", + "kind": "economy", + "label": "Expanded child tax credit", + "description": None, + "year": 2026, + "region_code": "state/ca", + "dataset_name": None, + "baseline_simulation": ReportSimulationRead( + id=BASELINE_SIMULATION_ID, policy_id=None, dynamic_id=None + ), + "reform_simulation": ReportSimulationRead( + id=REFORM_SIMULATION_ID, policy_id=POLICY_ID, dynamic_id=None + ), + "options": {"include_cliffs": False}, + "created_at": CREATED_AT, + "status": "succeeded", + "run": report_run_read(), + "current_versions": CURRENT_VERSIONS, + } + return {**values, **changes} + + +def report_summary_read(**changes: Any) -> ReportSummaryRead: + return ReportSummaryRead(**report_summary_fields(**changes)) + + +def report_read(**changes: Any) -> ReportRead: + fields = { + "result": EconomyResult.model_validate(us_economy_result()), + **report_summary_fields(), + **changes, + } + return ReportRead(**fields) + + +def simulation_read(**changes: Any) -> SimulationRead: + values: dict[str, Any] = { + "id": BASELINE_SIMULATION_ID, + "country_id": "us", + "kind": "economy", + "policy_id": POLICY_ID, + "dynamic_id": None, + "household_id": None, + "year": 2026, + "region_code": "us", + "dataset_name": "enhanced_cps_2024", + "created_at": CREATED_AT, + "status": "pending", + "run": SimulationRunRead( + id=SIMULATION_RUN_ID, + year=2026, + status="pending", + country_package_version="1.5.0", + policyengine_version="4.2.0", + error_message=None, + created_at=CREATED_AT, + started_at=None, + completed_at=None, + ), + "current_versions": CURRENT_VERSIONS, + } + return SimulationRead(**{**values, **changes}) + + +@dataclass +class FakeReportService: + """Answer with ``report`` or raise ``error``, recording each call.""" + + report: ReportRead = field(default_factory=report_read) + listed: tuple[ReportSummaryRead, ...] = () + error: Exception | None = None + calls: list[tuple[str, dict[str, Any]]] = field(default_factory=list) + + def _answer(self, name: str, **arguments: Any) -> None: + self.calls.append((name, arguments)) + if self.error is not None: + raise self.error + + def get_report(self, *, country_id: str, report_id: UUID) -> ReportRead: + self._answer("get_report", country_id=country_id, report_id=report_id) + return self.report + + def list_reports( + self, *, country_id: str, report_ids: Sequence[UUID] + ) -> tuple[ReportSummaryRead, ...]: + self._answer("list_reports", country_id=country_id, report_ids=report_ids) + return self.listed + + def create_report(self, report_input: EconomyReportCreationInput) -> ReportRead: + self._answer("create_report", report_input=report_input) + return self.report + + +@dataclass +class FakeSimulationService: + """Answer with ``simulation`` or raise ``error``, recording each call.""" + + simulation: SimulationRead = field(default_factory=simulation_read) + error: Exception | None = None + calls: list[tuple[str, dict[str, Any]]] = field(default_factory=list) + + def _answer(self, name: str, **arguments: Any) -> None: + self.calls.append((name, arguments)) + if self.error is not None: + raise self.error + + def get_simulation(self, *, country_id: str, simulation_id: UUID) -> SimulationRead: + self._answer( + "get_simulation", country_id=country_id, simulation_id=simulation_id + ) + return self.simulation + + def create_simulation( + self, simulation_input: EconomySimulationCreationInput + ) -> SimulationRead: + self._answer("create_simulation", simulation_input=simulation_input) + return self.simulation + + +def report_route_client( + *, + reports: V2StoredReportResourceService | None = None, + simulations: V2StoredSimulationResourceService | None = None, +) -> TestClient: + """Serve the report and simulation routes over these services, usually stand-ins.""" + factories: dict[str, Callable[[], Any]] = {} + if reports is not None: + factories["v2_stored_report_service_factory"] = lambda: reports + if simulations is not None: + factories["v2_stored_simulation_service_factory"] = lambda: simulations + dependencies = NativeRouteDependencies( + readiness_probe=lambda: True, + gateway_client_factory=lambda: None, + metadata_reader_factory=lambda: None, + **factories, + ) + settings = RouteImplementationSettings( + health=RouteImplementation.FLASK_FALLBACK, + specification=RouteImplementation.FLASK_FALLBACK, + metadata=RouteImplementation.FLASK_FALLBACK, + ) + return TestClient( + create_asgi_app( + Flask(__name__), dependencies=dependencies, route_settings=settings + ) + ) diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py new file mode 100644 index 000000000..30eb29082 --- /dev/null +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -0,0 +1,361 @@ +"""Rebuild report runs' economy results from the rows the simulation service stores. + +Most results are stored through a port of the simulation service's writer +(``tests.fixtures.economy_results``), so a rebuild that matches the result +reverses that writer. ``economy_result_rows_golden.json`` holds what the +writer itself stored at a named commit +(``scripts/generate_economy_result_golden.py``), so a rebuild that matches it +reverses the real writer, and a change in the writer fails once the file is +generated again. +""" + +from __future__ import annotations + +import json +from dataclasses import replace +from pathlib import Path +from typing import Any +from uuid import UUID, uuid4 + +import pytest + +from policyengine_api.data.v2.models import ( + BudgetSummary, + CongressionalDistrictImpact, + ConstituencyImpact, + DecileImpact, + Inequality, + IntraDecileImpact, + LaborSupplyDecileResponse, + LaborSupplyResponse, + LocalAuthorityImpact, + Poverty, + ProgramStatistics, +) +from policyengine_api.services.v2.stored_reports.economy_results import ( + transformations as result_transformations, +) +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResultRows, + EconomyResultUnreadableError, + ReportRunResultColumns, +) +from policyengine_api.spm import SPMComparisonProvenance +from tests.fixtures.economy_results import ( + RunIds, + economy_result_rows, + uk_economy_result, + us_economy_result, +) + +GOLDEN = json.loads( + ( + Path(__file__).parents[2] / "fixtures" / "economy_result_rows_golden.json" + ).read_text() +) + +TABLE_MODELS = { + "budget_summary": BudgetSummary, + "program_statistics": ProgramStatistics, + "decile_impacts": DecileImpact, + "intra_decile_impacts": IntraDecileImpact, + "poverty": Poverty, + "inequality": Inequality, + "labor_supply_responses": LaborSupplyResponse, + "labor_supply_decile_responses": LaborSupplyDecileResponse, + "congressional_district_impacts": CongressionalDistrictImpact, + "constituency_impacts": ConstituencyImpact, + "local_authority_impacts": LocalAuthorityImpact, +} + + +def stored_rows( + output: dict[str, Any], *, country: str, reverse_rows: bool = False +) -> EconomyResultRows: + """Store ``output`` as the writer does and load its rows as table models. + + With ``reverse_rows``, each table's rows come back in reverse order, as a + query without an order may return them. + """ + run_ids = RunIds( + report_run_id=uuid4(), + baseline_simulation_run_id=uuid4(), + reform_simulation_run_id=uuid4(), + ) + stored = economy_result_rows(output, run_ids=run_ids, country=country) + tables: dict[str, tuple[Any, ...]] = {} + for table, rows in stored.rows.items(): + loaded = [TABLE_MODELS[table](id=uuid4(), **row) for row in rows] + if reverse_rows: + loaded.reverse() + tables[table] = tuple(loaded) + return EconomyResultRows( + country_id=country, + report_run=ReportRunResultColumns( + country_package_version=output["model_version"], + **stored.report_run_columns, + ), + baseline_simulation_run_id=run_ids.baseline_simulation_run_id, + reform_simulation_run_id=run_ids.reform_simulation_run_id, + **tables, + ) + + +def as_json(value: Any) -> Any: + """Return ``value`` as the simulation service serves it: through JSON.""" + return json.loads(json.dumps(value)) + + +def golden_rows(case: dict[str, Any]) -> EconomyResultRows: + """Load one golden case's stored rows as the database connectors read them. + + Run IDs come back as UUIDs and each row gets a new ID, as the writer + draws them. + """ + run_ids = {key: UUID(value) for key, value in GOLDEN["run_ids"].items()} + + def loaded(table: str, row: dict[str, Any]) -> Any: + return TABLE_MODELS[table]( + id=uuid4(), + **{ + column: UUID(value) if column.endswith("run_id") else value + for column, value in row.items() + }, + ) + + return EconomyResultRows( + country_id=case["country"], + report_run=ReportRunResultColumns( + country_package_version=case["output"]["model_version"], + **case["report_run_columns"], + ), + baseline_simulation_run_id=run_ids["baseline_simulation_run_id"], + reform_simulation_run_id=run_ids["reform_simulation_run_id"], + **{ + table: tuple(loaded(table, row) for row in rows) + for table, rows in case["rows"].items() + }, + ) + + +@pytest.mark.parametrize( + "case", GOLDEN["cases"], ids=[case["name"] for case in GOLDEN["cases"]] +) +def test_rows_the_simulation_services_own_writer_stored_rebuild_its_result( + case: dict[str, Any], +) -> None: + rebuilt = result_transformations.economy_result(golden_rows(case)) + + assert rebuilt.model_dump(mode="json", by_alias=True) == case["output"] + + +def test_the_golden_rows_cover_the_shapes_the_fixtures_alone_do_not() -> None: + cases = {case["name"]: case for case in GOLDEN["cases"]} + variant = cases["us-labour-supply-deciles-and-at-large-districts"]["rows"] + + assert GOLDEN["writer"]["repository"] == "PolicyEngine/policyengine-sim-api" + assert {"us", "uk"} <= cases.keys() + assert {-1, 0} <= { + row["decile"] for row in variant["labor_supply_decile_responses"] + } + # DC (11) and Wyoming (56) each have one at-large district, stored as 0. + assert {(11, 0), (56, 0)} <= { + (row["state_fips"], row["district_number"]) + for row in variant["congressional_district_impacts"] + } + assert cases["us-negative-budget"]["output"]["budget"]["budgetary_impact"] < 0 + + +def test_a_stored_spm_receipt_is_read_as_the_public_apis_comparison_type() -> None: + rebuilt = result_transformations.economy_result( + stored_rows(us_economy_result(), country="us") + ) + + assert isinstance(rebuilt.spm_provenance, SPMComparisonProvenance) + assert rebuilt.spm_provenance.baseline.receipt.runtime_versions.policyengine_us == ( + "1.0.0" + ) + + +def test_a_stored_spm_receipt_of_another_shape_makes_the_result_unreadable() -> None: + rows = stored_rows(us_economy_result(), country="us") + receipt = as_json(rows.report_run.spm_provenance) + receipt["reform"]["receipt"]["scenario"] = "another_scenario" + rows = replace(rows, report_run=replace(rows.report_run, spm_provenance=receipt)) + + with pytest.raises(EconomyResultUnreadableError, match="SPM"): + result_transformations.economy_result(rows) + + +@pytest.mark.parametrize( + ("country", "output"), + [ + ("us", us_economy_result()), + ("uk", uk_economy_result()), + ], + ids=["us", "uk"], +) +def test_result_rows_rebuild_the_result_the_simulation_service_stored( + country: str, output: dict[str, Any] +) -> None: + rebuilt = result_transformations.economy_result( + stored_rows(output, country=country) + ) + + # The SPM receipts name their runtime packages, as the Public API serves them. + assert rebuilt.model_dump(mode="json", by_alias=True) == as_json(output) + + +@pytest.mark.parametrize( + ("country", "output"), + [ + ("us", us_economy_result()), + ("uk", uk_economy_result()), + ], + ids=["us", "uk"], +) +def test_result_rows_in_any_order_rebuild_the_same_result( + country: str, output: dict[str, Any] +) -> None: + rebuilt = result_transformations.economy_result( + stored_rows(output, country=country, reverse_rows=True) + ) + + # The SPM receipts name their runtime packages, as the Public API serves them. + assert rebuilt.model_dump(mode="json", by_alias=True) == as_json(output) + + +def test_rebuilt_result_lists_its_parts_in_the_simulation_service_order() -> None: + rebuilt = result_transformations.economy_result( + stored_rows(us_economy_result(), country="us") + ) + + assert list(rebuilt.model_dump(mode="json")) == list(us_economy_result()) + + +def test_relative_decile_changes_are_fractions_of_the_stored_percentages() -> None: + output = us_economy_result() + output["decile"]["relative"]["3"] = 0.07 + rebuilt = result_transformations.economy_result(stored_rows(output, country="us")) + + assert rebuilt.decile.relative["3"] == pytest.approx(0.07) + + +def test_a_uk_result_without_a_state_income_tax_row_reports_none_collected() -> None: + rows = stored_rows(uk_economy_result(), country="uk") + + assert "household_state_income_tax" not in { + row.variable_name for row in rows.budget_summary + } + assert ( + result_transformations.economy_result(rows).budget.state_tax_revenue_impact + == 0.0 + ) + + +def test_an_intra_decile_breakdown_without_rows_has_empty_categories() -> None: + rows = stored_rows(us_economy_result(), country="us") + rows = replace( + rows, + intra_decile_impacts=tuple( + row for row in rows.intra_decile_impacts if row.decile_type != "income" + ), + ) + + intra_decile = result_transformations.economy_result(rows).intra_decile + + assert set(intra_decile.deciles) == { + "Lose more than 5%", + "Lose less than 5%", + "No change", + "Gain less than 5%", + "Gain more than 5%", + } + assert all(values == [] for values in intra_decile.deciles.values()) + assert all(share == 0.0 for share in intra_decile.all.values()) + + +def _without(rows: EconomyResultRows, table: str, keep: Any) -> EconomyResultRows: + return replace( + rows, **{table: tuple(row for row in getattr(rows, table) if keep(row))} + ) + + +@pytest.mark.parametrize( + ("table", "keep", "missing"), + [ + ( + "budget_summary", + lambda row: row.variable_name != "household_tax", + "household_tax", + ), + ( + "budget_summary", + lambda row: row.variable_name != "household_state_income_tax", + "household_state_income_tax", + ), + ( + "poverty", + lambda row: ( + not (row.poverty_type == "spm_deep" and row.filter_group == "senior") + ), + "spm_deep", + ), + ("inequality", lambda row: False, "inequality"), + ("decile_impacts", lambda row: row.decile_variable is not None, "decile"), + ], + ids=[ + "tax", + "us-state-income-tax", + "deep-poverty-of-seniors", + "inequality", + "income-deciles", + ], +) +def test_a_result_without_a_part_every_result_has_is_unreadable( + table: str, keep: Any, missing: str +) -> None: + rows = _without( + stored_rows(us_economy_result(), country="us"), + table, + keep, + ) + + with pytest.raises(EconomyResultUnreadableError, match=missing): + result_transformations.economy_result(rows) + + +def test_a_result_without_its_data_version_is_unreadable() -> None: + rows = stored_rows(us_economy_result(), country="us") + rows = replace(rows, report_run=replace(rows.report_run, data_version=None)) + + with pytest.raises(EconomyResultUnreadableError, match="data version"): + result_transformations.economy_result(rows) + + +def test_a_null_stored_figure_makes_the_result_unreadable() -> None: + rows = stored_rows(us_economy_result(), country="us") + inequality = rows.inequality[0] + inequality.gini = None + + with pytest.raises(EconomyResultUnreadableError, match="gini"): + result_transformations.economy_result(rows) + + +def test_a_district_of_an_unknown_state_makes_the_result_unreadable() -> None: + rows = stored_rows(us_economy_result(), country="us") + district = rows.congressional_district_impacts[0] + district.state_fips = 3 + + with pytest.raises(EconomyResultUnreadableError, match="FIPS"): + result_transformations.economy_result(rows) + + +def test_a_country_without_poverty_measures_is_unreadable() -> None: + rows = replace( + stored_rows(us_economy_result(), country="us"), + country_id="ca", + ) + + with pytest.raises(EconomyResultUnreadableError, match="'ca'"): + result_transformations.economy_result(rows) diff --git a/tests/unit/v2/test_household_calculation_routes.py b/tests/unit/v2/test_household_calculation_routes.py index 36f5c9ee8..74850a2b8 100644 --- a/tests/unit/v2/test_household_calculation_routes.py +++ b/tests/unit/v2/test_household_calculation_routes.py @@ -21,10 +21,6 @@ HouseholdCalculationOutput, HouseholdCalculationRead, HouseholdCalculationSubmitted, - SimulationServiceAnswerUnreadableError, - SimulationServiceInternalError, - SimulationServiceInvalidRequestError, - SimulationServiceUnavailableError, ) from policyengine_api.services.v2.household_calculations.validators import ( HouseholdCalculationCountryError, @@ -38,6 +34,12 @@ PolicyNotFoundError, PolicyParametersMissingError, ) +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceAnswerUnreadableError, + SimulationServiceInternalError, + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, +) from tests.fixtures.household_calculation_documents import ( CALCULATED_HOUSEHOLD, INPUT_ERROR, diff --git a/tests/unit/v2/test_household_calculation_service.py b/tests/unit/v2/test_household_calculation_service.py index 6f1bc5c45..73335e8ab 100644 --- a/tests/unit/v2/test_household_calculation_service.py +++ b/tests/unit/v2/test_household_calculation_service.py @@ -11,10 +11,6 @@ from policyengine_api.services.v2.household_calculations.services import ( V2HouseholdCalculationService, ) -from policyengine_api.services.v2.household_calculations.types import ( - SimulationServiceInvalidRequestError, - SimulationServiceUnavailableError, -) from policyengine_api.services.v2.household_calculations.validators import ( HouseholdCalculationCountryError, HouseholdCalculationStorageError, @@ -25,6 +21,10 @@ PolicyNotFoundError, PolicyParametersMissingError, ) +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, +) from tests.fixtures.household_calculation_documents import JOB_ID from tests.unit.v2.household_calculation_support import ( HOUSEHOLD_ID, diff --git a/tests/unit/v2/test_metadata_routes.py b/tests/unit/v2/test_metadata_routes.py index 74400c396..ae8602905 100644 --- a/tests/unit/v2/test_metadata_routes.py +++ b/tests/unit/v2/test_metadata_routes.py @@ -337,6 +337,10 @@ def test_openapi_references_explicit_resource_response_schemas() -> None: "/v2/household-calculations/{calculation_id}", "/v2/policies", "/v2/policies/{policy_id}", + "/v2/reports", + "/v2/reports/{report_id}", + "/v2/simulations", + "/v2/simulations/{simulation_id}", "/v2/user-households", "/v2/user-households/{association_id}", "/v2/user-policies", diff --git a/tests/unit/v2/test_report_create_routes.py b/tests/unit/v2/test_report_create_routes.py new file mode 100644 index 000000000..3c980d99f --- /dev/null +++ b/tests/unit/v2/test_report_create_routes.py @@ -0,0 +1,970 @@ +"""Create v2 reports and simulations over stand-in services.""" + +from __future__ import annotations + +import logging +from typing import TYPE_CHECKING, Any, NoReturn +from uuid import UUID + +import httpx +import pytest + +from policyengine_api.data.v2.settings import V2ConfigurationError +from policyengine_api.fastapi_routes.v2.reports.routes import REPORT_ERROR_MAPPINGS +from policyengine_api.fastapi_routes.v2.simulations.routes import ( + SIMULATION_ERROR_MAPPINGS, +) +from policyengine_api.libs.simulation_reports import SimulationServiceReportClient +from policyengine_api.services.v2.policies.validators import PolicyNotFoundError +from policyengine_api.services.v2.simulation_service.types import ( + SimulationServiceAnswerUnreadableError, + SimulationServiceInternalError, + SimulationServiceInvalidRequestError, + SimulationServiceUnavailableError, +) +from policyengine_api.services.v2.simulation_service.validators import ( + EconomyCalculationsUnsupportedError, +) +from policyengine_api.services.v2.stored_reports.services import ( + V2StoredReportService, +) +from policyengine_api.services.v2.stored_reports.validators import ( + CreatedReportUnreadableError, +) +from policyengine_api.services.v2.stored_simulations.services import ( + V2StoredSimulationService, +) +from policyengine_api.services.v2.stored_simulations.validators import ( + CreatedSimulationUnreadableError, +) +from tests.unit.v2.simulation_service_messages import ( + answer_lost_message, + possibly_created_message, +) +from tests.unit.v2.stored_report_support import ( + CURRENT_VERSIONS, + POLICY_ID, + REPORT_ID, + FakeReportService, + FakeSimulationService, + report_route_client, +) + +if TYPE_CHECKING: + from collections.abc import Callable + + from fastapi.testclient import TestClient + +ROUTE_SUPPORT_LOGGER = "policyengine_api.fastapi_routes.v2.simulation_resources_support" + + +@pytest.fixture +def enabled_route_support_logger(monkeypatch: pytest.MonkeyPatch) -> None: + """Enable the report and simulation routes' logger for one test. + + Alembic's env.py runs logging.config.fileConfig, which disables every + logger that already exists. Alembic tests run it in this process, after + collection has imported the routes, so the logger may be disabled here. + """ + monkeypatch.setattr(logging.getLogger(ROUTE_SUPPORT_LOGGER), "disabled", False) + + +def logged_events(caplog) -> list[str]: + """Return the events the report and simulation routes logged.""" + return [ + record.getMessage() + for record in caplog.records + if record.name == ROUTE_SUPPORT_LOGGER + ] + + +def report_body(**changes: Any) -> dict[str, Any]: + values: dict[str, Any] = { + "country_id": "us", + "kind": "economy", + "label": "Expanded child tax credit", + "year": 2026, + "region_code": "state/ca", + "baseline": {}, + "reform": {"policy_id": str(POLICY_ID)}, + } + return {**values, **changes} + + +def simulation_body(**changes: Any) -> dict[str, Any]: + values: dict[str, Any] = { + "country_id": "us", + "kind": "economy", + "year": 2026, + "region_code": "us", + "policy_id": str(POLICY_ID), + } + return {**values, **changes} + + +def test_a_report_is_created_and_answered_as_stored() -> None: + service = FakeReportService() + + response = report_route_client(reports=service).post( + "/v2/reports?country_id=us", + json=report_body(include_cliffs=True, spm={"geography_kind": "national"}), + ) + + assert response.status_code == 201, response.text + assert response.json()["result"]["item"]["id"] == str(REPORT_ID) + ((operation, arguments),) = service.calls + assert operation == "create_report" + created = arguments["report_input"] + assert created.country_id == "us" + assert created.include_cliffs is True + assert created.reform.policy_id == POLICY_ID + assert created.spm.geography_kind == "national" + + +def test_a_report_body_naming_another_country_is_refused() -> None: + service = FakeReportService() + + response = report_route_client(reports=service).post( + "/v2/reports?country_id=uk", json=report_body() + ) + + assert response.status_code == 400 + assert service.calls == [] + + +@pytest.mark.parametrize( + "body", + [ + {key: value for key, value in report_body().items() if key != "label"}, + report_body(kind="household"), + report_body(year=2201), + report_body(region_code="two words"), + report_body(spm=None), + report_body(include_cliffs="yes"), + report_body(policyengine_version="4.2.0"), + report_body(reform={"policy_id": "not-a-uuid"}), + ], + ids=[ + "no-label", + "household-kind", + "year-too-late", + "region-with-space", + "null-spm", + "non-boolean-cliffs", + "names-a-version", + "malformed-policy", + ], +) +def test_a_malformed_report_is_refused_before_the_service( + body: dict[str, Any], +) -> None: + service = FakeReportService() + + response = report_route_client(reports=service).post( + "/v2/reports?country_id=us", json=body + ) + + assert response.status_code == 422 + assert service.calls == [] + + +def test_a_report_body_over_16_kib_is_refused() -> None: + service = FakeReportService() + + response = report_route_client(reports=service).post( + "/v2/reports?country_id=us", + json=report_body(description="x" * (17 * 1024)), + ) + + assert response.status_code == 413 + assert service.calls == [] + + +@pytest.mark.parametrize( + ("error", "status_code", "message"), + [ + ( + PolicyNotFoundError("Policy p was not found in country 'us'"), + 404, + "Policy p was not found in country 'us'", + ), + ( + EconomyCalculationsUnsupportedError( + "Economy calculations are not available for country 'us'" + ), + 422, + "Economy calculations are not available for country 'us'", + ), + ( + SimulationServiceInvalidRequestError( + "The simulation service cannot run this request (unknown_region): " + "no such region" + ), + 422, + "The simulation service cannot run this request (unknown_region): " + "no such region", + ), + ( + SimulationServiceInternalError( + possibly_created_message("500 internal_error", "report") + ), + 502, + possibly_created_message("500 internal_error", "report"), + ), + ( + SimulationServiceAnswerUnreadableError( + "The simulation service created the report, but its answer " + "could not be read." + ), + 502, + "The simulation service created the report, but its answer could " + "not be read.", + ), + ( + SimulationServiceUnavailableError( + "The simulation service is unavailable (503 manifest_unavailable)." + ), + 503, + "The simulation service is unavailable (503 manifest_unavailable).", + ), + ], + ids=[ + "policy-not-stored", + "household-only", + "service-refusal", + "service-failure", + "unreadable-answer", + "service-unavailable", + ], +) +def test_report_creation_failures_answer_typed_errors( + error: Exception, status_code: int, message: str +) -> None: + client = report_route_client(reports=FakeReportService(error=error)) + + response = client.post("/v2/reports?country_id=us", json=report_body()) + + assert response.status_code == status_code + assert response.json() == {"status": "error", "message": message} + + +def test_a_simulation_is_created_and_answered_as_stored() -> None: + service = FakeSimulationService() + + response = report_route_client(simulations=service).post( + "/v2/simulations?country_id=us", + json=simulation_body(dataset_name="enhanced_cps_2024"), + ) + + assert response.status_code == 201, response.text + assert response.json()["result"]["item"]["id"] == str(service.simulation.id) + ((operation, arguments),) = service.calls + assert operation == "create_simulation" + created = arguments["simulation_input"] + assert created.dataset_name == "enhanced_cps_2024" + assert created.policy_id == POLICY_ID + + +@pytest.mark.parametrize( + ("query", "body", "status_code"), + [ + ("country_id=uk", simulation_body(), 400), + ("country_id=us", simulation_body(kind="household"), 422), + ("country_id=us", simulation_body(year=1899), 422), + ("country_id=us", simulation_body(include_cliffs=True), 422), + ], + ids=["other-country", "household-kind", "year-too-early", "report-option"], +) +def test_a_malformed_simulation_is_refused_before_the_service( + query: str, body: dict[str, Any], status_code: int +) -> None: + service = FakeSimulationService() + + response = report_route_client(simulations=service).post( + f"/v2/simulations?{query}", json=body + ) + + assert response.status_code == status_code + assert service.calls == [] + + +@pytest.mark.parametrize( + ("error", "status_code"), + [ + (PolicyNotFoundError("Policy p was not found"), 404), + (EconomyCalculationsUnsupportedError("not available"), 422), + (SimulationServiceInvalidRequestError("no such dataset"), 422), + (SimulationServiceInternalError("failed"), 502), + (SimulationServiceAnswerUnreadableError("answer lost"), 502), + (SimulationServiceUnavailableError("unavailable"), 503), + ], + ids=["policy", "country", "refusal", "failure", "unreadable", "unavailable"], +) +def test_simulation_creation_failures_answer_typed_errors( + error: Exception, status_code: int +) -> None: + client = report_route_client(simulations=FakeSimulationService(error=error)) + + response = client.post("/v2/simulations?country_id=us", json=simulation_body()) + + assert response.status_code == status_code + assert response.json()["message"] == str(error) + + +def test_a_created_report_that_cannot_be_read_back_answers_its_id() -> None: + error = CreatedReportUnreadableError(report_id=REPORT_ID, country_id="us") + client = report_route_client(reports=FakeReportService(error=error)) + + response = client.post("/v2/reports?country_id=us", json=report_body()) + + assert response.status_code == 502 + assert response.json() == { + "status": "error", + "message": ( + f"The simulation service created report {REPORT_ID}, but it could " + f"not be read back. Read it with GET /v2/reports/{REPORT_ID}" + "?country_id=us rather than submitting it again." + ), + "report_id": str(REPORT_ID), + } + + +def test_a_created_simulation_that_cannot_be_read_back_answers_its_id() -> None: + simulation_id = FakeSimulationService().simulation.id + error = CreatedSimulationUnreadableError( + simulation_id=simulation_id, country_id="us" + ) + client = report_route_client(simulations=FakeSimulationService(error=error)) + + response = client.post("/v2/simulations?country_id=us", json=simulation_body()) + + assert response.status_code == 502 + assert response.json() == { + "status": "error", + "message": ( + f"The simulation service created simulation {simulation_id}, but it " + f"could not be read back. Read it with GET /v2/simulations/" + f"{simulation_id}?country_id=us rather than submitting it again." + ), + "simulation_id": str(simulation_id), + } + + +@pytest.mark.usefixtures("enabled_route_support_logger") +def test_a_report_the_unavailable_service_created_answers_its_id(caplog) -> None: + message = ( + f"The simulation service created report {REPORT_ID}, but is unavailable " + "(503 modal_call_refused)." + ) + error = SimulationServiceUnavailableError(message, created_record_id=REPORT_ID) + client = report_route_client(reports=FakeReportService(error=error)) + + with caplog.at_level("ERROR", logger=ROUTE_SUPPORT_LOGGER): + response = client.post("/v2/reports?country_id=us", json=report_body()) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": message, + "report_id": str(REPORT_ID), + } + assert logged_events(caplog) == ["v2_report_unavailable_after_creation"] + + +@pytest.mark.usefixtures("enabled_route_support_logger") +def test_a_simulation_the_unavailable_service_created_answers_its_id( + caplog, +) -> None: + simulation_id = FakeSimulationService().simulation.id + message = ( + f"The simulation service created simulation {simulation_id}, but is " + "unavailable (503 modal_call_refused)." + ) + error = SimulationServiceUnavailableError(message, created_record_id=simulation_id) + client = report_route_client(simulations=FakeSimulationService(error=error)) + + with caplog.at_level("ERROR", logger=ROUTE_SUPPORT_LOGGER): + response = client.post("/v2/simulations?country_id=us", json=simulation_body()) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": message, + "simulation_id": str(simulation_id), + } + assert logged_events(caplog) == ["v2_simulation_unavailable_after_creation"] + + +@pytest.mark.parametrize( + ("path", "status_code", "schema", "id_field"), + [ + pytest.param( + "/v2/reports", + "502", + "CreatedReportUnreadableResponse", + "report_id", + id="report-502", + ), + pytest.param( + "/v2/simulations", + "502", + "CreatedSimulationUnreadableResponse", + "simulation_id", + id="simulation-502", + ), + pytest.param( + "/v2/reports", + "503", + "UnavailableAfterReportCreatedResponse", + "report_id", + id="report-503", + ), + pytest.param( + "/v2/simulations", + "503", + "UnavailableAfterSimulationCreatedResponse", + "simulation_id", + id="simulation-503", + ), + ], +) +def test_the_openapi_document_gives_the_created_records_id( + path: str, status_code: str, schema: str, id_field: str +) -> None: + document = report_route_client().get("/v2/openapi.json").json() + + answer = document["paths"][path]["post"]["responses"][status_code] + assert {"$ref": f"#/components/schemas/{schema}"} in answer["content"][ + "application/json" + ]["schema"]["anyOf"] + assert document["components"]["schemas"][schema]["required"] == [ + "message", + id_field, + ] + + +@pytest.mark.parametrize( + "error_mappings", + [REPORT_ERROR_MAPPINGS, SIMULATION_ERROR_MAPPINGS], + ids=["reports", "simulations"], +) +def test_no_error_mapping_is_shadowed_by_an_earlier_one(error_mappings) -> None: + # The first matching mapping answers, so an error type an earlier mapping + # already matches would never get its own answer. + shadowed = [ + (error_type.__name__, mapping.message) + for position, mapping in enumerate(error_mappings) + for error_type in mapping.error_types + if any( + issubclass(error_type, earlier_type) + for earlier in error_mappings[:position] + for earlier_type in earlier.error_types + ) + ] + + assert shadowed == [] + + +@pytest.mark.parametrize( + ("client_for_error", "method", "path", "body"), + [ + pytest.param( + lambda error: report_route_client(reports=FakeReportService(error=error)), + "get", + f"/v2/reports/{REPORT_ID}?country_id=us", + None, + id="report-read", + ), + pytest.param( + lambda error: report_route_client(reports=FakeReportService(error=error)), + "post", + "/v2/reports?country_id=us", + report_body(), + id="report-create", + ), + pytest.param( + lambda error: report_route_client( + simulations=FakeSimulationService(error=error) + ), + "post", + "/v2/simulations?country_id=us", + simulation_body(), + id="simulation-create", + ), + ], +) +def test_missing_v2_database_configuration_is_storage_unavailable( + client_for_error, method: str, path: str, body: dict[str, Any] | None +) -> None: + client = client_for_error(V2ConfigurationError("V2_DATABASE_URL is not set")) + + response = client.request(method, path, json=body) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": "V2 storage is unavailable", + } + + +SIMULATION_SERVICE_URL = "https://simulation.example.test" +# The record the simulation service names in its answers, and another record. +NAMED_RECORD_ID = UUID("00000000-0000-0000-0000-00000000c001") +OTHER_RECORD_ID = UUID("00000000-0000-0000-0000-00000000c002") +# The field naming each record in the simulation service's answers. +RECORD_ID_FIELDS = {"report": "report_id", "simulation": "simulation_id"} +# The field naming a record other than the submission's own. +OTHER_RECORD_ID_FIELDS = {"report": "simulation_id", "simulation": "report_id"} +RECORDS = ["report", "simulation"] + + +class UnreadDatabase: + """The detailed-save database, which a failed submission never reads.""" + + def read(self) -> NoReturn: + msg = "The route read the database after the submission failed." + raise AssertionError(msg) + + +def answering( + status_code: int, body: object +) -> Callable[[httpx.Request], httpx.Response]: + """Answer every request with ``status_code`` and ``body``; bytes as they are.""" + + def answer(request: httpx.Request) -> httpx.Response: + if isinstance(body, bytes): + return httpx.Response(status_code, content=body) + return httpx.Response(status_code, json=body) + + return answer + + +def losing_the_answer(request: httpx.Request) -> httpx.Response: + """Fail as a read timeout does, after the request was sent.""" + msg = "the answer did not arrive" + raise httpx.ReadTimeout(msg, request=request) + + +def modal_refusal_naming(id_field: str, record_id: str) -> dict[str, str]: + """Return the simulation service's 503 after Modal refused, naming one record.""" + return { + "code": "modal_call_refused", + "detail": "Modal refused the call.", + id_field: record_id, + } + + +def post_through_simulation_service( + record: str, answer: Callable[[httpx.Request], httpx.Response] +) -> httpx.Response: + """Create ``record`` through the real client, its requests answered by ``answer``. + + The route's stored service sends through ``SimulationServiceReportClient`` + over a mock transport. + """ + submissions = SimulationServiceReportClient( + httpx.Client( + base_url=SIMULATION_SERVICE_URL, transport=httpx.MockTransport(answer) + ) + ) + client: TestClient + if record == "report": + client = report_route_client( + reports=V2StoredReportService( + UnreadDatabase(), + current_versions=lambda _country_id: CURRENT_VERSIONS, + submissions=submissions, + ) + ) + return client.post("/v2/reports?country_id=us", json=report_body()) + client = report_route_client( + simulations=V2StoredSimulationService( + UnreadDatabase(), + current_versions=lambda _country_id: CURRENT_VERSIONS, + submissions=submissions, + ) + ) + return client.post("/v2/simulations?country_id=us", json=simulation_body()) + + +# A reason holding stored data, as an exception's text can. +EXCEPTION_TEXT = ( + "psycopg.errors.UniqueViolation: Key (label)=(Private household plan) " + "already exists." +) +CREATED_BODIES = { + "report": { + "report_id": str(NAMED_RECORD_ID), + "report_run_id": str(OTHER_RECORD_ID), + }, + "simulation": { + "simulation_id": str(NAMED_RECORD_ID), + "simulation_run_id": str(OTHER_RECORD_ID), + }, +} + + +@pytest.mark.parametrize( + ("answer", "stated_error"), + [ + pytest.param(losing_the_answer, "ReadTimeout", id="answer-lost"), + pytest.param( + answering(502, b"Bad Gateway"), + "a proxy answered 502 in its place", + id="proxy-502", + ), + pytest.param( + answering(504, b"upstream request timeout"), + "a proxy answered 504 in its place", + id="proxy-504", + ), + ], +) +@pytest.mark.parametrize("record", RECORDS) +def test_an_answer_lost_after_sending_answers_502( + record: str, + answer: Callable[[httpx.Request], httpx.Response], + stated_error: str, +) -> None: + # The service may have received the request and created the record, so + # the answer is not a 503, which says it created nothing. + response = post_through_simulation_service(record, answer) + + assert response.status_code == 502 + assert response.json() == { + "status": "error", + "message": answer_lost_message(stated_error, record), + } + + +@pytest.mark.parametrize( + ("answer_for_record", "status_and_code"), + [ + pytest.param( + lambda _record: answering( + 500, + {"code": "internal_error", "detail": "The run could not be started."}, + ), + "500 internal_error", + id="500", + ), + pytest.param( + lambda _record: answering(500, {"detail": "The run could not be started."}), + "500", + id="500-without-a-code", + ), + pytest.param( + lambda _record: answering(500, b"Internal Server Error"), + "500", + id="unreadable-500", + ), + pytest.param( + lambda _record: answering( + 503, b"upstream connect error or disconnect/reset before headers" + ), + "503", + id="unreadable-503", + ), + pytest.param( + lambda _record: answering(503, {"code": "modal_call_refused"}), + "503 modal_call_refused", + id="503-without-detail", + ), + pytest.param( + lambda record: answering( + 503, modal_refusal_naming(RECORD_ID_FIELDS[record], "not-a-uuid") + ), + "503 modal_call_refused", + id="503-malformed-record-id", + ), + pytest.param( + lambda record: answering( + 503, + modal_refusal_naming( + OTHER_RECORD_ID_FIELDS[record], str(OTHER_RECORD_ID) + ), + ), + "503 modal_call_refused", + id="503-naming-only-another-record", + ), + pytest.param( + lambda record: answering(200, CREATED_BODIES[record]), + "200", + id="200-naming-the-record", + ), + pytest.param(lambda _record: answering(204, b""), "204", id="204"), + pytest.param( + lambda _record: answering( + 409, {"code": "label_taken", "detail": "The label is taken."} + ), + "409 label_taken", + id="409-with-a-code", + ), + ], +) +@pytest.mark.parametrize("record", RECORDS) +def test_a_failure_that_may_follow_a_created_record_answers_502( + record: str, + answer_for_record: Callable[[str], Callable[[httpx.Request], httpx.Response]], + status_and_code: str, +) -> None: + # The service's route may have written rows before answering each of + # these, so none is a 503, which says it created nothing. + response = post_through_simulation_service(record, answer_for_record(record)) + + assert response.status_code == 502 + assert response.json() == { + "status": "error", + "message": possibly_created_message(status_and_code, record), + } + + +@pytest.mark.parametrize("record", RECORDS) +def test_a_503_naming_the_created_record_answers_503_with_its_id(record: str) -> None: + id_field = RECORD_ID_FIELDS[record] + answer = answering(503, modal_refusal_naming(id_field, str(NAMED_RECORD_ID))) + + response = post_through_simulation_service(record, answer) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": ( + f"The simulation service created {record} {NAMED_RECORD_ID}, but is " + "unavailable (503 modal_call_refused)." + ), + id_field: str(NAMED_RECORD_ID), + } + + +@pytest.mark.parametrize("record", RECORDS) +def test_a_503_naming_both_records_answers_503_with_the_submissions_own_id( + record: str, +) -> None: + # A report's 503 may also name a simulation it created; the answer names + # the submission's own record. + id_field = RECORD_ID_FIELDS[record] + answer = answering( + 503, + { + **modal_refusal_naming(id_field, str(NAMED_RECORD_ID)), + OTHER_RECORD_ID_FIELDS[record]: str(OTHER_RECORD_ID), + }, + ) + + response = post_through_simulation_service(record, answer) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": ( + f"The simulation service created {record} {NAMED_RECORD_ID}, but is " + "unavailable (503 modal_call_refused)." + ), + id_field: str(NAMED_RECORD_ID), + } + + +@pytest.mark.parametrize("record", RECORDS) +def test_a_503_naming_no_record_answers_503(record: str) -> None: + answer = answering( + 503, + { + "code": "manifest_unavailable", + "detail": "The v2 version manifest could not be read.", + }, + ) + + response = post_through_simulation_service(record, answer) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": "The simulation service is unavailable (503 manifest_unavailable).", + } + + +@pytest.mark.parametrize("status_code", [401, 403, 404, 405, 413, 429]) +@pytest.mark.parametrize("record", RECORDS) +def test_a_status_sent_before_the_services_route_runs_answers_503( + record: str, status_code: int +) -> None: + # The gateway, Cloud Run or the service's framework answers these before + # the service's route runs, so nothing was created. + response = post_through_simulation_service( + record, answering(status_code, {"detail": "Not Found"}) + ) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": f"The simulation service is unavailable ({status_code}).", + } + + +@pytest.mark.parametrize( + ("status_code", "record_named", "answer_status"), + [ + pytest.param(500, None, 502, id="500"), + pytest.param(503, None, 503, id="503-naming-no-record"), + pytest.param(503, "own", 503, id="503-naming-the-record"), + pytest.param(503, "other", 502, id="503-naming-another-record"), + ], +) +@pytest.mark.parametrize("record", RECORDS) +def test_the_services_failure_reason_never_reaches_the_caller( + record: str, status_code: int, record_named: str | None, answer_status: int +) -> None: + # A 500's or 503's reason may be an exception's text holding stored data, + # which must not reach an anonymous caller. Only the code is passed on. + body = {"code": "internal_error", "detail": EXCEPTION_TEXT} + if record_named == "own": + body[RECORD_ID_FIELDS[record]] = str(NAMED_RECORD_ID) + if record_named == "other": + body[OTHER_RECORD_ID_FIELDS[record]] = str(OTHER_RECORD_ID) + + response = post_through_simulation_service(record, answering(status_code, body)) + + assert response.status_code == answer_status + assert f"({status_code} internal_error)" in response.json()["message"] + assert "Private household plan" not in response.text + assert "psycopg" not in response.text + + +@pytest.mark.parametrize( + ("status_code", "body", "answer_status", "message"), + [ + pytest.param( + 422, + {"detail": "spm settings apply only to the US"}, + 422, + "The simulation service cannot run this request: spm settings apply " + "only to the US", + id="422", + ), + pytest.param( + 400, + { + "code": "unknown_region", + "detail": "Region state/zz is not in the catalog version.", + }, + 422, + "The simulation service cannot run this request (unknown_region): " + "Region state/zz is not in the catalog version.", + id="400-for-the-callers-region", + ), + pytest.param( + 400, + { + "code": "unknown_catalog_version", + "detail": "Country us has no catalog version for .py 4.2.0.", + }, + 503, + "The simulation service refused the {record} (unknown_catalog_version): " + "Country us has no catalog version for .py 4.2.0.", + id="400-for-the-services-state", + ), + ], +) +@pytest.mark.parametrize("record", RECORDS) +def test_a_refusal_gives_the_services_code_and_reason_but_not_its_status( + record: str, + status_code: int, + body: dict[str, str], + answer_status: int, + message: str, +) -> None: + # A 400's or 422's code and reason are passed on, but not its status, + # since the route answers with its own. + response = post_through_simulation_service(record, answering(status_code, body)) + + assert response.status_code == answer_status + assert response.json() == { + "status": "error", + "message": message.format(record=record), + } + + +# Codes that are not a fixed identifier (lower-case letters, digits and +# underscores, starting with a letter, at most 64 characters), so a 500's or +# 503's message leaves them out. +CODES_LEFT_OUT = [ + pytest.param(EXCEPTION_TEXT, id="exception-text"), + pytest.param("", id="empty"), + pytest.param("Internal_Error", id="capital-letters"), + pytest.param("5xx_error", id="starting-with-a-digit"), + pytest.param("modal-call-refused", id="hyphenated"), + pytest.param("internal_error\n", id="ending-in-a-newline"), + pytest.param("a" * 65, id="65-characters"), +] + + +def without_a_code_answer( + record: str, status_code: int, record_named: str | None +) -> tuple[int, dict[str, str]]: + """Return the route's status and JSON for a failure whose code is left out.""" + if status_code != 503: + return 502, { + "status": "error", + "message": possibly_created_message(str(status_code), record), + } + if record_named is None: + return 503, { + "status": "error", + "message": "The simulation service is unavailable (503).", + } + return 503, { + "status": "error", + "message": ( + f"The simulation service created {record} {NAMED_RECORD_ID}, but is " + "unavailable (503)." + ), + RECORD_ID_FIELDS[record]: str(NAMED_RECORD_ID), + } + + +@pytest.mark.parametrize("code", CODES_LEFT_OUT) +@pytest.mark.parametrize( + ("status_code", "record_named"), + [ + pytest.param(500, None, id="500"), + pytest.param(409, None, id="unexpected-409"), + pytest.param(503, None, id="503-naming-no-record"), + pytest.param(503, "own", id="503-naming-the-record"), + ], +) +@pytest.mark.parametrize("record", RECORDS) +def test_a_code_that_is_not_a_fixed_identifier_is_left_out( + record: str, status_code: int, record_named: str | None, code: str +) -> None: + # A 500's or 503's code is passed on without its reason, so it must not + # carry what the reason could: an exception's text, holding stored data. + body = {"code": code, "detail": "The run failed."} + if record_named == "own": + body[RECORD_ID_FIELDS[record]] = str(NAMED_RECORD_ID) + + response = post_through_simulation_service(record, answering(status_code, body)) + + answer_status, answer = without_a_code_answer(record, status_code, record_named) + assert response.status_code == answer_status + assert response.json() == answer + + +@pytest.mark.parametrize( + "code", + [ + pytest.param("a" * 64, id="64-characters"), + pytest.param("modal_call_refused_2", id="letters-digits-and-underscores"), + ], +) +@pytest.mark.parametrize("record", RECORDS) +def test_a_code_that_is_a_fixed_identifier_is_passed_on(record: str, code: str) -> None: + answer = answering(503, {"code": code, "detail": "The run failed."}) + + response = post_through_simulation_service(record, answer) + + assert response.status_code == 503 + assert response.json() == { + "status": "error", + "message": f"The simulation service is unavailable (503 {code}).", + } diff --git a/tests/unit/v2/test_report_read_routes.py b/tests/unit/v2/test_report_read_routes.py new file mode 100644 index 000000000..5076ff51c --- /dev/null +++ b/tests/unit/v2/test_report_read_routes.py @@ -0,0 +1,225 @@ +"""Read v2 reports and simulations over stand-in services.""" + +from __future__ import annotations + +import json +from dataclasses import replace +from uuid import uuid4 + +import pytest + +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + EconomyResultUnreadableError, +) +from policyengine_api.services.v2.stored_reports.validators import ( + ReportKindUnsupportedError, + ReportStorageError, + StoredReportNotFoundError, +) +from policyengine_api.services.v2.stored_simulations.validators import ( + SimulationStorageError, + StoredSimulationNotFoundError, +) +from tests.fixtures.economy_results import us_economy_result +from tests.unit.v2.stored_report_support import ( + REPORT_ID, + FakeReportService, + FakeSimulationService, + report_route_client, + report_summary_read, +) + + +def test_a_report_answers_its_definition_newest_run_versions_and_result() -> None: + service = FakeReportService() + client = report_route_client(reports=service) + + response = client.get(f"/v2/reports/{REPORT_ID}?country_id=us") + + assert response.status_code == 200 + body = response.json() + assert body["status"] == "ok" + assert body["message"] is None + item = body["result"]["item"] + assert item["result"] == json.loads(json.dumps(us_economy_result())) + assert item["run"]["country_package_version"] == "1.4.0" + assert item["run"]["policyengine_version"] == "4.1.0" + assert item["current_versions"] == { + "country_package_version": "1.5.0", + "policyengine_version": "4.2.0", + } + assert item["reform_simulation"]["policy_id"] is not None + assert service.calls == [ + ("get_report", {"country_id": "us", "report_id": REPORT_ID}) + ] + + +def test_a_reports_spm_receipts_are_answered_with_package_names_as_keys() -> None: + client = report_route_client(reports=FakeReportService()) + + item = client.get(f"/v2/reports/{REPORT_ID}?country_id=us").json()["result"]["item"] + + receipts = item["result"]["spm_provenance"] + assert receipts == json.loads(json.dumps(us_economy_result()["spm_provenance"])) + assert set(receipts["baseline"]["receipt"]["runtime_versions"]) == { + "policyengine", + "policyengine-core", + "policyengine-us", + "spm-calculator", + } + + +def test_a_report_without_a_run_answers_with_no_run_and_no_result() -> None: + service = FakeReportService() + service.report = replace(service.report, status="not_run", run=None, result=None) + + item = ( + report_route_client(reports=service) + .get(f"/v2/reports/{REPORT_ID}?country_id=us") + .json()["result"]["item"] + ) + + assert item["status"] == "not_run" + assert item["run"] is None + assert item["result"] is None + + +@pytest.mark.parametrize( + ("error", "status_code", "message"), + [ + ( + StoredReportNotFoundError("Report x was not found in country 'us'"), + 404, + "Report x was not found in country 'us'", + ), + ( + ReportKindUnsupportedError("Report x is a household report"), + 422, + "Report x is a household report", + ), + ( + EconomyResultUnreadableError("the budget summary has no household_tax row"), + 500, + "The report's stored result cannot be read", + ), + ( + ReportStorageError("V2 report storage is unavailable"), + 503, + "V2 report storage is unavailable", + ), + (RuntimeError("unexpected"), 500, "V2 report operation failed"), + ], + ids=["not-found", "other-kind", "unreadable-result", "storage", "unexpected"], +) +def test_report_read_failures_answer_typed_errors( + error: Exception, status_code: int, message: str +) -> None: + client = report_route_client(reports=FakeReportService(error=error)) + + response = client.get(f"/v2/reports/{REPORT_ID}?country_id=us") + + assert response.status_code == status_code + assert response.json() == {"status": "error", "message": message} + + +def test_a_report_read_needs_a_country() -> None: + response = report_route_client(reports=FakeReportService()).get( + f"/v2/reports/{REPORT_ID}" + ) + + assert response.status_code == 422 + + +def test_listing_passes_the_named_reports_in_order_and_answers_without_results() -> ( + None +): + first, second = uuid4(), uuid4() + service = FakeReportService( + listed=(report_summary_read(id=second), report_summary_read(id=first)) + ) + client = report_route_client(reports=service) + + response = client.get( + f"/v2/reports?country_id=us&report_id={second}&report_id={first}" + ) + + assert response.status_code == 200 + items = response.json()["result"]["items"] + assert [item["id"] for item in items] == [str(second), str(first)] + assert all("result" not in item for item in items) + assert service.calls == [ + ("list_reports", {"country_id": "us", "report_ids": [second, first]}) + ] + + +@pytest.mark.parametrize( + "query", + [ + "country_id=us", + "country_id=us&" + "&".join(f"report_id={uuid4()}" for _ in range(26)), + f"country_id=us&report_id={uuid4()}&unknown=1", + "country_id=us&report_id=not-a-uuid", + ], + ids=["no-report", "more-than-25", "unknown-parameter", "malformed-id"], +) +def test_listing_refuses_a_malformed_query(query: str) -> None: + service = FakeReportService() + + response = report_route_client(reports=service).get(f"/v2/reports?{query}") + + assert response.status_code == 422 + assert service.calls == [] + + +def test_listing_twenty_five_reports_is_allowed() -> None: + service = FakeReportService() + query = "&".join(f"report_id={uuid4()}" for _ in range(25)) + + response = report_route_client(reports=service).get( + f"/v2/reports?country_id=uk&{query}" + ) + + assert response.status_code == 200 + assert len(service.calls[0][1]["report_ids"]) == 25 + + +def test_a_simulation_answers_its_definition_newest_run_and_versions() -> None: + service = FakeSimulationService() + simulation_id = service.simulation.id + + response = report_route_client(simulations=service).get( + f"/v2/simulations/{simulation_id}?country_id=us" + ) + + assert response.status_code == 200 + item = response.json()["result"]["item"] + assert item["id"] == str(simulation_id) + assert item["kind"] == "economy" + assert item["status"] == "pending" + assert item["run"]["policyengine_version"] == "4.2.0" + assert item["current_versions"]["country_package_version"] == "1.5.0" + assert service.calls == [ + ( + "get_simulation", + {"country_id": "us", "simulation_id": simulation_id}, + ) + ] + + +@pytest.mark.parametrize( + ("error", "status_code"), + [ + (StoredSimulationNotFoundError("Simulation x was not found"), 404), + (SimulationStorageError("V2 simulation storage is unavailable"), 503), + ], + ids=["not-found", "storage"], +) +def test_simulation_read_failures_answer_typed_errors( + error: Exception, status_code: int +) -> None: + client = report_route_client(simulations=FakeSimulationService(error=error)) + + response = client.get(f"/v2/simulations/{uuid4()}?country_id=us") + + assert response.status_code == status_code + assert response.json()["status"] == "error" diff --git a/tests/unit/v2/test_saved_detailed_save_references.py b/tests/unit/v2/test_saved_detailed_save_references.py new file mode 100644 index 000000000..0cc8f19a3 --- /dev/null +++ b/tests/unit/v2/test_saved_detailed_save_references.py @@ -0,0 +1,308 @@ +"""Saved reports and simulations name a detailed-save record or a v1 one.""" + +from __future__ import annotations + +from types import SimpleNamespace +from typing import TYPE_CHECKING, cast +from uuid import uuid4 + +import pytest +from pydantic import ValidationError +from sqlalchemy.exc import IntegrityError + +from policyengine_api.data.v2.models import ( + UserReportAssociation, + UserSimulationAssociation, +) +from policyengine_api.services.v2.associations.validators import ( + AssociationReferenceConflictError, + require_one_reference, + violates_foreign_key, +) +from policyengine_api.services.v2.user_reports.database_connectors.creates import ( + create_user_report, +) +from policyengine_api.services.v2.user_reports.database_connectors.updates import ( + update_user_report, +) +from policyengine_api.services.v2.user_reports.types import ( + UserReportCreateFields, + UserReportCreationInput, + UserReportUpdateInput, +) +from policyengine_api.services.v2.user_reports.validators import ( + AssociationReportNotFoundError, +) +from policyengine_api.services.v2.user_simulations.database_connectors.creates import ( + create_user_simulation, +) +from policyengine_api.services.v2.user_simulations.database_connectors.updates import ( + update_user_simulation, +) +from policyengine_api.services.v2.user_simulations.types import ( + UserSimulationCreateFields, + UserSimulationCreationInput, + UserSimulationUpdateInput, +) +from policyengine_api.services.v2.user_simulations.validators import ( + AssociationSimulationNotFoundError, +) +from tests.unit.v2.user_route_support import user_route_client + +if TYPE_CHECKING: + from uuid import UUID + + from sqlmodel import Session + +REPORT_KEY = "fk_user_report_associations_report_id_reports" +SIMULATION_KEY = "fk_user_simulation_associations_simulation_id_simulations" +# Another foreign key of the same rows, which the write's checks don't cover. +SAVED_REPORT_OWNER_KEY = "fk_user_report_associations_user_id_users" +SAVED_SIMULATION_OWNER_KEY = "fk_user_simulation_associations_user_id_users" + + +def integrity_error(sqlstate: str, constraint_name: str | None) -> IntegrityError: + """Return an IntegrityError as psycopg reports one, with its SQLSTATE.""" + driver_error = SimpleNamespace( + sqlstate=sqlstate, diag=SimpleNamespace(constraint_name=constraint_name) + ) + return IntegrityError("INSERT", {}, driver_error) + + +def test_a_saved_report_names_a_detailed_save_report_or_a_v1_report() -> None: + report_id = uuid4() + + by_report = UserReportCreateFields(country_id="us", report_id=report_id) + by_number = UserReportCreateFields(country_id="us", legacy_report_id=615) + + assert (by_report.report_id, by_report.legacy_report_id) == (report_id, None) + assert (by_number.report_id, by_number.legacy_report_id) == (None, 615) + with pytest.raises(ValidationError, match="report_id or legacy_report_id"): + UserReportCreateFields(country_id="us") + + +def test_a_saved_simulation_names_a_detailed_save_simulation_or_a_v1_one() -> None: + simulation_id = uuid4() + + saved = UserSimulationCreateFields(country_id="uk", simulation_id=simulation_id) + + assert saved.simulation_id == simulation_id + assert saved.legacy_simulation_id is None + with pytest.raises(ValidationError, match="simulation_id or legacy_simulation_id"): + UserSimulationCreateFields(country_id="uk") + + +@pytest.mark.parametrize( + ("model", "field"), + [ + (UserReportUpdateInput, "report_id"), + (UserSimulationUpdateInput, "simulation_id"), + ], + ids=["report", "simulation"], +) +def test_a_detailed_save_reference_cannot_be_cleared(model: type, field: str) -> None: + with pytest.raises(ValidationError, match=f"{field} must not be null"): + model(**{field: None}) + + +def test_naming_both_references_is_a_conflict() -> None: + with pytest.raises(AssociationReferenceConflictError, match="not both"): + require_one_reference("report", detailed_save_id=uuid4(), legacy_id=615) + require_one_reference("report", detailed_save_id=uuid4(), legacy_id=None) + require_one_reference("report", detailed_save_id=None, legacy_id=615) + + +def test_only_the_named_foreign_key_violation_counts() -> None: + assert violates_foreign_key(integrity_error("23503", REPORT_KEY), REPORT_KEY) + assert not violates_foreign_key( + integrity_error("23503", "fk_user_report_associations_user_id_users"), + REPORT_KEY, + ) + assert not violates_foreign_key(integrity_error("23505", REPORT_KEY), REPORT_KEY) + + +class RefusingFlushSession: + """A session whose flush fails with ``error``, as PostgreSQL refusing a write.""" + + def __init__(self, error: IntegrityError) -> None: + self.error = error + + def add(self, _row: object) -> None: + """Accept the row; the database refuses it at flush.""" + + def flush(self) -> None: + raise self.error + + def refresh(self, _row: object) -> None: + msg = "a refused write is never read back" + raise AssertionError(msg) + + +def refusing_session(sqlstate: str, constraint_name: str) -> Session: + """Return a session whose flush fails with that SQLSTATE on that constraint.""" + return cast( + "Session", RefusingFlushSession(integrity_error(sqlstate, constraint_name)) + ) + + +def save_report(session: Session, *, operation: str, report_id: UUID) -> None: + """Save a new report naming ``report_id``, or repoint a saved one to it.""" + if operation == "create": + create_user_report( + session, + UserReportCreationInput( + country_id="us", user_id=uuid4(), report_id=report_id + ), + ) + return + saved = UserReportAssociation(user_id=uuid4(), country_id="us", report_id=uuid4()) + update_user_report(session, saved, {"report_id": report_id}) + + +def save_simulation(session: Session, *, operation: str, simulation_id: UUID) -> None: + """Save a new simulation naming ``simulation_id``, or repoint a saved one.""" + if operation == "create": + create_user_simulation( + session, + UserSimulationCreationInput( + country_id="uk", user_id=uuid4(), simulation_id=simulation_id + ), + ) + return + saved = UserSimulationAssociation( + user_id=uuid4(), country_id="uk", simulation_id=uuid4() + ) + update_user_simulation( + session, saved, UserSimulationUpdateInput(simulation_id=simulation_id) + ) + + +@pytest.mark.parametrize("operation", ["create", "update"]) +def test_a_report_deleted_before_the_saved_report_is_written_is_not_found( + operation: str, +) -> None: + report_id = uuid4() + + with pytest.raises( + AssociationReportNotFoundError, + match=f"Report {report_id} was not found in country 'us'", + ) as raised: + save_report( + refusing_session("23503", REPORT_KEY), + operation=operation, + report_id=report_id, + ) + + assert isinstance(raised.value.__cause__, IntegrityError) + + +@pytest.mark.parametrize("operation", ["create", "update"]) +def test_a_simulation_deleted_before_the_saved_one_is_written_is_not_found( + operation: str, +) -> None: + simulation_id = uuid4() + + with pytest.raises( + AssociationSimulationNotFoundError, + match=f"Simulation {simulation_id} was not found in country 'uk'", + ) as raised: + save_simulation( + refusing_session("23503", SIMULATION_KEY), + operation=operation, + simulation_id=simulation_id, + ) + + assert isinstance(raised.value.__cause__, IntegrityError) + + +@pytest.mark.parametrize("operation", ["create", "update"]) +@pytest.mark.parametrize( + ("sqlstate", "constraint_name"), + [("23503", SAVED_REPORT_OWNER_KEY), ("23505", REPORT_KEY)], + ids=["owner-key", "not-a-foreign-key-violation"], +) +def test_a_saved_reports_other_integrity_errors_are_raised_unchanged( + operation: str, sqlstate: str, constraint_name: str +) -> None: + with pytest.raises(IntegrityError): + save_report( + refusing_session(sqlstate, constraint_name), + operation=operation, + report_id=uuid4(), + ) + + +@pytest.mark.parametrize("operation", ["create", "update"]) +@pytest.mark.parametrize( + ("sqlstate", "constraint_name"), + [("23503", SAVED_SIMULATION_OWNER_KEY), ("23505", SIMULATION_KEY)], + ids=["owner-key", "not-a-foreign-key-violation"], +) +def test_a_saved_simulations_other_integrity_errors_are_raised_unchanged( + operation: str, sqlstate: str, constraint_name: str +) -> None: + with pytest.raises(IntegrityError): + save_simulation( + refusing_session(sqlstate, constraint_name), + operation=operation, + simulation_id=uuid4(), + ) + + +class RefusingReports: + """A saved-report service that raises ``error`` on create.""" + + def __init__(self, error: Exception) -> None: + self.error = error + + def create_user_report(self, **_arguments: object) -> object: + raise self.error + + +class RefusingSimulations: + """A saved-simulation service that raises ``error`` on create.""" + + def __init__(self, error: Exception) -> None: + self.error = error + + def create_user_simulation(self, **_arguments: object) -> object: + raise self.error + + +@pytest.mark.parametrize( + ("error", "status_code"), + [ + (AssociationReportNotFoundError("Report r was not found in 'us'"), 404), + (AssociationReferenceConflictError("not both"), 400), + ], + ids=["missing-report", "both-references"], +) +def test_saved_report_reference_failures_answer_their_status( + error: Exception, status_code: int +) -> None: + client, _flask_calls = user_route_client( + v2_user_report_service_factory=lambda: RefusingReports(error) + ) + + response = client.post( + "/v2/user-reports?country_id=us", + json={"country_id": "us", "report_id": str(uuid4())}, + ) + + assert response.status_code == status_code + assert response.json() == {"status": "error", "message": str(error)} + + +def test_a_saved_simulation_naming_a_missing_simulation_is_not_found() -> None: + error = AssociationSimulationNotFoundError("Simulation s was not found") + client, _flask_calls = user_route_client( + v2_user_simulation_service_factory=lambda: RefusingSimulations(error) + ) + + response = client.post( + "/v2/user-simulations?country_id=us", + json={"country_id": "us", "simulation_id": str(uuid4())}, + ) + + assert response.status_code == 404 + assert response.json()["message"] == str(error) diff --git a/tests/unit/v2/test_shared_report_routes.py b/tests/unit/v2/test_shared_report_routes.py index 2bf23f22a..9409f7233 100644 --- a/tests/unit/v2/test_shared_report_routes.py +++ b/tests/unit/v2/test_shared_report_routes.py @@ -39,6 +39,7 @@ def _shared_report_read() -> SharedUserReportRead: return SharedUserReportRead( id=REPORT_ASSOCIATION_ID, country_id="us", + report_id=None, legacy_report_id=615, name="CTC report", source_note="from chat", @@ -76,6 +77,7 @@ def test_anyone_reads_a_saved_report_by_its_link_without_the_owner() -> None: "item": { "id": str(REPORT_ASSOCIATION_ID), "country_id": "us", + "report_id": None, "legacy_report_id": 615, "name": "CTC report", "source_note": "from chat", diff --git a/tests/unit/v2/test_simulation_submissions.py b/tests/unit/v2/test_simulation_submissions.py new file mode 100644 index 000000000..b6e22bd33 --- /dev/null +++ b/tests/unit/v2/test_simulation_submissions.py @@ -0,0 +1,197 @@ +"""Check simulations and reports before the simulation service creates them.""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from typing import Any +from uuid import UUID, uuid4 + +import pytest + +from policyengine_api.services.v2.countries.types import CountryRead +from policyengine_api.services.v2.policies.validators import PolicyNotFoundError +from policyengine_api.services.v2.simulation_service.services import ( + SimulationSubmissionService, +) +from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + SubmittedReport, + SubmittedSimulation, +) +from policyengine_api.services.v2.simulation_service.validators import ( + EconomyCalculationsUnsupportedError, +) + +STORED_POLICY_ID = UUID("00000000-0000-0000-0000-00000000c001") +OTHER_POLICY_ID = UUID("00000000-0000-0000-0000-00000000c002") +SERVED_COUNTRIES = [ + CountryRead(id="uk", household_enabled=True, society_wide_enabled=True), + CountryRead(id="us", household_enabled=True, society_wide_enabled=True), +] +# The UK as a household-only country, with no economy calculations. +HOUSEHOLD_ONLY_UK = [ + CountryRead(id="uk", household_enabled=True, society_wide_enabled=False), + CountryRead(id="us", household_enabled=True, society_wide_enabled=True), +] + + +@dataclass +class StoredCountries: + countries: list[CountryRead] = field(default_factory=lambda: SERVED_COUNTRIES) + + def list_countries(self) -> list[CountryRead]: + return self.countries + + +@dataclass +class StoredPolicies: + """The stored policies: only STORED_POLICY_ID, in the US and the UK.""" + + asked: list[tuple[str, UUID]] = field(default_factory=list) + + def get_policy(self, *, country_id: str, policy_id: UUID) -> Any: + self.asked.append((country_id, policy_id)) + if policy_id != STORED_POLICY_ID: + msg = f"Policy {policy_id} was not found" + raise PolicyNotFoundError(msg) + return object() + + +@dataclass +class RecordingSimulationService: + """The simulation service's client, recording what it is sent.""" + + reports: list[EconomyReportCreationInput] = field(default_factory=list) + simulations: list[EconomySimulationCreationInput] = field(default_factory=list) + + def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: + self.reports.append(report) + return SubmittedReport(report_id=uuid4(), report_run_id=uuid4()) + + def submit_simulation( + self, simulation: EconomySimulationCreationInput + ) -> SubmittedSimulation: + self.simulations.append(simulation) + return SubmittedSimulation(simulation_id=uuid4(), simulation_run_id=uuid4()) + + +def unconfigured_client() -> RecordingSimulationService: + msg = "the simulation service must not be asked" + raise AssertionError(msg) + + +def report_input(**changes: Any) -> EconomyReportCreationInput: + values: dict[str, Any] = { + "country_id": "us", + "kind": "economy", + "label": "Reform", + "year": 2026, + "region_code": "us", + "baseline": {}, + "reform": {"policy_id": str(STORED_POLICY_ID)}, + } + return EconomyReportCreationInput.model_validate({**values, **changes}) + + +def simulation_input(**changes: Any) -> EconomySimulationCreationInput: + values: dict[str, Any] = { + "country_id": "uk", + "kind": "economy", + "year": 2026, + "region_code": "uk", + "policy_id": str(STORED_POLICY_ID), + } + return EconomySimulationCreationInput.model_validate({**values, **changes}) + + +def submissions( + client_factory: Any, policies: StoredPolicies | None = None +) -> SimulationSubmissionService: + return SimulationSubmissionService( + countries=StoredCountries(), + policies=policies or StoredPolicies(), + client_factory=client_factory, + ) + + +def test_a_report_is_sent_once_its_country_and_policies_are_checked() -> None: + client = RecordingSimulationService() + policies = StoredPolicies() + report = report_input( + baseline={"policy_id": str(STORED_POLICY_ID)}, + reform={"policy_id": str(STORED_POLICY_ID)}, + ) + + submitted = submissions(lambda: client, policies).submit_report(report) + + assert client.reports == [report] + assert isinstance(submitted, SubmittedReport) + assert policies.asked == [("us", STORED_POLICY_ID)] + + +def test_current_law_needs_no_stored_policy() -> None: + client = RecordingSimulationService() + policies = StoredPolicies() + + submissions(lambda: client, policies).submit_report( + report_input(reform={"dynamic_id": str(uuid4())}) + ) + + assert policies.asked == [] + assert len(client.reports) == 1 + + +def test_a_household_only_country_is_refused_before_sending() -> None: + service = SimulationSubmissionService( + countries=StoredCountries(countries=HOUSEHOLD_ONLY_UK), + policies=StoredPolicies(), + client_factory=unconfigured_client, + ) + + with pytest.raises(EconomyCalculationsUnsupportedError, match="'uk'"): + service.submit_report(report_input(country_id="uk")) + with pytest.raises(EconomyCalculationsUnsupportedError, match="'uk'"): + service.submit_simulation(simulation_input(country_id="uk")) + + +def test_a_country_without_a_countries_row_is_refused() -> None: + service = SimulationSubmissionService( + countries=StoredCountries(countries=SERVED_COUNTRIES[:1]), + policies=StoredPolicies(), + client_factory=unconfigured_client, + ) + + with pytest.raises(EconomyCalculationsUnsupportedError, match="'us'"): + service.submit_report(report_input()) + + +@pytest.mark.parametrize("side", ["baseline", "reform"]) +def test_a_report_naming_a_policy_not_stored_in_the_country_is_refused( + side: str, +) -> None: + service = submissions(unconfigured_client) + + with pytest.raises(PolicyNotFoundError, match=str(OTHER_POLICY_ID)): + service.submit_report( + report_input(**{side: {"policy_id": str(OTHER_POLICY_ID)}}) + ) + + +def test_a_simulation_is_sent_once_its_country_and_policy_are_checked() -> None: + client = RecordingSimulationService() + policies = StoredPolicies() + simulation = simulation_input() + + submitted = submissions(lambda: client, policies).submit_simulation(simulation) + + assert client.simulations == [simulation] + assert isinstance(submitted, SubmittedSimulation) + assert policies.asked == [("uk", STORED_POLICY_ID)] + + +def test_a_simulation_naming_a_policy_not_stored_is_refused() -> None: + service = submissions(unconfigured_client) + + with pytest.raises(PolicyNotFoundError): + service.submit_simulation(simulation_input(policy_id=str(OTHER_POLICY_ID))) diff --git a/tests/unit/v2/test_stored_resource_storage_failures.py b/tests/unit/v2/test_stored_resource_storage_failures.py new file mode 100644 index 000000000..4d688fde3 --- /dev/null +++ b/tests/unit/v2/test_stored_resource_storage_failures.py @@ -0,0 +1,134 @@ +"""A failed database read in the report and simulation services is a typed error.""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING, Any +from uuid import uuid4 + +import pytest +from sqlalchemy.exc import OperationalError + +from policyengine_api.services.v2.simulation_service.types import ( + EconomyReportCreationInput, + EconomySimulationCreationInput, + SubmittedReport, + SubmittedSimulation, +) +from policyengine_api.services.v2.stored_reports.services import V2StoredReportService +from policyengine_api.services.v2.stored_reports.validators import ( + CreatedReportUnreadableError, + ReportStorageError, +) +from policyengine_api.services.v2.stored_simulations.services import ( + V2StoredSimulationService, +) +from policyengine_api.services.v2.stored_simulations.validators import ( + CreatedSimulationUnreadableError, + SimulationStorageError, +) +from tests.unit.v2.stored_report_support import ( + CURRENT_VERSIONS, + REPORT_ID, + REPORT_RUN_ID, + SIMULATION_RUN_ID, +) + +CREATED_SIMULATION_ID = uuid4() + +if TYPE_CHECKING: + from collections.abc import Iterator + + +CONNECTION_REFUSED = OperationalError( + "SELECT 1", {}, ConnectionRefusedError("connection refused") +) + + +class UnreachableDatabase: + """A database session whose reads fail as an unreachable database's do.""" + + @contextmanager + def read(self) -> Iterator[Any]: + raise CONNECTION_REFUSED + yield + + +def test_report_reads_raise_a_storage_error_when_the_database_fails() -> None: + service = V2StoredReportService( + UnreachableDatabase(), + current_versions=lambda country_id: CURRENT_VERSIONS, + ) + + with pytest.raises(ReportStorageError): + service.get_report(country_id="us", report_id=uuid4()) + with pytest.raises(ReportStorageError): + service.list_reports(country_id="us", report_ids=[uuid4()]) + + +def test_simulation_reads_raise_a_storage_error_when_the_database_fails() -> None: + service = V2StoredSimulationService( + UnreachableDatabase(), + current_versions=lambda country_id: CURRENT_VERSIONS, + ) + + with pytest.raises(SimulationStorageError): + service.get_simulation(country_id="us", simulation_id=uuid4()) + + +class CreatingSimulationService: + """The simulation service, answering that it created each submission.""" + + def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: + return SubmittedReport(report_id=REPORT_ID, report_run_id=REPORT_RUN_ID) + + def submit_simulation( + self, simulation: EconomySimulationCreationInput + ) -> SubmittedSimulation: + return SubmittedSimulation( + simulation_id=CREATED_SIMULATION_ID, simulation_run_id=SIMULATION_RUN_ID + ) + + +def test_a_created_report_the_database_cannot_read_back_is_named() -> None: + # The simulation service created the report, so the caller must get its + # ID rather than an answer that invites submitting it again. + service = V2StoredReportService( + UnreachableDatabase(), + current_versions=lambda country_id: CURRENT_VERSIONS, + submissions=CreatingSimulationService(), + ) + + with pytest.raises(CreatedReportUnreadableError) as unreadable: + service.create_report( + EconomyReportCreationInput( + country_id="us", + kind="economy", + label="Expanded child tax credit", + year=2026, + region_code="us", + baseline={}, + reform={}, + ) + ) + + assert unreadable.value.report_id == REPORT_ID + assert isinstance(unreadable.value.__cause__, ReportStorageError) + + +def test_a_created_simulation_the_database_cannot_read_back_is_named() -> None: + service = V2StoredSimulationService( + UnreachableDatabase(), + current_versions=lambda country_id: CURRENT_VERSIONS, + submissions=CreatingSimulationService(), + ) + + with pytest.raises(CreatedSimulationUnreadableError) as unreadable: + service.create_simulation( + EconomySimulationCreationInput( + country_id="us", kind="economy", year=2026, region_code="us" + ) + ) + + assert unreadable.value.simulation_id == CREATED_SIMULATION_ID + assert isinstance(unreadable.value.__cause__, SimulationStorageError) diff --git a/tests/unit/v2/test_user_simulation_report_routes.py b/tests/unit/v2/test_user_simulation_report_routes.py index 9a5aca120..08279e8ae 100644 --- a/tests/unit/v2/test_user_simulation_report_routes.py +++ b/tests/unit/v2/test_user_simulation_report_routes.py @@ -157,7 +157,7 @@ def _clients(): return client, simulations, reports -def test_simulation_routes_require_v1_references_and_scope_to_the_user() -> None: +def test_simulation_routes_take_either_reference_and_scope_to_the_user() -> None: client, simulations, _reports = _clients() created = client.post( @@ -189,18 +189,23 @@ def test_simulation_routes_require_v1_references_and_scope_to_the_user() -> None "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:01Z", } - assert v2_reference.status_code == 422 + assert v2_reference.status_code == 201 assert listed.status_code == 200 assert patched.status_code == 200 assert deleted.status_code == 204 assert [call[0] for call in simulations.calls] == [ + "create_user_simulation", "create_user_simulation", "list_user_simulations", "patch_user_simulation", "delete_user_simulation", ] assert all(call[1]["principal"] == PRINCIPAL for call in simulations.calls) - assert simulations.calls[1][1]["legacy_simulation_id"] == 613 + assert ( + simulations.calls[1][1]["association_input"].simulation_id + == SIMULATION_ASSOCIATION_ID + ) + assert simulations.calls[2][1]["legacy_simulation_id"] == 613 def test_report_routes_round_trip_v3_fields() -> None: @@ -243,7 +248,6 @@ def test_report_routes_round_trip_v3_fields() -> None: @pytest.mark.parametrize( "changes", [ - {"report_id": str(REPORT_ASSOCIATION_ID)}, {"legacy_report_id": None}, {"user_id": str(OWNER_ID)}, {"last_run_at": "2026-02-01T12:00:00"},