Loads one or more columns from a CSV file directly into a TimeSeriesPacket using TimeSeries.from_csv(). Supports assigning the result to any packet attribute (content, past_covariates, future_covariates, predictions) and can either create a new packet or update an existing one in the container.

The following attributes apply to TimeSeriesFromCSVLoader:

• root_dir (str | None, optional): Base directory prepended to path_to_csv. If omitted, path_to_csv is used as-is.
• assign_to (Literal, required): The TimeSeriesPacket attribute where the loaded series is stored. One of "content", "past_covariates", "future_covariates", "predictions".
• reuse_packet (bool, optional): If True, assigns the loaded series to the first existing TimeSeriesPacket in the container instead of creating a new one. Useful when loading multiple columns (e.g., target + covariates) into the same packet. Defaults to False.
• loader_params (FromCSVKwargs, required): CSV-specific loading parameters:
  • path_to_csv (str): Filename or relative path to the CSV file.
  • time_col (str | None): Column name to use as the time index.
  • value_cols (str | list[str] | None): Column(s) to use as series values.
  • freq (str | None): Time series frequency (e.g., "D" for daily, "H" for hourly).
  • fill_missing_dates (bool): If True, inserts rows for missing timestamps. Defaults to False.
  • fillna_value (float | None): Fill value for any resulting NaNs after date insertion.

Converts Pandas DataFrame objects already present in a TimeSeriesPacket into Darts TimeSeries instances using TimeSeries.from_dataframe(). Useful when upstream templates deliver DataFrames that need to be converted before forecasting.

The following attributes apply to TimeSeriesFromDataframeLoader:

• apply_to (list[Literal], required): List of TimeSeriesPacket attributes to convert. Valid values: "content", "past_covariates", "future_covariates", "predictions".
• from_pandas_kwargs (FromDataFrameKwargs, optional): Keyword arguments forwarded to TimeSeries.from_dataframe():
  • time_col (str | None): Column to use as the time index.
  • value_cols (str | list[str] | None): Column(s) to use as the series values.
  • freq (str | None): Time series frequency (e.g., "D", "H").
  • fill_missing_dates (bool): Insert rows for missing timestamps. Defaults to False.
  • fillna_value (float | None): Value used to fill NaNs introduced by date filling.
  • make_copy (bool): Whether to copy the underlying NumPy array. Defaults to True.

Converts Pandas Series objects already present in a TimeSeriesPacket into Darts TimeSeries instances using TimeSeries.from_series(). The series index is automatically converted to timestamps via to_timestamp() before conversion.

The following attributes apply to TimeSeriesFromSeriesLoader:

• apply_to (list[Literal], required): List of TimeSeriesPacket attributes to convert. Valid values: "content", "past_covariates", "future_covariates", "predictions".
• from_pandas_kwargs (FromPandasBaseKwargs, optional): Keyword arguments forwarded to TimeSeries.from_series():
  • freq (str | None): Time series frequency (e.g., "D", "H").
  • fill_missing_dates (bool): Insert rows for missing timestamps. Defaults to False.
  • fillna_value (float | None): Value used to fill NaNs introduced by date filling.
  • make_copy (bool): Whether to copy the underlying NumPy array. Defaults to True.

Dynamic wrapper that exposes every transformer from darts.dataprocessing.transformers as an individual Sinapsis template (e.g., ScalerWrapper, MissingValuesFillerWrapper, BoxCoxWrapper). Transformations are applied to the selected TimeSeriesPacket attributes in-place.

For stateful transformers (e.g., Scaler), fitted parameters can be persisted in TimeSeriesPacket.generic_data and recovered automatically for inverse transforms — enabling clean scaler/unscaler pairs in a pipeline without manual state management.

The following attributes apply to all Darts Transformer templates:

• apply_to (list[Literal], required): TimeSeriesPacket attributes to transform. Valid values: "content", "past_covariates", "future_covariates", "predictions".
• method (Literal, required): Transformation method to call. One of "fit", "transform", "fit_transform", "inverse_transform".
• transform_kwargs (dict[str, Any], optional): Extra keyword arguments forwarded to the chosen method (e.g., {"method": "linear"} for MissingValuesFiller). Defaults to {}.
• params_key (str | None, optional): Key under which fitted parameters are stored in TimeSeriesPacket.generic_data. Required when pairing a fit_transform step with a later inverse_transform. Defaults to None (no storage).

Additional transformer-specific init arguments can be set via the *_init key (e.g., missingvaluesfiller_init, scaler_init). These are forwarded directly to the transformer constructor.

The following attribute apply only to templates from Darts Models:

• forecast_horizon (int, optional): Number of future time steps the model should predict. Defaults to 10.
• validation_mode (bool, optional): If True, the model is trained on all but the last forecast_horizon steps of the target series and predictions are generated for that held-out window, enabling metric evaluation. Defaults to False.

Additional model-specific attributes can be dynamically assigned through the class initialization dictionary (*_init attributes). These correspond directly to the constructor arguments of the chosen Darts model and are typically used for hyperparameter configuration.

Generates per-packet visualizations of the historical target series alongside the model's predictions. For each TimeSeriesPacket that contains predictions, the template produces:

• One Matplotlib PNG image per time series column, stored as ImagePacket objects in container.images.
• One interactive Plotly HTML file per time series column, stored as FilePacket objects in container.files.

HTML files are named <html_figure_save_path>_<packet_id>_<column>.html so that multiple packets and multivariate series never overwrite each other.

The following attributes apply to TimeSeriesVisualization:

• html_figure_save_path (str, optional): Base filename for the output HTML files. Defaults to "forecast_plot.html".
• root_dir (str, optional): Root directory where HTML files are saved. Defaults to SINAPSIS_CACHE_DIR. Parent directories are created automatically if they do not exist.
• plot_params (TimeSeriesPlotParams, optional): Nested model to customise the appearance of both Matplotlib and Plotly figures. Available sub-fields:
  • target_series_label (str): Legend label for the historical series. Defaults to "Historical".
  • predictions_label (str): Legend label for the predicted series. Defaults to "Predictions".
  • title (str): Figure title. Defaults to "Time Series Forecast Results".
  • x_axis_title (str): X-axis label. Defaults to "Time".
  • low_quantile (float): Lower quantile bound for probabilistic prediction intervals (Matplotlib only). Defaults to 0.05.
  • high_quantile (float): Upper quantile bound for probabilistic prediction intervals (Matplotlib only). Defaults to 0.95.

Dynamic wrapper that exposes every metric from darts.metrics as an individual Sinapsis template (e.g., maeTimeSeriesWrapper, mseTimeSeriesWrapper, rmseTimeSeriesWrapper). The selected metric is applied to the predictions and ground truth of each TimeSeriesPacket, and the result is stored in TimeSeriesPacket.generic_data keyed by the metric function name.

The following attributes apply to all metric templates. They are specified as a nested dictionary under the metric function name (e.g., mae: {}):

• intersect (bool, optional): When True, only the overlapping time interval between ground truth and predictions is used. Defaults to True.
• q (float | list[float] | None, optional): Quantile(s) to evaluate for probabilistic or quantile predictions. Defaults to None (median for stochastic predictions).
• n_jobs (int, optional): Number of parallel jobs when evaluating over a sequence of series. Defaults to 1.
• verbose (bool, optional): Whether to print progress. Defaults to False.

The following parameters are intentionally excluded and cannot be overridden via the template config (they are managed internally): actual_series, pred_series, component_reduction, series_reduction, time_reduction.

agent:
  name: XGBLSTMForecastingAgent
  description: ''

templates:

- template_name: InputTemplate
  class_name: InputTemplate
  attributes: {}

- template_name: TimeSeriesFromDataframeLoader
  class_name: TimeSeriesFromDataframeLoader
  template_input: InputTemplate
  attributes:
    apply_to: ["content", "past_covariates", "future_covariates"]
    from_pandas_kwargs:
      time_col: "Date"
      fill_missing_dates: True
      freq: "D"

- template_name: MissingValuesFiller
  class_name: MissingValuesFillerWrapper
  template_input: TimeSeriesFromDataframeLoader
  attributes:
    method: "transform"
    missingvaluesfiller_init: {}
    apply_to: ["content", "past_covariates", "future_covariates"]
    transform_kwargs:
      method: "linear"

- template_name: TimeSeries
  class_name: XGBModelWrapper
  template_input: MissingValuesFiller
  attributes:
    forecast_horizon: 100
    xgbmodel_init:
      lags: 30
      lags_past_covariates: 30
      output_chunk_length: 100
      random_state: 42
      n_estimators: 200
      learning_rate: 0.1
      max_depth: 6

IMPORTANT This docker image depends on the sinapsis-nvidia:base image. Please refer to the official sinapsis instructions to Build with Docker.

1. Build the sinapsis-time-series-forecasting image:

docker compose -f docker/compose.yaml build

2. Start the app container:

docker compose -f docker/compose_apps.yaml up sinapsis-darts-forecasting-gradio -d

3. Check the status:

docker logs -f sinapsis-darts-forecasting-gradio

4. The logs will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of logs

Running on local URL:  http://127.0.0.1:7860

4. To stop the app:

docker compose -f docker/compose_apps.yaml down

To run the webapp using the uv package manager, please:

1. Create the virtual environment and sync the dependencies:

uv sync --frozen

2. Install the wheel:

uv pip install sinapsis-time-series[all] --extra-index-url https://pypi.sinapsis.tech

3. Run the webapp:

uv run webapps/darts_time_series_gradio_app.py

4. The terminal will display the URL to access the webapp, e.g.:

NOTE: The url can be different, check the output of the terminal

Running on local URL:  http://127.0.0.1:7860