ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/support/utils.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support # :nodoc:
+    module Utils # :nodoc:
+      UNDERSCORE_BOUNDARY = /(?<=[a-z\d])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/
+
+      # Keys a JSON Schema document carries for its own sake: $schema names the
+      # dialect and title names the document, neither of which describes the shape
+      # a provider is being asked to produce.
+      SCHEMA_METADATA_KEYS = %w[$schema title].freeze
+
+      module_function
+
+      def hash_get(hash, key)
+        symbol_key = key.to_sym
+        hash.key?(symbol_key) ? hash[symbol_key] : hash[key.to_s]
+      end
+
+      def strip_schema_metadata(schema)
+        return schema unless schema.is_a?(Hash)
+
+        schema.reject { |key, _| SCHEMA_METADATA_KEYS.include?(key.to_s) }
+      end
+
+      # Acronym-aware underscoring: 'HTTPProxyTool' -> 'http_proxy_tool'.
+      def underscore(name)
+        name.gsub(UNDERSCORE_BOUNDARY, '_').downcase
+      end
+
+      def to_safe_array(item)
+        case item
+        when Array then item
+        when Hash then [item]
+        else item.respond_to?(:read) ? [item] : Array(item)
+        end
+      end
+
+      def to_time(value)
+        return unless value
+
+        value.is_a?(Time) ? value : Time.parse(value.to_s)
+      end
+
+      def to_date(value)
+        return unless value
+
+        value.is_a?(Date) ? value : Date.parse(value.to_s)
+      end
+
+      def safe_constantize(name)
+        parts = name.to_s.split('::').reject(&:empty?)
+        return if parts.empty?
+
+        namespace = Object
+        until parts.empty?
+          const_name = parts.shift
+          return unless namespace.const_defined?(const_name, false)
+
+          namespace = namespace.const_get(const_name, false)
+        end
+        namespace
+      rescue NameError
+        nil
+      end
+
+      def parse_iso_date_prefix(value)
+        return value if value.is_a?(Date)
+
+        date = value.to_s.strip
+        return if date.empty?
+
+        case date
+        when /\A\d{4}-\d{2}-\d{2}\z/
+          Date.iso8601(date)
+        when /\A\d{4}-\d{2}\z/
+          Date.iso8601("#{date}-01")
+        when /\A\d{4}\z/
+          Date.iso8601("#{date}-01-01")
+        end
+      rescue ArgumentError
+        nil
+      end
+
+      def iso_date_prefix_to_utc_midnight_string(value)
+        date = parse_iso_date_prefix(value)
+        "#{date.strftime('%Y-%m-%d')} 00:00:00 UTC" if date
+      end
+
+      def deep_merge(original, overrides)
+        original.merge(overrides) do |_key, original_value, overrides_value|
+          if original_value.is_a?(Hash) && overrides_value.is_a?(Hash)
+            deep_merge(original_value, overrides_value)
+          else
+            overrides_value
+          end
+        end
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, val), duped|
+            duped[deep_dup(key)] = deep_dup(val)
+          end
+        when Array
+          value.map { |item| deep_dup(item) }
+        else
+          begin
+            value.dup
+          rescue TypeError
+            value
+          end
+        end
+      end
+
+      def deep_stringify_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, val), result|
+            result[key.to_s] = deep_stringify_keys(val)
+          end
+        when Array
+          value.map { |item| deep_stringify_keys(item) }
+        when Symbol
+          value.to_s
+        else
+          value
+        end
+      end
+
+      def deep_symbolize_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, val), result|
+            symbolized_key = key.respond_to?(:to_sym) ? key.to_sym : key
+            result[symbolized_key] = deep_symbolize_keys(val)
+          end
+        when Array
+          value.map { |item| deep_symbolize_keys(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/thinking.rb

@@ -1,48 +1,155 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Represents provider thinking output.
+  # A Thinking holds the reasoning output a provider returned alongside a
+  # response. Instances appear on Message#thinking, and on Chunk#thinking
+  # while streaming, when the model exposes its thinking.
+  #
+  #   chat = RubyLLM.chat(model: 'claude-opus-5').with_thinking(display: :summarized)
+  #   response = chat.ask "What is 15 * 23?"
+  #   response.thinking&.text
+  #   response.thinking&.signature
+  #
   class Thinking
-    attr_reader :text, :signature
+    include Support::Inspectable
 
-    def initialize(text: nil, signature: nil)
+    # The reasoning text the provider returned, or +nil+.
+    attr_reader :text
+
+    # The provider's opaque signature or encrypted reasoning payload for the
+    # thinking block, or +nil+. Shown as redacted in pretty-print output.
+    attr_reader :signature
+
+    def initialize(text: nil, signature: nil) # :nodoc:
       @text = text
       @signature = signature
     end
 
-    def self.build(text: nil, signature: nil)
-      text = nil if text.is_a?(String) && text.empty?
+    def self.build(text: nil, signature: nil) # :nodoc:
       signature = nil if signature.is_a?(String) && signature.empty?
+      text = nil if text.is_a?(String) && text.empty? && signature.nil?
 
       return nil if text.nil? && signature.nil?
 
       new(text: text, signature: signature)
     end
 
-    def pretty_print(printer)
-      printer.object_group(self) do
-        printer.breakable
-        printer.text 'text='
-        printer.pp text
-        printer.comma_breakable
-        printer.text 'signature='
-        printer.pp(signature ? '[REDACTED]' : nil)
-      end
+    def inspect_attributes # :nodoc:
+      { text: text, signature: signature ? '[REDACTED]' : nil }
     end
   end
 
   class Thinking
-    # Normalized config for thinking across providers.
-    class Config
-      attr_reader :effort, :budget
+    class Controls # :nodoc: all
+      PREFERRED_EFFORTS = %w[medium low minimal high xhigh max].freeze
+
+      def initialize(model)
+        @model = model
+      end
+
+      def enable
+        effort = default_effort
+        return { effort: effort } if effort
+
+        budget = explicit_budget
+        return { budget: budget } if budget
+        return { enabled: true } if model.reasoning_option(:toggle)
+
+        effort = preferred_effort
+        return { effort: effort } if effort
+
+        budget = minimum_budget
+        return { budget: budget } if budget
+
+        :already_on if reasoning_model? && model.reasoning_options.empty?
+      end
+
+      def disable
+        return { effort: :none } if model.reasoning_option_values(:effort).include?('none')
 
-      def initialize(effort: nil, budget: nil)
-        @effort = effort.is_a?(Symbol) ? effort.to_s : effort
+        budget = model.reasoning_option(:budget_tokens)
+        return { budget: 0 } if budget && budget[:min].is_a?(Numeric) && budget[:min] <= 0
+
+        { enabled: false } if model.reasoning_option(:toggle) || budget
+      end
+
+      private
+
+      attr_reader :model
+
+      def default_effort
+        option = model.reasoning_option(:effort)
+        return unless option&.key?(:default)
+
+        default = option[:default].to_s
+        default.to_sym unless default == 'none'
+      end
+
+      def preferred_effort
+        PREFERRED_EFFORTS.find { |effort| model.reasoning_option_values(:effort).include?(effort) }&.to_sym
+      end
+
+      def explicit_budget
+        default = model.reasoning_option(:budget_tokens)&.fetch(:default, nil)
+        default if default.is_a?(Numeric) && default.positive?
+      end
+
+      def minimum_budget
+        minimum = model.reasoning_option(:budget_tokens)&.fetch(:min, nil)
+        return unless minimum.is_a?(Numeric)
+
+        [minimum, 1].max
+      end
+
+      def reasoning_model?
+        model.supports?(:reasoning) || model.metadata[:reasoning] || model.metadata['reasoning']
+      end
+    end
+
+    class Config # :nodoc: all
+      attr_reader :effort, :budget, :display, :enabled
+
+      def self.default
+        new(intent: :enable)
+      end
+
+      def self.disabled
+        new(intent: :disable)
+      end
+
+      def initialize(effort: nil, budget: nil, display: nil, enabled: nil, intent: nil)
+        @effort = effort&.to_sym
         @budget = budget
+        @display = display&.to_sym
+        @enabled = enabled
+        @intent = intent
       end
 
       def enabled?
-        !effort.nil? || !budget.nil?
+        !@intent.nil? || !enabled.nil? || !effort.nil? || !budget.nil? || !display.nil?
+      end
+
+      def disabled?
+        enabled == false || effort == :none
+      end
+
+      def resolve(model)
+        return self if @intent.nil?
+
+        options = Controls.new(model).public_send(@intent)
+        return nil if options == :already_on
+        raise ArgumentError, resolution_error(model) unless options
+
+        self.class.new(**options)
+      end
+
+      private
+
+      def resolution_error(model)
+        message = "RubyLLM does not know how to #{@intent} thinking for #{model.provider}/#{model.id}."
+        return "#{message} Pass effort:, budget:, or display:." if @intent == :enable
+
+        "#{message} The model registry has no off control."
       end
     end
   end

data/lib/ruby_llm/tokenization.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # The token IDs produced by a model's tokenizer for plain text.
+  # These exclude chat formatting, tools, and media, and do not measure
+  # billable generation usage.
+  class Tokenization
+    include Support::Inspectable
+
+    # The integer token IDs in text order.
+    attr_reader :ids
+
+    # The id of the model whose tokenizer was used.
+    attr_reader :model
+
+    # The provider's unmodified response, including token strings when available.
+    attr_reader :raw
+
+    # Tokenizes +text+ and returns a Tokenization. Most code calls
+    # RubyLLM.tokenize. +model:+ defaults to the configured chat model;
+    # +provider:+ selects its provider. +assume_model_exists:+ skips
+    # registry lookup, and +context:+ supplies an isolated configuration.
+    #
+    #   result = RubyLLM.tokenize("Hello Ruby", model: "grok-4.3", provider: :xai)
+    #   result.ids
+    #   result.count
+    #
+    # Raises ArgumentError for non-string input and RubyLLM::Error when
+    # the provider does not expose a tokenizer.
+    def self.tokenize(text, model: nil, provider: nil, assume_model_exists: false, context: nil)
+      raise ArgumentError, 'text must be a String' unless text.is_a?(String)
+
+      config = context&.config || RubyLLM.config
+      model ||= config.default_model
+      model, provider_instance = Models.resolve(model, provider:, assume_model_exists:, config:)
+      payload = { model: model.id, provider: provider_instance.slug }
+      RubyLLM.instrument('tokenization.ruby_llm', payload, config:) do |event|
+        result = provider_instance.tokenize(text, model:)
+        event[:result] = result
+        result
+      end
+    end
+
+    def initialize(ids:, model:, raw: nil) # :nodoc:
+      @ids = ids.dup.freeze
+      @model = model
+      @raw = raw
+    end
+
+    # Returns the number of tokens in the text.
+    def count
+      ids.length
+    end
+
+    def inspect_attributes # :nodoc:
+      { model:, count: }
+    end
+  end
+end

data/lib/ruby_llm/tokens.rb

@@ -1,55 +1,125 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Represents token usage for a response.
+  # A Tokens holds normalized token counts for a provider attempt, a
+  # response, or an aggregate. Read them from Chat#tokens, Message#tokens,
+  # Chunk#tokens, and individual operation results such as Embedding.
+  # Counts the provider did not report are +nil+.
+  #
+  #   response = chat.ask "What is the capital of France?"
+  #   response.tokens.input       # standard input tokens
+  #   response.tokens.output      # billable output tokens
+  #   response.tokens.cache_read  # prompt cache reads
+  #   response.tokens.cache_write # prompt cache writes
+  #
   class Tokens
-    attr_reader :input, :output, :cached, :cache_creation, :thinking
+    include Support::Inspectable
 
-    # rubocop:disable Metrics/ParameterLists
-    def initialize(input: nil, output: nil, cached: nil, cache_creation: nil, thinking: nil, reasoning: nil)
+    # The number of standard (non-cached) input tokens, or +nil+ if the
+    # provider did not report it.
+    attr_reader :input
+
+    # The number of billable output tokens, or +nil+ if the provider did
+    # not report it. Includes thinking tokens when the provider bills
+    # them as output.
+    attr_reader :output
+
+    # The number of tokens served from the provider's prompt cache, or
+    # +nil+ if the provider did not report it.
+    attr_reader :cache_read
+
+    # The number of tokens written to the provider's prompt cache, or
+    # +nil+ if the provider did not report it.
+    attr_reader :cache_write
+
+    # The number of thinking (reasoning) tokens, or +nil+ if the provider
+    # does not report them.
+    attr_reader :thinking
+
+    # The provider's server-tool usage counters as a Hash, such as
+    # <tt>{"web_search_requests" => 2}</tt>, or +nil+ if the provider did
+    # not report any. Counters are provider-shaped and billed per use, not
+    # in tokens.
+    attr_reader :server_tool_use
+
+    # The exact cost of the call in US dollars as reported by the
+    # provider, or +nil+ if the provider does not report one. When present,
+    # Cost#total returns it instead of a registry-price estimate.
+    attr_reader :reported_cost
+
+    # Creates token counts from the supplied values. Omitted counts remain
+    # +nil+; zero means a reported count of zero. Returns a Tokens object
+    # even when every count is +nil+.
+    #
+    #   tokens = RubyLLM::Tokens.new(input: 100, output: 20)
+    #   RubyLLM.models.find("gpt-5.6").cost_for(tokens).total
+    #
+    # +server_tool_use:+ holds provider tool-usage counters;
+    # +reported_cost:+ holds the provider's total price in US dollars.
+    def initialize(input: nil, output: nil, cache_read: nil, cache_write: nil, thinking: nil,
+                   server_tool_use: nil, reported_cost: nil)
       @input = input
       @output = output
-      @cached = cached
-      @cache_creation = cache_creation
-      @thinking = thinking || reasoning
+      @cache_read = cache_read
+      @cache_write = cache_write
+      @thinking = thinking
+      @server_tool_use = server_tool_use
+      @reported_cost = reported_cost
     end
-    # rubocop:enable Metrics/ParameterLists
 
-    # rubocop:disable Metrics/ParameterLists
-    def self.build(input: nil, output: nil, cached: nil, cache_creation: nil, thinking: nil, reasoning: nil)
-      return nil if [input, output, cached, cache_creation, thinking, reasoning].all?(&:nil?)
+    # Sums token counts across provider attempts. A bucket remains +nil+ when
+    # no attempt reported it.
+    def self.aggregate(tokens)
+      tokens = Array(tokens).compact
+      return new if tokens.empty?
+      return tokens.first if tokens.one?
 
-      new(
-        input: input,
-        output: output,
-        cached: cached,
-        cache_creation: cache_creation,
-        thinking: thinking,
-        reasoning: reasoning
-      )
+      values = %i[input output cache_read cache_write thinking reported_cost].to_h do |component|
+        reported = tokens.filter_map { |usage| usage.public_send(component) }
+        [component, reported.empty? ? nil : reported.sum]
+      end
+      new(**values, server_tool_use: aggregate_server_tool_use(tokens))
+    end
+
+    def self.aggregate_server_tool_use(tokens) # :nodoc:
+      reported = tokens.filter_map(&:server_tool_use)
+      return nil if reported.empty?
+
+      reported.each_with_object({}) do |counters, total|
+        counters.each { |tool, count| total[tool] = total.fetch(tool, 0) + count.to_i }
+      end
     end
-    # rubocop:enable Metrics/ParameterLists
+    private_class_method :aggregate_server_tool_use
 
+    # Returns the counts as a hash with keys +:input_tokens+,
+    # +:output_tokens+, +:cache_read_tokens+, +:cache_write_tokens+, and
+    # +:thinking_tokens+, omitting +nil+ counts. Includes +:server_tool_use+
+    # when reported. The provider's reported cost is available separately
+    # through #reported_cost.
+    #
+    #   response.tokens.to_h
+    #   # => {input_tokens: 14, output_tokens: 5}
+    #
     def to_h
       {
         input_tokens: input,
         output_tokens: output,
-        cached_tokens: cached,
-        cache_creation_tokens: cache_creation,
-        thinking_tokens: thinking
+        cache_read_tokens: cache_read,
+        cache_write_tokens: cache_write,
+        thinking_tokens: thinking,
+        server_tool_use: server_tool_use
       }.compact
     end
 
-    def reasoning
-      thinking
-    end
-
-    def cache_read
-      cached
-    end
-
-    def cache_write
-      cache_creation
+    def inspect_attributes # :nodoc:
+      {
+        input: input,
+        output: output,
+        cache_read: cache_read,
+        cache_write: cache_write,
+        thinking: thinking,
+        server_tool_use: server_tool_use
+      }.compact
     end
   end
 end