homeassistant — Agent Instructions

This tool is independent of mimirheim. It has its own pyproject.toml, its own virtual environment, and its own dependency set. It communicates with mimirheim exclusively via MQTT topics. There is no shared Python package, no shared virtual environment, and no shared imports between this tool and mimirheim.

Critical separation rule

Never add dependencies required by this tool to the mimirheim pyproject.toml. If this tool needs a library, add it here:

mimirheim_helpers/baseload/homeassistant/pyproject.toml

The mimirheim pyproject.toml at the repo root must not list httpx or any other dependency that belongs to this tool.

Environment setup

All commands must be run from this directory (mimirheim_helpers/baseload/homeassistant/), not from the repo root.

cd mimirheim_helpers/baseload/homeassistant

uv sync --group dev           # create .venv and install runtime + test dependencies
uv run pytest                 # run tests
uv run python -m baseload_ha --config config.yaml   # run the tool

Use uv sync without --group dev only when you want runtime dependencies without pytest. Running uv sync from the repo root creates the mimirheim venv, not this tool's venv.

Source of truth

Before writing any code, read:

• README.md in this directory — external behaviour, configuration schema, MQTT topics, output format, HA API prerequisites.
• IMPLEMENTATION_DETAILS.md in the repo root — the mimirheim architectural conventions this tool follows.

The wiki provides supplementary user-facing documentation for this tool:

• wiki/Helpers/Baseload-HA.md — setup guide, lookback/decay explanation, Long-Lived Access Token instructions.
• wiki/Developer/Helper-API.md — MQTT contract for all mimirheim input topics.

Code standards

Apply all mimirheim code standards from the root AGENTS.md to this tool without exception:

• All public functions and methods must have complete type annotations.
• All Pydantic models must set model_config = ConfigDict(extra="forbid").
• Never use a bare except: or except Exception: without logging with full traceback.
• Google-style docstrings on all public classes and functions.
• Module-level docstring on every module.
• No emoticons in code, comments, or documentation.

Project structure

mimirheim_helpers/baseload/homeassistant/
  pyproject.toml       # dependencies: httpx, paho-mqtt, pydantic, pyyaml
  README.md            # external specification (authoritative)
  AGENTS.md            # this file
  baseload_ha/
    __init__.py
    __main__.py        # entry point: config load, MQTT loop, signal handling
    config.py          # Pydantic config schema (BaseloadConfig, HaConfig, etc.)
    fetcher.py         # calls HA statistics API; returns list[HourlyReading]
    forecast.py        # computes same-hour average profile from historical readings
    publisher.py       # formats payload and publishes retained to output_topic
  tests/
    unit/
      test_config.py
      test_fetcher.py
      test_forecast.py
      test_publisher.py
    conftest.py

MQTT interface

The tool never imports from mimirheim/ and never calls build_and_solve().

HA API notes

The tool calls:

GET {ha_url}/api/recorder/statistics_during_period

with a Bearer token in the Authorization header. The response format changed in HA 2022.11; do not target earlier versions. Parse the response as a dict keyed by entity_id where each value is a list of {"start": ..., "mean": ...} objects.