tariffkit 0.2.0__py3-none-any.whl

tariffkit/tariff/__init__.py

@@ -0,0 +1,5 @@
+"""Retail import tariffs."""
+
+from .retail import RetailTariff, TariffSnapshot, load_snapshot
+
+__all__ = ["RetailTariff", "TariffSnapshot", "load_snapshot"]

tariffkit/tariff/retail.py

@@ -0,0 +1,271 @@
+"""PG&E residential retail import pricing.
+
+Schedule-agnostic: everything that differs between schedules lives in the
+vendored snapshot, so adding one is a data change. Currently vendored are
+E-ELEC, E-TOU-C, and EV2-A.
+
+They share a shape that keeps pricing cheap: period boundaries are identical
+every day of the week including holidays, and do not shift by season. So a
+price is determined by (season, hour) alone.
+
+The one exception is E-TOU-C's baseline credit, which applies to the first N
+kWh of a cycle. That is a quantity rather than a time, so no marginal price can
+express it. ``price_at`` returns the over-baseline price -- the right answer for
+a dispatch decision, since an allowance is normally spent early in the cycle --
+and reports the available credit as ``ImportPrice.baseline_credit`` for the
+billing engine, which sees a whole cycle, to apply.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass
+from datetime import date, datetime
+from functools import lru_cache
+from importlib.resources import files
+from typing import Any
+
+from ..cca import load_rate_card
+from ..config import Config
+from ..errors import ConfigError, DataError
+from ..models import ImportPrice, Season, Supplier, TouPeriod
+
+TARIFF_DATA_ROOT = "tariff"
+
+
+@dataclass(frozen=True, slots=True)
+class TariffSnapshot:
+    """One effective-dated version of a tariff sheet."""
+
+    effective: date
+    raw: dict[str, Any]
+
+    @property
+    def advice_letter(self) -> str:
+        return str(self.raw.get("advice_letter", ""))
+
+    @property
+    def source_url(self) -> str:
+        return str(self.raw.get("source_url", ""))
+
+
+@lru_cache(maxsize=8)
+def _snapshots(utility: str, tariff: str) -> tuple[TariffSnapshot, ...]:
+    directory = (
+        files("tariffkit.data")
+        / TARIFF_DATA_ROOT
+        / utility.lower()
+        / tariff.lower().replace("-", "")
+    )
+    if not directory.is_dir():
+        raise DataError(f"no vendored tariff data for {utility}/{tariff}")
+    found = []
+    for entry in directory.iterdir():
+        if not entry.name.endswith(".toml"):
+            continue
+        raw = tomllib.loads(entry.read_text(encoding="utf-8"))
+        found.append(TariffSnapshot(date.fromisoformat(raw["effective"]), raw))
+    if not found:
+        raise DataError(f"no tariff snapshots for {utility}/{tariff}")
+    return tuple(sorted(found, key=lambda s: s.effective))
+
+
+def load_snapshot(utility: str, tariff: str, on: date) -> TariffSnapshot:
+    """The snapshot in force on ``on`` -- the latest one not in the future."""
+    snapshots = _snapshots(utility, tariff)
+    applicable = [s for s in snapshots if s.effective <= on]
+    if not applicable:
+        raise DataError(
+            f"{utility}/{tariff}: no snapshot effective on or before {on}; "
+            f"earliest vendored is {snapshots[0].effective}"
+        )
+    return applicable[-1]
+
+
+class RetailTariff:
+    """Prices a kWh of grid import under the configured schedule."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+
+    def snapshot_for(self, moment: datetime) -> TariffSnapshot:
+        return load_snapshot(self.config.utility, self.config.tariff, moment.date())
+
+    def season(self, moment: datetime, snapshot: TariffSnapshot | None = None) -> Season:
+        snapshot = snapshot or self.snapshot_for(moment)
+        seasons = snapshot.raw["seasons"]
+        start_month, start_day = (int(p) for p in seasons["summer_start"].split("-"))
+        end_month, end_day = (int(p) for p in seasons["summer_end"].split("-"))
+        marker = (moment.month, moment.day)
+        if (start_month, start_day) <= marker <= (end_month, end_day):
+            return Season.SUMMER
+        return Season.WINTER
+
+    def period(self, moment: datetime, snapshot: TariffSnapshot | None = None) -> TouPeriod:
+        """Resolve the TOU period. Identical every day of the week."""
+        snapshot = snapshot or self.snapshot_for(moment)
+        periods = snapshot.raw["periods"]
+        hour = moment.hour
+        for start, end in periods["peak"]:
+            if start <= hour < end:
+                return TouPeriod.PEAK
+        # Absent rather than empty on a schedule with no part-peak, which is how
+        # E-TOU-C is written: peak or off-peak, nothing between.
+        for start, end in periods.get("part_peak", []):
+            if start <= hour < end:
+                return TouPeriod.PART_PEAK
+        return TouPeriod.OFF_PEAK
+
+    def price_at(self, moment: datetime) -> ImportPrice:
+        snapshot = self.snapshot_for(moment)
+        season = self.season(moment, snapshot)
+        period = self.period(moment, snapshot)
+        components, complete = self._components(snapshot, season, period, moment)
+        total = self._apply_discount(snapshot, components)
+        return ImportPrice(
+            total=round(total, 6),
+            season=season,
+            period=period,
+            components={k: round(v, 6) for k, v in components.items()},
+            complete=complete,
+            baseline_credit=float(snapshot.raw.get("baseline", {}).get("credit", 0.0)),
+        )
+
+    def baseline_allowance(self, moment: datetime) -> float:
+        """Baseline kWh allowed for the day containing ``moment``.
+
+        Zero on a schedule without a baseline, and zero when no territory is
+        configured -- the quantities vary several-fold between territories, so
+        guessing one would be worse than reporting no allowance.
+        """
+        snapshot = self.snapshot_for(moment)
+        quantities = snapshot.raw.get("baseline", {}).get("quantities")
+        if not quantities or self.config.baseline_territory is None:
+            return 0.0
+        table = quantities.get(self.config.baseline_code)
+        if table is None:
+            raise ConfigError(
+                f"unknown baseline_code {self.config.baseline_code!r}; "
+                f"vendored: {sorted(quantities)}"
+            )
+        territory = table.get(self.config.baseline_territory.upper())
+        if territory is None:
+            raise ConfigError(
+                f"no baseline quantity for territory "
+                f"{self.config.baseline_territory!r}; vendored: {sorted(table)}"
+            )
+        return float(territory[str(self.season(moment, snapshot))])
+
+    def _components(
+        self,
+        snapshot: TariffSnapshot,
+        season: Season,
+        period: TouPeriod,
+        moment: datetime,
+    ) -> tuple[dict[str, float], bool]:
+        energy = snapshot.raw["energy"][str(season)][str(period)]
+        components: dict[str, float] = dict(energy)
+        components.update(snapshot.raw["adders"])
+        complete = True
+
+        if self.config.supplier is Supplier.CCA:
+            cca = self.config.cca
+            assert cca is not None
+            for name in snapshot.raw["cca"]["drop_components"]:
+                components.pop(name, None)
+
+            # A rate taken straight from a bill wins over the vintage table,
+            # which only carries the vintages printed on the E-ELEC sheet.
+            if cca.pcia_rate is not None:
+                components["pcia"] = cca.pcia_rate
+            elif cca.pcia_vintage is not None:
+                table = snapshot.raw["cca"]["pcia_vintages"]
+                key = str(cca.pcia_vintage)
+                if key not in table:
+                    raise ConfigError(
+                        f"no PCIA rate vendored for vintage {cca.pcia_vintage}; "
+                        f"available: {sorted(table)}"
+                    )
+                components["pcia"] = float(table[key])
+
+            # Same precedence as the PCIA above: an explicit rate wins, then the
+            # vendored Schedule E-FFS table, which is vintaged off the same year.
+            if cca.franchise_fee_surcharge is not None:
+                components["franchise_fee_surcharge"] = cca.franchise_fee_surcharge
+            elif cca.pcia_vintage is not None:
+                ffs_table = snapshot.raw["cca"]["franchise_fee_vintages"]
+                key = str(cca.pcia_vintage)
+                if key not in ffs_table:
+                    # Reaching here means the two vintaged tables disagree, since
+                    # the PCIA lookup above already accepted this year. That is a
+                    # vendoring bug, not a gap in the user's config, so it raises
+                    # rather than degrading to complete=False -- which means
+                    # something quite different and much larger.
+                    raise ConfigError(
+                        f"vintage {cca.pcia_vintage} has a PCIA rate but no franchise fee "
+                        f"surcharge; vendored franchise fee vintages: {sorted(ffs_table)}"
+                    )
+                components["franchise_fee_surcharge"] = float(ffs_table[key])
+            else:
+                complete = False
+
+            rates = cca.generation_rates.get(str(season), {})
+            if str(period) in rates:
+                components["cca_generation"] = float(rates[str(period)])
+            elif cca.rate_card is not None:
+                card = load_rate_card(cca.rate_card, moment.date())
+                components["cca_generation"] = card.generation(
+                    self.config.tariff, str(season), str(period), cca.option
+                )
+                credit = card.cost_relief_credit(moment.date())
+                if credit:
+                    components["cca_cost_relief_credit"] = credit
+            else:
+                # Delivery-only price. Flagged rather than silently understated.
+                complete = False
+
+        return components, complete
+
+    def _apply_discount(self, snapshot: TariffSnapshot, components: dict[str, float]) -> float:
+        total = sum(components.values())
+        if self.config.discount == "none":
+            return total
+        discounts = snapshot.raw.get("discounts")
+        if not discounts or self.config.discount not in discounts:
+            # The percentage is schedule-specific and not every sheet prints it.
+            # Better to refuse than to borrow another schedule's figure.
+            raise ConfigError(
+                f"{snapshot.raw['tariff']} does not vendor a {self.config.discount.upper()} "
+                "discount; it is not published on that schedule's tariff sheet"
+            )
+        rate = float(discounts[self.config.discount])
+        if self.config.discount == "care":
+            # The Wildfire Fund Charge is not levied on CARE sales at all, so it
+            # comes off before the percentage discount rather than being
+            # discounted alongside everything else.
+            for name in discounts.get("care_excludes", []):
+                if name in components:
+                    total -= components.pop(name)
+        return total * (1.0 - rate)
+
+    def daily_fixed_charge(self, moment: datetime) -> float:
+        """Base Services Charge in $/day.
+
+        Kept out of the per-kWh price on purpose: it does not vary with
+        consumption, so folding it in would corrupt any marginal decision about
+        whether to import, export, or self-consume.
+
+        The CARE/FERA reduction is already baked into the tier 1 and tier 2
+        amounts, so the percentage discount is not applied again here.
+
+        Zero when the vintage being priced has no such charge. AB 205's charge
+        began on 2026-03-01; before it, E-TOU-C and EV2-A had no daily fixed
+        charge at all, and E-ELEC had a single flat per-meter rate. A snapshot
+        from then carries no table, and that absence is the correct answer
+        rather than a missing-data error.
+        """
+        snapshot = self.snapshot_for(moment)
+        table = snapshot.raw.get("base_services_charge")
+        if not table:
+            return 0.0
+        return float(table[f"tier_{self.config.base_services_charge_tier}"])

tariffkit/timeutil.py

@@ -0,0 +1,120 @@
+"""Pacific-time primitives shared by the import and export engines.
+
+Everything PG&E publishes is anchored to Pacific Prevailing Time, so the whole
+package normalizes to it exactly once, here, and works in wall-clock terms
+downstream.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from datetime import UTC, date, datetime, timedelta
+from enum import StrEnum
+from functools import lru_cache
+from zoneinfo import ZoneInfo
+
+from .errors import DataError
+
+PACIFIC = ZoneInfo("America/Los_Angeles")
+
+MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+
+
+class DayType(StrEnum):
+    """Export day type. E-ELEC import pricing does not use this at all."""
+
+    WEEKDAY = "Weekday"
+    WEEKEND = "Weekend"
+
+
+def to_pacific(moment: datetime) -> datetime:
+    """Convert an aware datetime to Pacific time.
+
+    Naive datetimes are rejected rather than assumed: silently guessing a zone
+    is how an export lookup ends up eight hours off.
+    """
+    if moment.tzinfo is None:
+        raise ValueError("naive datetime; pass an aware one, e.g. datetime.now(tariffkit.PACIFIC)")
+    return moment.astimezone(PACIFIC)
+
+
+def now_pacific() -> datetime:
+    return datetime.now(PACIFIC)
+
+
+def hour_floor(moment: datetime) -> datetime:
+    """Truncate to the start of the containing hour, preserving the offset."""
+    return moment.replace(minute=0, second=0, microsecond=0)
+
+
+def next_hour(moment: datetime) -> datetime:
+    """The start of the next hour.
+
+    Steps in absolute time so it stays correct across DST transitions: on the
+    fall-back day 01:00 PDT + 1h is 01:00 PST, a real distinct hour. Adding to
+    the zoned value instead would skip straight to 02:00, two hours later, and
+    an hourly publisher driven off that would never emit the second 01:00.
+    """
+    floor = hour_floor(moment)
+    return (floor.astimezone(UTC) + timedelta(hours=1)).astimezone(floor.tzinfo)
+
+
+@lru_cache(maxsize=1)
+def _holiday_table() -> dict[int, frozenset[date]]:
+    from .data import read_data_text
+
+    raw = tomllib.loads(read_data_text("holidays.toml"))["holidays"]
+    return {
+        int(year): frozenset(date.fromisoformat(d) for d in dates) for year, dates in raw.items()
+    }
+
+
+def holidays(year: int) -> frozenset[date]:
+    """The eight tariff holidays observed in ``year``.
+
+    Extracted from PG&E's own data rather than recomputed, so the observed-date
+    rules (Saturday -> preceding Friday, Sunday -> following Monday) and the
+    year-spanning New Year's case come from the source of truth.
+    """
+    table = _holiday_table()
+    if year not in table:
+        raise DataError(
+            f"no holiday calendar for {year}; vendored data covers {min(table)}-{max(table)}"
+        )
+    return table[year]
+
+
+def is_holiday(day: date) -> bool:
+    return day in holidays(day.year)
+
+
+def export_hour(moment: datetime) -> int:
+    """The hour index (``HS0``-``HS23``) upstream assigns to this instant.
+
+    Almost always the wall-clock hour, but the fall-back day has 25 real hours
+    and only 24 labels. PG&E resolves that by giving the repeated 01:00 PST the
+    ``HS2`` label, so the second 1am is priced as 2am and the rest of the day
+    stays aligned. ``fold`` is 1 only during that ambiguous hour, so adding it
+    reproduces the published labelling exactly.
+
+    The spring-forward day needs no special case: 02:00 simply does not exist,
+    and upstream correspondingly publishes no ``HS2`` row for it.
+    """
+    return moment.hour + moment.fold
+
+
+def day_type(moment: datetime, calendar: frozenset[date] | None = None) -> DayType:
+    """Classify a Pacific-time moment for export-rate lookup.
+
+    Saturdays, Sundays, and the eight tariff holidays all share the "Weekend"
+    matrix column.
+
+    ``calendar`` overrides the shared holiday table. Export lookups pass the
+    calendar embedded in their own vintage file: the vintages disagree about
+    far-future holidays, and using the wrong one reads the wrong matrix column.
+    """
+    if moment.weekday() >= 5:
+        return DayType.WEEKEND
+    day = moment.date()
+    holiday = day in calendar if calendar is not None else is_holiday(day)
+    return DayType.WEEKEND if holiday else DayType.WEEKDAY

tariffkit/web/__init__.py

@@ -0,0 +1,5 @@
+"""Optional FastAPI service."""
+
+from .app import create_app
+
+__all__ = ["create_app"]

tariffkit/web/app.py

@@ -0,0 +1,220 @@
+"""A small read-only REST API over the rate engine.
+
+Every response is pure computation over vendored data, so there is nothing to
+cache invalidate and no upstream to rate-limit.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..account import (
+    AccountError,
+    AccountRateEngine,
+    NamedProfileRepository,
+    ProfileNotFoundError,
+    configured_profile_name,
+)
+from ..config import Config
+from ..engine import RateEngine
+from ..errors import ConfigError, DataError, OutOfRangeError
+
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+MAX_FORECAST_HOURS = 24 * 365
+_PROFILE_UNAVAILABLE = "profile unavailable"
+
+
+def create_app(
+    config: Config | None = None,
+    *,
+    profile_name: str | None = None,
+    profile_repository: NamedProfileRepository | None = None,
+    config_path: str | Path | None = None,
+) -> FastAPI:
+    try:
+        from fastapi import Body, FastAPI, HTTPException, Query
+    except ImportError as exc:  # pragma: no cover - exercised by packaging
+        raise RuntimeError(
+            "web support requires the 'web' extra: pip install 'tariffkit[web]'"
+        ) from exc
+
+    def load_profile(name: str) -> AccountRateEngine:
+        repository = profile_repository or NamedProfileRepository()
+        try:
+            return AccountRateEngine(repository.load(name))
+        except ProfileNotFoundError as exc:
+            # Do not reveal whether a profile exists, nor details from its
+            # managed file, through a request-facing error.
+            raise HTTPException(404, _PROFILE_UNAVAILABLE) from exc
+        except AccountError as exc:
+            raise HTTPException(404, _PROFILE_UNAVAILABLE) from exc
+
+    selected_profile = profile_name
+    if selected_profile is None and config is None:
+        selected_profile = configured_profile_name(config_path)
+    engine: RateEngine | AccountRateEngine
+    if selected_profile is not None:
+        engine = load_profile(selected_profile)
+    else:
+        engine = RateEngine(config or Config.load(config_path))
+
+    def request_engine(
+        payload: dict[str, Any], *, allowed: set[str]
+    ) -> RateEngine | AccountRateEngine:
+        unknown = set(payload) - allowed
+        if unknown:
+            raise HTTPException(422, f"unknown request keys: {sorted(unknown)}")
+        raw = payload.get("config")
+        requested_profile = payload.get("profile")
+        requested_account = payload.get("account")
+        if requested_profile is not None and requested_account is not None:
+            if requested_profile != requested_account:
+                raise HTTPException(422, "profile and account selections disagree")
+        elif requested_profile is None:
+            requested_profile = requested_account
+        if raw is not None and requested_profile is not None:
+            raise HTTPException(422, "choose either config or profile")
+        if requested_profile is not None:
+            if not isinstance(requested_profile, str):
+                raise HTTPException(404, _PROFILE_UNAVAILABLE)
+            return load_profile(requested_profile)
+        if raw is None:
+            if selected_profile is not None:
+                return engine
+            raise HTTPException(422, "config must be a JSON object or profile must be selected")
+        if not isinstance(raw, dict):
+            raise HTTPException(422, "config must be a JSON object")
+        try:
+            return RateEngine(Config.from_dict(raw))
+        except (ConfigError, DataError) as exc:
+            raise HTTPException(422, str(exc)) from exc
+
+    def request_timestamp(raw: object, name: str) -> datetime:
+        if not isinstance(raw, str):
+            raise HTTPException(422, f"{name} must be an ISO 8601 string")
+        try:
+            parsed = datetime.fromisoformat(raw)
+        except ValueError as exc:
+            raise HTTPException(422, f"{name} must be an ISO 8601 string") from exc
+        if parsed.tzinfo is None:
+            raise HTTPException(422, f"{name} must include a UTC offset")
+        return parsed
+
+    app = FastAPI(
+        title="tariffkit",
+        summary="PG&E E-ELEC import/export prices under NEM 3.0",
+        version=_version(),
+    )
+
+    @app.get("/v1/healthz")
+    def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/v1/meta")
+    def meta() -> dict[str, Any]:
+        try:
+            return engine.describe()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+
+    @app.post("/v1/meta")
+    def configured_meta(payload: dict[str, Any] = Body()) -> dict[str, Any]:
+        try:
+            return request_engine(payload, allowed={"config", "profile", "account"}).describe()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+
+    @app.get("/v1/price/now")
+    def price_now() -> dict[str, Any]:
+        try:
+            return engine.price_now().to_dict()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+
+    @app.post("/v1/price/now")
+    def configured_price_now(payload: dict[str, Any] = Body()) -> dict[str, Any]:
+        try:
+            return (
+                request_engine(payload, allowed={"config", "profile", "account"})
+                .price_now()
+                .to_dict()
+            )
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+
+    @app.get("/v1/price/at")
+    def price_at(
+        ts: datetime = Query(description="ISO 8601 timestamp with offset"),
+    ) -> dict[str, Any]:
+        if ts.tzinfo is None:
+            raise HTTPException(422, "ts must include a UTC offset, e.g. 2026-09-15T19:00-07:00")
+        try:
+            return engine.price_at(ts).to_dict()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except OutOfRangeError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except DataError as exc:
+            raise HTTPException(422, str(exc)) from exc
+
+    @app.post("/v1/price/at")
+    def configured_price_at(payload: dict[str, Any] = Body()) -> dict[str, Any]:
+        request = request_engine(payload, allowed={"config", "profile", "account", "ts"})
+        ts = request_timestamp(payload.get("ts"), "ts")
+        try:
+            return request.price_at(ts).to_dict()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except OutOfRangeError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except DataError as exc:
+            raise HTTPException(422, str(exc)) from exc
+
+    @app.get("/v1/forecast")
+    def forecast(
+        hours: int = Query(24, ge=1, le=MAX_FORECAST_HOURS),
+        start: datetime | None = Query(None, description="defaults to the current hour"),
+    ) -> dict[str, Any]:
+        if start is not None and start.tzinfo is None:
+            raise HTTPException(422, "start must include a UTC offset")
+        try:
+            return engine.forecast(hours=hours, start=start).to_dict()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except OutOfRangeError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except DataError as exc:
+            raise HTTPException(422, str(exc)) from exc
+
+    @app.post("/v1/forecast")
+    def configured_forecast(payload: dict[str, Any] = Body()) -> dict[str, Any]:
+        request = request_engine(
+            payload, allowed={"config", "profile", "account", "hours", "start"}
+        )
+        hours = payload.get("hours", 24)
+        if not isinstance(hours, int) or isinstance(hours, bool):
+            raise HTTPException(422, "hours must be an integer")
+        if not 1 <= hours <= MAX_FORECAST_HOURS:
+            raise HTTPException(422, f"hours must be between 1 and {MAX_FORECAST_HOURS}")
+        raw_start = payload.get("start")
+        start = request_timestamp(raw_start, "start") if raw_start is not None else None
+        try:
+            return request.forecast(hours=hours, start=start).to_dict()
+        except AccountError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except OutOfRangeError as exc:
+            raise HTTPException(404, str(exc)) from exc
+        except DataError as exc:
+            raise HTTPException(422, str(exc)) from exc
+
+    return app
+
+
+def _version() -> str:
+    from .. import __version__
+
+    return __version__