swarm_sdk 2.4.6 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7155af152f3d943e4dd31a18dc869a021105250d4e9b12f1b020ade293682e61
-  data.tar.gz: a4bee8bc106e8237bc9f32c70846d4ed4485f92197a126d37e4ee3a97596c378
+  metadata.gz: 5043d994b9ec60ad756b1c088571886acec8e5225ebac60f55484b0004e8ff0a
+  data.tar.gz: 37ce390a6a458cde546be634388a436459c70db1de9cf3f86b19345c2a556846
 SHA512:
-  metadata.gz: d7c433a8cb0f454369613e1d3b1c713f3ec4bc727806dc78072d46eac2e9abf1a9928682df3bc12502095cfb79f189366a0cd799ec1cd9eb3ba467186c078c40
-  data.tar.gz: ccbebf882f4d5dcdd54d47faa1819ba45d664624b5cf3ac412c03b32fb69722dfff21a4020d517d04b2902421b2e2cb8b4bdfe59a5a3869518fecaf817bbf68d
+  metadata.gz: 4c7964fa7d22f1b059fcadd5f2a8f963037018bed4fe57ae9f430ffa4f593275868ab44a83692e7706faf5fb2ac2e933b46922c393b3c684227d7facb46e98d7
+  data.tar.gz: 0f8fab5ebd7c97f6de61f12a0ed30af096e1130472691e0bd4ee66bcdc6e6bb7823a583a268ff56b4e01ecb91970217900f31bca40f47d69af1bb0698652e5ca

data/lib/swarm_sdk/agent/system_prompt_builder.rb

@@ -148,7 +148,7 @@ module SwarmSDK
         contributions = []
 
         PluginRegistry.all.each do |plugin|
-          next unless plugin.storage_enabled?(@definition)
+          next unless plugin.memory_configured?(@definition)
 
           contribution = plugin.system_prompt_contribution(agent_definition: @definition, storage: nil)
           contributions << contribution if contribution && !contribution.strip.empty?

data/lib/swarm_sdk/custom_tool_registry.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module SwarmSDK
+  # Registry for user-defined custom tools
+  #
+  # Provides a simple way to register custom tools without creating a full plugin.
+  # Custom tools are registered globally and available to all agents that request them.
+  #
+  # ## When to Use Custom Tools vs Plugins
+  #
+  # **Use Custom Tools when:**
+  # - You have simple, stateless tools
+  # - Tools don't need persistent storage
+  # - Tools don't need lifecycle hooks
+  # - Tools don't need system prompt contributions
+  #
+  # **Use Plugins when:**
+  # - Tools need persistent storage per agent
+  # - Tools need lifecycle hooks (on_agent_initialized, on_user_message, etc.)
+  # - Tools need to contribute to system prompts
+  # - You have a suite of related tools that share configuration
+  #
+  # @example Register a simple tool
+  #   class WeatherTool < RubyLLM::Tool
+  #     description "Get weather for a city"
+  #     param :city, type: "string", required: true
+  #
+  #     def execute(city:)
+  #       "Weather in #{city}: Sunny"
+  #     end
+  #   end
+  #
+  #   SwarmSDK.register_tool(WeatherTool)
+  #
+  # @example Register with explicit name
+  #   SwarmSDK.register_tool(:Weather, WeatherTool)
+  #
+  # @example Tool with creation requirements
+  #   class AgentAwareTool < RubyLLM::Tool
+  #     def self.creation_requirements
+  #       [:agent_name, :directory]
+  #     end
+  #
+  #     def initialize(agent_name:, directory:)
+  #       super()
+  #       @agent_name = agent_name
+  #       @directory = directory
+  #     end
+  #
+  #     def execute
+  #       "Agent: #{@agent_name}, Dir: #{@directory}"
+  #     end
+  #   end
+  #
+  #   SwarmSDK.register_tool(AgentAwareTool)
+  #
+  module CustomToolRegistry
+    # Wrapper that overrides the tool's name to match the registered name
+    #
+    # This ensures that when a user registers a tool with a specific name,
+    # that name is what gets used for tool lookup (has_tool?) and LLM tool calls.
+    class NamedToolWrapper < SimpleDelegator
+      def initialize(tool, registered_name)
+        super(tool)
+        @registered_name = registered_name.to_s
+      end
+
+      # Override name to return the registered name
+      def name
+        @registered_name
+      end
+    end
+
+    @tools = {}
+
+    class << self
+      # Register a custom tool
+      #
+      # @param name [Symbol] Tool name
+      # @param tool_class [Class] Tool class (must be a RubyLLM::Tool subclass)
+      # @raise [ArgumentError] If tool_class is not a RubyLLM::Tool subclass
+      # @raise [ArgumentError] If a tool with the same name is already registered
+      # @return [void]
+      def register(name, tool_class)
+        name = name.to_sym
+
+        unless tool_class.is_a?(Class) && tool_class < RubyLLM::Tool
+          raise ArgumentError, "Tool class must inherit from RubyLLM::Tool"
+        end
+
+        if @tools.key?(name)
+          raise ArgumentError, "Custom tool '#{name}' is already registered"
+        end
+
+        if PluginRegistry.plugin_tool?(name)
+          raise ArgumentError, "Tool '#{name}' is already provided by a plugin"
+        end
+
+        if Tools::Registry.exists?(name)
+          raise ArgumentError, "Tool '#{name}' is a built-in tool and cannot be overridden"
+        end
+
+        @tools[name] = tool_class
+      end
+
+      # Check if a custom tool is registered
+      #
+      # @param name [Symbol, String] Tool name
+      # @return [Boolean]
+      def registered?(name)
+        @tools.key?(name.to_sym)
+      end
+
+      # Get a registered tool class
+      #
+      # @param name [Symbol, String] Tool name
+      # @return [Class, nil] Tool class or nil if not found
+      def get(name)
+        @tools[name.to_sym]
+      end
+
+      # Get all registered custom tool names
+      #
+      # @return [Array<Symbol>]
+      def tool_names
+        @tools.keys
+      end
+
+      # Create a tool instance
+      #
+      # Uses the tool's `creation_requirements` class method (if defined) to determine
+      # what parameters to pass to the constructor. The created tool is wrapped with
+      # NamedToolWrapper to ensure the registered name is used for tool lookup.
+      #
+      # @param name [Symbol, String] Tool name
+      # @param context [Hash] Available context for tool creation
+      # @option context [Symbol] :agent_name Agent identifier
+      # @option context [String] :directory Agent's working directory
+      # @return [RubyLLM::Tool] Instantiated tool (wrapped with registered name)
+      # @raise [ConfigurationError] If tool is unknown or has unmet requirements
+      def create(name, context = {})
+        name_sym = name.to_sym
+        tool_class = @tools[name_sym]
+
+        raise ConfigurationError, "Unknown custom tool: #{name}" unless tool_class
+
+        # Create the tool instance
+        tool = if tool_class.respond_to?(:creation_requirements)
+          requirements = tool_class.creation_requirements
+          params = extract_params(requirements, context, name)
+          tool_class.new(**params)
+        else
+          # No requirements - simple instantiation
+          tool_class.new
+        end
+
+        # Wrap with NamedToolWrapper to ensure registered name is used
+        NamedToolWrapper.new(tool, name_sym)
+      end
+
+      # Unregister a custom tool
+      #
+      # @param name [Symbol, String] Tool name
+      # @return [Class, nil] The unregistered tool class, or nil if not found
+      def unregister(name)
+        @tools.delete(name.to_sym)
+      end
+
+      # Clear all registered custom tools
+      #
+      # Primarily useful for testing.
+      #
+      # @return [void]
+      def clear
+        @tools.clear
+      end
+
+      # Infer tool name from class name
+      #
+      # @param tool_class [Class] Tool class
+      # @return [Symbol] Inferred tool name
+      #
+      # @example
+      #   infer_name(WeatherTool) #=> :Weather
+      #   infer_name(MyApp::Tools::StockPrice) #=> :StockPrice
+      #   infer_name(MyApp::Tools::StockPriceTool) #=> :StockPrice
+      def infer_name(tool_class)
+        # Get the class name without module prefix
+        class_name = tool_class.name.split("::").last
+
+        # Remove "Tool" suffix if present
+        name = class_name.sub(/Tool\z/, "")
+
+        name.to_sym
+      end
+
+      private
+
+      # Extract required parameters from context
+      #
+      # @param requirements [Array<Symbol>] Required parameter names
+      # @param context [Hash] Available context
+      # @param tool_name [Symbol] Tool name for error messages
+      # @return [Hash] Parameters to pass to tool constructor
+      # @raise [ConfigurationError] If required parameter is missing
+      def extract_params(requirements, context, tool_name)
+        params = {}
+
+        requirements.each do |req|
+          unless context.key?(req)
+            raise ConfigurationError,
+              "Custom tool '#{tool_name}' requires '#{req}' but it was not provided. " \
+                "Ensure the tool's `creation_requirements` only includes supported keys: " \
+                ":agent_name, :directory"
+          end
+
+          params[req] = context[req]
+        end
+
+        params
+      end
+    end
+  end
+end

data/lib/swarm_sdk/plugin.rb

@@ -139,11 +139,11 @@ module SwarmSDK
       []
     end
 
-    # Agent storage enabled for this agent? (optional)
+    # Check if memory is configured for this agent (optional)
     #
     # @param agent_definition [Agent::Definition] Agent definition
     # @return [Boolean] True if storage should be created
-    def storage_enabled?(agent_definition)
+    def memory_configured?(agent_definition)
       false
     end
 

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -569,7 +569,7 @@ module SwarmSDK
         PluginRegistry.all.each do |plugin|
           @swarm.agent_definitions.each do |agent_name, agent_definition|
             # Check if this plugin needs storage for this agent
-            next unless plugin.storage_enabled?(agent_definition)
+            next unless plugin.memory_configured?(agent_definition)
 
             # Get plugin config for this agent
             config = get_plugin_config(agent_definition, plugin.name)

data/lib/swarm_sdk/swarm/tool_configurator.rb

@@ -60,6 +60,11 @@ module SwarmSDK
       # Uses the Registry factory pattern to instantiate tools based on their
       # declared requirements. This eliminates the need for a giant case statement.
       #
+      # Tool lookup order:
+      # 1. Plugin tools (registered via SwarmSDK::PluginRegistry)
+      # 2. Custom tools (registered via SwarmSDK.register_tool)
+      # 3. Built-in tools (SwarmSDK::Tools::Registry)
+      #
       # File tools and TodoWrite require agent context for tracking state.
       # Scratchpad tools require shared scratchpad instance.
       # Plugin tools are delegated to their respective plugins.
@@ -80,7 +85,16 @@ module SwarmSDK
           return create_plugin_tool(tool_name_sym, agent_name, directory, chat, agent_definition)
         end
 
-        # Use Registry factory pattern - tools declare their own requirements
+        # Check if tool is a custom registered tool
+        if CustomToolRegistry.registered?(tool_name_sym)
+          context = {
+            agent_name: agent_name,
+            directory: directory,
+          }
+          return CustomToolRegistry.create(tool_name_sym, context)
+        end
+
+        # Use Registry factory pattern for built-in tools
         context = {
           agent_name: agent_name,
           directory: directory,
@@ -267,7 +281,7 @@ module SwarmSDK
       def register_plugin_tools(chat, agent_name, agent_definition, explicit_tool_names)
         PluginRegistry.all.each do |plugin|
           # Check if plugin has storage enabled for this agent
-          next unless plugin.storage_enabled?(agent_definition)
+          next unless plugin.memory_configured?(agent_definition)
 
           # Register each tool provided by the plugin
           plugin.tools.each do |tool_name|

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.4.6"
+  VERSION = "2.5.0"
 end

data/lib/swarm_sdk.rb

@@ -162,6 +162,149 @@ module SwarmSDK
       AgentRegistry.clear
     end
 
+    # Register a custom tool for use in swarms
+    #
+    # Provides a simple way to add tools without creating a full plugin.
+    # Tools can be registered with an explicit name or the name can be
+    # inferred from the class name.
+    #
+    # Custom tools are available to any agent that includes them in their
+    # tools configuration, just like built-in tools.
+    #
+    # @overload register_tool(tool_class)
+    #   Register a tool with name inferred from class name
+    #   @param tool_class [Class] Tool class (must inherit from RubyLLM::Tool)
+    #   @return [Symbol] The registered tool name
+    #
+    # @overload register_tool(name, tool_class)
+    #   Register a tool with explicit name
+    #   @param name [Symbol, String] Tool name
+    #   @param tool_class [Class] Tool class (must inherit from RubyLLM::Tool)
+    #   @return [Symbol] The registered tool name
+    #
+    # @raise [ArgumentError] If tool_class doesn't inherit from RubyLLM::Tool
+    # @raise [ArgumentError] If a tool with the same name is already registered
+    # @raise [ArgumentError] If the name conflicts with a built-in or plugin tool
+    #
+    # @example Register with inferred name
+    #   class WeatherTool < RubyLLM::Tool
+    #     description "Get weather for a city"
+    #     param :city, type: "string", required: true
+    #
+    #     def execute(city:)
+    #       "Weather in #{city}: Sunny, 72°F"
+    #     end
+    #   end
+    #
+    #   SwarmSDK.register_tool(WeatherTool)  # Registers as :Weather
+    #
+    # @example Register with explicit name
+    #   SwarmSDK.register_tool(:GetWeather, WeatherTool)
+    #
+    # @example Tool with agent context
+    #   class ContextAwareTool < RubyLLM::Tool
+    #     # Declare what context the tool needs
+    #     def self.creation_requirements
+    #       [:agent_name, :directory]
+    #     end
+    #
+    #     def initialize(agent_name:, directory:)
+    #       super()
+    #       @agent_name = agent_name
+    #       @directory = directory
+    #     end
+    #
+    #     description "Shows agent context"
+    #     def execute
+    #       "Agent: #{@agent_name} in #{@directory}"
+    #     end
+    #   end
+    #
+    #   SwarmSDK.register_tool(ContextAwareTool)
+    #
+    # @example Use registered tool in a swarm
+    #   SwarmSDK.register_tool(WeatherTool)
+    #
+    #   swarm = SwarmSDK.build do
+    #     name "Weather Assistant"
+    #     lead :assistant
+    #
+    #     agent :assistant do
+    #       model "claude-sonnet-4"
+    #       description "Weather helper"
+    #       tools :Weather, :Read  # Custom + built-in tools
+    #     end
+    #   end
+    #
+    # @see CustomToolRegistry For the underlying registry
+    # @see Plugin For complex tool systems requiring storage or lifecycle hooks
+    def register_tool(name_or_class, tool_class = nil)
+      if tool_class.nil?
+        # Single argument: infer name from class
+        tool_class = name_or_class
+        name = CustomToolRegistry.infer_name(tool_class)
+      else
+        # Two arguments: explicit name
+        name = name_or_class.to_sym
+      end
+
+      CustomToolRegistry.register(name, tool_class)
+      name
+    end
+
+    # Check if a custom tool is registered
+    #
+    # @param name [Symbol, String] Tool name
+    # @return [Boolean] true if the tool is registered
+    #
+    # @example
+    #   SwarmSDK.register_tool(WeatherTool)
+    #   SwarmSDK.custom_tool_registered?(:Weather)  #=> true
+    #   SwarmSDK.custom_tool_registered?(:Unknown)  #=> false
+    def custom_tool_registered?(name)
+      CustomToolRegistry.registered?(name)
+    end
+
+    # Get all registered custom tool names
+    #
+    # @return [Array<Symbol>] List of registered custom tool names
+    #
+    # @example
+    #   SwarmSDK.register_tool(WeatherTool)
+    #   SwarmSDK.register_tool(StockTool)
+    #   SwarmSDK.custom_tools  #=> [:Weather, :Stock]
+    def custom_tools
+      CustomToolRegistry.tool_names
+    end
+
+    # Unregister a custom tool
+    #
+    # @param name [Symbol, String] Tool name to unregister
+    # @return [Class, nil] The unregistered tool class, or nil if not found
+    #
+    # @example
+    #   SwarmSDK.register_tool(WeatherTool)
+    #   SwarmSDK.unregister_tool(:Weather)
+    #   SwarmSDK.custom_tool_registered?(:Weather)  #=> false
+    def unregister_tool(name)
+      CustomToolRegistry.unregister(name)
+    end
+
+    # Clear all registered custom tools
+    #
+    # Removes all custom tool registrations. Primarily useful for testing
+    # to ensure clean state between tests.
+    #
+    # @return [void]
+    #
+    # @example In test teardown
+    #   def teardown
+    #     SwarmSDK.clear_custom_tools!
+    #   end
+    def clear_custom_tools!
+      CustomToolRegistry.clear
+    end
+
     # Main entry point for DSL - builds simple multi-agent swarms
     #
     # @return [Swarm] Always returns a Swarm instance

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.4.6
+  version: 2.5.0
 platform: ruby
 authors:
 - Paulo Arruda
@@ -154,6 +154,7 @@ files:
 - lib/swarm_sdk/context_compactor/token_counter.rb
 - lib/swarm_sdk/context_management/builder.rb
 - lib/swarm_sdk/context_management/context.rb
+- lib/swarm_sdk/custom_tool_registry.rb
 - lib/swarm_sdk/defaults.rb
 - lib/swarm_sdk/events_to_messages.rb
 - lib/swarm_sdk/hooks/adapter.rb