ruby_llm_community 0.0.1 → 0.0.2

data/lib/ruby_llm/attachment.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # A class representing a file attachment.
+  class Attachment
+    attr_reader :source, :filename, :mime_type
+
+    def initialize(source, filename: nil)
+      @source = source
+      if url?
+        @source = URI source
+        @filename = filename || File.basename(@source.path).to_s
+      elsif path?
+        @source = Pathname.new source
+        @filename = filename || @source.basename.to_s
+      elsif active_storage?
+        @filename = filename || extract_filename_from_active_storage
+      else
+        @filename = filename
+      end
+
+      determine_mime_type
+    end
+
+    def url?
+      @source.is_a?(URI) || (@source.is_a?(String) && @source.match?(%r{^https?://}))
+    end
+
+    def path?
+      @source.is_a?(Pathname) || (@source.is_a?(String) && !url?)
+    end
+
+    def io_like?
+      @source.respond_to?(:read) && !path? && !active_storage?
+    end
+
+    def active_storage?
+      return false unless defined?(ActiveStorage)
+
+      @source.is_a?(ActiveStorage::Blob) ||
+        @source.is_a?(ActiveStorage::Attached::One) ||
+        @source.is_a?(ActiveStorage::Attached::Many)
+    end
+
+    def content
+      return @content if defined?(@content) && !@content.nil?
+
+      if url?
+        fetch_content
+      elsif path?
+        load_content_from_path
+      elsif active_storage?
+        load_content_from_active_storage
+      elsif io_like?
+        load_content_from_io
+      else
+        RubyLLM.logger.warn "Source is neither a URL, path, ActiveStorage, nor IO-like: #{@source.class}"
+        nil
+      end
+
+      @content
+    end
+
+    def encoded
+      Base64.strict_encode64(content)
+    end
+
+    def type
+      return :image if image?
+      return :audio if audio?
+      return :pdf if pdf?
+      return :text if text?
+
+      :unknown
+    end
+
+    def image?
+      RubyLLM::MimeType.image? mime_type
+    end
+
+    def audio?
+      RubyLLM::MimeType.audio? mime_type
+    end
+
+    def pdf?
+      RubyLLM::MimeType.pdf? mime_type
+    end
+
+    def text?
+      RubyLLM::MimeType.text? mime_type
+    end
+
+    def to_h
+      { type: type, source: @source }
+    end
+
+    private
+
+    def determine_mime_type
+      return @mime_type = active_storage_content_type if active_storage? && active_storage_content_type.present?
+
+      @mime_type = RubyLLM::MimeType.for(url? ? nil : @source, name: @filename)
+      @mime_type = RubyLLM::MimeType.for(content) if @mime_type == 'application/octet-stream'
+      @mime_type = 'audio/wav' if @mime_type == 'audio/x-wav' # Normalize WAV type
+    end
+
+    def fetch_content
+      response = Connection.basic.get @source.to_s
+      @content = response.body
+    end
+
+    def load_content_from_path
+      @content = File.read(@source)
+    end
+
+    def load_content_from_io
+      @source.rewind if @source.respond_to? :rewind
+      @content = @source.read
+    end
+
+    def load_content_from_active_storage
+      return unless defined?(ActiveStorage)
+
+      @content = case @source
+                 when ActiveStorage::Blob
+                   @source.download
+                 when ActiveStorage::Attached::One
+                   @source.blob&.download
+                 when ActiveStorage::Attached::Many
+                   # For multiple attachments, just take the first one
+                   # This maintains the single-attachment interface
+                   @source.blobs.first&.download
+                 end
+    end
+
+    def extract_filename_from_active_storage # rubocop:disable Metrics/PerceivedComplexity
+      return 'attachment' unless defined?(ActiveStorage)
+
+      case @source
+      when ActiveStorage::Blob
+        @source.filename.to_s
+      when ActiveStorage::Attached::One
+        @source.blob&.filename&.to_s || 'attachment'
+      when ActiveStorage::Attached::Many
+        @source.blobs.first&.filename&.to_s || 'attachment'
+      else
+        'attachment'
+      end
+    end
+
+    def active_storage_content_type
+      return unless defined?(ActiveStorage)
+
+      case @source
+      when ActiveStorage::Blob
+        @source.content_type
+      when ActiveStorage::Attached::One
+        @source.blob&.content_type
+      when ActiveStorage::Attached::Many
+        @source.blobs.first&.content_type
+      end
+    end
+  end
+end

data/lib/ruby_llm/chat.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents a conversation with an AI model. Handles message history,
+  # streaming responses, and tool integration with a simple, conversational API.
+  #
+  # Example:
+  #   chat = RubyLLM.chat
+  #   chat.ask "What's the best way to learn Ruby?"
+  #   chat.ask "Can you elaborate on that?"
+  class Chat
+    include Enumerable
+
+    attr_reader :model, :messages, :tools, :params, :headers, :schema
+
+    def initialize(model: nil, provider: nil, assume_model_exists: false, context: nil)
+      if assume_model_exists && !provider
+        raise ArgumentError, 'Provider must be specified if assume_model_exists is true'
+      end
+
+      @context = context
+      @config = context&.config || RubyLLM.config
+      model_id = model || @config.default_model
+      with_model(model_id, provider: provider, assume_exists: assume_model_exists)
+      @temperature = 0.7
+      @messages = []
+      @tools = {}
+      @params = {}
+      @headers = {}
+      @schema = nil
+      @on = {
+        new_message: nil,
+        end_message: nil,
+        tool_call: nil,
+        tool_result: nil
+      }
+    end
+
+    def ask(message = nil, with: nil, &)
+      add_message role: :user, content: Content.new(message, with)
+      complete(&)
+    end
+
+    alias say ask
+
+    def with_instructions(instructions, replace: false)
+      @messages = @messages.reject { |msg| msg.role == :system } if replace
+
+      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
+      self
+    end
+
+    def with_tools(*tools, replace: false)
+      @tools.clear if replace
+      tools.compact.each { |tool| with_tool tool }
+      self
+    end
+
+    def with_model(model_id, provider: nil, assume_exists: false)
+      @model, @provider = Models.resolve(model_id, provider:, assume_exists:, config: @config)
+      @connection = @provider.connection
+      self
+    end
+
+    def with_temperature(temperature)
+      @temperature = temperature
+      self
+    end
+
+    def with_context(context)
+      @context = context
+      @config = context.config
+      with_model(@model.id, provider: @provider.slug, assume_exists: true)
+      self
+    end
+
+    def with_params(**params)
+      @params = params
+      self
+    end
+
+    def with_headers(**headers)
+      @headers = headers
+      self
+    end
+
+    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
+
+      self
+    end
+
+    def on_new_message(&block)
+      @on[:new_message] = block
+      self
+    end
+
+    def on_end_message(&block)
+      @on[:end_message] = block
+      self
+    end
+
+    def on_tool_call(&block)
+      @on[:tool_call] = block
+      self
+    end
+
+    def on_tool_result(&block)
+      @on[:tool_result] = block
+      self
+    end
+
+    def each(&)
+      messages.each(&)
+    end
+
+    def complete(&) # rubocop:disable Metrics/PerceivedComplexity
+      response = @provider.complete(
+        messages,
+        tools: @tools,
+        temperature: @temperature,
+        model: @model.id,
+        params: @params,
+        headers: @headers,
+        schema: @schema,
+        &wrap_streaming_block(&)
+      )
+
+      @on[:new_message]&.call unless block_given?
+
+      # Parse JSON if schema was set
+      if @schema && response.content.is_a?(String)
+        begin
+          response.content = JSON.parse(response.content)
+        rescue JSON::ParserError
+          # If parsing fails, keep content as string
+        end
+      end
+
+      add_message response
+      @on[:end_message]&.call(response)
+
+      if response.tool_call?
+        handle_tool_calls(response, &)
+      else
+        response
+      end
+    end
+
+    def add_message(message_or_attributes)
+      message = message_or_attributes.is_a?(Message) ? message_or_attributes : Message.new(message_or_attributes)
+      messages << message
+      message
+    end
+
+    def reset_messages!
+      @messages.clear
+    end
+
+    private
+
+    def wrap_streaming_block(&block)
+      return nil unless block_given?
+
+      first_chunk_received = false
+
+      proc do |chunk|
+        # Create message on first content chunk
+        unless first_chunk_received
+          first_chunk_received = true
+          @on[:new_message]&.call
+        end
+
+        # Pass chunk to user's block
+        block.call chunk
+      end
+    end
+
+    def handle_tool_calls(response, &)
+      halt_result = nil
+
+      response.tool_calls.each_value do |tool_call|
+        @on[:new_message]&.call
+        @on[:tool_call]&.call(tool_call)
+        result = execute_tool tool_call
+        @on[:tool_result]&.call(result)
+        message = add_message role: :tool, content: result.to_s, tool_call_id: tool_call.id
+        @on[:end_message]&.call(message)
+
+        halt_result = result if result.is_a?(Tool::Halt)
+      end
+
+      halt_result || complete(&)
+    end
+
+    def execute_tool(tool_call)
+      tool = tools[tool_call.name.to_sym]
+      args = tool_call.arguments
+      tool.call(args)
+    end
+
+    def instance_variables
+      super - %i[@connection @config]
+    end
+  end
+end

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,75 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Global configuration for RubyLLM. Manages API keys, default models,
+  # and provider-specific settings.
+  #
+  # Configure via:
+  #   RubyLLM.configure do |config|
+  #     config.openai_api_key = ENV['OPENAI_API_KEY']
+  #     config.anthropic_api_key = ENV['ANTHROPIC_API_KEY']
+  #   end
+  class Configuration
+    # Provider-specific 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,
+                  :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_image_model,
+                  # Connection configuration
+                  :request_timeout,
+                  :max_retries,
+                  :retry_interval,
+                  :retry_backoff_factor,
+                  :retry_interval_randomness,
+                  :http_proxy,
+                  # Logging configuration
+                  :logger,
+                  :log_file,
+                  :log_level,
+                  :log_assume_model_exists,
+                  :log_stream_debug
+
+    def initialize
+      # Connection configuration
+      @request_timeout = 120
+      @max_retries = 3
+      @retry_interval = 0.1
+      @retry_backoff_factor = 2
+      @retry_interval_randomness = 0.5
+      @http_proxy = nil
+
+      # Default models
+      @default_model = 'gpt-4.1-nano'
+      @default_embedding_model = 'text-embedding-3-small'
+      @default_image_model = 'gpt-image-1'
+
+      # Logging configuration
+      @log_file = $stdout
+      @log_level = ENV['RUBYLLM_DEBUG'] ? Logger::DEBUG : Logger::INFO
+      @log_assume_model_exists = true
+      @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, &)
+      body = payload.is_a?(Hash) ? JSON.generate(payload, ascii_only: false) : payload
+      @connection.post url, body 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
+
+    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,}}, 'data":"[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 :json
+      faraday.response :json
+      faraday.adapter Faraday.default_adapter
+      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
+
+    def instance_variables
+      super - %i[@config @connection]
+    end
+  end
+end

data/lib/ruby_llm/content.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Represents the content sent to or received from an LLM.
+  # Selects the appropriate attachment class based on the content type.
+  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)
+        # Ignores types (like :image, :audio, :text, :pdf) since we have robust MIME type detection
+        attachments.each_value { |attachment| process_attachments_array_or_string(attachment) }
+      else
+        process_attachments_array_or_string attachments
+      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,30 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Core embedding interface. Provides a clean way to generate embeddings
+  # from text using various provider models.
+  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