Timestral CoreAI

Run Mistral Timestral time-series forecasting on an Apple silicon Mac using the native Apple CoreAI framework. This independent port converts all four existing Timestral MLX FP32 checkpoints through a PyTorch export bridge into .aimodel assets. Checkpoint loading preserves trained tensor values and layouts; no training or quantization is performed. CoreAI may rearrange its internal tensor storage, which is checked through numerical parity rather than a byte comparison of compiled constants.

Original models: Mistral Timestral collection. Source port: Timestral MLX. Export follows Apple coreai-torch and the local coreai-models recipes.

For native applications and sustained batches, use TimestralKit, the Swift SDK. It provides a bounded queue, warm CoreAI worker pool, loading/offload, cancellation, memory limits, and streaming bulk processing. Its AI skill teaches integration and operation.

Download

The public repository includes all four portable FP32 model bundles, the Python package and wheel, the native Swift package, the AI skill, original licenses and source references, tests, and accepted validation evidence. Local build caches, development environments and diagnostic dumps are excluded.

Download the whole release with the Hugging Face CLI:

python3 -m pip install huggingface_hub
hf download jbilcke/timestral-coreai --local-dir ./timestral-coreai

To download just the SDK, Python runtime and smallest model, use:

hf download jbilcke/timestral-coreai --local-dir ./timestral-coreai \
  --include "5M/**" "Package.swift" "swift/**" "skills/**" \
  "timestral_coreai/**" "examples/**" "pyproject.toml" "requirements*.txt" \
  "README.md" "LICENSE*" "NOTICE" "models.json" "release-manifest.json" "SHA256SUMS"

Replace 5M/** with another variant, and use --revision <trusted-commit-SHA> for a reproducible download. Model loading is offline. The SDK uses native CoreAI CPU on macOS 27+; Python is only needed for the Python runtime or optional download/validation tooling.

For Swift, build from the downloaded repository root:

cd timestral-coreai
swift build -c release -j 2
TIMESTRAL_SWIFT_BIN="$(swift build -c release --show-bin-path)"
"$TIMESTRAL_SWIFT_BIN/timestral" demo --bundle ./5M --horizon 96

See the SDK guide for SwiftPM integration and the measured results for warm/cold timings and the 1,000-request benchmark. In that benchmark, 5M completed 1,000 forecasts in 3.13 seconds with a sampled worker-memory peak of 61 MiB; the documented 64-to-32 workload disables symmetric averaging. A separate warmed forecast with default symmetry took 6.22 ms. These measurements apply to the recorded machine, shapes and settings.

Verified bundles and Python runtime

All four bundles passed nine forecast cases against both the MLX port and original Mistral implementation on native CoreAI CPU, including the full 32,768-step context. The table gives the worst normalized RMSE across both references; the acceptance limit is 1e-4.

Model Bundle size CoreAI stages Worst normalized RMSE
5M 20.06 MiB 10 3.07e-6
28M 106.40 MiB 14 3.15e-6
123M 468.14 MiB 22 6.03e-6
209M 798.97 MiB 26 1.19e-6

models.json records the verified manifests, report hashes, source hashes and numerical results. All four also passed exact context-truncation checks with no Torch/MLX imports in either parent or native worker. The final guarded validation and smoke runs recorded a maximum combined process RSS of 1.77 GiB and at least 9.07 GiB of available system memory. These sampled values describe these fixtures, not a bound for arbitrary batch sizes.

Python requirements and quick start

Use an Apple silicon Mac running macOS 27 or later, Python 3.11 or later, and the bundled coreai-core==1.0.0b3 dependency. This checkout was developed on macOS 27.0.1 with Python 3.12.12. Runtime model specialization writes to Apple's per-user model cache; a process restricted to writing only inside this checkout must be granted cache access.

cd timestral-coreai
python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
python examples/forecast.py ./5M --horizon 96

The four model directories (5M/, 28M/, 123M/, 209M/) are separate from the Python package. Keep the selected directory alongside your application or point to its absolute path. Loading is offline and verifies each bundle's file sizes and SHA-256 checksums.

import numpy as np
from timestral_coreai import TimestralForecaster

context = np.sin(np.arange(512, dtype=np.float32) * 2 * np.pi / 24)
with TimestralForecaster.from_pretrained("./5M") as forecaster:
    forecast = forecaster.forecast(context, prediction_length=96)

print(forecast.quantiles.shape)  # (1, 1, 96, 21)
print(forecast.median.shape)     # (1, 1, 96)
print(forecast.quantile(0.9))

Keep a forecaster open across calls, including changing input shapes. Each neural invocation uses a fresh worker process that loads, executes, and releases one CoreAI stage at a time, then exits. This also releases CoreAI's process-wide caches between positive/negative and autoregressive calls. A context manager or forecaster.close() releases the runtime. The synchronous interface also works from an existing Python event loop, such as a notebook.

Forecast behavior

Inputs accept (T,), (B,T) or (B,V,T). NaN marks missing values, and observation_mask can mask additional observations. Contexts are left-padded to 32-step patches and truncated to the most recent 32,768 steps. Outputs are NumPy float32 quantiles (B,V,H,21) at levels 0.01, 0.05, 0.10, โ€ฆ, 0.95, 0.99. Horizons longer than 1,024 steps use median block feedback.

Symmetric averaging and clipping of forecasts for nonnegative observed contexts are enabled by default, as in the source port. Disable them with symmetric_averaging=False and clip_nonnegative=False.

Numeric and categorical covariates retain the source API:

with TimestralForecaster.from_pretrained("./5M") as forecaster:
    forecast = forecaster.forecast(
        context, 96,
        past_covariates=past,       # (B,C_past,T)
        known_covariates=known,     # (B,C_known,T+96)
        categorical_past_covariates=past_codes,
        categorical_known_covariates=known_codes,
    )

Categorical inputs are numeric codes, with NaN for missing values. Codes remain float64 during target encoding, retaining large category IDs. Known binary indicators keep the original normalization rule. Attention masks isolate independent batches and keep covariates exogenous.

The exported graph supports up to 256 packed rows (targets plus covariates across the batch) and up to 1,056 patches per stream, including the extended covariate stream. This covers the trained context and 32-patch forecast block. Very large multivariate batches can require substantial memory because attention masks scale quadratically; the row bound is a graph limit, not a memory-capacity guarantee.

What runs where

CoreAI executes patch embedding, gated time/variate attention, partial RoPE, SwiGLU, RMSNorm, and the monotone quantile head. Each bundle contains an embedding asset, one asset per transformer block, and a final normalization/head asset. The worker copies FP32 activations between stages and releases each native executable before loading the next. Only the final quantiles return to the parent process. NumPy retains packing, masks, categorical encoding, normalization, denormalization, and advancing-frame refinement. Causal and advancing statistics stay in float64.

PyTorch and MLX are not runtime dependencies and are not imported during forecasting. PyTorch is used to author/export the graph; MLX and original Mistral PyTorch are reference implementations for validation. Neural inference uses native CoreAI on the CPU (compute_unit="cpu"). GPU/Neural Engine execution is not supported by this port on the tested macOS build.

Three export choices preserve correctness and limit memory: separate encoder/decoder time attention with explicit scaled matmul/softmax, materialized gathers instead of dynamic decoder slices, and two-dimensional linear projections instead of broadcasting weight matrices across sequence positions. The trained tensor values and layouts are unchanged. Stage boundaries keep the full graph's intermediates from remaining live together.

The .aimodel assets expose a prepared neural-network interface, not raw time-series inputs. Both the Python wrapper and native Swift SDK provide the complete forecasting pipeline. The Swift implementation uses Double statistics and native CoreAI worker processes without a Python runtime. iPhone/iPad validation remains outside this Mac-first release.

Reproduce conversion and validation

Conversion reads verified local MLX bundles and strictly loads every FP32 tensor with unchanged layouts and names. Each output bundle preserves the original license, model card, source revisions and checksums, along with the export tool versions and source hashes.

python -m pip install -e '.[conversion,validation]'
python -m pytest -q

# Run one variant per process. Repeat for 28M, 123M and 209M.
python scripts/run_guarded.py --report reports/guard-export-5M.json -- \
  python scripts/convert.py 5M --source ../timestral-mlx

# Prepare references separately, so their models are not resident during CoreAI checks.
python scripts/run_guarded.py --report reports/guard-reference-5M.json -- \
  python scripts/validate.py 5M --extended \
  --prepare-reference-cache reports/reference-cache \
  --upstream references/timestral-a534bdbd244d64f3d9d743f46c7bf6fc330ed4ff/src

python scripts/run_guarded.py --report reports/guard-validation-5M.json -- \
  python scripts/validate.py 5M --extended --compute-unit cpu \
  --reference-cache reports/reference-cache \
  --upstream references/timestral-a534bdbd244d64f3d9d743f46c7bf6fc330ed4ff/src

python scripts/run_guarded.py --report reports/guard-smoke-5M.json -- \
  python scripts/smoke.py 5M --report reports/smoke-5M.json

Conversion refuses to overwrite existing bundles unless --overwrite is supplied. It refuses to overwrite the source checkpoint directory.

The guard defaults to a 120-second time limit, a 4 GiB process-memory ceiling, and a 6 GiB available-system-memory reserve. It stops the child process when a budget is crossed and records the reason. It samples memory, so these are monitoring limits, not hard allocation caps. Avoid concurrent conversion or validation jobs. A stopped or incomplete report is not a successful validation.

The original Mistral source at revision a534bdbd244d64f3d9d743f46c7bf6fc330ed4ff is retained under references/, with archive provenance in references/provenance.json. Reference preparation loads the same trained values into the original architecture, reversing only the MLX parameter-name change from ._gate. to .gate.. Cached fixtures verify inputs, source hashes and array checksums before use; native validation loads neither MLX nor PyTorch.

Reconversion, Python reference regeneration, and Python catalog revalidation also require the matching Timestral MLX release in the sibling ../timestral-mlx directory, or an explicit --source path. Check its source and checkpoint hashes against the retained reports. Ordinary inference does not need that sibling checkout. Native Swift reference validation uses the included portable swift/Fixtures/ and does not need MLX checkpoints.

Reports in reports/ record finite ordered quantiles, output shapes, normalized RMSE, normalized maximum error, PSNR, environment versions, and code/bundle hashes. FP32 acceptance requires normalized RMSE โ‰ค 1e-4 and normalized maximum error โ‰ค 2e-3. The seven deterministic fixtures cover missing data, batched multivariate inputs, numeric/categorical covariates, 1,057-step autoregression, constant data, and entirely missing contexts. The --extended checks add a one-step context/horizon and full-context numerical parity. The smoke check separately covers full context, exact truncation, and inference without PyTorch/MLX imports.

After validating all four variants, regenerate the catalog with python scripts/summarize_validation.py --output models.json. It checks current code, bundles, references and all nine cases before writing an accepted catalog. See reports/README.md for the final evidence and the distinction from earlier diagnostic runs.

These synthetic comparisons establish implementation parity, not real-world forecast accuracy. No GIFT-Eval, TIME, or fev-bench evaluation was rerun. Reported timings include initial compilation and are not performance benchmarks. Ahead-of-time coreai-build is optional and was unavailable in this Xcode installation; the native runtime compiles/specializes assets when loaded.

Licenses

Source code is Apache-2.0; see LICENSE and NOTICE. The weights retain Mistral AI's original Modified MIT license, copied verbatim to LICENSE-WEIGHTS and each bundle's LICENSE. Consult that license for its terms and revenue restriction. The code license does not relicense the weights.

This is an independent community conversion, not an official Mistral or Apple release. The public release is hosted at jbilcke/timestral-coreai.

release-manifest.json inventories the public files with repository-relative paths; SHA256SUMS covers the release files. Historical validation reports retain the exact original workspace paths and hashes as provenance. Those paths are not installation requirements: use the downloaded model directories and your own worker executable URL. The Swift SDK is shipped as source and built on the target Mac; the Python wheel contains only the Python package. See reports/README.md for the evidence boundaries.

Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. ๐Ÿ™‹ Ask for provider support

Model tree for jbilcke/timestral-coreai

Finetuned
(3)
this model