fix: normalise loaded handles to PeriodIndex so seasonal forecasters work (#531)

load_data_source produced a DatetimeIndex with freq "MS" (MonthBegin) for
monthly data. Seasonal forecasters (sp>1) coerce the index to a PeriodIndex
internally via index.to_period(freq) and raise "<MonthBegin> is not supported
as period frequency" — so fit succeeded and predict failed, with no signal at
fit time and no in-toolset workaround. This also broke evaluate and
demo-fit + handle-update (NB-19) for the same reason.

Normalise a regular DatetimeIndex to PeriodIndex at load, matching sktime's
demo datasets (which carry a PeriodIndex and work). to_period() is called with
no argument so pandas maps the offset to its period alias (MS -> "M"); passing
the offset string back would re-raise the same error. No-op for irregular
indexes, already-PeriodIndex, or non-datetime indexes. Applied in
format_data_handle (the auto-format-on-load path) and in the
auto-format-disabled fallback.

Verified: split_data, save_data, plot_series, inspect_data all still work on
the period-indexed handles. Fixes #531; unblocks NB-19.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Shashankss1205

src/sktime_mcp/runtime/executor.py

@@ -49,6 +49,38 @@ def _get_demo_datasets() -> dict:
     return _DEMO_DATASETS
 
 
+def _to_period_index_if_possible(obj: Any) -> Any:
+    """Return *obj* with a ``PeriodIndex`` when its index is a regular datetime index.
+
+    Seasonal sktime forecasters coerce the series index to a ``PeriodIndex``
+    internally (``index.to_period(freq)``) and raise on offset frequencies such
+    as ``MonthBegin`` ("MS"), which is what ``load_data_source`` produces for
+    monthly data. Demo datasets carry a ``PeriodIndex`` and work, so we
+    normalise handle-loaded data to match. ``to_period()`` is called with no
+    argument so pandas maps the offset to its period alias (MS -> "M"); passing
+    the offset string back in would re-raise the same error.
+
+    No-op for non-datetime indexes, ``PeriodIndex`` already, or an index with no
+    determinable frequency.
+    """
+    if obj is None or not hasattr(obj, "index"):
+        return obj
+    idx = obj.index
+    if isinstance(idx, pd.PeriodIndex) or not isinstance(idx, pd.DatetimeIndex):
+        return obj
+    try:
+        if idx.freq is None:
+            inferred = pd.infer_freq(idx)
+            if inferred is None:
+                return obj
+            idx = pd.DatetimeIndex(idx, freq=inferred)
+        converted = obj.copy()
+        converted.index = idx.to_period()
+        return converted
+    except (ValueError, TypeError):
+        return obj
+
+
 def _get_index_frequency_metadata(
     index: pd.Index,
     fallback: str | None = None,
@@ -1055,6 +1087,15 @@ def load_data_source(self, config: dict[str, Any]) -> dict[str, Any]:
                 except Exception as e:
                     logger.warning(f"Auto-formatting failed: {e}")
                     # Continue with unformatted data if formatting fails
+
+            # Auto-format disabled or failed: still normalise the stored handle to
+            # a PeriodIndex where possible so seasonal forecasters work (#531).
+            stored = self._data_handles.get(data_handle)
+            if stored is not None:
+                stored["y"] = _to_period_index_if_possible(stored["y"])
+                if stored.get("X") is not None:
+                    stored["X"] = _to_period_index_if_possible(stored["X"])
+
             _final_meta = adapter.get_metadata().copy()
             _final_meta["dtypes"] = {col: str(dtype) for col, dtype in data.dtypes.items()}
             return {
@@ -1302,6 +1343,12 @@ def format_data_handle(
             if X is not None:
                 X.index.freq = changes_made["frequency"]
 
+        # 6. Normalise a regular DatetimeIndex to PeriodIndex so seasonal
+        # forecasters can predict on handle-loaded data (#531).
+        y = _to_period_index_if_possible(y)
+        if X is not None:
+            X = _to_period_index_if_possible(X)
+
         # Generate new handle
         new_handle = f"data_{uuid.uuid4().hex[:8]}"
 

tests/test_periodindex_normalization.py

@@ -0,0 +1,95 @@
+"""Handle-loaded monthly data must support seasonal forecasters (#531).
+
+load_data_source produced a DatetimeIndex with freq "MS" (MonthBegin), while
+seasonal forecasters coerce to PeriodIndex internally and raise
+"<MonthBegin> is not supported as period frequency" at predict time — fit
+succeeded, predict failed. Handles are now normalised to PeriodIndex at load,
+matching demo datasets.
+"""
+
+import pandas as pd
+import pytest
+
+from sktime_mcp.runtime.executor import _to_period_index_if_possible, get_executor
+from sktime_mcp.tools.fit_predict import fit_tool, predict_tool, update_tool
+from sktime_mcp.tools.instantiate import instantiate_tool
+
+
+def _load_monthly(executor, periods=36):
+    data = {
+        "date": [f"20{20 + i // 12}-{i % 12 + 1:02d}-01" for i in range(periods)],
+        "value": [100.0 + i + 10 * (i % 12) for i in range(periods)],
+    }
+    res = executor.load_data_source(
+        {"type": "pandas", "data": data, "time_column": "date", "target_column": "value"}
+    )
+    assert res["success"], res
+    return res["data_handle"]
+
+
+class TestHelper:
+    def test_datetime_ms_becomes_period(self):
+        idx = pd.date_range("2020-01-01", periods=12, freq="MS")
+        s = pd.Series(range(12), index=idx)
+        out = _to_period_index_if_possible(s)
+        assert isinstance(out.index, pd.PeriodIndex)
+        assert out.index.freqstr == "M"
+
+    def test_freqless_but_regular_is_inferred(self):
+        idx = pd.DatetimeIndex(pd.date_range("2020-01-01", periods=12, freq="MS").values)
+        assert idx.freq is None
+        out = _to_period_index_if_possible(pd.Series(range(12), index=idx))
+        assert isinstance(out.index, pd.PeriodIndex)
+
+    def test_irregular_index_untouched(self):
+        idx = pd.to_datetime(["2020-01-01", "2020-01-05", "2020-03-02"])
+        s = pd.Series([1, 2, 3], index=idx)
+        out = _to_period_index_if_possible(s)
+        assert isinstance(out.index, pd.DatetimeIndex)
+
+    def test_period_index_noop(self):
+        s = pd.Series(range(6), index=pd.period_range("2020-01", periods=6, freq="M"))
+        assert _to_period_index_if_possible(s) is not None
+        assert isinstance(_to_period_index_if_possible(s).index, pd.PeriodIndex)
+
+
+class TestSeasonalPredictOnHandle:
+    def test_load_gives_period_index(self):
+        executor = get_executor()
+        dh = _load_monthly(executor)
+        try:
+            assert isinstance(executor._data_handles[dh]["y"].index, pd.PeriodIndex)
+        finally:
+            executor._data_handles.pop(dh, None)
+
+    def test_seasonal_fit_then_predict(self):
+        """The exact reported repro: fit sp=12 on a handle, then predict."""
+        executor = get_executor()
+        dh = _load_monthly(executor)
+        inst = instantiate_tool(spec="NaiveForecaster(strategy='last', sp=12)")
+        handle = inst["handle"]
+        try:
+            fit_res = fit_tool(estimator_handle=handle, y_handle=dh)
+            assert fit_res["success"], fit_res
+            pred = predict_tool(estimator_handle=handle, horizon=6)
+            assert pred["success"], pred
+            assert len(pred["predictions"]) == 6
+        finally:
+            executor._handle_manager.release_handle(handle)
+            executor._data_handles.pop(dh, None)
+
+    def test_seasonal_evaluate_on_handle(self):
+        from sktime_mcp.tools.evaluate import evaluate_tool
+
+        executor = get_executor()
+        dh = _load_monthly(executor)
+        inst = instantiate_tool(spec="NaiveForecaster(sp=12)")
+        handle = inst["handle"]
+        try:
+            res = evaluate_tool(estimator_handle=handle, y=dh, cv_folds=3)
+            assert res["success"], res
+            for v in res["metrics"].values():
+                assert v == v  # not NaN
+        finally:
+            executor._handle_manager.release_handle(handle)
+            executor._data_handles.pop(dh, None)