ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/request_shape.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A RequestShape describes a conversation request as the provider received
+  # it, without its contents: each turn's role and parts with their sizes,
+  # the tools on offer, the thinking settings, and the problems RubyLLM finds
+  # in it, such as a part with no data or a tool call with no result. Read it
+  # from Error#request_shape when a provider rejects a request without saying
+  # what is wrong with it.
+  #
+  #   begin
+  #     chat.ask "What's due today?"
+  #   rescue RubyLLM::BadRequestError => e
+  #     Rails.logger.error("#{e.message}\n#{e.request_shape}")
+  #     Rails.error.report(e, context: { request_shape: e.request_shape.to_h })
+  #     raise
+  #   end
+  #
+  # A shape holds no text, tool arguments, tool results, signatures, URLs,
+  # file data, or setting values beyond thinking settings, so you can log it
+  # and send it to an error tracker. A long conversation keeps its first 10
+  # and last 50 turns.
+  class RequestShape
+    include Support::Inspectable
+
+    # The provider's slug, such as <tt>"gemini"</tt>.
+    attr_reader :provider
+
+    # The id of the model the request went to.
+    attr_reader :model
+
+    # Which model call of the current turn the request makes, counting from
+    # 1, so +3+ follows two tool rounds. Returns +nil+ when the request holds
+    # no user turn to count from.
+    attr_reader :step
+
+    # The names of the payload's top-level fields, without their values.
+    attr_reader :payload_keys
+
+    # The thinking settings the request sends, such as an effort or a budget,
+    # as a Hash of the provider's setting names and values.
+    attr_reader :thinking_settings
+
+    # The Part objects of the instructions the request sends apart from its
+    # turns, or an empty Array when the provider takes instructions as a turn.
+    attr_reader :instructions
+
+    # The Turn objects of the conversation, in the order the request sends
+    # them. A long conversation keeps its first 10 and last 50 turns.
+    attr_reader :turns
+
+    # The number of turns the request sends, including omitted ones.
+    attr_reader :turn_count
+
+    # The number of turns left out of #turns.
+    attr_reader :omitted_turns
+
+    # The names of the tools the request offers, in order. Provider tools
+    # keep the name their provider's API gives them.
+    attr_reader :tool_names
+
+    # The ToolRound objects of the turns kept, one for each model turn that
+    # called tools.
+    attr_reader :tool_rounds
+
+    # The Problem objects RubyLLM finds in the request, across every turn.
+    attr_reader :problems
+
+    # Creates a shape. Protocols build shapes in
+    # Protocol#parse_request_shape; every attribute but +turns+ is optional.
+    def initialize(turns:, provider: nil, model: nil, step: nil, payload_keys: [], thinking_settings: {},
+                   instructions: [], turn_count: nil, omitted_turns: 0, tool_names: [], tool_rounds: [], problems: [])
+      @turns = turns
+      @provider = provider
+      @model = model
+      @step = step
+      @payload_keys = payload_keys
+      @thinking_settings = thinking_settings
+      @instructions = instructions
+      @turn_count = turn_count || turns.size
+      @omitted_turns = omitted_turns
+      @tool_names = tool_names
+      @tool_rounds = tool_rounds
+      @problems = problems
+    end
+
+    # Returns the shape as text, one turn per line:
+    #
+    #   gemini, gemini-2.5-flash, model call 1 of the turn
+    #   payload keys: contents, generationConfig, tools
+    #   thinking: includeThoughts true, thinkingBudget -1
+    #   #0 user: text (17 chars)
+    #   #1 model: call find_tasks (args 40 chars), signed
+    #   #2 user: result find_tasks (6859 chars)
+    #   #3 model: thinking (no text), signed, text (1075 chars)
+    #   #4 user: text (31 chars)
+    #   tools: find_tasks
+    #   tool round at #1: 1 call, 1 result, paired
+    #   problem at #3, part 0: thinking part carries no data
+    #
+    def to_s
+      [summary_line, list_line('payload keys', payload_keys), settings_line, list_line('instructions', instructions),
+       *turn_lines, list_line('tools', tool_names), *tool_rounds.map(&:to_s), *problem_lines].compact.join("\n")
+    end
+
+    # Returns the shape as a Hash with the same keys every time, for
+    # structured logs and error trackers.
+    def to_h
+      {
+        provider: provider, model: model, step: step, payload_keys: payload_keys,
+        thinking_settings: thinking_settings, instructions: instructions.map(&:to_h),
+        turn_count: turn_count, omitted_turns: omitted_turns, turns: turns.map(&:to_h),
+        tool_names: tool_names, tool_rounds: tool_rounds.map(&:to_h), problems: problems.map(&:to_h)
+      }
+    end
+
+    def inspect_attributes # :nodoc:
+      { provider: provider, model: model, turns: turn_count, problems: problems.size }
+    end
+
+    private
+
+    def summary_line
+      line = [provider, model, step_description].compact.join(', ')
+      line unless line.empty?
+    end
+
+    def step_description
+      return unless step
+
+      rounds = step - 1
+      description = "model call #{step} of the turn"
+      return description unless rounds.positive?
+
+      "#{description}, after #{rounds} tool #{rounds == 1 ? 'round' : 'rounds'}"
+    end
+
+    def list_line(label, items)
+      "#{label}: #{items.join(', ')}" if items.any?
+    end
+
+    def settings_line
+      "thinking: #{thinking_settings.map { |name, value| "#{name} #{value}" }.join(', ')}" if thinking_settings.any?
+    end
+
+    def turn_lines
+      turns.each_cons(2).flat_map { |turn, following| [turn.to_s, *gap_line(turn, following)] }
+           .push(*turns.last&.to_s)
+    end
+
+    def gap_line(turn, following)
+      gap = following.index - turn.index - 1
+      "(#{gap} #{gap == 1 ? 'turn' : 'turns'} omitted)" if gap.positive?
+    end
+
+    def problem_lines
+      problems.any? ? problems.map(&:to_s) : ['no problems found']
+    end
+  end
+end

data/lib/ruby_llm/rerank.rb

@@ -49,6 +49,8 @@ module RubyLLM
       Cost.new(tokens:, model: model_info, category: :embeddings)
     end
 
+    attr_writer :model_info # :nodoc:
+
     def model_info # :nodoc:
       @model_info ||= RubyLLM.models.find(model)
     rescue ModelNotFoundError
@@ -64,6 +66,8 @@ module RubyLLM
     # provider-specific and have no cross-provider default. +top_n:+
     # limits how many results come back. +provider_options:+ merges
     # options into the request in the provider's vocabulary.
+    # +owner:+ attributes the usage to a record, such as a user, and wins
+    # over RubyLLM.with_usage_owner.
     #
     #   RubyLLM.rerank "what is ruby", docs, model: "voyageai/rerank-2.5-lite", provider: :openrouter
     #
@@ -74,7 +78,8 @@ module RubyLLM
                     context: nil,
                     top_n: nil,
                     provider_options: {},
-                    metadata: nil)
+                    metadata: nil,
+                    owner: nil)
       config = context&.config || RubyLLM.config
       model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                        config: config)
@@ -94,7 +99,9 @@ module RubyLLM
       }
 
       RubyLLM.instrument('rerank.ruby_llm', payload, config: config) do |event|
-        result = provider_instance.rerank(query, documents, model:, top_n:, provider_options:)
+        result = Accounting::Usage.owned_by(owner) do
+          provider_instance.rerank(query, documents, model:, top_n:, provider_options:)
+        end
         event[:result] = result
         event[:tokens] = result.tokens
         event[:cost] = result.cost

data/lib/ruby_llm/research_job.rb

@@ -68,14 +68,18 @@ module RubyLLM
     # Submits one research task without waiting. +provider:+ and +agent:+
     # are required; +with:+ attaches documents or images where supported.
     # +provider_tools:+ accepts an array of aliases or a Hash of aliases
-    # and their options, as on Chat#with_provider_tools.
+    # and their options, as on Chat#with_provider_tools. The job records
+    # its usage, attributed to +owner:+ or the owner of
+    # RubyLLM.with_usage_owner, when it finishes.
     def self.research_later(prompt, provider:, agent:, with: nil, provider_tools: nil,
-                            context: nil, provider_options: {}, metadata: nil)
+                            context: nil, provider_options: {}, metadata: nil, owner: nil)
       config = context&.config || RubyLLM.config
       instance = Provider.resolve!(provider).new(config)
       payload = { provider: instance.slug, agent:, prompt:, metadata: }
       RubyLLM.instrument('research_job.ruby_llm', payload, config:) do |event|
-        job = instance.research_later(prompt, agent:, with:, provider_tools:, provider_options:)
+        job = Accounting::Usage.owned_by(owner) do
+          instance.research_later(prompt, agent:, with:, provider_tools:, provider_options:)
+        end
         event[:job_id] = job.id
         event[:status] = job.status
         job
@@ -85,9 +89,9 @@ module RubyLLM
     # Runs a research task and returns its Message. On a timeout or
     # interrupt, attempts to cancel the remote task before raising an
     # error retaining the job. +timeout:+ and +interval:+ are seconds.
-    def self.research(prompt, timeout: 600, interval: 5, **options)
+    def self.research(prompt, timeout: 600, interval: 5, **)
       validate_polling_options(timeout, interval)
-      job = research_later(prompt, **options)
+      job = research_later(prompt, **)
       job.wait(timeout:, interval:).message
     rescue Interrupt => e
       raise unless job
@@ -123,6 +127,7 @@ module RubyLLM
       @provider = provider.to_sym
       @agent = agent
       @protocol = protocol
+      @usage_owner = Accounting::Usage.owner
       apply_state(state)
     end
 
@@ -216,12 +221,23 @@ module RubyLLM
       raise Error.new("Research request failed: #{e.message} (job #{id})", job: self, response:), cause: e
     end
 
+    # A job found by ID may have been submitted and recorded elsewhere, so
+    # only a finish this object observes records usage.
     def apply_state(state)
+      observed_finish = pending? && state.fetch(:status) != :pending
       @status = state.fetch(:status)
       @raw = state[:raw]
       @error = state[:error]
       @message = state[:message]
       @tokens = state[:tokens] || @message&.tokens || Tokens.new
+      record_usage if observed_finish
+    end
+
+    def record_usage
+      status = { completed: :succeeded, incomplete: :succeeded, cancelled: :cancelled }.fetch(@status, :failed)
+      entry = Accounting::Usage::Entry.new(operation: :research, provider:, model: agent, status:, tokens:, cost:,
+                                           owner: @usage_owner)
+      Accounting::Usage.report(entry, config: @protocol.config)
     end
 
     def attempt_cancellation

data/lib/ruby_llm/score.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A probability-weighted position on a judgment's ordered levels.
+  class Score
+    include Support::Inspectable
+
+    # Returns the weighted score, which can fall between level indexes.
+    attr_reader :score
+
+    # Returns the ordered descriptions, preserving structured Hashes and Arrays.
+    attr_reader :levels
+
+    # Returns each zero-based Integer level index's probability.
+    attr_reader :probabilities
+
+    # Returns the provider's confidence in the distribution, between 0 and 1.
+    attr_reader :confidence
+
+    def initialize(score:, levels:, probabilities:, confidence:) # :nodoc:
+      @score = score
+      @levels = Judge::Data.copy(levels)
+      @probabilities = probabilities.dup.freeze
+      @confidence = confidence
+      freeze
+    end
+
+    # Returns :score.
+    def type
+      :score
+    end
+
+    # Returns the answer as a Hash.
+    def to_h
+      { type:, score:, levels:, probabilities:, confidence: }
+    end
+
+    def inspect_attributes # :nodoc:
+      { score:, confidence: }
+    end
+  end
+end

data/lib/ruby_llm/search_results.rb

@@ -52,8 +52,8 @@ module RubyLLM
       { KEY => results }
     end
 
-    def to_json(*args) # :nodoc:
-      JSON.generate(to_h, *args)
+    def to_json(*) # :nodoc:
+      JSON.generate(to_h, *)
     end
 
     private

data/lib/ruby_llm/server_tool_call.rb

@@ -39,22 +39,30 @@ module RubyLLM
     # conversation is sent back to the provider.
     attr_reader :raw
 
+    # The HTML of the search suggestions the provider requires you to show
+    # with a grounded answer, such as Google's for Google Search grounding,
+    # or +nil+. Only the live response carries them: #to_h leaves them out,
+    # so a persisted chat never stores them.
+    attr_reader :search_suggestions
+
     def self.from_h(data) # :nodoc:
       data = Support::Utils.deep_symbolize_keys(data)
       new(type: data[:type], name: data[:name], id: data[:id], input: data[:input],
           result: data[:result], raw: data[:raw])
     end
 
-    def initialize(type:, raw:, name: nil, id: nil, input: nil, result: nil) # :nodoc:
+    def initialize(type:, raw:, name: nil, id: nil, input: nil, result: nil, search_suggestions: nil) # :nodoc:
       @type = type
       @name = name
       @id = id
       @input = input
       @result = result
       @raw = raw
+      @search_suggestions = search_suggestions
     end
 
-    # Returns the call's attributes as a Hash, omitting +nil+ values.
+    # Returns the call's attributes as a Hash, omitting +nil+ values and
+    # #search_suggestions.
     def to_h
       {
         type: type,

data/lib/ruby_llm/speech.rb

@@ -54,6 +54,8 @@ module RubyLLM
     # that is not in the registry. +provider_options:+ takes options in the
     # provider's request vocabulary, such as +instructions:+ and +speed:+
     # for OpenAI, and merges them into the request as-is.
+    # +owner:+ attributes the usage to a record, such as a user, and wins
+    # over RubyLLM.with_usage_owner.
     #
     #   speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
     #   speech.save "welcome.mp3"
@@ -82,6 +84,7 @@ module RubyLLM
                    context: nil,
                    provider_options: {},
                    metadata: nil,
+                   owner: nil,
                    &block)
       config = context&.config || RubyLLM.config
       model ||= config.default_speech_model
@@ -105,7 +108,9 @@ module RubyLLM
       }
 
       RubyLLM.instrument('speech.ruby_llm', payload, config: config) do |event|
-        result = provider_instance.speak(input, model:, voice:, format:, provider_options:, &block)
+        result = Accounting::Usage.owned_by(owner) do
+          provider_instance.speak(input, model:, voice:, format:, provider_options:, &block)
+        end
         event[:result] = result
         event[:response_model] = result.model
         event[:voice] = result.voice
@@ -137,6 +142,8 @@ module RubyLLM
       Cost.new(tokens:, model: model_info, category: :audio_tokens)
     end
 
+    attr_writer :model_info # :nodoc:
+
     def model_info # :nodoc:
       @model_info ||= RubyLLM.models.find(model)
     rescue ModelNotFoundError

data/lib/ruby_llm/support/cancellation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support
+    # Lets work that runs inside a chat operation, such as a tool waiting on
+    # a remote server, stop when the chat is cancelled. The chat installs a
+    # checkpoint for the current fiber; #check raises CancelledError once
+    # the chat has been cancelled.
+    module Cancellation # :nodoc:
+      KEY = :ruby_llm_cancellation_checkpoint
+      CHECK_INTERVAL = 0.1
+
+      module_function
+
+      def watch(checkpoint)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = checkpoint
+        yield
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      def check
+        Thread.current[KEY]&.call
+      end
+
+      def pause(seconds)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        loop do
+          check
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          break unless remaining.positive?
+
+          sleep [remaining, CHECK_INTERVAL].min
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/support/inspectable.rb

@@ -17,9 +17,10 @@ module RubyLLM
         attributes = inspect_attributes
                      .reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
                      .map { |name, value| "#{name}: #{format_for_inspect(value)}" }
-        return "#<#{self.class.name}>" if attributes.empty?
+        class_name = self.class.ancestors.find(&:name).name
+        return "#<#{class_name}>" if attributes.empty?
 
-        "#<#{self.class.name} #{attributes.join(', ')}>"
+        "#<#{class_name} #{attributes.join(', ')}>"
       end
 
       def pretty_print(printer) # :nodoc:

data/lib/ruby_llm/support/instrumentation.rb

@@ -5,15 +5,51 @@ module RubyLLM
     module Instrumentation # :nodoc:
       WORKFLOW_CONTEXT_KEY = :ruby_llm_workflow_context
 
+      @subscribers = [].freeze
+      @mutex = Mutex.new
+
       module_function
 
-      def instrument(name, payload = nil, config: nil, **attributes) # rubocop:disable Metrics/PerceivedComplexity
+      def instrument(name, payload = nil, config: nil, **attributes, &block)
         payload ||= {}
         payload = payload.merge(attributes) unless attributes.empty?
         workflow_context = current_workflow
         payload = payload.merge(workflow_context) if workflow_context
         instrumenter = (config || RubyLLM.config).instrumenter
+        subscribers = @subscribers
+        return dispatch(instrumenter, name, payload, &block) if subscribers.empty?
+
+        dispatch = -> { dispatch(instrumenter, name, payload, &block) }
+        subscribers.reverse_each do |subscriber|
+          inner = dispatch
+          dispatch = -> { subscriber.instrument(name, payload, &inner) }
+        end
+        dispatch.call
+      end
+
+      def subscribe(subscriber)
+        @mutex.synchronize { @subscribers = (@subscribers | [subscriber]).freeze }
+      end
+
+      def unsubscribe(subscriber)
+        @mutex.synchronize { @subscribers = (@subscribers - [subscriber]).freeze }
+      end
+
+      def capture_context
+        @subscribers.filter_map do |subscriber|
+          [subscriber, subscriber.capture_context] if subscriber.respond_to?(:capture_context)
+        end
+      end
+
+      def with_context(context, &block)
+        context.reverse_each do |subscriber, value|
+          inner = block
+          block = -> { subscriber.with_context(value, &inner) }
+        end
+        block.call
+      end
 
+      def dispatch(instrumenter, name, payload)
         if instrumenter.respond_to?(:instrument)
           if block_given?
             instrumenter.instrument(name, payload) { yield(payload) }
@@ -24,6 +60,7 @@ module RubyLLM
           yield(payload)
         end
       end
+      private_class_method :dispatch
 
       def current_workflow
         Thread.current[WORKFLOW_CONTEXT_KEY]

data/lib/ruby_llm/support/process_cache.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support # :nodoc:
+    class ProcessCache # :nodoc:
+      LIMIT = 64
+
+      def initialize(limit: LIMIT)
+        @limit = limit
+        @lock = Mutex.new
+        @pid = Process.pid
+        @entries = {}
+      end
+
+      # Builds outside the lock, so a slow build never stalls other threads or
+      # fibers. When two callers race, the first value stored wins.
+      def fetch(key)
+        @lock.synchronize { touch(key) } || store(key, yield)
+      end
+
+      def clear
+        @lock.synchronize { @entries.clear }
+      end
+
+      def delete(key)
+        @lock.synchronize do
+          forget_inherited_entries
+          @entries.delete(key)
+        end
+      end
+
+      private
+
+      def touch(key)
+        forget_inherited_entries
+        value = @entries.delete(key)
+        @entries[key] = value if value
+      end
+
+      def store(key, value)
+        @lock.synchronize do
+          value = touch(key) || value
+          @entries[key] = value
+          @entries.shift while @entries.size > @limit
+          value
+        end
+      end
+
+      # A forked child shares its parent's sockets and credentials. Closing
+      # them here would tear down the parent's connections, so the child only
+      # forgets them.
+      def forget_inherited_entries
+        return if @pid == Process.pid
+
+        @pid = Process.pid
+        @entries = {}
+      end
+    end
+  end
+end

data/lib/ruby_llm/support/progress_reporter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Support
+    # Carries the progress of work that runs inside a chat operation, such
+    # as a tool call, to whoever listens for it. The chat installs a
+    # listener for the current execution context; #report hands it a
+    # Progress. Each concurrent tool call installs its own listener, so its
+    # reports reach only its own callback. The listener lives in fiber
+    # storage, which fibers and threads the tool starts inherit.
+    module ProgressReporter # :nodoc:
+      KEY = :ruby_llm_progress_listener
+
+      module_function
+
+      def listen(listener)
+        previous = Fiber[KEY]
+        Fiber[KEY] = listener
+        yield
+      ensure
+        Fiber[KEY] = previous
+      end
+
+      def listener
+        Fiber[KEY]
+      end
+
+      def report(progress)
+        listener&.call(progress)
+      end
+    end
+  end
+end

data/lib/ruby_llm/thinking.rb

@@ -69,8 +69,9 @@ module RubyLLM
 
         budget = model.reasoning_option(:budget_tokens)
         return { budget: 0 } if budget && budget[:min].is_a?(Numeric) && budget[:min] <= 0
+        return { enabled: false } if model.reasoning_option(:toggle) || budget
 
-        { enabled: false } if model.reasoning_option(:toggle) || budget
+        model.provider_class&.thinking_off_control(model.id)
       end
 
       private