Skip to content

Plans

skforecast_ai.schemas.plans

Classes:

Name Description
CVParams

LLM-produced cross-validation parameters for TimeSeriesFold.
PreprocessingStep

A preprocessing action required before forecasting.
WindowFeature

A single rolling-window feature specification for a forecaster.
PlanOverrides

LLM-produced overrides for a forecasting plan.
ForecastPlan

Detailed forecasting plan produced from a ForecastingProfile.

Attributes

Classes

CVParams

Bases: BaseModel

LLM-produced cross-validation parameters for TimeSeriesFold.

Returned as structured output from the CV configuration agent. All fields have defaults so the LLM only needs to specify the parameters it wants to override from the deterministic baseline.

Attributes:

Name Type Description
initial_train_size (int, float, str)

Number of observations (int), fraction of data (float in (0, 1)), or date string for the initial training set.
refit (bool, int)

Whether to refit every fold (True), never (False), or every n folds (int).
fixed_train_size bool

If True, training size stays fixed; if False, expands.
gap int

Observations between end of training and start of test.
fold_stride (int, None)

Observations between consecutive test set starts. None means equal to steps.
skip_folds int, list of int, None

Folds to skip. Int means keep every n-th fold; list specifies indexes.
allow_incomplete_fold bool

Whether to allow a final fold with fewer observations than steps.
reasoning str

Explanation of why these parameters were chosen. Shown to the user for transparency.
Attributes
initial_train_size class-attribute instance-attribute 
initial_train_size = Field(
    description="Number of observations (int), fraction of total data (float in (0,1)), or date string for the initial training set."
)
refit class-attribute instance-attribute 
refit = Field(
    default=True,
    description="Whether to refit the model every fold (True), never (False), or every n folds (int).",
)
fixed_train_size class-attribute instance-attribute 
fixed_train_size = Field(
    default=False,
    description="If True, training window stays fixed (rolling). If False, training window expands each fold.",
)
gap class-attribute instance-attribute 
gap = Field(
    default=0,
    description="Number of observations between training end and test start.",
)
fold_stride class-attribute instance-attribute 
fold_stride = Field(
    default=None,
    description="Number of observations between consecutive test set starts. None defaults to steps (non-overlapping test sets).",
)
skip_folds class-attribute instance-attribute 
skip_folds = Field(
    default=None,
    description="Folds to skip. Int keeps every n-th fold; list specifies fold indexes to skip.",
)
allow_incomplete_fold class-attribute instance-attribute 
allow_incomplete_fold = Field(
    default=True,
    description="Whether to allow a final fold with fewer observations than steps.",
)
reasoning class-attribute instance-attribute 
reasoning = Field(
    description="Explanation of why these parameters were chosen, referencing the user's deployment scenario."
)

PreprocessingStep

Bases: BaseModel

A preprocessing action required before forecasting.

Attributes:

Name Type Description
action str

Identifier for the preprocessing operation (e.g. 'sort_index', 'asfreq', 'reshape_long_to_dict').
reason str

Human-readable explanation of why this step is needed.
code_snippet str

Python code template that implements this step. May contain format placeholders (e.g. {frequency}, {date_column}).
blocking bool, default True

Whether skforecast will fail without this step. Non-blocking steps are recommended but optional.
Attributes
action instance-attribute 
action
reason instance-attribute 
reason
code_snippet instance-attribute 
code_snippet
blocking class-attribute instance-attribute 
blocking = True

WindowFeature

Bases: BaseModel

A single rolling-window feature specification for a forecaster.

Attributes:

Name Type Description
stats list of str

Rolling statistics to compute (e.g. ['mean', 'std']). Each value must be one of the statistics supported by skforecast's RollingFeatures: 'mean', 'std', 'min', 'max', 'sum', 'median', 'ratio_min_max', 'coef_variation', 'ewm'.
window_size int

Rolling window length in observations, applied to every statistic in stats. Must be a scalar; to combine several window sizes, use one WindowFeature per size.
Attributes
stats class-attribute instance-attribute 
stats = Field(
    description="Rolling statistics to compute. Each value must be one of: 'mean', 'std', 'min', 'max', 'sum', 'median', 'ratio_min_max', 'coef_variation', 'ewm'."
)
window_size class-attribute instance-attribute 
window_size = Field(
    description="Rolling window length in observations, e.g. 7. Scalar only: it is applied to every statistic in `stats`. Use one entry per window size to combine several sizes."
)

PlanOverrides

Bases: BaseModel

LLM-produced overrides for a forecasting plan.

Attributes:

Name Type Description
lags list of int, int, default None

Overridden lag indices or lag count.
window_features list of WindowFeature, default None

Overridden window features configurations.
reasoning str

Explanation of why the LLM chose these features based on the user's domain knowledge prompt.
Attributes
lags class-attribute instance-attribute 
lags = Field(
    default=None,
    description="The lag indices to use for the forecaster. E.g. [1, 2, 3, 7, 14] or an integer for consecutive lags.",
)
window_features class-attribute instance-attribute 
window_features = Field(
    default=None,
    description="The window features configurations to use. E.g. [{'stats': ['mean', 'std'], 'window_size': 7}].",
)
reasoning class-attribute instance-attribute 
reasoning = Field(
    description="Explanation of why these specific features (lags and window features) were chosen based on the user's prompt and time series context."
)

ForecastPlan

Bases: DisplayMixin, BaseModel

Detailed forecasting plan produced from a ForecastingProfile.

Carries every concrete decision needed to fit, evaluate and predict: lag structure, prediction intervals, NaN handling, exogenous usage and preprocessing steps.

Attributes:

Name Type Description
task_type str

Forecasting task category (mirrored from the source ForecastingProfile). One of 'single_series', 'multi_series', 'multivariate', 'statistical', 'foundation'.
forecaster str

Name of the skforecast forecaster class.
forecaster_kwargs dict, default {}

Keyword arguments for the forecaster constructor (e.g. lags, steps, encoding, dropna_from_series). Can be unpacked directly into the constructor alongside estimator.
estimator str, default None

Name of the scikit-learn compatible estimator.
estimator_kwargs dict, default {}

Keyword arguments for the estimator constructor (e.g. n_estimators, learning_rate). Merged on top of built-in defaults (random_state, silencing flags).
steps int

Number of steps ahead to predict. Must be greater than 0.
frequency str, default None

Pandas frequency string for the series.
end_train str, default None

Last datetime (inclusive) of the training set as a string (e.g. '2005-03-01'). When set, the generated code runs in evaluation mode: it splits the data at this boundary, trains on the training portion, predicts the test portion and computes metrics. When None, the generated code runs in prediction mode: it trains on all available data and forecasts the future (no metrics, since there is no ground truth to compare against).
interval list, default None

Prediction interval quantiles as [lower, upper] (e.g. [0.1, 0.9]). If None, no intervals are computed.
interval_method str, default None

Method for prediction intervals. One of 'bootstrapping', 'conformal', 'native'.
metric str, default 'mean_absolute_error'

Recommended primary evaluation metric (string name matching sklearn/skforecast naming conventions).
metrics_to_compute (list, default['mean_absolute_error', 'mean_squared_error', 'mean_absolute_scaled_error'])

Full list of metrics to evaluate in generated code.
use_exog bool, default False

Whether to include exogenous variables.
preprocessing_steps list

Ordered list of preprocessing steps required before forecasting.
warnings list

Human-readable warnings about the plan.
llm_refined_fields list

Names of the fields ('lags', 'window_features') whose values were suggested by the LLM during refine_plan(). Empty for deterministic plans and for fields the user overrode explicitly. Used to flag LLM-sourced values when the plan is displayed.
explanation str

Explanation of the plan-level decisions.
Attributes
task_type instance-attribute 
task_type
forecaster instance-attribute 
forecaster
forecaster_kwargs class-attribute instance-attribute 
forecaster_kwargs = Field(default_factory=dict)
estimator class-attribute instance-attribute 
estimator = None
estimator_kwargs class-attribute instance-attribute 
estimator_kwargs = Field(default_factory=dict)
steps class-attribute instance-attribute 
steps = Field(gt=0)
frequency class-attribute instance-attribute 
frequency = None
end_train class-attribute instance-attribute 
end_train = None
interval class-attribute instance-attribute 
interval = None
interval_method class-attribute instance-attribute 
interval_method = None
metric class-attribute instance-attribute 
metric = 'mean_absolute_error'
metrics_to_compute class-attribute instance-attribute 
metrics_to_compute = Field(
    default_factory=lambda: [
        "mean_absolute_error",
        "mean_squared_error",
        "mean_absolute_scaled_error",
    ]
)
use_exog class-attribute instance-attribute 
use_exog = False
preprocessing_steps class-attribute instance-attribute 
preprocessing_steps = Field(default_factory=list)
warnings class-attribute instance-attribute 
warnings = Field(default_factory=list)
llm_refined_fields class-attribute instance-attribute 
llm_refined_fields = Field(default_factory=list)
explanation instance-attribute 
explanation
Functions
_rich_body 
_rich_body(console, options)
Source code in skforecast_ai/schemas/plans.py 
274
275
def _rich_body(self, console, options):
    yield render_plan(self)

Functions