Skip to main content

timestral-metal

timestral-metal runs Mistral's Timestral forecasting models on Apple silicon with MLX. It is a port of timestral 1.0.0 that loads the released checkpoints unchanged, supports the same features (including past-only, known-future and categorical covariates), and gives the same forecasts within float32 rounding. It does not need PyTorch.

Install

pip install timestral-metal

You need a Mac with Apple silicon and Python 3.11 or later.

Example

import numpy as np
from timestral_metal import TimestralForecaster

forecaster = TimestralForecaster.from_pretrained("mistralai/Timestral-123M")
context = np.random.randn(2, 1, 2000).cumsum(-1)  # (series, variates, time); NaN marks a missing value
forecast = forecaster.forecast(context, prediction_length=96)
forecast.median  # numpy array, (2, 1, 96)

The API is timestral's, documented in its README, with two differences: forecasts are numpy arrays, and there is no device argument.

Performance

Time per forecast on an Apple M5 Pro, from bench.py, against timestral on the CPU:

Timestral-123M timestral timestral-metal timestral-metal, full float32
2 series x 3 variates, 2,000-step context, 96 steps 181 ms 22 ms 43 ms
1 series, 3,000-step context, 1,100 steps 179 ms 20 ms 34 ms
1 series with 5 covariates, 32,768-step context, 48 steps not measured 395 ms 797 ms

The covariate case peaks at 2.1 GB of memory.

Changes from timestral

Besides running on the GPU, timestral-metal changes these parts of timestral's computation. The forecasts stay the same within float32 rounding.

  • With covariates, the model creates decoder tokens for the horizon patches only. timestral creates one for every patch of the window and keeps the predictions of the horizon patches. The other decoder tokens do not affect the forecast. Leaving them out halves the time of covariate forecasts, from 804 ms to 395 ms in the case above.
  • The forecast of the context and the forecast of its negation, which symmetric averaging combines, run as one batch instead of two calls. This saves 4 to 5 ms per forecast on Timestral-123M.
  • Each attention computes Q, K, V and its output gate with one matrix product, saving up to 0.5 ms per model call on Timestral-123M. load_model reorders the checkpoint's QKV weights from (qkv, head_dim, heads) to (qkv, heads, head_dim) and appends the gate weights.
  • Variate attention, which runs over the few variates of one series, uses a plain matrix product and softmax. On sequences this short it is 3 to 4 times faster than MLX's fused attention kernel.
  • Apple GPUs have no float64. To keep the normalisation statistics on the GPU, they are computed in float32: each row is shifted by its first observed value before the sums, and per-patch statistics are combined with a log-depth scan. timestral computes them in float64.
  • mx.compile compiles the transformer layers, saving 5 to 10% of their time, and the refine step that runs after each decoded block, saving about 10% on forecasts of more than one block.

The first two changes also apply to timestral's PyTorch code.

Precision

On M5-class GPUs, MLX computes float32 matrix products at reduced (TF32-class) precision by default. It is faster than full float32 and moves forecasts by up to about 1e-2 of their largest value. For full float32, set MLX_ENABLE_TF32=0 before your program's first MLX computation:

MLX_ENABLE_TF32=0 python my_forecast.py

Forecasts then match timestral's within 1e-4 of their largest value.

Development

uv run pytest            # compare every module with timestral, on a tiny model and Timestral-5M
uv run pytest -m slow    # compare forecasts on Timestral-123M
uv run python bench.py   # time and memory against timestral

Licence

Apache License 2.0. The code is a port of timestral (Copyright Mistral AI); see NOTICE. The model weights are distributed by Mistral AI under their own licence on the Hugging Face Hub.

Metadata

Release files for timestral-metal 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for timestral-metal 0.1.0
File Size Uploaded Provenance Actions
timestral_metal-0.1.0.tar.gz 28.2 kB With provenance Details for timestral_metal-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for timestral-metal 0.1.0
File Interpreter ABI Platform Actions
timestral_metal-0.1.0-py3-none-any.whl Python 3 none any Details for timestral_metal-0.1.0-py3-none-any.whl

Total release size: 60.9 kB

Release files / timestral_metal-0.1.0.tar.gz

Download URL timestral_metal-0.1.0.tar.gz
Size 28.2 kB
Tags Source
SHA-256 checksum
How to use checksums
fbc817095a835cf94e266eb42365c75cf7667334fdbafcd93e6d616b481660d5
BLAKE2b-256 checksum
How to use checksums
80f398cc7941d07b6742b51cbe21b01771fe31b255e07b694623bc2534e60295
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Release files / timestral_metal-0.1.0-py3-none-any.whl

Download URL timestral_metal-0.1.0-py3-none-any.whl
Size 32.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fb066c3b828f9261f888582cb00c66376dd39250f36e2af9065aecc95caeb97e
BLAKE2b-256 checksum
How to use checksums
1e9f44b45290525b2d980965472dcfa5c22d906ad55be0ccad830e60924c466d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

Security for timestral-metal 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for timestral_metal-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page