ruby_llm 1.12.0 → 1.14.1

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,7 +19,40 @@ 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_options
+          %i[openrouter_api_key openrouter_api_base]
+        end
+
         def configuration_requirements
           %i[openrouter_api_key]
         end

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

@@ -3,63 +3,55 @@
 module RubyLLM
   module Providers
     class Perplexity
-      # Determines capabilities and pricing for Perplexity models
+      # Provider-level capability checks and narrow registry fallbacks.
       module Capabilities
         module_function
 
-        def context_window_for(model_id)
-          case model_id
-          when /sonar-pro/ then 200_000
-          else 128_000
-          end
-        end
+        PRICES = {
+          sonar: { input: 1.0, output: 1.0 },
+          sonar_pro: { input: 3.0, output: 15.0 },
+          sonar_reasoning: { input: 1.0, output: 5.0 },
+          sonar_reasoning_pro: { input: 2.0, output: 8.0 },
+          sonar_deep_research: {
+            input: 2.0,
+            output: 8.0,
+            reasoning_output: 3.0
+          }
+        }.freeze
 
-        def max_tokens_for(model_id)
-          case model_id
-          when /sonar-(?:pro|reasoning-pro)/ then 8_192
-          else 4_096
-          end
+        def supports_tool_choice?(_model_id)
+          false
         end
 
-        def input_price_for(model_id)
-          PRICES.dig(model_family(model_id), :input) || 1.0
+        def supports_tool_parallel_control?(_model_id)
+          false
         end
 
-        def output_price_for(model_id)
-          PRICES.dig(model_family(model_id), :output) || 1.0
+        def context_window_for(model_id)
+          model_id.match?(/sonar-pro/) ? 200_000 : 128_000
         end
 
-        def supports_vision?(model_id)
-          case model_id
-          when /sonar-reasoning-pro/, /sonar-reasoning/, /sonar-pro/, /sonar/ then true
-          else false
-          end
+        def max_tokens_for(model_id)
+          model_id.match?(/sonar-(?:pro|reasoning-pro)/) ? 8_192 : 4_096
         end
 
-        def supports_functions?(_model_id)
-          false
+        def critical_capabilities_for(model_id)
+          capabilities = []
+          capabilities << 'vision' if model_id.match?(/sonar(?:-pro|-reasoning(?:-pro)?)?$/)
+          capabilities << 'reasoning' if model_id.match?(/reasoning|deep-research/)
+          capabilities
         end
 
-        def supports_json_mode?(_model_id)
-          true
-        end
+        def pricing_for(model_id)
+          prices = PRICES.fetch(model_family(model_id), { input: 1.0, output: 1.0 })
 
-        def format_display_name(model_id)
-          case model_id
-          when 'sonar' then 'Sonar'
-          when 'sonar-pro' then 'Sonar Pro'
-          when 'sonar-reasoning' then 'Sonar Reasoning'
-          when 'sonar-reasoning-pro' then 'Sonar Reasoning Pro'
-          when 'sonar-deep-research' then 'Sonar Deep Research'
-          else
-            model_id.split('-')
-                    .map(&:capitalize)
-                    .join(' ')
-          end
-        end
+          standard = {
+            input_per_million: prices[:input],
+            output_per_million: prices[:output]
+          }
+          standard[:reasoning_output_per_million] = prices[:reasoning_output] if prices[:reasoning_output]
 
-        def model_type(_model_id)
-          'chat'
+          { text_tokens: { standard: standard } }
         end
 
         def model_family(model_id)
@@ -73,64 +65,7 @@ module RubyLLM
           end
         end
 
-        def modalities_for(_model_id)
-          {
-            input: ['text'],
-            output: ['text']
-          }
-        end
-
-        def capabilities_for(model_id)
-          capabilities = %w[streaming json_mode]
-          capabilities << 'vision' if supports_vision?(model_id)
-          capabilities
-        end
-
-        def pricing_for(model_id)
-          family = model_family(model_id)
-          prices = PRICES.fetch(family, { input: 1.0, output: 1.0 })
-
-          standard_pricing = {
-            input_per_million: prices[:input],
-            output_per_million: prices[:output]
-          }
-
-          standard_pricing[:citation_per_million] = prices[:citation] if prices[:citation]
-          standard_pricing[:reasoning_per_million] = prices[:reasoning] if prices[:reasoning]
-          standard_pricing[:search_per_thousand] = prices[:search_queries] if prices[:search_queries]
-
-          {
-            text_tokens: {
-              standard: standard_pricing
-            }
-          }
-        end
-
-        PRICES = {
-          sonar: {
-            input: 1.0,
-            output: 1.0
-          },
-          sonar_pro: {
-            input: 3.0,
-            output: 15.0
-          },
-          sonar_reasoning: {
-            input: 1.0,
-            output: 5.0
-          },
-          sonar_reasoning_pro: {
-            input: 2.0,
-            output: 8.0
-          },
-          sonar_deep_research: {
-            input: 2.0,
-            output: 8.0,
-            citation: 2.0,
-            reasoning: 3.0,
-            search_queries: 5.0
-          }
-        }.freeze
+        module_function :context_window_for, :max_tokens_for, :critical_capabilities_for, :pricing_for, :model_family
       end
     end
   end

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

@@ -5,33 +5,31 @@ module RubyLLM
     class Perplexity
       # Models methods of the Perplexity API integration
       module Models
+        MODEL_IDS = %w[
+          sonar
+          sonar-pro
+          sonar-reasoning
+          sonar-reasoning-pro
+          sonar-deep-research
+        ].freeze
+
         def list_models(**)
           slug = 'perplexity'
-          capabilities = Perplexity::Capabilities
-          parse_list_models_response(nil, slug, capabilities)
+          parse_list_models_response(nil, slug, Perplexity::Capabilities)
         end
 
         def parse_list_models_response(_response, slug, capabilities)
-          [
-            create_model_info('sonar', slug, capabilities),
-            create_model_info('sonar-pro', slug, capabilities),
-            create_model_info('sonar-reasoning', slug, capabilities),
-            create_model_info('sonar-reasoning-pro', slug, capabilities),
-            create_model_info('sonar-deep-research', slug, capabilities)
-          ]
+          MODEL_IDS.map { |id| create_model_info(id, slug, capabilities) }
         end
 
         def create_model_info(id, slug, capabilities)
           Model::Info.new(
             id: id,
-            name: capabilities.format_display_name(id),
+            name: id,
             provider: slug,
-            family: capabilities.model_family(id).to_s,
-            created_at: Time.now,
             context_window: capabilities.context_window_for(id),
             max_output_tokens: capabilities.max_tokens_for(id),
-            modalities: capabilities.modalities_for(id),
-            capabilities: capabilities.capabilities_for(id),
+            capabilities: capabilities.critical_capabilities_for(id),
             pricing: capabilities.pricing_for(id),
             metadata: {}
           )

data/lib/ruby_llm/providers/perplexity.rb

@@ -23,6 +23,10 @@ module RubyLLM
           Perplexity::Capabilities
         end
 
+        def configuration_options
+          %i[perplexity_api_key]
+        end
+
         def configuration_requirements
           %i[perplexity_api_key]
         end

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
@@ -35,6 +40,10 @@ module RubyLLM
       end
 
       class << self
+        def configuration_options
+          %i[vertexai_project_id vertexai_location vertexai_service_account_key]
+        end
+
         def configuration_requirements
           %i[vertexai_project_id vertexai_location]
         end
@@ -44,12 +53,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/providers/xai.rb

@@ -19,6 +19,10 @@ module RubyLLM
       end
 
       class << self
+        def configuration_options
+          %i[xai_api_key]
+        end
+
         def configuration_requirements
           %i[xai_api_key]
         end

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,13 +24,13 @@ module RubyLLM
       end
 
       message = accumulator.to_message(response)
-      RubyLLM.logger.debug "Stream completed: #{message.content}"
+      RubyLLM.logger.debug { "Stream completed: #{message.content}" }
       message
     end
 
     def handle_stream(&block)
       build_on_data_handler do |data|
-        block.call(build_chunk(data)) if data
+        block.call(build_chunk(data)) if data.is_a?(Hash)
       end
     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.14.1'
 end