From c1c7a5d9301884897ada213ce857f9de57012469 Mon Sep 17 00:00:00 2001 From: Supernova Date: Wed, 11 Nov 2026 22:26:55 +0000 Subject: [PATCH 1/2] Accept RubyLLM 2.0's tool call and provider options interfaces Tool#call takes keyword arguments and a reserved tool_call: keyword, and Chat#execute_tool calls it that way. The 1.x positional Hash still works unless allow_positional_tool_arguments is false. Chat gains with_provider_options / provider_options, sharing @params with with_params / params. Co-authored-by: Sam Boland --- lib/ruby_llm/chat.rb | 12 ++- lib/ruby_llm/configuration.rb | 1 + lib/ruby_llm/tool.rb | 29 ++++++- spec/ruby_llm/chat_spec.rb | 24 ++++++ spec/ruby_llm/chat_tools_spec.rb | 27 +++++++ spec/ruby_llm/tool_spec.rb | 128 +++++++++++++++++++++++++++++++ 6 files changed, 217 insertions(+), 4 deletions(-) diff --git a/lib/ruby_llm/chat.rb b/lib/ruby_llm/chat.rb index 53972a8da2..c0ed729ec2 100644 --- a/lib/ruby_llm/chat.rb +++ b/lib/ruby_llm/chat.rb @@ -159,6 +159,16 @@ def with_params(**params) self end + # RubyLLM 2.0 name for with_params; shares @params so both names always agree. + def with_provider_options(provider_options) + @params = provider_options.to_h + self + end + + def provider_options + @params + end + def with_protocol(protocol) @protocol = protocol self @@ -461,7 +471,7 @@ def execute_tool(tool_call) } RubyLLM.instrument('tool_call.ruby_llm', payload, config: @config) do |event| - result = tool.call(args) + result = tool.call(**(args || {}), tool_call:) event[:result] = result event[:result_content] = result event[:result_class] = result.class.name diff --git a/lib/ruby_llm/configuration.rb b/lib/ruby_llm/configuration.rb index 52c1b65b46..3af732bcfb 100644 --- a/lib/ruby_llm/configuration.rb +++ b/lib/ruby_llm/configuration.rb @@ -60,6 +60,7 @@ def defaults = @defaults ||= {} option :http_proxy, nil option :tool_concurrency, false option :auto_upload_large_files, true + option :allow_positional_tool_arguments, true option :logger, nil option :instrumenter, nil diff --git a/lib/ruby_llm/tool.rb b/lib/ruby_llm/tool.rb index a2f9464372..e90c149399 100644 --- a/lib/ruby_llm/tool.rb +++ b/lib/ruby_llm/tool.rb @@ -18,6 +18,8 @@ def initialize(name, type: 'string', desc: nil, description: nil, required: true # Base class for creating tools that AI models can use class Tool POSITIONAL_PARAMETER_KINDS = %i[req opt rest].freeze + KEYWORD_PARAMETER_KINDS = %i[keyreq key].freeze # :nodoc: + TOOL_CALL_KEYWORD = :tool_call # :nodoc: class << self def description(text = nil) @@ -127,12 +129,15 @@ def parameters_schema end end - def call(args) - normalized_args = normalize_args(args) + # Keywords are the RubyLLM 2.0 form; the positional Hash is the 1.x form. `tool_call` is + # reserved and reaches execute only when execute declares a `tool_call:` keyword. + def call(args = nil, tool_call: nil, **arguments) + normalized_args = normalize_args(tool_arguments(args, arguments)) validation_error = validate_keyword_arguments(normalized_args) return { error: "Invalid tool arguments: #{validation_error}" } if validation_error RubyLLM.logger.debug { "Tool #{name} called with: #{normalized_args.inspect}" } + normalized_args[TOOL_CALL_KEYWORD] = tool_call if execute_accepts_tool_call? result = execute(**normalized_args) RubyLLM.logger.debug { "Tool #{name} returned: #{result.inspect}" } result @@ -142,8 +147,26 @@ def execute(...) raise NotImplementedError, 'Subclasses must implement #execute' end + def execute_accepts_tool_call? # :nodoc: + method(:execute).parameters.any? do |kind, name| + name == TOOL_CALL_KEYWORD && KEYWORD_PARAMETER_KINDS.include?(kind) + end + end + protected + def tool_arguments(args, arguments) + return arguments if args.nil? + + unless RubyLLM.config.allow_positional_tool_arguments + raise ArgumentError, + 'Tool#call takes keyword arguments; positional Hash arguments are removed in RubyLLM 2.0' + end + raise ArgumentError, 'pass tool arguments either as one Hash or as keywords, not both' unless arguments.empty? + + args + end + def normalize_args(args) return {} if args.nil? return args.transform_keys(&:to_sym) if args.respond_to?(:transform_keys) @@ -169,7 +192,7 @@ def validate_keyword_arguments(arguments) end def execute_keyword_signature - keyword_signature = method(:execute).parameters + keyword_signature = method(:execute).parameters.reject { |_, name| name == TOOL_CALL_KEYWORD } required_keywords = keyword_signature.filter_map { |kind, name| name if kind == :keyreq } optional_keywords = keyword_signature.filter_map { |kind, name| name if kind == :key } accepts_extra_keywords = keyword_signature.any? { |kind, _| kind == :keyrest } diff --git a/spec/ruby_llm/chat_spec.rb b/spec/ruby_llm/chat_spec.rb index 055fb2271f..7fa3ce1413 100644 --- a/spec/ruby_llm/chat_spec.rb +++ b/spec/ruby_llm/chat_spec.rb @@ -21,6 +21,30 @@ def expect_token_usage(message) expect(message.output_tokens).to be_positive end + describe '#with_provider_options' do + it 'sets provider_options and params to the same value and returns the chat' do + chat = RubyLLM.chat + + expect(chat.with_provider_options(a: 1)).to be(chat) + expect(chat.provider_options).to eq({ a: 1 }) + expect(chat.params).to eq({ a: 1 }) + end + + it 'is replaced by a later with_params' do + chat = RubyLLM.chat.with_provider_options(a: 1).with_params(b: 2) + + expect(chat.provider_options).to eq({ b: 2 }) + expect(chat.params).to eq({ b: 2 }) + end + + it 'replaces an earlier with_params' do + chat = RubyLLM.chat.with_params(b: 2).with_provider_options(a: 1) + + expect(chat.provider_options).to eq({ a: 1 }) + expect(chat.params).to eq({ a: 1 }) + end + end + describe 'basic chat functionality' do CHAT_MODELS.each do |model_info| model = model_info[:model] diff --git a/spec/ruby_llm/chat_tools_spec.rb b/spec/ruby_llm/chat_tools_spec.rb index 16f775d120..01006b26bc 100644 --- a/spec/ruby_llm/chat_tools_spec.rb +++ b/spec/ruby_llm/chat_tools_spec.rb @@ -590,6 +590,33 @@ def stub_tool_response(chat, tool_calls) end end + describe 'keyword tool calls' do + it 'calls the tool with keywords and passes the ToolCall to a call override' do + received = [] + tool_class = Class.new(RubyLLM::Tool) do + description 'Records what call receives' + + define_method(:call) do |tool_call: nil, **args| + received << [tool_call, args] + 'recorded' + end + + def execute(query:) + query + end + end + stub_const('KeywordRecorder', tool_class) + tool_call = RubyLLM::ToolCall.new(id: 'call_1', name: 'keyword_recorder', arguments: { 'query' => 'x' }) + chat = RubyLLM.chat.with_tool(KeywordRecorder) + stub_tool_response(chat, { tool_call.id => tool_call }) + + chat.ask('Record it') + + expect(received).to eq([[tool_call, { 'query' => 'x' }]]) + expect(chat.messages.find { |message| message.role == :tool }.content).to eq('recorded') + end + end + describe 'concurrent tool execution' do let(:tool_calls) do { diff --git a/spec/ruby_llm/tool_spec.rb b/spec/ruby_llm/tool_spec.rb index 52c6b344a9..29fd5fa7cf 100644 --- a/spec/ruby_llm/tool_spec.rb +++ b/spec/ruby_llm/tool_spec.rb @@ -139,6 +139,134 @@ def execute(*args) expect(result).to eq([{ legacy: true }]) end + + context 'with keyword arguments (the RubyLLM 2.0 form)' do + before do + stub_const('KeywordTool', Class.new(described_class) do + def execute(questions:, limit: 5) + { questions:, limit: } + end + end) + end + + it 'gives the same result for Symbol keys, String keys and a positional Hash' do + positional = KeywordTool.new.call({ 'questions' => [1], 'limit' => 2 }) + + expect(KeywordTool.new.call(questions: [1], limit: 2)).to eq(positional) + expect(KeywordTool.new.call(**{ 'questions' => [1], 'limit' => 2 })).to eq(positional) + expect(positional).to eq({ questions: [1], limit: 2 }) + end + + it 'validates keyword arguments as it does a positional Hash' do + expect(KeywordTool.new.call(**{ 'questions' => [], 'isOther' => true })) + .to eq({ error: 'Invalid tool arguments: unknown keyword: isOther' }) + expect(KeywordTool.new.call).to eq({ error: 'Invalid tool arguments: missing keyword: questions' }) + end + + it 'raises ArgumentError when given both a Hash and keywords' do + expect { KeywordTool.new.call({ 'questions' => [] }, limit: 1) } + .to raise_error(ArgumentError, 'pass tool arguments either as one Hash or as keywords, not both') + end + end + + context 'with the reserved tool_call keyword' do + let(:tool_call) { RubyLLM::ToolCall.new(id: 'call_1', name: 'probe', arguments: { 'query' => 'x' }) } + + it 'passes tool_call into an execute that declares it' do + stub_const('ToolCallAwareTool', Class.new(described_class) do + def execute(tool_call:, **args) + { tool_call:, args: } + end + end) + + result = ToolCallAwareTool.new.call(tool_call:, query: 'x') + + expect(result).to eq({ tool_call:, args: { query: 'x' } }) + end + + it 'passes tool_call alongside a positional Hash' do + stub_const('PositionalToolCallTool', Class.new(described_class) do + def execute(query:, tool_call: nil) + [query, tool_call] + end + end) + + expect(PositionalToolCallTool.new.call({ 'query' => 'x' }, tool_call:)).to eq(['x', tool_call]) + end + + it 'does not pass tool_call into an execute without that keyword' do + stub_const('PlainTool', Class.new(described_class) do + def execute(query:) + query + end + end) + + expect(PlainTool.new.call(tool_call:, query: 'x')).to eq('x') + end + + it 'does not pass tool_call into an execute that only accepts keyrest' do + stub_const('KeyrestTool', Class.new(described_class) do + def execute(**args) + args + end + end) + + expect(KeyrestTool.new.call(tool_call:, query: 'x')).to eq({ query: 'x' }) + end + + it 'never counts tool_call as an unknown keyword or as a required argument' do + stub_const('StrictKeywordTool', Class.new(described_class) do + def execute(query:) + query + end + end) + + expect(StrictKeywordTool.new.call(tool_call:)) + .to eq({ error: 'Invalid tool arguments: missing keyword: query' }) + expect(StrictKeywordTool.new.call(tool_call:, query: 'x')).to eq('x') + end + + it 'leaves tool_call out of the inferred parameter schema' do + stub_const('SchemaToolCallTool', Class.new(described_class) do + def execute(query:, tool_call: nil) + [query, tool_call] + end + end) + + expect(SchemaToolCallTool.new.params_schema['properties'].keys).to eq(['query']) + expect(SchemaToolCallTool.new.params_schema['required']).to eq(['query']) + end + end + + context 'when allow_positional_tool_arguments is false' do + around do |example| + original = RubyLLM.config.allow_positional_tool_arguments + RubyLLM.config.allow_positional_tool_arguments = false + example.run + ensure + RubyLLM.config.allow_positional_tool_arguments = original + end + + before do + stub_const('StrictTool', Class.new(described_class) do + def execute(questions:) + questions + end + end) + end + + it 'raises ArgumentError for a positional Hash' do + expect { StrictTool.new.call({ 'questions' => [] }) } + .to raise_error( + ArgumentError, + 'Tool#call takes keyword arguments; positional Hash arguments are removed in RubyLLM 2.0' + ) + end + + it 'accepts keyword arguments' do + expect(StrictTool.new.call(**{ 'questions' => [1] })).to eq([1]) + end + end end describe '#params_schema' do From 6b9d65a354bfb39bb910812153fd9bba6ab2e0cf Mon Sep 17 00:00:00 2001 From: Supernova Date: Wed, 11 Nov 2026 22:40:35 +0000 Subject: [PATCH 2/2] Keep legacy call(args) overrides working and delegate provider_options execute_tool passes keywords only when the tool's call accepts them (keyrest or a tool_call keyword) and otherwise passes the 1.16 positional Hash, so a missed override keeps working on the default config and raises when allow_positional_tool_arguments is false. Non-Hash arguments become an empty Hash instead of raising TypeError. The ActiveRecord chat delegates with_provider_options and provider_options, as 2.0 does. Co-authored-by: Sam Boland --- lib/ruby_llm/active_record/chat_methods.rb | 9 +++ lib/ruby_llm/chat.rb | 17 +++++- spec/ruby_llm/active_record/acts_as_spec.rb | 8 +++ spec/ruby_llm/chat_tools_spec.rb | 68 +++++++++++++++++++++ 4 files changed, 101 insertions(+), 1 deletion(-) diff --git a/lib/ruby_llm/active_record/chat_methods.rb b/lib/ruby_llm/active_record/chat_methods.rb index ac53442631..0c32d4cf19 100644 --- a/lib/ruby_llm/active_record/chat_methods.rb +++ b/lib/ruby_llm/active_record/chat_methods.rb @@ -122,6 +122,15 @@ def with_params(...) self end + def with_provider_options(...) + to_llm.with_provider_options(...) + self + end + + def provider_options + to_llm.provider_options + end + def with_headers(...) to_llm.with_headers(...) self diff --git a/lib/ruby_llm/chat.rb b/lib/ruby_llm/chat.rb index c0ed729ec2..6edd7a68c5 100644 --- a/lib/ruby_llm/chat.rb +++ b/lib/ruby_llm/chat.rb @@ -471,7 +471,7 @@ def execute_tool(tool_call) } RubyLLM.instrument('tool_call.ruby_llm', payload, config: @config) do |event| - result = tool.call(**(args || {}), tool_call:) + result = call_tool(tool, args, tool_call) event[:result] = result event[:result_content] = result event[:result_class] = result.class.name @@ -479,6 +479,21 @@ def execute_tool(tool_call) end end + # A 1.x override of call(args) keeps getting the positional Hash, so a missed conversion + # still works on the default config and fails loudly when positional calls are disallowed. + def call_tool(tool, args, tool_call) + kwargs = args.respond_to?(:to_hash) ? args.to_hash : {} + return tool.call(**kwargs, tool_call:) if tool_call_accepts_keywords?(tool) + + tool.call(kwargs) + end + + def tool_call_accepts_keywords?(tool) + tool.method(:call).parameters.any? do |kind, name| + kind == :keyrest || (Tool::KEYWORD_PARAMETER_KINDS.include?(kind) && name == Tool::TOOL_CALL_KEYWORD) + end + end + def update_tool_options(choice:, calls:) unless choice.nil? normalized_choice = normalize_tool_choice(choice) diff --git a/spec/ruby_llm/active_record/acts_as_spec.rb b/spec/ruby_llm/active_record/acts_as_spec.rb index 788e3206b1..b90662d294 100644 --- a/spec/ruby_llm/active_record/acts_as_spec.rb +++ b/spec/ruby_llm/active_record/acts_as_spec.rb @@ -257,6 +257,14 @@ def execute(expression:) llm_chat = chat.instance_variable_get(:@chat) expect(llm_chat.params).to eq(max_tokens: 100, temperature: 0.5) end + + it 'supports with_provider_options and provider_options' do + chat = Chat.create!(model: model) + + expect(chat.with_provider_options(foo: 1)).to eq(chat) + expect(chat.provider_options).to eq({ foo: 1 }) + expect(chat.to_llm.params).to eq({ foo: 1 }) + end end describe 'tool functionality' do diff --git a/spec/ruby_llm/chat_tools_spec.rb b/spec/ruby_llm/chat_tools_spec.rb index 01006b26bc..5900d169e1 100644 --- a/spec/ruby_llm/chat_tools_spec.rb +++ b/spec/ruby_llm/chat_tools_spec.rb @@ -615,6 +615,74 @@ def execute(query:) expect(received).to eq([[tool_call, { 'query' => 'x' }]]) expect(chat.messages.find { |message| message.role == :tool }.content).to eq('recorded') end + + context 'with a legacy call(args) override' do + let(:received) { [] } + let(:tool_call) { RubyLLM::ToolCall.new(id: 'call_1', name: 'legacy_call', arguments: { 'query' => 'x' }) } + let(:chat) do + sink = received + stub_const('LegacyCall', Class.new(RubyLLM::Tool) do + description 'Overrides call with the 1.x positional form' + + def call(args) = super(args) # rubocop:disable Lint/UselessMethodDefinition,Style/SuperArguments + + define_method(:execute) do |query:| + sink << { query: } + 'legacy ok' + end + end) + RubyLLM.chat.with_tool(LegacyCall).tap { |c| stub_tool_response(c, { tool_call.id => tool_call }) } + end + + it 'passes a positional Hash on the default config' do + chat.ask('Run it') + + expect(received).to eq([{ query: 'x' }]) + expect(chat.messages.find { |message| message.role == :tool }.content).to eq('legacy ok') + end + + it 'raises when positional tool arguments are disallowed' do + original = RubyLLM.config.allow_positional_tool_arguments + RubyLLM.config.allow_positional_tool_arguments = false + + expect { chat.ask('Run it') }.to raise_error( + ArgumentError, + 'Tool#call takes keyword arguments; positional Hash arguments are removed in RubyLLM 2.0' + ) + ensure + RubyLLM.config.allow_positional_tool_arguments = original + end + end + + context 'with non-Hash tool call arguments' do + [[], 'not json'].each do |arguments| + it "runs a tool without arguments when arguments is #{arguments.class}" do + stub_const('NoArgs', Class.new(RubyLLM::Tool) do + description 'Takes nothing' + + def execute = 'no args ok' + end) + tool_call = RubyLLM::ToolCall.new(id: 'call_1', name: 'no_args', arguments:) + chat = RubyLLM.chat.with_tool(NoArgs) + stub_tool_response(chat, { tool_call.id => tool_call }) + + chat.ask('Run it') + + expect(chat.messages.find { |message| message.role == :tool }.content).to eq('no args ok') + end + + it "returns the invalid arguments error for a required keyword when arguments is #{arguments.class}" do + tool_call = RubyLLM::ToolCall.new(id: 'call_1', name: 'content_returning', arguments:) + results = [] + chat = RubyLLM.chat.with_tool(ContentReturningTool).after_tool_result { |result| results << result } + stub_tool_response(chat, { tool_call.id => tool_call }) + + chat.ask('Run it') + + expect(results).to eq([{ error: 'Invalid tool arguments: missing keyword: query' }]) + end + end + end end describe 'concurrent tool execution' do