Add frontend annotation queue interaction type and GET single annotated interaction endpoint

examples/v2/agent-observability/GetLLMObsAnnotatedInteraction.ts

@@ -0,0 +1,23 @@
+/**
+ * Get an annotated queue interaction returns "OK" response
+ */
+
+import { client, v2 } from "@datadog/datadog-api-client";
+
+const configuration = client.createConfiguration();
+configuration.unstableOperations["v2.getLLMObsAnnotatedInteraction"] = true;
+const apiInstance = new v2.AgentObservabilityApi(configuration);
+
+const params: v2.AgentObservabilityApiGetLLMObsAnnotatedInteractionRequest = {
+  queueId: "queue_id",
+  interactionId: "interaction_id",
+};
+
+apiInstance
+  .getLLMObsAnnotatedInteraction(params)
+  .then((data: v2.LLMObsAnnotatedInteractionResponse) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  })
+  .catch((error: any) => console.error(error));

features/generated-test/test-server

@@ -16,7 +16,7 @@ import re
 import tempfile
 import threading
 import uuid
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from http import HTTPStatus
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
@@ -435,7 +435,8 @@ def _json_contains(actual: Any, expected: Any) -> bool:
         return all(key in actual and _json_contains(actual[key], value) for key, value in expected.items())
     if isinstance(expected, list) and isinstance(actual, list):
         return len(expected) == len(actual) and all(
-            _json_contains(actual_item, expected_item) for actual_item, expected_item in zip(actual, expected)
+            _json_contains(actual_item, expected_item)
+            for actual_item, expected_item in zip(actual, expected, strict=False)
         )
     return actual == expected
 
@@ -460,7 +461,7 @@ def _slug(value: str) -> str:
 
 
 def _now_iso() -> str:
-    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
 
 
 def _read_json(path: Path) -> dict[str, Any]:

features/support/scenarios_model_mapping.ts

@@ -2614,6 +2614,17 @@ export const ScenariosModelMappings: {[key: string]: {[key: string]: any}} = {
             },
         "operationResponseType": "LLMObsAnnotatedInteractionsResponse",
     },
+    "v2.GetLLMObsAnnotatedInteraction": {
+        "queueId": {
+            "type": "string",
+            "format": "",
+            },
+        "interactionId": {
+            "type": "string",
+            "format": "",
+            },
+        "operationResponseType": "LLMObsAnnotatedInteractionResponse",
+    },
     "v2.UpsertLLMObsAnnotations": {
         "queueId": {
             "type": "string",

features/v2/agent_observability.feature

@@ -782,6 +782,33 @@ Feature: Agent Observability
     When the request is sent
     Then the response status is 200 OK
 
+  @generated @skip @team:DataDog/ml-observability
+  Scenario: Get an annotated queue interaction returns "Bad Request" response
+    Given operation "GetLLMObsAnnotatedInteraction" enabled
+    And new "GetLLMObsAnnotatedInteraction" request
+    And request contains "queue_id" parameter from "REPLACE.ME"
+    And request contains "interaction_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/ml-observability
+  Scenario: Get an annotated queue interaction returns "Not Found" response
+    Given operation "GetLLMObsAnnotatedInteraction" enabled
+    And new "GetLLMObsAnnotatedInteraction" request
+    And request contains "queue_id" parameter from "REPLACE.ME"
+    And request contains "interaction_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
+  @generated @skip @team:DataDog/ml-observability
+  Scenario: Get an annotated queue interaction returns "OK" response
+    Given operation "GetLLMObsAnnotatedInteraction" enabled
+    And new "GetLLMObsAnnotatedInteraction" request
+    And request contains "queue_id" parameter from "REPLACE.ME"
+    And request contains "interaction_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 200 OK
+
   @generated @skip @team:DataDog/ml-observability
   Scenario: Get annotated interactions by content IDs returns "Bad Request" response
     Given operation "GetLLMObsAnnotatedInteractionsByTraceIDs" enabled

features/v2/undo.json

@@ -4636,6 +4636,12 @@
       "type": "safe"
     }
   },
+  "GetLLMObsAnnotatedInteraction": {
+    "tag": "Agent Observability",
+    "undo": {
+      "type": "safe"
+    }
+  },
   "UpsertLLMObsAnnotations": {
     "tag": "Agent Observability",
     "undo": {

packages/datadog-api-client-common/configuration.ts

@@ -260,6 +260,7 @@ export function createConfiguration(
       "v2.deleteLLMObsProjects": false,
       "v2.deleteLLMObsPrompt": false,
       "v2.exportLLMObsDataset": false,
+      "v2.getLLMObsAnnotatedInteraction": false,
       "v2.getLLMObsAnnotatedInteractions": false,
       "v2.getLLMObsAnnotatedInteractionsByTraceIDs": false,
       "v2.getLLMObsAnnotationQueueLabelSchema": false,

packages/datadog-api-client-v2/apis/AgentObservabilityApi.ts

@@ -21,6 +21,7 @@ import { ApiException } from "../../datadog-api-client-common/exception";
 
 import { APIErrorResponse } from "../models/APIErrorResponse";
 import { JSONAPIErrorResponse } from "../models/JSONAPIErrorResponse";
+import { LLMObsAnnotatedInteractionResponse } from "../models/LLMObsAnnotatedInteractionResponse";
 import { LLMObsAnnotatedInteractionsByTraceResponse } from "../models/LLMObsAnnotatedInteractionsByTraceResponse";
 import { LLMObsAnnotatedInteractionsResponse } from "../models/LLMObsAnnotatedInteractionsResponse";
 import { LLMObsAnnotationQueueInteractionsRequest } from "../models/LLMObsAnnotationQueueInteractionsRequest";
@@ -1529,6 +1530,57 @@ export class AgentObservabilityApiRequestFactory extends BaseAPIRequestFactory {
     return requestContext;
   }
 
+  public async getLLMObsAnnotatedInteraction(
+    queueId: string,
+    interactionId: string,
+    _options?: Configuration
+  ): Promise<RequestContext> {
+    const _config = _options || this.configuration;
+
+    logger.warn("Using unstable operation 'getLLMObsAnnotatedInteraction'");
+    if (!_config.unstableOperations["v2.getLLMObsAnnotatedInteraction"]) {
+      throw new Error(
+        "Unstable operation 'getLLMObsAnnotatedInteraction' is disabled"
+      );
+    }
+
+    // verify required parameter 'queueId' is not null or undefined
+    if (queueId === null || queueId === undefined) {
+      throw new RequiredError("queueId", "getLLMObsAnnotatedInteraction");
+    }
+
+    // verify required parameter 'interactionId' is not null or undefined
+    if (interactionId === null || interactionId === undefined) {
+      throw new RequiredError("interactionId", "getLLMObsAnnotatedInteraction");
+    }
+
+    // Path Params
+    const localVarPath =
+      "/api/v2/llm-obs/v1/annotation-queues/{queue_id}/annotated-interactions/{interaction_id}"
+        .replace("{queue_id}", encodeURIComponent(String(queueId)))
+        .replace("{interaction_id}", encodeURIComponent(String(interactionId)));
+
+    // Make Request Context
+    const requestContext = _config
+      .getServer("v2.AgentObservabilityApi.getLLMObsAnnotatedInteraction")
+      .makeRequestContext(localVarPath, HttpMethod.GET);
+    requestContext.setHeaderParam("Accept", "application/json");
+    requestContext.setHttpConfig(_config.httpConfig);
+
+    // Set IaC header
+    if (_config.isIaC) {
+      requestContext.setHeaderParam("X-Datadog-Managed-By", "iac");
+    }
+
+    // Apply auth methods
+    applySecurityAuthentication(_config, requestContext, [
+      "apiKeyAuth",
+      "appKeyAuth",
+    ]);
+
+    return requestContext;
+  }
+
   public async getLLMObsAnnotatedInteractions(
     queueId: string,
     _options?: Configuration
@@ -6432,6 +6484,94 @@ export class AgentObservabilityApiResponseProcessor {
     );
   }
 
+  /**
+   * Unwraps the actual response sent by the server from the response context and deserializes the response content
+   * to the expected objects
+   *
+   * @params response Response returned by the server for a request to getLLMObsAnnotatedInteraction
+   * @throws ApiException if the response code was not in [200, 299]
+   */
+  public async getLLMObsAnnotatedInteraction(
+    response: ResponseContext
+  ): Promise<LLMObsAnnotatedInteractionResponse> {
+    const contentType = ObjectSerializer.normalizeMediaType(
+      response.headers["content-type"]
+    );
+    if (response.httpStatusCode === 200) {
+      const body: LLMObsAnnotatedInteractionResponse =
+        ObjectSerializer.deserialize(
+          ObjectSerializer.parse(await response.body.text(), contentType),
+          "LLMObsAnnotatedInteractionResponse"
+        ) as LLMObsAnnotatedInteractionResponse;
+      return body;
+    }
+    if (
+      response.httpStatusCode === 400 ||
+      response.httpStatusCode === 401 ||
+      response.httpStatusCode === 403 ||
+      response.httpStatusCode === 404
+    ) {
+      const bodyText = ObjectSerializer.parse(
+        await response.body.text(),
+        contentType
+      );
+      let body: JSONAPIErrorResponse;
+      try {
+        body = ObjectSerializer.deserialize(
+          bodyText,
+          "JSONAPIErrorResponse"
+        ) as JSONAPIErrorResponse;
+      } catch (error) {
+        logger.debug(`Got error deserializing error: ${error}`);
+        throw new ApiException<JSONAPIErrorResponse>(
+          response.httpStatusCode,
+          bodyText
+        );
+      }
+      throw new ApiException<JSONAPIErrorResponse>(
+        response.httpStatusCode,
+        body
+      );
+    }
+    if (response.httpStatusCode === 429) {
+      const bodyText = ObjectSerializer.parse(
+        await response.body.text(),
+        contentType
+      );
+      let body: APIErrorResponse;
+      try {
+        body = ObjectSerializer.deserialize(
+          bodyText,
+          "APIErrorResponse"
+        ) as APIErrorResponse;
+      } catch (error) {
+        logger.debug(`Got error deserializing error: ${error}`);
+        throw new ApiException<APIErrorResponse>(
+          response.httpStatusCode,
+          bodyText
+        );
+      }
+      throw new ApiException<APIErrorResponse>(response.httpStatusCode, body);
+    }
+
+    // Work around for missing responses in specification, e.g. for petstore.yaml
+    if (response.httpStatusCode >= 200 && response.httpStatusCode <= 299) {
+      const body: LLMObsAnnotatedInteractionResponse =
+        ObjectSerializer.deserialize(
+          ObjectSerializer.parse(await response.body.text(), contentType),
+          "LLMObsAnnotatedInteractionResponse",
+          ""
+        ) as LLMObsAnnotatedInteractionResponse;
+      return body;
+    }
+
+    const body = (await response.body.text()) || "";
+    throw new ApiException<string>(
+      response.httpStatusCode,
+      'Unknown API Status Code!\nBody: "' + body + '"'
+    );
+  }
+
   /**
    * Unwraps the actual response sent by the server from the response context and deserializes the response content
    * to the expected objects
@@ -10847,6 +10987,19 @@ export interface AgentObservabilityApiExportLLMObsDatasetRequest {
   version?: number;
 }
 
+export interface AgentObservabilityApiGetLLMObsAnnotatedInteractionRequest {
+  /**
+   * The ID of the Agent Observability annotation queue.
+   * @type string
+   */
+  queueId: string;
+  /**
+   * The ID of the interaction within the annotation queue.
+   * @type string
+   */
+  interactionId: string;
+}
+
 export interface AgentObservabilityApiGetLLMObsAnnotatedInteractionsRequest {
   /**
    * The ID of the Agent Observability annotation queue.
@@ -11689,6 +11842,9 @@ export class AgentObservabilityApi {
    * - `display_block`: omit `content_id` and provide the rendered content
    *   in `display_block`. The server generates `content_id` as a
    *   deterministic hash of the block list.
+   * - `frontend`: omit `content_id` and provide the web content in
+   *   `frontend`. The server returns a deterministic `content_id` for the
+   *   content.
    *
    * Items of different types can be mixed in a single request.
    * @param param The request object
@@ -12149,6 +12305,31 @@ export class AgentObservabilityApi {
     });
   }
 
+  /**
+   * Retrieve a single interaction (trace, session, display block, or frontend content) and its annotations for a given annotation queue.
+   * @param param The request object
+   */
+  public getLLMObsAnnotatedInteraction(
+    param: AgentObservabilityApiGetLLMObsAnnotatedInteractionRequest,
+    options?: Configuration
+  ): Promise<LLMObsAnnotatedInteractionResponse> {
+    const requestContextPromise =
+      this.requestFactory.getLLMObsAnnotatedInteraction(
+        param.queueId,
+        param.interactionId,
+        options
+      );
+    return requestContextPromise.then((requestContext) => {
+      return this.configuration.httpApi
+        .send(requestContext)
+        .then((responseContext) => {
+          return this.responseProcessor.getLLMObsAnnotatedInteraction(
+            responseContext
+          );
+        });
+    });
+  }
+
   /**
    * Retrieve all interactions (traces and sessions) and their annotations for a given annotation queue.
    * @param param The request object

packages/datadog-api-client-v2/index.ts

@@ -94,6 +94,7 @@ export {
   AgentObservabilityApiDeleteLLMObsProjectsRequest,
   AgentObservabilityApiDeleteLLMObsPromptRequest,
   AgentObservabilityApiExportLLMObsDatasetRequest,
+  AgentObservabilityApiGetLLMObsAnnotatedInteractionRequest,
   AgentObservabilityApiGetLLMObsAnnotatedInteractionsRequest,
   AgentObservabilityApiGetLLMObsAnnotatedInteractionsByTraceIDsRequest,
   AgentObservabilityApiGetLLMObsAnnotationQueueLabelSchemaRequest,
@@ -5398,7 +5399,10 @@ export { ListWorkflowsResponse } from "./models/ListWorkflowsResponse";
 export { ListWorkflowsResponseMeta } from "./models/ListWorkflowsResponseMeta";
 export { ListWorkflowsResponseMetaPage } from "./models/ListWorkflowsResponseMetaPage";
 export { LLMObsAnnotatedInteractionByTraceItem } from "./models/LLMObsAnnotatedInteractionByTraceItem";
+export { LLMObsAnnotatedInteractionDataAttributesResponse } from "./models/LLMObsAnnotatedInteractionDataAttributesResponse";
+export { LLMObsAnnotatedInteractionDataResponse } from "./models/LLMObsAnnotatedInteractionDataResponse";
 export { LLMObsAnnotatedInteractionItem } from "./models/LLMObsAnnotatedInteractionItem";
+export { LLMObsAnnotatedInteractionResponse } from "./models/LLMObsAnnotatedInteractionResponse";
 export { LLMObsAnnotatedInteractionsByTraceDataAttributesResponse } from "./models/LLMObsAnnotatedInteractionsByTraceDataAttributesResponse";
 export { LLMObsAnnotatedInteractionsByTraceDataResponse } from "./models/LLMObsAnnotatedInteractionsByTraceDataResponse";
 export { LLMObsAnnotatedInteractionsByTraceResponse } from "./models/LLMObsAnnotatedInteractionsByTraceResponse";
@@ -5410,7 +5414,6 @@ export { LLMObsAnnotatedInteractionsType } from "./models/LLMObsAnnotatedInterac
 export { LLMObsAnnotationAssessment } from "./models/LLMObsAnnotationAssessment";
 export { LLMObsAnnotationError } from "./models/LLMObsAnnotationError";
 export { LLMObsAnnotationErrorCode } from "./models/LLMObsAnnotationErrorCode";
-export { LLMObsAnnotationItem } from "./models/LLMObsAnnotationItem";
 export { LLMObsAnnotationItemResponse } from "./models/LLMObsAnnotationItemResponse";
 export { LLMObsAnnotationLabelValue } from "./models/LLMObsAnnotationLabelValue";
 export { LLMObsAnnotationLabelValueResponse } from "./models/LLMObsAnnotationLabelValueResponse";
@@ -5633,6 +5636,11 @@ export { LLMObsExperimentUpdateDataAttributesRequest } from "./models/LLMObsExpe
 export { LLMObsExperimentUpdateDataRequest } from "./models/LLMObsExperimentUpdateDataRequest";
 export { LLMObsExperimentUpdateRequest } from "./models/LLMObsExperimentUpdateRequest";
 export { LLMObsExperimentUser } from "./models/LLMObsExperimentUser";
+export { LLMObsFrontendAnnotatedInteractionItem } from "./models/LLMObsFrontendAnnotatedInteractionItem";
+export { LLMObsFrontendContent } from "./models/LLMObsFrontendContent";
+export { LLMObsFrontendInteractionItem } from "./models/LLMObsFrontendInteractionItem";
+export { LLMObsFrontendInteractionResponseItem } from "./models/LLMObsFrontendInteractionResponseItem";
+export { LLMObsFrontendInteractionType } from "./models/LLMObsFrontendInteractionType";
 export { LLMObsInferenceCode } from "./models/LLMObsInferenceCode";
 export { LLMObsInferenceContent } from "./models/LLMObsInferenceContent";
 export { LLMObsInferenceContentValue } from "./models/LLMObsInferenceContentValue";