> open source · sktime ecosystem

Agentic Forecaster for sktime

A drop-in sktime forecaster that uses an LLM-powered ReAct agent loop to automatically select and configure time series pipelines — from a plain English description of your data.

• Python
• sktime
• Claude API
• OpenAI
• Gemini
• FastMCP
• ReAct

Try It

Interactive demo running on Hugging Face Spaces. Enter a description of your time series and watch the agent reason through model selection in real time.

↗ Open in full screen at huggingface.co/spaces/kpal002/sktime-agentic-forecaster

What is sktime?

sktime is a Python library for time series machine learning — think scikit-learn, but for sequential data. It provides a unified interface across forecasting, classification, regression, and transformation tasks. Every model follows the same fit() /predict() contract, making models composable in pipelines and ensembles.

This project asks: what if an LLM could reason about your data and pick the right model for you?

The Big Picture

From the outside, AgenticForecaster looks like any sktime model. You call .fit() with your time series and a natural language description of the data. Under the hood, an LLM agent takes over — reasoning through available models, fitting candidates, scoring them, and committing to the best one before returning control.

The key design constraint: the LLM never executes arbitrary code. It can only call a predefined set of six tools. This makes the system safe to deploy in a library context and keeps every decision auditable.

Constrained Tools, Not Free-Form Code

Most "LLM picks a model" demos work like this: prompt the model, get back a code snippet, run it with exec(). That isn't shippable in a library — you can't audit it, test it, or guarantee it won't import os and do something unexpected.

This is the same principle behind function calling in modern LLM APIs — instead of letting the model generate raw code, you give it a structured action space and let it reason within those constraints.

The Six Tools

The agent has exactly six tools available during .fit(). Each tool maps to a concrete action: inspect the data, enumerate models, fit a candidate, score it, or commit. Nothing outside this surface can be called.

The ReAct Loop

ReAct (Reasoning + Acting) is a prompting pattern introduced in a 2022 paper by Yao et al. The LLM alternates between a thought step — reasoning about what to do next — and an act step — calling a tool and observing the result. Each observation is appended to the message history, giving the model a growing context of everything it has tried so far.

• →The LLM maintains a message history — each tool result becomes part of the context for the next step.
• →Max steps is configurable (default 12). If the limit approaches without a commit, the loop emits a warning and hints the agent toward its best candidates so far.
• →A three-tier fallback fires if steps exhaust: use highest-scored candidate → attempt quick scoring on fitted candidates → use any fitted candidate.
• →The full transcript (every tool call and response) is stored in forecaster.transcript_ for inspection.

There are several ways to get an LLM to select a forecasting model. Each makes different trade-offs. ReAct was chosen because model selection is an empirical task — the right answer depends on what the data actually looks like and how candidates actually score, not what an LLM thinks they might score.

• →Latency — a full fit() run with a real LLM backend takes several seconds. This is acceptable for offline model selection but rules out real-time use cases.
• →Loop instability — LLMs can get stuck calling the same tool repeatedly without committing. The max_steps cap and three-tier fallback are mitigations, not solutions. Better prompting or a fine-tuned model would help.
• →Context length — the message history grows with every step. On very long runs (many candidates, verbose tool results) the context can become expensive. Tool results are kept terse to limit this.
• →Non-determinism — two runs on the same data with the same prompt can select different models. Temperature=0 reduces this but doesn't eliminate it for all backends.

What Happens During .fit()

Calling .fit(y, fh=h) triggers four distinct stages. The first three happen inside the ReAct loop; the last happens once the agent commits.

Two Transport Modes

A transport is how tool calls get routed from the agent to the actual tool implementation. This is an architectural layer that most single-purpose scripts ignore — but a library that wants to work in multiple deployment contexts needs to make it explicit. The transport parameter controls which path is used without changing anything else about the agent's behavior.

forecaster = AgenticForecaster(
    prompt="Monthly data, yearly seasonality",
    transport="in-process",
)

forecaster = AgenticForecaster(
    prompt="Monthly data, yearly seasonality",
    transport="mcp",
)

The Model Context Protocol (MCP) is an open standard introduced by Anthropic in 2024 for connecting AI models to external tools and data sources. Before MCP, every AI tool integration was bespoke — a plugin format for one app, a function schema for another, a REST API for a third. MCP standardizes the interface so any compliant client can talk to any compliant server without custom glue code.

Think of it as the USB-C of AI tool use. A sktime MCP server exposes forecasting tools; Claude Desktop, Cursor, or a custom agent can call them without knowing anything about sktime's internals.

Yes — several alternatives were considered. The design goal was: support the standard library use case with zero overhead, and support external clients without a custom integration per client.

• →stdio MCP is one-client-at-a-time — not suitable for serving multiple concurrent agents. An HTTP MCP transport would be needed for multi-tenant or server deployments.
• →State isolation in MCP mode — fitted candidates live in the server process, not the calling process. If the server crashes mid-fit, in-progress state is lost. In-process mode doesn't have this problem.
• →No remote MCP yet — the current MCP mode launches the server as a subprocess on the same machine. True remote deployment (server on a different host) requires the HTTP MCP transport, which is a planned extension.

Supported LLM Backends

The LLM client is swappable — the agent logic is the same regardless of which model powers it. This is important for cost management: you might use a cheaper model in development and a stronger one in production.

Full System Flow

Putting it all together — from the user's .fit() call to a fitted model ready for .predict().

Using AgenticForecaster

The interface is intentionally identical to any other sktime forecaster. The only additions are the prompt parameter (your natural language data description) and the post-fit attributes that expose the agent's reasoning.

from sktime_agentic import AgenticForecaster
import pandas as pd

# Your time series — a standard pandas Series with a DatetimeIndex
y = load_your_data()

# Describe what you know about the data in plain English
forecaster = AgenticForecaster(
    prompt="Monthly passenger counts with linear trend and yearly seasonality.",
    backend="anthropic",   # "openai" | "gemini" | "mock"
    transport="in-process",
    holdout=12,            # months held out for candidate scoring
    metric="mape",         # "mae" | "rmse"
    max_steps=12,          # max ReAct iterations
)

# Standard sktime interface — nothing special here
forecaster.fit(y, fh=12)

# Inspect what the agent decided and why
print(forecaster.selected_)
# → "ExponentialSmoothing"

print(forecaster.selected_params_)
# → {"trend": "add", "seasonal": "add", "sp": 12}

print(forecaster.rationale_)
# → "The series shows a clear linear trend and strong yearly seasonality
#    (sp=12). ExponentialSmoothing with additive trend and seasonal
#    components achieved MAPE=4.2% on the holdout — better than
#    NaiveForecaster (11.3%) and AutoARIMA (5.8%)."

# Generate forecast — same as any other sktime forecaster
forecast = forecaster.predict()
print(forecast)

The rationale_ attribute is the agent's explanation in plain English — not a log dump, but the reasoning it used to justify its selection. This is stored alongside the full transcript_ (every tool call and response) for full auditability.

Why These Choices?

Where This Is Going

The current prototype handles univariate selection with a fixed tool surface. Several natural extensions would make it production-ready.