+ + """
+
"""
+ battery_status_icon
+ """
diff --git a/coverage/analyze_data.py b/coverage/analyze_data.py
new file mode 100644
index 000000000..c19237caf
--- /dev/null
+++ b/coverage/analyze_data.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+import json
+import statistics
+
+# Load the data
+with open("load_minutes_debug.json", "r") as f:
+ load_data = {int(k): float(v) for k, v in json.load(f).items()}
+
+# Convert to energy per step (like predictor does)
+STEP_MINUTES = 5
+energy_per_step = {}
+sorted_minutes = sorted(load_data.keys())
+
+for minute in sorted_minutes:
+ if minute + STEP_MINUTES in load_data:
+ energy = max(0, load_data[minute] - load_data[minute + STEP_MINUTES])
+ energy_per_step[minute] = energy
+
+# Get statistics
+energies = list(energy_per_step.values())
+print(f"Energy per step statistics:")
+print(f" Count: {len(energies)}")
+print(f" Min: {min(energies):.4f} kWh")
+print(f" Max: {max(energies):.4f} kWh")
+print(f" Mean: {statistics.mean(energies):.4f} kWh")
+print(f" Median: {statistics.median(energies):.4f} kWh")
+print(f" Std: {statistics.stdev(energies):.4f} kWh")
+energies_sorted = sorted(energies)
+print(f" 25th percentile: {energies_sorted[len(energies)//4]:.4f} kWh")
+print(f" 75th percentile: {energies_sorted[3*len(energies)//4]:.4f} kWh")
+print(f" 95th percentile: {energies_sorted[95*len(energies)//100]:.4f} kWh")
+
+# Show first 24 hours of data
+print(f"\nFirst 24 hours of data (minute 0-1440):")
+for minute in range(0, min(1440, max(energy_per_step.keys())), 60):
+ if minute in energy_per_step:
+ print(f" Minute {minute}: {energy_per_step[minute]:.4f} kWh")
+
+# Check what the training data looks like
+print(f"\nTraining window analysis (for predicting minute 0-2880):")
+print(f"Looking at samples from minute 2880 onwards...")
+for sample_minute in range(2880, min(2880 + 1440, max(energy_per_step.keys())), 60):
+ if sample_minute in energy_per_step:
+ print(f" Sample at minute {sample_minute} (lookback from here): {energy_per_step[sample_minute]:.4f} kWh")
diff --git a/coverage/analyze_periods.py b/coverage/analyze_periods.py
new file mode 100644
index 000000000..5b1ad4aef
--- /dev/null
+++ b/coverage/analyze_periods.py
@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+import json
+
+# Load the data
+with open("load_minutes_debug.json", "r") as f:
+ load_data = {int(k): float(v) for k, v in json.load(f).items()}
+
+# Convert to energy per step
+STEP_MINUTES = 5
+energy_per_step = {}
+sorted_minutes = sorted(load_data.keys())
+
+for minute in sorted_minutes:
+ if minute + STEP_MINUTES in load_data:
+ energy = max(0, load_data[minute] - load_data[minute + STEP_MINUTES])
+ energy_per_step[minute] = energy
+
+# Analyze different time periods
+periods = [("Recent (0-1440min, 0-24h)", 0, 1440), ("Recent (0-2880min, 0-48h)", 0, 2880), ("Training window (2880-10080min, 2-7 days ago)", 2880, 10080), ("Full dataset", 0, max(energy_per_step.keys()))]
+
+for name, start, end in periods:
+ values = [energy_per_step[m] for m in energy_per_step.keys() if start <= m < end]
+ if values:
+ mean_val = sum(values) / len(values)
+ max_val = max(values)
+ median_val = sorted(values)[len(values) // 2]
+ print(f"{name}:")
+ print(f" Count: {len(values)}, Mean: {mean_val:.4f} kWh, Median: {median_val:.4f} kWh, Max: {max_val:.4f} kWh")
+ else:
+ print(f"{name}: No data")
diff --git a/coverage/debug_model.py b/coverage/debug_model.py
new file mode 100644
index 000000000..eb2023d87
--- /dev/null
+++ b/coverage/debug_model.py
@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""Debug script to analyze what the model is learning"""
+import json
+import sys
+
+sys.path.insert(0, "../apps/predbat")
+from load_predictor import LoadPredictor
+from datetime import datetime, timezone
+
+# Load data
+with open("load_minutes_debug.json", "r") as f:
+ load_data = {int(k): float(v) for k, v in json.load(f).items()}
+
+# Train model
+predictor = LoadPredictor(learning_rate=0.001, max_load_kw=20.0)
+now_utc = datetime.now(timezone.utc)
+
+print("Training model...")
+predictor.train(load_data, now_utc, is_initial=True, epochs=30, time_decay_days=7)
+
+# Check normalization parameters
+print(f"\nNormalization parameters:")
+print(f" Feature mean (first 12): {predictor.feature_mean[:12]}") # Lookback values
+print(f" Feature mean (last 4): {predictor.feature_mean[12:]}") # Time features
+print(f" Feature std (first 12): {predictor.feature_std[:12]}")
+print(f" Feature std (last 4): {predictor.feature_std[12:]}")
+print(f" Target mean: {predictor.target_mean:.4f} kWh")
+print(f" Target std: {predictor.target_std:.4f} kWh")
+
+# Check first layer weights to see feature importance
+print(f"\nFirst layer weight magnitudes (input importance):")
+w1 = predictor.weights[0] # Shape: (16, 32)
+for i in range(16):
+ mag = float((w1[i, :] ** 2).sum() ** 0.5)
+ feat_name = f"lookback_{i}" if i < 12 else ["sin_minute", "cos_minute", "sin_day", "cos_day"][i - 12]
+ print(f" {feat_name:15s}: {mag:.4f}")
diff --git a/coverage/debug_predict.py b/coverage/debug_predict.py
new file mode 100644
index 000000000..9e8931d81
--- /dev/null
+++ b/coverage/debug_predict.py
@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Debug the prediction issue"""
+import sys
+
+sys.path.insert(0, "../apps/predbat")
+
+import json
+import numpy as np
+from datetime import datetime, timezone, timedelta
+from load_predictor import LoadPredictor, LOOKBACK_STEPS, STEP_MINUTES
+
+# Load data
+with open("load_minutes_debug.json", "r") as f:
+ load_data = {int(k): float(v) for k, v in json.load(f).items()}
+
+# Quick mode - just check final energies
+if len(sys.argv) > 1 and sys.argv[1] == "--quick":
+ predictor = LoadPredictor(learning_rate=0.001, max_load_kw=20.0)
+ now_utc = datetime.now(timezone.utc)
+ midnight_utc = now_utc.replace(hour=0, minute=0, second=0, microsecond=0)
+
+ predictor.train(load_data, now_utc, is_initial=True, epochs=30, time_decay_days=7)
+ predictions = predictor.predict(load_data, now_utc, midnight_utc)
+
+ pred_keys = sorted(predictions.keys())
+ energies = []
+ for i, minute in enumerate(pred_keys):
+ if i == 0:
+ energies.append(predictions[minute])
+ else:
+ energies.append(predictions[minute] - predictions[pred_keys[i - 1]])
+
+ print("Energy stats:")
+ print(f" Min: {min(energies):.4f}, Max: {max(energies):.4f}, Mean: {np.mean(energies):.4f}")
+ print(f" Steps 0-20: {[round(e, 4) for e in energies[0:20]]}")
+ print(f" Steps 200-220: {[round(e, 4) for e in energies[200:220]]}")
+ print(f" Steps 400-420: {[round(e, 4) for e in energies[400:420]]}")
+ print(f" Steps 550-576: {[round(e, 4) for e in energies[550:576]]}")
+ sys.exit(0)
+
+# Train model
+predictor = LoadPredictor(learning_rate=0.001, max_load_kw=20.0)
+now_utc = datetime.now(timezone.utc)
+midnight_utc = now_utc.replace(hour=0, minute=0, second=0, microsecond=0)
+
+print("Training model...")
+predictor.train(load_data, now_utc, is_initial=True, epochs=30, time_decay_days=7)
+
+# Check normalization parameters
+print(f"\n=== Normalization Parameters ===")
+print(f"Feature mean (first 10 lookback): {predictor.feature_mean[:10]}")
+print(f"Feature std (first 10 lookback): {predictor.feature_std[:10]}")
+print(f"Target mean: {predictor.target_mean:.6f}")
+print(f"Target std: {predictor.target_std:.6f}")
+
+# Get the energy per step for historical data
+energy_per_step = predictor._load_to_energy_per_step(load_data)
+
+# Look at the initial lookback buffer
+print(f"\n=== Initial Lookback Buffer ===")
+lookback_buffer = []
+for lb_offset in range(LOOKBACK_STEPS):
+ lb_minute = lb_offset * STEP_MINUTES
+ if lb_minute in energy_per_step:
+ lookback_buffer.append(energy_per_step[lb_minute])
+ else:
+ lookback_buffer.append(0)
+
+print(f"First 10 values: {lookback_buffer[:10]}")
+print(f"Mean: {np.mean(lookback_buffer):.6f}, Std: {np.std(lookback_buffer):.6f}")
+print(f"Min: {np.min(lookback_buffer):.6f}, Max: {np.max(lookback_buffer):.6f}")
+
+# Now trace through a few prediction steps
+print(f"\n=== Prediction Step-by-Step ===")
+predictions_energy = []
+
+for step_idx in range(200): # First 200 steps (16+ hours)
+ target_time = now_utc + timedelta(minutes=(step_idx + 1) * STEP_MINUTES)
+ minute_of_day = target_time.hour * 60 + target_time.minute
+ day_of_week = target_time.weekday()
+ time_features = predictor._create_time_features(minute_of_day, day_of_week)
+
+ # Combine features
+ features = np.concatenate([np.array(lookback_buffer, dtype=np.float32), time_features])
+
+ # Normalize
+ features_norm = predictor._normalize_features(features.reshape(1, -1), fit=False)
+
+ # Forward pass
+ pred_norm, _, _ = predictor._forward(features_norm)
+
+ # Denormalize
+ pred_energy = predictor._denormalize_predictions(pred_norm[0])
+
+ # Clip
+ pred_clipped = predictor._clip_predictions(pred_energy)
+ energy_value = float(pred_clipped[0])
+
+ print(f"Step {step_idx}: lb_mean={np.mean(lookback_buffer):.4f}, " f"pred_norm={pred_norm[0][0]:.4f}, pred_denorm={pred_energy[0]:.4f}, " f"pred_clipped={energy_value:.4f}")
+
+ predictions_energy.append(energy_value)
+
+ # Update lookback buffer
+ lookback_buffer.insert(0, energy_value)
+ lookback_buffer.pop()
+
+# Check for the issue - when does it first go to zero?
+print(f"\n=== Full Prediction Analysis ===")
+full_predictions = predictor.predict(load_data, now_utc, midnight_utc)
+
+# Show cumulative values
+pred_keys = sorted(full_predictions.keys())
+print("\nFirst 20 cumulative values:")
+for i in range(20):
+ print(f" minute {pred_keys[i]}: {full_predictions[pred_keys[i]]:.4f}")
+
+print("\nAround step 120-140:")
+for i in range(120, 140):
+ print(f" minute {pred_keys[i]}: {full_predictions[pred_keys[i]]:.4f}")
+
+# Convert to energy
+pred_energy_list = []
+sorted_minutes = sorted(full_predictions.keys())
+prev_cum = 0
+for minute in sorted_minutes:
+ cum = full_predictions[minute]
+ energy = cum - prev_cum
+ pred_energy_list.append(energy)
+ prev_cum = cum
+
+print(f"\nPrediction minutes: {sorted_minutes[:10]}...{sorted_minutes[-3:]}")
+print(f"First 20 energies: {[f'{e:.4f}' for e in pred_energy_list[:20]]}")
+print(f"Middle energies (140-160): {[f'{e:.4f}' for e in pred_energy_list[140:160]]}")
+print(f"Late energies (200-220): {[f'{e:.4f}' for e in pred_energy_list[200:220]]}")
+
+# Check for zeros or near-zeros
+zeros = [(i, e) for i, e in enumerate(pred_energy_list) if e < 0.01]
+print(f"\nSteps with energy < 0.01: {len(zeros)}")
+if zeros:
+ print(f"First 10: {zeros[:10]}")
+
+# Stats
+print(f"\nOverall stats:")
+print(f" Min: {min(pred_energy_list):.4f}")
+print(f" Max: {max(pred_energy_list):.4f}")
+print(f" Mean: {np.mean(pred_energy_list):.4f}")
+print(f" Std: {np.std(pred_energy_list):.4f}")
diff --git a/docs/components.md b/docs/components.md
index 4917b352c..05288b5e9 100644
--- a/docs/components.md
+++ b/docs/components.md
@@ -21,6 +21,8 @@ This document provides a comprehensive overview of all Predbat components, their
- [Solis Cloud API (Solis)](#solis-cloud-api-solis)
- [Alert Feed (alert_feed)](#alert-feed-alert_feed)
- [Carbon Intensity API (carbon)](#carbon-intensity-api-carbon)
+ - [Temperature API (temperature)](#temperature-api-temperature)
+ - [ML Load Prediction (load_ml)](#ml-load-prediction-load_ml)
- [Managing Components](#managing-components)
- [Checking Component Status](#checking-component-status)
- [Restarting Components](#restarting-components)
@@ -617,6 +619,152 @@ Note: To use the carbon data in Predbat you also have to turn on **switch.predba
---
+### Temperature API (temperature)
+
+**Can be restarted:** Yes
+
+#### What it does (temperature)
+
+Fetches temperature forecasts from the Open-Meteo API to provide accurate temperature predictions for the next 48+ hours.
+This temperature data is used by the ML Load Prediction component to improve load forecasting accuracy, especially for homes with electric heating or air conditioning systems.
+
+#### When to enable (temperature)
+
+- You are using ML Load Prediction and want improved accuracy
+- Your energy consumption is significantly affected by temperature (heating/cooling)
+- You want temperature forecasts available for other automations
+
+#### How it works (temperature)
+
+- Fetches temperature data from Open-Meteo API every hour
+- Uses your location coordinates (from `temperature_latitude`/`temperature_longitude` or defaults to `zone.home`)
+- Provides current temperature and hourly forecasts
+- Publishes data to `sensor.predbat_temperature` with forecasts in the `results` attribute
+- Automatically retries on API failures with exponential backoff
+
+**Important**: This component is **recommended** when using ML Load Prediction, as temperature data cam improve prediction accuracy for households with electric/heat-pump heating.
+
+#### Configuration Options (temperature)
+
+| Option | Type | Required | Default | Config Key | Description |
+| ------ | ---- | -------- | ------- | ---------- | ----------- |
+| `temperature_enable` | Boolean | Yes | False | `temperature_enable` | Set to `true` to enable temperature forecasts |
+| `temperature_url` | String | No | Open-Meteo API URL | `temperature_url` | API URL with LATITUDE/LONGITUDE placeholders |
+| `temperature_latitude` | Float | No | Uses zone.home | `temperature_latitude` | Latitude for temperature forecast location |
+| `temperature_longitude` | Float | No | Uses zone.home | `temperature_longitude` | Longitude for temperature forecast location |
+
+#### Configuration example (temperature)
+
+```yaml
+predbat:
+ # Enable temperature forecasts (recommended for ML load prediction)
+ temperature_enable: true
+
+ # Optional: specify location (defaults to zone.home)
+ # temperature_latitude: 51.5074
+ # temperature_longitude: -0.1278
+```
+
+#### Accessing temperature data (temperature)
+
+Temperature data is published to:
+
+- `sensor.predbat_temperature` - Current temperature with forecast in `results` attribute
+
+The `results` attribute contains a dictionary of timestamp strings (ISO format with timezone) to temperature values in °C.
+
+---
+
+### ML Load Prediction (load_ml)
+
+**Can be restarted:** Yes
+
+#### What it does (load_ml)
+
+Uses a neural network to predict your household energy consumption for the next 48 hours based on historical patterns, time-of-day, day-of-week, and optionally temperature and PV generation data.
+This provides more accurate load predictions than simple averaging, especially for households with variable usage patterns.
+
+#### When to enable (load_ml)
+
+- You want more accurate load predictions than historical averages
+- Your energy consumption has regular daily/weekly patterns
+- You have at least 1 day of historical load data (7+ days recommended)
+- You want Predbat to automatically adapt to changing consumption patterns
+
+#### How it works (load_ml)
+
+- Fetches historical load data from your configured `load_today` sensor
+- Optionally incorporates PV generation and temperature forecast data
+- Trains a multi-layer neural network on your historical patterns
+- Makes autoregressive predictions for 48 hours ahead in 5-minute intervals
+- Fine-tunes periodically (every 2 hours) to adapt to changing patterns
+- Validates predictions and falls back gracefully if accuracy is poor
+- Publishes predictions to `sensor.predbat_load_ml_forecast`
+
+**Important**: For best results, enable the Temperature component (`temperature_enable: true`) as temperature data significantly improves prediction accuracy.
+
+For a detailed explanation of how the neural network works and comprehensive configuration guidance, see the [ML Load Prediction documentation](load-ml.md).
+
+#### Configuration Options (load_ml)
+
+| Option | Type | Required | Default | Config Key | Description |
+| ------ | ---- | -------- | ------- | ---------- | ----------- |
+| `load_ml_enable` | Boolean | Yes | False | `load_ml_enable` | Set to `True` to enable ML load prediction |
+| `load_ml_source` | Boolean | Yes | False | `load_ml_source` | Set to `True` to use the ML load prediction in Predbat |
+
+Note: load_today, pv_today and car_charging_energy apps.yaml configuration items are also used, but these should already be set in Predbat.
+
+#### Configuration example (load_ml)
+
+```yaml
+predbat:
+ # Enable ML load prediction
+ load_ml_enable: True
+ # Use the data in Predbat, can be false while exploring the predictions but not using them
+ load_ml_source: True
+
+ # Optional but recommended: enable temperature forecasts
+ temperature_enable: true
+```
+
+#### Understanding model status (load_ml)
+
+The ML component tracks several status indicators:
+
+- **not_initialized**: Model has not been created yet
+- **training**: Model is currently training on historical data
+- **active**: Model is trained and making predictions
+- **validation_failed**: Predictions are disabled due to high validation error
+- **stale**: Model hasn't been trained in 48+ hours and needs retraining
+
+Check Predbat logs for training progress and validation metrics:
+
+```text
+ML Component: Starting initial training
+ML Predictor: Training complete, final val_mae=0.3245 kWh
+ML Component: Model status: active
+```
+
+#### Accessing predictions (load_ml)
+
+ML load predictions are published to:
+
+- `sensor.predbat_load_ml_forecast` - Contains 48-hour prediction in `results` attribute
+
+Predbat automatically uses these predictions when making battery charge/discharge decisions.
+
+#### For more information (load_ml)
+
+See the comprehensive [ML Load Prediction documentation](load-ml.md) for:
+
+- Detailed explanation of neural network architecture
+- Training process and parameters
+- Expected accuracy metrics
+- Troubleshooting guide
+- Advanced configuration options
+
+---
+
## Managing Components
### Checking Component Status
diff --git a/docs/load-ml.md b/docs/load-ml.md
new file mode 100644
index 000000000..cebc9ad38
--- /dev/null
+++ b/docs/load-ml.md
@@ -0,0 +1,303 @@
+# ML Load Prediction
+
+Predbat includes a neural network-based machine learning component that can predict your household energy consumption for the next 48 hours.
+This prediction is based on historical load patterns, time-of-day patterns, day-of-week patterns, and optionally PV generation history and temperature forecasts.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [How the Neural Network Works](#how-the-neural-network-works)
+- [Configuration](#configuration)
+- [Setup Instructions](#setup-instructions)
+- [Understanding the Model](#understanding-the-model)
+- [Monitoring and Troubleshooting](#monitoring-and-troubleshooting)
+- [Model Persistence](#model-persistence)
+
+## Overview
+
+The ML Load Prediction component uses a lightweight multi-layer perceptron (MLP) neural network implemented in pure NumPy. It learns from your historical energy consumption patterns and makes predictions about future load.
+
+**Key Features:**
+
+- Predicts 48 hours of load data in 5-minute intervals
+- Learns daily and weekly patterns automatically
+- Supports historical PV generation data as an input feature
+- Supports temperature forecast data for improved accuracy
+- Automatically trains on historical data (requires at least 1 day, recommended 7+ days)
+- Fine-tunes periodically to adapt to changing patterns
+- Model persists across restarts
+- Falls back gracefully if predictions are unreliable
+
+## How the Neural Network Works
+
+### Architecture
+
+The ML Load Predictor uses a deep neural network with an input layer, some hidden layers and an output layer.
+
+### Input Features
+
+The neural network uses several types of input features to make predictions:
+
+1. **Historical Load Lookback**
+ - Past 24 hours of energy consumption at 5-minute intervals
+ - Helps the network understand recent usage patterns
+
+2. **Historical PV Generation**
+ - Past 24 hours of solar PV generation at 5-minute intervals
+ - Helps correlate solar production with consumption patterns
+ - Requires `pv_today` sensor to be configured
+
+3. **Historical Temperature**
+ - Past 7 days and future 2 days of temperature data at 5-minute intervals
+ - Helps correlate temperature with energy usage (heating/cooling)
+ - **Requires the Temperature component to be enabled**
+
+4. **Cyclical Time Features** (4 features)
+ - Sin/Cos encoding of hour-of-day (captures daily patterns)
+ - Sin/Cos encoding of day-of-week (captures weekly patterns)
+ - These features help the network understand that 23:55 is close to 00:05
+
+### Prediction Process
+
+The model uses an autoregressive approach:
+
+1. Takes the last 24 hours of historical data
+2. Predicts the next 5-minute step
+3. Adds that prediction to the history window
+4. Shifts the window forward and repeats
+5. Continues for 576 steps to cover 48 hours
+
+To prevent drift in long-range predictions, the model blends autoregressive predictions with historical daily patterns.
+
+### Training Process
+
+**Initial Training:**
+
+- Requires at least 1 day of historical data (7+ days recommended)
+- Uses 50 epochs with early stopping
+- Validates on the last 24 hours of data
+- Saves model to disk: `predbat_ml_model.npz`
+
+**Fine-tuning:**
+
+- Runs every 2 hours if enabled
+- Uses last 24 hours of data
+- Uses 2 epochs to quickly adapt to recent changes
+- Preserves learned patterns while adapting to new ones
+
+**Model Validation:**
+
+- Model is validated after each training session
+- If validation error exceeds threshold (default 2.0 kWh MAE), predictions are disabled
+- Model is considered stale after 48 hours and requires retraining
+
+## Configuration
+
+### Basic Setup
+
+To enable ML load prediction, add to your `apps.yaml`:
+
+```yaml
+predbat:
+ module: predbat
+ class: PredBat
+
+ # Enable ML load prediction
+ load_ml_enable: True
+ # Use the output data in Predbat (can be False to explore the use without using the data)
+ load_ml_source: True
+```
+
+For best results:
+
+- Ensure you have a least a weeks worth of data before enabling load_ml_source.
+- Make sure you do not have PredAI enabled at the same time
+- Disable in day adjustment (switch.predbat_calculate_inday_adjustment) as the AI model will do that for you.
+
+### Recommended: Enable Temperature Predictions
+
+**For best results, enable the Temperature component to provide temperature forecasts:**
+
+```yaml
+predbat:
+ # ... other config ...
+
+ # Enable temperature predictions (RECOMMENDED for ML load prediction)
+ temperature_enable: true
+
+ # Optional: specify coordinates (defaults to zone.home)
+ # temperature_latitude: 51.5074
+ # temperature_longitude: -0.1278
+```
+
+The temperature data significantly improves prediction accuracy for homes with heating/cooling systems, as energy consumption is often correlated with outside temperature.
+
+### Optional: Add PV Generation Data
+
+Your PV data will be picked from the pv_today setting in Predbat already
+
+```yaml
+predbat:
+ # ... other config ...
+
+ pv_today:
+ - sensor.my_solar_generation_today
+```
+
+### Optional: Subtract Car Charging
+
+If you have an EV charger set in Predbat then this will be subtracted from predictions.
+If this is not set then the default EV charging threshold is used if car_charging_hold is True.
+
+```yaml
+predbat:
+ # ... other config ...
+
+ # Optional: subtract car charging from load history
+ car_charging_energy:
+ - sensor.my_ev_charger_energy
+```
+
+## Setup Instructions
+
+### Step 1: Verify Prerequisites
+
+Before enabling ML load prediction:
+
+1. Ensure you have a `load_today` sensor that tracks cumulative daily energy consumption
+2. Optionally configure `pv_today` if you have solar panels
+3. **Recommended**: Enable the Temperature component (Temperature Component in components documentation)
+4. Ensure you have at least 1 day of historical data (7+ days recommended)
+
+### Step 2: Enable the Component
+
+Add `load_ml_enable: true` to your `apps.yaml` and restart Predbat.
+
+### Step 3: Wait for Initial Training
+
+On first run, the component will:
+
+1. Fetch historical load data (default: 7 days)
+2. Train the neural network (takes 1-5 minutes depending on data)
+3. Validate the model
+4. Begin making predictions if validation passes
+
+Check the Predbat logs for training progress:
+
+```text
+ML Component: Starting initial training
+ML Predictor: Starting initial training with 50 epochs
+ML Predictor: Training complete, final val_mae=0.3245 kWh
+ML Component: Initial training completed, validation MAE=0.3245 kWh
+```
+
+### Step 4: Monitor Predictions
+
+Once trained, the component publishes predictions to:
+
+- `sensor.predbat_load_ml_forecast` - Contains 48-hour prediction in `results` attribute
+
+You can visualize these predictions in the Predbat web interface or by creating charts in Home Assistant.
+
+## Understanding the Model
+
+### Model Status
+
+The ML component tracks several status indicators:
+
+- **Model Status**: `not_initialized`, `training`, `active`, `validation_failed`, `stale`
+- **Validation MAE**: Mean Absolute Error on validation data (in kWh per 5-min step)
+- **Model Age**: How long since the model was last trained
+
+You can check model status in the Predbat logs or via the component status page in the web interface.
+
+### What Makes Good Predictions?
+
+Good predictions require:
+
+1. **Sufficient Historical Data**: At least 7 days recommended
+2. **Consistent Patterns**: Regular daily/weekly routines improve accuracy
+3. **Temperature Data**: Especially important for homes with electric heating/cooling
+4. **Clean Data**: Avoid gaps or incorrect readings in historical data
+5. **Recent Training**: Model should be retrained periodically (happens automatically)
+
+### Expected Accuracy
+
+Typical validation MAE values:
+
+- **Excellent**: < 0.3 kWh per 5-min step (~ 3.6 kW average)
+- **Good**: 0.3 - 0.5 kWh per 5-min step
+- **Fair**: 0.5 - 1.0 kWh per 5-min step
+- **Poor**: > 1.0 kWh per 5-min step (may indicate issues)
+
+If validation MAE exceeds the threshold (default 2.0 kWh), predictions are disabled and the model will attempt to retrain.
+
+## Monitoring and Troubleshooting
+
+### Check Model Status
+
+View model status in Predbat logs:
+
+```text
+ML Component: Model status: active, last trained: 2024-02-07 10:30:00
+ML Component: Validation MAE: 0.3245 kWh
+```
+
+### Common Issues
+
+**Issue**: Model never trains
+
+- **Cause**: Insufficient historical data
+- **Solution**: Wait until you have at least 1 day of data, preferably 7+ days
+
+**Issue**: Validation MAE too high (predictions disabled)
+
+- **Cause**: Inconsistent load patterns, poor data quality, or insufficient training data
+- **Solution**:
+ - Ensure historical data is accurate
+ - Add temperature data if not already enabled
+ - Wait for more historical data to accumulate
+ - Check for gaps or anomalies in historical data
+
+**Issue**: Model becomes stale
+
+- **Cause**: No training for 48+ hours
+- **Solution**: Check logs for training failures, ensure Predbat is running continuously
+
+**Issue**: Predictions seem inaccurate
+
+- **Cause**: Changing household patterns, insufficient features, or missing temperature data
+- **Solution**:
+ - Enable temperature predictions for better accuracy
+ - Wait for fine-tuning to adapt to new patterns
+ - Verify historical data quality
+ - Consider adding PV data if you have solar panels
+
+### Viewing Predictions
+
+Access predictions via:
+
+1. **Web Interface**: Navigate to the battery plan view to see ML predictions
+2. **Home Assistant**: Check `sensor.predbat_load_ml_forecast` and its `results` attribute
+3. **Logs**: Look for "ML Predictor: Generated predictions" messages
+
+## Model Persistence
+
+The trained model is saved to disk as `predbat_ml_model.npz` in your Predbat config directory. This file contains:
+
+- Network weights and biases
+- Normalization parameters (mean, standard deviation)
+- Training metadata (epochs, timestamp, version)
+
+The model is automatically loaded on Predbat restart, allowing predictions to continue immediately without retraining.
+
+If the model becomes unstable you can also delete this file to start again.
+
+---
+
+## See Also
+
+- [Components Documentation](components.md) - Overview of all Predbat components
+- [Configuration Guide](configuration-guide.md) - General configuration guidance
+- [Temperature Component](components.md#temperature-api-temperature) - Setup guide for temperature forecasts
+- [Customisation Guide](customisation.md) - Advanced customisation options
diff --git a/mkdocs.yml b/mkdocs.yml
index 1dc956759..ccf2f8afd 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -12,6 +12,7 @@ nav:
- energy-rates.md
- apps-yaml.md
- components.md
+ - load-ml.md
- car-charging.md
- configuration-guide.md
- customisation.md