prompt_builder 0.1.2 → 0.3.0

data/lib/prompt_builder/serializers/chat_completion/response.rb

@@ -16,6 +16,18 @@ module PromptBuilder
         class << self
           private
 
+          # OpenAI errors arrive as {"error" => {"message" => ..., "type" =>
+          # ..., "code" => ...}}; some compatible servers return a bare string
+          # under "error".
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil if error.nil? || hash.key?("choices")
+
+            return error.to_s unless error.is_a?(Hash)
+
+            [error["code"] || error["type"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             validate_response!(hash)
 

data/lib/prompt_builder/serializers/converse/request.rb

@@ -8,6 +8,9 @@ module PromptBuilder
     class Converse < Base
       # Request serializer for the Amazon Bedrock Converse API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+ — populates the required +modelId+ parameter
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -19,7 +22,8 @@ module PromptBuilder
       # - +parallel_tool_calls+ — parallel tool call control is not supported
       # - +presence_penalty+ — not supported by the Converse API
       # - +prompt_cache_key+ / +prompt_cache_retention+ — explicit prompt cache keys are not supported
-      # - +reasoning+ — extended thinking is not supported on the Converse endpoint
+      # - +reasoning+ — extended thinking is not supported on the Converse endpoint;
+      #   a warning is issued (once per process) when +session.reasoning+ is set
       # - +safety_identifier+ — no equivalent user-safety field on the Converse endpoint
       # - +store+ — server-side response storage is not supported
       # - +stream+ — SSE streaming is handled outside the Converse request payload
@@ -35,6 +39,10 @@ module PromptBuilder
       # - +tool_choice: "none"+ has no Converse representation and is omitted
       #
       # Input content restrictions:
+      # - System and developer messages are hoisted out of conversational order
+      #   into the top-level +system+ parameter, with +instructions+ merged last
+      #   (instructions apply to the current request, matching Open Responses
+      #   semantics)
       # - +Reasoning+ items are silently skipped
       # - +RefusalContent+ is dropped silently (a parsed response refusal can
       #   stay in session history without breaking subsequent request_payload calls)
@@ -64,8 +72,11 @@ module PromptBuilder
       # - Prompt management variables (+prompt_variables+)
       #
       # Prompt caching markers (+cachePoint+) are emitted via the +cache_point+
-      # content extra. Cross-region routing via inference profiles is selected
-      # through the model id and needs no request field.
+      # extra on system/message content, tool definitions (appended to the
+      # +toolConfig.tools+ array), and +FunctionCallOutput+ items (appended to
+      # the message content after the +toolResult+ block). Cross-region routing
+      # via inference profiles is selected through the model id and needs no
+      # request field.
       class Request < Base
         IMAGE_MEDIA_TYPE_FORMATS = {
           "image/jpeg" => "jpeg",
@@ -110,6 +121,13 @@ module PromptBuilder
         }.freeze
 
         class << self
+          # Reset the once-per-process reasoning warning. Primarily used in tests.
+          #
+          # @return [void]
+          def reset_reasoning_warning!
+            @reasoning_warning_issued = false
+          end
+
           private
 
           def serialize_request(session)
@@ -118,7 +136,11 @@ module PromptBuilder
             ctx = {document_name_counts: Hash.new(0)}
 
             h = {}
-            h["modelId"] = session.model if session.model
+            raise UnsupportedFormatError, "Converse format requires session.model" unless session.model
+
+            warn_reasoning_unsupported! if session.reasoning
+
+            h["modelId"] = session.model
 
             system = build_system(session)
             h["system"] = system unless system.empty?
@@ -149,11 +171,22 @@ module PromptBuilder
             h["toolConfig"] = tool_config if tool_config
 
             # Session extra: recognized keys for Converse API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             h
           end
 
+          # The Converse endpoint has no reasoning/extended thinking parameter,
+          # so the reasoning config is dropped. Warn once per process instead of
+          # dropping it silently.
+          def warn_reasoning_unsupported!
+            return if @reasoning_warning_issued
+
+            @reasoning_warning_issued = true
+            warn "PromptBuilder: session.reasoning is not supported by the Converse format and was omitted from the request payload"
+          end
+
           def apply_session_extra!(h, extra)
             if extra.key?("stop_sequences")
               inference_config = h["inferenceConfig"] ||= {}
@@ -169,8 +202,6 @@ module PromptBuilder
           def build_system(session)
             parts = []
 
-            parts << {"text" => session.instructions} if session.instructions
-
             session.items.each do |item|
               next unless item.is_a?(Items::Message)
               next unless item.role == "system" || item.role == "developer"
@@ -186,6 +217,11 @@ module PromptBuilder
               end
             end
 
+            # Instructions come last: in the Open Responses API they apply to
+            # the current request, so they must follow any system messages
+            # accumulated in the conversation history.
+            parts << {"text" => session.instructions} if session.instructions
+
             parts
           end
 
@@ -224,10 +260,14 @@ module PromptBuilder
                   }]
                 }
               when Items::FunctionCallOutput
-                raw_messages << {
-                  "role" => "user",
-                  "content" => [serialize_tool_result(item, ctx)]
-                }
+                # The Converse ToolResultContentBlock union has no cachePoint
+                # member; the marker must be a sibling content block after the
+                # toolResult block.
+                content = [serialize_tool_result(item, ctx)]
+                if item.extra && item.extra["cache_point"]
+                  content << {"cachePoint" => {"type" => "default"}}
+                end
+                raw_messages << {"role" => "user", "content" => content}
               when Items::Reasoning, Items::Compaction, Items::ItemReference
                 # Reasoning, Compaction, and ItemReference items are not supported
                 # in the request, so ignore them rather than raising an error.
@@ -240,7 +280,7 @@ module PromptBuilder
 
           def serialize_system_content(content)
             case content
-            when Content::InputText
+            when Content::InputText, Content::Text
               {"text" => content.text}
             when Content::OutputText
               validate_output_text!(content)
@@ -268,7 +308,7 @@ module PromptBuilder
 
           def serialize_content(content, role:, ctx: nil)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               validate_output_text!(content) if content.is_a?(Content::OutputText)
               {"text" => content.text}
             when Content::InputImage
@@ -487,7 +527,7 @@ module PromptBuilder
 
           def serialize_tool_result_content(content, ctx)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               validate_output_text!(content) if content.is_a?(Content::OutputText)
               {"text" => content.text}
             when Content::InputImage
@@ -585,13 +625,17 @@ module PromptBuilder
           end
 
           def build_tools(session)
-            session.tool_definitions.map do |definition|
+            session.tool_definitions.flat_map do |definition|
               tool_spec = {"name" => definition.name}
               tool_spec["description"] = definition.description if definition.description
               tool_spec["inputSchema"] = {
                 "json" => definition.parameters || {"type" => "object", "properties" => {}}
               }
-              {"toolSpec" => tool_spec}
+              tools = [{"toolSpec" => tool_spec}]
+              # The Converse Tool union type has a cachePoint member, so the
+              # marker is its own entry in the tools array.
+              tools << {"cachePoint" => {"type" => "default"}} if definition.extra["cache_point"]
+              tools
             end
           end
 

data/lib/prompt_builder/serializers/converse/response.rb

@@ -10,6 +10,21 @@ module PromptBuilder
         class << self
           private
 
+          # Bedrock exception bodies carry a top-level "message" (the exception
+          # class travels in the x-amzn-ErrorType header) or a top-level
+          # "__type", while misrouted requests get a Coral service envelope
+          # like {"Output" => {"__type" => "..."}, "Version" => "1.0"}.
+          def error_response_message(hash)
+            return nil if hash.key?("output")
+
+            coral_output = hash["Output"].is_a?(Hash) ? hash["Output"] : {}
+            error_type = hash["__type"] || coral_output["__type"]
+            message = hash["message"] || hash["Message"] || coral_output["message"] || coral_output["Message"]
+            return nil unless error_type || message
+
+            [error_type, message].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "output")
             require_response_key!(hash, "stopReason")

data/lib/prompt_builder/serializers/gemini/request.rb

@@ -7,6 +7,11 @@ module PromptBuilder
     class Gemini < Base
       # Request serializer for the Google Gemini API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+ — not part of the payload (it belongs in the request URL) but
+      #   validated so an incomplete session fails at serialization time
+      # - at least one user/model message (the +contents+ array must not be empty)
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -22,6 +27,12 @@ module PromptBuilder
       # - +truncation+ — server-side context truncation is not supported
       #
       # Input content restrictions:
+      # - System and developer messages are hoisted out of conversational order
+      #   into the top-level +systemInstruction+ field, with +instructions+ merged
+      #   last (instructions apply to the current request, matching Open Responses
+      #   semantics)
+      # - Only text content (+InputText+/+OutputText+/+Text+) survives in system
+      #   and developer messages; other content is silently omitted
       # - +InputImage+ content is only supported in user messages (assistant images are omitted)
       # - +InputImage+ with +image_url+ requires either base64 +data+ or a URL;
       #   content without +image_url+ or +file_id+ raises
@@ -115,7 +126,11 @@ module PromptBuilder
             system_instruction = build_system_instruction(session)
             h["systemInstruction"] = system_instruction if system_instruction
 
-            h["contents"] = build_contents(session)
+            contents = build_contents(session)
+            if contents.empty?
+              raise UnsupportedFormatError, "Gemini format requires at least one user/model message"
+            end
+            h["contents"] = contents
 
             generation_config = build_generation_config(session)
             h["generationConfig"] = generation_config unless generation_config.empty?
@@ -127,7 +142,8 @@ module PromptBuilder
             h["toolConfig"] = tool_config if tool_config
 
             # Session extra: recognized keys for Gemini API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             # Gemini selects streaming via endpoint (:streamGenerateContent)
             # rather than a request body field, so session.stream is a no-op
@@ -153,19 +169,24 @@ module PromptBuilder
           def build_system_instruction(session)
             parts = []
 
-            if session.instructions
-              parts << {"text" => session.instructions}
-            end
-
             session.items.each do |item|
               next unless item.is_a?(Items::Message)
               next unless item.role == "system" || item.role == "developer"
 
               item.content.each do |content|
-                parts << {"text" => content.text} if content.is_a?(Content::InputText)
+                if content.is_a?(Content::InputText) || content.is_a?(Content::OutputText) || content.is_a?(Content::Text)
+                  parts << {"text" => content.text}
+                end
               end
             end
 
+            # Instructions come last: in the Open Responses API they apply to
+            # the current request, so they must follow any system messages
+            # accumulated in the conversation history.
+            if session.instructions
+              parts << {"text" => session.instructions}
+            end
+
             return nil if parts.empty?
 
             {"parts" => parts}
@@ -265,7 +286,7 @@ module PromptBuilder
               # types are silently omitted.
               text = output.filter_map do |content|
                 case content
-                when Content::InputText, Content::OutputText
+                when Content::InputText, Content::OutputText, Content::Text
                   content.text
                 end
               end.join("\n")
@@ -298,7 +319,7 @@ module PromptBuilder
 
           def serialize_content(content, role:)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               part = {"text" => content.text}
               if content.extra && content.extra["thought_signature"]
                 part["thoughtSignature"] = content.extra["thought_signature"]

data/lib/prompt_builder/serializers/gemini/response.rb

@@ -63,6 +63,15 @@ module PromptBuilder
         class << self
           private
 
+          # Gemini errors arrive as
+          # {"error" => {"code" => 400, "message" => ..., "status" => ...}}.
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil unless error.is_a?(Hash) && !hash.key?("candidates")
+
+            [error["status"] || error["code"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "candidates")
             require_response_key!(hash, "modelVersion")

data/lib/prompt_builder/serializers/messages/request.rb

@@ -5,6 +5,10 @@ module PromptBuilder
     class Messages < Base
       # Request serializer for the Anthropic Messages API format.
       #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+
+      # - +max_output_tokens+ — populates the required +max_tokens+ parameter
+      #
       # === Unsupported Open Responses features
       #
       # These session fields are not supported and are silently omitted from the
@@ -27,9 +31,17 @@ module PromptBuilder
       # - +service_tier+ — only +auto+ and +standard_only+ are accepted
       # - +text+ — +format.type=json_schema+ is mapped to +output_config.format+
       # - +reasoning+ — +budget_tokens+, +display+, +effort+, and +type+ are forwarded;
-      #   +temperature+ must be unset and +top_p+ must be >= 0.95 when reasoning is enabled
+      #   +temperature+ must be unset, +top_p+ must be >= 0.95, and
+      #   +max_output_tokens+ must be greater than +budget_tokens+ when reasoning
+      #   is enabled
       #
       # Input content restrictions:
+      # - System and developer messages are hoisted out of conversational order
+      #   into the top-level +system+ parameter, with +instructions+ merged last
+      #   (instructions apply to the current request, matching Open Responses
+      #   semantics)
+      # - Only text content (+InputText+/+OutputText+/+Text+) survives in system
+      #   and developer messages; other content is silently omitted
       # - +InputVideo+ content is not supported and is omitted
       # - +RefusalContent+ is dropped silently (a parsed refusal can stay in
       #   session history without breaking subsequent request_payload calls)
@@ -95,7 +107,11 @@ module PromptBuilder
             raise UnsupportedFormatError, "Messages format requires session.model" unless session.model
 
             h["model"] = session.model
-            h["max_tokens"] = session.max_output_tokens if session.max_output_tokens
+            unless session.max_output_tokens
+              raise UnsupportedFormatError,
+                "Messages format requires session.max_output_tokens to populate the required max_tokens field"
+            end
+            h["max_tokens"] = session.max_output_tokens
             h["temperature"] = session.temperature if session.temperature
             h["top_p"] = session.top_p if session.top_p
             effective_metadata = build_effective_metadata(session)
@@ -105,7 +121,8 @@ module PromptBuilder
             h["stream"] = session.stream unless session.stream.nil?
 
             # Session extra: recognized keys for Messages API
-            apply_session_extra!(h, session.extra) if session.extra
+            extra = session.extra
+            apply_session_extra!(h, extra) unless extra.empty?
 
             output_config = build_output_config(session)
             h["output_config"] = output_config unless output_config.empty?
@@ -249,6 +266,12 @@ module PromptBuilder
           def validate_thinking_compatibility!(session, thinking)
             return unless thinking
 
+            budget = thinking["budget_tokens"]
+            if budget && session.max_output_tokens && session.max_output_tokens <= budget
+              raise UnsupportedFormatError,
+                "Messages format requires max_output_tokens (max_tokens) to be greater than reasoning.budget_tokens"
+            end
+
             if session.temperature
               raise UnsupportedFormatError,
                 "Messages format does not support temperature when thinking is enabled"
@@ -263,16 +286,12 @@ module PromptBuilder
           def build_system(session)
             parts = []
 
-            if session.instructions
-              parts << {"type" => "text", "text" => session.instructions}
-            end
-
             session.items.each do |item|
               next unless item.is_a?(Items::Message)
               next unless item.role == "system" || item.role == "developer"
 
               item.content.each do |content|
-                if content.is_a?(Content::InputText)
+                if content.is_a?(Content::InputText) || content.is_a?(Content::OutputText) || content.is_a?(Content::Text)
                   part = {"type" => "text", "text" => content.text}
                   if content.extra && content.extra["cache_control"]
                     part["cache_control"] = content.extra["cache_control"]
@@ -282,6 +301,13 @@ module PromptBuilder
               end
             end
 
+            # Instructions come last: in the Open Responses API they apply to
+            # the current request, so they must follow any system messages
+            # accumulated in the conversation history.
+            if session.instructions
+              parts << {"type" => "text", "text" => session.instructions}
+            end
+
             parts
           end
 
@@ -347,7 +373,7 @@ module PromptBuilder
 
           def serialize_content_block(content, role:)
             case content
-            when Content::InputText
+            when Content::InputText, Content::Text
               {"type" => "text", "text" => content.text}
             when Content::OutputText
               text = {"type" => "text", "text" => content.text}
@@ -476,7 +502,7 @@ module PromptBuilder
           # Document blocks are rejected by the API.
           def serialize_tool_result_content(content)
             case content
-            when Content::InputText, Content::OutputText
+            when Content::InputText, Content::OutputText, Content::Text
               {"type" => "text", "text" => content.text}
             when Content::InputImage
               serialize_content(content, role: "user")

data/lib/prompt_builder/serializers/messages/response.rb

@@ -10,6 +10,15 @@ module PromptBuilder
         class << self
           private
 
+          # Anthropic errors arrive as
+          # {"type" => "error", "error" => {"type" => ..., "message" => ...}}.
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil unless error.is_a?(Hash) && !hash.key?("content")
+
+            [error["type"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "content")
             require_response_key!(hash, "stop_reason")

data/lib/prompt_builder/serializers/open_responses/request.rb

@@ -4,6 +4,9 @@ module PromptBuilder
   module Serializers
     class OpenResponses < Base
       # Request serializer for the OpenAI Open Responses API format.
+      #
+      # Required session fields (an UnsupportedFormatError is raised when missing):
+      # - +model+
       class Request < Base
         # Content extra keys that are part of the Open Responses API schema and
         # must survive extra-stripping (the canonical content classes have no
@@ -20,9 +23,12 @@ module PromptBuilder
           # @param session [Session] the session to export
           # @return [Hash] the serialized request payload
           def request_payload(session)
+            raise UnsupportedFormatError, "Open Responses format requires session.model" unless session.model
+
             payload = session.to_h
             items = apply_server_state!(payload, session)
             payload.delete("extra")
+            payload.delete("response_boundary_index")
             strip_extra(payload, items, session.tool_definitions)
             normalize_content_urls!(payload)
             strip_non_replayable_reasoning!(payload)

data/lib/prompt_builder/serializers/open_responses/response.rb

@@ -8,6 +8,16 @@ module PromptBuilder
         class << self
           private
 
+          # Open Responses request errors arrive as a bare {"error" => {...}}
+          # envelope. A failed response object also carries an "error" field,
+          # but it has a "status" and parses into a failed Response instead.
+          def error_response_message(hash)
+            error = hash["error"]
+            return nil unless error.is_a?(Hash) && !hash.key?("status")
+
+            [error["code"] || error["type"], error["message"]].compact.join(": ")
+          end
+
           def deserialize_response(hash)
             require_response_key!(hash, "status")
             require_response_key!(hash, "object")