ruby_llm 1.11.0 → 1.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6cabf287dc7cd62616a9061131291f404c391be59f1468ccdb3b7f7cb9d2cb5
-  data.tar.gz: bf1123d01a7ddadcbfde46a2ffb6e378928bcbcc0b1cdb0b927b7905f0534c12
+  metadata.gz: 6f2aa1f16058fca83243f2b098b0a3f454fb9383e410a00b04955cd5b48cbf54
+  data.tar.gz: fb4591fe16b50449dc1baf90f77a2b92baa986a51b9573f5c0b79dc231d9a9b9
 SHA512:
-  metadata.gz: 12c1f267367279716c8e5e7fe6ef44327e4921b4e24516313f99954775a4c51d7e874d42184f466f8eb71ebe4f814b14a93b63b043c46096e7be4d804a15fc76
-  data.tar.gz: dd2d797e49e3c1741108b63f191ccc3252d1fec1868851802ceb33b65afec4609498cbdb8ee516800e48f04220fdd4179b43abb645177e8ed14ea25c1036916d
+  metadata.gz: 687200d2c127d604e0bbff56c888ef5bb5ab2938b585ec2f8959f77b74ad35ae0d0dbad588068ccccd3219ab0aa4208dbc47b8436606c7b12ec1de10cf2928c2
+  data.tar.gz: 9aab7e7a79aa98b2772e4a01f4269c17a1969755276fde9b0fb4b3311a81dd4ff3a4a1e4e4c4a1f0fa863a162caaa4f3d3cd05cc044cfc5116ceaaa878963737

data/README.md

@@ -95,6 +95,17 @@ end
 chat.with_tool(Weather).ask "What's the weather in Berlin?"
 ```
 
+```ruby
+# Define an agent with instructions + tools
+class WeatherAssistant < RubyLLM::Agent
+  model "gpt-4.1-nano"
+  instructions "Be concise and always use tools for weather."
+  tools Weather
+end
+
+WeatherAssistant.new.ask "What's the weather in Berlin?"
+```
+
 ```ruby
 # Get structured output
 class ProductSchema < RubyLLM::Schema
@@ -118,6 +129,7 @@ response = chat.with_schema(ProductSchema).ask "Analyze this product", with: "pr
 * **Embeddings:** Generate embeddings with `RubyLLM.embed`
 * **Moderation:** Content safety with `RubyLLM.moderate`
 * **Tools:** Let AI call your Ruby methods
+* **Agents:** Reusable assistants with `RubyLLM::Agent`
 * **Structured output:** JSON schemas that just work
 * **Streaming:** Real-time responses with blocks
 * **Rails:** ActiveRecord integration with `acts_as_chat`

data/lib/ruby_llm/active_record/acts_as.rb

@@ -53,8 +53,6 @@ module RubyLLM
                      foreign_key: model_foreign_key,
                      optional: true
 
-          delegate :add_message, to: :to_llm
-
           define_method :messages_association do
             send(messages_association_name)
           end

data/lib/ruby_llm/active_record/acts_as_legacy.rb

@@ -18,8 +18,6 @@ module RubyLLM
                    class_name: @message_class,
                    inverse_of: :chat,
                    dependent: :destroy
-
-          delegate :add_message, to: :to_llm
         end
 
         def acts_as_message(chat_class: 'Chat',
@@ -95,19 +93,19 @@ module RubyLLM
                   end
         @chat.reset_messages!
 
-        messages.each do |msg|
+        ordered_messages = order_messages_for_llm(messages.to_a)
+        ordered_messages.each do |msg|
           @chat.add_message(msg.to_llm)
         end
 
         setup_persistence_callbacks
       end
 
-      def with_instructions(instructions, replace: false)
-        transaction do
-          messages.where(role: :system).destroy_all if replace
-          messages.create!(role: :system, content: instructions)
-        end
-        to_llm.with_instructions(instructions)
+      def with_instructions(instructions, append: false, replace: nil)
+        append = append_instructions?(append:, replace:)
+        persist_system_instruction(instructions, append:)
+
+        to_llm.with_instructions(instructions, append:, replace:)
         self
       end
 
@@ -185,14 +183,34 @@ module RubyLLM
         self
       end
 
-      def create_user_message(content, with: nil)
-        message_record = messages.create!(role: :user, content: content)
-        persist_content(message_record, with) if with.present?
+      def add_message(message_or_attributes)
+        llm_message = message_or_attributes.is_a?(RubyLLM::Message) ? message_or_attributes : RubyLLM::Message.new(message_or_attributes)
+        content, attachments_to_persist = prepare_content_for_storage(llm_message.content)
+
+        attrs = { role: llm_message.role, content: }
+        tool_call_foreign_key = messages.klass.tool_call_foreign_key
+        if llm_message.tool_call_id && tool_call_foreign_key
+          tool_call_id = find_tool_call_id(llm_message.tool_call_id)
+          attrs[tool_call_foreign_key] = tool_call_id if tool_call_id
+        end
+
+        message_record = messages.create!(attrs)
+        persist_content(message_record, attachments_to_persist) if attachments_to_persist.present?
+        persist_tool_calls(llm_message.tool_calls, message_record:) if llm_message.tool_calls.present?
+
         message_record
       end
 
-      def ask(message, with: nil, &)
-        create_user_message(message, with:)
+      def create_user_message(content, with: nil)
+        RubyLLM.logger.warn(
+          '`create_user_message` is deprecated and will be removed in RubyLLM 2.0. ' \
+          'Use `add_message(role: :user, content: ...)` instead.'
+        )
+        add_message(role: :user, content: build_content(content, with))
+      end
+
+      def ask(message = nil, with: nil, &)
+        add_message(role: :user, content: build_content(message, with))
         complete(&)
       end
 
@@ -233,6 +251,40 @@ module RubyLLM
         end
       end
 
+      def replace_persisted_system_instructions(instructions)
+        system_messages = messages.where(role: :system).order(:id).to_a
+
+        if system_messages.empty?
+          messages.create!(role: :system, content: instructions)
+          return
+        end
+
+        primary_message = system_messages.shift
+        primary_message.update!(content: instructions) if primary_message.content != instructions
+        system_messages.each(&:destroy!)
+      end
+
+      def append_instructions?(append:, replace:)
+        return append if replace.nil?
+
+        append || (replace == false)
+      end
+
+      def persist_system_instruction(instructions, append:)
+        transaction do
+          if append
+            messages.create!(role: :system, content: instructions)
+          else
+            replace_persisted_system_instructions(instructions)
+          end
+        end
+      end
+
+      def order_messages_for_llm(messages)
+        system_messages, non_system_messages = messages.partition { |msg| msg.role.to_s == 'system' }
+        system_messages + non_system_messages
+      end
+
       def setup_persistence_callbacks
         return @chat if @chat.instance_variable_get(:@_persistence_callbacks_setup)
 
@@ -247,21 +299,13 @@ module RubyLLM
         @message = messages.create!(role: :assistant, content: '')
       end
 
-      def persist_message_completion(message) # rubocop:disable Metrics/PerceivedComplexity
+      def persist_message_completion(message)
         return unless message
 
         tool_call_id = find_tool_call_id(message.tool_call_id) if message.tool_call_id
 
         transaction do
-          content = message.content
-          attachments_to_persist = nil
-
-          if content.is_a?(RubyLLM::Content)
-            attachments_to_persist = content.attachments if content.attachments.any?
-            content = content.text
-          elsif content.is_a?(Hash) || content.is_a?(Array)
-            content = content.to_json
-          end
+          content, attachments_to_persist = prepare_content_for_storage(message.content)
 
           @message.update!(
             role: message.role,
@@ -278,14 +322,17 @@ module RubyLLM
         end
       end
 
-      def persist_tool_calls(tool_calls)
-        supports_thought_signature = tool_calls.klass.column_names.include?('thought_signature')
+      def persist_tool_calls(tool_calls, message_record: @message)
+        tool_call_assoc = message_record.respond_to?(:tool_calls) ? message_record.tool_calls : nil
+        return unless tool_call_assoc
+
+        supports_thought_signature = tool_call_assoc.klass.column_names.include?('thought_signature')
 
         tool_calls.each_value do |tool_call|
           attributes = tool_call.to_h
           attributes.delete(:thought_signature) unless supports_thought_signature
           attributes[:tool_call_id] = attributes.delete(:id)
-          @message.tool_calls.create!(**attributes)
+          tool_call_assoc.create!(**attributes)
         end
       end
 
@@ -329,6 +376,29 @@ module RubyLLM
         RubyLLM.logger.warn "Failed to process attachment #{source}: #{e.message}"
         nil
       end
+
+      def build_content(message, attachments)
+        return message if content_like?(message)
+
+        RubyLLM::Content.new(message, attachments)
+      end
+
+      def content_like?(object)
+        object.is_a?(RubyLLM::Content) || object.is_a?(RubyLLM::Content::Raw)
+      end
+
+      def prepare_content_for_storage(content)
+        attachments = nil
+
+        if content.is_a?(RubyLLM::Content)
+          attachments = content.attachments if content.attachments.any?
+          [content.text, attachments]
+        elsif content.is_a?(Hash) || content.is_a?(Array)
+          [content.to_json, attachments]
+        else
+          [content, attachments]
+        end
+      end
     end
 
     # Methods mixed into message models.

data/lib/ruby_llm/active_record/chat_methods.rb

@@ -83,19 +83,19 @@ module RubyLLM
         )
         @chat.reset_messages!
 
-        messages_association.each do |msg|
+        ordered_messages = order_messages_for_llm(messages_association.to_a)
+        ordered_messages.each do |msg|
           @chat.add_message(msg.to_llm)
         end
 
         setup_persistence_callbacks
       end
 
-      def with_instructions(instructions, replace: false)
-        transaction do
-          messages_association.where(role: :system).destroy_all if replace
-          messages_association.create!(role: :system, content: instructions)
-        end
-        to_llm.with_instructions(instructions)
+      def with_instructions(instructions, append: false, replace: nil)
+        append = append_instructions?(append:, replace:)
+        persist_system_instruction(instructions, append:)
+
+        to_llm.with_instructions(instructions, append:, replace:)
         self
       end
 
@@ -178,22 +178,32 @@ module RubyLLM
         self
       end
 
-      def create_user_message(content, with: nil)
-        content_text, attachments, content_raw = prepare_content_for_storage(content)
+      def add_message(message_or_attributes)
+        llm_message = message_or_attributes.is_a?(RubyLLM::Message) ? message_or_attributes : RubyLLM::Message.new(message_or_attributes)
+        content_text, attachments, content_raw = prepare_content_for_storage(llm_message.content)
+
+        attrs = { role: llm_message.role, content: content_text }
+        parent_tool_call_assoc = messages_association.klass.reflect_on_association(:parent_tool_call)
+        if parent_tool_call_assoc && llm_message.tool_call_id
+          tool_call_id = find_tool_call_id(llm_message.tool_call_id)
+          attrs[parent_tool_call_assoc.foreign_key] = tool_call_id if tool_call_id
+        end
 
-        message_record = messages_association.build(role: :user)
-        message_record.content = content_text
-        message_record.content_raw = content_raw if message_record.respond_to?(:content_raw=)
-        message_record.save!
+        message_record = messages_association.create!(attrs)
+        message_record.update!(content_raw:) if message_record.respond_to?(:content_raw=)
 
-        persist_content(message_record, with) if with.present?
         persist_content(message_record, attachments) if attachments.present?
+        persist_tool_calls(llm_message.tool_calls, message_record:) if llm_message.tool_calls.present?
 
         message_record
       end
 
-      def ask(message, with: nil, &)
-        create_user_message(message, with:)
+      def create_user_message(content, with: nil)
+        add_message(role: :user, content: build_content(content, with))
+      end
+
+      def ask(message = nil, with: nil, &)
+        add_message(role: :user, content: build_content(message, with))
         complete(&)
       end
 
@@ -244,6 +254,40 @@ module RubyLLM
         @chat
       end
 
+      def replace_persisted_system_instructions(instructions)
+        system_messages = messages_association.where(role: :system).order(:id).to_a
+
+        if system_messages.empty?
+          messages_association.create!(role: :system, content: instructions)
+          return
+        end
+
+        primary_message = system_messages.shift
+        primary_message.update!(content: instructions) if primary_message.content != instructions
+        system_messages.each(&:destroy!)
+      end
+
+      def append_instructions?(append:, replace:)
+        return append if replace.nil?
+
+        append || (replace == false)
+      end
+
+      def persist_system_instruction(instructions, append:)
+        transaction do
+          if append
+            messages_association.create!(role: :system, content: instructions)
+          else
+            replace_persisted_system_instructions(instructions)
+          end
+        end
+      end
+
+      def order_messages_for_llm(messages)
+        system_messages, non_system_messages = messages.partition { |msg| msg.role.to_s == 'system' }
+        system_messages + non_system_messages
+      end
+
       def persist_new_message
         @message = messages_association.create!(role: :assistant, content: '')
       end
@@ -289,15 +333,15 @@ module RubyLLM
       end
       # rubocop:enable Metrics/PerceivedComplexity
 
-      def persist_tool_calls(tool_calls)
-        tool_call_klass = @message.tool_calls_association.klass
+      def persist_tool_calls(tool_calls, message_record: @message)
+        tool_call_klass = message_record.tool_calls_association.klass
         supports_thought_signature = tool_call_klass.column_names.include?('thought_signature')
 
         tool_calls.each_value do |tool_call|
           attributes = tool_call.to_h
           attributes.delete(:thought_signature) unless supports_thought_signature
           attributes[:tool_call_id] = attributes.delete(:id)
-          @message.tool_calls_association.create!(**attributes)
+          message_record.tool_calls_association.create!(**attributes)
         end
       end
 
@@ -352,6 +396,16 @@ module RubyLLM
         nil
       end
 
+      def build_content(message, attachments)
+        return message if content_like?(message)
+
+        RubyLLM::Content.new(message, attachments)
+      end
+
+      def content_like?(object)
+        object.is_a?(RubyLLM::Content) || object.is_a?(RubyLLM::Content::Raw)
+      end
+
       def prepare_content_for_storage(content)
         attachments = nil
         content_raw = nil