Serve household reports at /v2/reports

.github/workflows/v2-integration-check.yml

@@ -77,8 +77,8 @@ jobs:
         run: uv run coverage run --branch -m pytest -q tests/integration/test_v2_catalog_installed.py
         env:
           RUN_V2_CATALOG_COMPATIBILITY: "1"
-      - name: Test v2 metadata publication, resource routes, the countries list and economy reports
-        run: uv run coverage run -a --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_metadata_routes.py tests/integration/test_v2_country_routes.py tests/integration/test_v2_economy_reports.py
+      - name: Test v2 metadata publication, resource routes, the countries list and economy and household reports
+        run: uv run coverage run -a --branch -m pytest -q tests/integration/test_v2_catalog_publication.py tests/integration/test_v2_metadata_routes.py tests/integration/test_v2_country_routes.py tests/integration/test_v2_economy_reports.py tests/integration/test_v2_household_reports.py
       - name: Test v2 policy persistence and immediate v1 mirroring
         run: uv run 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 and user associations

changelog.d/v2-household-reports.added.md

@@ -0,0 +1 @@
+Household reports at /v2/reports: a household stored through /v2/households under a baseline and an optional reform, calculated by the simulation service for the household's default year, for any country with household calculations, including a household-only one.

docs/engineering/migration-contracts.md

@@ -7,8 +7,8 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
 | Metric | Count |
 | --- | ---: |
 | route group count | 9 |
-| workflow count | 18 |
-| request count | 96 |
+| workflow count | 19 |
+| request count | 99 |
 | db entity count | 6 |
 | sim flow count | 3 |
 
@@ -213,6 +213,17 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi
 | `POST` | `/v2/reports/{report_id}/runs?country_id=us` | 201 | `report` | none | `status`, `message`, `result.item.id`, `result.item.trigger`, `result.item.tax_benefit_model_version_id`, `result.item.policyengine_version`, `result.item.status` |
 | `GET` | `/v2/reports/{report_id}/runs?country_id=us` | 200 | `report` | none | `status`, `message`, `result.items` |
 
+### `household_reports_v2`
+
+- Current contract: `typed_v2_resources`
+- Future owner: Household reports on v2
+
+| Method | Path | Status | Route group | Required headers | Stable response fields |
+| --- | --- | ---: | --- | --- | --- |
+| `POST` | `/v2/reports?country_id=uk` | 201 | `report` | none | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.kind`, `result.item.year`, `result.item.household_id`, `result.item.baseline_simulation_id`, `result.item.reform_simulation_id`, `result.item.status`, `result.item.run` |
+| `GET` | `/v2/reports/{report_id}?country_id=uk` | 200 | `report` | none | `status`, `message`, `result.item.id`, `result.item.kind`, `result.item.status`, `result.item.run.baseline.result`, `result.item.run.reform.result` |
+| `POST` | `/v2/reports/{report_id}/runs?country_id=uk` | 201 | `report` | none | `status`, `message`, `result.item.kind`, `result.item.id`, `result.item.trigger`, `result.item.tax_benefit_model_version_id`, `result.item.policyengine_version`, `result.item.status` |
+
 ### `metadata_resources_v2_preview`
 
 - Current contract: `typed_v2_resources`

docs/generated/migration_contracts.json

@@ -1,10 +1,10 @@
 {
   "metadata": {
     "db_entity_count": 6,
-    "request_count": 96,
+    "request_count": 99,
     "route_group_count": 9,
     "sim_flow_count": 3,
-    "workflow_count": 18
+    "workflow_count": 19
   },
   "route_groups": [
     {
@@ -1471,6 +1471,66 @@
         }
       ]
     },
+    {
+      "current_contract": "typed_v2_resources",
+      "future_owner_pr": "Household reports on v2",
+      "name": "household_reports_v2",
+      "requests": [
+        {
+          "expected_status": 201,
+          "headers": [],
+          "method": "POST",
+          "path": "/v2/reports?country_id=uk",
+          "route_group": "report",
+          "stable_response_fields": [
+            "status",
+            "message",
+            "result.item.id",
+            "result.item.country_id",
+            "result.item.kind",
+            "result.item.year",
+            "result.item.household_id",
+            "result.item.baseline_simulation_id",
+            "result.item.reform_simulation_id",
+            "result.item.status",
+            "result.item.run"
+          ]
+        },
+        {
+          "expected_status": 200,
+          "headers": [],
+          "method": "GET",
+          "path": "/v2/reports/{report_id}?country_id=uk",
+          "route_group": "report",
+          "stable_response_fields": [
+            "status",
+            "message",
+            "result.item.id",
+            "result.item.kind",
+            "result.item.status",
+            "result.item.run.baseline.result",
+            "result.item.run.reform.result"
+          ]
+        },
+        {
+          "expected_status": 201,
+          "headers": [],
+          "method": "POST",
+          "path": "/v2/reports/{report_id}/runs?country_id=uk",
+          "route_group": "report",
+          "stable_response_fields": [
+            "status",
+            "message",
+            "result.item.kind",
+            "result.item.id",
+            "result.item.trigger",
+            "result.item.tax_benefit_model_version_id",
+            "result.item.policyengine_version",
+            "result.item.status"
+          ]
+        }
+      ]
+    },
     {
       "current_contract": "typed_v2_resources",
       "future_owner_pr": "Later metadata read cutover and v2 route-prefix removal",

policyengine_api/fastapi_routes/dependencies.py

@@ -30,7 +30,13 @@
         SimulationReferenceChecker,
     )
     from policyengine_api.services.v2.countries.types import CountryRead
-    from policyengine_api.services.v2.economy_reports.types import EconomyReportFields
+    from policyengine_api.services.v2.economy_reports.types import (
+        EconomyReportFields,
+        EconomyReportListing,
+    )
+    from policyengine_api.services.v2.household_reports.types import (
+        HouseholdReportSimulation,
+    )
     from policyengine_api.services.v2.households.types import (
         HouseholdPage,
         HouseholdRead,
@@ -62,6 +68,9 @@
         PolicyPage,
         PolicyRead,
     )
+    from policyengine_api.services.v2.report_kinds.types import (
+        HouseholdReportOperations as V2HouseholdReportResourceService,
+    )
     from policyengine_api.services.v2.simulation_entrypoint.types import (
         EconomyReportRecord,
         EconomyReportRunRecord,
@@ -382,6 +391,12 @@ def list_reports(
         """Return the country's reports among ``report_ids``, in order, once each."""
         ...
 
+    def find_reports(
+        self, *, country_id: str, report_ids: Sequence[UUID]
+    ) -> EconomyReportListing:
+        """List the country's reports among ``report_ids``, naming the unreadable."""
+        ...
+
     def list_report_runs(
         self, *, country_id: str, report_id: UUID
     ) -> tuple[EconomyReportRunRecord, ...]:
@@ -901,6 +916,57 @@ def _default_v2_economy_report_service_factory() -> V2EconomyReportResourceServi
     )
 
 
+def _default_household_report_simulation() -> HouseholdReportSimulation:
+    """Return the process's adapter for the entrypoint's household report routes.
+
+    Raise ``SimulationServiceUnavailableError`` when the generated client is
+    not installed or has no household report routes (a client generated
+    before them, whose import fails with ``ImportError``), or the entrypoint
+    URL or gateway auth is unusable.
+    """
+    try:
+        from policyengine_api.libs.simulation_household_reports import (
+            shared_household_reports,
+        )
+    except ImportError as error:
+        if (error.name or "").split(".")[0] != SIMULATION_CLIENT_PACKAGE:
+            raise
+        msg = (
+            "the generated simulation client (policyengine-api-simulation-client) "
+            "is not installed or has no household report routes"
+        )
+        raise SimulationServiceUnavailableError(msg) from error
+    return shared_household_reports()
+
+
+def _default_v2_household_report_service_factory() -> V2HouseholdReportResourceService:
+    """Build the household report service; the adapter waits for its first call.
+
+    Refusals the Public API decides itself, such as a household-only
+    country's missing household, then answer without the simulation client.
+    """
+    from policyengine_api.data.v2.database import (
+        get_v2_session_factory,
+    )
+    from policyengine_api.services.v2.household_reports.database_session import (
+        HouseholdReportDatabaseSession,
+    )
+    from policyengine_api.services.v2.household_reports.services import (
+        DeferredHouseholdReportSimulation,
+        V2HouseholdReportService,
+    )
+
+    return V2HouseholdReportService(
+        HouseholdReportDatabaseSession(get_v2_session_factory()),
+        households=_default_v2_household_service_factory(),
+        policies=_default_v2_policy_service_factory(),
+        simulation=DeferredHouseholdReportSimulation(
+            _default_household_report_simulation
+        ),
+        current_policyengine_version=_running_policyengine_version(),
+    )
+
+
 def _default_v2_policy_service_factory() -> V2PolicyResourceService:
     from policyengine_api.data.v2.database import (
         get_v2_session_factory,
@@ -987,11 +1053,19 @@ def _default_legacy_reference_checker() -> LegacyReferenceChecker:
 
 def _default_simulation_reference_checker() -> SimulationReferenceChecker:
     """Defer the simulation client until a request checks a v2 reference."""
+    from policyengine_api.services.v2.household_reports.services import (
+        DeferredHouseholdReportSimulation,
+    )
     from policyengine_api.services.v2.simulation_refs.services import (
         SimulationReferenceService,
     )
 
-    return SimulationReferenceService(_deferred_economy_report_simulation())
+    return SimulationReferenceService(
+        _deferred_economy_report_simulation(),
+        household_reports=DeferredHouseholdReportSimulation(
+            _default_household_report_simulation
+        ),
+    )
 
 
 def _default_v2_user_policy_service_factory() -> V2UserPolicyResourceService:
@@ -1091,6 +1165,9 @@ class NativeRouteDependencies:
     v2_economy_report_service_factory: (
         Callable[[], V2EconomyReportResourceService] | None
     ) = None
+    v2_household_report_service_factory: (
+        Callable[[], V2HouseholdReportResourceService] | None
+    ) = None
     v2_policy_service_factory: Callable[[], V2PolicyResourceService] | None = None
     v2_household_service_factory: Callable[[], V2HouseholdResourceService] | None = None
     v2_user_policy_service_factory: Callable[[], V2UserPolicyResourceService] | None = (
@@ -1125,6 +1202,9 @@ def defaults(cls) -> NativeRouteDependencies:
             v2_economy_report_service_factory=(
                 _default_v2_economy_report_service_factory
             ),
+            v2_household_report_service_factory=(
+                _default_v2_household_report_service_factory
+            ),
             v2_policy_service_factory=_default_v2_policy_service_factory,
             v2_household_service_factory=_default_v2_household_service_factory,
             v2_user_policy_service_factory=(_default_v2_user_policy_service_factory),