ruby_llm 1.12.0 → 1.14.1

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',
@@ -60,6 +58,8 @@ module RubyLLM
         end
 
         def acts_as_tool_call(message_class: 'Message', message_foreign_key: nil, result_foreign_key: nil)
+          include RubyLLM::ActiveRecord::ToolCallMethods
+
           @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)
@@ -99,6 +99,7 @@ module RubyLLM
         ordered_messages.each do |msg|
           @chat.add_message(msg.to_llm)
         end
+        reapply_runtime_instructions(@chat)
 
         setup_persistence_callbacks
       end
@@ -111,6 +112,14 @@ module RubyLLM
         self
       end
 
+      def with_runtime_instructions(instructions, append: false, replace: nil)
+        append = append_instructions?(append:, replace:)
+        store_runtime_instruction(instructions, append:)
+
+        to_llm.with_instructions(instructions, append:, replace:)
+        self
+      end
+
       def with_tool(...)
         to_llm.with_tool(...)
         self
@@ -185,14 +194,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
 
@@ -267,6 +296,26 @@ module RubyLLM
         system_messages + non_system_messages
       end
 
+      def runtime_instructions
+        @runtime_instructions ||= []
+      end
+
+      def store_runtime_instruction(instructions, append:)
+        if append
+          runtime_instructions << instructions
+        else
+          @runtime_instructions = [instructions]
+        end
+      end
+
+      def reapply_runtime_instructions(chat)
+        return if runtime_instructions.empty?
+
+        first, *rest = runtime_instructions
+        chat.with_instructions(first)
+        rest.each { |instruction| chat.with_instructions(instruction, append: true) }
+      end
+
       def setup_persistence_callbacks
         return @chat if @chat.instance_variable_get(:@_persistence_callbacks_setup)
 
@@ -281,21 +330,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,
@@ -312,14 +353,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
 
@@ -363,6 +407,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

@@ -79,7 +79,8 @@ module RubyLLM
         model_record = model_association
         @chat ||= (context || RubyLLM).chat(
           model: model_record.model_id,
-          provider: model_record.provider.to_sym
+          provider: model_record.provider.to_sym,
+          assume_model_exists: assume_model_exists || false
         )
         @chat.reset_messages!
 
@@ -87,6 +88,7 @@ module RubyLLM
         ordered_messages.each do |msg|
           @chat.add_message(msg.to_llm)
         end
+        reapply_runtime_instructions(@chat)
 
         setup_persistence_callbacks
       end
@@ -99,6 +101,14 @@ module RubyLLM
         self
       end
 
+      def with_runtime_instructions(instructions, append: false, replace: nil)
+        append = append_instructions?(append:, replace:)
+        store_runtime_instruction(instructions, append:)
+
+        to_llm.with_instructions(instructions, append:, replace:)
+        self
+      end
+
       def with_tool(...)
         to_llm.with_tool(...)
         self
@@ -115,7 +125,7 @@ module RubyLLM
         self.assume_model_exists = assume_exists
         resolve_model_from_strings
         save!
-        to_llm.with_model(model.model_id, provider: model.provider.to_sym, assume_exists:)
+        to_llm.with_model(model_association.model_id, provider: model_association.provider.to_sym, assume_exists:)
         self
       end
 
@@ -178,22 +188,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)
 
-        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!
+        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.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
 
@@ -223,9 +243,10 @@ module RubyLLM
         if last.tool_call?
           last.destroy
         elsif last.tool_result?
-          tool_call_message = last.parent_tool_call.message
-          expected_results = tool_call_message.tool_calls.pluck(:id)
-          actual_results = tool_call_message.tool_results.pluck(:tool_call_id)
+          tool_call_message = last.parent_tool_call.message_association
+          expected_results = tool_call_message.tool_calls_association.pluck(:id)
+          fk_column = tool_call_message.class.reflections['tool_results'].foreign_key
+          actual_results = tool_call_message.tool_results.pluck(fk_column)
 
           if expected_results.sort != actual_results.sort
             tool_call_message.tool_results.each(&:destroy)
@@ -278,6 +299,26 @@ module RubyLLM
         system_messages + non_system_messages
       end
 
+      def runtime_instructions
+        @runtime_instructions ||= []
+      end
+
+      def store_runtime_instruction(instructions, append:)
+        if append
+          runtime_instructions << instructions
+        else
+          @runtime_instructions = [instructions]
+        end
+      end
+
+      def reapply_runtime_instructions(chat)
+        return if runtime_instructions.empty?
+
+        first, *rest = runtime_instructions
+        chat.with_instructions(first)
+        rest.each { |instruction| chat.with_instructions(instruction, append: true) }
+      end
+
       def persist_new_message
         @message = messages_association.create!(role: :assistant, content: '')
       end
@@ -323,15 +364,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
 
@@ -376,16 +417,33 @@ module RubyLLM
 
         attachment = source.is_a?(RubyLLM::Attachment) ? source : RubyLLM::Attachment.new(source)
 
-        {
-          io: StringIO.new(attachment.content),
-          filename: attachment.filename,
-          content_type: attachment.mime_type
-        }
+        if attachment.active_storage?
+          case attachment.source
+          when ActiveStorage::Blob then attachment.source
+          when ActiveStorage::Attached::One, ActiveStorage::Attached::Many then attachment.source.blobs
+          end
+        else
+          {
+            io: StringIO.new(attachment.content),
+            filename: attachment.filename,
+            content_type: attachment.mime_type
+          }
+        end
       rescue StandardError => e
         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
         content_raw = nil

data/lib/ruby_llm/active_record/message_methods.rb

@@ -5,6 +5,7 @@ module RubyLLM
     # Methods mixed into message models.
     module MessageMethods
       extend ActiveSupport::Concern
+      include PayloadHelpers
 
       class_methods do
         attr_reader :chat_class, :tool_call_class, :chat_foreign_key, :tool_call_foreign_key
@@ -39,6 +40,22 @@ module RubyLLM
         )
       end
 
+      def to_partial_path
+        partial_prefix = self.class.name.underscore.pluralize
+        role_partial = if to_llm.tool_call?
+                         'tool_calls'
+                       elsif role.to_s == 'tool'
+                         'tool'
+                       else
+                         role.to_s.presence || 'assistant'
+                       end
+        "#{partial_prefix}/#{role_partial}"
+      end
+
+      def tool_error_message
+        payload_error_message(content)
+      end
+
       private
 
       def thinking_text_value

data/lib/ruby_llm/active_record/model_methods.rb

@@ -77,7 +77,7 @@ module RubyLLM
       delegate :supports?, :supports_vision?, :supports_functions?, :type,
                :input_price_per_million, :output_price_per_million,
                :function_calling?, :structured_output?, :batch?,
-               :reasoning?, :citations?, :streaming?, :provider_class,
+               :reasoning?, :citations?, :streaming?, :provider_class, :label,
                to: :to_llm
     end
   end

data/lib/ruby_llm/active_record/payload_helpers.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Shared helpers for parsing serialized payloads on ActiveRecord-backed models.
+    module PayloadHelpers
+      private
+
+      def payload_error_message(value)
+        payload = parse_payload(value)
+        return unless payload.is_a?(Hash)
+
+        payload['error'] || payload[:error]
+      end
+
+      def parse_payload(value)
+        return value if value.is_a?(Hash) || value.is_a?(Array)
+        return if value.blank?
+
+        JSON.parse(value)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/ruby_llm/active_record/tool_call_methods.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module ActiveRecord
+    # Methods mixed into tool call models.
+    module ToolCallMethods
+      extend ActiveSupport::Concern
+      include PayloadHelpers
+
+      def tool_error_message
+        payload_error_message(arguments)
+      end
+    end
+  end
+end

data/lib/ruby_llm/agent.rb

@@ -1,11 +1,14 @@
 # frozen_string_literal: true
 
 require 'erb'
+require 'forwardable'
 require 'pathname'
+require 'ruby_llm/schema'
 
 module RubyLLM
   # Base class for simple, class-configured agents.
   class Agent
+    extend Forwardable
     include Enumerable
 
     class << self
@@ -118,6 +121,7 @@ module RubyLLM
         input_values, = partition_inputs(kwargs)
         record = resolved_chat_model.find(id)
         apply_configuration(record, input_values:, persist_instructions: false)
+
         record
       end
 
@@ -126,6 +130,7 @@ module RubyLLM
 
         input_values, = partition_inputs(kwargs)
         record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
+        apply_assume_model_exists(record)
         runtime = runtime_context(chat: record, inputs: input_values)
         instructions_value = resolved_instructions_value(record, runtime, inputs: input_values)
         return record if instructions_value.nil?
@@ -136,7 +141,10 @@ module RubyLLM
 
       def render_prompt(name, chat:, inputs:, locals:)
         path = prompt_path_for(name)
-        return nil unless File.exist?(path)
+        unless File.exist?(path)
+          raise RubyLLM::PromptNotFoundError,
+                "Prompt file not found for #{self}: #{path}. Create the file or use inline instructions."
+        end
 
         resolved_locals = resolve_prompt_locals(locals, runtime: runtime_context(chat:, inputs:), chat:, inputs:)
         ERB.new(File.read(path)).result_with_hash(resolved_locals)
@@ -175,7 +183,10 @@ module RubyLLM
         value = resolved_instructions_value(chat_object, runtime, inputs:)
         return if value.nil?
 
-        instruction_target(chat_object, persist:).with_instructions(value)
+        target = instruction_target(chat_object, persist:)
+        return target.with_runtime_instructions(value) if use_runtime_instructions?(target, persist:)
+
+        target.with_instructions(value)
       end
 
       def apply_tools(llm_chat, runtime)
@@ -202,20 +213,40 @@ module RubyLLM
       end
 
       def apply_schema(llm_chat, runtime)
-        value = evaluate(schema, runtime)
+        value = resolved_schema_value(runtime)
         llm_chat.with_schema(value) if value
       end
 
+      def resolved_schema_value(runtime)
+        value = schema
+        return value unless value.is_a?(Proc)
+
+        evaluate(value, runtime)
+      rescue NoMethodError => e
+        raise unless e.receiver.equal?(runtime)
+
+        RubyLLM::Schema.create(&value)
+      end
+
       def llm_chat_for(chat_object)
+        apply_assume_model_exists(chat_object)
         chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
       end
 
+      def apply_assume_model_exists(chat_object)
+        return unless chat_kwargs.key?(:assume_model_exists) &&
+                      resolved_chat_model &&
+                      chat_object.is_a?(resolved_chat_model)
+
+        chat_object.assume_model_exists = chat_kwargs[:assume_model_exists]
+      end
+
       def evaluate(value, runtime)
         value.is_a?(Proc) ? runtime.instance_exec(&value) : value
       end
 
       def resolved_instructions_value(chat_object, runtime, inputs:)
-        value = evaluate(instructions, runtime)
+        value = evaluate(@instructions, runtime)
         return value unless prompt_instruction?(value)
 
         runtime.prompt(
@@ -232,10 +263,20 @@ module RubyLLM
         if persist || !chat_object.respond_to?(:to_llm)
           chat_object
         else
-          chat_object.to_llm
+          runtime_instruction_target(chat_object)
         end
       end
 
+      def runtime_instruction_target(chat_object)
+        return chat_object if chat_object.respond_to?(:with_runtime_instructions)
+
+        chat_object.to_llm
+      end
+
+      def use_runtime_instructions?(target, persist:)
+        !persist && target.respond_to?(:with_runtime_instructions)
+      end
+
       def resolve_prompt_locals(locals, runtime:, chat:, inputs:)
         base = { chat: chat }.merge(inputs)
         evaluated = locals.each_with_object({}) do |(key, value), acc|
@@ -316,8 +357,9 @@ module RubyLLM
 
     attr_reader :chat
 
-    delegate :ask, :say, :complete, :add_message, :messages,
-             :on_new_message, :on_end_message, :on_tool_call, :on_tool_result, :each,
-             to: :chat
+    def_delegators :chat, :model, :messages, :tools, :params, :headers, :schema, :ask, :say, :with_tool, :with_tools,
+                   :with_model, :with_temperature, :with_thinking, :with_context, :with_params, :with_headers,
+                   :with_schema, :on_new_message, :on_end_message, :on_tool_call, :on_tool_result, :each, :complete,
+                   :add_message, :reset_messages!
   end
 end