> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wayak.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Demand forecasting
> Forecast energy demand using historical consumption data and weather patterns for optimized generation and grid balancing
Accurate demand forecasting is the foundation of efficient grid operations. Over-forecasting leads to excess generation costs and wasted fuel. Under-forecasting risks brownouts, expensive spot-market purchases, and grid instability. Traditional forecasting methods rely on static models and manual adjustments, which struggle to account for changing weather patterns, seasonal shifts, and evolving customer behavior.
Wayak runs a Python-based forecasting model inside a playbook that combines historical meter data with weather API feeds to produce daily and weekly demand projections. An agent lets grid operators query forecasts conversationally, drill into specific zones or time periods, and understand what is driving the forecast — so they can make informed dispatch decisions.
***
## What you need
* **Meter data management system** — historical consumption readings at 15-minute or hourly intervals, aggregated by zone, feeder, and customer class
* **Weather API** — temperature, humidity, wind speed, cloud cover, and precipitation forecasts (hourly and daily)
* **Operations database** — generation schedules, planned outages, and demand response event history
* **Forecasting methodology** — upload your forecasting model documentation, including variable definitions, seasonal adjustment rules, and accuracy targets
* **Rate schedules and tariffs** — upload current rate structures that influence demand patterns (time-of-use pricing, demand charges)
**Semantic layer:** Define these in your ontology before setting up the agent.
| Component | Name | Definition |
| --------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Object | Meter Zone | Maps to the `zones` table in the meter data management system. Represents a geographic or electrical grouping of meters |
| Object | Forecast | Maps to `forecasts` in the operations database. Represents a predicted demand value for a zone and time period |
| Metric | Peak Demand | Maximum hourly demand in MW for a zone or the entire system, measured over a rolling 24-hour window |
| Metric | Forecast Accuracy (MAPE) | Mean Absolute Percentage Error between forecasted and actual demand, calculated daily |
| Dimension | Customer Class | Groups consumption by customer type (residential, commercial, industrial, municipal) |
| Dimension | Zone | Groups meters and demand by geographic or electrical zone |
See [building a semantic layer](/quickstart/build-semantic-layer) for a step-by-step guide.
***
## Agent setup
Go to **Agent Space** → **New agent**.
| Field | Value |
| -------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Name** | Grid Operations Analyst |
| **Role** | Demand Forecasting Specialist |
| **Goal** | Provide demand forecasts by zone and time period, explain forecast drivers, and assess forecast accuracy against actuals |
> You are a demand forecasting specialist who combines historical consumption patterns with weather data to project energy demand. You explain forecast results clearly — identifying the key drivers (temperature, day of week, season, special events) behind each projection. You compare forecasts against actuals to track accuracy and flag when model performance degrades. You support grid operators with the data they need for dispatch decisions but do not make dispatch recommendations directly.
Grant access to:
* Meter data management system (consumption readings, zone aggregations)
* Weather API (forecasts and historical weather data)
* Operations database (generation schedules, demand response events)
* Forecasting methodology knowledge space
* Rate schedules and tariffs knowledge space
* Meter Zone and Forecast objects, Peak Demand and Forecast Accuracy metrics
**Trigger:** User asks for the demand forecast for a specific zone, time period, or the entire system.
1. Retrieve the latest forecast data for the requested zone and time period from the operations database.
2. Pull the weather forecast for the same period from the weather API.
3. Identify the primary drivers of the forecast (temperature sensitivity, day-of-week pattern, seasonal trend).
4. Compare the forecast to the same period in the prior year for context.
5. Return the forecast values (hourly or daily), peak demand expected, key drivers, and year-over-year comparison.
**Trigger:** User asks about forecast accuracy or model performance.
1. Retrieve the forecasted and actual demand values for the requested period from the operations database and meter data system.
2. Calculate MAPE and identify the hours or days with the largest forecast errors.
3. Correlate the largest errors with weather forecast misses or unexpected events (e.g., unplanned outages, demand response activations).
4. Compare current accuracy against the accuracy target from the forecasting methodology knowledge space.
5. Return an accuracy summary with MAPE, error distribution, root causes for large misses, and trend over time.
**Trigger:** User asks how weather is affecting or will affect demand.
1. Retrieve the current and forecasted weather conditions from the weather API.
2. Query historical demand data for similar weather conditions from the meter data management system.
3. Estimate the demand impact of the weather event (e.g., a heat wave increases residential cooling load by X MW).
4. Identify the zones and customer classes most affected.
5. Return a weather impact assessment with estimated demand change, affected zones, and historical comparisons.
***
## Automation
### Playbook: Daily demand forecast generation
Set the trigger to **Schedule — Daily** at 4:00 AM, providing grid operators with updated forecasts before the morning load ramp.
The workflow generates 48-hour demand forecasts for all zones and flags any expected peaks:
1. **Query** the meter data management system for the most recent 30 days of hourly consumption data by zone and customer class.
2. **Query** the weather API for the 48-hour hourly forecast (temperature, humidity, wind speed, cloud cover).
3. **Python code block** — run the demand forecasting model. The code uses a combination of historical load patterns, temperature regression coefficients, and day-of-week/holiday adjustments to produce hourly demand projections for each zone. It also calculates the expected system peak and the probability of exceeding the seasonal peak record.
The **forecasting model** step uses a Python code block to combine weather-adjusted regression with historical load patterns. You can customize the temperature sensitivity coefficients, holiday calendars, and peak probability thresholds.
4. **Condition** — if the forecasted peak exceeds 90% of system capacity, flag a peak warning.
5. **Action** — write the forecast values to the `forecasts` table in the operations database for downstream consumption.
6. **Delivery** — distribute the forecast report.
* **Email** — send the full 48-hour forecast report to the grid operations team
* **Slack** — post a summary to `#grid-ops` with today's expected peak, tomorrow's expected peak, and any peak warnings
* **Email escalation** — if a peak warning is triggered, notify the VP of Operations and the demand response team
Click **Run now** to test with live data, then toggle to **Active**.
***
## What's next
Detect outages from SCADA events and coordinate dispatch response with automated escalation.
See the full list.