Source code for energy_data_retrieval.foobot

"""Read published Foobot simulation outputs; never execute the JavaScript wrapper."""

from __future__ import annotations

import json
from dataclasses import dataclass
from urllib.request import urlopen

import numpy as np

SOURCE_URL = "https://techblog.foobot.io/assets/timestral-counterfactual/data.js"
ARTICLE_URL = "https://techblog.foobot.io/ai/hvac/control/tsfm-counterfactual-thermal-dynamics.html"


[docs] @dataclass(frozen=True) class ThermalPanel: """Published temperatures (degrees C) and minutes relative to baseline start. Dates are simulation dates, not observations. Time zone is not published; relative minutes deliberately avoid inventing UTC timestamps. """ date: str test: str offset: int threshold: float minutes: tuple[float, ...] truth: tuple[float, ...] median: tuple[float, ...] lo: tuple[float, ...] hi: tuple[float, ...] setpoint: tuple[float, ...] command: tuple[float, ...]
[docs] def parse_foobot(text: str) -> tuple[ThermalPanel, ...]: """Validate the fixed assignment wrapper and decode JSON without eval. Reject duplicate panels, incomplete schedules, nonfinite or unordered data, and inconsistent T2 issue times/setpoints. No missing trajectories are filled. """ prefix = "window.TIMESTRAL_EXPERIMENT = " if not text.startswith(prefix): raise ValueError("Unexpected Foobot data wrapper") try: records = json.loads(text[len(prefix) :].strip().removesuffix(";")) if not isinstance(records, list) or not records: raise ValueError("Expected nonempty morning records") panels = [] seen = set() for day in records: if day["date"] in seen: raise ValueError("Duplicate morning") seen.add(day["date"]) daily = [] for p in day["panels"]: panel = ThermalPanel( str(day["date"]), str(p["test"]), int(p["offset"]), float(day["threshold"]), *( tuple(float(v) for v in p[k]) for k in ("x", "truth", "median", "lo", "hi", "setpoint", "cmd") ), ) arrays = np.asarray( [ panel.minutes, panel.truth, panel.median, panel.lo, panel.hi, panel.setpoint, panel.command, ] ) if ( arrays.ndim != 2 or arrays.shape[1] < 2 or not np.isfinite(arrays).all() or not np.isfinite(panel.threshold) or not np.all(np.diff(arrays[0]) > 0) or not np.all(arrays[3] <= arrays[2]) or not np.all(arrays[2] <= arrays[4]) or not np.isin(arrays[6], [0, 1]).all() ): raise ValueError("Invalid thermal trajectory") if p["offset"] != panel.offset: raise ValueError("Offset must be an integer") daily.append(panel) expected = {("T1", 0), *(("T2", n) for n in (-60, -30, 0, 30, 60))} if len(daily) != 6 or {(p.test, p.offset) for p in daily} != expected: raise ValueError("Each morning requires T1 and five paired T2 schedules") t2 = [p for p in daily if p.test == "T2"] if any(p.minutes != t2[0].minutes or p.setpoint != t2[0].setpoint for p in t2): raise ValueError("T2 schedules need identical issue grid and setpoints") panels.extend(daily) return tuple(panels) except (KeyError, TypeError, OverflowError) as exc: raise ValueError("Malformed Foobot experiment") from exc
[docs] def fetch_foobot() -> str: """Fetch the public numerical asset with a timeout and 5 MB size bound. The returned source text is intended for local audit, not redistribution of the publisher's scripts or artwork. Public access does not imply a licence. """ with urlopen(SOURCE_URL, timeout=30) as response: payload = response.read(5_000_001) if len(payload) > 5_000_000: raise ValueError("Foobot asset exceeds size limit") text = payload.decode("utf-8") parse_foobot(text) return text