ruby_llm 1.12.0 → 1.13.0

data/lib/ruby_llm/providers/gemini/tools.rb

@@ -205,6 +205,25 @@ module RubyLLM
           else 'STRING'
           end
         end
+
+        def build_tool_config(tool_choice)
+          {
+            functionCallingConfig: {
+              mode: forced_tool_choice?(tool_choice) ? 'any' : tool_choice
+            }.tap do |config|
+              # Use allowedFunctionNames to simulate specific tool choice
+              config[:allowedFunctionNames] = [tool_choice] if specific_tool_choice?(tool_choice)
+            end
+          }
+        end
+
+        def forced_tool_choice?(tool_choice)
+          tool_choice == :required || specific_tool_choice?(tool_choice)
+        end
+
+        def specific_tool_choice?(tool_choice)
+          !%i[auto none required].include?(tool_choice)
+        end
       end
     end
   end

data/lib/ruby_llm/providers/gpustack/capabilities.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class GPUStack
+      # Determines capabilities for GPUStack models
+      module Capabilities
+        module_function
+
+        def supports_tool_choice?(_model_id)
+          false
+        end
+
+        def supports_tool_parallel_control?(_model_id)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/gpustack.rb

@@ -28,6 +28,10 @@ module RubyLLM
         def configuration_requirements
           %i[gpustack_api_base]
         end
+
+        def capabilities
+          GPUStack::Capabilities
+        end
       end
     end
   end

data/lib/ruby_llm/providers/mistral/capabilities.rb

@@ -15,6 +15,14 @@ module RubyLLM
           !model_id.match?(/embed|moderation|ocr|voxtral|transcriptions|mistral-(tiny|small)-(2312|2402)/)
         end
 
+        def supports_tool_choice?(_model_id)
+          true
+        end
+
+        def supports_tool_parallel_control?(_model_id)
+          true
+        end
+
         def supports_vision?(model_id)
           model_id.match?(/pixtral|mistral-small-(2503|2506)|mistral-medium/)
         end

data/lib/ruby_llm/providers/mistral/chat.rb

@@ -23,7 +23,8 @@ module RubyLLM
         end
 
         # rubocop:disable Metrics/ParameterLists
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, thinking: nil)
+        def render_payload(messages, tools:, temperature:, model:, stream: false,
+                           schema: nil, thinking: nil, tool_prefs: nil)
           payload = super
           payload.delete(:stream_options)
           payload.delete(:reasoning_effort)

data/lib/ruby_llm/providers/ollama/capabilities.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class Ollama
+      # Determines capabilities for Ollama models
+      module Capabilities
+        module_function
+
+        def supports_tool_choice?(_model_id)
+          false
+        end
+
+        def supports_tool_parallel_control?(_model_id)
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/ollama.rb

@@ -13,7 +13,9 @@ module RubyLLM
       end
 
       def headers
-        {}
+        return {} unless @config.ollama_api_key
+
+        { 'Authorization' => "Bearer #{@config.ollama_api_key}" }
       end
 
       class << self
@@ -24,6 +26,10 @@ module RubyLLM
         def local?
           true
         end
+
+        def capabilities
+          Ollama::Capabilities
+        end
       end
     end
   end

data/lib/ruby_llm/providers/openai/capabilities.rb

@@ -97,6 +97,14 @@ module RubyLLM
           end
         end
 
+        def supports_tool_choice?(_model_id)
+          true
+        end
+
+        def supports_tool_parallel_control?(_model_id)
+          true
+        end
+
         def supports_structured_output?(model_id)
           case model_family(model_id)
           when 'gpt5', 'gpt5_mini', 'gpt5_nano', 'gpt41', 'gpt41_mini', 'gpt41_nano', 'chatgpt4o', 'gpt4o',
@@ -225,10 +233,10 @@ module RubyLLM
 
         def self.normalize_temperature(temperature, model_id)
           if model_id.match?(/^(o\d|gpt-5)/) && !temperature.nil? && !temperature_close_to_one?(temperature)
-            RubyLLM.logger.debug "Model #{model_id} requires temperature=1.0, setting that instead."
+            RubyLLM.logger.debug { "Model #{model_id} requires temperature=1.0, setting that instead." }
             1.0
           elsif model_id.match?(/-search/)
-            RubyLLM.logger.debug "Model #{model_id} does not accept temperature parameter, removing"
+            RubyLLM.logger.debug { "Model #{model_id} does not accept temperature parameter, removing" }
             nil
           else
             temperature

data/lib/ruby_llm/providers/openai/chat.rb

@@ -11,7 +11,10 @@ module RubyLLM
 
         module_function
 
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable Metrics/ParameterLists,Metrics/PerceivedComplexity
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil,
+                           thinking: nil, tool_prefs: nil)
+          tool_prefs ||= {}
           payload = {
             model: model.id,
             messages: format_messages(messages),
@@ -19,16 +22,22 @@ module RubyLLM
           }
 
           payload[:temperature] = temperature unless temperature.nil?
-          payload[:tools] = tools.map { |_, tool| tool_for(tool) } if tools.any?
+          if tools.any?
+            payload[:tools] = tools.map { |_, tool| tool_for(tool) }
+            payload[:tool_choice] = build_tool_choice(tool_prefs[:choice]) unless tool_prefs[:choice].nil?
+            payload[:parallel_tool_calls] = tool_prefs[:calls] == :many unless tool_prefs[:calls].nil?
+          end
 
           if schema
-            strict = schema[:strict] != false
+            schema_name = schema[:name]
+            schema_def = schema[:schema]
+            strict = schema[:strict]
 
             payload[:response_format] = {
               type: 'json_schema',
               json_schema: {
-                name: 'response',
-                schema: schema,
+                name: schema_name,
+                schema: schema_def,
                 strict: strict
               }
             }
@@ -40,6 +49,7 @@ module RubyLLM
           payload[:stream_options] = { include_usage: true } if stream
           payload
         end
+        # rubocop:enable Metrics/ParameterLists,Metrics/PerceivedComplexity
 
         def parse_completion_response(response)
           data = response.body

data/lib/ruby_llm/providers/openai/media.rb

@@ -8,7 +8,10 @@ module RubyLLM
         module_function
 
         def format_content(content) # rubocop:disable Metrics/PerceivedComplexity
-          return content.value if content.is_a?(RubyLLM::Content::Raw)
+          if content.is_a?(RubyLLM::Content::Raw)
+            value = content.value
+            return value.is_a?(Hash) ? value.to_json : value
+          end
           return content.to_json if content.is_a?(Hash) || content.is_a?(Array)
           return content unless content.is_a?(Content)
 

data/lib/ruby_llm/providers/openai/temperature.rb

@@ -9,10 +9,10 @@ module RubyLLM
 
         def normalize(temperature, model_id)
           if model_id.match?(/^(o\d|gpt-5)/) && !temperature.nil? && !temperature_close_to_one?(temperature)
-            RubyLLM.logger.debug "Model #{model_id} requires temperature=1.0, setting that instead."
+            RubyLLM.logger.debug { "Model #{model_id} requires temperature=1.0, setting that instead." }
             1.0
           elsif model_id.include?('-search')
-            RubyLLM.logger.debug "Model #{model_id} does not accept temperature parameter, removing"
+            RubyLLM.logger.debug { "Model #{model_id} does not accept temperature parameter, removing" }
             nil
           else
             temperature

data/lib/ruby_llm/providers/openai/tools.rb

@@ -53,7 +53,7 @@ module RubyLLM
           return nil unless tool_calls&.any?
 
           tool_calls.map do |_, tc|
-            {
+            call = {
               id: tc.id,
               type: 'function',
               function: {
@@ -61,6 +61,12 @@ module RubyLLM
                 arguments: JSON.generate(tc.arguments)
               }
             }
+            if tc.thought_signature
+              call[:extra_content] = {
+                google: { thought_signature: tc.thought_signature }
+              }
+            end
+            call
           end
         end
 
@@ -87,11 +93,30 @@ module RubyLLM
                              parse_tool_call_arguments(tc)
                            else
                              tc.dig('function', 'arguments')
-                           end
+                           end,
+                thought_signature: extract_tool_call_thought_signature(tc)
               )
             ]
           end
         end
+
+        def build_tool_choice(tool_choice)
+          case tool_choice
+          when :auto, :none, :required
+            tool_choice
+          else
+            {
+              type: 'function',
+              function: {
+                name: tool_choice
+              }
+            }
+          end
+        end
+
+        def extract_tool_call_thought_signature(tool_call)
+          tool_call.dig('extra_content', 'google', 'thought_signature')
+        end
       end
     end
   end

data/lib/ruby_llm/providers/openrouter/chat.rb

@@ -7,7 +7,10 @@ module RubyLLM
       module Chat
         module_function
 
-        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists
+        # rubocop:disable Metrics/ParameterLists,Metrics/PerceivedComplexity
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil,
+                           thinking: nil, tool_prefs: nil)
+          tool_prefs ||= {}
           payload = {
             model: model.id,
             messages: format_messages(messages),
@@ -15,15 +18,25 @@ module RubyLLM
           }
 
           payload[:temperature] = temperature unless temperature.nil?
-          payload[:tools] = tools.map { |_, tool| OpenAI::Tools.tool_for(tool) } if tools.any?
+          if tools.any?
+            payload[:tools] = tools.map { |_, tool| OpenAI::Tools.tool_for(tool) }
+            payload[:tool_choice] = OpenAI::Tools.build_tool_choice(tool_prefs[:choice]) unless tool_prefs[:choice].nil?
+            payload[:parallel_tool_calls] = tool_prefs[:calls] == :many unless tool_prefs[:calls].nil?
+          end
 
           if schema
-            strict = schema[:strict] != false
+            schema_name = schema[:name]
+            schema_def = RubyLLM::Utils.deep_dup(schema[:schema])
+            if schema_def.is_a?(Hash)
+              schema_def.delete(:strict)
+              schema_def.delete('strict')
+            end
+            strict = schema[:strict]
             payload[:response_format] = {
               type: 'json_schema',
               json_schema: {
-                name: 'response',
-                schema: schema,
+                name: schema_name,
+                schema: schema_def,
                 strict: strict
               }
             }
@@ -35,6 +48,7 @@ module RubyLLM
           payload[:stream_options] = { include_usage: true } if stream
           payload
         end
+        # rubocop:enable Metrics/ParameterLists,Metrics/PerceivedComplexity
 
         def parse_completion_response(response)
           data = response.body

data/lib/ruby_llm/providers/openrouter/images.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class OpenRouter
+      # Image generation methods for the OpenRouter API integration.
+      # OpenRouter uses the chat completions endpoint for image generation
+      # instead of a dedicated images endpoint.
+      module Images
+        module_function
+
+        def images_url
+          'chat/completions'
+        end
+
+        def render_image_payload(prompt, model:, size:)
+          RubyLLM.logger.debug "Ignoring size #{size}. OpenRouter image generation does not support size parameter."
+          {
+            model: model,
+            messages: [
+              {
+                role: 'user',
+                content: prompt
+              }
+            ],
+            modalities: %w[image text]
+          }
+        end
+
+        def parse_image_response(response, model:)
+          data = response.body
+          message = data.dig('choices', 0, 'message')
+
+          unless message&.key?('images') && message['images']&.any?
+            raise Error.new(nil, 'Unexpected response format from OpenRouter image generation API')
+          end
+
+          image_data = message['images'].first
+          image_url = image_data.dig('image_url', 'url') || image_data['url']
+
+          raise Error.new(nil, 'No image URL found in OpenRouter response') unless image_url
+
+          build_image_from_url(image_url, model)
+        end
+
+        def build_image_from_url(image_url, model)
+          if image_url.start_with?('data:')
+            # Parse data URL format: data:image/png;base64,<data>
+            match = image_url.match(/^data:([^;]+);base64,(.+)$/)
+            raise Error.new(nil, 'Invalid data URL format from OpenRouter') unless match
+
+            Image.new(
+              data: match[2],
+              mime_type: match[1],
+              model_id: model
+            )
+          else
+            # Regular URL
+            Image.new(
+              url: image_url,
+              mime_type: 'image/png',
+              model_id: model
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/openrouter.rb

@@ -7,9 +7,10 @@ module RubyLLM
       include OpenRouter::Chat
       include OpenRouter::Models
       include OpenRouter::Streaming
+      include OpenRouter::Images
 
       def api_base
-        'https://openrouter.ai/api/v1'
+        @config.openrouter_api_base || 'https://openrouter.ai/api/v1'
       end
 
       def headers
@@ -18,6 +19,35 @@ module RubyLLM
         }
       end
 
+      def parse_error(response)
+        return if response.body.empty?
+
+        body = try_parse_json(response.body)
+        case body
+        when Hash
+          parse_error_part_message body
+        when Array
+          body.map do |part|
+            parse_error_part_message part
+          end.join('. ')
+        else
+          body
+        end
+      end
+
+      private
+
+      def parse_error_part_message(part)
+        message = part.dig('error', 'message')
+        raw = try_parse_json(part.dig('error', 'metadata', 'raw'))
+        return message unless raw.is_a?(Hash)
+
+        raw_message = raw.dig('error', 'message')
+        return [message, raw_message].compact.join(' - ') if raw_message
+
+        message
+      end
+
       class << self
         def configuration_requirements
           %i[openrouter_api_key]

data/lib/ruby_llm/providers/vertexai/models.rb

@@ -56,7 +56,7 @@ module RubyLLM
 
           all_models
         rescue StandardError => e
-          RubyLLM.logger.debug "Error fetching Vertex AI models: #{e.message}"
+          RubyLLM.logger.debug { "Error fetching Vertex AI models: #{e.message}" }
           build_known_models
         end
 

data/lib/ruby_llm/providers/vertexai.rb

@@ -10,6 +10,11 @@ module RubyLLM
       include VertexAI::Models
       include VertexAI::Transcription
 
+      SCOPES = [
+        'https://www.googleapis.com/auth/cloud-platform',
+        'https://www.googleapis.com/auth/generative-language.retriever'
+      ].freeze
+
       def initialize(config)
         super
         @authorizer = nil
@@ -44,12 +49,15 @@ module RubyLLM
 
       def initialize_authorizer
         require 'googleauth'
-        @authorizer = ::Google::Auth.get_application_default(
-          scope: [
-            'https://www.googleapis.com/auth/cloud-platform',
-            'https://www.googleapis.com/auth/generative-language.retriever'
-          ]
-        )
+        @authorizer =
+          if @config.vertexai_service_account_key
+            ::Google::Auth::ServiceAccountCredentials.make_creds(
+              json_key_io: StringIO.new(@config.vertexai_service_account_key),
+              scope: SCOPES
+            )
+          else
+            ::Google::Auth.get_application_default(SCOPES)
+          end
       rescue LoadError
         raise Error,
               'The googleauth gem ~> 1.15 is required for Vertex AI. Please add it to your Gemfile: gem "googleauth"'

data/lib/ruby_llm/stream_accumulator.rb

@@ -21,13 +21,13 @@ module RubyLLM
     end
 
     def add(chunk)
-      RubyLLM.logger.debug chunk.inspect if RubyLLM.config.log_stream_debug
+      RubyLLM.logger.debug { chunk.inspect } if RubyLLM.config.log_stream_debug
       @model_id ||= chunk.model_id
 
       handle_chunk_content(chunk)
       append_thinking_from_chunk(chunk)
       count_tokens chunk
-      RubyLLM.logger.debug inspect if RubyLLM.config.log_stream_debug
+      RubyLLM.logger.debug { inspect } if RubyLLM.config.log_stream_debug
     end
 
     def to_message(response)
@@ -73,11 +73,14 @@ module RubyLLM
     end
 
     def accumulate_tool_calls(new_tool_calls) # rubocop:disable Metrics/PerceivedComplexity
-      RubyLLM.logger.debug "Accumulating tool calls: #{new_tool_calls}" if RubyLLM.config.log_stream_debug
+      RubyLLM.logger.debug { "Accumulating tool calls: #{new_tool_calls}" } if RubyLLM.config.log_stream_debug
       new_tool_calls.each_value do |tool_call|
         if tool_call.id
           tool_call_id = tool_call.id.empty? ? SecureRandom.uuid : tool_call.id
-          tool_call_arguments = tool_call.arguments.empty? ? +'' : tool_call.arguments
+          tool_call_arguments = tool_call.arguments
+          if tool_call_arguments.nil? || (tool_call_arguments.respond_to?(:empty?) && tool_call_arguments.empty?)
+            tool_call_arguments = +''
+          end
           @tool_calls[tool_call.id] = ToolCall.new(
             id: tool_call_id,
             name: tool_call.name,
@@ -88,7 +91,9 @@ module RubyLLM
         else
           existing = @tool_calls[@latest_tool_call_id]
           if existing
-            existing.arguments << tool_call.arguments
+            fragment = tool_call.arguments
+            fragment = '' if fragment.nil?
+            existing.arguments << fragment
             if tool_call.thought_signature && existing.thought_signature.nil?
               existing.thought_signature = tool_call.thought_signature
             end

data/lib/ruby_llm/streaming.rb

@@ -24,7 +24,7 @@ module RubyLLM
       end
 
       message = accumulator.to_message(response)
-      RubyLLM.logger.debug "Stream completed: #{message.content}"
+      RubyLLM.logger.debug { "Stream completed: #{message.content}" }
       message
     end
 
@@ -52,7 +52,7 @@ module RubyLLM
     end
 
     def process_stream_chunk(chunk, parser, env, &)
-      RubyLLM.logger.debug "Received chunk: #{chunk}" if RubyLLM.config.log_stream_debug
+      RubyLLM.logger.debug { "Received chunk: #{chunk}" } if RubyLLM.config.log_stream_debug
 
       if error_chunk?(chunk)
         handle_error_chunk(chunk, env)
@@ -85,7 +85,7 @@ module RubyLLM
       error_data = JSON.parse(buffer)
       handle_parsed_error(error_data, env)
     rescue JSON::ParserError
-      RubyLLM.logger.debug "Accumulating error chunk: #{chunk}"
+      RubyLLM.logger.debug { "Accumulating error chunk: #{chunk}" }
     end
 
     def handle_sse(chunk, parser, env, &block)
@@ -105,7 +105,7 @@ module RubyLLM
 
       handle_parsed_error(parsed, env)
     rescue JSON::ParserError => e
-      RubyLLM.logger.debug "Failed to parse data chunk: #{e.message}"
+      RubyLLM.logger.debug { "Failed to parse data chunk: #{e.message}" }
     end
 
     def handle_error_event(data, env)
@@ -116,7 +116,7 @@ module RubyLLM
       error_data = JSON.parse(data)
       [500, error_data['message'] || 'Unknown streaming error']
     rescue JSON::ParserError => e
-      RubyLLM.logger.debug "Failed to parse streaming error: #{e.message}"
+      RubyLLM.logger.debug { "Failed to parse streaming error: #{e.message}" }
       [500, "Failed to parse error: #{data}"]
     end
 
@@ -130,7 +130,7 @@ module RubyLLM
       parsed_data = JSON.parse(data)
       handle_parsed_error(parsed_data, env)
     rescue JSON::ParserError => e
-      RubyLLM.logger.debug "#{error_message}: #{e.message}"
+      RubyLLM.logger.debug { "#{error_message}: #{e.message}" }
     end
 
     def build_stream_error_response(parsed_data, env, status)

data/lib/ruby_llm/tool.rb

@@ -99,9 +99,13 @@ module RubyLLM
     end
 
     def call(args)
-      RubyLLM.logger.debug "Tool #{name} called with: #{args.inspect}"
-      result = execute(**args.transform_keys(&:to_sym))
-      RubyLLM.logger.debug "Tool #{name} returned: #{result.inspect}"
+      normalized_args = normalize_args(args)
+      validation_error = validate_keyword_arguments(normalized_args)
+      return { error: "Invalid tool arguments: #{validation_error}" } if validation_error
+
+      RubyLLM.logger.debug { "Tool #{name} called with: #{normalized_args.inspect}" }
+      result = execute(**normalized_args)
+      RubyLLM.logger.debug { "Tool #{name} returned: #{result.inspect}" }
       result
     end
 
@@ -115,6 +119,47 @@ module RubyLLM
       Halt.new(message)
     end
 
+    def normalize_args(args)
+      return {} if args.nil?
+      return args.transform_keys(&:to_sym) if args.respond_to?(:transform_keys)
+
+      {}
+    end
+
+    def validate_keyword_arguments(arguments)
+      required_keywords, optional_keywords, accepts_extra_keywords = execute_keyword_signature
+
+      return nil if required_keywords.empty? && optional_keywords.empty?
+
+      argument_keys = arguments.keys
+      missing_keyword = first_missing_keyword(required_keywords, argument_keys)
+      return "missing keyword: #{missing_keyword}" if missing_keyword
+      return nil if accepts_extra_keywords
+
+      allowed_keywords = required_keywords + optional_keywords
+      unknown_keyword = first_unknown_keyword(argument_keys, allowed_keywords)
+      return "unknown keyword: #{unknown_keyword}" if unknown_keyword
+
+      nil
+    end
+
+    def execute_keyword_signature
+      keyword_signature = method(:execute).parameters
+      required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq }
+      optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key }
+      accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest }
+
+      [required_keywords, optional_keywords, accepts_extra_keywords]
+    end
+
+    def first_missing_keyword(required_keywords, argument_keys)
+      (required_keywords - argument_keys).first
+    end
+
+    def first_unknown_keyword(argument_keys, allowed_keywords)
+      (argument_keys - allowed_keywords).first
+    end
+
     # Wraps schema handling for tool parameters, supporting JSON Schema hashes,
     # RubyLLM::Schema instances/classes, and DSL blocks.
     class SchemaDefinition

data/lib/ruby_llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  VERSION = '1.12.0'
+  VERSION = '1.13.0'
 end