LLMObs Document version-pinned prompt composition

.generator/schemas/v2/openapi.yaml

@@ -64785,6 +64785,26 @@ components:
       required:
         - data
       type: object
+    LLMObsPromptAuthoringChatTemplate:
+      description: A chat prompt containing messages, references to specific versions of other prompts, or both.
+      items:
+        $ref: "#/components/schemas/LLMObsPromptAuthoringItem"
+      minItems: 1
+      type: array
+    LLMObsPromptAuthoringItem:
+      description: >-
+        A chat message or a reference to a specific version of another prompt. A chat message must not contain an `include` field; the API rejects items that combine both forms.
+      oneOf:
+        - $ref: "#/components/schemas/LLMObsPromptChatMessage"
+        - $ref: "#/components/schemas/LLMObsPromptIncludeItem"
+    LLMObsPromptAuthoringMessagesTemplate:
+      description: A chat prompt whose authored items are stored under `messages`.
+      properties:
+        messages:
+          $ref: "#/components/schemas/LLMObsPromptAuthoringChatTemplate"
+      required:
+        - messages
+      type: object
     LLMObsPromptChatMessage:
       description: A single chat message in a prompt template.
       properties:
@@ -64919,6 +64939,46 @@ components:
       required:
         - id
       type: object
+    LLMObsPromptInclude:
+      additionalProperties: false
+      description: >-
+        Includes messages from a specific version of another prompt. Omitting `items` includes every message from that version in its original order. When `items` is present, messages are included in the specified order, including repetitions.
+      properties:
+        items:
+          description: >-
+            Zero-based indexes of messages from the included prompt. For example, `[2, 0, 0]` includes the third message, followed by the first message twice. Omit this field to include all messages in their original order.
+          items:
+            format: int64
+            maximum: 2147483647
+            minimum: 0
+            type: integer
+          minItems: 1
+          type: array
+        prompt_id:
+          description: Customer-provided identifier of the included prompt.
+          example: "response-policy"
+          minLength: 1
+          type: string
+        version:
+          description: Positive sequential version number of the included prompt.
+          example: 3
+          format: int64
+          maximum: 2147483647
+          minimum: 1
+          type: integer
+      required:
+        - prompt_id
+        - version
+      type: object
+    LLMObsPromptIncludeItem:
+      additionalProperties: false
+      description: Includes all or selected messages from a specific version of another prompt.
+      properties:
+        include:
+          $ref: "#/components/schemas/LLMObsPromptInclude"
+      required:
+        - include
+      type: object
     LLMObsPromptResponse:
       description: Response containing a single Agent Observability prompt.
       example:
@@ -65028,11 +65088,17 @@ components:
         - data
       type: object
     LLMObsPromptTemplate:
-      description: A text template or a list of chat messages.
+      description: >-
+        A text template, a list of chat messages, or an authored chat object. Text can include an exact prompt version with `{{>prompt-id version=N}}`; other text, including `{{>...}}` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
+
+        **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager.
+
+        Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution.
       example: "You are a helpful assistant for {{audience}}."
       oneOf:
         - $ref: "#/components/schemas/LLMObsPromptTextTemplate"
         - $ref: "#/components/schemas/LLMObsPromptChatTemplate"
+        - $ref: "#/components/schemas/LLMObsPromptAuthoringMessagesTemplate"
     LLMObsPromptTextTemplate:
       description: A text prompt template.
       minLength: 1
@@ -65064,11 +65130,13 @@ components:
       type: object
     LLMObsPromptVersionDataAttributes:
       description: >-
-        Attributes of a specific version of an Agent Observability prompt. Empty `config` is omitted when configuration authoring is disabled for the organization. Non-empty saved configuration is always returned.
+        Attributes of a specific version of an Agent Observability prompt. For a composed version, `authoring_template` contains its pinned include-bearing source; ordinary versions omit that attribute. Empty `config` is omitted when configuration authoring is disabled for the organization. Non-empty saved configuration is always returned.
       properties:
         author:
           description: UUID of the user who authored this version.
           type: string
+        authoring_template:
+          $ref: "#/components/schemas/LLMObsPromptTemplate"
         config:
           $ref: "#/components/schemas/LLMObsPromptConfig"
         created_at:
@@ -175955,7 +176023,10 @@ paths:
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
     post:
-      description: Create a new prompt (and its first version) in the Agent Observability prompt registry.
+      description: |-
+        Create a new prompt (and its first version) in the Agent Observability prompt registry.
+
+        > **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager.
       operationId: CreateLLMObsPrompt
       requestBody:
         content:
@@ -176332,14 +176403,42 @@ paths:
         **Note**: This endpoint is in preview and is subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
     post:
-      description: Create a new version of an existing Agent Observability prompt.
+      description: |-
+        Create a new version of an existing Agent Observability prompt.
+
+        > **Preview**: Prompt composition is available in Preview. To request access, contact [Datadog Support](https://docs.datadoghq.com/help/) or your Customer Success Manager.
       operationId: CreateLLMObsPromptVersion
       parameters:
         - $ref: "#/components/parameters/LLMObsPromptIDPathParameter"
       requestBody:
         content:
           application/json:
             examples:
+              composed_chat:
+                summary: Create a version that includes all or selected messages from other prompts
+                value:
+                  data:
+                    attributes:
+                      template:
+                        messages:
+                          - include:
+                              prompt_id: "assistant-introduction"
+                              version: 2
+                          - include:
+                              items: [2, 0, 0]
+                              prompt_id: "response-examples"
+                              version: 4
+                          - content: "Answer {{question}}."
+                            role: "user"
+                    type: prompt-template-versions
+              composed_text:
+                summary: Create a version that includes text from another prompt
+                value:
+                  data:
+                    attributes:
+                      description: "Reuse the exact response policy."
+                      template: "{{>response-policy version=3}}\n\nAnswer {{question}}."
+                    type: prompt-template-versions
               default:
                 value:
                   data:
@@ -176363,6 +176462,50 @@ paths:
           content:
             application/json:
               examples:
+                composed_chat:
+                  summary: A composed chat version preserves structured authored includes
+                  value:
+                    data:
+                      attributes:
+                        authoring_template:
+                          messages:
+                            - include:
+                                prompt_id: "assistant-introduction"
+                                version: 2
+                            - include:
+                                items: [2, 0, 0]
+                                prompt_id: "response-examples"
+                                version: 4
+                            - content: "Answer {{question}}."
+                              role: "user"
+                        prompt_id: "support-chat"
+                        prompt_uuid: "4a1a28ff-8a25-5f0f-946f-f48264d772eb"
+                        template:
+                          - content: "You are a helpful assistant."
+                            role: "system"
+                          - content: "Here is one concise example."
+                            role: "assistant"
+                          - content: "You are a helpful assistant."
+                            role: "system"
+                          - content: "You are a helpful assistant."
+                            role: "system"
+                          - content: "Answer {{question}}."
+                            role: "user"
+                        version: 2
+                      id: "d83ab666-61cc-5545-a83b-2424bb85467b"
+                      type: prompt-template-versions
+                composed_text:
+                  summary: A composed text version returns compiled and authored templates
+                  value:
+                    data:
+                      attributes:
+                        authoring_template: "{{>response-policy version=3}}\n\nAnswer {{question}}."
+                        prompt_id: "support-answer"
+                        prompt_uuid: "4a1a28ff-8a25-5f0f-946f-f48264d772eb"
+                        template: "Follow the approved response policy.\n\nAnswer {{question}}."
+                        version: 2
+                      id: "d83ab666-61cc-5545-a83b-2424bb85467b"
+                      type: prompt-template-versions
                 default:
                   value:
                     data:

src/datadog_api_client/v2/api/agent_observability_api.py

@@ -2482,6 +2482,11 @@ def create_llm_obs_prompt(
 
         Create a new prompt (and its first version) in the Agent Observability prompt registry.
 
+        ..
+
+           **Preview** : Prompt composition is available in Preview. To request access, contact `Datadog Support <https://docs.datadoghq.com/help/>`_ or your Customer Success Manager.
+
+
         :param body: Create prompt payload.
         :type body: LLMObsCreatePromptRequest
         :rtype: LLMObsCreatePromptResponse
@@ -2500,6 +2505,11 @@ def create_llm_obs_prompt_version(
 
         Create a new version of an existing Agent Observability prompt.
 
+        ..
+
+           **Preview** : Prompt composition is available in Preview. To request access, contact `Datadog Support <https://docs.datadoghq.com/help/>`_ or your Customer Success Manager.
+
+
         :param prompt_id: The customer-provided identifier of the Agent Observability prompt.
         :type prompt_id: str
         :param body: Create prompt version payload.

src/datadog_api_client/v2/model/llm_obs_create_prompt_data_attributes.py

@@ -18,6 +18,9 @@
     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_authoring_messages_template import (
+        LLMObsPromptAuthoringMessagesTemplate,
+    )
 
 
 class LLMObsCreatePromptDataAttributes(ModelNormal):
@@ -58,7 +61,9 @@ def openapi_types(_):
     def __init__(
         self_,
         prompt_id: str,
-        template: Union[LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage]],
+        template: Union[
+            LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage], LLMObsPromptAuthoringMessagesTemplate
+        ],
         config: Union[LLMObsPromptConfig, UnsetType] = unset,
         description: Union[str, UnsetType] = unset,
         env_ids: Union[List[str], UnsetType] = unset,
@@ -85,7 +90,9 @@ def __init__(
         :param prompt_id: Customer-provided identifier for the new prompt.
         :type prompt_id: str
 
-        :param template: A text template or a list of chat messages.
+        :param template: A text template, a list of chat messages, or an authored chat object. Text can include an exact prompt version with ``{{>prompt-id version=N}}`` ; other text, including ``{{>...}}`` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
+            **Preview** : Prompt composition is available in Preview. To request access, contact `Datadog Support <https://docs.datadoghq.com/help/>`_ or your Customer Success Manager.
+            Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution.
         :type template: LLMObsPromptTemplate
 
         :param title: Optional title of the prompt.

src/datadog_api_client/v2/model/llm_obs_create_prompt_version_data_attributes.py

@@ -18,6 +18,9 @@
     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_authoring_messages_template import (
+        LLMObsPromptAuthoringMessagesTemplate,
+    )
 
 
 class LLMObsCreatePromptVersionDataAttributes(ModelNormal):
@@ -47,7 +50,9 @@ def openapi_types(_):
 
     def __init__(
         self_,
-        template: Union[LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage]],
+        template: Union[
+            LLMObsPromptTemplate, str, List[LLMObsPromptChatMessage], LLMObsPromptAuthoringMessagesTemplate
+        ],
         config: Union[LLMObsPromptConfig, UnsetType] = unset,
         description: Union[str, UnsetType] = unset,
         env_ids: Union[List[str], UnsetType] = unset,
@@ -70,7 +75,9 @@ def __init__(
         :param labels: Optional labels to attach to this version. Do not use this attribute for new integrations. **Deprecated**.
         :type labels: [LLMObsPromptVersionLabel], optional
 
-        :param template: A text template or a list of chat messages.
+        :param template: A text template, a list of chat messages, or an authored chat object. Text can include an exact prompt version with ``{{>prompt-id version=N}}`` ; other text, including ``{{>...}}`` sequences without a version, remains literal. Use an authored chat object when including prompts as chat messages.
+            **Preview** : Prompt composition is available in Preview. To request access, contact `Datadog Support <https://docs.datadoghq.com/help/>`_ or your Customer Success Manager.
+            Without access, inline references remain literal text and structured includes are unsupported. Previously compiled prompt versions remain available for execution.
         :type template: LLMObsPromptTemplate
 
         :param user_version: Optional user-supplied version identifier for this version.

src/datadog_api_client/v2/model/llm_obs_prompt_authoring_item.py

@@ -0,0 +1,46 @@
+# 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 LLMObsPromptAuthoringItem(ModelComposed):
+    def __init__(self, **kwargs):
+        """
+        A chat message or a reference to a specific version of another prompt. A chat message must not contain an ``include`` field; the API rejects items that combine both forms.
+
+        :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 include: Includes messages from a specific version of another prompt. Omitting `items` includes every message from that version in its original order. When `items` is present, messages are included in the specified order, including repetitions.
+        :type include: LLMObsPromptInclude
+        """
+        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_include_item import LLMObsPromptIncludeItem
+
+        return {
+            "oneOf": [
+                LLMObsPromptChatMessage,
+                LLMObsPromptIncludeItem,
+            ],
+        }