prompt_builder 0.1.0

data/lib/prompt_builder/session.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  # The main DSL entry point for building Open Responses API request payloads.
+  # Manages conversation items, tool registration, and serialization to
+  # multiple API formats.
+  class Session
+    # Boolean fields that may legitimately be false; serialized with a nil? check.
+    BOOLEAN_FIELDS = %i[parallel_tool_calls stream background store].freeze
+    private_constant :BOOLEAN_FIELDS
+
+    # String-typed fields coerced with .to_s on assignment.
+    STRING_FIELDS = %i[
+      model instructions previous_response_id truncation safety_identifier prompt_cache_key prompt_cache_retention service_tier
+    ].freeze
+    private_constant :STRING_FIELDS
+
+    # Float-typed fields coerced with .to_f on assignment.
+    FLOAT_FIELDS = %i[temperature top_p presence_penalty frequency_penalty].freeze
+    private_constant :FLOAT_FIELDS
+
+    # Integer-typed fields coerced with .to_i on assignment.
+    INTEGER_FIELDS = %i[max_output_tokens max_tool_calls top_logprobs].freeze
+    private_constant :INTEGER_FIELDS
+
+    # Complex fields serialized to JSON-compatible values via PromptBuilder.jsonify.
+    JSONIFY_FIELDS = %i[include tool_choice metadata text stream_options reasoning].freeze
+    private_constant :JSONIFY_FIELDS
+
+    # @!attribute [rw] model
+    #   @return [String, nil] the model identifier
+    # @!attribute [rw] instructions
+    #   @return [String, nil] the system instructions
+    # @!attribute [rw] previous_response_id
+    #   @return [String, nil] the previous response identifier for server-side state
+    # @!attribute [rw] truncation
+    #   @return [String, nil] the truncation strategy
+    # @!attribute [rw] safety_identifier
+    #   @return [String, nil] the safety identifier
+    # @!attribute [rw] prompt_cache_key
+    #   @return [String, nil] the prompt cache key
+    # @!attribute [rw] prompt_cache_retention
+    #   @return [String, nil] the prompt cache retention policy
+    # @!attribute [rw] service_tier
+    #   @return [String, nil] the service tier
+    STRING_FIELDS.each do |f|
+      attr_reader f
+      define_method(:"#{f}=") { |v| instance_variable_set(:"@#{f}", v.nil? ? nil : v.to_s) }
+    end
+
+    # @!attribute [rw] temperature
+    #   @return [Float, nil] the temperature
+    # @!attribute [rw] top_p
+    #   @return [Float, nil] the top_p sampling parameter
+    # @!attribute [rw] presence_penalty
+    #   @return [Float, nil] the presence penalty
+    # @!attribute [rw] frequency_penalty
+    #   @return [Float, nil] the frequency penalty
+    FLOAT_FIELDS.each do |f|
+      attr_reader f
+      define_method(:"#{f}=") { |v| instance_variable_set(:"@#{f}", v.nil? ? nil : v.to_f) }
+    end
+
+    # @!attribute [rw] max_output_tokens
+    #   @return [Integer, nil] the maximum output tokens
+    # @!attribute [rw] max_tool_calls
+    #   @return [Integer, nil] the maximum number of tool calls
+    # @!attribute [rw] top_logprobs
+    #   @return [Integer, nil] the number of top log probabilities to return
+    INTEGER_FIELDS.each do |f|
+      attr_reader f
+      define_method(:"#{f}=") { |v| instance_variable_set(:"@#{f}", v.nil? ? nil : v.to_i) }
+    end
+
+    # @!attribute [rw] parallel_tool_calls
+    #   @return [Boolean, nil] whether parallel tool calls are enabled
+    # @!attribute [rw] stream
+    #   @return [Boolean, nil] whether to stream the response
+    # @!attribute [rw] background
+    #   @return [Boolean, nil] whether this is a background request
+    # @!attribute [rw] store
+    #   @return [Boolean, nil] whether to store the response
+    BOOLEAN_FIELDS.each do |f|
+      attr_reader f
+      define_method(:"#{f}=") { |v| instance_variable_set(:"@#{f}", v) }
+      alias_method :"#{f}?", f
+    end
+
+    # @!attribute [rw] include
+    #   @return [Array, nil] fields to include in the response
+    # @!attribute [rw] tool_choice
+    #   @return [String, Hash, nil] the tool choice configuration
+    # @!attribute [rw] metadata
+    #   @return [Hash, nil] arbitrary metadata
+    # @!attribute [rw] text
+    #   @return [Hash, nil] text output configuration
+    # @!attribute [rw] stream_options
+    #   @return [Hash, nil] stream configuration options
+    # @!attribute [rw] reasoning
+    #   @return [Hash, nil] the reasoning configuration
+    JSONIFY_FIELDS.each do |f|
+      attr_reader f
+      define_method(:"#{f}=") { |v| instance_variable_set(:"@#{f}", v.nil? ? nil : PromptBuilder.jsonify(v)) }
+    end
+
+    # @return [Array<Items::Base>] all conversation items
+    attr_reader :items
+
+    # @return [Integer] the index in +items+ marking the boundary after the last response
+    attr_reader :response_boundary_index
+
+    # @return [Hash, nil] provider-specific extra data for serializers.
+    #   Recognized keys vary by target format. Unrecognized keys are silently
+    #   ignored by each serializer.
+    attr_reader :extra
+
+    class << self
+      # Deserialize a Session from a Hash produced by +to_h+ or parsed JSON.
+      # Reconstructs all config fields and conversation items. Tool definitions
+      # are restored without handlers; re-register handlers separately if you
+      # need to invoke the tools.
+      #
+      # @param hash [Hash] a Hash with string keys
+      # @return [Session]
+      def from_h(hash)
+        attrs = (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS)
+          .each_with_object({}) { |f, acc| acc[f] = hash[f.to_s] }
+        attrs[:extra] = hash["extra"] if hash["extra"]
+        session = new(**attrs)
+
+        Array(hash["input"]).each do |item_hash|
+          session.add_item(Items::Base.from_h(item_hash))
+        end
+
+        Array(hash["tools"]).each do |tool_hash|
+          defn = Tools::Definition.from_h(tool_hash)
+          extra = defn.extra.transform_keys(&:to_sym)
+          session.register_tool(defn.name, description: defn.description, parameters: defn.parameters, strict: defn.strict, **extra)
+        end
+
+        session
+      end
+    end
+
+    # Create a new Session with the given options.
+    # Accepts keyword arguments for all typed field groups (STRING_FIELDS,
+    # FLOAT_FIELDS, INTEGER_FIELDS, BOOLEAN_FIELDS, JSONIFY_FIELDS); all default
+    # to +nil+. The +input+ shorthand auto-creates a user message if provided.
+    #
+    # @param attributes [Hash] keyword options; see attribute declarations above
+    # @option attributes [String, nil] :input optional string shorthand; a user
+    #   message is automatically added with this text
+    # @option attributes [Hash, nil] :extra provider-specific extra data for
+    #   serializers; recognized keys vary by target format
+    def initialize(**attributes)
+      (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS).each do |f|
+        send(:"#{f}=", attributes[f])
+      end
+      @extra = PromptBuilder.jsonify(attributes[:extra]) if attributes[:extra]
+      @items = []
+      @tool_definitions = {}
+      @response_boundary_index = 0
+      user(attributes[:input]) if attributes[:input]
+    end
+
+    # Add a user message to the conversation.
+    #
+    # @param content [String, Content::Base, Hash, Array<Content::Base>, Array<Hash>] the message content
+    # @return [Items::Message] the added message
+    # @example
+    #  session.user("Hello, how are you?")
+    #  session.user(Content::InputText.new(text: "Hello, how are you?"))
+    #  session.user(type: "input_text", text: "Hello, how are you?")
+    #  session.user([
+    #    Content::InputText.new(text: "What is in this image?"),
+    #    Content::InputImage.new(url: "http://example.com/image.png")
+    #  ])
+    #  session.user([
+    #    {type: "input_text", text: "What is in this image?"},
+    #    {type: "input_image", url: "http://example.com/image.png"}
+    #  ])
+    def user(content)
+      add_item(Items::Message.new(role: "user", content: content))
+    end
+
+    # Add an assistant message to the conversation.
+    #
+    # @param content [String, Content::Base, Hash, Array<Content::Base>, Array<Hash>] the message content
+    # @return [Items::Message] the added message
+    def assistant(content)
+      add_item(Items::Message.new(role: "assistant", content: content))
+    end
+
+    # Add a system message to the conversation.
+    #
+    # @param content [String, Content::Base, Hash, Array<Content::Base>, Array<Hash>] the message content
+    # @return [Items::Message] the added message
+    def system(content)
+      add_item(Items::Message.new(role: "system", content: content))
+    end
+
+    # Add a developer message to the conversation.
+    #
+    # @param content [String, Content::Base, Hash, Array<Content::Base>, Array<Hash>] the message content
+    # @return [Items::Message] the added message
+    def developer(content)
+      add_item(Items::Message.new(role: "developer", content: content))
+    end
+
+    # Add a tool call output to the conversation.
+    #
+    # @param call_id [String] the tool call identifier
+    # @param result [String, Hash, Array, Content::Base, nil] the tool call result
+    # @return [Items::FunctionOutput] the added function output item
+    def add_function_call_output(call_id:, result:)
+      add_item(Items::FunctionOutput.new(call_id: call_id, result: result))
+    end
+
+    # Add a raw item to the conversation.
+    #
+    # @param item [Items::Base] the item to add
+    # @return [Items::Base] the added item
+    def add_item(item)
+      raise ArgumentError, "item must be an instance of Items::Base" unless item.is_a?(Items::Base)
+
+      @items << item
+      item
+    end
+
+    # Add a response to the conversation. Output items are always appended
+    # to +items+ so that the full history is available locally. When the
+    # session is in server state mode (previous_response_id already set),
+    # the id is also updated so +to_h+ can use it as a serialization
+    # optimization.
+    #
+    # @param response [Response] the API response
+    # @return [void]
+    def add_response(response)
+      raise ArgumentError, "response must be an instance of Response" unless response.is_a?(Response)
+
+      @items.concat(response.output)
+      # Only refresh previous_response_id when the session is already in
+      # server-state mode AND the response actually carries an id; otherwise
+      # leave the existing pointer alone (responses from formats that don't
+      # populate `id` would otherwise silently drop us back into local state).
+      self.previous_response_id = response.id if !local_state? && response.id
+      @response_boundary_index = @items.length
+    end
+
+    # Register a tool on this session.
+    #
+    # @param name [String] the tool name
+    # @param description [String, nil] the tool description
+    # @param parameters [Hash, nil] the JSON Schema for parameters
+    # @param strict [Boolean] whether strict mode is enabled
+    # @param extra [Hash] provider-specific extra keyword arguments (e.g. cache_control)
+    # @return [Tools::Definition] the registered definition
+    def register_tool(name, description: nil, parameters: nil, strict: false, **extra)
+      definition = Tools::Definition.new(
+        name: name,
+        description: description,
+        parameters: parameters,
+        strict: strict,
+        **extra
+      )
+      @tool_definitions[name] = definition
+      definition
+    end
+
+    # Register all tools from a ToolRegistry.
+    #
+    # @param registry [ToolRegistry] the registry to copy tools from
+    # @return [void]
+    def register_tools(registry)
+      raise ArgumentError, "registry must be an instance of ToolRegistry" unless registry.is_a?(ToolRegistry)
+
+      registry.definitions.each do |defn|
+        extra = defn.extra.transform_keys(&:to_sym)
+        register_tool(
+          defn.name,
+          description: defn.description,
+          parameters: defn.parameters,
+          strict: defn.strict,
+          **extra
+        )
+      end
+    end
+
+    # Return all tool definitions registered on this session.
+    #
+    # @return [Array<Tools::Definition>] all tool definitions
+    def tool_definitions
+      @tool_definitions.values
+    end
+
+    # Create a new Session with the same configuration and tools but no items.
+    #
+    # @return [Session] a new session with cloned configuration
+    def clone_config
+      session = Session.new(**config_hash)
+      @tool_definitions.each do |name, defn|
+        extra = defn.extra.transform_keys(&:to_sym)
+        session.register_tool(
+          name,
+          description: defn.description,
+          parameters: defn.parameters,
+          strict: defn.strict,
+          **extra
+        )
+      end
+      session
+    end
+
+    # Check if this session is in local state mode (no previous_response_id). This
+    # indicates that the full conversation history is stored in the session and will be
+    # sent with each request. Once a response with an id is added, the session switches
+    # to server state mode, where only new items after the last response are sent
+    # and the previous_response_id is used to reference the last response.
+    #
+    # @return [Boolean]
+    def local_state?
+      @previous_response_id.nil?
+    end
+
+    # Serialize to an Open Responses API request Hash with string keys.
+    #
+    # @return [Hash]
+    def to_h
+      h = {}
+      h["model"] = @model if @model
+      h["instructions"] = @instructions if @instructions
+
+      h["input"] = @items.map(&:to_h) unless @items.empty?
+      h["previous_response_id"] = @previous_response_id if @previous_response_id
+
+      h["tools"] = tool_definitions.map(&:to_h) unless @tool_definitions.empty?
+
+      (STRING_FIELDS - %i[model instructions previous_response_id]).each do |f|
+        val = send(f)
+        h[f.to_s] = val if val
+      end
+      FLOAT_FIELDS.each { |f|
+        val = send(f)
+        h[f.to_s] = val if val
+      }
+      INTEGER_FIELDS.each { |f|
+        val = send(f)
+        h[f.to_s] = val if val
+      }
+      BOOLEAN_FIELDS.each { |f|
+        val = send(f)
+        h[f.to_s] = val unless val.nil?
+      }
+      JSONIFY_FIELDS.each { |f|
+        val = send(f)
+        h[f.to_s] = val if val
+      }
+      h["extra"] = @extra if @extra
+
+      h
+    end
+
+    # Export this session to an alternate API format using the given serializer.
+    #
+    # @param serializer_class [Class, Symbol] a serializer class (e.g. Serializers::ChatCompletion)
+    #   or a symbol shorthand (+:open_responses+, +:chat_completion+, +:messages+,
+    #   +:gemini+, +:converse+)
+    # @return [Hash] the serialized request payload
+    # @raise [ArgumentError] if a symbol is given that does not map to a known serializer
+    def request_payload(serializer_class)
+      Serializers.resolve(serializer_class).request_payload(self)
+    end
+
+    private
+
+    def config_hash
+      h = (STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS - %i[previous_response_id])
+        .each_with_object({}) { |f, acc| acc[f] = send(f) }
+      h[:extra] = @extra if @extra
+      h
+    end
+  end
+end

data/lib/prompt_builder/tool_registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  # Registry for tool definitions and their handler callables.
+  class ToolRegistry
+    # Create a new ToolRegistry.
+    def initialize
+      @definitions = {}
+      @handlers = {}
+    end
+
+    # Register a tool with its definition and handler.
+    #
+    # @param name [String, Symbol] the tool name
+    # @param description [String, nil] the tool description
+    # @param parameters [Hash, nil] the JSON Schema for parameters
+    # @param strict [Boolean] whether strict mode is enabled
+    # @param callable [#call, nil] a callable handler (alternative to block)
+    # @param extra [Hash] provider-specific extra keyword arguments (e.g. cache_control)
+    # @yield [Hash] the parsed arguments when the tool is invoked
+    # @yieldreturn [Object] the tool output (String, Hash, Array, or any object)
+    # @return [Tools::Definition] the registered definition
+    def register(name, description: nil, parameters: nil, strict: false, callable: nil, **extra, &handler)
+      name = name.to_s
+      raise ArgumentError.new("Tool name is required") if name.empty?
+
+      definition = Tools::Definition.new(
+        name: name,
+        description: description,
+        parameters: parameters,
+        strict: strict,
+        **extra
+      )
+      @definitions[name] = definition
+      @handlers[name] = callable || handler
+      definition
+    end
+
+    # Look up a handler by name.
+    #
+    # @param name [String] the tool name
+    # @return [#call, nil] the handler, or nil if not found
+    def handler_for(name)
+      @handlers[name]
+    end
+
+    # Look up a definition by name.
+    #
+    # @param name [String] the tool name
+    # @return [Tools::Definition, nil] the definition, or nil if not found
+    def definition_for(name)
+      @definitions[name]
+    end
+
+    # Return all tool definitions.
+    #
+    # @return [Array<Tools::Definition>] all tool definitions
+    def definitions
+      @definitions.values
+    end
+
+    # Invoke a tool by name with the given arguments.
+    #
+    # @param name [String] the tool name
+    # @param arguments [Hash] the parsed arguments
+    # @return [Object] the raw tool handler return value
+    # @raise [ToolNotFoundError] if no handler is found for the given name
+    def invoke(name, arguments)
+      handler = handler_for(name)
+      raise ToolNotFoundError, "No handler registered for tool: #{name.inspect}" unless handler
+
+      handler.call(arguments)
+    end
+  end
+end

data/lib/prompt_builder/tools/definition.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Tools
+    # Represents a tool definition that describes a function available to the model.
+    class Definition
+      # @return [String] the tool name
+      attr_reader :name
+
+      # @return [String, nil] the tool description
+      attr_reader :description
+
+      # @return [Hash, nil] the JSON Schema for the tool parameters
+      attr_reader :parameters
+
+      # @return [Boolean] whether strict mode is enabled
+      attr_reader :strict
+
+      # @return [Hash, nil] provider-specific extra data (e.g. cache_control)
+      attr_reader :extra
+
+      # Create a new tool Definition.
+      #
+      # @param name [String] the tool name
+      # @param description [String, nil] the tool description
+      # @param parameters [Hash, nil] the JSON Schema for the parameters
+      # @param strict [Boolean] whether strict mode is enabled
+      # @param extra [Hash] provider-specific extra keyword arguments
+      def initialize(name:, description: nil, parameters: nil, strict: false, **extra)
+        @name = name&.to_s
+        @description = description&.to_s
+        @parameters = PromptBuilder.jsonify(parameters)
+        @strict = strict ? true : false
+        @extra = extra.transform_keys(&:to_s)
+      end
+
+      class << self
+        # Deserialize a Definition from a Hash.
+        #
+        # @param hash [Hash] a Hash with string keys
+        # @return [Definition]
+        def from_h(hash)
+          new(
+            name: hash["name"],
+            description: hash["description"],
+            parameters: hash["parameters"],
+            strict: hash.fetch("strict", false),
+            **hash.except("type", "name", "description", "parameters", "strict").transform_keys(&:to_sym)
+          )
+        end
+      end
+
+      # Serialize to a Hash with string keys. Nil values are omitted.
+      #
+      # @return [Hash]
+      def to_h
+        h = {"type" => "function", "name" => @name}
+        h["description"] = @description if @description
+        h["parameters"] = @parameters if @parameters
+        h["strict"] = @strict if @strict
+        h = PromptBuilder.jsonify(@extra).merge(h) unless @extra.empty?
+        h
+      end
+    end
+  end
+end

data/lib/prompt_builder/tools.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  module Tools
+    autoload :Definition, File.expand_path("tools/definition", __dir__)
+  end
+end

data/lib/prompt_builder/usage.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module PromptBuilder
+  # Value object representing token usage statistics from an API response.
+  class Usage
+    # @return [Integer, nil] number of input tokens
+    attr_reader :input_tokens
+
+    # @return [Integer, nil] number of output tokens
+    attr_reader :output_tokens
+
+    # @return [Integer, nil] total number of tokens
+    attr_reader :total_tokens
+
+    # @return [Hash, nil] input token details
+    attr_reader :input_tokens_details
+
+    # @return [Hash, nil] output token details
+    attr_reader :output_tokens_details
+
+    # Create a new Usage value object.
+    #
+    # @param input_tokens [Integer, nil] number of input tokens
+    # @param output_tokens [Integer, nil] number of output tokens
+    # @param total_tokens [Integer, nil] total number of tokens
+    # @param input_tokens_details [Hash, nil] input token details
+    # @param output_tokens_details [Hash, nil] output token details
+    # @param reasoning_tokens [Integer, nil] number of reasoning tokens
+    def initialize(input_tokens: nil, output_tokens: nil, total_tokens: nil,
+      input_tokens_details: nil, output_tokens_details: nil, reasoning_tokens: nil)
+      @input_tokens = input_tokens&.to_i
+      @output_tokens = output_tokens&.to_i
+      @total_tokens = total_tokens&.to_i
+      @input_tokens_details = PromptBuilder.jsonify(input_tokens_details)
+      @output_tokens_details = PromptBuilder.jsonify(output_tokens_details) || build_output_tokens_details(reasoning_tokens)
+    end
+
+    class << self
+      # Deserialize a Usage from a Hash.
+      #
+      # @param hash [Hash] a Hash with string keys
+      # @return [Usage]
+      def from_h(hash)
+        input_tokens_details = hash["input_tokens_details"]
+        output_tokens_details = hash["output_tokens_details"]
+
+        new(
+          input_tokens: hash["input_tokens"],
+          output_tokens: hash["output_tokens"],
+          total_tokens: hash["total_tokens"],
+          input_tokens_details: input_tokens_details,
+          output_tokens_details: output_tokens_details,
+          reasoning_tokens: hash["reasoning_tokens"] || output_tokens_details&.fetch("reasoning_tokens", nil)
+        )
+      end
+    end
+
+    # Number of cached input tokens.
+    #
+    # @return [Integer, nil]
+    def cached_tokens
+      @input_tokens_details&.fetch("cached_tokens", nil)
+    end
+
+    # Number of tokens used for cache creation. This is specific only to the Anthropic Messages API format.
+    #
+    # @return [Integer, nil]
+    def cache_creation_input_tokens
+      @input_tokens_details&.fetch("cache_creation_input_tokens", nil)
+    end
+
+    # Number of reasoning tokens.
+    #
+    # @return [Integer, nil]
+    def reasoning_tokens
+      @output_tokens_details&.fetch("reasoning_tokens", nil)
+    end
+
+    # Serialize to a Hash with string keys. Nil values are omitted.
+    #
+    # @return [Hash]
+    def to_h
+      h = {}
+      h["input_tokens"] = @input_tokens if @input_tokens
+      h["output_tokens"] = @output_tokens if @output_tokens
+      h["total_tokens"] = @total_tokens if @total_tokens
+      h["input_tokens_details"] = @input_tokens_details if @input_tokens_details
+      h["output_tokens_details"] = @output_tokens_details if @output_tokens_details
+      h
+    end
+
+    private
+
+    def build_output_tokens_details(reasoning_tokens)
+      return nil unless reasoning_tokens
+
+      {"reasoning_tokens" => reasoning_tokens}
+    end
+  end
+end