swarm_sdk 2.7.14 → 3.0.0.alpha2

data/lib/swarm_sdk/models.rb

@@ -1,161 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Models provides model validation and suggestion functionality
-  #
-  # Uses static JSON files:
-  # - models.json: Curated model list from Parsera
-  # - model_aliases.json: Shortcuts mapping to latest models
-  #
-  # This avoids network calls, API key requirements, and RubyLLM
-  # registry manipulation.
-  #
-  # @example
-  #   model = SwarmSDK::Models.find("claude-sonnet-4-5-20250929")
-  #   model = SwarmSDK::Models.find("sonnet")  # Uses alias
-  #   suggestions = SwarmSDK::Models.suggest_similar("anthropic:claude-sonnet-4-5")
-  class Models
-    MODELS_JSON_PATH = File.expand_path("models.json", __dir__)
-    ALIASES_JSON_PATH = File.expand_path("model_aliases.json", __dir__)
-
-    # Model information wrapper providing method access to model data
-    #
-    # Wraps the raw Hash from models.json to provide RubyLLM::Model::Info-like
-    # interface for compatibility with code expecting method access.
-    #
-    # @example
-    #   model = SwarmSDK::Models.find("claude-sonnet-4-5-20250929")
-    #   model.context_window  #=> 200000
-    #   model.id              #=> "claude-sonnet-4-5-20250929"
-    class ModelInfo
-      attr_reader :id,
-        :name,
-        :provider,
-        :family,
-        :context_window,
-        :max_output_tokens,
-        :knowledge_cutoff,
-        :modalities,
-        :capabilities,
-        :pricing,
-        :metadata
-
-      # Create a ModelInfo from a Hash
-      #
-      # @param data [Hash] Model data from models.json
-      def initialize(data)
-        @id = data["id"] || data[:id]
-        @name = data["name"] || data[:name]
-        @provider = data["provider"] || data[:provider]
-        @family = data["family"] || data[:family]
-        @context_window = data["context_window"] || data[:context_window]
-        @max_output_tokens = data["max_output_tokens"] || data[:max_output_tokens]
-        @knowledge_cutoff = data["knowledge_cutoff"] || data[:knowledge_cutoff]
-        @modalities = data["modalities"] || data[:modalities]
-        @capabilities = data["capabilities"] || data[:capabilities]
-        @pricing = data["pricing"] || data[:pricing]
-        @metadata = data["metadata"] || data[:metadata]
-      end
-    end
-
-    class << self
-      # Find a model by ID or alias
-      #
-      # @param model_id [String] Model ID or alias to find
-      # @return [ModelInfo, nil] Model info or nil if not found
-      def find(model_id)
-        # Check if it's an alias first
-        resolved_id = resolve_alias(model_id)
-
-        model_hash = all.find { |m| m["id"] == resolved_id || m[:id] == resolved_id }
-        model_hash ? ModelInfo.new(model_hash) : nil
-      end
-
-      # Resolve a model alias to full model ID
-      #
-      # @param model_id [String] Model ID or alias
-      # @return [String] Resolved model ID (or original if not an alias)
-      def resolve_alias(model_id)
-        aliases[model_id.to_s] || model_id
-      end
-
-      # Suggest similar models for a given query
-      #
-      # Strips provider prefixes and normalizes for fuzzy matching.
-      #
-      # @param query [String] Model ID to match against
-      # @param limit [Integer] Maximum number of suggestions
-      # @return [Array<Hash>] Up to `limit` similar models
-      def suggest_similar(query, limit: 3)
-        # Strip provider prefix (e.g., "anthropic:claude-sonnet-4-5" → "claude-sonnet-4-5")
-        query_without_prefix = query.to_s.sub(/^[^:]+:/, "")
-        normalized_query = query_without_prefix.downcase.gsub(/[.\-_]/, "")
-
-        matches = all.select do |model|
-          model_id = (model["id"] || model[:id]).to_s
-          model_name = (model["name"] || model[:name]).to_s
-
-          normalized_id = model_id.downcase.gsub(/[.\-_]/, "")
-          normalized_name = model_name.downcase.gsub(/[.\-_]/, "")
-
-          normalized_id.include?(normalized_query) || normalized_name.include?(normalized_query)
-        end.first(limit)
-
-        matches.map do |m|
-          {
-            id: m["id"] || m[:id],
-            name: m["name"] || m[:name],
-            context_window: m["context_window"] || m[:context_window],
-          }
-        end
-      end
-
-      # Get all models
-      #
-      # @return [Array<Hash>] All models from models.json
-      def all
-        @models ||= load_models
-      end
-
-      # Get all aliases
-      #
-      # @return [Hash] Alias mappings
-      def aliases
-        @aliases ||= load_aliases
-      end
-
-      # Reload models and aliases from JSON files
-      #
-      # @return [Array<Hash>] Loaded models
-      def reload!
-        @models = load_models
-        @aliases = load_aliases
-        @models
-      end
-
-      private
-
-      # Load models from JSON file
-      #
-      # @return [Array<Hash>] Models array
-      def load_models
-        JSON.parse(File.read(MODELS_JSON_PATH))
-      rescue StandardError => e
-        # Log error and return empty array
-        RubyLLM.logger.error("Failed to load SwarmSDK models.json: #{e.class} - #{e.message}")
-        []
-      end
-
-      # Load aliases from JSON file
-      #
-      # @return [Hash] Alias mappings
-      def load_aliases
-        JSON.parse(File.read(ALIASES_JSON_PATH))
-      rescue StandardError => e
-        # Log error and return empty hash
-        RubyLLM.logger.debug("Failed to load SwarmSDK model_aliases.json: #{e.class} - #{e.message}")
-        {}
-      end
-    end
-  end
-end

data/lib/swarm_sdk/node_context.rb

@@ -1,245 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # NodeContext provides context information to node transformers
-  #
-  # This class is passed to input and output transformers, giving them access to:
-  # - The original user prompt
-  # - Results from all previous nodes
-  # - Current node metadata
-  # - Convenience accessors for common operations
-  #
-  # @example Input transformer
-  #   input do |ctx|
-  #     ctx.content              # Previous node's content (convenience)
-  #     ctx.original_prompt      # Original user prompt
-  #     ctx.all_results[:plan]   # Access any previous node
-  #     ctx.node_name            # Current node name
-  #   end
-  #
-  # @example Output transformer
-  #   output do |ctx|
-  #     ctx.content              # Current result's content (convenience)
-  #     ctx.original_prompt      # Original user prompt
-  #     ctx.all_results[:plan]   # Access previous nodes
-  #   end
-  class NodeContext
-    attr_reader :original_prompt, :all_results, :node_name, :dependencies
-
-    # For input transformers: result from previous node(s)
-    attr_reader :previous_result
-
-    # For output transformers: current node's result
-    attr_reader :result
-
-    class << self
-      # Create a NodeContext for input transformers
-      #
-      # @param previous_result [Result, Hash, String] Previous node's result or hash of results
-      # @param all_results [Hash<Symbol, Result>] Results from all completed nodes
-      # @param original_prompt [String] The original user prompt
-      # @param node_name [Symbol] Current node name
-      # @param dependencies [Array<Symbol>] Node dependencies
-      # @param transformed_content [String, nil] Already-transformed content from previous output transformer
-      # @return [NodeContext]
-      def for_input(previous_result:, all_results:, original_prompt:, node_name:, dependencies:, transformed_content: nil)
-        new(
-          previous_result: previous_result,
-          all_results: all_results,
-          original_prompt: original_prompt,
-          node_name: node_name,
-          dependencies: dependencies,
-          result: nil,
-          transformed_content: transformed_content,
-        )
-      end
-
-      # Create a NodeContext for output transformers
-      #
-      # @param result [Result] Current node's execution result
-      # @param all_results [Hash<Symbol, Result>] Results from all completed nodes (including current)
-      # @param original_prompt [String] The original user prompt
-      # @param node_name [Symbol] Current node name
-      # @return [NodeContext]
-      def for_output(result:, all_results:, original_prompt:, node_name:)
-        new(
-          result: result,
-          all_results: all_results,
-          original_prompt: original_prompt,
-          node_name: node_name,
-          dependencies: [],
-          previous_result: nil,
-          transformed_content: nil,
-        )
-      end
-    end
-
-    def initialize(previous_result:, all_results:, original_prompt:, node_name:, dependencies:, result:, transformed_content:)
-      @previous_result = previous_result
-      @result = result
-      @all_results = all_results
-      @original_prompt = original_prompt
-      @node_name = node_name
-      @dependencies = dependencies
-      @transformed_content = transformed_content
-    end
-
-    # Convenience accessor: Get content from previous_result or result
-    #
-    # For input transformers:
-    #   - Returns transformed_content if available (from previous output transformer)
-    #   - Otherwise returns previous_result.content (original content)
-    #   - Returns nil for multiple dependencies (use all_results instead)
-    # For output transformers: returns result.content
-    #
-    # @return [String, nil]
-    def content
-      if @result
-        # Output transformer context: return current result's content
-        @result.content
-      elsif @transformed_content
-        # Input transformer with transformed content from previous output
-        @transformed_content
-      elsif @previous_result.respond_to?(:content)
-        # Input transformer context with Result object (original content)
-        @previous_result.content
-      elsif @previous_result.is_a?(Hash)
-        # Input transformer with multiple dependencies (hash of results)
-        nil # No single "content" - user must pick from all_results hash
-      else
-        # String or other type (initial prompt, no dependencies)
-        @previous_result.to_s
-      end
-    end
-
-    # Convenience accessor: Get agent from previous_result or result
-    #
-    # @return [String, nil]
-    def agent
-      if @result
-        @result.agent
-      elsif @previous_result.respond_to?(:agent)
-        @previous_result.agent
-      end
-    end
-
-    # Convenience accessor: Get logs from previous_result or result
-    #
-    # @return [Array, nil]
-    def logs
-      if @result
-        @result.logs
-      elsif @previous_result.respond_to?(:logs)
-        @previous_result.logs
-      end
-    end
-
-    # Convenience accessor: Get duration from previous_result or result
-    #
-    # @return [Float, nil]
-    def duration
-      if @result
-        @result.duration
-      elsif @previous_result.respond_to?(:duration)
-        @previous_result.duration
-      end
-    end
-
-    # Convenience accessor: Get error from previous_result or result
-    #
-    # @return [Exception, nil]
-    def error
-      if @result
-        @result.error
-      elsif @previous_result.respond_to?(:error)
-        @previous_result.error
-      end
-    end
-
-    # Convenience accessor: Check success status
-    #
-    # @return [Boolean, nil]
-    def success?
-      if @result
-        @result.success?
-      elsif @previous_result.respond_to?(:success?)
-        @previous_result.success?
-      end
-    end
-
-    # Control flow methods for transformers
-    # These return special hashes that Workflow recognizes
-
-    # Skip current node's LLM execution and return content immediately
-    #
-    # Only valid for input transformers.
-    #
-    # @param content [String] Content to return (skips LLM call)
-    # @return [Hash] Control hash for skip_execution
-    # @raise [ArgumentError] If content is nil
-    #
-    # @example
-    #   input do |ctx|
-    #     cached = check_cache(ctx.content)
-    #     return ctx.skip_execution(content: cached) if cached
-    #     ctx.content
-    #   end
-    def skip_execution(content:)
-      if content.nil?
-        raise ArgumentError,
-          "skip_execution requires content (got nil). " \
-            "Check that ctx.content or your content source is not nil. " \
-            "Node: #{@node_name}"
-      end
-      { skip_execution: true, content: content }
-    end
-
-    # Halt entire workflow and return content as final result
-    #
-    # Valid for both input and output transformers.
-    #
-    # @param content [String] Final content to return
-    # @return [Hash] Control hash for halt_workflow
-    # @raise [ArgumentError] If content is nil
-    #
-    # @example
-    #   output do |ctx|
-    #     return ctx.halt_workflow(content: ctx.content) if converged?(ctx.content)
-    #     ctx.content
-    #   end
-    def halt_workflow(content:)
-      if content.nil?
-        raise ArgumentError,
-          "halt_workflow requires content (got nil). " \
-            "Check that ctx.content or your content source is not nil. " \
-            "Node: #{@node_name}"
-      end
-      { halt_workflow: true, content: content }
-    end
-
-    # Jump to a different node with provided content as input
-    #
-    # Valid for both input and output transformers.
-    #
-    # @param node [Symbol] Node name to jump to
-    # @param content [String] Content to pass to target node
-    # @return [Hash] Control hash for goto_node
-    # @raise [ArgumentError] If content is nil
-    #
-    # @example
-    #   input do |ctx|
-    #     return ctx.goto_node(:review, content: ctx.content) if needs_review?(ctx.content)
-    #     ctx.content
-    #   end
-    def goto_node(node, content:)
-      if content.nil?
-        raise ArgumentError,
-          "goto_node requires content (got nil). " \
-            "Check that ctx.content or your content source is not nil. " \
-            "This often happens when the previous node failed with an error. " \
-            "Node: #{@node_name}, Target: #{node}"
-      end
-      { goto_node: node.to_sym, content: content }
-    end
-  end
-end

data/lib/swarm_sdk/observer/builder.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Observer
-    # DSL for configuring observer agents
-    #
-    # Used by Swarm::Builder#observer to provide a clean DSL for defining
-    # event handlers and observer configuration options.
-    #
-    # @example Basic usage
-    #   observer :profiler do
-    #     on :swarm_start do |event|
-    #       "Analyze this prompt: #{event[:prompt]}"
-    #     end
-    #
-    #     timeout 120
-    #     max_concurrent 2
-    #   end
-    class Builder
-      # Initialize builder with agent name and config
-      #
-      # @param agent_name [Symbol] Name of the observer agent
-      # @param config [Observer::Config] Configuration object to populate
-      def initialize(agent_name, config)
-        @agent_name = agent_name
-        @config = config
-      end
-
-      # Register an event handler
-      #
-      # The block receives the event hash and should return:
-      # - A prompt string to trigger the observer agent
-      # - nil to skip execution for this event
-      #
-      # @param event_type [Symbol] Type of event to handle (e.g., :swarm_start, :tool_call)
-      # @yield [Hash] Event hash
-      # @yieldreturn [String, nil] Prompt or nil to skip
-      # @return [void]
-      #
-      # @example
-      #   on :tool_call do |event|
-      #     next unless event[:tool_name] == "Bash"
-      #     "Check this command: #{event[:arguments][:command]}"
-      #   end
-      def on(event_type, &block)
-        @config.add_handler(event_type, &block)
-      end
-
-      # Set maximum concurrent executions for this observer
-      #
-      # Limits how many instances of this observer agent can run simultaneously.
-      # Useful for resource-intensive observers.
-      #
-      # @param n [Integer] Maximum concurrent executions
-      # @return [void]
-      def max_concurrent(n)
-        @config.options[:max_concurrent] = n
-      end
-
-      # Set timeout for observer execution
-      #
-      # Observer tasks will be cancelled after this duration.
-      #
-      # @param seconds [Integer] Timeout in seconds (default: 60)
-      # @return [void]
-      def timeout(seconds)
-        @config.options[:timeout] = seconds
-      end
-
-      # Wait for observer to complete before swarm execution ends
-      #
-      # By default, observers are fire-and-forget. This option causes
-      # the main execution to wait for this observer to complete.
-      #
-      # @return [void]
-      def wait_for_completion!
-        @config.options[:fire_and_forget] = false
-      end
-    end
-  end
-end

data/lib/swarm_sdk/observer/config.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Observer
-    # Configuration for an observer agent
-    #
-    # Holds the agent name, event handlers (blocks that return prompts or nil),
-    # and execution options.
-    #
-    # @example
-    #   config = Observer::Config.new(:profiler)
-    #   config.add_handler(:swarm_start) { |event| "Analyze: #{event[:prompt]}" }
-    #   config.options[:timeout] = 120
-    class Config
-      attr_reader :agent_name, :event_handlers, :options
-
-      # Initialize a new observer configuration
-      #
-      # @param agent_name [Symbol] Name of the agent to use as observer
-      def initialize(agent_name)
-        @agent_name = agent_name
-        @event_handlers = {} # { event_type => block }
-        @options = {
-          max_concurrent: nil,
-          timeout: 60,
-          fire_and_forget: true,
-        }
-      end
-
-      # Add an event handler for a specific event type
-      #
-      # The block receives the event hash and should return:
-      # - A prompt string to trigger the observer agent
-      # - nil to skip execution for this event
-      #
-      # @param event_type [Symbol] Type of event to handle (e.g., :swarm_start, :tool_call)
-      # @yield [Hash] Event hash with type, agent, and other data
-      # @yieldreturn [String, nil] Prompt to execute or nil to skip
-      # @return [void]
-      def add_handler(event_type, &block)
-        @event_handlers[event_type] = block
-      end
-    end
-  end
-end