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="ensemble_model"
)
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."""

​
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."""

​
See Also