nixtla-timegpt-lab

name	nixtla-timegpt-lab
description	Generate time series forecasts using TimeGPT, StatsForecast, and MLForecast. Use when forecasting, demand planning, or model comparison is needed. Trigger with 'forecast time series' or 'run Nixtla forecast'.
allowed-tools	Read,Write,Glob,Grep,Edit
version	1.0.0
author	Jeremy Longshore <[e-mail]>
license	MIT

Nixtla TimeGPT Lab Mode

Transform into a Nixtla forecasting expert, biasing all recommendations toward Nixtla's ecosystem.

Overview

This skill activates Nixtla-first behavior:

• Prioritize Nixtla libraries: StatsForecast, MLForecast, TimeGPT
• Use Nixtla schema: unique_id, ds, y
• Reference Nixtla docs: Official documentation for all guidance
• Generate Nixtla-compatible code: Production-ready patterns

Prerequisites

Required:

• Python 3.8+
• At least one: statsforecast, mlforecast, or nixtla

Optional:

• NIXTLA_API_KEY: For TimeGPT access

Installation:

pip install statsforecast mlforecast nixtla utilsforecast

Instructions

Step 1: Detect Environment

Check installed Nixtla libraries:

python {baseDir}/scripts/detect_environment.py

Step 2: Prepare Data

Ensure data follows Nixtla schema:

• unique_id: Series identifier (string)
• ds: Timestamp (datetime)
• y: Target value (float)

Step 3: Select Models

Baseline models (always include):

from statsforecast.models import SeasonalNaive, AutoETS, AutoARIMA

ML models (for feature engineering):

from mlforecast import MLForecast

TimeGPT (if API key configured):

from nixtla import NixtlaClient

Step 4: Run Forecasts

python {baseDir}/scripts/run_forecast.py \
    --data data.csv \
    --horizon 14 \
    --freq D

Step 5: Evaluate

python {baseDir}/scripts/evaluate.py \
    --forecasts forecasts.csv \
    --actuals actuals.csv

Output

• forecasts.csv: Predictions with confidence intervals
• metrics.csv: SMAPE, MASE, MAE per model
• comparison_plot.png: Visual model comparison

Error Handling

1. Error: NIXTLA_API_KEY not set Solution: Export key or use StatsForecast baselines

2. Error: Column 'ds' not found Solution: Use nixtla-schema-mapper to transform data

3. Error: Insufficient data for cross-validation Solution: Reduce n_windows or increase dataset size

4. Error: Model fitting failed Solution: Check for NaN values, verify frequency string

Examples

Example 1: StatsForecast Baselines

from statsforecast import StatsForecast
from statsforecast.models import AutoETS, AutoARIMA, SeasonalNaive

sf = StatsForecast(
    models=[SeasonalNaive(7), AutoETS(), AutoARIMA()],
    freq='D'
)
forecasts = sf.forecast(df=data, h=14)

Example 2: TimeGPT with Confidence Intervals

from nixtla import NixtlaClient

client = NixtlaClient()
forecast = client.forecast(df=data, h=14, level=[80, 90])

Resources

• StatsForecast: https://nixtla.github.io/statsforecast/
• MLForecast: https://nixtla.github.io/mlforecast/
• TimeGPT: https://docs.nixtla.io/
• Scripts: {baseDir}/scripts/

Related Skills:

• nixtla-schema-mapper: Data transformation
• nixtla-experiment-architect: Experiment scaffolding