ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/attachment.rb

@@ -30,6 +30,13 @@ module RubyLLM
     # The detected MIME type string, such as <tt>"image/png"</tt>.
     attr_reader :mime_type
 
+    # The requested media resolution: +:low+, +:medium+, +:high+,
+    # +:ultra_high+, +:original+, or +nil+ for the provider default.
+    attr_reader :resolution
+
+    # Media resolutions accepted by +resolution:+.
+    RESOLUTIONS = %i[low medium high ultra_high original].freeze
+
     # File extensions recognized as document attachments when the MIME type
     # alone is inconclusive.
     DOCUMENT_EXTENSIONS = %w[
@@ -49,15 +56,25 @@ module RubyLLM
       case sources
       when nil then []
       when Hash then sources.values.flat_map { |group| wrap(group, config:) }
-      else
-        Support::Utils.to_safe_array(sources).filter_map do |source|
-          next if source.nil? || (source.is_a?(String) && source.strip.empty?)
-
-          source.is_a?(Attachment) ? source : new(source, config:)
-        end
+      else Support::Utils.to_safe_array(sources).filter_map { |source| coerce(source, config:) }
       end
     end
 
+    def self.coerce(source, config:) # :nodoc:
+      return if source.nil? || (source.is_a?(String) && source.strip.empty?)
+      return source if source.is_a?(Attachment)
+      return source.to_attachment if source.respond_to?(:to_attachment)
+      return from_h(source, config:) if source.is_a?(Hash)
+
+      new(source, config:)
+    end
+    private_class_method :coerce
+
+    def self.from_h(data, config: nil) # :nodoc:
+      data = data.transform_keys(&:to_sym)
+      new(data.fetch(:source), filename: data[:filename], resolution: data[:resolution]&.to_sym, config:)
+    end
+
     # Creates an attachment from +source+: a file path, URL, IO-like object,
     # ActiveStorage object, or UploadedFile. Derives the filename from the
     # source when +filename:+ is not given, then detects the MIME type.
@@ -65,6 +82,13 @@ module RubyLLM
     #   RubyLLM::Attachment.new("diagram.png")
     #   RubyLLM::Attachment.new(StringIO.new(data), filename: "report.pdf")
     #
+    # +resolution:+ asks the provider to spend more or fewer tokens on an
+    # image, video, or PDF. +:original+ requests original image detail where
+    # supported, or the highest available resolution. Providers without
+    # the setting ignore it.
+    #
+    #   RubyLLM::Attachment.new("page-3.png", resolution: :ultra_high)
+    #
     # +config:+ is the Configuration a URL source is downloaded with, and
     # defaults to the global one.
     #
@@ -72,8 +96,13 @@ module RubyLLM
     # They can be read or fetched during construction to detect the MIME type.
     # Validate upload parameters before passing them here: an unchecked String
     # can access local files or internal network endpoints.
-    def initialize(source, filename: nil, config: nil)
+    def initialize(source, filename: nil, resolution: nil, config: nil)
+      unless resolution.nil? || RESOLUTIONS.include?(resolution)
+        raise ArgumentError, "resolution must be one of #{RESOLUTIONS.join(', ')}, got #{resolution.inspect}"
+      end
+
       @config = config
+      @resolution = resolution
       @source = source
       @source = source_type_cast
       @filename = filename || source_filename
@@ -100,6 +129,13 @@ module RubyLLM
       @provider_uploads ||= {}
     end
 
+    # Where uploads of this attachment outlive the process: an object that
+    # responds to <tt>fetch(provider:, account:)</tt>,
+    # <tt>store(upload, provider:, account:)</tt>, and
+    # <tt>forget(id, provider:, account:)</tt>. The Rails integration sets
+    # one for files kept in Active Storage.
+    attr_accessor :provider_file_store # :nodoc:
+
     def provider_file_id # :nodoc:
       @source.id if provider_file?
     end
@@ -144,10 +180,14 @@ module RubyLLM
       when :text
         "<file name='#{filename}' mime_type='#{mime_type}'>#{content}</file>"
       else
-        "data:#{mime_type};base64,#{encoded}"
+        data_uri
       end
     end
 
+    def url_or_data_uri # :nodoc:
+      url? ? @source.to_s : data_uri
+    end
+
     # Returns the attachment category as a Symbol: +:image+, +:video+,
     # +:audio+, +:pdf+, +:text+, +:document+, or +:unknown+.
     def type
@@ -211,7 +251,7 @@ module RubyLLM
     end
 
     def to_h # :nodoc:
-      { type: type, source: @source }
+      { type: type, source: @source, filename: filename, resolution: resolution }.compact
     end
 
     def byte_size # :nodoc:
@@ -220,6 +260,10 @@ module RubyLLM
 
     private
 
+    def data_uri
+      "data:#{mime_type};base64,#{encoded}"
+    end
+
     def file_byte_size
       return @source.byte_size if provider_file?
       return File.size(@source) if path?
@@ -362,7 +406,7 @@ module RubyLLM
     end
 
     def inspect_attributes # :nodoc:
-      { filename: filename, mime_type: mime_type, source: @source }
+      { filename: filename, mime_type: mime_type, resolution: resolution, source: @source }
     end
   end
 end

data/lib/ruby_llm/batch.rb

@@ -237,6 +237,7 @@ module RubyLLM
     #     puts message.content
     #   end
     #
+    # Raises Error when the provider returns malformed result indices.
     def messages
       return @messages if @messages
 
@@ -287,6 +288,7 @@ module RubyLLM
 
     def collect_results
       results = @provider.batch_results(id, batch_protocol: @batch_protocol)
+      validate_result_indices(results)
       slots = Array.new(result_slot_count(results))
 
       results.each do |index, result, failure_status|
@@ -299,8 +301,22 @@ module RubyLLM
       slots
     end
 
+    def validate_result_indices(results)
+      count = known_request_count
+      indices = results.map(&:first)
+      invalid = indices.find { |index| index.negative? || (count && index >= count) }
+      raise Error, "Invalid batch result index: #{invalid}" if invalid
+
+      duplicate, = indices.tally.find { |_, occurrences| occurrences > 1 }
+      raise Error, "Duplicate batch result index: #{duplicate}" if duplicate
+    end
+
+    def known_request_count
+      chats&.size || requests&.size || @request_count
+    end
+
     def result_slot_count(results)
-      chats&.size || requests&.size || @request_count || ((results.map(&:first).max || -1) + 1)
+      known_request_count || ((results.map(&:first).max || -1) + 1)
     end
 
     def fill_missing_statuses(size)
@@ -364,10 +380,17 @@ module RubyLLM
         status: :succeeded,
         tokens: result.tokens,
         cost: @provider.batch_cost(result.tokens, model:, category:),
-        message: result.is_a?(Message) ? result : nil
+        message: result.is_a?(Message) ? result : nil,
+        owner: Accounting::Usage.owner
       )
       result.ruby_llm_usage_entries = [entry]
-      Accounting::Usage.instrument(entry, config: @provider.config) if instrument
+      return unless instrument
+
+      if operation == :chat
+        Accounting::Usage.instrument(entry, config: @provider.config)
+      else
+        Accounting::Usage.report(entry, config: @provider.config)
+      end
     end
 
     # A plain answer is the chat's last message once it arrives. A tool-call

data/lib/ruby_llm/chat/tool_concurrency.rb

@@ -18,13 +18,16 @@ module RubyLLM
       end
 
       def run_with_threads(tool_calls, on_result:, &execute)
-        executor = rails_executor
+        caller_context = execution_context
         workflow_context = Support::Instrumentation.current_workflow
+        instrumentation_context = Support::Instrumentation.capture_context
         queue = Queue.new
         threads = tool_calls.each_value.with_index.map do |tool_call, index|
           thread = Thread.new do
             Support::Instrumentation.with_workflow(workflow_context) do
-              queue << capture_result(index, tool_call, executor, execute)
+              Support::Instrumentation.with_context(instrumentation_context) do
+                queue << capture_result(index, tool_call, caller_context, execute)
+              end
             end
           end
           thread.report_on_exception = false
@@ -48,22 +51,29 @@ module RubyLLM
           raise LoadError, "The 'async' gem version 2.0 or newer is required for concurrent tool execution with fibers."
         end
 
-        executor = rails_executor
+        caller_context = execution_context
         workflow_context = Support::Instrumentation.current_workflow
-        Async do |task|
-          queue = Async::Queue.new
-          tasks = tool_calls.each_value.with_index.map do |tool_call, index|
-            task.async do
-              Support::Instrumentation.with_workflow(workflow_context) do
-                queue << capture_result(index, tool_call, executor, execute)
+        instrumentation_context = Support::Instrumentation.capture_context
+        # Inside a reactor, Sync runs the block in the calling fiber, so
+        # results persist with the caller's execution state and connection.
+        Sync do |task|
+          isolated(caller_context) do
+            queue = Async::Queue.new
+            tasks = tool_calls.each_value.with_index.map do |tool_call, index|
+              task.async do
+                Support::Instrumentation.with_workflow(workflow_context) do
+                  Support::Instrumentation.with_context(instrumentation_context) do
+                    queue << capture_result(index, tool_call, caller_context, execute)
+                  end
+                end
               end
             end
-          end
 
-          collect_results(queue, tasks.size, on_result:)
-        ensure
-          tasks&.each(&:wait)
-        end.wait
+            collect_results(queue, tasks.size, on_result:)
+          ensure
+            tasks&.each(&:wait)
+          end
+        end
       end
 
       def collect_results(queue, count, on_result:)
@@ -85,27 +95,41 @@ module RubyLLM
         results
       end
 
-      def capture_result(index, tool_call, rails_executor, execute)
-        tool_call, value = run_tool_call(tool_call, rails_executor, execute)
+      def capture_result(index, tool_call, caller_context, execute)
+        value = isolated(caller_context) { execute.call(tool_call) }
         Result.new(index:, tool_call:, value:)
       rescue Exception => e # rubocop:disable Lint/RescueException
         Result.new(index:, tool_call:, error: e)
       end
 
-      def run_tool_call(tool_call, rails_executor, execute)
-        if rails_executor
-          rails_executor.wrap { [tool_call, execute.call(tool_call)] }
-        else
-          [tool_call, execute.call(tool_call)]
+      # Rails gives a thread, and a fiber under fiber isolation, execution
+      # state of its own: the block runs as its own unit of work, so its
+      # connections return to the pool. A fiber sharing the caller's state
+      # must not start one, whose completion resets the caller's Current
+      # attributes. Unlike wrap, run! reports no errors: they reach the
+      # caller, whose own executor reports what nothing rescues.
+      def isolated(caller_context)
+        executor = rails_executor
+        return yield unless executor && !execution_context.equal?(caller_context)
+
+        execution = executor.run!
+        begin
+          yield
+        ensure
+          execution.complete!
         end
       end
 
+      def execution_context
+        defined?(ActiveSupport::IsolatedExecutionState) ? ActiveSupport::IsolatedExecutionState.context : Thread.current
+      end
+
       def rails_executor
         defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.executor
       end
 
-      private_class_method :run_with_threads, :run_with_fibers, :collect_results, :capture_result, :run_tool_call,
-                           :rails_executor
+      private_class_method :run_with_threads, :run_with_fibers, :collect_results, :capture_result, :isolated,
+                           :execution_context, :rails_executor
     end
   end
 end

data/lib/ruby_llm/chat/tool_search.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Chat
+    # Deferred tool registration and the tool set rendered for the request.
+    module ToolSearch # :nodoc:
+      private
+
+      def deferred_tool_names
+        names = @tool_deferrals.filter_map { |name, deferred| name if deferred }
+        mcp.each do |server|
+          explicit = @mcp_deferrals[server.name.to_sym]
+          server.tools.each do |tool|
+            names << tool.name.to_sym if explicit.nil? ? server.defers?(tool) : explicit
+          end
+        end
+        names
+      end
+
+      def request_tools
+        deferred = deferred_tool_names
+        tools.to_h { |name, tool| [name, deferred.include?(name) ? Tool::Deferred.new(tool) : tool] }
+      end
+    end
+  end
+end