prompt_builder 0.1.0

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PromptBuilder
+  module Serializers
+    class Messages < Base
+      # Response parser for the Anthropic Messages API format.
+      class Response < Base
+        class << self
+          private
+
+          def deserialize_response(hash)
+            usage_hash = hash["usage"]
+            usage = build_usage(usage_hash) if usage_hash
+
+            PromptBuilder::Response.new(
+              id: hash["id"],
+              object: hash["type"],
+              model: hash["model"],
+              output: build_output_items(hash["content"] || []),
+              status: map_stop_reason(hash["stop_reason"]),
+              incomplete_details: build_incomplete_details(hash),
+              usage: usage
+            )
+          end
+
+          def build_usage(usage_hash)
+            input_tokens_details = usage_hash["input_tokens_details"] || {}
+            cache_creation = usage_hash["cache_creation_input_tokens"]
+            cache_read = usage_hash["cache_read_input_tokens"]
+            cache_creation_breakdown = usage_hash["cache_creation"]
+            service_tier = usage_hash["service_tier"]
+            inference_geo = usage_hash["inference_geo"]
+            server_tool_use = usage_hash["server_tool_use"]
+
+            input_tokens_details = input_tokens_details.merge("cache_creation_input_tokens" => cache_creation) if cache_creation
+            input_tokens_details = input_tokens_details.merge("cached_tokens" => cache_read) if cache_read
+            input_tokens_details = input_tokens_details.merge("cache_creation" => cache_creation_breakdown) if cache_creation_breakdown
+            input_tokens_details = input_tokens_details.merge("service_tier" => service_tier) if service_tier
+            input_tokens_details = input_tokens_details.merge("inference_geo" => inference_geo) if inference_geo
+            input_tokens_details = input_tokens_details.merge("server_tool_use" => server_tool_use) if server_tool_use
+
+            # Anthropic reports input_tokens excluding cached/cache-creation tokens,
+            # which are billed and counted separately. Include them in the total.
+            total = usage_hash["input_tokens"].to_i + usage_hash["output_tokens"].to_i +
+              cache_creation.to_i + cache_read.to_i
+
+            Usage.new(
+              input_tokens: usage_hash["input_tokens"],
+              output_tokens: usage_hash["output_tokens"],
+              total_tokens: total,
+              input_tokens_details: input_tokens_details.empty? ? nil : input_tokens_details,
+              output_tokens_details: usage_hash["output_tokens_details"]
+            )
+          end
+
+          def build_incomplete_details(hash)
+            details = {}
+            details["stop_sequence"] = hash["stop_sequence"] if hash["stop_sequence"]
+            details["stop_details"] = hash["stop_details"] if hash["stop_details"]
+            details["container"] = hash["container"] if hash["container"]
+            details.empty? ? nil : details
+          end
+
+          # Anthropic stop_reason values:
+          # - end_turn, tool_use, stop_sequence, pause_turn → completed
+          # - max_tokens → incomplete (truncated mid-output)
+          # - refusal → failed (model declined to respond)
+          # - anything else → pass through unchanged so callers can inspect it
+          def map_stop_reason(reason)
+            case reason
+            when "end_turn", "tool_use", "stop_sequence", "pause_turn"
+              "completed"
+            when "max_tokens"
+              "incomplete"
+            when "refusal"
+              "failed"
+            else
+              reason
+            end
+          end
+
+          def build_output_items(content_blocks)
+            output = []
+            text_contents = []
+            reasoning_contents = []
+
+            content_blocks.each do |block|
+              type = block["type"]
+              case type
+              when "text"
+                flush_reasoning_contents!(output, reasoning_contents)
+                text_contents << Content::OutputText.new(
+                  text: block["text"],
+                  annotations: block["citations"] || []
+                )
+              when "tool_use"
+                flush_text_contents!(output, text_contents)
+                flush_reasoning_contents!(output, reasoning_contents)
+                output << Items::FunctionCall.new(
+                  name: block["name"],
+                  call_id: block["id"],
+                  arguments: JSON.generate(block["input"] || {})
+                )
+              when "thinking", "redacted_thinking"
+                flush_text_contents!(output, text_contents)
+                reasoning_contents << deserialize_reasoning_block(block)
+              else
+                # Unsupported content block types (e.g. built-in tool results)
+                # are silently skipped rather than raising.
+                next
+              end
+            end
+
+            flush_text_contents!(output, text_contents)
+            flush_reasoning_contents!(output, reasoning_contents)
+            output
+          end
+
+          def deserialize_reasoning_block(block)
+            case block["type"]
+            when "thinking"
+              {
+                "type" => "thinking",
+                "thinking" => block.fetch("thinking", ""),
+                "signature" => block["signature"]
+              }
+            when "redacted_thinking"
+              {
+                "type" => "redacted_thinking",
+                "data" => block["data"]
+              }
+            end
+          end
+
+          def flush_text_contents!(output, text_contents)
+            return if text_contents.empty?
+
+            output << Items::Message.new(
+              role: "assistant",
+              content: text_contents.dup
+            )
+            text_contents.clear
+          end
+
+          def flush_reasoning_contents!(output, reasoning_contents)
+            return if reasoning_contents.empty?
+
+            output << Items::Reasoning.new(content: reasoning_contents.dup)
+            reasoning_contents.clear
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers/messages.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    # Serializer for the Anthropic Messages API format.
+    # Delegates request and response handling to dedicated nested classes.
+    class Messages < Base
+      autoload :Request, File.expand_path("messages/request", __dir__)
+      autoload :Response, File.expand_path("messages/response", __dir__)
+
+      class << self
+        # Export a session to Messages request payload.
+        #
+        # @param session [Session] the session to export
+        # @return [Hash] the serialized request payload
+        def request_payload(session)
+          Request.request_payload(session)
+        end
+
+        # Parse a Messages response into an PromptBuilder::Response.
+        #
+        # @param hash [Hash] the response hash in Messages format
+        # @return [PromptBuilder::Response] the parsed response
+        def parse_response(hash)
+          Response.parse_response(hash)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    class OpenResponses < Base
+      # Request serializer for the OpenAI Open Responses API format.
+      class Request < Base
+        class << self
+          # Export a session to Open Responses API request payload.
+          #
+          # @param session [Session] the session to export
+          # @return [Hash] the serialized request payload
+          def request_payload(session)
+            payload = session.to_h
+            apply_server_state!(payload, session)
+            payload.delete("extra")
+            strip_extra(payload)
+            normalize_content_urls!(payload)
+            strip_non_replayable_reasoning!(payload)
+            strip_output_only_fields!(payload)
+            normalize_and_validate_input_images!(payload)
+            normalize_text_format!(payload)
+            payload
+          end
+
+          private
+
+          # When the session is in server-state mode, replace the full input
+          # array with only items added after the last response boundary and
+          # include previous_response_id for the API to resolve history.
+          def apply_server_state!(payload, session)
+            return if session.local_state?
+
+            payload.delete("input")
+            new_items = session.items[session.response_boundary_index..]
+            payload["input"] = new_items.map(&:to_h) if new_items && !new_items.empty?
+          end
+
+          # Walk the payload and remove any "extra" keys from items, content
+          # blocks, and tool definitions since they are not part of the Open
+          # Responses API schema.
+          def strip_extra(payload)
+            input = payload["input"]
+            if input.is_a?(Array)
+              input.each do |item|
+                next unless item.is_a?(Hash)
+
+                item.delete("extra")
+
+                if item["type"] == "function_call_output" && item["output"].is_a?(Array)
+                  strip_extra_from_blocks!(item["output"])
+                else
+                  content = item["content"]
+                  strip_extra_from_blocks!(content) if content.is_a?(Array)
+                end
+              end
+            end
+
+            tools = payload["tools"]
+            strip_extra_from_blocks!(tools) if tools.is_a?(Array)
+          end
+
+          # Convert canonical "url" keys back to Open Responses API keys:
+          # input_image "url" -> "image_url"
+          # input_file "url" -> "file_url"/"file_data"
+          # input_video "url" -> "video_url"
+          def normalize_content_urls!(payload)
+            input = payload["input"]
+            return unless input.is_a?(Array)
+
+            input.each do |item|
+              next unless item.is_a?(Hash)
+
+              if item["type"] == "function_call_output" && item["output"].is_a?(Array)
+                normalize_url_keys_in_blocks!(item["output"])
+                next
+              end
+
+              content = item["content"]
+              normalize_url_keys_in_blocks!(content) if content.is_a?(Array)
+            end
+          end
+
+          def normalize_url_keys_in_blocks!(blocks)
+            blocks.each do |block|
+              next unless block.is_a?(Hash)
+
+              case block["type"]
+              when "input_image"
+                if block.key?("url")
+                  block["image_url"] = block.delete("url")
+                end
+              when "input_file"
+                if block.key?("url")
+                  url = block.delete("url")
+                  if PromptBuilder.parse_data_url(url)
+                    block["file_data"] = url
+                  else
+                    block["file_url"] = url
+                  end
+                end
+              when "input_video"
+                if block.key?("url")
+                  block["video_url"] = block.delete("url")
+                end
+              end
+            end
+          end
+
+          def normalize_and_validate_input_images!(payload)
+            input = payload["input"]
+            return unless input.is_a?(Array)
+
+            input.each_with_index do |item, input_index|
+              next unless item.is_a?(Hash)
+
+              if item["type"] == "function_call_output" && item["output"].is_a?(Array)
+                normalize_and_validate_image_blocks!(item["output"], "input.#{input_index}.output")
+                next
+              end
+
+              content = item["content"]
+              next unless content.is_a?(Array)
+
+              normalize_and_validate_image_blocks!(content, "input.#{input_index}.content")
+            end
+          end
+
+          def normalize_and_validate_image_blocks!(blocks, path_prefix)
+            blocks.each_with_index do |block, block_index|
+              next unless block.is_a?(Hash)
+              next unless block["type"] == "input_image"
+
+              image_url = normalize_optional_string(block["image_url"])
+              file_id = normalize_optional_string(block["file_id"])
+
+              image_url ? block["image_url"] = image_url : block.delete("image_url")
+              file_id ? block["file_id"] = file_id : block.delete("file_id")
+
+              if image_url && file_id
+                raise InvalidItemError,
+                  "#{path_prefix}.#{block_index} includes both image_url and file_id; provide exactly one"
+              end
+
+              next if image_url || file_id
+
+              raise InvalidItemError,
+                "#{path_prefix}.#{block_index} requires exactly one of image_url or file_id"
+            end
+          end
+
+          # Remove reasoning items that cannot be sent back in input.
+          # The Responses API only accepts reasoning items with
+          # encrypted_content; plain reasoning_text content blocks are
+          # output-only and cause an invalid_union error.
+          # For preserved reasoning items, strip the content key since
+          # the input schema only accepts null for that field.
+          def strip_non_replayable_reasoning!(payload)
+            input = payload["input"]
+            return unless input.is_a?(Array)
+
+            input.reject! do |item|
+              item.is_a?(Hash) &&
+                item["type"] == "reasoning" &&
+                !item["encrypted_content"]
+            end
+
+            input.each do |item|
+              next unless item.is_a?(Hash) && item["type"] == "reasoning"
+
+              item.delete("content")
+            end
+          end
+
+          # Remove output-only fields from content blocks that are not
+          # accepted by the Responses API input schema.
+          # OutputTextContentParam only accepts type, text, and annotations;
+          # logprobs is output-only metadata.
+          def strip_output_only_fields!(payload)
+            input = payload["input"]
+            return unless input.is_a?(Array)
+
+            input.each do |item|
+              next unless item.is_a?(Hash)
+
+              content = item["content"]
+              next unless content.is_a?(Array)
+
+              content.each do |block|
+                next unless block.is_a?(Hash) && block["type"] == "output_text"
+
+                block.delete("logprobs")
+              end
+            end
+          end
+
+          def normalize_optional_string(value)
+            return value unless value.is_a?(String)
+
+            normalized = value.strip
+            normalized.empty? ? nil : normalized
+          end
+
+          def strip_extra_from_blocks!(blocks)
+            blocks.each do |block|
+              next unless block.is_a?(Hash)
+
+              block.delete("extra")
+            end
+          end
+
+          # Normalize text.format for the Responses API. If the format uses
+          # the Chat Completions nested json_schema sub-object, flatten it
+          # so name/schema/strict/description sit directly under format.
+          def normalize_text_format!(payload)
+            format = payload.dig("text", "format")
+            return unless format.is_a?(Hash) && format["type"] == "json_schema"
+
+            json_schema = format["json_schema"]
+            return unless json_schema.is_a?(Hash)
+
+            format.delete("json_schema")
+            json_schema.each { |key, value| format[key] = value }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    class OpenResponses < Base
+      # Response parser for the OpenAI Open Responses API format.
+      class Response < Base
+        class << self
+          private
+
+          def deserialize_response(hash)
+            PromptBuilder::Response.from_h(hash)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers/open_responses.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    # Serializer for OpenAI Open Responses API format.
+    # Delegates request and response handling to dedicated nested classes.
+    class OpenResponses < Base
+      autoload :Request, File.expand_path("open_responses/request", __dir__)
+      autoload :Response, File.expand_path("open_responses/response", __dir__)
+
+      class << self
+        # Export a session to Open Responses API request payload.
+        #
+        # @param session [Session] the session to export
+        # @return [Hash] the serialized request payload
+        def request_payload(session)
+          Request.request_payload(session)
+        end
+
+        # Parse an Open Responses response into an PromptBuilder::Response.
+        #
+        # @param hash [Hash] the response hash in Open Responses format
+        # @return [PromptBuilder::Response] the parsed response
+        def parse_response(hash)
+          Response.parse_response(hash)
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/serializers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Serializers
+    autoload :Base, File.expand_path("serializers/base", __dir__)
+    autoload :ChatCompletion, File.expand_path("serializers/chat_completion", __dir__)
+    autoload :Converse, File.expand_path("serializers/converse", __dir__)
+    autoload :Gemini, File.expand_path("serializers/gemini", __dir__)
+    autoload :Messages, File.expand_path("serializers/messages", __dir__)
+    autoload :OpenResponses, File.expand_path("serializers/open_responses", __dir__)
+
+    # Mapping of shorthand symbols to serializer classes.
+    ALIASES = {
+      chat_completion: ChatCompletion,
+      converse: Converse,
+      gemini: Gemini,
+      messages: Messages,
+      open_responses: OpenResponses
+    }.freeze
+
+    # Resolve a serializer class from a symbol or class reference.
+    #
+    # @param serializer [Class, Symbol] a serializer class or a symbol shorthand
+    #   (+:open_responses+, +:chat_completion+, +:messages+, +:gemini+, +:converse+)
+    # @return [Class] the resolved serializer class
+    # @raise [ArgumentError] if a symbol is given that does not map to a known serializer
+    def self.resolve(serializer)
+      return serializer unless serializer.is_a?(Symbol)
+
+      ALIASES.fetch(serializer) do
+        raise ArgumentError, "Unknown serializer: #{serializer.inspect}. Valid options: #{ALIASES.keys.map(&:inspect).join(", ")}"
+      end
+    end
+  end
+end