tariff-core 2026.10.1__tar.gz

tariff_core-2026.10.1/.github/copilot-instructions.md

@@ -0,0 +1,119 @@
+# Copilot instructions: tariff-core
+
+## What this repo is
+
+`tariff-core` is a pure Python library that models electricity, gas and water tariff plans, validates them and calculates bills and rates from interval usage data. It is the single source of truth for the plan schema (`docs/schema.md`).
+
+It is consumed by:
+
+- `tariff-catalogue`: harvests and publishes plans; uses this library to normalise and validate them
+- `ha-energy-tariff`: the Home Assistant custom integration; uses this library to evaluate plans locally
+- potentially other tools (evcc, EMHASS, Predbat), so the API must not assume Home Assistant
+
+Read `docs/schema.md` before changing any model, validator or engine code.
+
+## Hard constraints
+
+- **No I/O.** No network calls, no file system access outside explicit `load_*`/`dump_*` helpers that take a path or a string. No logging configuration. The library must be importable and fully usable offline.
+- **No Home Assistant imports**, ever. Home Assistant-specific concepts (entities, `hass`, config entries) do not exist here.
+- **Synchronous, side-effect-free functions.** Home Assistant will call this from an executor or wrap it; do not add `async`.
+- **Money is `decimal.Decimal`.** Never use `float` for rates, costs or credits. Parse JSON numbers and strings into `Decimal` at the boundary; reject floats in monetary fields.
+- **Time uses `zoneinfo` and timezone-aware `datetime` only.** Naive datetimes are a `ValueError`.
+- **Minimal dependencies.** Home Assistant pins many packages, so conflicts are costly. Allowed runtime dependencies: `python-holidays` (optional extra `[holidays]`). Do not add `pydantic`, `pandas`, `numpy`, `attrs` or `arrow`. Use `dataclasses` (`frozen=True`, `slots=True`) and the standard library.
+- **Python version:** match the oldest Python supported by current Home Assistant releases (3.13 at time of writing). Check `pyproject.toml` `requires-python`.
+
+## Package layout
+
+```
+src/tariff_core/
+  __init__.py          # public API re-exports only
+  models.py            # frozen dataclasses mirroring docs/schema.md
+  parse.py             # dict/JSON/YAML -> models; strict, with useful error paths
+  serialise.py         # models -> canonical JSON; content hashing
+  validate.py          # structural + semantic validation (coverage, refs, codes)
+  schedule.py          # window matching, half-open intervals, midnight wrap, seasons, holidays
+  units.py             # dimensions, exact Decimal conversion constants, contract conversions
+  engine/
+    rates.py           # rate_at(), forecast()
+    bill.py            # bill() -> Bill with line items
+    demand.py          # demand charge methods
+    blocks.py          # stepped/block pricing and pro-rating
+  contract.py          # Contract, ContractSegment, segment lookup, overrides (JSON pointer)
+  adapters/            # source-format -> PlanVersion converters (pure functions)
+    cdr.py             # Australian CDR Energy plan detail (x-v 3), electricity and gas -> PlanVersion
+  jsonschema/
+    plan.v1.json       # generated, do not hand-edit (see scripts/gen_schema.py)
+tests/
+docs/schema.md
+```
+
+Adapters live here (not in `tariff-catalogue`) because they are pure transformations and both the pipeline and tests need them. Fetching data is **not** an adapter's job.
+
+## Public API (keep stable; changes need a changelog entry)
+
+```python
+parse_plan(data: Mapping | str) -> PlanVersion
+validate_plan(plan: PlanVersion) -> list[ValidationIssue]   # empty = valid
+validate_contract(contract: Contract) -> list[ValidationIssue]
+convert(quantity: Decimal, from_unit: str, to_unit: str) -> Decimal   # same dimension only
+content_hash(plan: PlanVersion) -> str
+dump_plan(plan: PlanVersion) -> str                         # canonical JSON
+
+rate_at(plan, when: datetime, *, register="general", direction="import",
+        resolved: Mapping[str, Decimal] | None = None) -> RateInfo
+forecast(plan, start: datetime, end: datetime, *, register="general",
+         direction="import") -> list[RateSlot]
+
+bill(plan, intervals: Iterable[Interval], *, period: BillingPeriod,
+     resolved_rates: RateResolver | None = None) -> Bill
+
+Contract.active_segment(when: datetime) -> ContractSegment
+```
+
+- `RateInfo` carries: `rate`, `period`, `period_label`, `next_change`, `next_rate`, `next_period`.
+- `Interval` carries: `end` (interval-ending timestamp), `duration`, `register`, `unit`, `import_qty`, `export_qty`, optional `demand_kw`/`demand_kva`. Quantities are in the meter's unit; `bill()` converts to each component's `quantity_unit` using `units.py` and the contract's `conversions`. Intervals may be long (daily, monthly, quarterly reads for gas and water).
+- `Bill` carries line items (`component`, `quantity`, `unit`, `rate`, `amount`, `type: cost | credit`), subtotals, tax, total and a list of warnings (e.g. dynamic rate missing for 3 intervals).
+- Dynamic rates (`rate: {entity: …}`) are resolved by the caller through `RateResolver`. The library never reads entities.
+
+## Behaviour rules (from the schema; tests must enforce them)
+
+- Windows are half-open `[start, end)`. Midnight-wrapping windows are normal.
+- Interval data is interval-ending. Window lookup uses the interval **start** (`end - duration`).
+- CDR inclusive end times (`HH:59`) are converted to the next minute in `adapters/cdr.py`.
+- Export credits are negative rates internally; `Bill` line items always show positive amounts with `type`.
+- Units convert within a dimension only (energy, volume, power). Gas volume → energy uses the contract's dated `conversions` (heating value × correction factor); never a built-in constant. `gal` is the US gallon.
+- Derived quantities (e.g. sewerage = 0.85 × water) are computed from their source register before billing; cycles are a validation error.
+- Long intervals that span a season or rate change are split pro-rata by elapsed time, with a warning on the `Bill`.
+- Every `(register, direction, season)` with usage components must cover 168 h/week after precedence (scheduled beats anytime, seasonal beats all-year); schedules are lists of windows; seasons are MM-DD half-open ranges covering the year.
+- Demand: average power over each interval (`kWh / hours`), not instantaneous, unless `method: max_instant`.
+- Block pricing: thresholds pro-rated by billing-period length when `prorate: true`.
+- Conditional discounts are excluded from `bill()` unless `include_conditional=True`.
+- Incentives never affect `bill()`.
+
+## Testing
+
+- `pytest`, `pytest-cov`; target ≥ 95% line coverage on `engine/` and `schedule.py`.
+- Use `hypothesis` for schedule coverage and window matching (random windows, midnight wraps, DST transitions in `Australia/Sydney` and `Europe/Amsterdam`).
+- Golden tests in `tests/golden/`: real plans (e.g. the Origin Ergon plan `ORI1161031MRE3@EME`, Energex `6900`, one Origin Queensland gas plan, and one hand-built water plan with derived sewerage) with hand-calculated bills from fixed interval CSVs. A golden test must document where its expected numbers came from.
+- Every bug fix starts with a failing test.
+- Never use floats in test expectations for money; compare `Decimal`s.
+
+## Tooling
+
+- `ruff` (lint + format), `mypy --strict` on `src/`.
+- `pyproject.toml` with `hatchling`; version from git tags.
+- CI: lint, type-check, tests on all supported Python versions, regenerate JSON Schema and fail if it differs from the committed file.
+
+## Style
+
+- Small pure functions, explicit types, no global state, no singletons.
+- Error messages include the JSON path of the problem (e.g. `components[3].schedule`).
+- Docstrings explain *why* and units; do not restate the signature.
+- Prefer clear names from the schema vocabulary (`commodity`, `register`, `direction`, `period`, `quantity_unit`) over synonyms. Never name anything `kwh` unless it is specifically kWh.
+
+## Do not
+
+- Add fetching, caching or scheduling code.
+- Introduce float arithmetic for money "for performance".
+- Add Home Assistant, evcc or vendor-specific concepts to models.
+- Change `docs/schema.md` semantics without bumping the schema version and adding a migration.

tariff_core-2026.10.1/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install development tools and package
+        run: python -m pip install ".[dev]"
+      - name: Lint
+        run: python -m ruff check .
+      - name: Check formatting
+        run: python -m ruff format --check .
+      - name: Type-check
+        run: python -m mypy --strict src/
+      - name: Check generated JSON Schema
+        run: python scripts/gen_schema.py --check
+      - name: Test
+        run: python -m pytest --cov=tariff_core --cov-report=term-missing
+      - name: Build wheel and source distribution
+        run: python -m hatchling build

tariff_core-2026.10.1/.github/workflows/lint.yml

@@ -0,0 +1,55 @@
+name: Lint
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+
+permissions: {}
+
+jobs:
+  ruff:
+    name: "Ruff"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14.8"
+          cache: "pip"
+
+      - name: Install requirements
+        run: python3 -m pip install -r requirements.txt
+
+      - name: Lint
+        run: python3 -m ruff check .
+
+      - name: Check formatting
+        run: python3 -m ruff format . --check
+
+  test:
+    name: "Tests"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14.8"
+          cache: "pip"
+
+      - name: Install test dependencies
+        run: python3 -m pip install -r requirements.txt
+
+      - name: Test
+        run: python3 -m pytest

tariff_core-2026.10.1/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

tariff_core-2026.10.1/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Install build backend
+        run: python -m pip install "hatchling>=1.32.4" "hatch-vcs>=0.5.0"
+      - name: Build distributions
+        run: python -m hatchling build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

tariff_core-2026.10.1/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+build/
+dist/

tariff_core-2026.10.1/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Stabilize the public API and publish the v1 plan JSON Schema.
+- Add contract parsing and validation, CDR conversion exports, and PyPI trusted publishing.
+- Document installation and usage.

tariff_core-2026.10.1/LICENSE

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

tariff_core-2026.10.1/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: tariff-core
+Version: 2026.10.1
+Summary: Pure Python electricity, gas and water tariff modelling and evaluation.
+Project-URL: Documentation, https://github.com/cabberley/tariff-core/blob/main/docs/schema.md
+Project-URL: Issues, https://github.com/cabberley/tariff-core/issues
+Project-URL: Source, https://github.com/cabberley/tariff-core
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.13
+Provides-Extra: dev
+Requires-Dist: hatch-vcs>=0.5.0; extra == 'dev'
+Requires-Dist: hatchling>=1.32.4; extra == 'dev'
+Requires-Dist: holidays>=0.106; extra == 'dev'
+Requires-Dist: hypothesis>=6.168.5; extra == 'dev'
+Requires-Dist: jsonschema>=4.26.0; extra == 'dev'
+Requires-Dist: mypy>=2.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.16.10; extra == 'dev'
+Provides-Extra: holidays
+Requires-Dist: holidays>=0.106; extra == 'holidays'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0.2; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# tariff-core
+
+`tariff-core` is a pure Python library for modelling electricity, gas and water tariffs. It parses and validates tariff plans, calculates rates and bills, and works offline without Home Assistant or other application-specific dependencies.
+
+## Install
+
+```sh
+python -m pip install tariff-core
+```
+
+YAML support is optional: install `tariff-core[yaml]` to parse YAML documents.
+
+## Example
+
+This example loads the Origin Ergon fixture, prints its current tariff rate, then bills one day of hourly usage:
+
+```python
+from datetime import datetime, time, timedelta
+from decimal import Decimal
+from importlib.resources import files
+from zoneinfo import ZoneInfo
+
+from tariff_core import BillingPeriod, Interval, bill, parse_plan, rate_at
+
+plan = parse_plan(files("tariff_core").joinpath("data", "origin_ergon.json").read_text())
+zone = ZoneInfo("Australia/Brisbane")
+now = datetime.now(zone)
+start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+rate = rate_at(plan, now)
+print(f"Current rate: {rate.rate} per kWh ({rate.period_label})")
+intervals = [
+    Interval(start + timedelta(hours=hour), timedelta(hours=1), "general", "kWh", Decimal("1"))
+    for hour in range(1, 25)
+]
+result = bill(
+    plan,
+    intervals,
+    period=BillingPeriod(start, start + timedelta(days=1)),
+)
+print(f"One-day total: {result.total_rounded}")
+```
+
+See the [tariff plan schema](docs/schema.md) for the data model and validation rules.

tariff_core-2026.10.1/README.md

@@ -0,0 +1,43 @@
+# tariff-core
+
+`tariff-core` is a pure Python library for modelling electricity, gas and water tariffs. It parses and validates tariff plans, calculates rates and bills, and works offline without Home Assistant or other application-specific dependencies.
+
+## Install
+
+```sh
+python -m pip install tariff-core
+```
+
+YAML support is optional: install `tariff-core[yaml]` to parse YAML documents.
+
+## Example
+
+This example loads the Origin Ergon fixture, prints its current tariff rate, then bills one day of hourly usage:
+
+```python
+from datetime import datetime, time, timedelta
+from decimal import Decimal
+from importlib.resources import files
+from zoneinfo import ZoneInfo
+
+from tariff_core import BillingPeriod, Interval, bill, parse_plan, rate_at
+
+plan = parse_plan(files("tariff_core").joinpath("data", "origin_ergon.json").read_text())
+zone = ZoneInfo("Australia/Brisbane")
+now = datetime.now(zone)
+start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+rate = rate_at(plan, now)
+print(f"Current rate: {rate.rate} per kWh ({rate.period_label})")
+intervals = [
+    Interval(start + timedelta(hours=hour), timedelta(hours=1), "general", "kWh", Decimal("1"))
+    for hour in range(1, 25)
+]
+result = bill(
+    plan,
+    intervals,
+    period=BillingPeriod(start, start + timedelta(days=1)),
+)
+print(f"One-day total: {result.total_rounded}")
+```
+
+See the [tariff plan schema](docs/schema.md) for the data model and validation rules.