prompt_builder 0.1.2 → 0.3.0

data/lib/prompt_builder/session.rb

@@ -27,6 +27,25 @@ module PromptBuilder
     JSONIFY_FIELDS = %i[include tool_choice metadata text stream_options reasoning].freeze
     private_constant :JSONIFY_FIELDS
 
+    # Effort levels accepted by +think+. This is the union of the levels
+    # recognized across serializers; each serializer omits levels its target
+    # API does not support.
+    THINK_EFFORT_LEVELS = %w[minimal low medium high xhigh max].freeze
+    private_constant :THINK_EFFORT_LEVELS
+
+    # All keyword options accepted by +initialize+.
+    #
+    # This constant is public API — unlike the private field-group constants
+    # above, it must not be marked with +private_constant+. Integrating gems
+    # use it to validate or partition option hashes before constructing a
+    # Session, e.g. +options.slice(*PromptBuilder::Session::INITIALIZE_OPTIONS)+.
+    #
+    # @api public
+    # @return [Array<Symbol>] the supported keyword option names
+    INITIALIZE_OPTIONS = (
+      STRING_FIELDS + FLOAT_FIELDS + INTEGER_FIELDS + BOOLEAN_FIELDS + JSONIFY_FIELDS + %i[input extra system]
+    ).freeze
+
     # @!attribute [rw] model
     #   @return [String, nil] the model identifier
     # @!attribute [rw] instructions
@@ -109,10 +128,44 @@ module PromptBuilder
     # @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
+    # Restore the response boundary, e.g. when deserializing a session. The
+    # value is clamped to the current item count. Normally the boundary is
+    # maintained by +add_response+; use this only to reconstruct state.
+    #
+    # @param index [Integer] the boundary index
+    # @return [Integer]
+    def response_boundary_index=(index)
+      @response_boundary_index = index.to_i.clamp(0, @items.length)
+    end
+
+    # Provider-specific extra data for serializers. Always returns a Hash, empty
+    # when nothing is set. Keys are always Strings.
+    #
+    # The returned Hash is a copy, so mutating it does not change the session.
+    # To add or remove a key, modify a copy and assign it back:
+    #
+    #   session.extra = session.extra.merge("guardrail_config" => {"guardrailIdentifier" => "gr-1"})
+    #
+    # Recognized keys vary by target format. Unrecognized keys are silently
+    # ignored by each serializer.
+    #
+    # @return [Hash] a copy of the provider-specific extra data
+    def extra
+      PromptBuilder.jsonify(@extra)
+    end
+
+    # Replace the provider-specific extra data. Keys are deep-stringified with
+    # +PromptBuilder.jsonify+ and the value is copied, so the assigned Hash is
+    # not shared with the session. Pass +nil+ to clear.
+    #
+    # @param value [Hash, nil] the extra data, or nil to clear it
+    # @return [Hash] the stored extra data
+    # @raise [ArgumentError] if the value is neither a Hash nor nil
+    def extra=(value)
+      raise ArgumentError, "extra must be a Hash" unless value.nil? || value.is_a?(Hash)
+
+      @extra = PromptBuilder.jsonify(value || {})
+    end
 
     class << self
       # Deserialize a Session from a Hash produced by +to_h+ or parsed JSON.
@@ -125,7 +178,7 @@ module PromptBuilder
       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"]
+        attrs[:extra] = hash["extra"]
         session = new(**attrs)
 
         Array(hash["input"]).each do |item_hash|
@@ -138,6 +191,8 @@ module PromptBuilder
           session.register_tool(defn.name, description: defn.description, parameters: defn.parameters, strict: defn.strict, **extra)
         end
 
+        session.response_boundary_index = hash["response_boundary_index"] if hash["response_boundary_index"]
+
         session
       end
     end
@@ -145,19 +200,33 @@ module PromptBuilder
     # 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.
+    # to +nil+. The +system+ and +input+ shorthands auto-create a system and
+    # user message if provided. Unsupported keyword options raise an ArgumentError.
     #
     # @param attributes [Hash] keyword options; see attribute declarations above
+    # @option attributes [String, nil] :system optional string shorthand; a system
+    #   message is automatically added with this text
     # @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
+    #   serializers; recognized keys vary by target format. Keys are stringified.
+    #   Defaults to an empty Hash and can be replaced later with +extra=+.
+    # @raise [ArgumentError] if an unsupported option is passed
     def initialize(**attributes)
+      unsupported = attributes.keys - INITIALIZE_OPTIONS
+      unless unsupported.empty?
+        raise ArgumentError, "unsupported option#{"s" if unsupported.size > 1}: #{unsupported.join(", ")}"
+      end
+
       (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]
+
+      self.extra = attributes[:extra]
+
       @items = []
+      system(attributes[:system]) if attributes[:system]
+
       @tool_definitions = {}
       @response_boundary_index = 0
       user(attributes[:input]) if attributes[:input]
@@ -171,6 +240,7 @@ module PromptBuilder
     #  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(text: "Hello, how are you?") # type defaults to "input_text"
     #  session.user([
     #    Content::InputText.new(text: "What is in this image?"),
     #    Content::InputImage.new(url: "http://example.com/image.png")
@@ -195,6 +265,10 @@ module PromptBuilder
     #
     # @param content [String, Content::Base, Hash, Array<Content::Base>, Array<Hash>] the message content
     # @return [Items::Message] the added message
+    # @example
+    #  session.system("You are a helpful assistant.")
+    #  session.system(text: "You are a helpful assistant.") # type defaults to "input_text"
+    #  session.system(text: "You are a helpful assistant.", cache_point: true, cache_control: {type: "ephemeral"})
     def system(content)
       add_item(Items::Message.new(role: "system", content: content))
     end
@@ -247,6 +321,19 @@ module PromptBuilder
       @response_boundary_index = @items.length
     end
 
+    # Clear all conversation items and the system instructions, returning the
+    # session to a fresh local-state start. Model configuration and registered
+    # tools are preserved.
+    #
+    # @return [self]
+    def clear
+      @items.clear
+      self.instructions = nil
+      self.previous_response_id = nil
+      @response_boundary_index = 0
+      self
+    end
+
     # Register a tool on this session.
     #
     # @param name [String] the tool name
@@ -263,7 +350,7 @@ module PromptBuilder
         strict: strict,
         **extra
       )
-      @tool_definitions[name] = definition
+      @tool_definitions[name.to_s] = definition
       definition
     end
 
@@ -286,6 +373,143 @@ module PromptBuilder
       end
     end
 
+    # Copy tool definitions from a ToolRegistry onto this session by name.
+    # With no names, all tools in the registry are copied (same as
+    # +register_tools+). Definitions are copied, so later registry changes do
+    # not affect the session and the tools survive +to_h+/+from_h+ round-trips.
+    #
+    # @param names [Array<String, Symbol>] the tool names to copy; empty for all
+    # @param registry [ToolRegistry, nil] the registry to copy from; defaults
+    #   to the global +PromptBuilder.tool_registry+
+    # @return [Array<Tools::Definition>] the definitions registered on the session
+    # @raise [ToolNotFoundError] if a name is not registered in the registry
+    # @example
+    #   session.use_tools("weather", "traffic_conditions")
+    #   session.use_tools                                  # all registry tools
+    #   session.use_tools(:weather, registry: my_registry)
+    def use_tools(*names, registry: nil)
+      registry ||= PromptBuilder.tool_registry
+      raise ArgumentError, "registry must be an instance of ToolRegistry" unless registry.is_a?(ToolRegistry)
+
+      definitions = if names.empty?
+        registry.definitions
+      else
+        names.map do |name|
+          registry.definition_for(name.to_s) ||
+            raise(ToolNotFoundError, "No tool registered with name: #{name.to_s.inspect}")
+        end
+      end
+
+      definitions.map 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
+
+    # Remove a single registered tool by name. Accepts a string or symbol and
+    # matches regardless of how the tool's key was stored.
+    #
+    # @param name [String, Symbol] the tool name
+    # @return [Tools::Definition, nil] the removed definition, or nil if not found
+    def remove_tool(name)
+      key = name.to_s
+      removed = nil
+      @tool_definitions.delete_if do |k, defn|
+        match = k.to_s == key
+        removed = defn if match
+        match
+      end
+      removed
+    end
+
+    # Remove all registered tools from the session.
+    #
+    # @return [Array<Tools::Definition>] the removed tool definitions
+    def clear_tools
+      removed = @tool_definitions.values
+      @tool_definitions.clear
+      removed
+    end
+
+    # Configure JSON Schema structured output. Writes the canonical
+    # +text.format+ wire hash consumed by all serializers, preserving any
+    # other +text+ keys (e.g. +verbosity+) already set.
+    #
+    # @param schema [Hash] the JSON Schema for the response
+    # @param name [String] the schema name
+    # @param strict [Boolean, nil] whether strict schema adherence is requested;
+    #   omitted from the format when nil
+    # @param description [String, nil] an optional schema description
+    # @return [Hash] the resulting +text+ configuration
+    # @example
+    #   session.json_output({"type" => "object", "properties" => {...}}, strict: true)
+    def json_output(schema, name: "response", strict: nil, description: nil)
+      format = {"type" => "json_schema", "name" => name.to_s, "schema" => schema}
+      format["strict"] = strict unless strict.nil?
+      format["description"] = description.to_s if description
+      self.text = (text || {}).merge("format" => format)
+    end
+
+    # Configure reasoning/extended thinking portably across serializers.
+    # Stores a normalized +reasoning+ configuration; each serializer maps it
+    # to its native parameter:
+    #
+    # - +effort+ — Messages (+output_config.effort+), Chat Completions
+    #   (+reasoning_effort+), Gemini (+thinkingConfig.thinkingLevel+), and
+    #   Open Responses (+reasoning.effort+)
+    # - +budget_tokens+ — Messages (+thinking.budget_tokens+) and Gemini
+    #   (+thinkingConfig.thinkingBudget+); ignored by effort-based APIs
+    # - Converse supports neither and warns once at serialization time
+    #
+    # Pass either +effort+ or +budget_tokens+, not both — providers reject
+    # requests that set both controls. Direct +session.reasoning = {...}+
+    # assignment keeps working for provider-specific keys.
+    #
+    # @param enabled [Boolean] pass +false+ to clear the reasoning configuration
+    # @param effort [String, Symbol, nil] a portable effort level; one of
+    #   +minimal+, +low+, +medium+, +high+, +xhigh+, +max+ (unsupported levels
+    #   are omitted by serializers whose target API does not accept them)
+    # @param budget_tokens [Integer, nil] an explicit thinking token budget
+    # @return [Hash, nil] the resulting +reasoning+ configuration
+    # @raise [ArgumentError] if neither or both of +effort+ and +budget_tokens+
+    #   are given when enabling, or the values are invalid
+    # @example
+    #   session.think(effort: :medium)       # portable across serializers
+    #   session.think(budget_tokens: 8_000)  # explicit where supported
+    #   session.think(false)                 # disable
+    def think(enabled = true, effort: nil, budget_tokens: nil)
+      unless enabled
+        raise ArgumentError, "cannot combine think(false) with effort or budget_tokens" if effort || budget_tokens
+
+        return self.reasoning = nil
+      end
+
+      if effort && budget_tokens
+        raise ArgumentError, "pass either effort or budget_tokens, not both"
+      elsif effort.nil? && budget_tokens.nil?
+        raise ArgumentError, "think requires effort: or budget_tokens:"
+      end
+
+      if effort
+        effort = effort.to_s
+        unless THINK_EFFORT_LEVELS.include?(effort)
+          raise ArgumentError, "effort must be one of: #{THINK_EFFORT_LEVELS.join(", ")}"
+        end
+        self.reasoning = {"effort" => effort}
+      else
+        budget_tokens = Integer(budget_tokens)
+        raise ArgumentError, "budget_tokens must be positive" unless budget_tokens.positive?
+
+        self.reasoning = {"budget_tokens" => budget_tokens}
+      end
+    end
+
     # Return all tool definitions registered on this session.
     #
     # @return [Array<Tools::Definition>] all tool definitions
@@ -332,6 +556,7 @@ module PromptBuilder
 
       h["input"] = @items.map(&:to_h) unless @items.empty?
       h["previous_response_id"] = @previous_response_id if @previous_response_id
+      h["response_boundary_index"] = @response_boundary_index if @response_boundary_index.positive?
 
       h["tools"] = tool_definitions.map(&:to_h) unless @tool_definitions.empty?
 
@@ -355,7 +580,7 @@ module PromptBuilder
         val = send(f)
         h[f.to_s] = val if val
       }
-      h["extra"] = @extra if @extra
+      h["extra"] = extra unless @extra.empty?
 
       h
     end
@@ -376,7 +601,7 @@ module PromptBuilder
     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[:extra] = @extra
       h
     end
   end

data/prompt_builder.gemspec

@@ -36,6 +36,4 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.required_ruby_version = ">= 3.0"
-
-  spec.add_development_dependency "bundler"
 end

metadata

@@ -1,28 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prompt_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Brian Durand
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+dependencies: []
 email:
 - bbdurand@gmail.com
 executables: []