Repository navigation
feat: add detect_seasonality and check_structural_break diagnostic tools (#96) - #114
SarthakB11 wants to merge 3 commits into
Conversation
bc437e2 to
b0cdaff
Compare
Two new MCP tools for pre-modeling statistical diagnostics: - detect_seasonality: FFT-accelerated autocorrelation with adaptive detrending, dynamic significance threshold, and optional frequency- aware scoring. Returns period, strength, and next_action_hint. - check_structural_break: Retrospective CUSUM on raw data with a Brownian Bridge confidence bound. Returns break location, confidence, and next_action_hint. Both tools are registered in the MCP server and include 12 tests. Closes sktime#96
Both detect_seasonality and check_structural_break now reject series containing NaN or Inf values with a clear error message, instead of silently producing garbage results from FFT/CUSUM on non-finite data. Added 4 tests (NaN + Inf for each tool).
Expose break location as a fraction of series length (0.0 to 1.0). This helps LLMs detect the known CUSUM false-positive pattern where a linear trend produces a break near 0.5 — the fraction field makes this signal explicit without requiring the LLM to compute it. Added 2 tests: location_fraction None when no break, and linear trend break-at-midpoint pattern.
b0cdaff to
75fa67c
Compare
|
Rebased onto main (import/dispatcher conflicts with the newer job-cleanup tools, resolved by keeping both). Full suite passes locally (215 passed, including the 18 new diagnostics tests). Ready for review whenever you get a chance. |
|
Since this was opened the maintainers consolidated the server to 26 tools (#270) and prefer exposing sktime's own estimators through instantiate/fit/get_fitted_params/call_method over adding task-specific tools; seasonality and change-point detection are already reachable that way (SeasonalityACF from sktime.param_est, detectors in sktime.detection). Closing in line with that direction; if a diagnostics tool is ever warranted, a thin wrapper over those sktime estimators would be the preferred shape. |
|
Since this was opened the maintainers consolidated the server to 26 tools (#270) and prefer exposing sktime's own estimators through instantiate/fit/get_fitted_params/call_method over adding task-specific tools; seasonality and change-point detection are already reachable that way (SeasonalityACF from sktime.param_est, detectors in sktime.detection). Closing in line with that direction; if a diagnostics tool is ever warranted, a thin wrapper over those sktime estimators would be the preferred shape. |
Closes #96
Summary
Two new MCP tools for pre-modeling statistical diagnostics, following @nXtCyberNet's design from #96:
detect_seasonalityO(N log N)) with adaptive detrendingmax(1.96/sqrt(N), 0.2)period,strength,seasonality_class,confidence,candidates,next_action_hintcheck_structural_break1.358 * (1 + 0.1 * ln(N))(Brownian Bridge 95% bound)break_detected,location,confidence,test_stat,next_action_hintBoth tools provide
next_action_hintto guide LLM agents in agentic forecasting workflows.Changes
src/sktime_mcp/tools/diagnostics.py— tool implementations (265 lines)src/sktime_mcp/server.py— tool registration inlist_tools+call_tooltests/test_diagnostics.py— 12 tests covering both tools (seasonality detection, structural breaks, edge cases, output structure)Test plan
pytest tests/test_diagnostics.py)pytest tests/)numpywhich is already a dep)