LEARN / PRACTICAL TUTORIALS

Start building energy-aware applications.

Small examples that teach real SDK concepts. Start with simulation, compose a tool, then connect data sources you are authorized to use.

Set up EnergyChain ↗Browse the API reference ↗

01 · BEGINNER · APPROX. 10 MIN

Battery backup assistant

Discover a battery in the built-in simulator and estimate backup hours for a given load. The estimate is not a device guarantee, and the underlying readings are synthetic.

Python · battery_runtime.py

from energychain import EnergyChain

sdk = EnergyChain.demo()
user = sdk.principal("demo", allowed_sites={"demo-site"})

battery = sdk.tools.invoke(
    "get_battery_state", user, "demo-site",
    arguments={"asset_id": "demo-battery"},
)

estimate = sdk.tools.invoke(
    "estimate_battery_runtime", user, "demo-site",
    arguments={
        "battery_id": "demo-battery",
        "load_w": 900,
        "reserve_pct": 20,
    },
)
print("SOC:", battery["state_of_charge"].value)
print("Estimated hours:", estimate["hours"])

Full quickstart ↗

02 · BEGINNER · APPROX. 10 MIN

Electricity-cost calculator

Calculate the estimated cost of an energy quantity using a known tariff. The example intentionally accepts the tariff from the host app; EnergyChain does not fabricate a utility price.

Python · energy_cost.py

from energychain import EnergyChain

sdk = EnergyChain.demo()
user = sdk.principal("demo", allowed_sites={"demo-site"})
result = sdk.tools.invoke(
    "estimate_energy_cost", user, "demo-site",
    arguments={
        "energy_wh": 3000,
        "price_per_kwh": 100,
    },
)
print("Estimated cost:", result["cost"])

Understand tools ↗

03 · INTERMEDIATE · APPROX. 20 MIN

Multi-site fleet snapshot

Compose two isolated simulated sites into one read-only fleet and retrieve scoped observations. Fleet snapshots report missing or stale data explicitly.

Python · fleet_snapshot.py

from energychain import EnergyChain, Fleet, HybridSiteSimulator

sdk = EnergyChain.demo()
sdk.add_connector("south", HybridSiteSimulator(site_id="south"))
sdk.fleets.register(
    Fleet("portfolio", frozenset({"demo-site", "south"}))
)
principal = sdk.principal(
    "analyst", allowed_sites={"demo-site", "south"}
)
snapshot = sdk.tools.invoke(
    "get_fleet_snapshot",
    principal,
    "demo-site",
    arguments={
        "fleet_id": "portfolio",
        "metric": "power_w",
        "max_age_seconds": 3600,
    },
)
print(snapshot["observations"])
print(snapshot["failures"])

Fleet architecture ↗

04 · ADVANCED · APPROX. 20 MIN

Model-pluggable explanation agent

Keep the energy calculation separate from the text explanation. The callback below is a local demonstration, not a connected AI provider or trained energy model.

Python · energy_assistant.py

from energychain import EnergyChain, CallableTextModel

sdk = EnergyChain.demo()
user = sdk.principal("developer", allowed_sites={"demo-site"})
model = CallableTextModel(
    lambda system, prompt, context: "Observation: " + context[:160]
)
response = sdk.agent(model).run(
    "Explain the battery state.",
    principal=user,
    site_id="demo-site",
    tool_name="get_battery_state",
    tool_arguments={"asset_id": "demo-battery"},
)
print(response.answer)

Understand safe agents ↗

NEXT STEP

Connect a real, approved data source.

Learn the connector interface, read-only Home Assistant mapping, provenance rules and provider credentials before integrating a real energy installation.

Explore connectors ↗