skforecast-ai

<h1 align="left">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/skforecast/skforecast-ai/blob/main/docs/img/banner-landing-page-dark-mode-skforecast-ai-no-background.png?raw=true">
    <img src="https://github.com/skforecast/skforecast-ai/blob/main/docs/img/banner-landing-page-skforecast-ai.png?raw=true" alt="skforecast-ai">
  </picture>
</h1>


| | |
| --- | --- |
| Package | ![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue) [![PyPI](https://img.shields.io/pypi/v/skforecast-ai)](https://pypi.org/project/skforecast-ai/) [![Total downloads](https://static.pepy.tech/personalized-badge/skforecast-ai?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=total%20downloads)](https://pepy.tech/projects/skforecast-ai) [![PyPI monthly downloads](https://img.shields.io/pypi/dm/skforecast-ai?color=blue&label=pypi%20downloads)](https://pypistats.org/packages/skforecast-ai) |
| Agents | [![MCP server](https://img.shields.io/badge/MCP-server-blue?logo=modelcontextprotocol&logoColor=white)](https://ai.skforecast.org/stable/user-guides/mcp-server.html) [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue?logo=modelcontextprotocol&logoColor=white)](https://registry.modelcontextprotocol.io/?q=skforecast) [![Claude Code plugin](https://img.shields.io/badge/Claude_Code-plugin-d97757)](https://ai.skforecast.org/stable/user-guides/mcp-server.html#install) |
| Meta | [![License](https://img.shields.io/github/license/skforecast/skforecast-ai)](https://github.com/skforecast/skforecast-ai/blob/main/LICENSE) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21338159.svg)](https://doi.org/10.5281/zenodo.21338159) |
| Testing | [![Build status](https://github.com/skforecast/skforecast-ai/actions/workflows/unit-tests.yml/badge.svg)](https://github.com/skforecast/skforecast-ai/actions/workflows/unit-tests.yml) [![codecov](https://codecov.io/gh/skforecast/skforecast-ai/branch/main/graph/badge.svg)](https://codecov.io/gh/skforecast/skforecast-ai) |
| Community | [![!discord](https://img.shields.io/static/v1?logo=discord&label=discord&message=chat&color=lightgreen)](https://discord.gg/3V52qpNkuj) [![!linkedin](https://img.shields.io/static/v1?logo=linkedin&label=LinkedIn&message=news&color=lightblue)](https://www.linkedin.com/company/skforecast/) [![Forecasting Python](https://img.shields.io/static/v1?logo=readme&logoColor=white&label=Blog&labelColor=%23333333&message=Forecasting%20Python&color=%23ffab40)](https://cienciadedatos.net/en/forecasting-python) |


## About skforecast-ai

**The forecasting assistant that shows its work.** Give skforecast-ai a time series: it profiles the data, chooses the model with deterministic rules, validates it and returns the forecast together with the [skforecast](https://skforecast.org) script that produced it. Every decision comes from a rule you can read, the same data always gives the same result, and the script runs on its own with plain skforecast. An optional LLM explains every decision; it never makes them.

<p align="center">
  <img src="https://github.com/skforecast/skforecast-ai/blob/main/docs/img/skforecast-ai-forecast-ask.png?raw=true" alt="skforecast-ai forecast of hourly bike sharing users with its 80% interval, and the ask() answer that explains the evaluation metrics" width="100%">
</p>

<sub>36-hour LightGBM forecast of hourly bike sharing users, with its 80% prediction interval against the held-out hours, and the answer of `ask()` that explains its metrics. Real skforecast-ai outputs, from the animation on [ai.skforecast.org](https://ai.skforecast.org).</sub>


## Installation

```bash
pip install skforecast-ai
```

The LLM layer is optional. To use it, install the extra (`[bedrock]` for AWS Bedrock):

```bash
pip install "skforecast-ai[llm]"
```

Requires Python 3.10 or newer. More options in the [installation guide](https://ai.skforecast.org/stable/quick-start/how-to-install.html); to install from source, see the [Contribution Guide](https://github.com/skforecast/skforecast-ai/blob/main/CONTRIBUTING.md).


## Quick example

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/skforecast/skforecast-ai/blob/main/docs/quick-start/first-forecast.ipynb) Try it without installing anything: [Your first forecast](https://ai.skforecast.org/stable/quick-start/first-forecast.html) runs in Google Colab, from the data to a validated forecast, with no API key.

```python
from skforecast_ai import ForecastingAssistant
from skforecast.datasets import load_demo_dataset

# Download demo dataset (monthly)
data = load_demo_dataset(verbose=False)

# Profile the data, plan the model, generate the script and run it,
# evaluated on the last 12 months. No LLM needed.
assistant = ForecastingAssistant()
result = assistant.forecast(data=data, target="y", steps=12, test_size=12)

result.predictions.head()
#                 pred
# 2007-07-01  0.851486
# 2007-08-01  1.048000
# 2007-09-01  0.998147
# 2007-10-01  1.147577
# 2007-11-01  1.110845

result.metrics
#   series       MAE       MSE      MASE      MAPE
# 0      y  0.078442  0.008933  0.802828  0.088608

print(result.code)  # the skforecast script that produced this result
```

That single call chose a `ForecasterRecursive` with a `Ridge` estimator, its lags and window features, and ran the script that `result.code` returns. `result.profile` and `result.plan` hold every decision and the rule behind it. Drop `test_size` to train on all the data and forecast the next 12 months.

<details>
<summary><b>Same pipeline from the terminal</b></summary>

```bash
# End-to-end forecast
skforecast-ai forecast data.csv --target y --date-column date --steps 12

# Only the standalone script, without running it
skforecast-ai forecast-code data.csv --target y --date-column date --steps 12 --output forecast.py
```

The CLI covers the whole pipeline, including `ask()` and the prompts of `refine_plan()` and `create_cv()`. See [Using the CLI](https://ai.skforecast.org/stable/user-guides/cli-usage.html).

</details>

<details>
<summary><b>Ask why (optional LLM)</b></summary>

```python
# pip install "skforecast-ai[llm]"
assistant = ForecastingAssistant(llm="openai:gpt-5.5")

answer = assistant.ask(
    "Is the MASE good, and why was this estimator chosen?",
    context=result,
)
```

`ask()` reads the object you pass and explains it, grounded in the skforecast agent skills. It never changes the result. The dataset is never sent: a result shares only its own predictions and metrics, with a warning. Providers, credentials and local models are covered in [Configuring the LLM](https://ai.skforecast.org/stable/user-guides/llm-configuration.html).

</details>

<details open>
<summary><b>From your coding agent (MCP server)</b></summary>

In Claude Code, install the server and its skill as a plugin:

```text
/plugin marketplace add skforecast/skforecast-ai
/plugin install skforecast-ai@skforecast-ai
```

Then ask in plain language: *"Forecast the next 12 months of `data/sales.csv` and tell me how accurate it is."* The agent brings the language model and calls skforecast-ai as tools; every decision still comes from the same deterministic rules, every result comes with the script that produced it, and responses never carry rows of your data. The setups for Cursor, VS Code, Codex and Claude Desktop are in [MCP server for coding agents](https://ai.skforecast.org/stable/user-guides/mcp-server.html).

<p align="center">
  <img src="https://github.com/skforecast/skforecast-ai/blob/main/docs/img/agent-session-short.gif?raw=true" alt="A coding agent asked to compare models for the next 12 months of a monthly series calls the skforecast-ai MCP server (profile, plan, create_cv, compare, get_code) and answers with the leaderboard against a seasonal naive baseline and the script of the winner" width="100%">
</p>

<sub>A real Claude Code session with the server and its skill, from the agent check of skforecast-ai 0.4.0, abridged: the first three calls share a row, and an ellipsis marks every cut in a response or in the answer. The <a href="https://github.com/skforecast/skforecast-ai/blob/main/docs/img/agent-session.gif">whole session</a> shows every call, every message of the agent and its complete answer.</sub>

In VS Code, this button adds the server and asks for the directory with your data (it needs [uv](https://docs.astral.sh/uv/)):

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522skforecast-ai%2522%252C%2522command%2522%253A%2522uvx%2522%252C%2522args%2522%253A%255B%2522skforecast-ai-mcp%2522%252C%2522--allow-dir%2522%252C%2522%2524%257Binput%253Aallow_dir%257D%2522%255D%252C%2522inputs%2522%253A%255B%257B%2522type%2522%253A%2522promptString%2522%252C%2522id%2522%253A%2522allow_dir%2522%252C%2522description%2522%253A%2522Absolute%2520path%2520of%2520the%2520directory%2520with%2520your%2520CSV%2520files%2520%2528the%2520server%2520reads%2520only%2520inside%2520it%2529%2522%257D%255D%257D)

</details>


## Features

### A deterministic engine

- **[Data profiling](https://ai.skforecast.org/stable/user-guides/agentic-forecasting-step-by-step.html)**: frequency, missing values, exogenous and categorical variables, and the significant lags from the partial autocorrelation.
- **A plan with a rule for every decision**: forecaster and estimator, lags, window and calendar features, prediction intervals, metric and cross-validation.
- **The code you see is the code that ran**: `forecast()` and `backtest()` execute the same script that `forecast_code()` and `backtest_code()` return. Inspect it, version it or run it with plain skforecast.
- **[Model selection](https://ai.skforecast.org/stable/user-guides/agentic-fore