claude_swarm 1.0.10 → 1.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. checksums.yaml +4 -4
  2. data/{CHANGELOG.md → CHANGELOG.claude-swarm.md} +3 -0
  3. data/CLAUDE.md +0 -1
  4. data/decisions/2025-11-22-001-global-agent-registry.md +172 -0
  5. data/docs/v2/CHANGELOG.swarm_cli.md +12 -0
  6. data/docs/v2/CHANGELOG.swarm_memory.md +139 -0
  7. data/docs/v2/CHANGELOG.swarm_sdk.md +249 -1
  8. data/docs/v2/README.md +15 -5
  9. data/docs/v2/guides/complete-tutorial.md +93 -7
  10. data/docs/v2/guides/getting-started.md +3 -1
  11. data/docs/v2/guides/memory-adapters.md +41 -0
  12. data/docs/v2/guides/{migrating-to-2.3.md → migrating-to-2.x.md} +213 -8
  13. data/docs/v2/guides/plugins.md +52 -5
  14. data/docs/v2/guides/rails-integration.md +6 -0
  15. data/docs/v2/guides/swarm-memory.md +2 -13
  16. data/docs/v2/reference/cli.md +0 -1
  17. data/docs/v2/reference/configuration_reference.md +300 -0
  18. data/docs/v2/reference/event_payload_structures.md +26 -4
  19. data/docs/v2/reference/ruby-dsl.md +457 -4
  20. data/docs/v2/reference/swarm_memory_technical_details.md +7 -29
  21. data/docs/v2/reference/yaml.md +2 -2
  22. data/lib/claude_swarm/mcp_generator.rb +1 -1
  23. data/lib/claude_swarm/orchestrator.rb +8 -1
  24. data/lib/claude_swarm/version.rb +1 -1
  25. data/lib/swarm_cli/version.rb +1 -1
  26. data/lib/swarm_memory/core/semantic_index.rb +10 -2
  27. data/lib/swarm_memory/core/storage.rb +7 -2
  28. data/lib/swarm_memory/dsl/memory_config.rb +37 -0
  29. data/lib/swarm_memory/integration/sdk_plugin.rb +120 -27
  30. data/lib/swarm_memory/optimization/defragmenter.rb +1 -1
  31. data/lib/swarm_memory/prompts/memory_researcher.md.erb +0 -1
  32. data/lib/swarm_memory/tools/load_skill.rb +0 -1
  33. data/lib/swarm_memory/tools/memory_edit.rb +2 -1
  34. data/lib/swarm_memory/tools/memory_read.rb +1 -1
  35. data/lib/swarm_memory/version.rb +1 -1
  36. data/lib/swarm_memory.rb +7 -5
  37. data/lib/swarm_sdk/agent/chat.rb +1 -1
  38. data/lib/swarm_sdk/agent/chat_helpers/context_tracker.rb +4 -0
  39. data/lib/swarm_sdk/agent/chat_helpers/hook_integration.rb +1 -1
  40. data/lib/swarm_sdk/agent/chat_helpers/llm_configuration.rb +38 -4
  41. data/lib/swarm_sdk/agent/chat_helpers/logging_helpers.rb +2 -2
  42. data/lib/swarm_sdk/agent/chat_helpers/system_reminder_injector.rb +3 -5
  43. data/lib/swarm_sdk/agent/chat_helpers/token_tracking.rb +48 -0
  44. data/lib/swarm_sdk/agent/context.rb +1 -2
  45. data/lib/swarm_sdk/agent/definition.rb +3 -3
  46. data/lib/swarm_sdk/agent/system_prompt_builder.rb +1 -1
  47. data/lib/swarm_sdk/agent_registry.rb +146 -0
  48. data/lib/swarm_sdk/builders/base_builder.rb +91 -12
  49. data/lib/swarm_sdk/config.rb +302 -0
  50. data/lib/swarm_sdk/configuration/parser.rb +22 -2
  51. data/lib/swarm_sdk/configuration.rb +13 -4
  52. data/lib/swarm_sdk/context_compactor/token_counter.rb +2 -6
  53. data/lib/swarm_sdk/custom_tool_registry.rb +226 -0
  54. data/lib/swarm_sdk/hooks/adapter.rb +3 -3
  55. data/lib/swarm_sdk/hooks/shell_executor.rb +4 -3
  56. data/lib/swarm_sdk/models.json +4333 -1
  57. data/lib/swarm_sdk/models.rb +43 -2
  58. data/lib/swarm_sdk/plugin.rb +2 -2
  59. data/lib/swarm_sdk/result.rb +52 -0
  60. data/lib/swarm_sdk/swarm/agent_initializer.rb +1 -1
  61. data/lib/swarm_sdk/swarm/hook_triggers.rb +1 -0
  62. data/lib/swarm_sdk/swarm/logging_callbacks.rb +1 -0
  63. data/lib/swarm_sdk/swarm/tool_configurator.rb +18 -4
  64. data/lib/swarm_sdk/swarm.rb +76 -13
  65. data/lib/swarm_sdk/tools/bash.rb +7 -9
  66. data/lib/swarm_sdk/tools/glob.rb +5 -5
  67. data/lib/swarm_sdk/tools/read.rb +8 -8
  68. data/lib/swarm_sdk/tools/stores/scratchpad_storage.rb +4 -3
  69. data/lib/swarm_sdk/tools/web_fetch.rb +20 -18
  70. data/lib/swarm_sdk/version.rb +1 -1
  71. data/lib/swarm_sdk/workflow/builder.rb +49 -0
  72. data/lib/swarm_sdk/workflow/node_builder.rb +4 -2
  73. data/lib/swarm_sdk/workflow/transformer_executor.rb +4 -3
  74. data/lib/swarm_sdk.rb +261 -105
  75. data/swarm_cli.gemspec +1 -1
  76. data/swarm_memory.gemspec +8 -3
  77. data/swarm_sdk.gemspec +4 -4
  78. data/team_full.yml +104 -300
  79. metadata +9 -5
  80. data/lib/swarm_memory/tools/memory_multi_edit.rb +0 -281
  81. /data/lib/swarm_memory/{errors.rb → error.rb} +0 -0
data/docs/v2/README.md CHANGED
@@ -1,7 +1,5 @@
1
1
  # SwarmSDK, SwarmCLI & SwarmMemory Documentation
2
2
 
3
- **Version 2.3**
4
-
5
3
  Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory - a Ruby framework for orchestrating multiple AI agents as a collaborative team with persistent memory.
6
4
 
7
5
  ---
@@ -63,6 +61,10 @@ Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory -
63
61
  - **[Ruby DSL Reference](reference/ruby-dsl.md)**
64
62
  Complete programmatic API: `SwarmSDK.build`, `SwarmSDK.load`, agent DSL, permissions DSL, node DSL, hooks
65
63
 
64
+ ### Configuration
65
+ - **[Configuration Reference](reference/configuration_reference.md)** ⭐ NEW
66
+ Complete reference for all 45+ configuration options: API keys, timeouts, limits, WebFetch settings, security
67
+
66
68
  ### YAML Configuration
67
69
  - **[YAML Configuration Reference](reference/yaml.md)**
68
70
  Complete YAML structure: agents, tools, permissions, hooks, nodes, MCP servers
@@ -90,7 +92,7 @@ Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory -
90
92
  Persistent agent knowledge storage with semantic search:
91
93
  - Installation and setup
92
94
  - 4 memory categories (concept, fact, skill, experience)
93
- - 9 memory tools (MemoryWrite, LoadSkill, etc.)
95
+ - 8 memory tools (7 memory tools + LoadSkill for dynamic tool swapping)
94
96
  - Automatic skill discovery (hybrid semantic + keyword)
95
97
  - Relationship discovery and knowledge graphs
96
98
  - Performance and troubleshooting
@@ -199,12 +201,18 @@ Welcome to the official documentation for SwarmSDK, SwarmCLI, and SwarmMemory -
199
201
  **Build composable/reusable swarm teams** ⭐ NEW
200
202
  → [Composable Swarms Guide](guides/composable-swarms.md)
201
203
 
204
+ **Add custom tools to agents**
205
+ → [Ruby DSL Reference - Custom Tools](reference/ruby-dsl.md#custom-tool-registration)
206
+
202
207
  **Build a SwarmSDK plugin**
203
208
  → [Plugin System Guide](guides/plugins.md)
204
209
 
205
210
  **Build a custom storage adapter**
206
211
  → [Memory Adapter Guide](guides/memory-adapters.md)
207
212
 
213
+ **Configure SwarmSDK settings** ⭐ NEW
214
+ → [Configuration Reference](reference/configuration_reference.md)
215
+
208
216
  **Secure swarms for production** ⭐ NEW
209
217
  → [Filesystem Tools Control](reference/ruby-dsl.md#swarmsdk.configure) | [Security Considerations](guides/complete-tutorial.md#security-considerations)
210
218
 
@@ -237,6 +245,7 @@ docs/v2/
237
245
  ├── reference/ # Complete API references
238
246
  │ ├── architecture-flow.md # System architecture diagram ⭐ NEW
239
247
  │ ├── execution-flow.md # Runtime execution flow ⭐ NEW
248
+ │ ├── configuration_reference.md # All configuration options ⭐ NEW
240
249
  │ ├── event_payload_structures.md # Log event payloads
241
250
  │ ├── swarm_memory_technical_details.md # SwarmMemory deep dive
242
251
  │ ├── cli.md # CLI command reference
@@ -297,8 +306,8 @@ A command-line interface for running SwarmSDK swarms with two modes:
297
306
  A persistent memory system for agents with semantic search capabilities:
298
307
  - **Storage**: Hierarchical knowledge organization (concept, fact, skill, experience)
299
308
  - **Semantic Search**: FAISS-based vector similarity with local ONNX embeddings
300
- - **Memory Tools**: 9 tools for writing, reading, editing, and searching knowledge
301
- - **LoadSkill**: Dynamic tool swapping based on semantic skill discovery
309
+ - **Memory Tools**: 7 tools for writing, reading, editing, and searching knowledge
310
+ - **LoadSkill**: Dynamic tool swapping based on semantic skill discovery (8 tools total)
302
311
  - **Plugin Architecture**: Integrates seamlessly via SwarmSDK plugin system
303
312
 
304
313
  ### Configuration Formats
@@ -328,6 +337,7 @@ A persistent memory system for agents with semantic search capabilities:
328
337
  | **Memory Adapters** | [Adapter Guide](guides/memory-adapters.md) | [Technical Details](reference/swarm_memory_technical_details.md) |
329
338
  | **Plugins** | [Plugin Guide](guides/plugins.md) | - |
330
339
  | **Rails** | [Rails Guide](guides/rails-integration.md) | - |
340
+ | **Configuration** | - | [Configuration Ref](reference/configuration_reference.md) |
331
341
  | **Testing** | [Tutorial Part 8](guides/complete-tutorial.md#testing-strategies) | - |
332
342
 
333
343
  ---
@@ -2858,7 +2858,93 @@ project/
2858
2858
  └── .env # API keys
2859
2859
  ```
2860
2860
 
2861
- ### 8.3 Testing Strategies
2861
+ ### 8.3 Reusable Agent Definitions (Global Registry)
2862
+
2863
+ For large projects, define agents once and reuse them across multiple swarms.
2864
+
2865
+ **Register agents globally:**
2866
+ ```ruby
2867
+ # agents/backend.rb
2868
+ SwarmSDK.agent :backend do
2869
+ model "claude-sonnet-4"
2870
+ description "Backend developer"
2871
+ system_prompt "You build APIs and databases"
2872
+ tools :Read, :Edit, :Bash
2873
+ # Note: Don't set delegates_to here - it's swarm-specific!
2874
+ end
2875
+
2876
+ # agents/database.rb
2877
+ SwarmSDK.agent :database do
2878
+ model "claude-sonnet-4"
2879
+ description "Database specialist"
2880
+ system_prompt "You design schemas and write migrations"
2881
+ tools :Read, :Edit
2882
+ end
2883
+ ```
2884
+
2885
+ **Reference in swarms (set delegation per-swarm):**
2886
+ ```ruby
2887
+ # Load agent definitions first
2888
+ require_relative "agents/backend"
2889
+ require_relative "agents/database"
2890
+
2891
+ # Reference by name and configure delegation (swarm-specific)
2892
+ swarm = SwarmSDK.build do
2893
+ name "Dev Team"
2894
+ lead :backend
2895
+
2896
+ agent :backend do
2897
+ delegates_to :database # Delegation is swarm-specific
2898
+ end
2899
+ agent :database # Pulls from registry as-is
2900
+ end
2901
+ ```
2902
+
2903
+ **Override other registry settings:**
2904
+ ```ruby
2905
+ swarm = SwarmSDK.build do
2906
+ name "Extended Team"
2907
+ lead :backend
2908
+
2909
+ # Registry config applied first, then override block
2910
+ agent :backend do
2911
+ delegates_to :database, :cache # Set delegation for this swarm
2912
+ tools :CustomTool # Adds to registry tools
2913
+ timeout 300 # Overrides registry timeout
2914
+ end
2915
+ end
2916
+ ```
2917
+
2918
+ **Workflow auto-resolution:**
2919
+ Agents referenced in workflow nodes automatically resolve from the global registry:
2920
+
2921
+ ```ruby
2922
+ SwarmSDK.workflow do
2923
+ name "Pipeline"
2924
+ start_node :build
2925
+
2926
+ # No need to define :backend here - auto-resolved from registry!
2927
+ node :build do
2928
+ agent(:backend)
2929
+ end
2930
+ end
2931
+ ```
2932
+
2933
+ **Testing with registry:**
2934
+ ```ruby
2935
+ # Clear registry between tests
2936
+ def setup
2937
+ SwarmSDK.clear_agent_registry!
2938
+ end
2939
+ ```
2940
+
2941
+ **Benefits:**
2942
+ - **Code reuse**: Define agents once, use in multiple swarms
2943
+ - **Separation of concerns**: Agent definitions in dedicated files
2944
+ - **Organization**: Large projects with many agents stay manageable
2945
+ - **DRY principle**: No duplication of agent configurations
2946
+
2947
+ ### 8.4 Testing Strategies
2862
2948
 
2863
2949
  **Unit test agents**:
2864
2950
  ```ruby
@@ -2920,7 +3006,7 @@ allow(LLM).to receive(:chat).and_return(
2920
3006
  )
2921
3007
  ```
2922
3008
 
2923
- ### 8.4 Performance Optimization
3009
+ ### 8.5 Performance Optimization
2924
3010
 
2925
3011
  **1. Choose appropriate models**:
2926
3012
  ```ruby
@@ -2993,7 +3079,7 @@ node :summarizer do
2993
3079
  end
2994
3080
  ```
2995
3081
 
2996
- ### 8.5 Security Considerations
3082
+ ### 8.6 Security Considerations
2997
3083
 
2998
3084
  **1. Restrict file access**:
2999
3085
  ```ruby
@@ -3099,7 +3185,7 @@ end
3099
3185
  - **Priority**: Explicit parameter > Global setting > Environment variable > Default (true)
3100
3186
  - **Non-breaking**: Defaults to `true` for backward compatibility
3101
3187
 
3102
- ### 8.6 Cost Management
3188
+ ### 8.7 Cost Management
3103
3189
 
3104
3190
  **Track costs in real-time**:
3105
3191
  ```ruby
@@ -3153,7 +3239,7 @@ end
3153
3239
  - [ ] Batch similar operations
3154
3240
  - [ ] Monitor and set cost alerts
3155
3241
 
3156
- ### 8.7 Monitoring and Observability
3242
+ ### 8.8 Monitoring and Observability
3157
3243
 
3158
3244
  **Structured logging to files**:
3159
3245
  ```ruby
@@ -3205,7 +3291,7 @@ end
3205
3291
  }
3206
3292
  ```
3207
3293
 
3208
- ### 8.8 Common Patterns Summary
3294
+ ### 8.9 Common Patterns Summary
3209
3295
 
3210
3296
  **Pattern: Code Review Workflow**
3211
3297
  ```
@@ -3263,7 +3349,7 @@ You've now learned **100% of SwarmSDK features**:
3263
3349
 
3264
3350
  ✅ **Part 7: Production Features** - Structured logging, token/cost tracking, error handling, validation, document conversion
3265
3351
 
3266
- ✅ **Part 8: Best Practices** - Architecture patterns, testing strategies, performance optimization, security, cost management, monitoring
3352
+ ✅ **Part 8: Best Practices** - Architecture patterns, reusable agent definitions (global registry), testing strategies, performance optimization, security, cost management, monitoring
3267
3353
 
3268
3354
  ## Next Steps
3269
3355
 
@@ -192,7 +192,7 @@ Tools are functions agents call to interact with the world. SwarmSDK provides:
192
192
  | **Web** | WebFetch | Fetch and process web content |
193
193
  | **Task Management** | TodoWrite | Track progress on multi-step tasks |
194
194
  | **Shared Scratchpad** | ScratchpadWrite, ScratchpadRead, ScratchpadList | Share work-in-progress between agents (volatile) |
195
- | **Per-Agent Memory** | MemoryWrite, MemoryRead, MemoryEdit, MemoryMultiEdit, MemoryGlob, MemoryGrep, MemoryDelete | Persistent learning and knowledge storage (opt-in) |
195
+ | **Per-Agent Memory** | MemoryWrite, MemoryRead, MemoryEdit, MemoryGlob, MemoryGrep, MemoryDelete | Persistent learning and knowledge storage (opt-in) |
196
196
  | **Reasoning** | Think | Extended reasoning for complex problems |
197
197
 
198
198
  **Default tools**: Every agent automatically gets **Read, Grep, and Glob** unless you explicitly disable them with `disable_default_tools: true`. Scratchpad tools (ScratchpadWrite, ScratchpadRead, ScratchpadList) are opt-in via `scratchpad: :enabled`.
@@ -1239,6 +1239,8 @@ Congratulations! You've learned the fundamentals of SwarmSDK.
1239
1239
 
1240
1240
  **Agent Delegation Patterns**: Learn advanced collaboration strategies like hierarchical delegation, peer collaboration, and specialist chains.
1241
1241
 
1242
+ **Reusable Agent Definitions**: Use the Global Agent Registry (`SwarmSDK.agent`) to define agents once and reuse them across multiple swarms—perfect for large projects with shared agents.
1243
+
1242
1244
  **Permissions System**: Discover how to restrict agents to specific directories, prevent dangerous commands, and create secure multi-agent systems.
1243
1245
 
1244
1246
  **Hooks and Customization**: Master pre/post hooks for tool calls, prompt injection, and workflow automation.
@@ -193,6 +193,47 @@ end
193
193
  # MyAdapter.new(namespace: "researcher", table_name: "memory_entries")
194
194
  ```
195
195
 
196
+ ### YAML Configuration
197
+
198
+ Custom adapters also work seamlessly with YAML configuration. All YAML keys (except `directory`, `adapter`, `mode`) are automatically passed to the adapter constructor:
199
+
200
+ ```yaml
201
+ # swarm.yml
202
+ agents:
203
+ researcher:
204
+ memory:
205
+ adapter: multi_bank_postgres
206
+ agent_id: researcher
207
+ discovery_threshold: 0.5
208
+ discovery_threshold_short: 0.3
209
+ semantic_weight: 0.6
210
+ default_bank: working
211
+ banks:
212
+ working: { max_size: 10485760 }
213
+ long_term: { max_size: 52428800 }
214
+ ```
215
+
216
+ This configuration creates an adapter with:
217
+ ```ruby
218
+ MultiBankPostgresAdapter.new(
219
+ agent_id: "researcher",
220
+ discovery_threshold: 0.5,
221
+ discovery_threshold_short: 0.3,
222
+ semantic_weight: 0.6,
223
+ default_bank: "working",
224
+ banks: {
225
+ "working" => { "max_size" => 10485760 },
226
+ "long_term" => { "max_size" => 52428800 }
227
+ }
228
+ )
229
+ ```
230
+
231
+ **Benefits:**
232
+ - ✅ No code changes needed for configuration
233
+ - ✅ Per-agent customization via YAML
234
+ - ✅ All options passed directly to adapter
235
+ - ✅ Each adapter validates its own requirements
236
+
196
237
  ---
197
238
 
198
239
  ## Example: ActiveRecord Adapter (PostgreSQL/Rails)
@@ -1,8 +1,197 @@
1
- # Migrating to SwarmSDK v2.3.0
1
+ # Migrating SwarmSDK 2.x
2
2
 
3
- This guide covers all breaking changes and migration steps for upgrading from SwarmSDK v2.2.x to v2.3.0.
3
+ This guide covers all breaking changes and migration steps for upgrading between SwarmSDK 2.x versions.
4
4
 
5
- ## Overview
5
+ ---
6
+
7
+ ## Migrating to v2.4.0
8
+
9
+ ### Overview
10
+
11
+ SwarmSDK v2.4.0 introduces a centralized configuration system that replaces the previous `SwarmSDK.settings` approach.
12
+
13
+ ### Breaking Changes
14
+
15
+ #### 1. Configuration API Change
16
+
17
+ **What Changed:**
18
+ - `SwarmSDK.settings` replaced with `SwarmSDK.config` singleton
19
+ - New `SwarmSDK.configure` block syntax for setting values
20
+ - Lazy ENV loading with thread-safe initialization
21
+ - Auto-proxying of API keys to RubyLLM
22
+
23
+ **Before (v2.3.x):**
24
+ ```ruby
25
+ # Direct property access
26
+ SwarmSDK.settings.openai_api_key = "sk-..."
27
+ SwarmSDK.settings.default_model = "gpt-5"
28
+ SwarmSDK.settings.allow_filesystem_tools = false
29
+
30
+ # Reading values
31
+ model = SwarmSDK.settings.default_model
32
+ ```
33
+
34
+ **After (v2.4.0):**
35
+ ```ruby
36
+ # Block-based configuration
37
+ SwarmSDK.configure do |config|
38
+ config.openai_api_key = "sk-..."
39
+ config.default_model = "gpt-5"
40
+ config.allow_filesystem_tools = false
41
+ end
42
+
43
+ # Reading values
44
+ model = SwarmSDK.config.default_model
45
+ ```
46
+
47
+ **Migration Steps:**
48
+
49
+ 1. **Replace all `SwarmSDK.settings` with `SwarmSDK.config`:**
50
+ ```ruby
51
+ # Before
52
+ timeout = SwarmSDK.settings.agent_request_timeout
53
+
54
+ # After
55
+ timeout = SwarmSDK.config.agent_request_timeout
56
+ ```
57
+
58
+ 2. **Use configure block for setting multiple values:**
59
+ ```ruby
60
+ # Before
61
+ SwarmSDK.settings.openai_api_key = ENV["OPENAI_API_KEY"]
62
+ SwarmSDK.settings.default_model = "claude-sonnet-4"
63
+ SwarmSDK.settings.agent_request_timeout = 600
64
+
65
+ # After
66
+ SwarmSDK.configure do |config|
67
+ config.openai_api_key = ENV["OPENAI_API_KEY"]
68
+ config.default_model = "claude-sonnet-4"
69
+ config.agent_request_timeout = 600
70
+ end
71
+ ```
72
+
73
+ 3. **Update test setup/teardown:**
74
+ ```ruby
75
+ # Before
76
+ def setup
77
+ @original = SwarmSDK.settings.default_model
78
+ SwarmSDK.settings.default_model = "test-model"
79
+ end
80
+
81
+ def teardown
82
+ SwarmSDK.settings.default_model = @original
83
+ end
84
+
85
+ # After
86
+ def setup
87
+ SwarmSDK.reset_config!
88
+ SwarmSDK.configure do |config|
89
+ config.default_model = "test-model"
90
+ end
91
+ end
92
+
93
+ def teardown
94
+ SwarmSDK.reset_config!
95
+ end
96
+ ```
97
+
98
+ #### 2. API Key Auto-Proxying
99
+
100
+ **What Changed:**
101
+ - API keys set via `SwarmSDK.configure` are automatically proxied to `RubyLLM.config`
102
+ - No need to configure both SwarmSDK and RubyLLM separately
103
+
104
+ **Before (v2.3.x):**
105
+ ```ruby
106
+ # Had to configure both
107
+ SwarmSDK.settings.openai_api_key = "sk-..."
108
+ RubyLLM.config.openai_api_key = "sk-..."
109
+ ```
110
+
111
+ **After (v2.4.0):**
112
+ ```ruby
113
+ # Only configure SwarmSDK - auto-proxied to RubyLLM
114
+ SwarmSDK.configure do |config|
115
+ config.openai_api_key = "sk-..."
116
+ end
117
+ # RubyLLM.config.openai_api_key is now also set
118
+ ```
119
+
120
+ #### 3. Configuration Priority
121
+
122
+ Values are resolved in this order:
123
+ 1. **Explicit value** (set via `SwarmSDK.configure`)
124
+ 2. **Environment variable** (e.g., `SWARM_SDK_DEFAULT_MODEL`)
125
+ 3. **Default value** (from `SwarmSDK::Defaults` module)
126
+
127
+ ```ruby
128
+ # ENV has SWARM_SDK_DEFAULT_MODEL=gpt-4o
129
+
130
+ # Without explicit config - uses ENV
131
+ SwarmSDK.config.default_model # => "gpt-4o"
132
+
133
+ # With explicit config - overrides ENV
134
+ SwarmSDK.configure do |config|
135
+ config.default_model = "claude-sonnet-4"
136
+ end
137
+ SwarmSDK.config.default_model # => "claude-sonnet-4"
138
+ ```
139
+
140
+ ### New Features
141
+
142
+ #### Configuration Reference
143
+
144
+ See [Configuration Reference](../reference/configuration_reference.md) for all 45+ configuration options including:
145
+ - API keys for all providers
146
+ - Timeouts and limits
147
+ - WebFetch LLM processing
148
+ - Security settings
149
+
150
+ #### New Helper Methods
151
+
152
+ ```ruby
153
+ # Check if WebFetch LLM processing is enabled
154
+ SwarmSDK.config.webfetch_llm_enabled?
155
+
156
+ # Reset config for testing
157
+ SwarmSDK.reset_config!
158
+ ```
159
+
160
+ ### Testing Your Migration
161
+
162
+ ```ruby
163
+ describe "v2.4.0 Migration" do
164
+ def setup
165
+ SwarmSDK.reset_config!
166
+ end
167
+
168
+ def teardown
169
+ SwarmSDK.reset_config!
170
+ end
171
+
172
+ it "uses new config API" do
173
+ SwarmSDK.configure do |config|
174
+ config.default_model = "test-model"
175
+ end
176
+
177
+ assert_equal "test-model", SwarmSDK.config.default_model
178
+ end
179
+
180
+ it "auto-proxies API keys to RubyLLM" do
181
+ SwarmSDK.configure do |config|
182
+ config.openai_api_key = "test-key"
183
+ end
184
+
185
+ assert_equal "test-key", RubyLLM.config.openai_api_key
186
+ end
187
+ end
188
+ ```
189
+
190
+ ---
191
+
192
+ ## Migrating to v2.3.0
193
+
194
+ ### Overview
6
195
 
7
196
  SwarmSDK v2.3.0 introduces significant architectural improvements:
8
197
 
@@ -508,12 +697,19 @@ end
508
697
 
509
698
  ## Deprecation Timeline
510
699
 
511
- - **v2.3.0** (This Release)
512
- - Old APIs removed (no deprecation warnings)
513
- - Migration required immediately
700
+ - **v2.3.0**
701
+ - Swarm/Workflow API separation
702
+ - Delegation tool rebranding
703
+ - Agent::Chat abstraction layer
704
+ - Snapshot format v2.1.0
705
+
706
+ - **v2.4.0** (Current Release)
707
+ - `SwarmSDK.settings` → `SwarmSDK.config`
708
+ - Centralized configuration system
709
+ - API key auto-proxying to RubyLLM
514
710
 
515
- - **v2.4.0** (Future)
516
- - No further breaking changes planned
711
+ - **v2.5.0** (Future)
712
+ - No breaking changes planned
517
713
  - Focus on new features
518
714
 
519
715
  ---
@@ -531,6 +727,13 @@ If you encounter issues during migration:
531
727
 
532
728
  ## Summary Checklist
533
729
 
730
+ ### v2.4.0 Migration
731
+ - [ ] Replace `SwarmSDK.settings` with `SwarmSDK.config`
732
+ - [ ] Use `SwarmSDK.configure` block for setting values
733
+ - [ ] Update test setup/teardown to use `SwarmSDK.reset_config!`
734
+ - [ ] Remove duplicate RubyLLM API key configuration (auto-proxied now)
735
+
736
+ ### v2.3.0 Migration
534
737
  - [ ] Update delegation tool calls: `DelegateTaskTo*` → `WorkWith*`
535
738
  - [ ] Update delegation parameters: `task:` → `message:`
536
739
  - [ ] Update Chat API usage: `tools.key?` → `has_tool?`, etc.
@@ -538,4 +741,6 @@ If you encounter issues during migration:
538
741
  - [ ] Update YAML: `swarm:` key for swarms, `workflow:` key for workflows
539
742
  - [ ] Regenerate snapshots (v1.0.0 → v2.1.0)
540
743
  - [ ] Update custom plugins with new lifecycle methods
744
+
745
+ ### Final Step
541
746
  - [ ] Test all changes with `bundle exec rake swarm_sdk:test`
@@ -21,6 +21,53 @@ The **plugin system** allows gems to extend SwarmSDK without creating tight coup
21
21
  - 🛠️ **Tool Provider** - Plugins create and manage their own tools
22
22
  - 📦 **Storage Provider** - Plugins handle their own data persistence
23
23
 
24
+ ### Plugins vs Custom Tools
25
+
26
+ SwarmSDK offers two ways to add custom functionality:
27
+
28
+ | Feature | Custom Tools (`SwarmSDK.register_tool`) | Plugins |
29
+ |---------|----------------------------------------|---------|
30
+ | **Use Case** | Simple, stateless tools | Complex features with storage & hooks |
31
+ | **Setup** | One line: `register_tool(ToolClass)` | Full plugin class with lifecycle |
32
+ | **Storage** | ❌ No persistent storage | ✅ Per-agent storage |
33
+ | **Lifecycle Hooks** | ❌ No hooks | ✅ on_agent_initialized, on_user_message, etc. |
34
+ | **System Prompts** | ❌ No prompt injection | ✅ Can contribute to system prompts |
35
+ | **Examples** | Weather API, Calculator | SwarmMemory (persistent knowledge) |
36
+
37
+ **Choose Custom Tools when:**
38
+ - Tool is simple and stateless
39
+ - No need for persistent storage
40
+ - No lifecycle hooks required
41
+ - Want quickest setup
42
+
43
+ **Choose Plugins when:**
44
+ - Need per-agent storage
45
+ - Need lifecycle hooks
46
+ - Want to contribute to system prompts
47
+ - Building a suite of related tools
48
+
49
+ **Custom Tool Example:**
50
+ ```ruby
51
+ class WeatherTool < RubyLLM::Tool
52
+ description "Get weather for a city"
53
+ param :city, type: "string", required: true
54
+
55
+ def execute(city:)
56
+ "Weather in #{city}: Sunny"
57
+ end
58
+ end
59
+
60
+ SwarmSDK.register_tool(WeatherTool)
61
+
62
+ SwarmSDK.build do
63
+ agent :helper do
64
+ tools :Weather # Use the registered tool
65
+ end
66
+ end
67
+ ```
68
+
69
+ See the Ruby DSL reference for complete custom tool documentation.
70
+
24
71
  ---
25
72
 
26
73
  ## Architecture
@@ -85,8 +132,8 @@ module MyPlugin
85
132
  end
86
133
  end
87
134
 
88
- # Check if storage should be created for an agent
89
- def storage_enabled?(agent_definition)
135
+ # Check if memory should be configured for an agent
136
+ def memory_configured?(agent_definition)
90
137
  agent_definition.respond_to?(:my_plugin) && agent_definition.my_plugin
91
138
  end
92
139
 
@@ -216,8 +263,8 @@ def create_storage(agent_name:, config:)
216
263
  MyStorage.new(...)
217
264
  end
218
265
 
219
- # Check if storage should be created
220
- def storage_enabled?(agent_definition)
266
+ # Check if memory should be configured
267
+ def memory_configured?(agent_definition)
221
268
  agent_definition.respond_to?(:my_plugin)
222
269
  end
223
270
 
@@ -750,7 +797,7 @@ class StoragePlugin < SwarmSDK::Plugin
750
797
  :database
751
798
  end
752
799
 
753
- def storage_enabled?(agent_definition)
800
+ def memory_configured?(agent_definition)
754
801
  agent_definition.respond_to?(:database)
755
802
  end
756
803
 
@@ -45,6 +45,12 @@ Install dependencies:
45
45
  bundle install
46
46
  ```
47
47
 
48
+ ### Set the active support isolation level to :Fiber
49
+ Edit `config/application.rb` and add:
50
+ ```
51
+ config.active_support.isolation_level = :fiber
52
+ ```
53
+
48
54
  ### Create Initializer
49
55
 
50
56
  Create `config/initializers/swarm_sdk.rb`:
@@ -113,7 +113,7 @@ Auto-registration: SwarmMemory::Integration::SDKPlugin
113
113
  SwarmSDK::PluginRegistry.register(plugin)
114
114
 
115
115
  Plugin provides:
116
- - 8 memory tools (MemoryWrite, MemoryRead, etc.)
116
+ - 7 memory tools (MemoryWrite, MemoryRead, MemoryEdit, MemoryDelete, MemoryGlob, MemoryGrep, MemoryDefrag)
117
117
  - Memory storage (FilesystemAdapter + Embeddings)
118
118
  - System prompt contributions
119
119
  - Automatic skill discovery on user messages
@@ -190,17 +190,6 @@ MemoryEdit(
190
190
  )
191
191
  ```
192
192
 
193
- **MemoryMultiEdit** - Multiple edits in one operation
194
- ```ruby
195
- MemoryMultiEdit(
196
- file_path: "concept/ruby/classes.md",
197
- edits_json: '[
198
- {"old_string": "foo", "new_string": "bar"},
199
- {"old_string": "baz", "new_string": "qux"}
200
- ]'
201
- )
202
- ```
203
-
204
193
  **MemoryDelete** - Remove entries
205
194
  ```ruby
206
195
  MemoryDelete(file_path: "concept/old-api/deprecated.md")
@@ -382,7 +371,7 @@ end
382
371
  When memory is configured:
383
372
 
384
373
  1. **Storage Created**: `FilesystemAdapter` + `InformersEmbedder`
385
- 2. **Tools Registered**: 8 memory tools + LoadSkill
374
+ 2. **Tools Registered**: 7 memory tools + LoadSkill (8 total)
386
375
  3. **Prompt Injected**: Memory system guidance
387
376
  4. **Discovery Enabled**: Semantic search on user messages
388
377
  5. **Embeddings Generated**: For all stored content
@@ -401,7 +401,6 @@ Starts an MCP server that exposes SwarmSDK tools (Read, Write, Edit, Bash, Grep,
401
401
  - `MemoryWrite`: Write to per-agent memory (persistent)
402
402
  - `MemoryRead`: Read from memory (with line numbers)
403
403
  - `MemoryEdit`: Edit memory entries
404
- - `MemoryMultiEdit`: Apply multiple edits to memory
405
404
  - `MemoryGlob`: Search memory by glob pattern
406
405
  - `MemoryGrep`: Search memory content by regex
407
406
  - `MemoryDelete`: Delete memory entries