[miladh]

Stacked on #2878

Description

Adds client.ai.time_series.forecast_with_retrieval(...), which forecasts CDF time series by instance id. It reads history in [start, end) with the existing client.time_series.data.retrieve, aligns it with build_inputs, and calls client.ai.time_series.forecast.

• Aggregates: with granularity and aggregate, history is aligned with CDF aggregates, and empty buckets are sent as missing.
• Raw datapoints: without them, raw datapoints must already be evenly spaced. Alignment errors explain how to fix the call, e.g. "Pass granularity= and aggregate=…".
• Return type: follows retrieve. One instance id returns a TimeSeriesForecast; several return a TimeSeriesForecastList.
• Cohorts: cohort= forecasts all requested series jointly, on one common grid.

The method lives on the existing AITimeSeriesAPI, next to the low-level forecast. No existing datapoints files are changed.

Also included: the regenerated sync API.

Usage

from cognite.client import CogniteClient
from cognite.client.data_classes.data_modeling import NodeId

client = CogniteClient()
node = NodeId("my_space", "21-PT-1019")

# One time series, from 30 days of hourly averages -> TimeSeriesForecast
fc = client.ai.time_series.forecast_with_retrieval(
    instance_id=node, start="30d-ago", granularity="1h", aggregate="average"
)
fc.to_pandas()   # DatetimeIndex, one column per quantile level

# Several -> TimeSeriesForecastList
ids = [node, NodeId("my_space", "21-PT-1029")]
res = client.ai.time_series.forecast_with_retrieval(
    instance_id=ids, start="30d-ago", granularity="1h", aggregate="average"
)
res.get(instance_id=ids[1]).forecast
res.to_pandas()   # (time series, quantile) columns, named by instance id

# Compressors on one train, forecast jointly on a common grid
res = client.ai.time_series.forecast_with_retrieval(
    instance_id=[NodeId("my_space", x) for x in ("23-PT-1101", "23-PT-1201", "23-PT-1301")],
    start="14d-ago", granularity="10m", aggregate="average",
    cohort="compression-train-a",
)

# Raw datapoints that aren't evenly spaced raise instead of being resampled:
client.ai.time_series.forecast_with_retrieval(instance_id=node, start="7d-ago")
# ValueError: 'my_space:21-PT-1019' is not evenly spaced. Pass `granularity=` and `aggregate=` to align it
# with CDF aggregates, e.g. `granularity='1h', aggregate='average'`.

Checklist:

• Tests added/updated: test_api/test_ai_time_series_retrieval.py, which fakes retrieval and the low-level API; plus the docstring test.
• Documentation updated: docstrings, rendered in the existing ai.rst section.
• The PR title follows the Conventional Commit spec.

🤖 Generated with Claude Code