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:

lib/datadog_api_client/inflector.rb

@@ -5044,10 +5044,14 @@ def overrides
           "v2.llm_obs_project_update_data_attributes_request" => "LLMObsProjectUpdateDataAttributesRequest",
           "v2.llm_obs_project_update_data_request" => "LLMObsProjectUpdateDataRequest",
           "v2.llm_obs_project_update_request" => "LLMObsProjectUpdateRequest",
+          "v2.llm_obs_prompt_authoring_item" => "LLMObsPromptAuthoringItem",
+          "v2.llm_obs_prompt_authoring_messages_template" => "LLMObsPromptAuthoringMessagesTemplate",
           "v2.llm_obs_prompt_chat_message" => "LLMObsPromptChatMessage",
           "v2.llm_obs_prompt_data" => "LLMObsPromptData",
           "v2.llm_obs_prompt_data_attributes" => "LLMObsPromptDataAttributes",
           "v2.llm_obs_prompt_dataset" => "LLMObsPromptDataset",
+          "v2.llm_obs_prompt_include" => "LLMObsPromptInclude",
+          "v2.llm_obs_prompt_include_item" => "LLMObsPromptIncludeItem",
           "v2.llm_obs_prompt_response" => "LLMObsPromptResponse",
           "v2.llm_obs_prompt_response_source" => "LLMObsPromptResponseSource",
           "v2.llm_obs_prompt_sdk_data" => "LLMObsPromptSDKData",

lib/datadog_api_client/v2/api/agent_observability_api.rb

@@ -914,6 +914,8 @@ def create_llm_obs_prompt(body, opts = {})
     #
     # 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 [LLMObsCreatePromptRequest] Create prompt payload.
     # @param opts [Hash] the optional parameters
     # @return [Array<(LLMObsCreatePromptResponse, Integer, Hash)>] LLMObsCreatePromptResponse data, response status code and response headers
@@ -987,6 +989,8 @@ def create_llm_obs_prompt_version(prompt_id, body, opts = {})
     #
     # 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 [String] The customer-provided identifier of the Agent Observability prompt.
     # @param body [LLMObsCreatePromptVersionRequest] Create prompt version payload.
     # @param opts [Hash] the optional parameters

lib/datadog_api_client/v2/models/llm_obs_create_prompt_data_attributes.rb

@@ -36,7 +36,9 @@ class LLMObsCreatePromptDataAttributes
     # Customer-provided identifier for the new prompt.
     attr_reader :prompt_id
 
-    # A text template or a list of chat messages.
+    # 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.
     attr_reader :template
 
     # Optional title of the prompt.

lib/datadog_api_client/v2/models/llm_obs_create_prompt_version_data_attributes.rb

@@ -33,7 +33,9 @@ class LLMObsCreatePromptVersionDataAttributes
     # Optional labels to attach to this version. Do not use this attribute for new integrations.
     attr_accessor :labels
 
-    # A text template or a list of chat messages.
+    # 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.
     attr_reader :template
 
     # Optional user-supplied version identifier for this version.

lib/datadog_api_client/v2/models/llm_obs_prompt_authoring_item.rb

@@ -0,0 +1,63 @@
+=begin
+#Datadog API V2 Collection
+
+#Collection of all Datadog Public endpoints.
+
+The version of the OpenAPI document: 1.0
+Contact: support@datadoghq.com
+Generated by: https://github.com/DataDog/datadog-api-client-ruby/tree/master/.generator
+
+ 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 2020-Present Datadog, Inc.
+
+=end
+
+require 'date'
+require 'time'
+
+module DatadogAPIClient::V2
+  # 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.
+  module LLMObsPromptAuthoringItem
+    class << self
+      include BaseOneOfModel
+      include BaseOneOfModelNoDiscriminator
+
+      # List of class defined in oneOf (OpenAPI v3)
+      def openapi_one_of
+        [
+          :'LLMObsPromptChatMessage',
+          :'LLMObsPromptIncludeItem'
+        ]
+      end
+      # Builds the object
+      # @param data [Mixed] Data to be matched against the list of oneOf items
+      # @return [Object] Returns the model or the data itself
+      def build(data)
+        # Go through the list of oneOf items and attempt to identify the appropriate one.
+        # Note:
+        # - We do not attempt to check whether exactly one item matches.
+        # - No advanced validation of types in some cases (e.g. "x: { type: string }" will happily match { x: 123 })
+        #   due to the way the deserialization is made in the base_object template (it just casts without verifying).
+        # - TODO: scalar values are de facto behaving as if they were nullable.
+        # - TODO: logging when debugging is set.
+        openapi_one_of.each do |klass|
+          begin
+            next if klass == :AnyType # "nullable: true"
+            typed_data = find_and_cast_into_type(klass, data)
+            next if typed_data.respond_to?(:_unparsed) && typed_data._unparsed
+            return typed_data if typed_data
+          rescue # rescue all errors so we keep iterating even if the current item lookup raises
+          end
+        end
+
+        if openapi_one_of.include?(:AnyType)
+          data
+        else
+          self._unparsed = true
+          DatadogAPIClient::UnparsedObject.new(data)
+        end
+      end
+    end
+  end
+end