diff --git a/docs/examples/custom-ensembles.ipynb b/docs/examples/custom-ensembles.ipynb
new file mode 100644
index 0000000..a57c4fe
--- /dev/null
+++ b/docs/examples/custom-ensembles.ipynb
@@ -0,0 +1,536 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Building Custom Ensembles\n",
+ "\n",
+ "TimeCopilot ships a built-in [`MedianEnsemble`](../api/models/ensembles.md) that combines several models by taking the median of their forecasts. But you are not limited to it: any aggregation you can think of can be packaged as a reusable ensemble.\n",
+ "\n",
+ "This tutorial shows how to build your own ensemble from scratch and run it with the low-level `TimeCopilotForecaster` API. We'll implement a `WeightedEnsemble` that plugs in your own weighting scheme."
+ ],
+ "id": "a1b2c3d0"
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## The ensemble contract\n",
+ "\n",
+ "An ensemble in TimeCopilot is just a `Forecaster`. To build your own you only need to:\n",
+ "\n",
+ "1. Subclass `Forecaster`.\n",
+ "2. Set `self.alias` (the name of your ensemble's output column).\n",
+ "3. Implement `forecast(...)`, returning a DataFrame with `unique_id`, `ds`, and a column named `self.alias`.\n",
+ "\n",
+ "That's it. The base class gives you `cross_validation` and `plot` for free, and your ensemble can be used anywhere a `Forecaster` is expected. The built-in `MedianEnsemble` follows exactly this pattern: it wraps a `TimeCopilotForecaster` internally to get one column per model, then aggregates those columns."
+ ],
+ "id": "a1b2c3d1"
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Imports"
+ ],
+ "id": "a1b2c3d2"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "import pandas as pd\n",
+ "\n",
+ "from timecopilot import TimeCopilotForecaster\n",
+ "from timecopilot.models.utils.forecaster import Forecaster\n",
+ "from timecopilot.models.foundation.chronos import Chronos\n",
+ "from timecopilot.models.stats import AutoARIMA, SeasonalNaive"
+ ],
+ "execution_count": null,
+ "outputs": [],
+ "id": "a1b2c3d3"
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Define a custom `WeightedEnsemble`\n",
+ "\n",
+ "Our ensemble takes a list of base models and an optional list of `weights`. Internally it delegates to `TimeCopilotForecaster`, which returns one forecast column per model (named after each model's alias). For every timestamp we then combine those columns into a single prediction by multiplying each model's forecast by its weight and summing the results. When no weights are given, every model gets the same weight, which is just the plain average.\n",
+ "\n",
+ "The weights only express *relative* importance, so you do not have to pass fractions that add up to 1. The ensemble normalizes them for you: it divides each weight by the sum of all weights before combining. That is why we can use whole numbers like `[2, 1, 1]` instead of `[0.5, 0.25, 0.25]`. Both mean exactly the same thing: the first model counts twice as much as each of the other two. Writing `[2, 1, 1]` is easier to read and to tweak, and you never have to recompute the fractions when you add or remove a model.\n",
+ "\n",
+ "This keeps the example focused on point forecasts. To also produce quantiles, you would aggregate the per-model `{alias}-q-{pct}` columns the same way and use `QuantileConverter`, exactly as the built-in `MedianEnsemble` does."
+ ],
+ "id": "a1b2c3d4"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "class WeightedEnsemble(Forecaster):\n",
+ " def __init__(\n",
+ " self,\n",
+ " models: list[Forecaster],\n",
+ " weights: list[float] | None = None,\n",
+ " alias: str = \"WeightedEnsemble\",\n",
+ " ):\n",
+ " if weights is not None and len(weights) != len(models):\n",
+ " raise ValueError(\"`weights` must have the same length as `models`.\")\n",
+ " self.tcf = TimeCopilotForecaster(models=models, fallback_model=None)\n",
+ " self.weights = weights\n",
+ " self.alias = alias\n",
+ "\n",
+ " def forecast(\n",
+ " self,\n",
+ " df: pd.DataFrame,\n",
+ " h: int,\n",
+ " freq: str | None = None,\n",
+ " level: list[int | float] | None = None,\n",
+ " quantiles: list[float] | None = None,\n",
+ " ) -> pd.DataFrame:\n",
+ " # one forecast column per base model\n",
+ " fcst_df = self.tcf.forecast(df=df, h=h, freq=freq)\n",
+ " model_cols = [model.alias for model in self.tcf.models]\n",
+ " weights = self.weights or [1.0] * len(model_cols)\n",
+ " weights = pd.Series(weights, index=model_cols)\n",
+ " weights = weights / weights.sum()\n",
+ " out = fcst_df[[\"unique_id\", \"ds\"]].copy()\n",
+ " out[self.alias] = fcst_df[model_cols].mul(weights, axis=1).sum(axis=1)\n",
+ " return out"
+ ],
+ "execution_count": 2,
+ "outputs": [],
+ "id": "a1b2c3d5"
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Load data\n",
+ "\n",
+ "We use the classic AirPassengers series. The DataFrame must contain `unique_id`, `ds`, and `y` columns."
+ ],
+ "id": "a1b2c3d6"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "df = pd.read_csv(\n",
+ " \"https://timecopilot.s3.amazonaws.com/public/data/air_passengers.csv\",\n",
+ " parse_dates=[\"ds\"],\n",
+ ")\n",
+ "df.head()"
+ ],
+ "execution_count": 3,
+ "outputs": [
+ {
+ "output_type": "execute_result",
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " unique_id \n",
+ " ds \n",
+ " y \n",
+ " \n",
+ " \n",
+ " \n",
+ " \n",
+ " 0 \n",
+ " AirPassengers \n",
+ " 1949-01-01 \n",
+ " 112 \n",
+ " \n",
+ " \n",
+ " 1 \n",
+ " AirPassengers \n",
+ " 1949-02-01 \n",
+ " 118 \n",
+ " \n",
+ " \n",
+ " 2 \n",
+ " AirPassengers \n",
+ " 1949-03-01 \n",
+ " 132 \n",
+ " \n",
+ " \n",
+ " 3 \n",
+ " AirPassengers \n",
+ " 1949-04-01 \n",
+ " 129 \n",
+ " \n",
+ " \n",
+ " 4 \n",
+ " AirPassengers \n",
+ " 1949-05-01 \n",
+ " 121 \n",
+ " \n",
+ " \n",
+ "
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " unique_id \n",
+ " ds \n",
+ " WeightedEnsemble \n",
+ " \n",
+ " \n",
+ " \n",
+ " \n",
+ " 0 \n",
+ " AirPassengers \n",
+ " 1961-01-01 \n",
+ " 438.240814 \n",
+ " \n",
+ " \n",
+ " 1 \n",
+ " AirPassengers \n",
+ " 1961-02-01 \n",
+ " 430.611206 \n",
+ " \n",
+ " \n",
+ " 2 \n",
+ " AirPassengers \n",
+ " 1961-03-01 \n",
+ " 457.616318 \n",
+ " \n",
+ " \n",
+ " 3 \n",
+ " AirPassengers \n",
+ " 1961-04-01 \n",
+ " 484.624809 \n",
+ " \n",
+ " \n",
+ " 4 \n",
+ " AirPassengers \n",
+ " 1961-05-01 \n",
+ " 513.398132 \n",
+ " \n",
+ " \n",
+ "
\n",
+ "
"
+ ]
+ },
+ "metadata": {},
+ "execution_count": 5
+ }
+ ],
+ "id": "a1b2c3db"
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Compare ensembles side by side\n",
+ "\n",
+ "Because every ensemble is just a `Forecaster`, you can drop your `WeightedEnsemble` into a `TimeCopilotForecaster` next to the built-in `MedianEnsemble` and any regular model (here `AutoETS`). This runs them together and returns one column per forecaster, so you can compare them directly."
+ ],
+ "id": "9e9085a0"
+ },
+ {
+ "cell_type": "code",
+ "metadata": {},
+ "source": [
+ "from timecopilot.models.ensembles.median import MedianEnsemble\n",
+ "from timecopilot.models.stats import AutoETS\n",
+ "\n",
+ "tcf = TimeCopilotForecaster(\n",
+ " models=[\n",
+ " WeightedEnsemble(models=models, weights=[2.0, 1.0, 1.0]),\n",
+ " MedianEnsemble(models=models),\n",
+ " AutoETS(),\n",
+ " ]\n",
+ ")\n",
+ "\n",
+ "fcst_df = tcf.forecast(df=df, h=12)\n",
+ "fcst_df.head()"
+ ],
+ "execution_count": 6,
+ "outputs": [
+ {
+ "output_type": "stream",
+ "text": [
+ "100%|██████████| 1/1 [00:00<00:00, 11.16it/s]\n",
+ "100%|██████████| 1/1 [00:00<00:00, 11.60it/s]\n"
+ ],
+ "name": "stdout"
+ },
+ {
+ "output_type": "execute_result",
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " unique_id \n",
+ " ds \n",
+ " WeightedEnsemble \n",
+ " MedianEnsemble \n",
+ " AutoETS \n",
+ " \n",
+ " \n",
+ " \n",
+ " \n",
+ " 0 \n",
+ " AirPassengers \n",
+ " 1961-01-01 \n",
+ " 434.490509 \n",
+ " 444.309570 \n",
+ " 442.357178 \n",
+ " \n",
+ " \n",
+ " 1 \n",
+ " AirPassengers \n",
+ " 1961-02-01 \n",
+ " 429.840576 \n",
+ " 418.213745 \n",
+ " 428.267365 \n",
+ " \n",
+ " \n",
+ " 2 \n",
+ " AirPassengers \n",
+ " 1961-03-01 \n",
+ " 450.629410 \n",
+ " 446.243408 \n",
+ " 492.974792 \n",
+ " \n",
+ " \n",
+ " 3 \n",
+ " AirPassengers \n",
+ " 1961-04-01 \n",
+ " 481.439613 \n",
+ " 476.343262 \n",
+ " 477.369995 \n",
+ " \n",
+ " \n",
+ " 4 \n",
+ " AirPassengers \n",
+ " 1961-05-01 \n",
+ " 503.482880 \n",
+ " 499.237061 \n",
+ " 477.602814 \n",
+ " \n",
+ " \n",
+ "
\n",
+ "
"
+ ]
+ },
+ "metadata": {},
+ "execution_count": 7
+ }
+ ],
+ "id": "a125a34e"
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Recap\n",
+ "\n",
+ "Building a custom ensemble comes down to subclassing `Forecaster`, setting an `alias`, and implementing `forecast`. Because it is a regular `Forecaster`, the same class can be:\n",
+ "\n",
+ "- dropped into a `TimeCopilotForecaster(models=[...])` alongside other models,\n",
+ "- passed to the agent via `forecasters=[...]`,\n",
+ "- cross-validated with `ensemble.cross_validation(...)`.\n",
+ "\n",
+ "For a complete reference implementation, including probabilistic (quantile) forecasts, see the built-in [`MedianEnsemble`](../api/models/ensembles.md)."
+ ],
+ "id": "a1b2c3dc"
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.11.12"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/examples/explaining-foundation-models-and-ensembles.ipynb b/docs/examples/explaining-foundation-models-and-ensembles.ipynb
new file mode 100644
index 0000000..e89c77b
--- /dev/null
+++ b/docs/examples/explaining-foundation-models-and-ensembles.ipynb
@@ -0,0 +1,317 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "a1b2c3d4",
+ "metadata": {},
+ "source": [
+ "# Explaining Foundation Models & Ensembles\n",
+ "\n",
+ "This example shows how to give the `TimeCopilot` agent your own foundation models and an ensemble, and then ask plain-English questions to understand and compare them."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "b2c3d4e5",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import nest_asyncio\n",
+ "\n",
+ "nest_asyncio.apply()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "c3d4e5f6",
+ "metadata": {},
+ "source": [
+ "## Import libraries"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d4e5f6a7",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import pandas as pd\n",
+ "\n",
+ "from timecopilot import TimeCopilot\n",
+ "from timecopilot.models.foundation.chronos import Chronos\n",
+ "from timecopilot.models.ensembles.median import MedianEnsemble\n",
+ "from timecopilot.models.stats import SeasonalNaive"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "e5f6a7b8",
+ "metadata": {},
+ "source": [
+ "## Load the dataset\n",
+ "\n",
+ "The DataFrame must include at least the following columns:\n",
+ "- unique_id: Unique identifier for each time series (string)\n",
+ "- ds: Date column (datetime format)\n",
+ "- y: Target variable for forecasting (float format)\n",
+ "\n",
+ "The pandas frequency will be inferred from the ds column, if not provided.\n",
+ "If the seasonality is not provided, it will be inferred based on the frequency.\n",
+ "If the horizon is not set, it will default to 2 times the inferred seasonality."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "f6a7b8c9",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " unique_id \n",
+ " ds \n",
+ " y \n",
+ " \n",
+ " \n",
+ " \n",
+ " \n",
+ " 0 \n",
+ " AirPassengers \n",
+ " 1949-01-01 \n",
+ " 112 \n",
+ " \n",
+ " \n",
+ " 1 \n",
+ " AirPassengers \n",
+ " 1949-02-01 \n",
+ " 118 \n",
+ " \n",
+ " \n",
+ " 2 \n",
+ " AirPassengers \n",
+ " 1949-03-01 \n",
+ " 132 \n",
+ " \n",
+ " \n",
+ " 3 \n",
+ " AirPassengers \n",
+ " 1949-04-01 \n",
+ " 129 \n",
+ " \n",
+ " \n",
+ " 4 \n",
+ " AirPassengers \n",
+ " 1949-05-01 \n",
+ " 121 \n",
+ " \n",
+ " \n",
+ "
\n",
+ "