Class: SwarmSDK::V3::Tools::Registry

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/v3/tools/registry.rb

Overview

Registry for V3 tools (built-in and custom)

Maps tool names (symbols) to their V3 tool classes. Provides lookup, validation, factory, and custom tool registration.

Tools fall into categories based on creation requirements:

  1. **No params**: Simple tools (Think, Clock)

  2. **Directory only**: Tools needing working directory (Bash, Grep, Glob)

  3. **Agent context**: Tools needing agent name + directory (Read, Write, Edit)

Examples:

Look up a tool

klass = Registry.get(:Read)

Create a tool instance

tool = Registry.create(:Read, agent_name: :backend, directory: "/app")

Register a custom tool

Registry.register(:MyTool, MyCustomTool)

List available tools

Registry.available_names  #=> [:Read, :Write, :Edit, ...]

Class Method Summary collapse

Class Method Details

.available_names ⇒ Array<Symbol>

Get all available tool names (respects registered_tools filter)

Returns:

  • (Array<Symbol>) 


170
171
172
173
174
175
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 170

def available_names
  allowed = Configuration.instance.registered_tools
  names = builtin_tools.keys
  names.select! { |n| allowed.map(&:to_sym).include?(n) } if allowed
  names
end

.builtin_tools ⇒ Hash<Symbol, Class>

Lazily-built tool mapping

Uses lazy evaluation so tool classes are only resolved when first accessed, allowing Zeitwerk to load them on demand. Mutable to support custom registration.

Returns:

  • (Hash<Symbol, Class>) —

    Tool name to class mapping



35
36
37
38
39
40
41
42
43
44
45
46
47
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 35

def builtin_tools
  @builtin_tools ||= {
    Read: SwarmSDK::V3::Tools::Read,
    Write: SwarmSDK::V3::Tools::Write,
    Edit: SwarmSDK::V3::Tools::Edit,
    Bash: SwarmSDK::V3::Tools::Bash,
    Grep: SwarmSDK::V3::Tools::Grep,
    Glob: SwarmSDK::V3::Tools::Glob,
    Think: SwarmSDK::V3::Tools::Think,
    Clock: SwarmSDK::V3::Tools::Clock,
    SubTask: SwarmSDK::V3::Tools::SubTask,
  }
end

.create(name, **context) ⇒ RubyLLM::Tool

Create a tool instance with context

Uses the tool’s ‘creation_requirements` to determine constructor params.

Examples:

tool = Registry.create(:Read, agent_name: :backend, directory: "/app")

Parameters:

  • name (Symbol, String) —

    Tool name

  • context (Hash) —

    Available context for tool creation

Options Hash (**context):

  • :agent_name (Symbol) —

    Agent identifier

  • :directory (String) —

    Agent’s working directory

Returns:

  • (RubyLLM::Tool) —

    Instantiated tool

Raises:



103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 103

def create(name, **context)
  name_sym = name.to_sym
  tool_class = get(name_sym)

  raise ConfigurationError, "Unknown tool: #{name}" unless tool_class

  if tool_class.respond_to?(:creation_requirements) && tool_class.creation_requirements.any?
    requirements = tool_class.creation_requirements
    params = extract_params(requirements, context, name)
    tool_class.new(**params)
  else
    tool_class.new
  end
end

.create_all(definition, memory_store: nil, subtask_depth: 0) ⇒ Array<RubyLLM::Tool>

Create all tools for an agent definition

Merges the agent’s tools with global ‘default_tools` from configuration. Filters against `registered_tools` if configured.

Examples:

tools = Registry.create_all(definition)

Parameters:

Returns:

  • (Array<RubyLLM::Tool>) —

    Instantiated tools

Raises:



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 129

def create_all(definition, memory_store: nil, subtask_depth: 0)
  # Create shared read tracker for cross-tool enforcement
  read_tracker = ReadTracker.new

  context = {
    agent_name: definition.name,
    directory: definition.directory,
    read_tracker: read_tracker,
    memory_store: memory_store,
    agent_definition: definition,
    subtask_depth: subtask_depth,
  }

  config = Configuration.instance

  # Start with the agent's declared tools + global default_tools
  tool_names = definition.tools.dup
  config.default_tools.each do |name|
    tool_names << name.to_sym unless tool_names.include?(name.to_sym)
  end

  # Filter against registered_tools if configured
  if config.registered_tools
    allowed = config.registered_tools.map(&:to_sym)
    tool_names.select! { |name| allowed.include?(name) }
  end

  tool_names.uniq.map { |name| create(name, **context) }
end

.exists?(name) ⇒ Boolean

Check if a tool exists (respects registered_tools filter)

Parameters:

  • name (Symbol, String) —

    Tool name

Returns:

  • (Boolean) 


163
164
165
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 163

def exists?(name)
  !get(name.to_sym).nil?
end

.get(name) ⇒ Class?

Get tool class by name

Respects the ‘registered_tools` configuration filter. If `registered_tools` is set, only those tools are visible.

Examples:

Registry.get(:Read)  #=> SwarmSDK::V3::Tools::Read

Parameters:

  • name (Symbol, String) —

    Tool name

Returns:

  • (Class, nil) —

    Tool class or nil if not found/filtered



82
83
84
85
86
87
88
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 82

def get(name)
  name_sym = name.to_sym
  allowed = Configuration.instance.registered_tools
  return if allowed && !allowed.map(&:to_sym).include?(name_sym)

  builtin_tools[name_sym]
end

.register(name, klass) ⇒ void

This method returns an undefined value.

Register a custom tool

Examples:

Registry.register(:WebSearch, MyWebSearchTool)

Parameters:

  • name (Symbol, String) —

    Tool name

  • klass (Class) —

    Tool class (must inherit from Base or RubyLLM::Tool)

Raises:



58
59
60
61
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 58

def register(name, klass)
  name_sym = name.to_sym
  builtin_tools[name_sym] = klass
end

.reset! ⇒ void

This method returns an undefined value.

Reset registry to built-in tools only

Removes all custom tool registrations. Useful for test cleanup.



68
69
70
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 68

def reset!
  @builtin_tools = nil
end

.validate(names) ⇒ Array<Symbol>

Validate tool names

Parameters:

  • names (Array<Symbol, String>) —

    Tool names to validate

Returns:

  • (Array<Symbol>) —

    Invalid tool names



181
182
183
 
# File 'lib/swarm_sdk/v3/tools/registry.rb', line 181

def validate(names)
  names.map(&:to_sym).reject { |name| exists?(name) }
end