`ForecasterFoundation`¶

skforecast.foundation._forecaster_foundation.ForecasterFoundation ¶


ForecasterFoundation(estimator, forecaster_id=None)

Forecaster that wraps a FoundationModel for full skforecast ecosystem compatibility: backtesting, model selection, etc.

Unlike ML-based forecasters, there is no training step — the underlying foundation models are zero-shot. fit only stores the context (recent observations) and records index metadata. Predictions are generated directly by the model's predict_quantiles pipeline.

Supports both single-series and multi-series modes. Pass a pandas.Series to fit for single-series forecasting or a wide pandas.DataFrame, a long-format pandas.DataFrame (MultiIndex), or a dict[str, pd.Series] for multi-series (global-model) forecasting.

Parameters:

Name	Type	Description	Default
`estimator`	`FoundationModel`	A configured `FoundationModel` instance, e.g. `FoundationModel("autogluon/chronos-2-small", context_length=512)`. See `FoundationModel` for the list of supported `model_id` values and adapter-specific parameters.	required
`forecaster_id`	`(str, int)`	Name used as an identifier of the forecaster.	`None`

Attributes:

Name	Type	Description
`estimator`	`FoundationModel`	The `FoundationModel` instance provided by the user.
`model_id`	`str`	HuggingFace model ID. Delegates to `estimator.model_id`.
`context_`	`dict`	Per-series dict of pandas Series containing the last `context_length` observations from the training data. Delegates to `estimator.context_`. `None` before fitting.
`context_exog_`	`dict`	Per-series dict of pandas DataFrame containing the last `context_length` exogenous variables from the training data. Delegates to `estimator.context_exog_`. `None` before fitting or if no exogenous variables were provided.
`last_window_`	`dict`	Alias for `context_`.
`last_window_exog_`	`dict`	Alias for `context_exog_`.
`context_length`	`int`	Maximum number of historical observations used as context. Delegates to `estimator.context_length`.
`window_size`	`int`	Desired number of historical observations used as context by the model. Always equals `context_length`.
`index_type_`	`type`	Type of index of the input used in training. Delegates to `estimator.index_type_`.
`index_freq_`	`pandas DateOffset, int`	Frequency of the index of the input used in training. A `pandas.DateOffset` for `DatetimeIndex`; the `step` integer for `RangeIndex`. Delegates to `estimator.index_freq_`.
`context_range_`	`dict`	First and last values of index of the data used during training. A `dict` keyed by series name with `pandas.Index` values. Delegates to `estimator.context_range_`.
`series_names_in_`	`list`	Names of the series (levels) provided by the user during training. Delegates to `estimator.series_names_in_`.
`is_multiple_series_`	`bool`	Whether the forecaster was fitted with multiple series. Delegates to `estimator.is_multiple_series_`.
`exog_in_`	`bool`	If the forecaster has been trained using exogenous variable/s. Delegates to `estimator.exog_in_`.
`exog_names_in_`	`list`	Names of the exogenous variables used during training. Delegates to `estimator.exog_names_in_`.
`exog_names_in_per_series_`	`dict`	Names of the exogenous variables used during training for each series. Delegates to `estimator.exog_names_in_per_series_`.
`exog_type_in_`	`type`	Type of exogenous variable/s used in training. Delegates to `estimator.exog_type_in_`.
`creation_date`	`str`	Date of creation.
`is_fitted`	`bool`	Tag to identify if the forecaster has been fitted (trained).
`fit_date`	`str`	Date of last fit. Delegates to `estimator.fit_date`.
`skforecast_version`	`str`	Version of skforecast library used to create the forecaster.
`python_version`	`str`	Version of python used to create the forecaster.
`forecaster_id`	`(str, int)`	Name used as an identifier of the forecaster.
`__skforecast_tags__`	`dict`	Tags associated with the forecaster.

Methods:

Name	Description
`fit`	Training Forecaster.
`predict`	Predict n steps ahead.
`predict_interval`	Predict n steps ahead with prediction intervals.
`predict_quantiles`	Predict n steps ahead at specified quantile levels.
`set_params`	Set new values to the parameters of the underlying estimator.
`summary`	Show forecaster information.

Source code in skforecast/foundation/_forecaster_foundation.py

def __init__(
    self,
    estimator: FoundationModel,
    forecaster_id: str | int | None = None,
) -> None:

    if not isinstance(estimator, FoundationModel):
        raise TypeError(
            f"`estimator` must be a `FoundationModel` instance. "
            f"Got {type(estimator)}."
        )

    self.estimator          = estimator
    self.creation_date      = pd.Timestamp.today().strftime('%Y-%m-%d %H:%M:%S')
    self.is_fitted          = False
    self.skforecast_version = __version__
    self.python_version     = sys.version.split(" ")[0]
    self.forecaster_id      = forecaster_id

    self.__skforecast_tags__ = {
        "library": "skforecast",
        "forecaster_name": "ForecasterFoundation",
        "forecaster_task": "regression",
        "forecasting_scope": "single-series|multi-series",
        "forecasting_strategy": "foundation",
        "index_types_supported": ["pandas.RangeIndex", "pandas.DatetimeIndex"],
        "requires_index_frequency": True,

        "allowed_input_types_series": [
            "pandas.Series",
            "pandas.DataFrame",
            "long-format pandas.DataFrame",
            "dict[str, pandas.Series]",
        ],
        "supports_exog": True,
        "allowed_input_types_exog": [
            "pandas.Series",
            "pandas.DataFrame",
            "long-format pandas.DataFrame",
            "dict[str, pandas.Series | pandas.DataFrame | None]",
        ],
        "handles_missing_values_series": False,
        "handles_missing_values_exog": False,

        "supports_lags": False,
        "supports_window_features": False,
        "supports_transformer_series": False,
        "supports_transformer_exog": False,
        "supports_categorical_features": True,
        "supports_weight_func": False,
        "supports_differentiation": False,

        "prediction_types": ["point", "interval", "quantiles"],
        "supports_probabilistic": True,
        "probabilistic_methods": ["quantile_native"],
        "handles_binned_residuals": False,
    }

Attributes¶

estimator `instance-attribute` ¶


estimator = estimator

creation_date `instance-attribute` ¶


creation_date = strftime('%Y-%m-%d %H:%M:%S')

is_fitted `instance-attribute` ¶


is_fitted = False

skforecast_version `instance-attribute` ¶


skforecast_version = __version__

python_version `instance-attribute` ¶


python_version = split(' ')[0]

forecaster_id `instance-attribute` ¶


forecaster_id = forecaster_id

context_length `property` ¶


context_length

Maximum number of historical observations used as context.

Returns:

Name	Type	Description
`context_length`	`int`	Maximum context length. Delegates to `estimator.context_length`.

model_id `property` ¶


model_id

HuggingFace model ID.

Returns:

Name	Type	Description
`model_id`	`str`	HuggingFace model ID. Delegates to `estimator.model_id`.

window_size `property` ¶


window_size

Desired number of historical observations used as context by the model. Always equals context_length.

Returns:

Name	Type	Description
`window_size`	`int`	Context window size. Delegates to `estimator.context_length`.

context_ `property` ¶


context_

Per-series context stored during fit.

Returns:

Name	Type	Description
`context_`	`(dict, None)`	Per-series dict of pandas Series containing the last `context_length` observations from the training data. Delegates to `estimator.context_`. `None` before fitting.

last_window_ `property` ¶


last_window_

Alias for context_.

Returns:

Name	Type	Description
`last_window_`	`(dict, None)`	Per-series dict of pandas Series. Alias for `context_`.

context_exog_ `property` ¶


context_exog_

Per-series exogenous context stored during fit.

Returns:

Name	Type	Description
`context_exog_`	`(dict, None)`	Per-series dict of pandas DataFrame containing the last `context_length` exogenous variables from the training data. Delegates to `estimator.context_exog_`. `None` before fitting or if no exogenous variables were provided.

last_window_exog_ `property` ¶


last_window_exog_

Alias for context_exog_.

Returns:

Name	Type	Description
`last_window_exog_`	`(dict, None)`	Per-series dict of pandas DataFrame. Alias for `context_exog_`.

index_type_ `property` ¶


index_type_

Type of index of the input used in training.

Returns:

Name	Type	Description
`index_type_`	`(type, None)`	Index type. Delegates to `estimator.index_type_`.

index_freq_ `property` ¶


index_freq_

Frequency of the index of the input used in training.

Returns:

Name	Type	Description
`index_freq_`	`pandas DateOffset, int, None`	Index frequency. Delegates to `estimator.index_freq_`.

context_range_ `property` ¶


context_range_

First and last values of index of the data used during training.

Returns:

Name	Type	Description
`context_range_`	`(dict, None)`	Per-series index range. Delegates to `estimator.context_range_`.

series_names_in_ `property` ¶


series_names_in_

Names of the series (levels) provided by the user during training.

Returns:

Name	Type	Description
`series_names_in_`	`(list, None)`	Series names. Delegates to `estimator.series_names_in_`.

is_multiple_series_ `property` ¶


is_multiple_series_

Whether the forecaster was fitted with multiple series.

Returns:

Name	Type	Description
`is_multiple_series_`	`bool`	Delegates to `estimator.is_multiple_series_`.

exog_in_ `property` ¶


exog_in_

If the forecaster has been trained using exogenous variable/s.

Returns:

Name	Type	Description
`exog_in_`	`bool`	Delegates to `estimator.exog_in_`.

exog_names_in_ `property` ¶


exog_names_in_

Names of the exogenous variables used during training.

Returns:

Name	Type	Description
`exog_names_in_`	`(list, None)`	Delegates to `estimator.exog_names_in_`.

exog_names_in_per_series_ `property` ¶


exog_names_in_per_series_

Names of the exogenous variables used during training for each series.

Returns:

Name	Type	Description
`exog_names_in_per_series_`	`(dict, None)`	Delegates to `estimator.exog_names_in_per_series_`.

exog_type_in_ `property` ¶


exog_type_in_

Type of exogenous variable/s used in training.

Returns:

Name	Type	Description
`exog_type_in_`	`(type, None)`	Delegates to `estimator.exog_type_in_`.

fit_date `property` ¶


fit_date

Date of last fit.

Returns:

Name	Type	Description
`fit_date`	`(str, None)`	Delegates to `estimator.fit_date`.

Functions¶

_truncate_names `staticmethod` ¶


_truncate_names(names, max_items=50)

Truncate a list of names for display.

Returns the first and last max_items // 2 elements (joined by '...') when the list exceeds max_items. Returns a shallow copy so callers can mutate the result freely.

Parameters:

Name	Type	Description	Default
`names`	`(list, None)`	Names to truncate. If `None`, returns `None`.	required
`max_items`	`int`	Maximum number of names to keep before truncation.	`50`

Returns:

Name	Type	Description
`truncated`	`(list, None)`	Truncated list, or `None` if `names` is `None`.

Source code in skforecast/foundation/_forecaster_foundation.py

@staticmethod
def _truncate_names(
    names: list[str] | None,
    max_items: int = 50,
) -> list[str] | None:
    """
    Truncate a list of names for display.

    Returns the first and last `max_items // 2` elements (joined by
    `'...'`) when the list exceeds `max_items`. Returns a shallow
    copy so callers can mutate the result freely.

    Parameters
    ----------
    names : list, None
        Names to truncate. If `None`, returns `None`.
    max_items : int, default 50
        Maximum number of names to keep before truncation.

    Returns
    -------
    truncated : list, None
        Truncated list, or `None` if `names` is `None`.

    """

    if names is None:
        return None

    names = list(names)
    if len(names) > max_items:
        half = max_items // 2
        names = names[:half] + ["..."] + names[-half:]

    return names

_format_names_repr `staticmethod` ¶


_format_names_repr(names, max_items=50, max_text_length=58)

Format a list of names for text __repr__.

Truncates the list to the first and last max_items // 2 elements (joined by '...') when it exceeds max_items, then wraps the resulting string with textwrap.fill when it exceeds max_text_length characters.

Parameters:

Name	Type	Description	Default
`names`	`(list, None)`	Names to format. If `None`, returns `None`.	required
`max_items`	`int`	Maximum number of names to display before truncation.	`50`
`max_text_length`	`int`	Maximum length of the joined string before text wrapping.	`58`

Returns:

Name	Type	Description
`formatted`	`(str, None)`	Formatted string, or `None` if `names` is `None`.

Source code in skforecast/foundation/_forecaster_foundation.py

@staticmethod
def _format_names_repr(
    names: list[str] | None,
    max_items: int = 50,
    max_text_length: int = 58,
) -> str | None:
    """
    Format a list of names for text `__repr__`.

    Truncates the list to the first and last `max_items // 2` elements
    (joined by `'...'`) when it exceeds `max_items`, then wraps the
    resulting string with `textwrap.fill` when it exceeds
    `max_text_length` characters.

    Parameters
    ----------
    names : list, None
        Names to format. If `None`, returns `None`.
    max_items : int, default 50
        Maximum number of names to display before truncation.
    max_text_length : int, default 58
        Maximum length of the joined string before text wrapping.

    Returns
    -------
    formatted : str, None
        Formatted string, or `None` if `names` is `None`.

    """

    names = ForecasterFoundation._truncate_names(names, max_items)
    if names is None:
        return None

    formatted = ", ".join(names)
    if len(formatted) > max_text_length:
        formatted = "\n    " + textwrap.fill(
            formatted, width=80, subsequent_indent="    "
        )

    return formatted

_repr_html_ ¶


_repr_html_()

HTML representation of the object. The "General Information" section is expanded by default.

Source code in skforecast/foundation/_forecaster_foundation.py

def _repr_html_(self) -> str:
    """
    HTML representation of the object.
    The "General Information" section is expanded by default.
    """

    style, unique_id = get_style_repr_html(self.is_fitted)

    exog_names = self._truncate_names(self.exog_names_in_)
    if exog_names is not None:
        parts = []
        for n in exog_names:
            if n == "...":
                parts.append('<em style="color: #999;">\u2026</em>')
            else:
                parts.append(html.escape(str(n)))
        exog_names_html = ", ".join(parts)
    else:
        exog_names_html = str(None)

    series_names = self._truncate_names(self.series_names_in_)
    if series_names is not None:
        series_value_html = ", ".join(html.escape(str(n)) for n in series_names)
    else:
        series_value_html = str(self.series_names_in_)

    if self.is_fitted:
        context_range_parts = [
            f"'{k}': {v.astype(str).to_list()}"
            for k, v in self.context_range_.items()
        ]
        if len(context_range_parts) > 10:
            context_range_parts = (
                context_range_parts[:5] + ["..."] + context_range_parts[-5:]
            )
        context_range_html = ", ".join(context_range_parts)
    else:
        context_range_html = "Not fitted"

    params_html = "".join(
        f"<li><strong>{html.escape(str(k))}:</strong> {html.escape(str(v))}</li>"
        for k, v in self.estimator.adapter.get_params().items()
        if k != "model_id"
    )

    content = f"""
    <div class="container-{unique_id}">
        <p style="font-size: 1.5em; font-weight: bold; margin-block-start: 0.83em; margin-block-end: 0.83em;">{type(self).__name__}</p>
        <details open>
            <summary>General Information</summary>
            <ul>
                <li><strong>Model ID:</strong> {self.model_id}</li>
                <li><strong>Context length:</strong> {self.context_length}</li>
                <li><strong>Window size:</strong> {self.window_size}</li>
                <li><strong>Series names:</strong> {series_value_html}</li>
                <li><strong>Exogenous included:</strong> {self.exog_in_}</li>
                <li><strong>Creation date:</strong> {self.creation_date}</li>
                <li><strong>Last fit date:</strong> {self.fit_date}</li>
                <li><strong>Skforecast version:</strong> {self.skforecast_version}</li>
                <li><strong>Python version:</strong> {self.python_version}</li>
                <li><strong>Forecaster id:</strong> {self.forecaster_id}</li>
            </ul>
        </details>
        <details>
            <summary>Exogenous Variables</summary>
            <p style="margin: 0.2em 0 0.2em 1.5em;">{exog_names_html}</p>
        </details>
        <details>
            <summary>Training Information</summary>
            <ul>
                <li><strong>Context range:</strong> {context_range_html}</li>
                <li><strong>Training index type:</strong> {str(self.index_type_).split('.')[-1][:-2] if self.is_fitted else 'Not fitted'}</li>
                <li><strong>Training index frequency:</strong> {self.index_freq_ if self.is_fitted else 'Not fitted'}</li>
            </ul>
        </details>
        <details>
            <summary>Model Parameters</summary>
            <ul>
                {params_html}
            </ul>
        </details>
        <p>
            <a href="https://skforecast.org/{__version__}/api/forecasterfoundation.html">&#128214; <strong>API Reference</strong></a>
            &nbsp;&nbsp;
            <a href="https://skforecast.org/{__version__}/user_guides/foundation-forecasting-models.html">&#128221; <strong>User Guide</strong></a>
        </p>
    </div>
    """

    return style + content

fit ¶


fit(series, exog=None)

Training Forecaster.

Stores index metadata and delegates context storage to the underlying adapter. No model training occurs since foundation model is zero-shot.

Parameters:

Name	Type	Description	Default
`series`	`pandas Series, pandas DataFrame, dict`	Training time series. If `pandas.Series`: single-series mode. If wide `pandas.DataFrame` (one column per series): multi-series mode. If long-format `pandas.DataFrame` with a MultiIndex (first level = series IDs, second level = `DatetimeIndex`): multi-series mode. Internally converted to a dict. An `InputTypeWarning` is issued; consider passing a dict directly for better performance. If `dict[str, pd.Series]`: multi-series mode.	required
`exog`	`pandas Series, pandas DataFrame, dict`	Historical exogenous variables aligned to `series`. At prediction time they are forwarded to the underlying adapter as past (historical) covariates, using the adapter-specific covariate format. In single-series mode: `pd.Series` or `pd.DataFrame` aligned to `series`. In multi-series mode: a `dict[str, pd.Series \| pd.DataFrame \| None]` with one entry per series, a single `pd.Series` / `pd.DataFrame` broadcast to all series, or a long-format `pd.DataFrame` with a MultiIndex (first level = series IDs, second level = `DatetimeIndex`). Long-format inputs are converted to a `dict` internally; an `InputTypeWarning` is issued.	`None`

Returns:

Type	Description
`None`

Source code in skforecast/foundation/_forecaster_foundation.py

def fit(
    self,
    series: pd.Series | pd.DataFrame | dict[str, pd.Series],
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
) -> None:
    """
    Training Forecaster.

    Stores index metadata and delegates context storage to the underlying
    adapter. No model training occurs since foundation model is zero-shot.

    Parameters
    ----------
    series : pandas Series, pandas DataFrame, dict
        Training time series.

        - If `pandas.Series`: single-series mode.
        - If wide `pandas.DataFrame` (one column per series): multi-series
          mode.
        - If long-format `pandas.DataFrame` with a MultiIndex (first level =
          series IDs, second level = `DatetimeIndex`): multi-series
          mode. Internally converted to a dict. An `InputTypeWarning` is
          issued; consider passing a dict directly for better performance.
        - If `dict[str, pd.Series]`: multi-series mode.
    exog : pandas Series, pandas DataFrame, dict, default None
        Historical exogenous variables aligned to `series`. At prediction
        time they are forwarded to the underlying adapter as past
        (historical) covariates, using the adapter-specific covariate
        format.

        In single-series mode: `pd.Series` or `pd.DataFrame` aligned to
        `series`.

        In multi-series mode: a `dict[str, pd.Series | pd.DataFrame | None]`
        with one entry per series, a single `pd.Series` / `pd.DataFrame`
        broadcast to all series, or a long-format `pd.DataFrame` with a
        MultiIndex (first level = series IDs, second level =
        `DatetimeIndex`). Long-format inputs are converted to a `dict`
        internally; an `InputTypeWarning` is issued.

    Returns
    -------
    None

    """

    self.is_fitted = False

    if exog is not None and not self.estimator.allow_exog:
        warnings.warn(
            f"The model '{self.estimator.model_id}' does not support "
            f"exogenous variables. `exog` will be ignored.",
            IgnoredArgumentWarning,
            stacklevel=2,
        )
        exog = None

    self.estimator.fit(series=series, exog=exog)
    self.is_fitted = True

predict ¶


predict(
    steps,
    levels=None,
    context=None,
    context_exog=None,
    exog=None,
    check_inputs=True,
)

Predict n steps ahead.

Parameters:

Name	Type	Description	Default
`steps`	`int`	Number of steps ahead to forecast.	required
`levels`	`(str, list)`	Subset of series to predict. If `None`, all series in `context` are predicted.	`None`
`context`	`pandas Series, pandas DataFrame, dict`	Context override for backtesting. When provided, replaces the context stored at fit time. In single-series mode pass a `pd.Series`; in multi-series mode pass a wide `pd.DataFrame` or a `dict[str, pd.Series]`. If longer than `context_length`, only the last `context_length` observations are used. If shorter, all available observations are passed as-is and the model handles the reduced context gracefully.	`None`
`context_exog`	`pandas Series, pandas DataFrame, dict`	Historical exogenous variables aligned to `context` (past covariates, mapped to the adapter-specific covariate format).	`None`
`exog`	`pandas Series, pandas DataFrame, dict`	Future-known exogenous variables for the forecast horizon (future covariates, mapped to the adapter-specific covariate format). Must cover exactly `steps` steps for each series.	`None`
`check_inputs`	`bool`	If `True`, the `context` and `context_exog` inputs are validated and normalized. If `False`, `context` must already be a `dict[str, pandas Series]` and `context_exog` must be a `dict[str, pandas DataFrame \| None]` or `None`. This argument is created for internal use and is not recommended to be changed.	`True`

Returns:

Name	Type	Description
`predictions`	`pandas DataFrame`	Long-format DataFrame with columns `['level', 'pred']`. The index repeats each forecast timestamp once per series.

Notes

Foundation models are pre-trained and do not learn from the data passed to fit. The fit method only stores context (the last context_length observations) and metadata. This leads to four distinct behaviors depending on the combination of is_fitted and context:

Not fitted, context=None: raises NotFittedError. There is no context available for prediction.
Fitted, context=None: uses the context and context_exog_ stored during fit. If the user supplies context_exog, it is ignored with a warning.
Not fitted, context provided (zero-shot mode): The model uses context and context_exog (if provided) as context for prediction.
Fitted, context provided: Stored context is ignored, the provided context and context_exog (if provided) are used for prediction.

Source code in skforecast/foundation/_forecaster_foundation.py

def predict(
    self,
    steps: int,
    levels: str | list[str] | None = None,
    context: pd.Series | pd.DataFrame | dict[str, pd.Series] | None = None,
    context_exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.DataFrame | pd.Series | None]
        | None
    ) = None,
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
    check_inputs: bool = True,
) -> pd.DataFrame:
    """
    Predict n steps ahead.

    Parameters
    ----------
    steps : int
        Number of steps ahead to forecast.
    levels : str, list, default None
        Subset of series to predict. If `None`, all series in `context` are 
        predicted. 
    context : pandas Series, pandas DataFrame, dict, default None
        Context override for backtesting. When provided, replaces the
        context stored at fit time. In single-series mode pass a
        `pd.Series`; in multi-series mode pass a wide `pd.DataFrame` or a
        `dict[str, pd.Series]`. If longer than `context_length`, only the
        last `context_length` observations are used. If shorter, all
        available observations are passed as-is and the model handles the
        reduced context gracefully.
    context_exog : pandas Series, pandas DataFrame, dict, default None
        Historical exogenous variables aligned to `context` (past
        covariates, mapped to the adapter-specific covariate format).
    exog : pandas Series, pandas DataFrame, dict, default None
        Future-known exogenous variables for the forecast horizon (future
        covariates, mapped to the adapter-specific covariate format).
        Must cover exactly `steps` steps for each series.
    check_inputs : bool, default True
        If `True`, the `context` and `context_exog` inputs are validated
        and normalized. If `False`, `context` must already be a
        `dict[str, pandas Series]` and `context_exog` must be a
        `dict[str, pandas DataFrame | None]` or `None`. This argument
        is created for internal use and is not recommended to be changed.

    Returns
    -------
    predictions : pandas DataFrame
        Long-format DataFrame with columns `['level', 'pred']`.
        The index repeats each forecast timestamp once per series.

    Notes
    -----
    Foundation models are pre-trained and do not learn from the data passed
    to `fit`. The `fit` method only stores context (the last `context_length`
    observations) and metadata. This leads to four distinct behaviors
    depending on the combination of `is_fitted` and `context`:

    - **Not fitted, `context=None`**: raises `NotFittedError`. There is no
    context available for prediction.
    - **Fitted, `context=None`**: uses the context and `context_exog_` stored
    during `fit`. If the user supplies `context_exog`, it is ignored with a
    warning.
    - **Not fitted, `context` provided (zero-shot mode)**: The model uses
    `context` and `context_exog` (if provided) as context for prediction.
    - **Fitted, `context` provided**: Stored context is ignored, the
    provided `context` and `context_exog` (if provided) are used for
    prediction.

    """

    if not self.is_fitted and context is None:
        raise NotFittedError(
            "This forecaster is not fitted yet. Call `fit` with appropriate "
            "arguments before using `predict()`, or pass `context`."
        )

    predictions = self.estimator.predict(
                      steps        = steps,
                      context      = context,
                      context_exog = context_exog,
                      exog         = exog,
                      quantiles    = None,
                      levels       = levels,
                      check_inputs = check_inputs,
                  )

    return predictions

predict_interval ¶


predict_interval(
    steps,
    levels=None,
    context=None,
    context_exog=None,
    exog=None,
    interval=[10, 90],
    check_inputs=True,
)

Predict n steps ahead with prediction intervals.

Prediction intervals are derived directly from the underlying foundation model's native quantile output — no bootstrapping or residual estimation is used.

Parameters:

Name	Type	Description	Default
`steps`	`int`	Number of steps ahead to forecast.	required
`levels`	`(str, list)`	Subset of series to predict. If `None`, all series in `context` are predicted.	`None`
`context`	`pandas Series, pandas DataFrame, dict`	Context override for backtesting.	`None`
`context_exog`	`pandas Series, pandas DataFrame, dict`	Historical exog aligned to `context` (past covariates).	`None`
`exog`	`pandas Series, pandas DataFrame, dict`	Future-known exogenous variables for the forecast horizon (future covariates).	`None`
`interval`	`(list, tuple)`	Confidence of the prediction interval. Sequence of two percentiles `[lower, upper]`, e.g. `[10, 90]` for an 80 % interval. Values must be between 0 and 100 inclusive.	`[10, 90]`
`check_inputs`	`bool`	If `True`, the `context` and `context_exog` inputs are validated and normalized. If `False`, `context` must already be a `dict[str, pandas Series]` and `context_exog` must be a `dict[str, pandas DataFrame \| None]` or `None`. This argument is created for internal use and is not recommended to be changed.	`True`

Returns:

Name	Type	Description
`predictions`	`pandas DataFrame`	Long-format DataFrame with columns `['level', 'pred', 'lower_bound', 'upper_bound']`.

Notes

Foundation models are pre-trained and do not learn from the data passed to fit. The fit method only stores context (the last context_length observations) and metadata. This leads to four distinct behaviors depending on the combination of is_fitted and context:

Not fitted, context=None: raises NotFittedError. There is no context available for prediction.
Fitted, context=None: uses the context and context_exog_ stored during fit. If the user supplies context_exog, it is ignored with a warning.
Not fitted, context provided (zero-shot mode): The model uses context and context_exog (if provided) as context for prediction.
Fitted, context provided: Stored context is ignored, the provided context and context_exog (if provided) are used for prediction.

Source code in skforecast/foundation/_forecaster_foundation.py

def predict_interval(
    self,
    steps: int,
    levels: str | list[str] | None = None,
    context: pd.Series | pd.DataFrame | dict[str, pd.Series] | None = None,
    context_exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.DataFrame | pd.Series | None]
        | None
    ) = None,
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
    interval: list[float] | tuple[float] = [10, 90],
    check_inputs: bool = True,
) -> pd.DataFrame:
    """
    Predict n steps ahead with prediction intervals.

    Prediction intervals are derived directly from the underlying
    foundation model's native quantile output — no bootstrapping or
    residual estimation is used.

    Parameters
    ----------
    steps : int
        Number of steps ahead to forecast.
    levels : str, list, default None
        Subset of series to predict. If `None`, all series in `context` are 
        predicted. 
    context : pandas Series, pandas DataFrame, dict, default None
        Context override for backtesting.
    context_exog : pandas Series, pandas DataFrame, dict, default None
        Historical exog aligned to `context` (past covariates).
    exog : pandas Series, pandas DataFrame, dict, default None
        Future-known exogenous variables for the forecast horizon
        (future covariates).
    interval : list, tuple, default [10, 90]
        Confidence of the prediction interval. Sequence of two percentiles
        `[lower, upper]`, e.g. `[10, 90]` for an 80 % interval.
        Values must be between 0 and 100 inclusive.
    check_inputs : bool, default True
        If `True`, the `context` and `context_exog` inputs are validated
        and normalized. If `False`, `context` must already be a
        `dict[str, pandas Series]` and `context_exog` must be a
        `dict[str, pandas DataFrame | None]` or `None`. This argument
        is created for internal use and is not recommended to be changed.

    Returns
    -------
    predictions : pandas DataFrame
        Long-format DataFrame with columns `['level', 'pred', 'lower_bound',
        'upper_bound']`.

    Notes
    -----
    Foundation models are pre-trained and do not learn from the data passed
    to `fit`. The `fit` method only stores context (the last `context_length`
    observations) and metadata. This leads to four distinct behaviors
    depending on the combination of `is_fitted` and `context`:

    - **Not fitted, `context=None`**: raises `NotFittedError`. There is no
    context available for prediction.
    - **Fitted, `context=None`**: uses the context and `context_exog_` stored
    during `fit`. If the user supplies `context_exog`, it is ignored with a
    warning.
    - **Not fitted, `context` provided (zero-shot mode)**: The model uses
    `context` and `context_exog` (if provided) as context for prediction.
    - **Fitted, `context` provided**: Stored context is ignored, the
    provided `context` and `context_exog` (if provided) are used for
    prediction.

    """

    if not self.is_fitted and context is None:
        raise NotFittedError(
            "This forecaster is not fitted yet. Call `fit` with appropriate "
            "arguments before using `predict_interval()`, or pass `context`."
        )

    if isinstance(interval, (int, float)):
        check_interval(alpha=interval, alpha_literal='interval')
        interval = [(0.5 - interval / 2) * 100, (0.5 + interval / 2) * 100]

    if len(interval) != 2:
        raise ValueError(
            f"`interval` must be a sequence of exactly two values [lower, upper]. "
            f"Got {len(interval)} values."
        )
    lower_pct, upper_pct = float(interval[0]), float(interval[1])
    if not (0 <= lower_pct < upper_pct <= 100):
        raise ValueError(
            f"`interval` values must satisfy 0 <= lower < upper <= 100. "
            f"Got [{lower_pct}, {upper_pct}]."
        )

    lower_q = lower_pct / 100
    upper_q = upper_pct / 100
    # Always include the median (0.5) so 'pred' is the central forecast.
    quantiles = sorted({lower_q, 0.5, upper_q})

    predictions = self.predict_quantiles(
                      steps        = steps,
                      levels       = levels,
                      context      = context,
                      context_exog = context_exog,
                      exog         = exog,
                      quantiles    = quantiles,
                      check_inputs = check_inputs,
                  )

    predictions = predictions[['level', f'q_{0.5}', f'q_{lower_q}', f'q_{upper_q}']]
    predictions.columns = ['level', 'pred', 'lower_bound', 'upper_bound']

    return predictions

predict_quantiles ¶


predict_quantiles(
    steps,
    levels=None,
    context=None,
    context_exog=None,
    exog=None,
    quantiles=[0.1, 0.5, 0.9],
    check_inputs=True,
)

Predict n steps ahead at specified quantile levels.

Parameters:

Name	Type	Description	Default
`steps`	`int`	Number of steps ahead to forecast.	required
`levels`	`(str, list)`	Subset of series to predict. If `None`, all series in `context` are predicted.	`None`
`context`	`pandas Series, pandas DataFrame, dict`	Context override for backtesting.	`None`
`context_exog`	`pandas Series, pandas DataFrame, dict`	Historical exog aligned to `context` (past covariates).	`None`
`exog`	`pandas Series, pandas DataFrame, dict`	Future-known exogenous variables for the forecast horizon (future covariates).	`None`
`quantiles`	`(list, tuple)`	Quantile levels to forecast. Values must be in the range (0, 1).	`[0.1, 0.5, 0.9]`
`check_inputs`	`bool`	If `True`, the `context` and `context_exog` inputs are validated and normalized. If `False`, `context` must already be a `dict[str, pandas Series]` and `context_exog` must be a `dict[str, pandas DataFrame \| None]` or `None`. This argument is created for internal use and is not recommended to be changed.	`True`

Returns:

Name	Type	Description
`predictions`	`pandas DataFrame`	Long-format DataFrame with columns `['level', 'q_0.1', 'q_0.5', ...]`.

Notes

Foundation models are pre-trained and do not learn from the data passed to fit. The fit method only stores context (the last context_length observations) and metadata. This leads to four distinct behaviors depending on the combination of is_fitted and context:

Not fitted, context=None: raises NotFittedError. There is no context available for prediction.
Fitted, context=None: uses the context and context_exog_ stored during fit. If the user supplies context_exog, it is ignored with a warning.
Not fitted, context provided (zero-shot mode): The model uses context and context_exog (if provided) as context for prediction.
Fitted, context provided: Stored context is ignored, the provided context and context_exog (if provided) are used for prediction.

Source code in skforecast/foundation/_forecaster_foundation.py

def predict_quantiles(
    self,
    steps: int,
    levels: str | list[str] | None = None,
    context: pd.Series | pd.DataFrame | dict[str, pd.Series] | None = None,
    context_exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.DataFrame | pd.Series | None]
        | None
    ) = None,
    exog: (
        pd.Series
        | pd.DataFrame
        | dict[str, pd.Series | pd.DataFrame | None]
        | None
    ) = None,
    quantiles: list[float] | tuple[float] = [0.1, 0.5, 0.9],
    check_inputs: bool = True,
) -> pd.DataFrame:
    """
    Predict n steps ahead at specified quantile levels.

    Parameters
    ----------
    steps : int
        Number of steps ahead to forecast.
    levels : str, list, default None
        Subset of series to predict. If `None`, all series in `context` are 
        predicted. 
    context : pandas Series, pandas DataFrame, dict, default None
        Context override for backtesting.
    context_exog : pandas Series, pandas DataFrame, dict, default None
        Historical exog aligned to `context` (past covariates).
    exog : pandas Series, pandas DataFrame, dict, default None
        Future-known exogenous variables for the forecast horizon
        (future covariates).
    quantiles : list, tuple, default [0.1, 0.5, 0.9]
        Quantile levels to forecast. Values must be in the range (0, 1).
    check_inputs : bool, default True
        If `True`, the `context` and `context_exog` inputs are validated
        and normalized. If `False`, `context` must already be a
        `dict[str, pandas Series]` and `context_exog` must be a
        `dict[str, pandas DataFrame | None]` or `None`. This argument
        is created for internal use and is not recommended to be changed.

    Returns
    -------
    predictions : pandas DataFrame
        Long-format DataFrame with columns `['level', 'q_0.1', 'q_0.5', ...]`.

    Notes
    -----
    Foundation models are pre-trained and do not learn from the data passed
    to `fit`. The `fit` method only stores context (the last `context_length`
    observations) and metadata. This leads to four distinct behaviors
    depending on the combination of `is_fitted` and `context`:

    - **Not fitted, `context=None`**: raises `NotFittedError`. There is no
    context available for prediction.
    - **Fitted, `context=None`**: uses the context and `context_exog_` stored
    during `fit`. If the user supplies `context_exog`, it is ignored with a
    warning.
    - **Not fitted, `context` provided (zero-shot mode)**: The model uses
    `context` and `context_exog` (if provided) as context for prediction.
    - **Fitted, `context` provided**: Stored context is ignored, the
    provided `context` and `context_exog` (if provided) are used for
    prediction.

    """

    if not self.is_fitted and context is None:
        raise NotFittedError(
            "This forecaster is not fitted yet. Call `fit` with appropriate "
            "arguments before using `predict_quantiles()`, or pass `context`."
        )

    predictions = self.estimator.predict(
                      steps        = steps,
                      context      = context,
                      context_exog = context_exog,
                      exog         = exog,
                      quantiles    = list(quantiles),
                      levels       = levels,
                      check_inputs = check_inputs,
                  )

    return predictions

set_params ¶


set_params(params)

Set new values to the parameters of the underlying estimator.

After calling this method, the forecaster is reset to an unfitted state.

Parameters:

Name	Type	Description	Default
`params`	`dict`	Parameters values.	required

Returns:

Type	Description
`None`

Source code in skforecast/foundation/_forecaster_foundation.py

def set_params(self, params: dict[str, object]) -> None:
    """
    Set new values to the parameters of the underlying estimator.

    After calling this method, the forecaster is reset to an unfitted state.

    Parameters
    ----------
    params : dict
        Parameters values.

    Returns
    -------
    None

    """

    self.estimator.set_params(**params)
    self.is_fitted = False

summary ¶


summary()

Show forecaster information.

Returns:

Type	Description
`None`

Source code in skforecast/foundation/_forecaster_foundation.py

def summary(self) -> None:
    """
    Show forecaster information.

    Returns
    -------
    None

    """

    print(self.__repr__())

ForecasterFoundation¶

skforecast.foundation._forecaster_foundation.ForecasterFoundation ¶

Attributes¶

estimator instance-attribute ¶

creation_date instance-attribute ¶

is_fitted instance-attribute ¶

skforecast_version instance-attribute ¶

python_version instance-attribute ¶

forecaster_id instance-attribute ¶

context_length property ¶

model_id property ¶

window_size property ¶

context_ property ¶

last_window_ property ¶

context_exog_ property ¶

last_window_exog_ property ¶

index_type_ property ¶

index_freq_ property ¶

context_range_ property ¶

series_names_in_ property ¶

is_multiple_series_ property ¶

exog_in_ property ¶

exog_names_in_ property ¶

exog_names_in_per_series_ property ¶

exog_type_in_ property ¶

fit_date property ¶

Functions¶

_truncate_names staticmethod ¶

_format_names_repr staticmethod ¶

_repr_html_ ¶

fit ¶

predict ¶

predict_interval ¶

predict_quantiles ¶

set_params ¶

summary ¶

`ForecasterFoundation`¶

estimator `instance-attribute` ¶

creation_date `instance-attribute` ¶

is_fitted `instance-attribute` ¶

skforecast_version `instance-attribute` ¶

python_version `instance-attribute` ¶

forecaster_id `instance-attribute` ¶

context_length `property` ¶

model_id `property` ¶

window_size `property` ¶

context_ `property` ¶

last_window_ `property` ¶

context_exog_ `property` ¶

last_window_exog_ `property` ¶

index_type_ `property` ¶

index_freq_ `property` ¶

context_range_ `property` ¶

series_names_in_ `property` ¶

is_multiple_series_ `property` ¶

exog_in_ `property` ¶

exog_names_in_ `property` ¶

exog_names_in_per_series_ `property` ¶

exog_type_in_ `property` ¶

fit_date `property` ¶

_truncate_names `staticmethod` ¶

_format_names_repr `staticmethod` ¶