AI

AI API

`AsyncCogniteClient.ai.tools.documents.ask_question`(...)	Ask a question about one or more documents using a Large Language Model.
`AsyncCogniteClient.ai.tools.documents.summarize`([...])	Summarize a document using a Large Language Model.

Time Series Forecasting and Imputation

`AsyncCogniteClient.ai.time_series.forecast`(...)	Forecast the next 512 points of each time series from its history.
`AsyncCogniteClient.ai.time_series.impute`(...)	Predict the value of every datapoint marked missing, from the datapoints on both sides of it.

AI Data classes

class cognite.client.data_classes.ai.Answer(content: list[AnswerContent])

Bases: object

An answer returned from the Document Question Answering API.

The answer is essentially a list of content objects. Each content object consists of a chunk of text along with a set of references.

Each reference contains information about which document this part of the answer was found in, and gives the bounding box and page number of the piece of text the answer was constructed from.

Parameters:: content (list[AnswerContent]) – The list of content objects.

property all_references: set[AnswerReference]: Get all unique references. This is the full set of references from all the content objects.

property full_answer: str: Get the full answer text. This is the concatenation of the texts from all the content objects.

class cognite.client.data_classes.ai.AnswerContent( text: str, references: list[AnswerReference], )

Bases: object

A single content object.

It consists of part of the answer from the LLM along with references to the documents containing the source material for the answer.

Parameters:

text (str) – The extracted plain text
references (list[AnswerReference]) – The list of references.

class cognite.client.data_classes.ai.AnswerLanguage(value)

Bases: Enum

An enumeration.

class cognite.client.data_classes.ai.AnswerLocation( page_number: int, left: float, right: float, top: float, bottom: float, )

Bases: object

A location object

The location object consists of a page number and a bounding box. This specifies exactly where inside a document an answer can be found.

Parameters:

page_number (int) – Page number, starting with 1
left (float) – Leftmost edge of the bounding box
right (float) – Rightmost edge of the bounding box
top (float) – Topmost edge of the bounding box
bottom (float) – Bottommost edge of the bounding box

class cognite.client.data_classes.ai.AnswerReference( file_id: int, external_id: str | None, instance_id: NodeId | None, file_name: str, locations: list[AnswerLocation], )

Bases: object

A single reference object.

The reference object specifies which file an answer is based on, and has a list of locations pointing to the specific pages and bounding boxes where the answer was found.

Parameters:

file_id (int) – The internal id of the document
external_id (str | None) – The external id of the document
instance_id (NodeId | None) – The instance id of the document
file_name (str) – The name of the document
locations (list[AnswerLocation]) – A list of locations within the document, where the answer was found

class cognite.client.data_classes.ai.ForecastInputDatapoint( timestamp: int | float | str | datetime, value: float | None, missing: bool = False, )

Bases: object

One history point sent to the forecast or impute endpoint.

The datapoints of a series must be evenly spaced. To represent a gap in the history, such as a sensor outage, keep the timestamp and set the value to None or mark the datapoint as missing.

A datapoint with value None has no reading. The model does not see it, and impute does not return it.

A datapoint marked missing is hidden from the model, whatever its value. Impute predicts its value and returns it: mark a gap as missing to fill it, or mark observed datapoints as missing to compare each value with its prediction. For forecast, marking datapoints as missing excludes a segment of the history, for example to see how it affects the result.

At least one datapoint per series must have a value and not be marked missing.

Parameters:

timestamp (int | float | str | datetime) – Milliseconds since epoch, a datetime, or a time-shift string like “2d-ago”.
value (float | None) – The value, or None when there is no reading.
missing (bool) – Hide the datapoint from the model, whatever its value. Impute returns a prediction for it.

classmethod load( data: ForecastInputDatapoint | tuple[Any, ...] | list[Any] | dict[str, Any], ) → ForecastInputDatapoint

Create a datapoint from any of the supported formats.

Parameters:: data (ForecastInputDatapoint | tuple[Any, ...] | list[Any] | dict[str, Any]) – A datapoint, returned as is; a (timestamp, value) or (timestamp, value, missing) tuple or list; or a dict with the API keys timestamp, value and missing, where an absent value means None.
Returns:: The datapoint.
Return type:: ForecastInputDatapoint

Examples

Create datapoints from tuples and dicts:

>>> from cognite.client.data_classes.ai import ForecastInputDatapoint
>>> dps = [
...     ForecastInputDatapoint.load((1790812800000, 42.1)),
...     ForecastInputDatapoint.load({"timestamp": 1790812860000, "missing": True}),
... ]

class cognite.client.data_classes.ai.ForecastInputTimeSeries( label: str, datapoints: Sequence[ForecastInputDatapoint], cohort: str | None = None, )

Bases: object

One series sent to the forecast or impute endpoint.

Parameters:

label (str) – Caller-chosen identifier, echoed back in the result.
datapoints (Sequence[ForecastInputDatapoint]) – Evenly spaced history. Use ForecastInputDatapoint.load to load datapoints from tuples or dicts.
cohort (str | None) – A group name. Give related series, such as the sensors on one compressor, the same cohort to process them jointly (multivariate), so the model can use the relationships between them. Series in a cohort must have identical timestamps: the same start, interval and number of datapoints. Leave it as None to process the series independently.

class cognite.client.data_classes.ai.ForecastMetadata(quantile_levels: list[float], cohorts: list[str])

Bases: CogniteResource

The metadata of a forecast or impute response.

Parameters:

quantile_levels (list[float]) – The quantile levels in every point’s quantiles.
cohorts (list[str]) – The distinct cohorts in the request. Time series without a cohort are not included.

class cognite.client.data_classes.ai.ForecastResult( label: str, forecast: list[QuantileDatapoint], cohort: str | None = None, )

Bases: CogniteResource

The forecast for one input series.

Parameters:

label (str) – The label of the input series.
forecast (list[QuantileDatapoint]) – One point per forecasted step.
cohort (str | None) – The cohort of the input series, if any.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

to_pandas(include_all_quantiles: bool = False) → pd.DataFrame

Convert to a DataFrame with a DatetimeIndex and one column, named by the label, with the median.

Parameters:: include_all_quantiles (bool) – Include every quantile level instead of only the median, as one column per level.
Returns:: The forecast.
Return type:: pd.DataFrame

class cognite.client.data_classes.ai.ForecastResultList( resources: Sequence[ForecastResult], metadata: ForecastMetadata | None = None, )

Bases: CogniteResourceList[ForecastResult]

Forecasts for several input series, with the response metadata.

Parameters:

resources (Sequence[ForecastResult]) – One result per input series.
metadata (ForecastMetadata | None) – The metadata of the response. Empty for a list built from results alone, like a slice.

dump_raw(camel_case: bool = True) → dict[str, Any]

Dump the list the way the API returns it: the items, and the metadata.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: The items and the metadata.
Return type:: dict[str, Any]

get( label: str, ) → ForecastResult | None

Get the result for an input series by its label (user-given).

Parameters:: label (str) – The label of the input series.
Returns:: The result, or None if no series has that label.
Return type:: ForecastResult | None

to_pandas( include_all_quantiles: bool = False, ) → pd.DataFrame

Convert to a DataFrame with a DatetimeIndex and one column per label, with the median.

Parameters:: include_all_quantiles (bool) – Include every quantile level instead of only the median, as (label, quantile level) columns.
Returns:: The forecasts.
Return type:: pd.DataFrame

class cognite.client.data_classes.ai.ImputeResult( label: str, imputed: list[QuantileDatapoint], cohort: str | None = None, )

Bases: CogniteResource

The reconstructed points for one input series.

Parameters:

label (str) – The label of the input series.
imputed (list[QuantileDatapoint]) – One point per point marked missing. Empty if none were.
cohort (str | None) – The cohort of the input series, if any.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

to_pandas(include_all_quantiles: bool = False) → pd.DataFrame

Convert to a DataFrame with a DatetimeIndex and one column, named by the label, with the median.

Parameters:: include_all_quantiles (bool) – Include every quantile level instead of only the median, as one column per level.
Returns:: The reconstructed points.
Return type:: pd.DataFrame

class cognite.client.data_classes.ai.ImputeResultList( resources: Sequence[ImputeResult], metadata: ForecastMetadata | None = None, )

Bases: CogniteResourceList[ImputeResult]

Reconstructed points for several input series, with the response metadata.

Parameters:

resources (Sequence[ImputeResult]) – One result per input series.
metadata (ForecastMetadata | None) – The metadata of the response. Empty for a list built from results alone, like a slice.

dump_raw(camel_case: bool = True) → dict[str, Any]

Dump the list the way the API returns it: the items, and the metadata.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: The items and the metadata.
Return type:: dict[str, Any]

get( label: str, ) → ImputeResult | None

Get the result for an input series by its label.

Labels are unique within a result, since duplicate labels in a request are rejected.

Parameters:: label (str) – The label of the input series.
Returns:: The result, or None if no series has that label.
Return type:: ImputeResult | None

to_pandas(include_all_quantiles: bool = False) → pd.DataFrame

Convert to a DataFrame with a DatetimeIndex and one column per label, with the median.

Parameters:: include_all_quantiles (bool) – Include every quantile level instead of only the median, as (label, quantile level) columns.
Returns:: The reconstructed points.
Return type:: pd.DataFrame

class cognite.client.data_classes.ai.QuantileDatapoint(timestamp: int, quantiles: dict[float, float])

Bases: CogniteResource

One forecasted or reconstructed step.

Parameters:

timestamp (int) – Milliseconds since epoch.
quantiles (dict[float, float]) – Quantile level -> value.

dump(camel_case: bool = True) → dict[str, Any]

Dump the instance into a json serializable Python data type.

Parameters:: camel_case (bool) – Use camelCase for attribute names. Defaults to True.
Returns:: A dictionary representation of the instance.
Return type:: dict[str, Any]

class cognite.client.data_classes.ai.Summary( summary: str, id: int | None = None, external_id: str | None = None, instance_id: NodeId | None = None, )

Bases: object

A summary object consisting of a textual summary plus the id of the summarized document

Parameters:

summary (str) – The textual summary of the document
id (int | None) – The id of the document
external_id (str | None) – The external id of the document
instance_id (NodeId | None) – The instance id of the document