ruby_llm 1.5.1 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 854c31993769b5123faf650081276dae4026907d467514c905739b8737220b55
-  data.tar.gz: 408fb8253e5fdbf82bc3f3c3cc737e313d9835bd8023c1431cc4e6adc2a09be9
+  metadata.gz: e1fd977cc46769d8d235fe13a31e030a133618a335c8cd012ab8de2b7d439297
+  data.tar.gz: ce8d22464541ac19246e6018fde5c7b414ba0022bc5995f8900052f3d0ac5b42
 SHA512:
-  metadata.gz: c5572a959bcd8f314d1af4d66bb363cbe9eaa783fa8cbd6e051d3b0e471da49e87a895724def790fad59589d08eb5eb259ffd8dbe1f09d70274a900ae9575af4
-  data.tar.gz: 191f6f8aadc239998b0346e6a3e54fa4ace1d39fd56947693d7bd26e4248bfccc7894410f2f758bc456750cbef602b1577e7f3ca8a7c3a986077a7e957b7aa13
+  metadata.gz: aec038a65867c5fa13b93a11aa5356183b8f105bb7f48792e6300a9259a809206bc07da0b54c63a0a0de726cc3698ec2cd79c511be43e6fd8f47273adecc47a9
+  data.tar.gz: 5386da468b9f413d7fbf27192a693c2427a1e88a9082a7375f5641f01854a7cbd2235c1c8108ea870c97c97ea79c712bdd5d33e2ac09a22e25a74f9510a1599f

data/README.md

@@ -1,44 +1,18 @@
-<img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
-
-**A delightful Ruby way to work with AI.** RubyLLM provides **one** beautiful, Ruby-like interface to interact with modern AI models. Chat, generate images, create embeddings, and use tools – all with clean, expressive code that feels like Ruby, not like patching together multiple services.
-
-<div class="provider-icons">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/anthropic-text.svg" alt="Anthropic" class="logo-small">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-color.svg" alt="Bedrock" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-text.svg" alt="Bedrock" class="logo-small">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-color.svg" alt="DeepSeek" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/deepseek-text.svg" alt="DeepSeek" class="logo-small">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/gemini-brand-color.svg" alt="Gemini" class="logo-large">
-  <br>
-  <img src="https://raw.githubusercontent.com/gpustack/gpustack/main/docs/assets/gpustack-logo.png" alt="GPUStack" class="logo-medium" height="16">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/mistral-color.svg" alt="Mistral" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/mistral-text.svg" alt="Mistral" class="logo-small">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama.svg" alt="Ollama" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/ollama-text.svg" alt="Ollama" class="logo-medium">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai.svg" alt="OpenAI" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openai-text.svg" alt="OpenAI" class="logo-medium">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter.svg" alt="OpenRouter" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/openrouter-text.svg" alt="OpenRouter" class="logo-small">
-  &nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/perplexity-color.svg" alt="Perplexity" class="logo-medium">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/perplexity-text.svg" alt="Perplexity" class="logo-small">
-</div>
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="/docs/assets/images/logotype_dark.svg">
+  <img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
+</picture>
+
+**One *beautiful* Ruby API for GPT, Claude, Gemini, and more.** Easily build chatbots, AI agents, RAG applications, and content generators. Features chat (text, images, audio, PDFs), image generation, embeddings, tools (function calling), structured output, Rails integration, and streaming. Works with OpenAI, Anthropic, Google Gemini, AWS Bedrock, DeepSeek, Mistral, Ollama (local models), OpenRouter, Perplexity, GPUStack, and any OpenAI-compatible API.
 
 <div class="badge-container">
-  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg?a=1" alt="Gem Version" /></a>
+  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg?a=3" alt="Gem Version" /></a>
   <a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide" /></a>
   <a href="https://rubygems.org/gems/ruby_llm"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm"></a>
   <a href="https://codecov.io/gh/crmne/ruby_llm"><img src="https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg" alt="codecov" /></a>
 </div>
 
-🤺 Battle tested at [💬 Chat with Work](https://chatwithwork.com)
+Battle tested at [<picture><source media="(prefers-color-scheme: dark)" srcset="https://chatwithwork.com/logotype-dark.svg"><img src="https://chatwithwork.com/logotype.svg" alt="Chat with Work" height="30" align="absmiddle"></picture>](https://chatwithwork.com) — *Claude Code for your documents*
 
 ## The problem with AI libraries
 

data/lib/ruby_llm/active_record/acts_as.rb

@@ -96,8 +96,7 @@ module RubyLLM
           @chat.add_message(msg.to_llm)
         end
 
-        @chat.on_new_message { persist_new_message }
-             .on_end_message { |msg| persist_message_completion(msg) }
+        setup_persistence_callbacks
       end
 
       def with_instructions(instructions, replace: false)
@@ -139,18 +138,47 @@ module RubyLLM
         self
       end
 
+      def with_headers(...)
+        to_llm.with_headers(...)
+        self
+      end
+
       def with_schema(...)
         to_llm.with_schema(...)
         self
       end
 
-      def on_new_message(...)
-        to_llm.on_new_message(...)
+      def on_new_message(&block)
+        to_llm
+
+        existing_callback = @chat.instance_variable_get(:@on)[:new_message]
+
+        @chat.on_new_message do
+          existing_callback&.call
+          block&.call
+        end
         self
       end
 
-      def on_end_message(...)
-        to_llm.on_end_message(...)
+      def on_end_message(&block)
+        to_llm
+
+        existing_callback = @chat.instance_variable_get(:@on)[:end_message]
+
+        @chat.on_end_message do |msg|
+          existing_callback&.call(msg)
+          block&.call(msg)
+        end
+        self
+      end
+
+      def on_tool_call(...)
+        to_llm.on_tool_call(...)
+        self
+      end
+
+      def on_tool_result(...)
+        to_llm.on_tool_result(...)
         self
       end
 
@@ -170,15 +198,41 @@ module RubyLLM
       def complete(...)
         to_llm.complete(...)
       rescue RubyLLM::Error => e
-        if @message&.persisted? && @message.content.blank?
-          RubyLLM.logger.debug "RubyLLM: API call failed, destroying message: #{@message.id}"
-          @message.destroy
-        end
+        cleanup_failed_messages if @message&.persisted? && @message.content.blank?
+        cleanup_orphaned_tool_results
         raise e
       end
 
       private
 
+      def cleanup_failed_messages
+        RubyLLM.logger.debug "RubyLLM: API call failed, destroying message: #{@message.id}"
+        @message.destroy
+      end
+
+      def cleanup_orphaned_tool_results
+        loop do
+          messages.reload
+          last = messages.order(:id).last
+
+          break unless last&.tool_call? || last&.tool_result?
+
+          last.destroy
+        end
+      end
+
+      def setup_persistence_callbacks
+        # Only set up once per chat instance
+        return @chat if @chat.instance_variable_get(:@_persistence_callbacks_setup)
+
+        # Set up persistence callbacks (user callbacks will be chained via on_new_message/on_end_message methods)
+        @chat.on_new_message { persist_new_message }
+        @chat.on_end_message { |msg| persist_message_completion(msg) }
+
+        @chat.instance_variable_set(:@_persistence_callbacks_setup, true)
+        @chat
+      end
+
       def persist_new_message
         @message = messages.create!(role: :assistant, content: String.new)
       end

data/lib/ruby_llm/aliases.json

@@ -29,13 +29,17 @@
     "bedrock": "anthropic.claude-3-opus-20240229-v1:0:200k"
   },
   "claude-3-sonnet": {
-    "bedrock": "anthropic.claude-3-sonnet-20240229-v1:0",
-    "openrouter": "anthropic/claude-3-sonnet"
+    "bedrock": "anthropic.claude-3-sonnet-20240229-v1:0"
   },
   "claude-opus-4": {
     "anthropic": "claude-opus-4-20250514",
     "openrouter": "anthropic/claude-opus-4",
-    "bedrock": "us.anthropic.claude-opus-4-20250514-v1:0"
+    "bedrock": "us.anthropic.claude-opus-4-1-20250805-v1:0"
+  },
+  "claude-opus-4-1": {
+    "anthropic": "claude-opus-4-1-20250805",
+    "openrouter": "anthropic/claude-opus-4.1",
+    "bedrock": "us.anthropic.claude-opus-4-1-20250805-v1:0"
   },
   "claude-sonnet-4": {
     "anthropic": "claude-sonnet-4-20250514",
@@ -162,6 +166,22 @@
     "openai": "gpt-4o-search-preview",
     "openrouter": "openai/gpt-4o-search-preview"
   },
+  "gpt-5": {
+    "openai": "gpt-5",
+    "openrouter": "openai/gpt-5"
+  },
+  "gpt-5-mini": {
+    "openai": "gpt-5-mini",
+    "openrouter": "openai/gpt-5-mini"
+  },
+  "gpt-5-nano": {
+    "openai": "gpt-5-nano",
+    "openrouter": "openai/gpt-5-nano"
+  },
+  "gpt-oss-120b": {
+    "openai": "gpt-oss-120b",
+    "openrouter": "openai/gpt-oss-120b"
+  },
   "o1": {
     "openai": "o1",
     "openrouter": "openai/o1"

data/lib/ruby_llm/chat.rb

@@ -11,7 +11,7 @@ module RubyLLM
   class Chat
     include Enumerable
 
-    attr_reader :model, :messages, :tools, :params, :schema
+    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
@@ -26,11 +26,13 @@ module RubyLLM
       @messages = []
       @tools = {}
       @params = {}
+      @headers = {}
       @schema = nil
       @on = {
         new_message: nil,
         end_message: nil,
-        tool_call: nil
+        tool_call: nil,
+        tool_result: nil
       }
     end
 
@@ -58,14 +60,15 @@ module RubyLLM
       self
     end
 
-    def with_tools(*tools)
-      tools.each { |tool| with_tool tool }
+    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:)
-      @connection = @context ? @context.connection_for(@provider) : @provider.connection(@config)
+      @model, @provider = Models.resolve(model_id, provider:, assume_exists:, config: @config)
+      @connection = @provider.connection
       self
     end
 
@@ -86,6 +89,11 @@ module RubyLLM
       self
     end
 
+    def with_headers(**headers)
+      @headers = headers
+      self
+    end
+
     def with_schema(schema, force: false)
       unless force || @model.structured_output?
         raise UnsupportedStructuredOutputError, "Model #{@model.id} doesn't support structured output"
@@ -118,6 +126,11 @@ module RubyLLM
       self
     end
 
+    def on_tool_result(&block)
+      @on[:tool_result] = block
+      self
+    end
+
     def each(&)
       messages.each(&)
     end
@@ -128,8 +141,8 @@ module RubyLLM
         tools: @tools,
         temperature: @temperature,
         model: @model.id,
-        connection: @connection,
         params: @params,
+        headers: @headers,
         schema: @schema,
         &wrap_streaming_block(&)
       )
@@ -185,15 +198,20 @@ module RubyLLM
     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
 
-      complete(&)
+      halt_result || complete(&)
     end
 
     def execute_tool(tool_call)
@@ -201,5 +219,9 @@ module RubyLLM
       args = tool_call.arguments
       tool.call(args)
     end
+
+    def instance_variables
+      super - %i[@connection @config]
+    end
   end
 end

data/lib/ruby_llm/configuration.rb

@@ -15,6 +15,7 @@ module RubyLLM
                   :openai_api_base,
                   :openai_organization_id,
                   :openai_project_id,
+                  :openai_use_system_role,
                   :anthropic_api_key,
                   :gemini_api_key,
                   :deepseek_api_key,
@@ -43,7 +44,8 @@ module RubyLLM
                   :logger,
                   :log_file,
                   :log_level,
-                  :log_assume_model_exists
+                  :log_assume_model_exists,
+                  :log_stream_debug
 
     def initialize
       # Connection configuration
@@ -57,30 +59,17 @@ module RubyLLM
       # Default models
       @default_model = 'gpt-4.1-nano'
       @default_embedding_model = 'text-embedding-3-small'
-      @default_image_model = 'dall-e-3'
+      @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 inspect
-      redacted = lambda do |name, value|
-        if name.match?(/_id|_key|_secret|_token$/)
-          value.nil? ? 'nil' : '[FILTERED]'
-        else
-          value
-        end
-      end
-
-      inspection = instance_variables.map do |ivar|
-        name = ivar.to_s.delete_prefix('@')
-        value = redacted[name, instance_variable_get(ivar)]
-        "#{name}: #{value}"
-      end.join(', ')
-
-      "#<#{self.class}:0x#{object_id.to_s(16)} #{inspection}>"
+    def instance_variables
+      super.reject { |ivar| ivar.to_s.match?(/_id|_key|_secret|_token$/) }
     end
   end
 end

data/lib/ruby_llm/connection.rb

@@ -24,7 +24,7 @@ module RubyLLM
       @config = config
 
       ensure_configured!
-      @connection ||= Faraday.new(provider.api_base(@config)) do |faraday|
+      @connection ||= Faraday.new(provider.api_base) do |faraday|
         setup_timeout(faraday)
         setup_logging(faraday)
         setup_retry(faraday)
@@ -36,14 +36,14 @@ module RubyLLM
     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(@config) if @provider.respond_to?(:headers)
+        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(@config) if @provider.respond_to?(:headers)
+        req.headers.merge! @provider.headers if @provider.respond_to?(:headers)
         yield req if block_given?
       end
     end
@@ -106,16 +106,21 @@ module RubyLLM
     end
 
     def ensure_configured!
-      return if @provider.configured?(@config)
+      return if @provider.configured?
 
+      missing = @provider.configuration_requirements.reject { |req| @config.send(req) }
       config_block = <<~RUBY
         RubyLLM.configure do |config|
-          #{@provider.missing_configs(@config).map { |key| "config.#{key} = ENV['#{key.to_s.upcase}']" }.join("\n  ")}
+          #{missing.map { |key| "config.#{key} = ENV['#{key.to_s.upcase}']" }.join("\n  ")}
         end
       RUBY
 
       raise ConfigurationError,
-            "#{@provider.slug} provider is not configured. Add this to your initialization:\n\n#{config_block}"
+            "#{@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/context.rb

@@ -22,9 +22,8 @@ module RubyLLM
       Image.paint(*args, **kwargs, context: self, &)
     end
 
-    def connection_for(provider_module)
-      slug = provider_module.slug.to_sym
-      @connections[slug] ||= Connection.new(provider_module, @config)
+    def connection_for(provider_instance)
+      provider_instance.connection
     end
   end
 end

data/lib/ruby_llm/embedding.rb

@@ -20,12 +20,11 @@ module RubyLLM
                    dimensions: nil)
       config = context&.config || RubyLLM.config
       model ||= config.default_embedding_model
-      model, provider = Models.resolve(model, provider: provider, assume_exists: assume_model_exists)
+      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                       config: config)
       model_id = model.id
 
-      provider = Provider.for(model_id) if provider.nil?
-      connection = context ? context.connection_for(provider) : provider.connection(config)
-      provider.embed(text, model: model_id, connection:, dimensions:)
+      provider_instance.embed(text, model: model_id, dimensions:)
     end
   end
 end

data/lib/ruby_llm/error.rb

@@ -40,9 +40,9 @@ module RubyLLM
   # 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, provider:)
+    def initialize(app, options = {})
       super(app)
-      @provider = provider
+      @provider = options[:provider]
     end
 
     def call(env)

data/lib/ruby_llm/image.rb

@@ -43,12 +43,11 @@ module RubyLLM
                    context: nil)
       config = context&.config || RubyLLM.config
       model ||= config.default_image_model
-      model, provider = Models.resolve(model, provider: provider, assume_exists: assume_model_exists)
+      model, provider_instance = Models.resolve(model, provider: provider, assume_exists: assume_model_exists,
+                                                       config: config)
       model_id = model.id
 
-      provider = Provider.for(model_id) if provider.nil?
-      connection = context ? context.connection_for(provider) : provider.connection(config)
-      provider.paint(prompt, model: model_id, size:, connection:)
+      provider_instance.paint(prompt, model: model_id, size:)
     end
   end
 end

data/lib/ruby_llm/message.rb

@@ -55,6 +55,10 @@ module RubyLLM
       }.compact
     end
 
+    def instance_variables
+      super - [:@raw]
+    end
+
     private
 
     def normalize_content(content)