Class: SwarmSDK::SwarmRegistry

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/swarm_registry.rb

Overview

Registry for managing sub-swarms in composable swarms

SwarmRegistry handles lazy loading, caching, and lifecycle management of child swarms registered via the swarms DSL block.

Features

  • Lazy loading: Sub-swarms are only loaded when first accessed
  • Caching: Loaded swarms are cached for reuse
  • Hierarchical IDs: Sub-swarms get IDs based on parent + registration name
  • Context control: keep_context determines if swarm state persists
  • Lifecycle management: Cleanup cascades through all sub-swarms

Example

registry = SwarmRegistry.new(parent_swarm_id: "main_app")
registry.register("code_review", file: "./swarms/code_review.rb", keep_context: true)

# Lazy load on first access
swarm = registry.load_swarm("code_review")
# => Swarm with swarm_id = "main_app/code_review"

# Reset if keep_context: false
registry.reset_if_needed("code_review")

Instance Method Summary collapse

Constructor Details

#initialize(parent_swarm_id:) ⇒ SwarmRegistry

Initialize a new swarm registry

Parameters:

  • parent_swarm_id (String) —

    ID of the parent swarm



32
33
34
35
36
 
# File 'lib/swarm_sdk/swarm_registry.rb', line 32

def initialize(parent_swarm_id:)
  @parent_swarm_id = parent_swarm_id
  @registered_swarms = {}
  # Format: { "code_review" => { file: "...", keep_context: true, instance: nil } }
end

Instance Method Details

#load_swarm(name) ⇒ Swarm

Load a registered swarm (lazy load + cache)

Loads the swarm from its source (file, yaml, or block) on first access, then caches it. Sets hierarchical swarm_id based on parent_swarm_id + registration name.

Parameters:

  • name (String) —

    Swarm registration name

Returns:

  • (Swarm) —

    Loaded swarm instance

Raises:



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/swarm_sdk/swarm_registry.rb', line 74

def load_swarm(name)
  entry = @registered_swarms[name]
  raise ConfigurationError, "Swarm '#{name}' not registered" unless entry

  # Return cached instance if exists
  return entry[:instance] if entry[:instance]

  # Load from appropriate source
  swarm_id = "#{@parent_swarm_id}/#{name}" # Hierarchical
  source = entry[:source]

  swarm = case source[:type]
  when :file
    SwarmLoader.load_from_file(
      source[:value],
      swarm_id: swarm_id,
      parent_swarm_id: @parent_swarm_id,
    )
  when :yaml
    SwarmLoader.load_from_yaml_string(
      source[:value],
      swarm_id: swarm_id,
      parent_swarm_id: @parent_swarm_id,
    )
  when :block
    SwarmLoader.load_from_block(
      source[:value],
      swarm_id: swarm_id,
      parent_swarm_id: @parent_swarm_id,
    )
  else
    raise ConfigurationError, "Unknown source type: #{source[:type]}"
  end

  entry[:instance] = swarm
  swarm
end

#register(name, source:, keep_context: true) ⇒ void

This method returns an undefined value.

Register a sub-swarm for lazy loading

Parameters:

  • name (String) —

    Registration name for the swarm

  • source (Hash) —

    Source specification with :type and :value

    • { type: :file, value: "./path/to/swarm.rb" }
    • { type: :yaml, value: "version: 2\n..." }
    • { type: :block, value: Proc }
  • keep_context (Boolean) (defaults to: true) —

    Whether to preserve conversation state between calls (default: true)

Raises:

  • (ArgumentError) —

    If swarm with same name already registered



48
49
50
51
52
53
54
55
56
 
# File 'lib/swarm_sdk/swarm_registry.rb', line 48

def register(name, source:, keep_context: true)
  raise ArgumentError, "Swarm '#{name}' already registered" if @registered_swarms.key?(name)

  @registered_swarms[name] = {
    source: source,
    keep_context: keep_context,
    instance: nil, # Lazy load
  }
end

#registered?(name) ⇒ Boolean

Check if a swarm is registered

Parameters:

  • name (String) —

    Swarm registration name

Returns:

  • (Boolean) —

    True if swarm is registered



62
63
64
 
# File 'lib/swarm_sdk/swarm_registry.rb', line 62

def registered?(name)
  @registered_swarms.key?(name)
end

#reset_if_needed(name) ⇒ void

This method returns an undefined value.

Reset swarm context if keep_context: false

Parameters:

  • name (String) —

    Swarm registration name



116
117
118
119
120
121
 
# File 'lib/swarm_sdk/swarm_registry.rb', line 116

def reset_if_needed(name)
  entry = @registered_swarms[name]
  return if entry[:keep_context]

  entry[:instance]&.reset_context!
end

#shutdown_all ⇒ void

This method returns an undefined value.

Cleanup all registered swarms

Stops all loaded swarm instances and clears the registry. Should be called when parent swarm is done.



129
130
131
132
133
134
 
# File 'lib/swarm_sdk/swarm_registry.rb', line 129

def shutdown_all
  @registered_swarms.each_value do |entry|
    entry[:instance]&.cleanup
  end
  @registered_swarms.clear
end