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:
ProtocolMinimal upstream interface; allows offline contract tests without PyTorch.
- class energy_methods.timestral.TimestralForecast(quantiles, quantile_levels)[source]#
Bases:
objectCPU NumPy forecasts in the input unit, shaped (batch, variates, horizon, Q).
Quantiles describe the model’s predictive distribution, not calibrated confidence bounds.
medianis 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:
objectLazy, reusable local inference with optional CPU/GPU model loading.
Constructing this object never loads packages or downloads weights. The first valid
forecastcall loads Timestral and caches the forecaster. Install the official package usingTIMESTRAL_INSTALL. This is not a Mistral chat API: no Mistral API key is needed. Use a model commitrevisionfor reproducible Hub downloads, or a local checkpoint directory withlocal_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.
cpuorcuda.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.
contextis (T,), (B, T) or (B, V, T); 2D means independent univariate series, not one multivariate series. Use (1, V, T) for that.observation_maskmust 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: