ruby_llm 1.2.0 → 1.3.0rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f06ce431337dc189e6172b0c98ed897fdba930200f3f118c39c15f4527ec135
-  data.tar.gz: 18f8ff36e7ee18cbee315e66db4b8f04619c98595a5de3b73d215bed248ca0d4
+  metadata.gz: ff16d82f5fc8836eba0943ee83bc3fe3b1558172ecc78cc6d4136fa504461e8f
+  data.tar.gz: 73cd15c8c05f53dae87740e0022cbb4b72ebd151918d7fe97d2f9a6047264069
 SHA512:
-  metadata.gz: 42f7603cfec24fa6cc59b1186d2d6a90af9e9076eb79124ac5ce09d73000fbcdb931ab90cafe21bf95b39417a52ff000ca9d02ba51c8a78877d1a1f47b70866f
-  data.tar.gz: 8513b6774ef3d745e7bbc8947f856608d13ade163ca658139c2992e923ad08d5ee00b99275cbfe762591182897b73db7bfc879fae8db7b8ce2f3ba1fea5ee235
+  metadata.gz: d9bff16dce3e4cef7f57d8afad8cf90fd995045a6da5412588fc019ac2e57fa4137628525c603ef4df259eec6bf40d748296619671713094ca7d8e7c824c0e78
+  data.tar.gz: 3f44c0c2783202e8f162d9d705f10061a7ca717f23a26026bbbcdb2cea214edd48c9a0458ec9a226a03eb823f3ec8f3d9a601526c01e277c24f4988bb0634521

data/README.md

@@ -1,26 +1,37 @@
 <img src="/docs/assets/images/logotype.svg" alt="RubyLLM" height="120" width="250">
 
-A delightful Ruby way to work with AI. No configuration madness, no complex callbacks, no handler hell – just beautiful, expressive Ruby code.
-
-<div style="display: flex; align-items: center; flex-wrap: wrap; margin-bottom: 1em">
-  <img src="https://upload.wikimedia.org/wikipedia/commons/4/4d/OpenAI_Logo.svg" alt="OpenAI" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Anthropic_logo.svg" alt="Anthropic" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Google_Gemini_logo.svg" alt="Google" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-color.svg" alt="Bedrock" height="40">
-  <img src="https://registry.npmmirror.com/@lobehub/icons-static-svg/latest/files/icons/bedrock-text.svg" alt="Bedrock" height="40" width="120">
-  &nbsp;&nbsp;
-  <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" alt="DeepSeek" height="40" width="120">
+**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">
+  &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;
 </div>
 
-<a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg" 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 class="badge-container">
+  <a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg" 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 [💬 Chat with Work](https://chatwithwork.com)
 
 ## The problem with AI libraries
 
@@ -28,17 +39,6 @@ Every AI provider comes with its own client library, its own response format, it
 
 RubyLLM fixes all that. One beautiful API for everything. One consistent format. Minimal dependencies — just Faraday and Zeitwerk. Because working with AI should be a joy, not a chore.
 
-## Features
-
-- 💬 **Chat** with OpenAI, Anthropic, Gemini, AWS Bedrock Anthropic, and DeepSeek models
-- 👁️ **Vision and Audio** understanding
-- 📄 **PDF Analysis** for analyzing documents
-- 🖼️ **Image generation** with DALL-E and other providers
-- 📊 **Embeddings** for vector search and semantic analysis
-- 🔧 **Tools** that let AI use your Ruby code
-- 🚂 **Rails integration** to persist chats and messages with ActiveRecord
-- 🌊 **Streaming** responses with proper Ruby patterns
-
 ## What makes it great
 
 ```ruby
@@ -85,142 +85,89 @@ end
 chat.with_tool(Weather).ask "What's the weather in Berlin? (52.5200, 13.4050)"
 ```
 
+## Core Capabilities
+
+*   💬 **Unified Chat:** Converse with models from OpenAI, Anthropic, Gemini, Bedrock, OpenRouter, DeepSeek, Ollama, or any OpenAI-compatible API using `RubyLLM.chat`.
+*   👁️ **Vision:** Analyze images within chats.
+*   🔊 **Audio:** Transcribe and understand audio content.
+*   📄 **PDF Analysis:** Extract information and summarize PDF documents.
+*   🖼️ **Image Generation:** Create images with `RubyLLM.paint`.
+*   📊 **Embeddings:** Generate text embeddings for vector search with `RubyLLM.embed`.
+*   🔧 **Tools (Function Calling):** Let AI models call your Ruby code using `RubyLLM::Tool`.
+*   🚂 **Rails Integration:** Easily persist chats, messages, and tool calls using `acts_as_chat` and `acts_as_message`.
+*   🌊 **Streaming:** Process responses in real-time with idiomatic Ruby blocks.
+
 ## Installation
 
+Add to your Gemfile:
 ```ruby
-# In your Gemfile
 gem 'ruby_llm'
-
-# Then run
-bundle install
-
-# Or install it yourself
-gem install ruby_llm
 ```
+Then `bundle install`.
 
-Configure with your API keys:
-
+Configure your API keys (using environment variables is recommended):
 ```ruby
+# config/initializers/ruby_llm.rb or similar
 RubyLLM.configure do |config|
   config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
-  config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
-  config.gemini_api_key = ENV.fetch('GEMINI_API_KEY', nil)
-  config.deepseek_api_key = ENV.fetch('DEEPSEEK_API_KEY', nil)
-
-  # Bedrock
-  config.bedrock_api_key = ENV.fetch('AWS_ACCESS_KEY_ID', nil)
-  config.bedrock_secret_key = ENV.fetch('AWS_SECRET_ACCESS_KEY', nil)
-  config.bedrock_region = ENV.fetch('AWS_REGION', nil)
-  config.bedrock_session_token = ENV.fetch('AWS_SESSION_TOKEN', nil)
+  # Add keys ONLY for providers you intend to use
+  # config.anthropic_api_key = ENV.fetch('ANTHROPIC_API_KEY', nil)
+  # ... see Configuration guide for all options ...
 end
 ```
+See the [Installation Guide](https://rubyllm.com/installation) for full details.
 
-## Have great conversations
-
-```ruby
-# Start a chat with the default model (gpt-4.1-nano)
-chat = RubyLLM.chat
-
-# Or specify what you want
-chat = RubyLLM.chat(model: 'claude-3-7-sonnet-20250219')
-
-# Simple questions just work
-chat.ask "What's the difference between attr_reader and attr_accessor?"
-
-# Multi-turn conversations are seamless
-chat.ask "Could you give me an example?"
-
-# Stream responses in real-time
-chat.ask "Tell me a story about a Ruby programmer" do |chunk|
-  print chunk.content
-end
-
-# Set personality or behavior with instructions (aka system prompts)
-chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
-
-# Understand content in multiple forms
-chat.ask "Compare these diagrams", with: { image: ["diagram1.png", "diagram2.png"] }
-chat.ask "Summarize this document", with: { pdf: "contract.pdf" }
-chat.ask "What's being said?", with: { audio: "meeting.wav" }
-
-# Need a different model mid-conversation? No problem
-chat.with_model('gemini-2.0-flash').ask "What's your favorite algorithm?"
-```
+## Rails Integration
 
-## Rails integration that makes sense
+Add persistence to your chat models effortlessly:
 
 ```ruby
 # app/models/chat.rb
 class Chat < ApplicationRecord
-  acts_as_chat
-
-  # Works great with Turbo
-  broadcasts_to ->(chat) { "chat_#{chat.id}" }
+  acts_as_chat # Automatically saves messages & tool calls
+  # ... your other model logic ...
 end
 
 # app/models/message.rb
 class Message < ApplicationRecord
   acts_as_message
+  # ...
 end
 
-# app/models/tool_call.rb
+# app/models/tool_call.rb (if using tools)
 class ToolCall < ApplicationRecord
   acts_as_tool_call
+  # ...
 end
 
-# In a background job
-chat = Chat.create! model_id: "gpt-4.1-nano"
-
-# Set personality or behavior with instructions (aka system prompts) - they're persisted too!
-chat.with_instructions "You are a friendly Ruby expert who loves to help beginners"
-
-chat.ask("What's your favorite Ruby gem?") do |chunk|
-  Turbo::StreamsChannel.broadcast_append_to(
-    chat,
-    target: "response",
-    partial: "messages/chunk",
-    locals: { chunk: chunk }
-  )
-end
-
-# That's it - chat history is automatically saved
+# Now interacting with a Chat record persists the conversation:
+chat_record = Chat.create!(model_id: "gpt-4.1-nano")
+chat_record.ask("Explain Active Record callbacks.") # User & Assistant messages saved
 ```
-
-## Creating tools is a breeze
-
-```ruby
-class Search < RubyLLM::Tool
-  description "Searches a knowledge base"
-
-  param :query, desc: "The search query"
-  param :limit, type: :integer, desc: "Max results", required: false
-
-  def execute(query:, limit: 5)
-    # Your search logic here
-    Document.search(query).limit(limit).map(&:title)
-  end
-end
-
-# Let the AI use it
-chat.with_tool(Search).ask "Find documents about Ruby 3.3 features"
-```
-
-## Learn more
-
-Check out the guides at https://rubyllm.com for deeper dives into conversations with tools, streaming responses, embedding generations, and more.
+Check the [Rails Integration Guide](https://rubyllm.com/guides/rails) for more.
+
+## Learn More
+
+Dive deeper with the official documentation:
+
+-   [Installation](https://rubyllm.com/installation)
+-   [Configuration](https://rubyllm.com/configuration)
+-   **Guides:**
+    -   [Getting Started](https://rubyllm.com/guides/getting-started)
+    -   [Chatting with AI Models](https://rubyllm.com/guides/chat)
+    -   [Using Tools](https://rubyllm.com/guides/tools)
+    -   [Streaming Responses](https://rubyllm.com/guides/streaming)
+    -   [Rails Integration](https://rubyllm.com/guides/rails)
+    -   [Image Generation](https://rubyllm.com/guides/image-generation)
+    -   [Embeddings](https://rubyllm.com/guides/embeddings)
+    -   [Working with Models](https://rubyllm.com/guides/models)
+    -   [Error Handling](https://rubyllm.com/guides/error-handling)
+    -   [Available Models](https://rubyllm.com/guides/available-models)
 
 ## Contributing
 
-We welcome contributions to RubyLLM!
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions on how to:
-- Run the test suite
-- Add new features
-- Update documentation
-- Re-record VCR cassettes when needed
-
-We appreciate your help making RubyLLM better!
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on setup, testing, and contribution guidelines.
 
 ## License
 
-Released under the MIT License.
+Released under the MIT License.

data/lib/ruby_llm/active_record/acts_as.rb

@@ -3,8 +3,8 @@
 module RubyLLM
   module ActiveRecord
     # Adds chat and message persistence capabilities to ActiveRecord models.
-    # Provides a clean interface for storing chat history and message metadata
-    # in your database.
+    # Provides a clean interface for storing chat history, message metadata,
+    # and attachments in your database.
     module ActsAs
       extend ActiveSupport::Concern
 
@@ -20,37 +20,55 @@ module RubyLLM
                    class_name: @message_class,
                    dependent: :destroy
 
-          delegate :complete,
-                   :add_message,
+          delegate :add_message,
                    to: :to_llm
         end
 
-        def acts_as_message(chat_class: 'Chat', tool_call_class: 'ToolCall', touch_chat: false) # rubocop:disable Metrics/MethodLength
+        def acts_as_message(chat_class: 'Chat',
+                            chat_foreign_key: nil,
+                            tool_call_class: 'ToolCall',
+                            tool_call_foreign_key: nil,
+                            touch_chat: false)
           include MessageMethods
 
           @chat_class = chat_class.to_s
+          @chat_foreign_key = chat_foreign_key || ActiveSupport::Inflector.foreign_key(@chat_class)
+
           @tool_call_class = tool_call_class.to_s
+          @tool_call_foreign_key = tool_call_foreign_key || ActiveSupport::Inflector.foreign_key(@tool_call_class)
+
+          belongs_to :chat,
+                     class_name: @chat_class,
+                     foreign_key: @chat_foreign_key,
+                     inverse_of: :messages,
+                     touch: touch_chat
 
-          belongs_to :chat, class_name: @chat_class, touch: touch_chat
-          has_many :tool_calls, class_name: @tool_call_class, dependent: :destroy
+          has_many :tool_calls,
+                   class_name: @tool_call_class,
+                   dependent: :destroy
 
           belongs_to :parent_tool_call,
                      class_name: @tool_call_class,
-                     foreign_key: 'tool_call_id',
+                     foreign_key: @tool_call_foreign_key,
                      optional: true,
                      inverse_of: :result
 
           delegate :tool_call?, :tool_result?, :tool_results, to: :to_llm
         end
 
-        def acts_as_tool_call(message_class: 'Message')
+        def acts_as_tool_call(message_class: 'Message', message_foreign_key: nil, result_foreign_key: nil)
           @message_class = message_class.to_s
+          @message_foreign_key = message_foreign_key || ActiveSupport::Inflector.foreign_key(@message_class)
+          @result_foreign_key = result_foreign_key || ActiveSupport::Inflector.foreign_key(name)
 
-          belongs_to :message, class_name: @message_class
+          belongs_to :message,
+                     class_name: @message_class,
+                     foreign_key: @message_foreign_key,
+                     inverse_of: :tool_calls
 
           has_one :result,
                   class_name: @message_class,
-                  foreign_key: 'tool_call_id',
+                  foreign_key: @result_foreign_key,
                   inverse_of: :parent_tool_call,
                   dependent: :nullify
         end
@@ -68,6 +86,7 @@ module RubyLLM
 
       def to_llm
         @chat ||= RubyLLM.chat(model: model_id)
+        @chat.reset_messages!
 
         # Load existing messages into chat
         messages.each do |msg|
@@ -94,44 +113,72 @@ module RubyLLM
         self
       end
 
-      def with_tool(tool)
-        to_llm.with_tool(tool)
+      def with_tool(...)
+        to_llm.with_tool(...)
         self
       end
 
-      def with_tools(*tools)
-        to_llm.with_tools(*tools)
+      def with_tools(...)
+        to_llm.with_tools(...)
         self
       end
 
-      def with_model(model_id, provider: nil)
-        to_llm.with_model(model_id, provider: provider)
+      def with_model(...)
+        to_llm.with_model(...)
         self
       end
 
-      def with_temperature(temperature)
-        to_llm.with_temperature(temperature)
+      def with_temperature(...)
+        to_llm.with_temperature(...)
         self
       end
 
-      def on_new_message(&)
-        to_llm.on_new_message(&)
+      def on_new_message(...)
+        to_llm.on_new_message(...)
         self
       end
 
-      def on_end_message(&)
-        to_llm.on_end_message(&)
+      def on_end_message(...)
+        to_llm.on_end_message(...)
         self
       end
 
-      def ask(message, &)
-        message = { role: :user, content: message }
-        messages.create!(**message)
-        to_llm.complete(&)
+      def create_user_message(content, with: nil)
+        message_record = messages.create!(
+          role: :user,
+          content: content
+        )
+
+        if with.present?
+          files = Array(with).reject(&:blank?)
+
+          if files.any? && files.first.is_a?(ActionDispatch::Http::UploadedFile)
+            message_record.attachments.attach(files)
+          else
+            attach_files(message_record, process_attachments(with))
+          end
+        end
+
+        message_record
+      end
+
+      def ask(message, with: nil, &)
+        create_user_message(message, with:)
+        complete(&)
       end
 
       alias say ask
 
+      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
+        raise e
+      end
+
       private
 
       def persist_new_message
@@ -141,22 +188,23 @@ module RubyLLM
         )
       end
 
-      def persist_message_completion(message) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      def persist_message_completion(message)
         return unless message
 
         if message.tool_call_id
-          tool_call_id = self.class.tool_call_class.constantize.find_by(tool_call_id: message.tool_call_id).id
+          tool_call_id = self.class.tool_call_class.constantize.find_by(tool_call_id: message.tool_call_id)&.id
         end
 
         transaction do
-          @message.update!(
+          @message.update(
             role: message.role,
             content: message.content,
             model_id: message.model_id,
-            tool_call_id: tool_call_id,
             input_tokens: message.input_tokens,
             output_tokens: message.output_tokens
           )
+          @message.write_attribute(@message.class.tool_call_foreign_key, tool_call_id) if tool_call_id
+          @message.save!
           persist_tool_calls(message.tool_calls) if message.tool_calls.present?
         end
       end
@@ -168,6 +216,86 @@ module RubyLLM
           @message.tool_calls.create!(**attributes)
         end
       end
+
+      def process_attachments(attachments) # rubocop:disable Metrics/PerceivedComplexity
+        return {} if attachments.nil?
+
+        result = {}
+        files = Array(attachments)
+
+        files.each do |file|
+          content_type = if file.respond_to?(:content_type)
+                           file.content_type
+                         elsif file.is_a?(ActiveStorage::Attachment)
+                           file.blob.content_type
+                         else
+                           RubyLLM::MimeTypes.detect_from_path(file.to_s)
+                         end
+
+          if RubyLLM::MimeTypes.image?(content_type)
+            result[:image] ||= []
+            result[:image] << file
+          elsif RubyLLM::MimeTypes.audio?(content_type)
+            result[:audio] ||= []
+            result[:audio] << file
+          else
+            # Default to PDF for unknown types
+            result[:pdf] ||= []
+            result[:pdf] << file
+          end
+        end
+
+        result
+      end
+
+      def attach_files(message, attachments_hash)
+        return unless message.respond_to?(:attachments)
+
+        %i[image audio pdf].each do |type|
+          Array(attachments_hash[type]).each do |file_source|
+            attach_file(message, file_source)
+          end
+        end
+      end
+
+      def attach_file(message, file_source)
+        if file_source.to_s.match?(%r{^https?://})
+          # For URLs, create a special attachment that just stores the URL
+          content_type = RubyLLM::MimeTypes.detect_from_path(file_source.to_s)
+
+          # Create a minimal blob that just stores the URL
+          blob = ActiveStorage::Blob.create_and_upload!(
+            io: StringIO.new('URL Reference'),
+            filename: File.basename(file_source),
+            content_type: content_type,
+            metadata: { original_url: file_source.to_s }
+          )
+          message.attachments.attach(blob)
+        elsif file_source.respond_to?(:read)
+          # Handle various file source types
+          message.attachments.attach(
+            io: file_source,
+            filename: extract_filename(file_source),
+            content_type: RubyLLM::MimeTypes.detect_from_path(extract_filename(file_source))
+          ) # Already a file-like object
+        elsif file_source.is_a?(::ActiveStorage::Attachment)
+          # Copy from existing ActiveStorage attachment
+          message.attachments.attach(file_source.blob)
+        elsif file_source.is_a?(::ActiveStorage::Blob)
+          message.attachments.attach(file_source)
+        else
+          # Local file path
+          message.attachments.attach(
+            io: File.open(file_source),
+            filename: File.basename(file_source),
+            content_type: RubyLLM::MimeTypes.detect_from_path(file_source)
+          )
+        end
+      end
+
+      def extract_filename(file)
+        file.respond_to?(:original_filename) ? file.original_filename : 'attachment'
+      end
     end
 
     # Methods mixed into message models to handle serialization and
@@ -175,6 +303,10 @@ module RubyLLM
     module MessageMethods
       extend ActiveSupport::Concern
 
+      class_methods do
+        attr_reader :chat_class, :tool_call_class, :chat_foreign_key, :tool_call_foreign_key
+      end
+
       def to_llm
         RubyLLM::Message.new(
           role: role.to_sym,
@@ -204,8 +336,55 @@ module RubyLLM
         parent_tool_call&.tool_call_id
       end
 
-      def extract_content
-        content
+      def extract_content # rubocop:disable Metrics/PerceivedComplexity
+        return content unless respond_to?(:attachments) && attachments.attached?
+
+        content_obj = RubyLLM::Content.new(content)
+
+        # We need to keep tempfiles alive for the duration of the API call
+        @_tempfiles = []
+
+        attachments.each do |attachment|
+          attachment_data = if attachment.metadata&.key?('original_url')
+                              attachment.metadata['original_url']
+                            elsif defined?(ActiveJob) && caller.any? { |c| c.include?('active_job') }
+                              # We're in a background job - need to download the data
+                              temp_file = Tempfile.new([File.basename(attachment.filename.to_s, '.*'),
+                                                        File.extname(attachment.filename.to_s)])
+                              temp_file.binmode
+                              temp_file.write(attachment.download)
+                              temp_file.flush
+                              temp_file.rewind
+
+                              # Store the tempfile reference in the instance variable to prevent GC
+                              @_tempfiles << temp_file
+
+                              # Return the file object itself, not just the path
+                              temp_file
+                            else
+                              blob_path_for(attachment)
+                            end
+
+          if RubyLLM::MimeTypes.image?(attachment.content_type)
+            content_obj.add_image(attachment_data)
+          elsif RubyLLM::MimeTypes.audio?(attachment.content_type)
+            content_obj.add_audio(attachment_data)
+          elsif RubyLLM::MimeTypes.pdf?(attachment.content_type)
+            content_obj.add_pdf(attachment_data)
+          end
+        end
+
+        content_obj
+      end
+
+      private
+
+      def blob_path_for(attachment)
+        if Rails.application.routes.url_helpers.respond_to?(:rails_blob_path)
+          Rails.application.routes.url_helpers.rails_blob_path(attachment, only_path: true)
+        else
+          attachment.service_url
+        end
       end
     end
   end