sinapsis-timesfm 0.1.1

Module for time series forecasting using Google's TimesFM foundation model.

Sinapsis TimesFM

Module for time series forecasting using Google's TimesFM foundation model.

🐍 Installation • 🚀 Features • 📚 Usage Example • 📙 Documentation • 🔍 License

Sinapsis TimesFM provides zero-shot time series forecasting using Google's TimesFM foundation model. It supports both pandas DataFrame and Darts TimeSeries outputs, including point and quantile predictions.

🐍 Installation

Install using your package manager of choice. We encourage the use of uv

Example with uv:

  uv pip install sinapsis-timesfm --extra-index-url https://pypi.sinapsis.tech

or with raw pip:

  pip install sinapsis-timesfm --extra-index-url https://pypi.sinapsis.tech

[!NOTE] TimesFM supports multiple backends. Install the one you need:

uv pip install sinapsis-timesfm[torch] --extra-index-url https://pypi.sinapsis.tech   # PyTorch
uv pip install sinapsis-timesfm[flax] --extra-index-url https://pypi.sinapsis.tech    # Flax/JAX
uv pip install sinapsis-timesfm[all] --extra-index-url https://pypi.sinapsis.tech     # All backends

🚀 Features

Templates Supported

TimesFM

Zero-shot time series forecasting template powered by Google's TimesFM 2.5 foundation model. Accepts pandas DataFrames or Darts TimeSeries as input, automatically sorts by time, and produces point forecasts with optional quantile predictions.

The following attributes apply to the TimesFM template:

• model_name (str, optional): Hugging Face model identifier for TimesFM. Defaults to "google/timesfm-2.5-200m-pytorch".
• forecasting_config (ForecastConfigBM, optional): Forecasting behavior configuration passed to TimesFM.compile(). Defaults to ForecastConfigBM().
• forecast_horizon (int, optional): Number of future steps to predict for each input series. Defaults to 12.
• validation_mode (bool, optional): If True, reserves the last forecast_horizon points for validation. Defaults to False.
• time_series_output_format (Literal, optional): Output format for predictions. One of "pandas_dataframe" or "darts_series". Defaults to "pandas_dataframe".
• device (str, optional): Torch device used for inference, for example "cpu" or "cuda:0". Defaults to "cpu".
• time_format (str | None, optional): Explicit datetime format for parsing and formatting. Defaults to None (auto-inferred).
• time_column_name (str, optional): Name of the time column in the input dataframe. Defaults to "Date".

[!TIP] Use CLI command sinapsis info --all-template-names to show a list with all the available Template names installed with Sinapsis TimesFM.

[!TIP] Use CLI command sinapsis info --example-template-config TEMPLATE_NAME to produce an example Agent config for the Template specified in TEMPLATE_NAME.

For example, for TimesFM use sinapsis info --example-template-config TimesFM to produce the following example config:

agent:
  name: my_test_agent
templates:
- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}
- template_name: TimesFM
  class_name: TimesFM
  template_input: InputTemplate
  attributes:
    model_name: google/timesfm-2.5-200m-pytorch
    forecasting_config:
      max_context: 0
      max_horizon: 0
      normalize_inputs: false
      window_size: 0
      per_core_batch_size: 1
      use_continuous_quantile_head: false
      force_flip_invariance: true
      infer_is_positive: true
      fix_quantile_crossing: false
      return_backcast: false
    forecast_horizon: 12
    validation_mode: false
    time_series_output_format: pandas_dataframe
    device: cpu
    time_format: null
    time_column_name: Date

📚 Usage Example

Below is an example configuration for Sinapsis TimesFM that loads a CSV file into a time series packet and runs zero-shot forecasting with a 30-step horizon on GPU.

Example config

agent:
  name: TimesFMForecastingAgent
  description: 'Agent for zero-shot time series forecasting using TimesFM'

templates:
  - template_name: InputTemplate
    class_name: InputTemplate
    attributes: {}

  - template_name: TimeSeriesFromCSVLoader
    class_name: TimeSeriesFromCSVLoader
    template_input: InputTemplate
    attributes:
      root_dir: ./artifacts
      assign_to: "content"
      loader_params:
        path_to_csv: "bitcoin.csv"
        time_col: "Date"
        value_cols: ["open", "high", "low", "close", "Volume BTC", "Volume USD"]
        freq: "D"

  - template_name: TimesFM
    class_name: TimesFM
    template_input: TimeSeriesFromCSVLoader
    attributes:
      model_name: google/timesfm-2.5-200m-pytorch
      forecast_horizon: 30
      validation_mode: false
      time_series_output_format: pandas_dataframe
      device: cuda:0
      time_column_name: Date

This configuration defines an agent and a sequence of templates to load data and generate forecasts.

To run the config, use the CLI:

sinapsis run name_of_config.yml

📙 Documentation

Documentation for this and other sinapsis packages is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.