Document managed prompt message placeholders

.generator/schemas/v2/openapi.yaml

@@ -63786,10 +63786,15 @@ components:
     LLMObsPromptChatTemplate:
       description: A chat prompt template.
       items:
-        $ref: "#/components/schemas/LLMObsPromptChatMessage"
+        $ref: "#/components/schemas/LLMObsPromptChatTemplateItem"
       minItems: 1
       type: array
       x-generate-alias-as-model: true
+    LLMObsPromptChatTemplateItem:
+      description: A chat message or a named message placeholder in a prompt template.
+      oneOf:
+        - $ref: "#/components/schemas/LLMObsPromptChatMessage"
+        - $ref: "#/components/schemas/LLMObsPromptMessagePlaceholder"
     LLMObsPromptData:
       description: Data object for an Agent Observability prompt.
       properties:
@@ -63891,6 +63896,30 @@ components:
       required:
         - id
       type: object
+    LLMObsPromptMessagePlaceholder:
+      additionalProperties: false
+      description: A named placeholder that inserts a list of messages when a compatible SDK formats the prompt.
+      properties:
+        name:
+          description: Name used to supply the message list when formatting the prompt.
+          example: "history"
+          minLength: 1
+          pattern: "^\\w+$"
+          type: string
+        type:
+          $ref: "#/components/schemas/LLMObsPromptMessagePlaceholderType"
+      required:
+        - type
+        - name
+      type: object
+    LLMObsPromptMessagePlaceholderType:
+      description: Type of the chat-template item.
+      enum:
+        - placeholder
+      example: "placeholder"
+      type: string
+      x-enum-varnames:
+        - PLACEHOLDER
     LLMObsPromptResponse:
       description: Response containing a single Agent Observability prompt.
       example:
@@ -63946,9 +63975,9 @@ components:
       properties:
         chat_template:
           description: >-
-            Chat template for this prompt version, as a list of role and content messages. Omitted for text templates.
+            Chat template for this prompt version, as a list of messages and named message placeholders. Omitted for text templates.
           items:
-            $ref: "#/components/schemas/LLMObsPromptChatMessage"
+            $ref: "#/components/schemas/LLMObsPromptChatTemplateItem"
           type: array
         labels:
           deprecated: true
@@ -63981,6 +64010,8 @@ components:
             chat_template:
               - content: "You are a helpful customer support assistant for {{company_name}}."
                 role: "system"
+              - name: "history"
+                type: "placeholder"
               - content: "Help {{customer_name}} with this question: {{question}}"
                 role: "user"
             prompt_id: "customer-support-assistant"

src/datadog_api_client/v2/model/llm_obs_create_prompt_data_attributes.py

@@ -16,7 +16,7 @@
 if TYPE_CHECKING:
     from datadog_api_client.v2.model.llm_obs_prompt_version_label import LLMObsPromptVersionLabel
     from datadog_api_client.v2.model.llm_obs_prompt_template import LLMObsPromptTemplate
-    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
 
 
 class LLMObsCreatePromptDataAttributes(ModelNormal):
@@ -54,7 +54,11 @@ def openapi_types(_):
     def __init__(
         self_,
         prompt_id: str,
-        template: Union[LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage]],
+        template: Union[
+            LLMObsPromptTemplate,
+            str,
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+        ],
         description: Union[str, UnsetType] = unset,
         env_ids: Union[List[str], UnsetType] = unset,
         labels: Union[List[LLMObsPromptVersionLabel], UnsetType] = unset,

src/datadog_api_client/v2/model/llm_obs_create_prompt_version_data_attributes.py

@@ -16,7 +16,7 @@
 if TYPE_CHECKING:
     from datadog_api_client.v2.model.llm_obs_prompt_version_label import LLMObsPromptVersionLabel
     from datadog_api_client.v2.model.llm_obs_prompt_template import LLMObsPromptTemplate
-    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
 
 
 class LLMObsCreatePromptVersionDataAttributes(ModelNormal):
@@ -43,7 +43,11 @@ def openapi_types(_):
 
     def __init__(
         self_,
-        template: Union[LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage]],
+        template: Union[
+            LLMObsPromptTemplate,
+            str,
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+        ],
         description: Union[str, UnsetType] = unset,
         env_ids: Union[List[str], UnsetType] = unset,
         labels: Union[List[LLMObsPromptVersionLabel], UnsetType] = unset,

src/datadog_api_client/v2/model/llm_obs_prompt_chat_template_item.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 datadog_api_client.model_utils import (
+    ModelComposed,
+    cached_property,
+)
+
+
+class LLMObsPromptChatTemplateItem(ModelComposed):
+    def __init__(self, **kwargs):
+        """
+        A chat message or a named message placeholder in a prompt template.
+
+        :param content: Content of the message.
+        :type content: str
+
+        :param role: Role of the message (for example `system`, `user`, or `assistant`).
+        :type role: str
+
+        :param name: Name used to supply the message list when formatting the prompt.
+        :type name: str
+
+        :param type: Type of the chat-template item.
+        :type type: LLMObsPromptMessagePlaceholderType
+        """
+        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.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+        from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
+
+        return {
+            "oneOf": [
+                LLMObsPromptChatMessage,
+                LLMObsPromptMessagePlaceholder,
+            ],
+        }

src/datadog_api_client/v2/model/llm_obs_prompt_message_placeholder.py

@@ -0,0 +1,58 @@
+# 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 TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder_type import LLMObsPromptMessagePlaceholderType
+
+
+class LLMObsPromptMessagePlaceholder(ModelNormal):
+    validations = {
+        "name": {
+            "min_length": 1,
+        },
+    }
+
+    @cached_property
+    def additional_properties_type(_):
+        return None
+
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder_type import (
+            LLMObsPromptMessagePlaceholderType,
+        )
+
+        return {
+            "name": (str,),
+            "type": (LLMObsPromptMessagePlaceholderType,),
+        }
+
+    attribute_map = {
+        "name": "name",
+        "type": "type",
+    }
+
+    def __init__(self_, name: str, type: LLMObsPromptMessagePlaceholderType, **kwargs):
+        """
+        A named placeholder that inserts a list of messages when a compatible SDK formats the prompt.
+
+        :param name: Name used to supply the message list when formatting the prompt.
+        :type name: str
+
+        :param type: Type of the chat-template item.
+        :type type: LLMObsPromptMessagePlaceholderType
+        """
+        super().__init__(kwargs)
+
+        self_.name = name
+        self_.type = type

src/datadog_api_client/v2/model/llm_obs_prompt_message_placeholder_type.py

@@ -0,0 +1,35 @@
+# 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 LLMObsPromptMessagePlaceholderType(ModelSimple):
+    """
+    Type of the chat-template item.
+
+    :param value: If omitted defaults to "placeholder". Must be one of ["placeholder"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "placeholder",
+    }
+    PLACEHOLDER: ClassVar["LLMObsPromptMessagePlaceholderType"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+LLMObsPromptMessagePlaceholderType.PLACEHOLDER = LLMObsPromptMessagePlaceholderType("placeholder")

src/datadog_api_client/v2/model/llm_obs_prompt_sdk_data_attributes.py

@@ -14,16 +14,18 @@
 
 
 if TYPE_CHECKING:
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
     from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
 
 
 class LLMObsPromptSDKDataAttributes(ModelNormal):
     @cached_property
     def openapi_types(_):
-        from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+        from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
 
         return {
-            "chat_template": ([LLMObsPromptChatMessage],),
+            "chat_template": ([LLMObsPromptChatTemplateItem],),
             "labels": ([str],),
             "prompt_id": (str,),
             "prompt_version_uuid": (str,),
@@ -42,7 +44,10 @@ def openapi_types(_):
 
     def __init__(
         self_,
-        chat_template: Union[List[LLMObsPromptChatMessage], UnsetType] = unset,
+        chat_template: Union[
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+            UnsetType,
+        ] = unset,
         labels: Union[List[str], UnsetType] = unset,
         prompt_id: Union[str, UnsetType] = unset,
         prompt_version_uuid: Union[str, UnsetType] = unset,
@@ -53,8 +58,8 @@ def __init__(
         """
         Attributes of a flattened prompt version returned for SDK consumption. Exactly one of ``template`` and ``chat_template`` is returned.
 
-        :param chat_template: Chat template for this prompt version, as a list of role and content messages. Omitted for text templates.
-        :type chat_template: [LLMObsPromptChatMessage], optional
+        :param chat_template: Chat template for this prompt version, as a list of messages and named message placeholders. Omitted for text templates.
+        :type chat_template: [LLMObsPromptChatTemplateItem], optional
 
         :param labels: Labels attached to the selected version. **Deprecated**.
         :type labels: [str], optional

src/datadog_api_client/v2/model/llm_obs_prompt_template.py

@@ -26,11 +26,11 @@ def _composed_schemas(_):
         # 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.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+        from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
 
         return {
             "oneOf": [
                 str,
-                [LLMObsPromptChatMessage],
+                [LLMObsPromptChatTemplateItem],
             ],
         }

src/datadog_api_client/v2/model/llm_obs_prompt_version_data_attributes.py

@@ -17,7 +17,7 @@
 if TYPE_CHECKING:
     from datadog_api_client.v2.model.llm_obs_prompt_dataset import LLMObsPromptDataset
     from datadog_api_client.v2.model.llm_obs_prompt_template import LLMObsPromptTemplate
-    from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+    from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
 
 
 class LLMObsPromptVersionDataAttributes(ModelNormal):
@@ -72,7 +72,11 @@ def __init__(
         self_,
         prompt_id: str,
         prompt_uuid: str,
-        template: Union[LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage]],
+        template: Union[
+            LLMObsPromptTemplate,
+            str,
+            List[Union[LLMObsPromptChatTemplateItem, LLMObsPromptChatMessage, LLMObsPromptMessagePlaceholder]],
+        ],
         version: int,
         author: Union[str, UnsetType] = unset,
         created_at: Union[datetime, UnsetType] = unset,

src/datadog_api_client/v2/models/__init__.py

@@ -5044,9 +5044,12 @@
 from datadog_api_client.v2.model.llm_obs_project_update_request import LLMObsProjectUpdateRequest
 from datadog_api_client.v2.model.llm_obs_projects_response import LLMObsProjectsResponse
 from datadog_api_client.v2.model.llm_obs_prompt_chat_message import LLMObsPromptChatMessage
+from datadog_api_client.v2.model.llm_obs_prompt_chat_template_item import LLMObsPromptChatTemplateItem
 from datadog_api_client.v2.model.llm_obs_prompt_data import LLMObsPromptData
 from datadog_api_client.v2.model.llm_obs_prompt_data_attributes import LLMObsPromptDataAttributes
 from datadog_api_client.v2.model.llm_obs_prompt_dataset import LLMObsPromptDataset
+from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder import LLMObsPromptMessagePlaceholder
+from datadog_api_client.v2.model.llm_obs_prompt_message_placeholder_type import LLMObsPromptMessagePlaceholderType
 from datadog_api_client.v2.model.llm_obs_prompt_response import LLMObsPromptResponse
 from datadog_api_client.v2.model.llm_obs_prompt_response_source import LLMObsPromptResponseSource
 from datadog_api_client.v2.model.llm_obs_prompt_sdk_data import LLMObsPromptSDKData
@@ -15234,9 +15237,12 @@
     "LLMObsProjectUpdateRequest",
     "LLMObsProjectsResponse",
     "LLMObsPromptChatMessage",
+    "LLMObsPromptChatTemplateItem",
     "LLMObsPromptData",
     "LLMObsPromptDataAttributes",
     "LLMObsPromptDataset",
+    "LLMObsPromptMessagePlaceholder",
+    "LLMObsPromptMessagePlaceholderType",
     "LLMObsPromptResponse",
     "LLMObsPromptResponseSource",
     "LLMObsPromptSDKData",