@pikaa-ai/pikaa 0.2.4 → 0.3.0

package/skills/timesfm-forecasting/examples/covariates-forecasting/output/sales_with_covariates.csv

@@ -0,0 +1,109 @@
+store_id,week,split,sales,base_sales,price,price_effect,promotion,holiday,day_of_week,store_type,region
+store_A,0,context,1369.59,1012.19,11.6299,7.4,1,1,0,premium,urban
+store_A,1,context,973.53,973.04,11.9757,0.49,0,0,1,premium,urban
+store_A,2,context,1064.63,1059.16,11.7269,5.46,0,0,2,premium,urban
+store_A,3,context,1077.59,1080.99,12.1698,-3.4,0,0,3,premium,urban
+store_A,4,context,980.39,979.14,11.9372,1.26,0,0,4,premium,urban
+store_A,5,context,1011.7,1018.36,12.3327,-6.65,0,0,5,premium,urban
+store_A,6,context,1084.16,1088.16,12.2003,-4.01,0,0,6,premium,urban
+store_A,7,context,1085.98,1082.23,11.8124,3.75,0,0,0,premium,urban
+store_A,8,context,1098.52,1105.17,12.3323,-6.65,0,0,1,premium,urban
+store_A,9,context,1075.62,1081.71,12.3048,-6.1,0,0,2,premium,urban
+store_A,10,context,1312.23,1159.98,11.8875,2.25,1,0,3,premium,urban
+store_A,11,context,1368.02,1163.79,11.7883,4.23,0,1,4,premium,urban
+store_A,12,context,1138.41,1142.06,12.1825,-3.65,0,0,5,premium,urban
+store_A,13,context,1197.29,1190.09,11.6398,7.2,0,0,6,premium,urban
+store_A,14,context,1174.12,1168.12,11.6999,6.0,0,0,0,premium,urban
+store_A,15,context,1128.16,1118.3,11.5074,9.85,0,0,1,premium,urban
+store_A,16,context,1163.81,1169.55,12.2869,-5.74,0,0,2,premium,urban
+store_A,17,context,1114.18,1117.48,12.1649,-3.3,0,0,3,premium,urban
+store_A,18,context,1186.87,1190.98,12.2052,-4.1,0,0,4,premium,urban
+store_A,19,context,1147.27,1152.88,12.2807,-5.61,0,0,5,premium,urban
+store_A,20,context,1146.48,1145.66,11.9589,0.82,0,0,6,premium,urban
+store_A,21,context,1121.83,1123.21,12.0687,-1.37,0,0,0,premium,urban
+store_A,22,context,1203.28,1196.08,11.6398,7.2,0,0,1,premium,urban
+store_A,23,context,1344.9,1137.19,11.6145,7.71,0,1,2,premium,urban
+store_A,24,horizon,1118.64,1122.01,12.1684,-3.37,0,0,3,premium,urban
+store_A,25,horizon,1121.14,1120.56,11.9711,0.58,0,0,4,premium,urban
+store_A,26,horizon,1149.99,1151.29,12.0652,-1.3,0,0,5,premium,urban
+store_A,27,horizon,1284.67,1139.97,12.265,-5.3,1,0,6,premium,urban
+store_A,28,horizon,1284.67,1137.36,12.1347,-2.69,1,0,0,premium,urban
+store_A,29,horizon,1132.79,1133.86,12.0536,-1.07,0,0,1,premium,urban
+store_A,30,horizon,1197.3,1198.49,12.0592,-1.18,0,0,2,premium,urban
+store_A,31,horizon,1247.22,1093.3,11.804,3.92,1,0,3,premium,urban
+store_A,32,horizon,1095.84,1086.46,11.5308,9.38,0,0,4,premium,urban
+store_A,33,horizon,1073.83,1072.57,11.9367,1.27,0,0,5,premium,urban
+store_A,34,horizon,1134.51,1128.8,11.7146,5.71,0,0,6,premium,urban
+store_A,35,horizon,1351.15,1149.32,11.9085,1.83,0,1,0,premium,urban
+store_B,0,context,1062.53,712.0,9.9735,0.53,1,1,0,standard,suburban
+store_B,1,context,904.49,749.83,9.767,4.66,1,0,1,standard,suburban
+store_B,2,context,813.63,810.26,9.8316,3.37,0,0,2,standard,suburban
+store_B,3,context,720.11,720.53,10.0207,-0.41,0,0,3,standard,suburban
+store_B,4,context,820.78,819.55,9.9389,1.22,0,0,4,standard,suburban
+store_B,5,context,833.27,823.7,9.5216,9.57,0,0,5,standard,suburban
+store_B,6,context,795.26,801.78,10.3263,-6.53,0,0,6,standard,suburban
+store_B,7,context,770.37,778.29,10.3962,-7.92,0,0,0,standard,suburban
+store_B,8,context,855.92,848.72,9.6402,7.2,0,0,1,standard,suburban
+store_B,9,context,832.33,833.41,10.054,-1.08,0,0,2,standard,suburban
+store_B,10,context,1029.44,871.61,9.6086,7.83,1,0,3,standard,suburban
+store_B,11,context,1066.35,869.8,10.1722,-3.44,0,1,4,standard,suburban
+store_B,12,context,942.86,938.49,9.7812,4.38,0,0,5,standard,suburban
+store_B,13,context,1015.99,869.18,10.1594,-3.19,1,0,6,standard,suburban
+store_B,14,context,836.44,840.98,10.227,-4.54,0,0,0,standard,suburban
+store_B,15,context,885.72,891.1,10.2686,-5.37,0,0,1,standard,suburban
+store_B,16,context,901.45,893.6,9.6077,7.85,0,0,2,standard,suburban
+store_B,17,context,1080.63,938.95,10.416,-8.32,1,0,3,standard,suburban
+store_B,18,context,922.14,916.74,9.7302,5.4,0,0,4,standard,suburban
+store_B,19,context,904.66,895.41,9.5374,9.25,0,0,5,standard,suburban
+store_B,20,context,935.48,936.58,10.0549,-1.1,0,0,6,standard,suburban
+store_B,21,context,979.23,826.64,9.8709,2.58,1,0,0,standard,suburban
+store_B,22,context,837.49,844.09,10.3298,-6.6,0,0,1,standard,suburban
+store_B,23,context,1021.39,827.56,10.3083,-6.17,0,1,2,standard,suburban
+store_B,24,horizon,847.21,843.55,9.8171,3.66,0,0,3,standard,suburban
+store_B,25,horizon,789.27,798.33,10.4529,-9.06,0,0,4,standard,suburban
+store_B,26,horizon,877.09,872.91,9.7909,4.18,0,0,5,standard,suburban
+store_B,27,horizon,832.42,832.72,10.0151,-0.3,0,0,6,standard,suburban
+store_B,28,horizon,781.9,777.02,9.756,4.88,0,0,0,standard,suburban
+store_B,29,horizon,781.04,789.76,10.436,-8.72,0,0,1,standard,suburban
+store_B,30,horizon,844.57,837.86,9.6646,6.71,0,0,2,standard,suburban
+store_B,31,horizon,863.43,854.33,9.5449,9.1,0,0,3,standard,suburban
+store_B,32,horizon,898.12,896.82,9.9351,1.3,0,0,4,standard,suburban
+store_B,33,horizon,1070.58,930.42,10.4924,-9.85,1,0,5,standard,suburban
+store_B,34,horizon,820.4,828.24,10.3917,-7.83,0,0,6,standard,suburban
+store_B,35,horizon,965.86,770.83,10.2486,-4.97,0,1,0,standard,suburban
+store_C,0,context,709.12,501.23,7.1053,7.89,0,1,0,discount,rural
+store_C,1,context,651.44,492.78,7.0666,8.67,1,0,1,discount,rural
+store_C,2,context,659.15,511.04,7.5944,-1.89,1,0,2,discount,rural
+store_C,3,context,733.06,575.98,7.1462,7.08,1,0,3,discount,rural
+store_C,4,context,712.21,568.7,7.8247,-6.49,1,0,4,discount,rural
+store_C,5,context,615.23,611.44,7.3103,3.79,0,0,5,discount,rural
+store_C,6,context,568.99,561.87,7.1439,7.12,0,0,6,discount,rural
+store_C,7,context,541.12,549.54,7.921,-8.42,0,0,0,discount,rural
+store_C,8,context,583.57,576.88,7.1655,6.69,0,0,1,discount,rural
+store_C,9,context,607.34,603.04,7.2847,4.31,0,0,2,discount,rural
+store_C,10,context,613.79,606.86,7.1536,6.93,0,0,3,discount,rural
+store_C,11,context,919.49,561.8,7.1155,7.69,1,1,4,discount,rural
+store_C,12,context,622.61,613.04,7.0211,9.58,0,0,5,discount,rural
+store_C,13,context,630.52,621.63,7.0554,8.89,0,0,6,discount,rural
+store_C,14,context,721.62,715.12,7.1746,6.51,0,0,0,discount,rural
+store_C,15,context,699.18,690.25,7.0534,8.93,0,0,1,discount,rural
+store_C,16,context,578.85,580.67,7.5911,-1.82,0,0,2,discount,rural
+store_C,17,context,598.23,601.84,7.6807,-3.61,0,0,3,discount,rural
+store_C,18,context,554.43,552.3,7.3936,2.13,0,0,4,discount,rural
+store_C,19,context,587.39,583.75,7.318,3.64,0,0,5,discount,rural
+store_C,20,context,615.58,615.67,7.5045,-0.09,0,0,6,discount,rural
+store_C,21,context,638.68,646.18,7.875,-7.5,0,0,0,discount,rural
+store_C,22,context,555.99,563.01,7.8511,-7.02,0,0,1,discount,rural
+store_C,23,context,768.83,559.7,7.0435,9.13,0,1,2,discount,rural
+store_C,24,horizon,499.62,493.25,7.1815,6.37,0,0,3,discount,rural
+store_C,25,horizon,570.9,565.64,7.2367,5.27,0,0,4,discount,rural
+store_C,26,horizon,677.52,522.5,7.2494,5.01,1,0,5,discount,rural
+store_C,27,horizon,685.25,536.68,7.5712,-1.42,1,0,6,discount,rural
+store_C,28,horizon,517.46,515.78,7.4163,1.67,0,0,0,discount,rural
+store_C,29,horizon,549.38,540.36,7.0493,9.01,0,0,1,discount,rural
+store_C,30,horizon,470.04,467.51,7.3736,2.53,0,0,2,discount,rural
+store_C,31,horizon,622.9,473.37,7.5238,-0.48,1,0,3,discount,rural
+store_C,32,horizon,620.09,612.12,7.1017,7.97,0,0,4,discount,rural
+store_C,33,horizon,614.45,471.12,7.8335,-6.67,1,0,5,discount,rural
+store_C,34,horizon,484.25,475.29,7.052,8.96,0,0,6,discount,rural
+store_C,35,horizon,781.64,590.14,7.9248,-8.5,0,1,0,discount,rural

package/skills/timesfm-forecasting/examples/global-temperature/README.md

@@ -0,0 +1,178 @@
+# TimesFM Forecast Report: Global Temperature Anomaly (2025)
+
+**Model:** TimesFM 1.0 (200M) PyTorch  
+**Generated:** 2026-02-21  
+**Source:** NOAA GISTEMP Global Land-Ocean Temperature Index
+
+---
+
+## Executive Summary
+
+TimesFM forecasts a mean temperature anomaly of **1.19°C** for 2025, slightly below the 2024 average of 1.25°C. The model predicts continued elevated temperatures with a peak of 1.30°C in March 2025 and a minimum of 1.06°C in December 2025.
+
+---
+
+## Input Data
+
+### Historical Temperature Anomalies (2022-2024)
+
+| Date | Anomaly (°C) | Date | Anomaly (°C) | Date | Anomaly (°C) |
+|------|-------------|------|-------------|------|-------------|
+| 2022-01 | 0.89 | 2023-01 | 0.87 | 2024-01 | 1.22 |
+| 2022-02 | 0.89 | 2023-02 | 0.98 | 2024-02 | 1.35 |
+| 2022-03 | 1.02 | 2023-03 | 1.21 | 2024-03 | 1.34 |
+| 2022-04 | 0.88 | 2023-04 | 1.00 | 2024-04 | 1.26 |
+| 2022-05 | 0.85 | 2023-05 | 0.94 | 2024-05 | 1.15 |
+| 2022-06 | 0.88 | 2023-06 | 1.08 | 2024-06 | 1.20 |
+| 2022-07 | 0.88 | 2023-07 | 1.18 | 2024-07 | 1.24 |
+| 2022-08 | 0.90 | 2023-08 | 1.24 | 2024-08 | 1.30 |
+| 2022-09 | 0.88 | 2023-09 | 1.47 | 2024-09 | 1.28 |
+| 2022-10 | 0.95 | 2023-10 | 1.32 | 2024-10 | 1.27 |
+| 2022-11 | 0.77 | 2023-11 | 1.18 | 2024-11 | 1.22 |
+| 2022-12 | 0.78 | 2023-12 | 1.16 | 2024-12 | 1.20 |
+
+**Statistics:**
+- Total observations: 36 months
+- Mean anomaly: 1.09°C
+- Trend (2022→2024): +0.37°C
+
+---
+
+## Raw Forecast Output
+
+### Point Forecast and Confidence Intervals
+
+| Month | Point | 80% CI | 90% CI |
+|-------|-------|--------|--------|
+| 2025-01 | 1.259 | [1.141, 1.297] | [1.248, 1.324] |
+| 2025-02 | 1.286 | [1.141, 1.340] | [1.277, 1.375] |
+| 2025-03 | 1.295 | [1.127, 1.355] | [1.287, 1.404] |
+| 2025-04 | 1.221 | [1.035, 1.290] | [1.208, 1.331] |
+| 2025-05 | 1.170 | [0.969, 1.239] | [1.153, 1.289] |
+| 2025-06 | 1.146 | [0.942, 1.218] | [1.128, 1.270] |
+| 2025-07 | 1.170 | [0.950, 1.248] | [1.151, 1.300] |
+| 2025-08 | 1.203 | [0.971, 1.284] | [1.186, 1.341] |
+| 2025-09 | 1.191 | [0.959, 1.283] | [1.178, 1.335] |
+| 2025-10 | 1.149 | [0.908, 1.240] | [1.126, 1.287] |
+| 2025-11 | 1.080 | [0.836, 1.176] | [1.062, 1.228] |
+| 2025-12 | 1.061 | [0.802, 1.153] | [1.037, 1.217] |
+
+### JSON Output
+
+```json
+{
+  "model": "TimesFM 1.0 (200M) PyTorch",
+  "input": {
+    "source": "NOAA GISTEMP Global Temperature Anomaly",
+    "n_observations": 36,
+    "date_range": "2022-01 to 2024-12",
+    "mean_anomaly_c": 1.089
+  },
+  "forecast": {
+    "horizon": 12,
+    "dates": ["2025-01", "2025-02", "2025-03", "2025-04", "2025-05", "2025-06",
+              "2025-07", "2025-08", "2025-09", "2025-10", "2025-11", "2025-12"],
+    "point": [1.259, 1.286, 1.295, 1.221, 1.170, 1.146, 1.170, 1.203, 1.191, 1.149, 1.080, 1.061]
+  },
+  "summary": {
+    "forecast_mean_c": 1.186,
+    "forecast_max_c": 1.295,
+    "forecast_min_c": 1.061,
+    "vs_last_year_mean": -0.067
+  }
+}
+```
+
+---
+
+## Visualization
+
+![Temperature Anomaly Forecast](forecast_visualization.png)
+
+---
+
+## Findings
+
+### Key Observations
+
+1. **Slight cooling trend expected**: The model forecasts a mean anomaly 0.07°C below 2024 levels, suggesting a potential stabilization after the record-breaking temperatures of 2023-2024.
+
+2. **Seasonal pattern preserved**: The forecast shows the expected seasonal variation with higher anomalies in late winter (Feb-Mar) and lower in late fall (Nov-Dec).
+
+3. **Widening uncertainty**: The 90% CI expands from ±0.04°C in January to ±0.08°C in December, reflecting typical forecast uncertainty growth over time.
+
+4. **Peak temperature**: March 2025 is predicted to have the highest anomaly at 1.30°C, potentially approaching the September 2023 record of 1.47°C.
+
+### Limitations
+
+- TimesFM is a zero-shot forecaster without physical climate model constraints
+- The 36-month training window may not capture multi-decadal climate trends
+- El Niño/La Niña cycles are not explicitly modeled
+
+### Recommendations
+
+- Use this forecast as a baseline comparison for physics-based climate models
+- Update forecast quarterly as new observations become available
+- Consider ensemble approaches combining TimesFM with other methods
+
+---
+
+## Reproducibility
+
+### Files
+
+| File | Description |
+|------|-------------|
+| `temperature_anomaly.csv` | Input data (36 months) |
+| `forecast_output.csv` | Point forecast with quantiles |
+| `forecast_output.json` | Machine-readable forecast |
+| `forecast_visualization.png` | Fan chart visualization |
+| `run_forecast.py` | Forecasting script |
+| `visualize_forecast.py` | Visualization script |
+| `run_example.sh` | One-click runner |
+
+### How to Reproduce
+
+```bash
+# Install dependencies
+uv pip install "timesfm[torch]" matplotlib pandas numpy
+
+# Run the complete example
+cd skills/timesfm-forecasting/examples/global-temperature
+./run_example.sh
+```
+
+---
+
+## Technical Notes
+
+### API Discovery
+
+The TimesFM PyTorch API differs from the GitHub README documentation:
+
+**Documented (GitHub README):**
+```python
+model = timesfm.TimesFm(
+    context_len=512,
+    horizon_len=128,
+    backend="gpu",
+)
+model.load_from_google_repo("google/timesfm-2.5-200m-pytorch")
+```
+
+**Actual Working API:**
+```python
+hparams = timesfm.TimesFmHparams(horizon_len=12)
+checkpoint = timesfm.TimesFmCheckpoint(
+    huggingface_repo_id="google/timesfm-1.0-200m-pytorch"
+)
+model = timesfm.TimesFm(hparams=hparams, checkpoint=checkpoint)
+```
+
+### TimesFM 2.5 PyTorch Issue
+
+The `google/timesfm-2.5-200m-pytorch` checkpoint downloads as `model.safetensors`, but the TimesFM loader expects `torch_model.ckpt`. This causes a `FileNotFoundError` at model load time. Using TimesFM 1.0 PyTorch resolves this issue.
+
+---
+
+*Report generated by TimesFM Forecasting Skill (scientific-agent-skills)*

package/skills/timesfm-forecasting/examples/global-temperature/generate_animation_data.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Generate animation data for interactive forecast visualization.
+
+This script runs TimesFM forecasts incrementally, starting with minimal data
+and adding one point at a time. Each forecast extends to the final date (2025-12).
+
+Output: animation_data.json with all forecast steps
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import timesfm
+
+# Configuration
+MIN_CONTEXT = 12  # Minimum points to start forecasting
+MAX_HORIZON = (
+    36  # Max forecast length (when we have 12 points, forecast 36 months to 2025-12)
+)
+TOTAL_MONTHS = 48  # Total months from 2022-01 to 2025-12 (graph extent)
+INPUT_FILE = Path(__file__).parent / "temperature_anomaly.csv"
+OUTPUT_FILE = Path(__file__).parent / "output" / "animation_data.json"
+
+
+def main() -> None:
+    print("=" * 60)
+    print("  TIMESFM ANIMATION DATA GENERATOR")
+    print("  Dynamic horizon - forecasts always reach 2025-12")
+    print("=" * 60)
+
+    # Load data
+    df = pd.read_csv(INPUT_FILE, parse_dates=["date"])
+    df = df.sort_values("date").reset_index(drop=True)
+
+    all_dates = df["date"].tolist()
+    all_values = df["anomaly_c"].values.astype(np.float32)
+
+    print(f"\n📊 Total data: {len(all_values)} months")
+    print(
+        f"   Date range: {all_dates[0].strftime('%Y-%m')} to {all_dates[-1].strftime('%Y-%m')}"
+    )
+    print(f"   Animation steps: {len(all_values) - MIN_CONTEXT + 1}")
+
+    # Load TimesFM with max horizon (will truncate output for shorter forecasts)
+    print(f"\n🤖 Loading TimesFM 1.0 (200M) PyTorch (horizon={MAX_HORIZON})...")
+    hparams = timesfm.TimesFmHparams(horizon_len=MAX_HORIZON)
+    checkpoint = timesfm.TimesFmCheckpoint(
+        huggingface_repo_id="google/timesfm-1.0-200m-pytorch"
+    )
+    model = timesfm.TimesFm(hparams=hparams, checkpoint=checkpoint)
+
+    # Generate forecasts for each step
+    animation_steps = []
+
+    for n_points in range(MIN_CONTEXT, len(all_values) + 1):
+        step_num = n_points - MIN_CONTEXT + 1
+        total_steps = len(all_values) - MIN_CONTEXT + 1
+
+        # Calculate dynamic horizon: forecast enough to reach 2025-12
+        horizon = TOTAL_MONTHS - n_points
+
+        print(
+            f"\n📈 Step {step_num}/{total_steps}: Using {n_points} points, forecasting {horizon} months..."
+        )
+
+        # Get historical data up to this point
+        historical_values = all_values[:n_points]
+        historical_dates = all_dates[:n_points]
+
+        # Run forecast (model outputs MAX_HORIZON, we truncate to actual horizon)
+        point, quantiles = model.forecast(
+            [historical_values],
+            freq=[0],
+        )
+
+        # Truncate to actual horizon
+        point = point[0][:horizon]
+        quantiles = quantiles[0, :horizon, :]
+
+        # Determine forecast dates
+        last_date = historical_dates[-1]
+        forecast_dates = pd.date_range(
+            start=last_date + pd.DateOffset(months=1),
+            periods=horizon,
+            freq="MS",
+        )
+
+        # Store step data
+        step_data = {
+            "step": step_num,
+            "n_points": n_points,
+            "horizon": horizon,
+            "last_historical_date": historical_dates[-1].strftime("%Y-%m"),
+            "historical_dates": [d.strftime("%Y-%m") for d in historical_dates],
+            "historical_values": historical_values.tolist(),
+            "forecast_dates": [d.strftime("%Y-%m") for d in forecast_dates],
+            "point_forecast": point.tolist(),
+            "q10": quantiles[:, 0].tolist(),
+            "q20": quantiles[:, 1].tolist(),
+            "q80": quantiles[:, 7].tolist(),
+            "q90": quantiles[:, 8].tolist(),
+        }
+
+        animation_steps.append(step_data)
+
+        # Show summary
+        print(f"   Last date: {historical_dates[-1].strftime('%Y-%m')}")
+        print(f"   Forecast to: {forecast_dates[-1].strftime('%Y-%m')}")
+        print(f"   Forecast mean: {point.mean():.3f}°C")
+
+    # Create output
+    output = {
+        "metadata": {
+            "model": "TimesFM 1.0 (200M) PyTorch",
+            "total_steps": len(animation_steps),
+            "min_context": MIN_CONTEXT,
+            "max_horizon": MAX_HORIZON,
+            "total_months": TOTAL_MONTHS,
+            "data_source": "NOAA GISTEMP Global Temperature Anomaly",
+            "full_date_range": f"{all_dates[0].strftime('%Y-%m')} to {all_dates[-1].strftime('%Y-%m')}",
+        },
+        "actual_data": {
+            "dates": [d.strftime("%Y-%m") for d in all_dates],
+            "values": all_values.tolist(),
+        },
+        "animation_steps": animation_steps,
+    }
+
+    # Save
+    with open(OUTPUT_FILE, "w") as f:
+        json.dump(output, f, indent=2)
+
+    print(f"\n" + "=" * 60)
+    print("  ✅ ANIMATION DATA COMPLETE")
+    print("=" * 60)
+    print(f"\n📁 Output: {OUTPUT_FILE}")
+    print(f"   Total steps: {len(animation_steps)}")
+    print(f"   Each forecast extends to 2025-12")
+
+
+if __name__ == "__main__":
+    main()

package/skills/timesfm-forecasting/examples/global-temperature/generate_gif.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""
+Generate animated GIF showing forecast evolution.
+
+Creates a GIF animation showing how the TimesFM forecast changes
+as more historical data points are added. Shows the full actual data as a background layer.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import matplotlib.dates as mdates
+import numpy as np
+import pandas as pd
+from PIL import Image
+
+# Configuration
+EXAMPLE_DIR = Path(__file__).parent
+DATA_FILE = EXAMPLE_DIR / "output" / "animation_data.json"
+OUTPUT_FILE = EXAMPLE_DIR / "output" / "forecast_animation.gif"
+DURATION_MS = 500  # Time per frame in milliseconds
+
+
+def create_frame(
+    ax,
+    step_data: dict,
+    actual_data: dict,
+    final_forecast: dict,
+    total_steps: int,
+    x_min,
+    x_max,
+    y_min,
+    y_max,
+) -> None:
+    """Create a single frame of the animation with fixed axes."""
+    ax.clear()
+
+    # Parse dates
+    historical_dates = pd.to_datetime(step_data["historical_dates"])
+    forecast_dates = pd.to_datetime(step_data["forecast_dates"])
+    
+    # Get final forecast dates for full extent
+    final_forecast_dates = pd.to_datetime(final_forecast["forecast_dates"])
+    
+    # All actual dates for full background
+    all_actual_dates = pd.to_datetime(actual_data["dates"])
+    all_actual_values = np.array(actual_data["values"])
+
+    # ========== BACKGROUND LAYER: Full actual data (faded) ==========
+    ax.plot(
+        all_actual_dates,
+        all_actual_values,
+        color="#9ca3af",
+        linewidth=1,
+        marker="o",
+        markersize=2,
+        alpha=0.3,
+        label="All observed data",
+        zorder=1,
+    )
+    
+    # ========== BACKGROUND LAYER: Final forecast (faded) ==========
+    ax.plot(
+        final_forecast_dates,
+        final_forecast["point_forecast"],
+        color="#fca5a5",
+        linewidth=1,
+        linestyle="--",
+        marker="s",
+        markersize=2,
+        alpha=0.3,
+        label="Final forecast",
+        zorder=2,
+    )
+
+    # ========== FOREGROUND LAYER: Historical data used (bright) ==========
+    ax.plot(
+        historical_dates,
+        step_data["historical_values"],
+        color="#3b82f6",
+        linewidth=2.5,
+        marker="o",
+        markersize=5,
+        label="Data used",
+        zorder=10,
+    )
+
+    # ========== FOREGROUND LAYER: Current forecast (bright) ==========
+    # 90% CI (outer)
+    ax.fill_between(
+        forecast_dates,
+        step_data["q10"],
+        step_data["q90"],
+        alpha=0.15,
+        color="#ef4444",
+        zorder=5,
+    )
+    
+    # 80% CI (inner)
+    ax.fill_between(
+        forecast_dates,
+        step_data["q20"],
+        step_data["q80"],
+        alpha=0.25,
+        color="#ef4444",
+        zorder=6,
+    )
+    
+    # Forecast line
+    ax.plot(
+        forecast_dates,
+        step_data["point_forecast"],
+        color="#ef4444",
+        linewidth=2.5,
+        marker="s",
+        markersize=5,
+        label="Forecast",
+        zorder=7,
+    )
+
+    # ========== Vertical line at forecast boundary ==========
+    ax.axvline(
+        x=historical_dates[-1],
+        color="#6b7280",
+        linestyle="--",
+        linewidth=1.5,
+        alpha=0.7,
+        zorder=8,
+    )
+
+    # ========== Formatting ==========
+    ax.set_xlabel("Date", fontsize=11)
+    ax.set_ylabel("Temperature Anomaly (°C)", fontsize=11)
+    ax.set_title(
+        f"TimesFM Forecast Evolution\n"
+        f"Step {step_data['step']}/{total_steps}: {step_data['n_points']} points → "
+        f"forecast from {step_data['last_historical_date']}",
+        fontsize=13,
+        fontweight="bold",
+    )
+    
+    ax.grid(True, alpha=0.3, zorder=0)
+    ax.legend(loc="upper left", fontsize=8)
+    
+    # FIXED AXES - same for all frames
+    ax.set_xlim(x_min, x_max)
+    ax.set_ylim(y_min, y_max)
+    
+    # Format x-axis
+    ax.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m"))
+    ax.xaxis.set_major_locator(mdates.MonthLocator(interval=4))
+    plt.setp(ax.xaxis.get_majorticklabels(), rotation=45, ha="right")
+
+
+def main() -> None:
+    print("=" * 60)
+    print("  GENERATING ANIMATED GIF")
+    print("=" * 60)
+    
+    # Load data
+    with open(DATA_FILE) as f:
+        data = json.load(f)
+    
+    total_steps = len(data["animation_steps"])
+    print(f"\n📊 Total frames: {total_steps}")
+    
+    # Get the final forecast step for reference
+    final_forecast = data["animation_steps"][-1]
+    
+    # Calculate fixed axis extents from ALL data
+    all_actual_dates = pd.to_datetime(data["actual_data"]["dates"])
+    all_actual_values = np.array(data["actual_data"]["values"])
+    
+    final_forecast_dates = pd.to_datetime(final_forecast["forecast_dates"])
+    final_forecast_values = np.array(final_forecast["point_forecast"])
+    
+    # X-axis: from first actual date to last forecast date
+    x_min = all_actual_dates[0]
+    x_max = final_forecast_dates[-1]
+    
+    # Y-axis: min/max across all actual + all forecasts with CIs
+    all_forecast_q10 = np.array(final_forecast["q10"])
+    all_forecast_q90 = np.array(final_forecast["q90"])
+    
+    all_values = np.concatenate([
+        all_actual_values,
+        final_forecast_values,
+        all_forecast_q10,
+        all_forecast_q90,
+    ])
+    y_min = all_values.min() - 0.05
+    y_max = all_values.max() + 0.05
+    
+    print(f"   X-axis: {x_min.strftime('%Y-%m')} to {x_max.strftime('%Y-%m')}")
+    print(f"   Y-axis: {y_min:.2f}°C to {y_max:.2f}°C")
+    
+    # Create figure
+    fig, ax = plt.subplots(figsize=(12, 6))
+    
+    # Generate frames
+    frames = []
+    
+    for i, step in enumerate(data["animation_steps"]):
+        print(f"   Frame {i + 1}/{total_steps}...")
+        
+        create_frame(
+            ax,
+            step,
+            data["actual_data"],
+            final_forecast,
+            total_steps,
+            x_min,
+            x_max,
+            y_min,
+            y_max,
+        )
+        
+        # Save frame to buffer
+        fig.canvas.draw()
+        
+        # Convert to PIL Image
+        buf = fig.canvas.buffer_rgba()
+        width, height = fig.canvas.get_width_height()
+        img = Image.frombytes("RGBA", (width, height), buf)
+        frames.append(img.convert("RGB"))
+    
+    plt.close()
+    
+    # Save as GIF
+    print(f"\n💾 Saving GIF: {OUTPUT_FILE}")
+    frames[0].save(
+        OUTPUT_FILE,
+        save_all=True,
+        append_images=frames[1:],
+        duration=DURATION_MS,
+        loop=0,  # Loop forever
+    )
+    
+    # Get file size
+    size_kb = OUTPUT_FILE.stat().st_size / 1024
+    print(f"   File size: {size_kb:.1f} KB")
+    print(f"\n✅ Done!")
+
+
+if __name__ == "__main__":
+    main()