Agentic Forecaster

MCP-native agentic time series forecaster built on top of sktime-mcp.

Problem

Existing LLM-based forecasters (#9721) do single-shot model selection: the LLM picks one model and that's it. No evaluation, no comparison, no pipeline composition.

Solution

An agentic loop that uses sktime-mcp tools (via JSON-RPC over stdio) to automatically:

1. Load data — built-in datasets or custom CSV files via load_data_source
2. Analyze features — LLM identifies seasonality, trend, stationarity, volatility
3. Select & evaluate candidates — list_estimators + evaluate_estimator (cross-validation)
4. Reflect & decide — LLM analyzes results, decides next action (pipeline, hyperparams, new model, or stop)
5. Iterate — compose pipelines, tune parameters, try new models until stopping criteria are met
6. Predict & export — fit_predict + export_code (reproducible output)

Architecture

User: "predict next 12 months"
       |
AgenticForecaster (LLM + reflect-decide-act loop)
       | JSON-RPC over stdio (MCP protocol)
sktime-mcp server (subprocess)
       | calls
sktime library (hundreds of estimators)

Agentic Loop

Unlike a fixed pipeline, the agent uses a reflect-decide-act loop:

1. Evaluate initial candidate models with cross-validation
2. Reflect — LLM analyzes what worked, what didn't, and why
3. Decide next action: try_pipeline, try_hyperparams, try_new_model, or stop
4. Act — execute the chosen action and record results
5. Repeat until stopping criteria are met (MAPE threshold, max iterations, no improvement)

Setup

# Clone dependencies
git clone https://github.com/sktime/sktime-mcp.git ../sktime-mcp

# Install
pip install -r requirements.txt
cd ../sktime-mcp && pip install -e . && cd -

# Configure
cp .env.example .env
# Edit .env with your GEMINI_API_KEY

Usage

# Built-in datasets
python main.py                                          # airline dataset, horizon=12
python main.py --dataset sunspots --horizon 24          # sunspots, 24 periods

# Custom CSV data
python main.py --csv data.csv                           # auto-detect columns
python main.py --csv data.csv --time-col date --target-col sales

Examples

python examples/01_forecasting_workflow.py   # Full workflow: discovery, eval, predict, export
python examples/02_pipeline_composition.py   # Pipeline creation, validation, comparison
python examples/03_custom_csv_data.py        # Load and forecast on custom CSV files
python examples/04_model_comparison.py       # Compare multiple models with cross-validation
python examples/05_async_training.py         # Non-blocking async training with progress

Output

Best model: ConditionalDeseasonalizer -> Detrender -> AutoARIMA
Best MAPE: 0.0523
Model type: pipeline
Iterations: 3
Total attempts: 7 (1 failed)

All evaluation results:
  * ConditionalDeseasonalizer -> Detrender -> AutoARIMA: MAPE=0.0523 (pipeline)
    AutoARIMA: MAPE=0.0812 (single)
    AutoETS: MAPE=0.0867 (single)
    ThetaForecaster: MAPE=0.0934 (single)
    TBATS: MAPE=0.1021 (single)

Project Structure

agentic-forecaster/
├── src/
│   ├── agent.py          # Agentic loop with reflection and adaptive retry
│   ├── mcp_client.py     # MCP client (JSON-RPC over stdio)
│   └── prompts.py        # LLM prompt templates (analysis, reflection, stopping)
├── examples/
│   ├── 01_forecasting_workflow.py  # Full MCP workflow demo
│   ├── 02_pipeline_composition.py  # Pipeline creation and validation
│   ├── 03_custom_csv_data.py       # Custom CSV data loading
│   ├── 04_model_comparison.py      # Multi-model comparison
│   └── 05_async_training.py       # Async training with progress
├── docs/
│   ├── architecture.md    # System architecture and MCP communication
│   ├── user-guide.md      # Installation, usage, configuration
│   └── agentic-loop.md    # How the reflect-decide-act loop works
├── main.py               # CLI entry point
├── requirements.txt
└── .env