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
- 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
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-forecastingVisit faim.it.com to sign up and get your API key.
export FAIM_API_KEY="your_api_key_here"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); }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]) });Specialized for irregular or sparse time series.
await client.forecastTiRex({ x: data, horizon: 10, output_type: "point", });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]] ];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]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); }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"); } }const client = new FaimClient(apiKey, { baseUrl: "https://api.faim.it.com", // Default timeout: 30000, // 30 seconds maxRetries: 2, // Automatic exponential backoff });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.tsOption 2: View examples in the repository
Visit the GitHub repository to browse the examples without cloning.
To run example scripts from this repository, use the pnpm tsx command:
pnpm tsx examples/<filename>.tsMake sure you have FAIM_API_KEY set as an environment variable:
export FAIM_API_KEY="your_api_key_here"Basic Point Forecasts:
pnpm tsx examples/basic_forecast/chronos2.ts pnpm tsx examples/basic_forecast/tirex.tsQuantile Forecasts:
pnpm tsx examples/quantiles_forecast/chronos2.ts pnpm tsx examples/quantiles_forecast/tirex.tsComprehensive Example (Air Passengers Dataset):
pnpm tsx examples/air_passengers.tsThe 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
MIT