Document AI Guard evaluation API

examples/v2/ai-guard/EvaluateAIGuardRequest.py

@@ -0,0 +1,40 @@
+"""
+Evaluate an AI Guard request returns "OK" response
+"""
+
+from os import environ
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.ai_guard_api import AIGuardApi
+from datadog_api_client.v2.model.ai_guard_evaluate_request import AIGuardEvaluateRequest
+from datadog_api_client.v2.model.ai_guard_evaluate_request_data import AIGuardEvaluateRequestData
+from datadog_api_client.v2.model.ai_guard_evaluate_request_data_attributes import AIGuardEvaluateRequestDataAttributes
+from datadog_api_client.v2.model.ai_guard_evaluation_type import AIGuardEvaluationType
+from datadog_api_client.v2.model.ai_guard_message import AIGuardMessage
+from datadog_api_client.v2.model.ai_guard_message_role import AIGuardMessageRole
+from datadog_api_client.v2.model.ai_guard_meta import AIGuardMeta
+
+body = AIGuardEvaluateRequest(
+    data=AIGuardEvaluateRequestData(
+        type=AIGuardEvaluationType.EVALUATIONS,
+        attributes=AIGuardEvaluateRequestDataAttributes(
+            messages=[
+                AIGuardMessage(
+                    content="Hello world!",
+                    role=AIGuardMessageRole.USER,
+                ),
+            ],
+            meta=AIGuardMeta(
+                confidence_threshold=0.8,
+            ),
+        ),
+    ),
+)
+
+configuration = Configuration()
+configuration.access_token = environ["DD_BEARER_TOKEN"]
+configuration.unstable_operations["evaluate_ai_guard_request"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = AIGuardApi(api_client)
+    response = api_instance.evaluate_ai_guard_request(body=body)
+
+    print(response)

examples/v2/ai-guard/EvaluateAIGuardRequest_1377048937.py

@@ -0,0 +1,45 @@
+"""
+Evaluate an AI Guard request with per-category confidence thresholds
+"""
+
+from os import environ
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.ai_guard_api import AIGuardApi
+from datadog_api_client.v2.model.ai_guard_confidence_threshold import AIGuardConfidenceThreshold
+from datadog_api_client.v2.model.ai_guard_evaluate_request import AIGuardEvaluateRequest
+from datadog_api_client.v2.model.ai_guard_evaluate_request_data import AIGuardEvaluateRequestData
+from datadog_api_client.v2.model.ai_guard_evaluate_request_data_attributes import AIGuardEvaluateRequestDataAttributes
+from datadog_api_client.v2.model.ai_guard_evaluation_type import AIGuardEvaluationType
+from datadog_api_client.v2.model.ai_guard_message import AIGuardMessage
+from datadog_api_client.v2.model.ai_guard_message_role import AIGuardMessageRole
+from datadog_api_client.v2.model.ai_guard_meta import AIGuardMeta
+
+body = AIGuardEvaluateRequest(
+    data=AIGuardEvaluateRequestData(
+        type=AIGuardEvaluationType.EVALUATIONS,
+        attributes=AIGuardEvaluateRequestDataAttributes(
+            messages=[
+                AIGuardMessage(
+                    role=AIGuardMessageRole.USER,
+                    content="Hello world!",
+                ),
+            ],
+            meta=AIGuardMeta(
+                confidence_threshold=AIGuardConfidenceThreshold(
+                    flagging_global=0.6,
+                    policy_evasion=0.9,
+                    indirect_prompt_injection=0.4,
+                ),
+            ),
+        ),
+    ),
+)
+
+configuration = Configuration()
+configuration.access_token = environ["DD_BEARER_TOKEN"]
+configuration.unstable_operations["evaluate_ai_guard_request"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = AIGuardApi(api_client)
+    response = api_instance.evaluate_ai_guard_request(body=body)
+
+    print(response)

examples/v2/ai-guard/EvaluateAIGuardRequest_3923646360.py

@@ -0,0 +1,40 @@
+"""
+Evaluate an AI Guard request with a numeric confidence threshold
+"""
+
+from os import environ
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.ai_guard_api import AIGuardApi
+from datadog_api_client.v2.model.ai_guard_evaluate_request import AIGuardEvaluateRequest
+from datadog_api_client.v2.model.ai_guard_evaluate_request_data import AIGuardEvaluateRequestData
+from datadog_api_client.v2.model.ai_guard_evaluate_request_data_attributes import AIGuardEvaluateRequestDataAttributes
+from datadog_api_client.v2.model.ai_guard_evaluation_type import AIGuardEvaluationType
+from datadog_api_client.v2.model.ai_guard_message import AIGuardMessage
+from datadog_api_client.v2.model.ai_guard_message_role import AIGuardMessageRole
+from datadog_api_client.v2.model.ai_guard_meta import AIGuardMeta
+
+body = AIGuardEvaluateRequest(
+    data=AIGuardEvaluateRequestData(
+        type=AIGuardEvaluationType.EVALUATIONS,
+        attributes=AIGuardEvaluateRequestDataAttributes(
+            messages=[
+                AIGuardMessage(
+                    role=AIGuardMessageRole.USER,
+                    content="Hello world!",
+                ),
+            ],
+            meta=AIGuardMeta(
+                confidence_threshold=0.8,
+            ),
+        ),
+    ),
+)
+
+configuration = Configuration()
+configuration.access_token = environ["DD_BEARER_TOKEN"]
+configuration.unstable_operations["evaluate_ai_guard_request"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = AIGuardApi(api_client)
+    response = api_instance.evaluate_ai_guard_request(body=body)
+
+    print(response)

src/datadog_api_client/configuration.py

@@ -341,6 +341,7 @@ def __init__(
                 "v2.get_execution_policy": False,
                 "v2.list_execution_policies": False,
                 "v2.update_execution_policy": False,
+                "v2.evaluate_ai_guard_request": False,
                 "v2.create_annotation": False,
                 "v2.delete_annotation": False,
                 "v2.get_page_annotations": False,

src/datadog_api_client/v2/api/ai_guard_api.py

@@ -0,0 +1,71 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from datadog_api_client.api_client import ApiClient, Endpoint as _Endpoint
+from datadog_api_client.configuration import Configuration
+from datadog_api_client.v2.model.ai_guard_evaluate_response import AIGuardEvaluateResponse
+from datadog_api_client.v2.model.ai_guard_evaluate_request import AIGuardEvaluateRequest
+
+
+class AIGuardApi:
+    """
+    Evaluate LLM interactions for security threats such as prompt injection and jailbreak attempts.
+    """
+
+    def __init__(self, api_client=None):
+        if api_client is None:
+            api_client = ApiClient(Configuration())
+        self.api_client = api_client
+
+        self._evaluate_ai_guard_request_endpoint = _Endpoint(
+            settings={
+                "response_type": (AIGuardEvaluateResponse,),
+                "auth": ["apiKeyAuth", "appKeyAuth", "AuthZ"],
+                "endpoint_path": "/api/v2/ai-guard/evaluate",
+                "operation_id": "evaluate_ai_guard_request",
+                "http_method": "POST",
+                "version": "v2",
+            },
+            params_map={
+                "body": {
+                    "required": True,
+                    "openapi_types": (AIGuardEvaluateRequest,),
+                    "location": "body",
+                },
+            },
+            headers_map={"accept": ["application/json"], "content_type": ["application/json"]},
+            api_client=api_client,
+        )
+
+    def evaluate_ai_guard_request(
+        self,
+        body: AIGuardEvaluateRequest,
+    ) -> AIGuardEvaluateResponse:
+        """Evaluate an AI Guard request.
+
+        Analyzes a conversation for security threats such as prompt injection,
+        jailbreak attempts, and other AI-specific attacks. Returns an action
+        recommendation ( ``ALLOW`` , ``DENY`` , or ``ABORT`` ) along with the detected threat
+        tags and their confidence scores.
+        AI Guard must be activated for the organization, and the calling user or
+        application key requires the ``ai_guard_evaluate`` permission. The action is a
+        recommendation for the caller to enforce: ALLOW permits the interaction,
+        DENY blocks the interaction, and ABORT terminates the workflow.
+        This endpoint is rate limited to ``700`` requests per minute per organization.
+        Organization token limits can also result in a 429 response.
+        Malformed messages return a 400 response. Requests exceeding the raw-input
+        limit of 1,000,000 tokens return a 413 response; this limit applies to the
+        input context, not only the size of the HTTP request body.
+
+        :param body: The conversation to evaluate for security threats.
+        :type body: AIGuardEvaluateRequest
+        :rtype: AIGuardEvaluateResponse
+        """
+        kwargs: Dict[str, Any] = {}
+        kwargs["body"] = body
+
+        return self._evaluate_ai_guard_request_endpoint.call_with_http_info(**kwargs)

src/datadog_api_client/v2/apis/__init__.py

@@ -1,3 +1,4 @@
+from datadog_api_client.v2.api.ai_guard_api import AIGuardApi
 from datadog_api_client.v2.api.api_management_api import APIManagementApi
 from datadog_api_client.v2.api.apm_api import APMApi
 from datadog_api_client.v2.api.apm_retention_filters_api import APMRetentionFiltersApi
@@ -154,6 +155,7 @@
 
 
 __all__ = [
+    "AIGuardApi",
     "APIManagementApi",
     "APMApi",
     "APMRetentionFiltersApi",

src/datadog_api_client/v2/model/ai_guard_action.py

@@ -0,0 +1,41 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class AIGuardAction(ModelSimple):
+    """
+    The recommended action for the evaluated conversation.
+
+    :param value: Must be one of ["ALLOW", "DENY", "ABORT"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "ALLOW",
+        "DENY",
+        "ABORT",
+    }
+    ALLOW: ClassVar["AIGuardAction"]
+    DENY: ClassVar["AIGuardAction"]
+    ABORT: ClassVar["AIGuardAction"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+AIGuardAction.ALLOW = AIGuardAction("ALLOW")
+AIGuardAction.DENY = AIGuardAction("DENY")
+AIGuardAction.ABORT = AIGuardAction("ABORT")

src/datadog_api_client/v2/model/ai_guard_confidence_threshold.py

@@ -0,0 +1,49 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+class AIGuardConfidenceThreshold(ModelNormal):
+    @cached_property
+    def additional_properties_type(_):
+        return (float,)
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "flagging_global": (float,),
+        }
+
+    attribute_map = {
+        "flagging_global": "flagging_global",
+    }
+
+    def __init__(self_, flagging_global: Union[float, UnsetType] = unset, **kwargs):
+        """
+        Request-level confidence threshold override. ``flagging_global`` is the global
+        threshold applied to every threat category. Any other property is a
+        per-category override keyed by an AI Guard threat tag; per-category values
+        take precedence over ``flagging_global`` , and categories without an entry fall
+        back to it. When this object omits flagging_global, the fallback is ``0.5``.
+        Recognized category keys include policy-evasion, indirect-prompt-injection,
+        system-and-capability-discovery, credential-access, sensitive-data-collection,
+        privilege-escalation, malicious-execution, private-network-target,
+        destructive-or-resource-abuse, tool-abuse, poisoning-or-persistence, and
+        ``data-exfiltration``. Unknown category keys are ignored.
+
+        :param flagging_global: The global confidence threshold applied to categories without a specific override.
+        :type flagging_global: float, optional
+        """
+        if flagging_global is not unset:
+            kwargs["flagging_global"] = flagging_global
+        super().__init__(kwargs)

src/datadog_api_client/v2/model/ai_guard_confidence_threshold_override.py

@@ -0,0 +1,42 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+
+from datadog_api_client.model_utils import (
+    ModelComposed,
+    cached_property,
+)
+
+
+class AIGuardConfidenceThresholdOverride(ModelComposed):
+    def __init__(self, **kwargs):
+        """
+        Request-only confidence threshold override. A number sets the threshold
+        for every threat category; an object supplies a global threshold and
+        optional per-category overrides. Omit this field to use the stored
+        sensitivity policy. This field is not returned in evaluation responses.
+
+        :param flagging_global: The global confidence threshold applied to categories without a specific override.
+        :type flagging_global: float, optional
+        """
+        super().__init__(kwargs)
+
+    @cached_property
+    def _composed_schemas(_):
+        # we need this here to make our import statements work
+        # we must store _composed_schemas in here so the code is only run
+        # when we invoke this method. If we kept this at the class
+        # level we would get an error because the class level
+        # code would be run when this module is imported, and these composed
+        # classes don't exist yet because their module has not finished
+        # loading
+        from datadog_api_client.v2.model.ai_guard_confidence_threshold import AIGuardConfidenceThreshold
+
+        return {
+            "oneOf": [
+                float,
+                AIGuardConfidenceThreshold,
+            ],
+        }