ratebook

Ratebook

面向电气化家庭的开放电价引擎——一个以开放许可发布的美国电价数据库、一个开源电价计算引擎和一个 MCP 服务，让任何应用、设备或 Agent 都能回答“这一度电要花多少钱？我应该什么时候充电？”

_{↑ 在浏览器中运行的真实引擎。亲自试试：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

真实电价方案可通过 JSON 往返转换：Tariff.from_json(...)。若要使用语料库数据，请加载 URDB 种子集（uv run ratebook-data urdb），或运行 MCP 服务（uv run ratebook-mcp），然后让 Agent 调用 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 中针对已提交的电价方案 fixture 运行（uv sync --group validation 会安装作为基准的实现）。MCP 工具测试还需要构建好的语料库，并在本地运行（uv run ratebook-data urdb）；否则会跳过。两个引擎必须始终保持一致：它们都必须逐字节复现 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）。