skforecast-ai 0.1.0

AI-powered forecasting assistant built on top of skforecast.

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.

Table of contents

• Why skforecast-ai?
• Installation
• Quickstart (Python)
• Quickstart (CLI)
• How it works
• Documentation
• Contributing
• Citation
• License

✨ 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.

Read more in Introduction to agentic forecasting.

📚 Documentation

Explore the full capabilities of skforecast-ai with our comprehensive documentation:

:books: https://ai.skforecast.org

Documentation
:rocket: Quick start	Get started quickly with skforecast
:book: Introduction to agentic forecasting	Basics of forecasting concepts and methodologies
:books: API Reference	Comprehensive reference for skforecast functions and classes
:memo: Releases	Keep track of major updates and changes
:mag: More	Discover more about skforecast and its creators

🤝 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 (v0.23.0). Zenodo. https://doi.org/10.5281/zenodo.8382787

APA:

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

BibTeX:

@software{skforecast,
  author  = {Amat Rodrigo, Joaquin and Escobar Ortiz, Javier},
  title   = {skforecast},
  url     = {https://skforecast.org/},
  doi     = {10.5281/zenodo.8382787}
}

View the citation file.

📄 License

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

Built with ❤️ on top of skforecast.