ruby_llm 1.12.0 → 1.14.1

data/lib/ruby_llm/aliases.json

@@ -1,8 +1,4 @@
 {
-  "chatgpt-4o": {
-    "openai": "chatgpt-4o-latest",
-    "openrouter": "openai/chatgpt-4o-latest"
-  },
   "claude-3-5-haiku": {
     "anthropic": "claude-3-5-haiku-20241022",
     "openrouter": "anthropic/claude-3.5-haiku",
@@ -14,7 +10,7 @@
   "claude-3-5-sonnet": {
     "anthropic": "claude-3-5-sonnet-20241022",
     "openrouter": "anthropic/claude-3.5-sonnet",
-    "bedrock": "anthropic.claude-3-5-sonnet-20240620-v1:0:200k"
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0"
   },
   "claude-3-7-sonnet": {
     "anthropic": "claude-3-7-sonnet-20250219",
@@ -30,8 +26,7 @@
     "bedrock": "anthropic.claude-3-haiku-20240307-v1:0:200k"
   },
   "claude-3-opus": {
-    "anthropic": "claude-3-opus-20240229",
-    "bedrock": "anthropic.claude-3-opus-20240229-v1:0:200k"
+    "anthropic": "claude-3-opus-20240229"
   },
   "claude-3-sonnet": {
     "anthropic": "claude-3-sonnet-20240229",
@@ -66,7 +61,8 @@
   "claude-opus-4-6": {
     "anthropic": "claude-opus-4-6",
     "openrouter": "anthropic/claude-opus-4.6",
-    "bedrock": "anthropic.claude-opus-4-6-v1"
+    "bedrock": "anthropic.claude-opus-4-6-v1",
+    "azure": "claude-opus-4-6"
   },
   "claude-sonnet-4": {
     "anthropic": "claude-sonnet-4-20250514",
@@ -82,6 +78,12 @@
     "bedrock": "anthropic.claude-sonnet-4-5-20250929-v1:0",
     "azure": "claude-sonnet-4-5-20250929"
   },
+  "claude-sonnet-4-6": {
+    "anthropic": "claude-sonnet-4-6",
+    "openrouter": "anthropic/claude-sonnet-4.6",
+    "bedrock": "anthropic.claude-sonnet-4-6",
+    "azure": "claude-sonnet-4-6"
+  },
   "deepseek-chat": {
     "deepseek": "deepseek-chat",
     "openrouter": "deepseek/deepseek-chat"
@@ -181,14 +183,30 @@
     "openrouter": "google/gemini-3-pro-preview",
     "vertexai": "gemini-3-pro-preview"
   },
+  "gemini-3.1-flash-image-preview": {
+    "gemini": "gemini-3.1-flash-image-preview",
+    "openrouter": "google/gemini-3.1-flash-image-preview",
+    "vertexai": "gemini-3.1-flash-image-preview"
+  },
+  "gemini-3.1-flash-lite-preview": {
+    "gemini": "gemini-3.1-flash-lite-preview",
+    "openrouter": "google/gemini-3.1-flash-lite-preview",
+    "vertexai": "gemini-3.1-flash-lite-preview"
+  },
+  "gemini-3.1-pro-preview": {
+    "gemini": "gemini-3.1-pro-preview",
+    "openrouter": "google/gemini-3.1-pro-preview",
+    "vertexai": "gemini-3.1-pro-preview"
+  },
+  "gemini-3.1-pro-preview-customtools": {
+    "gemini": "gemini-3.1-pro-preview-customtools",
+    "openrouter": "google/gemini-3.1-pro-preview-customtools",
+    "vertexai": "gemini-3.1-pro-preview-customtools"
+  },
   "gemini-embedding-001": {
     "gemini": "gemini-embedding-001",
     "vertexai": "gemini-embedding-001"
   },
-  "gemini-exp-1206": {
-    "gemini": "gemini-exp-1206",
-    "vertexai": "gemini-exp-1206"
-  },
   "gemini-flash": {
     "gemini": "gemini-flash-latest",
     "vertexai": "gemini-flash-latest"
@@ -230,18 +248,10 @@
     "openrouter": "openai/gpt-4",
     "azure": "gpt-4"
   },
-  "gpt-4-1106-preview": {
-    "openai": "gpt-4-1106-preview",
-    "openrouter": "openai/gpt-4-1106-preview"
-  },
   "gpt-4-turbo": {
     "openai": "gpt-4-turbo",
     "openrouter": "openai/gpt-4-turbo"
   },
-  "gpt-4-turbo-preview": {
-    "openai": "gpt-4-turbo-preview",
-    "openrouter": "openai/gpt-4-turbo-preview"
-  },
   "gpt-4.1": {
     "openai": "gpt-4.1",
     "openrouter": "openai/gpt-4.1",
@@ -321,7 +331,8 @@
   },
   "gpt-5.1": {
     "openai": "gpt-5.1",
-    "openrouter": "openai/gpt-5.1"
+    "openrouter": "openai/gpt-5.1",
+    "azure": "gpt-5.1"
   },
   "gpt-5.1-codex": {
     "openai": "gpt-5.1-codex",
@@ -347,6 +358,26 @@
     "openai": "gpt-5.2-pro",
     "openrouter": "openai/gpt-5.2-pro"
   },
+  "gpt-5.3-codex": {
+    "openai": "gpt-5.3-codex",
+    "openrouter": "openai/gpt-5.3-codex"
+  },
+  "gpt-5.4": {
+    "openai": "gpt-5.4",
+    "openrouter": "openai/gpt-5.4"
+  },
+  "gpt-5.4-mini": {
+    "openai": "gpt-5.4-mini",
+    "openrouter": "openai/gpt-5.4-mini"
+  },
+  "gpt-5.4-nano": {
+    "openai": "gpt-5.4-nano",
+    "openrouter": "openai/gpt-5.4-nano"
+  },
+  "gpt-5.4-pro": {
+    "openai": "gpt-5.4-pro",
+    "openrouter": "openai/gpt-5.4-pro"
+  },
   "gpt-audio": {
     "openai": "gpt-audio",
     "openrouter": "openai/gpt-audio"
@@ -355,6 +386,14 @@
     "openai": "gpt-audio-mini",
     "openrouter": "openai/gpt-audio-mini"
   },
+  "lyria-3-clip-preview": {
+    "gemini": "lyria-3-clip-preview",
+    "openrouter": "google/lyria-3-clip-preview"
+  },
+  "lyria-3-pro-preview": {
+    "gemini": "lyria-3-pro-preview",
+    "openrouter": "google/lyria-3-pro-preview"
+  },
   "o1": {
     "openai": "o1",
     "openrouter": "openai/o1"

data/lib/ruby_llm/attachment.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'pathname'
+require 'uri'
+
 module RubyLLM
   # A class representing a file attachment.
   class Attachment
@@ -134,7 +137,7 @@ module RubyLLM
     end
 
     def load_content_from_path
-      @content = File.read(@source)
+      @content = File.binread(@source)
     end
 
     def load_content_from_io

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,
@@ -149,7 +152,7 @@ module RubyLLM
 
       @on[:new_message]&.call unless block_given?
 
-      if @schema && response.content.is_a?(String)
+      if @schema && response.content.is_a?(String) && !response.tool_call?
         begin
           response.content = JSON.parse(response.content)
         rescue JSON::ParserError
@@ -183,6 +186,41 @@ 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: sanitize_schema_name(schema[:name] || 'response'),
+        schema: schema_def,
+        strict: strict.nil? || strict,
+        description: schema[:description]
+      }.compact
+    end
+
+    def sanitize_schema_name(name)
+      sanitized = name.to_s.gsub(/[^a-zA-Z0-9_-]/, '_')
+      sanitized.empty? ? 'response' : sanitized
+    end
+
     def wrap_streaming_block(&block)
       return nil unless block_given?
 
@@ -209,15 +247,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

@@ -3,80 +3,79 @@
 module RubyLLM
   # Global configuration for RubyLLM
   class Configuration
-    attr_accessor :openai_api_key,
-                  :openai_api_base,
-                  :openai_organization_id,
-                  :openai_project_id,
-                  :openai_use_system_role,
-                  :azure_api_base,
-                  :azure_api_key,
-                  :azure_ai_auth_token,
-                  :anthropic_api_key,
-                  :gemini_api_key,
-                  :gemini_api_base,
-                  :vertexai_project_id,
-                  :vertexai_location,
-                  :deepseek_api_key,
-                  :perplexity_api_key,
-                  :bedrock_api_key,
-                  :bedrock_secret_key,
-                  :bedrock_region,
-                  :bedrock_session_token,
-                  :openrouter_api_key,
-                  :xai_api_key,
-                  :ollama_api_base,
-                  :gpustack_api_base,
-                  :gpustack_api_key,
-                  :mistral_api_key,
-                  # Default models
-                  :default_model,
-                  :default_embedding_model,
-                  :default_moderation_model,
-                  :default_image_model,
-                  :default_transcription_model,
-                  # Model registry
-                  :model_registry_file,
-                  :model_registry_class,
-                  # Rails integration
-                  :use_new_acts_as,
-                  # Connection configuration
-                  :request_timeout,
-                  :max_retries,
-                  :retry_interval,
-                  :retry_backoff_factor,
-                  :retry_interval_randomness,
-                  :http_proxy,
-                  # Logging configuration
-                  :logger,
-                  :log_file,
-                  :log_level,
-                  :log_stream_debug
+    class << self
+      # Declare a single configuration option.
+      def option(key, default = nil)
+        key = key.to_sym
+        return if options.include?(key)
 
-    def initialize
-      @request_timeout = 300
-      @max_retries = 3
-      @retry_interval = 0.1
-      @retry_backoff_factor = 2
-      @retry_interval_randomness = 0.5
-      @http_proxy = nil
+        send(:attr_accessor, key)
+        option_keys << key
+        defaults[key] = default
+      end
+
+      def register_provider_options(options)
+        Array(options).each { |key| option(key, nil) }
+      end
+
+      def options
+        option_keys.dup
+      end
+
+      private
+
+      def option_keys = @option_keys ||= []
+      def defaults = @defaults ||= {}
+      private :option
+    end
 
-      @default_model = 'gpt-5-nano'
-      @default_embedding_model = 'text-embedding-3-small'
-      @default_moderation_model = 'omni-moderation-latest'
-      @default_image_model = 'gpt-image-1'
-      @default_transcription_model = 'whisper-1'
+    # System-level options are declared here.
+    # Provider-specific options are declared in each provider class via
+    # `self.configuration_options` and registered through Provider.register.
+    option :default_model, 'gpt-5.4'
+    option :default_embedding_model, 'text-embedding-3-small'
+    option :default_moderation_model, 'omni-moderation-latest'
+    option :default_image_model, 'gpt-image-1.5'
+    option :default_transcription_model, 'whisper-1'
 
-      @model_registry_file = File.expand_path('models.json', __dir__)
-      @model_registry_class = 'Model'
-      @use_new_acts_as = false
+    option :model_registry_file, -> { File.expand_path('models.json', __dir__) }
+    option :model_registry_class, 'Model'
 
-      @log_file = $stdout
-      @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
-      @log_stream_debug = ENV['RUBYLLM_STREAM_DEBUG'] == 'true'
+    option :use_new_acts_as, false
+
+    option :request_timeout, 300
+    option :max_retries, 3
+    option :retry_interval, 0.1
+    option :retry_backoff_factor, 2
+    option :retry_interval_randomness, 0.5
+    option :http_proxy, nil
+
+    option :logger, nil
+    option :log_file, -> { $stdout }
+    option :log_level, -> { ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO }
+    option :log_stream_debug, -> { ENV['RUBYLLM_STREAM_DEBUG'] == 'true' }
+    option :log_regexp_timeout, -> { Regexp.respond_to?(:timeout) ? (Regexp.timeout || 1.0) : nil }
+
+    def initialize
+      self.class.send(:defaults).each do |key, default|
+        value = default.respond_to?(:call) ? instance_exec(&default) : default
+        public_send("#{key}=", value)
+      end
     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

@@ -10,7 +10,6 @@ module RubyLLM
         f.response :logger,
                    RubyLLM.logger,
                    bodies: false,
-                   response: false,
                    errors: true,
                    headers: false,
                    log_level: :debug
@@ -60,24 +59,29 @@ module RubyLLM
     def setup_logging(faraday)
       faraday.response :logger,
                        RubyLLM.logger,
-                       bodies: true,
-                       response: true,
+                       bodies: RubyLLM.logger.debug?,
                        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

@@ -7,6 +7,11 @@ module RubyLLM
     attr_reader :response
 
     def initialize(response = nil, message = nil)
+      if response.is_a?(String)
+        message = response
+        response = nil
+      end
+
       @response = response
       super(message || response&.body)
     end
@@ -14,13 +19,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 +50,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 +69,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 +82,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 +97,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)