Skip to content

skygazer42/ForeSight

BranchesTags

Repository files navigation

A lightweight, batteries-included time-series forecasting toolkit for Python.

Unified model registry • Walk-forward backtesting • Probabilistic forecasting • CLI + Python API

PyPI Python License GitHub stars Last commit


Installation · Quick Start · Model Zoo · Architecture · Docs · Contributing


  250+ models · 7 backends · 20+ metrics · 1 unified interface

Highlights

🧠 250+ Models, One Interface

Statistical, ML, and deep learning models all share the same forecaster(train, horizon) → ŷ contract. From naive baselines to Transformers and Mamba — unified under one API.

🔄 Backtesting-First Design

Walk-forward evaluation with expanding or rolling windows, full cross-validation predictions table, per-step metrics, and conformal prediction intervals — all built in.

📊 Panel & Global Models

First-class multi-series support via unique_id / ds / y long format. Global models train across thousands of series with covariate-aware feature engineering.

⚡ Minimal by Default

Core depends only on numpy + pandas. Heavy backends (PyTorch, XGBoost, LightGBM, CatBoost, statsmodels, scikit-learn) are all opt-in extras.

📐 Probabilistic Forecasting

Quantile regression, conformal intervals, bootstrap intervals, CRPS, pinball loss — production-ready uncertainty quantification across all model families.

🏭 Production-Friendly

fit / predict object API, model artifact save/load with schema versioning, hierarchical reconciliation, grid-search tuning, and a full-featured CLI.

Design inspired by StatsForecast · Darts · sktime · NeuralForecast · Prophet

Support Contract

ForeSight exposes a broad model catalog, but the stable public surface is narrower than the full implementation footprint.

  • The stable public surface is the root foresight Python API documented in docs/api.md, the model registry metadata surfaced by foresight models list/info, the artifact schema/load contract, and the documented core CLI workflows such as doctor, models, forecast, eval, leaderboard, and artifact.
  • Default docs, examples, and release checks target the stable public surface first. Beta and experimental model families remain available, but they are not held to the same compatibility promise as the stable core workflows.
  • The current CI-backed support matrix is: Python 3.10 and 3.11 for the core install and contract checks; Python 3.10 for release packaging and artifact smoke; Python 3.10 smoke coverage for the stats and ml extras.
  • Torch, transformers, foundation wrappers, and frontier paper-zoo style models remain available, but their maturity level is communicated through stable, beta, and experimental rather than a blanket platform guarantee.

See Compatibility guide for the detailed support policy.

⚙️ How It Works

ForeSight Pipeline 

graph LR
    A["📊 Raw Data<br/><small>CSV / DataFrame</small>"] --> B["🔧 Prepare<br/><small>to_long · validate</small>"]
    B --> C["🧠 Model<br/><small>250+ choices</small>"]
    C --> D["🔄 Backtest<br/><small>walk-forward CV</small>"]
    D --> E["📈 Metrics<br/><small>MAE · CRPS · ...</small>"]
    C --> F["🚀 Forecast<br/><small>point + intervals</small>"]
    F --> G["💾 Artifacts<br/><small>save · load · deploy</small>"]

    style A fill:#fef3c7,stroke:#fbbf24,color:#92400e
    style B fill:#fef3c7,stroke:#fbbf24,color:#92400e
    style C fill:#dbeafe,stroke:#3b82f6,color:#1e40af
    style D fill:#d1fae5,stroke:#10b981,color:#065f46
    style E fill:#fce7f3,stroke:#ec4899,color:#9d174d
    style F fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style G fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
Loading

📦 Installation

pip install foresight-ts                # core (numpy + pandas only)

Install optional backends as needed:

pip install "foresight-ts[ml]"          # scikit-learn models
pip install "foresight-ts[xgb]"         # XGBoost models
pip install "foresight-ts[lgbm]"        # LightGBM models
pip install "foresight-ts[catboost]"    # CatBoost models
pip install "foresight-ts[stats]"       # statsmodels (ARIMA, ETS, VAR, …)
pip install "foresight-ts[torch]"       # PyTorch neural models
pip install "foresight-ts[sktime]"      # sktime adapter bridge
pip install "foresight-ts[darts]"       # Darts data adapter bridge
pip install "foresight-ts[gluonts]"     # GluonTS data adapter bridge
pip install "foresight-ts[all]"         # everything above

Check the active environment, optional dependencies, and dataset resolution:

foresight doctor
foresight --data-dir /path/to/root doctor
foresight doctor --format text
foresight --data-dir /path/to/root doctor --format text --strict
foresight doctor --require-extra torch --strict
Install from source (for development) 
git clone https://github.com/skygazer42/ForeSight.git
cd ForeSight
pip install -e ".[dev]"     # editable install + pytest, ruff, mypy

🚀 Quick Start

Python API

from foresight import eval_model, make_forecaster, make_forecaster_object

# 1️⃣ Walk-forward evaluation on a built-in dataset
metrics = eval_model(
    model="theta", dataset="catfish", y_col="Total",
    horizon=3, step=3, min_train_size=12,
)
print(metrics)  # {'mae': ..., 'rmse': ..., 'mape': ..., 'smape': ...}

# 2️⃣ Functional API — stateless forecaster
f = make_forecaster("holt", alpha=0.3, beta=0.1)
yhat = f([112, 118, 132, 129, 121, 135, 148, 148], horizon=3)

# 3️⃣ Object API — fit / predict / save / load
obj = make_forecaster_object("moving-average", window=3)
obj.fit([1, 2, 3, 4, 5, 6])
yhat = obj.predict(3)

Beta Adapters

ForeSight now exposes beta integration adapters through the named foresight.adapters module rather than the stable root package surface.

from foresight.adapters import (
    make_sktime_forecaster_adapter,
    to_darts_timeseries,
    from_darts_timeseries,
    to_gluonts_list_dataset,
)
  • make_sktime_forecaster_adapter(...) bridges local point forecaster objects into a minimal sktime-style fit/predict interface.
  • to_darts_timeseries(...) / from_darts_timeseries(...) convert between ForeSight single-series or panel data and Darts TimeSeries objects.
  • to_gluonts_list_dataset(...) converts canonical long-format history into a GluonTS ListDataset.

These adapters are intentionally beta and are not part of the root foresight.__all__ contract yet.

CLI

# Discover models and datasets
foresight models list                     # list all 250+ models
foresight models info theta               # inspect parameters & defaults
foresight models list --stability stable  # filter by maturity level
foresight models list --capability supports_x_cols=true --format json
foresight datasets list                   # browse built-in datasets
foresight doctor                          # inspect optional deps and data paths
foresight doctor --format text            # human-readable environment summary
foresight doctor --require-extra torch --strict

# Evaluate a model
foresight eval run --model theta --dataset catfish --y-col Total \
    --horizon 3 --step 3 --min-train-size 12

# Compare models on a leaderboard
foresight leaderboard models --dataset catfish --y-col Total \
    --horizon 3 --step 3 --min-train-size 12 \
    --models naive-last,seasonal-naive,theta,holt

# Forecast from any CSV
foresight forecast csv --model naive-last --path ./data.csv \
    --time-col ds --y-col y --parse-dates --horizon 7

# Cross-validation from any CSV
foresight cv csv --model naive-last --path ./data.csv \
    --time-col ds --y-col y --parse-dates \
    --horizon 3 --step-size 1 --min-train-size 24

# Detect anomalies from any CSV
foresight detect csv --path ./anomaly.csv \
    --time-col ds --y-col y --parse-dates \
    --score-method rolling-zscore --threshold-method zscore

Long-running CLI commands emit enhanced runtime logs to stderr by default, so stdout stays clean for JSON / CSV piping and file redirects.

More Python API examples (intervals, tuning, global models, hierarchical) 
import pandas as pd
from foresight import (
    bootstrap_intervals,
    detect_anomalies,
    eval_hierarchical_forecast_df,
    forecast_model, tune_model, save_forecaster, load_forecaster,
    make_forecaster_object,
    make_global_forecaster, make_multivariate_forecaster,
    build_hierarchy_spec, reconcile_hierarchical_forecasts,
)

# Forecast with bootstrap prediction intervals
future_df = forecast_model(
    model="naive-last",
    y=[1, 2, 3, 4, 5, 6],
    ds=pd.date_range("2024-01-01", periods=6, freq="D"),
    horizon=3,
    interval_levels=(0.8, 0.9),
    interval_min_train_size=4,
)

# Save / load trained model artifacts
obj = make_forecaster_object("theta", alpha=0.3)
obj.fit([1, 2, 3, 4, 5])
save_forecaster(obj, "/tmp/theta.pkl")
loaded = load_forecaster("/tmp/theta.pkl")

# Detect anomalies from a dataset-backed series
anomalies = detect_anomalies(
    dataset="catfish",
    y_col="Total",
    model="naive-last",
    score_method="forecast-residual",
    min_train_size=24,
    step_size=1,
)

# Grid search tuning
result = tune_model(
    model="moving-average", dataset="catfish", y_col="Total",
    horizon=1, step=1, min_train_size=24, max_windows=8,
    search_space={"window": (1, 3, 6)},
)

# Multivariate model (VAR)
mv = make_multivariate_forecaster("var", maxlags=1)
yhat_mv = mv(wide_df[["sales", "traffic"]], horizon=2)

# Hierarchical reconciliation
hierarchy = build_hierarchy_spec(raw_df, id_cols=("region", "store"), root="total")
reconciled = reconcile_hierarchical_forecasts(
    forecast_df=pred_df, hierarchy=hierarchy,
    method="top_down", history_df=history_long,
)
hier_payload = eval_hierarchical_forecast_df(
    forecast_df=reconciled,
    hierarchy=hierarchy,
    y_col="y",
)
More CLI examples (artifacts, covariates, sweep) 
# Forecast with prediction intervals
foresight forecast csv --model naive-last --path ./my.csv \
    --time-col ds --y-col y --parse-dates --horizon 3 \
    --interval-levels 80,90 --interval-min-train-size 12

# Enhanced runtime logs go to stderr; stdout remains pipe-safe
foresight forecast csv --model torch-mlp-direct --path ./train.csv \
    --time-col ds --y-col y --parse-dates --horizon 3 \
    --model-param lags=24 --model-param epochs=10 \
    --format json > /tmp/forecast.json

# Reduce per-epoch chatter or persist structured event logs
foresight eval run --model theta --dataset catfish --y-col Total \
    --horizon 3 --step 3 --min-train-size 12 \
    --no-progress --log-style plain --log-file /tmp/eval-log.jsonl

# Save and reuse model artifacts
foresight forecast csv --model naive-last --path ./my.csv \
    --time-col ds --y-col y --parse-dates --horizon 3 \
    --save-artifact /tmp/naive-last.pkl
foresight forecast artifact --artifact /tmp/naive-last.pkl --horizon 3

# Save and reuse a local x_cols artifact with the saved future covariates
foresight forecast csv --model sarimax --path ./my_exog.csv \
    --time-col ds --y-col y --parse-dates --horizon 3 \
    --model-param order=0,0,0 --model-param seasonal_order=0,0,0,0 \
    --model-param trend=c --model-param x_cols=promo \
    --save-artifact /tmp/sarimax.pkl
foresight forecast artifact --artifact /tmp/sarimax.pkl --horizon 2

# Override the saved future covariates with a new future CSV
foresight forecast artifact --artifact /tmp/sarimax.pkl \
    --future-path ./my_exog_future.csv --time-col ds --parse-dates \
    --horizon 4

# Reuse a quantile-capable global artifact and derive interval columns
foresight forecast artifact --artifact /tmp/xgb-global.pkl \
    --horizon 2 --interval-levels 80

# Override a saved global artifact with new future covariates
# The override CSV can contain canonical unique_id values or the raw id columns
# that were used when the artifact was saved, plus ds and required x_cols.
# Single-series global artifacts can also omit id columns entirely.
foresight forecast artifact --artifact /tmp/ridge-global.pkl \
    --future-path ./my_global_future.csv --time-col ds --parse-dates \
    --horizon 2

foresight artifact info --artifact /tmp/naive-last.pkl
foresight artifact info --artifact /tmp/naive-last.pkl --format markdown
foresight artifact validate --artifact /tmp/naive-last.pkl
foresight artifact diff \
    --left-artifact /tmp/naive-last.pkl \
    --right-artifact /tmp/naive-last-v2.pkl \
    --path-prefix metadata.train_schema.runtime --format csv
foresight artifact diff \
    --left-artifact /tmp/naive-last.pkl \
    --right-artifact /tmp/naive-last-v2.pkl \
    --path-prefix tracking_summary --format csv
foresight artifact diff \
    --left-artifact /tmp/naive-last.pkl \
    --right-artifact /tmp/naive-last-v2.pkl \
    --path-prefix future_override_schema --format markdown

# SARIMAX with exogenous features
foresight forecast csv --model sarimax --path ./my_exog.csv \
    --time-col ds --y-col y --parse-dates --horizon 3 \
    --model-param order=0,0,0 --model-param x_cols=promo

# Anomaly detection with exogenous covariates
foresight detect csv --model sarimax --path ./my_exog.csv \
    --time-col ds --y-col y --parse-dates \
    --score-method forecast-residual --threshold-method mad \
    --min-train-size 24 --model-param order=0,0,0 \
    --model-param seasonal_order=0,0,0,0 \
    --model-param trend=c --model-param x_cols=promo

# Multi-dataset sweep (parallel + resumable)
foresight leaderboard sweep \
    --datasets catfish,ice_cream_interest \
    --models naive-last,theta --horizon 3 --step 3 \
    --min-train-size 12 --jobs 4 --progress

# Conformal prediction intervals
foresight eval run --model theta --dataset catfish --y-col Total \
    --horizon 3 --step 3 --min-train-size 12 --conformal-levels 80,90

# Cross-validation predictions table
foresight cv run --model theta --dataset catfish --y-col Total \
    --horizon 3 --step-size 3 --min-train-size 12 --n-windows 30

# Cross-validation on arbitrary CSV data
foresight cv csv --model sarimax --path ./my_exog.csv \
    --time-col ds --y-col y --parse-dates \
    --horizon 3 --step-size 3 --min-train-size 24 \
    --model-param order=0,0,0 \
    --model-param seasonal_order=0,0,0,0 \
    --model-param trend=c --model-param x_cols=promo \
    --format json > /tmp/cv.json

🧠 Model Zoo

ForeSight organizes 250+ registered models into families. Core models are dependency-free; optional models activate with the corresponding extra.

Model Landscape

mindmap
  root((ForeSight<br/>250+ Models))
    Statistical
      Naive & Baseline
        naive-last
        seasonal-naive
        drift
        moving-average
      Exponential Smoothing
        SES / Holt / Holt-Winters
      Theta
        theta / theta-auto
      Fourier & Spectral
        fourier / FFT
      Kalman Filter
      Intermittent Demand
        Croston / TSB / ADIDA
    Machine Learning
      scikit-learn
        Ridge / RF / GBR
        20+ lag regressors
      XGBoost
        Direct / Recursive / DirRec / MIMO
        Custom objectives
      LightGBM
      CatBoost
    Deep Learning
      MLP & Linear
        NLinear / DLinear / TiDE
      RNN
        LSTM / GRU / DeepAR
      CNN
        TCN / WaveNet / SCINet
      Transformer
        PatchTST / Informer / Autoformer
        TFT / iTransformer / FEDformer
      SSM
        Mamba / RWKV / Hyena
      Residual Blocks
        N-BEATS / N-HiTS
    Global & Panel
      sklearn global
      XGB / LGBM / CatBoost global
      Torch global
        TFT / Informer / TimesNet
    Multivariate
      VAR
    Ensemble
      Mean / Median / Pipeline
Loading

Core Models (no extra dependencies)

Family Models Key Parameters
Naive / Baseline naive-last, seasonal-naive, mean, median, drift, moving-average, weighted-moving-average, moving-median, seasonal-mean, seasonal-drift season_length, window
Exponential Smoothing ses, ses-auto, holt, holt-auto, holt-damped, holt-winters-add, holt-winters-add-auto alpha, beta, gamma, season_length
Theta theta, theta-auto alpha, grid_size
AR / Regression ar-ols, ar-ols-lags, sar-ols, ar-ols-auto, lr-lag, lr-lag-direct p, lags, season_length
Fourier / Spectral fourier, fourier-multi, poly-trend, fft period, order, top_k
Kalman Filter kalman-level, kalman-trend process_variance, obs_variance
Intermittent Demand croston, croston-sba, croston-sbj, croston-opt, tsb, les, adida alpha, beta
Meta / Ensemble pipeline, ensemble-mean, ensemble-median base, members, transforms

Optional Models

scikit-learn — pip install "foresight-ts[ml]"

Local (lag-feature + direct multi-horizon):

ridge-lag, ridge-lag-direct, rf-lag, decision-tree-lag, extra-trees-lag, adaboost-lag, bagging-lag, lasso-lag, elasticnet-lag, knn-lag, gbrt-lag, hgb-lag, svr-lag, linear-svr-lag, kernel-ridge-lag, mlp-lag, huber-lag, quantile-lag, sgd-lag

Global/panel (step-lag, trains across all series):

ridge-step-lag-global, rf-step-lag-global, extra-trees-step-lag-global, gbrt-step-lag-global, decision-tree-step-lag-global, bagging-step-lag-global, lasso-step-lag-global, elasticnet-step-lag-global, knn-step-lag-global, svr-step-lag-global, mlp-step-lag-global, and more

XGBoost — pip install "foresight-ts[xgb]"
Strategy Models
Direct xgb-lag, xgb-dart-lag, xgbrf-lag, xgb-linear-lag
Recursive xgb-lag-recursive, xgb-dart-lag-recursive, xgb-linear-lag-recursive
Step-index xgb-step-lag
DirRec xgb-dirrec-lag
MIMO xgb-mimo-lag
Custom objectives xgb-mae-lag, xgb-huber-lag, xgb-quantile-lag, xgb-poisson-lag, xgb-gamma-lag, ...
Global/panel xgb-step-lag-global (supports quantile output)
LightGBM — pip install "foresight-ts[lgbm]"

Local: lgbm-lag, lgbm-lag-recursive, lgbm-step-lag, lgbm-dirrec-lag, lgbm-custom-lag

Global/panel: lgbm-step-lag-global (supports quantile output)

CatBoost — pip install "foresight-ts[catboost]"

Local: catboost-lag, catboost-lag-recursive, catboost-step-lag, catboost-dirrec-lag

Global/panel: catboost-step-lag-global (supports quantile output)

statsmodels — pip install "foresight-ts[stats]"
Family Models
ARIMA arima, auto-arima, sarimax, autoreg
Fourier Hybrid fourier-arima, fourier-auto-arima, fourier-autoreg, fourier-sarimax
Decomposition stl-arima, stl-autoreg, stl-ets, mstl-arima, mstl-autoreg, mstl-ets, mstl-auto-arima
TBATS-lite tbats-lite, tbats-lite-autoreg, tbats-lite-auto-arima
Unobserved Components uc-local-level, uc-local-linear-trend, uc-seasonal
ETS ets
Multivariate var
PyTorch — Local models — pip install "foresight-ts[torch]"
Category Models
MLP / Linear torch-mlp-direct, torch-nlinear-direct, torch-dlinear-direct, torch-tide-direct, torch-kan-direct
RNN torch-lstm-direct, torch-gru-direct, torch-bilstm-direct, torch-bigru-direct, torch-attn-gru-direct
CNN torch-cnn-direct, torch-tcn-direct, torch-resnet1d-direct, torch-wavenet-direct, torch-inception-direct, torch-scinet-direct
Transformer torch-transformer-direct, torch-patchtst-direct, torch-crossformer-direct, torch-pyraformer-direct, torch-fnet-direct, torch-tsmixer-direct, torch-retnet-direct
Residual Blocks torch-nbeats-direct, torch-nhits-direct
SSM / State-space torch-mamba-direct, torch-rwkv-direct, torch-hyena-direct
Hybrid torch-etsformer-direct, torch-esrnn-direct, torch-lstnet-direct
Probabilistic torch-deepar-recursive, torch-qrnn-recursive
RNN Paper Zoo 100 named paper architectures (torch-rnnpaper-*-direct)
RNN Zoo 100 combos: 20 bases × 5 wrappers (torch-rnnzoo-*-direct)
Configurable Transformer torch-xformer-*-direct — 10 attention variants × positional encodings × extras
PyTorch — Global/panel models — pip install "foresight-ts[torch]"

Train across all series in long-format; supports covariates (x_cols), time features, and optional quantile regression.

Category Models
Transformer torch-tft-global, torch-informer-global, torch-autoformer-global, torch-fedformer-global, torch-patchtst-global, torch-itransformer-global, torch-timesnet-global, torch-tsmixer-global
MLP / Linear torch-nbeats-global, torch-nhits-global, torch-nlinear-global, torch-dlinear-global, torch-tide-global
RNN torch-deepar-global, torch-lstnet-global, torch-esrnn-global
CNN torch-tcn-global, torch-wavenet-global, torch-scinet-global
SSM torch-mamba-global, torch-rwkv-global, torch-hyena-global

Multi-horizon Strategies

graph LR
    subgraph strategies ["Multi-horizon Forecasting Strategies"]
        direction TB
        D["<b>Direct</b><br/><small>One model per step</small>"]
        R["<b>Recursive</b><br/><small>One-step, re-fed iteratively</small>"]
        S["<b>Step-index</b><br/><small>Single model, step as feature</small>"]
        DR["<b>DirRec</b><br/><small>Per-step + prev-step features</small>"]
        M["<b>MIMO</b><br/><small>Single model → full horizon</small>"]
    end

    style D fill:#dbeafe,stroke:#3b82f6,color:#1e40af
    style R fill:#d1fae5,stroke:#10b981,color:#065f46
    style S fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style DR fill:#fce7f3,stroke:#ec4899,color:#9d174d
    style M fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
Loading
Strategy How it works Suffix
Direct One model per horizon step *-lag
Recursive One-step model, iteratively re-fed *-lag-recursive
Step-index Single model with step as a feature *-step-lag
DirRec Per-step model with previous-step features *-dirrec-lag
MIMO Single model predicts entire horizon *-mimo-lag

🏗️ Architecture

ForeSight Architecture 

graph TB
    subgraph surface ["User Surface"]
        API["Python API<br/><small>eval_model · make_forecaster</small>"]
        CLI["CLI<br/><small>foresight eval · forecast · cv</small>"]
        OOP["OOP Interface<br/><small>fit · predict · save · load</small>"]
    end

    subgraph facades ["Facades"]
        FC["forecast.py"]
        EV["eval_forecast.py"]
        TN["tuning.py"]
        CV["cv.py"]
        HR["hierarchical.py"]
    end

    subgraph services ["Services"]
        FS["Forecasting Service"]
        ES["Evaluation Service"]
    end

    subgraph models ["Model Registry (250+)"]
        CAT["Catalog<br/><small>classical · ml · stats<br/>torch_local · torch_global</small>"]
        FAC["Factories"]
        RUN["Runtime"]
    end

    subgraph contracts ["Contracts"]
        VAL["Validation"]
        NORM["Normalization"]
        CAP["Capability Checks"]
    end

    subgraph data ["Data Layer"]
        LONG["Long Format I/O"]
        FEAT["Feature Engineering"]
        TRANS["Transforms"]
        DS["Datasets"]
    end

    surface --> facades
    facades --> services
    services --> models
    services --> contracts
    models --> contracts
    services --> data

    style surface fill:#ede9fe,stroke:#8b5cf6
    style facades fill:#f5f3ff,stroke:#c4b5fd
    style services fill:#d1fae5,stroke:#6ee7b7
    style models fill:#dbeafe,stroke:#93c5fd
    style contracts fill:#fef3c7,stroke:#fcd34d
    style data fill:#fef3c7,stroke:#fbbf24
Loading

📐 Data Format

ForeSight uses a panel-friendly long format compatible with StatsForecast and Prophet:

Column Description
unique_id Series identifier (optional for single series)
ds Timestamp (datetime)
y Target value (float)
extra columns Covariates / exogenous features

Covariate Roles

graph LR
    subgraph covariates ["Covariate System"]
        Y["<b>y</b><br/>Forecast target"]
        HX["<b>historic_x_cols</b><br/>Observed up to cutoff"]
        FX["<b>future_x_cols</b><br/>Known through horizon"]
        XC["<b>x_cols</b><br/>Alias for future_x_cols"]
    end

    style Y fill:#fce7f3,stroke:#ec4899,color:#9d174d
    style HX fill:#dbeafe,stroke:#3b82f6,color:#1e40af
    style FX fill:#d1fae5,stroke:#10b981,color:#065f46
    style XC fill:#f5f3ff,stroke:#c4b5fd,color:#6d28d9
Loading 
from foresight.data import to_long, prepare_long_df

long_df = to_long(
    raw_df, time_col="ds", y_col="y",
    id_cols=("store", "dept"),
    historic_x_cols=("promo_hist",),
    future_x_cols=("promo_plan", "price"),
)

prepared = prepare_long_df(
    long_df, freq="D",
    y_missing="interpolate",
    historic_x_missing="ffill",
    future_x_missing="ffill",
)

📊 Evaluation & Backtesting

Capabilities

graph TB
    subgraph eval ["Evaluation Toolkit"]
        direction LR
        BT["🔄 Walk-forward<br/>Backtesting"]
        CVT["📋 Cross-validation<br/>Table"]
        LB["🏆 Leaderboard<br/>Comparison"]
        SW["🌐 Multi-dataset<br/>Sweep"]
        TU["🎯 Grid Search<br/>Tuning"]
        CI["📐 Conformal<br/>Intervals"]
        BI["📊 Bootstrap<br/>Intervals"]
    end

    style BT fill:#d1fae5,stroke:#10b981,color:#065f46
    style CVT fill:#dbeafe,stroke:#3b82f6,color:#1e40af
    style LB fill:#fef3c7,stroke:#f59e0b,color:#92400e
    style SW fill:#fce7f3,stroke:#ec4899,color:#9d174d
    style TU fill:#ede9fe,stroke:#8b5cf6,color:#5b21b6
    style CI fill:#d1fae5,stroke:#10b981,color:#065f46
    style BI fill:#dbeafe,stroke:#3b82f6,color:#1e40af
Loading
Capability Description
Walk-forward backtesting Expanding or rolling-window evaluation (horizon, step, min_train_size, max_train_size)
Cross-validation table Full predictions DataFrame: unique_id, ds, cutoff, step, y, yhat, model
Leaderboard Multi-model comparison on a single dataset
Sweep Multi-dataset × multi-model benchmark with parallel workers + resume
Tuning Grid search over model parameters, scored via backtesting
Conformal intervals Symmetric prediction intervals from backtesting residuals
Bootstrap intervals Non-parametric prediction intervals

Metrics

Point Metrics MAE · RMSE · MAPE · sMAPE · WAPE · MASE · RMSSE · MSE
Probabilistic Metrics Pinball loss · CRPS · Coverage · Width · Sharpness · Interval Score · Winkler Score · Weighted Interval Score · MSIS

Probabilistic Forecasting

# Quantile regression with Torch global models
foresight eval run --model torch-itransformer-global \
    --dataset catfish --y-col Total --horizon 7 --step 7 --min-train-size 60 \
    --model-param quantiles=0.1,0.5,0.9

Produces yhat_p10, yhat_p50, yhat_p90 columns alongside yhat (defaults to median quantile).

📦 Optional Dependencies

Extra Backend Version Example Models
[ml] scikit-learn ≥ 1.0 ridge-lag, rf-lag, hgb-lag, mlp-lag, *-step-lag-global
[xgb] XGBoost ≥ 2.0 xgb-lag, xgb-step-lag, xgb-mimo-lag, xgb-step-lag-global
[lgbm] LightGBM ≥ 4.0 lgbm-lag, lgbm-step-lag-global
[catboost] CatBoost ≥ 1.2 catboost-lag, catboost-step-lag-global
[stats] statsmodels ≥ 0.14 arima, auto-arima, sarimax, ets, var, stl-*, mstl-*
[torch] PyTorch ≥ 2.0 torch-transformer-direct, torch-tft-global, torch-mamba-global
[all] All of the above — —

🗂️ Repository Structure

ForeSight/
├── src/foresight/              # Main Python package
│   ├── models/                 #   Model registry, catalog, factories
│   │   ├── catalog/            #     Model metadata shards
│   │   ├── factories.py        #     Runtime construction
│   │   └── registry.py         #     Public model facade
│   ├── services/               #   Forecast & evaluation orchestration
│   ├── contracts/              #   Validation & capability checks
│   ├── data/                   #   Long-format I/O & preprocessing
│   ├── datasets/               #   Built-in dataset registry
│   ├── features/               #   Feature engineering
│   ├── cli.py                  #   CLI entry point
│   ├── base.py                 #   BaseForecaster classes
│   ├── backtesting.py          #   Walk-forward engine
│   ├── metrics.py              #   20+ evaluation metrics
│   ├── conformal.py            #   Conformal prediction intervals
│   ├── hierarchical.py         #   Hierarchical reconciliation
│   └── transforms.py           #   Data transformations
├── examples/                   # Runnable example scripts
├── data/                       # Bundled CSV datasets
├── benchmarks/                 # Reproducible benchmark harness
├── tests/                      # 150+ test files
├── docs/                       # MkDocs documentation
└── tools/                      # Dev & release utilities

Example scripts: quickstart_eval.py · leaderboard.py · cv_and_conformal.py · intermittent_demand.py · torch_global_models.py · rnn_paper_zoo.py

🔬 Model Capability Flags

Model discovery surfaces machine-readable capability flags:

Flag Meaning
supports_panel Supports panel / multi-series workflows through the high-level long-format APIs
supports_univariate Supports univariate forecasting targets
supports_multivariate Supports multivariate / wide-matrix forecasting targets
supports_probabilistic Supports probabilistic forecasting through intervals and/or quantiles
supports_conformal_eval Can participate in conformal backtest evaluation flows
supports_future_covariates Accepts known future covariates in supported workflows
supports_historic_covariates Accepts historical covariate values in supported workflows
supports_static_covariates Accepts series-level static covariates
supports_refit_free_cv Can reuse training state across CV cutoffs without refitting from scratch
supports_x_cols Accepts future covariates / exogenous regressors
supports_static_cols Accepts series-level static covariates from long_df
supports_quantiles Emits quantile forecast columns directly
supports_interval_forecast Supports forecast intervals
supports_interval_forecast_with_x_cols Supports forecast intervals when future covariates are provided
supports_artifact_save Can be saved and reused through the artifact workflow
requires_future_covariates Requires known future covariates 
foresight models info holt-winters-add    # see all flags & defaults

🧪 Benchmarks

ForeSight ships a reproducible benchmark harness for packaged datasets:

python benchmarks/run_benchmarks.py --smoke          # CI smoke run
python benchmarks/run_benchmarks.py --config baseline --format md

🤝 Contributing

We welcome contributions! Here's how to get started:

git clone https://github.com/skygazer42/ForeSight.git
cd ForeSight
pip install -e ".[dev]"

ruff check src tests tools    # lint
ruff format src tests tools   # format
pytest -q                     # test

See docs/DEVELOPMENT.md for detailed guidelines and docs/ARCHITECTURE.md for the layered design.

🔗 Related Projects

ForeSight draws design inspiration from these excellent projects:

Project Highlights
StatsForecast Fast statistical baselines, unique_id/ds/y convention, cross-validation
NeuralForecast Modern neural architectures (TFT, Informer, Autoformer, …)
Darts Unified model API + backtesting helpers
sktime Unified fit/predict interface and evaluation utilities
GluonTS Probabilistic forecasting datasets + benchmarking
Prophet ds/y DataFrame convention for forecasting
PyTorch Forecasting Deep learning forecasting pipelines
Kats Time series analysis & forecasting toolbox (Meta)

📖 Citing ForeSight

If you find ForeSight useful in your research, please consider citing:

@software{foresight2024,
  title   = {ForeSight: A Lightweight Time-Series Forecasting Toolkit},
  author  = {ForeSight Contributors},
  year    = {2024},
  url     = {https://github.com/skygazer42/ForeSight},
  version = {0.2.9},
}

⚖️ License: GPL-3.0-only


Made with ❤️ by the ForeSight community


Report Bug · Request Feature · Documentation

About

一个轻量级、开箱即用的 Python 时间序列预测工具包，通过统一接口支持 250+ 种统计、机器学习与深度学习模型

Topics

machine-learning deep-learning time-series forecasting backtesting

Resources

Readme

License

GPL-3.0 license
Activity

Stars

123 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases 11

v0.2.10 Latest
Mar 26, 2026
+ 10 releases

Packages

 
 
 

Contributors

Languages