tariffkit 0.2.2__tar.gz → 0.3.0__tar.gz

{tariffkit-0.2.2 → tariffkit-0.3.0}/CHANGELOG.md

@@ -5,6 +5,68 @@ All notable changes to this project are documented here. This project follows
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-22
+
+### Added
+- PG&E's complete active single-family residential lineup is now covered:
+  generated E-1 and E-TOU-D snapshots join E-ELEC, E-TOU-C, and EV2-A.
+  E-1 preserves tiered baseline billing while exposing the over-baseline
+  marginal price, and E-TOU-D observes its weekday-only 5–8 p.m. peak and
+  tariff holiday calendar.
+- Generated, effective-dated D-CARE, D-MEDICAL, Rule 19 Medical Baseline, and
+  E-RSMART data now drive residential program adjustments. SmartRate accepts
+  explicit announced event dates and marks prices beyond the authoritative
+  event horizon incomplete rather than guessing future events.
+- Prices now decompose into a fixed set of chartable component groups —
+  generation, distribution, transmission, surcharges, credits, and a catch-all
+  other on the import side; generation, delivery, credits, and other on the
+  export side. The groups sum back to the price they came from and do not vary
+  with the tariff, supplier, or discount, so a chart built against them
+  survives an account change. `ImportPrice.grouped()`, `ExportPrice.grouped()`,
+  a `groups` key in every `to_dict` payload, and `tariffkit.components` expose
+  them to library and REST callers.
+- Home Assistant gains a sensor per component group in each direction, and the
+  forecast's `rates` attribute carries the same roll-up per hour, so both the
+  recorded past and the next 48 hours can be drawn as stacked charts -- one
+  card each, because stacking recorded and forecast points together would
+  double-count the current hour. The MQTT publisher publishes the same series
+  with matching discovery payloads, each band carrying its price's quality
+  flags.
+- Home Assistant now exposes the AB 205 Base Services Charge as **Daily Fixed
+  Charge** in `USD/day`. The unit keeps it out of the Energy dashboard's price
+  pickers and out of any `USD/kWh` stack, which is why it can be published at
+  all: it is a fixed daily amount, not a marginal price.
+
+### Changed
+- Home Assistant now offers every active PG&E residential schedule and
+  Medical Baseline configuration while preserving existing profile and entity
+  identities.
+
+### Fixed
+- Predbat attributes now use its `from` / `to` / `rate` contract for values
+  already expressed in cents. Predbat no longer interprets TariffKit's cents as
+  currency units and multiplies them by 100, while Pacific-midnight anchoring
+  and complete 46-, 48-, and 50-slot tariff days remain unchanged.
+
+## [0.2.3] - 2026-08-17
+
+### Changed
+- Pacific Gas and Electric now has the unambiguous machine identifier
+  `pacific_gas_and_electric`, while Home Assistant and MQTT present `PG&E` or
+  the full company name. The separate `pge` identifier correctly means Portland
+  General Electric and is recognized but explicitly unsupported for pricing,
+  preventing it from ever selecting California tariff data.
+- Home Assistant now labels the export-minus-import calculation explicitly,
+  translates time-of-use states for display, and presents the forecast horizon
+  as **Rates Available Through**. Forecast metadata and a new **Rate Data
+  Status** entity are grouped under diagnostics, where PTO date, export lock
+  end, NBT vintage, tariff provenance, source, and quality flags explain the
+  active rates without crowding the primary price controls.
+
+### Fixed
+- The PyPI project page now loads the TariffKit banner from an absolute URL
+  instead of an unresolved repository-relative path.
+
 ## [0.2.2] - 2026-08-16
 
 ### Added
@@ -221,7 +283,9 @@ Initial release.
 - Holiday calendars are extracted per vintage from the source data rather than
   recomputed, because the vintage files disagree in far-future years.
 
-[Unreleased]: https://github.com/eman/tariffkit/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/eman/tariffkit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/eman/tariffkit/releases/tag/v0.3.0
+[0.2.3]: https://github.com/eman/tariffkit/releases/tag/v0.2.3
 [0.2.2]: https://github.com/eman/tariffkit/releases/tag/v0.2.2
 [0.2.1]: https://github.com/eman/tariffkit/releases/tag/v0.2.1
 [0.2.0]: https://github.com/eman/tariffkit/releases/tag/v0.2.0

{tariffkit-0.2.2 → tariffkit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tariffkit
-Version: 0.2.2
+Version: 0.3.0
 Summary: Offline electricity tariff pricing, billing, and integration tools
 Project-URL: Homepage, https://github.com/eman/tariffkit
 Project-URL: Documentation, https://github.com/eman/tariffkit#documentation
@@ -44,7 +44,7 @@ Requires-Dist: uvicorn[standard]>=0.29; extra == 'web'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
+  <img src="https://raw.githubusercontent.com/eman/tariffkit/main/images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
 </p>
 
 # TariffKit
@@ -59,8 +59,10 @@ integrations. The first data provider supports PG&E residential rate plans under
 **NEM 3.0 / the Net Billing Tariff (NBT)**; the package identity is deliberately
 not tied to one utility or tariff program.
 
-Three schedules are vendored: **E-ELEC** (Electric Home), **E-TOU-C**
-(Time-of-Use, peak 4–9 p.m. every day), and **EV2-A** (Home Charging).
+The complete active single-family residential portfolio is vendored:
+**E-1**, **E-ELEC**, **E-TOU-C**, **E-TOU-D**, and **EV2-A**. CARE, FERA,
+Medical Baseline/D-MEDICAL, and event-injected SmartRate adjustments are
+modeled separately from their underlying plans.
 
 Under NBT your export credit is not a time-of-use schedule: it is an hourly
 Avoided Cost Calculator value that swings from about $0.06/kWh at midday to
@@ -92,9 +94,9 @@ component. `tariffkit` collapses it at build time, verifying losslessness cell b
 cell, so the entire five-vintage dataset ships inside the wheel at **268 KiB**
 and every lookup is a few list indexes.
 
-The retail side is similar: these schedules' period boundaries are identical every day
-of the week including holidays and do not shift by season, so an import price is
-fully determined by `(season, hour)`.
+The retail side is similar: generated effective-dated tables hold every active
+schedule. E-TOU-D additionally selects weekday versus weekend/observed-holiday
+periods from the vendored tariff calendar.
 
 Nothing here touches the network at runtime.
 
@@ -108,7 +110,9 @@ Nothing here touches the network at runtime.
 | [Bill calculator](docs/billing.md) | Computing a cycle from interval meter data |
 | [MQTT](docs/mqtt.md) | Publishing, with Home Assistant discovery |
 | [REST API](docs/web.md) | HTTP service |
-| [Home Assistant](docs/home-assistant.md) | Custom component, Energy dashboard, account history, response actions, opt-in Predbat |
+| [Home Assistant](docs/home-assistant.md) | Custom component, Energy dashboard, stacked component charts, account history, response actions, opt-in Predbat |
+| [Predbat](docs/predbat.md) | Installing TariffKit and Predbat together, end to end |
+| [Predbat on Sigenergy](docs/predbat-sigenergy.md) | Sigenergy SigenStor specifics: entity mapping, sign and unit conversions, control |
 | [Home Assistant quality checklist](docs/home-assistant-quality.md) | Self-assessment against the Integration Quality Scale, with exemptions |
 | [Containers](docs/containers.md) | Local Home Assistant development stack and API/MQTT deployment proposal |
 | [Maintaining rate data](docs/data.md) | Regenerating export rates, updating the retail tariff and CCA cards |

{tariffkit-0.2.2 → tariffkit-0.3.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
+  <img src="https://raw.githubusercontent.com/eman/tariffkit/main/images/banner.svg" alt="TariffKit — electricity pricing, billing, and energy integrations" width="100%">
 </p>
 
 # TariffKit
@@ -14,8 +14,10 @@ integrations. The first data provider supports PG&E residential rate plans under
 **NEM 3.0 / the Net Billing Tariff (NBT)**; the package identity is deliberately
 not tied to one utility or tariff program.
 
-Three schedules are vendored: **E-ELEC** (Electric Home), **E-TOU-C**
-(Time-of-Use, peak 4–9 p.m. every day), and **EV2-A** (Home Charging).
+The complete active single-family residential portfolio is vendored:
+**E-1**, **E-ELEC**, **E-TOU-C**, **E-TOU-D**, and **EV2-A**. CARE, FERA,
+Medical Baseline/D-MEDICAL, and event-injected SmartRate adjustments are
+modeled separately from their underlying plans.
 
 Under NBT your export credit is not a time-of-use schedule: it is an hourly
 Avoided Cost Calculator value that swings from about $0.06/kWh at midday to
@@ -47,9 +49,9 @@ component. `tariffkit` collapses it at build time, verifying losslessness cell b
 cell, so the entire five-vintage dataset ships inside the wheel at **268 KiB**
 and every lookup is a few list indexes.
 
-The retail side is similar: these schedules' period boundaries are identical every day
-of the week including holidays and do not shift by season, so an import price is
-fully determined by `(season, hour)`.
+The retail side is similar: generated effective-dated tables hold every active
+schedule. E-TOU-D additionally selects weekday versus weekend/observed-holiday
+periods from the vendored tariff calendar.
 
 Nothing here touches the network at runtime.
 
@@ -63,7 +65,9 @@ Nothing here touches the network at runtime.
 | [Bill calculator](docs/billing.md) | Computing a cycle from interval meter data |
 | [MQTT](docs/mqtt.md) | Publishing, with Home Assistant discovery |
 | [REST API](docs/web.md) | HTTP service |
-| [Home Assistant](docs/home-assistant.md) | Custom component, Energy dashboard, account history, response actions, opt-in Predbat |
+| [Home Assistant](docs/home-assistant.md) | Custom component, Energy dashboard, stacked component charts, account history, response actions, opt-in Predbat |
+| [Predbat](docs/predbat.md) | Installing TariffKit and Predbat together, end to end |
+| [Predbat on Sigenergy](docs/predbat-sigenergy.md) | Sigenergy SigenStor specifics: entity mapping, sign and unit conversions, control |
 | [Home Assistant quality checklist](docs/home-assistant-quality.md) | Self-assessment against the Integration Quality Scale, with exemptions |
 | [Containers](docs/containers.md) | Local Home Assistant development stack and API/MQTT deployment proposal |
 | [Maintaining rate data](docs/data.md) | Regenerating export rates, updating the retail tariff and CCA cards |

{tariffkit-0.2.2 → tariffkit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tariffkit"
-version = "0.2.2"
+version = "0.3.0"
 description = "Offline electricity tariff pricing, billing, and integration tools"
 readme = "README.md"
 license = "MIT"

{tariffkit-0.2.2 → tariffkit-0.3.0}/src/tariffkit/__init__.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 from importlib.metadata import version
 
+from .components import ComponentGroup
 from .config import CcaConfig, Config
 from .engine import RateEngine
 from .errors import ConfigError, DataError, OutOfRangeError, TariffKitError
@@ -25,6 +26,7 @@ from .models import (
     Season,
     Supplier,
     TouPeriod,
+    Utility,
 )
 from .timeutil import PACIFIC, DayType, now_pacific
 
@@ -33,6 +35,7 @@ __version__ = version("tariffkit")
 __all__ = [
     "PACIFIC",
     "CcaConfig",
+    "ComponentGroup",
     "Config",
     "ConfigError",
     "DataError",
@@ -47,6 +50,7 @@ __all__ = [
     "Supplier",
     "TariffKitError",
     "TouPeriod",
+    "Utility",
     "__version__",
     "now_pacific",
 ]

{tariffkit-0.2.2 → tariffkit-0.3.0}/src/tariffkit/billing/engine.py

@@ -21,6 +21,7 @@ from ..config import Config
 from ..engine import RateEngine
 from ..errors import DataError
 from ..models import ImportPrice, Season, TouPeriod
+from ..tariff.retail import load_program
 from ..timeutil import PACIFIC, hour_floor, to_pacific
 from .models import Bill, BillingPeriod, IntervalReading, UsageBucket
 from .netting import check_coverage
@@ -139,6 +140,9 @@ class BillEngine:
         credit = self._baseline_credit(in_period, period)
         if credit:
             import_components["baseline_credit"] = credit
+        smart_rate_credit = self._smartrate_credit(in_period, period)
+        if smart_rate_credit:
+            import_components["smartrate_credit"] = smart_rate_credit
 
         if uncompensated:
             warnings.append(
@@ -300,6 +304,28 @@ class BillEngine:
                 break
         return credit
 
+    def _smartrate_credit(
+        self, readings: Sequence[IntervalReading], period: BillingPeriod
+    ) -> float:
+        """Credits non-high-price imports once for each SmartDay in the cycle."""
+        config = self.rates.config
+        if not config.smartrate:
+            return 0.0
+        events = {event for event in config.smartrate_events if period.start <= event <= period.end}
+        if not events:
+            return 0.0
+        terms = load_program("ersmart", period.end)
+        start = int(terms["high_price_start"])
+        end = int(terms["high_price_end"])
+        eligible = 0.0
+        for reading in readings:
+            moment = to_pacific(reading.start)
+            if moment.date() in events and start <= moment.hour < end:
+                continue
+            eligible += reading.imported
+        credit = float(terms["program_credit"]) + float(terms["participation_credit"])
+        return -eligible * credit * len(events)
+
     def _fixed_charges(self, period: BillingPeriod) -> dict[str, float]:
         """Charges billed per day rather than per kWh.
 

{tariffkit-0.2.2 → tariffkit-0.3.0}/src/tariffkit/cca.py

@@ -15,6 +15,7 @@ from typing import Any
 
 from .data import versioned
 from .errors import ConfigError, DataError
+from .models import Utility
 
 
 @dataclass(frozen=True, slots=True)
@@ -32,6 +33,11 @@ class CcaRateCard:
     def source_url(self) -> str:
         return str(self.raw.get("source_url", ""))
 
+    @property
+    def supported_schedules(self) -> frozenset[str]:
+        """PG&E schedule slugs for which this card publishes generation rates."""
+        return frozenset(self.raw["generation"])
+
     def generation(
         self, schedule: str, season: str, period: str, option: str = "light_green"
     ) -> float:
@@ -115,7 +121,12 @@ def load_rate_card(provider: str, on: date) -> CcaRateCard:
         ) from exc
     if version.raw.get("schema") != 1:
         raise DataError(f"{provider}: unsupported rate card schema {version.raw.get('schema')}")
-    return CcaRateCard(provider=str(version.raw["provider"]), raw=version.raw)
+    raw = dict(version.raw)
+    try:
+        raw["utility"] = Utility(raw["utility"]).value
+    except (KeyError, ValueError) as exc:
+        raise DataError(f"{provider}: invalid utility identifier") from exc
+    return CcaRateCard(provider=str(raw["provider"]), raw=raw)
 
 
 def available_rate_cards() -> tuple[str, ...]:

tariffkit-0.3.0/src/tariffkit/components.py

@@ -0,0 +1,200 @@
+"""Rolling unbundled tariff components up into a fixed, stackable vocabulary.
+
+A price's ``components`` mapping speaks the tariff sheet's own language: fifteen
+or so import lines on a bundled residential schedule, a different set once a CCA
+supplies generation, and another line again when a CARE discount or a SmartRate
+event applies. That is exactly the right level for reconciling a statement, and
+exactly the wrong level for a chart -- a fifteen-band stack is unreadable, and
+a consumer that made one series per line would watch series appear and vanish as
+the account's configuration changed.
+
+The groups below are a small closed vocabulary that every component maps into.
+Two properties make them safe to draw as a stacked graph against the price
+itself:
+
+* the set of groups for a direction is fixed, so the series exist whether or not
+  the account happens to pay that kind of charge this hour; and
+* every component lands in exactly one group -- anything this table has not seen
+  falls into :attr:`ComponentGroup.OTHER` rather than being dropped -- so the
+  groups sum back to the price, within per-component rounding.
+
+Grouping is a presentation, not a billing rule. ``tariffkit.billing.ledger``
+classifies the same components again, differently and for a different purpose:
+which export credits may offset which charges. Neither is derived from the
+other, because being drawn in the same band of a chart and being offsettable by
+the same credit bucket are unrelated questions.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from enum import StrEnum
+
+
+class ComponentGroup(StrEnum):
+    """A band in a stacked price chart."""
+
+    #: Generation supply, whoever supplies it, plus the charges that follow the
+    #: supply decision: the PCIA a departed customer pays, the bundled PCIA
+    #: credit a PG&E-supplied one receives, a CCA's own cost relief credit, and
+    #: a SmartRate event's high-price energy charge.
+    GENERATION = "generation"
+    #: Distribution, and the Conservation Incentive Adjustment that implements
+    #: the baseline credit as a distribution-side rate spread.
+    DISTRIBUTION = "distribution"
+    #: Transmission, its rate adjustments, and reliability services.
+    TRANSMISSION = "transmission"
+    #: The export side's delivery component. PG&E publishes the export rate as
+    #: exactly two components -- delivery, which every Solar Billing Plan
+    #: customer earns, and generation, which only a bundled one does. Delivery
+    #: is not published split into distribution and transmission, so it gets its
+    #: own band rather than being apportioned across two on a guess.
+    DELIVERY = "delivery"
+    #: Non-bypassable charges and riders: public purpose programs, nuclear
+    #: decommissioning, competition transition, energy cost recovery, the
+    #: wildfire fund and hardening charges, new system generation, the recovery
+    #: bond charge and its offsetting credit, and the CCA franchise fee.
+    SURCHARGES = "surcharges"
+    #: Discounts and incentives: CARE, FERA, Medical Baseline, and the ACC Plus
+    #: adder on the export side.
+    CREDITS = "credits"
+    #: Anything this module has not classified. Normally zero; non-zero means a
+    #: schedule grew a line and this table has not caught up.
+    OTHER = "other"
+
+    @property
+    def label(self) -> str:
+        """Human-readable name, for interfaces without their own translations."""
+        match self:
+            case ComponentGroup.GENERATION:
+                return "Generation"
+            case ComponentGroup.DISTRIBUTION:
+                return "Distribution"
+            case ComponentGroup.TRANSMISSION:
+                return "Transmission"
+            case ComponentGroup.DELIVERY:
+                return "Delivery"
+            case ComponentGroup.SURCHARGES:
+                return "Surcharges"
+            case ComponentGroup.CREDITS:
+                return "Credits"
+            case ComponentGroup.OTHER:
+                return "Other"
+
+
+#: The groups an import price is drawn from, in stack order: supply at the
+#: bottom, then wires, then policy charges, then whatever reduces the bill.
+IMPORT_GROUPS: tuple[ComponentGroup, ...] = (
+    ComponentGroup.GENERATION,
+    ComponentGroup.DISTRIBUTION,
+    ComponentGroup.TRANSMISSION,
+    ComponentGroup.SURCHARGES,
+    ComponentGroup.CREDITS,
+    ComponentGroup.OTHER,
+)
+
+#: The groups an export credit is drawn from. The ACC has no retail wires or
+#: policy charges in it -- there is nothing to bill a customer who is exporting.
+EXPORT_GROUPS: tuple[ComponentGroup, ...] = (
+    ComponentGroup.GENERATION,
+    ComponentGroup.DELIVERY,
+    ComponentGroup.CREDITS,
+    ComponentGroup.OTHER,
+)
+
+#: Component name -> group. Import and export names share one table because the
+#: names that appear on both sides mean the same thing on both sides.
+COMPONENT_GROUPS: dict[str, ComponentGroup] = {
+    # Generation supply and the charges attached to who supplies it.
+    "generation": ComponentGroup.GENERATION,
+    "cca_generation": ComponentGroup.GENERATION,
+    "cca_cost_relief_credit": ComponentGroup.GENERATION,
+    "cca_solar_bonus": ComponentGroup.GENERATION,
+    "bundled_pcia": ComponentGroup.GENERATION,
+    "pcia": ComponentGroup.GENERATION,
+    "smartrate_high_price": ComponentGroup.GENERATION,
+    # Distribution.
+    "distribution": ComponentGroup.DISTRIBUTION,
+    "conservation_incentive_adjustment": ComponentGroup.DISTRIBUTION,
+    # Transmission.
+    "transmission": ComponentGroup.TRANSMISSION,
+    "transmission_rate_adjustments": ComponentGroup.TRANSMISSION,
+    "reliability_services": ComponentGroup.TRANSMISSION,
+    # Export-side avoided delivery.
+    "delivery": ComponentGroup.DELIVERY,
+    # Non-bypassable charges and riders.
+    "public_purpose_programs": ComponentGroup.SURCHARGES,
+    "nuclear_decommissioning": ComponentGroup.SURCHARGES,
+    "competition_transition_charges": ComponentGroup.SURCHARGES,
+    "energy_cost_recovery": ComponentGroup.SURCHARGES,
+    "wildfire_fund_charge": ComponentGroup.SURCHARGES,
+    "wildfire_hardening": ComponentGroup.SURCHARGES,
+    "new_system_generation": ComponentGroup.SURCHARGES,
+    "recovery_bond_charge": ComponentGroup.SURCHARGES,
+    # Paired with the charge above, which it currently offsets exactly. Keeping
+    # the pair in one group means the band shows the net, rather than inflating
+    # surcharges and inventing an equal and opposite credit.
+    "recovery_bond_credit": ComponentGroup.SURCHARGES,
+    "franchise_fee_surcharge": ComponentGroup.SURCHARGES,
+    # Discounts and incentives.
+    "medical_discount": ComponentGroup.CREDITS,
+    "acc_plus": ComponentGroup.CREDITS,
+    # Bill-level components. A marginal price never carries these -- a baseline
+    # credit depends on cumulative usage, and a tax on a whole cycle's charges
+    # -- but ``group_of`` is public, so a caller grouping a ``Bill``'s
+    # breakdown gets the same answers rather than a pile of ``OTHER``. The Base
+    # Services Charge is deliberately absent: it is a $/day amount, and there
+    # is no band of a per-kWh chart it honestly belongs in.
+    "energy_commission_tax": ComponentGroup.SURCHARGES,
+    "baseline_credit": ComponentGroup.DISTRIBUTION,
+    "smartrate_credit": ComponentGroup.GENERATION,
+}
+
+#: The discount component is named for the program applied (``care_discount``,
+#: ``fera_discount``), so the suffix is matched rather than every program being
+#: enumerated -- a new discount program should not silently land in ``OTHER``.
+_DISCOUNT_SUFFIX = "_discount"
+
+
+def group_of(name: str) -> ComponentGroup:
+    """The group ``name`` belongs to, or ``OTHER`` if it is unrecognized."""
+    group = COMPONENT_GROUPS.get(name)
+    if group is not None:
+        return group
+    if name.endswith(_DISCOUNT_SUFFIX):
+        return ComponentGroup.CREDITS
+    return ComponentGroup.OTHER
+
+
+def split_components(
+    components: Mapping[str, float],
+    groups: Iterable[ComponentGroup],
+) -> dict[ComponentGroup, dict[str, float]]:
+    """Bucket ``components`` by group, keeping each group's underlying lines.
+
+    Every group in ``groups`` is present, empty if nothing landed in it, so a
+    consumer builds the same series every time. A component whose group is not
+    among ``groups`` is folded into ``OTHER`` instead of being dropped, which
+    keeps the sum identity true even if a direction ever grows a line from a
+    band it was not expected to have.
+    """
+    ordered = tuple(groups)
+    buckets: dict[ComponentGroup, dict[str, float]] = {group: {} for group in ordered}
+    for name, value in components.items():
+        group = group_of(name)
+        if group not in buckets:
+            group = ComponentGroup.OTHER
+            buckets.setdefault(group, {})
+        buckets[group][name] = value
+    return buckets
+
+
+def group_components(
+    components: Mapping[str, float],
+    groups: Iterable[ComponentGroup],
+) -> dict[ComponentGroup, float]:
+    """``components`` summed per group, one entry per group in ``groups``."""
+    return {
+        group: round(float(sum(lines.values())), 6)
+        for group, lines in split_components(components, groups).items()
+    }

{tariffkit-0.2.2 → tariffkit-0.3.0}/src/tariffkit/config.py

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, Literal
 
 from .errors import ConfigError
-from .models import Supplier
+from .models import Supplier, Utility
 
 AccPlusSegment = Literal["residential", "residential_low_income", "none"]
 Discount = Literal["none", "care", "fera"]
@@ -32,6 +32,15 @@ LOCK_YEARS = 9
 _ONE_DAY = timedelta(days=1)
 
 
+def _env_bool(name: str, value: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    raise ConfigError(f"{name} must be true or false")
+
+
 @dataclass(frozen=True, slots=True)
 class CcaConfig:
     """Settings for customers whose generation comes from a CCA or ESP.
@@ -80,7 +89,7 @@ class CcaConfig:
 class Config:
     """Everything needed to price a kWh for one service agreement."""
 
-    utility: str = "PGE"
+    utility: Utility = Utility.PACIFIC_GAS_AND_ELECTRIC
     tariff: str = "E-ELEC"
     supplier: Supplier = Supplier.BUNDLED
 
@@ -104,6 +113,17 @@ class Config:
     #: electric. PG&E prints this as Code B or Code H; the bill's "Heat Source"
     #: line says which.
     baseline_code: BaselineCode = "basic"
+    #: Medical Baseline enrollment. Tiered schedules receive additional
+    #: baseline quantity; E-ELEC, E-TOU-D, and EV2-A receive D-MEDICAL.
+    medical_baseline: bool = False
+    medical_kwh_per_day: float | None = None
+
+    #: SmartRate is event-driven. Event dates and the date through which the
+    #: supplied calendar is authoritative are explicit so a missing future
+    #: event cannot be silently priced as an ordinary day.
+    smartrate: bool = False
+    smartrate_events: tuple[date, ...] = ()
+    smartrate_known_through: date | None = None
 
     cca: CcaConfig | None = None
 
@@ -117,6 +137,7 @@ class Config:
     nsc_rate: float | None = None
 
     def __post_init__(self) -> None:
+        object.__setattr__(self, "utility", Utility(self.utility))
         # Coerce the string forms of the enums. Supplier is a StrEnum, so a
         # plain "cca" compares equal to Supplier.CCA but is not it -- and every
         # branch that matters tests identity. Constructing Config directly with
@@ -133,6 +154,18 @@ class Config:
         object.__setattr__(self, "supplier", Supplier(self.supplier))
         if self.supplier is Supplier.CCA and self.cca is None:
             raise ConfigError("supplier='cca' requires a CcaConfig")
+        if self.smartrate and self.supplier is not Supplier.BUNDLED:
+            raise ConfigError("SmartRate is available only with bundled PG&E generation")
+        if self.smartrate_events and not self.smartrate:
+            raise ConfigError("smartrate_events requires smartrate=true")
+        if self.smartrate and self.smartrate_known_through is None:
+            raise ConfigError("smartrate=true requires smartrate_known_through")
+        if self.smartrate_known_through is not None and any(
+            event > self.smartrate_known_through for event in self.smartrate_events
+        ):
+            raise ConfigError("a SmartRate event falls after smartrate_known_through")
+        if self.medical_kwh_per_day is not None and self.medical_kwh_per_day <= 0:
+            raise ConfigError("medical_kwh_per_day must be greater than zero")
         if self.vintage is None and self.interconnection_year is None:
             raise ConfigError("set either interconnection_year or vintage")
         if self.discount != "none" and self.acc_plus_segment == "residential":
@@ -188,6 +221,15 @@ class Config:
             value = data.get("pto_date")
             if isinstance(value, str):
                 data["pto_date"] = date.fromisoformat(value)
+            value = data.get("smartrate_known_through")
+            if isinstance(value, str):
+                data["smartrate_known_through"] = date.fromisoformat(value)
+            events = data.get("smartrate_events")
+            if isinstance(events, list | tuple):
+                data["smartrate_events"] = tuple(
+                    date.fromisoformat(value) if isinstance(value, str) else value
+                    for value in events
+                )
             return cls(**data)
         except (TypeError, ValueError) as exc:
             raise ConfigError(f"invalid config: {exc}") from exc
@@ -195,7 +237,7 @@ class Config:
     def to_dict(self) -> dict[str, Any]:
         """A JSON-compatible representation suitable for API request bodies."""
         data: dict[str, Any] = {
-            "utility": self.utility,
+            "utility": self.utility.value,
             "tariff": self.tariff,
             "supplier": self.supplier.value,
             "interconnection_year": self.interconnection_year,
@@ -206,6 +248,15 @@ class Config:
             "base_services_charge_tier": self.base_services_charge_tier,
             "baseline_territory": self.baseline_territory,
             "baseline_code": self.baseline_code,
+            "medical_baseline": self.medical_baseline,
+            "medical_kwh_per_day": self.medical_kwh_per_day,
+            "smartrate": self.smartrate,
+            "smartrate_events": [event.isoformat() for event in self.smartrate_events],
+            "smartrate_known_through": (
+                self.smartrate_known_through.isoformat()
+                if self.smartrate_known_through is not None
+                else None
+            ),
             "nsc_rate": self.nsc_rate,
         }
         if self.cca is not None:
@@ -261,6 +312,18 @@ class Config:
             overrides["baseline_territory"] = value
         if value := os.environ.get("TARIFFKIT_BASELINE_CODE"):
             overrides["baseline_code"] = value
+        if value := os.environ.get("TARIFFKIT_MEDICAL_BASELINE"):
+            overrides["medical_baseline"] = _env_bool("TARIFFKIT_MEDICAL_BASELINE", value)
+        if value := os.environ.get("TARIFFKIT_MEDICAL_KWH_PER_DAY"):
+            overrides["medical_kwh_per_day"] = float(value)
+        if value := os.environ.get("TARIFFKIT_SMARTRATE"):
+            overrides["smartrate"] = _env_bool("TARIFFKIT_SMARTRATE", value)
+        if value := os.environ.get("TARIFFKIT_SMARTRATE_EVENTS"):
+            overrides["smartrate_events"] = tuple(
+                date.fromisoformat(item.strip()) for item in value.split(",") if item.strip()
+            )
+        if value := os.environ.get("TARIFFKIT_SMARTRATE_KNOWN_THROUGH"):
+            overrides["smartrate_known_through"] = date.fromisoformat(value)
         if value := os.environ.get("TARIFFKIT_NSC_RATE"):
             overrides["nsc_rate"] = float(value)
         if value := os.environ.get("TARIFFKIT_CCA_JSON"):

{tariffkit-0.2.2 → tariffkit-0.3.0}/src/tariffkit/data/cca/mce/2023-01-01.toml

@@ -16,7 +16,7 @@
 schema = 1
 provider = "MCE"
 name = "Marin Clean Energy"
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 schedules = ["E-ELEC", "E-TOU-C", "EV2-A"]
 effective = "2023-01-01"
 currency = "USD/kWh"

{tariffkit-0.2.2 → tariffkit-0.3.0}/src/tariffkit/data/cca/mce/2026-04-01.toml

@@ -49,7 +49,7 @@
 schema = 1
 provider = "MCE"
 name = "Marin Clean Energy"
-utility = "PGE"
+utility = "pacific_gas_and_electric"
 #: MCE prices each PG&E schedule separately, so a rate card is keyed by schedule
 #: rather than tied to one. Slugs match the tariff data directories.
 schedules = ["E-ELEC", "E-TOU-C", "EV2-A"]