@faim-group/sdk-forecasting

Zero-shot time-series forecasting in JavaScript using state-of-the-art foundation models. Get accurate predictions without training or complex setup.

📦 View on npm | 📚 GitHub | 🌐 Website

Features

• Zero-Shot Forecasting - Works out-of-the-box without model training
• Advanced Models - Chronos2 from AWS and TiRex from NXAI
• Point & Quantile Forecasts - Get predictions and uncertainty estimates
• Type-Safe - Full TypeScript support with strict type checking
• Automatic Retries - Built-in exponential backoff for reliability

Installation

Install the package using your preferred package manager:

# npm
npm install @faim-group/sdk-forecasting

# pnpm
pnpm add @faim-group/sdk-forecasting

# yarn
yarn add @faim-group/sdk-forecasting

Quick Start

1. Get an API Key

Visit faim.it.com to sign up and get your API key.

2. Set Environment Variable

export FAIM_API_KEY="your_api_key_here"

3. Basic Usage

import { FaimClient } from "@faim-group/sdk-forecasting";

const client = new FaimClient(process.env.FAIM_API_KEY!);

const result = await client.forecastChronos2({
  x: [[[1], [2], [3], [4], [5]]],
  horizon: 10,
  output_type: "point",
});

if (result.success) {
  console.log("Forecasts:", result.data.outputs.point);
} else {
  console.error("Error:", result.error.message);
}

Models

Chronos2

State-of-the-art for diverse time series. Supports custom quantiles.

await client.forecastChronos2({
  x: data,
  horizon: 10,
  output_type: "quantiles",
  quantiles: [0.1, 0.5, 0.9], // Optional (default: [0.1, 0.2, ..., 0.9])
});

TiRex

Specialized for irregular or sparse time series.

await client.forecastTiRex({
  x: data,
  horizon: 10,
  output_type: "point",
});

Input/Output Shapes

Input Format: 3D Array

All models expect: x: number[][][] with shape [batch_size, sequence_length, num_features]

// Example: 1 sequence, 5 timesteps, 1 feature
const x = [[[1], [2], [3], [4], [5]]];

// Example: 2 sequences, 3 timesteps, 2 features
const x = [
  [[1, 2], [3, 4], [5, 6]],
  [[7, 8], [9, 10], [11, 12]]
];

Output Format

Point Forecasts (output_type: "point"):

outputs.point: number[][][] // [batch_size, horizon, num_features]

Quantile Forecasts (output_type: "quantiles"):

outputs.quantiles: number[][][][] // [batch_size, horizon, num_quantiles, num_features]

Error Handling

const result = await client.forecastChronos2({ x, horizon: 10, output_type: "point" });

if (result.success) {
  console.log(result.data.outputs);
} else {
  console.error(result.error.error_code, result.error.message);
}

Error Type Checking

import { isAuthError, isValidationError, isTimeoutError } from "@faim-group/sdk-forecasting";

if (!result.success) {
  if (isAuthError(result.error)) {
    console.error("Invalid API key");
  } else if (isValidationError(result.error)) {
    console.error("Invalid input");
  } else if (isTimeoutError(result.error)) {
    console.error("Request timed out - reduce batch size");
  }
}

Configuration

const client = new FaimClient(apiKey, {
  baseUrl: "https://api.faim.it.com", // Default
  timeout: 30000, // 30 seconds
  maxRetries: 2, // Automatic exponential backoff
});

Examples

Using Examples from npm Package

The best way to learn how to use the SDK is by looking at the examples. You can either:

Option 1: Install the npm package and run examples locally

# Install the package
npm install @faim-group/sdk-forecasting

# Clone the repository to access examples
git clone https://github.com/S-FM/faim-js-client
cd faim-js-client

# Set your API key
export FAIM_API_KEY="your_api_key_here"

# Run an example
pnpm install
pnpm tsx examples/basic_forecast/chronos2.ts

Option 2: View examples in the repository

Visit the GitHub repository to browse the examples without cloning.

Running Example Scripts Locally

To run example scripts from this repository, use the pnpm tsx command:

pnpm tsx examples/<filename>.ts

Make sure you have FAIM_API_KEY set as an environment variable:

export FAIM_API_KEY="your_api_key_here"

Available Examples

Basic Point Forecasts:

pnpm tsx examples/basic_forecast/chronos2.ts
pnpm tsx examples/basic_forecast/tirex.ts

Quantile Forecasts:

pnpm tsx examples/quantiles_forecast/chronos2.ts
pnpm tsx examples/quantiles_forecast/tirex.ts

Comprehensive Example (Air Passengers Dataset):

pnpm tsx examples/air_passengers.ts

The Air Passengers example demonstrates:

• Point and probabilistic forecasting with both Chronos2 and TiRex models
• Metric calculation (MAE, MSE)
• Formatted table output with predictions and confidence intervals

License

MIT