hems 0.1.0__py3-none-any.whl

hems/__init__.py

@@ -0,0 +1,3 @@
+"""hems: an OUTUS v1 engine (Open Utility Tariff & Usage Specification). Plans, the usage
+ledger, prices, explainable bills and setup steps. Pure Python, no I/O."""
+__version__ = "0.1.0"

hems/billing.py

@@ -0,0 +1,400 @@
+"""Bills from an OUTUS plan and the ledger.
+
+Interval charges are priced per ledger interval at the rate in force at its start;
+period charges are worked out from the period's ledger. ``bill`` returns an OUTUS bill
+whose line items carry their inputs and formula. For an open period it is
+``provisional``: period charges are prorated to the elapsed days, and ``progress`` holds
+the projection to the period's end.
+"""
+from __future__ import annotations
+
+import datetime as dt
+from collections import defaultdict
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from . import periods
+from .prices import PriceBook
+from .windows import HolidayCheck, day_type, in_window
+
+#: Which ledger channel each tariff reads.
+CHANNEL = {"general": "general", "export": "general", "controlled_load": "controlled_load",
+           "ev": "ev", "rider": "general"}
+INTERVAL_BASES = {"per_unit", "series", "series_plus_adder", "value_table"}
+SUPPORTED_DEMAND = {"monthly_max", "top_n_avg", "daily_excess"}
+
+
+def plan_in_force(plans: list[dict], day: dt.date) -> dict | None:
+    """The plan whose dates cover ``day`` (blank end = still in force)."""
+    for p in plans:
+        start = p.get("effective_start")
+        end = p.get("effective_end")
+        if start and day < dt.date.fromisoformat(start):
+            continue
+        if end and day > dt.date.fromisoformat(end):
+            continue
+        return p
+    return None
+
+
+def _direction(tariff: dict, charge: dict) -> str:
+    return charge.get("direction") or ("export" if tariff.get("applies_to") == "export" else "import")
+
+
+def _sign(charge: dict) -> float:
+    return -1.0 if charge.get("effect") == "credit" else 1.0
+
+
+def rate_at(charge: dict, local: dt.datetime, is_holiday: HolidayCheck | None = None
+            ) -> tuple[float | None, str | None]:
+    """A static charge's (rate, band) at ``local``: its rate table's first matching
+    entry, else its flat ``rate``."""
+    for entry in charge.get("rates") or []:
+        if in_window(entry.get("window"), local, is_holiday):
+            return entry.get("rate"), entry.get("band")
+    if "rates" in charge and charge.get("rate") is None:
+        return None, None
+    return charge.get("rate"), None
+
+
+def _value_table(charge: dict, local: dt.datetime) -> float | None:
+    month = (charge.get("value_table") or {}).get(str(local.month)) or {}
+    row = month.get("weekend" if local.weekday() >= 5 else "weekday")
+    return row[local.hour] if row and len(row) == 24 else None
+
+
+def _interval_rate(tariff: dict, charge: dict, local: dt.datetime, ts: float,
+                   prices: PriceBook | None, is_holiday: HolidayCheck | None
+                   ) -> tuple[float | None, str | None, str]:
+    """(rate, band, price kind) for one interval charge."""
+    basis = charge["basis"]
+    if basis == "value_table":
+        return _value_table(charge, local), None, "static"
+    if basis in ("series", "series_plus_adder"):
+        p = prices.at(ts) if prices is not None else None
+        if p is None:
+            return None, None, "missing"
+        side = p.get("export") if _direction(tariff, charge) == "export" else p.get("import")
+        if side is None:
+            return None, None, "missing"
+        adder = 0.0
+        band = p.get("band")
+        if basis == "series_plus_adder":
+            a, band2 = rate_at(charge, local, is_holiday)
+            adder, band = (a or 0.0), (band2 or band)
+        return side + adder, band, p.get("kind", "actual")
+    rate, band = rate_at(charge, local, is_holiday)
+    return rate, band, "static"
+
+
+def _local(ts: float, tz: ZoneInfo) -> dt.datetime:
+    return dt.datetime.fromtimestamp(ts, tz)
+
+
+def _money(v: float) -> float:
+    return round(v + 0.0, 2)
+
+
+def _fmt(v: float, dp: int = 2) -> str:
+    return f"{v:,.{dp}f}"
+
+
+def _tariffs(plan: dict) -> list[dict]:
+    return [t for t in plan.get("tariffs") or [] if isinstance(t, dict)]
+
+
+def _qty(iv: dict, direction: str) -> float:
+    return float(iv.get("quantity_out" if direction == "export" else "quantity_in") or 0.0)
+
+
+def _interval_lines(plan: dict, ledger: dict[str, list[dict]], tz: ZoneInfo,
+                    prices: PriceBook | None, is_holiday: HolidayCheck | None) -> list[dict]:
+    lines = []
+    for t in _tariffs(plan):
+        chan = ledger.get(CHANNEL.get(t.get("applies_to"), "general")) or []
+        for c in t.get("charges") or []:
+            if c.get("class") != "interval" or c.get("basis") not in INTERVAL_BASES:
+                continue
+            d = _direction(t, c)
+            qty = amount = unpriced = 0.0
+            bands: dict[str, float] = defaultdict(float)
+            rates_seen, n, kinds = set(), 0, set()
+            for iv in chan:
+                q = _qty(iv, d)
+                if q <= 0:
+                    continue
+                local = _local(iv["start"], tz)
+                if not in_window(c.get("window"), local, is_holiday):
+                    continue
+                rate, band, kind = _interval_rate(t, c, local, iv["start"], prices, is_holiday)
+                if rate is None:
+                    unpriced += q
+                    continue
+                qty += q
+                amount += q * rate
+                n += 1
+                rates_seen.add(round(rate, 6))
+                kinds.add(kind)
+                if band:
+                    bands[band] += q
+            if qty <= 0 and unpriced <= 0:
+                continue
+            unit = c.get("unit") or "kWh"
+            one_rate = next(iter(rates_seen)) if len(rates_seen) == 1 else None
+            if one_rate is not None:
+                formula = f"{_fmt(qty, 3)} {unit} × ${one_rate}"
+            else:
+                what = "prices" if c["basis"] != "per_unit" else "TOU rates"
+                formula = f"{_fmt(qty, 3)} {unit} × {what} ({n:,} intervals)"
+            inputs: dict[str, Any] = {f"{b}_{unit}": round(v, 3) for b, v in bands.items()}
+            if unpriced:
+                inputs["unpriced_" + unit] = round(unpriced, 3)
+            if kinds - {"static"}:
+                inputs["price_kinds"] = sorted(kinds)
+            lines.append({"tariff_id": t.get("id"), "charge_id": c.get("id"),
+                          "label": c.get("label") or c.get("id"), "quantity": round(qty, 3),
+                          "unit": unit, **({"rate": one_rate} if one_rate is not None else {}),
+                          "amount": _money(_sign(c) * amount), "formula": formula,
+                          "inputs": inputs, "class": "interval"})
+    return lines
+
+
+def _demand(t: dict, c: dict, chan: list[dict], tz: ZoneInfo,
+            is_holiday: HolidayCheck | None) -> tuple[float, dict]:
+    spec = c.get("demand") or {}
+    step = int(spec.get("interval_min") or 30) * 60
+    buckets: dict[int, float] = defaultdict(float)
+    for iv in chan:
+        start = int(iv["start"]) // step * step
+        if in_window(c.get("window"), _local(start, tz), is_holiday):
+            buckets[start] += float(iv.get("quantity_in") or 0.0)
+    kw = {s: q * 3600.0 / step for s, q in buckets.items()}
+    if spec.get("unit") == "kVA" and spec.get("power_factor"):
+        kw = {s: v / float(spec["power_factor"]) for s, v in kw.items()}
+    method = spec.get("method") or "monthly_max"
+    inputs: dict[str, Any] = {"method": method}
+    if not kw:
+        return 0.0, inputs
+    if method == "top_n_avg":
+        n = int(spec.get("n") or 1)
+        ranked = sorted(kw.items(), key=lambda x: -x[1])
+        if spec.get("distinct_days"):
+            seen, picked = set(), []
+            for s, v in ranked:
+                day = _local(s, tz).date()
+                if day not in seen:
+                    seen.add(day)
+                    picked.append((s, v))
+            ranked = picked
+        top = ranked[:n]
+        value = sum(v for _, v in top) / len(top)
+        inputs["peaks"] = [{"at": _local(s, tz).isoformat(), "kw": round(v, 3)} for s, v in top]
+    elif method == "daily_excess":
+        by_day: dict[dt.date, float] = defaultdict(float)
+        for s, v in kw.items():
+            d = _local(s, tz).date()
+            by_day[d] = max(by_day[d], v)
+        thr = float(spec.get("threshold") or 0.0)
+        value = sum(max(0.0, v - thr) for v in by_day.values())
+        inputs["threshold"] = thr
+    else:
+        s, value = max(kw.items(), key=lambda x: x[1])
+        inputs["peak_at"] = _local(s, tz).isoformat()
+    value = max(value, float(spec.get("min") or 0.0))
+    inputs["peak"] = round(value, 3)
+    return value, inputs
+
+
+def _period_lines(plan: dict, ledger: dict[str, list[dict]], tz: ZoneInfo, start: dt.datetime,
+                  end: dt.datetime, used_days: float, period_days: float,
+                  is_holiday: HolidayCheck | None) -> tuple[list[dict], list[tuple[dict, dict]]]:
+    """Period charges, except those that need the subtotal (minimum bill, percent)."""
+    lines, deferred = [], []
+    cycle = (plan.get("billing") or {}).get("cycle", "monthly")
+    months = periods.MONTHS_PER_CYCLE.get(cycle, 1)
+    frac = used_days / period_days if period_days else 0.0
+    owners = [(None, c) for c in plan.get("charges") or []] + [
+        (t, c) for t in _tariffs(plan) for c in t.get("charges") or []]
+    for t, c in owners:
+        if c.get("class") != "period":
+            continue
+        basis, rate = c.get("basis"), float(c.get("rate") or 0.0)
+        tid = t.get("id") if t else None
+        base = {"tariff_id": tid, "charge_id": c.get("id"), "label": c.get("label") or c.get("id"),
+                "class": "period"}
+        chan = ledger.get(CHANNEL.get((t or {}).get("applies_to"), "general")) or []
+        if basis == "per_day":
+            lines.append({**base, "quantity": round(used_days, 3), "unit": "day", "rate": rate,
+                          "amount": _money(_sign(c) * rate * used_days),
+                          "formula": f"{_fmt(used_days, 0 if used_days == int(used_days) else 2)} days × ${rate}"})
+        elif basis == "per_month":
+            q = months * frac
+            lines.append({**base, "quantity": round(q, 4), "unit": "month", "rate": rate,
+                          "amount": _money(_sign(c) * rate * q), "formula": f"{_fmt(q, 2)} months × ${rate}"})
+        elif basis == "per_year":
+            q = used_days / 365.0
+            lines.append({**base, "quantity": round(q, 4), "unit": "year", "rate": rate,
+                          "amount": _money(_sign(c) * rate * q), "formula": f"{used_days:g}/365 years × ${rate}"})
+        elif basis == "demand":
+            spec = c.get("demand") or {}
+            method = spec.get("method") or "monthly_max"
+            if method not in SUPPORTED_DEMAND:
+                lines.append({**base, "amount": 0.0, "formula": f"{method}: not supported yet",
+                              "inputs": {"unsupported": method}})
+                continue
+            peak, inputs = _demand(t or {}, c, chan, tz, is_holiday)
+            per = spec.get("frequency", "per_month")
+            mult, how = (used_days, f" × {used_days:g} days") if per == "per_day" else (
+                months * frac, f" × {_fmt(months * frac, 2)} months" if months * frac != 1 else "")
+            unit = spec.get("unit", "kW")
+            at = inputs.get("peak_at")
+            when = f" ({_local_short(at)})" if at else ""
+            lines.append({**base, "quantity": round(peak, 3), "unit": unit, "rate": rate,
+                          "amount": _money(_sign(c) * peak * rate * mult),
+                          "formula": f"peak {_fmt(peak, 2)} {unit}{when} × ${rate}{how}", "inputs": inputs})
+        elif basis == "excess_over_free_band":
+            fb = c.get("free_band") or {}
+            free = float(fb.get("quantity") or 0.0)
+            d = _direction(t or {}, c)
+            by_day: dict[dt.date, float] = defaultdict(float)
+            for iv in chan:
+                local = _local(iv["start"], tz)
+                if in_window(c.get("window"), local, is_holiday):
+                    by_day[local.date()] += _qty(iv, d)
+            total = sum(by_day.values())
+            if fb.get("per") == "day":
+                excess = sum(max(0.0, v - free) for v in by_day.values())
+                today = max(by_day) if by_day else None
+                left = max(0.0, free - by_day[today]) if today else free
+                desc = f"{_fmt(free, 0)} kWh/day free"
+            else:
+                allow = free if fb.get("per") == "period" else free * used_days / 365.0
+                excess, left = max(0.0, total - allow), max(0.0, allow - total)
+                desc = f"{_fmt(allow, 1)} kWh free"
+            lines.append({**base, "quantity": round(excess, 3), "unit": c.get("unit") or "kWh",
+                          "rate": rate, "amount": _money(_sign(c) * excess * rate),
+                          "formula": f"{_fmt(excess, 3)} kWh above {desc} × ${rate}",
+                          "inputs": {"in_window": round(total, 3), "free_left": round(left, 3)}})
+        elif basis == "tier":
+            used = sum(_qty(iv, _direction(t or {}, c)) for iv in chan)
+            lines.append({**base, **_tier(c, used, start, used_days)})
+        elif basis in ("minimum_bill", "percent_of_bill"):
+            deferred.append((base, c))
+        # true_up is an annual settlement: informational, not a line in a period bill.
+    return lines, deferred
+
+
+def _local_short(iso: str) -> str:
+    d = dt.datetime.fromisoformat(iso)
+    return f"{d.day} {d:%b %H:%M}"
+
+
+def _tier(c: dict, used: float, start: dt.datetime, used_days: float) -> dict:
+    """Tiered quantity over the period. With a ``baseline`` the first tier's allowance is
+    the baseline kWh/day for the period's season × days."""
+    tiers = [x for x in c.get("tiers") or [] if isinstance(x, dict)]
+    allowance = None
+    for b in c.get("baseline") or []:
+        if not b.get("months") or start.month in b["months"]:
+            allowance = float(b["kwh_per_day"]) * used_days
+            break
+    amount, left, prev, parts = 0.0, used, 0.0, []
+    for i, tier in enumerate(tiers):
+        cap = allowance if (i == 0 and allowance is not None) else tier.get("up_to")
+        span = left if cap is None else max(0.0, min(left, float(cap) - prev))
+        if span > 0:
+            amount += span * float(tier["rate"])
+            parts.append(f"{_fmt(span, 1)} × ${tier['rate']}")
+        left -= span
+        if cap is not None:
+            prev = float(cap)
+    inputs = {"used": round(used, 3)}
+    if allowance is not None:
+        inputs["baseline_allowance"] = round(allowance, 3)
+    return {"quantity": round(used, 3), "unit": c.get("unit") or "kWh",
+            "amount": _money(_sign(c) * amount), "formula": " + ".join(parts) or "0",
+            "inputs": inputs}
+
+
+def bill(plan: dict, ledger: dict[str, list[dict]], start: dt.datetime, end: dt.datetime,
+         now: dt.datetime | None = None, prices: PriceBook | None = None,
+         is_holiday: HolidayCheck | None = None) -> dict:
+    """An OUTUS bill for ``plan`` over [start, end) from the ledger intervals
+    (``{channel: [interval]}``, ``start`` in epoch seconds). ``now`` before ``end`` makes
+    it provisional, with period charges to date and a projection."""
+    tz = ZoneInfo(plan.get("timezone") or "UTC")
+    start, end = start.astimezone(tz), end.astimezone(tz)
+    s_ts, e_ts = start.timestamp(), end.timestamp()
+    led = {ch: [iv for iv in ivs if s_ts <= iv["start"] < e_ts] for ch, ivs in ledger.items()}
+    period_days = periods.days(start, end)
+    final = now is None or now >= end
+    used_days = period_days if final else max(0.0, round((now - start).total_seconds() / 86400.0, 3))
+    lines = _interval_lines(plan, led, tz, prices, is_holiday)
+    plines, deferred = _period_lines(plan, led, tz, start, end, used_days, period_days, is_holiday)
+    lines += plines
+    subtotal = sum(x["amount"] for x in lines)
+    for base, c in deferred:
+        if c.get("basis") == "minimum_bill":
+            floor = float(c.get("amount") or 0.0) * (used_days / period_days if period_days else 0)
+            top_up = max(0.0, floor - subtotal)
+            if top_up:
+                lines.append({**base, "amount": _money(top_up),
+                              "formula": f"minimum ${_fmt(floor)} − charges ${_fmt(subtotal)}"})
+        else:
+            r = float(c.get("rate") or 0.0)
+            lines.append({**base, "rate": r, "amount": _money(_sign(c) * r * subtotal),
+                          "formula": f"{r:.2%} × ${_fmt(subtotal)}"})
+    net = _money(sum(x["amount"] for x in lines))
+    tax_cfg = plan.get("tax") or {}
+    rate = float(tax_cfg.get("rate") or 0.0)
+    if tax_cfg.get("rates_include_tax", True):
+        tax = _money(net * rate / (1 + rate)) if rate else 0.0
+    else:
+        tax = _money(net * rate)
+        net = _money(net + tax)
+    for x in lines:
+        x.pop("class", None)
+    out = {
+        "type": "outus/bill", "version": 1,
+        "plan_id": plan.get("id"), "plan_name": plan.get("name"),
+        "retailer": (plan.get("retailer") or {}).get("name"),
+        "currency": plan.get("currency"),
+        "period_start": start.astimezone(dt.timezone.utc).isoformat().replace("+00:00", "Z"),
+        "period_end": end.astimezone(dt.timezone.utc).isoformat().replace("+00:00", "Z"),
+        "source": "calculated", "status": "final" if final else "provisional",
+        "line_items": lines, "tax": tax, "net_total": net,
+    }
+    if plan.get("meter"):
+        out["meter"] = plan["meter"]
+    if plan.get("account_number"):
+        out["account_number"] = plan["account_number"]
+    if not final:
+        out["progress"] = _progress(lines, used_days, period_days, rate, tax_cfg)
+    return {k: v for k, v in out.items() if v is not None}
+
+
+def _progress(lines: list[dict], used_days: float, period_days: float, tax_rate: float,
+              tax_cfg: dict) -> dict:
+    """Day n of N and a straight-line projection of every line to the period's end."""
+    scale = period_days / used_days if used_days else 0.0
+    projected = sum(x["amount"] for x in lines) * scale
+    if not tax_cfg.get("rates_include_tax", True):
+        projected *= 1 + tax_rate
+    return {"days_elapsed": used_days, "days": period_days, "projected_total": _money(projected)}
+
+
+def now_rates(plan: dict, at: dt.datetime, prices: PriceBook | None = None,
+              is_holiday: HolidayCheck | None = None) -> list[dict]:
+    """Each interval charge's rate and band now: the live inputs of Bill detail."""
+    tz = ZoneInfo(plan.get("timezone") or "UTC")
+    local = at.astimezone(tz)
+    out = []
+    for t in _tariffs(plan):
+        for c in t.get("charges") or []:
+            if c.get("class") != "interval" or not in_window(c.get("window"), local, is_holiday):
+                continue
+            rate, band, kind = _interval_rate(t, c, local, local.timestamp(), prices, is_holiday)
+            out.append({"tariff_id": t.get("id"), "charge_id": c.get("id"),
+                        "label": c.get("label") or c.get("id"), "rate": rate, "band": band,
+                        "kind": kind, "day_type": day_type(local, None, is_holiday)})
+    return out

hems/ledger.py

@@ -0,0 +1,82 @@
+"""The energy ledger: grid readings in, clock-aligned 5-minute intervals out.
+
+Each device behind a meter (an inverter or battery gateway, say) reports the grid power
+through its own connection, so the meter's power is the sum of their latest readings;
+a device silent for ``FRESH_S`` is left out until it reports again.
+
+State is a plain dict (JSON-safe) that the caller saves; nothing here does I/O.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+SCHEMA_VERSION = 1
+INTERVAL_S = 300          #: OUTUS ledger granularity
+FRESH_S = 300             #: a reading older than this is stale
+MAX_GAP_S = 3600          #: a longer gap between samples is not integrated
+
+
+def new_state(meter_id: str, channel: str = "general") -> dict[str, Any]:
+    return {"schema_version": SCHEMA_VERSION, "meter_id": meter_id, "channel": channel,
+            "latest": {}, "last_ts": None, "open": None}
+
+
+def _blank(start: int) -> dict[str, Any]:
+    return {"start": start, "duration_s": INTERVAL_S, "quantity_in": 0.0, "quantity_out": 0.0,
+            "peak_rate": 0.0, "seconds": 0.0}
+
+
+def combined(state: dict, ts: float) -> float | None:
+    """The meter's power now: the sum of fresh device readings (W), or None."""
+    fresh = [w for t, w in state["latest"].values() if ts - t <= FRESH_S]
+    return sum(fresh) if fresh else None
+
+
+def add_reading(state: dict, device_id: str, ts: float, grid_w: float | None) -> list[dict]:
+    """Record one device's grid power (W, + = import) at ``ts`` (UTC epoch seconds).
+
+    Integrates the meter's power since the previous reading into the open interval and
+    returns the intervals that closed (oldest first) as OUTUS usage intervals with
+    ``start`` in epoch seconds.
+    """
+    if grid_w is not None:
+        state["latest"][device_id] = (float(ts), float(grid_w))
+    closed: list[dict] = []
+    last = state["last_ts"]
+    if last is not None and ts <= last:
+        return closed
+    power = combined(state, ts)
+    if last is not None and power is not None and ts - last <= MAX_GAP_S:
+        t = float(last)
+        while t < ts:
+            slot = int(t // INTERVAL_S * INTERVAL_S)
+            cur = state["open"]
+            if cur is None or cur["start"] != slot:
+                if cur is not None:
+                    closed.append(_finish(cur))
+                cur = state["open"] = _blank(slot)
+            seg_end = min(ts, slot + INTERVAL_S)
+            sec = seg_end - t
+            kwh = abs(power) * sec / 3_600_000.0
+            if power >= 0:
+                cur["quantity_in"] += kwh
+            else:
+                cur["quantity_out"] += kwh
+            cur["seconds"] += sec
+            t = seg_end
+    elif state["open"] is not None and ts >= state["open"]["start"] + INTERVAL_S:
+        closed.append(_finish(state["open"]))
+        state["open"] = None
+    state["last_ts"] = float(ts)
+    return closed
+
+
+def _finish(cur: dict) -> dict:
+    out = {k: v for k, v in cur.items() if k != "seconds"}
+    out["quantity_in"] = round(out["quantity_in"], 6)
+    out["quantity_out"] = round(out["quantity_out"], 6)
+    # Average import power over the interval, kW: the basis for any demand window.
+    out["peak_rate"] = round(out["quantity_in"] * 3600.0 / INTERVAL_S, 4)
+    if cur["seconds"] < INTERVAL_S * 0.9:
+        out["source"] = "estimated"
+    return out

hems/periods.py

@@ -0,0 +1,45 @@
+"""Billing periods: where the period containing a moment starts and ends."""
+from __future__ import annotations
+
+import calendar
+import datetime as dt
+
+MONTHS_PER_CYCLE = {"monthly": 1, "bimonthly": 2, "quarterly": 3}
+
+
+def _on_day(year: int, month: int, day: int, like: dt.datetime) -> dt.datetime:
+    return like.replace(year=year, month=month, day=min(day, calendar.monthrange(year, month)[1]),
+                        hour=0, minute=0, second=0, microsecond=0)
+
+
+def _add_months(year: int, month: int, n: int) -> tuple[int, int]:
+    i = year * 12 + (month - 1) + n
+    return i // 12, i % 12 + 1
+
+
+def bounds(local: dt.datetime, cycle: str = "monthly", cycle_day: int = 1,
+           anchor_month: int = 1) -> tuple[dt.datetime, dt.datetime]:
+    """(start, end) of the billing period containing ``local`` (site local time).
+
+    Periods start on ``cycle_day`` (clamped to the month's length). Bimonthly and
+    quarterly periods are counted from ``anchor_month``.
+    """
+    step = MONTHS_PER_CYCLE.get(cycle, 1)
+    day = max(1, min(28, int(cycle_day or 1)))
+    # The latest cycle-day on or before `local`, in a month on the cycle's grid.
+    y, m = local.year, local.month
+    for _ in range(step + 1):
+        if (m - anchor_month) % step == 0:
+            start = _on_day(y, m, day, local)
+            if start <= local:
+                break
+        y, m = _add_months(y, m, -1)
+    else:                                                       # pragma: no cover
+        raise ValueError("no period start found")
+    ey, em = _add_months(start.year, start.month, step)
+    return start, _on_day(ey, em, day, local)
+
+
+def days(start: dt.datetime, end: dt.datetime) -> float:
+    """Length in days (a DST change makes it fractional; bills count whole days)."""
+    return round((end - start).total_seconds() / 86400.0)

hems/plans.py

@@ -0,0 +1,58 @@
+"""Checks on OUTUS plans that a JSON Schema can't express."""
+from __future__ import annotations
+
+import datetime as dt
+
+from .billing import INTERVAL_BASES
+from .windows import hhmm
+
+BANDS = ("super_off_peak", "off_peak", "mid_peak", "on_peak")
+PERIOD_BASES = {"per_day", "per_month", "per_year", "demand", "excess_over_free_band", "tier",
+                "minimum_bill", "true_up", "percent_of_bill"}
+
+
+def _date(v):
+    return dt.date.fromisoformat(v) if v else None
+
+
+def overlaps(plans: list[dict]) -> list[str]:
+    """Plans on one meter must not overlap (blank end = open-ended)."""
+    issues = []
+    spans = sorted(((_date(p.get("effective_start")) or dt.date.min,
+                     _date(p.get("effective_end")) or dt.date.max, p.get("name") or p.get("id"))
+                    for p in plans), key=lambda x: x[0])
+    for (s1, e1, n1), (s2, _e2, n2) in zip(spans, spans[1:]):
+        if s2 <= e1:
+            issues.append(f"{n1} and {n2} overlap from {s2.isoformat()}")
+    return issues
+
+
+def check(plan: dict) -> list[str]:
+    """Problems that would price wrongly. Empty = fine."""
+    issues = []
+    if not plan.get("tariffs"):
+        issues.append("the plan has no tariffs")
+    s, e = _date(plan.get("effective_start")), _date(plan.get("effective_end"))
+    if s and e and e < s:
+        issues.append("effective_end is before effective_start")
+    for t in plan.get("tariffs") or []:
+        tn = t.get("name") or t.get("id")
+        for c in t.get("charges") or []:
+            cn = f"{tn} › {c.get('label') or c.get('id')}"
+            cls, basis = c.get("class"), c.get("basis")
+            if cls == "interval" and basis not in INTERVAL_BASES:
+                issues.append(f"{cn}: {basis} is a period basis, not interval")
+            if cls == "period" and basis not in PERIOD_BASES:
+                issues.append(f"{cn}: {basis} is an interval basis, not period")
+            if basis in ("series", "series_plus_adder") and (t.get("price_source") or {}).get("kind") != "series":
+                issues.append(f"{cn}: priced from a series, but the tariff has no series price source")
+            for r in c.get("rates") or []:
+                if r.get("band") and r["band"] not in BANDS:
+                    issues.append(f"{cn}: unknown band {r['band']}")
+                w = r.get("window") or {}
+                for k in ("start", "end"):
+                    if w.get(k) is not None and hhmm(w[k]) is None:
+                        issues.append(f"{cn}: bad time {w[k]}")
+            if basis == "per_unit" and c.get("rates") and not any(not r.get("window") for r in c["rates"]):
+                issues.append(f"{cn}: no catch-all rate; times outside its windows go unpriced")
+    return issues

hems/prices.py

@@ -0,0 +1,59 @@
+"""Dynamic prices (OUTUS price series): the price at an interval's start holds for its
+duration, and a later kind replaces an earlier one for the same start."""
+from __future__ import annotations
+
+import bisect
+import datetime as dt
+from typing import Any
+
+RANK = {"forecast": 0, "estimate": 1, "confirmed": 2, "actual": 3}
+
+
+def _epoch(v: Any) -> int:
+    if isinstance(v, (int, float)):
+        return int(v)
+    return int(dt.datetime.fromisoformat(str(v).replace("Z", "+00:00")).timestamp())
+
+
+class PriceBook:
+    """One source's price intervals, keyed by start (UTC epoch seconds)."""
+
+    def __init__(self, provider: str = "", region: str = "") -> None:
+        self.provider, self.region = provider, region
+        self._by_start: dict[int, dict] = {}
+        self._starts: list[int] = []
+
+    def add(self, intervals: list[dict]) -> list[int]:
+        """Merge intervals; returns the starts whose price changed (to re-price)."""
+        changed = []
+        for iv in intervals:
+            start = _epoch(iv["start"])
+            old = self._by_start.get(start)
+            if old is not None and RANK.get(iv.get("kind"), 0) < RANK.get(old.get("kind"), 0):
+                continue
+            new = dict(iv, start=start)
+            if old is None:
+                bisect.insort(self._starts, start)
+            if old is None or (old.get("import"), old.get("export"), old.get("kind")) != (
+                    new.get("import"), new.get("export"), new.get("kind")):
+                changed.append(start)
+            self._by_start[start] = new
+        return changed
+
+    def at(self, ts: float) -> dict | None:
+        """The price in force at ``ts``. Past the last interval, the last known price is
+        carried forward and marked ``estimate``; None before the first."""
+        i = bisect.bisect_right(self._starts, int(ts)) - 1
+        if i < 0:
+            return None
+        iv = self._by_start[self._starts[i]]
+        if ts < iv["start"] + int(iv.get("duration_s") or 300):
+            return iv
+        return dict(iv, kind="estimate", carried=True)
+
+    @classmethod
+    def from_document(cls, doc: dict) -> PriceBook:
+        src = doc.get("source") or {}
+        book = cls(src.get("provider", ""), src.get("region", ""))
+        book.add(doc.get("intervals") or [])
+        return book

hems/profile_v1.py

@@ -0,0 +1,146 @@
+"""Import a ``franklinwh-bridge/tariff-profile`` v1 file as an OUTUS plan.
+
+A v1 profile is one tariff: seasons of TOU blocks naming a time period with buy/sell
+rates, a tariff-wide default rate (a number or a tier ladder), optional demand, export
+bonus and export charge windows, and fixed charges. It becomes a plan with a ``general``
+tariff (buy) and, when anything is paid or charged for export, an ``export`` tariff. The
+original profile is kept under ``x-tariff-profile-v1`` so nothing is lost.
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any
+
+PROFILE_TYPE = "franklinwh-bridge/tariff-profile"
+_FIXED = {"daily": ("per_day", 1.0), "weekly": ("per_day", 1 / 7.0),
+          "monthly": ("per_month", 1.0), "quarterly": ("per_month", 1 / 3.0),
+          "annual": ("per_year", 1.0)}
+
+
+def _days(days: list | None, out: dict) -> None:
+    """v1 weekday numbers (Monday 0) → OUTUS day types where exact, else kept as ``days``."""
+    d = set(days or [])
+    if not d or d == set(range(7)):
+        return
+    if d == {0, 1, 2, 3, 4}:
+        out["day_types"] = ["weekday"]
+    elif d == {5, 6}:
+        out["day_types"] = ["weekend"]
+    else:
+        out["days"] = sorted(d)
+
+
+def _window(w: dict | None) -> dict | None:
+    if not isinstance(w, dict) or not w:
+        return None
+    out = {k: w[k] for k in ("months", "start", "end") if w.get(k)}
+    _days(w.get("days"), out)
+    return out or None
+
+
+def _tou(seasons: list, side: str) -> list[dict]:
+    rates = []
+    for s in seasons or []:
+        periods = s.get("time_periods") or s.get("waves") or {}
+        for b in s.get("blocks") or []:
+            band = b.get("time_period") or b.get("wave")
+            rate = (periods.get(band) or {}).get(side)
+            if not isinstance(rate, (int, float)):
+                continue
+            win = {"start": b.get("start"), "end": b.get("end")}
+            if s.get("months"):
+                win["months"] = list(s["months"])
+            _days(b.get("days"), win)
+            rates.append({"window": win, "band": band, "rate": float(rate)})
+    return rates
+
+
+def _flat_or_tiers(value: Any) -> tuple[float | None, list[dict] | None]:
+    if isinstance(value, (int, float)):
+        return float(value), None
+    if isinstance(value, list) and value:
+        tiers = [{"up_to": t.get("up_to_kwh"), "rate": float(t["rate"])}
+                 for t in value if isinstance(t, dict) and isinstance(t.get("rate"), (int, float))]
+        return None, tiers or None
+    return None, None
+
+
+def from_tariff_profile(doc: dict) -> dict:
+    """A v1 tariff-profile document (or its inner ``profile``) → an OUTUS plan."""
+    p = doc.get("profile", doc) if doc.get("type") == PROFILE_TYPE else doc
+    pr = p.get("pricing") or {}
+    seasons = pr.get("seasons") or []
+    default = pr.get("default_rate") or {}
+    general: list[dict] = []
+    export: list[dict] = []
+
+    buy_flat, buy_tiers = _flat_or_tiers(default.get("buy"))
+    tou_buy = _tou(seasons, "buy")
+    if tou_buy or buy_flat is not None:
+        rates = tou_buy + ([{"rate": buy_flat}] if buy_flat is not None else [])
+        general.append({"id": "energy", "label": "Energy", "class": "interval", "basis": "per_unit",
+                        "unit": "kWh", "rates": rates})
+    if buy_tiers:
+        general.append({"id": "energy_tiers", "label": "Energy (tiered)", "class": "period",
+                        "basis": "tier", "unit": "kWh", "tiers": buy_tiers})
+
+    if pr.get("demand_rate") and _window(p.get("demand_window")):
+        per = "per_month" if pr.get("demand_charge_basis") == "per_kw_month" else "per_day"
+        general.append({"id": "demand", "label": "Peak demand", "class": "period", "basis": "demand",
+                        "rate": float(pr["demand_rate"]), "unit": "kW",
+                        "window": _window(p.get("demand_window")),
+                        "demand": {"method": "monthly_max",
+                                   "interval_min": int(pr.get("demand_interval_min") or 30),
+                                   "unit": "kW", "frequency": per}})
+
+    sell_flat, _ = _flat_or_tiers(default.get("sell"))
+    tou_sell = _tou(seasons, "sell")
+    if tou_sell or sell_flat is not None:
+        rates = tou_sell + ([{"rate": sell_flat}] if sell_flat is not None else [])
+        export.append({"id": "feed_in", "label": "Feed-in credit", "class": "interval",
+                       "basis": "per_unit", "direction": "export", "effect": "credit", "unit": "kWh",
+                       "rates": rates})
+    if pr.get("export_bonus_rate") and _window(p.get("bonus_window")):
+        export.append({"id": "bonus", "label": "Export bonus", "class": "interval", "basis": "per_unit",
+                       "direction": "export", "effect": "credit", "unit": "kWh",
+                       "window": _window(p.get("bonus_window")), "rate": float(pr["export_bonus_rate"])})
+    ec = pr.get("export_charge") or {}
+    if ec.get("rate"):
+        export.append({"id": "export_charge", "label": "Export charge", "class": "period",
+                       "basis": "excess_over_free_band", "direction": "export", "unit": "kWh",
+                       "rate": float(ec["rate"]), "window": _window(ec.get("window")),
+                       "free_band": {"quantity": float(ec.get("free_kwh_per_day") or 0.0), "per": "day"}})
+
+    charges = []
+    for i, f in enumerate(pr.get("fixed_charges") or []):
+        if not isinstance(f, dict) or not isinstance(f.get("rate"), (int, float)):
+            continue
+        basis, k = _FIXED.get(f.get("frequency") or "daily", ("per_day", 1.0))
+        charges.append({"id": f"fixed_{i + 1}", "label": f.get("description") or f.get("type") or "Fixed charge",
+                        "class": "period", "basis": basis,
+                        "rate": round(float(f["rate"]) * k * (1 + float(f.get("tax_rate") or 0.0)), 6),
+                        "unit": basis.removeprefix("per_")})
+
+    tariffs = []
+    if general:
+        tariffs.append({"id": "general", "name": "General", "applies_to": "general",
+                        "price_source": {"kind": "static"}, "charges": general})
+    if export:
+        tariffs.append({"id": "export", "name": "Export", "applies_to": "export", "charges": export})
+    plan: dict[str, Any] = {
+        "type": "outus/plan", "version": 1,
+        "name": p.get("name") or "Imported plan",
+        "retailer": {k: v for k, v in (("name", p.get("retailer")), ("network", p.get("network")),
+                                       ("country", p.get("country"))) if v},
+        "currency": {"AU": "AUD", "US": "USD", "NZ": "NZD", "GB": "GBP"}.get(p.get("country") or "", "AUD"),
+        "billing": {"cycle": "monthly", "cycle_day": max(1, min(28, int(pr.get("billing_cycle_day") or 1)))},
+        "tax": {"rate": 0.10 if p.get("country") == "AU" else 0.0, "rates_include_tax": True},
+        "export_compensation": "feed_in",
+        "charges": charges,
+        "tariffs": tariffs,
+        "x-tariff-profile-v1": copy.deepcopy(p),
+    }
+    for k in ("timezone", "effective_start", "effective_end"):
+        if p.get(k):
+            plan[k] = p[k]
+    return plan

hems/setup.py

@@ -0,0 +1,47 @@
+"""Billing setup steps, in the model's order: site → meter → plan → tariffs.
+
+One source for every place an application tells the user what is missing, so all of
+them say the same thing.
+"""
+from __future__ import annotations
+
+import datetime as dt
+
+from .billing import plan_in_force
+
+STEPS = (
+    ("site", "Site", "Add your site"),
+    ("meter", "Meter", "Add your meter"),
+    ("plan", "Plan", "Add your retailer plan on the meter"),
+    ("tariffs", "Tariffs", "Add the plan's tariffs"),
+)
+
+
+def steps(sites: list[dict], meters: list[dict], plans: list[dict], meter_id: str | None,
+          today: dt.date) -> list[dict]:
+    """Each step with ``done`` and, while missing, what to do. ``plans`` are that meter's plans."""
+    meter = next((m for m in meters if m.get("id") == meter_id), None)
+    plan = plan_in_force(plans, today) if meter else None
+    done = {
+        "site": bool(sites),
+        "meter": meter is not None,
+        "plan": plan is not None,
+        "tariffs": bool(plan and plan.get("tariffs")),
+    }
+    out, blocked = [], False
+    for key, label, todo in STEPS:
+        step = {"key": key, "label": label, "done": done[key]}
+        if not done[key]:
+            step["todo"] = todo
+            step["blocked"] = blocked          # an earlier step is missing
+            blocked = True
+        if key == "meter" and meter:
+            step["detail"] = meter.get("name")
+        if key == "plan" and plan:
+            step["detail"] = plan.get("name")
+        out.append(step)
+    return out
+
+
+def complete(steps_: list[dict]) -> bool:
+    return all(s["done"] for s in steps_)

hems/windows.py

@@ -0,0 +1,64 @@
+"""Time windows: does a local time fall inside an OUTUS window?
+
+A window is ``{months, day_types, start, end, holiday_region, clock}`` (OUTUS) or the
+older tariff-profile ``{months, days, start, end}`` (``days`` = weekday numbers, Monday 0).
+Omitted parts mean always. An end at or before the start wraps past midnight, and
+``24:00`` ends the day.
+"""
+from __future__ import annotations
+
+import datetime as dt
+from collections.abc import Callable
+from typing import Any
+
+#: A callable telling whether a local date is a public holiday in a region.
+HolidayCheck = Callable[[dt.date, str | None], bool]
+
+
+def hhmm(raw: Any) -> int | None:
+    """``"HH:MM"`` → minutes since midnight, or None."""
+    if not isinstance(raw, str) or ":" not in raw:
+        return None
+    try:
+        h, m = (int(x) for x in raw.split(":", 1))
+    except ValueError:
+        return None
+    if not (0 <= h <= 24 and 0 <= m < 60) or (h == 24 and m):
+        return None
+    return h * 60 + m
+
+
+def day_type(local: dt.datetime, region: str | None = None,
+             is_holiday: HolidayCheck | None = None) -> str:
+    """``holiday``, ``weekend`` or ``weekday`` for a local time."""
+    if is_holiday is not None and is_holiday(local.date(), region):
+        return "holiday"
+    return "weekend" if local.weekday() >= 5 else "weekday"
+
+
+def in_window(win: Any, local: dt.datetime, is_holiday: HolidayCheck | None = None) -> bool:
+    """Is ``local`` (the site's local time) inside ``win``? No window means always."""
+    if win is None:
+        return True
+    if not isinstance(win, dict):
+        return False
+    months = win.get("months") or []
+    if months and local.month not in months:
+        return False
+    days = win.get("days") or []
+    if days and local.weekday() not in days:
+        return False
+    types = win.get("day_types") or []
+    # A public holiday is its own day type: a window listing only weekdays excludes it.
+    # Without a holiday check, no day is a holiday.
+    if types and day_type(local, win.get("holiday_region"), is_holiday) not in types:
+        return False
+    start, end = hhmm(win.get("start")), hhmm(win.get("end"))
+    if start is None or end is None:
+        return True
+    if win.get("clock") == "standard" and local.dst():
+        local = local - local.dst()
+    minute = local.hour * 60 + local.minute
+    if end <= start:
+        return minute >= start or minute < end
+    return start <= minute < end

hems-0.1.0.dist-info/METADATA

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: hems
+Version: 0.1.0
+Summary: An OUTUS v1 engine: plans, the usage ledger, dynamic prices and explainable bills
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/david2069/hems
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: schema
+Requires-Dist: jsonschema>=4.18; extra == "schema"
+Requires-Dist: referencing; extra == "schema"
+Requires-Dist: rfc3339-validator; extra == "schema"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: jsonschema>=4.18; extra == "test"
+Requires-Dist: referencing; extra == "test"
+Requires-Dist: rfc3339-validator; extra == "test"
+Dynamic: license-file
+
+# hems
+
+An engine for [OUTUS](https://github.com/david2069/outus), the Open Utility Tariff & Usage
+Specification. It reads OUTUS plans and price series, keeps the usage ledger, and writes
+OUTUS bills with every line explained.
+
+- **Implements:** OUTUS v1 (electricity). The spec is published separately; hems is one
+  implementation of it.
+- **Python ≥ 3.11, no dependencies, no I/O.** Callers supply readings, prices and the plan,
+  and store the results.
+- **Used by:** the FranklinWH Direct Connect and Modbus bridges.
+
+| Module | Job |
+|---|---|
+| `hems.ledger` | grid readings from the devices behind a meter → 5-minute usage intervals |
+| `hems.prices` | a price series: price at an interval's start, later kinds replace earlier ones |
+| `hems.billing` | an OUTUS bill from a plan and the ledger, with formulas; provisional bills project to the period's end; `now_rates` for the live band and rate |
+| `hems.periods` | billing period bounds (monthly, bimonthly, quarterly) |
+| `hems.plans` | checks a schema can't express (overlapping plans, wrong charge class, unpriced gaps) |
+| `hems.setup` | setup steps in order: site → meter → plan → tariffs |
+| `hems.profile_v1` | imports a `franklinwh-bridge/tariff-profile` v1 file as an OUTUS plan |
+
+```
+pip install -e ".[test]"
+pytest
+```
+
+The tests check every bill hems writes against the OUTUS v1 schemas, copied in
+`tests/outus-v1/`.
+
+## Licence
+MIT

hems-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+hems/__init__.py,sha256=rfB2ESRRnGmKxwpjqWuRrdLD4A7U9L9_mvmxE7aF8og,187
+hems/billing.py,sha256=hhwq1c7aHhiGPNDaPQLnPJ4VDZ8JVTJKQzYeSkafriw,19091
+hems/ledger.py,sha256=pHnyYmvp0_oY6E2p2TX5SYMFst0zIttXmvgfMHrujGE,3337
+hems/periods.py,sha256=yIWDBOUQD_-K54O2dz7c54nmf4Z7VaUU20NM7NJOHzM,1830
+hems/plans.py,sha256=IkH6KCagp7KP1i54_YYDaxMa9lLn6tObr8arl0Tpywk,2730
+hems/prices.py,sha256=VO8Ndrf8HxYnYpmO-FhWSgd-U7xvdZs0iU1ySDJN5FE,2316
+hems/profile_v1.py,sha256=QQw3Y1ii03uQqGTtf6YxDDMrAxlTtaCwAk0f0xL8FSw,7145
+hems/setup.py,sha256=ryOMjfc1-1vS10RrWs1D-2dbpjbXAEpX8RKst49aC-g,1614
+hems/windows.py,sha256=FBqgHGkXGaB6x69_8YlYJgii-uMLwhC-UD76RHpBkgI,2438
+hems-0.1.0.dist-info/licenses/LICENSE,sha256=C8ltdG5x2gcOmXk68ypMIdob1FzV7vxlOPEM0vbGG1w,3760
+hems-0.1.0.dist-info/METADATA,sha256=TH9Wd8zyb1LXwulzK4T7huYow44jZrPHkaI3w75cDgY,2120
+hems-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+hems-0.1.0.dist-info/top_level.txt,sha256=dvmCq4wXZ-2M-ahK0Xn68ajbIG3d9BYos6Jdj1e56Yo,5
+hems-0.1.0.dist-info/RECORD,,

hems-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hems-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,72 @@
+MIT License
+
+Copyright (c) 2026 david2069
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+================================================================================
+ADDITIONAL TERMS
+================================================================================
+
+These Additional Terms accompany and supplement the MIT License above. By using,
+copying, modifying, or distributing the Software you accept them.
+
+1. UNOFFICIAL — NO AFFILIATION
+   This is UNOFFICIAL software, NOT affiliated with, endorsed by, or supported by
+   FranklinWH. It interfaces with FranklinWH's undocumented Direct Connect (local)
+   API and its cloud API — technically the same private API the official FranklinWH
+   mobile app and the FleetView installer portal use, intended for those apps and not
+   for third-party use — plus the standard SunSpec Modbus TCP API (with undocumented
+   FranklinWH extensions). Any of these may change, break, or become unavailable
+   without notice. Do
+   NOT contact FranklinWH support about this Software — raise issues, defects, or
+   feature requests on GitHub:
+   https://github.com/david2069/franklinwh-direct-connect-bridge/issues
+
+2. COMPLIANCE & ANTI-CIRCUMVENTION
+   You agree to keep your gateway and battery settings, controls, and operation
+   compliant with the configuration set through the official FranklinWH Mobile App
+   and the installer/support FleetView portal.
+
+   FranklinWH-managed settings may exist to, among other things:
+     - protect the safety and longevity of the battery and gateway;
+     - apply automatic software updates and restrict your ability to view or change
+       battery, grid-import, or grid-export controls;
+     - enforce your local electricity grid profile and any import/export limits or
+       prohibitions;
+     - enforce restrictions tied to contractual incentives, subsidies, or VPP/grid
+       programmes.
+
+   If you use this Software to bypass or override any such control, restriction, or
+   compliance measure — deliberately or inadvertently — you do so entirely at your
+   own risk. This is neither condoned nor encouraged by the authors or any other
+   party.
+
+3. INTENT & RISK
+   This Software is provided for informational and educational purposes, AS-IS,
+   with no warranty of fitness for any purpose. Any use — personal or commercial
+   — is permitted under the MIT License above and is entirely at your own risk.
+
+4. NOTICE
+   As the MIT License above requires, the copyright notice and this permission
+   notice (including these Additional Terms) shall be included in all copies or
+   substantial portions of the Software. Retaining it in copies, forks, derivatives,
+   and AI-assisted works keeps the unofficial-app, compliance, and support context
+   travelling with the code.

hems-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hems