| name | nixtla-batch-forecaster |
| description | 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".
|
| 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
-
Error: NIXTLA_TIMEGPT_API_KEY not set
Solution: export NIXTLA_TIMEGPT_API_KEY=your_key
-
Error: API Rate Limit Exceeded
Solution: Increase --delay or reduce --batch-size
-
Error: Missing required columns
Solution: Ensure CSV has unique_id, ds, y columns
-
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/
