tariffkit 0.2.0__tar.gz

tariffkit-0.2.0/.gitignore

@@ -0,0 +1,33 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+.env.bak*
+
+# One real account's tariff history. audit/account.example.toml is the template.
+audit/account.toml
+
+# Statements carry a name, an address, an account number and a year of usage.
+# They are read wherever they already sit and never committed; the audit tests
+# use synthetic fixtures instead. Downloads land in .cache/, ignored above.
+*.pdf
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Upstream archives and documents fetched by `python -m tools.regen` — large, not
+# vendored. Also where downloaded statements and Green Button exports land.
+# The normalized outputs under src/tariffkit/data/ ARE committed.
+/.cache/
+*.zip
+!tests/fixtures/*.zip
+
+.DS_Store

tariffkit-0.2.0/CHANGELOG.md

@@ -0,0 +1,172 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-16
+
+### Added
+- **Named, effective-dated account profiles** track tariff, supplier, baseline,
+  export, and credential-set changes over a service agreement's lifetime.
+  Pricing and billing resolve the settings in force at each timestamp, including
+  cycles that cross an account transition. Profile writes are atomic,
+  revision-checked, and locked against concurrent updates.
+- **PG&E statement import and portal synchronization** can populate an account
+  profile from printed facts. Proposed changes are reported as additions,
+  confirmations, conflicts, or missing required values; a statement with a
+  conflict cannot be partially applied. Statement support is available through
+  the `statements` extra, while the account-specific audit harness remains
+  repository-only.
+- **Profile-scoped meter sources** store provider-neutral grid-import and
+  grid-export mappings for Home Assistant and InfluxDB 3. The bill command can
+  query either source directly, with explicit command options taking precedence
+  over profile, environment, and global defaults.
+- **Credential sets backed by the operating-system keyring** hold PG&E, Home
+  Assistant, InfluxDB, and MQTT secrets outside configuration files and command
+  arguments. Environment injection remains available for containers.
+- **A complete billing layer** now covers interval netting, coverage warnings,
+  baseline credits, fixed charges, taxes, export-credit buckets, annual true-up,
+  and CCA cash-out. Credits retain their printed statement scope instead of
+  being treated as one fungible balance.
+- **Home Assistant and InfluxDB 3 interval sources** complement the Green Button
+  reader. Home Assistant reads long-term statistics and prefers five-minute
+  data; InfluxDB derives exact totals from cumulative-counter endpoints and
+  spreads advances across the time in which they accrued.
+- **E-TOU-C and EV2-A retail schedules**, complete PCIA and franchise-fee
+  vintage tables, E-TOU-C baseline allowances, California's electrical-energy
+  surcharge, Net Surplus Compensation data, and effective-dated PG&E and MCE
+  rate snapshots extend pricing and billing beyond the original E-ELEC
+  schedule.
+- **Repository-only rate-data generators** rebuild every vendored dataset from
+  its published source and read the rendered result back through runtime code
+  before writing it. A weekly workflow checks export matrices, retail tariffs,
+  ACC Plus, CCA cards, Net Surplus Compensation, holidays, and the state
+  surcharge for upstream changes.
+- **Home Assistant account-history flows** support staged initial setup and
+  profile inspection, transition editing, statement import, and sanitized
+  profile export. Stable profile-based config-entry identity survives tariff and
+  supplier changes.
+- **Home Assistant response actions** provide current or forecast rates in
+  native and EMHASS shapes for caller-selected windows. Requests reject
+  ambiguous DST-fold timestamps, misaligned windows, and horizons beyond seven
+  days rather than guessing.
+- **Home Assistant diagnostics and integration tests** cover config and options
+  flows, migration, entities, actions, Energy dashboard compatibility,
+  effective-dated provenance, DST handling, and opt-in Predbat output.
+  Diagnostics deliberately omit account history, observations, credentials,
+  and meter mappings.
+- **Pure interoperability adapters** generate EMHASS, Predbat, and generic slot
+  payloads from a `PriceCurve`, shared by Home Assistant and MQTT without either
+  integration becoming a dependency.
+- **Request-scoped REST configuration and account selection** allow callers to
+  price one request against validated settings or a named profile. Unknown
+  configuration keys and credential fields are rejected.
+- **A bind-mounted Home Assistant development stack** runs the custom component
+  and local package source in a real container without publishing a wheel.
+- **A build-once release process and maintainer runbook** synchronize Python,
+  lockfile, Home Assistant, changelog, and documentation versions. One validated
+  wheel/sdist pair moves through optional TestPyPI staging, protected PyPI
+  approval, PEP 740 attestations, and an immutable GitHub release.
+
+### Changed
+- **The project is now TariffKit.** The distribution, import package, CLI,
+  configuration directory, environment prefix, MQTT namespace, repository
+  links, and Home Assistant domain use the utility-neutral `tariffkit` identity.
+  The initial data-provider scope remains PG&E and California.
+- **Packaging remains one public distribution in one repository.** Optional
+  features use extras and lazy imports, leaving the default runtime
+  dependency-free. Rate-data tooling and the account-specific audit harness are
+  excluded from wheel and sdist but retain strict lint, typing, and test
+  coverage.
+- **Python 3.14 is the minimum**, and Home Assistant 2026.3.0 is therefore the
+  integration floor. Development dependencies use PEP 735 groups, package
+  licensing uses an SPDX expression, and installed metadata is the runtime
+  version source.
+- **Home Assistant installs the exact matching TariffKit release** instead of
+  vendoring package source. Its config flow asks only questions made relevant
+  by earlier answers and separates account history from forecast and Predbat
+  options.
+- **Home Assistant entities are lean and recorder-safe.** Import and export
+  price sensors remain compatible with the Energy dashboard, a timestamp entity
+  reports forecast coverage, and large forecast or optimizer payloads are not
+  recorded every minute. The fixed daily charge is no longer represented as a
+  marginal price sensor.
+- **EMHASS forecasts are requested through an action and Predbat output is
+  opt-in.** Neither large payload is computed and attached to every entity when
+  unused.
+- **Pricing provenance and quality are preserved end to end.** Core, CLI, REST,
+  MQTT, and Home Assistant outputs retain `locked`, `exact`, and `complete`
+  states and describe contiguous provenance segments across effective-date
+  boundaries.
+- **Green Button names now describe the format rather than its container.**
+  `read_green_button`, `GreenButtonLayout`, and `--source green-button` replace
+  generic CSV terminology; the legacy source spelling remains accepted.
+- **Strict typing now covers the Home Assistant custom component and all
+  repository tools**, while Ruff enforces function annotations throughout the
+  repository.
+
+### Fixed
+- Production publishing no longer inherits a false implicit failure from the
+  intentionally skipped optional TestPyPI job. The explicit release dependency
+  checks now permit protected PyPI and GitHub publication only after the build
+  and draft jobs themselves succeed.
+- Account-profile updates no longer race between revision checks and filesystem
+  mutation, statement-derived histories reject gaps and overlaps, imported Home
+  Assistant profiles cannot replace an entry's stable identity, and MQTT
+  profile selection respects environment precedence.
+- Baseline credits use each day and vintage's own rate, pre-PTO exports earn no
+  compensation, string supplier values are normalized before branching, and
+  historical pricing never borrows data from a future vintage.
+- CCA generation rates are selected by PG&E schedule instead of silently using
+  E-ELEC values for every plan. PCIA, franchise-fee, MCE generation, cost-relief,
+  and premium data are resolved from their actual effective vintages.
+- Billing coverage and interval stepping use absolute time across both DST
+  transitions. Repeated autumn timestamps are disambiguated during ingest, rate
+  points remain contiguous, and MQTT no longer sleeps through the second 01:00
+  hour.
+- Green Button ingestion handles account preambles, split date/time columns,
+  unit-suffixed headers, explicit offsets, and repeated autumn wall times.
+  Home Assistant and InfluxDB sources report implausible resets and missing
+  coverage instead of inventing plausible energy.
+- Export-rate lookups use each vintage's own holiday calendar and surface
+  publisher drift beyond the verified exact range rather than silently claiming
+  exact future values.
+- Generator parsing no longer drops a PCIA row joined to the next page header,
+  and all generated files are validated through independent runtime readers
+  before replacing vendored data.
+
+## [0.1.0] - 2026-07-28
+
+Initial release.
+
+### Added
+- `RateEngine` with `price_now()`, `price_at()`, and `forecast()` for PG&E
+  E-ELEC import prices and NEM 3.0 / Net Billing Tariff export credits.
+- Vendored rate data for all five NBT vintages (NBT23/24/25/26/00), collapsed
+  from PG&E's ~40 MB-per-vintage hourly files to 268 KiB total with verified
+  lossless round-tripping.
+- ACC Plus adder as a first-class, separately reported component.
+- CCA / Direct Access support: bundled generation and PCIA are dropped, and
+  delivery-only prices are flagged `complete=False` rather than understated.
+- CLI: `now`, `forecast`, `info`, `mqtt`, `serve`.
+- MQTT publisher with Home Assistant MQTT Discovery and a last-will
+  availability topic.
+- FastAPI service under the `web` extra.
+- HACS-installable Home Assistant custom component.
+- `tools/regen_data.py` for refreshing vendored data, plus a weekly CI job that
+  fails when upstream rates change.
+
+### Notes on upstream data
+- PG&E's export files label the repeated 01:00 on the autumn DST transition as
+  `HS2`, so that hour is priced as 2am. Handled in `timeutil.export_hour`.
+- From 2036 onward PG&E's own hour labels stop tracking Pacific daylight time
+  and NBT25/26/00 duplicate some holidays onto the following day. The verified
+  boundary is recorded per vintage as `exact_through` and surfaced as
+  `ExportPrice.exact`. Every year within a nine-year rate lock is exact.
+- 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.0...HEAD
+[0.2.0]: https://github.com/eman/tariffkit/releases/tag/v0.2.0

tariffkit-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emmanuel
+
+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.

tariffkit-0.2.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.5
+Name: tariffkit
+Version: 0.2.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
+Project-URL: Issues, https://github.com/eman/tariffkit/issues
+Project-URL: Source, https://github.com/eman/tariffkit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: battery,energy,home-assistant,nem3,net-billing-tariff,pge,solar,tariff
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: all
+Requires-Dist: fastapi>=0.110; extra == 'all'
+Requires-Dist: httpx>=0.27; extra == 'all'
+Requires-Dist: keyring>=25; extra == 'all'
+Requires-Dist: paho-mqtt>=2.0; extra == 'all'
+Requires-Dist: pypdf>=4.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'all'
+Requires-Dist: websockets>=12; extra == 'all'
+Provides-Extra: ha
+Requires-Dist: websockets>=12; extra == 'ha'
+Provides-Extra: influx
+Requires-Dist: httpx>=0.27; extra == 'influx'
+Provides-Extra: mqtt
+Requires-Dist: paho-mqtt>=2.0; extra == 'mqtt'
+Provides-Extra: pge
+Requires-Dist: httpx>=0.27; extra == 'pge'
+Provides-Extra: secrets
+Requires-Dist: keyring>=25; extra == 'secrets'
+Provides-Extra: statements
+Requires-Dist: pypdf>=4.0; extra == 'statements'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.110; extra == 'web'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'web'
+Description-Content-Type: text/markdown
+
+# TariffKit
+
+An offline electricity tariff engine for pricing, billing, and energy-system
+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).
+
+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
+about $1.19/kWh on an August evening. Knowing what a kWh is worth right now, and
+what it will be worth over the next two days, is the input to every useful
+solar-and-battery dispatch decision.
+
+```python
+from tariffkit import RateEngine
+
+engine = RateEngine()
+point = engine.price_now()
+
+print(point.import_price.total)  # $/kWh to draw from the grid
+print(point.export_price.total)  # $/kWh earned by exporting
+print(point.spread)  # positive => exporting beats self-consuming
+
+curve = engine.forecast(hours=48)
+for hour in curve.best_export_hours(3):
+    print(hour.start, hour.export_price.total)
+```
+
+## Why it works offline
+
+PG&E publishes 20 years of hourly export rates per vintage, as CPUC Resolution
+E-5301 requires (roughly 40 MB of CSV per vintage). But that file is a lossless
+expansion of a 576-cell matrix per year (12 months × 2 day types × 24 hours) per
+component. `tariffkit` collapses it at build time, verifying losslessness cell by
+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)`.
+
+Nothing here touches the network at runtime.
+
+## Documentation
+
+| | |
+|---|---|
+| [Configuration](docs/configuration.md) | Settings, CCA setup, reading your bill |
+| [Library](docs/library.md) | Embedding in Python |
+| [Named account profiles](docs/accounts.md) | Tracking a changing service agreement over time, importing PG&E statements |
+| [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 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 |
+| [Packaging strategy](docs/packaging_strategy.md) | Architecture decision, boundaries, and release model |
+| [Release procedure](docs/releases.md) | Versioning, Trusted Publishing, verification, and recovery |
+
+## Works with
+
+Prices are published in the shapes these already read, via either the custom
+component or the MQTT publisher — no template plumbing on your side. The two
+surfaces differ for EMHASS and Predbat: MQTT always publishes their
+attributes, while the custom component asks for a window on demand and keeps
+Predbat opt-in.
+
+| | Custom component | MQTT |
+|---|---|---|
+| **Home Assistant Energy dashboard** | Import/export price entities | Import/export price entities |
+| **EMHASS** | `tariffkit.get_emhass_forecast` action, called with any window | `load_cost_forecast` / `prod_price_forecast` attributes, always published |
+| **Predbat** | `raw_today` / `raw_tomorrow` attributes, only once enabled in options | `raw_today` / `raw_tomorrow` attributes, always published |
+
+See [docs/home-assistant.md](docs/home-assistant.md) and
+[docs/mqtt.md](docs/mqtt.md) for setup of each.
+
+## Install
+
+```bash
+pip install tariffkit              # core, zero dependencies
+pip install 'tariffkit[mqtt]'      # + MQTT publisher with Home Assistant discovery
+pip install 'tariffkit[web]'       # + FastAPI service
+pip install 'tariffkit[secrets]'   # + OS keyring credential storage
+pip install 'tariffkit[statements]' # + reading local PG&E statement PDFs
+pip install 'tariffkit[all]'
+```
+
+## CLI
+
+```bash
+tariffkit now                          # current import/export price
+tariffkit forecast --hours 48          # the upcoming curve
+tariffkit forecast --format json       # machine-readable
+tariffkit mqtt --broker 192.168.1.100  # publish hourly, with HA discovery
+tariffkit serve                        # REST API on :8000
+tariffkit bill intervals.csv           # compute a cycle from meter data
+tariffkit info                         # which data is loaded, and from where
+tariffkit account init home            # track a service agreement's history
+tariffkit account source home show ha  # inspect profile grid-import/export entities
+```
+
+## Configuration
+
+Defaults target a PG&E-bundled residential customer. Point it at your own
+service agreement via `~/.config/tariffkit/config.toml`:
+
+```toml
+supplier = "bundled"              # or "cca"
+interconnection_year = 2026       # selects the NBT vintage and ACC Plus row
+pto_date = "2026-06-03"           # starts the nine-year rate lock
+acc_plus_segment = "residential"
+base_services_charge_tier = 3
+```
+
+`TARIFFKIT_*` environment variables override any file setting.
+Long-lived PG&E, Home Assistant, InfluxDB, and MQTT credentials can be stored
+outside that file with `tariffkit credentials set`; see
+[Configuration](docs/configuration.md#credentials).
+
+### What the numbers include
+
+- **Import price** is the marginal per-kWh cost: generation + distribution for
+  the season and period, plus the flat riders. The AB 205 Base Services Charge
+  is a fixed $/day amount and is deliberately *excluded*: folding it into a
+  $/kWh figure would corrupt any marginal dispatch decision. Read it separately
+  via `engine.daily_fixed_charge()`.
+- **Export credit** is the generation component plus the delivery component,
+  plus your ACC Plus adder. Values past your nine-year lock are still returned
+  but flagged `locked=False`; PG&E publishes them for illustration only.
+
+### Edge cases in PG&E's published data
+
+Found by round-tripping the vendored matrices against all 1.75 million source
+rows. The library handles each; they are documented because they are surprising.
+
+- **The autumn DST hour.** The fall-back day has 25 real hours but only 24 rate
+  labels. PG&E gives the repeated 01:00 PST the `HS2` label, so it is priced as
+  2am. Pricing it by wall-clock hour returns the wrong value for that hour.
+- **Far-future drift.** From 2036 onward PG&E's own hour labels stop tracking
+  Pacific daylight time, and NBT25/26/00 duplicate some holidays onto the
+  following day. Each vintage records the last year verified exact; prices past
+  it are returned with `exact=False`. Every year inside a nine-year rate lock is
+  exact, and those years are already published as illustrative only.
+- **Vintages disagree about holidays** in those same late years, so the holiday
+  calendar used for a lookup is the one embedded in that vintage's own file.
+- **Only the June 2026 tariff sheets are vendored**, for each of the three
+  schedules. Earlier timestamps raise rather than silently back-dating current
+  rates onto an older billing period.
+- **E-TOU-C's baseline credit is not in the marginal price.** It applies to the
+  first N kWh of a cycle, which is a quantity rather than a time, so `price_at`
+  reports it as `baseline_credit` and the billing engine applies it.
+
+### CCA customers
+
+If a Community Choice Aggregator supplies your generation, PG&E still delivers,
+and under NEM 3.0 you receive **only the delivery component** of the export
+credit from PG&E; generation compensation comes from the CCA.
+
+An MCE rate card is vendored (generation by season/period, the Cost Relief
+Credit, Deep Green premium, and the 10% Solar Bonus Credit):
+
+```toml
+supplier = "cca"
+
+[cca]
+name = "MCE"
+rate_card = "mce"
+pcia_rate = 0.03476                # $/kWh, from your bill
+franchise_fee_surcharge = 0.00042  # $/kWh, from your bill
+```
+
+For other CCAs, supply `generation_rates` directly; see
+[docs/configuration.md](docs/configuration.md). Until generation rates and a
+franchise fee are configured, CCA mode returns delivery-only prices flagged
+`complete = False` rather than quietly understating your rates.
+
+Note that a CCA customer's PCIA is a **charge**, while a bundled customer's is a
+**credit**, so CCA service can cost several cents per kWh more on import.
+
+## Keeping rates current
+
+Every vendored dataset is regenerated from the document that publishes it, by
+`tools.regen`. Nothing is hand-transcribed and nothing is hand-edited.
+
+```bash
+python -m tools.regen                              # rebuild every dataset
+python -m tools.regen --check                      # exit 1 if a publisher moved
+python -m tools.regen tariff --for-date 2025-12-15 # rebuild a superseded vintage
+python -m tools.regen.export --download            # the 843 MB export-rate archive
+```
+
+Export matrices come from PG&E's CSV archive, which is large enough to have its
+own entry point; everything else comes from a published PDF. Nothing is written
+unless the rendered file survives being read back by the library code that will
+consume it, so a generator that drifts from the schema fails instead of shipping.
+
+A weekly CI job runs `--check`, so a rate change surfaces as a failing build
+rather than as silent drift. Export files are updated by **October 1** of any
+year the CPUC adopts a new Avoided Cost Calculator; retail rates change more
+often, via advice letters — three times in the first half of 2026 alone — which
+is why a superseded vintage can be rebuilt from the filing that adopted it. See
+[docs/data.md](docs/data.md).
+
+## Data sources
+
+See [docs/data.md](docs/data.md#data-sources) for the source of every vendored
+table and why OpenEI's URDB is deliberately not used.
+
+## License
+
+MIT