prompt_builder 0.1.0

data/lib/prompt_builder/items/function_call.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+
+module PromptBuilder
+  module Items
+    # Represents a function call item in a conversation. This is output
+    # by the model when it wants to invoke a tool.
+    class FunctionCall < Base
+      # @return [String] the function name
+      attr_reader :name
+
+      # @return [String] the unique call identifier
+      attr_reader :call_id
+
+      # @return [String] the JSON-encoded arguments string (always a Hash-shaped JSON object)
+      attr_reader :arguments
+
+      # @return [String, nil] the item identifier
+      attr_reader :id
+
+      # @return [String, nil] the call status
+      attr_reader :status
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new FunctionCall item.
+      #
+      # @param name [String] the function name
+      # @param call_id [String] the unique call identifier
+      # @param arguments [String, Hash, nil] the function arguments; a String is
+      #   stored as-is (must be valid JSON), a Hash is JSON-encoded, and nil
+      #   defaults to an empty JSON object (+"{}"+ )
+      # @param id [String, nil] the item identifier
+      # @param status [String, nil] the call status
+      # @param extra [Hash] provider-specific extra keyword arguments
+      # @raise [ArgumentError] if arguments is not a String, Hash, or nil
+      def initialize(name:, call_id:, arguments:, id: nil, status: nil, **extra)
+        @name = name&.to_s
+        @call_id = call_id&.to_s
+        @arguments = case arguments
+        when nil then "{}"
+        when String then arguments
+        when Hash then JSON.generate(arguments)
+        else raise ArgumentError, "FunctionCall arguments must be a String, Hash, or nil; got #{arguments.class}"
+        end
+        @id = id&.to_s
+        @status = status&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a FunctionCall from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [FunctionCall]
+        def from_h(hash)
+          new(
+            name: hash["name"],
+            call_id: hash["call_id"],
+            arguments: hash["arguments"],
+            id: hash["id"],
+            status: hash["status"],
+            **hash.except("type", "id", "name", "call_id", "arguments", "status").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Parse the JSON arguments string into a Hash.
+      #
+      # @raise [PromptBuilder::InvalidItemError] if the arguments string is not valid JSON
+      # @return [Hash] the parsed arguments
+      def parsed_arguments
+        JSON.parse(@arguments)
+      rescue JSON::ParserError => e
+        raise PromptBuilder::InvalidItemError, "Invalid JSON in function call arguments for '#{@name}': #{e.message}"
+      end
+
+      # Serialize to a Hash with string keys. Nil values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {
+          "type" => "function_call",
+          "name" => @name,
+          "call_id" => @call_id,
+          "arguments" => @arguments
+        }
+        h["id"] = @id if @id
+        h["status"] = @status if @status
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/items/function_call_output.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    # Represents the output of a function call. This is added to the
+    # conversation after a tool has been invoked.
+    class FunctionCallOutput < Base
+      # @return [String, nil] the function call output identifier
+      attr_reader :id
+
+      # @return [String] the call identifier this output corresponds to
+      attr_reader :call_id
+
+      # @return [String, nil] the function call output status
+      attr_reader :status
+
+      # @return [String, Array<Content::Base>, nil] the output from the function; either a plain
+      #   string, an array of content objects, or nil (serialized as +""+)
+      attr_reader :output
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new FunctionCallOutput item.
+      #
+      # @param id [String, nil] the function call output identifier
+      # @param call_id [String] the call identifier
+      # @param status [String, nil] the function call output status
+      # @param output [String, Array<Content::Base, Hash>, nil] the function output;
+      #   Hash elements in an array are normalized into +Content::Base+ objects
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(call_id:, output:, id: nil, status: nil, **extra)
+        @id = id&.to_s
+        @call_id = call_id&.to_s
+        @status = status&.to_s
+        @output = normalize_output(output)
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a FunctionCallOutput from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [FunctionCallOutput]
+        def from_h(hash)
+          output = hash["output"]
+          output = output.map { |c| Content::Base.from_h(c) } if output.is_a?(Array)
+          new(
+            id: hash["id"],
+            call_id: hash["call_id"],
+            status: hash["status"],
+            output: output,
+            **hash.except("type", "id", "call_id", "status", "output").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Serialize to a Hash with string keys. A nil output is emitted as an
+      # empty string so the on-the-wire shape matches the Open Responses API.
+      #
+      # @return [Hash]
+      def to_h
+        hash = {
+          "type" => "function_call_output",
+          "call_id" => @call_id,
+          "output" => serialize_output
+        }
+        hash["id"] = @id if @id
+        hash["status"] = @status if @status
+        hash = PromptBuilder.jsonify(@extra).merge(hash) unless @extra.empty?
+        hash
+      end
+
+      private
+
+      def serialize_output
+        case @output
+        when nil then ""
+        when Array then @output.map(&:to_h)
+        else @output
+        end
+      end
+
+      def normalize_output(output)
+        case output
+        when String, NilClass
+          output
+        when Array
+          output.map do |c|
+            case c
+            when Hash
+              hash = c.transform_keys(&:to_s)
+              unless hash["type"]
+                raise InvalidItemError,
+                  "Output content hash is missing required \"type\" key: #{hash.inspect}"
+              end
+              Content::Base.from_h(hash)
+            when Content::Base
+              c
+            else
+              raise InvalidItemError, "Unsupported output element: #{c.class}"
+            end
+          end
+        else
+          raise InvalidItemError, "Unsupported output type: #{output.class}"
+        end
+      end
+    end
+  end
+end

data/lib/prompt_builder/items/item_reference.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    # Represents a reference to an existing conversation item by ID.
+    class ItemReference < Base
+      # @return [String] the referenced item identifier
+      attr_reader :id
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new ItemReference item.
+      #
+      # @param id [String] the referenced item identifier
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(id:, **extra)
+        @id = id&.to_s
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize an ItemReference from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [ItemReference]
+        def from_h(hash)
+          new(id: hash["id"], **hash.except("type", "id").transform_keys(&:to_sym))
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "item_reference", "id" => @id}
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/items/message.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    # Represents a message item in a conversation. Messages have a role
+    # and an array of content objects.
+    class Message < Base
+      # @return [String, nil] the message identifier
+      attr_reader :id
+
+      # @return [String] the message role (e.g. "user", "assistant", "system", "developer")
+      attr_reader :role
+
+      # @return [String, nil] the message status
+      attr_reader :status
+
+      # @return [String, nil] the message phase
+      attr_reader :phase
+
+      # @return [Array<Content::Base>] the content objects
+      attr_reader :content
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new Message item.
+      #
+      # @param id [String, nil] the message identifier
+      # @param role [String] the message role
+      # @param status [String, nil] the message status
+      # @param phase [String, nil] the message phase
+      # @param content [Array<Content::Base>] the content objects
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(role:, content:, id: nil, status: nil, phase: nil, **extra)
+        @id = id&.to_s
+        @role = role&.to_s
+        @status = status&.to_s
+        @phase = phase&.to_s
+        @content = normalize_content(content)
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a Message from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Message]
+        def from_h(hash)
+          content = (hash["content"] || []).map { |c| Content::Base.from_h(c) }
+          new(
+            id: hash["id"],
+            role: hash["role"],
+            status: hash["status"],
+            phase: hash["phase"],
+            content: content,
+            **hash.except("type", "id", "role", "status", "phase", "content").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Serialize to a Hash with string keys.
+      #
+      # @return [Hash]
+      def to_h
+        hash = {
+          "type" => "message",
+          "role" => @role,
+          "content" => @content.map(&:to_h)
+        }
+        hash["id"] = @id if @id
+        hash["status"] = @status if @status
+        hash["phase"] = @phase if @phase
+        hash = PromptBuilder.jsonify(@extra).merge(hash) unless @extra.empty?
+        hash
+      end
+
+      private
+
+      def normalize_content(content)
+        case content
+        when String
+          [Content::InputText.new(text: content)]
+        when Content::Base
+          [content]
+        when Hash
+          [normalize_hash_content(content)]
+        when Array
+          content.map do |c|
+            case c
+            when Hash
+              normalize_hash_content(c)
+            when Content::Base
+              c
+            else
+              raise InvalidItemError, "Unsupported content element: #{c.class}"
+            end
+          end
+        else
+          raise InvalidItemError, "Unsupported content type: #{content.class}"
+        end
+      end
+
+      def normalize_hash_content(hash)
+        hash = hash.transform_keys(&:to_s)
+        unless hash["type"]
+          raise InvalidItemError,
+            "Content hash is missing required \"type\" key: #{hash.inspect}"
+        end
+        Content::Base.from_h(hash)
+      end
+    end
+  end
+end

data/lib/prompt_builder/items/reasoning.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    # Represents a reasoning item in a conversation. This captures the
+    # model's chain-of-thought reasoning output.
+    class Reasoning < Base
+      # @return [String, nil] the reasoning identifier
+      attr_reader :id
+
+      # @return [String, nil] the reasoning status
+      attr_reader :status
+
+      # @return [String, nil] the encrypted reasoning content
+      attr_reader :encrypted_content
+
+      # @return [Array<Hash>] summary blocks
+      attr_reader :summary
+
+      # @return [Array<Hash>] reasoning content blocks
+      attr_reader :content
+
+      # @return [Hash, nil] provider-specific extra data
+      attr_reader :extra
+
+      # Create a new Reasoning item.
+      #
+      # @param id [String, nil] the reasoning identifier
+      # @param status [String, nil] the reasoning status
+      # @param encrypted_content [String, nil] the encrypted reasoning content
+      # @param summary [Array<Hash>] summary blocks
+      # @param content [Array<Hash>] reasoning content blocks
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(id: nil, status: nil, encrypted_content: nil, summary: [], content: [], **extra)
+        @id = id&.to_s
+        @status = status&.to_s
+        @encrypted_content = encrypted_content&.to_s
+        @summary = PromptBuilder.jsonify(summary)
+        @content = PromptBuilder.jsonify(content)
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a Reasoning item from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Reasoning]
+        def from_h(hash)
+          new(
+            id: hash["id"],
+            status: hash["status"],
+            encrypted_content: hash["encrypted_content"],
+            summary: hash["summary"] || [],
+            content: hash["content"] || [],
+            **hash.except("type", "id", "status", "encrypted_content", "summary", "content").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Serialize to a Hash with string keys. Nil and empty values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "reasoning"}
+        h["id"] = @id if @id
+        h["status"] = @status if @status
+        h["encrypted_content"] = @encrypted_content if @encrypted_content
+        h["summary"] = @summary unless @summary.empty?
+        h["content"] = @content unless @content.empty?
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/items.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Items
+    autoload :Base, File.expand_path("items/base", __dir__)
+    autoload :Compaction, File.expand_path("items/compaction", __dir__)
+    autoload :FunctionCall, File.expand_path("items/function_call", __dir__)
+    autoload :FunctionCallOutput, File.expand_path("items/function_call_output", __dir__)
+    autoload :ItemReference, File.expand_path("items/item_reference", __dir__)
+    autoload :Message, File.expand_path("items/message", __dir__)
+    autoload :Reasoning, File.expand_path("items/reasoning", __dir__)
+  end
+end