swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/v3/agent_definition.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    # Immutable agent configuration
+    #
+    # Defines everything about an agent's identity, capabilities, and memory settings.
+    # Once created, a definition cannot be modified — create a new one instead.
+    #
+    # @example Minimal definition
+    #   definition = AgentDefinition.new(
+    #     name: :assistant,
+    #     description: "A helpful assistant",
+    #   )
+    #
+    # @example Full definition with memory
+    #   definition = AgentDefinition.new(
+    #     name: :researcher,
+    #     description: "Research specialist",
+    #     model: "claude-sonnet-4",
+    #     system_prompt: "You are an expert researcher.",
+    #     tools: [:Read, :Write, :Edit, :Bash, :Grep, :Glob],
+    #     directory: "/path/to/project",
+    #     parameters: { temperature: 0.7, thinking: { type: "enabled", budget_tokens: 10_000 } },
+    #     headers: { "anthropic-beta" => "some-feature" },
+    #     memory_directory: ".swarm/memory",
+    #     memory_stm_turns: 8,
+    #     memory_retrieval_top_k: 15,
+    #   )
+    #
+    # @example Custom memory adapter
+    #   definition = AgentDefinition.new(
+    #     name: :assistant,
+    #     description: "Assistant with Postgres memory",
+    #     memory_adapter: PgvectorAdapter.new("postgres://localhost/myapp"),
+    #   )
+    class AgentDefinition
+      # Valid API versions for OpenAI provider
+      VALID_API_VERSIONS = ["v1/responses", "v1/chat/completions"].freeze
+
+      # Valid queue delivery modes
+      VALID_QUEUE_MODES = [:all, :one_at_a_time].freeze
+
+      # @return [Symbol] Agent identifier
+      attr_reader :name
+
+      # @return [String] Agent role description
+      attr_reader :description
+
+      # @return [String] LLM model ID
+      attr_reader :model
+
+      # @return [String, nil] LLM provider
+      attr_reader :provider
+
+      # @return [String, nil] System prompt instructions
+      attr_reader :system_prompt
+
+      # @return [Array<Symbol>] Tool names
+      attr_reader :tools
+
+      # @return [String] Working directory
+      attr_reader :directory
+
+      # @return [String, nil] Custom API endpoint
+      attr_reader :base_url
+
+      # @return [Integer, nil] Maximum concurrent tool executions
+      attr_reader :max_concurrent_tools
+
+      # @return [Hash] Raw API body parameters (temperature, thinking, etc.)
+      attr_reader :parameters
+
+      # @return [Hash] Raw HTTP headers
+      attr_reader :headers
+
+      # @return [String, nil] Filesystem adapter path (nil = no memory)
+      attr_reader :memory_directory
+
+      # @return [Memory::Adapters::Base, nil] Custom adapter instance
+      attr_reader :memory_adapter
+
+      # @return [Integer] Recent turns to keep in short-term memory
+      attr_reader :memory_stm_turns
+
+      # @return [Integer] Cards to retrieve per turn
+      attr_reader :memory_retrieval_top_k
+
+      # @return [Float] Hybrid search semantic weight (0.0-1.0)
+      attr_reader :memory_semantic_weight
+
+      # @return [Float] Hybrid search keyword weight (0.0-1.0)
+      attr_reader :memory_keyword_weight
+
+      # @return [Boolean] Whether to surface exploration cards as tangential memories
+      #   the agent is encouraged to naturally bring up in conversation
+      attr_reader :memory_associative
+
+      # @return [Array<String>] Skill directory paths (expanded, frozen)
+      attr_reader :skills
+
+      # @return [Array<V3::MCP::ServerDefinition>] MCP server configurations (frozen)
+      attr_reader :mcp_servers
+
+      # @return [Hash, Object, nil] JSON Schema for structured output (pass-through to RubyLLM)
+      attr_reader :output_schema
+
+      # @return [String, nil] API version for OpenAI provider ("v1/responses" or "v1/chat/completions").
+      #   Defaults to "v1/responses" when provider is "openai". nil for non-OpenAI providers.
+      attr_reader :api_version
+
+      # @return [Array<Hash>] Hook configurations (frozen). Each hash has :event, :block,
+      #   and optional :match keys. Opaque to the definition — {Hooks::Runner} interprets them.
+      attr_reader :hooks
+
+      # @return [Symbol] Steering queue delivery mode (:all or :one_at_a_time)
+      attr_reader :steering_mode
+
+      # --- Subtask model configuration (per-agent override) ---
+
+      # @return [String, nil] Model for this agent's subtasks (nil = use global config or inherit)
+      attr_reader :subtask_model
+
+      # @return [String, nil] Provider for subtask model
+      attr_reader :subtask_provider
+
+      # @return [String, nil] Custom API base URL for subtask model
+      attr_reader :subtask_base_url
+
+      # @return [Hash] Custom HTTP headers for subtask model
+      attr_reader :subtask_headers
+
+      # @return [Hash] Raw API body parameters for subtask model
+      attr_reader :subtask_parameters
+
+      # Create a new agent definition
+      #
+      # @param name [Symbol, String] Agent identifier (required)
+      # @param description [String] Agent role description (required)
+      # @param model [String, nil] LLM model ID
+      # @param provider [String, nil] LLM provider
+      # @param system_prompt [String, nil] System prompt instructions
+      # @param tools [Array<Symbol>] Tool names
+      # @param directory [String] Working directory
+      # @param base_url [String, nil] Custom API endpoint
+      # @param max_concurrent_tools [Integer, nil] Max concurrent tool executions
+      # @param parameters [Hash] Raw API body parameters
+      # @param headers [Hash] Raw HTTP headers
+      # @param memory_directory [String, nil] Filesystem adapter path
+      # @param memory_adapter [Memory::Adapters::Base, nil] Custom adapter instance
+      # @param memory_stm_turns [Integer] Recent turns in STM
+      # @param memory_retrieval_top_k [Integer] Cards to retrieve per turn
+      # @param memory_semantic_weight [Float] Semantic search weight
+      # @param memory_keyword_weight [Float] Keyword search weight
+      # @param memory_associative [Boolean, nil] Enable associative memory
+      # @param skills [Array<String>] Skill directory paths
+      # @param mcp_servers [Array<Hash, V3::MCP::ServerDefinition>] MCP server configurations
+      # @param output_schema [Hash, Object, nil] JSON Schema for structured output (pass-through to RubyLLM)
+      # @param api_version [String, nil] API version for OpenAI provider.
+      #   Valid values: "v1/responses", "v1/chat/completions".
+      #   Defaults to "v1/responses" when provider is "openai". Ignored for other providers.
+      # @param hooks [Array<Hash>] Hook configurations. Each hash has :event (Symbol),
+      #   :block (Proc), and optional :match keys. See {Hooks::Runner} for details.
+      # @param steering_mode [Symbol] Steering queue delivery mode (:all or :one_at_a_time).
+      #   Default: :all (all steering messages injected together).
+      # @param subtask_model [String, nil] Model for this agent's subtasks
+      # @param subtask_provider [String, nil] Provider for subtask model
+      # @param subtask_base_url [String, nil] Custom API base URL for subtask model
+      # @param subtask_headers [Hash] Custom HTTP headers for subtask model
+      # @param subtask_parameters [Hash] Raw API body parameters for subtask model
+      #
+      # @raise [ConfigurationError] If required fields are missing or invalid
+      def initialize(
+        name:,
+        description:,
+        model: nil,
+        provider: nil,
+        system_prompt: nil,
+        tools: [],
+        directory: ".",
+        base_url: nil,
+        max_concurrent_tools: nil,
+        parameters: {},
+        headers: {},
+        memory_directory: nil,
+        memory_adapter: nil,
+        memory_stm_turns: nil,
+        memory_retrieval_top_k: nil,
+        memory_semantic_weight: nil,
+        memory_keyword_weight: nil,
+        memory_associative: nil,
+        skills: [],
+        mcp_servers: [],
+        output_schema: nil,
+        api_version: nil,
+        hooks: [],
+        steering_mode: :all,
+        subtask_model: nil,
+        subtask_provider: nil,
+        subtask_base_url: nil,
+        subtask_headers: {},
+        subtask_parameters: {}
+      )
+        config = Configuration.instance
+
+        @name = name.to_sym
+        @description = description
+        @model = model || config.default_model
+        @provider = provider
+        @system_prompt = system_prompt
+        @tools = Array(tools).map(&:to_sym)
+        @directory = File.expand_path(directory)
+        @base_url = base_url
+        @max_concurrent_tools = max_concurrent_tools || config.default_max_concurrent_tools
+        @parameters = parameters.freeze
+        @headers = headers.freeze
+        @memory_directory = memory_directory
+        @memory_adapter = memory_adapter
+        @memory_stm_turns = memory_stm_turns || config.default_stm_turns
+        @memory_retrieval_top_k = memory_retrieval_top_k || config.default_retrieval_top_k
+        @memory_semantic_weight = memory_semantic_weight || config.default_semantic_weight
+        @memory_keyword_weight = memory_keyword_weight || config.default_keyword_weight
+        @memory_associative = memory_associative.nil? ? config.default_associative_memory : memory_associative
+        @skills = Array(skills).map { |s| File.expand_path(s) }.freeze
+        @mcp_servers = Array(mcp_servers).map do |config|
+          config.is_a?(V3::MCP::ServerDefinition) ? config : V3::MCP::ServerDefinition.new(**config)
+        end.freeze
+        @output_schema = output_schema
+        @api_version = resolve_api_version(api_version)
+        @hooks = Array(hooks).freeze
+        @steering_mode = steering_mode.to_sym
+        @subtask_model = subtask_model
+        @subtask_provider = subtask_provider
+        @subtask_base_url = subtask_base_url
+        @subtask_headers = subtask_headers.freeze
+        @subtask_parameters = subtask_parameters.freeze
+
+        validate!
+        freeze
+      end
+
+      # Whether this agent has memory enabled
+      #
+      # @return [Boolean] true if memory_directory or memory_adapter is set
+      def memory_enabled?
+        !@memory_directory.nil? || !@memory_adapter.nil?
+      end
+
+      # Whether this agent has subtask model configuration
+      #
+      # @return [Boolean] true if any subtask_* option is set
+      def subtask_config?
+        !@subtask_model.nil? ||
+          !@subtask_provider.nil? ||
+          !@subtask_base_url.nil? ||
+          !@subtask_headers.empty? ||
+          !@subtask_parameters.empty?
+      end
+
+      private
+
+      # Resolve the effective API version based on provider
+      #
+      # When provider is "openai" and no api_version is specified,
+      # defaults to "v1/responses" (OpenAI Responses API).
+      #
+      # @param explicit_version [String, nil] Explicitly set api_version
+      # @return [String, nil] Resolved API version
+      def resolve_api_version(explicit_version)
+        openai = @provider.to_s.downcase == "openai"
+
+        if explicit_version
+          return explicit_version if openai
+
+          raise ConfigurationError,
+            "api_version is only supported for the OpenAI provider (got provider: #{@provider.inspect})"
+        end
+
+        openai ? "v1/responses" : nil
+      end
+
+      # Validate the definition
+      #
+      # @raise [ConfigurationError] If validation fails
+      def validate!
+        raise ConfigurationError, "Agent name is required" if @name.nil? || @name.to_s.strip.empty?
+        raise ConfigurationError, "Agent description is required" if @description.nil? || @description.to_s.strip.empty?
+        raise ConfigurationError, "Agent model is required" if @model.nil? || @model.to_s.strip.empty?
+
+        if @api_version && !VALID_API_VERSIONS.include?(@api_version)
+          raise ConfigurationError,
+            "Invalid api_version #{@api_version.inspect}. " \
+              "Valid values: #{VALID_API_VERSIONS.map(&:inspect).join(", ")}"
+        end
+
+        if @memory_semantic_weight < 0.0 || @memory_semantic_weight > 1.0
+          raise ConfigurationError, "memory_semantic_weight must be between 0.0 and 1.0"
+        end
+
+        if @memory_keyword_weight < 0.0 || @memory_keyword_weight > 1.0
+          raise ConfigurationError, "memory_keyword_weight must be between 0.0 and 1.0"
+        end
+
+        if @memory_stm_turns < 1
+          raise ConfigurationError, "memory_stm_turns must be at least 1"
+        end
+
+        if @memory_retrieval_top_k < 1
+          raise ConfigurationError, "memory_retrieval_top_k must be at least 1"
+        end
+
+        if @skills.any? && !@tools.include?(:Read)
+          raise ConfigurationError, "Agent with skills requires the Read tool to activate skills"
+        end
+
+        unless VALID_QUEUE_MODES.include?(@steering_mode)
+          raise ConfigurationError,
+            "Invalid steering_mode #{@steering_mode.inspect}. " \
+              "Valid values: #{VALID_QUEUE_MODES.map(&:inspect).join(", ")}"
+        end
+
+        if subtask_config? && !@tools.include?(:SubTask)
+          raise ConfigurationError,
+            "Agent '#{@name}' has subtask model configuration but does not include the :SubTask tool. " \
+              "Either add :SubTask to tools or remove subtask_* options."
+        end
+      end
+    end
+  end
+end