ruby_llm 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6cabf287dc7cd62616a9061131291f404c391be59f1468ccdb3b7f7cb9d2cb5
-  data.tar.gz: bf1123d01a7ddadcbfde46a2ffb6e378928bcbcc0b1cdb0b927b7905f0534c12
+  metadata.gz: e8ff2f4da0c39e4909925217affa2b76908207e2c936a6dc05b56cffb2781863
+  data.tar.gz: 0eebb76434b049d4332a247e7581bb721d4dd86b0496be8655d15a4adcb42f65
 SHA512:
-  metadata.gz: 12c1f267367279716c8e5e7fe6ef44327e4921b4e24516313f99954775a4c51d7e874d42184f466f8eb71ebe4f814b14a93b63b043c46096e7be4d804a15fc76
-  data.tar.gz: dd2d797e49e3c1741108b63f191ccc3252d1fec1868851802ceb33b65afec4609498cbdb8ee516800e48f04220fdd4179b43abb645177e8ed14ea25c1036916d
+  metadata.gz: 95a3eb5a1c6a50c69dd8166044d99d77848fc8dcdd5d31b748e8303a3e8c5756cc86a8ce0220dd3c643bc0b32080f6c2125c79f5e437bb654725a119b4b4b601
+  data.tar.gz: 5efbd317193ca7f5e28df0a2d9bcc7ffd8a1740f40d29e7b872bed8a2ee910db376dc2dc890723b0c253718404993e55deab87356d414afdfd741d9392bd5e0f

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_legacy.rb

@@ -95,19 +95,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
 
@@ -233,6 +233,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)
 

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
 
@@ -244,6 +244,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

data/lib/ruby_llm/agent.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'pathname'
+
+module RubyLLM
+  # Base class for simple, class-configured agents.
+  class Agent
+    include Enumerable
+
+    class << self
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@chat_kwargs, (@chat_kwargs || {}).dup)
+        subclass.instance_variable_set(:@tools, (@tools || []).dup)
+        subclass.instance_variable_set(:@instructions, @instructions)
+        subclass.instance_variable_set(:@temperature, @temperature)
+        subclass.instance_variable_set(:@thinking, @thinking)
+        subclass.instance_variable_set(:@params, (@params || {}).dup)
+        subclass.instance_variable_set(:@headers, (@headers || {}).dup)
+        subclass.instance_variable_set(:@schema, @schema)
+        subclass.instance_variable_set(:@context, @context)
+        subclass.instance_variable_set(:@chat_model, @chat_model)
+        subclass.instance_variable_set(:@input_names, (@input_names || []).dup)
+      end
+
+      def model(model_id = nil, **options)
+        options[:model] = model_id unless model_id.nil?
+        @chat_kwargs = options
+      end
+
+      def tools(*tools, &block)
+        return @tools || [] if tools.empty? && !block_given?
+
+        @tools = block_given? ? block : tools.flatten
+      end
+
+      def instructions(text = nil, **prompt_locals, &block)
+        if text.nil? && prompt_locals.empty? && !block_given?
+          @instructions ||= { prompt: 'instructions', locals: {} }
+          return @instructions
+        end
+
+        @instructions = block || text || { prompt: 'instructions', locals: prompt_locals }
+      end
+
+      def temperature(value = nil)
+        return @temperature if value.nil?
+
+        @temperature = value
+      end
+
+      def thinking(effort: nil, budget: nil)
+        return @thinking if effort.nil? && budget.nil?
+
+        @thinking = { effort: effort, budget: budget }
+      end
+
+      def params(**params, &block)
+        return @params || {} if params.empty? && !block_given?
+
+        @params = block_given? ? block : params
+      end
+
+      def headers(**headers, &block)
+        return @headers || {} if headers.empty? && !block_given?
+
+        @headers = block_given? ? block : headers
+      end
+
+      def schema(value = nil, &block)
+        return @schema if value.nil? && !block_given?
+
+        @schema = block_given? ? block : value
+      end
+
+      def context(value = nil)
+        return @context if value.nil?
+
+        @context = value
+      end
+
+      def chat_model(value = nil)
+        return @chat_model if value.nil?
+
+        @chat_model = value
+        remove_instance_variable(:@resolved_chat_model) if instance_variable_defined?(:@resolved_chat_model)
+      end
+
+      def inputs(*names)
+        return @input_names || [] if names.empty?
+
+        @input_names = names.flatten.map(&:to_sym)
+      end
+
+      def chat_kwargs
+        @chat_kwargs || {}
+      end
+
+      def chat(**kwargs)
+        input_values, chat_options = partition_inputs(kwargs)
+        chat = RubyLLM.chat(**chat_kwargs, **chat_options)
+        apply_configuration(chat, input_values:, persist_instructions: true)
+        chat
+      end
+
+      def create(**kwargs)
+        with_rails_chat_record(:create, **kwargs)
+      end
+
+      def create!(**kwargs)
+        with_rails_chat_record(:create!, **kwargs)
+      end
+
+      def find(id, **kwargs)
+        raise ArgumentError, 'chat_model must be configured to use find' unless resolved_chat_model
+
+        input_values, = partition_inputs(kwargs)
+        record = resolved_chat_model.find(id)
+        apply_configuration(record, input_values:, persist_instructions: false)
+        record
+      end
+
+      def sync_instructions!(chat_or_id, **kwargs)
+        raise ArgumentError, 'chat_model must be configured to use sync_instructions!' unless resolved_chat_model
+
+        input_values, = partition_inputs(kwargs)
+        record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
+        runtime = runtime_context(chat: record, inputs: input_values)
+        instructions_value = resolved_instructions_value(record, runtime, inputs: input_values)
+        return record if instructions_value.nil?
+
+        record.with_instructions(instructions_value)
+        record
+      end
+
+      def render_prompt(name, chat:, inputs:, locals:)
+        path = prompt_path_for(name)
+        return nil unless File.exist?(path)
+
+        resolved_locals = resolve_prompt_locals(locals, runtime: runtime_context(chat:, inputs:), chat:, inputs:)
+        ERB.new(File.read(path)).result_with_hash(resolved_locals)
+      end
+
+      private
+
+      def with_rails_chat_record(method_name, **kwargs)
+        raise ArgumentError, 'chat_model must be configured to use create/create!' unless resolved_chat_model
+
+        input_values, chat_options = partition_inputs(kwargs)
+        record = resolved_chat_model.public_send(method_name, **chat_kwargs, **chat_options)
+        apply_configuration(record, input_values:, persist_instructions: true) if record
+        record
+      end
+
+      def apply_configuration(chat_object, input_values:, persist_instructions:)
+        runtime = runtime_context(chat: chat_object, inputs: input_values)
+        llm_chat = llm_chat_for(chat_object)
+
+        apply_context(llm_chat)
+        apply_instructions(chat_object, runtime, inputs: input_values, persist: persist_instructions)
+        apply_tools(llm_chat, runtime)
+        apply_temperature(llm_chat)
+        apply_thinking(llm_chat)
+        apply_params(llm_chat, runtime)
+        apply_headers(llm_chat, runtime)
+        apply_schema(llm_chat, runtime)
+      end
+
+      def apply_context(llm_chat)
+        llm_chat.with_context(context) if context
+      end
+
+      def apply_instructions(chat_object, runtime, inputs:, persist:)
+        value = resolved_instructions_value(chat_object, runtime, inputs:)
+        return if value.nil?
+
+        instruction_target(chat_object, persist:).with_instructions(value)
+      end
+
+      def apply_tools(llm_chat, runtime)
+        tools_to_apply = Array(evaluate(tools, runtime))
+        llm_chat.with_tools(*tools_to_apply) unless tools_to_apply.empty?
+      end
+
+      def apply_temperature(llm_chat)
+        llm_chat.with_temperature(temperature) unless temperature.nil?
+      end
+
+      def apply_thinking(llm_chat)
+        llm_chat.with_thinking(**thinking) if thinking
+      end
+
+      def apply_params(llm_chat, runtime)
+        value = evaluate(params, runtime)
+        llm_chat.with_params(**value) if value && !value.empty?
+      end
+
+      def apply_headers(llm_chat, runtime)
+        value = evaluate(headers, runtime)
+        llm_chat.with_headers(**value) if value && !value.empty?
+      end
+
+      def apply_schema(llm_chat, runtime)
+        value = evaluate(schema, runtime)
+        llm_chat.with_schema(value) if value
+      end
+
+      def llm_chat_for(chat_object)
+        chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+      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)
+        return value unless prompt_instruction?(value)
+
+        runtime.prompt(
+          value[:prompt],
+          **resolve_prompt_locals(value[:locals] || {}, runtime:, chat: chat_object, inputs:)
+        )
+      end
+
+      def prompt_instruction?(value)
+        value.is_a?(Hash) && value[:prompt]
+      end
+
+      def instruction_target(chat_object, persist:)
+        if persist || !chat_object.respond_to?(:to_llm)
+          chat_object
+        else
+          chat_object.to_llm
+        end
+      end
+
+      def resolve_prompt_locals(locals, runtime:, chat:, inputs:)
+        base = { chat: chat }.merge(inputs)
+        evaluated = locals.each_with_object({}) do |(key, value), acc|
+          acc[key.to_sym] = value.is_a?(Proc) ? runtime.instance_exec(&value) : value
+        end
+        base.merge(evaluated)
+      end
+
+      def partition_inputs(kwargs)
+        input_values = {}
+        chat_options = {}
+
+        kwargs.each do |key, value|
+          symbolized_key = key.to_sym
+          if inputs.include?(symbolized_key)
+            input_values[symbolized_key] = value
+          else
+            chat_options[symbolized_key] = value
+          end
+        end
+
+        [input_values, chat_options]
+      end
+
+      def runtime_context(chat:, inputs:)
+        agent_class = self
+        Object.new.tap do |runtime|
+          runtime.define_singleton_method(:chat) { chat }
+          runtime.define_singleton_method(:prompt) do |name, **locals|
+            agent_class.render_prompt(name, chat:, inputs:, locals:)
+          end
+
+          inputs.each do |name, value|
+            runtime.define_singleton_method(name) { value }
+          end
+        end
+      end
+
+      def prompt_path_for(name)
+        filename = name.to_s
+        filename += '.txt.erb' unless filename.end_with?('.txt.erb')
+        prompt_root.join(prompt_agent_path, filename)
+      end
+
+      def prompt_agent_path
+        class_name = name || 'agent'
+        class_name.gsub('::', '/')
+                  .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                  .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                  .tr('-', '_')
+                  .downcase
+      end
+
+      def prompt_root
+        if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          Rails.root.join('app/prompts')
+        else
+          Pathname.new(Dir.pwd).join('app/prompts')
+        end
+      end
+
+      def resolved_chat_model
+        return @resolved_chat_model if defined?(@resolved_chat_model)
+
+        @resolved_chat_model = case @chat_model
+                               when String then Object.const_get(@chat_model)
+                               else @chat_model
+                               end
+      end
+    end
+
+    def initialize(chat: nil, inputs: nil, persist_instructions: true, **kwargs)
+      input_values, chat_options = self.class.send(:partition_inputs, kwargs)
+      @chat = chat || RubyLLM.chat(**self.class.chat_kwargs, **chat_options)
+      self.class.send(:apply_configuration, @chat, input_values: input_values.merge(inputs || {}),
+                                                   persist_instructions:)
+    end
+
+    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
+  end
+end

data/lib/ruby_llm/aliases.json

@@ -40,7 +40,8 @@
   "claude-haiku-4-5": {
     "anthropic": "claude-haiku-4-5-20251001",
     "openrouter": "anthropic/claude-haiku-4.5",
-    "bedrock": "anthropic.claude-haiku-4-5-20251001-v1:0"
+    "bedrock": "anthropic.claude-haiku-4-5-20251001-v1:0",
+    "azure": "claude-haiku-4-5-20251001"
   },
   "claude-opus-4": {
     "anthropic": "claude-opus-4-20250514",
@@ -53,12 +54,19 @@
   "claude-opus-4-1": {
     "anthropic": "claude-opus-4-1-20250805",
     "openrouter": "anthropic/claude-opus-4.1",
-    "bedrock": "anthropic.claude-opus-4-1-20250805-v1:0"
+    "bedrock": "anthropic.claude-opus-4-1-20250805-v1:0",
+    "azure": "claude-opus-4-1-20250805"
   },
   "claude-opus-4-5": {
     "anthropic": "claude-opus-4-5-20251101",
     "openrouter": "anthropic/claude-opus-4.5",
-    "bedrock": "anthropic.claude-opus-4-5-20251101-v1:0"
+    "bedrock": "anthropic.claude-opus-4-5-20251101-v1:0",
+    "azure": "claude-opus-4-5-20251101"
+  },
+  "claude-opus-4-6": {
+    "anthropic": "claude-opus-4-6",
+    "openrouter": "anthropic/claude-opus-4.6",
+    "bedrock": "anthropic.claude-opus-4-6-v1"
   },
   "claude-sonnet-4": {
     "anthropic": "claude-sonnet-4-20250514",
@@ -71,7 +79,8 @@
   "claude-sonnet-4-5": {
     "anthropic": "claude-sonnet-4-5-20250929",
     "openrouter": "anthropic/claude-sonnet-4.5",
-    "bedrock": "anthropic.claude-sonnet-4-5-20250929-v1:0"
+    "bedrock": "anthropic.claude-sonnet-4-5-20250929-v1:0",
+    "azure": "claude-sonnet-4-5-20250929"
   },
   "deepseek-chat": {
     "deepseek": "deepseek-chat",
@@ -98,10 +107,6 @@
     "openrouter": "google/gemini-2.0-flash-001",
     "vertexai": "gemini-2.0-flash-001"
   },
-  "gemini-2.0-flash-exp": {
-    "gemini": "gemini-2.0-flash-exp",
-    "vertexai": "gemini-2.0-flash-exp"
-  },
   "gemini-2.0-flash-lite": {
     "gemini": "gemini-2.0-flash-lite",
     "vertexai": "gemini-2.0-flash-lite"
@@ -222,7 +227,8 @@
   },
   "gpt-4": {
     "openai": "gpt-4",
-    "openrouter": "openai/gpt-4"
+    "openrouter": "openai/gpt-4",
+    "azure": "gpt-4"
   },
   "gpt-4-1106-preview": {
     "openai": "gpt-4-1106-preview",
@@ -238,31 +244,38 @@
   },
   "gpt-4.1": {
     "openai": "gpt-4.1",
-    "openrouter": "openai/gpt-4.1"
+    "openrouter": "openai/gpt-4.1",
+    "azure": "gpt-4.1"
   },
   "gpt-4.1-mini": {
     "openai": "gpt-4.1-mini",
-    "openrouter": "openai/gpt-4.1-mini"
+    "openrouter": "openai/gpt-4.1-mini",
+    "azure": "gpt-4.1-mini"
   },
   "gpt-4.1-nano": {
     "openai": "gpt-4.1-nano",
-    "openrouter": "openai/gpt-4.1-nano"
+    "openrouter": "openai/gpt-4.1-nano",
+    "azure": "gpt-4.1-nano"
   },
   "gpt-4o": {
     "openai": "gpt-4o",
-    "openrouter": "openai/gpt-4o"
+    "openrouter": "openai/gpt-4o",
+    "azure": "gpt-4o"
   },
   "gpt-4o-2024-05-13": {
     "openai": "gpt-4o-2024-05-13",
-    "openrouter": "openai/gpt-4o-2024-05-13"
+    "openrouter": "openai/gpt-4o-2024-05-13",
+    "azure": "gpt-4o-2024-05-13"
   },
   "gpt-4o-2024-08-06": {
     "openai": "gpt-4o-2024-08-06",
-    "openrouter": "openai/gpt-4o-2024-08-06"
+    "openrouter": "openai/gpt-4o-2024-08-06",
+    "azure": "gpt-4o-2024-08-06"
   },
   "gpt-4o-2024-11-20": {
     "openai": "gpt-4o-2024-11-20",
-    "openrouter": "openai/gpt-4o-2024-11-20"
+    "openrouter": "openai/gpt-4o-2024-11-20",
+    "azure": "gpt-4o-2024-11-20"
   },
   "gpt-4o-audio-preview": {
     "openai": "gpt-4o-audio-preview",
@@ -270,11 +283,13 @@
   },
   "gpt-4o-mini": {
     "openai": "gpt-4o-mini",
-    "openrouter": "openai/gpt-4o-mini"
+    "openrouter": "openai/gpt-4o-mini",
+    "azure": "gpt-4o-mini"
   },
   "gpt-4o-mini-2024-07-18": {
     "openai": "gpt-4o-mini-2024-07-18",
-    "openrouter": "openai/gpt-4o-mini-2024-07-18"
+    "openrouter": "openai/gpt-4o-mini-2024-07-18",
+    "azure": "gpt-4o-mini-2024-07-18"
   },
   "gpt-4o-mini-search-preview": {
     "openai": "gpt-4o-mini-search-preview",
@@ -324,10 +339,6 @@
     "openai": "gpt-5.2",
     "openrouter": "openai/gpt-5.2"
   },
-  "gpt-5.2-chat": {
-    "openai": "gpt-5.2-chat-latest",
-    "openrouter": "openai/gpt-5.2-chat-latest"
-  },
   "gpt-5.2-codex": {
     "openai": "gpt-5.2-codex",
     "openrouter": "openai/gpt-5.2-codex"
@@ -336,13 +347,22 @@
     "openai": "gpt-5.2-pro",
     "openrouter": "openai/gpt-5.2-pro"
   },
+  "gpt-audio": {
+    "openai": "gpt-audio",
+    "openrouter": "openai/gpt-audio"
+  },
+  "gpt-audio-mini": {
+    "openai": "gpt-audio-mini",
+    "openrouter": "openai/gpt-audio-mini"
+  },
   "o1": {
     "openai": "o1",
     "openrouter": "openai/o1"
   },
   "o1-pro": {
     "openai": "o1-pro",
-    "openrouter": "openai/o1-pro"
+    "openrouter": "openai/o1-pro",
+    "azure": "o1-pro"
   },
   "o3": {
     "openai": "o3",
@@ -354,7 +374,8 @@
   },
   "o3-mini": {
     "openai": "o3-mini",
-    "openrouter": "openai/o3-mini"
+    "openrouter": "openai/o3-mini",
+    "azure": "o3-mini"
   },
   "o3-pro": {
     "openai": "o3-pro",
@@ -362,14 +383,11 @@
   },
   "o4-mini": {
     "openai": "o4-mini",
-    "openrouter": "openai/o4-mini"
+    "openrouter": "openai/o4-mini",
+    "azure": "o4-mini"
   },
   "o4-mini-deep-research": {
     "openai": "o4-mini-deep-research",
     "openrouter": "openai/o4-mini-deep-research"
-  },
-  "text-embedding-004": {
-    "gemini": "text-embedding-004",
-    "vertexai": "text-embedding-004"
   }
 }