# RubyLLM Patches: Tools Array Merging & OpenAI Responses API Support for tools

[Halvanhelv]

This is a temporary solution until ruby_llm gem adds native support for these features. If you're facing similar issues, this might help you.

---

When using .with_tools() and .with_params(tools: [...]), the tools arrays were being replaced instead of merged, causing one set of tools to be lost.

Related: #205

# config/initializers/ruby_llm_patches.rb

# Monkey patch to fix deep_merge in ruby_llm to properly merge Arrays
# This allows using both RubyLLM::Tool classes and provider-specific tools
#
# Issue: https://github.com/crmne/ruby_llm/issues/205
# When using .with_tools() and .with_params(tools: [...]), the tools arrays were being replaced
# instead of merged, causing one set of tools to be lost.
#
# Solution: Extend deep_merge to concatenate Arrays instead of replacing them

module RubyLLM
  module Utils
    class << self
      def deep_merge(original, overrides)
        original.merge(overrides) do |_key, original_value, overrides_value|
          if original_value.is_a?(Hash) && overrides_value.is_a?(Hash)
            # Deep merge nested hashes (original behavior)
            deep_merge(original_value, overrides_value)
          elsif original_value.is_a?(Array) && overrides_value.is_a?(Array)
            # Concatenate arrays instead of replacing (NEW behavior)
            # This allows both RubyLLM tools and provider-specific tools to coexist
            original_value + overrides_value
          else
            # For all other types, override with new value (original behavior)
            overrides_value
          end
        end
      end
    end
  end
end

---

OpenAI's Responses API (required for Deep Research mode and built-in web_search) requires a flat tool format, not the nested format used by Chat Completions API.

# config/initializers/ruby_llm_patches.rb

# Monkey patch to support OpenAI Responses API (Deep Research + web_search)
# Responses API requires a flat format for tools, not a nested one
#
# Use this patch when you need:
# 1. Deep Research mode - advanced research with automatic planning
# 2. OpenAI's built-in web_search tool

module RubyLLM
  module Providers
    class OpenAI
      module Tools
        module_function

        # New method for generating tools in Responses API format
        # Use this for Deep Research mode and built-in web_search
        def tool_for_responses(tool)
          {
            name: tool.name,
            type: "function",
            description: tool.description,
            parameters: {
              type: "object",
              properties: tool.parameters.transform_values { |param| param_schema(param) },
              required: tool.parameters.select { |_, p| p.required }.keys
            }
          }
        end
      end
    end
  end
end

Usage Example

class KnowledgeSearchTool
  include RubyLLM::Tool

  description "Search knowledge base"

  parameter :query, type: :string, required: true, description: "Search query"

  def call(query:)
    # Your search logic
  end

  # Add method to generate Responses API format
  def self.to_openai_responses_format
    RubyLLM::Providers::OpenAI::Tools.tool_for_responses(self)
  end
end

# Usage
KnowledgeSearchTool.to_openai_responses_format

---

Complete Installation

# config/initializers/ruby_llm_patches.rb

# Patch 1: Array merging in deep_merge
module RubyLLM
  module Utils
    class << self
      def deep_merge(original, overrides)
        original.merge(overrides) do |_key, original_value, overrides_value|
          if original_value.is_a?(Hash) && overrides_value.is_a?(Hash)
            deep_merge(original_value, overrides_value)
          elsif original_value.is_a?(Array) && overrides_value.is_a?(Array)
            original_value + overrides_value
          else
            overrides_value
          end
        end
      end
    end
  end
end

# Patch 2: OpenAI Responses API support
module RubyLLM
  module Providers
    class OpenAI
      module Tools
        module_function

        def tool_for_responses(tool)
          {
            name: tool.name,
            type: "function",
            description: tool.description,
            parameters: {
              type: "object",
              properties: tool.parameters.transform_values { |param| param_schema(param) },
              required: tool.parameters.select { |_, p| p.required }.keys
            }
          }
        end
      end
    end
  end
end

Rails.logger.info "✅ RubyLLM patches loaded"

---

Note: These are temporary workarounds. Remove them once ruby_llm gem adds native support for Responses API and fixes the deep_merge issue.

[tpaulshippy]

I'm curious. There's much more to supporting responses api than the tools parameter. As seen here -- #325

How does this work?

[Halvanhelv]

Perhaps I didn't express myself clearly. I'm talking about using tools from ruby_llm for responses api.

This can be useful if you have several providers(one with Responses API) and don't want to duplicate the tools and code they execute.

[tpaulshippy]

Sure, that makes sense. Are you using RubyLLM with the responses api today? How are you accomplishing that? That's my curiosity.

[Halvanhelv]

I use a different gem for Responses API, but I have closely integrated it for use with ruby_llm. This will help me easily switch completely to ruby_llm in the future. At the moment, I am only using tools, and this allows me to use these tools in the same way I would for ruby_llm. Of course, there is some manual work involved, such as calling the method for the response_api format, but ultimately, I now have access to the power of the responses API and the convenience of the ruby_llm Tools classes. However, as I said, this is a temporary solution for those who need it now.

[tpaulshippy]

Interesting. Which gem?

Have you looked at https://github.com/tpaulshippy/ruby_llm_community?

[Halvanhelv]

https://github.com/alexrudall/ruby-openai