ruby_llm 1.15.0 → 2.0.0.rc1

data/lib/ruby_llm/error.rb

@@ -1,112 +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
-  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
-  class ServerError < Error; end
-  class ServiceUnavailableError < Error; end
-  class UnauthorizedError < Error; end
-
-  # Faraday middleware that maps provider-specific API errors to RubyLLM errors.
-  class ErrorMiddleware < Faraday::Middleware
-    def initialize(app, options = {})
-      super(app)
-      @provider = options[:provider]
+
+  # 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
+
+  # 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
+
+  # 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
 
-    def call(env)
-      @app.call(env).on_complete do |response|
-        self.class.parse_error(provider: @provider, response: response)
-      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
 
-    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)
-
-        case response.status
-        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')
-        when 402
-          raise PaymentRequiredError.new(response, message || 'Payment required - please top up your account')
-        when 403
-          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..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')
-        else
-          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
+  # 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
-end
 
-Faraday::Middleware.register_middleware(llm_errors: RubyLLM::ErrorMiddleware)
+  # 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