intent-solutions-io/nixtla-timegpt-lab

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