energy_methods.timestral#

Optional local connector to Mistral AI’s Timestral forecasting models.

Timestral is model inference, so it belongs in energy_methods rather than the public-observation retrieval package. Inputs must have equally spaced time steps in a consistent unit. No resampling, unit conversion or interpolation is performed here. NaN marks missing data; infinity is rejected.

Reference: mistralai/timestral (Apache-2.0 inference code; model weights have their own Modified MIT licence). No weights are bundled.

class energy_methods.timestral.ForecastBackend(*args, **kwargs)[source]#

Bases: Protocol

Minimal upstream interface; allows offline contract tests without PyTorch.

forecast(context, prediction_length, **kwargs)[source]#

Return an object with quantiles and quantile_levels attributes.

Parameters:
  • context (FloatArray)

  • prediction_length (int)

  • kwargs (object)

Return type:

object

class energy_methods.timestral.TimestralForecast(quantiles, quantile_levels)[source]#

Bases: object

CPU NumPy forecasts in the input unit, shaped (batch, variates, horizon, Q).

Quantiles describe the model’s predictive distribution, not calibrated confidence bounds. median is the 0.5 quantile, not the expected value. Arrays are copied and frozen, and invalid model output is rejected.

Parameters:
  • quantiles (FloatArray)

  • quantile_levels (tuple[float, ...])

quantiles: FloatArray#
quantile_levels: tuple[float, ...]#
quantile(level)[source]#

Select an exact model probability level without interpolating it.

Parameters:

level (float)

Return type:

FloatArray

property median: FloatArray#

Return the median, shaped (batch, variates, horizon).

class energy_methods.timestral.TimestralConnector(model_id='mistralai/Timestral-5M', *, device='cpu', revision=None, cache_dir=None, local_files_only=False, max_context=32768, forecaster=None)[source]#

Bases: object

Lazy, reusable local inference with optional CPU/GPU model loading.

Constructing this object never loads packages or downloads weights. The first valid forecast call loads Timestral and caches the forecaster. Install the official package using TIMESTRAL_INSTALL. This is not a Mistral chat API: no Mistral API key is needed. Use a model commit revision for reproducible Hub downloads, or a local checkpoint directory with local_files_only=True.

Parameters:
  • model_id (str | Path) – Official Hub ID (5M, 28M, 123M or 209M) or local checkpoint path.

  • device (str) – Upstream PyTorch device, e.g. cpu or cuda.

  • revision (str | None) – Hugging Face checkpoint revision, distinct from the code revision.

  • cache_dir (str | Path | None) – Optional Hugging Face cache path.

  • local_files_only (bool) – Refuse network downloads; missing cache files are errors.

  • max_context (int) – Maximum recent steps passed to the model, at most 32,768.

  • forecaster (ForecastBackend | None) – Optional preloaded upstream-compatible backend.

forecast(context, prediction_length, *, observation_mask=None, past_covariates=None, known_covariates=None, categorical_past_covariates=None, categorical_known_covariates=None, symmetric_averaging=True, clip_nonnegative=True)[source]#

Forecast uniformly spaced context without training or future target data.

context is (T,), (B, T) or (B, V, T); 2D means independent univariate series, not one multivariate series. Use (1, V, T) for that. observation_mask must be boolean and exactly match the input shape. Covariates are (B, C, T) for past-only and (B, C, T + horizon) for known future values. Numeric category codes use the same shapes. Only supply covariates actually available at forecast time (e.g. calendars or archived weather forecasts, never subsequently observed weather).

Long context and covariates are trimmed together, preserving the whole horizon. Each target must have an observed value in the retained window. Errors propagate: there is no synthetic or persistence fallback.

Parameters:
  • context (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str])

  • prediction_length (int)

  • observation_mask (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None)

  • past_covariates (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None)

  • known_covariates (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None)

  • categorical_past_covariates (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None)

  • categorical_known_covariates (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None)

  • symmetric_averaging (bool)

  • clip_nonnegative (bool)

Return type:

TimestralForecast