h2ofm — H2O.ai Foundation Models

Standalone inference for TimeH2O time-series models. Python 3.12+; CPU and CUDA.

pip install h2ofm

Quick Start

import numpy as np
from h2ofm import TimeH2O

model = TimeH2O.from_pretrained("h2oai/timeh2o-v1-tiny")
forecast = model.forecast(np.sin(np.arange(200) / 10), horizon=24)

forecast.point  # (24,), median forecast; also forecast.median
forecast.quantiles  # (24, 9), default levels 0.1 through 0.9
forecast.quantile(0.9)  # (24,)

Loading defaults to device="auto" (CUDA if available, otherwise CPU). Set batch_size at load time (default 256): it counts target and covariate rows, not series. Checkpoints without cross-variate attention drop covariate rows first, so there only targets count. Checkpoint settings are available through model.config.

Array Forecasts

forecast(context, horizon=...) returns a Forecast with CPU NumPy arrays:

forecast_many(contexts, horizon=...) forecasts several independent series in one pass. It takes a list of series, with possibly different history lengths, and returns one Forecast per series in input order:

import numpy as np
from h2ofm import TimeH2O

contexts = [np.sin(np.arange(n) / 10) for n in (200, 150, 300)]

model = TimeH2O.from_pretrained("h2oai/timeh2o-v1-tiny")
forecasts = model.forecast_many(contexts, horizon=24)

len(forecasts)  # 3
forecasts[0].point  # (24,)
forecasts[0].quantiles  # (24, 9)

For array inputs, the first axis is the batch: a 2D array batches univariate series; a 3D array batches multi-target series.

quantile_levels selects output levels (default 0.1 through 0.9) and their order on the last axis. Point forecasts are always medians. NaN marks missing observations; all-missing targets use a zero-valued cold start.

Covariate arguments:

• past_covariates: values observed over the history only, shaped (history,) or (covariates, history). Ignored by checkpoints without past-covariate support.
• future_covariates: known values spanning history + horizon, shaped (history + horizon,) or (covariates, history + horizon).
• For forecast_many, pass one covariate entry per series, using None where absent.
• A covariate row is numeric when its dtype is numeric and not boolean. Rows of any other dtype (strings, objects, booleans, pd.Categorical) are categorical and encoded exactly as the matching forecast_df column, with None/NaN as a missing label. Pass mixed covariates as a list of rows, e.g. [prices, holiday_names].

Checkpoints without cross-variate attention ignore covariates with a warning.

Dataframe Forecasts

Generate 100 days of two series with different periods and forecast the next 24 days:

import numpy as np
import pandas as pd

from h2ofm import TimeH2O

history, horizon = 100, 24
days = np.arange(history)
dates = pd.date_range("2026-01-01", periods=len(days), freq="D")

frames = []
for item, period in [("weekly", 7), ("monthly", 30)]:
    value = np.sin(2 * np.pi * days / period)
    frames.append(pd.DataFrame({"item": item, "date": dates, "value": value}))
context = pd.concat(frames, ignore_index=True)

model = TimeH2O.from_pretrained("h2oai/timeh2o-v1-tiny")
predictions = model.forecast_df(
    context,
    horizon=horizon,
    target="value",
    id_column="item",
    time_column="date",
)
print(predictions.head())

target is one column name or a list of target column names (default "target"). Without id_column, the frame is one series; without time_column, rows stay in input order. The time column may contain datetimes or integer values representing time steps. Integer times are never converted to dates; forecast rows continue them at the inferred step, or at an integer freq.

context contains only history, including trailing missing measurements or all-missing series. An integer horizon generates that many future steps per item, and every covariate is past-only.

To supply future covariates, pass a horizon frame as horizon instead. Target columns in it must be absent or entirely missing. Every covariate column in the horizon frame is future-known, even when all its horizon values are missing (a missing categorical value is itself informative, e.g. "no holiday"); leave past-only covariates out of it, and timeh2o-v1 ignores them. Partial missingness is allowed, including items with no known values for a covariate.

For panels, both frames must contain the same IDs, and every item in the horizon frame must have the same number of rows. That count sets the horizon. Future timestamps must continue each history at its inferred frequency (or the explicit freq), even without future covariates. Without time columns, rows retain their per-item input order. Neither input frame is mutated.

Output columns: the supplied ID and time columns (or step, 1 to horizon, when no time column is given), target_name, predictions (median), and one column per quantile, e.g. "0.1". freq overrides inferred frequency: a pandas offset alias for datetimes, the integer step between time values for an integer time column.

Forecast Options

All three forecast methods accept:

Model Checkpoints

Multi-target modes, both forecasting the targets of an item in parallel:

• independent: each target is forecast from its own history, as if the targets were separate independent series.
• multivariate: the targets are forecast as one multivariate series.

Past and future covariates are always validated, but a checkpoint only uses the kinds it supports. The others are ignored with a warning.

Flip-equivariant checkpoints honor flip_equivariant=True without an extra forecast pass; see Forecast Options.

License

Apache-2.0; see the LICENSE file in the distribution. Upstream attribution: THIRD_PARTY.md, shipped alongside it. Model weights are downloaded and licensed separately.