Expose current rate calculation details

Author: javaDevJT

README.md

@@ -56,6 +56,7 @@ During setup you choose:
 - **Net metering enabled** (checkbox).
 - **Include PSCR** (enabled by default).
 - **Tax rate (%)** (free-form, defaults to `4.0`; set to `0` to omit tax).
+- Detroit residents may incur an additional 5.0% City Utility Users' Tax; adjust the free-form tax rate if that applies to your service address.
 
 ## Entities Created
 
@@ -84,6 +85,8 @@ Core rate entities include attributes such as:
 - `include_pscr`
 - `tax_rate_percent`
 - `pscr_cents`
+- `current_rate_formula`
+- `current_rate_calculation`
 - `selected_rate_available`
 - `warning` (when selected plan disappears)
 

custom_components/dte_rates/config_flow.py

@@ -134,5 +134,6 @@ def _rider18_status(rate_card) -> str:
 def _tax_note() -> str:
     return (
         "Default tax is Michigan's 4.0% residential electric sales tax. "
+        "Detroit residents may incur an additional 5.0% City Utility Users' Tax. "
         "Set tax rate to 0 to omit taxes from rate calculations."
     )

custom_components/dte_rates/const.py

@@ -41,6 +41,8 @@
 ATTR_SELECTED_RATE_AVAILABLE = "selected_rate_available"
 ATTR_WARNING = "warning"
 ATTR_CURRENT_RATE_NAME = "current_rate_name"
+ATTR_CURRENT_RATE_CALCULATION = "current_rate_calculation"
+ATTR_CURRENT_RATE_FORMULA = "current_rate_formula"
 ATTR_NEXT_RATE_CHANGE = "next_rate_change"
 ATTR_NEXT_RATE_NAME = "next_rate_name"
 ATTR_NEXT_RATE_VALUE = "next_rate_value"

custom_components/dte_rates/sensor.py

@@ -19,6 +19,8 @@
     ATTR_COMPONENTS,
     ATTR_MONTHLY_COMPONENTS,
     ATTR_PERIOD,
+    ATTR_CURRENT_RATE_CALCULATION,
+    ATTR_CURRENT_RATE_FORMULA,
     ATTR_CURRENT_RATE_NAME,
     ATTR_EXPORT_RATE_SOURCE,
     ATTR_EXPORT_RATE_WARNING,
@@ -46,6 +48,7 @@
 )
 from .models import RatePlan, SeasonalPeriodRate
 from .rate_calculator import (
+    GENERATION_COMPONENT_MARKERS,
     current_export_rate_cents,
     current_import_rate_cents,
     get_active_period,
@@ -161,6 +164,80 @@ def _export_rate_warning(self, period: SeasonalPeriodRate) -> str | None:
             "for the active period; using the available formula components only."
         )
 
+    def _import_rate_calculation(self, period: SeasonalPeriodRate, mode: str = "import") -> dict:
+        base = period.components.per_kwh_total
+        pscr = self._pscr_cents_for_rate()
+        pscr_applied = pscr if self._include_pscr() and pscr is not None else Decimal("0")
+        pre_tax = base + pscr_applied
+        tax_rate = self._tax_rate_percent()
+        tax = pre_tax * tax_rate / Decimal("100")
+        total = pre_tax + tax
+
+        formula = (
+            f"((base {self._fmt(base)} + PSCR {self._fmt(pscr_applied)}) "
+            f"* (1 + tax {self._fmt(tax_rate)}%)) / 100 = ${self._fmt_usd(total)}/kWh"
+        )
+        if mode == "net_metering_export":
+            formula = f"net metering export uses modified import rate: {formula}"
+
+        return {
+            "mode": mode,
+            "base_cents_per_kwh": self._as_float(base),
+            "pscr_cents_per_kwh": self._as_float(pscr),
+            "pscr_included": self._include_pscr() and pscr is not None,
+            "tax_rate_percent": self._as_float(tax_rate),
+            "tax_applied": tax_rate != 0,
+            "pre_tax_cents_per_kwh": self._as_float(pre_tax),
+            "tax_cents_per_kwh": self._as_float(tax),
+            "total_cents_per_kwh": self._as_float(total),
+            "total_usd_per_kwh": self._as_float(total / Decimal("100")),
+            "formula": formula,
+        }
+
+    def _export_rate_calculation(self, period: SeasonalPeriodRate) -> dict:
+        if self._entry.data.get(CONF_NET_METERING, False):
+            return self._import_rate_calculation(period, "net_metering_export")
+
+        generation = sum(
+            value
+            for key, value in period.components.per_kwh.items()
+            if any(marker in key for marker in GENERATION_COMPONENT_MARKERS)
+        )
+        pscr = self._pscr_cents_for_rate()
+        pscr_applied = pscr if self._include_pscr() and pscr is not None else Decimal("0")
+        total = generation + pscr_applied
+        formula = (
+            f"(generation {self._fmt(generation)} + PSCR {self._fmt(pscr_applied)}) "
+            f"/ 100 = ${self._fmt_usd(total)}/kWh"
+        )
+
+        return {
+            "mode": "rider18_export",
+            "generation_cents_per_kwh": self._as_float(generation),
+            "pscr_cents_per_kwh": self._as_float(pscr),
+            "pscr_included": self._include_pscr() and pscr is not None,
+            "tax_rate_percent": self._as_float(self._tax_rate_percent()),
+            "tax_applied": False,
+            "total_cents_per_kwh": self._as_float(total),
+            "total_usd_per_kwh": self._as_float(total / Decimal("100")),
+            "formula": formula,
+        }
+
+    def _period_calculation(self, period: SeasonalPeriodRate) -> dict:
+        return self._import_rate_calculation(period)
+
+    @staticmethod
+    def _as_float(value: Decimal | None) -> float | None:
+        return float(value) if value is not None else None
+
+    @staticmethod
+    def _fmt(value: Decimal) -> str:
+        return f"{value:.4f}"
+
+    @staticmethod
+    def _fmt_usd(cents: Decimal) -> str:
+        return f"{(cents / Decimal('100')):.6f}"
+
     def _warning(self) -> str | None:
         selected = self._entry.data[CONF_SELECTED_RATE]
         if selected not in self.coordinator.data.rates:
@@ -212,6 +289,9 @@ def _base_attributes(self) -> dict:
                 ATTR_MONTHLY_COMPONENTS: {k: float(v) for k, v in period.components.monthly.items()},
             }
         )
+        calculation = self._period_calculation(period)
+        attrs[ATTR_CURRENT_RATE_CALCULATION] = calculation
+        attrs[ATTR_CURRENT_RATE_FORMULA] = calculation["formula"]
         return attrs
 
     def _period_value_usd(self, period: SeasonalPeriodRate | None) -> float | None:
@@ -348,6 +428,9 @@ def _period_value_usd(self, period: SeasonalPeriodRate | None) -> float | None:
             return None
         return float(self._export_rate_cents(period) / 100)
 
+    def _period_calculation(self, period: SeasonalPeriodRate) -> dict:
+        return self._export_rate_calculation(period)
+
 
 class DteCurrentRateNameSensor(_DteBaseRateSensor):
     _attr_native_unit_of_measurement = None

docs/research/issue-3-rate-modifiers.md

@@ -17,6 +17,8 @@ The issue asks for rate modifiers so Home Assistant can show a closer out-of-poc
 - Users can disable PSCR with an `include_pscr` setting. When disabled, Rider 18 export credits intentionally use generation-only formula components and should not report a missing-PSCR warning.
 - The default tax rate is `4.0%`. Michigan Treasury describes residential electricity as taxed at a 4% rate, and MPSC residential bill-charge guidance says utility companies collect 4% sales tax from residential customers.
 - The tax rate remains free-form as `tax_rate`, labeled as a percentage. Users can enter `0` to omit taxes from rate calculations.
+- Detroit residents may incur an additional `5.0%` City Utility Users' Tax. The UI note mentions this but does not change the default, because the integration does not currently know the service address.
+- Rate entities expose `current_rate_formula` and `current_rate_calculation` attributes so users can see the PSCR/tax inputs and exact math used for the active period.
 
 ## Calculation Scope
 
@@ -28,3 +30,4 @@ The issue asks for rate modifiers so Home Assistant can show a closer out-of-poc
 
 - Michigan Treasury sales and use tax page: https://www.michigan.gov/taxes/business-taxes/sales-use-tax
 - MPSC residential electric bill charges PDF: https://www.michigan.gov/-/media/Project/Websites/mpsc/consumer/info/tips/electric_residential_bill_charges_final.pdf?rev=e80ef0b163614800b1d8910b9e781775
+- City of Detroit September 2019 Revenue Estimating Conference Report: https://detroitmi.gov/sites/detroitmi.localhost/files/migrated_docs/financial-reports/Sept2019RevenueEstimatingConferenceReportFINAL.pdf

tests/test_config_flow.py

@@ -85,6 +85,7 @@ async def _refresh(self):
         == "Rider 18 export credits use parsed generation rates plus MPSC PSCR factors loaded for 2 tariffs."
     )
     assert "Set tax rate to 0" in result["description_placeholders"]["tax_note"]
+    assert "Detroit residents may incur an additional 5.0%" in result["description_placeholders"]["tax_note"]
 
 
 @pytest.mark.asyncio

tests/test_sensor.py

@@ -68,6 +68,20 @@ def test_import_sensor_returns_default_out_of_pocket_rate(monkeypatch):
     assert attrs["next_rate_change"] is None
     assert attrs["include_pscr"] is True
     assert attrs["tax_rate_percent"] == 4.0
+    assert attrs["current_rate_formula"] == "((base 6.0000 + PSCR 1.8770) * (1 + tax 4.0000%)) / 100 = $0.081921/kWh"
+    assert attrs["current_rate_calculation"] == {
+        "mode": "import",
+        "base_cents_per_kwh": 6.0,
+        "pscr_cents_per_kwh": 1.877,
+        "pscr_included": True,
+        "tax_rate_percent": 4.0,
+        "tax_applied": True,
+        "pre_tax_cents_per_kwh": 7.877,
+        "tax_cents_per_kwh": 0.31508,
+        "total_cents_per_kwh": 8.19208,
+        "total_usd_per_kwh": 0.0819208,
+        "formula": "((base 6.0000 + PSCR 1.8770) * (1 + tax 4.0000%)) / 100 = $0.081921/kWh",
+    }
 
 
 def test_import_sensor_can_omit_modifiers(monkeypatch):
@@ -105,6 +119,11 @@ def test_export_sensor_uses_rider18_formula_without_net_metering(monkeypatch):
     assert sensor.extra_state_attributes["rider18_export_available"] is True
     assert sensor.extra_state_attributes["pscr_cents"] == 1.877
     assert sensor.extra_state_attributes["pscr_rate_code"] == "D1.11"
+    assert (
+        sensor.extra_state_attributes["current_rate_formula"]
+        == "(generation 3.0000 + PSCR 1.8770) / 100 = $0.048770/kWh"
+    )
+    assert sensor.extra_state_attributes["current_rate_calculation"]["tax_applied"] is False
 
 
 def test_export_sensor_ignores_rider18_credit_with_net_metering(monkeypatch):
@@ -116,6 +135,8 @@ def test_export_sensor_ignores_rider18_credit_with_net_metering(monkeypatch):
     sensor = DteExportRateSensor(coordinator, entry)
     assert sensor.native_value == pytest.approx(0.0819208)
     assert sensor.extra_state_attributes["export_rate_source"] == "net_metering"
+    assert sensor.extra_state_attributes["current_rate_calculation"]["mode"] == "net_metering_export"
+    assert "net metering export" in sensor.extra_state_attributes["current_rate_formula"]
 
 
 def test_export_sensor_reports_formula_unavailable_without_pscr(monkeypatch):