System Overview
This page explains how the repository is organized at a subsystem level.
Two layers
The repository contains two related but distinct layers:
foreblocks: the main forecasting libraryforetools: auxiliary tools for generation, decomposition, and analysis
Core runtime path
The main foreblocks training flow is:
- prepare data as windows
- build a
ForecastingModel - train with
Trainer - evaluate with
ModelEvaluator
Main subsystems
| Path | Role |
|---|---|
foreblocks/kernels | compute tier — Triton/CUDA kernels, no nn.Module API surface |
foreblocks/ops | tensor ops and execution dispatch on top of kernels/ |
foreblocks/nn | reusable nn.Module primitives: attention config/variants/cache, transformer stack, blocks, heads, MoE, routing, sequence backbones, norms, embeddings, graph |
foreblocks/models | assembled models: forecasting.py (ForecastingModel), graph.py, baselines/ (NBEATS, Informer, …), kan/, anomaly/ (applications layer) |
foreblocks/training | Trainer, config, sampling, conformal prediction, optimization (LLRD, NAS) |
foreblocks/evaluation | ModelEvaluator, benchmarking, metrics |
foreblocks/studio | Studio node/spec auto-discovery backend for apps/webui |
foreblocks/processing | preprocessing, normalization, filtering, imputation, window creation |
darts | neural architecture search and finalization workflow |
foretools | synthetic data generation, feature engineering, decomposition, BOHB search |
mltracker | experiment tracking support |
Public API boundary
The stable starting point is the top-level import surface:
python
from foreblocks import ForecastingModel, Trainer, ModelEvaluatorThat boundary is safer than importing deep internal modules unless you are extending the library itself.
Dependency graph
text
foreblocks (main)
├── foreblocks/kernels — Triton/CUDA compute: attention/, mamba/, linear/, normalization/, activations/, graph/
├── foreblocks/ops — tensor ops + dispatch on top of kernels/: attention/, mamba/
├── foreblocks/integrations — optional external backends: fla/ (flash-linear-attention), softpick
├── foreblocks/nn — attention/, transformer/, blocks/, heads/, moe/, routing/, sequence/, normalization/, embeddings/, graph/
├── foreblocks/models
│ ├── forecasting.py — ForecastingModel
│ ├── graph.py — GraphForecastingModel
│ ├── baselines/ — NBEATS, Informer, Autoformer, TimesNet, …
│ ├── kan/ — Kolmogorov-Arnold Network
│ └── anomaly/ — anomaly-detection applications layer
├── foreblocks/training — Trainer, config, sampling, conformal, optimization (LLRD, NAS)
├── foreblocks/evaluation — ModelEvaluator, benchmarking, metrics
├── foreblocks/quantization — FakeQuantize, DynamicQuantizedLinear
├── foreblocks/studio — Studio node/spec auto-discovery backend
├── foreblocks/processing — TimeSeriesHandler, preprocessing, filtering
├── mltracker — Experiment tracking
└── darts (standalone) — Neural architecture search
foretools (companion)
├── foretools/tsgen — Synthetic time-series generation
├── foretools/bohb — Bayesian hyperparameter search
├── foretools/decomposition — emd/ (VMD, EMD-family), ewt/ (Empirical Wavelet Transform)
├── foretools/tsaug — AutoDA augmentation
├── foretools/fengineer — Feature engineering pipeline
├── foretools/foreminer — Changepoint detection & mining
├── foretools/stats — mutual information, distance correlation, HSIC, Bayesian Blocks binning
├── foretools/arima — ARIMA model utilities
└── foretools/benchmarking — benchmarking frameworksChoosing where to start
| Your goal | Start here |
|---|---|
| Train a forecasting model from scratch | Getting Started |
Use raw [T, D] time-series data | Preprocessor Guide |
| Try different model architectures | Transformer Guide or DARTS Guide |
| Add uncertainty estimates | Uncertainty Quantification |
| Search for a better architecture | Run A DARTS Search |
| Generate synthetic test data | Generate Synthetic Series |
Design intent
The codebase is organized around modular composition:
- model composition in
ForecastingModel - backbone specialization in recurrent and transformer blocks
- optional preprocessing before training
- optional architecture search through DARTS
- optional synthetic data generation in
foretools