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.
- checksums.yaml +4 -4
- data/{CHANGELOG.md → CHANGELOG.claude-swarm.md} +3 -0
- data/CLAUDE.md +0 -1
- data/decisions/2025-11-22-001-global-agent-registry.md +172 -0
- data/docs/v2/CHANGELOG.swarm_cli.md +12 -0
- data/docs/v2/CHANGELOG.swarm_memory.md +139 -0
- data/docs/v2/CHANGELOG.swarm_sdk.md +249 -1
- data/docs/v2/README.md +15 -5
- data/docs/v2/guides/complete-tutorial.md +93 -7
- data/docs/v2/guides/getting-started.md +3 -1
- data/docs/v2/guides/memory-adapters.md +41 -0
- data/docs/v2/guides/{migrating-to-2.3.md → migrating-to-2.x.md} +213 -8
- data/docs/v2/guides/plugins.md +52 -5
- data/docs/v2/guides/rails-integration.md +6 -0
- data/docs/v2/guides/swarm-memory.md +2 -13
- data/docs/v2/reference/cli.md +0 -1
- data/docs/v2/reference/configuration_reference.md +300 -0
- data/docs/v2/reference/event_payload_structures.md +26 -4
- data/docs/v2/reference/ruby-dsl.md +457 -4
- data/docs/v2/reference/swarm_memory_technical_details.md +7 -29
- data/docs/v2/reference/yaml.md +2 -2
- data/lib/claude_swarm/mcp_generator.rb +1 -1
- data/lib/claude_swarm/orchestrator.rb +8 -1
- data/lib/claude_swarm/version.rb +1 -1
- data/lib/swarm_cli/version.rb +1 -1
- data/lib/swarm_memory/core/semantic_index.rb +10 -2
- data/lib/swarm_memory/core/storage.rb +7 -2
- data/lib/swarm_memory/dsl/memory_config.rb +37 -0
- data/lib/swarm_memory/integration/sdk_plugin.rb +120 -27
- data/lib/swarm_memory/optimization/defragmenter.rb +1 -1
- data/lib/swarm_memory/prompts/memory_researcher.md.erb +0 -1
- data/lib/swarm_memory/tools/load_skill.rb +0 -1
- data/lib/swarm_memory/tools/memory_edit.rb +2 -1
- data/lib/swarm_memory/tools/memory_read.rb +1 -1
- data/lib/swarm_memory/version.rb +1 -1
- data/lib/swarm_memory.rb +7 -5
- data/lib/swarm_sdk/agent/chat.rb +1 -1
- data/lib/swarm_sdk/agent/chat_helpers/context_tracker.rb +4 -0
- data/lib/swarm_sdk/agent/chat_helpers/hook_integration.rb +1 -1
- data/lib/swarm_sdk/agent/chat_helpers/llm_configuration.rb +38 -4
- data/lib/swarm_sdk/agent/chat_helpers/logging_helpers.rb +2 -2
- data/lib/swarm_sdk/agent/chat_helpers/system_reminder_injector.rb +3 -5
- data/lib/swarm_sdk/agent/chat_helpers/token_tracking.rb +48 -0
- data/lib/swarm_sdk/agent/context.rb +1 -2
- data/lib/swarm_sdk/agent/definition.rb +3 -3
- data/lib/swarm_sdk/agent/system_prompt_builder.rb +1 -1
- data/lib/swarm_sdk/agent_registry.rb +146 -0
- data/lib/swarm_sdk/builders/base_builder.rb +91 -12
- data/lib/swarm_sdk/config.rb +302 -0
- data/lib/swarm_sdk/configuration/parser.rb +22 -2
- data/lib/swarm_sdk/configuration.rb +13 -4
- data/lib/swarm_sdk/context_compactor/token_counter.rb +2 -6
- data/lib/swarm_sdk/custom_tool_registry.rb +226 -0
- data/lib/swarm_sdk/hooks/adapter.rb +3 -3
- data/lib/swarm_sdk/hooks/shell_executor.rb +4 -3
- data/lib/swarm_sdk/models.json +4333 -1
- data/lib/swarm_sdk/models.rb +43 -2
- data/lib/swarm_sdk/plugin.rb +2 -2
- data/lib/swarm_sdk/result.rb +52 -0
- data/lib/swarm_sdk/swarm/agent_initializer.rb +1 -1
- data/lib/swarm_sdk/swarm/hook_triggers.rb +1 -0
- data/lib/swarm_sdk/swarm/logging_callbacks.rb +1 -0
- data/lib/swarm_sdk/swarm/tool_configurator.rb +18 -4
- data/lib/swarm_sdk/swarm.rb +76 -13
- data/lib/swarm_sdk/tools/bash.rb +7 -9
- data/lib/swarm_sdk/tools/glob.rb +5 -5
- data/lib/swarm_sdk/tools/read.rb +8 -8
- data/lib/swarm_sdk/tools/stores/scratchpad_storage.rb +4 -3
- data/lib/swarm_sdk/tools/web_fetch.rb +20 -18
- data/lib/swarm_sdk/version.rb +1 -1
- data/lib/swarm_sdk/workflow/builder.rb +49 -0
- data/lib/swarm_sdk/workflow/node_builder.rb +4 -2
- data/lib/swarm_sdk/workflow/transformer_executor.rb +4 -3
- data/lib/swarm_sdk.rb +261 -105
- data/swarm_cli.gemspec +1 -1
- data/swarm_memory.gemspec +8 -3
- data/swarm_sdk.gemspec +4 -4
- data/team_full.yml +104 -300
- metadata +9 -5
- data/lib/swarm_memory/tools/memory_multi_edit.rb +0 -281
- /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
|
-
-
|
|
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**:
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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,
|
|
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
|
|
1
|
+
# Migrating SwarmSDK 2.x
|
|
2
2
|
|
|
3
|
-
This guide covers all breaking changes and migration steps for upgrading
|
|
3
|
+
This guide covers all breaking changes and migration steps for upgrading between SwarmSDK 2.x versions.
|
|
4
4
|
|
|
5
|
-
|
|
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**
|
|
512
|
-
-
|
|
513
|
-
-
|
|
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.
|
|
516
|
-
- No
|
|
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`
|
data/docs/v2/guides/plugins.md
CHANGED
|
@@ -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
|
|
89
|
-
def
|
|
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
|
|
220
|
-
def
|
|
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
|
|
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
|
-
-
|
|
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**:
|
|
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
|
data/docs/v2/reference/cli.md
CHANGED
|
@@ -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
|