ruby_llm_community 0.0.1 → 0.0.3

data/lib/ruby_llm/error.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Custom error class that wraps API errors from different providers
+  # into a consistent format with helpful error messages.
+  #
+  # Example:
+  #   begin
+  #     chat.ask "What's 2+2?"
+  #   rescue RubyLLM::Error => e
+  #     puts "Couldn't chat with AI: #{e.message}"
+  #   end
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(response = nil, message = nil)
+      @response = response
+      super(message || response&.body)
+    end
+  end
+
+  # Error classes for non-HTTP errors
+  class ConfigurationError < StandardError; end
+  class InvalidRoleError < 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 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.
+  # Uses provider's parse_error method to extract meaningful error messages.
+  class ErrorMiddleware < Faraday::Middleware
+    def initialize(app, options = {})
+      super(app)
+      @provider = options[:provider]
+    end
+
+    def call(env)
+      @app.call(env).on_complete do |response|
+        self.class.parse_error(provider: @provider, response: response)
+      end
+    end
+
+    class << self
+      def parse_error(provider:, response:) # rubocop:disable Metrics/PerceivedComplexity
+        message = provider&.parse_error(response)
+
+        case response.status
+        when 200..399
+          message
+        when 400
+          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
+          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
+          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
+    end
+  end
+end
+
+Faraday::Middleware.register_middleware(llm_errors: RubyLLM::ErrorMiddleware)

data/lib/ruby_llm/image.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents a generated image from an AI model.
+  # Provides an interface to image generation capabilities
+  # from providers like DALL-E and Gemini's Imagen.
+  class Image
+    attr_reader :url, :data, :mime_type, :revised_prompt, :model_id
+
+    def initialize(url: nil, data: nil, mime_type: nil, revised_prompt: nil, model_id: nil)
+      @url = url
+      @data = data
+      @mime_type = mime_type
+      @revised_prompt = revised_prompt
+      @model_id = model_id
+    end
+
+    def base64?
+      !@data.nil?
+    end
+
+    # Returns the raw binary image data regardless of source
+    def to_blob
+      if base64?
+        Base64.decode64 @data
+      else
+        response = Connection.basic.get @url
+        response.body
+      end
+    end
+
+    # Saves the image to a file path
+    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)
+      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:)
+    end
+  end
+end

data/lib/ruby_llm/message.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A single message in a chat conversation. Can represent user input,
+  # AI responses, or tool interactions. Tracks token usage and handles
+  # the complexities of tool calls and responses.
+  class Message
+    ROLES = %i[system user assistant tool].freeze
+
+    attr_reader :role, :tool_calls, :tool_call_id, :input_tokens, :output_tokens, :model_id, :raw,
+                :cached_tokens, :cache_creation_tokens
+    attr_writer :content
+
+    def initialize(options = {})
+      @role = options.fetch(:role).to_sym
+      @content = normalize_content(options.fetch(:content))
+      @tool_calls = options[:tool_calls]
+      @input_tokens = options[:input_tokens]
+      @output_tokens = options[:output_tokens]
+      @model_id = options[:model_id]
+      @tool_call_id = options[:tool_call_id]
+      @cached_tokens = options[:cached_tokens]
+      @cache_creation_tokens = options[:cache_creation_tokens]
+      @raw = options[:raw]
+
+      ensure_valid_role
+    end
+
+    def content
+      if @content.is_a?(Content) && @content.text && @content.attachments.empty?
+        @content.text
+      else
+        @content
+      end
+    end
+
+    def tool_call?
+      !tool_calls.nil? && !tool_calls.empty?
+    end
+
+    def tool_result?
+      !tool_call_id.nil? && !tool_call_id.empty?
+    end
+
+    def tool_results
+      content if tool_result?
+    end
+
+    def to_h
+      {
+        role: role,
+        content: content,
+        tool_calls: tool_calls,
+        tool_call_id: tool_call_id,
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        model_id: model_id,
+        cache_creation_tokens: cache_creation_tokens,
+        cached_tokens: cached_tokens
+      }.compact
+    end
+
+    def instance_variables
+      super - [:@raw]
+    end
+
+    private
+
+    def normalize_content(content)
+      case content
+      when String then Content.new(content)
+      when Hash then Content.new(content[:text], content)
+      else content # Pass through nil, Content, or other types
+      end
+    end
+
+    def ensure_valid_role
+      raise InvalidRoleError, "Expected role to be one of: #{ROLES.join(', ')}" unless ROLES.include?(role)
+    end
+  end
+end

data/lib/ruby_llm/mime_type.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'marcel'
+
+module RubyLLM
+  # MimeTypes module provides methods to handle MIME types using Marcel gem
+  module MimeType
+    module_function
+
+    def for(...)
+      Marcel::MimeType.for(...)
+    end
+
+    def image?(type)
+      type.start_with?('image/')
+    end
+
+    def audio?(type)
+      type.start_with?('audio/')
+    end
+
+    def pdf?(type)
+      type == 'application/pdf'
+    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
+
+    # MIME types that have a text/ prefix but need to be handled differently
+    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
+  end
+end

data/lib/ruby_llm/model/info.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Model
+    # Information about an AI model's capabilities, pricing, and metadata.
+    # Used by the Models registry to help developers choose the right model
+    # for their needs.
+    #
+    # Example:
+    #   model = RubyLLM.models.find('gpt-4')
+    #   model.supports_vision?          # => true
+    #   model.supports_functions?       # => true
+    #   model.input_price_per_million   # => 30.0
+    class Info
+      attr_reader :id, :name, :provider, :family, :created_at, :context_window, :max_output_tokens, :knowledge_cutoff,
+                  :modalities, :capabilities, :pricing, :metadata
+
+      def initialize(data)
+        @id = data[:id]
+        @name = data[:name]
+        @provider = data[:provider]
+        @family = data[:family]
+        @created_at = Utils.to_time(data[:created_at])
+        @context_window = data[:context_window]
+        @max_output_tokens = data[:max_output_tokens]
+        @knowledge_cutoff = Utils.to_date(data[:knowledge_cutoff])
+        @modalities = Modalities.new(data[:modalities] || {})
+        @capabilities = data[:capabilities] || []
+        @pricing = Pricing.new(data[:pricing] || {})
+        @metadata = data[:metadata] || {}
+      end
+
+      # Capability methods
+      def supports?(capability)
+        capabilities.include?(capability.to_s)
+      end
+
+      %w[function_calling structured_output batch reasoning citations streaming].each do |cap|
+        define_method "#{cap}?" do
+          supports?(cap)
+        end
+      end
+
+      # Backward compatibility methods
+      def display_name
+        name
+      end
+
+      def max_tokens
+        max_output_tokens
+      end
+
+      def supports_vision?
+        modalities.input.include?('image')
+      end
+
+      def supports_functions?
+        function_calling?
+      end
+
+      def input_price_per_million
+        pricing.text_tokens.input
+      end
+
+      def output_price_per_million
+        pricing.text_tokens.output
+      end
+
+      def type # rubocop:disable Metrics/PerceivedComplexity
+        if modalities.output.include?('embeddings') && !modalities.output.include?('text')
+          'embedding'
+        elsif modalities.output.include?('image') && !modalities.output.include?('text')
+          'image'
+        elsif modalities.output.include?('audio') && !modalities.output.include?('text')
+          'audio'
+        elsif modalities.output.include?('moderation')
+          'moderation'
+        else
+          'chat'
+        end
+      end
+
+      def to_h
+        {
+          id: id,
+          name: name,
+          provider: provider,
+          family: family,
+          created_at: created_at,
+          context_window: context_window,
+          max_output_tokens: max_output_tokens,
+          knowledge_cutoff: knowledge_cutoff,
+          modalities: modalities.to_h,
+          capabilities: capabilities,
+          pricing: pricing.to_h,
+          metadata: metadata
+        }
+      end
+    end
+  end
+end

data/lib/ruby_llm/model/modalities.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Model
+    # Holds and manages input and output modalities for a language model
+    class Modalities
+      attr_reader :input, :output
+
+      def initialize(data)
+        @input = Array(data[:input]).map(&:to_s)
+        @output = Array(data[:output]).map(&:to_s)
+      end
+
+      def to_h
+        {
+          input: input,
+          output: output
+        }
+      end
+    end
+  end
+end

data/lib/ruby_llm/model/pricing.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Model
+    # A collection that manages and provides access to different categories of pricing information
+    # (text tokens, images, audio tokens, embeddings)
+    class Pricing
+      def initialize(data)
+        @data = {}
+
+        # Initialize pricing categories
+        %i[text_tokens images audio_tokens embeddings].each do |category|
+          @data[category] = PricingCategory.new(data[category]) if data[category] && !empty_pricing?(data[category])
+        end
+      end
+
+      def method_missing(method, *args)
+        if respond_to_missing?(method)
+          @data[method.to_sym] || PricingCategory.new
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        %i[text_tokens images audio_tokens embeddings].include?(method.to_sym) || super
+      end
+
+      def to_h
+        @data.transform_values(&:to_h)
+      end
+
+      private
+
+      def empty_pricing?(data)
+        # Check if all pricing values in this category are zero or nil
+        return true unless data
+
+        %i[standard batch].each do |tier|
+          next unless data[tier]
+
+          data[tier].each_value do |value|
+            return false if value && value != 0.0
+          end
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/ruby_llm/model/pricing_category.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Model
+    # Represents pricing tiers for different usage categories (standard and batch)
+    class PricingCategory
+      attr_reader :standard, :batch
+
+      def initialize(data = {})
+        @standard = PricingTier.new(data[:standard] || {}) unless empty_tier?(data[:standard])
+        @batch = PricingTier.new(data[:batch] || {}) unless empty_tier?(data[:batch])
+      end
+
+      # Shorthand methods that default to standard tier
+      def input
+        standard&.input_per_million
+      end
+
+      def output
+        standard&.output_per_million
+      end
+
+      def cached_input
+        standard&.cached_input_per_million
+      end
+
+      # Get value for a specific tier
+      def [](key)
+        key == :batch ? batch : standard
+      end
+
+      def to_h
+        result = {}
+        result[:standard] = standard.to_h if standard
+        result[:batch] = batch.to_h if batch
+        result
+      end
+
+      private
+
+      def empty_tier?(tier_data)
+        return true unless tier_data
+
+        tier_data.values.all? { |v| v.nil? || v == 0.0 }
+      end
+    end
+  end
+end

data/lib/ruby_llm/model/pricing_tier.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Model
+    # A dynamic class for storing non-zero pricing values with flexible attribute access
+    class PricingTier
+      def initialize(data = {})
+        @values = {}
+
+        # Only store non-zero values
+        data.each do |key, value|
+          @values[key.to_sym] = value if value && value != 0.0
+        end
+      end
+
+      def method_missing(method, *args)
+        if method.to_s.end_with?('=')
+          key = method.to_s.chomp('=').to_sym
+          @values[key] = args.first if args.first && args.first != 0.0
+        elsif @values.key?(method)
+          @values[method]
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        method.to_s.end_with?('=') || @values.key?(method.to_sym) || super
+      end
+
+      def to_h
+        @values
+      end
+    end
+  end
+end

data/lib/ruby_llm/model.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Model-related classes for working with LLM models
+  module Model
+  end
+end