StaticfromCreate a TimesFM model from a pretrained ONNX checkpoint.
The model architecture is resolved from the model-descriptor.json
co-located with the ONNX file. When no descriptor is found, the
engine falls back to the canonical TimesFM 2.5 200M config.
Path to ONNX model file. Required.
OptionalexecutionProvider?: "cpu" | "cuda" | "dml"Execution provider: 'cpu' | 'cuda' | 'dml' (default 'cpu').
Optionalprecision?: ModelPrecisionHint for which precision variant to load. The engine itself does not branch on precision — ONNX Runtime transparently executes QDQ (INT8) graphs. This field is informational metadata forwarded from the model descriptor for logging and diagnostics.
Optionalengine?: IInferenceEngineOptional pre-built inference engine for dependency injection.
When provided, the engine is used as-is (already loaded). When omitted, @agentix-e/timesfm-node is dynamically imported to create the default engine. Install @agentix-e/timesfm-node for the Node.js ONNX Runtime backend,
Web use case: Pass a TimesFMWebInferenceEngine from @agentix-e/timesfm-web to run TimesFM in the browser with onnxruntime-web.
Testing use case: Inject a mock engine for isolated unit testing.
import { TimesFMWebInferenceEngine } from '@agentix-e/timesfm-web';
const webEngine = new TimesFMWebInferenceEngine(modelConfig);
await webEngine.load('https://example.com/timesfm-2.5.onnx');
const model = await TimesFMModel.fromPretrained({
modelPath: 'https://example.com/timesfm-2.5.onnx',
engine: webEngine,
});
OptionalcacheDir?: stringCustom cache directory for downloaded models.
Optionalproxy?: { url: string; username?: string; password?: string }Proxy configuration for model download in restricted network environments.
IMPORTANT: This field is forwarded to downloadModel only when
called explicitly. fromPretrained() itself does not download
models — it requires an existing modelPath. If you use the separate
downloadModel() function to obtain the model before calling
fromPretrained(), pass your proxy config directly to downloadModel().
import { downloadModel, TimesFMModel } from '@agentix-e/timesfm-core';
const modelPath = await downloadModel({
proxy: { url: 'http://proxy:8080', username: 'user', password: 'pass' },
});
const model = await TimesFMModel.fromPretrained({ modelPath });
Priority: this option → TIMESFM_PROXY_URL env var → HTTPS_PROXY env var.
For security, prefer passing the password via the TIMESFM_PROXY_PASSWORD
environment variable instead of embedding it in this config object.
The password field is accepted as a convenience for programmatic use
but will NOT be logged or serialized.
OptionalskipWarmup?: booleanWhen true, the warmup inference (triggered during load()) is skipped.
This is intended for benchmarking where the caller wants to measure
the true cold-start (first-inference) latency separately. Production
callers should leave this at the default (false) so that the first
user-facing forecast() call benefits from JIT-compiled execution plans.
OptionalintraOpNumThreads?: numberNumber of threads for intra-op parallelism in ONNX Runtime.
Controls intraOpNumThreads in the ONNX Runtime session options.
Set to 0 to let ONNX Runtime auto-detect (default). Higher values
improve throughput on multi-core CPUs but increase memory usage.
Recommendations:
Compile the model with the given forecast configuration.
This must be called before forecast(). It validates and normalises
the config and sets up batch-size calculations.
this for method chaining.
Forecast a batch of univariate time series.
Number of future time points to forecast.
List of 1-D time series. Each can have different length. May contain NaN values (leading NaNs are stripped, internal NaNs are linearly interpolated).
Optionaloptions: ForecastCallOptionsOptional AbortSignal and progress callback.
Point forecasts + quantile forecasts.
Forecast with exogenous covariates via @agentix-e/timesfm-xreg.
Internally caches the dynamic import of the optional peer dependency so that repeated calls avoid re-resolution overhead.
Concurrent safety: uses a Promise-based singleton pattern so that multiple concurrent first-time calls share a single import() and import failures are retried on subsequent calls.
Public interface for TimesFMModel.
Enables dependency injection and testing while maintaining a stable contract.