Skip to content

RubyLLM2 W1-12: Accept RubyLLM 2.0's tool call and provider options interfaces on the 1.16 fork - #44

Merged
samuelboland merged 2 commits into
mainfrom
dux-rubyllm2-w1-12-tool-call-provider-options
Nov 11, 2026
Merged

samuelboland merged 2 commits into
mainfrom
dux-rubyllm2-w1-12-tool-call-provider-options

Conversation

@staging-supernova-dx-appf-io

@staging-supernova-dx-appf-io staging-supernova-dx-appf-io Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

What this does

Lets the 1.16 fork accept the two interfaces RubyLLM 2.0 uses for tool calls and request options, so Supernova can move its code to them before the 2.0 bump. 1.16 behaviour is unchanged by default.

Tool calls

  • Tool#call(args = nil, tool_call: nil, **arguments) accepts keywords (the 2.0 form) as well as the 1.16 positional Hash. Symbol keys, String keys and a positional Hash give the same arguments to execute.
  • Passing a positional Hash and keywords together raises ArgumentError.
  • tool_call is a reserved keyword. It reaches execute only when execute declares a tool_call: keyword (execute_accepts_tool_call?), and it is left out of keyword validation and the inferred schema. **kwargs does not receive it, matching 2.0.
  • Chat#execute_tool calls the tool through call_tool: arguments that are not a Hash (an Array or String from JSON.parse) become {}, as before this PR. When the tool's call accepts keywords (the base Tool#call, or an override with ** or tool_call:), it calls tool.call(**kwargs, tool_call:), the 2.0 form. A tool that still overrides call(args) the 1.16 way gets the positional Hash, so it keeps working on the default config.
  • New config option allow_positional_tool_arguments (default true). When false, a positional Hash call raises ArgumentError ("Tool#call takes keyword arguments; positional Hash arguments are removed in RubyLLM 2.0"). Supernova's test suite sets it to false to catch every remaining positional caller.

Chat records: acts_as_chat records delegate with_provider_options (returns the record) and provider_options to to_llm, as on 2.0.

Provider options

  • Chat#with_provider_options(hash) sets @params to hash.to_h and returns the chat; Chat#provider_options reads it. Like 2.0, it replaces rather than merges. with_params still works and shares @params.

Not changed: no provider or protocol code, so no VCR cassettes were re-recorded.

Files

  • lib/ruby_llm/tool.rb: the new call, TOOL_CALL_KEYWORD, KEYWORD_PARAMETER_KINDS, execute_accepts_tool_call?, tool_arguments, and tool_call excluded from execute_keyword_signature.
  • lib/ruby_llm/chat.rb: with_provider_options, provider_options, call_tool and tool_call_accepts_keywords? used by execute_tool.
  • lib/ruby_llm/active_record/chat_methods.rb: with_provider_options and provider_options delegation.
  • lib/ruby_llm/configuration.rb: allow_positional_tool_arguments.
  • Specs: spec/ruby_llm/tool_spec.rb, spec/ruby_llm/chat_tools_spec.rb, spec/ruby_llm/chat_spec.rb, spec/ruby_llm/active_record/acts_as_spec.rb.

Brief: RubyLLM2 W1-12 (prep wave on 1.16 before the 2.0 bump).

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 <sam.boland@appfolio.com>
@samuelboland samuelboland changed the title feat: accept RubyLLM 2.0 tool call and provider options interfaces RubyLLM2 W1-12: Accept RubyLLM 2.0's tool call and provider options interfaces on the 1.16 fork Nov 11, 2026
@samuelboland
samuelboland marked this pull request as ready for review November 11, 2026 22:30
@samuelboland
samuelboland requested a review from a team as a code owner November 11, 2026 22:30
@staging-supernova-dx-appf-io

Copy link
Copy Markdown
Author

🤖 Supernova Code Review — View trace

🔁 Re-run this review

— via automation "Code Review Opus 5.5 Medium" (run), installed by Sam Boland (sam.boland@appfolio.com)

@staging-supernova-dx-appf-io staging-supernova-dx-appf-io Bot left a comment

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did an adversarial review of the tool-call and provider-options changes and left 3 inline findings in lib/ruby_llm/chat.rb:

  • Line 474: tools that still override call(args) the 1.16 way now get tool_call mixed into their argument Hash. With a strict execute, super(args) then fails with unknown keyword: tool_call. With a **kwargs execute, tool_call leaks into it.
  • Line 474: **(args || {}) raises TypeError when the model sends arguments that parse to something other than a Hash, like an Array or a String. Before this PR, normalize_args turned those into {}.
  • Line 163: with_provider_options isn't delegated from ActiveRecord::ChatMethods, so records using acts_as_chat can't switch to it.

🔁 Re-run this review

— via automation "Code Review Opus 5.5 Medium" (run), installed by Sam Boland (sam.boland@appfolio.com)

Comment thread lib/ruby_llm/chat.rb Outdated

RubyLLM.instrument('tool_call.ruby_llm', payload, config: @config) do |event|
result = tool.call(args)
result = tool.call(**(args || {}), tool_call:)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tools that still override call(args) with the 1.16 signature now get tool_call mixed into their arguments, so "1.16 behaviour is unchanged by default" doesn't hold for them.

On Ruby 3, keywords passed to a method that declares no keywords are packed into one positional Hash. So def call(args) now receives { "query" => "x", tool_call: #<ToolCall> }. If that override then calls super(args), tool_arguments returns the Hash with :tool_call still in it. validate_keyword_arguments then reports unknown keyword: tool_call for a strict execute, or a **kwargs execute receives it, which goes against the "**kwargs does not receive it" contract. allow_positional_tool_arguments = true doesn't protect these tools.

Suggested fix: only pass the keyword form when the tool's call accepts keywords. For example, check tool.method(:call).parameters for :key/:keyrest and otherwise fall back to tool.call(args). Please also add a spec with a legacy def call(args) = super(args) override.

Comment thread lib/ruby_llm/chat.rb Outdated

RubyLLM.instrument('tool_call.ruby_llm', payload, config: @config) do |event|
result = tool.call(args)
result = tool.call(**(args || {}), tool_call:)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If a model sends a non-Hash argument payload, **(args || {}) now raises TypeError out of chat.ask, where it used to fail gracefully.

ToolCall#arguments is whatever JSON.parse returns (ChatCompletions::Tools#parse_tool_call_arguments, StreamAccumulator#tool_calls_from_stream). A model that emits "[]" or "\"x\"" produces an Array or a String, and ** on those raises TypeError: no implicit conversion of Array into Hash. Before this PR, tool.call(args) went through normalize_args, which has an explicit non-Hash fallback to {}. The tool then either ran or returned an Invalid tool arguments error the model could recover from.

Suggested fix: normalize first, e.g. kwargs = args.respond_to?(:to_hash) ? args.to_hash : {}, then call tool.call(**kwargs, tool_call:).

Comment thread lib/ruby_llm/chat.rb
end

# RubyLLM 2.0 name for with_params; shares @params so both names always agree.
def with_provider_options(provider_options)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with_provider_options isn't delegated from RubyLLM::ActiveRecord::ChatMethods, so moving acts_as_chat callers off with_params raises NoMethodError.

lib/ruby_llm/active_record/chat_methods.rb delegates with_params(...) to to_llm (around line 120), but this PR adds no matching with_provider_options there. Any Supernova code that calls with_params on a persisted chat record can't make the 2.0 move this PR is meant to enable.

Suggested fix: add the same delegation, plus a spec.

def with_provider_options(...)
  to_llm.with_provider_options(...)
  self
end

@samuelboland

Copy link
Copy Markdown

Rulings on the staging bot's three inline findings. All three are right; please fix all three in this PR.

  1. lib/ruby_llm/chat.rb:474, legacy call(args) overrides (bot's first inline note). Do it. Supernova has 22 tools that override call(args) today, and the Supernova PR that bumps to this commit converts them. Any override that conversion misses must keep working on the default setting, not start failing with unknown keyword: tool_call. Change execute_tool to pass keywords only when the tool's call accepts them:

    • keyword form tool.call(**kwargs, tool_call:) when tool.method(:call).parameters includes a :keyrest entry, or a :key/:keyreq entry named tool_call;
    • otherwise tool.call(kwargs), the 1.16 positional form. With allow_positional_tool_arguments = false that path raises the existing "positional Hash arguments are removed in RubyLLM 2.0" error, which is what lets Supernova's test suite find a missed override.
      Add specs in spec/ruby_llm/chat_tools_spec.rb: (a) a tool with def call(args) = super(args) and a strict execute(query:) runs through chat.ask with the default config and execute receives only query; (b) the same tool with allow_positional_tool_arguments = false raises ArgumentError with that message.
  2. lib/ruby_llm/chat.rb:474, non-Hash arguments (bot's second inline note). Do it. Normalize before splatting: kwargs = args.respond_to?(:to_hash) ? args.to_hash : {}, and use kwargs in both branches from item 1. Add a spec where ToolCall#arguments is an Array ([]) and one where it is a String; each must run the tool with no arguments (or return the existing Invalid tool arguments error for a tool with a required keyword), not raise TypeError.

  3. lib/ruby_llm/chat.rb:163, ActiveRecord delegation (bot's third inline note). Do it, and add the reader too, to match 2.0 (lib/ruby_llm/active_record/chat_methods.rb on 2.0 delegates both with_provider_options and provider_options). In lib/ruby_llm/active_record/chat_methods.rb, next to with_params (line 120):

    def with_provider_options(...)
      to_llm.with_provider_options(...)
      self
    end
    
    def provider_options
      to_llm.provider_options
    end

    Add a spec in spec/ruby_llm/active_record/acts_as_spec.rb: chat.with_provider_options(foo: 1) returns the record, and chat.provider_options and chat.to_llm.params both equal { foo: 1 }.

Verified and fine as is: the Tool#call signature and tool_arguments error cases; tool_call reaching execute only through a declared tool_call: keyword and being left out of execute_keyword_signature; with_provider_options replacing @params with to_h and returning the chat; the config option's default; RuboCop and the test matrix on c1c7a5d.

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 <sam.boland@appfolio.com>
@staging-supernova-dx-appf-io

Copy link
Copy Markdown
Author

Supernova has stopped updating this pull request's title and description.

The description was edited outside Supernova after Supernova last wrote it, so later pushes will leave the title and description as they are instead of replacing those changes.

To have Supernova keep them up to date again, turn automatic updates back on. You'll be asked to confirm first, because turning them back on replaces the current description with a newly generated one.

— via Coder session (view)

@samuelboland samuelboland left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified: keyword and positional Tool#call paths, tool_call reserved and passed only to a declared keyword, legacy call(args) overrides kept on the positional path, non-Hash arguments normalized to {}, with_provider_options/provider_options on Chat and acts_as_chat records; specs cover each; CI green on 6b9d65a.

@samuelboland
samuelboland merged commit 1e53648 into main Nov 11, 2026
24 of 25 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants