• 1. Install
  • PyPI (stable)
  • With extras
  • Install examples
• 2. Imports
• 3. Trainer and MLTracker notes
• 4. Shape expectations
  • Direct forecasting
  • Encoder / decoder (seq2seq)
• 5. Starting from raw time series
• 6. When to add DARTS
• Related pages

Getting Started

This guide gives you the shortest reliable path to a working foreblocks training loop, then shows where to branch when you need preprocessing, search, or richer tooling.

If you want the broader mental model first, start from Overview.

GoalRun one small training job end to end with the stable public API.

Good first successYou can import the package, train a baseline model, and compute metrics on held-out data.

Only thenAdd preprocessing extras, custom transformer internals, DARTS, or tracking-heavy workflows.

1. Install

This project targets Python 3.10 and newer.

PyPI (stable)

pip install foreblocks

With extras

Extra	Adds
preprocessing	TimeSeriesHandler, windowing, scaling, filtering, imputation
darts	Architecture search, NAS, and evaluation helpers
mltracker	Experiment tracking API, local dashboard, and CLI TUI
studio	Studio frontend launcher and bundled server command
vmd	VMD decomposition and analysis helpers
wavelets	Wavelet preprocessing and multiwavelet feature extraction
benchmark	External forecasting baselines and spreadsheet readers
foreminer	Changepoint detection and dataset mining
all	All runtime extras

Install examples

# DARTS only
pip install "foreblocks[darts]"

# Multiple extras
pip install "foreblocks[vmd,wavelets]"

# Everything (large)
pip install "foreblocks[all]"

What this first run should validate

• Your foreblocks import path is correct.
• Dataloader shapes line up with the trainer.
• The model trains without needing optional subsystems.
• Evaluation works on held-out data.

2. Imports

The stable public surface starts at the top level of foreblocks:

Full surface

from foreblocks import (
    ForecastingModel,
    Trainer,
    ModelEvaluator,
    TimeSeriesHandler,
    TimeSeriesDataset,
    create_dataloaders,
    ModelConfig,
    TrainingConfig,
)

Minimal check

from foreblocks import ForecastingModel, Trainer

Run a quick import check before the full example:

python -c "from foreblocks import ForecastingModel, Trainer; print('foreblocks import OK')"

3. Trainer and MLTracker notes

Trainer initializes MLTracker automatically if installed. Pass auto_track=False during local smoke tests.

4. Shape expectations

Direct forecasting

Tensor	Shape	Description
X	[N, T, F]	Samples × input timesteps × features
y	[N, H]	Samples × horizon

Encoder / decoder (seq2seq)

Tensor	Shape	Description
X	[N, T, F]	Samples × input timesteps × features
y	[N, H, D]	Samples × horizon × output channels

Decoder-based models have stricter dimension contracts. Read the Custom Blocks guide before wiring custom modules.

5. Starting from raw time series

When your starting point is a single [T, D] array, use TimeSeriesHandler instead of building windows manually:

import numpy as np
import pandas as pd
from foreblocks import TimeSeriesHandler

# Load raw data
raw = np.random.randn(240, 3)  # [T, F]
timestamps = pd.date_range("2025-01-01", periods=len(raw), freq="h")

# Configure preprocessing
pre = TimeSeriesHandler(
    window_size=24,   # sequence length
    horizon=6,        # forecast horizon
    normalize=True,   # standardize features
    generate_time_features=False,
    verbose=False,
)

# Fit and transform
X, y, processed, time_feats = pre.fit_transform(raw, time_stamps=timestamps)

# Transform validation data using fitted state
X_val = pre.transform(val_raw, time_stamps=val_timestamps)

Continue with Preprocessor Guide for advanced options like filtering, outlier handling, and feature engineering.

6. When to add DARTS

If the basic training loop works and you want architecture search instead of hand-selecting blocks:

pip install "foreblocks[darts]"

Baseline works and metrics are acceptable?
├── No → improve your data
│   ├── Raw series (single array)   → Preprocessor Guide
│   └── Feature engineering        → Feature Engineering
│
├── Yes, but I want better accuracy
│   ├── Try a stronger backbone     → Transformer Guide
│   ├── Add MoE feedforward         → MoE Guide
│   ├── Add preprocessing heads     → Custom Blocks Guide
│   └── Search architectures        → DARTS Guide
│
├── Yes, but I need uncertainty
│   └── Post-hoc conformal intervals → Uncertainty Guide
│
├── Yes, but I need richer evaluation
│   └── Metrics, plots, CV           → Evaluation Guide
│
└── Yes, but training is slow or OOM
    └── AMP, gradient checkpointing  → Configuration Reference

Related pages

• Overview - Mental model of the stack
• Public API - Complete API reference
• Imports Reference - Consolidated import patterns
• Configuration - All configuration options
• Troubleshooting - Common issues and fixes