1from __future__ import annotations2import pandas as pd3import numpy as np45def build_calendar_features(df: pd.DataFrame) -> pd.DataFrame:6    # week-of-year, day-of-week, holiday flags7    df["woy"] = df["date"].dt.isocalendar().week8    df["dow"] = df["date"].dt.dayofweek9    df["is_snap_day"] = df["snap_TX"] | df["snap_CA"] | df["snap_WI"]10    return df1112def build_lag_features(df: pd.DataFrame, lags: list[int] = [7, 14, 28]) -> pd.DataFrame:13    for lag in lags:14        df[f"sales_lag_{lag}"] = df.groupby("id")["sales"].shift(lag)15    return df1617def build_rolling_features(df: pd.DataFrame, windows: list[int] = [7, 28]) -> pd.DataFrame:18    for w in windows:19        df[f"roll_mean_{w}"] = df.groupby("id")["sales"].rolling(w).mean().values20        df[f"roll_std_{w}"]  = df.groupby("id")["sales"].rolling(w).std().values21    return df18    for w in windows:19        grp = df.groupby("id")["sales"]20        df[f"roll_mean_{w}"] = grp.rolling(w, min_periods=1).mean().values21        df[f"roll_std_{w}"]  = grp.rolling(w, min_periods=1).std().values22    return df2324# NEW v4 — addresses cluster #14 (Pacific NW Q4 winter footwear under-prediction)25def build_promo_overlap_features(df: pd.DataFrame) -> pd.DataFrame:26    # 1-week-prior promotion flag — when promo runs the week BEFORE the forecast week27    df["promo_lag_1w"] = df.groupby("id")["sell_price"].pct_change(7).fillna(0) < -0.1028    # cold-snap regional flag — temp anomaly for Pacific NW stores in current week29    df["cold_snap_pnw"] = (df["region"] == "PNW") & (df["temp_anomaly"] < -5)30    # interaction term: promo overlap × cold snap — the cluster #14 root cause31    df["promo_x_cold_pnw"] = df["promo_lag_1w"] & df["cold_snap_pnw"]32    return df3334def build_features(df: pd.DataFrame) -> pd.DataFrame:35    df = build_calendar_features(df)36    df = build_lag_features(df)37    df = build_rolling_features(df)38    df = build_promo_overlap_features(df)39    return df.fillna(0)