swarm_memory 2.1.1 → 2.1.3

data/lib/swarm_sdk.rb

@@ -21,19 +21,17 @@ require_relative "swarm_sdk/version"
 
 require "zeitwerk"
 loader = Zeitwerk::Loader.new
+loader.tag = File.basename(__FILE__, ".rb")
 loader.push_dir("#{__dir__}/swarm_sdk", namespace: SwarmSDK)
+loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.inflector.inflect(
   "cli" => "CLI",
+  "llm_instrumentation_middleware" => "LLMInstrumentationMiddleware",
+  "mcp" => "MCP",
+  "openai_with_responses" => "OpenAIWithResponses",
 )
 loader.setup
 
-# Load plugin system explicitly (core infrastructure)
-require_relative "swarm_sdk/plugin"
-require_relative "swarm_sdk/plugin_registry"
-
-# Load custom providers explicitly (Zeitwerk doesn't eager load by default)
-require_relative "swarm_sdk/providers/openai_with_responses"
-
 module SwarmSDK
   class Error < StandardError; end
   class ConfigurationError < Error; end
@@ -48,8 +46,176 @@ module SwarmSDK
     attr_accessor :settings
 
     # Main entry point for DSL
-    def build(&block)
-      Swarm::Builder.build(&block)
+    def build(allow_filesystem_tools: nil, &block)
+      Swarm::Builder.build(allow_filesystem_tools: allow_filesystem_tools, &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
+
+        # Build swarm to trigger DSL validation
+        # This catches errors from Agent::Definition, Builder, etc.
+        config.to_swarm
+      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, allow_filesystem_tools: nil)
+      config = Configuration.new(yaml_content, base_dir: base_dir)
+      config.load_and_validate
+      swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
+
+      # 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, allow_filesystem_tools: nil)
+      config = Configuration.load_file(path)
+      swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
+
+      # 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
@@ -66,6 +232,180 @@ 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_config| agent_config[: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 (old format)
+      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,
+        )
+
+      # Unknown agent in connections (new format with composable swarms)
+      when /Agent '([^']+)' delegates to unknown target '([^']+)'/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)
@@ -73,17 +413,33 @@ module SwarmSDK
     # WebFetch tool LLM processing configuration
     attr_accessor :webfetch_provider, :webfetch_model, :webfetch_base_url, :webfetch_max_tokens
 
+    # Filesystem tools control
+    attr_accessor :allow_filesystem_tools
+
     def initialize
       @webfetch_provider = nil
       @webfetch_model = nil
       @webfetch_base_url = nil
       @webfetch_max_tokens = 4096
+      @allow_filesystem_tools = parse_env_bool("SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", default: true)
     end
 
     # Check if WebFetch LLM processing is enabled
     def webfetch_llm_enabled?
       !@webfetch_provider.nil? && !@webfetch_model.nil?
     end
+
+    private
+
+    def parse_env_bool(key, default:)
+      return default unless ENV.key?(key)
+
+      value = ENV[key].to_s.downcase
+      return true if ["true", "yes", "1", "on", "enabled"].include?(value)
+      return false if ["false", "no", "0", "off", "disabled"].include?(value)
+
+      default
+    end
   end
 
   # Initialize default settings
@@ -136,22 +492,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_memory
 version: !ruby/object:Gem::Version
-  version: 2.1.1
+  version: 2.1.3
 platform: ruby
 authors:
 - Paulo Arruda
@@ -57,28 +57,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.8'
+        version: '1.9'
 - !ruby/object:Gem::Dependency
   name: swarm_sdk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -214,11 +214,13 @@ files:
 - lib/swarm_sdk/agent/context.rb
 - lib/swarm_sdk/agent/context_manager.rb
 - lib/swarm_sdk/agent/definition.rb
+- lib/swarm_sdk/agent/llm_instrumentation_middleware.rb
 - lib/swarm_sdk/claude_code_agent_adapter.rb
 - lib/swarm_sdk/configuration.rb
 - lib/swarm_sdk/context_compactor.rb
 - lib/swarm_sdk/context_compactor/metrics.rb
 - lib/swarm_sdk/context_compactor/token_counter.rb
+- lib/swarm_sdk/events_to_messages.rb
 - lib/swarm_sdk/hooks/adapter.rb
 - lib/swarm_sdk/hooks/context.rb
 - lib/swarm_sdk/hooks/definition.rb
@@ -247,15 +249,24 @@ files:
 - lib/swarm_sdk/permissions_builder.rb
 - lib/swarm_sdk/plugin.rb
 - lib/swarm_sdk/plugin_registry.rb
+- lib/swarm_sdk/proc_helpers.rb
 - lib/swarm_sdk/prompts/base_system_prompt.md.erb
 - lib/swarm_sdk/providers/openai_with_responses.rb
+- lib/swarm_sdk/restore_result.rb
 - lib/swarm_sdk/result.rb
+- lib/swarm_sdk/snapshot.rb
+- lib/swarm_sdk/snapshot_from_events.rb
+- lib/swarm_sdk/state_restorer.rb
+- lib/swarm_sdk/state_snapshot.rb
 - lib/swarm_sdk/swarm.rb
 - lib/swarm_sdk/swarm/agent_initializer.rb
 - lib/swarm_sdk/swarm/all_agents_builder.rb
 - lib/swarm_sdk/swarm/builder.rb
 - lib/swarm_sdk/swarm/mcp_configurator.rb
+- lib/swarm_sdk/swarm/swarm_registry_builder.rb
 - lib/swarm_sdk/swarm/tool_configurator.rb
+- lib/swarm_sdk/swarm_loader.rb
+- lib/swarm_sdk/swarm_registry.rb
 - lib/swarm_sdk/tools/bash.rb
 - lib/swarm_sdk/tools/clock.rb
 - lib/swarm_sdk/tools/delegate.rb
@@ -286,6 +297,7 @@ files:
 - lib/swarm_sdk/tools/web_fetch.rb
 - lib/swarm_sdk/tools/write.rb
 - lib/swarm_sdk/utils.rb
+- lib/swarm_sdk/validation_result.rb
 - lib/swarm_sdk/version.rb
 homepage: https://github.com/parruda/claude-swarm
 licenses: