nixtla-batch-forecaster

intent-solutions-io's avatarfrom intent-solutions-io

Forecasts multiple time series in parallel batches using TimeGPT API.Optimizes throughput with rate limiting and supports portfolio aggregation.Use when processing 10-100+ contracts or needing efficient multi-series forecasting.Trigger with "batch forecast", "portfolio forecast", "parallel forecasting".

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 10, 2026
[Reporting]

When & Why to Use This Skill

The Nixtla Batch Forecaster is a high-performance Claude skill designed for large-scale time series analysis and predictive reporting. By integrating the state-of-the-art TimeGPT API, it enables users to generate parallel forecasts for hundreds of data series simultaneously with built-in rate limiting and error handling. This tool is optimized for efficiency, offering portfolio-level aggregation and automated report generation, making it an essential asset for data-driven decision-making and long-term trend analysis.

Use Cases

  • Financial Portfolio Management: Forecast future performance and risk metrics for 10-100+ individual contracts or investment vehicles in a single batch.
  • Supply Chain & Inventory Optimization: Predict demand across multiple product SKUs and locations to streamline stock levels and reduce operational waste.
  • Operational Resource Planning: Generate parallel forecasts for departmental workloads or energy consumption to optimize resource allocation and budgeting.
  • SaaS Growth Tracking: Analyze and predict multi-segment user growth, churn rates, and recurring revenue trends for comprehensive business health reporting.
namenixtla-batch-forecaster
description|
allowed-tools"Read,Write,Bash,Glob,Grep"
version"1.0.0"

Nixtla Batch Forecaster

Process multiple time series forecasts in parallel with optimized throughput.

Overview

Leverages TimeGPT API to generate forecasts for many time series concurrently. Features parallel batch processing with rate limiting, automatic fallback for failed batches, and optional portfolio-level aggregation. Produces individual forecasts per series plus combined outputs.

Prerequisites

Required:

  • Python 3.8+
  • nixtla, pandas, tqdm packages

Environment Variables:

  • NIXTLA_TIMEGPT_API_KEY: Your TimeGPT API key

Installation:

pip install nixtla pandas tqdm

Instructions

Step 1: Prepare Input Data

Your CSV must have the Nixtla schema columns:

Column Type Description
unique_id string Series identifier (contract ID)
ds datetime Timestamp
y numeric Value to forecast

Analyze your data:

python {baseDir}/scripts/prepare_data.py your_data.csv

Step 2: Set API Key

export NIXTLA_TIMEGPT_API_KEY=your_api_key_here

Step 3: Run Batch Forecast

Execute the batch forecasting engine:

python {baseDir}/scripts/batch_forecast.py your_data.csv --horizon 14 --freq D

Available options:

  • --horizon: Forecast horizon (default: 14)
  • --freq: Frequency D/H/W/M (default: D)
  • --batch-size: Series per batch (default: 20)
  • --output-dir: Output directory (default: forecasts)
  • --aggregate: Create portfolio aggregation
  • --delay: Rate limit delay in seconds (default: 1.0)

Step 4: Generate Report

Create a summary report:

python {baseDir}/scripts/generate_report.py forecasts/

Output

  • forecasts/all_forecasts.csv: Combined forecasts for all series
  • forecasts/{series}_forecast.csv: Individual series forecasts
  • forecasts/summary.json: Processing metadata
  • forecasts/aggregated_forecast.csv: Portfolio aggregation (if --aggregate)
  • forecasts/batch_report.md: Human-readable summary

Error Handling

  1. Error: NIXTLA_TIMEGPT_API_KEY not set Solution: export NIXTLA_TIMEGPT_API_KEY=your_key

  2. Error: API Rate Limit Exceeded Solution: Increase --delay or reduce --batch-size

  3. Error: Missing required columns Solution: Ensure CSV has unique_id, ds, y columns

  4. Error: Batch failed, falling back to individual Solution: Normal behavior - some series may have issues

Examples

Example 1: Forecast 50 Daily Contracts

python {baseDir}/scripts/batch_forecast.py contracts.csv \
    --horizon 14 \
    --freq D \
    --batch-size 10 \
    --output-dir forecasts/

Output:

Batch Forecast Complete
Series forecasted: 50/50
Success rate: 100.0%

Example 2: Hourly Portfolio with Aggregation

python {baseDir}/scripts/batch_forecast.py portfolio.csv \
    --horizon 24 \
    --freq H \
    --aggregate \
    --output-dir portfolio_forecasts/

Resources

  • Scripts:
    • {baseDir}/scripts/prepare_data.py - Data validation and analysis
    • {baseDir}/scripts/batch_forecast.py - Main forecasting engine
    • {baseDir}/scripts/generate_report.py - Report generation
  • Nixtla Docs: https://nixtla.github.io/