[miladh]

Stacked on #2875.

Description

DataFrame variants of forecast and impute, validated and converted like insert_dataframe:

• Each numeric column is one time series, named by its label, so column names must be strings.
• Datapoints keep the API's meaning. A NaN is a gap with no reading, sent as a datapoint without a value: the model doesn't see it, and impute doesn't return it.
• missing= is an optional boolean DataFrame with the same index and columns, sent as the API's missing flag: the datapoints to hide from the model whatever their value, which impute predicts. Like in the API, nothing is marked by default.
• cohort= takes one cohort for every column, or a {column: cohort} mapping. Columns not in the mapping are processed independently.
• The result is to_pandas() of the result list: the median in one column per time series, with a timezone-naive DatetimeIndex in UTC like other SDK result DataFrames. include_all_quantiles=True gives (column, quantile level) columns for every level the API returns.
• A DataFrame without a DatetimeIndex, with repeated, non-string or non-numeric columns (booleans included) or infinite values, a cohort mapping that names a column not in the DataFrame, or a missing that doesn't match the DataFrame, is rejected before anything is sent.

Usage

import numpy as np
import pandas as pd
from cognite.client import CogniteClient

client = CogniteClient()
df = pd.DataFrame(
    {
        "23-PT-1101": [42.1, 42.4, 42.9],
        "23-PT-1201": [39.8, 40.1, 40.0],
        "24-TT-3001": [31.0, np.nan, 30.9],   # NaN: a gap with no reading
    },
    index=pd.date_range("2026-10-01", periods=3, freq="1min"),
)

# Every column independently
forecast = client.ai.time_series.forecast_dataframe(df)
forecast["23-PT-1101"]   # the median forecast

# The two compressor pressures jointly; 24-TT-3001 stays independent
forecast = client.ai.time_series.forecast_dataframe(
    df, cohort={"23-PT-1101": "compression-train-a", "23-PT-1201": "compression-train-a"}
)
all_levels = client.ai.time_series.forecast_dataframe(df, include_all_quantiles=True)

# Predict the gaps, and fill them with the predicted median
imputed = client.ai.time_series.impute_dataframe(df, missing=df.isna())
filled = df.fillna(imputed)

pandas is an optional extra, so the new tests are marked dsl. The ai.time_series docstring test moves to its own dsl-marked test, like datapoints and raw.

Checklist:

• Tests added/updated: TestDataFrames in test_api/test_ai_time_series.py, and DataFrame integration tests in tests_integration/test_api/test_ai_time_series.py.
• Documentation updated: docstrings.
• The PR title follows the Conventional Commit spec.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces forecast_dataframe and impute_dataframe methods to both the async and sync AI Time Series APIs, allowing users to forecast and reconstruct missing values directly from pandas DataFrames. Feedback on the implementation of the _dataframe_to_input helper function highlights the need for improved robustness, specifically regarding DatetimeIndex validation, timezone-aware index handling, and validating that all columns are numeric to prevent cryptic runtime errors.