A lightweight, batteries-included time-series forecasting toolkit for Python.
Unified model registry • Walk-forward backtesting • Probabilistic forecasting • CLI + Python API
Installation · Quick Start · Model Zoo · Architecture · Docs · Contributing
250+ models · 7 backends · 20+ metrics · 1 unified interface | Statistical, ML, and deep learning models all share the same | Walk-forward evaluation with expanding or rolling windows, full cross-validation predictions table, per-step metrics, and conformal prediction intervals — all built in. |
| First-class multi-series support via | Core depends only on |
| Quantile regression, conformal intervals, bootstrap intervals, CRPS, pinball loss — production-ready uncertainty quantification across all model families. |
|
Design inspired by StatsForecast · Darts · sktime · NeuralForecast · Prophet
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 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[all]" # everything aboveInstall from source (for development)
git clone https://github.com/skygazer42/ForeSight.git cd ForeSight pip install -e ".[dev]" # editable install + pytest, ruff, mypyfrom 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)# Discover models and datasets foresight models list # list all 250+ models foresight models info theta # inspect parameters & defaults foresight datasets list # browse built-in datasets # 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 zscoreLong-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.jsonForeSight organizes 250+ registered models into families. Core models are dependency-free; optional models activate with the corresponding extra.
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 | 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 |
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 |
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 | 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 |
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 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 |
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 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", )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 | 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 |
| 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 |
# 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.9Produces yhat_p10, yhat_p50, yhat_p90 columns alongside yhat (defaults to median quantile).
| 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 | — | — |
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 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 & defaultsForeSight 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 mdWe 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 # testSee docs/DEVELOPMENT.md for detailed guidelines and docs/ARCHITECTURE.md for the layered design.
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) |
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}, }