Overview

This repository has three packages that work well together but serve different purposes (all distributed in the same foreblocks wheel):

• foreblocks: the main forecasting library
• darts: a standalone differentiable neural-architecture-search package (imported as import darts)
• foretools: companion utilities for generation, search, decomposition, and analysis

The docs are organized to make that split explicit while still showing how the pieces connect in a single workflow.

Start here if you are newGetting Started is still the safest first read.

Keep the first run smallValidate the public API path before opening the more specialist subsystems.

Branch by workflowUse the guide that matches your actual task instead of reading every subsystem in order.

Best starting page by goal

Goal	Best starting page
Run a first end-to-end training loop	Getting Started
Quick config reference	Cheat Sheet
Start from raw multivariate series	Preprocessor Guide
Understand stable top-level imports	Public API
Customize model blocks or training internals	Custom Blocks Guide
Work with transformer backbones	Transformer Guide → Advanced
Enable expert routing	MoE Guide → Advanced
Production tuning and optimization	Advanced Transformer & Advanced MoE
Run neural architecture search	DARTS Guide
Generate synthetic time series	Time Series Generator
Run budgeted hyperparameter search	BOHB Search
Diagnose install or shape issues	Troubleshooting

Mental model of the repo

Layer 01

Stable public surface

The safest imports live at the top level of foreblocks: model assembly, trainer loop, dataloaders, configs, evaluator, and preprocessing bridge.

Layer 02

Optional workflow extras

Preprocessing, DARTS, tracking, VMD, and other heavier dependencies are packaged as extras so the base install stays lean.

Layer 03

Specialist subsystems

Transformer internals, MoE, Hybrid Mamba, uncertainty, and architecture notes are best treated as focused branches once the baseline path is healthy.

What is stable today

The most reliable public surface is the top-level foreblocks import path. See the Imports Reference for full code examples.

Treat deeper imports as subsystem-level APIs unless a topic guide explicitly tells you to use them directly.

Install map

The packaging reflects real feature boundaries:

Need	Suggested install
Minimal forecasting core	pip install foreblocks
Preprocessing, filtering, statistics	pip install "foreblocks[preprocessing]"
DARTS training, search, and analysis	pip install "foreblocks[darts]"
MLTracker UI and API clients	pip install "foreblocks[mltracker]"
VMD utilities	pip install "foreblocks[vmd]"
All runtime extras	pip install "foreblocks[all]"

How the docs are layered

Tutorials

Runnable paths first. Use these when you want a clear success condition and a smaller number of moving parts.

Guides

Subsystem pages that explain capabilities, important configuration knobs, and how modules are meant to be composed.

Architecture notes

Pages that explain internal structure and code layout. These are more useful when you are extending, debugging, or reviewing implementation choices.

Reference

Stable surfaces, configuration maps, and repository orientation.

Repository landmarks

Area	Purpose
foreblocks/models	model assembly, heads, conformal utilities
foreblocks/training	trainer loop, optimizer/scheduler integration
foreblocks/evaluation	evaluator, metrics, benchmark helpers
foreblocks/processing	preprocessing, filtering, imputation, window creation
foreblocks/nn/transformer	transformer stack, attention variants, MoE, norms, embeddings
darts	architecture search configs, search loops, analysis
mltracker	experiment tracking and local dashboards
foretools	synthetic data, BOHB, VMD, exploratory tooling

Recommended reading tracks

Track A: I just want a model training

1. Getting Started
2. Public API
3. Evaluation & Metrics

Track B: I have raw data and need preprocessing

1. Getting Started
2. Preprocessor Guide
3. Feature Engineering

Track C: I want automated search or more advanced architectures

1. Getting Started
2. Transformer Guide or MoE Guide
3. DARTS Guide
4. DARTS Search Pipeline

Practical notes

• The project is broad. Not every internal module should be treated as stable public API.
• ForecastingModel plus Trainer is still the best first path for a new user.
• TimeSeriesHandler is the main bridge from raw arrays into the trainer loop.
• DARTS is a staged workflow, not just a single training function.
• foretools is worth browsing even if you primarily use foreblocks, especially for data generation and search tooling.