Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
0ddd093
Test reading budget-window reports from their window runs and years (…
anth-volk Nov 12, 2026
a8751d1
Read budget-window reports from their window runs and years
anth-volk Nov 12, 2026
e0f3168
Test creating budget-window reports through the simulation service (f…
anth-volk Nov 12, 2026
d52ba76
Create budget-window reports through the simulation service
anth-volk Nov 12, 2026
642470d
Test that a saved report's budget window agrees with its report (fail…
anth-volk Nov 12, 2026
54330d2
Keep a saved report's budget window agreeing with its report
anth-volk Nov 12, 2026
df26a6c
Test that CI runs the budget-window integration tests (failing)
anth-volk Nov 12, 2026
89c8034
Run the budget-window integration tests in the cross-database check
anth-volk Nov 12, 2026
75340d8
Describe budget-window reports in the changelog and the saved-record …
anth-volk Nov 12, 2026
3e63d42
Test listing and saving unreadable windows, and the window's document…
anth-volk Nov 12, 2026
faa1481
Fix review round 1's quality findings for budget-window reports
anth-volk Nov 12, 2026
b2a6309
Merge #4286's branch, with master's admin user profiles, into budget-…
anth-volk Nov 12, 2026
0e62b26
Test that only saved-report writes document the window refusal (failing)
anth-volk Nov 12, 2026
4e2007c
Fix review round 2's findings: the window's 400 text and each year's …
anth-volk Nov 12, 2026
9c10921
Fix review round 3's wording and test-helper findings
anth-volk Nov 12, 2026
7c8e881
Merge master into v2plan/c1-14-budget-window-reports
anth-volk Nov 12, 2026
1701655
Merge master into v2plan/c1-14-budget-window-reports
anth-volk Nov 12, 2026
2908556
Merge master into v2plan/c1-14-budget-window-reports
anth-volk Nov 12, 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
4 changes: 2 additions & 2 deletions .github/workflows/v2-integration-check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -74,11 +74,11 @@ jobs:
- name: Verify the managed v2 roles hold their declared privileges
run: uv run --frozen --extra dev python scripts/reconcile_v2_privileges.py verify
- name: Test v2 metadata publication, resource routes, the countries list, reports and simulations
run: uv run --frozen --extra dev coverage run --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_catalog_publication_time_periods.py tests/integration/test_v2_catalog_publication_pruning.py tests/integration/test_v2_catalog_spm_availability.py tests/integration/test_v2_metadata_routes.py tests/integration/test_v2_country_routes.py tests/integration/test_v2_report_reads.py tests/integration/test_v2_report_creation.py
run: uv run --frozen --extra dev coverage run --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_catalog_publication_time_periods.py tests/integration/test_v2_catalog_publication_pruning.py tests/integration/test_v2_catalog_spm_availability.py tests/integration/test_v2_metadata_routes.py tests/integration/test_v2_country_routes.py tests/integration/test_v2_report_reads.py tests/integration/test_v2_report_creation.py tests/integration/test_v2_budget_window_report_reads.py tests/integration/test_v2_budget_window_report_creation.py
- name: Test v2 policy persistence and immediate v1 mirroring
run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_policy_persistence.py tests/integration/test_v1_policy_dual_write.py tests/integration/test_mysql_policy_dual_write.py tests/integration/test_v2_user_policy_mirroring.py tests/integration/test_v1_user_policy_dual_write.py
- name: Test signed-in identity provisioning, user associations, saved detailed-save records and user types
run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_user_identity_persistence.py tests/integration/test_v2_user_type_persistence.py tests/integration/test_v2_saved_detailed_save_records.py
run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_user_identity_persistence.py tests/integration/test_v2_user_type_persistence.py tests/integration/test_v2_saved_detailed_save_records.py tests/integration/test_v2_saved_budget_window_reports.py
- name: Test comparison-run persistence, the simulation API's roles and privilege reconciliation as the managed roles
run: uv run --frozen --extra dev coverage run -a --branch -m pytest -q tests/integration/test_v2_stage12_comparison_persistence.py tests/integration/test_v2_simulation_role_privileges.py tests/integration/test_v2_privilege_reconciliation.py
- name: Test v2 household persistence, immediate v1 copying and household calculation reads
Expand Down
1 change: 1 addition & 0 deletions changelog.d/v2-budget-window-reports.added.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
`/v2/reports` serves budget windows: a report comparing a baseline and a reform in each year of a window of 1 to 75 years, ending in 2200 or earlier. `POST /v2/reports` takes `kind` `budget_window` with the first `year` and `budget_window_size`, checks it as an economy report is, and has the simulation service create it. `GET /v2/reports/{report_id}` and the report listing answer a budget window with its newest budget-window run and that run's years, each a report run with its own status and versions; once the run has succeeded, the read gives today's budget-window result, each year's budget figures and their totals, rebuilt from each year's stored rows. A saved report naming a detailed-save report must give that report's own budget window as `budget_window_years` (none for a window shorter than two years), or is refused with 400.
7 changes: 5 additions & 2 deletions docs/engineering/skills/alembic-migrations.md
Original file line number Diff line number Diff line change
Expand Up @@ -647,8 +647,11 @@ model changes:
filter selects (`child` for `age`); both join their table's unique key.
- `report_runs` gains its Modal call ID.
- Budget windows: a simulation run calculates one `year`, which joins the
index for a simulation's newest successful run, so a budget window compares
a report's same two simulations in every year. `reports.budget_window_size`
index for a simulation's newest successful run. Each year of a budget
window is a report run naming the two simulation runs it compares; the
simulation service gives each year simulations of that year, or reuses
succeeded runs, and the report's own two simulations are its first year's.
`reports.budget_window_size`
(1 to 75 years, an economy report with a year, ending by 2200) marks a
budget-window report. The new `budget_window_runs` holds one row per
calculation of one: its report, catalog version, trigger, whether its years
Expand Down
7 changes: 7 additions & 0 deletions docs/migration/stage-12a-user-login.md
Original file line number Diff line number Diff line change
Expand Up @@ -436,6 +436,13 @@ detailed-save `simulation_id` or `report_id` beside the v1
still be renamed.
- Neither reference can be cleared. No route looks a detailed-save record up
by its v1 number, and no read starts a run.
- A detailed-save report stores its own budget window
(`reports.budget_window_size`), so a saved report naming one gives the same
`budget_window_years`, or null for a report without a window of two or more
years (a saved report stores a one-year window as null). Anything else is
400, on create and on any update naming `report_id` or
`budget_window_years`; it is read in the write's transaction. A saved v1
report keeps the `budget_window_years` it is given.

`MeItem` is `{id, user_type, primary_country, first_name, last_name, email,
created_at}`; `user_type` is `unauthenticated` or the signed-in user's stored
Expand Down
6 changes: 4 additions & 2 deletions policyengine_api/data/v2/models/simulations.py
Original file line number Diff line number Diff line change
Expand Up @@ -135,8 +135,10 @@ class Simulation(TimestampedModel, table=True):
class SimulationRun(TimestampedModel, table=True):
"""One run of a simulation for one year on one catalog and .py version.

A simulation has a run per year it is calculated for, so a budget window
compares a report's same two simulations in every year of the window.
Each run calculates one ``year``. Each year of a budget window is a
report run naming the two simulation runs it compares: the simulation
service gives each year simulations of that year, or reuses succeeded
runs, and the report's own two simulations are its first year's.

``tax_benefit_model_version_id``, ``dataset_id`` and ``region_id`` name the
catalog version, dataset and region the run used, which a run on a newer
Expand Down
26 changes: 14 additions & 12 deletions policyengine_api/fastapi_routes/resource_service_protocols.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,12 @@
NativePolicyCreationInput,
)
from policyengine_api.services.v2.simulation_service.types import (
EconomyReportCreationInput,
EconomySimulationCreationInput,
ReportCreationInput,
)
from policyengine_api.services.v2.stored_reports.types import (
ReportRead,
ReportSummaryRead,
StoredReportRead,
StoredReportSummaryRead,
)
from policyengine_api.services.v2.stored_simulations.types import SimulationRead
from policyengine_api.services.v2.user_accounts.types import (
Expand Down Expand Up @@ -190,23 +190,25 @@ def get_calculation(self, calculation_id: UUID) -> HouseholdCalculationRead:
class V2StoredReportResourceService(Protocol):
"""Route-independent report operations for one request."""

def get_report(self, *, country_id: str, report_id: UUID) -> ReportRead:
"""Return the country's economy report, its newest run and that run's result.
def get_report(self, *, country_id: str, report_id: UUID) -> StoredReportRead:
"""Return the country's report, its newest run and that run's result.

Raise ``StoredReportNotFoundError`` when the country has no such
report, ``ReportKindUnsupportedError`` for a household report or
budget window, and ``EconomyResultUnreadableError`` when a succeeded
run's result cannot be read.
The report is an economy report or a budget window. Raise
``StoredReportNotFoundError`` when the country has no such report,
``ReportKindUnsupportedError`` for a household report, and
``EconomyResultUnreadableError`` or
``BudgetWindowResultUnreadableError`` when a succeeded run's result
cannot be read.
"""
...

def list_reports(
self, *, country_id: str, report_ids: Sequence[UUID]
) -> tuple[ReportSummaryRead, ...]:
"""Return the country's economy reports among ``report_ids``, in that order."""
) -> tuple[StoredReportSummaryRead, ...]:
"""Return the country's economy reports and budget windows, as named."""
...

def create_report(self, report_input: EconomyReportCreationInput) -> ReportRead:
def create_report(self, report_input: ReportCreationInput) -> StoredReportRead:
"""Create the report through the simulation service; return it as stored.

Raise ``EconomyCalculationsUnsupportedError`` for a country without
Expand Down
24 changes: 23 additions & 1 deletion policyengine_api/fastapi_routes/v2/reports/request_models.py
Original file line number Diff line number Diff line change
@@ -1,14 +1,36 @@
"""Strict HTTP request models for v2 reports."""

from typing import Annotated

from pydantic import Field

from policyengine_api.services.v2.simulation_service.types import (
BudgetWindowReportCreationInput,
EconomyReportCreationInput,
)


class ReportCreateRequest(EconomyReportCreationInput):
class EconomyReportCreateRequest(EconomyReportCreationInput):
"""An economy report to create; ``country_id`` must match the query's.

Each simulation's empty object is current law. No field names a
PolicyEngine.py version: the simulation service runs its default
worker's.
"""


class BudgetWindowReportCreateRequest(BudgetWindowReportCreationInput):
"""A budget window to create; ``country_id`` must match the query's.

It compares ``baseline`` and ``reform`` in each of ``budget_window_size``
years (1 to 75) from ``year``, ending in 2200 or earlier. Each
simulation's empty object is current law, and no field names a
PolicyEngine.py version.
"""


# A report to create: ``kind`` says which.
ReportCreateRequest = Annotated[
EconomyReportCreateRequest | BudgetWindowReportCreateRequest,
Field(discriminator="kind"),
]
141 changes: 132 additions & 9 deletions policyengine_api/fastapi_routes/v2/reports/response_models.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
from __future__ import annotations

from datetime import datetime
from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar
from typing import TYPE_CHECKING, Annotated, Any, Generic, Literal, TypeVar
from uuid import UUID

from pydantic import BaseModel, ConfigDict, JsonValue
from pydantic import BaseModel, ConfigDict, Field, JsonValue

from policyengine_api.fastapi_routes.v2.errors_support import (
V2ErrorResponse,
Expand All @@ -15,14 +15,21 @@
from policyengine_api.fastapi_routes.v2.simulation_resources_support import (
error_response,
)
from policyengine_api.services.v2.stored_reports.budget_window_results.types import (
BudgetWindowResult,
)
from policyengine_api.services.v2.stored_reports.economy_results.types import (
EconomyResult,
)

if TYPE_CHECKING:
from policyengine_api.services.v2.stored_reports.types import (
BudgetWindowReportRead,
BudgetWindowReportSummaryRead,
ReportRead,
ReportSummaryRead,
StoredReportRead,
StoredReportSummaryRead,
)


Expand Down Expand Up @@ -115,16 +122,129 @@ def from_read(cls, read: ReportRead) -> ReportItem:
return cls.model_validate(read)


class BudgetWindowYearItem(ReportRunItem):
"""One year of a budget-window run: the report run calculating that year.

Its fields are a report run's, as ``ReportRunItem`` describes them; its
simulation runs are that year's own. A year still waiting to start is
``pending``, and one the window failed before it started is ``failed``,
its ``error_message`` saying so.
"""

year: int


class BudgetWindowRunItem(StrictReportAPIModel):
"""One calculation of a budget window: a report run per year, in year order.

``status`` is ``pending`` until a year starts running, ``running`` while
its years run, ``failed`` once a year has failed, with ``error_message``
saying which, and ``succeeded`` once every year has. ``trigger`` is
``initial`` for the run the report's creation started, and
``recalculate`` says whether its years calculate their
simulations again rather than reusing successful runs.
``country_package_version`` and ``policyengine_version`` are the versions
its years run on, null for a run with no year.
"""

id: UUID
status: Literal["pending", "running", "succeeded", "failed"]
trigger: Literal["initial", "manual", "system"]
recalculate: bool
country_package_version: str | None
policyengine_version: str | None
error_message: str | None
created_at: datetime
started_at: datetime | None
completed_at: datetime | None
years: list[BudgetWindowYearItem]


class BudgetWindowReportSummaryItem(StrictReportAPIModel):
"""A budget window: a baseline and a reform policy compared in each year.

The window is ``budget_window_size`` years from ``year``, in the region
and dataset named. ``baseline_simulation`` and ``reform_simulation`` are
the first year's; each year's run names that year's own simulation runs.
``status`` is the newest run's, or ``not_run`` for a
report with no run. ``run`` is the newest budget-window run, whatever its
status and versions, with its years; ``current_versions`` are the
versions the Public API runs now, so a newest run on other versions is
out of date. ``options`` are the options the report was created with.
"""

id: UUID
country_id: str
kind: Literal["budget_window"]
label: str
description: str | None
year: int | None
budget_window_size: int
region_code: str | None
dataset_name: str | None
baseline_simulation: ReportSimulationItem | None
reform_simulation: ReportSimulationItem | None
options: dict[str, JsonValue]
created_at: datetime
status: Literal["not_run", "pending", "running", "succeeded", "failed"]
run: BudgetWindowRunItem | None
current_versions: PackageVersionsItem

@classmethod
def from_summary(
cls, read: BudgetWindowReportSummaryRead
) -> BudgetWindowReportSummaryItem:
"""Build the summary from the service's read, without a result."""
return cls.model_validate(read)


class BudgetWindowReportItem(BudgetWindowReportSummaryItem):
"""A budget window with its newest run's result.

``result`` is the budget-window result, in the format the app reads
today: each year's budget figures, in year order, and their totals. It is
there once the newest run has succeeded, and null otherwise.
"""

result: BudgetWindowResult | None

@classmethod
def from_read(cls, read: BudgetWindowReportRead) -> BudgetWindowReportItem:
"""Build the item from the service's read, with its result."""
return cls.model_validate(read)


def report_item(read: StoredReportRead) -> ReportItem | BudgetWindowReportItem:
"""Build the item of the report's kind from the service's read."""
if read.kind == "budget_window":
return BudgetWindowReportItem.from_read(read)
return ReportItem.from_read(read)


def report_summary_item(
read: StoredReportSummaryRead,
) -> ReportSummaryItem | BudgetWindowReportSummaryItem:
"""Build the summary of the report's kind from the service's read."""
if read.kind == "budget_window":
return BudgetWindowReportSummaryItem.from_summary(read)
return ReportSummaryItem.from_summary(read)


class ReportDetailResult(StrictReportAPIModel):
"""Result holding one report in ``item``."""
"""Result holding one report in ``item``; its ``kind`` says which model it is."""

item: ReportItem
item: Annotated[ReportItem | BudgetWindowReportItem, Field(discriminator="kind")]


class ReportListResult(StrictReportAPIModel):
"""The listed reports in ``items``, in the order named, without results."""

items: list[ReportSummaryItem]
items: list[
Annotated[
ReportSummaryItem | BudgetWindowReportSummaryItem,
Field(discriminator="kind"),
]
]


ResultT = TypeVar("ResultT")
Expand Down Expand Up @@ -176,11 +296,12 @@ class UnavailableAfterReportCreatedResponse(V2ErrorResponse):
404: error_response("No report has this ID in this country."),
422: error_response(
"The request does not match the schema, or the report is a household "
"report or a budget window, which this route does not read yet."
"report, which this route does not read yet."
),
500: error_response(
"The newest run succeeded but its stored result cannot be read, or the "
"operation could not be completed."
"The newest run succeeded but its stored result cannot be read (for a "
"budget window, a year has no succeeded run or no budget figures), or "
"the operation could not be completed."
),
}
CREATE_RESPONSES: dict[int | str, dict[str, Any]] = {
Expand All @@ -190,7 +311,9 @@ class UnavailableAfterReportCreatedResponse(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 (such as a budget window of "
"fewer than 1 or more than 75 years, or one ending after 2200); the "
"country has no economy "
"reports (such as a household-only country); a policy the report "
"names sets parameters the running catalog version does not have "
"(code missing_parameters, which names them; the baseline's policy is "
Expand Down
Loading
Loading