ruby_llm_swarm 1.9.1

data/lib/ruby_llm/chunk.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  class Chunk < Message
+  end
+end

data/lib/ruby_llm/configuration.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+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,
+                  :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
+
+    def initialize
+      @request_timeout = 300
+      @max_retries = 3
+      @retry_interval = 0.1
+      @retry_backoff_factor = 2
+      @retry_interval_randomness = 0.5
+      @http_proxy = nil
+
+      @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'
+
+      @model_registry_file = File.expand_path('models.json', __dir__)
+      @model_registry_class = 'Model'
+      @use_new_acts_as = false
+
+      @log_file = $stdout
+      @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
+      @log_stream_debug = ENV['RUBYLLM_STREAM_DEBUG'] == 'true'
+    end
+
+    def instance_variables
+      super.reject { |ivar| ivar.to_s.match?(/_id|_key|_secret|_token$/) }
+    end
+  end
+end

data/lib/ruby_llm/connection.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Connection class for managing API connections to various providers.
+  class Connection
+    attr_reader :provider, :connection, :config
+
+    def self.basic(&)
+      Faraday.new do |f|
+        f.response :logger,
+                   RubyLLM.logger,
+                   bodies: false,
+                   response: false,
+                   errors: true,
+                   headers: false,
+                   log_level: :debug
+        f.response :raise_error
+        yield f if block_given?
+      end
+    end
+
+    def initialize(provider, config)
+      @provider = provider
+      @config = config
+
+      ensure_configured!
+      @connection ||= Faraday.new(provider.api_base) do |faraday|
+        setup_timeout(faraday)
+        setup_logging(faraday)
+        setup_retry(faraday)
+        setup_middleware(faraday)
+        setup_http_proxy(faraday)
+      end
+    end
+
+    def post(url, payload, &)
+      @connection.post url, payload do |req|
+        req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
+        yield req if block_given?
+      end
+    end
+
+    def get(url, &)
+      @connection.get url do |req|
+        req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
+        yield req if block_given?
+      end
+    end
+
+    def instance_variables
+      super - %i[@config @connection]
+    end
+
+    private
+
+    def setup_timeout(faraday)
+      faraday.options.timeout = @config.request_timeout
+    end
+
+    def setup_logging(faraday)
+      faraday.response :logger,
+                       RubyLLM.logger,
+                       bodies: true,
+                       response: true,
+                       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]')
+      end
+    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]
+      }
+    end
+
+    def setup_middleware(faraday)
+      faraday.request :multipart
+      faraday.request :json
+      faraday.response :json
+      faraday.adapter :net_http
+      faraday.use :llm_errors, provider: @provider
+    end
+
+    def setup_http_proxy(faraday)
+      return unless @config.http_proxy
+
+      faraday.proxy = @config.http_proxy
+    end
+
+    def retry_exceptions
+      [
+        Errno::ETIMEDOUT,
+        Timeout::Error,
+        Faraday::TimeoutError,
+        Faraday::ConnectionFailed,
+        Faraday::RetriableResponse,
+        RubyLLM::RateLimitError,
+        RubyLLM::ServerError,
+        RubyLLM::ServiceUnavailableError,
+        RubyLLM::OverloadedError
+      ]
+    end
+
+    def ensure_configured!
+      return if @provider.configured?
+
+      missing = @provider.configuration_requirements.reject { |req| @config.send(req) }
+      config_block = <<~RUBY
+        RubyLLM.configure do |config|
+          #{missing.map { |key| "config.#{key} = ENV['#{key.to_s.upcase}']" }.join("\n  ")}
+        end
+      RUBY
+
+      raise ConfigurationError,
+            "#{@provider.name} provider is not configured. Add this to your initialization:\n\n#{config_block}"
+    end
+  end
+end

data/lib/ruby_llm/content.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents the content sent to or received from an LLM.
+  class Content
+    attr_reader :text, :attachments
+
+    def initialize(text = nil, attachments = nil)
+      @text = text
+      @attachments = []
+
+      process_attachments(attachments)
+      raise ArgumentError, 'Text and attachments cannot be both nil' if @text.nil? && @attachments.empty?
+    end
+
+    def add_attachment(source, filename: nil)
+      @attachments << Attachment.new(source, filename:)
+      self
+    end
+
+    def format
+      if @text && @attachments.empty?
+        @text
+      else
+        self
+      end
+    end
+
+    # For Rails serialization
+    def to_h
+      { text: @text, attachments: @attachments.map(&:to_h) }
+    end
+
+    private
+
+    def process_attachments_array_or_string(attachments)
+      Utils.to_safe_array(attachments).each do |file|
+        add_attachment(file)
+      end
+    end
+
+    def process_attachments(attachments)
+      if attachments.is_a?(Hash)
+        attachments.each_value { |attachment| process_attachments_array_or_string(attachment) }
+      else
+        process_attachments_array_or_string attachments
+      end
+    end
+  end
+end
+
+module RubyLLM
+  class Content
+    # Represents provider-specific payloads that should bypass RubyLLM formatting.
+    class Raw
+      attr_reader :value
+
+      def initialize(value)
+        raise ArgumentError, 'Raw content payload cannot be nil' if value.nil?
+
+        @value = value
+      end
+
+      def format
+        @value
+      end
+
+      def to_h
+        @value
+      end
+    end
+  end
+end

data/lib/ruby_llm/context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Holds per-call configs
+  class Context
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+      @connections = {}
+    end
+
+    def chat(*args, **kwargs, &)
+      Chat.new(*args, **kwargs, context: self, &)
+    end
+
+    def embed(*args, **kwargs, &)
+      Embedding.embed(*args, **kwargs, context: self, &)
+    end
+
+    def paint(*args, **kwargs, &)
+      Image.paint(*args, **kwargs, context: self, &)
+    end
+
+    def connection_for(provider_instance)
+      provider_instance.connection
+    end
+  end
+end

data/lib/ruby_llm/embedding.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Core embedding interface.
+  class Embedding
+    attr_reader :vectors, :model, :input_tokens
+
+    def initialize(vectors:, model:, input_tokens: 0)
+      @vectors = vectors
+      @model = model
+      @input_tokens = input_tokens
+    end
+
+    def self.embed(text, # rubocop:disable Metrics/ParameterLists
+                   model: nil,
+                   provider: nil,
+                   assume_model_exists: false,
+                   context: nil,
+                   dimensions: nil)
+      config = context&.config || RubyLLM.config
+      model ||= config.default_embedding_model
+      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                       config: config)
+      model_id = model.id
+
+      provider_instance.embed(text, model: model_id, dimensions:)
+    end
+  end
+end

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.
+  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
+
+  # Responses API specific errors
+  class ResponsesApiError < Error; end
+  class ResponseIdNotFoundError < ResponsesApiError; end
+  class ResponseFailedError < ResponsesApiError; end
+  class ResponseInProgressError < ResponsesApiError; end
+  class ResponseCancelledError < ResponsesApiError; end
+  class ResponseIncompleteError < ResponsesApiError; 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]
+    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,49 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents a generated image from an AI model.
+  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
+
+    def to_blob
+      if base64?
+        Base64.decode64 @data
+      else
+        response = Connection.basic.get @url
+        response.body
+      end
+    end
+
+    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,86 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A single message in a chat conversation.
+  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,
+                :response_id, :reasoning_summary, :reasoning_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]
+      @tool_call_id = options[:tool_call_id]
+      @input_tokens = options[:input_tokens]
+      @output_tokens = options[:output_tokens]
+      @cached_tokens = options[:cached_tokens]
+      @cache_creation_tokens = options[:cache_creation_tokens]
+      @raw = options[:raw]
+      @response_id = options[:response_id]
+      @reasoning_summary = options[:reasoning_summary]
+      @reasoning_tokens = options[:reasoning_tokens]
+
+      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,
+        model_id: model_id,
+        tool_calls: tool_calls,
+        tool_call_id: tool_call_id,
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        cached_tokens: cached_tokens,
+        cache_creation_tokens: cache_creation_tokens,
+        response_id: response_id,
+        reasoning_summary: reasoning_summary,
+        reasoning_tokens: reasoning_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
+      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,71 @@
+# 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 video?(type)
+      type.start_with?('video/')
+    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