diff --git a/changelog.d/report-cliffs-from-simulation-runs.changed.md b/changelog.d/report-cliffs-from-simulation-runs.changed.md new file mode 100644 index 000000000..8d3b1ebb0 --- /dev/null +++ b/changelog.d/report-cliffs-from-simulation-runs.changed.md @@ -0,0 +1 @@ +`/v2/reports` reads a report run's cliff impact from its two simulation runs' cliff results, never from the report run's own cliff columns, and each economy report read gives `cliffs`: how far each side's cliff calculation has got. `POST /v2/reports/{report_id}/runs` takes `include_cliffs`, which a household report or budget window refuses with 422. diff --git a/policyengine_api/fastapi_routes/resource_service_protocols.py b/policyengine_api/fastapi_routes/resource_service_protocols.py index aa2818879..ea08e7113 100644 --- a/policyengine_api/fastapi_routes/resource_service_protocols.py +++ b/policyengine_api/fastapi_routes/resource_service_protocols.py @@ -285,11 +285,15 @@ def rerun_report( country_id: str, report_id: UUID, force: bool, + include_cliffs: bool = False, requester: AccountPrincipal | None = None, ) -> StoredReportRead: """Run the country's report again; return it with the run the request ended on. That is the run the simulation service named, created or joined. + With ``include_cliffs``, it also starts the cliff calculations an + economy report run's simulation runs lack; ``CliffsNotAvailableError`` + is raised, before anything is asked, for any other kind. With a ``requester``, the request is recorded for its user once the simulation service has answered, and ``StandardUserRequiresSignInError`` is raised, before anything is diff --git a/policyengine_api/fastapi_routes/v2/reports/response_models.py b/policyengine_api/fastapi_routes/v2/reports/response_models.py index 3b9e3c760..6e8e190c3 100644 --- a/policyengine_api/fastapi_routes/v2/reports/response_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/response_models.py @@ -140,14 +140,60 @@ def from_summary(cls, read: ReportSummaryRead) -> ReportSummaryItem: return cls.model_validate(read) +# How far a side's cliff calculation has got. +CliffCalculationStatus = Literal[ + "not_calculated", "pending", "running", "succeeded", "failed" +] + + +class CliffCalculationItem(StrictReportAPIModel): + """How far one side's cliff calculation of its simulation run has got. + + ``status`` is ``not_calculated`` while the simulation run has no cliff + calculation, ``pending`` or ``running`` while one is under way, + ``succeeded`` once it has its result, and ``failed`` once its newest + calculation failed and none is under way; ``error_message`` then says + why, and is null otherwise. + """ + + status: CliffCalculationStatus + error_message: str | None + + +class ReportCliffsItem(StrictReportAPIModel): + """How far the cliff calculations of the run read's two simulation runs have got. + + A simulation run's cliffs are calculated apart from it, once, when a + create or re-run asks with ``include_cliffs``, and every report naming + the run shares them. ``status`` is ``succeeded`` once both sides are; + otherwise ``failed`` when either side is, else ``not_calculated`` when + either side is, else ``running`` when either side is, else ``pending``. + Running the report again with ``include_cliffs`` on the current versions + starts a new calculation for each side that is ``not_calculated`` or + ``failed``, and joins one under way; a run on older versions is not run + again, so its re-run answers another run, with that run's ``cliffs``. A + report naming one simulation run on both sides gives its calculation for + each. + """ + + status: CliffCalculationStatus + baseline: CliffCalculationItem + reform: CliffCalculationItem + + class ReportItem(ReportSummaryItem): """An economy report with its run's result. ``result`` is the single-year economy result, in the format the app reads - today, once the run read has succeeded, and null otherwise. + today, once the run read has succeeded, and null otherwise. Its + ``cliff_impact`` is the two simulation runs' cliff results once ``cliffs`` + is ``succeeded``, and null otherwise. ``cliffs`` says how far their cliff + calculations have got, whatever the run's status, and is null for a + report with no run. """ result: EconomyResult | None + cliffs: ReportCliffsItem | None @classmethod def from_read(cls, read: ReportRead) -> ReportItem: diff --git a/policyengine_api/fastapi_routes/v2/reports/routes.py b/policyengine_api/fastapi_routes/v2/reports/routes.py index 2628f3053..e4586ae6a 100644 --- a/policyengine_api/fastapi_routes/v2/reports/routes.py +++ b/policyengine_api/fastapi_routes/v2/reports/routes.py @@ -99,6 +99,7 @@ HouseholdResultUnreadableError, ) from policyengine_api.services.v2.stored_reports.validators import ( + CliffsNotAvailableError, CreatedReportUnreadableError, ForcedRerunRequiresAdminError, ForcedRerunRequiresSignInError, @@ -131,11 +132,13 @@ StoredReportNotFoundError, ReportRunNotFoundError, ForcedRerunRequiresAdminError, + CliffsNotAvailableError, *SUBMISSION_REFUSALS, ) REPORT_ERROR_MAPPINGS = ( V2ErrorMapping((StoredReportNotFoundError, ReportRunNotFoundError), 404), V2ErrorMapping((ForcedRerunRequiresAdminError,), 403), + V2ErrorMapping((CliffsNotAvailableError,), 422), *SUBMISSION_ERROR_MAPPINGS, V2ErrorMapping( ( @@ -321,10 +324,10 @@ def _rerun_report( *, country_id: str, report_id: UUID, - force: bool, + body: ReportRerunRequest, requester: AccountPrincipal | None, ) -> ReportDetailResponse | JSONResponse: - """Run the report again and answer it with the run the request ended on. + """Run the report again, as ``body`` asks; answer it with the run it ended on. The simulation service's refusal to run it again now answers 409 with the run it names; a report that cannot be read back once its run started @@ -339,7 +342,8 @@ def _rerun_report( report = service.rerun_report( country_id=country_id, report_id=report_id, - force=force, + force=body.force, + include_cliffs=body.include_cliffs, requester=requester, ) except (StandardUserRequiresSignInError, ForcedRerunRequiresSignInError) as error: @@ -390,7 +394,12 @@ def _add_report_run_routes( "side reuses a run of its own simulation that succeeded on those " "versions; with force, both simulations are calculated again. A " "household report's sides are always calculated again, so force " - "changes nothing for it. A budget window's new run is a " + "changes nothing for it. With include_cliffs, the simulation " + "service also starts a cliff calculation for each of an economy " + "report run's simulation runs that has none, or whose newest one " + "failed, and the answer's cliffs says how far they have got; a " + "household report or budget window asking for cliffs answers 422 " + "before anything is asked. A budget window's new run is a " "budget-window run with a report run for each year, and " "with force each year calculates its simulations again. Answers the " "report as stored, with the run the simulation service named (a " @@ -416,7 +425,7 @@ def rerun() -> ReportDetailResponse | JSONResponse: service_factory(), country_id=query.country_id, report_id=report_id, - force=body.force, + body=body, requester=requester, ) @@ -475,8 +484,12 @@ def build_v2_report_router(dependencies: NativeRouteDependencies) -> APIRouter: "local authority's impact and the codes of those withheld; the " "simulation service takes it for uk and its four nations only, on a " "release that gives local areas a dataset of their own, and the " - "Public API answers its refusal with 422. A household report (kind " - "household) " + "Public API answers its refusal with 422. With include_cliffs, the " + "simulation service also starts a cliff calculation for each of an " + "economy report's two simulation runs that has none, or whose newest " + "one failed, and joins one under way; a simulation service that " + "doesn't calculate cliffs per simulation run yet refuses it with 422. " + "A household report (kind household) " "is checked the same way, except that the country must have " "household calculations instead (a household-only country does), " "and the household it names must be stored in the country, with a " @@ -564,7 +577,10 @@ def read() -> ReportListResponse | JSONResponse: "its result. Its label and description are the requesting user's " "saved report's name and description, null without a user " "credential or a saved report. An economy report's run is one report " - "run and its result today's economy result. A household report's " + "run and its result today's economy result; its cliffs say how far " + "the cliff calculations of the run's two simulation runs have got, " + "whatever the run's status, and the result's cliff_impact holds them " + "once both have succeeded. A household report's " "result is each simulation's calculated household, as " "/v2/household-calculations answers one, and a failed run gives each " "side's error. A budget window's run is a budget-window run with a " diff --git a/policyengine_api/fastapi_routes/v2/reports/run_models.py b/policyengine_api/fastapi_routes/v2/reports/run_models.py index 4680fa289..b2a3a02d1 100644 --- a/policyengine_api/fastapi_routes/v2/reports/run_models.py +++ b/policyengine_api/fastapi_routes/v2/reports/run_models.py @@ -44,10 +44,17 @@ class ReportRerunRequest(StrictSubmissionModel): Without ``force`` (``{}``), each side reuses a run of its own simulation that succeeded on those versions; with it, both simulations are calculated again. A household report's sides are always calculated - again. The new run is kept beside every earlier one. + again. The new run is kept beside every earlier one. ``include_cliffs`` + also starts a cliff calculation for each of the run's two simulation + runs that has none, or whose newest one failed, and joins one under way; + the report's ``cliffs`` then says how far they have got. Only an + economy report has cliffs: a household report or budget window asking + for them is refused with 422, and so is any request with it while the + simulation service doesn't calculate cliffs per simulation run yet. """ force: StrictBool = False + include_cliffs: StrictBool = False class ReportRunListResult(StrictReportAPIModel): @@ -178,7 +185,9 @@ class RerunReportUnreadableResponse(V2ErrorResponse): 422: { "model": V2MissingParametersErrorResponse | V2ErrorResponse, "description": ( - "The request does not match the schema; the country has no economy " + "The request does not match the schema; a household report or " + "budget window asks for cliffs (include_cliffs), which only an " + "economy report has; the country has no economy " "reports, or no household calculations for a household report; a " "policy of the report's simulations sets " "parameters the running catalog version does not have (code " diff --git a/policyengine_api/libs/simulation_report_reruns.py b/policyengine_api/libs/simulation_report_reruns.py index 8f8d2e636..157d4db1c 100644 --- a/policyengine_api/libs/simulation_report_reruns.py +++ b/policyengine_api/libs/simulation_report_reruns.py @@ -3,10 +3,14 @@ ``start_report_rerun`` is what ``SimulationServiceReportClient.rerun_report`` does: it posts ``{"force": …}`` to the Cloud Run simulation service's ``POST /reports/{report_id}/runs``, through the same HTTP client as the -service's other v2 routes (``policyengine_api.libs.simulation_reports``). -The service creates the stored report's new run on its default worker's +service's other v2 routes (``policyengine_api.libs.simulation_reports``), +with ``"include_cliffs": true`` when the re-run asks for cliffs. The +service creates the stored report's new run on its default worker's versions and starts it, keeping every earlier run. Without ``force``, each side reuses a run of its own simulation that succeeded on those versions. +With ``include_cliffs``, it also starts a cliff calculation for each side's +simulation run that has none; until it calculates cliffs per simulation +run, it refuses the field with 422, which is passed on as any 422 is. The Public API reads the report in its country before asking, so it never asks about a report it does not have. The simulation service answers: @@ -132,8 +136,16 @@ def report_runs_path(report_id: UUID) -> str: def report_rerun_request(rerun: ReportRerunInput) -> dict[str, Any]: - """Return the simulation service's request body for the re-run.""" - return {"force": rerun.force} + """Return the simulation service's request body for the re-run. + + ``include_cliffs`` is sent only when true: a simulation service from + before cliffs were calculated per simulation run refuses the field, so a + re-run that doesn't ask for cliffs still runs there. + """ + body: dict[str, Any] = {"force": rerun.force} + if rerun.include_cliffs: + body["include_cliffs"] = True + return body def post_report_rerun( diff --git a/policyengine_api/services/v2/simulation_service/types.py b/policyengine_api/services/v2/simulation_service/types.py index 4691ba88e..402c3d270 100644 --- a/policyengine_api/services/v2/simulation_service/types.py +++ b/policyengine_api/services/v2/simulation_service/types.py @@ -258,12 +258,17 @@ def require_spm_object(cls, value: object) -> object: class EconomyReportFields(ReportDefinitionFields): """An economy report: a baseline and a reform simulation of one region's data. - ``include_cliffs`` also calculates the baseline's and reform's cliff - impact. ``data_source`` ``local_area_dataset`` calculates both - simulations on the dataset the catalog version gives local areas - instead of the region's, so the result also has each constituency's and - local authority's impact and the codes of those disclosure control - withheld; omit it, rather than sending null, for the region's dataset. + ``include_cliffs`` also starts a cliff calculation for each of the two + simulation runs that has none, or whose newest one failed, and joins one + under way: a simulation run's cliffs are calculated once, apart from it, + and every report naming the run shares them. It is never stored. The + report's ``cliffs`` says how far they have got, and its result's + ``cliff_impact`` holds them once both have succeeded. + ``data_source`` ``local_area_dataset`` calculates both simulations on + the dataset the catalog version gives local areas instead of the + region's, so the result also has each constituency's and local + authority's impact and the codes of those disclosure control withheld; + omit it, rather than sending null, for the region's dataset. The simulation service takes it only for ``uk`` and the four ``country/*`` nations, on a release that gives local areas a dataset of their own, and refuses it with 422 otherwise: the Public API checks only @@ -427,7 +432,9 @@ class ReportRerunInput: economy calculations. ``policy_ids`` are the policies of the report's simulations, baseline first, None for current law, a report of the baseline alone or a simulation that is gone, for the checks before the - simulation service is asked. + simulation service is asked. ``include_cliffs``, only for an economy + report, also starts a cliff calculation for each side's simulation run + that has none, or whose newest one failed; it is sent only when true. """ country_id: str @@ -435,6 +442,7 @@ class ReportRerunInput: kind: ReportRerunKind force: bool policy_ids: tuple[UUID | None, ...] + include_cliffs: bool = False class SimulationServiceClient(Protocol): diff --git a/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py b/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py index c5285fb41..bec67bdfa 100644 --- a/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py +++ b/policyengine_api/services/v2/stored_reports/database_connectors/reads_results.py @@ -4,10 +4,12 @@ from typing import TYPE_CHECKING +from sqlalchemy import case from sqlmodel import col, select from policyengine_api.data.v2.models import ( BudgetSummary, + CliffImpact, CongressionalDistrictImpact, ConstituencyImpact, DecileImpact, @@ -18,10 +20,12 @@ LocalAuthorityImpact, Poverty, ProgramStatistics, + SimulationStatus, WithheldAreaCode, ) from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultRows, + ReportRunCliffRows, ReportRunResultColumns, ) @@ -33,13 +37,57 @@ from policyengine_api.data.v2.models import ReportRun -def read_economy_result_rows( +def _side_cliff_calculation( + session: Session, simulation_run_id: UUID +) -> CliffImpact | None: + """Return the run's unfailed cliff calculation, else its newest failed one. + + A run has at most one calculation that hasn't failed + (``uq_cliff_impacts_unfailed``), so ordering failed ones last reads it + first; among failed ones, the newest is read, the larger ID breaking a + tie in creation time. + """ + return session.exec( + select(CliffImpact) + .where(CliffImpact.simulation_run_id == simulation_run_id) + .order_by( + case((col(CliffImpact.status) == SimulationStatus.FAILED, 1), else_=0), + col(CliffImpact.created_at).desc(), + col(CliffImpact.id).desc(), + ) + .limit(1) + ).first() + + +def read_cliff_calculations( + session: Session, + *, + baseline_simulation_run_id: UUID, + reform_simulation_run_id: UUID, +) -> ReportRunCliffRows: + """Return each side's cliff calculation of its simulation run, or None. + + It is the run's calculation that hasn't failed, else its newest failed + one: one query per distinct run, so a report run naming one simulation + run on both sides reads it once, for both. + """ + baseline = _side_cliff_calculation(session, baseline_simulation_run_id) + reform = ( + baseline + if reform_simulation_run_id == baseline_simulation_run_id + else _side_cliff_calculation(session, reform_simulation_run_id) + ) + return ReportRunCliffRows(baseline=baseline, reform=reform) + + +def read_economy_result_rows( # noqa: PLR0913 # the session, then each part of the run the read needs session: Session, *, country_id: str, report_run: ReportRun, reform_simulation_run_id: UUID, on_local_area_dataset: bool, + cliff_calculations: ReportRunCliffRows, ) -> EconomyResultRows: """Return every result row of ``report_run``, one query per result table. @@ -47,6 +95,9 @@ def read_economy_result_rows( inequality rows are those of its baseline and reform simulation runs. The withheld area codes are read only for a local-area report's run (``on_local_area_dataset``), whose writer records them. + ``cliff_calculations`` are its simulation runs' cliff calculations, as + ``read_cliff_calculations`` read them. The report run's own four cliff + columns are not read. """ report_run_id = report_run.id simulation_run_ids = ( @@ -59,10 +110,6 @@ def read_economy_result_rows( country_package_version=report_run.country_package_version, data_version=report_run.data_version, spm_provenance=report_run.spm_provenance, - baseline_cliff_gap=report_run.baseline_cliff_gap, - baseline_cliff_share=report_run.baseline_cliff_share, - reform_cliff_gap=report_run.reform_cliff_gap, - reform_cliff_share=report_run.reform_cliff_share, ), baseline_simulation_run_id=report_run.baseline_simulation_run_id, reform_simulation_run_id=reform_simulation_run_id, @@ -141,6 +188,7 @@ def read_economy_result_rows( ) ) ), + cliff_calculations=cliff_calculations, on_local_area_dataset=on_local_area_dataset, withheld_area_codes=( tuple( diff --git a/policyengine_api/services/v2/stored_reports/economy_results/transformations.py b/policyengine_api/services/v2/stored_reports/economy_results/transformations.py index 4909fad68..d82ed8962 100644 --- a/policyengine_api/services/v2/stored_reports/economy_results/transformations.py +++ b/policyengine_api/services/v2/stored_reports/economy_results/transformations.py @@ -24,9 +24,12 @@ order. - ``constituency_withheld_codes`` and ``local_authority_withheld_codes``, for a local-area report only, from ``withheld_area_codes``, sorted. -- ``cliff_impact``, ``spm_provenance``, ``data_version`` and - ``model_version`` from the report run's own columns; the SPM receipts are - read as ``SPMComparisonProvenance``. +- ``cliff_impact`` from each simulation run's cliff calculation + (``cliff_impacts``), once both have succeeded, and never from the report + run's own four cliff columns. +- ``spm_provenance``, ``data_version`` and ``model_version`` from the report + run's own columns; the SPM receipts are read as + ``SPMComparisonProvenance``. An optional part with no rows is null. The writer stores no rows for an empty list either, so a UK result whose areas were all withheld reads back with @@ -41,6 +44,7 @@ from pydantic import ValidationError +from policyengine_api.data.v2.models import SimulationStatus from policyengine_api.services.v2.stored_reports.economy_results.types import ( AgePoverty, BaselineReformValue, @@ -77,6 +81,7 @@ from pydantic import JsonValue from policyengine_api.data.v2.models import BudgetSummary as BudgetSummaryRow + from policyengine_api.data.v2.models import CliffImpact as CliffImpactRow from policyengine_api.data.v2.models import ( CongressionalDistrictImpact as CongressionalDistrictImpactRow, ) @@ -87,7 +92,7 @@ from policyengine_api.data.v2.models import Poverty as PovertyRow from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultRows, - ReportRunResultColumns, + ReportRunCliffRows, ) # .py's poverty types behind the result's "poverty" and "deep_poverty". @@ -253,7 +258,7 @@ def economy_result(rows: EconomyResultRows) -> EconomyResult: congressional_district_impact=_districts(rows.congressional_district_impacts), constituency_withheld_codes=_withheld_codes(rows, "constituency"), local_authority_withheld_codes=_withheld_codes(rows, "local_authority"), - cliff_impact=_cliff_impact(report_run), + cliff_impact=cliff_impact(rows.cliff_calculations), ) @@ -601,25 +606,30 @@ def _districts( ) -def _cliff_impact(report_run: ReportRunResultColumns) -> CliffImpact | None: - """Return the cliff impact, or None when the run stores none. +def _cliff_result(calculation: CliffImpactRow | None) -> CliffImpactInSimulation | None: + """Return a side's cliff result, or None until its calculation has succeeded. - The database keeps the four columns all set or all null. + The table's check keeps both numbers set exactly when it has succeeded. """ if ( - report_run.baseline_cliff_gap is None - or report_run.baseline_cliff_share is None - or report_run.reform_cliff_gap is None - or report_run.reform_cliff_share is None + calculation is None + or calculation.status is not SimulationStatus.SUCCEEDED + or calculation.cliff_gap is None + or calculation.cliff_share is None ): return None - return CliffImpact( - baseline=CliffImpactInSimulation( - cliff_gap=report_run.baseline_cliff_gap, - cliff_share=report_run.baseline_cliff_share, - ), - reform=CliffImpactInSimulation( - cliff_gap=report_run.reform_cliff_gap, - cliff_share=report_run.reform_cliff_share, - ), + return CliffImpactInSimulation( + cliff_gap=calculation.cliff_gap, cliff_share=calculation.cliff_share ) + + +def cliff_impact(cliff_calculations: ReportRunCliffRows) -> CliffImpact | None: + """Return the report run's cliff impact, or None until both sides have one. + + Each side's is its simulation run's succeeded cliff calculation. + """ + baseline = _cliff_result(cliff_calculations.baseline) + reform = _cliff_result(cliff_calculations.reform) + if baseline is None or reform is None: + return None + return CliffImpact(baseline=baseline, reform=reform) diff --git a/policyengine_api/services/v2/stored_reports/economy_results/types.py b/policyengine_api/services/v2/stored_reports/economy_results/types.py index fb25dd75c..6428c9020 100644 --- a/policyengine_api/services/v2/stored_reports/economy_results/types.py +++ b/policyengine_api/services/v2/stored_reports/economy_results/types.py @@ -30,6 +30,7 @@ # The tables' models, named apart from the result parts they hold. from policyengine_api.data.v2.models import BudgetSummary as BudgetSummaryRow + from policyengine_api.data.v2.models import CliffImpact as CliffImpactRow from policyengine_api.data.v2.models import ( CongressionalDistrictImpact as CongressionalDistrictImpactRow, ) @@ -325,8 +326,11 @@ class EconomyResult(EconomyResultModel): and ``local_authority_withheld_codes`` are a local-area report's sorted codes of the areas each level withheld, empty when it withheld none; for every other report they are null and left out of the JSON, as the - simulation service leaves them out. ``labor_supply_response`` and - ``cliff_impact`` are null when the run did not compute them. + simulation service leaves them out. ``labor_supply_response`` is null + when the run did not compute it, and ``cliff_impact`` until both + simulation runs' cliff calculations have succeeded: a run's cliffs are + calculated apart from it, and the report's ``cliffs`` says how far they + have got. """ spm_provenance: SPMComparisonProvenance | None @@ -359,17 +363,26 @@ class EconomyResult(EconomyResultModel): class ReportRunResultColumns: """The result columns of the report run itself. - ``country_package_version`` is the run's; the four cliff columns are all - set or all null. + ``country_package_version`` is the run's. Its four cliff columns are not + read: a report run's cliffs are its simulation runs' (``cliff_impacts``). """ country_package_version: str data_version: str | None spm_provenance: dict[str, JsonValue] | None - baseline_cliff_gap: float | None - baseline_cliff_share: float | None - reform_cliff_gap: float | None - reform_cliff_share: float | None + + +@dataclass(frozen=True) +class ReportRunCliffRows: + """Each side's cliff calculation of the simulation run the report run names. + + It is the run's calculation that hasn't failed, of which it has at most + one, else its newest failed one, else None. A report run naming one + simulation run on both sides has the same calculation on each. + """ + + baseline: CliffImpactRow | None + reform: CliffImpactRow | None @dataclass(frozen=True) @@ -377,10 +390,11 @@ class EconomyResultRows: """Every result row of one report run, as the database connectors read them. The comparison tables' rows are the report run's; the poverty and - inequality rows are those of its baseline and reform simulation runs. - ``on_local_area_dataset`` says whether the run is a local-area report's, - whose ``withheld_area_codes`` rows are read and list every area its - writer withheld; for any other run they are not read. + inequality rows, and the cliff calculations, are those of its baseline + and reform simulation runs. ``on_local_area_dataset`` says whether the + run is a local-area report's, whose ``withheld_area_codes`` rows are + read and list every area its writer withheld; for any other run they are + not read. """ country_id: str @@ -398,5 +412,6 @@ class EconomyResultRows: congressional_district_impacts: tuple[CongressionalDistrictImpactRow, ...] constituency_impacts: tuple[ConstituencyImpactRow, ...] local_authority_impacts: tuple[LocalAuthorityImpactRow, ...] + cliff_calculations: ReportRunCliffRows on_local_area_dataset: bool = False withheld_area_codes: tuple[WithheldAreaCodeRow, ...] = () diff --git a/policyengine_api/services/v2/stored_reports/requester_views/__init__.py b/policyengine_api/services/v2/stored_reports/requester_views/__init__.py new file mode 100644 index 000000000..7eab48c57 --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/requester_views/__init__.py @@ -0,0 +1 @@ +"""Reports as the requesting user sees them: their labels and requested runs.""" diff --git a/policyengine_api/services/v2/stored_reports/requester_views/services.py b/policyengine_api/services/v2/stored_reports/requester_views/services.py new file mode 100644 index 000000000..bc5474c4a --- /dev/null +++ b/policyengine_api/services/v2/stored_reports/requester_views/services.py @@ -0,0 +1,118 @@ +"""Reports as the requesting user sees them. + +A report's label and description are the requesting user's saved report's, +and a report the user asked to run is read with the run of their newest +request in place of its default. ``requesters_view`` gives that view of the +rows the report service read; it moved here from +``policyengine_api.services.v2.stored_reports.services`` unchanged. +""" + +from __future__ import annotations + +from dataclasses import replace +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.identity.services import ( + find_principal_user_in_session, +) +from policyengine_api.services.v2.stored_reports.database_connectors import ( + reads_requests as request_reads, +) +from policyengine_api.services.v2.stored_reports.database_connectors.reads import ( + read_budget_window_years, +) + +if TYPE_CHECKING: + from collections.abc import Sequence + from uuid import UUID + + from sqlmodel import Session + + from policyengine_api.services.v2.identity.types import AccountPrincipal + from policyengine_api.services.v2.stored_reports.types import ( + StoredReportRows, + ) + + +def _viewer_user_id( + session: Session, + *, + requester: AccountPrincipal | None, + recorded_user_id: UUID | None, +) -> UUID | None: + """Return the ID of the user a read is for. + + That is ``recorded_user_id`` when a request was just recorded for it, or + else the requester's stored user's, or None. + """ + if recorded_user_id is not None: + return recorded_user_id + if requester is None: + return None + user = find_principal_user_in_session(session, requester) + return None if user is None else user.user_id + + +def requesters_view( + session: Session, + rows: Sequence[StoredReportRows], + *, + requester: AccountPrincipal | None, + recorded_user_id: UUID | None = None, + with_requested_runs: bool, +) -> list[StoredReportRows]: + """Return the reports as the requester sees them. + + The requester's stored user is looked up, unless ``recorded_user_id`` + names the user a request was just recorded for. Each report takes its + label and description from that user's saved report of it. With + ``with_requested_runs``, a report the user asked to run + is read with the run of their newest request in place of its default (a + budget window's with that year's budget-window run and its years). A + request naming no user, or a user not stored yet, sees each report's + default run and no label. Raise StandardUserRequiresSignInError for an + unauthenticated credential that names a signed-in user. + """ + user_id = _viewer_user_id( + session, requester=requester, recorded_user_id=recorded_user_id + ) + if user_id is None or not rows: + return list(rows) + report_ids = [stored.report.id for stored in rows] + labels = request_reads.read_saved_report_labels( + session, user_id=user_id, report_ids=report_ids + ) + requested_runs = ( + request_reads.read_requested_report_runs( + session, user_id=user_id, report_ids=report_ids + ) + if with_requested_runs + else {} + ) + window_run_ids = [ + run.budget_window_run_id + for run in requested_runs.values() + if run.budget_window_run_id is not None + ] + window_runs = request_reads.read_budget_window_runs_by_id( + session, budget_window_run_ids=window_run_ids + ) + window_years = read_budget_window_years(session, window_run_ids) + viewed = [] + for stored in rows: + name, description = labels.get(stored.report.id, (None, None)) + seen = replace( + stored, saved_report_name=name, saved_report_description=description + ) + requested = requested_runs.get(stored.report.id) + if requested is not None and requested.budget_window_run_id is None: + seen = replace(seen, run=requested) + elif requested is not None and requested.budget_window_run_id in window_runs: + window_run_id = requested.budget_window_run_id + seen = replace( + seen, + budget_window_run=window_runs[window_run_id], + budget_window_years=window_years.get(window_run_id, ()), + ) + viewed.append(seen) + return viewed diff --git a/policyengine_api/services/v2/stored_reports/services.py b/policyengine_api/services/v2/stored_reports/services.py index 9107b5192..5d095065e 100644 --- a/policyengine_api/services/v2/stored_reports/services.py +++ b/policyengine_api/services/v2/stored_reports/services.py @@ -17,7 +17,8 @@ The result is rebuilt from the run's result rows once it has succeeded; a local-area report's (a UK-wide or nation report on the dataset its catalog -version gives local areas) also lists its withheld area codes. A +version gives local areas) also lists its withheld area codes. An economy +report's read also gives its run's cliffs (``ReportCliffsRead``). A budget-window report's run is a budget-window run, read with its years; once that run has succeeded, its result is the budget-window format, rebuilt from each year's budget rows. Reading a @@ -67,9 +68,6 @@ from policyengine_api.data.v2.models import ReportRunStatus, ReportRunTrigger from policyengine_api.data.v2.models.base import utc_now from policyengine_api.query_parameters import MAXIMUM_LISTED_REPORTS -from policyengine_api.services.v2.identity.services import ( - find_principal_user_in_session, -) from policyengine_api.services.v2.report_run_records.types import ReportRunRequest from policyengine_api.services.v2.simulation_service.types import ( ReportRerunInput, @@ -84,9 +82,6 @@ from policyengine_api.services.v2.stored_reports.database_connectors import ( reads_household_results as household_result_reads, ) -from policyengine_api.services.v2.stored_reports.database_connectors import ( - reads_requests as request_reads, -) from policyengine_api.services.v2.stored_reports.database_connectors import ( reads_results as result_reads, ) @@ -110,6 +105,9 @@ from policyengine_api.services.v2.stored_reports.household_results.validators import ( require_household_report_result, ) +from policyengine_api.services.v2.stored_reports.requester_views.services import ( + requesters_view, +) from policyengine_api.services.v2.stored_reports.transformations import ( budget_window_read, budget_window_runs_read, @@ -117,6 +115,7 @@ household_report_read, household_report_summary_read, listed_reports, + report_cliffs, report_kind, report_policy_ids, report_read, @@ -130,6 +129,7 @@ ReportStorageError, RerunReportUnreadableError, require_admin_to_force, + require_cliffs_available, require_reform_run, require_report, require_report_run, @@ -157,6 +157,7 @@ from policyengine_api.services.v2.stored_reports.types import ( BudgetWindowReportRead, HouseholdReportRead, + ReportRead, StoredReportRead, StoredReportRows, StoredReportRunsRead, @@ -245,90 +246,6 @@ def _record_request(recording: _RunRecording, request: ReportRunRequest) -> UUID ) from error -def _viewer_user_id( - session: Session, - *, - requester: AccountPrincipal | None, - recorded_user_id: UUID | None, -) -> UUID | None: - """Return the ID of the user a read is for. - - That is ``recorded_user_id`` when a request was just recorded for it, or - else the requester's stored user's, or None. - """ - if recorded_user_id is not None: - return recorded_user_id - if requester is None: - return None - user = find_principal_user_in_session(session, requester) - return None if user is None else user.user_id - - -def _requesters_view( - session: Session, - rows: Sequence[StoredReportRows], - *, - requester: AccountPrincipal | None, - recorded_user_id: UUID | None = None, - with_requested_runs: bool, -) -> list[StoredReportRows]: - """Return the reports as the requester sees them. - - The requester's stored user is looked up, unless ``recorded_user_id`` - names the user a request was just recorded for. Each report takes its - label and description from that user's saved report of it. With - ``with_requested_runs``, a report the user asked to run - is read with the run of their newest request in place of its default (a - budget window's with that year's budget-window run and its years). A - request naming no user, or a user not stored yet, sees each report's - default run and no label. Raise StandardUserRequiresSignInError for an - unauthenticated credential that names a signed-in user. - """ - user_id = _viewer_user_id( - session, requester=requester, recorded_user_id=recorded_user_id - ) - if user_id is None or not rows: - return list(rows) - report_ids = [stored.report.id for stored in rows] - labels = request_reads.read_saved_report_labels( - session, user_id=user_id, report_ids=report_ids - ) - requested_runs = ( - request_reads.read_requested_report_runs( - session, user_id=user_id, report_ids=report_ids - ) - if with_requested_runs - else {} - ) - window_run_ids = [ - run.budget_window_run_id - for run in requested_runs.values() - if run.budget_window_run_id is not None - ] - window_runs = request_reads.read_budget_window_runs_by_id( - session, budget_window_run_ids=window_run_ids - ) - window_years = read_budget_window_years(session, window_run_ids) - viewed = [] - for stored in rows: - name, description = labels.get(stored.report.id, (None, None)) - seen = replace( - stored, saved_report_name=name, saved_report_description=description - ) - requested = requested_runs.get(stored.report.id) - if requested is not None and requested.budget_window_run_id is None: - seen = replace(seen, run=requested) - elif requested is not None and requested.budget_window_run_id in window_runs: - window_run_id = requested.budget_window_run_id - seen = replace( - seen, - budget_window_run=window_runs[window_run_id], - budget_window_years=window_years.get(window_run_id, ()), - ) - viewed.append(seen) - return viewed - - def _summary_read( stored: StoredReportRows, *, current_versions: PackageVersions ) -> StoredReportSummaryRead: @@ -413,8 +330,9 @@ def get_report( ``run_id`` (a budget window's runs are its budget-window runs; any other report's, its own report runs), StandardUserRequiresSignInError for an unauthenticated credential - that names a signed-in user, EconomyResultUnreadableError when a - succeeded run's rows lack a part every result has, + that names a signed-in user, EconomyResultUnreadableError when an + economy run names no reform simulation run or a succeeded one's rows + lack a part every result has, HouseholdResultUnreadableError when a succeeded household report run's calculated households cannot be read, BudgetWindowResultUnreadableError when a succeeded window run's @@ -445,7 +363,7 @@ def _read_report( """ with _storage_failures(), self._database_session.read() as session: stored = _stored_report(session, country_id=country_id, report_id=report_id) - (stored,) = _requesters_view( + (stored,) = requesters_view( session, [stored], requester=requester, @@ -459,23 +377,42 @@ def _read_report( return self._budget_window(session, stored) if kind == "household": return self._household_report(session, stored) - run = stored.run - result = None - if run is not None and run.status is ReportRunStatus.SUCCEEDED: + return self._economy_report(session, stored) + + def _economy_report(self, session: Session, stored: StoredReportRows) -> ReportRead: + """Return an economy report with its run's cliffs, and its result if succeeded. + + The cliffs of its two simulation runs are read whatever the run's + status, since they are calculated apart from it; the result's cliff + impact is theirs once both have succeeded. + """ + run = stored.run + result = cliffs = None + if run is not None: + reform_simulation_run_id = require_reform_run(run) + cliff_calculations = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=run.baseline_simulation_run_id, + reform_simulation_run_id=reform_simulation_run_id, + ) + cliffs = report_cliffs(cliff_calculations) + if run.status is ReportRunStatus.SUCCEEDED: result = result_transformations.economy_result( result_reads.read_economy_result_rows( session, - country_id=country_id, + country_id=stored.report.country, report_run=run, - reform_simulation_run_id=require_reform_run(run), + reform_simulation_run_id=reform_simulation_run_id, on_local_area_dataset=stored.on_local_area_dataset, + cliff_calculations=cliff_calculations, ) ) - return report_read( - stored, - current_versions=self._current_versions(country_id), - result=result, - ) + return report_read( + stored, + current_versions=self._current_versions(stored.report.country), + result=result, + cliffs=cliffs, + ) def _budget_window( self, session: Session, stored: StoredReportRows @@ -545,7 +482,7 @@ def list_reports( cannot be read. """ with _storage_failures(), self._database_session.read() as session: - rows = _requesters_view( + rows = requesters_view( session, read_report_rows(session, country_id=country_id, report_ids=report_ids), requester=requester, @@ -580,7 +517,7 @@ def search_reports( dataset_independent_key=dataset_independent_key, limit=MAXIMUM_LISTED_REPORTS, ) - rows = _requesters_view( + rows = requesters_view( session, read_report_rows(session, country_id=country_id, report_ids=report_ids), requester=requester, @@ -665,6 +602,7 @@ def rerun_report( country_id: str, report_id: UUID, force: bool, + include_cliffs: bool = False, requester: AccountPrincipal | None = None, ) -> StoredReportRead: """Run the country's report again; return it with the run the request ended on. @@ -676,14 +614,16 @@ def rerun_report( on the current versions; with it, both are calculated again (a budget window's new run then recalculates each year). A household report's sides are always calculated again. Only an admin user may force a - re-run. With a ``requester``, it is + re-run; ``include_cliffs`` asks for an economy report run's cliffs + too. With a ``requester``, it is checked before the simulation service is asked, and the request is recorded for its user (trigger ``manual``, forced or not) once the service has answered: that run, or each year's report run of a budget window's. Raise StoredReportNotFoundError when the country has no such report, ForcedRerunRequiresSignInError for a forced re-run naming no - user and ForcedRerunRequiresAdminError for one by a user below admin, - both before the simulation service is asked, ReportStorageError when + user, ForcedRerunRequiresAdminError for one by a user below admin and + CliffsNotAvailableError for a household report's or window's cliffs, + each before the simulation service is asked, ReportStorageError when it cannot be read, the recorder's check's errors, the submission's checks' and the simulation service's errors (see ``SimulationSubmissionService.rerun_report``), @@ -700,6 +640,7 @@ def rerun_report( recording = self._run_recording(requester) if force: require_admin_to_force(None if recording is None else recording.requester) + require_cliffs_available(kind, include_cliffs=include_cliffs) started = submissions.rerun_report( ReportRerunInput( country_id=country_id, @@ -707,6 +648,7 @@ def rerun_report( kind=kind, force=force, policy_ids=report_policy_ids(stored), + include_cliffs=include_cliffs, ) ) if kind != "budget_window": diff --git a/policyengine_api/services/v2/stored_reports/transformations.py b/policyengine_api/services/v2/stored_reports/transformations.py index dae16644f..36c9f0033 100644 --- a/policyengine_api/services/v2/stored_reports/transformations.py +++ b/policyengine_api/services/v2/stored_reports/transformations.py @@ -4,6 +4,7 @@ from typing import TYPE_CHECKING +from policyengine_api.data.v2.models import SimulationStatus from policyengine_api.services.v2.simulation_service.types import LOCAL_AREA_DATASET from policyengine_api.services.v2.stored_reports.types import ( BudgetWindowReportRead, @@ -11,8 +12,10 @@ BudgetWindowRunRead, BudgetWindowRunsRead, BudgetWindowYearRead, + CliffCalculationRead, HouseholdReportRead, HouseholdReportSummaryRead, + ReportCliffsRead, ReportDefinitionRead, ReportRead, ReportRunRead, @@ -27,6 +30,7 @@ from policyengine_api.data.v2.models import ( BudgetWindowRun, + CliffImpact, Report, ReportRun, Simulation, @@ -39,12 +43,14 @@ ) from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResult, + ReportRunCliffRows, ) from policyengine_api.services.v2.stored_reports.household_results.types import ( HouseholdReportFailure, HouseholdReportResult, ) from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationStatusName, ReportKind, ReportRunsKind, ReportStatusName, @@ -139,10 +145,58 @@ def report_read( *, current_versions: PackageVersions, result: EconomyResult | None, + cliffs: ReportCliffsRead | None, ) -> ReportRead: - """Return an economy report with the run read's result, if it has one.""" + """Return an economy report with the run read's result and cliffs, if any.""" summary = report_summary_read(rows, current_versions=current_versions) - return ReportRead(**vars(summary), result=result) + return ReportRead(**vars(summary), result=result, cliffs=cliffs) + + +# A side's status for its cliff calculation's. +CLIFF_CALCULATION_STATUSES: dict[SimulationStatus, CliffCalculationStatusName] = { + SimulationStatus.PENDING: "pending", + SimulationStatus.RUNNING: "running", + SimulationStatus.SUCCEEDED: "succeeded", + SimulationStatus.FAILED: "failed", +} + + +def _cliff_calculation_read(calculation: CliffImpact | None) -> CliffCalculationRead: + """Return how far a side's cliff calculation has got; the error once failed.""" + if calculation is None: + return CliffCalculationRead(status="not_calculated", error_message=None) + status = CLIFF_CALCULATION_STATUSES[calculation.status] + return CliffCalculationRead( + status=status, + error_message=calculation.error_message if status == "failed" else None, + ) + + +# A report run's cliff status is the first of these that either side has, +# else succeeded: a failed or missing side needs a new request, and one +# still pending or running needs only time. +CLIFF_STATUSES_BEFORE_SUCCESS: tuple[CliffCalculationStatusName, ...] = ( + "failed", + "not_calculated", + "running", + "pending", +) + + +def report_cliffs(cliff_calculations: ReportRunCliffRows) -> ReportCliffsRead: + """Return how far a report run's two cliff calculations have got. + + Its status is ``succeeded`` once both sides are, else the first of + ``CLIFF_STATUSES_BEFORE_SUCCESS`` either side has. + """ + baseline = _cliff_calculation_read(cliff_calculations.baseline) + reform = _cliff_calculation_read(cliff_calculations.reform) + side_statuses = {baseline.status, reform.status} + status: CliffCalculationStatusName = next( + (status for status in CLIFF_STATUSES_BEFORE_SUCCESS if status in side_statuses), + "succeeded", + ) + return ReportCliffsRead(status=status, baseline=baseline, reform=reform) def household_report_summary_read( diff --git a/policyengine_api/services/v2/stored_reports/types.py b/policyengine_api/services/v2/stored_reports/types.py index b6d8e2e90..8d30de6d1 100644 --- a/policyengine_api/services/v2/stored_reports/types.py +++ b/policyengine_api/services/v2/stored_reports/types.py @@ -53,6 +53,12 @@ # budget-window runs. ReportRunsKind = Literal["economy", "household"] ReportRunTriggerName = Literal["initial", "manual", "system"] +# How far a side's cliff calculation has got: not_calculated while its +# simulation run has none, else its calculation's status (failed once its +# newest calculation failed and none is pending, running or succeeded). +CliffCalculationStatusName = Literal[ + "not_calculated", "pending", "running", "succeeded", "failed" +] @dataclass(frozen=True) @@ -133,11 +139,49 @@ class ReportSummaryRead(ReportDefinitionRead): run: ReportRunRead | None +@dataclass(frozen=True) +class CliffCalculationRead: + """How far one side's cliff calculation of its simulation run has got. + + ``error_message`` says why a ``failed`` side's newest calculation failed, + and is None otherwise. + """ + + status: CliffCalculationStatusName + error_message: str | None + + +@dataclass(frozen=True) +class ReportCliffsRead: + """How far the cliff calculations of a report run's two simulation runs have got. + + A simulation run's cliffs are calculated apart from it, once, when a + request asks for them; every report naming the run shares them. + ``status`` is ``succeeded`` once both sides are; otherwise ``failed`` + when either side is, else ``not_calculated`` when either side is, else + ``running`` when either side is, else ``pending``. A request with + ``include_cliffs`` ending on this run (on the current versions) starts a + new calculation for each side that is ``not_calculated`` or ``failed``. + A report naming one simulation run on both sides reads its calculation + for each. + """ + + status: CliffCalculationStatusName + baseline: CliffCalculationRead + reform: CliffCalculationRead + + @dataclass(frozen=True) class ReportRead(ReportSummaryRead): - """A report with its run's result, once that run has succeeded.""" + """A report with its run's result, once that run has succeeded. + + ``cliffs`` says how far the cliff calculations of the run read have got, + whatever its status, and is None for a report with no run. The result's + ``cliff_impact`` is set once both of them have succeeded. + """ result: EconomyResult | None + cliffs: ReportCliffsRead | None @dataclass(frozen=True) diff --git a/policyengine_api/services/v2/stored_reports/validators.py b/policyengine_api/services/v2/stored_reports/validators.py index 683874a30..6982dcffb 100644 --- a/policyengine_api/services/v2/stored_reports/validators.py +++ b/policyengine_api/services/v2/stored_reports/validators.py @@ -17,7 +17,10 @@ from policyengine_api.services.v2.report_run_records.types import ( CheckedRequester, ) - from policyengine_api.services.v2.stored_reports.types import StoredReportRows + from policyengine_api.services.v2.stored_reports.types import ( + ReportKind, + StoredReportRows, + ) # A report run, or a budget window's budget-window run. RunT = TypeVar("RunT") @@ -64,6 +67,22 @@ class ForcedRerunRequiresAdminError(PermissionError): """A forced re-run's user is below admin; only an admin user may force one.""" +class CliffsNotAvailableError(ValueError): + """A re-run asked for cliffs of a report that has none. + + Only an economy report's simulation runs have cliff calculations: a + household report's and a budget window's have none. + """ + + +def require_cliffs_available(kind: ReportKind, *, include_cliffs: bool) -> None: + """Raise CliffsNotAvailableError when a re-run of a ``kind`` asks for cliffs.""" + if include_cliffs and kind != "economy": + name = "a household report" if kind == "household" else "a budget window" + msg = f"include_cliffs: {name} has no cliff impacts, so it cannot be true" + raise CliffsNotAvailableError(msg) + + FORCED_RERUN_SIGN_IN_MESSAGE = ( "Only admin users may force a re-run: sign in with a bearer access token" ) diff --git a/tests/fixtures/economy_results.py b/tests/fixtures/economy_results.py index d5ee9f6a4..df75f45d8 100644 --- a/tests/fixtures/economy_results.py +++ b/tests/fixtures/economy_results.py @@ -7,14 +7,20 @@ its rows is tested against the same mapping. Its ``withheld_area_codes`` rows follow the writer as PolicyEngine/policyengine-sim-api#1068 changes it (``46c38f07``): one row per code a result's ``constituency_withheld_codes`` -and ``local_authority_withheld_codes`` list. Each row is a dict of the -table's columns; ``id`` and ``created_at`` are left for the caller. +and ``local_authority_withheld_codes`` list. A result's ``cliff_impact`` is +not the report run's: each side's simulation run stores its own succeeded +cliff calculation (``cliff_impacts``, which sim's cliff calculation writes, +not that writer), and the report run's four cliff columns stay null, as the +writer leaves them from PolicyEngine/policyengine-sim-api's C1 · 38 on. Each +row is a dict of the table's columns; ``id`` and ``created_at`` are left for +the caller. """ from __future__ import annotations import copy from dataclasses import dataclass +from datetime import UTC, datetime, timedelta from typing import TYPE_CHECKING, Any if TYPE_CHECKING: @@ -372,18 +378,7 @@ def economy_result_rows( "baseline_simulation_run_id": run_ids.baseline_simulation_run_id, "reform_simulation_run_id": run_ids.reform_simulation_run_id, } - cliffs = output.get("cliff_impact") report_run_columns = { - "baseline_cliff_gap": None - if cliffs is None - else cliffs["baseline"]["cliff_gap"], - "baseline_cliff_share": ( - None if cliffs is None else cliffs["baseline"]["cliff_share"] - ), - "reform_cliff_gap": None if cliffs is None else cliffs["reform"]["cliff_gap"], - "reform_cliff_share": None - if cliffs is None - else cliffs["reform"]["cliff_share"], "spm_provenance": output.get("spm_provenance"), "data_version": output["data_version"], } @@ -406,10 +401,37 @@ def economy_result_rows( output.get("local_authority_impact"), report_keys, "local_authority" ), "withheld_area_codes": _withheld_rows(output, report_keys), + "cliff_impacts": _cliff_rows(output, run_ids), }, ) +# When a stored cliff calculation started and finished. +CLIFF_CALCULATION_STARTED_AT = datetime(2026, 11, 17, 9, tzinfo=UTC) +CLIFF_CALCULATION_COMPLETED_AT = CLIFF_CALCULATION_STARTED_AT + timedelta(minutes=1) + + +def _cliff_rows(output: dict[str, Any], run_ids: RunIds) -> list[dict[str, Any]]: + """Return each simulation run's succeeded cliff calculation, if it has cliffs.""" + cliffs = output.get("cliff_impact") + if cliffs is None: + return [] + return [ + { + "simulation_run_id": simulation_run_id, + "status": "succeeded", + "started_at": CLIFF_CALCULATION_STARTED_AT, + "completed_at": CLIFF_CALCULATION_COMPLETED_AT, + "cliff_gap": cliffs[side]["cliff_gap"], + "cliff_share": cliffs[side]["cliff_share"], + } + for side, simulation_run_id in ( + ("baseline", run_ids.baseline_simulation_run_id), + ("reform", run_ids.reform_simulation_run_id), + ) + ] + + def _labor_supply_rows(output: dict[str, Any], run_ids: RunIds) -> list[dict[str, Any]]: response = output.get("labor_supply_response") if response is None: diff --git a/tests/integration/stored_report_rows.py b/tests/integration/stored_report_rows.py index 9c5c16f9a..53848196c 100644 --- a/tests/integration/stored_report_rows.py +++ b/tests/integration/stored_report_rows.py @@ -429,6 +429,43 @@ def store_report_run( return run_ids +def store_cliff_calculation( # noqa: PLR0913 # the connection, the run and its status, then each column a test sets + connection: Connection, + simulation_run_id: UUID, + status: str, + *, + created_at: datetime = STARTED_AT, + error_message: str | None = None, + cliff_gap: float | None = None, + cliff_share: float | None = None, +) -> UUID: + """Store one cliff calculation of the simulation run, as sim and its worker do. + + A finished calculation has a completion time; a succeeded one needs + ``cliff_gap`` and ``cliff_share``, a failed one an ``error_message``. + """ + calculation_id = uuid4() + insert_row( + connection, + "cliff_impacts", + id=calculation_id, + created_at=created_at, + updated_at=created_at, + simulation_run_id=simulation_run_id, + status=status, + error_message=error_message, + started_at=None if status == "pending" else created_at, + completed_at=( + created_at + timedelta(minutes=1) + if status in {"succeeded", "failed"} + else None + ), + cliff_gap=cliff_gap, + cliff_share=cliff_share, + ) + return calculation_id + + def store_budget_window_run( connection: Connection, catalog: CatalogRows, diff --git a/tests/integration/test_v2_report_cliff_reads.py b/tests/integration/test_v2_report_cliff_reads.py new file mode 100644 index 000000000..f8c423bc0 --- /dev/null +++ b/tests/integration/test_v2_report_cliff_reads.py @@ -0,0 +1,269 @@ +"""Read a v2 report's cliffs from its simulation runs' cliff calculations. + +The routes run as the Public API's runtime role, so the tests prove its +``SELECT`` on ``cliff_impacts`` covers the read (rule +``api.v2.runtime-privileges-tested-as-runtime-role``). The simulation +service inserts a run's cliff calculations and its Modal worker finishes +them; here the database owner stores them, commits them, and the catalog's +deletion removes them with their runs. +""" + +from __future__ import annotations + +import json +from datetime import timedelta +from typing import TYPE_CHECKING, Any + +import pytest +from alembic import command +from alembic.config import Config +from fastapi.testclient import TestClient +from flask import Flask +from sqlalchemy import create_engine, text +from sqlalchemy.orm import sessionmaker +from sqlalchemy.pool import NullPool +from sqlmodel import Session + +from policyengine_api.asgi_factory import create_asgi_app +from policyengine_api.constants import REPO +from policyengine_api.fastapi_routes.dependencies import NativeRouteDependencies +from policyengine_api.migration_flags import ( + RouteImplementation, + RouteImplementationSettings, +) +from policyengine_api.services.v2.simulation_service.types import PackageVersions +from policyengine_api.services.v2.stored_reports.database_session import ( + StoredReportDatabaseSession, +) +from policyengine_api.services.v2.stored_reports.services import V2StoredReportService +from tests.fixtures.economy_results import uk_economy_result, us_economy_result +from tests.integration.stored_report_rows import ( + STARTED_AT, + RunSettings, + delete_catalog, + store_catalog, + store_cliff_calculation, + store_report, + store_report_run, +) + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Engine + + from tests.integration.stored_report_rows import CatalogRows + +CURRENT_VERSIONS = {"country_package_version": "1.5.0", "policyengine_version": "4.2.0"} +FAILURE = "cliff_calculation_failed: the calculation raised an error" + + +def current_versions(country_id: str) -> PackageVersions: + return PackageVersions(**CURRENT_VERSIONS) + + +@pytest.fixture +def owner_engine(disposable_v2_database_url: str) -> Iterator[Engine]: + command.upgrade(Config(str(REPO / "alembic-v2.ini")), "head") + engine = create_engine(disposable_v2_database_url, poolclass=NullPool) + yield engine + engine.dispose() + + +@pytest.fixture +def catalogs(owner_engine: Engine) -> Iterator[dict[str, CatalogRows]]: + """Store a US and a UK catalog, and delete them and their reports after.""" + with owner_engine.begin() as connection: + stored = { + country: store_catalog(connection, country) for country in ("us", "uk") + } + yield stored + with owner_engine.begin() as connection: + for catalog in stored.values(): + delete_catalog(connection, catalog) + + +@pytest.fixture +def client(managed_v2_roles, v2_engine_as_role) -> Iterator[TestClient]: + """Serve the report routes as the runtime role.""" + runtime_engine = v2_engine_as_role(managed_v2_roles.runtime, poolclass=NullPool) + sessions = sessionmaker(runtime_engine, class_=Session) + dependencies = NativeRouteDependencies( + readiness_probe=lambda: True, + gateway_client_factory=lambda: None, + metadata_reader_factory=lambda: None, + v2_stored_report_service_factory=lambda: V2StoredReportService( + StoredReportDatabaseSession(sessions), current_versions=current_versions + ), + ) + settings = RouteImplementationSettings( + health=RouteImplementation.FLASK_FALLBACK, + specification=RouteImplementation.FLASK_FALLBACK, + metadata=RouteImplementation.FLASK_FALLBACK, + ) + yield TestClient( + create_asgi_app( + Flask(__name__), dependencies=dependencies, route_settings=settings + ) + ) + runtime_engine.dispose() + + +def read_report(client: TestClient, report_id: object, country: str) -> Any: + response = client.get(f"/v2/reports/{report_id}?country_id={country}") + assert response.status_code == 200, response.text + return response.json()["result"]["item"] + + +def test_a_succeeded_run_reads_its_simulation_runs_cliff_results( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + output = us_economy_result() + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + # The result's cliff impact is stored as each simulation run's + # succeeded cliff calculation. + store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS), + result=output, + ) + + item = read_report(client, report.report_id, "us") + + assert item["result"]["cliff_impact"] == json.loads( + json.dumps(output["cliff_impact"]) + ) + assert item["cliffs"] == { + "status": "succeeded", + "baseline": {"status": "succeeded", "error_message": None}, + "reform": {"status": "succeeded", "error_message": None}, + } + + +def test_a_report_runs_own_cliff_columns_are_not_read( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["uk"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + run_ids = store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS), + result=uk_economy_result(), + ) + # As a report run stored its cliffs before C1 · 38. + connection.execute( + text( + "UPDATE report_runs SET baseline_cliff_gap = 1.0, " + "baseline_cliff_share = 0.1, reform_cliff_gap = 2.0, " + "reform_cliff_share = 0.2 WHERE id = :id" + ), + {"id": run_ids.report_run_id}, + ) + + item = read_report(client, report.report_id, "uk") + + assert item["status"] == "succeeded" + assert item["result"]["cliff_impact"] is None + assert item["cliffs"]["status"] == "not_calculated" + + +def test_a_run_still_calculating_reads_each_sides_cliff_progress( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["us"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + run_ids = store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS, status="running"), + ) + store_cliff_calculation( + connection, run_ids.baseline_simulation_run_id, "running" + ) + # A failed calculation never counts: the newer pending one is read. + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "failed", + error_message=FAILURE, + ) + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "pending", + created_at=STARTED_AT + timedelta(minutes=5), + ) + + item = read_report(client, report.report_id, "us") + + assert item["result"] is None + assert item["cliffs"] == { + "status": "running", + "baseline": {"status": "running", "error_message": None}, + "reform": {"status": "pending", "error_message": None}, + } + + +def test_a_side_whose_calculations_all_failed_says_why_the_newest_failed( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + catalog = catalogs["uk"] + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + run_ids = store_report_run( + connection, + catalog, + report, + RunSettings(versions=CURRENT_VERSIONS), + result=uk_economy_result(), + ) + store_cliff_calculation( + connection, + run_ids.baseline_simulation_run_id, + "succeeded", + cliff_gap=1_000_000.0, + cliff_share=0.02, + ) + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "failed", + error_message="modal_call_ended: the call ended without a result", + ) + store_cliff_calculation( + connection, + run_ids.reform_simulation_run_id, + "failed", + created_at=STARTED_AT + timedelta(minutes=5), + error_message=FAILURE, + ) + + item = read_report(client, report.report_id, "uk") + + assert item["result"]["cliff_impact"] is None + assert item["cliffs"] == { + "status": "failed", + "baseline": {"status": "succeeded", "error_message": None}, + "reform": {"status": "failed", "error_message": FAILURE}, + } + + +def test_a_report_with_no_run_reads_no_cliffs( + owner_engine: Engine, catalogs: dict[str, CatalogRows], client: TestClient +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalogs["us"]) + + item = read_report(client, report.report_id, "us") + + assert item["status"] == "not_run" + assert item["cliffs"] is None diff --git a/tests/integration/test_v2_report_creation.py b/tests/integration/test_v2_report_creation.py index 7ce1d32b7..6cebf553d 100644 --- a/tests/integration/test_v2_report_creation.py +++ b/tests/integration/test_v2_report_creation.py @@ -63,6 +63,7 @@ RunSettings, delete_catalog, store_catalog, + store_cliff_calculation, store_report, store_report_run, store_simulation, @@ -93,6 +94,8 @@ class StoringSimulationService: With ``answer_unstored``, it answers with IDs it stored nothing for, and keeps them in ``unstored_ids`` (a report's run in ``unstored_run_ids``). + A report with ``include_cliffs`` also gets a pending cliff calculation for + each side's simulation run, as the simulation service starts them. """ engine: Engine @@ -120,6 +123,12 @@ def submit_report(self, report: EconomyReportCreationInput) -> SubmittedReport: stored, RunSettings(versions=CURRENT_VERSIONS, status="pending"), ) + if report.include_cliffs: + for simulation_run_id in ( + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ): + store_cliff_calculation(connection, simulation_run_id, "pending") return SubmittedReport( report_id=stored.report_id, report_run_id=run_ids.report_run_id ) @@ -246,6 +255,24 @@ def test_a_created_report_is_answered_as_the_tables_hold_it( assert sent.include_cliffs is True +def test_a_report_created_with_cliffs_answers_their_pending_calculations( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + simulation_service = StoringSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + "/v2/reports?country_id=us", json=report_body(catalog.policy_id) + ) + + assert response.status_code == 201, response.text + item = response.json()["result"]["item"] + assert item["cliffs"] == { + "status": "pending", + "baseline": {"status": "pending", "error_message": None}, + "reform": {"status": "pending", "error_message": None}, + } + + def test_a_report_naming_a_policy_the_country_does_not_store_is_not_sent( owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any ) -> None: diff --git a/tests/integration/test_v2_report_runs.py b/tests/integration/test_v2_report_runs.py index ca4612001..57d8c959d 100644 --- a/tests/integration/test_v2_report_runs.py +++ b/tests/integration/test_v2_report_runs.py @@ -73,6 +73,7 @@ household_only_catalog, store_budget_window_run, store_catalog, + store_cliff_calculation, store_report, store_report_run, store_year_simulations, @@ -153,6 +154,9 @@ class RerunningSimulationService: it records how many of the report service's sessions are open when asked. With ``window_years``, the report is a budget window, and the new run is a budget-window run with a pending report run for each of those years. + A report run again with ``include_cliffs`` also gets a pending cliff + calculation for each side's new simulation run, as the simulation + service starts them. """ engine: Engine @@ -208,6 +212,14 @@ def rerun_report(self, rerun: ReportRerunInput) -> StartedReportRun: else: run_ids = store_report_run(connection, self.catalog, report, settings) mark_manual(connection, run_ids.report_run_id) + if rerun.include_cliffs: + for simulation_run_id in ( + run_ids.baseline_simulation_run_id, + run_ids.reform_simulation_run_id, + ): + store_cliff_calculation( + connection, simulation_run_id, "pending" + ) self.new_run_ids.append(run_ids.report_run_id) started = StartedReportRun(report_run_id=run_ids.report_run_id) if self.delete_report: @@ -591,6 +603,75 @@ def test_running_a_report_again_answers_it_with_its_new_run( ] +def test_running_a_report_again_with_cliffs_asks_for_them_and_answers_their_progress( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + with owner_engine.begin() as connection: + report = store_report(connection, catalog) + simulation_service = RerunningSimulationService(owner_engine, catalog) + + response = client_for(runtime_sessions, simulation_service).post( + f"/v2/reports/{report.report_id}/runs?country_id=us", + json={"include_cliffs": True}, + ) + + assert response.status_code == 201, response.text + assert simulation_service.reruns == [ + ReportRerunInput( + country_id="us", + report_id=report.report_id, + kind="economy", + force=False, + policy_ids=(None, catalog.policy_id), + include_cliffs=True, + ) + ] + item = response.json()["result"]["item"] + assert item["cliffs"] == { + "status": "pending", + "baseline": {"status": "pending", "error_message": None}, + "reform": {"status": "pending", "error_message": None}, + } + + +def test_a_budget_window_run_again_with_cliffs_is_refused_before_asking( + owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any +) -> None: + with owner_engine.begin() as connection: + window = store_report(connection, catalog, budget_window_size=2) + simulation_service = RerunningSimulationService( + owner_engine, catalog, window_years=(2026, 2027) + ) + + response = client_for(runtime_sessions, simulation_service).post( + f"/v2/reports/{window.report_id}/runs?country_id=us", + json={"include_cliffs": True}, + ) + + assert response.status_code == 422, response.text + assert "include_cliffs" in response.json()["message"] + assert simulation_service.reruns == [] + + +def test_a_household_report_run_again_asks_for_no_cliffs( + owner_engine: Engine, household_only_uk: CatalogRows, runtime_sessions: Any +) -> None: + with owner_engine.begin() as connection: + report = store_household_report(connection, household_only_uk) + simulation_service = RerunningSimulationService(owner_engine, household_only_uk) + client = client_for(runtime_sessions, simulation_service) + runs_path = f"/v2/reports/{report.report_id}/runs?country_id=uk" + + refused = client.post(runs_path, json={"include_cliffs": True}) + not_asked = client.post(runs_path, json={"include_cliffs": False}) + + assert refused.status_code == 422, refused.text + assert "include_cliffs" in refused.json()["message"] + assert not_asked.status_code == 201, not_asked.text + (rerun,) = simulation_service.reruns + assert rerun.include_cliffs is False + + def test_a_report_whose_reform_simulation_is_gone_is_left_to_the_service_to_refuse( owner_engine: Engine, catalog: CatalogRows, runtime_sessions: Any ) -> None: diff --git a/tests/unit/libs/test_simulation_report_reruns.py b/tests/unit/libs/test_simulation_report_reruns.py index fdefc74fa..1ed0e2470 100644 --- a/tests/unit/libs/test_simulation_report_reruns.py +++ b/tests/unit/libs/test_simulation_report_reruns.py @@ -132,6 +132,25 @@ def test_a_rerun_posts_force_to_the_reports_runs_route( assert json.loads(request.content) == {"force": force} +def test_a_rerun_asking_for_cliffs_sends_include_cliffs() -> None: + service = ScriptedService() + + service.rerun(include_cliffs=True) + + (request,) = service.requests + assert json.loads(request.content) == {"force": False, "include_cliffs": True} + + +def test_a_rerun_not_asking_for_cliffs_sends_no_include_cliffs() -> None: + """Sim's re-run body before C1 · 39 refuses any field but ``force``.""" + service = ScriptedService() + + service.rerun(include_cliffs=False) + + (request,) = service.requests + assert json.loads(request.content) == {"force": False} + + @pytest.mark.parametrize("status_code", [201, 202]) def test_a_started_rerun_naming_the_report_is_accepted(status_code: int) -> None: service = ScriptedService( diff --git a/tests/unit/v2/report_run_support.py b/tests/unit/v2/report_run_support.py index 5cd6cb3fa..83c4317e0 100644 --- a/tests/unit/v2/report_run_support.py +++ b/tests/unit/v2/report_run_support.py @@ -119,11 +119,16 @@ def rerun_report( country_id: str, report_id: UUID, force: bool, + include_cliffs: bool = False, requester: AccountPrincipal | None = None, ) -> StoredReportRead: self.requesters.append(requester) self._answer( - "rerun_report", country_id=country_id, report_id=report_id, force=force + "rerun_report", + country_id=country_id, + report_id=report_id, + force=force, + include_cliffs=include_cliffs, ) return self.report if self.rerun is None else self.rerun diff --git a/tests/unit/v2/stored_report_support.py b/tests/unit/v2/stored_report_support.py index b566275f2..bb3c89757 100644 --- a/tests/unit/v2/stored_report_support.py +++ b/tests/unit/v2/stored_report_support.py @@ -21,6 +21,8 @@ EconomyResult, ) from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationRead, + ReportCliffsRead, ReportRead, ReportRunRead, ReportSimulationRead, @@ -110,6 +112,11 @@ def report_summary_read(**changes: Any) -> ReportSummaryRead: def report_read(**changes: Any) -> ReportRead: fields = { "result": EconomyResult.model_validate(us_economy_result()), + "cliffs": ReportCliffsRead( + status="succeeded", + baseline=CliffCalculationRead(status="succeeded", error_message=None), + reform=CliffCalculationRead(status="succeeded", error_message=None), + ), **report_summary_fields(), **changes, } diff --git a/tests/unit/v2/test_economy_result_rebuild.py b/tests/unit/v2/test_economy_result_rebuild.py index bc42fb37f..e19e55f35 100644 --- a/tests/unit/v2/test_economy_result_rebuild.py +++ b/tests/unit/v2/test_economy_result_rebuild.py @@ -6,13 +6,16 @@ writer itself stored at a named commit (``scripts/generate_economy_result_golden.py``), so a rebuild that matches it reverses the real writer, and a change in the writer fails once the file is -generated again. +generated again. That writer no longer stores cliffs +(PolicyEngine/policyengine-sim-api's C1 · 38): a result's cliff impact comes +from its two simulation runs' cliff calculations, so the golden rows rebuild +their results without one, whatever the report run's four cliff columns hold. """ from __future__ import annotations import json -from dataclasses import replace +from dataclasses import fields, replace from pathlib import Path from typing import Any from uuid import UUID, uuid4 @@ -21,6 +24,7 @@ from policyengine_api.data.v2.models import ( BudgetSummary, + CliffImpact, CongressionalDistrictImpact, ConstituencyImpact, DecileImpact, @@ -31,6 +35,7 @@ LocalAuthorityImpact, Poverty, ProgramStatistics, + SimulationStatus, WithheldAreaCode, ) from policyengine_api.services.v2.stored_reports.economy_results import ( @@ -39,6 +44,7 @@ from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultRows, EconomyResultUnreadableError, + ReportRunCliffRows, ReportRunResultColumns, ) from policyengine_api.spm import SPMComparisonProvenance @@ -69,7 +75,39 @@ "constituency_impacts": ConstituencyImpact, "local_authority_impacts": LocalAuthorityImpact, "withheld_area_codes": WithheldAreaCode, + "cliff_impacts": CliffImpact, } +# The report run's own cliff columns, which no read uses: C1 · 41 drops them. +REPORT_RUN_CLIFF_COLUMNS = ( + "baseline_cliff_gap", + "baseline_cliff_share", + "reform_cliff_gap", + "reform_cliff_share", +) +NO_CLIFF_CALCULATIONS = ReportRunCliffRows(baseline=None, reform=None) + + +def side_calculations( + calculations: tuple[CliffImpact, ...], run_ids: RunIds +) -> ReportRunCliffRows: + """Return each side's cliff calculation among ``calculations``, or none.""" + by_run = { + calculation.simulation_run_id: calculation for calculation in calculations + } + return ReportRunCliffRows( + baseline=by_run.get(run_ids.baseline_simulation_run_id), + reform=by_run.get(run_ids.reform_simulation_run_id), + ) + + +def table_row(table: str, row: dict[str, Any]) -> Any: + """Load one stored row as its table's model, with a new ID. + + A cliff calculation's status is loaded as the enum a database read gives. + """ + if "status" in row: + row = {**row, "status": SimulationStatus(row["status"])} + return TABLE_MODELS[table](id=uuid4(), **row) def stored_rows( @@ -94,11 +132,12 @@ def stored_rows( stored = economy_result_rows(output, run_ids=run_ids, country=country) tables: dict[str, tuple[Any, ...]] = {} for table, rows in stored.rows.items(): - loaded = [TABLE_MODELS[table](id=uuid4(), **row) for row in rows] + loaded = [table_row(table, row) for row in rows] if reverse_rows: loaded.reverse() tables[table] = tuple(loaded) withheld_area_codes = tables.pop("withheld_area_codes") + cliff_calculations = side_calculations(tables.pop("cliff_impacts"), run_ids) local_area_rows: dict[str, Any] = ( {"on_local_area_dataset": True, "withheld_area_codes": withheld_area_codes} if on_local_area_dataset @@ -112,6 +151,7 @@ def stored_rows( ), baseline_simulation_run_id=run_ids.baseline_simulation_run_id, reform_simulation_run_id=run_ids.reform_simulation_run_id, + cliff_calculations=cliff_calculations, **tables, **local_area_rows, ) @@ -126,7 +166,8 @@ def golden_rows(case: dict[str, Any]) -> EconomyResultRows: """Load one golden case's stored rows as the database connectors read them. Run IDs come back as UUIDs and each row gets a new ID, as the writer - draws them. + draws them. The report run's cliff columns are left out, and neither + side has a cliff calculation. """ run_ids = {key: UUID(value) for key, value in GOLDEN["run_ids"].items()} @@ -143,10 +184,15 @@ def loaded(table: str, row: dict[str, Any]) -> Any: country_id=case["country"], report_run=ReportRunResultColumns( country_package_version=case["output"]["model_version"], - **case["report_run_columns"], + **{ + column: value + for column, value in case["report_run_columns"].items() + if column not in REPORT_RUN_CLIFF_COLUMNS + }, ), baseline_simulation_run_id=run_ids["baseline_simulation_run_id"], reform_simulation_run_id=run_ids["reform_simulation_run_id"], + cliff_calculations=NO_CLIFF_CALCULATIONS, **{ table: tuple(loaded(table, row) for row in rows) for table, rows in case["rows"].items() @@ -162,7 +208,17 @@ def test_rows_the_simulation_services_own_writer_stored_rebuild_its_result( ) -> None: rebuilt = result_transformations.economy_result(golden_rows(case)) - assert rebuilt.model_dump(mode="json", by_alias=True) == case["output"] + assert rebuilt.model_dump(mode="json", by_alias=True) == { + **case["output"], + "cliff_impact": None, + } + + +def test_the_report_runs_result_columns_hold_none_of_its_cliff_columns() -> None: + """A report run's cliffs are its simulation runs'; its own columns are not read.""" + column_names = {column.name for column in fields(ReportRunResultColumns)} + + assert column_names.isdisjoint(REPORT_RUN_CLIFF_COLUMNS) def test_the_golden_rows_cover_the_shapes_the_fixtures_alone_do_not() -> None: diff --git a/tests/unit/v2/test_report_cliff_reads.py b/tests/unit/v2/test_report_cliff_reads.py new file mode 100644 index 000000000..0be7fde64 --- /dev/null +++ b/tests/unit/v2/test_report_cliff_reads.py @@ -0,0 +1,314 @@ +"""Read a report run's cliffs from its two simulation runs' cliff calculations. + +Each simulation run has at most one cliff calculation that hasn't failed, and +any number of failed ones (``cliff_impacts``). A side reads its run's +unfailed calculation, else its newest failed one, else none. The report run's +cliff impact is the two sides' results once both have succeeded; ``cliffs`` +says how far each side's calculation has got. +""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta +from typing import TYPE_CHECKING, get_args +from uuid import UUID, uuid4 + +import pytest + +from policyengine_api.data.v2.models import CliffImpact as CliffImpactRow +from policyengine_api.data.v2.models import SimulationStatus +from policyengine_api.services.v2.stored_reports.database_connectors import ( + reads_results as result_reads, +) +from policyengine_api.services.v2.stored_reports.economy_results import ( + transformations as result_transformations, +) +from policyengine_api.services.v2.stored_reports.economy_results.types import ( + CliffImpact, + CliffImpactInSimulation, + ReportRunCliffRows, +) +from policyengine_api.services.v2.stored_reports.transformations import ( + report_cliffs, +) +from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationRead, + CliffCalculationStatusName, + ReportCliffsRead, +) +from tests.unit.v2.sqlite_report_rows import sqlite_sessions + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy.orm import sessionmaker + from sqlmodel import Session + +CALCULATED_AT = datetime(2026, 11, 17, 9, tzinfo=UTC) +FAILURE = "cliff_calculation_failed: the calculation raised an error" + + +def cliff_calculation( + status: SimulationStatus, + *, + simulation_run_id: UUID | None = None, + created_at: datetime = CALCULATED_AT, + cliff_gap: float = 1_200_000_000.0, + cliff_share: float = 0.04, +) -> CliffImpactRow: + """Return a cliff calculation in ``status``, as the table's checks allow it. + + A succeeded one has its two numbers, a failed one its error, and each + finished one its completion time. + """ + finished = status in {SimulationStatus.SUCCEEDED, SimulationStatus.FAILED} + succeeded = status is SimulationStatus.SUCCEEDED + return CliffImpactRow( + id=uuid4(), + created_at=created_at, + updated_at=created_at, + simulation_run_id=uuid4() if simulation_run_id is None else simulation_run_id, + status=status, + error_message=FAILURE if status is SimulationStatus.FAILED else None, + started_at=None if status is SimulationStatus.PENDING else created_at, + completed_at=created_at + timedelta(minutes=1) if finished else None, + cliff_gap=cliff_gap if succeeded else None, + cliff_share=cliff_share if succeeded else None, + ) + + +def side_calculation(status: CliffCalculationStatusName) -> CliffImpactRow | None: + """Return the calculation a side reads for ``status``: none when not calculated.""" + if status == "not_calculated": + return None + return cliff_calculation(SimulationStatus(status)) + + +def side(status: CliffCalculationStatusName) -> CliffCalculationRead: + """Return a side's read in ``status``, with the error only when failed.""" + return CliffCalculationRead( + status=status, error_message=FAILURE if status == "failed" else None + ) + + +@pytest.fixture +def sessions() -> Iterator[sessionmaker[Session]]: + yield from sqlite_sessions() + + +def store_calculations( + sessions: sessionmaker[Session], *calculations: CliffImpactRow +) -> None: + with sessions() as session: + session.add_all(calculations) + session.commit() + + +def test_sides_without_cliff_calculations_are_not_calculated() -> None: + cliffs = report_cliffs(ReportRunCliffRows(baseline=None, reform=None)) + + assert cliffs == ReportCliffsRead( + status="not_calculated", + baseline=side("not_calculated"), + reform=side("not_calculated"), + ) + + +@pytest.mark.parametrize( + "status", + [SimulationStatus.PENDING, SimulationStatus.RUNNING, SimulationStatus.SUCCEEDED], + ids=["pending", "running", "succeeded"], +) +def test_a_side_reads_its_unfailed_calculations_status_without_an_error( + status: SimulationStatus, +) -> None: + calculation = cliff_calculation(status) + + cliffs = report_cliffs(ReportRunCliffRows(baseline=calculation, reform=calculation)) + + assert cliffs.baseline == CliffCalculationRead( + status=status.value, error_message=None + ) + assert cliffs.reform == cliffs.baseline + + +def test_a_failed_side_says_why_its_calculation_failed() -> None: + cliffs = report_cliffs( + ReportRunCliffRows( + baseline=cliff_calculation(SimulationStatus.SUCCEEDED), + reform=cliff_calculation(SimulationStatus.FAILED), + ) + ) + + assert cliffs.reform == CliffCalculationRead(status="failed", error_message=FAILURE) + assert cliffs.baseline == side("succeeded") + + +@pytest.mark.parametrize( + ("baseline", "reform", "overall"), + [ + ("succeeded", "succeeded", "succeeded"), + ("succeeded", "failed", "failed"), + ("running", "failed", "failed"), + ("failed", "not_calculated", "failed"), + ("succeeded", "not_calculated", "not_calculated"), + ("running", "not_calculated", "not_calculated"), + ("succeeded", "running", "running"), + ("pending", "running", "running"), + ("succeeded", "pending", "pending"), + ("pending", "pending", "pending"), + ], +) +def test_the_reports_cliff_status_follows_its_least_finished_side( + baseline: CliffCalculationStatusName, + reform: CliffCalculationStatusName, + overall: CliffCalculationStatusName, +) -> None: + cliffs = report_cliffs( + ReportRunCliffRows( + baseline=side_calculation(baseline), reform=side_calculation(reform) + ) + ) + swapped = report_cliffs( + ReportRunCliffRows( + baseline=side_calculation(reform), reform=side_calculation(baseline) + ) + ) + + assert cliffs == ReportCliffsRead( + status=overall, baseline=side(baseline), reform=side(reform) + ) + assert swapped.status == overall + + +def test_every_side_status_is_one_a_report_can_have() -> None: + assert set(get_args(CliffCalculationStatusName)) == { + "not_calculated", + *(status.value for status in SimulationStatus), + } + + +def test_two_succeeded_sides_give_the_report_runs_cliff_impact() -> None: + cliff_impact = result_transformations.cliff_impact( + ReportRunCliffRows( + baseline=cliff_calculation( + SimulationStatus.SUCCEEDED, cliff_gap=1_200_000_000.0, cliff_share=0.04 + ), + reform=cliff_calculation( + SimulationStatus.SUCCEEDED, cliff_gap=1_100_000_000.0, cliff_share=0.035 + ), + ) + ) + + assert cliff_impact == CliffImpact( + baseline=CliffImpactInSimulation(cliff_gap=1_200_000_000.0, cliff_share=0.04), + reform=CliffImpactInSimulation(cliff_gap=1_100_000_000.0, cliff_share=0.035), + ) + + +@pytest.mark.parametrize( + "unfinished", ["not_calculated", "pending", "running", "failed"] +) +def test_a_side_without_a_result_leaves_the_cliff_impact_null( + unfinished: CliffCalculationStatusName, +) -> None: + succeeded = cliff_calculation(SimulationStatus.SUCCEEDED) + + for rows in ( + ReportRunCliffRows(baseline=succeeded, reform=side_calculation(unfinished)), + ReportRunCliffRows(baseline=side_calculation(unfinished), reform=succeeded), + ): + assert result_transformations.cliff_impact(rows) is None + + +def test_each_side_reads_its_runs_unfailed_calculation_before_a_newer_failed_one( + sessions: sessionmaker[Session], +) -> None: + baseline_run_id, reform_run_id = uuid4(), uuid4() + running = cliff_calculation( + SimulationStatus.RUNNING, simulation_run_id=baseline_run_id + ) + succeeded = cliff_calculation( + SimulationStatus.SUCCEEDED, simulation_run_id=reform_run_id + ) + store_calculations( + sessions, + running, + succeeded, + *( + cliff_calculation( + SimulationStatus.FAILED, + simulation_run_id=run_id, + created_at=CALCULATED_AT + timedelta(hours=1), + ) + for run_id in (baseline_run_id, reform_run_id) + ), + ) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=baseline_run_id, + reform_simulation_run_id=reform_run_id, + ) + + assert rows.baseline is not None + assert rows.baseline.id == running.id + assert rows.reform is not None + assert rows.reform.id == succeeded.id + + +def test_a_side_with_only_failed_calculations_reads_the_newest( + sessions: sessionmaker[Session], +) -> None: + run_id = uuid4() + failures = [ + cliff_calculation( + SimulationStatus.FAILED, + simulation_run_id=run_id, + created_at=CALCULATED_AT + timedelta(minutes=minutes), + ) + for minutes in (0, 20, 10) + ] + store_calculations(sessions, *failures) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, baseline_simulation_run_id=run_id, reform_simulation_run_id=uuid4() + ) + + assert rows.baseline is not None + assert rows.baseline.id == failures[1].id + assert rows.reform is None + + +def test_another_runs_calculations_are_not_read( + sessions: sessionmaker[Session], +) -> None: + store_calculations(sessions, cliff_calculation(SimulationStatus.SUCCEEDED)) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, + baseline_simulation_run_id=uuid4(), + reform_simulation_run_id=uuid4(), + ) + + assert rows == ReportRunCliffRows(baseline=None, reform=None) + + +def test_one_run_on_both_sides_reads_its_calculation_for_each( + sessions: sessionmaker[Session], +) -> None: + run_id = uuid4() + succeeded = cliff_calculation(SimulationStatus.SUCCEEDED, simulation_run_id=run_id) + store_calculations(sessions, succeeded) + + with sessions() as session: + rows = result_reads.read_cliff_calculations( + session, baseline_simulation_run_id=run_id, reform_simulation_run_id=run_id + ) + + assert rows.baseline is not None + assert rows.baseline.id == succeeded.id + assert rows.reform is rows.baseline diff --git a/tests/unit/v2/test_report_read_routes.py b/tests/unit/v2/test_report_read_routes.py index f9a935d96..ad8810cf0 100644 --- a/tests/unit/v2/test_report_read_routes.py +++ b/tests/unit/v2/test_report_read_routes.py @@ -11,6 +11,10 @@ from policyengine_api.services.v2.stored_reports.economy_results.types import ( EconomyResultUnreadableError, ) +from policyengine_api.services.v2.stored_reports.types import ( + CliffCalculationRead, + ReportCliffsRead, +) from policyengine_api.services.v2.stored_reports.validators import ( ReportStorageError, StoredReportNotFoundError, @@ -100,6 +104,83 @@ def test_a_report_without_a_run_answers_with_no_run_and_no_result() -> None: assert item["result"] is None +def test_a_report_answers_how_far_each_sides_cliff_calculation_has_got() -> None: + service = FakeReportService() + service.report = replace( + service.report, + cliffs=ReportCliffsRead( + status="failed", + baseline=CliffCalculationRead(status="succeeded", error_message=None), + reform=CliffCalculationRead( + status="failed", error_message="cliff_share_undefined: no adults" + ), + ), + ) + + item = ( + report_route_client(reports=service) + .get(f"/v2/reports/{REPORT_ID}?country_id=us") + .json()["result"]["item"] + ) + + assert item["cliffs"] == { + "status": "failed", + "baseline": {"status": "succeeded", "error_message": None}, + "reform": { + "status": "failed", + "error_message": "cliff_share_undefined: no adults", + }, + } + + +def test_a_report_without_a_run_answers_no_cliffs() -> None: + service = FakeReportService() + service.report = replace( + service.report, status="not_run", run=None, result=None, cliffs=None + ) + + item = ( + report_route_client(reports=service) + .get(f"/v2/reports/{REPORT_ID}?country_id=us") + .json()["result"]["item"] + ) + + assert item["cliffs"] is None + + +def test_a_listed_report_answers_no_cliffs() -> None: + service = FakeReportService(listed=(report_summary_read(),)) + + response = report_route_client(reports=service).get( + f"/v2/reports?country_id=us&report_id={REPORT_ID}" + ) + + assert response.status_code == 200, response.text + (item,) = response.json()["result"]["items"] + assert "cliffs" not in item + + +def test_the_openapi_document_describes_a_reports_cliffs() -> None: + document = report_route_client().get("/v2/openapi.json").json() + schemas = document["components"]["schemas"] + + cliffs = schemas["ReportCliffsItem"] + assert set(cliffs["properties"]) == {"status", "baseline", "reform"} + assert set(cliffs["properties"]["status"]["enum"]) == { + "not_calculated", + "pending", + "running", + "succeeded", + "failed", + } + assert set(schemas["CliffCalculationItem"]["properties"]) == { + "status", + "error_message", + } + assert "cliffs" in schemas["ReportItem"]["required"] + assert "cliffs" not in schemas["ReportSummaryItem"]["properties"] + + @pytest.mark.parametrize( ("error", "status_code", "message"), [ diff --git a/tests/unit/v2/test_report_run_routes.py b/tests/unit/v2/test_report_run_routes.py index 1f906988c..9ce831810 100644 --- a/tests/unit/v2/test_report_run_routes.py +++ b/tests/unit/v2/test_report_run_routes.py @@ -26,6 +26,7 @@ SubmissionStorageError, ) from policyengine_api.services.v2.stored_reports.validators import ( + CliffsNotAvailableError, ReportStorageError, RerunReportUnreadableError, StoredReportNotFoundError, @@ -239,10 +240,37 @@ def test_running_a_report_again_answers_the_report_with_its_new_run( assert item["result"] is None assert item["current_versions"]["policyengine_version"] == "4.2.0" assert service.calls == [ - ("rerun_report", {"country_id": "us", "report_id": REPORT_ID, "force": force}) + ( + "rerun_report", + { + "country_id": "us", + "report_id": REPORT_ID, + "force": force, + "include_cliffs": False, + }, + ) ] +@pytest.mark.parametrize( + ("body", "include_cliffs"), + [({}, False), ({"include_cliffs": False}, False), ({"include_cliffs": True}, True)], + ids=["omitted", "not-asked", "asked"], +) +def test_running_a_report_again_passes_on_whether_it_asks_for_cliffs( + body: dict[str, bool], + include_cliffs: bool, # noqa: FBT001 # pytest passes parameters positionally +) -> None: + service = FakeReportRunService() + + response = report_route_client(reports=service).post(RUNS_PATH, json=body) + + assert response.status_code == 201, response.text + ((_, arguments),) = service.calls + assert arguments["include_cliffs"] is include_cliffs + assert arguments["force"] is False + + @pytest.mark.parametrize( "body", [ @@ -252,8 +280,21 @@ def test_running_a_report_again_answers_the_report_with_its_new_run( {"force": True, "country_id": "us"}, [], "force", + {"include_cliffs": "yes"}, + {"include_cliffs": 1}, + {"include_cliffs": None}, + ], + ids=[ + "text", + "number", + "null", + "extra-field", + "list", + "string", + "text-cliffs", + "number-cliffs", + "null-cliffs", ], - ids=["text", "number", "null", "extra-field", "list", "string"], ) def test_a_rerun_refuses_a_malformed_body(body: object) -> None: service = FakeReportRunService() @@ -405,6 +446,13 @@ def test_a_new_run_whose_report_cannot_be_read_back_answers_the_reports_id() -> 503, "V2 report storage is unavailable", ), + ( + CliffsNotAvailableError( + "include_cliffs: a household report has no cliff impacts" + ), + 422, + "include_cliffs: a household report has no cliff impacts", + ), (RuntimeError("unexpected"), 500, "V2 report operation failed"), ], ids=[ @@ -418,6 +466,7 @@ def test_a_new_run_whose_report_cannot_be_read_back_answers_the_reports_id() -> "service-unavailable", "check-storage", "report-storage", + "no-cliffs", "unexpected", ], )