Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
fa9f6c0
Test reading report cliffs from simulation runs' cliff calculations (…
anth-volk Nov 17, 2026
e689730
Read report cliffs from simulation runs' cliff calculations
anth-volk Nov 17, 2026
7bd2fca
Test include_cliffs on report re-runs (failing)
anth-volk Nov 17, 2026
bacc8f1
Take include_cliffs on report re-runs
anth-volk Nov 17, 2026
0c164c6
Add the changelog fragment for report cliffs from simulation runs
anth-volk Nov 17, 2026
e987333
Move the requester's view of reports out of the report service
anth-volk Nov 17, 2026
6ef47cb
Read an economy report in its own method, and say how cliffs read
anth-volk Nov 17, 2026
820ef6a
Test that the API says a service may refuse cliffs (failing)
anth-volk Nov 18, 2026
63bbd8d
Say that a simulation service may refuse include_cliffs
anth-volk Nov 18, 2026
4a3e9fe
Test the exact cliff refusal the API describes (failing)
anth-volk Nov 18, 2026
5b47027
State exactly when a simulation service refuses cliffs
anth-volk Nov 18, 2026
6def637
Describe the cliff test rows by what they do
anth-volk Nov 18, 2026
ad40604
Merge the cliff impacts branch into report cliffs
anth-volk Nov 18, 2026
ae8d464
Test that report runs stop loading their cliff columns (failing)
anth-volk Nov 18, 2026
61ac1d0
Stop mapping report runs' four cliff columns
anth-volk Nov 18, 2026
6be2b3e
Test that the unmapped cliff columns are not model fields (failing)
anth-volk Nov 18, 2026
3fed540
Keep report runs' cliff columns in the table only
anth-volk Nov 18, 2026
608cfb7
Test the table-only column category's new name (failing)
anth-volk Nov 18, 2026
a3c941b
Name the table-only columns category accurately
anth-volk Nov 18, 2026
b092348
Merge the cliff impacts branch into report cliffs
anth-volk Nov 19, 2026
60fc6a1
Merge the cliff impacts branch into report cliffs
anth-volk Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/report-cliffs-from-simulation-runs.changed.md
Original file line number Diff line number Diff line change
@@ -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. A simulation service that doesn't calculate cliffs per simulation run refuses `include_cliffs: true` with 422, on creates and re-runs alike.
8 changes: 7 additions & 1 deletion policyengine_api/data/v2/models/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@

# These are the complete direct-SQLAlchemy categories permitted in the v2
# table layer. Each remains underneath canonical SQLModel table classes and
# Field/Relationship declarations; no parallel declarative model exists.
# Field/Relationship declarations, apart from table-only columns awaiting
# removal; no parallel declarative model exists.
DIRECT_SQLALCHEMY_EXCEPTIONS = MappingProxyType(
{
"timezone_aware_timestamps": (
Expand Down Expand Up @@ -39,6 +40,11 @@
"Concurrent report idempotency requires a savepoint and bounded "
"IntegrityError recovery around the database uniqueness constraint."
),
"table_only_columns_awaiting_removal": (
"A column API v1 no longer uses stays in its table, outside the "
"SQLModel fields and the mapper, until other writers have stopped "
"and a later revision drops it; API v1 doesn't load it meanwhile."
),
}
)

Expand Down
32 changes: 22 additions & 10 deletions policyengine_api/data/v2/models/reports.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

from datetime import datetime
from enum import StrEnum
from typing import TYPE_CHECKING, Any
from typing import TYPE_CHECKING, Any, ClassVar
from uuid import UUID

import sqlalchemy as sa
Expand Down Expand Up @@ -277,11 +277,14 @@ class ReportRun(TimestampedModel, table=True):
It compares ``baseline_simulation_run_id`` with
``reform_simulation_run_id``; a household report with only a baseline has
no reform run. A year of a budget window names its ``budget_window_run_id``
and ``year``, at most one report run per year of a window run. An economy
comparison's cliff impact is the baseline's and reform's cliff gap and
share, stored together or not at all; ``spm_provenance`` is the SPM receipt
and ``data_version`` the data release it used. Its labour supply response
has its own two tables.
and ``year``, at most one report run per year of a window run.
``spm_provenance`` is the SPM receipt and ``data_version`` the data release
it used. Its labour supply response has its own two tables. Its cliff impact
is its two simulation runs' (``CliffImpact``). The table's four older cliff
columns are declared in ``__table_args__`` and left out of the mapper, so API
v1 neither loads nor writes them. This covers only those four: ``trigger`` is
still mapped, so it must stop being mapped in an earlier release before a
revision drops it.

Outside budget windows, a report has at most one run that hasn't failed
for each pair of package versions, which identical requests join; a
Expand All @@ -290,7 +293,20 @@ class ReportRun(TimestampedModel, table=True):
"""

__tablename__ = "report_runs"
__mapper_args__: ClassVar[dict[str, Any]] = {
"exclude_properties": (
"baseline_cliff_gap",
"baseline_cliff_share",
"reform_cliff_gap",
"reform_cliff_share",
)
}
__table_args__ = (
# Kept in the table, unmapped, until a revision drops them.
sa.Column("baseline_cliff_gap", sa.Float),
sa.Column("baseline_cliff_share", sa.Float),
sa.Column("reform_cliff_gap", sa.Float),
sa.Column("reform_cliff_share", sa.Float),
sa.UniqueConstraint(
"report_id",
"idempotency_key",
Expand Down Expand Up @@ -393,10 +409,6 @@ class ReportRun(TimestampedModel, table=True):
)
error_message: str | None = None
markdown: str | None = Field(default=None, sa_type=sa.Text)
baseline_cliff_gap: float | None = None
baseline_cliff_share: float | None = None
reform_cliff_gap: float | None = None
reform_cliff_share: float | None = None
spm_provenance: dict[str, Any] | None = Field(
default=None,
sa_type=sa.JSON().with_variant(postgresql.JSONB(), "postgresql"),
Expand Down
4 changes: 4 additions & 0 deletions policyengine_api/fastapi_routes/resource_service_protocols.py
Original file line number Diff line number Diff line change
Expand Up @@ -304,11 +304,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
Expand Down
53 changes: 51 additions & 2 deletions policyengine_api/fastapi_routes/v2/reports/response_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -140,14 +140,62 @@ 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. A simulation service that doesn't calculate cliffs per simulation
run starts none, so a side with no calculation stays ``not_calculated``,
and it refuses ``include_cliffs: true`` with 422.
"""

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:
Expand Down Expand Up @@ -505,7 +553,8 @@ class ReportRunNotRecordedResponse(V2ErrorResponse):
"422, or its 400 for a region or dataset it does not have. The "
"message says which; for the simulation service's refusal, it gives "
"the service's code, when it gave one, and its reason, but not its "
"status."
"status. A simulation service that doesn't calculate cliffs per "
"simulation run answers that 422 for include_cliffs: true."
),
},
502: {
Expand Down
34 changes: 26 additions & 8 deletions policyengine_api/fastapi_routes/v2/reports/routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@
HouseholdResultUnreadableError,
)
from policyengine_api.services.v2.stored_reports.validators import (
CliffsNotAvailableError,
CreatedReportUnreadableError,
ForcedRerunRequiresAdminError,
ForcedRerunRequiresSignInError,
Expand Down Expand Up @@ -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(
(
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -390,7 +394,14 @@ 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 "
"simulation service that doesn't calculate cliffs per simulation "
"run refuses include_cliffs: true with 422 and starts no run. 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 "
Expand All @@ -416,7 +427,7 @@ def rerun() -> ReportDetailResponse | JSONResponse:
service_factory(),
country_id=query.country_id,
report_id=report_id,
force=body.force,
body=body,
requester=requester,
)

Expand Down Expand Up @@ -475,8 +486,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 refuses include_cliffs: "
"true with 422 and creates nothing. 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 "
Expand Down Expand Up @@ -564,7 +579,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 "
Expand Down
16 changes: 14 additions & 2 deletions policyengine_api/fastapi_routes/v2/reports/run_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,18 @@ 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. A simulation service that doesn't
calculate cliffs per simulation run refuses ``include_cliffs: true`` with
422 and starts no run.
"""

force: StrictBool = False
include_cliffs: StrictBool = False


class ReportRunListResult(StrictReportAPIModel):
Expand Down Expand Up @@ -178,7 +186,11 @@ 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; a simulation service that doesn't calculate "
"cliffs per simulation run refuses include_cliffs: true; 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 "
Expand Down
20 changes: 16 additions & 4 deletions policyengine_api/libs/simulation_report_reruns.py
Original file line number Diff line number Diff line change
Expand Up @@ -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; a service that doesn't calculate cliffs per
simulation run refuses the field with 422, 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:
Expand Down Expand Up @@ -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 that
doesn't calculate cliffs per simulation run refuses the field, so a
re-run that doesn't ask for cliffs isn't refused for it.
"""
body: dict[str, Any] = {"force": rerun.force}
if rerun.include_cliffs:
body["include_cliffs"] = True
return body


def post_report_rerun(
Expand Down
26 changes: 19 additions & 7 deletions policyengine_api/services/v2/simulation_service/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -259,12 +259,19 @@ 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. A simulation
service that doesn't calculate cliffs per simulation run refuses
``include_cliffs: true`` with 422 and creates nothing.
``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
Expand Down Expand Up @@ -428,14 +435,19 @@ 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, asks the service to start a cliff calculation for each side's
simulation run that has none, or whose newest one failed; it is sent
only when true, and a service that doesn't calculate cliffs per
simulation run refuses it.
"""

country_id: str
report_id: UUID
kind: ReportRerunKind
force: bool
policy_ids: tuple[UUID | None, ...]
include_cliffs: bool = False


class SimulationServiceClient(Protocol):
Expand Down
Loading
Loading