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
Upgrade for SOTA features (LLRD, dropout schedule)	Upgrade Guide
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 still the top-level foreblocks import path:

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

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/core` | model assembly, heads, conformal utilities |
| `foreblocks/training` | trainer loop, optimizer/scheduler integration |
| `foreblocks/evaluation` | evaluator, metrics, benchmark helpers |
| `foreblocks/ts_handler` | preprocessing, filtering, imputation, window creation |
| `foreblocks/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](getting-started)
2. [Public API](reference/public-api)
3. [Evaluation & Metrics](evaluation)

### Track B: I have raw data and need preprocessing

1. [Getting Started](getting-started)
2. [Preprocessor Guide](preprocessor)
3. [Feature Engineering](foretools/feature-engineering)

### Track C: I want automated search or more advanced architectures

1. [Getting Started](getting-started)
2. [Transformer Guide](transformer) or [MoE Guide](moe)
3. [DARTS Guide](darts)
4. [DARTS Search Pipeline](architecture/darts-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.