swarm_sdk 2.1.2 → 2.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a77daa5d8abcd0cae1b1edad441d93421d25ecbf15a0713697d9eabb6c4dc00e
-  data.tar.gz: 97c037f892d03992b12292a31bc3ab9359ccacead39d37466af84ef5660e4933
+  metadata.gz: e5d0702a4e7e567c81f3a9974fdc197f4e3247fe9d6ce38d5a80b373423fff40
+  data.tar.gz: f6907d5c9baa55ab32e19cbe440643cb169aac1d1c9ef4501679357f63ec364c
 SHA512:
-  metadata.gz: e7620b869014c9f1b889795310ec1d648cbcc55fc53a3cbb7023c37b403f83c57e5f3645b4f8ffdd38d60fa4877fa24d9ab3f0ccf0de3b2be6a45420516dbf50
-  data.tar.gz: bc081f3a444bb410a22dc2e5971f258dd43dadaa69d53558e799d036149412bfecf8d95396aa0f6e1f0c39cf6716b986722669265b32cc2b550f7daa0a6e9c2c
+  metadata.gz: 460b59be54dc659ba6eb6cc37e9946ac9edd14d946bde9672f7a02c119cd89792b7253f2de29238fc9493cc4cdffa19283e83c4f86417840050fd1cf1dd33766
+  data.tar.gz: 5a377235df41937afacc67ac76ba8420960931bd1f72f64d77db2c86741a55bf0ea05918f78922f7bf4645f7beb0a8b2420413395a5fec267f098e10106d28e4

data/lib/swarm_sdk/agent/definition.rb

@@ -358,7 +358,7 @@ module SwarmSDK
 
       def render_non_coding_base_prompt
         # Simplified base prompt for non-coding agents
-        # Includes environment info, TODO, and Scratchpad tool information
+        # Includes environment info only
         # Does not steer towards coding tasks
         cwd = @directory || Dir.pwd
         platform = RUBY_PLATFORM
@@ -383,25 +383,6 @@ module SwarmSDK
           Platform: #{platform}
           OS Version: #{os_version}
           </env>
-
-          # Task Management
-
-          You have access to the TodoWrite tool to help you manage and plan tasks. Use this tool to track your progress and give visibility into your work.
-
-          When working on multi-step tasks:
-          1. Create a todo list with all known tasks before starting work
-          2. Mark each task as in_progress when you start it
-          3. Mark each task as completed IMMEDIATELY after finishing it
-          4. Complete ALL pending todos before finishing your response
-
-          # Scratchpad Storage
-
-          You have access to Scratchpad tools for storing and retrieving information:
-          - **ScratchpadWrite**: Store detailed outputs, analysis, or results that are too long for direct responses
-          - **ScratchpadRead**: Retrieve previously stored content
-          - **ScratchpadList**: List available scratchpad entries
-
-          Use the scratchpad to share information that would otherwise clutter your responses.
         PROMPT
       end
 

data/lib/swarm_sdk/configuration.rb

@@ -4,17 +4,43 @@ module SwarmSDK
   class Configuration
     ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
 
-    attr_reader :config_path, :swarm_name, :lead_agent, :agents, :all_agents_config, :swarm_hooks, :all_agents_hooks, :scratchpad_enabled
+    attr_reader :swarm_name, :lead_agent, :agents, :all_agents_config, :swarm_hooks, :all_agents_hooks, :scratchpad_enabled
 
     class << self
-      def load(path)
-        new(path).tap(&:load_and_validate)
+      # Load configuration from YAML file
+      #
+      # Convenience method that reads the file and uses the file's directory
+      # as the base directory for resolving agent file paths.
+      #
+      # @param path [String, Pathname] Path to YAML configuration file
+      # @return [Configuration] Validated configuration instance
+      # @raise [ConfigurationError] If file not found or invalid
+      def load_file(path)
+        path = Pathname.new(path).expand_path
+
+        unless path.exist?
+          raise ConfigurationError, "Configuration file not found: #{path}"
+        end
+
+        yaml_content = File.read(path)
+        base_dir = path.dirname
+
+        new(yaml_content, base_dir: base_dir).tap(&:load_and_validate)
+      rescue Errno::ENOENT
+        raise ConfigurationError, "Configuration file not found: #{path}"
       end
     end
 
-    def initialize(config_path)
-      @config_path = Pathname.new(config_path).expand_path
-      @config_dir = @config_path.dirname
+    # Initialize configuration from YAML string
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    def initialize(yaml_content, base_dir: Dir.pwd)
+      raise ArgumentError, "yaml_content cannot be nil" if yaml_content.nil?
+      raise ArgumentError, "base_dir cannot be nil" if base_dir.nil?
+
+      @yaml_content = yaml_content
+      @base_dir = Pathname.new(base_dir).expand_path
       @agents = {}
       @all_agents_config = {} # Settings applied to all agents
       @swarm_hooks = {} # Swarm-level hooks (swarm_start, swarm_stop)
@@ -22,7 +48,7 @@ module SwarmSDK
     end
 
     def load_and_validate
-      @config = YAML.load_file(@config_path, aliases: true)
+      @config = YAML.safe_load(@yaml_content, permitted_classes: [Symbol], aliases: true)
 
       unless @config.is_a?(Hash)
         raise ConfigurationError, "Invalid YAML syntax: configuration must be a Hash"
@@ -37,8 +63,6 @@ module SwarmSDK
       load_agents
       detect_circular_dependencies
       self
-    rescue Errno::ENOENT
-      raise ConfigurationError, "Configuration file not found: #{@config_path}"
     rescue Psych::SyntaxError => e
       raise ConfigurationError, "Invalid YAML syntax: #{e.message}"
     end
@@ -260,7 +284,7 @@ module SwarmSDK
     def resolve_agent_file_path(file_path)
       return file_path if Pathname.new(file_path).absolute?
 
-      @config_dir.join(file_path).to_s
+      @base_dir.join(file_path).to_s
     end
 
     def detect_circular_dependencies

data/lib/swarm_sdk/mcp.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module MCP
+    class << self
+      # Lazy load ruby_llm-mcp only when MCP servers are used
+      def lazy_load
+        return if @loaded
+
+        require "ruby_llm/mcp"
+
+        @loaded = true
+      end
+    end
+  end
+end

data/lib/swarm_sdk/prompts/base_system_prompt.md.erb

@@ -69,139 +69,15 @@ When making changes to files, first understand the file's conventions. Mimic exi
 - When you edit something, first look at the surrounding context (especially imports/requires) to understand the choice of frameworks and libraries. Then consider how to make the given change in a way that is most consistent with existing patterns.
 - Always follow security best practices. Never introduce code that exposes or logs secrets and keys. Never commit secrets or keys to repositories.
 
-# Task Management
-
-You have access to the TodoWrite tool to help you manage and plan tasks. Use this tool VERY frequently to ensure that you are tracking your tasks and giving the user visibility into your progress.
-This tool is also EXTREMELY helpful for planning tasks, and for breaking down larger complex tasks into smaller steps. If you do not use this tool when planning, you may forget to do important tasks - and that is unacceptable.
-
-**CRITICAL WORKFLOW**: When starting a multi-step task:
-1. **FIRST**: Analyze what needs to be done (search, read files, understand scope)
-2. **SECOND**: Create a COMPLETE todo list with ALL known tasks before starting work
-3. **THIRD**: Begin executing tasks, marking them in_progress → completed as you work
-4. **ONLY add new todos** if you discover unexpected work during implementation
-
-**CRITICAL RULES FOR TODO COMPLETION**:
-- Mark EACH task as completed IMMEDIATELY after finishing it (do not batch updates)
-- You MUST complete ALL pending todos before giving your final answer to the user
-- If a task becomes irrelevant, remove it from the list or mark it completed with a note
-- NEVER leave in_progress or pending tasks when you finish responding to the user
-- Before giving your final response, verify all todos are marked completed
-
-Examples:
-
-<example>
-user: Run the build and fix any type errors
-assistant: I'll run the build first to identify all type errors, then create a complete todo list.
-
-[Runs build and finds 3 type errors in 3 different files]
-
-Now I'll create a complete todo list with all the work:
-
-[Uses TodoWrite to create full list:]
-1. Fix type error in auth.ts:45 (in_progress)
-2. Fix type error in user.ts:23 (pending)
-3. Fix type error in api.ts:67 (pending)
-4. Run build again to verify all fixes (pending)
-
-Starting with the first error in auth.ts...
-[Fixes auth.ts error]
-
-[Updates TodoWrite - marks task 1 completed, task 2 in_progress]
-
-Now fixing user.ts...
-[Fixes user.ts error]
-
-[Updates TodoWrite - marks task 2 completed, task 3 in_progress]
-
-Now fixing api.ts...
-[Fixes api.ts error]
-
-[Updates TodoWrite - marks task 3 completed, task 4 in_progress]
-
-Running build to verify...
-[Runs build - all errors fixed!]
-
-[Updates TodoWrite - marks task 4 completed]
-
-All type errors have been fixed and the build passes successfully.
-</example>
-In this example, the assistant: (1) analyzed scope first, (2) created COMPLETE todo list, (3) marked EACH task completed immediately after finishing it, (4) completed ALL tasks before giving final response.
-
-<example>
-user: Help me write a new feature that allows users to track their usage metrics and export them to various formats
-
-A: I'll help you implement a usage metrics tracking and export feature. Let me first research the codebase to understand the scope, then create a complete todo list.
-
-[Searches for existing metrics/telemetry code, examines architecture, identifies integration points]
-
-Based on my analysis, here's the complete implementation plan:
-
-[Uses TodoWrite to create full list:]
-1. Create MetricsCollector class in src/metrics/ (in_progress)
-2. Add database schema for metrics storage (pending)
-3. Implement CSV export format (pending)
-4. Implement JSON export format (pending)
-5. Create MetricsService API endpoints (pending)
-6. Add frontend UI for export (pending)
-7. Write unit tests for collectors and exporters (pending)
-8. Update documentation (pending)
-
-Now starting with the MetricsCollector class...
-[Implements MetricsCollector]
-
-[Updates TodoWrite - marks task 1 completed, task 2 in_progress]
-
-Adding database schema...
-[Creates schema]
-
-[Updates TodoWrite - marks task 2 completed, task 3 in_progress]
-
-Implementing CSV export...
-[Implements CSV exporter]
-
-[Updates TodoWrite - marks task 3 completed, task 4 in_progress]
-
-Implementing JSON export...
-[Implements JSON exporter]
-
-[Updates TodoWrite - marks task 4 completed, task 5 in_progress]
-
-Creating MetricsService API endpoints...
-[Implements API endpoints]
-
-[Updates TodoWrite - marks task 5 completed, task 6 in_progress]
-
-Adding frontend UI for export...
-[Implements UI components]
-
-[Updates TodoWrite - marks task 6 completed, task 7 in_progress]
-
-Writing unit tests...
-[Writes and runs tests - all pass]
-
-[Updates TodoWrite - marks task 7 completed, task 8 in_progress]
-
-Updating documentation...
-[Updates docs with usage examples]
-
-[Updates TodoWrite - marks task 8 completed]
-
-The metrics tracking and export feature is now complete. Users can collect metrics and export them to CSV or JSON formats through both the API and the frontend UI.
-</example>
-
 # Doing tasks
 
 The user will primarily request you perform tasks. This includes solving problems, adding new functionality, refactoring, explaining content, and more. For these tasks the following steps are recommended:
 
-- Use the TodoWrite tool to plan the task if required
 - Use the available search tools to understand the context and the user's query. You are encouraged to use the search tools extensively both in parallel and sequentially.
 - Implement the solution using all tools available to you
-- Mark each todo completed IMMEDIATELY after finishing it
 - Verify the solution if possible with tests. NEVER assume specific test framework or test script. Check the project documentation or search to determine the testing approach.
 - When you have completed a task, if there are linting or validation commands available to you, run them to ensure your work is correct. NEVER assume what these commands are - check the project documentation first.
 NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
-- Before giving your final response: Ensure ALL todos are marked completed. NEVER leave pending or in_progress tasks.
-- IMPORTANT: Always use the TodoWrite tool to plan and track tasks throughout the conversation.
 
 # Tool usage policy
 
@@ -211,8 +87,6 @@ NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTAN
 - If the user specifies that they want you to run tools "in parallel", you MUST send a single message with multiple tool use content blocks. For example, if you need to delegate a task to multiple agents in parallel, send a single message with multiple DelegateTask tool calls.
 - Use specialized tools instead of bash commands when possible, as this provides a better user experience. For file operations, use dedicated tools: Read for reading files instead of cat/head/tail, Edit/MultiEdit for editing instead of sed/awk, and Write for creating files instead of cat with heredoc or echo redirection. Reserve bash tools exclusively for actual system commands and terminal operations that require shell execution. NEVER use bash echo or other command-line tools to communicate thoughts, explanations, or instructions to the user. Output all communication directly in your response text instead.
 
-IMPORTANT: Always use the TodoWrite tool to plan and track tasks throughout the conversation.
-
 You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless user asks for detail.
 
 

data/lib/swarm_sdk/swarm.rb

@@ -4,25 +4,10 @@ module SwarmSDK
   # Swarm orchestrates multiple AI agents with shared rate limiting and coordination.
   #
   # This is the main user-facing API for SwarmSDK. Users create swarms using:
-  # - Direct API: Create Agent::Definition objects and add to swarm
-  # - Ruby DSL: Use Swarm::Builder for fluent configuration
-  # - YAML: Load from configuration files
-  #
-  # ## Direct API
-  #
-  #   swarm = Swarm.new(name: "Development Team")
-  #
-  #   backend_agent = Agent::Definition.new(:backend, {
-  #     description: "Backend developer",
-  #     model: "gpt-5",
-  #     system_prompt: "You build APIs and databases...",
-  #     tools: [:Read, :Edit, :Bash],
-  #     delegates_to: [:database]
-  #   })
-  #   swarm.add_agent(backend_agent)
-  #
-  #   swarm.lead = :backend
-  #   result = swarm.execute("Build authentication")
+  # - Ruby DSL: SwarmSDK.build { ... } (Recommended)
+  # - YAML String: SwarmSDK.load(yaml, base_dir:)
+  # - YAML File: SwarmSDK.load_file(path)
+  # - Direct API: Swarm.new + add_agent (Advanced)
   #
   # ## Ruby DSL (Recommended)
   #
@@ -39,14 +24,36 @@ module SwarmSDK
   #   end
   #   result = swarm.execute("Build authentication")
   #
-  # ## YAML API
+  # ## YAML String API
   #
-  #   swarm = Swarm.load("swarm.yml")
+  #   yaml = File.read("swarm.yml")
+  #   swarm = SwarmSDK.load(yaml, base_dir: "/path/to/project")
+  #   result = swarm.execute("Build authentication")
+  #
+  # ## YAML File API (Convenience)
+  #
+  #   swarm = SwarmSDK.load_file("swarm.yml")
+  #   result = swarm.execute("Build authentication")
+  #
+  # ## Direct API (Advanced)
+  #
+  #   swarm = Swarm.new(name: "Development Team")
+  #
+  #   backend_agent = Agent::Definition.new(:backend, {
+  #     description: "Backend developer",
+  #     model: "gpt-5",
+  #     system_prompt: "You build APIs and databases...",
+  #     tools: [:Read, :Edit, :Bash],
+  #     delegates_to: [:database]
+  #   })
+  #   swarm.add_agent(backend_agent)
+  #
+  #   swarm.lead = :backend
   #   result = swarm.execute("Build authentication")
   #
   # ## Architecture
   #
-  # All three APIs converge on Agent::Definition for validation.
+  # All APIs converge on Agent::Definition for validation.
   # Swarm delegates to specialized concerns:
   # - Agent::Definition: Validates configuration, builds system prompts
   # - AgentInitializer: Complex 5-pass agent setup
@@ -96,39 +103,14 @@ module SwarmSDK
       def apply_mcp_logging_configuration
         return if @mcp_logging_configured
 
+        SwarmSDK::MCP.lazy_load
+
         RubyLLM::MCP.configure do |config|
           config.log_level = @mcp_log_level
         end
 
         @mcp_logging_configured = true
       end
-
-      # Load swarm from YAML configuration file
-      #
-      # @param config_path [String] Path to YAML configuration file
-      # @return [Swarm] Configured swarm instance
-      def load(config_path)
-        config = Configuration.load(config_path)
-        swarm = config.to_swarm
-
-        # Apply hooks if any are configured (YAML-only feature)
-        if hooks_configured?(config)
-          Hooks::Adapter.apply_hooks(swarm, config)
-        end
-
-        # Store config reference for agent hooks (applied during initialize_agents)
-        swarm.config_for_hooks = config
-
-        swarm
-      end
-
-      private
-
-      def hooks_configured?(config)
-        config.swarm_hooks.any? ||
-          config.all_agents_hooks.any? ||
-          config.agents.any? { |_, agent_def| agent_def.hooks&.any? }
-      end
     end
 
     # Initialize a new Swarm
@@ -433,7 +415,7 @@ module SwarmSDK
     # @return [Array<Hash>] Array of warning hashes from all agent definitions
     #
     # @example
-    #   swarm = Swarm.load("config.yml")
+    #   swarm = SwarmSDK.load_file("config.yml")
     #   warnings = swarm.validate
     #   warnings.each do |warning|
     #     puts "⚠️  #{warning[:agent]}: #{warning[:model]} not found"

data/lib/swarm_sdk/tools/scratchpad/scratchpad_list.rb

@@ -12,8 +12,29 @@ module SwarmSDK
 
         description <<~DESC
           List all entries in scratchpad with their metadata.
-          Shows path, title, size, and last updated time for each entry.
-          Use this to discover what's stored in the scratchpad.
+
+          ## When to Use ScratchpadList
+
+          Use ScratchpadList to:
+          - Discover what content is available in the scratchpad
+          - Check what other agents have stored
+          - Find relevant entries before reading them
+          - Review all stored outputs and analysis
+          - Check entry sizes and last update times
+
+          ## Best Practices
+
+          - Use this before ScratchpadRead if you don't know what's stored
+          - Filter by prefix to narrow down results (e.g., 'notes/' lists all notes)
+          - Shows path, title, size, and last updated time for each entry
+          - Any agent can see all scratchpad entries
+          - Helps coordinate multi-agent workflows
+
+          ## Examples
+
+          - List all entries: (no prefix parameter)
+          - List notes only: prefix='notes/'
+          - List analysis results: prefix='analysis/'
         DESC
 
         param :prefix,

data/lib/swarm_sdk/tools/scratchpad/scratchpad_read.rb

@@ -12,8 +12,29 @@ module SwarmSDK
 
         description <<~DESC
           Read content from scratchpad.
-          Use this to retrieve temporary notes, results, or messages stored by any agent.
-          Any agent can read any scratchpad content.
+
+          ## When to Use ScratchpadRead
+
+          Use ScratchpadRead to:
+          - Retrieve previously stored content and outputs
+          - Access detailed analysis or results from earlier steps
+          - Read messages or notes left by other agents
+          - Access cached computed data
+          - Retrieve content that was too long for direct responses
+
+          ## Best Practices
+
+          - Any agent can read any scratchpad content
+          - Content is returned with line numbers for easy reference
+          - Use ScratchpadList first if you don't know what's stored
+          - Scratchpad data is temporary and lost when swarm ends
+          - For persistent data, use MemoryRead instead
+
+          ## Examples
+
+          - Read status: file_path='status'
+          - Read analysis: file_path='api_analysis'
+          - Read agent notes: file_path='notes/backend'
         DESC
 
         param :file_path,

data/lib/swarm_sdk/tools/scratchpad/scratchpad_write.rb

@@ -13,12 +13,29 @@ module SwarmSDK
 
         description <<~DESC
           Store content in scratchpad for temporary cross-agent communication.
-          Use this for quick notes, intermediate results, or coordination messages.
-          Any agent can read this content. Data is lost when the swarm ends.
 
-          For persistent storage that survives across sessions, use MemoryWrite instead.
+          ## When to Use Scratchpad
 
-          Choose a simple, descriptive path. Examples: 'status', 'result', 'notes/agent_x'
+          Use ScratchpadWrite to:
+          - Store detailed outputs, analysis, or results that are too long for direct responses
+          - Share information that would otherwise clutter your responses
+          - Store intermediate results during multi-step tasks
+          - Leave coordination messages for other agents
+          - Cache computed data for quick retrieval
+
+          ## Best Practices
+
+          - Choose simple, descriptive paths: 'status', 'result', 'notes/agent_x'
+          - Use hierarchical paths for organization: 'analysis/step1', 'analysis/step2'
+          - Keep entries focused - one piece of information per entry
+          - Any agent can read scratchpad content
+          - Data is lost when the swarm ends (use MemoryWrite for persistent storage)
+          - Maximum 1MB per entry
+
+          ## Examples
+
+          Good paths: 'status', 'api_analysis', 'test_results', 'notes/backend'
+          Bad paths: 'scratch/temp/file123.txt', 'output.log'
         DESC
 
         param :file_path,

data/lib/swarm_sdk/tools/stores/storage.rb

@@ -14,11 +14,11 @@ module SwarmSDK
       # - Search capabilities: Glob patterns and grep-style content search
       # - Thread-safe: Mutex-protected operations
       class Storage
-        # Maximum size per entry (1MB)
-        MAX_ENTRY_SIZE = 1_000_000
+        # Maximum size per entry (3MB)
+        MAX_ENTRY_SIZE = 3_000_000
 
-        # Maximum total storage size (100MB)
-        MAX_TOTAL_SIZE = 100_000_000
+        # Maximum total storage size (100GB)
+        MAX_TOTAL_SIZE = 100_000_000_000
 
         # Represents a single storage entry with metadata
         Entry = Struct.new(:content, :title, :updated_at, :size, keyword_init: true)

data/lib/swarm_sdk/tools/think.rb

@@ -82,7 +82,10 @@ module SwarmSDK
         required: true
 
       def execute(**kwargs)
-        "Thought noted."
+        <<~RESP
+          Thought noted.
+        RESP
+        # <system-reminder>The user cannot see your thoughts. You MUST NOT stop without giving the user a response.</system-reminder>
       end
 
       private

data/lib/swarm_sdk/tools/todo_write.rb

@@ -8,17 +8,17 @@ module SwarmSDK
     # Each agent maintains its own independent todo list.
     class TodoWrite < RubyLLM::Tool
       description <<~DESC
-        Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+        Use this tool to create and manage a structured task list for your current work session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
         It also helps the user understand the progress of the task and overall progress of their requests.
 
         ## When to Use This Tool
         Use this tool proactively in these scenarios:
 
         **CRITICAL**: Follow this workflow for multi-step tasks:
-        1. FIRST: Analyze the task scope (search files, read code, understand requirements)
-        2. SECOND: Create a COMPLETE todo list with ALL known tasks BEFORE starting implementation
+        1. FIRST: Analyze the task scope (gather information, understand requirements)
+        2. SECOND: Create a COMPLETE todo list with ALL known tasks BEFORE starting work
         3. THIRD: Execute tasks, marking in_progress → completed as you work
-        4. ONLY add new todos if unexpected work is discovered during implementation
+        4. ONLY add new todos if unexpected work is discovered during execution
 
         Use the todo list when:
         1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
@@ -27,7 +27,7 @@ module SwarmSDK
         4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
         5. After receiving new instructions - After analyzing scope, create complete todo list before starting work
         6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
-        7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+        7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during execution
 
         ## When NOT to Use This Tool
 
@@ -73,9 +73,21 @@ module SwarmSDK
           - Create specific, actionable items
           - Break complex tasks into smaller, manageable steps
           - Use clear, descriptive task names
-          - Always provide both forms:
-            - content: "Fix authentication bug"
-            - activeForm: "Fixing authentication bug"
+          - Always provide both forms (content and activeForm)
+
+        ## Examples
+
+        **Coding Tasks**:
+        - content: "Fix authentication bug in login handler"
+        - activeForm: "Fixing authentication bug in login handler"
+
+        **Non-Coding Tasks**:
+        - content: "Analyze customer feedback from Q4 survey"
+        - activeForm: "Analyzing customer feedback from Q4 survey"
+
+        **Research Tasks**:
+        - content: "Research best practices for API rate limiting"
+        - activeForm: "Researching best practices for API rate limiting"
 
         When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.
       DESC

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk.rb

@@ -15,7 +15,6 @@ require "yaml"
 require "async"
 require "async/semaphore"
 require "ruby_llm"
-require "ruby_llm/mcp"
 
 require_relative "swarm_sdk/version"
 
@@ -48,6 +47,170 @@ module SwarmSDK
       Swarm::Builder.build(&block)
     end
 
+    # Validate YAML configuration without creating a swarm
+    #
+    # Performs comprehensive validation of YAML configuration including:
+    # - YAML syntax
+    # - Required fields (version, swarm name, lead, agents)
+    # - Agent configurations (description, directory existence)
+    # - Circular dependencies
+    # - File references (agent_file paths)
+    # - Hook configurations
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @return [Array<Hash>] Array of error hashes (empty if valid)
+    #
+    # @example Validate YAML string
+    #   errors = SwarmSDK.validate(yaml_content)
+    #   if errors.empty?
+    #     puts "Configuration is valid!"
+    #   else
+    #     errors.each do |error|
+    #       puts "#{error[:field]}: #{error[:message]}"
+    #     end
+    #   end
+    #
+    # @example Error hash structure
+    #   {
+    #     type: :missing_field,           # Error type
+    #     field: "swarm.agents.backend.description",  # JSON-style path to field
+    #     message: "Agent 'backend' missing required 'description' field",
+    #     agent: "backend"                # Optional, present if error is agent-specific
+    #   }
+    def validate(yaml_content, base_dir: Dir.pwd)
+      errors = []
+
+      begin
+        config = Configuration.new(yaml_content, base_dir: base_dir)
+        config.load_and_validate
+      rescue ConfigurationError, CircularDependencyError => e
+        errors << parse_configuration_error(e)
+      rescue StandardError => e
+        errors << {
+          type: :unknown_error,
+          field: nil,
+          message: e.message,
+        }
+      end
+
+      errors
+    end
+
+    # Validate YAML configuration file
+    #
+    # Convenience method that reads the file and validates the content.
+    #
+    # @param path [String, Pathname] Path to YAML configuration file
+    # @return [Array<Hash>] Array of error hashes (empty if valid)
+    #
+    # @example
+    #   errors = SwarmSDK.validate_file("config.yml")
+    #   if errors.empty?
+    #     puts "Valid configuration!"
+    #     swarm = SwarmSDK.load_file("config.yml")
+    #   else
+    #     errors.each { |e| puts "Error: #{e[:message]}" }
+    #   end
+    def validate_file(path)
+      path = Pathname.new(path).expand_path
+
+      unless path.exist?
+        return [{
+          type: :file_not_found,
+          field: nil,
+          message: "Configuration file not found: #{path}",
+        }]
+      end
+
+      yaml_content = File.read(path)
+      base_dir = path.dirname
+
+      validate(yaml_content, base_dir: base_dir)
+    rescue StandardError => e
+      [{
+        type: :file_read_error,
+        field: nil,
+        message: "Error reading file: #{e.message}",
+      }]
+    end
+
+    # Load swarm from YAML string
+    #
+    # This is the primary programmatic API for loading YAML configurations.
+    # For file-based loading, use SwarmSDK.load_file for convenience.
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @return [Swarm, NodeOrchestrator] Configured swarm or orchestrator instance
+    # @raise [ConfigurationError] If YAML is invalid or configuration is incorrect
+    #
+    # @example Load from YAML string
+    #   yaml = <<~YAML
+    #     version: 2
+    #     swarm:
+    #       name: "Dev Team"
+    #       lead: backend
+    #       agents:
+    #         backend:
+    #           description: "Backend developer"
+    #           model: "gpt-4"
+    #           agent_file: "agents/backend.md"  # Resolved relative to base_dir
+    #   YAML
+    #
+    #   swarm = SwarmSDK.load(yaml, base_dir: "/path/to/project")
+    #   result = swarm.execute("Build authentication")
+    #
+    # @example Load with default base_dir (Dir.pwd)
+    #   yaml = File.read("config.yml")
+    #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
+    def load(yaml_content, base_dir: Dir.pwd)
+      config = Configuration.new(yaml_content, base_dir: base_dir)
+      config.load_and_validate
+      swarm = config.to_swarm
+
+      # Apply hooks if any are configured (YAML-only feature)
+      if hooks_configured?(config)
+        Hooks::Adapter.apply_hooks(swarm, config)
+      end
+
+      # Store config reference for agent hooks (applied during initialize_agents)
+      swarm.config_for_hooks = config
+
+      swarm
+    end
+
+    # Load swarm from YAML file (convenience method)
+    #
+    # Reads the YAML file and uses the file's directory as the base directory
+    # for resolving agent file paths. This is the recommended method for
+    # loading swarms from configuration files.
+    #
+    # @param path [String, Pathname] Path to YAML configuration file
+    # @return [Swarm, NodeOrchestrator] Configured swarm or orchestrator instance
+    # @raise [ConfigurationError] If file not found or configuration invalid
+    #
+    # @example
+    #   swarm = SwarmSDK.load_file("config.yml")
+    #   result = swarm.execute("Build authentication")
+    #
+    # @example With absolute path
+    #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
+    def load_file(path)
+      config = Configuration.load_file(path)
+      swarm = config.to_swarm
+
+      # Apply hooks if any are configured (YAML-only feature)
+      if hooks_configured?(config)
+        Hooks::Adapter.apply_hooks(swarm, config)
+      end
+
+      # Store config reference for agent hooks (applied during initialize_agents)
+      swarm.config_for_hooks = config
+
+      swarm
+    end
+
     # Configure SwarmSDK global settings
     def configure
       self.settings ||= Settings.new
@@ -62,6 +225,171 @@ module SwarmSDK
     # Alias for backward compatibility
     alias_method :configuration, :settings
     alias_method :reset_configuration!, :reset_settings!
+
+    private
+
+    # Check if hooks are configured in the configuration
+    #
+    # @param config [Configuration] Configuration instance
+    # @return [Boolean] true if any hooks are configured
+    def hooks_configured?(config)
+      config.swarm_hooks.any? ||
+        config.all_agents_hooks.any? ||
+        config.agents.any? { |_, agent_def| agent_def.hooks&.any? }
+    end
+
+    # Parse configuration error and extract structured information
+    #
+    # Attempts to extract field path and agent name from error messages.
+    # Returns a structured error hash with type, field, message, and optional agent.
+    #
+    # @param error [StandardError] The caught error
+    # @return [Hash] Structured error hash
+    def parse_configuration_error(error)
+      message = error.message
+      error_hash = { message: message }
+
+      # Detect error type and extract field information
+      case message
+      # YAML syntax errors
+      when /Invalid YAML syntax/i
+        error_hash.merge!(
+          type: :syntax_error,
+          field: nil,
+        )
+
+      # Missing version field
+      when /Missing 'version' field/i
+        error_hash.merge!(
+          type: :missing_field,
+          field: "version",
+        )
+
+      # Invalid version
+      when /SwarmSDK requires version: (\d+)/i
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "version",
+        )
+
+      # Missing swarm fields
+      when /Missing '(\w+)' field in swarm configuration/i
+        field_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.#{field_name}",
+        )
+
+      # Agent missing required field
+      when /Agent '([^']+)' missing required '([^']+)' field/i
+        agent_name = Regexp.last_match(1)
+        field_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.agents.#{agent_name}.#{field_name}",
+          agent: agent_name,
+        )
+
+      # Directory does not exist
+      when /Directory '([^']+)' for agent '([^']+)' does not exist/i
+        agent_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :directory_not_found,
+          field: "swarm.agents.#{agent_name}.directory",
+          agent: agent_name,
+        )
+
+      # Error loading agent from file (must come before "Agent file not found")
+      when /Error loading agent '([^']+)' from file/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :file_load_error,
+          field: "swarm.agents.#{agent_name}.agent_file",
+          agent: agent_name,
+        )
+
+      # Agent file not found
+      when /Agent file not found: (.+)/i
+        # Try to extract agent name from the error context if available
+        error_hash.merge!(
+          type: :file_not_found,
+          field: nil, # We don't know which agent without more context
+        )
+
+      # Lead agent not found
+      when /Lead agent '([^']+)' not found in agents/i
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.lead",
+        )
+
+      # Unknown agent in connections
+      when /Agent '([^']+)' has connection to unknown agent '([^']+)'/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.agents.#{agent_name}.delegates_to",
+          agent: agent_name,
+        )
+
+      # Circular dependency
+      when /Circular dependency detected/i
+        error_hash.merge!(
+          type: :circular_dependency,
+          field: nil,
+        )
+
+      # Configuration file not found
+      when /Configuration file not found/i
+        error_hash.merge!(
+          type: :file_not_found,
+          field: nil,
+        )
+
+      # Invalid hook event
+      when /Invalid hook event '([^']+)' for agent '([^']+)'/i
+        agent_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.hooks",
+          agent: agent_name,
+        )
+
+      # api_version validation error
+      when /Agent '([^']+)' has api_version set, but provider is/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.api_version",
+          agent: agent_name,
+        )
+
+      # api_version invalid value
+      when /Agent '([^']+)' has invalid api_version/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.api_version",
+          agent: agent_name,
+        )
+
+      # No agents defined
+      when /No agents defined/i
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.agents",
+        )
+
+      # Default: unknown error
+      else
+        error_hash.merge!(
+          type: :validation_error,
+          field: nil,
+        )
+      end
+
+      error_hash.compact
+    end
   end
 
   # Settings class for SwarmSDK global settings (not to be confused with Configuration for YAML loading)
@@ -132,22 +460,3 @@ RubyLLM.configure do |config|
   config.gpustack_api_base ||= ENV["GPUSTACK_API_BASE"]
   config.gpustack_api_key ||= ENV["GPUSTACK_API_KEY"]
 end
-
-# monkey patches
-# ruby_llm/mcp
-# - add `id` when sending "notifications/initialized" message: https://github.com/patvice/ruby_llm-mcp/issues/65
-# - remove `to_sym` on MCP parameter type: https://github.com/patvice/ruby_llm-mcp/issues/62#issuecomment-3421488406
-require "ruby_llm/mcp/notifications/initialize"
-require "ruby_llm/mcp/parameter"
-
-module RubyLLM
-  module MCP
-    module Notifications
-      class Initialize
-        def call
-          @coordinator.request(notification_body, add_id: true, wait_for_response: false)
-        end
-      end
-    end
-  end
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.1.2
+  version: 2.1.3
 platform: ruby
 authors:
 - Paulo Arruda
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.2
+        version: 0.6.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.6.2
+        version: 0.6.3
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -106,6 +106,7 @@ files:
 - lib/swarm_sdk/log_collector.rb
 - lib/swarm_sdk/log_stream.rb
 - lib/swarm_sdk/markdown_parser.rb
+- lib/swarm_sdk/mcp.rb
 - lib/swarm_sdk/model_aliases.json
 - lib/swarm_sdk/models.json
 - lib/swarm_sdk/models.rb