ratebook

Ratebook

電化住宅のためのオープンな料金エンジンです。米国の電気料金プランを収録したオープンライセンスのデータベース、オープンソースの料金計算エンジン、そして MCP サーバーを備え、あらゆるアプリ、デバイス、エージェントが「この kWh の料金はいくらで、いつ充電すべきか？」に答えられるようにします。

_{↑ ブラウザーで実際のエンジンが動作しています。ぜひお試しください：demo/demo.html。}

ステータス：リリース前です。 現在利用できるもの：決定論的な料金エンジン（Python と、バイト単位で一致する TypeScript ポート）。NREL の PySAM との相互検証を行い、実際の請求書の内訳を入力すると、その合計額を再現できることを確認しています。また、電力会社の PDF から料金体系を抽出する LLM パイプライン、MCP サーバー、Home Assistant インテグレーションも利用できます。現在も開発中のもの：幅広い電力会社への対応、データの最新性を保つ自動化、再現可能な公開精度スコアカードです。詳しくは docs/ROADMAP.md をご覧ください。

クイックスタート

エンジンには I/O も必須のデータダウンロードもありません。数行で料金を計算できます：

git clone https://github.com/cbetz/ratebook && cd ratebook
uv sync
uv run python quickstart.py   # or paste the snippet below into `uv run python`

from datetime import date
from decimal import Decimal
from ratebook import (
    Tariff, TariffIdentity, Sector, EnergyRateStructure, EnergyPeriod, EnergyTier,
    Schedule, FixedCharge, FixedChargeUnit, Usage, BillingWindow, estimate_bill,
)

# A flat residential tariff: $0.10276/kWh + $11.30/month (PECO Rate R distribution).
no_tou = tuple(tuple(0 for _ in range(24)) for _ in range(12))  # 12 months × 24 hours, one period
tariff = Tariff(
    energy=EnergyRateStructure(periods=(EnergyPeriod(tiers=(EnergyTier(rate=Decimal("0.10276")),)),)),
    schedule=Schedule(weekday=no_tou, weekend=no_tou),
    identity=TariffIdentity(plan_code="R", plan_name="Example flat residential", sector=Sector.RESIDENTIAL),
    fixed_charges=(FixedCharge(Decimal("11.30"), FixedChargeUnit.PER_MONTH),),
)

bill = estimate_bill(tariff, Usage.aggregate(1244), BillingWindow(date(2026, 4, 28), 30))
print(f"ok={bill.ok}  total=${bill.total}")   # ok=True  total=$139.13344  →  1244 kWh × $0.10276 + $11.30

実際の料金プランは Tariff.from_json(...) で JSON との相互変換ができます。コーパスデータを扱うには、URDB のシードセットを読み込む（uv run ratebook-data urdb）か、MCP サーバーを実行し（uv run ratebook-mcp）、エージェントに lookup_tariff / estimate_bill / compare_plans / best_charge_window を依頼してください。

開発

Python 3.12 以上、uv ワークスペースを使用し、次のパッケージを含みます： packages/ratebook（料金エンジン）、packages/ratebook-data（データプラント）、 packages/ratebook-mcp（MCP サーバー）、packages/ratebook-ts（TypeScript エンジンのポート。 pnpm と vitest を使用し、共有 JSON テストベクトルで Python エンジンとの一致を維持します）、および packages/ratebook-homeassistant（Home Assistant のカスタムインテグレーション。電気料金と最安充電時間帯のセンサーを提供します）。

uv sync                            # install all workspace packages + dev tools
uv run pytest                      # Python tests
uv run ruff check .                # lint
uv run ratebook-data urdb          # download URDB bulk CSV → data/raw/, load into data/ratebook.duckdb
uv run ratebook-mcp                # run the MCP server (stdio)

pnpm -C packages/ratebook-ts install && pnpm -C packages/ratebook-ts test   # TS engine + vectors

PySAM との相互検証は、コミット済みの料金プランのフィクスチャを使って CI で実行されます（uv sync --group validation でオラクルをインストールします）。MCP ツールのテストには、さらにビルド済みコーパスが必要で、ローカルで実行します（uv run ratebook-data urdb）。それ以外の場合はスキップされます。2 つのエンジンに差異が生じてはなりません。どちらも packages/ratebook/tests/vectors/v0_bills.json をバイト単位で再現します。uv run python packages/ratebook/tests/generate_vectors.py で再生成できます。

CONTRIBUTING.md をご覧ください。最も価値の高い貢献は、料金プランの修正（誤った料金や古い料金を、その出典 PDF とともに報告すること）です。

ライセンス

コードは Apache-2.0 でライセンスされています。公開データセットは CC0-1.0 に基づきパブリックドメインに提供されています。シードコーパスは U.S. Utility Rate Database（CC0）に由来します。