Metadata-Version: 2.4
Name: h2ofm
Version: 0.42.0
Summary: H2O.ai Foundation Models — standalone inference
Author: H2O.ai
License-Expression: Apache-2.0
Project-URL: Homepage, https://h2oai.com/
Keywords: foundation models,time series,forecasting
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY.md
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.0
Requires-Dist: torch<3,>=2.10
Requires-Dist: safetensors>=0.6.2
Requires-Dist: huggingface-hub>=0.34
Dynamic: license-file

# h2ofm — H2O.ai Foundation Models

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

```bash
pip install h2ofm
```

## Quick Start

```python
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:

| Input shape            | `point` shape        | `quantiles` shape            |
| ---------------------- | ---------------------- | ------------------------------ |
| `(history,)`         | `(horizon,)`         | `(horizon, levels)`          |
| `(targets, history)` | `(targets, horizon)` | `(targets, horizon, levels)` |

`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:

```python
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:

```python
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:

| Option                     | Behavior                                                                                                                                                           |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `context_length`         | Shorten the checkpoint's context window.                                                                                                                           |
| `autoregressive=None`    | Use the checkpoint's default. `True` decodes beyond `max_horizon` in blocks; `False` uses one pass.                                                           |
| `quantile_levels`        | Distinct levels between 0 and 1; levels outside the trained 0.1–0.9 grid use Gaussian-tail extrapolation.                                                         |
| `flip_equivariant=False` | Set to `True` to make a flipped history always produce a flipped forecast. No extra pass for natively equivariant checkpoints; otherwise roughly doubles inference time. |
| `clip_nonnegative=False` | Set to `True` to clamp forecasts at zero for targets with nonnegative histories. Applied last.                                                                    |

## Model Checkpoints

| Name                        | Parameters | Multi-target | Past covariates | Future covariates | Flip equivariant |
| --------------------------- | ---------- | ------------ | --------------- | ----------------- | ---------------- |
| `h2oai/timeh2o-v1-tiny`     | 5.8M       | independent  | No              | No                | Yes              |

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.
