Forecasting as a loop, not a number on a slide

In most organisations a forecast is a number on a slide: produced once, argued over, and stale by the time anyone acts on it. The models are hard-coded, the backtest — if there is one — quietly leaks the future, and nobody can reconstruct which data produced which prediction. ZenForecast starts from the opposite premise: forecasting is a loop — predict → decide → act → learn — and the framework’s job is to make every turn of that loop reproducible, comparable, and auditable.

Seven layers, built from scratch

The framework specifies a 7-layer architecture — data → features → prediction → scenario → agents → governance → presentation — delivered against a phased 0→5 roadmap with per-story build specs. It’s a from-scratch design rather than a wrapper around any single library, because the interesting guarantees live between the layers.

Models are interchangeable, not sacred

At the centre is a model-agnostic Forecaster interface — fit, predict, backtest — so classical methods, machine learning, deep learning, and time-series foundation models (Chronos-2, TimesFM, Moirai-2) are interchangeable and empirically benchmarkable rather than hard-coded.

“Should we use a foundation model?” becomes an experiment you run, not an opinion you defend.

Honest numbers by construction

The prediction spine is Python 3.11+ with Pydantic v2: statsforecast wrappers (AutoARIMA, ETS, Theta), a leakage-free walk-forward backtesting harness, and both point and probabilistic metrics — MAPE, RMSE, MAE, pinball loss, and CRPS. Forecasts are probabilistic by default, emitting P10/P50/P90 quantiles, because a single point estimate hides exactly the uncertainty a decision-maker needs.

Storage runs on embedded DuckDB with Polars IO, Pandera schema validation, and schema-hash dataset versioning, so a backtest is reproducible down to the exact bytes it saw.

Governance from day one

Every operation is recorded in an append-only audit ledger — timestamp, actor, input hash — giving full lineage from raw data to published forecast. That’s paired with a strict CI quality gate: ruff, mypy --strict, 31 unit and integration tests across Python 3.11 and 3.12, hypothesis property tests, and structured logging. And the whole framework runs end-to-end with zero external data via a pluggable synthetic energy-demand domain pack — clone it and the loop turns immediately.

Where it’s heading — and what to borrow

The layers above prediction — scenario composition and the agentic layer that closes the predict → decide → act → learn loop — are the research frontier of the roadmap. The foundation underneath is the immediately transferable part: interchangeable models behind one interface, walk-forward evaluation that cannot leak, quantiles instead of point estimates, and an audit trail nobody can argue with.

A plugin registry for models, connectors, and domain packs means new domains bolt on rather than fork off — and working through the spine is a compact education in what rigorous time-series practice actually requires. The bet behind the project: trustworthy agentic forecasting has to stand on exactly this kind of foundation.