diff --git a/.github/scripts/simulation-staging-economy-check.sh b/.github/scripts/simulation-staging-economy-check.sh index 6f420c2fb..1fa60fecb 100755 --- a/.github/scripts/simulation-staging-economy-check.sh +++ b/.github/scripts/simulation-staging-economy-check.sh @@ -2,10 +2,13 @@ # Send a small economy report request through a deployed Simulation # Entrypoint, force a new run of the report, and require that run to succeed: # current law against current law for Wales in 2026, which needs no stored -# policy. The request reuses the simulation runs an earlier check on the same -# versions calculated (and, once reports are found by key, ends on that -# check's report run), so only a forced run, which nothing joins or reuses, -# calculates both simulations on every deploy. +# policy, on the bundle's local-area dataset (data_source), so the run also +# calculates Wales's constituencies and local authorities. The coordinator +# fails a run of such a report unless both area levels have rows or withheld +# codes, so its success covers them. The request reuses the simulation runs +# an earlier check on the same versions calculated (and, once reports are +# found by key, ends on that check's report run), so only a forced run, which +# nothing joins or reuses, calculates both simulations on every deploy. # Usage: simulation-staging-economy-check.sh # Required env vars: the test client's SIMULATION_TEST_AUTH_ISSUER, # SIMULATION_TEST_AUTH_AUDIENCE, SIMULATION_TEST_AUTH_CLIENT_ID and @@ -80,7 +83,8 @@ submission_status="$( region_code: "country/wales", baseline: {policy_id: null, dynamic_id: null}, reform: {policy_id: null, dynamic_id: null}, - include_cliffs: false + include_cliffs: false, + data_source: "local_area_dataset" }' \ | send submission "${submission_timeout_seconds}" --request POST --header "@${authorization_header}" \ --header 'Content-Type: application/json' --data @- \ diff --git a/changelog.d/c1-29a-data-source.added.md b/changelog.d/c1-29a-data-source.added.md new file mode 100644 index 000000000..c71fbd40c --- /dev/null +++ b/changelog.d/c1-29a-data-source.added.md @@ -0,0 +1 @@ +`POST /reports` takes `data_source: "local_area_dataset"` on UK-wide and nation economy reports: the report runs on the bundle's local-area dataset (the one constituency and local-authority regions use) and returns its full results with its constituency and local-authority results. Another value, another country or region, and a release that routes those areas to no dataset of their own (`no_local_area_dataset`) are refused with 422. The staging economy check's Wales report runs on that dataset. diff --git a/changelog.d/c1-29a-no-dataset-name.removed.md b/changelog.d/c1-29a-no-dataset-name.removed.md new file mode 100644 index 000000000..5a7911579 --- /dev/null +++ b/changelog.d/c1-29a-no-dataset-name.removed.md @@ -0,0 +1 @@ +`POST /reports` (economy reports and budget windows) and `POST /simulations` no longer take `dataset_name`, and refuse it with 422: a report or simulation runs on the dataset the catalog gives its region, or on the local-area dataset with `data_source`. The Public API stopped sending it in PolicyEngine/policyengine-api#4307, which must be deployed first. diff --git a/libs/policyengine-simulation-persistence/README.md b/libs/policyengine-simulation-persistence/README.md index 46106b720..cdd29d74a 100644 --- a/libs/policyengine-simulation-persistence/README.md +++ b/libs/policyengine-simulation-persistence/README.md @@ -87,12 +87,15 @@ runs too long and the limit never stays on a pooled connection. run writes for an economy report, or a standalone economy simulation. It reads the country's model (`read_model_id`) and a catalog version's region by code (`read_region`) and dataset by name or ID (`read_dataset`, -`read_dataset_by_id`), and builds a simulation run `pending` with no Modal -call ID (`simulation_run_row`, `insert_simulation_run`). The Simulation -Entrypoint creates every simulation, report and run by key ("Shared -simulations, reports and runs" below). A row naming one that does not exist -is refused by its foreign key with SQLSTATE `23503`; -`EconomyRecordReferenceError` names the table and column. +`read_dataset_by_id`), and its local-area dataset +(`read_local_area_dataset`): the one default dataset every constituency and +local-authority region of the version uses, or none. It builds a simulation +run `pending` with no Modal call ID (`simulation_run_row`, +`insert_simulation_run`). The Simulation Entrypoint creates every +simulation, report and run by key ("Shared simulations, reports and runs" +below). A row naming one that does not exist is refused by its foreign key +with SQLSTATE `23503`; `EconomyRecordReferenceError` names the table and +column. `record_report_run_call` and `record_simulation_run_call` record a Modal call's ID, and `fail_unstarted_report_run` and @@ -106,9 +109,16 @@ a transaction of its own: `read_report_inputs` reads the catalog version, model, region and dataset, and each side's policy and dynamic values together; `read_simulation_inputs` does the same for one simulation, and `read_budget_window_inputs` for a budget window's two sides; the writes and -reads each take their own. A missing region or dataset raises -`UnknownRegionError` or `UnknownDatasetError`, and a report side's refused -policy or dynamic raises `ReportSideError`, naming the side. A create whose +reads each take their own. The catalog rows come from `economy_inputs.py` +(`read_catalog_rows`): the dataset is the region's default, a re-run's +stored dataset by name (`EconomyRequest`'s `dataset_name`), or, for a +report created with `data_source` (`read_report_inputs`'s +`local_area_dataset_name`), the catalog version's local-area dataset; a +request naming two of them is refused with `ValueError` before any read. A +missing region or dataset raises `UnknownRegionError` or +`UnknownDatasetError`, a local-area dataset the catalog doesn't give both +area types raises `LocalAreaDatasetMismatchError`, and a report side's +refused policy or dynamic raises `ReportSideError`, naming the side. A create whose commit fails after its rows were inserted raises `EconomyRecordOutcomeUnknownError`: PostgreSQL may have applied the commit, so the rows may exist. diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py index 8a688c3c8..620dfdbc7 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/__init__.py @@ -60,6 +60,7 @@ fail_unstarted_simulation_run, read_dataset, read_dataset_by_id, + read_local_area_dataset, read_model_id, read_region, record_report_run_call, @@ -73,6 +74,7 @@ EconomyRequest, EconomyRunStore, EconomySimulationInputs, + LocalAreaDatasetMismatchError, ReportSide, ReportSideError, SideRefusal, @@ -221,6 +223,7 @@ "KeyedEconomySimulation", "KeyedHouseholdReport", "KeyedWindowYear", + "LocalAreaDatasetMismatchError", "MissingPolicyParametersError", "NewHouseholdJob", "NewHouseholdReportRerun", @@ -296,6 +299,7 @@ "read_economy_report", "read_economy_simulation", "read_household_job", + "read_local_area_dataset", "read_missing_table_privileges", "read_model_id", "read_policy_reform", diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py index 4d0ad395e..431abef80 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_inputs.py @@ -1,11 +1,12 @@ """What an economy request is read from: its catalog rows and its sides' values. -A request names a region code, a dataset name (or the region's default) and -a year, for the .py version of the default worker, and each side's stored -policy and dynamic. ``read_catalog_rows`` reads the catalog version's model, -region and dataset; ``read_report_sides`` and ``read_window_sides`` read -each side's values on that catalog version. ``EconomyRunStore`` runs these -in its transactions. +A request names a region code, a dataset name (or the region's default, or +the catalog version's local-area dataset for a report created with +``data_source``) and a year, for the .py version of the default worker, and +each side's stored policy and dynamic. ``read_catalog_rows`` reads the +catalog version's model, region and dataset; ``read_report_sides`` and +``read_window_sides`` read each side's values on that catalog version. +``EconomyRunStore`` runs these in its transactions. """ from __future__ import annotations @@ -20,6 +21,7 @@ SimulationChoice, read_dataset, read_dataset_by_id, + read_local_area_dataset, read_model_id, read_region, ) @@ -67,6 +69,23 @@ class UnknownDatasetError(LookupError): """The catalog version has no dataset with the requested name.""" +class LocalAreaDatasetMismatchError(LookupError): + """The catalog doesn't give both area types the dataset the worker routes them to. + + ``declared_dataset`` is the dataset the default worker declares it + calculates a report's local areas on. The catalog version's + constituency and local-authority regions use another, or one each. + """ + + def __init__(self, declared_dataset: str) -> None: + """Keep the declared dataset.""" + super().__init__( + "the catalog version's constituency and local-authority regions do " + f"not all use {declared_dataset}" + ) + self.declared_dataset = declared_dataset + + class ReportSideError(Exception): """A report side's policy or dynamic is refused. @@ -156,13 +175,26 @@ class BudgetWindowInputs: def read_catalog_rows( - connection: Connection, request: EconomyRequest + connection: Connection, + request: EconomyRequest, + *, + local_area_dataset_name: str | None = None, ) -> EconomyCatalogRows: """Read the catalog version, model, region and dataset a request names. - Raise UnknownCatalogVersionError, UnknownRegionError or - UnknownDatasetError. + The dataset is the region's default, or the one ``request`` names (a + re-run's stored dataset), or, with ``local_area_dataset_name``, the + catalog version's local-area dataset, which must have that name (a + report created with ``data_source``). Raise ValueError, before any read, + when both name a dataset; otherwise UnknownCatalogVersionError, + UnknownRegionError, UnknownDatasetError or LocalAreaDatasetMismatchError. """ + if local_area_dataset_name is not None and request.dataset_name is not None: + msg = ( + "a catalog read takes either a dataset name or the local-area " + "dataset, not both" + ) + raise ValueError(msg) country = request.country catalog_version_id = read_catalog_version_id( connection, @@ -184,19 +216,22 @@ def read_catalog_rows( f"has no region {request.region_code}" ) raise UnknownRegionError(msg) - dataset = ( - read_dataset_by_id( + if local_area_dataset_name is not None: + dataset = read_local_area_dataset( + connection, catalog_version_id=catalog_version_id + ) + if dataset is None or dataset.name != local_area_dataset_name: + raise LocalAreaDatasetMismatchError(local_area_dataset_name) + elif request.dataset_name is None: + dataset = read_dataset_by_id( connection, catalog_version_id=catalog_version_id, dataset_id=region.default_dataset_id, ) - if request.dataset_name is None - else read_dataset( - connection, - catalog_version_id=catalog_version_id, - name=request.dataset_name, + else: + dataset = read_dataset( + connection, catalog_version_id=catalog_version_id, name=request.dataset_name ) - ) if dataset is None: msg = ( f"{country}'s catalog version for .py {request.policyengine_version} " diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py index 01059a24e..501c1d8c2 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_records.py @@ -30,11 +30,19 @@ from dataclasses import dataclass from typing import TYPE_CHECKING, Any, Final -from sqlalchemy import func, insert, select, update +from sqlalchemy import ( + String, + cast, + func, + insert, + select, + update, +) from sqlalchemy.exc import IntegrityError from policyengine_simulation_persistence.input_tables import ( MODEL_NAME_PREFIX, + UK_AREA_REGION_TYPES, datasets, regions, tax_benefit_models, @@ -182,6 +190,46 @@ def read_dataset_by_id( return _dataset(connection, catalog_version_id, datasets.c.id == dataset_id) +def read_local_area_dataset( + connection: Connection, *, catalog_version_id: UUID +) -> CatalogDataset | None: + """Return the catalog version's local-area dataset, or None when it has none. + + It is the one default dataset every constituency and local-authority + region of the version uses. The Public API's catalog lists those regions + only when the .py release routes them to a dataset of their own, and + gives them that dataset, so a version with no such regions, with only + one of the two types, or with a dataset for each type has none: its + national reports calculate both area levels themselves. A report created + with ``data_source`` runs on this dataset, which may be the national + file: Stage 12 leaves the areas out of a UK-wide or nation run whenever + the release routes both types to one dataset + (``uk_area_breakdowns_omitted``). + """ + region_type = cast(regions.c.region_type, String) + rows = connection.execute( + select(region_type.label("region_type"), datasets.c.id, datasets.c.name) + .distinct() + .join( + datasets, + (datasets.c.id == regions.c.default_dataset_id) + & ( + datasets.c.tax_benefit_model_version_id + == regions.c.tax_benefit_model_version_id + ), + ) + .where( + regions.c.tax_benefit_model_version_id == catalog_version_id, + region_type.in_(UK_AREA_REGION_TYPES), + ) + ).all() + region_types = {row.region_type for row in rows} + found = {CatalogDataset(id=row.id, name=row.name) for row in rows} + if region_types != set(UK_AREA_REGION_TYPES) or len(found) != 1: + return None + return found.pop() + + def _dataset( connection: Connection, catalog_version_id: UUID, condition: ColumnElement[bool] ) -> CatalogDataset | None: diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py index 79cbb2782..2c75e31cb 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/economy_run_store.py @@ -22,6 +22,7 @@ EconomyReportInputs, EconomyRequest, EconomySimulationInputs, + LocalAreaDatasetMismatchError, ReportSide, ReportSideError, SideRefusal, @@ -152,15 +153,23 @@ def read_report_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, + local_area_dataset_name: str | None = None, ) -> EconomyReportInputs: """Read a report's catalog rows and both sides' values together. - Raise UnknownCatalogVersionError, UnknownRegionError or - UnknownDatasetError, or ReportSideError naming the side whose policy - or dynamic is refused. + With ``local_area_dataset_name``, the dataset the default worker + calculates local-area reports on, the report is read on the catalog + version's local-area dataset (``read_local_area_dataset``) in place + of the region's default. Raise ValueError when ``request`` also names + a dataset; otherwise UnknownCatalogVersionError, UnknownRegionError + or UnknownDatasetError, ReportSideError naming the side whose policy + or dynamic is refused, or LocalAreaDatasetMismatchError when the + catalog version doesn't give both area types that dataset. """ with self._transaction() as connection: - catalog = read_catalog_rows(connection, request) + catalog = read_catalog_rows( + connection, request, local_area_dataset_name=local_area_dataset_name + ) return read_report_sides( connection, request, catalog, baseline=baseline, reform=reform ) @@ -381,6 +390,7 @@ def read_simulation(self, simulation_id: UUID) -> EconomySimulationState | None: "EconomyRequest", "EconomyRunStore", "EconomySimulationInputs", + "LocalAreaDatasetMismatchError", "ReportSide", "ReportSideError", "SideRefusal", diff --git a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py index ec9797fad..aef548d47 100644 --- a/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py +++ b/libs/policyengine-simulation-persistence/src/policyengine_simulation_persistence/input_tables.py @@ -15,7 +15,16 @@ from typing import Final -from sqlalchemy import Column, DateTime, Integer, MetaData, String, Table, Uuid +from sqlalchemy import ( + Column, + DateTime, + Enum, + Integer, + MetaData, + String, + Table, + Uuid, +) from sqlalchemy.dialects.postgresql import JSONB from policyengine_simulation_persistence.tables import TABLE_SCHEMA @@ -24,6 +33,20 @@ # A country's tax-benefit model is named "policyengine-". MODEL_NAME_PREFIX: Final = "policyengine-" +# The kinds of geography a region covers, as the Public API's +# ``v2_region_type`` lists them. +REGION_TYPES: Final = ( + "national", + "country", + "state", + "congressional_district", + "constituency", + "local_authority", + "city", + "place", +) +# The UK region types a report on the local-area dataset calculates. +UK_AREA_REGION_TYPES: Final = ("constituency", "local_authority") tax_benefit_models = Table( "tax_benefit_models", @@ -49,6 +72,12 @@ input_metadata, Column("id", Uuid, nullable=False), Column("code", String(255), nullable=False), + # The enum names its schema itself, as the service tables' enums do. + Column( + "region_type", + Enum(*REGION_TYPES, name="v2_region_type", schema=TABLE_SCHEMA), + nullable=False, + ), Column("tax_benefit_model_version_id", Uuid, nullable=False), Column("default_dataset_id", Uuid, nullable=False), ) diff --git a/libs/policyengine-simulation-persistence/tests/economy_rows.py b/libs/policyengine-simulation-persistence/tests/economy_rows.py index 517487ebf..4fc7ce6bc 100644 --- a/libs/policyengine-simulation-persistence/tests/economy_rows.py +++ b/libs/policyengine-simulation-persistence/tests/economy_rows.py @@ -135,6 +135,31 @@ def _insert_catalog_rows( return EconomyCatalog(catalog=catalog, dataset_id=dataset_id, region_id=region_id) +def insert_uk_area_regions( + connection: Connection, + catalog: CatalogVersion, + *, + constituency_dataset_id: UUID, + local_authority_dataset_id: UUID, +) -> None: + """Insert two constituencies and a local authority, each using its dataset.""" + for code in ("constituency/Aldershot", "constituency/Cardiff West"): + insert_region( + connection, + catalog, + code, + default_dataset_id=constituency_dataset_id, + region_type="constituency", + ) + insert_region( + connection, + catalog, + "local_authority/Cardiff", + default_dataset_id=local_authority_dataset_id, + region_type="local_authority", + ) + + @dataclass(frozen=True) class StoredRun: """A simulation and one of its runs, as stored.""" diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py index 886a590f4..cb9776c3b 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_records.py @@ -20,6 +20,7 @@ insert_economy_catalog, insert_pending_report, insert_simulation_run, + insert_uk_area_regions, ) from policyengine_simulation_persistence import ( ReportRunStatus, @@ -28,6 +29,7 @@ fail_unstarted_simulation_run, read_dataset, read_dataset_by_id, + read_local_area_dataset, read_model_id, read_region, record_report_run_call, @@ -35,7 +37,11 @@ report_runs, simulation_runs, ) -from public_api_rows import insert_dataset, insert_region +from public_api_rows import ( + insert_catalog_version, + insert_dataset, + insert_region, +) from sqlalchemy import select, text, update if TYPE_CHECKING: @@ -134,6 +140,104 @@ def test_a_dataset_is_found_by_name_or_id_in_its_catalog_version_only( assert (by_id.id, by_id.name) == (economy.dataset_id, "populace_us_2024") +def test_the_local_area_dataset_is_the_one_both_area_types_use( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + local_area_id = insert_dataset( + connection, economy.catalog, "microcosm_uk_2024_25_dense" + ) + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=local_area_id, + local_authority_dataset_id=local_area_id, + ) + # Another catalog version of the model routes its areas elsewhere. + older = insert_catalog_version( + connection, + country="uk", + model_id=economy.catalog.model_id, + policyengine_version="6.16.0", + ) + older_dataset_id = insert_dataset(connection, older, "microcosm_uk_2024_25") + insert_uk_area_regions( + connection, + older, + constituency_dataset_id=older_dataset_id, + local_authority_dataset_id=older_dataset_id, + ) + act_as_the_service(connection) + + found = read_local_area_dataset( + connection, catalog_version_id=economy.catalog.version_id + ) + + assert found is not None + assert (found.id, found.name) == (local_area_id, "microcosm_uk_2024_25_dense") + + +@pytest.mark.parametrize( + "area_regions", ["none", "constituencies only", "a dataset for each type"] +) +def test_a_catalog_version_without_one_dataset_for_both_area_types_has_none( + public_api_database_url, area_regions +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + constituency_dataset_id = insert_dataset( + connection, economy.catalog, "microcosm_uk_constituencies" + ) + local_authority_dataset_id = insert_dataset( + connection, economy.catalog, "microcosm_uk_local_authorities" + ) + if area_regions == "constituencies only": + insert_region( + connection, + economy.catalog, + "constituency/Aldershot", + default_dataset_id=constituency_dataset_id, + region_type="constituency", + ) + elif area_regions == "a dataset for each type": + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=constituency_dataset_id, + local_authority_dataset_id=local_authority_dataset_id, + ) + act_as_the_service(connection) + + found = read_local_area_dataset( + connection, catalog_version_id=economy.catalog.version_id + ) + + assert found is None + + +def test_the_local_area_dataset_may_be_the_national_default( + public_api_database_url, +) -> None: + """Stage 12 leaves the areas out of a national run whenever both use one file.""" + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=economy.dataset_id, + local_authority_dataset_id=economy.dataset_id, + ) + act_as_the_service(connection) + + found = read_local_area_dataset( + connection, catalog_version_id=economy.catalog.version_id + ) + + assert found is not None + assert (found.id, found.name) == (economy.dataset_id, "populace_uk_2024") + + def _created_report(connection: Connection) -> PendingReport: """Insert a pending report and its runs, then act as the service.""" report = insert_pending_report(connection, insert_economy_catalog(connection)) diff --git a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py index 8e61562f5..6571833b8 100644 --- a/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py +++ b/libs/policyengine-simulation-persistence/tests/test_economy_run_store.py @@ -24,6 +24,7 @@ insert_economy_catalog, insert_pending_report, insert_simulation_run, + insert_uk_area_regions, ) from policyengine_simulation_persistence import ( CatalogDataset, @@ -33,6 +34,7 @@ EconomyRecordOutcomeUnknownError, EconomyRequest, EconomyRunStore, + LocalAreaDatasetMismatchError, MissingPolicyParametersError, NewReportRerun, OverlappingReformError, @@ -50,6 +52,7 @@ economy_inputs, economy_run_store, ) +from policyengine_simulation_persistence.economy_inputs import read_catalog_rows from public_api_rows import StoredValue, insert_dataset, insert_dynamic, insert_policy from sqlalchemy import text from sqlalchemy.exc import OperationalError @@ -125,6 +128,82 @@ def test_a_reports_inputs_are_read_together(public_api_database_url) -> None: } +UK_REQUEST = replace(REQUEST, country="uk", region_code="uk") +# The dataset the UK worker declares it calculates local areas on. +LOCAL_AREA_DATASET_NAME = "microcosm_uk_2024_25_dense" + + +def test_a_report_on_the_local_area_dataset_is_read_on_it( + public_api_database_url, +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + local_area_id = insert_dataset( + connection, economy.catalog, LOCAL_AREA_DATASET_NAME + ) + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=local_area_id, + local_authority_dataset_id=local_area_id, + ) + act_as_the_service(connection) + store = _store_on(connection) + + on_local_areas = store.read_report_inputs( + UK_REQUEST, + baseline=CURRENT_LAW, + reform=CURRENT_LAW, + local_area_dataset_name=LOCAL_AREA_DATASET_NAME, + ) + national = store.read_report_inputs( + UK_REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW + ) + + # The local-area dataset takes the place of the region's default. + assert on_local_areas.catalog.dataset == CatalogDataset( + id=local_area_id, name=LOCAL_AREA_DATASET_NAME + ) + assert national.catalog.dataset.id == economy.dataset_id + assert on_local_areas.catalog == replace( + national.catalog, dataset=on_local_areas.catalog.dataset + ) + + +@pytest.mark.parametrize( + "area_datasets", ["another dataset", "a dataset for each type", "no area regions"] +) +def test_a_declared_dataset_the_catalog_does_not_give_both_area_types_is_refused( + public_api_database_url, area_datasets +) -> None: + with rolled_back_transaction(public_api_database_url) as connection: + economy = insert_economy_catalog(connection, country="uk") + local_area_id = insert_dataset( + connection, economy.catalog, LOCAL_AREA_DATASET_NAME + ) + other_id = insert_dataset(connection, economy.catalog, "microcosm_uk_2024_25") + if area_datasets != "no area regions": + insert_uk_area_regions( + connection, + economy.catalog, + constituency_dataset_id=( + other_id if area_datasets == "another dataset" else local_area_id + ), + local_authority_dataset_id=other_id, + ) + act_as_the_service(connection) + + with pytest.raises(LocalAreaDatasetMismatchError) as mismatch: + _store_on(connection).read_report_inputs( + UK_REQUEST, + baseline=CURRENT_LAW, + reform=CURRENT_LAW, + local_area_dataset_name=LOCAL_AREA_DATASET_NAME, + ) + + assert mismatch.value.declared_dataset == LOCAL_AREA_DATASET_NAME + + def test_a_named_dataset_is_read_instead_of_the_regions_default( public_api_database_url, ) -> None: @@ -441,7 +520,9 @@ def test_every_side_refusal_is_raised_with_its_side(monkeypatch) -> None: dataset=CatalogDataset(id=uuid4(), name="populace_us_2024"), ) # Each patch replaces the name where its caller looks it up. - monkeypatch.setattr(economy_run_store, "read_catalog_rows", lambda *_: catalog) + monkeypatch.setattr( + economy_run_store, "read_catalog_rows", lambda *_, **__: catalog + ) refusals = { UnknownPolicyError: UnknownPolicyError("no policy"), UnknownDynamicError: UnknownDynamicError("no dynamic"), @@ -464,3 +545,15 @@ def refuse(*_, refusal=refusal): with pytest.raises(ReportSideError) as raised: store.read_report_inputs(REQUEST, baseline=CURRENT_LAW, reform=CURRENT_LAW) assert (raised.value.side, raised.value.error) == ("baseline", refusal) + + +def test_a_request_naming_a_dataset_and_the_local_area_dataset_is_refused() -> None: + """A re-run names its stored dataset and a create the local-area one, never both.""" + named = replace(UK_REQUEST, dataset_name="microcosm_uk_2024_25") + + with pytest.raises(ValueError, match="either a dataset name or"): + read_catalog_rows( + None, # refused before any read + named, + local_area_dataset_name=LOCAL_AREA_DATASET_NAME, + ) diff --git a/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py b/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py index 86b6d3eb4..ee015c792 100644 --- a/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py +++ b/projects/policyengine-apis-integ/tests/test_budget_window_generated_client.py @@ -26,7 +26,6 @@ "year": 2026, "budget_window_size": 2, "region_code": "us", - "dataset_name": None, "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": POLICY_ID, "dynamic_id": None}, } diff --git a/projects/policyengine-apis-integ/tests/test_economy_generated_client.py b/projects/policyengine-apis-integ/tests/test_economy_generated_client.py index 5d19bda13..82d0945e7 100644 --- a/projects/policyengine-apis-integ/tests/test_economy_generated_client.py +++ b/projects/policyengine-apis-integ/tests/test_economy_generated_client.py @@ -43,7 +43,6 @@ "description": None, "year": 2026, "region_code": "us", - "dataset_name": None, "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": POLICY_ID, "dynamic_id": None}, "include_cliffs": False, @@ -53,7 +52,6 @@ "simulation_type": "economy", "year": 2026, "region_code": "country/wales", - "dataset_name": None, "policy_id": None, "dynamic_id": None, } diff --git a/projects/policyengine-simulation-entry/DEPLOYMENT.md b/projects/policyengine-simulation-entry/DEPLOYMENT.md index fa001a6cc..620c80858 100644 --- a/projects/policyengine-simulation-entry/DEPLOYMENT.md +++ b/projects/policyengine-simulation-entry/DEPLOYMENT.md @@ -131,13 +131,17 @@ the Modal secret the Stage 12 secret sync writes. Every staging deployment runs `staging_economy_check` when the household check runs: `.github/scripts/simulation-staging-economy-check.sh` sends a small report request, current law against current law for `country/wales` -in 2026, through the candidate's tagged URL with the authenticated tests' -client credentials (`POST /reports`), then forces a new run of the report -(`POST /reports/{report_id}/runs` with `{"force": true}`), follows that run -through `GET /reports/{report_id}`, and requires it to succeed within 30 -minutes. The report is found by key, so on versions an earlier check ran on, -the request ends on that check's report run and calculates nothing; the -forced run, which nothing joins, is what calculates on every deploy: both +in 2026, on the bundle's local-area dataset +(`data_source: "local_area_dataset"`), through the candidate's tagged URL +with the authenticated tests' client credentials (`POST /reports`), then +forces a new run of the report (`POST /reports/{report_id}/runs` with +`{"force": true}`), follows that run through `GET /reports/{report_id}`, and +requires it to succeed within 30 minutes. The run also calculates Wales's +constituencies and local authorities, and the coordinator fails it unless +both area levels have rows or withheld codes, so its success covers them. +The report is found by key, so on versions an earlier check ran on, the +request ends on that check's report run and calculates nothing; the forced +run, which nothing joins, is what calculates on every deploy: both simulations on the release's workers and the comparison on its coordinator. Both requests need `simulation:submit`. `deployment_ready` requires the check to pass in staging, so a failure stops the production diff --git a/projects/policyengine-simulation-entry/README.md b/projects/policyengine-simulation-entry/README.md index 340269648..d4e20b444 100644 --- a/projects/policyengine-simulation-entry/README.md +++ b/projects/policyengine-simulation-entry/README.md @@ -113,11 +113,13 @@ staging check. `POST /reports` creates an economy report: a baseline and a reform simulation of one region's data for one year. It names the `country`, `report_type` (`economy`), `label`, `description`, `year`, `region_code` -and `dataset_name` (a region and dataset of the country's catalog version -for the default worker's .py version; null for the region's default -dataset), each side's stored `policy_id` and `dynamic_id` (null for current -law), `include_cliffs`, and `spm` (SPM settings; omit it, since null is -refused). `POST /simulations` creates a standalone economy simulation from +(a region of the country's catalog version for the default worker's .py +version), each side's stored `policy_id` and `dynamic_id` (null for current +law), `include_cliffs`, `spm` (SPM settings; omit it, since null is +refused) and, for a UK-wide or nation report, `data_source` (see "Local +areas"). No request names a dataset: a report or simulation runs on the +dataset the catalog version gives its region, and `dataset_name` is refused +with 422. `POST /simulations` creates a standalone economy simulation from the same fields for one policy and dynamic. Neither names a .py version or a record ID: the service runs the v2 version manifest's default worker and chooses every ID. @@ -148,16 +150,20 @@ simulation and run and whether it was reused, which is true for a side whose run this request didn't create. A request is refused before anything is written: with 400 and a `code` when -a row it names is missing (`unknown_region`, `unknown_dataset` and -`unknown_dynamic` name the caller's own choice; `unknown_catalog_version`, -`unknown_policy`, `no_economy_worker`, `dataset_not_in_bundle` and -`missing_reference` are the service's state, such as a catalog version -missing while a release deploys), and with 422 and a `code` when a policy or -dynamic sets parameters the catalog version lacks (`missing_parameters`) or -both set one (`overlapping_parameters`), and a report with -`include_cliffs: true` with 422 `cliffs_not_available`, located at the -field, until each simulation run's own cliff calculation exists (C1 · 39). -The routes answer 503 with +a row it names is missing (`unknown_region` and `unknown_dynamic` name the +caller's own choice, and `unknown_dataset` its region's dataset; +`unknown_catalog_version`, `unknown_policy`, `no_economy_worker`, +`dataset_not_in_bundle` and `missing_reference` are the service's state, +such as a catalog version missing while a release deploys), or, for a report +on the local-area dataset, when the default worker or the catalog can't +serve it (`local_areas_unsupported` and `local_area_dataset_mismatch`, also +the service's state; see "Local areas"); and with 422 and a `code` when a +policy or dynamic sets parameters the catalog version lacks +(`missing_parameters`), both set one (`overlapping_parameters`), or the +release has no local-area dataset for `data_source` +(`no_local_area_dataset`), and a report with `include_cliffs: true` with 422 +`cliffs_not_available`, located at the field, until each simulation run's +own cliff calculation exists (C1 · 39). The routes answer 503 with `Retry-After` when the manifest or the database can't be read. When Modal refuses the call, or doesn't confirm it within ten seconds, the run is failed at once (a report run alone: its simulation runs may already be @@ -168,6 +174,37 @@ a run claimed meanwhile is answered with 201. Every 500 is the JSON error with code `internal_error`, and may follow a write. No `detail` holds an exception's text. +### Local areas + +An economy report created with `data_source: "local_area_dataset"` runs on +the bundle's local-area dataset, the one the .py release routes +constituencies and local authorities to, in place of its region's dataset. +It is an ordinary report: it returns its full results, cliffs included when +asked, and its constituency and local-authority impacts, and is re-run on +the same dataset. `data_source` is left out unless given (null and any other +value are refused with 422), and is never stored as an option: the dataset +is stored with the report's simulations. Only a UK report whose region is +`uk` or one of the four `country/*` nations may ask; any other country or +region is refused with 422 at `data_source`. + +The default worker's UK entry in the v2 version manifest decides the rest +(`local_area_reports`): the input version its coordinator accepts for a +local-area report run, and the dataset the .py release routes constituency +and local-authority regions to, which the publisher computes by the rule +Stage 12's national aggregation uses to leave the areas out. Before anything +is read: + +- without that declaration, or with another input version, the request is + refused with 400 `local_areas_unsupported`, the service's state; +- with no dataset, the release routes the areas to none of their own, and + the request is refused with 422 `no_local_area_dataset` at `data_source`: + that release's national reports calculate both area levels themselves. + +With a dataset, the catalog version's constituency and local-authority +regions must all use it, or the request is refused with 400 +`local_area_dataset_mismatch`, the service's state; the report is then +calculated on the catalog's row for that dataset. + ### Budget windows `POST /reports` with `report_type` `budget_window` finds or creates a diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py index aecce669d..6396a501e 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/budget_window_api_models.py @@ -48,10 +48,10 @@ class BudgetWindowReportRequest(BaseModel): """A budget-window report: a baseline and a reform in each year of a window. ``year`` is the window's first year, and ``budget_window_size`` its - length. Every year uses the request's region and dataset, as an economy - report does. ``spm`` selects the SPM forecast scenario and geography; - omit it, rather than sending null, to use the bundle's certified - defaults. + length. Every year uses the request's region and its dataset, as an + economy report does; no request names a dataset. ``spm`` selects the SPM + forecast scenario and geography; omit it, rather than sending null, to + use the bundle's certified defaults. """ model_config = ConfigDict(extra="forbid", frozen=True, allow_inf_nan=False) @@ -65,7 +65,6 @@ class BudgetWindowReportRequest(BaseModel): year: SimulationYear budget_window_size: BudgetWindowSize region_code: CatalogKey - dataset_name: CatalogKey | None = None baseline: PolicyChoice reform: PolicyChoice spm: SPMSelection | SkipJsonSchema[None] = Field( diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py index 0fb0546ea..3547c9dbe 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_api_models.py @@ -1,9 +1,11 @@ """Request and response models of the economy simulation and report routes. -The Public API names a region and dataset of the country's catalog by code -and name, and each simulation's stored policy and dynamic by ID; the -Simulation Entrypoint reads them from the Public API's tables itself, and -calculates on the v2 version manifest's default worker. A request names no +The Public API names a region of the country's catalog by code, and each +simulation's stored policy and dynamic by ID; the Simulation Entrypoint +reads them, and the dataset the catalog gives the region, from the Public +API's tables itself, and calculates on the v2 version manifest's default +worker. No request names a dataset: only a UK-wide or nation report may +choose the bundle's local-area dataset instead (``data_source``). A request names no .py version and no record ID: the service runs its default worker's version and chooses every ID. @@ -41,10 +43,18 @@ from typing import Annotated, Any, Literal from uuid import UUID +from policyengine_simulation_contract.local_area_breakdown import UK_NATION_REGIONS from policyengine_simulation_contract.spm import SPMSelection from policyengine_simulation_contract.stage12_bundle import CountryId from policyengine_simulation_persistence import ReportRunStatus, SimulationStatus -from pydantic import BaseModel, ConfigDict, Field, StrictBool, field_validator +from pydantic import ( + BaseModel, + ConfigDict, + Field, + StrictBool, + ValidationInfo, + field_validator, +) from pydantic.json_schema import SkipJsonSchema # The bounds the tables accept. @@ -52,6 +62,13 @@ 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)] +# The one data source a report may ask for: the bundle's local-area dataset, +# on which a UK-wide or nation report also calculates its constituency and +# local-authority impacts. +LOCAL_AREA_DATA_SOURCE = "local_area_dataset" +LocalAreaDataSource = Literal["local_area_dataset"] +# The regions whose reports may run on the local-area dataset. +LOCAL_AREA_DATA_SOURCE_REGIONS = frozenset({"uk", *UK_NATION_REGIONS}) # A report's name and description are accepted and not stored: each user's # saved report in the Public API holds them (C1 · 24's answer 6). LABEL_NOT_STORED = ( @@ -63,9 +80,9 @@ ) # Why a request is refused (400), naming a row the caller chose that doesn't -# exist: the Public API answers these as its caller's error. On a re-run they -# name the stored record's own region, dataset or dynamic, which the current -# catalog version lacks or which was deleted. +# exist, or the region's dataset: the Public API answers these as its caller's +# error. On a re-run they name the stored record's own region, dataset or +# dynamic, which the current catalog version lacks or which was deleted. CallerRowRefusalCode = Literal["unknown_region", "unknown_dataset", "unknown_dynamic"] # Why a request is refused (400) for the service's own state, or a row the # Public API checks before asking. On a report's re-run, ``unknown_policy`` and @@ -84,6 +101,12 @@ "unknown_household", # The default worker has no household function for the country. "no_household_function", + # The default worker's coordinator runs no local-area report runs of the + # input this service sends. + "local_areas_unsupported", + # The catalog version's constituency and local-authority regions don't + # all use the dataset the default worker calculates local areas on. + "local_area_dataset_mismatch", ] EconomyRefusalCode = Literal[CallerRowRefusalCode, ServiceStateRefusalCode] # Why stored values cannot be calculated (422). @@ -94,6 +117,10 @@ # be read, or the household functions' contract refuses what the report # would calculate: located at the household or a side's policy. "household_not_calculable", + # The default worker's .py release routes constituencies and local + # authorities to no dataset of their own, so it has no local-area dataset + # for ``data_source``: located at ``data_source``. + "no_local_area_dataset", # A report asks for cliffs (include_cliffs: true), which wait for each # simulation run's own cliff calculation (C1 · 39); located at the field. "cliffs_not_available", @@ -146,27 +173,34 @@ class EconomySimulationRequest(PolicyChoice): """An economy simulation: a policy and dynamic applied to one region's data. ``region_code`` is a region of the country's catalog version for the - default worker's .py version (``us``, ``state/ca``, ``country/wales``), - and ``dataset_name`` one of that version's datasets; without it, the - region's default dataset is used. + default worker's .py version (``us``, ``state/ca``, ``country/wales``); + the simulation runs on the dataset that version gives the region. """ country: CountryId simulation_type: Literal["economy"] year: SimulationYear region_code: CatalogKey - dataset_name: CatalogKey | None = None class EconomyReportRequest(_Request): """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 - ``EconomySimulationRequest`` describes them. ``include_cliffs: true`` is - refused (422 ``cliffs_not_available``) until cliffs are calculated per - simulation run (C1 · 39). ``spm`` selects the + Both simulations use the report's year and region, and the region's + dataset, as ``EconomySimulationRequest`` describes them. ``include_cliffs: + true`` is refused (422 ``cliffs_not_available``) until cliffs are + calculated per simulation run (C1 · 39). ``spm`` selects the SPM forecast scenario and geography; omit it, rather than sending null, to use the bundle's certified defaults. + + ``data_source: "local_area_dataset"`` runs the report on the bundle's + local-area dataset, the one its .py release routes constituencies and + local authorities to, in place of the region's own: the report returns + its full results, cliffs included when asked, and its constituency and + local-authority impacts. Only a UK report whose region is ``uk`` or one + of the four ``country/*`` nations may ask; omit it, rather than sending + null, to use the region's dataset. It is never stored as an option: the + dataset it chooses is stored with the report's simulations. """ country: CountryId @@ -177,13 +211,16 @@ class EconomyReportRequest(_Request): ) 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_null_default ) + # Last, so its check can read the country and region. + data_source: LocalAreaDataSource | SkipJsonSchema[None] = Field( + default=None, json_schema_extra=omit_null_default + ) @field_validator("spm", mode="before") @classmethod @@ -194,12 +231,58 @@ def refuse_null_spm(cls, value: object) -> object: raise ValueError(msg) return value + @field_validator("data_source", mode="before") + @classmethod + def refuse_another_data_source(cls, value: object) -> object: + """Refuse null and any other value with one reason. + + Omit ``data_source`` to use the region's dataset. Without this, + another value would be refused once by each member of the field's + type. + """ + if value != LOCAL_AREA_DATA_SOURCE: + msg = ( + f'data_source must be "{LOCAL_AREA_DATA_SOURCE}" when given; omit ' + "it to use the region's dataset" + ) + raise ValueError(msg) + return value + + @field_validator("data_source") + @classmethod + def refuse_a_data_source_the_region_cannot_have( + cls, data_source: LocalAreaDataSource | None, info: ValidationInfo + ) -> LocalAreaDataSource | None: + """Refuse the local-area dataset for another country or region. + + Only a UK report whose region is UK-wide or a nation may run on it. A + country or region that failed its own validation is reported by that + field alone. + """ + country = info.data.get("country") + region_code = info.data.get("region_code") + if data_source is None or country is None or region_code is None: + return data_source + if country != "uk": + msg = "the local-area dataset is available only to UK reports" + raise ValueError(msg) + if region_code not in LOCAL_AREA_DATA_SOURCE_REGIONS: + accepted = ", ".join(sorted(LOCAL_AREA_DATA_SOURCE_REGIONS)) + msg = ( + "the local-area dataset needs a UK-wide or nation region " + f"({accepted}), not {region_code!r}" + ) + raise ValueError(msg) + return data_source + def options(self) -> dict[str, Any]: """Return the request's options, as its calculation reads them. ``spm`` holds only the settings the request gave, and is left out when it gave none. The report stores the selection alone - (``economy_requests.stored_options``). + (``economy_requests.stored_options``). ``data_source`` is never an + option: the dataset it chooses is stored with the report's + simulations. """ options: dict[str, Any] = {"include_cliffs": self.include_cliffs} if self.spm is not None: @@ -356,6 +439,9 @@ class EconomyRequestUnprocessable(_Answer): cannot be calculated carry one: ``missing_parameters`` for a policy or dynamic setting parameters the catalog version lacks, and ``overlapping_parameters`` for a policy and dynamic setting the same one. + ``no_local_area_dataset`` refuses ``data_source`` on a .py release that + routes constituencies and local authorities to no dataset of their own: + its national reports calculate both area levels themselves. """ detail: list[EconomyRequestReason] diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py index 5139ac641..14f1f3948 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_requests.py @@ -40,7 +40,6 @@ BudgetWindowReportRequest, ) from policyengine_simulation_entry.economy_api_models import ( - EconomyRefusalCode, EconomyReportRequest, EconomySimulationRequest, ) @@ -125,12 +124,16 @@ def economy_request_for( | BudgetWindowReportRequest, worker: EconomyWorker, ) -> EconomyRequest: - """Return what the request names apart from policies, for the default worker.""" + """Return what the request names apart from policies, for the default worker. + + It names no dataset: the store reads the region's, or the local-area + dataset a report on it asks for. + """ return EconomyRequest( country=request.country, policyengine_version=worker.policyengine_version, region_code=request.region_code, - dataset_name=request.dataset_name, + dataset_name=None, year=request.year, ) @@ -146,23 +149,20 @@ def calculation_scope( ) -> CalculationScope: """Return what the calculation runs on, with the bundle's dataset. - Raise EconomySubmissionRefusedError when the bundle lacks the catalog - dataset: ``unknown_dataset`` when the request named it, and - ``dataset_not_in_bundle`` for the region's default. + Raise EconomySubmissionRefusedError (``dataset_not_in_bundle``, the + service's state) when the bundle lacks the catalog dataset: no request + names one. """ try: dataset = bundle_dataset(worker, catalog.dataset.name) except DatasetNotInBundleError: - code: EconomyRefusalCode = ( - "dataset_not_in_bundle" - if request.dataset_name is None - else "unknown_dataset" - ) detail = ( f"The default v2 worker, .py {worker.version}, has no dataset " f"{catalog.dataset.name}." ) - raise EconomySubmissionRefusedError(code=code, detail=detail) from None + raise EconomySubmissionRefusedError( + code="dataset_not_in_bundle", detail=detail + ) from None return CalculationScope( country=request.country, region_code=catalog.region.code, diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py index 2462d6023..478eee539 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_routes.py @@ -126,13 +126,18 @@ } _REFUSED = { "description": ( - "A row the request names, or a function it needs, is missing; nothing " - "was written. unknown_region, unknown_dataset and unknown_dynamic name " - "the caller's own region, dataset or dynamic; a household report's " - "unknown_household and no_household_function name its household and " - "the default worker's household function; any other code is the " - "service's state, such as a catalog version missing while a release " - "deploys" + "A row the request names, or a function it needs, is missing, or the " + "catalog disagrees with the default worker; nothing was written. " + "unknown_region and unknown_dynamic name the caller's own region or " + "dynamic, and unknown_dataset its region's dataset (a request names " + "none); a household report's unknown_household and " + "no_household_function name its household and the default worker's " + "household function; any other code is the service's state, such as " + "a catalog version missing while a release deploys, or, for a report " + "on the local-area dataset, local_areas_unsupported (the default " + "worker declares no local-area report runs of this service's input " + "version) and local_area_dataset_mismatch (the catalog version doesn't " + "give its constituency and local-authority regions that one dataset)" ), **ERROR_ANSWER, } @@ -142,9 +147,10 @@ "cannot be calculated; nothing was written. Stored values that cannot " "be calculated carry a code: missing_parameters, " "overlapping_parameters, or household_not_calculable for a household " - "report's household; a report asking for cliffs (include_cliffs: " - "true) carries cliffs_not_available until each simulation run's own " - "cliff calculation exists" + "report's household; no_local_area_dataset refuses data_source on a " + "release with no local-area dataset; a report asking for cliffs " + "(include_cliffs: true) carries cliffs_not_available until each " + "simulation run's own cliff calculation exists" ), "model": EconomyRequestUnprocessable, } diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py index 10c882ee4..5e9404e0b 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submission_errors.py @@ -18,6 +18,7 @@ from typing import TYPE_CHECKING, Literal from policyengine_simulation_persistence import ( + LocalAreaDatasetMismatchError, MissingPolicyParametersError, OverlappingReformError, ReportSideError, @@ -47,11 +48,12 @@ ) # Each column whose foreign key can refuse a submission's rows: the code the -# refusal answers with and the row it names. A region, dataset or dynamic is -# the caller's own choice, or on a re-run the stored record's; any other row -# is one the Public API checked first, or one the service chose, so its -# refusal is the service's state. A simulation is refused only on a re-run, -# whose new runs name the report's stored simulations. +# refusal answers with and the row it names. A region or dynamic is the +# caller's own choice, and a dataset its region's, or on a re-run each is the +# stored record's; any other row is one the Public API checked first, or one +# the service chose, so its refusal is the service's state. A simulation is +# refused only on a re-run, whose new runs name the report's stored +# simulations. REFERENCE_REFUSALS: dict[str, tuple[EconomyRefusalCode, str]] = { "simulation_id": ("missing_reference", "simulation"), "region_id": ("unknown_region", "region"), @@ -191,7 +193,9 @@ def read_refusal( """Return the refusal a store read's error means, or None for any other error. A missing catalog version, region, dataset, policy or dynamic is refused - (400); a policy or dynamic setting parameters the catalog version lacks, + (400), and so is a catalog whose area regions don't use the dataset the + default worker calculates local areas on; a policy or dynamic setting + parameters the catalog version lacks, or both setting one, cannot be calculated (422). A report side's refusal (ReportSideError) is located on that side's fields, under ``source``: the request's body, or the stored record a re-run reads. Every detail is @@ -248,6 +252,14 @@ def _missing_row_refusal( "unknown_dynamic", f"No stored dynamic matches the one {named_by} names.", ) + elif isinstance(error, LocalAreaDatasetMismatchError): + # The dataset is the default worker's declaration, not the request's. + refusal = ( + "local_area_dataset_mismatch", + f"{catalog}'s constituency and local-authority regions do not all " + f"use {error.declared_dataset}, the dataset the default v2 worker " + "calculates local areas on.", + ) if refusal is None: return None code, detail = refusal diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py index 644b99d41..01de46eab 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_submissions.py @@ -1,14 +1,16 @@ """Create economy reports and simulations, and start the calls that calculate them. -A report submission names a region, a dataset, a year and each side's -stored policy and dynamic. Identical submissions, together or apart, end on -the same simulation, report and run rows (C1 · 24). The service: +A report submission names a region, a year and each side's stored policy +and dynamic, and runs on the region's dataset, or, with ``data_source``, on +the bundle's local-area dataset. Identical submissions, together or apart, +end on the same simulation, report and run rows (C1 · 24). The service: 1. finds the v2 version manifest's default worker's economy functions for - the country, and its bundle; + the country, and its bundle, and, for a report with ``data_source``, the + local-area dataset its UK entry declares (``local_area_reports``); 2. reads, in one transaction, the country's catalog version for that - worker's .py version, the region and dataset, and each side's policy and - dynamic values; + worker's .py version, the region and its dataset (or the catalog's + local-area dataset), and each side's policy and dynamic values; 3. finds or creates, in one transaction, each side's simulation and the report by their keys (the catalog's dataset name and region code, the year, the policies, dynamics and SPM selection), then the report's run @@ -97,6 +99,7 @@ from policyengine_simulation_entry.household_workers import ( VersionManifestUnavailableError, ) +from policyengine_simulation_entry.local_area_reports import local_area_dataset_name if TYPE_CHECKING: from collections.abc import Callable, Sequence @@ -140,8 +143,13 @@ def read_report_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, + local_area_dataset_name: str | None = None, ) -> EconomyReportInputs: - """Read a report's catalog rows and both sides' values.""" + """Read a report's catalog rows and both sides' values. + + With ``local_area_dataset_name``, the report is read on the catalog's + local-area dataset, which must have that name. + """ ... def read_simulation_inputs( @@ -266,6 +274,7 @@ async def submit_report( """ refuse_cliffs(request) worker = await self._default_worker(request.country) + area_dataset_name = local_area_dataset_name(request, worker) options = request.options() spm = options.get("spm") economy_request = economy_request_for(request, worker) @@ -274,6 +283,7 @@ async def submit_report( economy_request, baseline=simulation_choice(request.baseline), reform=simulation_choice(request.reform), + local_area_dataset_name=area_dataset_name, ), request=economy_request, ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py index b07a6e693..438271f38 100644 --- a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/economy_workers.py @@ -33,6 +33,7 @@ if TYPE_CHECKING: from policyengine_simulation_contract.stage12_bundle import Stage12CountryBundle from policyengine_simulation_contract.stage12_manifest import ( + LocalAreaReports, V2ManifestStore, V2VersionManifest, ) @@ -48,6 +49,9 @@ class EconomyWorker: ``version`` is the worker's .py version, the manifest's default, and ``version_manifest_sha256`` the digest of the manifest it was read from. + ``local_area_reports`` is the country's declaration of the local-area + report runs the coordinator runs, and the dataset it runs them on; None + when it runs none. """ version: str @@ -58,6 +62,7 @@ class EconomyWorker: bundle_manifest_sha256: str policyengine_version: str country: Stage12CountryBundle + local_area_reports: LocalAreaReports | None = None @property def versions(self) -> RunVersions: @@ -99,6 +104,7 @@ def default_economy_worker(manifest: V2VersionManifest, country: str) -> Economy bundle_manifest_sha256=worker.bundle_manifest_sha256, policyengine_version=worker.bundle.policyengine_version, country=country_bundle, + local_area_reports=country_worker.local_area_reports, ) diff --git a/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py new file mode 100644 index 000000000..28b6efdcb --- /dev/null +++ b/projects/policyengine-simulation-entry/src/policyengine_simulation_entry/local_area_reports.py @@ -0,0 +1,76 @@ +"""Which dataset a report created with ``data_source: "local_area_dataset"`` runs on. + +Such a UK-wide or nation report runs on the dataset the .py release routes +constituencies and local authorities to, and returns its full results and +both area levels. The default worker's UK entry in the v2 version manifest +declares both whether its coordinator runs such report runs +(``local_area_reports``, with the input version it accepts) and that +dataset, which the publisher computes in the worker's own environment by the +rule Stage 12's national aggregation uses to leave the areas out +(``uk_area_regions_routed``). So the service, the national runs and the +worker decide alike on every release. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_simulation_contract.stage12_manifest import ( + LOCAL_AREA_REPORTS_VERSION, +) + +from policyengine_simulation_entry.economy_submission_errors import ( + EconomySubmissionRefusedError, + EconomySubmissionUnprocessableError, + UnprocessableReason, +) + +if TYPE_CHECKING: + from policyengine_simulation_entry.economy_api_models import ( + EconomyReportRequest, + ) + from policyengine_simulation_entry.economy_workers import EconomyWorker + + +def local_area_dataset_name( + request: EconomyReportRequest, worker: EconomyWorker +) -> str | None: + """Return the dataset a report on the local-area dataset runs on, or None. + + None means the request names no ``data_source``: the report runs on its + region's dataset. Raise EconomySubmissionRefusedError + (``local_areas_unsupported``, the service's state) when the default + worker declares no local-area report runs of the input version this + service sends, and EconomySubmissionUnprocessableError + (``no_local_area_dataset``) when its release routes constituencies and + local authorities to no dataset of their own: there, national reports + calculate both area levels themselves. + """ + if request.data_source is None: + return None + declared = worker.local_area_reports + if declared is None or declared.input_version != LOCAL_AREA_REPORTS_VERSION: + raise EconomySubmissionRefusedError( + code="local_areas_unsupported", + detail=( + f"The default v2 worker, .py {worker.version}, cannot calculate " + f"a {request.country} report on the local-area dataset." + ), + ) + if declared.dataset is None: + raise EconomySubmissionUnprocessableError( + code="no_local_area_dataset", + reasons=( + UnprocessableReason( + loc=("body", "data_source"), + msg=( + f".py {worker.policyengine_version} routes constituencies " + "and local authorities to no dataset of their own, so it " + "has no local-area dataset; its national reports " + "calculate both area levels" + ), + type="no_local_area_dataset", + ), + ), + ) + return declared.dataset diff --git a/projects/policyengine-simulation-entry/tests/economy_fixtures.py b/projects/policyengine-simulation-entry/tests/economy_fixtures.py index d24a831bd..d6eebf30e 100644 --- a/projects/policyengine-simulation-entry/tests/economy_fixtures.py +++ b/projects/policyengine-simulation-entry/tests/economy_fixtures.py @@ -9,6 +9,8 @@ from household_fixtures import POLICYENGINE_VERSION, household_worker_version from policyengine_simulation_contract.stage12_bundle import Stage12Dataset from policyengine_simulation_contract.stage12_manifest import ( + LOCAL_AREA_REPORTS_VERSION, + LocalAreaReports, V2VersionManifest, V2WorkerVersion, ) @@ -20,6 +22,19 @@ sha256="c" * 64, repo_type="dataset", ) +# The dataset the UK release routes constituencies and local authorities to. +LOCAL_AREA_DATASET = Stage12Dataset( + identity="microcosm_uk_2024_25_dense", + uri="hf://policyengine/data/microcosm_uk_2024_25_dense.h5@dense-revision", + artifact_revision="dense-revision", + sha256="d" * 64, + repo_type="dataset", +) +# A UK worker's declaration that its coordinator runs local-area report runs +# on that dataset. +ROUTED_LOCAL_AREAS = LocalAreaReports( + input_version=LOCAL_AREA_REPORTS_VERSION, dataset=LOCAL_AREA_DATASET.identity +) def economy_worker_version( @@ -38,6 +53,25 @@ def economy_worker_version( ) +def local_area_worker_version( + local_area_reports: LocalAreaReports | None, +) -> V2WorkerVersion: + """Return the economy worker with the local-area dataset in its UK bundle. + + Its UK entry declares ``local_area_reports``, or nothing for None. The + worker is validated again, so the declaration must name a dataset of the + UK bundle. + """ + document = economy_worker_version().model_dump(mode="json") + for country in document["bundle"]["countries"]: + if country["country"] == "uk": + country["datasets"].append(LOCAL_AREA_DATASET.model_dump(mode="json")) + for country in document["countries"]: + if country["country"] == "uk" and local_area_reports is not None: + country["local_area_reports"] = local_area_reports.model_dump(mode="json") + return V2WorkerVersion.model_validate(document) + + def economy_manifest( default_worker: V2WorkerVersion | None = None, ) -> V2VersionManifest: diff --git a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py index 7978f2b7c..402622a72 100644 --- a/projects/policyengine-simulation-entry/tests/economy_service_fakes.py +++ b/projects/policyengine-simulation-entry/tests/economy_service_fakes.py @@ -7,7 +7,7 @@ from __future__ import annotations import asyncio -from dataclasses import dataclass, field +from dataclasses import dataclass, field, replace from datetime import UTC, datetime from itertools import count from typing import TYPE_CHECKING, Any @@ -47,6 +47,7 @@ if TYPE_CHECKING: from collections.abc import Sequence + from policyengine_simulation_contract.stage12_manifest import V2WorkerVersion from policyengine_simulation_persistence import ( EconomyRequest, KeyedEconomyReport, @@ -82,7 +83,6 @@ "description": "Raises the credit to $3,000", "year": 2026, "region_code": "us", - "dataset_name": None, "baseline": {"policy_id": None, "dynamic_id": None}, "reform": {"policy_id": str(POLICY_ID), "dynamic_id": str(DYNAMIC_ID)}, "include_cliffs": True, @@ -93,7 +93,6 @@ "simulation_type": "economy", "year": 2026, "region_code": "us", - "dataset_name": None, "policy_id": str(POLICY_ID), "dynamic_id": None, } @@ -115,15 +114,25 @@ def simulation_request(**changes: Any) -> EconomySimulationRequest: class FakeWorkers: - """The default worker's economy functions, or the lookup's failure.""" + """The default worker's economy functions, or the lookup's failure. - def __init__(self, failure: Exception | None = None) -> None: + ``worker_version`` is the manifest's default worker; without it, the + economy fixtures' worker. + """ + + def __init__( + self, + failure: Exception | None = None, + *, + worker_version: V2WorkerVersion | None = None, + ) -> None: self.failure = failure + self.worker_version = worker_version def default_worker(self, country: str) -> EconomyWorker: if self.failure is not None: raise self.failure - return default_economy_worker(economy_manifest(), country) + return default_economy_worker(economy_manifest(self.worker_version), country) def created_report(report: KeyedEconomyReport) -> FoundEconomyReport: @@ -180,7 +189,12 @@ class FakeStore: claimed: bool = False stored_report: EconomyReportState | None = None stored_simulation: EconomySimulationState | None = None + # The catalog's local-area dataset a report read calculates on, when + # asked for one. + local_area_dataset: CatalogDataset | None = None report_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) + # The local-area dataset each report read was asked for, or None. + local_area_reads: list[str | None] = field(default_factory=list) simulation_reads: list[tuple[EconomyRequest, Any]] = field(default_factory=list) reports: list[KeyedEconomyReport] = field(default_factory=list) simulations: list[KeyedEconomySimulation] = field(default_factory=list) @@ -195,11 +209,13 @@ def read_report_inputs( *, baseline: SimulationChoice, reform: SimulationChoice, + local_area_dataset_name: str | None = None, ) -> EconomyReportInputs: self.report_reads.append((request, (baseline, reform))) + self.local_area_reads.append(local_area_dataset_name) if self.read_failure is not None: raise self.read_failure - return EconomyReportInputs( + inputs = EconomyReportInputs( catalog=self.catalog, baseline=SimulationInputs(choice=baseline, reform={}), # Current law sets no values, on either side. @@ -208,6 +224,11 @@ def read_report_inputs( reform=REFORM if reform.policy_id or reform.dynamic_id else {}, ), ) + if local_area_dataset_name is None or self.local_area_dataset is None: + return inputs + return replace( + inputs, catalog=replace(self.catalog, dataset=self.local_area_dataset) + ) def read_simulation_inputs( self, request: EconomyRequest, choice: SimulationChoice diff --git a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py index d767c5f24..b424c83bb 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_rerun_routes.py @@ -397,3 +397,16 @@ def test_an_unconfigured_service_answers_503(client_for, path, body) -> None: assert result.status_code == 503 assert result.json()["code"] == "not_configured" + + +def test_a_report_rerun_takes_no_data_source(client_for) -> None: + """A re-run keeps the stored report's dataset, whatever it was created with.""" + reruns = FakeEconomyReruns() + + with client_for(reruns) as client: + result = client.post(REPORT_RUNS, json={"data_source": "local_area_dataset"}) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert (reason["loc"][-1], reason["type"]) == ("data_source", "extra_forbidden") + assert reruns.report_reruns == [] diff --git a/projects/policyengine-simulation-entry/tests/test_economy_routes.py b/projects/policyengine-simulation-entry/tests/test_economy_routes.py index 6f88a5054..65886fbfe 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_routes.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_routes.py @@ -13,6 +13,7 @@ from conftest import FakeBackend, make_settings from economy_service_fakes import REPORT_BODY, SIMULATION_BODY from fastapi.testclient import TestClient +from household_report_fakes import HOUSEHOLD_REPORT_BODY from policyengine_observability import REQUEST_ID_HEADER from policyengine_simulation_entry import app as app_module from policyengine_simulation_entry.app import create_app @@ -42,6 +43,7 @@ ReportRunStatus, SimulationStatus, ) +from test_budget_window_requests import WINDOW_BODY OBSERVABILITY_ID = "6e1f3d4c-0a5b-4c39-9d2e-7f8a9b0c1d2e" RECORD_ID = UUID("00000000-0000-4000-8000-0000000000e1") @@ -219,6 +221,184 @@ def test_a_malformed_request_is_refused_with_its_reasons(client_for, path, body) assert (submissions.reports, submissions.simulations) == ([], []) +@pytest.mark.parametrize("dataset_name", ["enhanced_cps_2024", None]) +@pytest.mark.parametrize( + ("path", "body"), + [ + ("/reports", REPORT_BODY), + ("/simulations", SIMULATION_BODY), + ("/reports", WINDOW_BODY), + ], + ids=["report", "simulation", "budget window"], +) +def test_a_request_naming_a_dataset_is_refused( + client_for, path, body, dataset_name +) -> None: + """No request chooses a dataset: each runs on its region's (or data_source's).""" + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post(path, json={**body, "dataset_name": dataset_name}) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert (reason["loc"][-1], reason["type"]) == ("dataset_name", "extra_forbidden") + assert (submissions.reports, submissions.simulations) == ([], []) + + +# A UK-wide report on the local-area dataset, with cliffs and no SPM settings. +LOCAL_AREA_REPORT_BODY: dict[str, Any] = { + **{name: value for name, value in REPORT_BODY.items() if name != "spm"}, + "country": "uk", + "region_code": "uk", + "data_source": "local_area_dataset", +} + + +@pytest.mark.parametrize( + ("changes", "expected_message"), + [ + ( + {"data_source": None}, + 'data_source must be "local_area_dataset" when given', + ), + ( + {"data_source": "local_areas"}, + 'data_source must be "local_area_dataset" when given', + ), + ( + {"country": "us", "region_code": "us"}, + "the local-area dataset is available only to UK reports", + ), + ({"region_code": "constituency/Aldershot"}, "UK-wide or nation region"), + ({"region_code": "local_authority/Cardiff"}, "UK-wide or nation region"), + ], + ids=[ + "null", + "another value", + "another country", + "a constituency", + "a local authority", + ], +) +def test_a_data_source_a_report_cannot_have_is_refused( + client_for, changes, expected_message +) -> None: + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post("/reports", json={**LOCAL_AREA_REPORT_BODY, **changes}) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert reason["loc"][-1] == "data_source" + assert expected_message in reason["msg"] + assert submissions.reports == [] + + +@pytest.mark.parametrize( + ("failure", "status_code", "answer"), + [ + ( + EconomySubmissionRefusedError( + code="local_areas_unsupported", detail="no local-area report runs" + ), + 400, + {"code": "local_areas_unsupported", "detail": "no local-area report runs"}, + ), + ( + EconomySubmissionRefusedError( + code="local_area_dataset_mismatch", detail="another dataset" + ), + 400, + {"code": "local_area_dataset_mismatch", "detail": "another dataset"}, + ), + ( + EconomySubmissionUnprocessableError( + code="no_local_area_dataset", + reasons=( + UnprocessableReason( + loc=("body", "data_source"), + msg="no local-area dataset", + type="no_local_area_dataset", + ), + ), + ), + 422, + { + "detail": [ + { + "loc": ["body", "data_source"], + "msg": "no local-area dataset", + "type": "no_local_area_dataset", + } + ], + "code": "no_local_area_dataset", + }, + ), + ], + ids=["unsupported", "mismatch", "no dataset"], +) +def test_a_local_area_refusal_answers_with_its_code( + client_for, failure, status_code, answer +) -> None: + submissions = FakeEconomySubmissions(failure=failure) + + with client_for(submissions) as client: + result = client.post("/reports", json=LOCAL_AREA_REPORT_BODY) + + assert result.status_code == status_code + assert result.json() == answer + + +@pytest.mark.parametrize( + "body", + [WINDOW_BODY, HOUSEHOLD_REPORT_BODY], + ids=["budget window", "household report"], +) +def test_only_an_economy_report_takes_a_data_source(client_for, body) -> None: + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post( + "/reports", json={**body, "data_source": "local_area_dataset"} + ) + + assert result.status_code == 422 + (reason,) = result.json()["detail"] + assert (reason["loc"][-1], reason["type"]) == ("data_source", "extra_forbidden") + assert submissions.reports == [] + + +@pytest.mark.parametrize( + "region_code", + [ + "uk", + "country/england", + "country/scotland", + "country/wales", + "country/northern_ireland", + ], +) +def test_a_uk_wide_or_nation_report_may_ask_for_the_local_area_dataset( + client_for, region_code +) -> None: + submissions = FakeEconomySubmissions() + + with client_for(submissions) as client: + result = client.post( + "/reports", json={**LOCAL_AREA_REPORT_BODY, "region_code": region_code} + ) + + assert result.status_code == 201 + ((request, _, _),) = submissions.reports + assert request.data_source == "local_area_dataset" + # The report still calculates cliffs. The data source is never stored as + # an option: the dataset it chooses is stored with the report's + # simulations. + assert request.options() == {"include_cliffs": True} + + @pytest.mark.parametrize(("path", "body"), ROUTES) def test_a_refusal_answers_400_with_its_code(client_for, path, body) -> None: submissions = FakeEconomySubmissions( diff --git a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py index 47b9f3137..8865bab37 100644 --- a/projects/policyengine-simulation-entry/tests/test_economy_submissions.py +++ b/projects/policyengine-simulation-entry/tests/test_economy_submissions.py @@ -35,6 +35,7 @@ EconomySubmissionRefusedError, EconomySubmissionUnavailableError, EconomySubmissionUnprocessableError, + read_refusal, ) from policyengine_simulation_entry.economy_workers import ( EconomyWorkerUnavailableError, @@ -48,6 +49,7 @@ EconomyRecordReferenceError, EconomyReportDefinition, EconomyReportState, + EconomyRequest, EconomySimulationDefinition, EconomySimulationState, FoundEconomyReport, @@ -356,24 +358,20 @@ def test_a_parameter_the_policy_and_dynamic_both_set_cannot_be_calculated() -> N ] -@pytest.mark.parametrize( - ("dataset_name", "code"), - [(None, "dataset_not_in_bundle"), ("enhanced_cps_2024", "unknown_dataset")], -) -def test_a_catalog_dataset_the_bundle_lacks_is_refused(dataset_name, code) -> None: +def test_a_region_dataset_the_bundle_lacks_is_the_services_state() -> None: catalog = replace( CATALOG, dataset=CatalogDataset(id=CATALOG.dataset.id, name="enhanced_cps_2024") ) store = FakeStore(catalog=catalog) with pytest.raises(EconomySubmissionRefusedError) as refusal: - _submit_report(service(store), report_request(dataset_name=dataset_name)) + _submit_report(service(store), report_request()) - assert refusal.value.code == code + assert refusal.value.code == "dataset_not_in_bundle" assert store.reports == [] -def test_a_named_dataset_in_the_bundle_is_the_one_calculated() -> None: +def test_the_catalog_dataset_in_the_bundle_is_the_one_calculated() -> None: catalog = replace( CATALOG, dataset=CatalogDataset(id=CATALOG.dataset.id, name=STATE_DATASET.identity), @@ -381,10 +379,7 @@ def test_a_named_dataset_in_the_bundle_is_the_one_calculated() -> None: store = FakeStore(catalog=catalog) caller = FakeCaller() - _submit_report( - service(store, caller=caller), - report_request(dataset_name=STATE_DATASET.identity), - ) + _submit_report(service(store, caller=caller), report_request()) payload = ReportExecutionInput.model_validate(caller.report_runs[0][1]) assert payload.baseline.bundle.dataset.identity == STATE_DATASET.identity @@ -714,13 +709,6 @@ def test_a_reports_overlapping_parameters_are_located_on_their_side() -> None: f"us's catalog version for .py {POLICYENGINE_VERSION} has no region " "state/zz.", ), - ( - UnknownDatasetError(ERROR_TEXT), - {"dataset_name": "acs_2099"}, - "unknown_dataset", - f"us's catalog version for .py {POLICYENGINE_VERSION} has no dataset " - "acs_2099.", - ), ( UnknownDatasetError(ERROR_TEXT), {}, @@ -754,6 +742,25 @@ def test_a_refusals_detail_is_built_from_the_request_not_the_error( assert ERROR_TEXT not in refusal.value.detail +def test_a_stored_dataset_the_catalog_lacks_is_named_in_the_refusal() -> None: + """A request names no dataset, but a re-run reads its stored report's by name.""" + stored = EconomyRequest( + country="us", + policyengine_version=POLICYENGINE_VERSION, + region_code="us", + dataset_name="acs_2099", + year=2026, + ) + + refusal = read_refusal(UnknownDatasetError(ERROR_TEXT), stored) + + assert isinstance(refusal, EconomySubmissionRefusedError) + assert (refusal.code, refusal.detail) == ( + "unknown_dataset", + f"us's catalog version for .py {POLICYENGINE_VERSION} has no dataset acs_2099.", + ) + + def test_a_standalone_simulations_unknown_rows_name_its_own_fields() -> None: for error, detail in ( (UnknownPolicyError(ERROR_TEXT), "us has no stored policy the request names."), diff --git a/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py new file mode 100644 index 000000000..4f0c9e521 --- /dev/null +++ b/projects/policyengine-simulation-entry/tests/test_local_area_submissions.py @@ -0,0 +1,256 @@ +"""Economy reports on the local-area dataset, with the store and Modal faked. + +A UK-wide or nation report created with ``data_source: "local_area_dataset"`` +is calculated on the dataset the default worker's UK entry declares for +local-area report runs (``local_area_reports``): the one the release routes +constituencies and local authorities to. A release that routes them to no +dataset of its own has none, and the request is refused. +""" + +from __future__ import annotations + +import asyncio +from dataclasses import replace +from typing import TYPE_CHECKING, Any +from uuid import UUID + +import pytest +from economy_fixtures import ( + LOCAL_AREA_DATASET, + ROUTED_LOCAL_AREAS, + local_area_worker_version, +) +from economy_rerun_fakes import ( + REPORT_ID, + STORED_REPORT, + FakeRerunStore, + rerun_service, +) +from economy_service_fakes import ( + CATALOG, + REPORT_BODY, + FakeCaller, + FakeStore, + FakeWorkers, + service, +) +from policyengine_simulation_contract.stage12_execution import ReportExecutionInput +from policyengine_simulation_contract.stage12_manifest import LocalAreaReports +from policyengine_simulation_entry.economy_api_models import ( + EconomyReportRequest, + ReportRerunRequest, +) +from policyengine_simulation_entry.economy_submission_errors import ( + EconomySubmissionRefusedError, + EconomySubmissionUnprocessableError, +) +from policyengine_simulation_persistence import ( + CatalogDataset, + LocalAreaDatasetMismatchError, +) + +if TYPE_CHECKING: + from policyengine_simulation_entry.economy_api_models import ( + EconomyReportCreated, + ) + from policyengine_simulation_entry.economy_submissions import ( + EconomySubmissionService, + ) + +# The UK worker's default dataset, which a UK-wide report calculates on. +NATIONAL_DATASET_NAME = "populace_uk_2024" +UK_CATALOG = replace( + CATALOG, + region=replace(CATALOG.region, code="uk"), + dataset=CatalogDataset(id=CATALOG.dataset.id, name=NATIONAL_DATASET_NAME), +) +CATALOG_LOCAL_AREA_DATASET = CatalogDataset( + id=UUID("00000000-0000-4000-8000-0000000000c7"), name=LOCAL_AREA_DATASET.identity +) + + +def _uk_report_request(**changes: Any) -> EconomyReportRequest: + """Return a UK-wide report request, with no SPM settings and no cliffs. + + The service refuses ``include_cliffs: true`` until per-run cliff + calculations exist (C1 · 24's interim answer A). + """ + body = {name: value for name, value in REPORT_BODY.items() if name != "spm"} + return EconomyReportRequest.model_validate( + { + **body, + "country": "uk", + "region_code": "uk", + "include_cliffs": False, + **changes, + } + ) + + +def _local_area_report_request(**changes: Any) -> EconomyReportRequest: + return _uk_report_request(data_source="local_area_dataset", **changes) + + +def _submit( + submissions: EconomySubmissionService, request: EconomyReportRequest +) -> EconomyReportCreated: + return asyncio.run( + submissions.submit_report( + request, request_id="observed", observability_context=None + ) + ) + + +def _workers_declaring(local_area_reports: LocalAreaReports | None) -> FakeWorkers: + return FakeWorkers(worker_version=local_area_worker_version(local_area_reports)) + + +def test_the_uk_worker_fixture_calculates_on_its_default_dataset() -> None: + """The national dataset the tests' UK catalog names is the UK bundle's default.""" + worker = _workers_declaring(None).default_worker("uk") + + assert worker.country.default_dataset == NATIONAL_DATASET_NAME + + +@pytest.mark.parametrize( + "declaration", + [ + None, + LocalAreaReports(input_version=2, dataset=LOCAL_AREA_DATASET.identity), + ], + ids=["no declaration", "another input version"], +) +def test_the_local_area_dataset_the_worker_cannot_run_is_refused_before_any_read( + declaration, +) -> None: + store = FakeStore(catalog=UK_CATALOG) + + with pytest.raises(EconomySubmissionRefusedError) as refusal: + _submit( + service(store, workers=_workers_declaring(declaration)), + _local_area_report_request(), + ) + + assert refusal.value.code == "local_areas_unsupported" + assert store.report_reads == [] + assert store.reports == [] + + +def test_a_report_without_a_data_source_needs_no_declaration() -> None: + store = FakeStore(catalog=UK_CATALOG) + + _submit(service(store, workers=_workers_declaring(None)), _uk_report_request()) + + assert store.local_area_reads == [None] + (report,) = store.reports + assert report.population.dataset_id == UK_CATALOG.dataset.id + + +def test_a_release_that_routes_no_areas_has_no_local_area_dataset() -> None: + """Its national reports calculate both area levels themselves (decision 8).""" + store = FakeStore(catalog=UK_CATALOG) + declaration = LocalAreaReports(input_version=1, dataset=None) + + with pytest.raises(EconomySubmissionUnprocessableError) as refusal: + _submit( + service(store, workers=_workers_declaring(declaration)), + _local_area_report_request(), + ) + + assert refusal.value.code == "no_local_area_dataset" + (reason,) = refusal.value.reasons + assert reason.loc == ("body", "data_source") + assert "routes constituencies and local authorities to no dataset" in reason.msg + assert store.report_reads == [] + assert store.reports == [] + + +def test_the_report_is_calculated_on_the_local_area_dataset_the_worker_routes_to() -> ( + None +): + store = FakeStore(catalog=UK_CATALOG, local_area_dataset=CATALOG_LOCAL_AREA_DATASET) + caller = FakeCaller() + + _submit( + service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS), caller=caller), + _local_area_report_request(), + ) + + assert store.local_area_reads == [LOCAL_AREA_DATASET.identity] + ((request, _),) = store.report_reads + # The dataset comes from the declaration, never from the request. + assert request.dataset_name is None + (report,) = store.reports + assert report.population.dataset_id == CATALOG_LOCAL_AREA_DATASET.id + # Its key names the local-area dataset, so it is found apart from the + # national report on the region's default dataset. + assert report.definition.dataset_name == LOCAL_AREA_DATASET.identity + # An ordinary report: it stores no option but an SPM selection. + assert report.inputs == {} + ((_, payload, _, _),) = caller.report_runs + execution = ReportExecutionInput.model_validate(payload) + for side in (execution.baseline, execution.reform): + assert side.bundle.dataset.identity == LOCAL_AREA_DATASET.identity + assert side.population.artifact.uri == LOCAL_AREA_DATASET.uri + assert side.geography.region == "uk" + assert side.options == {} + + +def test_a_catalog_whose_area_regions_use_another_dataset_is_refused() -> None: + store = FakeStore( + catalog=UK_CATALOG, + read_failure=LocalAreaDatasetMismatchError(LOCAL_AREA_DATASET.identity), + ) + + with pytest.raises(EconomySubmissionRefusedError) as refusal: + _submit( + service(store, workers=_workers_declaring(ROUTED_LOCAL_AREAS)), + _local_area_report_request(), + ) + + assert refusal.value.code == "local_area_dataset_mismatch" + # Written from the declaration, never from the error's text. + assert LOCAL_AREA_DATASET.identity in refusal.value.detail + assert store.reports == [] + + +def test_a_report_on_the_local_area_dataset_is_rerun_on_it() -> None: + """A re-run reads the stored report's dataset by name, and takes no data_source. + + It never reads the worker's local-area declaration, so a worker declaring + none still re-runs the report on its dataset. + """ + stored = replace( + STORED_REPORT, + country="uk", + region_code="uk", + dataset_name=LOCAL_AREA_DATASET.identity, + inputs={}, + ) + store = FakeRerunStore( + report_definition=stored, + catalog=replace(UK_CATALOG, dataset=CATALOG_LOCAL_AREA_DATASET), + ) + caller = FakeCaller() + + asyncio.run( + rerun_service( + store, workers=_workers_declaring(None), caller=caller + ).rerun_report( + REPORT_ID, + ReportRerunRequest(), + request_id="observed", + observability_context=None, + ) + ) + + ((request, _),) = store.rerun_reads + assert (request.region_code, request.dataset_name) == ( + "uk", + LOCAL_AREA_DATASET.identity, + ) + ((_, payload, _, _),) = caller.report_runs + execution = ReportExecutionInput.model_validate(payload) + for side in (execution.baseline, execution.reform): + assert side.bundle.dataset.identity == LOCAL_AREA_DATASET.identity + assert side.geography.region == "uk" diff --git a/projects/policyengine-simulation-entry/tests/test_openapi.py b/projects/policyengine-simulation-entry/tests/test_openapi.py index 14cc01a94..d80944bd2 100644 --- a/projects/policyengine-simulation-entry/tests/test_openapi.py +++ b/projects/policyengine-simulation-entry/tests/test_openapi.py @@ -511,18 +511,17 @@ def test_economy_requests_name_no_version_and_no_record_id(): "description", "year", "region_code", - "dataset_name", "baseline", "reform", "include_cliffs", "spm", + "data_source", } assert set(schemas["EconomySimulationRequest"]["properties"]) == { "country", "simulation_type", "year", "region_code", - "dataset_name", "policy_id", "dynamic_id", } @@ -531,6 +530,12 @@ def test_economy_requests_name_no_version_and_no_record_id(): assert spm["$ref"] == "#/components/schemas/SPMSelection" assert "default" not in spm assert "spm" not in schemas["EconomyReportRequest"].get("required", []) + # Omitted, not null, unless the caller asks for the local-area dataset. + data_source = schemas["EconomyReportRequest"]["properties"]["data_source"] + assert data_source["const"] == "local_area_dataset" + assert data_source["type"] == "string" + assert "default" not in data_source + assert "data_source" not in schemas["EconomyReportRequest"].get("required", []) def test_a_reports_label_and_description_are_optional_and_never_stored(): @@ -573,7 +578,6 @@ def test_a_report_request_is_an_economy_report_a_budget_window_or_a_household(): "year", "budget_window_size", "region_code", - "dataset_name", "baseline", "reform", "spm", @@ -635,3 +639,16 @@ def test_economy_reads_declare_every_answer(): names = operation_ids(cast("OpenAPIDocument", spec)) assert names[("GET", "/reports/{report_id}")] == "get_report" assert names[("GET", "/simulations/{simulation_id}")] == "get_simulation" + + +def test_the_local_area_refusals_are_in_the_error_codes(): + """A report on the local-area dataset has two 400 codes and one 422 code.""" + schemas = create_app().openapi()["components"]["schemas"] + + error_codes = set(schemas["EconomyError"]["properties"]["code"]["enum"]) + unprocessable_codes = set( + schemas["EconomyRequestUnprocessable"]["properties"]["code"]["enum"] + ) + + assert {"local_areas_unsupported", "local_area_dataset_mismatch"} <= error_codes + assert "no_local_area_dataset" in unprocessable_codes