[miladh]

Stacked on #2879

Description

Adds client.ai.time_series.impute_with_retrieval(...), which reconstructs gaps and chosen datapoints of CDF time series by instance id. Retrieval and alignment work as in client.ai.time_series.forecast_with_retrieval.

Callers must say what to reconstruct, so nothing is imputed by accident:

• fill_gaps=True reconstructs every grid point without a datapoint. With aggregates, that's every empty bucket.
• mask=[...] takes timestamps, or inclusive (start, end) ranges, to reconstruct even where values exist, for example a known-bad period. A mask that covers no grid point raises ValueError.

Passing neither raises ValueError before any data is retrieved. One instance id returns a TimeSeriesImpute; several return a TimeSeriesImputeList.

Only touches AITimeSeriesAPI and its generated sync file. No existing datapoints files are changed.

Usage

from datetime import datetime, timezone
from cognite.client import CogniteClient
from cognite.client.data_classes.data_modeling import NodeId

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

# Fill every empty 10-minute bucket in the last week -> TimeSeriesImpute
res = client.ai.time_series.impute_with_retrieval(
    instance_id=node, start="7d-ago", granularity="10m", aggregate="average", fill_gaps=True
)
res.to_pandas()   # reconstructed points: DatetimeIndex, one column per quantile level

# Reconstruct a period you know is bad, e.g. during a sensor fault
res = client.ai.time_series.impute_with_retrieval(
    instance_id=node, start="7d-ago", granularity="10m", aggregate="average",
    mask=[(datetime(2026, 9, 30, 8, tzinfo=timezone.utc), datetime(2026, 9, 30, 12, tzinfo=timezone.utc))],
)

# Not saying what to reconstruct raises, before anything is retrieved:
client.ai.time_series.impute_with_retrieval(instance_id=node, start="7d-ago")
# ValueError: Say what to reconstruct: pass `fill_gaps=True`, `mask=[...]`, or both.

Checklist:

• Tests added/updated: TestImputeWithRetrieval in test_ai_time_series_retrieval.py.
• Documentation updated: docstrings, rendered in the existing ai.rst section.
• The PR title follows the Conventional Commit spec.

🤖 Generated with Claude Code