ruby_llm 2.0.0 → 2.1.0

data/lib/ruby_llm/agent.rb

@@ -21,8 +21,10 @@ module RubyLLM
   # that class instead.
   #
   # Configuration that depends on runtime state goes in blocks or lambdas.
-  # They are evaluated when a chat is built, with +chat+ and any declared
-  # ::inputs available as methods:
+  # Most blocks run after a chat is built, with +chat+ and any declared
+  # ::inputs available as methods. The +model+ block runs before a chat
+  # exists. A deferred +context+ block also runs before Chat construction in
+  # plain Ruby, but receives the Rails chat record while Rails configures it:
   #
   #   class WorkAssistant < RubyLLM::Agent
   #     inputs :workspace
@@ -44,6 +46,7 @@ module RubyLLM
     DUPED_INHERITED_CONFIG = {
       :@chat_kwargs => {},
       :@tools => [],
+      :@mcp => [],
       :@provider_tools => [],
       :@tool_options => {},
       :@caching => nil,
@@ -59,6 +62,8 @@ module RubyLLM
     # agent forwards to the matching Chat#with_* when it builds its chat.
     PASSTHROUGH_OPTIONS = %i[temperature max_output_tokens].freeze
     THINKING_OPTIONS = %i[effort budget display].freeze
+    UNRESOLVED_CONTEXT = Object.new.freeze
+    private_constant :UNRESOLVED_CONTEXT
 
     # The chat operations an agent instance runs through its ::rescue_from
     # handlers. Remaining delegated methods pass through untouched.
@@ -66,21 +71,22 @@ module RubyLLM
 
     # Chat methods that return the wrapped chat so calls can be chained there.
     CHAINABLE_CHAT_DELEGATES = %i[
-      with_instructions with_tools with_provider_tools with_tool_options with_model
+      with_instructions with_tools with_mcp with_provider_tools with_tool_options with_model
       with_temperature with_max_output_tokens with_thinking with_citations
       with_end_user with_compaction with_caching with_context with_provider_options
       with_headers with_schema with_fallbacks
-      before_request before_message after_message before_tool_call after_tool_result
+      before_request before_message after_message before_tool_call after_tool_result after_tool_progress
       before_fallback after_fallback
-      cancel approve deny cache_until_here
+      convert_unsupported_attachments
+      cancel approve deny answer decline cache_until_here
     ].freeze
 
     # Chat values and operations whose return values pass through unchanged.
     PASSTHROUGH_CHAT_DELEGATES = %i[
-      model provider messages tools provider_tools tool_options provider_options headers schema concurrency
-      caching citations compaction context end_user fallbacks thinking temperature max_output_tokens
-      each complete? cancelled? awaiting_approval? pending_approvals
-      add_message add_completion tokens cost render
+      model provider messages tools deferred_tools mcp provider_tools tool_options provider_options headers schema
+      concurrency caching citations compaction context end_user fallbacks thinking temperature max_output_tokens
+      each complete? cancelled? waiting? awaiting_approval? pending_approvals awaiting_input? pending_inputs
+      awaiting_tasks? pending_tasks add_message add_completion tokens cost render
     ].freeze
 
     COPIED_INHERITED_CONFIG = (%i[
@@ -90,6 +96,8 @@ module RubyLLM
       @schema
       @context
       @chat_model
+      @tools_defer
+      @mcp_defer
     ] + PASSTHROUGH_OPTIONS.map { |option| :"@#{option}" }).freeze
     private_constant :DUPED_INHERITED_CONFIG, :COPIED_INHERITED_CONFIG,
                      :PASSTHROUGH_OPTIONS, :THINKING_OPTIONS, :GUARDED_OPERATIONS,
@@ -130,12 +138,36 @@ module RubyLLM
       #   tools SearchDocs, LookupAccount
       #   tools { [TodoTool.new(chat: chat)] }
       #
-      def tools(*tools, &block)
+      # Pass +defer:+ as Chat#with_tools takes it:
+      #
+      #   tools SearchDocs, LookupAccount, defer: true
+      #
+      def tools(*tools, defer: nil, &block)
         return @tools || [] if tools.empty? && !block_given?
 
+        @tools_defer = defer
         @tools = block_given? ? block : tools.flatten
       end
 
+      # Connects MCP servers to chats this agent builds, applied via
+      # Chat#with_mcp. A block defers construction until the chat is built,
+      # with the declared ::inputs available. Called with no arguments,
+      # returns the declared servers.
+      #
+      #   mcp Files
+      #   mcp { [Linear.new(user: user), Files] }
+      #
+      # Pass +defer:+ as Chat#with_mcp takes it:
+      #
+      #   mcp GitHub, defer: true
+      #
+      def mcp(*servers, defer: nil, &block)
+        return @mcp || [] if servers.empty? && !block_given?
+
+        @mcp_defer = defer
+        @mcp = block_given? ? block : servers.flatten
+      end
+
       # Sets how chats this agent builds use their tools, applied via
       # Chat#with_tool_options. Accepts +choice:+, +calls:+, and
       # +concurrency:+. A block defers evaluation until the chat is built.
@@ -363,12 +395,29 @@ module RubyLLM
       private :fallback_options
 
       # Sets a Context whose configuration chats this agent builds should
-      # use, applied via Chat#with_context. Called with no argument, returns
-      # the configured context.
-      def context(value = nil)
-        return @context if value.nil?
+      # use, applied via Chat#with_context. A block taking a configuration
+      # argument creates an isolated Context when the agent class is defined.
+      # A zero-argument block or Proc value defers evaluation until a chat is
+      # built or configured, with declared ::inputs available as methods. In
+      # plain Ruby, +chat+ is nil; in Rails mode, +chat+ is the record being
+      # configured. Called with no argument or block, returns the configured
+      # context or deferred Proc.
+      #
+      #   context SharedContext
+      #   context { |config| config.request_timeout = 180 }
+      #   context -> { RubyLLM.context { |config| config.openai_api_key = api_key } }
+      def context(value = nil, &block)
+        raise ArgumentError, 'Pass a context or a block, not both' if value && block
+
+        validate_context_proc(value)
+
+        return @context if value.nil? && !block
 
-        @context = value
+        @context = if block
+                     block.arity.zero? ? block : RubyLLM.context(&block)
+                   else
+                     value
+                   end
       end
 
       # Sets the ActiveRecord chat class this agent creates and finds,
@@ -453,6 +502,15 @@ module RubyLLM
         @chat_kwargs || {}
       end
 
+      # Resolves a deferred context before plain-Ruby chat construction;
+      # +chat+ is nil in the evaluation runtime.
+      def resolved_context(inputs:) # :nodoc:
+        value = context
+        return value unless value.is_a?(Proc)
+
+        evaluate(value, runtime_context(chat: nil, inputs:))
+      end
+
       def resolved_chat_kwargs(inputs: {}) # :nodoc:
         kwargs = chat_kwargs
         return kwargs unless kwargs[:model].is_a?(Proc)
@@ -460,8 +518,9 @@ module RubyLLM
         kwargs.merge(model: evaluate(kwargs[:model], runtime_context(chat: nil, inputs: inputs)))
       end
 
-      def build_chat(inputs:, options:) # :nodoc:
-        (context || RubyLLM).chat(**resolved_chat_kwargs(inputs:), **options)
+      def build_chat(inputs:, options:, resolved_context: UNRESOLVED_CONTEXT) # :nodoc:
+        context_value = resolved_context.equal?(UNRESOLVED_CONTEXT) ? self.resolved_context(inputs:) : resolved_context
+        (context_value || RubyLLM).chat(**resolved_chat_kwargs(inputs:), **options)
       end
 
       # Builds a Chat configured with this agent's declarations and returns
@@ -473,8 +532,9 @@ module RubyLLM
       #
       def chat(**kwargs)
         input_values, chat_options = partition_inputs(kwargs)
-        chat = build_chat(inputs: input_values, options: chat_options)
-        apply_configuration(chat, input_values:, persist_instructions: true)
+        context_value = resolved_context(inputs: input_values)
+        chat = build_chat(inputs: input_values, options: chat_options, resolved_context: context_value)
+        apply_configuration(chat, input_values:, persist_instructions: true, resolved_context: context_value)
         chat
       end
 
@@ -485,8 +545,8 @@ module RubyLLM
       #   chat = WorkAssistant.create(user: current_user)
       #
       # Raises ArgumentError if ::chat_model is not configured.
-      def create(**kwargs)
-        with_rails_chat_record(:create, **kwargs)
+      def create(**)
+        with_rails_chat_record(:create, **)
       end
 
       # Like ::create, but calls the model's <tt>create!</tt>, raising if
@@ -494,8 +554,8 @@ module RubyLLM
       #
       #   chat = WorkAssistant.create!(user: current_user)
       #
-      def create!(**kwargs)
-        with_rails_chat_record(:create!, **kwargs)
+      def create!(**)
+        with_rails_chat_record(:create!, **)
       end
 
       # Finds the ::chat_model record with +id+ and applies this agent's
@@ -530,8 +590,8 @@ module RubyLLM
         record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
         apply_assume_model_exists(record)
         apply_protocol(record)
-        apply_context(record)
         runtime = runtime_context(chat: record, inputs: input_values)
+        apply_context(record, runtime)
         apply_instructions(
           record,
           runtime,
@@ -563,10 +623,15 @@ module RubyLLM
         [input_values, chat_options]
       end
 
-      def apply_configuration(chat, input_values:, persist_instructions:) # :nodoc:
+      def apply_configuration( # :nodoc:
+        chat,
+        input_values:,
+        persist_instructions:,
+        resolved_context: UNRESOLVED_CONTEXT
+      )
         runtime = runtime_context(chat:, inputs: input_values)
         apply_chat_options(chat)
-        apply_context(chat)
+        apply_context(chat, runtime, resolved_context:)
         apply_instructions(chat, runtime, inputs: input_values, persist: persist_instructions)
         apply_tools(chat, runtime)
         apply_passthrough_options(chat)
@@ -583,6 +648,13 @@ module RubyLLM
 
       private
 
+      def validate_context_proc(value)
+        return unless value.is_a?(Proc)
+        return if value.arity.zero?
+
+        raise ArgumentError, 'context Proc must accept zero arguments'
+      end
+
       def validate_thinking_options(enabled, options)
         raise ArgumentError, 'thinking accepts false or thinking options' unless [true, false].include?(enabled)
         raise ArgumentError, 'thinking false does not accept options' if !enabled && options.any?
@@ -634,8 +706,9 @@ module RubyLLM
         record
       end
 
-      def apply_context(chat)
-        chat.with_context(context) if context
+      def apply_context(chat, runtime, resolved_context: UNRESOLVED_CONTEXT)
+        value = resolved_context.equal?(UNRESOLVED_CONTEXT) ? evaluate(context, runtime) : resolved_context
+        chat.with_context(value) if value && !chat.context.equal?(value)
       end
 
       def apply_instructions(chat, runtime, inputs:, persist:, persistent_only: false)
@@ -662,7 +735,10 @@ module RubyLLM
 
       def apply_tools(chat, runtime)
         tools_to_apply = Array(evaluate(tools, runtime)).compact
-        chat.with_tools(*tools_to_apply) if tools_to_apply.any?
+        chat.with_tools(*tools_to_apply, defer: @tools_defer) if tools_to_apply.any?
+
+        servers = Array(evaluate(mcp, runtime)).compact
+        chat.with_mcp(*servers, defer: @mcp_defer) if servers.any?
 
         options = evaluate(tool_options, runtime)
         chat.with_tool_options(**options) if options && !options.empty?
@@ -849,8 +925,25 @@ module RubyLLM
     def initialize(chat: nil, inputs: nil, persist_instructions: true, **kwargs)
       input_values, chat_options = self.class.partition_inputs(kwargs)
       input_values = input_values.merge(inputs || {})
-      @chat = chat || self.class.build_chat(inputs: input_values, options: chat_options)
-      self.class.apply_configuration(@chat, input_values:, persist_instructions:)
+
+      if chat
+        @chat = chat
+        self.class.apply_configuration(@chat, input_values:, persist_instructions:)
+        return
+      end
+
+      context_value = self.class.resolved_context(inputs: input_values)
+      @chat = self.class.build_chat(
+        inputs: input_values,
+        options: chat_options,
+        resolved_context: context_value
+      )
+      self.class.apply_configuration(
+        @chat,
+        input_values:,
+        persist_instructions:,
+        resolved_context: context_value
+      )
     end
 
     # The wrapped Chat, or the chat record in Rails mode.
@@ -868,10 +961,16 @@ module RubyLLM
 
     ##
     # :method: with_tools
-    # :call-seq: with_tools(*tools)
+    # :call-seq: with_tools(*tools, defer: nil)
     #
     # Delegates to Chat#with_tools. See that method for arguments and return values.
 
+    ##
+    # :method: with_mcp
+    # :call-seq: with_mcp(*servers, defer: nil)
+    #
+    # Delegates to Chat#with_mcp. See that method for arguments and return values.
+
     ##
     # :method: with_provider_tools
     # :call-seq: with_provider_tools(*tools, **tools_with_options)
@@ -962,6 +1061,12 @@ module RubyLLM
     #
     # Delegates to Chat#with_fallbacks. See that method for arguments and return values.
 
+    ##
+    # :method: convert_unsupported_attachments
+    # :call-seq: convert_unsupported_attachments(&block)
+    #
+    # Delegates to Chat#convert_unsupported_attachments. See that method for arguments and return values.
+
     ##
     # :method: before_request
     # :call-seq: before_request(&block)
@@ -992,6 +1097,12 @@ module RubyLLM
     #
     # Delegates to Chat#after_tool_result. See that method for arguments and return values.
 
+    ##
+    # :method: after_tool_progress
+    # :call-seq: after_tool_progress(&block)
+    #
+    # Delegates to Chat#after_tool_progress. See that method for arguments and return values.
+
     ##
     # :method: before_fallback
     # :call-seq: before_fallback(&block)
@@ -1022,9 +1133,21 @@ module RubyLLM
     #
     # Delegates to Chat#deny. See that method for arguments and return values.
 
+    ##
+    # :method: answer
+    # :call-seq: answer(request, **values)
+    #
+    # Delegates to Chat#answer. See that method for arguments and return values.
+
+    ##
+    # :method: decline
+    # :call-seq: decline(request)
+    #
+    # Delegates to Chat#decline. See that method for arguments and return values.
+
     ##
     # :method: cache_until_here
-    # :call-seq: cache_until_here()
+    # :call-seq: cache_until_here(ttl: nil)
     #
     # Delegates to Chat#cache_until_here. See that method for arguments and return values.
 
@@ -1052,6 +1175,18 @@ module RubyLLM
     #
     # Delegates to Chat#tools. See that method for arguments and return values.
 
+    ##
+    # :method: deferred_tools
+    # :call-seq: deferred_tools
+    #
+    # Delegates to Chat#deferred_tools. See that method for arguments and return values.
+
+    ##
+    # :method: mcp
+    # :call-seq: mcp
+    #
+    # Delegates to Chat#mcp. See that method for arguments and return values.
+
     ##
     # :method: provider_tools
     # :call-seq: provider_tools
@@ -1160,6 +1295,12 @@ module RubyLLM
     #
     # Delegates to Chat#cancelled?. See that method for arguments and return values.
 
+    ##
+    # :method: waiting?
+    # :call-seq: waiting?()
+    #
+    # Delegates to Chat#waiting?. See that method for arguments and return values.
+
     ##
     # :method: awaiting_approval?
     # :call-seq: awaiting_approval?()
@@ -1172,6 +1313,30 @@ module RubyLLM
     #
     # Delegates to Chat#pending_approvals. See that method for arguments and return values.
 
+    ##
+    # :method: awaiting_input?
+    # :call-seq: awaiting_input?()
+    #
+    # Delegates to Chat#awaiting_input?. See that method for arguments and return values.
+
+    ##
+    # :method: pending_inputs
+    # :call-seq: pending_inputs()
+    #
+    # Delegates to Chat#pending_inputs. See that method for arguments and return values.
+
+    ##
+    # :method: awaiting_tasks?
+    # :call-seq: awaiting_tasks?()
+    #
+    # Delegates to Chat#awaiting_tasks?. See that method for arguments and return values.
+
+    ##
+    # :method: pending_tasks
+    # :call-seq: pending_tasks()
+    #
+    # Delegates to Chat#pending_tasks. See that method for arguments and return values.
+
     ##
     # :method: add_message
     # :call-seq: add_message(message_or_attributes)

data/lib/ruby_llm/aliases.json

@@ -10,7 +10,8 @@
     "anthropic": "claude-fable-5-1",
     "openrouter": "anthropic/claude-fable-5.1",
     "bedrock": "anthropic.claude-fable-5-1",
-    "vertexai": "claude-fable-5-1"
+    "vertexai": "claude-fable-5-1",
+    "azure": "claude-fable-5-1"
   },
   "claude-haiku-4-5": {
     "anthropic": "claude-haiku-4-5-20251001",
@@ -58,6 +59,13 @@
     "vertexai": "claude-opus-5",
     "azure": "claude-opus-5"
   },
+  "claude-opus-5-5": {
+    "anthropic": "claude-opus-5-5",
+    "openrouter": "anthropic/claude-opus-5.5",
+    "bedrock": "anthropic.claude-opus-5-5",
+    "vertexai": "claude-opus-5-5",
+    "azure": "claude-opus-5-5"
+  },
   "claude-sonnet-4-5": {
     "anthropic": "claude-sonnet-4-5-20250929",
     "openrouter": "anthropic/claude-sonnet-4.5",
@@ -79,6 +87,13 @@
     "vertexai": "claude-sonnet-5",
     "azure": "claude-sonnet-5"
   },
+  "claude-sonnet-5-5": {
+    "anthropic": "claude-sonnet-5-5",
+    "openrouter": "anthropic/claude-sonnet-5.5",
+    "bedrock": "anthropic.claude-sonnet-5-5",
+    "vertexai": "claude-sonnet-5-5",
+    "azure": "claude-sonnet-5-5"
+  },
   "deepseek-ocr": {
     "vertexai": "deepseek-ai/deepseek-ocr-maas"
   },
@@ -200,6 +215,10 @@
     "gemini": "gemini-3.5-live-translate-preview",
     "vertexai": "gemini-3.5-live-translate-preview"
   },
+  "gemini-3.5-transcribe": {
+    "gemini": "gemini-3.5-transcribe",
+    "openrouter": "google/gemini-3.5-transcribe"
+  },
   "gemini-3.6-flash": {
     "gemini": "gemini-3.6-flash",
     "openrouter": "google/gemini-3.6-flash",
@@ -215,6 +234,18 @@
     "openrouter": "google/gemini-3.8-flash",
     "vertexai": "gemini-3.8-flash"
   },
+  "gemini-3.8-flash-lite-tts": {
+    "gemini": "gemini-3.8-flash-lite-tts",
+    "openrouter": "google/gemini-3.8-flash-lite-tts"
+  },
+  "gemini-3.8-flash-tts": {
+    "gemini": "gemini-3.8-flash-tts",
+    "openrouter": "google/gemini-3.8-flash-tts"
+  },
+  "gemini-3.8-live": {
+    "gemini": "gemini-3.8-live",
+    "vertexai": "gemini-3.8-live"
+  },
   "gemini-embedding-001": {
     "gemini": "gemini-embedding-001",
     "openrouter": "google/gemini-embedding-001",
@@ -237,6 +268,11 @@
     "gemini": "gemini-flash-lite-latest",
     "vertexai": "gemini-flash-lite-latest"
   },
+  "gemini-nano-banana-2.1": {
+    "gemini": "gemini-nano-banana-2.1",
+    "openrouter": "google/gemini-nano-banana-2.1",
+    "vertexai": "gemini-nano-banana-2.1"
+  },
   "gemini-omni-flash-preview": {
     "gemini": "gemini-omni-flash-preview",
     "vertexai": "gemini-omni-flash-preview"
@@ -272,7 +308,8 @@
   },
   "gpt-3.5-turbo-instruct": {
     "openai": "gpt-3.5-turbo-instruct",
-    "openrouter": "openai/gpt-3.5-turbo-instruct"
+    "openrouter": "openai/gpt-3.5-turbo-instruct",
+    "azure": "gpt-3.5-turbo-instruct"
   },
   "gpt-4": {
     "openai": "gpt-4",
@@ -280,7 +317,8 @@
   },
   "gpt-4-turbo": {
     "openai": "gpt-4-turbo",
-    "openrouter": "openai/gpt-4-turbo"
+    "openrouter": "openai/gpt-4-turbo",
+    "azure": "gpt-4-turbo"
   },
   "gpt-4.1": {
     "openai": "gpt-4.1",
@@ -354,7 +392,8 @@
   },
   "gpt-5-pro": {
     "openai": "gpt-5-pro",
-    "openrouter": "openai/gpt-5-pro"
+    "openrouter": "openai/gpt-5-pro",
+    "azure": "gpt-5-pro"
   },
   "gpt-5.1": {
     "openai": "gpt-5.1",
@@ -363,7 +402,8 @@
   },
   "gpt-5.1-codex": {
     "openai": "gpt-5.1-codex",
-    "openrouter": "openai/gpt-5.1-codex"
+    "openrouter": "openai/gpt-5.1-codex",
+    "azure": "gpt-5.1-codex"
   },
   "gpt-5.1-codex-max": {
     "openai": "gpt-5.1-codex-max",
@@ -372,7 +412,8 @@
   },
   "gpt-5.1-codex-mini": {
     "openai": "gpt-5.1-codex-mini",
-    "openrouter": "openai/gpt-5.1-codex-mini"
+    "openrouter": "openai/gpt-5.1-codex-mini",
+    "azure": "gpt-5.1-codex-mini"
   },
   "gpt-5.2": {
     "openai": "gpt-5.2",
@@ -442,6 +483,21 @@
     "openrouter": "openai/gpt-6-astra",
     "azure": "gpt-6-astra"
   },
+  "gpt-6-luna": {
+    "openai": "gpt-6-luna",
+    "openrouter": "openai/gpt-6-luna",
+    "azure": "gpt-6-luna"
+  },
+  "gpt-6-sol": {
+    "openai": "gpt-6-sol",
+    "openrouter": "openai/gpt-6-sol",
+    "azure": "gpt-6-sol"
+  },
+  "gpt-6.1-sol": {
+    "openai": "gpt-6.1-sol",
+    "openrouter": "openai/gpt-6.1-sol",
+    "azure": "gpt-6.1-sol"
+  },
   "gpt-audio": {
     "openai": "gpt-audio",
     "openrouter": "openai/gpt-audio",
@@ -469,11 +525,13 @@
   },
   "gpt-image-2.5-flare": {
     "openai": "gpt-image-2.5-flare",
-    "openrouter": "openai/gpt-image-2.5-flare"
+    "openrouter": "openai/gpt-image-2.5-flare",
+    "azure": "gpt-image-2.5-flare"
   },
   "gpt-image-2.5-sunburst": {
     "openai": "gpt-image-2.5-sunburst",
-    "openrouter": "openai/gpt-image-2.5-sunburst"
+    "openrouter": "openai/gpt-image-2.5-sunburst",
+    "azure": "gpt-image-2.5-sunburst"
   },
   "gpt-oss-120b": {
     "vertexai": "openai/gpt-oss-120b-maas",