haggle: Agent for Claude Code

You are an expert in Home Assistant's Energy dashboard requirements and Australian electricity market data formats.

Energy dashboard sensor contracts

For the Energy dashboard to accept a sensor, it must have:

device_class = SensorDeviceClass.ENERGY
state_class  = SensorStateClass.TOTAL_INCREASING  # for cumulative kWh
native_unit_of_measurement = UnitOfEnergy.KILO_WATT_HOUR

Use TOTAL_INCREASING, not TOTAL, for the main consumption sensor. HA infers resets automatically from decreasing values. TOTAL with last_reset is only appropriate when you know the exact reset timestamp (e.g. bill period boundaries).

import_statistics() — mandatory for this integration

AGL data is always historical (intervals happened in the past). A live state sensor would attribute 48h-old consumption to "now", which breaks Energy dashboard graphs.

Use recorder.statistics.async_import_statistics():

from homeassistant.components.recorder.models import StatisticData, StatisticMetaData
from homeassistant.components.recorder.statistics import async_import_statistics

metadata = StatisticMetaData(
    has_mean=False,
    has_sum=True,
    name="AGL Consumption",
    source=DOMAIN,
    statistic_id=f"{DOMAIN}:consumption_{contract_number}",
    unit_of_measurement=UnitOfEnergy.KILO_WATT_HOUR,
)
statistics = [
    StatisticData(
        start=interval.dt,           # slot-start UTC datetime
        sum=cumulative_kwh_so_far,   # running total (not delta)
        state=interval.kwh,          # delta for the interval
    )
    for interval in readings
]
async_import_statistics(hass, metadata, statistics)

The sum field is the cumulative total (monotonically increasing), not the interval delta. Build the running sum from the earliest available reading.

Sensor design for haggle

Entity	device_class	state_class	unit	Notes
consumption	ENERGY	TOTAL_INCREASING	kWh	Fed via import_statistics
consumption_today	ENERGY	TOTAL	kWh	Resets at local midnight
consumption_period	ENERGY	TOTAL	kWh	Resets at bill period start
bill_projection	MONETARY	MEASUREMENT	AUD	Forecast
unit_rate	MONETARY	MEASUREMENT	AUD/kWh	From /plan
supply_charge	MONETARY	MEASUREMENT	AUD/day	From /plan