dify_llm 1.9.1 → 1.14.1

data/lib/ruby_llm/chat.rb

@@ -5,7 +5,7 @@ module RubyLLM
   class Chat
     include Enumerable
 
-    attr_reader :model, :messages, :tools, :params, :headers, :schema, :provider
+    attr_reader :model, :messages, :tools, :tool_prefs, :params, :headers, :schema, :provider
 
     def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
       if assume_model_exists && !provider
@@ -19,9 +19,11 @@ module RubyLLM
       @temperature = nil
       @messages = []
       @tools = {}
+      @tool_prefs = { choice: nil, calls: nil }
       @params = {}
       @headers = {}
       @schema = nil
+      @thinking = nil
       @on = {
         new_message: nil,
         end_message: nil,
@@ -37,22 +39,31 @@ module RubyLLM
 
     alias say ask
 
-    def with_instructions(instructions, replace: false)
-      @messages = @messages.reject { |msg| msg.role == :system } if replace
+    def with_instructions(instructions, append: false, replace: nil)
+      append ||= (replace == false) unless replace.nil?
+
+      if append
+        append_system_instruction(instructions)
+      else
+        replace_system_instruction(instructions)
+      end
 
-      add_message role: :system, content: instructions
       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
 
@@ -67,6 +78,13 @@ module RubyLLM
       self
     end
 
+    def with_thinking(effort: nil, budget: nil)
+      raise ArgumentError, 'with_thinking requires :effort or :budget' if effort.nil? && budget.nil?
+
+      @thinking = Thinking::Config.new(effort: effort, budget: budget)
+      self
+    end
+
     def with_context(context)
       @context = context
       @config = context.config
@@ -87,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
@@ -125,17 +140,19 @@ module RubyLLM
       response = @provider.complete(
         messages,
         tools: @tools,
+        tool_prefs: @tool_prefs,
         temperature: @temperature,
         model: @model,
         params: @params,
         headers: @headers,
         schema: @schema,
+        thinking: @thinking,
         &wrap_streaming_block(&)
       )
 
       @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
@@ -169,18 +186,47 @@ 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?
 
-      first_chunk_received = false
+      @on[:new_message]&.call
 
       proc do |chunk|
-        # Create message on first content chunk
-        unless first_chunk_received
-          first_chunk_received = true
-          @on[:new_message]&.call
-        end
-
         block.call chunk
       end
     end
@@ -201,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)
 
@@ -219,5 +328,24 @@ module RubyLLM
     def content_like?(object)
       object.is_a?(Content) || object.is_a?(Content::Raw)
     end
+
+    def append_system_instruction(instructions)
+      system_messages, non_system_messages = @messages.partition { |msg| msg.role == :system }
+      system_messages << Message.new(role: :system, content: instructions)
+      @messages = system_messages + non_system_messages
+    end
+
+    def replace_system_instruction(instructions)
+      system_messages, non_system_messages = @messages.partition { |msg| msg.role == :system }
+
+      if system_messages.empty?
+        system_messages = [Message.new(role: :system, content: instructions)]
+      else
+        system_messages.first.content = instructions
+        system_messages = [system_messages.first]
+      end
+
+      @messages = system_messages + non_system_messages
+    end
   end
 end

data/lib/ruby_llm/configuration.rb

@@ -3,79 +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,
-                  :anthropic_api_key,
-                  :gemini_api_key,
-                  :gemini_api_base,
-                  :vertexai_project_id,
-                  :vertexai_location,
-                  :deepseek_api_key,
-                  :dify_api_base,
-                  :dify_api_key,
-                  :dify_user,
-                  :perplexity_api_key,
-                  :bedrock_api_key,
-                  :bedrock_secret_key,
-                  :bedrock_region,
-                  :bedrock_session_token,
-                  :openrouter_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-4.1-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
@@ -71,24 +70,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

@@ -5,22 +5,26 @@ module RubyLLM
   class Message
     ROLES = %i[system user assistant tool].freeze
 
-    attr_reader :role, :model_id, :tool_calls, :tool_call_id, :input_tokens, :output_tokens,
-                :cached_tokens, :cache_creation_tokens, :raw, :conversation_id
+    attr_reader :role, :model_id, :tool_calls, :tool_call_id, :raw, :conversation_id, :thinking, :tokens
     attr_writer :content
 
     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]
-      @conversation_id = options[:conversation_id]
-      @input_tokens = options[:input_tokens]
-      @output_tokens = options[:output_tokens]
-      @cached_tokens = options[:cached_tokens]
-      @cache_creation_tokens = options[:cache_creation_tokens]
+      @tokens = options[:tokens] || Tokens.build(
+        input: options[:input_tokens],
+        output: options[:output_tokens],
+        cached: options[:cached_tokens],
+        cache_creation: options[:cache_creation_tokens],
+        thinking: options[:thinking_tokens],
+        reasoning: options[:reasoning_tokens]
+      )
       @raw = options[:raw]
+      @conversation_id = options[:conversation_id]
+      @thinking = options[:thinking]
 
       ensure_valid_role
     end
@@ -45,6 +49,30 @@ module RubyLLM
       content if tool_result?
     end
 
+    def input_tokens
+      tokens&.input
+    end
+
+    def output_tokens
+      tokens&.output
+    end
+
+    def cached_tokens
+      tokens&.cached
+    end
+
+    def cache_creation_tokens
+      tokens&.cache_creation
+    end
+
+    def thinking_tokens
+      tokens&.thinking
+    end
+
+    def reasoning_tokens
+      tokens&.thinking
+    end
+
     def to_h
       {
         role: role,
@@ -53,11 +81,9 @@ module RubyLLM
         tool_calls: tool_calls,
         tool_call_id: tool_call_id,
         conversation_id: conversation_id,
-        input_tokens: input_tokens,
-        output_tokens: output_tokens,
-        cached_tokens: cached_tokens,
-        cache_creation_tokens: cache_creation_tokens
-      }.compact
+        thinking: thinking&.text,
+        thinking_signature: thinking&.signature
+      }.merge(tokens ? tokens.to_h : {}).compact
     end
 
     def instance_variables
@@ -66,7 +92,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)