{"id":41926997,"url":"https://github.com/skygazer42/foresight","last_synced_at":"2026-05-03T18:03:10.450Z","repository":{"id":162775592,"uuid":"621316538","full_name":"skygazer42/ForeSight","owner":"skygazer42","description":"通过统一接口支持 250+ 种统计、机器学习与深度学习模型时间序列预测工具包，","archived":false,"fork":false,"pushed_at":"2026-04-21T05:30:11.000Z","size":39824,"stargazers_count":123,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-21T07:29:46.028Z","etag":null,"topics":["backtesting","deep-learning","forecasting","machine-learning","time-series"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/skygazer42.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-03-30T12:24:30.000Z","updated_at":"2026-04-21T05:29:18.000Z","dependencies_parsed_at":"2025-10-16T17:43:42.153Z","dependency_job_id":null,"html_url":"https://github.com/skygazer42/ForeSight","commit_stats":null,"previous_names":["jhlucc/time-series","jhlucc/foresight","jhlu2019/foresight","skygazer42/foresight"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/skygazer42/ForeSight","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skygazer42%2FForeSight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skygazer42%2FForeSight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skygazer42%2FForeSight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skygazer42%2FForeSight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/skygazer42","download_url":"https://codeload.github.com/skygazer42/ForeSight/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/skygazer42%2FForeSight/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32579090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backtesting","deep-learning","forecasting","machine-learning","time-series"],"created_at":"2026-01-25T17:13:37.655Z","updated_at":"2026-05-03T18:03:10.443Z","avatar_url":"https://github.com/skygazer42.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"docs/assets/readme/hero.png\" alt=\"ForeSight hero banner\" width=\"1200\"/\u003e\n\u003c/p\u003e\n\n**A lightweight, batteries-included time-series forecasting toolkit for Python.**\n\nUnified model registry \u0026bull; Walk-forward backtesting \u0026bull; Probabilistic forecasting \u0026bull; CLI + Python API\n\n[![PyPI](https://img.shields.io/pypi/v/foresight-ts?color=6366f1\u0026style=for-the-badge\u0026logo=pypi\u0026logoColor=white)](https://pypi.org/project/foresight-ts/)\n[![Python](https://img.shields.io/pypi/pyversions/foresight-ts?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://pypi.org/project/foresight-ts/)\n[![License](https://img.shields.io/github/license/skygazer42/ForeSight?style=for-the-badge\u0026color=7c3aed)](https://github.com/skygazer42/ForeSight/blob/main/LICENSE)\n[![GitHub stars](https://img.shields.io/github/stars/skygazer42/ForeSight?style=for-the-badge\u0026color=f59e0b\u0026logo=github)](https://github.com/skygazer42/ForeSight)\n[![Last commit](https://img.shields.io/github/last-commit/skygazer42/ForeSight?style=for-the-badge\u0026color=10b981)](https://github.com/skygazer42/ForeSight/commits/main)\n\n[Installation](#installation) · [Quick Start](#quick-start) · [Model Zoo](#model-zoo) · [Architecture](#architecture) · [Docs](https://skygazer42.github.io/ForeSight/) · [Contributing](#contributing)\n\n`250+ models · 7 backends · 20+ metrics · 1 unified interface`\n\n## Overview\n\n- One interface across statistical, ML, and deep learning forecasters.\n- Backtesting-first workflows with walk-forward CV, leaderboards, and intervals.\n- First-class panel and global modeling with `unique_id / ds / y` long format.\n- Minimal core install; heavier runtimes stay optional.\n- Python API, CLI workflows, and reusable model artifacts share the same contracts.\n\n---\n\n## Support Contract\n\nForeSight exposes a broad catalog, but the **stable public surface** is narrower than the full implementation footprint.\n\n- Stable surface: the root `foresight` Python API, model registry metadata from `foresight models list/info`, the artifact schema/load contract, and the documented CLI workflows.\n- CI-backed matrix: Python 3.10 and 3.11 for core installs and contract checks, plus packaging smoke on Python 3.10 and smoke coverage for `stats` and `ml`.\n- Beta and experimental families remain available, but they are not covered by the same compatibility promise as the stable core workflows.\n\nSee [Compatibility guide](docs/compatibility.md) for the detailed support policy.\n\n---\n\n## How It Works\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/assets/readme/how-it-works.png\" alt=\"ForeSight workflow overview\" width=\"1100\"/\u003e\n\u003c/div\u003e\n\n---\n\n## Installation\n\n```bash\npip install foresight-ts                # core (numpy + pandas only)\n```\n\nOptional extras:\n\n| Extra | Install | Use for |\n|-------|---------|---------|\n| `ml` | `pip install \"foresight-ts[ml]\"` | scikit-learn models |\n| `xgb` | `pip install \"foresight-ts[xgb]\"` | XGBoost models |\n| `lgbm` | `pip install \"foresight-ts[lgbm]\"` | LightGBM models |\n| `catboost` | `pip install \"foresight-ts[catboost]\"` | CatBoost models |\n| `stats` | `pip install \"foresight-ts[stats]\"` | statsmodels models |\n| `torch` | `pip install \"foresight-ts[torch]\"` | PyTorch models |\n| `sktime` | `pip install \"foresight-ts[sktime]\"` | sktime adapter bridge |\n| `darts` | `pip install \"foresight-ts[darts]\"` | Darts adapter bridge |\n| `gluonts` | `pip install \"foresight-ts[gluonts]\"` | GluonTS adapter bridge |\n| `all` | `pip install \"foresight-ts[all]\"` | everything above |\n\nCheck the active environment, optional dependencies, and dataset resolution:\n\n```bash\nforesight doctor\nforesight --data-dir /path/to/root doctor\nforesight doctor --format text\nforesight --data-dir /path/to/root doctor --format text --strict\nforesight doctor --require-extra torch --strict\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eInstall from source (for development)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/skygazer42/ForeSight.git\ncd ForeSight\npip install -e \".[dev]\"     # editable install + pytest, ruff, mypy\n```\n\n\u003c/details\u003e\n\n---\n\n## Quick Start\n\n### Python API\n\n```python\nfrom foresight import eval_model, make_forecaster, make_forecaster_object\n\n# Walk-forward evaluation on a built-in dataset\nmetrics = eval_model(\n    model=\"theta\", dataset=\"catfish\", y_col=\"Total\",\n    horizon=3, step=3, min_train_size=12,\n)\nprint(metrics)  # {'mae': ..., 'rmse': ..., 'mape': ..., 'smape': ...}\n\n# Functional API — stateless forecaster\nf = make_forecaster(\"holt\", alpha=0.3, beta=0.1)\nyhat = f([112, 118, 132, 129, 121, 135, 148, 148], horizon=3)\n\n# Object API — fit / predict / save / load\nobj = make_forecaster_object(\"moving-average\", window=3)\nobj.fit([1, 2, 3, 4, 5, 6])\nyhat = obj.predict(3)\n```\n\n## Beta Adapters\n\nBeta integration adapters live under `foresight.adapters` rather than the stable root package surface.\n\n```python\nfrom foresight.adapters import (\n    make_sktime_forecaster_adapter,\n    to_darts_timeseries,\n    from_darts_timeseries,\n    to_gluonts_list_dataset,\n)\n```\n\n- `make_sktime_forecaster_adapter(...)` provides a minimal sktime-style `fit/predict` bridge.\n- `to_darts_timeseries(...)` and `from_darts_timeseries(...)` convert between ForeSight data and Darts `TimeSeries`.\n- `to_gluonts_list_dataset(...)` converts long-format history into a GluonTS `ListDataset`.\n\nThese adapters are intentionally **beta** and are not part of the root `foresight.__all__` contract yet.\n\n### CLI\n\n```bash\n# Discover models and datasets\nforesight models list                     # list all 250+ models\nforesight models info theta               # inspect parameters \u0026 defaults\nforesight models list --stability stable  # filter by maturity level\nforesight models list --capability supports_x_cols=true --format json\nforesight datasets list                   # browse built-in datasets\nforesight doctor                          # inspect optional deps and data paths\nforesight doctor --format text            # human-readable environment summary\nforesight doctor --require-extra torch --strict\n\n# Evaluate a model\nforesight eval run --model theta --dataset catfish --y-col Total \\\n    --horizon 3 --step 3 --min-train-size 12\n\n# Compare models on a leaderboard\nforesight leaderboard models --dataset catfish --y-col Total \\\n    --horizon 3 --step 3 --min-train-size 12 \\\n    --models naive-last,seasonal-naive,theta,holt\n\n# Forecast from any CSV\nforesight forecast csv --model naive-last --path ./data.csv \\\n    --time-col ds --y-col y --parse-dates --horizon 7\n\n# Cross-validation from any CSV\nforesight cv csv --model naive-last --path ./data.csv \\\n    --time-col ds --y-col y --parse-dates \\\n    --horizon 3 --step-size 1 --min-train-size 24\n\n# Detect anomalies from any CSV\nforesight detect csv --path ./anomaly.csv \\\n    --time-col ds --y-col y --parse-dates \\\n    --score-method rolling-zscore --threshold-method zscore\n```\n\nLong-running CLI commands emit enhanced runtime logs to `stderr` by default, so\n`stdout` stays clean for JSON / CSV piping and file redirects.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMore Python API examples (intervals, tuning, global models, hierarchical)\u003c/b\u003e\u003c/summary\u003e\n\n```python\nimport pandas as pd\nfrom foresight import (\n    bootstrap_intervals,\n    detect_anomalies,\n    eval_hierarchical_forecast_df,\n    forecast_model, tune_model, save_forecaster, load_forecaster,\n    make_forecaster_object,\n    make_global_forecaster, make_multivariate_forecaster,\n    build_hierarchy_spec, reconcile_hierarchical_forecasts,\n)\n\n# Forecast with bootstrap prediction intervals\nfuture_df = forecast_model(\n    model=\"naive-last\",\n    y=[1, 2, 3, 4, 5, 6],\n    ds=pd.date_range(\"2024-01-01\", periods=6, freq=\"D\"),\n    horizon=3,\n    interval_levels=(0.8, 0.9),\n    interval_min_train_size=4,\n)\n\n# Save / load trained model artifacts\nobj = make_forecaster_object(\"theta\", alpha=0.3)\nobj.fit([1, 2, 3, 4, 5])\nsave_forecaster(obj, \"/tmp/theta.pkl\")\nloaded = load_forecaster(\"/tmp/theta.pkl\")\n\n# Detect anomalies from a dataset-backed series\nanomalies = detect_anomalies(\n    dataset=\"catfish\",\n    y_col=\"Total\",\n    model=\"naive-last\",\n    score_method=\"forecast-residual\",\n    min_train_size=24,\n    step_size=1,\n)\n\n# Grid search tuning\nresult = tune_model(\n    model=\"moving-average\", dataset=\"catfish\", y_col=\"Total\",\n    horizon=1, step=1, min_train_size=24, max_windows=8,\n    search_space={\"window\": (1, 3, 6)},\n)\n\n# Multivariate model (VAR)\nmv = make_multivariate_forecaster(\"var\", maxlags=1)\nyhat_mv = mv(wide_df[[\"sales\", \"traffic\"]], horizon=2)\n\n# Hierarchical reconciliation\nhierarchy = build_hierarchy_spec(raw_df, id_cols=(\"region\", \"store\"), root=\"total\")\nreconciled = reconcile_hierarchical_forecasts(\n    forecast_df=pred_df, hierarchy=hierarchy,\n    method=\"top_down\", history_df=history_long,\n)\nhier_payload = eval_hierarchical_forecast_df(\n    forecast_df=reconciled,\n    hierarchy=hierarchy,\n    y_col=\"y\",\n)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMore CLI examples (artifacts, covariates, sweep)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Forecast with prediction intervals\nforesight forecast csv --model naive-last --path ./my.csv \\\n    --time-col ds --y-col y --parse-dates --horizon 3 \\\n    --interval-levels 80,90 --interval-min-train-size 12\n\n# Enhanced runtime logs go to stderr; stdout remains pipe-safe\nforesight forecast csv --model torch-mlp-direct --path ./train.csv \\\n    --time-col ds --y-col y --parse-dates --horizon 3 \\\n    --model-param lags=24 --model-param epochs=10 \\\n    --format json \u003e /tmp/forecast.json\n\n# Reduce per-epoch chatter or persist structured event logs\nforesight eval run --model theta --dataset catfish --y-col Total \\\n    --horizon 3 --step 3 --min-train-size 12 \\\n    --no-progress --log-style plain --log-file /tmp/eval-log.jsonl\n\n# Save and reuse model artifacts\nforesight forecast csv --model naive-last --path ./my.csv \\\n    --time-col ds --y-col y --parse-dates --horizon 3 \\\n    --save-artifact /tmp/naive-last.pkl\nforesight forecast artifact --artifact /tmp/naive-last.pkl --horizon 3\n\n# Only load artifacts from trusted sources.\n\n# Save and reuse a local x_cols artifact with the saved future covariates\nforesight forecast csv --model sarimax --path ./my_exog.csv \\\n    --time-col ds --y-col y --parse-dates --horizon 3 \\\n    --model-param order=0,0,0 --model-param seasonal_order=0,0,0,0 \\\n    --model-param trend=c --model-param x_cols=promo \\\n    --save-artifact /tmp/sarimax.pkl\nforesight forecast artifact --artifact /tmp/sarimax.pkl --horizon 2\n\n# Override the saved future covariates with a new future CSV\nforesight forecast artifact --artifact /tmp/sarimax.pkl \\\n    --future-path ./my_exog_future.csv --time-col ds --parse-dates \\\n    --horizon 4\n\n# Reuse a quantile-capable global artifact and derive interval columns\nforesight forecast artifact --artifact /tmp/xgb-global.pkl \\\n    --horizon 2 --interval-levels 80\n\n# Override a saved global artifact with new future covariates\n# The override CSV can contain canonical unique_id values or the raw id columns\n# that were used when the artifact was saved, plus ds and required x_cols.\n# Single-series global artifacts can also omit id columns entirely.\nforesight forecast artifact --artifact /tmp/ridge-global.pkl \\\n    --future-path ./my_global_future.csv --time-col ds --parse-dates \\\n    --horizon 2\n\nforesight artifact info --artifact /tmp/naive-last.pkl\nforesight artifact info --artifact /tmp/naive-last.pkl --format markdown\nforesight artifact validate --artifact /tmp/naive-last.pkl\nforesight artifact diff \\\n    --left-artifact /tmp/naive-last.pkl \\\n    --right-artifact /tmp/naive-last-v2.pkl \\\n    --path-prefix metadata.train_schema.runtime --format csv\nforesight artifact diff \\\n    --left-artifact /tmp/naive-last.pkl \\\n    --right-artifact /tmp/naive-last-v2.pkl \\\n    --path-prefix tracking_summary --format csv\nforesight artifact diff \\\n    --left-artifact /tmp/naive-last.pkl \\\n    --right-artifact /tmp/naive-last-v2.pkl \\\n    --path-prefix future_override_schema --format markdown\n\n# SARIMAX with exogenous features\nforesight forecast csv --model sarimax --path ./my_exog.csv \\\n    --time-col ds --y-col y --parse-dates --horizon 3 \\\n    --model-param order=0,0,0 --model-param x_cols=promo\n\n# Anomaly detection with exogenous covariates\nforesight detect csv --model sarimax --path ./my_exog.csv \\\n    --time-col ds --y-col y --parse-dates \\\n    --score-method forecast-residual --threshold-method mad \\\n    --min-train-size 24 --model-param order=0,0,0 \\\n    --model-param seasonal_order=0,0,0,0 \\\n    --model-param trend=c --model-param x_cols=promo\n\n# Multi-dataset sweep (parallel + resumable)\nforesight leaderboard sweep \\\n    --datasets catfish,ice_cream_interest \\\n    --models naive-last,theta --horizon 3 --step 3 \\\n    --min-train-size 12 --jobs 4 --progress\n\n# Conformal prediction intervals\nforesight eval run --model theta --dataset catfish --y-col Total \\\n    --horizon 3 --step 3 --min-train-size 12 --conformal-levels 80,90\n\n# Cross-validation predictions table\nforesight cv run --model theta --dataset catfish --y-col Total \\\n    --horizon 3 --step-size 3 --min-train-size 12 --n-windows 30\n\n# Cross-validation on arbitrary CSV data\nforesight cv csv --model sarimax --path ./my_exog.csv \\\n    --time-col ds --y-col y --parse-dates \\\n    --horizon 3 --step-size 3 --min-train-size 24 \\\n    --model-param order=0,0,0 \\\n    --model-param seasonal_order=0,0,0,0 \\\n    --model-param trend=c --model-param x_cols=promo \\\n    --format json \u003e /tmp/cv.json\n```\n\n\u003c/details\u003e\n\n---\n\n## Model Zoo\n\nForeSight organizes **250+** registered models into a few clear families. Use `foresight models list` and `foresight models info \u003ckey\u003e` for the full catalog.\n\n### Model Landscape\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/assets/readme/model-landscape.png\" alt=\"ForeSight model landscape across statistical, ML, deep learning, panel, multivariate, and ensemble families\" width=\"1100\"/\u003e\n\u003c/div\u003e\n\n### Model Families\n\n| Family | Coverage |\n|--------|----------|\n| Statistical | naive baselines, moving averages, ETS/Holt-Winters, theta, Fourier, Kalman, intermittent demand |\n| Machine learning | scikit-learn, XGBoost, LightGBM, CatBoost |\n| Deep learning | MLP, RNN, CNN, Transformer, SSM, residual blocks |\n| Panel/global | sklearn global, tree global, torch global |\n| Multivariate / ensemble | VAR, mean, median, pipeline |\n\n### Optional Models\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003escikit-learn\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[ml]\"\u003c/code\u003e\u003c/summary\u003e\n\n**Local (lag-feature + direct multi-horizon):**\n\n`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`\n\n**Global/panel (step-lag, trains across all series):**\n\n`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\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eXGBoost\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[xgb]\"\u003c/code\u003e\u003c/summary\u003e\n\n| Strategy | Models |\n|----------|--------|\n| Direct | `xgb-lag`, `xgb-dart-lag`, `xgbrf-lag`, `xgb-linear-lag` |\n| Recursive | `xgb-lag-recursive`, `xgb-dart-lag-recursive`, `xgb-linear-lag-recursive` |\n| Step-index | `xgb-step-lag` |\n| DirRec | `xgb-dirrec-lag` |\n| MIMO | `xgb-mimo-lag` |\n| Custom objectives | `xgb-mae-lag`, `xgb-huber-lag`, `xgb-quantile-lag`, `xgb-poisson-lag`, `xgb-gamma-lag`, ... |\n| **Global/panel** | `xgb-step-lag-global` (supports quantile output) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLightGBM\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[lgbm]\"\u003c/code\u003e\u003c/summary\u003e\n\n**Local:** `lgbm-lag`, `lgbm-lag-recursive`, `lgbm-step-lag`, `lgbm-dirrec-lag`, `lgbm-custom-lag`\n\n**Global/panel:** `lgbm-step-lag-global` (supports quantile output)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCatBoost\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[catboost]\"\u003c/code\u003e\u003c/summary\u003e\n\n**Local:** `catboost-lag`, `catboost-lag-recursive`, `catboost-step-lag`, `catboost-dirrec-lag`\n\n**Global/panel:** `catboost-step-lag-global` (supports quantile output)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003estatsmodels\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[stats]\"\u003c/code\u003e\u003c/summary\u003e\n\n| Family | Models |\n|--------|--------|\n| ARIMA | `arima`, `auto-arima`, `sarimax`, `autoreg` |\n| Fourier Hybrid | `fourier-arima`, `fourier-auto-arima`, `fourier-autoreg`, `fourier-sarimax` |\n| Decomposition | `stl-arima`, `stl-autoreg`, `stl-ets`, `mstl-arima`, `mstl-autoreg`, `mstl-ets`, `mstl-auto-arima` |\n| TBATS-lite | `tbats-lite`, `tbats-lite-autoreg`, `tbats-lite-auto-arima` |\n| Unobserved Components | `uc-local-level`, `uc-local-linear-trend`, `uc-seasonal` |\n| ETS | `ets` |\n| Multivariate | `var` |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePyTorch — Local models\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[torch]\"\u003c/code\u003e\u003c/summary\u003e\n\n| Category | Models |\n|----------|--------|\n| MLP / Linear | `torch-mlp-direct`, `torch-nlinear-direct`, `torch-dlinear-direct`, `torch-tide-direct`, `torch-kan-direct` |\n| RNN | `torch-lstm-direct`, `torch-gru-direct`, `torch-bilstm-direct`, `torch-bigru-direct`, `torch-attn-gru-direct` |\n| CNN | `torch-cnn-direct`, `torch-tcn-direct`, `torch-resnet1d-direct`, `torch-wavenet-direct`, `torch-inception-direct`, `torch-scinet-direct` |\n| Transformer | `torch-transformer-direct`, `torch-patchtst-direct`, `torch-crossformer-direct`, `torch-pyraformer-direct`, `torch-fnet-direct`, `torch-tsmixer-direct`, `torch-retnet-direct` |\n| Residual Blocks | `torch-nbeats-direct`, `torch-nhits-direct` |\n| SSM / State-space | `torch-mamba-direct`, `torch-rwkv-direct`, `torch-hyena-direct` |\n| Hybrid | `torch-etsformer-direct`, `torch-esrnn-direct`, `torch-lstnet-direct` |\n| Probabilistic | `torch-deepar-recursive`, `torch-qrnn-recursive` |\n| RNN Paper Zoo | 100 named paper architectures (`torch-rnnpaper-*-direct`) |\n| RNN Zoo | 100 combos: 20 bases × 5 wrappers (`torch-rnnzoo-*-direct`) |\n| Configurable Transformer | `torch-xformer-*-direct` — 10 attention variants × positional encodings × extras |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePyTorch — Global/panel models\u003c/b\u003e — \u003ccode\u003epip install \"foresight-ts[torch]\"\u003c/code\u003e\u003c/summary\u003e\n\nTrain across all series in long-format; supports covariates (`x_cols`), time features, and optional quantile regression.\n\n| Category | Models |\n|----------|--------|\n| 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` |\n| MLP / Linear | `torch-nbeats-global`, `torch-nhits-global`, `torch-nlinear-global`, `torch-dlinear-global`, `torch-tide-global` |\n| RNN | `torch-deepar-global`, `torch-lstnet-global`, `torch-esrnn-global` |\n| CNN | `torch-tcn-global`, `torch-wavenet-global`, `torch-scinet-global` |\n| SSM | `torch-mamba-global`, `torch-rwkv-global`, `torch-hyena-global` |\n\n\u003c/details\u003e\n\n### Multi-horizon Strategies\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/assets/readme/multi-horizon-strategies.png\" alt=\"Multi-horizon forecasting strategies: Direct, Recursive, Step-index, DirRec, and MIMO\" width=\"1200\"/\u003e\n\u003c/div\u003e\n\n| Strategy | How it works | Suffix |\n|----------|-------------|--------|\n| **Direct** | One model per horizon step | `*-lag` |\n| **Recursive** | One-step model, iteratively re-fed | `*-lag-recursive` |\n| **Step-index** | Single model with step as a feature | `*-step-lag` |\n| **DirRec** | Per-step model with previous-step features | `*-dirrec-lag` |\n| **MIMO** | Single model predicts entire horizon | `*-mimo-lag` |\n\n---\n\n## Architecture\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/assets/readme/architecture-overview.png\" alt=\"ForeSight layered architecture overview\" width=\"1100\"/\u003e\n\u003c/div\u003e\n\n---\n\n## Data Format\n\nForeSight uses a panel-friendly **long format** compatible with StatsForecast and Prophet:\n\n| Column | Description |\n|--------|-------------|\n| `unique_id` | Series identifier (optional for single series) |\n| `ds` | Timestamp (`datetime`) |\n| `y` | Target value (`float`) |\n| *extra columns* | Covariates / exogenous features |\n\n### Covariate Roles\n\n- `historic_x_cols`: observed only up to the forecast cutoff.\n- `future_x_cols`: known through the forecast horizon.\n- `x_cols`: shorthand alias for `future_x_cols`.\n\n```python\nfrom foresight.data import to_long, prepare_long_df\n\nlong_df = to_long(\n    raw_df, time_col=\"ds\", y_col=\"y\",\n    id_cols=(\"store\", \"dept\"),\n    historic_x_cols=(\"promo_hist\",),\n    future_x_cols=(\"promo_plan\", \"price\"),\n)\n\nprepared = prepare_long_df(\n    long_df, freq=\"D\",\n    y_missing=\"interpolate\",\n    historic_x_missing=\"ffill\",\n    future_x_missing=\"ffill\",\n)\n```\n\n---\n\n## Evaluation \u0026 Backtesting\n\n### Capabilities\n\n- Walk-forward backtesting with expanding or rolling windows.\n- Full cross-validation tables with `unique_id, ds, cutoff, step, y, yhat, model`.\n- Single-dataset leaderboards and multi-dataset sweeps.\n- Grid-search tuning scored through backtesting.\n- Conformal and bootstrap prediction intervals.\n\n### Metrics\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003ePoint Metrics\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003eMAE · RMSE · MAPE · sMAPE · WAPE · MASE · RMSSE · MSE\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cb\u003eProbabilistic Metrics\u003c/b\u003e\u003c/td\u003e\n\u003ctd\u003ePinball loss · CRPS · Coverage · Width · Sharpness · Interval Score · Winkler Score · Weighted Interval Score · MSIS\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### Probabilistic Forecasting\n\n```bash\n# Quantile regression with Torch global models\nforesight eval run --model torch-itransformer-global \\\n    --dataset catfish --y-col Total --horizon 7 --step 7 --min-train-size 60 \\\n    --model-param quantiles=0.1,0.5,0.9\n```\n\nProduces `yhat_p10`, `yhat_p50`, `yhat_p90` columns alongside `yhat` (defaults to median quantile).\n\n---\n\n## Optional Dependencies\n\n| Extra | Backend | Version | Example Models |\n|-------|---------|---------|---------------|\n| `[ml]` | scikit-learn | ≥ 1.0 | `ridge-lag`, `rf-lag`, `hgb-lag`, `mlp-lag`, `*-step-lag-global` |\n| `[xgb]` | XGBoost | ≥ 2.0 | `xgb-lag`, `xgb-step-lag`, `xgb-mimo-lag`, `xgb-step-lag-global` |\n| `[lgbm]` | LightGBM | ≥ 4.0 | `lgbm-lag`, `lgbm-step-lag-global` |\n| `[catboost]` | CatBoost | ≥ 1.2 | `catboost-lag`, `catboost-step-lag-global` |\n| `[stats]` | statsmodels | ≥ 0.14 | `arima`, `auto-arima`, `sarimax`, `ets`, `var`, `stl-*`, `mstl-*` |\n| `[torch]` | PyTorch | ≥ 2.0 | `torch-transformer-direct`, `torch-tft-global`, `torch-mamba-global` |\n| `[all]` | All of the above | — | — |\n\n---\n\n## Repository Structure\n\n```\nForeSight/\n├── src/foresight/              # Main Python package\n│   ├── models/                 #   Model registry, catalog, factories\n│   │   ├── catalog/            #     Model metadata shards\n│   │   ├── factories.py        #     Runtime construction\n│   │   └── registry.py         #     Public model facade\n│   ├── services/               #   Forecast \u0026 evaluation orchestration\n│   ├── contracts/              #   Validation \u0026 capability checks\n│   ├── data/                   #   Long-format I/O \u0026 preprocessing\n│   ├── datasets/               #   Built-in dataset registry\n│   ├── features/               #   Feature engineering\n│   ├── cli.py                  #   CLI entry point\n│   ├── base.py                 #   BaseForecaster classes\n│   ├── backtesting.py          #   Walk-forward engine\n│   ├── metrics.py              #   20+ evaluation metrics\n│   ├── conformal.py            #   Conformal prediction intervals\n│   ├── hierarchical.py         #   Hierarchical reconciliation\n│   └── transforms.py           #   Data transformations\n├── examples/                   # Runnable example scripts\n├── data/                       # Bundled CSV datasets\n├── benchmarks/                 # Reproducible benchmark harness\n├── tests/                      # 150+ test files\n├── docs/                       # MkDocs documentation\n└── tools/                      # Dev \u0026 release utilities\n```\n\n**Example scripts:** `quickstart_eval.py` · `leaderboard.py` · `cv_and_conformal.py` · `intermittent_demand.py` · `torch_global_models.py` · `rnn_paper_zoo.py`\n\n---\n\n## Model Capability Flags\n\nModel discovery surfaces machine-readable capability flags. Use them through `foresight models list` and `foresight models info`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCapability keys\u003c/b\u003e\u003c/summary\u003e\n\n| Flag | Meaning |\n|------|---------|\n| `supports_panel` | Supports panel / multi-series workflows through the high-level long-format APIs |\n| `supports_univariate` | Supports univariate forecasting targets |\n| `supports_multivariate` | Supports multivariate / wide-matrix forecasting targets |\n| `supports_probabilistic` | Supports probabilistic forecasting through intervals and/or quantiles |\n| `supports_conformal_eval` | Can participate in conformal backtest evaluation flows |\n| `supports_future_covariates` | Accepts known future covariates in supported workflows |\n| `supports_historic_covariates` | Accepts historical covariate values in supported workflows |\n| `supports_static_covariates` | Accepts series-level static covariates |\n| `supports_refit_free_cv` | Can reuse training state across CV cutoffs without refitting from scratch |\n| `supports_x_cols` | Accepts future covariates / exogenous regressors |\n| `supports_static_cols` | Accepts series-level static covariates from `long_df` |\n| `supports_quantiles` | Emits quantile forecast columns directly |\n| `supports_interval_forecast` | Supports forecast intervals |\n| `supports_interval_forecast_with_x_cols` | Supports forecast intervals when future covariates are provided |\n| `supports_artifact_save` | Can be saved and reused through the artifact workflow |\n| `requires_future_covariates` | Requires known future covariates |\n\n\u003c/details\u003e\n\n```bash\nforesight models info holt-winters-add    # see all flags \u0026 defaults\n```\n\n---\n\n## Benchmarks\n\nForeSight ships a reproducible benchmark harness for packaged datasets:\n\n```bash\npython benchmarks/run_benchmarks.py --smoke          # CI smoke run\npython benchmarks/run_benchmarks.py --config baseline --format md\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n```bash\ngit clone https://github.com/skygazer42/ForeSight.git\ncd ForeSight\npip install -e \".[dev]\"\n\nruff check src tests tools    # lint\nruff format src tests tools   # format\npytest -q                     # test\n```\n\nSee [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for detailed guidelines and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the layered design.\n\n---\n\n## Related Projects\n\nForeSight draws design inspiration from these excellent projects:\n\n| Project | Highlights |\n|---------|-----------|\n| [StatsForecast](https://github.com/Nixtla/statsforecast) | Fast statistical baselines, `unique_id/ds/y` convention, cross-validation |\n| [NeuralForecast](https://github.com/Nixtla/neuralforecast) | Modern neural architectures (TFT, Informer, Autoformer, …) |\n| [Darts](https://github.com/unit8co/darts) | Unified model API + backtesting helpers |\n| [sktime](https://www.sktime.org/) | Unified `fit`/`predict` interface and evaluation utilities |\n| [GluonTS](https://github.com/awslabs/gluonts) | Probabilistic forecasting datasets + benchmarking |\n| [Prophet](https://facebook.github.io/prophet/) | `ds/y` DataFrame convention for forecasting |\n| [PyTorch Forecasting](https://pytorch-forecasting.readthedocs.io/) | Deep learning forecasting pipelines |\n| [Kats](https://github.com/facebookresearch/Kats) | Time series analysis \u0026 forecasting toolbox (Meta) |\n\n---\n\n## Citing ForeSight\n\nIf you find ForeSight useful in your research, please consider citing:\n\n```bibtex\n@software{foresight2024,\n  title   = {ForeSight: A Lightweight Time-Series Forecasting Toolkit},\n  author  = {ForeSight Contributors},\n  year    = {2024},\n  url     = {https://github.com/skygazer42/ForeSight},\n  version = {0.2.9},\n}\n```\n\n---\n\n**License:** [GPL-3.0-only](LICENSE)\n\n[Issues](https://github.com/skygazer42/ForeSight/issues) · [Documentation](https://skygazer42.github.io/ForeSight/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskygazer42%2Fforesight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskygazer42%2Fforesight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskygazer42%2Fforesight/lists"}