ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/ruby_llm/error.rb

@@ -1,48 +1,184 @@
 # frozen_string_literal: true
 
 module RubyLLM
-  # Custom error class that wraps API errors from different providers
-  # into a consistent format with helpful error messages.
+  # Error is the base class for provider-operation errors raised by
+  # RubyLLM, including API, network, capability, and provider response-shape
+  # failures. When an HTTP response is available, it wraps that response and
+  # normalizes the message across providers. Subclasses map common HTTP
+  # status codes: BadRequestError (400), UnauthorizedError (401),
+  # PaymentRequiredError (402), ForbiddenError (403), RateLimitError (429),
+  # ServerError (500), ServiceUnavailableError (502 to 504), and
+  # OverloadedError (529).
+  #
+  #   begin
+  #     RubyLLM.chat.ask "Translate 'hello' to French."
+  #   rescue RubyLLM::RateLimitError
+  #     puts "Rate limit hit. Please wait a moment."
+  #   rescue RubyLLM::Error => e
+  #     puts "API error: #{e.message}"
+  #     puts e.response&.status
+  #   end
+  #
+  # Local setup and programming errors, such as ConfigurationError and
+  # ModelNotFoundError, inherit from StandardError directly and are not
+  # caught by rescuing Error.
   class Error < StandardError
+    # The HTTP response that caused the error, or +nil+ when none is
+    # available. Its +status+ and +body+ carry the provider's reply.
     attr_reader :response
 
-    def initialize(response = nil, message = nil)
-      if response.is_a?(String)
-        message = response
-        response = nil
-      end
+    def self.default_message # :nodoc:
+      nil
+    end
 
+    # Creates an error with +message+. Pass +response:+ to attach the HTTP
+    # response; its body supplies the message when +message+ is +nil+.
+    def initialize(message = nil, response: nil)
       @response = response
-      super(message || response&.body)
+      super(message || response&.body || self.class.default_message)
     end
   end
 
-  # Error classes for non-HTTP errors
+  # Raised when a deprecated API is used and
+  # Configuration#deprecation_behavior is +:raise+. With the default
+  # +:warn+, deprecations are logged instead.
+  #
+  #   RubyLLM.configure do |config|
+  #     config.deprecation_behavior = :raise
+  #   end
+  class DeprecationError < StandardError; end
+
+  # Raised when required configuration, such as a provider API key, is
+  # missing.
   class ConfigurationError < StandardError; end
+
+  # Raised when RubyLLM.render_prompt cannot find the named prompt file.
   class PromptNotFoundError < StandardError; end
+
+  # Raised when a message role outside +:system+, +:user+, +:assistant+, or
+  # +:tool+ is used.
   class InvalidRoleError < StandardError; end
+
+  # Raised when the +choice:+ option of Chat#with_tool_options is neither a
+  # known mode nor the name of a registered tool.
   class InvalidToolChoiceError < StandardError; end
+
+  # Raised when a user message is staged while the last response still has
+  # unanswered tool calls. Providers reject such a transcript, so the chat
+  # refuses it up front: finish the round with #complete, recording
+  # #approve or #deny decisions for calls that require approval.
+  class PendingToolCallsError < StandardError; end
+
+  # Raised when a requested model id is not in the model registry.
   class ModelNotFoundError < StandardError; end
 
-  # Raised when RubyLLM cannot format an attachment for the selected provider.
-  class UnsupportedAttachmentError < StandardError
-    GUIDANCE = 'Consider using a model that supports this attachment type.'
+  # Raised when a model registry cannot be fetched, parsed, or persisted.
+  class ModelRegistryError < StandardError; end
+
+  # Raised when an in-flight chat operation is cancelled with Chat#cancel.
+  class CancelledError < StandardError
+    # Creates an error for a cancelled chat operation.
+    def initialize(message = 'Chat generation cancelled')
+      super
+    end
+  end
+
+  # Raised when Chat#with_server_tools is used with a provider RubyLLM has
+  # no server-tool support for, or with an alias the provider's protocol
+  # does not define.
+  class UnsupportedServerToolError < Error; end
 
-    def initialize(type = nil)
+  # Raised when an attachment cannot be formatted for the selected provider,
+  # for example an audio file sent to a model without audio input.
+  class UnsupportedAttachmentError < Error
+    GUIDANCE = 'Consider using a model that supports this attachment type.' # :nodoc:
+
+    def initialize(type = nil) # :nodoc:
       message = 'Unsupported attachment type'
       message = "#{message}: #{type}" if type
       super("#{message}. #{GUIDANCE}")
     end
   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
-  class ServerError < Error; end
-  class ServiceUnavailableError < Error; end
-  class UnauthorizedError < Error; end
+  # Raised for HTTP 400 responses when the request is invalid.
+  class BadRequestError < Error
+    def self.default_message # :nodoc:
+      'Invalid request - please check your input'
+    end
+  end
+
+  # Raised for HTTP 403 responses when the API key lacks permission for the
+  # requested resource.
+  class ForbiddenError < Error
+    def self.default_message # :nodoc:
+      'Forbidden - you do not have permission to access this resource'
+    end
+  end
+
+  # Raised when the request exceeds the model's context window or token
+  # limits.
+  class ContextLengthExceededError < Error
+    def self.default_message # :nodoc:
+      'Context length exceeded'
+    end
+  end
+
+  # Raised when a provider returns tool-call arguments that are not valid
+  # JSON, often because the response was truncated mid-tool-call.
+  class ToolCallParseError < Error
+    # Returns the normalized reason generation stopped, or +nil+.
+    attr_reader :finish_reason
+
+    def initialize(message = nil, response: nil, finish_reason: nil) # :nodoc:
+      @finish_reason = finish_reason
+      message ||= 'Provider returned malformed tool call arguments'
+      message = "#{message} (finish_reason: #{finish_reason})" if finish_reason
+      super(message, response: response)
+    end
+  end
+
+  # Raised for HTTP 529 responses when the provider is temporarily
+  # overloaded.
+  class OverloadedError < Error
+    def self.default_message # :nodoc:
+      'Service overloaded - please try again later'
+    end
+  end
+
+  # Raised for HTTP 402 responses when the provider account has a billing
+  # or quota problem.
+  class PaymentRequiredError < Error
+    def self.default_message # :nodoc:
+      'Payment required - please top up your account'
+    end
+  end
+
+  # Raised for HTTP 429 responses when the provider rate limit is exceeded.
+  class RateLimitError < Error
+    def self.default_message # :nodoc:
+      'Rate limit exceeded - please wait a moment'
+    end
+  end
+
+  # Raised for HTTP 500 responses when the provider reports a server error.
+  class ServerError < Error
+    def self.default_message # :nodoc:
+      'API server error - please try again'
+    end
+  end
+
+  # Raised for HTTP 502, 503, and 504 responses when the provider is
+  # temporarily unavailable.
+  class ServiceUnavailableError < Error
+    def self.default_message # :nodoc:
+      'API server unavailable - please try again later'
+    end
+  end
+
+  # Raised for HTTP 401 responses when the API key is missing or invalid.
+  class UnauthorizedError < Error
+    def self.default_message # :nodoc:
+      'Invalid API key - check your credentials'
+    end
+  end
 end

data/lib/ruby_llm/fallback.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A Fallback is a fallback model target configured with Chat#with_fallbacks.
+  # When the active model fails with a matching error, the chat retries the
+  # request with each fallback in order. Instances are yielded to
+  # Chat#before_fallback and Chat#after_fallback callbacks, enriched with the
+  # details of that attempt.
+  #
+  #   chat = RubyLLM.chat(model: "gpt-4.1")
+  #                 .with_fallbacks("gpt-4.1-mini", "claude-haiku-4-5")
+  #
+  #   chat.before_fallback do |fallback|
+  #     puts "Falling back from #{fallback.from.id} to #{fallback.to.id}"
+  #   end
+  #
+  #   chat.after_fallback do |fallback|
+  #     puts "Fallback #{fallback.succeeded? ? 'succeeded' : 'failed'}"
+  #   end
+  class Fallback
+    include Support::Inspectable
+
+    # The error classes that trigger a fallback when Chat#with_fallbacks is
+    # called without +on:+.
+    DEFAULT_ERRORS = [
+      RateLimitError,
+      ServerError,
+      ServiceUnavailableError,
+      OverloadedError,
+      Faraday::TimeoutError,
+      Faraday::ConnectionFailed
+    ].freeze
+
+    # The model id of the fallback target.
+    attr_reader :id
+
+    # The provider slug of the fallback target as a String, or +nil+.
+    attr_reader :provider
+
+    # The Model object the fallback was configured with, or +nil+ when it was
+    # configured with a model id.
+    attr_reader :model
+
+    # The Chat performing the fallback attempt.
+    attr_reader :chat
+
+    # The error that triggered the fallback.
+    attr_reader :error
+
+    # The Model the chat is falling back from.
+    attr_reader :from
+
+    # The Model the chat is falling back to.
+    attr_reader :to
+
+    # The fallback attempt number, starting at 1.
+    attr_reader :attempt
+
+    # The response Message from a successful fallback attempt, or +nil+.
+    attr_reader :response
+
+    # The error raised by the fallback attempt itself, or +nil+ if it
+    # succeeded.
+    attr_reader :fallback_error
+
+    attr_reader :streaming # :nodoc:
+
+    def self.build(value) # :nodoc:
+      case value
+      when self
+        value
+      when RubyLLM::Model
+        new(model: value)
+      when String, Symbol
+        new(id: value.to_s)
+      else
+        raise ArgumentError, 'Expected a model id or RubyLLM::Model'
+      end
+    end
+
+    def inspect_attributes # :nodoc:
+      { id: id, provider: provider, attempt: attempt }
+    end
+
+    def initialize(id: nil, provider: nil, model: nil, **attributes) # :nodoc:
+      @id = id || model&.id
+      @provider = (provider || model&.provider)&.to_s
+      @model = model
+      @chat = attributes[:chat]
+      @error = attributes[:error]
+      @from = attributes[:from]
+      @to = attributes[:to]
+      @attempt = attributes[:attempt]
+      @streaming = attributes.fetch(:streaming, false)
+      @chunks_yielded = attributes.fetch(:chunks_yielded, false)
+      @response = attributes[:response]
+      @fallback_error = attributes[:fallback_error]
+    end
+
+    def with_attempt(**attributes) # :nodoc:
+      self.class.new(id: id, provider: provider, model: model, **attributes)
+    end
+
+    def finish(response: nil, fallback_error: nil) # :nodoc:
+      @response = response
+      @fallback_error = fallback_error
+      self
+    end
+
+    # Returns whether the fallback happened during a streaming request.
+    def streaming?
+      streaming
+    end
+
+    # Returns whether the failed model already yielded stream chunks before
+    # the fallback.
+    def chunks_yielded?
+      @chunks_yielded
+    end
+
+    # Returns +true+ if the fallback attempt raised an error, +false+
+    # otherwise.
+    def failed?
+      !fallback_error.nil?
+    end
+
+    # Returns +true+ if the fallback attempt produced a response without
+    # error, +false+ otherwise.
+    def succeeded?
+      !response.nil? && !failed?
+    end
+  end
+end

data/lib/ruby_llm/files/mime_type.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'marcel'
+
+module RubyLLM
+  module Files # :nodoc:
+    module MimeType # :nodoc: all
+      module_function
+
+      def for(...)
+        Marcel::MimeType.for(...)
+      end
+
+      def image?(type)
+        type.start_with?('image/')
+      end
+
+      def video?(type)
+        type.start_with?('video/')
+      end
+
+      def audio?(type)
+        type.start_with?('audio/')
+      end
+
+      def pdf?(type)
+        type == 'application/pdf'
+      end
+
+      def document?(type)
+        return false if pdf?(type) || text?(type)
+
+        DOCUMENT_MIME_TYPES.include?(type) ||
+          DOCUMENT_MIME_PREFIXES.any? { |prefix| type.start_with?(prefix) }
+      end
+
+      def text?(type)
+        type.start_with?('text/') ||
+          TEXT_SUFFIXES.any? { |suffix| type.end_with?(suffix) } ||
+          NON_TEXT_PREFIX_TEXT_MIME_TYPES.include?(type)
+      end
+
+      # Structured-syntax suffixes (+json, +xml, ...) that mark a non-text/ type as text.
+      TEXT_SUFFIXES = ['+json', '+xml', '+html', '+yaml', '+csv', '+plain', '+javascript', '+svg'].freeze
+
+      # MIME types that don't have a text/ prefix but should be treated as text
+      NON_TEXT_PREFIX_TEXT_MIME_TYPES = [
+        'application/json', # Base type, even if specific ones end with +json
+        'application/xml',  # Base type, even if specific ones end with +xml
+        'application/javascript',
+        'application/ecmascript',
+        'application/rtf',
+        'application/sql',
+        'application/x-sh',
+        'application/x-csh',
+        'application/x-httpd-php',
+        'application/sdp',
+        'application/sparql-query',
+        'application/graphql',
+        'application/yang', # Data modeling language, often serialized as XML/JSON but the type itself is distinct
+        'application/mbox', # Mailbox format
+        'application/x-tex',
+        'application/x-latex',
+        'application/x-perl',
+        'application/x-python',
+        'application/x-tcl',
+        'application/pgp-signature', # Often ASCII armored
+        'application/pgp-keys',      # Often ASCII armored
+        'application/vnd.coffeescript',
+        'application/vnd.dart',
+        'application/vnd.oai.openapi', # Base for OpenAPI, often with +json or +yaml suffix
+        'application/vnd.zul',         # ZK User Interface Language (can be XML-like)
+        'application/x-yaml',          # Common non-standard for YAML
+        'application/yaml',            # Standard for YAML
+        'application/toml'             # TOML configuration files
+      ].freeze
+
+      DOCUMENT_MIME_TYPES = [
+        'application/msword',
+        'application/rtf',
+        'application/vnd.apple.keynote',
+        'application/vnd.apple.numbers',
+        'application/vnd.apple.pages',
+        'application/vnd.google-apps.document',
+        'application/vnd.google-apps.presentation',
+        'application/vnd.google-apps.spreadsheet',
+        'application/vnd.ms-excel',
+        'application/vnd.ms-powerpoint'
+      ].freeze
+
+      DOCUMENT_MIME_PREFIXES = [
+        'application/vnd.openxmlformats-officedocument.',
+        'application/vnd.oasis.opendocument.'
+      ].freeze
+    end
+  end
+end

data/lib/ruby_llm/image.rb

@@ -3,82 +3,203 @@
 require 'base64'
 
 module RubyLLM
-  # Represents a generated image from an AI model.
+  # An Image is a generated or edited image. Save it to a file with #save
+  # or read its bytes with #to_blob. Both handle hosted URLs and inline data.
+  #
+  #   image = RubyLLM.paint("a sunset over mountains in watercolor style")
+  #   image.save("sunset.png")
+  #
   class Image
-    attr_reader :url, :data, :mime_type, :revised_prompt, :model_id, :usage
+    include Support::Inspectable
+    include Accounting::Usage::Result
 
-    def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model_id: nil, usage: {}) # rubocop:disable Metrics/ParameterLists
+    # The URL of the hosted image, for providers that return one, or +nil+.
+    attr_reader :url
+
+    # The Base64-encoded image data, for providers that return the image
+    # inline, or +nil+.
+    attr_reader :data
+
+    # The MIME type of the image data, such as <tt>"image/png"</tt>.
+    attr_reader :mime_type
+
+    # The provider's rewritten version of the prompt, when reported.
+    attr_reader :revised_prompt
+
+    # The id of the model that generated the image.
+    attr_reader :model
+
+    # Generates an image from +prompt+ and returns an Image. Most code
+    # calls this through RubyLLM.paint.
+    #
+    # +model:+ selects the image model and defaults to the configured
+    # +default_image_model+. +provider:+ forces a specific provider, and
+    # +assume_model_exists:+ skips the registry lookup, which is useful
+    # for custom endpoints. +size:+ requests dimensions on models that
+    # support it. +count:+ asks for several images in one request, returning
+    # an Array of Images instead of one. +with:+ passes one or more source
+    # images for editing, and +mask:+ constrains which parts of the image
+    # may change. +provider_options:+ takes options in the provider's
+    # request vocabulary and merges them into the request as-is.
+    # +context:+ supplies a Context whose configuration replaces the
+    # global one. +metadata:+ is included in the instrumentation payload.
+    #
+    #   image = RubyLLM.paint("A small watercolor robot", model: "gpt-image-2")
+    #
+    #   images = RubyLLM.paint("A small watercolor robot", count: 4)
+    #   images.each_with_index { |image, i| image.save("robot-#{i}.png") }
+    #
+    #   RubyLLM.paint(
+    #     "Turn the logo green and keep the background transparent",
+    #     model: "gpt-image-2",
+    #     with: "logo.png"
+    #   )
+    #
+    # Providers that cannot generate several images in one request ignore
+    # +count:+ and return a single Image.
+    def self.paint(prompt,
+                   model: nil,
+                   provider: nil,
+                   assume_model_exists: false,
+                   size: nil,
+                   count: nil,
+                   context: nil,
+                   with: nil,
+                   mask: nil,
+                   provider_options: {},
+                   metadata: nil)
+      config = context&.config || RubyLLM.config
+      model ||= config.default_image_model
+      model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
+                                                       config: config)
+      empty_tokens = Tokens.new
+      payload = {
+        provider: provider_instance.slug,
+        provider_class: provider_instance.class.display_name,
+        model: model.id,
+        model_info: model,
+        prompt: prompt,
+        size: size,
+        count: count,
+        provider_options: provider_options,
+        metadata: metadata,
+        tokens: empty_tokens,
+        cost: Cost.new(tokens: empty_tokens, model:, category: :images)
+      }
+
+      RubyLLM.instrument('image.ruby_llm', payload, config: config) do |event|
+        result = provider_instance.paint(prompt, model:, size:, count:, with:, mask:, provider_options:)
+        images = Support::Utils.to_safe_array(result)
+        event[:result] = result
+        event[:response_model] = images.first&.model
+        event[:tokens] = Tokens.aggregate(images.map(&:tokens))
+        event[:cost] = Cost.aggregate(images.map(&:cost))
+        result
+      end
+    end
+
+    # :stopdoc:
+
+    # Set by the protocol that generated the image, so a Context's
+    # connection settings reach #to_blob.
+    attr_writer :config
+
+    def config
+      @config || RubyLLM.config
+    end
+
+    def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model: nil, usage: {})
       @url = url
       @data = data
       @mime_type = mime_type
       @revised_prompt = revised_prompt
-      @model_id = model_id
-      @usage = usage
+      @model = model
+      @raw_usage = usage
     end
+    # :startdoc:
 
+    # Returns +true+ if the image holds inline Base64 data, +false+ otherwise.
     def base64?
       !@data.nil?
     end
 
+    # Returns the raw binary image bytes, decoding #data when present or
+    # downloading from #url otherwise.
+    #
+    #   image_bytes = image.to_blob
+    #
     def to_blob
       if base64?
         Base64.decode64 @data
       else
-        response = Connection.basic.get @url
+        response = Transport::Connection.basic(config).get @url
         response.body
       end
     end
 
+    # Writes the binary image to +path+, expanding it first. Returns
+    # +path+ as given.
+    #
+    #   image.save("steampunk_owl.png")
+    #
     def save(path)
       File.binwrite(File.expand_path(path), to_blob)
       path
     end
 
-    def self.paint(prompt, # rubocop:disable Metrics/ParameterLists
-                   model: nil,
-                   provider: nil,
-                   assume_model_exists: false,
-                   size: '1024x1024',
-                   context: nil,
-                   with: nil,
-                   mask: nil,
-                   params: {})
-      config = context&.config || RubyLLM.config
-      model ||= config.default_image_model
-      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
-                                                       config: config)
-      model_id = model.id
-
-      provider_instance.paint(prompt, model: model_id, size:, with:, mask:, params:)
-    end
-
+    # Returns a Tokens with usage across every provider attempt.
+    # Its fields are +nil+ when none were reported.
+    #
+    #   image.tokens.input
+    #   image.tokens.output
+    #
     def tokens
-      @tokens ||= Tokens.build(
-        input: usage_value('input_tokens'),
-        output: usage_value('output_tokens')
+      return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?
+
+      @tokens ||= Tokens.new(
+        input: raw_usage['input_tokens'],
+        output: raw_usage['output_tokens'],
+        reported_cost: raw_usage['cost']
       )
     end
 
+    # Returns a Cost across every provider attempt, using reported prices
+    # when available and registry pricing otherwise.
+    #
+    #   image.cost.total
+    #
     def cost
+      return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?
+
       Cost.new(tokens:, model: model_info, category: :images, input_details: input_tokens_details)
     end
 
+    # Returns the registry Model for #model, or +nil+ if the model id
+    # is missing or not in the registry.
     def model_info
-      return unless model_id
+      return unless model
 
-      @model_info ||= RubyLLM.models.find(model_id)
+      @model_info ||= RubyLLM.models.find(model)
     rescue ModelNotFoundError
       nil
     end
 
     private
 
+    attr_reader :raw_usage
+
     def input_tokens_details
-      usage_value('input_tokens_details')
+      raw_usage['input_tokens_details']
     end
 
-    def usage_value(key)
-      usage[key] || usage[key.to_sym]
+    def inspect_attributes # :nodoc:
+      {
+        model: model,
+        mime_type: mime_type,
+        url: url,
+        data: data && "#{data.bytesize} bytes",
+        revised_prompt: revised_prompt
+      }
     end
   end
 end