ruby_llm 1.12.0 → 1.13.0

data/lib/ruby_llm/chat.rb

@@ -5,7 +5,7 @@ module RubyLLM
   class Chat
     include Enumerable
 
-    attr_reader :model, :messages, :tools, :params, :headers, :schema
+    attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema
 
     def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
       if assume_model_exists && !provider
@@ -19,6 +19,7 @@ module RubyLLM
       @temperature = nil
       @messages = []
       @tools = {}
+      @tool_prefs = { choice: nil, calls: nil }
       @params = {}
       @headers = {}
       @schema = nil
@@ -50,15 +51,19 @@ module RubyLLM
       self
     end
 
-    def with_tool(tool)
-      tool_instance = tool.is_a?(Class) ? tool.new : tool
-      @tools[tool_instance.name.to_sym] = tool_instance
+    def with_tool(tool, choice: nil, calls: nil)
+      unless tool.nil?
+        tool_instance = tool.is_a?(Class) ? tool.new : tool
+        @tools[tool_instance.name.to_sym] = tool_instance
+      end
+      update_tool_options(choice:, calls:)
       self
     end
 
-    def with_tools(*tools, replace: false)
+    def with_tools(*tools, replace: false, choice: nil, calls: nil)
       @tools.clear if replace
       tools.compact.each { |tool| with_tool tool }
+      update_tool_options(choice:, calls:)
       self
     end
 
@@ -100,12 +105,9 @@ module RubyLLM
     def with_schema(schema)
       schema_instance = schema.is_a?(Class) ? schema.new : schema
 
-      # Accept both RubyLLM::Schema instances and plain JSON schemas
-      @schema = if schema_instance.respond_to?(:to_json_schema)
-                  schema_instance.to_json_schema[:schema]
-                else
-                  schema_instance
-                end
+      @schema = normalize_schema_payload(
+        schema_instance.respond_to?(:to_json_schema) ? schema_instance.to_json_schema : schema_instance
+      )
 
       self
     end
@@ -138,6 +140,7 @@ module RubyLLM
       response = @provider.complete(
         messages,
         tools: @tools,
+        tool_prefs: @tool_prefs,
         temperature: @temperature,
         model: @model,
         params: @params,
@@ -183,6 +186,36 @@ module RubyLLM
 
     private
 
+    def normalize_schema_payload(raw_schema)
+      return nil if raw_schema.nil?
+      return raw_schema unless raw_schema.is_a?(Hash)
+
+      schema = RubyLLM::Utils.deep_symbolize_keys(raw_schema)
+      schema_def = extract_schema_definition(schema)
+      strict = extract_schema_strict(schema, schema_def)
+      build_schema_payload(schema, schema_def, strict)
+    end
+
+    def extract_schema_definition(schema)
+      RubyLLM::Utils.deep_dup(schema[:schema] || schema)
+    end
+
+    def extract_schema_strict(schema, schema_def)
+      return schema[:strict] if schema.key?(:strict)
+      return schema_def.delete(:strict) if schema_def.is_a?(Hash)
+
+      nil
+    end
+
+    def build_schema_payload(schema, schema_def, strict)
+      {
+        name: schema[:name] || 'response',
+        schema: schema_def,
+        strict: strict.nil? || strict,
+        description: schema[:description]
+      }.compact
+    end
+
     def wrap_streaming_block(&block)
       return nil unless block_given?
 
@@ -209,15 +242,78 @@ module RubyLLM
         halt_result = result if result.is_a?(Tool::Halt)
       end
 
+      reset_tool_choice if forced_tool_choice?
       halt_result || complete(&)
     end
 
     def execute_tool(tool_call)
       tool = tools[tool_call.name.to_sym]
+      if tool.nil?
+        return {
+          error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
+                 "Available tools: #{tools.keys.to_json}."
+        }
+      end
+
       args = tool_call.arguments
       tool.call(args)
     end
 
+    def update_tool_options(choice:, calls:)
+      unless choice.nil?
+        normalized_choice = normalize_tool_choice(choice)
+        valid_tool_choices = %i[auto none required] + tools.keys
+        unless valid_tool_choices.include?(normalized_choice)
+          raise InvalidToolChoiceError,
+                "Invalid tool choice: #{choice}. Valid choices are: #{valid_tool_choices.join(', ')}"
+        end
+
+        @tool_prefs[:choice] = normalized_choice
+      end
+
+      @tool_prefs[:calls] = normalize_calls(calls) unless calls.nil?
+    end
+
+    def normalize_calls(calls)
+      case calls
+      when :many, 'many'
+        :many
+      when :one, 'one', 1
+        :one
+      else
+        raise ArgumentError, "Invalid calls value: #{calls.inspect}. Valid values are: :many, :one, or 1"
+      end
+    end
+
+    def normalize_tool_choice(choice)
+      return choice.to_sym if choice.is_a?(String) || choice.is_a?(Symbol)
+      return tool_name_for_choice_class(choice) if choice.is_a?(Class)
+
+      choice.respond_to?(:name) ? choice.name.to_sym : choice.to_sym
+    end
+
+    def tool_name_for_choice_class(tool_class)
+      matched_tool_name = tools.find { |_name, tool| tool.is_a?(tool_class) }&.first
+      return matched_tool_name if matched_tool_name
+
+      classify_tool_name(tool_class.name)
+    end
+
+    def classify_tool_name(class_name)
+      class_name.split('::').last
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+                .to_sym
+    end
+
+    def forced_tool_choice?
+      @tool_prefs[:choice] && !%i[auto none].include?(@tool_prefs[:choice])
+    end
+
+    def reset_tool_choice
+      @tool_prefs[:choice] = nil
+    end
+
     def build_content(message, attachments)
       return message if content_like?(message)
 

data/lib/ruby_llm/configuration.rb

@@ -11,20 +11,25 @@ module RubyLLM
                   :azure_api_base,
                   :azure_api_key,
                   :azure_ai_auth_token,
+                  :anthropic_api_base,
                   :anthropic_api_key,
                   :gemini_api_key,
                   :gemini_api_base,
                   :vertexai_project_id,
                   :vertexai_location,
+                  :vertexai_service_account_key,
                   :deepseek_api_key,
+                  :deepseek_api_base,
                   :perplexity_api_key,
                   :bedrock_api_key,
                   :bedrock_secret_key,
                   :bedrock_region,
                   :bedrock_session_token,
+                  :openrouter_api_base,
                   :openrouter_api_key,
                   :xai_api_key,
                   :ollama_api_base,
+                  :ollama_api_key,
                   :gpustack_api_base,
                   :gpustack_api_key,
                   :mistral_api_key,
@@ -51,6 +56,7 @@ module RubyLLM
                   :log_file,
                   :log_level,
                   :log_stream_debug
+    attr_reader :log_regexp_timeout
 
     def initialize
       @request_timeout = 300
@@ -73,10 +79,22 @@ module RubyLLM
       @log_file = $stdout
       @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
       @log_stream_debug = ENV['RUBYLLM_STREAM_DEBUG'] == 'true'
+      self.log_regexp_timeout = Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil
     end
 
     def instance_variables
       super.reject { |ivar| ivar.to_s.match?(/_id|_key|_secret|_token$/) }
     end
+
+    def log_regexp_timeout=(value)
+      if value.nil?
+        @log_regexp_timeout = nil
+      elsif Regexp.respond_to?(:timeout)
+        @log_regexp_timeout = value
+      else
+        RubyLLM.logger.warn("log_regexp_timeout is not supported on Ruby #{RUBY_VERSION}")
+        @log_regexp_timeout = value
+      end
+    end
   end
 end

data/lib/ruby_llm/connection.rb

@@ -65,19 +65,25 @@ module RubyLLM
                        errors: true,
                        headers: false,
                        log_level: :debug do |logger|
-        logger.filter(%r{[A-Za-z0-9+/=]{100,}}, '[BASE64 DATA]')
-        logger.filter(/[-\d.e,\s]{100,}/, '[EMBEDDINGS ARRAY]')
+        logger.filter(logging_regexp('[A-Za-z0-9+/=]{100,}'), '[BASE64 DATA]')
+        logger.filter(logging_regexp('[-\\d.e,\\s]{100,}'), '[EMBEDDINGS ARRAY]')
       end
     end
 
+    def logging_regexp(pattern)
+      return Regexp.new(pattern) if @config.log_regexp_timeout.nil? || !Regexp.respond_to?(:timeout)
+
+      Regexp.new(pattern, timeout: @config.log_regexp_timeout)
+    end
+
     def setup_retry(faraday)
       faraday.request :retry, {
         max: @config.max_retries,
         interval: @config.retry_interval,
         interval_randomness: @config.retry_interval_randomness,
         backoff_factor: @config.retry_backoff_factor,
-        exceptions: retry_exceptions,
-        retry_statuses: [429, 500, 502, 503, 504, 529]
+        methods: Faraday::Retry::Middleware::IDEMPOTENT_METHODS + [:post],
+        exceptions: retry_exceptions
       }
     end
 

data/lib/ruby_llm/content.rb

@@ -35,10 +35,16 @@ module RubyLLM
 
     def process_attachments_array_or_string(attachments)
       Utils.to_safe_array(attachments).each do |file|
+        next if blank_attachment_entry?(file)
+
         add_attachment(file)
       end
     end
 
+    def blank_attachment_entry?(file)
+      file.nil? || (file.is_a?(String) && file.strip.empty?)
+    end
+
     def process_attachments(attachments)
       if attachments.is_a?(Hash)
         attachments.each_value { |attachment| process_attachments_array_or_string(attachment) }
@@ -47,9 +53,7 @@ module RubyLLM
       end
     end
   end
-end
 
-module RubyLLM
   class Content
     # Represents provider-specific payloads that should bypass RubyLLM formatting.
     class Raw

data/lib/ruby_llm/error.rb

@@ -14,13 +14,16 @@ module RubyLLM
 
   # Error classes for non-HTTP errors
   class ConfigurationError < StandardError; end
+  class PromptNotFoundError < StandardError; end
   class InvalidRoleError < StandardError; end
+  class InvalidToolChoiceError < StandardError; end
   class ModelNotFoundError < StandardError; end
   class UnsupportedAttachmentError < StandardError; end
 
   # Error classes for different HTTP status codes
   class BadRequestError < Error; end
   class ForbiddenError < Error; end
+  class ContextLengthExceededError < Error; end
   class OverloadedError < Error; end
   class PaymentRequiredError < Error; end
   class RateLimitError < Error; end
@@ -42,6 +45,18 @@ module RubyLLM
     end
 
     class << self
+      CONTEXT_LENGTH_PATTERNS = [
+        /context length/i,
+        /context window/i,
+        /maximum context/i,
+        /request too large/i,
+        /too many tokens/i,
+        /token count exceeds/i,
+        /input[_\s-]?token/i,
+        /input or output tokens? must be reduced/i,
+        /reduce the length of messages/i
+      ].freeze
+
       def parse_error(provider:, response:) # rubocop:disable Metrics/PerceivedComplexity
         message = provider&.parse_error(response)
 
@@ -49,6 +64,10 @@ module RubyLLM
         when 200..399
           message
         when 400
+          if context_length_exceeded?(message)
+            raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
+          end
+
           raise BadRequestError.new(response, message || 'Invalid request - please check your input')
         when 401
           raise UnauthorizedError.new(response, message || 'Invalid API key - check your credentials')
@@ -58,10 +77,14 @@ module RubyLLM
           raise ForbiddenError.new(response,
                                    message || 'Forbidden - you do not have permission to access this resource')
         when 429
+          if context_length_exceeded?(message)
+            raise ContextLengthExceededError.new(response, message || 'Context length exceeded')
+          end
+
           raise RateLimitError.new(response, message || 'Rate limit exceeded - please wait a moment')
         when 500
           raise ServerError.new(response, message || 'API server error - please try again')
-        when 502..503
+        when 502..504
           raise ServiceUnavailableError.new(response, message || 'API server unavailable - please try again later')
         when 529
           raise OverloadedError.new(response, message || 'Service overloaded - please try again later')
@@ -69,6 +92,14 @@ module RubyLLM
           raise Error.new(response, message || 'An unknown error occurred')
         end
       end
+
+      private
+
+      def context_length_exceeded?(message)
+        return false if message.to_s.empty?
+
+        CONTEXT_LENGTH_PATTERNS.any? { |pattern| message.match?(pattern) }
+      end
     end
   end
 end

data/lib/ruby_llm/message.rb

@@ -10,9 +10,9 @@ module RubyLLM
 
     def initialize(options = {})
       @role = options.fetch(:role).to_sym
-      @content = normalize_content(options.fetch(:content))
-      @model_id = options[:model_id]
       @tool_calls = options[:tool_calls]
+      @content = normalize_content(options.fetch(:content), role: @role, tool_calls: @tool_calls)
+      @model_id = options[:model_id]
       @tool_call_id = options[:tool_call_id]
       @tokens = options[:tokens] || Tokens.build(
         input: options[:input_tokens],
@@ -90,7 +90,9 @@ module RubyLLM
 
     private
 
-    def normalize_content(content)
+    def normalize_content(content, role:, tool_calls:)
+      return '' if role == :assistant && content.nil? && tool_calls && !tool_calls.empty?
+
       case content
       when String then Content.new(content)
       when Hash then Content.new(content[:text], content)

data/lib/ruby_llm/model/info.rb

@@ -24,7 +24,7 @@ module RubyLLM
         @name = data[:name]
         @provider = data[:provider]
         @family = data[:family]
-        @created_at = Utils.to_time(data[:created_at])
+        @created_at = Utils.to_time(data[:created_at])&.utc
         @context_window = data[:context_window]
         @max_output_tokens = data[:max_output_tokens]
         @knowledge_cutoff = Utils.to_date(data[:knowledge_cutoff])