Skip to content

Welcome to skforecast-ai

Python PyPI Build status Project Status: Active PyPI Downloads Downloads License paypal buymeacoffee GitHub Sponsors Open Collective !linkedin !discord Forecasting Python Skforecast Studio

skforecast-ai is an AI forecasting assistant that pairs a deterministic engine, powered by skforecast, with an LLM reasoning layer. Simply provide a time series, and the assistant automatically profiles the data, selects a model using established best practices, and evaluates its performance. It returns both the final forecast and the runnable skforecast script that produced it.

✨ Why skforecast-ai?

  • 🎯 Deterministic by design: built as a strict rule-based engine to guarantee absolute consistency, same input always means the same output.
  • 🔍 Code you can inspect: the script you see is the code that ran. Inspect it, version it, or run it standalone with plain skforecast.
  • ⚡ From data to forecast in one call: automatic data profiling, model and estimator selection, lag/feature engineering, and backtest evaluation.
  • 💻 Python or terminal: drive the full pipeline from a few lines of Python or from the command line.
  • 💬 LLM reasoning layer: explains the engine's decisions in plain language, helps you improve the configuration, and lets you ask for advice. This layer is entirely optional; the core forecasting pipeline can run fully offline.
  • 🏗️ Built on skforecast: recursive & direct forecasters, multi-series, statistical, and foundation models (Chronos-2, TimesFM, Moirai, and more).

📦 Installation

Requires Python ≥ 3.10.

pip install skforecast-ai

To enable the optional LLM reasoning layer:

pip install "skforecast-ai[llm]"
Install from source (for development) 
git clone https://github.com/skforecast/skforecast-ai.git
cd skforecast-ai
pip install -e ".[dev]"

🚀 Quickstart (Python)

From raw data to a validated forecast, and the code behind it, in a few lines:

import pandas as pd
from skforecast_ai import ForecastingAssistant
from skforecast.datasets import load_demo_dataset

data = load_demo_dataset(verbose=False)
assistant = ForecastingAssistant()
result = assistant.forecast(data=data, target="y", steps=12)

print(result.predictions)   # forecast for the next 12 steps
print(result.metrics)       # evaluation metrics: MAE, MSE, MASE...
print(result.code)          # the exact skforecast script that produced this result

That single forecast() call profiled the data, chose a forecaster and estimator, generated a skforecast script, and executed it. result.code is the script that ran.

The returned ForecastResult exposes everything the pipeline produced:

Attribute What it holds
result.predictions Forecast for the requested horizon (includes interval columns when interval is requested)
result.metrics Backtest evaluation metrics (MAE, MSE, MASE)
result.code The runnable skforecast script that produced the result
result.profile What profiling detected about your data
result.plan The forecaster, estimator, lags, and metrics that were chosen

👉 New here? Walk through it step by step in Your first forecast.

💻 Quickstart (CLI)

The same pipeline runs from the terminal. Point it at a CSV file or URL:

# End-to-end forecast (profile → plan → code → forecast)
skforecast-ai forecast data.csv --target y --date-column datetime --steps 12

# Just inspect the data
skforecast-ai profile data.csv --target y --date-column datetime

# Generate a standalone, runnable script without executing it
skforecast-ai forecast-code data.csv --target y --date-column datetime --steps 12 --output forecast.py

Run skforecast-ai --help or skforecast-ai <command> --help for inline documentation on any command.

👉 Full command reference in CLI usage.

🧠 How it works

skforecast-ai supports two distinct workflows using the same underlying forecasting engine:

  • The Fast Path: Use this when you want a forecast or backtest result in a single call. The assistant profiles the data, builds the modeling plan, executes the workflow, and returns the results alongside the reproducible skforecast code.

  • The Step-by-Step Path: Use this when you want granular control to inspect or adjust intermediate decisions. You can manually create a profile, build a plan, optionally refine it with the LLM, define a validation strategy, evaluate the model, and then generate the forecast.

A useful mental model is that forecasting and validation are separate branches. Once you have a profile and a plan, you can use forecast() to produce future predictions directly, or backtest() to evaluate the model's performance on historical data.

The ask() method is available in both workflows. It can explain a profile, plan, validation setup, backtest result, or answer general forecasting questions, but it will never execute the workflow or modify your parameters without explicit instruction.

Fast path: one call

Profiling, planning and execution happen internally.

data
↓
Forecast
forecast()
or forecast_code()
↓
predictions + code
Backtesting (validation)
create_cv()
Deterministic, Agentic mode
or pass a skforecast TimeSeriesFold object
↓
backtest()
or backtest_code()
↓
metrics + predictions + code
Step-by-step path: full control

Build a profile and a plan from your data, then branch into forecasting and backtesting.

data
↓
profile()
↓
plan()
refine_plan(), optional (Deterministic or Agentic mode)
↓
Forecast
forecast()
or forecast_code()
↓
predictions + code
Backtesting (validation)
create_cv()
Deterministic, Agentic mode
or pass a skforecast TimeSeriesFold object
↓
backtest()
or backtest_code()
↓
metrics + predictions + code
LLM reasoning: available at any moment, in any workflow
Call ask() before, during or after either path. It can take a profile, a plan, a forecast_result, a backtest_result, or nothing at all (pure Q&A).

Read more in Agentic Forecasting.

🤝 Contributing

Contributions are welcome, whether it's a bug report, a feature idea, or a pull request. Please see the Contributing Guide and our Code of Conduct to get started.

📖 Citation

If you use skforecast-ai in your work, please cite the underlying skforecast library:

Zenodo

Amat Rodrigo, Joaquin, & Escobar Ortiz, Javier. (2026). skforecast-ai (Version 0.1.0). Zenodo. https://doi.org/10.5281/zenodo.21338159

APA

Amat Rodrigo, J., & Escobar Ortiz, J. (2026). skforecast-ai (Version 0.1.0) [Computer software]. https://doi.org/10.5281/zenodo.21338159

BibTeX

@software{skforecast-ai,
  author  = {Amat Rodrigo, Joaquin and Escobar Ortiz, Javier},
  title   = {skforecast-ai},
  version = {0.1.0},
  month   = {7},
  year    = {2026},
  license = {Apache-2.0},
  url     = {https://ai.skforecast.org/},
  doi     = {10.5281/zenodo.21338159}
}

View the citation file.

📄 License

Licensed under the Apache License 2.0 (see LICENSE for details).

Built with ❤️ on top of skforecast.