Skip to main content

​
ForecastV2Request

class ForecastV2Request(BaseModel):
    samples: List[List[SingleEvalSamplePayload]]
    model: str

​
Parameters

​
samples

Type: List[List[SingleEvalSamplePayload]] List of sample rows, where each row contains 1 or more time series samples (target + metadata). All samples in a row must have the same timestamps for consistency.

​
model

Type: str Name of the model to use for forecasting. Must be a non-empty string. The model name is trimmed of whitespace.

​
Raises

​
ValueError

  • If samples list is empty
  • If any sample row is empty
  • If samples in a row have mismatched timestamps
  • If model name is empty or whitespace

​
Notes

  • Each sample row represents a single forecast / forecasting scenario
  • The model name is automatically trimmed of leading/trailing whitespace
  • Samples are validated for consistency before processing
  • All samples in a row must have matching timestamps

​
Examples

​
Multiple Sample Rows

# First scenario: high sales, warm weather
scenario1 = [
    SingleEvalSamplePayload(
        sample_id="sales",
        history_timestamps=["2023-01-01", "2023-01-02"],
        history_values=[100.0, 110.0],
        target_timestamps=["2023-01-03", "2023-01-04"],
        target_values=[120.0, 130.0]
    ),
    SingleEvalSamplePayload(
        sample_id="temperature",
        history_timestamps=["2023-01-01", "2023-01-02"],
        history_values=[25.0, 26.0],
        target_timestamps=["2023-01-03", "2023-01-04"],
        target_values=[27.0, 28.0],
        metadata=True
    )
]

# Second scenario: low sales, cold weather
scenario2 = [
    SingleEvalSamplePayload(
        sample_id="sales",
        history_timestamps=["2023-01-01", "2023-01-02"],
        history_values=[50.0, 55.0],
        target_timestamps=["2023-01-03", "2023-01-04"],
        target_values=[60.0, 65.0]
    ),
    SingleEvalSamplePayload(
        sample_id="temperature",
        history_timestamps=["2023-01-01", "2023-01-02"],
        history_values=[5.0, 6.0],
        target_timestamps=["2023-01-03", "2023-01-04"],
        target_values=[7.0, 8.0],
        metadata=True
    )
]

request = ForecastV2Request(
    samples=[scenario1, scenario2],
    model="Migas-1.0"
)
print(f"Number of scenarios: {len(request.samples)}")

​
Class Methods

​
from_dfs

@classmethod
def from_dfs(
    cls,
    history_dfs: List[pd.DataFrame],
    target_dfs: List[pd.DataFrame],
    target_col: str,
    timestamp_col: str,
    metadata_cols: List[str],
    leak_cols: List[str],
    model: str,
) -> "ForecastV2Request":
    """Create a ForecastV2Request from pandas DataFrames."""
Create a ForecastV2Request from pandas DataFrames. This method converts pandas DataFrames into the structured format required for forecasting requests.

​
Parameters

history_dfs
Type: List[pd.DataFrame] List of DataFrames containing historical data. Each DataFrame represents one forecasting scenario.
target_dfs
Type: List[pd.DataFrame] List of DataFrames containing target (future) data. Must have the same length as history_dfs.
target_col
Type: str Name of the target column to forecast. Must exist in all DataFrames and cannot be in metadata_cols.
timestamp_col
Type: str Name of the timestamp column. Must exist in all DataFrames and cannot be in metadata_cols.
metadata_cols
Type: List[str] List of metadata column names. These columns provide context but are not forecasted. Cannot include target_col or timestamp_col.
leak_cols
Type: List[str] List of columns that should be marked as leak_target=True. Must be a subset of metadata_cols.
model
Type: str Name of the model to use for forecasting.

​
Raises

  • ValueError: If history_dfs and target_dfs have different lengths
  • ValueError: If any DataFrame is missing required columns
  • ValueError: If all DataFrames don’t have consistent column structure
  • ValueError: If leak_cols is not a subset of metadata_cols
  • ValueError: If target_col or timestamp_col are in metadata_cols
  • ValueError: If any DataFrame is empty

​
Notes

  • All DataFrames must have the same column structure
  • NaN values are automatically converted to None for JSON compatibility
  • Each DataFrame pair (history_df, target_df) creates one sample row/forecast scenario
  • Target column creates a forecast sample, metadata columns create metadata samples
  • Leak columns are marked with leak_target=True

​
Example

# Create historical data
history_data = {
    'timestamp': pd.date_range('2023-01-01', periods=3, freq='D'),
    'sales': [100, 110, 120],
    'temperature': [20, 21, 22]
}
history_df = pd.DataFrame(history_data)

# Create target data
target_data = {
    'timestamp': pd.date_range('2023-01-04', periods=2, freq='D'),
    'sales': [None, None],
    'temperature': [23, 24]
}
target_df = pd.DataFrame(target_data)

# Create request
request = ForecastV2Request.from_dfs(
    history_dfs=[history_df],
    target_dfs=[target_df],
    target_col='sales',
    timestamp_col='timestamp',
    metadata_cols=['temperature'],
    leak_cols=[],
    model='Migas-1.0'
)

​
from_dfs_pre_split

@classmethod
def from_dfs_pre_split(
    cls,
    dfs: List[pd.DataFrame],
    timestamp_col: str,
    target_cols: List[str],
    model: str,
    cutoff_date: Optional[str] = None,
    num_target_rows: Optional[int] = None,
    metadata_cols: List[str] = [],
    leak_cols: List[str] = [],
    forecast_window: Optional[Union[str, int]] = None,
    stride: Optional[Union[str, int]] = None,
) -> "ForecastV2Request":
    """Create a ForecastV2Request from pandas DataFrames with backtesting support."""
Create a ForecastV2Request from pandas DataFrames with backtesting support. This method creates evaluation batches from multiple DataFrames, supporting both single-window and backtesting scenarios.

​
Parameters

dfs
Type: List[pd.DataFrame] List of pandas DataFrames to process. Each DataFrame should contain time series data with a timestamp column and various feature columns.
timestamp_col
Type: str Name of the column containing timestamps. This column will be converted to datetime format and used for splitting data into history and target periods.
target_cols
Type: List[str] Column names to be used as forecast targets. These columns will have forecast=True in the resulting SingleEvalSamplePayload objects.
model
Type: str Name of the model to use for forecasting.
cutoff_date
Type: Optional[str] Default: None Date string (e.g., “2023-01-01”) to split data into history (≤ cutoff) and target (> cutoff) periods. Mutually exclusive with num_target_rows.
num_target_rows
Type: Optional[int] Default: None Number of rows to use as target period (taken from the end of each DataFrame). Mutually exclusive with cutoff_date.
metadata_cols
Type: List[str] Default: [] Column names to be used as metadata/correlates. These columns will have metadata=True in the resulting SingleEvalSamplePayload objects.
leak_cols
Type: List[str] Default: [] Column names that are allowed to leak target information. Must be a subset of metadata_cols. These columns will have leak_target=True.
forecast_window
Type: Optional[Union[str, int]] Default: None For backtesting: the size of the forecast window. If str, interpreted as pandas time offset (e.g., “7D” for 7 days). If int, interpreted as number of rows. Must be provided together with stride.
stride
Type: Optional[Union[str, int]] Default: None For backtesting: the step size between consecutive forecasts. If str, interpreted as pandas time offset. If int, interpreted as number of rows. Must be provided together with forecast_window.

​
Raises

  • ValueError: If both cutoff_date and num_target_rows are provided
  • ValueError: If neither cutoff_date nor num_target_rows are provided
  • ValueError: If forecast_window is provided without stride or vice versa
  • ValueError: If no history rows are found for the given cutoff_date
  • ValueError: If type mismatches occur (e.g., string vs int for forecast_window/stride)
  • ValueError: If leak_cols is not a subset of metadata_cols
  • ValueError: If target_cols overlap with metadata_cols

​
Processing Modes

The method supports four processing modes:
  1. Single window by date: cutoff_date provided, no forecast_window/stride
  2. Single window by rows: num_target_rows provided, no forecast_window/stride
  3. Backtesting by date: cutoff_date + forecast_window/stride (all strings)
  4. Backtesting by rows: num_target_rows + forecast_window/stride (all integers)

​
Examples

Single window by date: 
request = ForecastV2Request.from_dfs_pre_split(
    dfs=[df1, df2],
    timestamp_col="date",
    target_cols=["sales"],
    model="Migas-1.0",
    cutoff_date="2023-06-01",
    metadata_cols=["temperature", "holiday"]
)
Backtesting by date: 
request = ForecastV2Request.from_dfs_pre_split(
    dfs=[df1],
    timestamp_col="date",
    target_cols=["sales"],
    model="Migas-1.0",
    cutoff_date="2023-01-01",
    forecast_window="7D",
    stride="1D"
)
Backtesting by rows: 
request = ForecastV2Request.from_dfs_pre_split(
    dfs=[df1],
    timestamp_col="date",
    target_cols=["sales"],
    model="Migas-1.0",
    num_target_rows=30,
    forecast_window=7,
    stride=1,
    metadata_cols=["temperature"]
)

​
See Also