warmcast 0.1.0__tar.gz

warmcast-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+# Private notes: never commit
+private/
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+CLAUDE.local.md

warmcast-0.1.0/.import_linter_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by Grimp.
+*

warmcast-0.1.0/.import_linter_cache/1611e1dbfe0bcbc648563772f7e81bb2fa792146.data.json

@@ -0,0 +1 @@
+{"imports_by_module":{"warmcast":[],"warmcast.core":[["warmcast.core.house",false,5,"from .house import ("],["warmcast.core.learning",false,22,"from .learning import ("],["warmcast.core.signals",false,59,"from .signals import ("],["warmcast.core.engine",false,4,"from .engine import Engine"],["warmcast.core.ports",false,56,"from .ports import HistorySource, ModelStore"],["warmcast.core.model",false,32,"from .model import ("],["warmcast.core.settings",false,58,"from .settings import LearnSettings"],["warmcast.core.scoring",false,57,"from .scoring import PvForecast, ZoneDayScore, nightly_cutoff, scorable_days, score_day"],["warmcast.core.backtest",false,3,"from .backtest import GATE2_DAYS, GATE2_MAE_C, NightlyFit, Scorecard, ZoneSummary, walk_forward"],["warmcast.core.sun",false,76,"from .sun import morning_weight, sun_position"]],"warmcast.core.backtest":[["datetime",false,8,"from datetime import date, timedelta"],["collections",false,6,"from collections.abc import Mapping"],["warmcast.core.settings",false,16,"from .settings import LearnSettings"],["time",false,5,"import time"],["warmcast.core.model",false,14,"from .model import ThermalModel, prior_model"],["warmcast.core.signals",false,17,"from .signals import History"],["warmcast.core.house",false,12,"from .house import House, ZoneId"],["numpy",false,10,"import numpy as np"],["dataclasses",false,7,"from dataclasses import dataclass"],["warmcast.core.learning",false,13,"from .learning import Accepted, FitOutcome, learn"],["warmcast.core.scoring",false,15,"from .scoring import ZoneDayScore, nightly_cutoff, scorable_days, score_day"],["__future__",false,3,"from __future__ import annotations"]],"warmcast.core.engine":[["warmcast.core.model",false,12,"from .model import Drivers, ThermalModel, Trajectory, ZoneState, estimate_state, prior_model"],["warmcast.core.backtest",false,9,"from .backtest import Scorecard, walk_forward"],["zoneinfo",false,7,"from zoneinfo import ZoneInfo"],["datetime",false,6,"from datetime import UTC, date, datetime, time, timedelta"],["warmcast.core.scoring",false,15,"from .scoring import nightly_cutoff"],["warmcast.core.signals",false,17,"from .signals import History, build_history, house_feeds"],["warmcast.core.ports",false,14,"from .ports import HistorySource, ModelStore"],["warmcast.core.settings",false,16,"from .settings import LearnSettings"],["warmcast.core.learning",false,11,"from .learning import Accepted, FitOutcome, KeptPrevious, estimate_dhw_baseline, learn"],["collections",false,5,"from collections.abc import Mapping"],["warmcast.core.house",false,10,"from .house import House, ZoneId"],["warmcast.core.model",false,13,"from .model import simulate as simulate_model"],["__future__",false,3,"from __future__ import annotations"]],"warmcast.core.house":[["dataclasses",false,4,"from dataclasses import dataclass"],["zoneinfo",false,8,"from zoneinfo import ZoneInfo, ZoneInfoNotFoundError"],["collections",false,3,"from collections.abc import Mapping"],["datetime",false,5,"from datetime import UTC, date, datetime, time"],["enum",false,6,"from enum import Enum"],["typing",false,7,"from typing import Any, NewType"],["__future__",false,1,"from __future__ import annotations"]],"warmcast.core.learning":[["enum",false,9,"from enum import Enum"],["scipy",false,12,"import scipy.optimize"],["warmcast.core.scoring",false,29,"from .scoring import nightly_cutoff, scorable_days, score_day"],["warmcast.core.signals",false,31,"from .signals import Array, HeatSource, History, Segment"],["dataclasses",false,7,"from dataclasses import dataclass, fields, replace"],["warmcast.core.settings",false,30,"from .settings import LearnSettings"],["numpy",false,11,"import numpy as np"],["__future__",false,3,"from __future__ import annotations"],["warmcast.core.model",false,15,"from .model import ("],["warmcast.core.house",false,14,"from .house import House, ZoneId"],["datetime",false,8,"from datetime import date, datetime, timedelta"],["math",false,5,"import math"],["collections",false,6,"from collections.abc import Mapping, Sequence"]],"warmcast.core.model":[["warmcast.core.signals",false,30,"from .signals import Array, Segment"],["warmcast.core.sun",false,31,"from .sun import morning_weight"],["__future__",false,7,"from __future__ import annotations"],["functools",false,14,"from functools import cached_property"],["numpy",false,16,"import numpy as np"],["warmcast.core.house",false,19,"from .house import ("],["json",false,10,"import json"],["scipy",false,17,"import scipy.linalg"],["collections",false,11,"from collections.abc import Mapping"],["hashlib",false,9,"import hashlib"],["dataclasses",false,12,"from dataclasses import asdict, dataclass, field, fields"],["datetime",false,13,"from datetime import datetime, timedelta"]],"warmcast.core.ports":[["__future__",false,1,"from __future__ import annotations"],["typing",false,5,"from typing import Protocol"],["warmcast.core.signals",false,7,"from .signals import Feed, RawSeries"],["datetime",false,4,"from datetime import datetime"],["collections",false,3,"from collections.abc import Mapping"]],"warmcast.core.scoring":[["warmcast.core.signals",false,15,"from .signals import Array, History, Segment"],["warmcast.core.settings",false,14,"from .settings import LearnSettings"],["dataclasses",false,6,"from dataclasses import dataclass, replace"],["collections",false,5,"from collections.abc import Iterator, Mapping"],["warmcast.core.model",false,13,"from .model import ThermalModel, drivers_from_segment, estimate_state, simulate"],["warmcast.core.house",false,12,"from .house import House, ZoneId"],["__future__",false,3,"from __future__ import annotations"],["numpy",false,10,"import numpy as np"],["zoneinfo",false,8,"from zoneinfo import ZoneInfo"],["datetime",false,7,"from datetime import UTC, date, datetime, time, timedelta"]],"warmcast.core.settings":[["__future__",false,1,"from __future__ import annotations"],["datetime",false,5,"from datetime import time"],["dataclasses",false,4,"from dataclasses import asdict, dataclass"],["json",false,3,"import json"]],"warmcast.core.signals":[["__future__",false,1,"from __future__ import annotations"],["enum",false,8,"from enum import Enum"],["itertools",false,3,"import itertools"],["warmcast.core.house",false,13,"from .house import House, ZoneId"],["numpy",false,10,"import numpy as np"],["math",false,4,"import math"],["datetime",false,7,"from datetime import UTC, datetime, timedelta"],["numpy",false,11,"from numpy.typing import NDArray"],["collections",false,5,"from collections.abc import Iterable, Iterator, Mapping"],["dataclasses",false,6,"from dataclasses import dataclass"]],"warmcast.core.sun":[["warmcast.core.signals",false,14,"from .signals import Array"],["numpy",false,11,"import numpy as np"],["warmcast.core.house",false,13,"from .house import House"],["__future__",false,7,"from __future__ import annotations"],["datetime",false,9,"from datetime import datetime, timedelta"]],"warmcast.ha_connector":[],"warmcast.ha_connector.app":[["collections",false,17,"from collections.abc import Callable, Mapping"],["warmcast.ha_connector.binding",false,27,"from .binding import Binding, BindingError, load_binding"],["tomllib",false,16,"import tomllib"],["pathlib",false,20,"from pathlib import Path"],["sys",false,13,"import sys"],["zoneinfo",false,22,"from zoneinfo import ZoneInfo"],["json",false,10,"import json"],["warmcast.ha_connector.reading_log",false,30,"from .reading_log import ReadingLog, ReadingLogError"],["logging",false,11,"import logging"],["warmcast.core",false,24,"from warmcast.core import House, HouseConfigError, LearnSettings, parse_house"],["warmcast.ha_connector.sampler",false,31,"from .sampler import Sampler"],["os",false,12,"import os"],["time",false,15,"import time"],["warmcast.web",false,25,"from warmcast.web import Dashboard, describe_columns, make_server, serve_in_background"],["warmcast.ha_connector.client",false,28,"from .client import HomeAssistantError, SupervisorClient"],["__future__",false,8,"from __future__ import annotations"],["typing",false,21,"from typing import Any"],["threading",false,14,"import threading"],["dataclasses",false,18,"from dataclasses import dataclass"],["datetime",false,19,"from datetime import UTC, date, datetime, timedelta"],["warmcast.ha_connector.nightly",false,29,"from .nightly import READING_LOG, refit_and_record"]],"warmcast.ha_connector.binding":[["re",false,27,"import re"],["datetime",false,31,"from datetime import timedelta"],["warmcast.offline.signal_map",false,36,"from warmcast.offline.signal_map import LoggerMap, SignalMapError, load_signal_map"],["pathlib",false,32,"from pathlib import Path"],["dataclasses",false,30,"from dataclasses import dataclass"],["__future__",false,25,"from __future__ import annotations"],["tomllib",false,28,"import tomllib"],["collections",false,29,"from collections.abc import Mapping"],["warmcast.core",false,35,"from warmcast.core import House, Signal, house_feeds"],["typing",false,33,"from typing import Any"]],"warmcast.ha_connector.client":[["os",false,10,"import os"],["datetime",false,16,"from datetime import datetime"],["typing",false,17,"from typing import Any, Protocol"],["json",false,9,"import json"],["collections",false,14,"from collections.abc import Mapping, Sequence"],["dataclasses",false,15,"from dataclasses import dataclass"],["urllib",false,11,"import urllib.error"],["__future__",false,7,"from __future__ import annotations"],["urllib",false,12,"import urllib.parse"],["urllib",false,13,"import urllib.request"]],"warmcast.ha_connector.nightly":[["__future__",false,7,"from __future__ import annotations"],["warmcast.ha_connector.binding",false,17,"from .binding import Binding"],["warmcast.storage",false,15,"from warmcast.storage import JsonModelStore, RefitRecord, RefitResult, save_refit"],["pathlib",false,11,"from pathlib import Path"],["warmcast.offline.csv_sources",false,14,"from warmcast.offline.csv_sources import LoggerCsv"],["datetime",false,10,"from datetime import datetime"],["logging",false,9,"import logging"],["warmcast.core",false,13,"from warmcast.core import Accepted, Engine, FitOutcome, House, KeptPrevious, LearnSettings"]],"warmcast.ha_connector.reading_log":[["io",false,10,"import io"],["collections",false,12,"from collections.abc import Sequence"],["csv",false,9,"import csv"],["__future__",false,7,"from __future__ import annotations"],["os",false,11,"import os"],["pathlib",false,13,"from pathlib import Path"]],"warmcast.ha_connector.sampler":[["datetime",false,4,"from datetime import UTC, datetime"],["__future__",false,1,"from __future__ import annotations"],["warmcast.ha_connector.reading_log",false,9,"from .reading_log import ReadingLog"],["warmcast.ha_connector.binding",false,7,"from .binding import Binding, EntityRef"],["typing",false,5,"from typing import Any"],["logging",false,3,"import logging"],["warmcast.ha_connector.client",false,8,"from .client import EntityState, HomeAssistantError, HomeAssistantReader"]],"warmcast.offline":[],"warmcast.offline.cli":[["__future__",false,1,"from __future__ import annotations"],["collections",false,6,"from collections.abc import Mapping"],["warmcast.core",false,12,"from warmcast.core import ("],["warmcast.offline.csv_sources",false,43,"from .csv_sources import LoggerCsv, StatisticsCsv"],["argparse",false,3,"import argparse"],["sys",false,4,"import sys"],["numpy",false,10,"import numpy as np"],["datetime",false,7,"from datetime import UTC, date, datetime, timedelta"],["pathlib",false,8,"from pathlib import Path"],["tomllib",false,5,"import tomllib"],["warmcast.storage",false,41,"from warmcast.storage import JsonModelStore"],["warmcast.offline.signal_map",false,44,"from .signal_map import SignalMap, SignalMapError, load_signal_map"]],"warmcast.offline.csv_sources":[["datetime",false,7,"from datetime import UTC, datetime"],["__future__",false,1,"from __future__ import annotations"],["itertools",false,4,"import itertools"],["warmcast.core",false,10,"from warmcast.core import Aggregation, Feed, HourlyStats, RawSeries, RawValue, Samples, Signal"],["dataclasses",false,6,"from dataclasses import dataclass"],["warmcast.offline.signal_map",false,12,"from .signal_map import LoggerMap, StatisticsMap"],["csv",false,3,"import csv"],["pathlib",false,8,"from pathlib import Path"],["collections",false,5,"from collections.abc import Mapping"]],"warmcast.offline.signal_map":[["typing",false,8,"from typing import Any"],["pathlib",false,7,"from pathlib import Path"],["datetime",false,6,"from datetime import timedelta"],["dataclasses",false,5,"from dataclasses import dataclass"],["warmcast.core",false,10,"from warmcast.core import Aggregation, Feed, Signal, ZoneId"],["tomllib",false,3,"import tomllib"],["collections",false,4,"from collections.abc import Mapping"],["__future__",false,1,"from __future__ import annotations"]],"warmcast.storage":[["warmcast.storage.refit_record",false,4,"from .refit_record import RefitRecord, RefitResult, load_refit, save_refit"],["warmcast.storage.json_store",false,3,"from .json_store import JsonModelStore"]],"warmcast.storage.json_store":[["warmcast.core",false,10,"from warmcast.core import ("],["datetime",false,6,"from datetime import datetime"],["dataclasses",false,5,"from dataclasses import asdict, fields"],["typing",false,8,"from typing import Any"],["json",false,3,"import json"],["__future__",false,1,"from __future__ import annotations"],["pathlib",false,7,"from pathlib import Path"],["os",false,4,"import os"]],"warmcast.storage.refit_record":[["enum",false,9,"from enum import Enum"],["__future__",false,3,"from __future__ import annotations"],["dataclasses",false,7,"from dataclasses import dataclass"],["json",false,5,"import json"],["os",false,6,"import os"],["pathlib",false,10,"from pathlib import Path"],["datetime",false,8,"from datetime import datetime"]],"warmcast.web":[["warmcast.web.server",false,7,"from .server import make_server, serve_in_background"],["warmcast.web.dashboard",false,6,"from .dashboard import Column, Dashboard, describe_columns"]],"warmcast.web.dashboard":[["warmcast.web.log_view",false,20,"from .log_view import Row, rows_since, summarise"],["warmcast.core",false,16,"from warmcast.core import House, LearnSettings, Signal"],["datetime",false,11,"from datetime import datetime, timedelta"],["warmcast.offline.signal_map",false,17,"from warmcast.offline.signal_map import LoggerMap"],["enum",false,12,"from enum import Enum"],["dataclasses",false,10,"from dataclasses import dataclass"],["warmcast.storage",false,18,"from warmcast.storage import load_refit"],["__future__",false,7,"from __future__ import annotations"],["typing",false,14,"from typing import Any"],["collections",false,9,"from collections.abc import Mapping"],["pathlib",false,13,"from pathlib import Path"]],"warmcast.web.log_view":[["datetime",false,11,"from datetime import datetime"],["pathlib",false,12,"from pathlib import Path"],["dataclasses",false,10,"from dataclasses import dataclass"],["__future__",false,7,"from __future__ import annotations"],["csv",false,9,"import csv"]],"warmcast.web.server":[["logging",false,11,"import logging"],["pathlib",false,17,"from pathlib import Path"],["__future__",false,8,"from __future__ import annotations"],["collections",false,14,"from collections.abc import Callable, Mapping"],["warmcast.web.dashboard",false,21,"from .dashboard import Dashboard, readings, settings, status"],["datetime",false,15,"from datetime import UTC, datetime"],["threading",false,13,"import threading"],["mimetypes",false,12,"import mimetypes"],["http",false,16,"from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer"],["typing",false,18,"from typing import Any"],["json",false,10,"import json"],["urllib",false,19,"from urllib.parse import urlsplit"]]},"version":2}

warmcast-0.1.0/.import_linter_cache/CACHEDIR.TAG

@@ -0,0 +1,3 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag automatically created by Grimp.
+# For information about cache directory tags see https://bford.info/cachedir/

warmcast-0.1.0/.import_linter_cache/warmcast.meta.json

@@ -0,0 +1 @@
+{"warmcast": 1794141363.474377, "warmcast.core.learning": 1794177935.2527387, "warmcast.ha_connector": 1794179163.667668, "warmcast.ha_connector.binding": 1794179163.675702, "warmcast.storage": 1794180419.8382998, "warmcast.core.house": 1794177935.2470284, "warmcast.web.log_view": 1794180419.853937, "warmcast.core.backtest": 1794157114.0756273, "warmcast.web": 1794180419.8452218, "warmcast.core.model": 1794177935.2583046, "warmcast.ha_connector.app": 1794181470.0350342, "warmcast.offline.csv_sources": 1794141363.4755564, "warmcast.core.sun": 1794177935.2667928, "warmcast.offline": 1794141363.4752448, "warmcast.ha_connector.reading_log": 1794179163.6881475, "warmcast.core.scoring": 1794177935.2623255, "warmcast.core.ports": 1794141363.474938, "warmcast.core.engine": 1794177935.242703, "warmcast.ha_connector.sampler": 1794179163.6915927, "warmcast.ha_connector.nightly": 1794180419.834461, "warmcast.offline.cli": 1794177935.2715244, "warmcast.storage.json_store": 1794177935.2759578, "warmcast.ha_connector.client": 1794181424.225544, "warmcast.web.dashboard": 1794181424.2261527, "warmcast.core.settings": 1794157114.093296, "warmcast.offline.signal_map": 1794141363.4756885, "warmcast.core": 1794177935.2376137, "warmcast.core.signals": 1794157114.097916, "warmcast.storage.refit_record": 1794180419.8417583, "warmcast.web.server": 1794181424.2267637}

warmcast-0.1.0/AGENTS.md

@@ -0,0 +1,48 @@
+# Warmcast: project guide for Codex
+
+Warmcast is an open-source Home Assistant **app (add-on)** that learns how a home gains and loses heat and plans heat pump heating ahead in 30-minute slots. It stores heat in the building fabric (walls and floor slabs) and the hot water tank when energy is cheapest or most efficient, keeps every room in its comfort band, and reduces heating from the solar forecast so sunny days don't overheat the house.
+
+The full spec is in [docs/spec.md](docs/spec.md). The roadmap is in [docs/roadmap.md](docs/roadmap.md). Decisions made so far, with the reasons, are in [docs/decisions.md](docs/decisions.md). Read those before proposing design changes.
+
+Maintainer-only notes live in `CLAUDE.local.md` and `private/`, both gitignored. Read them when present.
+
+## Current status (8 Nov 2026)
+
+- **Phase 1: collecting heating-on data** on the reference install. No Warmcast code exists yet.
+- The working prototype is a set of Home Assistant helpers and automations on the reference install.
+- **`docs/spec.md` is the source of truth** for the spec.
+
+## Hard rules
+
+1. **The core engine has no Home Assistant imports.** Everything platform-specific sits behind adapter interfaces (sensor reads, control writes, tariff, solar forecast, history, publishing/UI). This keeps the engine reusable.
+2. **Comfort first, then savings.** Every control write is bounded: zone caps inside the comfort band, flow offset inside the user's range, tank setpoints inside the tank limits.
+3. **Warmcast is never the only safety net.** The user's own thermostats and automations must keep the house warm if Warmcast stops.
+4. **Learn, don't assume.** A heat pump's flow temperature comes from its weather curve and is not an input; only boiler users enter a flow temperature. Heat loss, fabric capacity, solar gain and COP are learned from real data.
+5. **Predbat is optional and never required.** The fallbacks are Forecast.Solar, Solcast or Open-Meteo Solar for the solar forecast, and Octopus Energy or EDF Energy integrations (or a tariff select or fixed rates) for the tariff.
+6. **Start in shadow mode.** It plans but doesn't act until the user switches to Advisory or Control.
+7. **Public files carry no personal details.** No owner names, addresses or hostnames in docs, code, commits or PRs. Describe the reference install generically.
+8. **Public contributions carry no personal name or email and no Codex attribution.** Commits use the project git identity, and Co-Authored-By and "Generated with Codex" lines stay out of public commits and PRs.
+
+## Writing style
+
+- UK English, plain words. Explain every setting and plan decision the way the app itself will.
+
+## Code
+
+- **Language: Python**, matching Predbat and AppDaemon and common across Home Assistant projects.
+
+| Part | Contents | Depends on HA? |
+| --- | --- | --- |
+| `core/` | Data model, thermal model, learning, planner, optimiser | No |
+| `ha_connector/` | Feeds, device templates, controls, published sensors | Yes |
+| `web/` | App dashboard: Overview, Plan, Charts, Settings, User guide (served through HA ingress) | Served by the app |
+| `templates/` | Device templates (Daikin Altherma, Heatmiser Neo, Ring, Forecast.Solar, Solcast, Open-Meteo Solar, Octopus, EDF, Predbat), each with test fixtures | Data only |
+| `addon/` | HA app packaging: Dockerfile, `config.yaml`, repository metadata | Yes |
+
+Open choices are listed at the end of the spec (web UI framework, charting library, licence). Ask the maintainer before settling any of them.
+
+## Folder map
+
+- `docs/`: public spec, roadmap and decision log
+- `notes/`: working notes that are safe to make public
+- `private/`: gitignored; internal notes, the reference install details and exported data

warmcast-0.1.0/CLAUDE.md

@@ -0,0 +1,49 @@
+# Warmcast: project guide for Claude
+
+Warmcast is an open-source Home Assistant **app (add-on)** that learns how a home gains and loses heat and plans heat pump heating ahead in 30-minute slots. It stores heat in the building fabric (walls and floor slabs) and the hot water tank when energy is cheapest or most efficient, keeps every room in its comfort band, and reduces heating from the solar forecast so sunny days don't overheat the house.
+
+The full spec is in [docs/spec.md](docs/spec.md). The roadmap is in [docs/roadmap.md](docs/roadmap.md). Decisions made so far, with the reasons, are in [docs/decisions.md](docs/decisions.md). Read those before proposing design changes.
+
+Maintainer-only notes live in `CLAUDE.local.md` and `private/`, both gitignored. Read them when present.
+
+## Current status (8 Nov 2026)
+
+- **Phase 2: fitting the thermal model.** The core engine is built in `src/warmcast/core` (data loading, thermal model, learning, scoring, backtest), with the offline `warmcast-lab` command. Design and implementation notes: [docs/design/core-engine.md](docs/design/core-engine.md).
+- Gate 1 still needs cold days; Gate 2 (peaks within about 0.5 °C for a week) is not met yet.
+- **`docs/spec.md` is the source of truth** for the spec.
+- Run checks with `ruff check`, `ruff format --check`, `lint-imports` and `pytest` (with `PYTHONPATH=src`).
+
+## Hard rules
+
+1. **The core engine has no Home Assistant imports.** Everything platform-specific sits behind adapter interfaces (sensor reads, control writes, tariff, solar forecast, history, publishing/UI). This keeps the engine reusable.
+2. **Comfort first, then savings.** Every control write is bounded: zone caps inside the comfort band, flow offset inside the user's range, tank setpoints inside the tank limits.
+3. **Warmcast is never the only safety net.** The user's own thermostats and automations must keep the house warm if Warmcast stops.
+4. **Learn, don't assume.** A heat pump's flow temperature comes from its weather curve and is not an input; only boiler users enter a flow temperature. Heat loss, fabric capacity, solar gain and COP are learned from real data.
+5. **Predbat is optional and never required.** The fallbacks are Forecast.Solar, Solcast or Open-Meteo Solar for the solar forecast, and Octopus Energy or EDF Energy integrations (or a tariff select or fixed rates) for the tariff.
+6. **Start in shadow mode.** It plans but doesn't act until the user switches to Advisory or Control.
+7. **Public files carry no personal details.** No owner names, addresses or hostnames in docs, code, commits or PRs. Describe the reference install generically.
+8. **Public contributions carry no personal name or email and no Claude attribution.** Commits use the project git identity, and Co-Authored-By and "Generated with Claude" lines stay out of public commits and PRs.
+
+## Writing style
+
+- UK English, plain words. Explain every setting and plan decision the way the app itself will.
+
+## Code
+
+- **Language: Python**, matching Predbat and AppDaemon and common across Home Assistant projects.
+
+| Part | Contents | Depends on HA? |
+| --- | --- | --- |
+| `core/` | Data model, thermal model, learning, planner, optimiser | No |
+| `ha_connector/` | Feeds, device templates, controls, published sensors | Yes |
+| `web/` | App dashboard: Overview, Plan, Charts, Settings, User guide (served through HA ingress) | Served by the app |
+| `templates/` | Device templates (Daikin Altherma, Heatmiser Neo, Ring, Forecast.Solar, Solcast, Open-Meteo Solar, Octopus, EDF, Predbat), each with test fixtures | Data only |
+| `addon/` | HA app packaging: Dockerfile, `config.yaml`, repository metadata | Yes |
+
+Open choices are listed at the end of the spec (web UI framework, charting library, licence). Ask the maintainer before settling any of them.
+
+## Folder map
+
+- `docs/`: public spec, roadmap and decision log
+- `notes/`: working notes that are safe to make public
+- `private/`: gitignored; internal notes, the reference install details and exported data

warmcast-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: warmcast
+Version: 0.1.0
+Summary: Learns how a home gains and loses heat and plans heat pump heating ahead.
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.13
+Provides-Extra: dev
+Requires-Dist: import-linter>=2.0; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'

warmcast-0.1.0/README.md

@@ -0,0 +1,8 @@
+# Warmcast
+
+*Work in progress, not ready to install.*
+
+Warmcast is an open-source Home Assistant app that learns how your home gains and loses heat, and plans your heat pump's heating ahead. It stores heat in the building fabric (walls and floor slabs) and the hot water tank when energy is cheapest or most efficient, keeps every room comfortable, and uses the solar forecast so sunny days need less heating.
+
+- [Spec](docs/spec.md)
+- [Roadmap](docs/roadmap.md)

warmcast-0.1.0/addon/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+
+# The app is installed from the tagged release that matches config.yaml's version.
+ARG WARMCAST_SOURCE=https://github.com/nighthawk944/warmcast/archive/refs/tags/v0.1.0.tar.gz
+RUN pip install --no-cache-dir "${WARMCAST_SOURCE}"
+
+CMD ["warmcast-app"]

warmcast-0.1.0/addon/README.md

@@ -0,0 +1,61 @@
+# Warmcast app
+
+Warmcast learns how your home gains and loses heat, so it can later plan your heat pump's heating ahead.
+
+## What this version does
+
+- Every minute (you can change this), it reads the sensors you list and adds one row to its own reading log, `/data/readings.csv`. A sensor that is unavailable leaves its cell empty, never zero.
+- Each night at 22:00 it tries to learn a model of your house from that log and writes the result to the app log and to the dashboard. With only a few days of readings it says it does not have enough data yet, and why.
+
+This version only reads from Home Assistant. It publishes no sensors, changes no settings and makes no plans. Your thermostats and automations run your heating exactly as before.
+
+## The dashboard
+
+Open Warmcast from the Home Assistant sidebar. It has five tabs:
+
+- **Overview** shows whether the reading log is being written, how many readings it holds, the last reading, what the last nightly refit said, and whether each sensor had a reading at the last sample.
+- **Plan** is empty for now. The 24-hour plan arrives after Gate 2. Warmcast stays in shadow mode until you change it: it works out what it would do but does not act on it.
+- **Charts** draws the last 24 hours of room, outdoor and heat-output readings from the log.
+- **Settings** shows your house settings, with a plain explanation under each one. To change a setting, edit `house.toml` and restart the app.
+- **User guide** explains what Warmcast does, what shadow mode means, and what Gate 1 and Gate 2 are.
+
+The dashboard only reads the app's own files. It shows no forecasts yet, because there is no tested model to make them. The charts use a copy of Chart.js that comes with the app, so they need no internet access.
+
+## Setting it up
+
+Put two files in this app's config folder (`/addon_configs/<id>_warmcast/` on your Home Assistant host):
+
+- `house.toml` lists your rooms, their heating type and comfort range. See `examples/` in the repository.
+- `signals.toml` says which entity feeds each reading:
+
+```toml
+[logger]
+time_column = "time"
+hold_minutes = 2
+
+[logger.signals]
+outdoor_c = "outdoor_c"
+heat_kw = "heat_kw"
+
+[logger.zones.living_room]
+air_c = "living_air_c"
+
+[logger.entities]
+outdoor_c = "sensor.outdoor_temperature"
+heat_kw = "sensor.heat_pump_heat_output"
+living_air_c = { entity = "climate.living_room", attribute = "current_temperature" }
+```
+
+`[logger.signals]` and `[logger.zones.<zone>]` name a log column for each reading Warmcast understands. `[logger.entities]` names the entity behind each column, in the order the columns are written. `hold_minutes` must be longer than the sample interval. The same file lets `warmcast-lab` read the log on a computer.
+
+If a reading your house settings need has no entity, the app stops at start-up and says which one is missing.
+
+## Options
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `house_file` | `/config/house.toml` | Your house settings |
+| `binding_file` | `/config/signals.toml` | Which entity feeds each reading |
+| `sample_interval_seconds` | `60` | How often the sensors are read |
+| `data_path` | `/data` | Where the reading log and the learned models are kept |
+| `timezone` | `Europe/London` | Your time zone, for the nightly run |

warmcast-0.1.0/addon/config.yaml

@@ -0,0 +1,30 @@
+name: Warmcast
+version: "0.1.0"
+slug: warmcast
+description: >-
+  Learns how your home gains and loses heat. This version only reads your sensors and
+  keeps its own log; it changes nothing in Home Assistant.
+arch:
+  - aarch64
+  - amd64
+startup: application
+boot: auto
+# Lets the app read entity states through the Supervisor with its own token.
+homeassistant_api: true
+# The read-only dashboard, served by the app on this port. The port number is provisional.
+ingress: true
+ingress_port: 8099
+panel_icon: mdi:home-thermometer
+# The house settings and entity binding live in this app's own config folder.
+map:
+  - addon_config
+options:
+  house_file: /config/house.toml
+  binding_file: /config/signals.toml
+  sample_interval_seconds: 60
+  data_path: /data
+schema:
+  house_file: str
+  binding_file: str
+  sample_interval_seconds: int(10,3600)
+  data_path: str

warmcast-0.1.0/docs/decisions.md

@@ -0,0 +1,28 @@
+# Decision log
+
+The decisions made while writing the spec (Oct–Nov 2026), newest first. Each one shows what was decided and why.
+
+| Date | Decision | Why |
+| --- | --- | --- |
+| 8 Nov 2026 | **Dashboard: plain web pages with Chart.js.** No build step, light enough for a Raspberry Pi. | Covers the five tabs and charts without the upkeep of a full framework. |
+| 8 Nov 2026 | **Platforms: 64-bit ARM and x86 supported; 32-bit ARM not.** scipy and numpy ship no 32-bit ARM builds. | Home Assistant no longer supports 32-bit ARM, so the app doesn't either. Supporting it would mean removing scipy from the fitting code. |
+| 8 Nov 2026 | **Language: Python.** | Matches Predbat and AppDaemon, and is common across open-source Home Assistant projects. |
+| 8 Nov 2026 | **Name: Warmcast**, replacing the working name HeatBank. Domain .app or .ai to be chosen; .com may follow later. | Short, says what it does (warmth from forecasts), and the .com is not held by a live product. |
+| 8 Nov 2026 | **Building fabric means walls and floor slabs.** The thermal model treats both as stored heat, not just the underfloor slab. | Walls hold a lot of heat in every home, including those with radiators. |
+| 8 Nov 2026 | **The reference install is described generically** in public docs: no owner name and no "my house". | Other people will use the docs as a guide to their own install. |
+| 1 Nov 2026 | **Cold-weather preheat:** when the forecast shows a colder than normal spell or a threshold crossing (e.g. below 5°C, below 0°C, frost), raise the flow offset overnight to store heat in the fabric. Cut the preheat back by the expected solar gain. | Cheap overnight heat beats peak-rate heat and running the heat pump hardest in the coldest hours. Sunny cold days must not end up overheated. |
+| 26 Oct 2026 | **The flow offset is a planned lever.** Cost mode raises it in free, low-rate and solar-divert slots. COP mode sets it back slightly overnight while people sleep. The user sets the baseline, range, sleep hours and night comfort band. | Weather-compensated heat pumps usually expose an offset, and it's the main way to move heat in time. |
+| 25 Oct 2026 | **Octopus and EDF free electricity sessions are in the launch release**, not a later phase. | Free sessions are the biggest single win for storing heat. |
+| 25 Oct 2026 | **EDF tariff source:** the unofficial [EDF Energy integration](https://github.com/stevekirtley/HomeAssistant-EDFEnergy) (HACS). It has rates but no free sessions, so EDF sessions need Warmcast's own connector or an upstream contribution. | It's the only EDF integration with rates; its README says free sessions were removed. |
+| 25 Oct 2026 | **Predbat is optional.** Fall back to Forecast.Solar, Solcast or Open-Meteo Solar for the solar forecast, Octopus/EDF or a tariff select for rates, and the inverter integration for PV and battery. | Most users won't have Predbat. |
+| 25 Oct 2026 | **Package as a Home Assistant app (add-on), like Predbat, not as a HACS integration.** At launch users add the repo URL to the app store; aim for a community listing later. | Logic runs locally on the user's hardware, with its own web UI. This replaced an earlier HACS plan. |
+| 25 Oct 2026 | **App dashboard with five tabs:** Overview, Plan, Charts, Settings, User guide. Charts includes a live schematic (like ESPAltherma's, but much nicer), plus temperatures, energy, COP and the heat loss curve. | One place to see whether it's working, what it plans and why. |
+| 25 Oct 2026 | **Don't assume a flow temperature.** Heat pumps follow their weather curve; boilers enter theirs. Learn the heat needed to reach target and the heat loss per hour at each outdoor temperature. | Assumptions break across installs; real data doesn't. |
+| 25 Oct 2026 | **Positioning:** Warmcast adjusts the heating it delivers using the solar forecast, rather than only preventing overheating. No comparison with Predbat in the copy. | Clearer, stands on its own. |
+| 24–25 Oct 2026 | **Door/window pause is set per zone:** Off, or pause after N minutes open (default 15). Shorter openings never pause. | Brief openings shouldn't stop heating. |
+| 24 Oct 2026 | **Two optimisation modes:** COP (least electricity) and Cost (least money), with the same comfort rules. Optional minimum COP in cost mode. | Different tariffs suit different goals. |
+| 24 Oct 2026 | **Hot water vs heating priority is the user's choice:** Hot water first, Heating first, or Balanced (default). Minimum tank and room temperatures always apply. Solar diversion goes to the tank first, and to the fabric only when zones are cooling and no big solar gain is due. | The heat pump can only heat one at a time. |
+| 24 Oct 2026 | **Plan table:** 30-minute slots, a 24-hour plan view and a 48-hour actuals view (toggle, never both at once). Every slot has a one-line reason. | Like Predbat's plan, built for heat. |
+| 24 Oct 2026 | **Rollout modes:** Shadow, then Advisory, then Control. Every install starts in Shadow. | Trust has to be earned on each house. |
+| 24 Oct 2026 | **Generic by design:** any `climate` thermostat, any number of zones, optional floor sensors, emitter type per zone (screed UFH, overlay UFH, radiators), optional door/window sensors, optional hot water tank. | Not tied to the reference install's kit. |
+| 24 Oct 2026 | **Working name: HeatBank** (heatbank.app free). Alternatives: Thermabank (thermabank.com free), Flowcast. Not final. | Avoid names too close to Predbat. |