diff --git a/MANIFEST.in b/MANIFEST.in
index 5457f1c..8ff5dff 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,2 +1,3 @@
include examples/forecast.py tests/conftest.py tests/distribution.py
+include examples/history.csv
include uv.lock .python-version
diff --git a/README.md b/README.md
index 7a96137..fef216f 100644
--- a/README.md
+++ b/README.md
@@ -32,8 +32,9 @@
pip install continuousintelligence
```
-Forecast the next day of bicycle rentals from five observed days of hourly demand
-in Washington, D.C. The example history is included with the package:
+Pass a PyTorch tensor, NumPy array, pandas DataFrame, or CSV file to `model.forecast`.
+The example below uses the bundled bicycle-rental data from Washington, D.C.,
+to forecast the next 24 hours from five days of hourly demand:
```python
import continuousintelligence as ci
@@ -98,69 +99,198 @@ you can try it.
## Usage details
-Forecast inputs and outputs
+Usage details
-Call `model.forecast(history, horizon=320)` with a two-dimensional PyTorch tensor. Rows
-are target variables and columns are consecutive time steps. Rows are forecast jointly by
-default. Supply `series_ids` to treat them as a cohort of independent univariate series.
+### Prepare your history
-In the table below, `V` is the number of target variables, `T` is the history length,
-`H` is the requested horizon, and `Q` is the number of quantile levels.
+History is the observed data you want to forecast from. ci-proto works with regularly
+sampled data, can forecast multiple variables together, and can handle missing data.
+Use `NaN` for missing values. The following formats are supported for the history:
-| Value | Shape or type | Description |
-| --- | --- | --- |
-| `history` | `[V, T]` | Observed target values. Use `NaN` for missing observations. |
-| `horizon` | `int` | Number of future steps to predict. Any positive integer; defaults to 320. |
-| Returned forecast | `[V, Q, H]` | CPU `float32` tensor in the original target units, ordered by quantile level. |
-| `model.quantiles` | `[Q]` | CPU tensor containing the probability level for each output quantile. |
+**PyTorch tensors and NumPy arrays** with shape `[variables, time]`: one row per variable,
+with observations running from left to right. This example has two variables and four
+time steps:
+
+```python
+import numpy as np
+import torch
+
+values = [[12, 9, 7, 6], [8, 6, 5, 4]]
+history = np.array(values)
+# Or use a tensor with the same layout.
+history = torch.tensor(values, dtype=torch.float32)
+```
+
+**pandas DataFrames** with one column per variable and one row per time step. The same
+data looks like this:
+
+```python
+import pandas as pd
+
+history = pd.DataFrame(
+ {
+ "store_a": [12, 9, 7, 6],
+ "store_b": [8, 6, 5, 4],
+ }
+)
+```
+
+A pandas Series, such as `history["store_a"]`, can be used to forecast a single variable.
+
+**CSV files** with the same layout as a DataFrame. Include a header naming the variables:
+
+```csv
+store_a,store_b
+12,8
+9,6
+7,5
+6,4
+```
+
+Pass the file path as history.
+
+```python
+history = "examples/history.csv"
+```
+
+### Make a forecast
-Input tensors can be real values or `NaN`. ci-proto returns nine quantiles
-between 0.1 and 0.9 in increments of 0.1. Histories up to 16,384 observations use the
-standard checkpoint. Longer histories automatically use the long checkpoint with the full
-supplied history. The median is the central quantile.
+Once you have your history, load the model and choose how many future steps to predict:
+
+```python
+import continuousintelligence as ci
+
+model = ci.load_model("ContinuousIntelligence/ci-proto")
+prediction = model.forecast(history, horizon=24)
+```
+
+`horizon` can be any positive integer and defaults to 320. For example, when forecasting hourly data, a horizon of
+24 predicts the next day. By default, all of the variables are forecast together. If you want independent forecasts, pass each variable in a separate call.
+
+### Read the forecast
+
+ci-proto returns nine quantiles from 0.1 to 0.9. The 0.5 quantile is the median forecast with the other quantiles describing the predicted range of value. All forecast values are `float32` in the original units.
+
+The output depends on the history format. Here, `V` is the number of variables, `T` is
+the history length, `H` is the horizon, and `Q` is the number of quantiles.
+
+| History | Returned forecast |
+| --- | --- |
+| PyTorch tensor | Tensor `[V, Q, H]` on the input tensor's device. |
+| NumPy array | Array `[V, Q, H]`. |
+| pandas DataFrame, Series, or CSV path | DataFrame with `H` rows and `(variable, quantile)` columns. A Series supplies its name as the variable label. |
+
+To extract the median from a DataFrame forecast or save all quantiles to CSV:
+
+```python
+median = prediction.xs(0.5, level="quantile", axis=1)
+prediction.to_csv("forecast.csv")
+```
-Covariates and categorical inputs
+Dates and frequency
-Pass covariates as keyword arguments to
-`model.forecast(..., past_covariates=..., future_covariates=...)`. Only the variables in
-`history` receive forecasts. Align all tensors to the same time axis before calling the
-model.
+Dates are used automatically to provide calendar information, such as the hour and day
+of the week.
-| Argument | Shape | Requirements |
+**PyTorch tensors and NumPy arrays**
+
+Using the tensor or NumPy history from above, supply dates for both the history and
+the forecast horizon with `timestamps` and `freq`:
+
+```python
+import pandas as pd
+import torch
+
+dates = pd.date_range("2026-11-01", periods=history.shape[1] + 24, freq="h")
+prediction = model.forecast(
+ history,
+ horizon=24,
+ timestamps=torch.tensor(dates.as_unit("ns").asi8),
+ freq="h",
+)
+```
+
+**pandas DataFrames**
+
+For a DataFrame, you can attach them with a `DatetimeIndex`:
+
+```python
+history.index = pd.date_range("2026-11-01", periods=len(history), freq="h")
+```
+
+**CSV files**
+
+For a CSV file, dates go in a `timestamp` column:
+
+```csv
+timestamp,store_a,store_b
+2026-11-01T00:00:00,12,8
+2026-11-01T01:00:00,9,6
+2026-11-01T02:00:00,7,5
+2026-11-01T03:00:00,6,4
+```
+
+The [example CSV](examples/history.csv) contains two series with hourly timestamps:
+
+```python
+prediction = model.forecast("examples/history.csv", horizon=24)
+```
+
+The timestamp arguments use the following shapes, with `T`, `H`, and `V` as defined above:
+
+| Argument | Shape or type | Description |
| --- | --- | --- |
-| `past_covariates` | `[past_variables, T]` | Must have exactly the same history length as `history`. |
-| `future_covariates` | `[known_variables, T + H]` | Must cover both the observed history and the requested forecast horizon. |
-| `categorical_past` | Tuple of row indices | Selects categorical rows in `past_covariates`; defaults to `()`. |
-| `categorical_future` | Tuple of row indices | Selects categorical rows in `future_covariates`; defaults to `()`. |
+| `timestamps` | `int64` tensor `[T + H]` or `[V, T + H]` | Epoch nanoseconds covering history and horizon, in increasing order. |
+| `freq` | String | Sampling frequency, such as `"h"`, `"D"`, or `"W"`. Inferred from dated pandas and CSV inputs when possible. |
-Represent categorical values with numeric category codes. For example,
-`categorical_future=(0, 2)` marks its first and third rows as categorical.
-Boolean covariates can be supplied as numeric
-inputs without marking them categorical. Use `NaN` for missing covariate observations.
+For gaps in a regular history, insert the missing time steps and use `NaN` for their values. For uneven histories, left-pad values with `NaN` and timestamps with `torch.iinfo(torch.int64).min`.
-Timestamps and related series
+Covariates and categorical inputs
-Pass optional metadata to add calendar features or context from related series.
+Covariates are extra inputs that can help explain the variables in your history. Past
+covariates contain observations available up to the forecast origin. Future covariates
+contain values known for both the history and forecast horizon, such as a planned promotion.
-| Argument | Shape or type | Description |
+Pass them to `model.forecast` as `past_covariates` and `future_covariates`. They accept
+the same formats and layouts as history. Align all inputs to the same time axis. Only
+the variables in `history` receive forecasts. History also determines the output format
+and device.
+
+| Argument | Shape | Requirements |
| --- | --- | --- |
-| `timestamps` | `int64` tensor `[T + H]` or `[V, T + H]` | Epoch nanoseconds covering history and horizon. Must increase strictly. |
-| `freq` | String | Pandas frequency, such as `"h"`, `"D"` or `"W"`. Required for calendar features. |
-| `series_ids` | `V` unique strings | Identifies independent series in input row order. |
-| `static_features` | Mapping of column names to `V` values | Optional grouping metadata, such as `{"region": ["north", "south"]}`. Requires `series_ids`. |
+| `past_covariates` | `[past_variables, T]` | Must have exactly the same history length as `history`. |
+| `future_covariates` | `[known_variables, T + H]` | Must cover both the observed history and the requested forecast horizon. |
+| `categorical_past` | Tuple of variable indices | Selects categorical variables in `past_covariates`; defaults to `()`. |
+| `categorical_future` | Tuple of variable indices | Selects categorical variables in `future_covariates`; defaults to `()`. |
+
+A categorical covariate describes a category, such as the type of promotion running in
+a store. For example, `0` could mean no promotion, `1` an email campaign, and `2` a discount.
+These numbers identify categories rather than quantities.
+
+```python
+history = pd.DataFrame({"sales": [12, 9, 7, 6]})
+future_covariates = pd.DataFrame({"promotion_type": [0, 0, 1, 2, 1, 0]})
+prediction = model.forecast(
+ history,
+ horizon=2,
+ future_covariates=future_covariates,
+ categorical_future=(0,),
+)
+```
-Pass all related series together. Context is shared only between series with the same
-forecast origin. Covariates can be shared across series or supplied per series as
-`[V, covariates, time]`.
+The first four rows of `future_covariates` cover the history and the last two cover the
+forecast horizon. `categorical_future=(0,)` marks the first covariate as categorical.
+Indices refer to tensor/array rows or pandas/CSV columns, starting from zero.
+Use `categorical_past` in the same way for past covariates.
-For uneven histories, left-pad values with `NaN` and timestamps with
-`torch.iinfo(torch.int64).min`.
+Boolean covariates can be supplied as numeric inputs without marking them categorical.
+Use `NaN` for missing covariate observations.
@@ -196,6 +326,9 @@ returns it. Hugging Face models always include it; local bundles may omit it.
For reproducibility, pin Hugging Face models with a full commit SHA. `revision` applies
only to Hub loading. Use `./` or a `Path` object to identify local paths explicitly.
+Histories up to 16,384 observations use the standard checkpoint. Longer histories
+automatically use the long checkpoint with the full supplied history.
+
@@ -218,8 +351,10 @@ Fused inference requires CUDA-enabled PyTorch, an Ampere-or-newer NVIDIA GPU, a
580-series-or-newer driver, and a host C++ compiler. Replace CPU-only PyTorch to enable
GPU inference.
-Inspect `model.device` and `model.backend`: `"mamba3"` means fused CUDA inference;
-`"torch"` means the portable backend. Forecast outputs are always CPU tensors.
+Inference runs on `model.device`. Tensor forecasts return on the input tensor's device,
+including its CUDA device index. NumPy and pandas outputs are on the CPU.
+
+`model.backend` is `"mamba3"` for fused CUDA inference or `"torch"` for the portable backend.
Reference results use H100 with PyTorch `2.13.0+cu130`. Reduced-precision results can vary
across runtimes.
@@ -227,11 +362,11 @@ across runtimes.
-Other data and plotting options
+Plotting forecasts
-`ci.plot_forecast(history, prediction, quantiles)` works with your own data:
-history has shape `[variables, time]`, predictions `[variables, quantiles, horizon]`,
-and the quantile levels form a sorted vector including `0.5` for the median.
+`ci.plot_forecast(history, prediction, quantiles)` accepts tensors: history has shape
+`[variables, time]`, predictions `[variables, quantiles, horizon]`, and quantile levels
+form a sorted vector including `0.5` for the median.
Each variable gets its own panel with the median and available nested quantile bands.
The function returns a Matplotlib figure; `output` saves it to a file. Pass `timestamps`
covering history plus horizon for a date axis, and `ylabel` to label the values.
@@ -248,9 +383,9 @@ python examples/forecast.py --model ContinuousIntelligence/ci-proto
The plot is saved to `outputs/forecast.png`.
-To forecast another source, pass `--data` with a CSV file and name its columns with
-`--time-column` and `--value-column`. If the file has a `split` column, rows marked
-`history` are observed and the following rows marked `forecast` set the horizon.
+The plotting script reads CSV files using its own column options. Pass `--data` and name
+the columns with `--time-column` and `--value-column`. If the file has a `split` column,
+rows marked `history` are observed and the following rows marked `forecast` set the horizon.
Otherwise every row is history; pass `--horizon`, and future timestamps continue the
inferred frequency. `--ylabel` sets the axis label.
@@ -278,7 +413,7 @@ calibration run automatically without changing model weights.
| `target_encode_categoricals` | Encodes categories using observed target statistics. |
| `clip_nonnegative` | Keeps forecasts nonnegative when the observed history is nonnegative. |
| `integer_round` | Rounds forecasts when the observed history contains only integers. |
-| `calendar_covariates` | Adds calendar features when timestamps and frequency are supplied. |
+| `calendar_covariates` | Adds calendar features from dates and frequency. |
| `bfloat16` | Enables reduced-precision inference; `false` uses float32. |
Edit a local `tta.json` to change these flags. Encoding, clipping, rounding, calendar
diff --git a/examples/history.csv b/examples/history.csv
new file mode 100644
index 0000000..c8c5d17
--- /dev/null
+++ b/examples/history.csv
@@ -0,0 +1,25 @@
+timestamp,store_a,store_b
+2026-11-01T00:00:00,12,8
+2026-11-01T01:00:00,9,6
+2026-11-01T02:00:00,7,5
+2026-11-01T03:00:00,6,4
+2026-11-01T04:00:00,8,5
+2026-11-01T05:00:00,14,9
+2026-11-01T06:00:00,25,18
+2026-11-01T07:00:00,42,31
+2026-11-01T08:00:00,58,45
+2026-11-01T09:00:00,65,52
+2026-11-01T10:00:00,72,58
+2026-11-01T11:00:00,80,64
+2026-11-01T12:00:00,86,70
+2026-11-01T13:00:00,83,68
+2026-11-01T14:00:00,78,63
+2026-11-01T15:00:00,82,67
+2026-11-01T16:00:00,91,74
+2026-11-01T17:00:00,96,80
+2026-11-01T18:00:00,84,69
+2026-11-01T19:00:00,67,54
+2026-11-01T20:00:00,49,38
+2026-11-01T21:00:00,35,26
+2026-11-01T22:00:00,24,17
+2026-11-01T23:00:00,17,12
diff --git a/pyproject.toml b/pyproject.toml
index 41b0968..79a1ffb 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "continuousintelligence"
-version = "0.1.1"
+version = "0.2.0"
description = "Continuous Intelligence models"
readme = "README.md"
license = "LicenseRef-ci-proto AND Apache-2.0 AND CC-BY-4.0"
diff --git a/src/continuousintelligence/ci_proto/_forecast.py b/src/continuousintelligence/ci_proto/_forecast.py
index 215d91a..107abfc 100644
--- a/src/continuousintelligence/ci_proto/_forecast.py
+++ b/src/continuousintelligence/ci_proto/_forecast.py
@@ -18,6 +18,7 @@
from torch import Tensor, nn
from torch.nn.functional import pad
+from ._formats import ForecastInput, ForecastOutput, as_tensor, prepare_history
from ._model import Model, forecast_layout
@@ -56,21 +57,26 @@ def backend(self) -> str:
def forecast(
self,
- history: Tensor,
+ history: ForecastInput,
horizon: int = 320,
*,
- past_covariates: Tensor | None = None,
- future_covariates: Tensor | None = None,
+ past_covariates: ForecastInput | None = None,
+ future_covariates: ForecastInput | None = None,
categorical_past: tuple[int, ...] = (),
categorical_future: tuple[int, ...] = (),
timestamps: Tensor | None = None,
freq: str | None = None,
series_ids: Sequence[str] | None = None,
static_features: Mapping[str, Sequence[object]] | None = None,
- ) -> Tensor:
+ ) -> ForecastOutput:
"""Forecast joint variables, or independent series identified by ``series_ids``.
- ``history``: float tensor ``[variables, time]``; NaN denotes missing data.
+ ``history``: tensor or NumPy array ``[variables, time]``, pandas DataFrame
+ (time rows, variable columns), Series, or CSV path with numeric columns.
+ NaN denotes missing data. Covariates accept the same input formats.
+ CSV files may include a ``timestamp`` column. A pandas DatetimeIndex or
+ CSV timestamps supply calendar dates; frequency is inferred or set by
+ ``freq``. Dated histories must be regularly spaced.
``past_covariates``: ``[past_variables, time]``.
``future_covariates``: ``[known_variables, time + horizon]``; extra future
steps are ignored. Only supply values known at forecast time. Categorical
@@ -86,17 +92,26 @@ def forecast(
names to values in input row order. Cohort covariates can also be shaped
``[variables, covariates, time]``, including the horizon for known values.
- Returns CPU float32 quantiles ``[variables, quantiles, horizon]``, in
- original units, with levels given by ``self.quantiles``. ci-proto returns
- nine quantiles between 0.1 and 0.9 in increments of 0.1. Horizon is any
- positive integer and defaults to 320.
+ Returns float32 quantiles in the original units. Tensors retain the input
+ device; NumPy inputs return arrays, both ``[variables, quantiles, horizon]``.
+ Pandas and CSV inputs return a DataFrame with horizon rows and
+ ``(variable, quantile)`` columns, indexed by future dates for dated inputs
+ or by steps starting at zero otherwise.
+ Levels are given by ``self.quantiles``. Horizon is any positive integer
+ and defaults to 320.
"""
model, tta = self._model, self._tta
if type(horizon) is not int or horizon < 1:
raise ValueError("horizon must be a positive integer")
+ history, restore, timestamps, freq = prepare_history(
+ history, model.get_buffer("quantiles"), horizon, timestamps, freq
+ )
+ if past_covariates is not None:
+ past_covariates = as_tensor(past_covariates, "past_covariates")
+ if future_covariates is not None:
+ future_covariates = as_tensor(future_covariates, "future_covariates")
if (
self._long_model is not None
- and isinstance(history, Tensor)
and history.ndim == 2
and history.shape[-1] > model.config.context_len
):
@@ -134,7 +149,7 @@ def forecast(
series_ids,
static_features,
)
- return _run_cases(model, cases, count, horizon, tta)
+ return restore(_run_cases(model, cases, count, horizon, tta))
if static_features is not None:
raise ValueError("static_features requires series_ids")
if stamps is not None:
@@ -159,7 +174,7 @@ def forecast(
context, future = _with_calendar(
context, future, count, stamps, freq, bool(tta["calendar_covariates"])
)
- return _predict(model, context[None], future[None], count, horizon, tta)[0]
+ return restore(_predict(model, context[None], future[None], count, horizon, tta)[0])
def _rows(
@@ -448,7 +463,7 @@ def _predict(
expected = (samples * n_targets, model.get_buffer("quantiles").numel(), horizon)
if pred.shape != expected or not bool(torch.isfinite(pred).all()):
raise ValueError("model returned invalid forecast values or shape")
- return pred.reshape(samples, n_targets, -1, horizon).detach().cpu()
+ return pred.reshape(samples, n_targets, -1, horizon).detach()
def _timestamps(
@@ -682,7 +697,13 @@ def _run_cases(
horizon: int,
tta: Mapping[str, float],
) -> Tensor:
- out = torch.empty(count, model.get_buffer("quantiles").numel(), horizon)
+ out = torch.empty(
+ count,
+ model.get_buffer("quantiles").numel(),
+ horizon,
+ device=next(model.parameters()).device,
+ dtype=torch.float32,
+ )
pending: dict[tuple[int, int, int], list[_Case]] = {}
rows = 0
views = 2 if tta["postprocess"] and tta["tta_sign_flip"] else 1
diff --git a/src/continuousintelligence/ci_proto/_formats.py b/src/continuousintelligence/ci_proto/_formats.py
new file mode 100644
index 0000000..ddb62f7
--- /dev/null
+++ b/src/continuousintelligence/ci_proto/_formats.py
@@ -0,0 +1,107 @@
+"""Convert forecast inputs and restore their containers at the API boundary."""
+
+from collections.abc import Callable
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import torch
+from torch import Tensor
+
+ForecastInput = Tensor | np.ndarray | pd.DataFrame | pd.Series | str | Path
+ForecastOutput = Tensor | np.ndarray | pd.DataFrame
+
+
+def _read_csv(path: str | Path) -> pd.DataFrame:
+ frame = pd.read_csv(Path(path).expanduser())
+ if "timestamp" in frame.columns:
+ frame = frame.set_index("timestamp")
+ frame.index = pd.DatetimeIndex(pd.to_datetime(frame.index))
+ return frame
+
+
+def _dates(
+ index: pd.DatetimeIndex, horizon: int, freq: str | None
+) -> tuple[pd.DatetimeIndex, Tensor, str]:
+ if index.empty or index.hasnans or not index.is_unique or not index.is_monotonic_increasing:
+ raise ValueError("history dates must be nonempty, unique, and increasing")
+ freq = freq or index.freqstr
+ if freq is None and len(index) >= 3:
+ freq = pd.DatetimeIndex(index, freq="infer").freqstr
+ if freq is None:
+ raise ValueError("cannot infer history frequency; pass freq, for example freq='h'")
+ dates = pd.date_range(index[0], periods=len(index) + horizon, freq=freq, name=index.name)
+ if not (dates[: len(index)] == index).all():
+ raise ValueError("history dates must be regularly spaced at freq; reindex missing steps")
+ stamps = torch.from_numpy(dates.as_unit("ns").asi8.copy())
+ return dates, stamps, freq
+
+
+def as_tensor(value: ForecastInput, name: str) -> Tensor:
+ """Arrays use [variables, time]; tables use time rows and variable columns."""
+ if isinstance(value, Tensor):
+ return value
+ if isinstance(value, (str, Path)):
+ value = _read_csv(value)
+ if isinstance(value, pd.Series):
+ value = value.to_frame()
+ if isinstance(value, pd.DataFrame):
+ array = value.to_numpy()
+ if array.dtype == object and all(dtype.kind in "biuf" for dtype in value.dtypes):
+ array = value.to_numpy(dtype=np.float64, na_value=np.nan)
+ value = array.T
+ if not isinstance(value, np.ndarray):
+ raise ValueError(f"{name} must be a tensor, NumPy array, pandas object, or CSV path")
+ try:
+ # Copy to support negative strides and read-only pandas/NumPy buffers.
+ return torch.from_numpy(value.copy())
+ except (TypeError, ValueError) as error:
+ raise ValueError(f"{name} must contain numeric values or NaN") from error
+
+
+def prepare_history(
+ history: ForecastInput,
+ quantiles: Tensor,
+ horizon: int,
+ timestamps: Tensor | None,
+ freq: str | None,
+) -> tuple[Tensor, Callable[[Tensor], ForecastOutput], Tensor | None, str | None]:
+ """Remember output labels and the caller's device before converting history."""
+ if isinstance(history, (str, Path)):
+ history = _read_csv(history)
+ if isinstance(history, pd.Series):
+ history = history.to_frame()
+ tensor = as_tensor(history, "history")
+ if isinstance(history, Tensor):
+ device = history.device
+ return tensor, lambda prediction: prediction.to(device), timestamps, freq
+ if isinstance(history, np.ndarray):
+ return tensor, lambda prediction: prediction.cpu().numpy(), timestamps, freq
+
+ future_index = pd.RangeIndex(horizon, name="step")
+ if isinstance(history.index, pd.DatetimeIndex):
+ dates, stamps, freq = _dates(history.index, horizon, freq)
+ if timestamps is not None:
+ if (
+ not isinstance(timestamps, Tensor)
+ or timestamps.dtype != torch.int64
+ or timestamps.ndim not in (1, 2)
+ or timestamps.shape[-1] < len(dates)
+ or not torch.equal(
+ timestamps[..., : len(dates)].detach().cpu(),
+ stamps.expand_as(timestamps[..., : len(dates)]),
+ )
+ ):
+ raise ValueError("timestamps must match the history dates and forecast frequency")
+ else:
+ timestamps = stamps
+ future_index = dates[len(history) :]
+
+ levels = quantiles.tolist()
+ columns = pd.MultiIndex.from_product([history.columns, levels], names=["variable", "quantile"])
+
+ def restore_frame(prediction: Tensor) -> pd.DataFrame:
+ values = prediction.permute(2, 0, 1).cpu().numpy().reshape(horizon, -1)
+ return pd.DataFrame(values, index=future_index, columns=columns)
+
+ return tensor, restore_frame, timestamps, freq
diff --git a/tests/test_dates.py b/tests/test_dates.py
new file mode 100644
index 0000000..7da3723
--- /dev/null
+++ b/tests/test_dates.py
@@ -0,0 +1,170 @@
+"""Date-aware pandas and CSV forecasts use the existing calendar API."""
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pytest
+import torch
+from test_forecast import TTA, Probe
+
+from continuousintelligence import load_model
+from continuousintelligence.ci_proto import Forecaster
+
+
+@pytest.mark.parametrize("cohort", [False, True])
+@pytest.mark.parametrize("kind", ["dataframe", "series", "csv_path", "csv_string"])
+def test_dated_forecast_matches_explicit_calendar_inputs(release_files, tmp_path, kind, cohort):
+ model = load_model(*release_files, device="cpu")
+ dates = pd.date_range("2026-11-01 09:00", periods=7, freq="h", name="timestamp")
+ frame = pd.DataFrame(
+ {"load": [0.25, -0.5, np.nan, 0.75], "temperature": [1.5, -2.5, 3.5, -4.5]},
+ # Drop frequency metadata so the frequency must be inferred from the dates.
+ index=pd.DatetimeIndex(list(dates[:4]), name="timestamp"),
+ )
+ if kind == "series":
+ frame = frame[["load"]]
+ source = frame["load"]
+ elif kind == "dataframe":
+ source = frame.copy()
+ else:
+ path = tmp_path / "history.csv"
+ frame.to_csv(path)
+ source = path if kind == "csv_path" else str(path)
+ before = frame.copy(deep=True)
+ arguments = {"series_ids": list(reversed(frame.columns))} if cohort else {}
+ expected = model.forecast(
+ torch.from_numpy(frame.to_numpy().T.copy()),
+ 3,
+ timestamps=torch.tensor(dates.as_unit("ns").asi8),
+ freq="h",
+ **arguments,
+ )
+ actual = model.forecast(source, 3, **arguments)
+ expected = pd.DataFrame(
+ expected.permute(2, 0, 1).numpy().reshape(3, -1),
+ index=dates[4:],
+ columns=pd.MultiIndex.from_product(
+ [frame.columns, model.quantiles.tolist()], names=["variable", "quantile"]
+ ),
+ )
+ pd.testing.assert_frame_equal(actual, expected)
+ pd.testing.assert_frame_equal(frame, before)
+ if kind == "dataframe":
+ pd.testing.assert_frame_equal(source, before)
+ elif kind == "series":
+ pd.testing.assert_series_equal(source, before["load"])
+
+
+@pytest.mark.parametrize("freq", ["MS", "ME", "W-MON", "D"])
+def test_calendar_frequency_preserves_future_dates(freq):
+ dates = pd.date_range("2024-01-01", periods=7, freq=freq, name="date")
+ frame = pd.DataFrame({"load": [1.5, -2.5, 3.5, -4.5]}, index=dates[:4])
+ model = Forecaster(Probe(), TTA)
+ prediction = model.forecast(frame, 3)
+ pd.testing.assert_index_equal(prediction.index, dates[4:])
+ assert np.isfinite(prediction.to_numpy()).all()
+
+
+def test_timezone_and_daylight_saving_time_are_preserved():
+ dates = pd.date_range(
+ "2026-03-08 00:00", periods=6, freq="h", tz="America/New_York", name="time"
+ )
+ frame = pd.DataFrame({"load": [0.25, -0.5, 0.75]}, index=dates[:3])
+ prediction = Forecaster(Probe(), TTA).forecast(frame, 3)
+ pd.testing.assert_index_equal(prediction.index, dates[3:])
+
+
+def test_utc_csv_preserves_dates(tmp_path):
+ dates = pd.date_range("2026-11-01", periods=6, freq="h", tz="UTC", name="timestamp")
+ frame = pd.DataFrame({"load": [0.25, -0.5, 0.75, -0.25]}, index=dates[:4])
+ path = tmp_path / "history.csv"
+ frame.to_csv(path)
+ prediction = Forecaster(Probe(), TTA).forecast(path, 2)
+ pd.testing.assert_index_equal(prediction.index, dates[4:])
+
+
+@pytest.mark.parametrize("length", [1, 2])
+def test_short_history_accepts_explicit_frequency(length):
+ dates = pd.date_range("2026-11-01", periods=length + 2, freq="h")
+ frame = pd.DataFrame(
+ {"load": [0.25, -0.5][:length]}, index=pd.DatetimeIndex(list(dates[:length]))
+ )
+ model = Forecaster(Probe(), TTA)
+ with pytest.raises(ValueError, match="infer.*frequency"):
+ model.forecast(frame, 2)
+ prediction = model.forecast(frame, 2, freq="h")
+ pd.testing.assert_index_equal(prediction.index, dates[length:])
+
+
+@pytest.mark.parametrize(
+ "dates,freq,message",
+ [
+ (["2026-11-01", "2026-11-01"], "D", "unique"),
+ (["2026-11-02", "2026-11-01"], "D", "increasing"),
+ (["2026-11-01", None], "D", "increasing"),
+ (["2026-11-01", "2026-11-02", "2026-11-04"], None, "infer.*frequency"),
+ (["2026-11-01", "2026-11-02", "2026-11-04"], "D", "regularly spaced"),
+ ],
+)
+def test_invalid_dates_fail_before_inference(dates, freq, message):
+ neural = Probe()
+ frame = pd.DataFrame({"load": np.ones(len(dates))}, index=pd.to_datetime(dates))
+ with pytest.raises(ValueError, match=message):
+ Forecaster(neural, TTA).forecast(frame, 2, freq=freq)
+ assert not neural.batches
+
+
+@pytest.mark.parametrize("per_series", [False, True])
+def test_explicit_timestamps_must_agree_with_dated_history(per_series):
+ dates = pd.date_range("2026-11-01", periods=6, freq="h")
+ frame = pd.DataFrame({"load": [0.25, -0.5, 0.75, -0.25]}, index=dates[:4])
+ stamps = torch.tensor(dates.as_unit("ns").asi8)
+ if per_series:
+ stamps = stamps[None]
+ model = Forecaster(Probe(), TTA)
+ actual = model.forecast(frame, 2, timestamps=stamps)
+ expected = model.forecast(frame, 2)
+ pd.testing.assert_frame_equal(actual, expected)
+ for index in (0, -1):
+ damaged = stamps.clone()
+ damaged[..., index] += 1
+ with pytest.raises(ValueError, match="timestamps must match"):
+ model.forecast(frame, 2, timestamps=damaged)
+
+
+def test_dated_csv_covariates(tmp_path):
+ dates = pd.date_range("2026-11-01", periods=6, freq="h", name="timestamp")
+ history = pd.DataFrame({"load": [0.25, -0.5, 0.75, -0.25]}, index=dates[:4])
+ past = pd.DataFrame({"past": [1.0, 2.0, 3.0, 4.0]}, index=dates[:4])
+ future = pd.DataFrame({"known": [0, 0, 1, 1, 0, 1]}, index=dates)
+ past_path, future_path = tmp_path / "past.csv", tmp_path / "future.csv"
+ past.to_csv(past_path)
+ future.to_csv(future_path)
+ model = Forecaster(Probe(), TTA)
+ actual = model.forecast(
+ history,
+ 2,
+ past_covariates=past_path,
+ future_covariates=future_path,
+ categorical_future=(0,),
+ )
+ expected = model.forecast(
+ history,
+ 2,
+ past_covariates=past,
+ future_covariates=future,
+ categorical_future=(0,),
+ )
+ pd.testing.assert_frame_equal(actual, expected)
+
+
+def test_example_csv():
+ path = Path(__file__).resolve().parents[1] / "examples" / "history.csv"
+ prediction = Forecaster(Probe(), TTA).forecast(path, 3)
+ expected = pd.date_range("2026-11-02", periods=3, freq="h", name="timestamp")
+ pd.testing.assert_index_equal(prediction.index, expected)
+ assert prediction.columns.get_level_values("variable").unique().tolist() == [
+ "store_a",
+ "store_b",
+ ]
diff --git a/tests/test_formats.py b/tests/test_formats.py
new file mode 100644
index 0000000..bedb6b2
--- /dev/null
+++ b/tests/test_formats.py
@@ -0,0 +1,187 @@
+"""Public forecast containers, tabular labels, and input-device placement."""
+
+import numpy as np
+import pandas as pd
+import pytest
+import torch
+from test_forecast import TTA, Probe
+
+from continuousintelligence import load_model
+from continuousintelligence.ci_proto import Forecaster
+
+
+@pytest.mark.parametrize("cohort", [False, True])
+@pytest.mark.parametrize("kind", ["numpy", "dataframe", "series", "csv_path", "csv_string"])
+def test_forecast_returns_expected_container(release_files, tmp_path, kind, cohort):
+ model = load_model(*release_files, device="cpu")
+ history = torch.tensor([[0.25, -0.5, torch.nan, 0.75], [1.5, -2.5, 3.5, -4.5]])
+ if kind == "series":
+ history = history[:1]
+ labels = ["load", "temperature"][: len(history)]
+ frame = pd.DataFrame(history.numpy().T, columns=labels)
+ if kind == "numpy":
+ source = history.numpy().copy()
+ # Reversed arrays can have negative strides; read-only inputs are valid.
+ source = source[:, ::-1].copy()[:, ::-1]
+ source.setflags(write=False)
+ elif kind == "series":
+ source = frame["load"]
+ elif kind == "dataframe":
+ source = frame.copy()
+ else:
+ path = tmp_path / "history.csv"
+ frame.to_csv(path, index=False)
+ source = path if kind == "csv_path" else str(path)
+ arguments = {"series_ids": list(reversed(labels))} if cohort else {}
+ expected = model.forecast(history, 3, **arguments).numpy()
+ actual = model.forecast(source, 3, **arguments)
+ if kind == "numpy":
+ assert isinstance(actual, np.ndarray) and actual.dtype == np.float32
+ np.testing.assert_array_equal(actual, expected)
+ np.testing.assert_array_equal(source, history.numpy())
+ else:
+ assert isinstance(actual, pd.DataFrame)
+ pd.testing.assert_index_equal(actual.index, pd.RangeIndex(3, name="step"))
+ assert actual.columns.names == ["variable", "quantile"]
+ assert actual.columns.tolist() == [
+ (label, q) for label in labels for q in model.quantiles.tolist()
+ ]
+ np.testing.assert_array_equal(actual.to_numpy(), expected.transpose(2, 0, 1).reshape(3, -1))
+ assert all(dtype == np.float32 for dtype in actual.dtypes)
+ if kind == "series":
+ pd.testing.assert_series_equal(source, frame["load"])
+ elif kind == "dataframe":
+ pd.testing.assert_frame_equal(source, frame)
+ else:
+ pd.testing.assert_frame_equal(pd.read_csv(path), frame, check_dtype=False)
+
+
+@pytest.mark.parametrize("cohort", [False, True])
+def test_covariates_accept_mixed_formats(tmp_path, cohort):
+ model = Forecaster(Probe(), TTA)
+ history = torch.tensor([[0.25, -0.5, 0.75, -0.25]])
+ past = torch.tensor([[1.0, 2.0, 3.0, 4.0]])
+ future = torch.tensor([[0, 0, 1, 1, 0, 1]])
+ arguments = {"series_ids": ["load"]} if cohort else {}
+ expected = model.forecast(
+ history,
+ 2,
+ past_covariates=past,
+ future_covariates=future,
+ categorical_future=(0,),
+ **arguments,
+ )
+ future_path = tmp_path / "future.csv"
+ pd.DataFrame(future.numpy().T).to_csv(future_path, index=False)
+ actual = model.forecast(
+ history.numpy(),
+ 2,
+ past_covariates=pd.Series(past[0].numpy()),
+ future_covariates=future_path,
+ categorical_future=(0,),
+ **arguments,
+ )
+ np.testing.assert_array_equal(actual, expected.numpy())
+
+
+def test_nullable_numeric_pandas_columns():
+ frame = pd.DataFrame(
+ {
+ "load": pd.Series([0.25, pd.NA, -0.5, 0.75], dtype="Float64"),
+ "count": pd.Series([1, 2, pd.NA, 4], dtype="Int64"),
+ "flag": pd.Series([True, False, pd.NA, True], dtype="boolean"),
+ }
+ )
+ before = frame.copy(deep=True)
+ model = Forecaster(Probe(), TTA)
+ expected = model.forecast(
+ torch.tensor([[0.25, torch.nan, -0.5, 0.75], [1, 2, torch.nan, 4], [1, 0, torch.nan, 1]]),
+ 2,
+ ).numpy()
+ actual = model.forecast(frame, 2)
+ np.testing.assert_array_equal(actual.to_numpy(), expected.transpose(2, 0, 1).reshape(2, -1))
+ pd.testing.assert_frame_equal(frame, before)
+
+
+@pytest.mark.parametrize("kind", ["numpy", "dataframe", "csv"])
+def test_non_tensor_history_selects_long_model(tmp_path, kind):
+ standard = Probe()
+ long = Probe([[11.0, 12.0, 13.0]])
+ long.config.context_len = 32
+ model = Forecaster(standard, {**TTA, "postprocess": False})
+ model._long_model = lambda: Forecaster(long, {**TTA, "postprocess": False})
+ history = np.sin(np.arange(17, dtype=np.float32))[None]
+ if kind != "numpy":
+ history = pd.DataFrame(history.T, columns=["load"])
+ if kind == "csv":
+ path = tmp_path / "history.csv"
+ history.to_csv(path, index=False)
+ history = path
+ model.forecast(history, 2)
+ assert not standard.batches
+ assert long.batches[0]["x"].shape[-1] == 32 + long.config.future_len
+
+
+@pytest.mark.parametrize(
+ "history",
+ [
+ np.ones(4),
+ np.empty((0, 4)),
+ [[1, 2, 3]],
+ pd.DataFrame({"load": [1.0], "label": ["bad"]}),
+ np.array([[complex(1, 2)]]),
+ ],
+)
+def test_invalid_formats_fail_before_inference(history):
+ neural = Probe()
+ with pytest.raises(ValueError, match="history"):
+ Forecaster(neural, TTA).forecast(history, 2)
+ assert not neural.batches
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA hardware is unavailable")
+@pytest.mark.parametrize("cohort", [False, True])
+@pytest.mark.parametrize(
+ "model_device,input_device",
+ [
+ ("cuda:0", "cpu"),
+ ("cuda:0", "cuda:0"),
+ ("cpu", "cuda:0"),
+ pytest.param(
+ "cuda:0",
+ "cuda:1",
+ marks=pytest.mark.skipif(
+ torch.cuda.device_count() < 2, reason="Two CUDA devices are required"
+ ),
+ ),
+ ],
+)
+def test_tensor_output_keeps_input_device(release_files, model_device, input_device, cohort):
+ model = load_model(*release_files, device="cpu")
+ model._model.to(model_device)
+ history = torch.tensor(
+ [[0.25, -0.5, 0.75, -0.25]], device=input_device, dtype=torch.float64, requires_grad=True
+ )
+ arguments = {"series_ids": ["load"]} if cohort else {}
+ current = torch.cuda.current_device()
+ expected = model.forecast(history.detach().cpu(), 3, **arguments)
+ actual = model.forecast(history, 3, **arguments)
+ assert actual.device == history.device
+ assert actual.dtype == torch.float32 and not actual.requires_grad
+ assert model.device == torch.device(model_device)
+ assert torch.cuda.current_device() == current
+ torch.testing.assert_close(actual.cpu(), expected)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA hardware is unavailable")
+@pytest.mark.parametrize("cohort", [False, True])
+def test_gpu_model_returns_host_numpy_and_pandas(release_files, cohort):
+ model = load_model(*release_files, device="cpu")
+ model._model.cuda()
+ history = np.array([[0.25, -0.5, 0.75, -0.25]], dtype=np.float32)
+ arguments = {"series_ids": ["load"]} if cohort else {}
+ expected = model.forecast(torch.from_numpy(history), 3, **arguments)
+ actual = model.forecast(history, 3, **arguments)
+ np.testing.assert_array_equal(actual, expected.numpy())
+ frame = model.forecast(pd.DataFrame(history.T, columns=["load"]), 3, **arguments)
+ np.testing.assert_array_equal(frame["load"].to_numpy().T, actual[0])
diff --git a/uv.lock b/uv.lock
index 66a70da..1da8627 100644
--- a/uv.lock
+++ b/uv.lock
@@ -320,7 +320,7 @@ wheels = [
[[package]]
name = "continuousintelligence"
-version = "0.1.1"
+version = "0.2.0"
source = { editable = "." }
dependencies = [
{ name = "apache-tvm-ffi", marker = "platform_machine == 'x86_64' and sys_platform == 'linux'" },