swarm_sdk 2.7.14 → 3.0.0.alpha2

data/lib/swarm_sdk/v3/agent_builder.rb

@@ -0,0 +1,533 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    # DSL builder for creating a single V3 Agent
+    #
+    # Provides a clean, block-based interface for defining an agent without
+    # needing to construct AgentDefinition kwargs directly. Unlike the V2
+    # builder which manages multi-agent swarms, this creates a single agent.
+    #
+    # @example Minimal agent
+    #   agent = SwarmSDK::V3.agent do
+    #     name :assistant
+    #     description "A helpful assistant"
+    #   end
+    #
+    # @example Full agent with memory
+    #   agent = SwarmSDK::V3.agent do
+    #     name :researcher
+    #     description "Research specialist"
+    #     model "claude-sonnet-4"
+    #     provider "anthropic"
+    #     system_prompt "You are an expert researcher."
+    #     tools :Read, :Write, :Edit, :Bash, :Grep, :Glob
+    #     directory "/path/to/project"
+    #
+    #     memory do
+    #       directory ".swarm/memory"
+    #       stm_turns 8
+    #       retrieval_top_k 15
+    #     end
+    #   end
+    #
+    #   agent.ask("Hello!")
+    class AgentBuilder
+      class << self
+        # Build an Agent from a DSL block
+        #
+        # @yield DSL block evaluated via instance_eval
+        # @return [Agent] Initialized agent ready for use
+        #
+        # @example
+        #   agent = AgentBuilder.build do
+        #     name :coder
+        #     description "Code writer"
+        #     tools :Read, :Edit
+        #   end
+        def build(&block)
+          builder = new
+          builder.instance_eval(&block)
+          builder.to_agent
+        end
+      end
+
+      def initialize
+        @config = {}
+        @tools = []
+        @skills = []
+        @mcp_servers = []
+        @hooks = []
+        @memory_config = nil
+      end
+
+      # @!group DSL Methods
+
+      # Set agent name
+      #
+      # @param value [Symbol, String] Agent identifier
+      # @return [void]
+      #
+      # @example
+      #   name :researcher
+      def name(value)
+        @config[:name] = value
+      end
+
+      # Set agent description
+      #
+      # @param value [String] Agent role description
+      # @return [void]
+      #
+      # @example
+      #   description "Research specialist"
+      def description(value)
+        @config[:description] = value
+      end
+
+      # Set LLM model
+      #
+      # @param value [String] Model identifier
+      # @return [void]
+      #
+      # @example
+      #   model "claude-sonnet-4"
+      def model(value)
+        @config[:model] = value
+      end
+
+      # Set LLM provider
+      #
+      # @param value [String] Provider name
+      # @return [void]
+      #
+      # @example
+      #   provider "anthropic"
+      def provider(value)
+        @config[:provider] = value
+      end
+
+      # Set system prompt instructions
+      #
+      # @param value [String] System prompt text
+      # @return [void]
+      #
+      # @example
+      #   system_prompt "You are an expert researcher."
+      def system_prompt(value)
+        @config[:system_prompt] = value
+      end
+
+      # Add tools to the agent
+      #
+      # Can be called multiple times; tools accumulate across calls.
+      #
+      # @param names [Array<Symbol, String>] Tool names
+      # @return [void]
+      #
+      # @example Single call
+      #   tools :Read, :Write, :Edit
+      #
+      # @example Multiple calls accumulate
+      #   tools :Read, :Write
+      #   tools :Bash, :Grep
+      #   # => [:Read, :Write, :Bash, :Grep]
+      def tools(*names)
+        @tools.concat(names.flatten)
+      end
+
+      # Add skill directories to the agent
+      #
+      # Can be called multiple times; paths accumulate across calls.
+      # Each path should be a directory containing a SKILL.md file,
+      # or a parent directory whose children contain SKILL.md files.
+      #
+      # @param paths [Array<String>] Skill directory paths
+      # @return [void]
+      #
+      # @example Single call
+      #   skills "/path/to/skills"
+      #
+      # @example Multiple calls accumulate
+      #   skills "/skills/pdf"
+      #   skills "/skills/csv"
+      def skills(*paths)
+        @skills.concat(paths.flatten)
+      end
+
+      # Set working directory
+      #
+      # @param value [String] Directory path
+      # @return [void]
+      #
+      # @example
+      #   directory "/path/to/project"
+      def directory(value)
+        @config[:directory] = value
+      end
+
+      # Set custom API endpoint
+      #
+      # @param value [String] Base URL
+      # @return [void]
+      #
+      # @example
+      #   base_url "https://api.example.com"
+      def base_url(value)
+        @config[:base_url] = value
+      end
+
+      # Set maximum concurrent tool executions
+      #
+      # @param value [Integer] Max concurrent tools
+      # @return [void]
+      #
+      # @example
+      #   max_concurrent_tools 5
+      def max_concurrent_tools(value)
+        @config[:max_concurrent_tools] = value
+      end
+
+      # Set raw API body parameters
+      #
+      # @param value [Hash] Parameters hash
+      # @return [void]
+      #
+      # @example
+      #   parameters(temperature: 0.7, thinking: { type: "enabled", budget_tokens: 10_000 })
+      def parameters(value)
+        @config[:parameters] = value
+      end
+
+      # Set raw HTTP headers
+      #
+      # @param value [Hash] Headers hash
+      # @return [void]
+      #
+      # @example
+      #   headers("anthropic-beta" => "some-feature")
+      def headers(value)
+        @config[:headers] = value
+      end
+
+      # Set output schema for structured output
+      #
+      # The schema is passed through to RubyLLM's Chat#with_schema.
+      # Can be a Hash (raw JSON Schema) or any object responding to #to_json_schema.
+      #
+      # @param value [Hash, Object] Schema definition
+      # @return [void]
+      #
+      # @example Raw JSON Schema
+      #   output_schema({ type: "object", properties: { name: { type: "string" } } })
+      def output_schema(value)
+        @config[:output_schema] = value
+      end
+
+      # Set API version for OpenAI provider
+      #
+      # Controls which OpenAI API endpoint to use. Only applicable when
+      # provider is "openai". Defaults to "v1/responses" for OpenAI agents.
+      #
+      # @param value [String] API version ("v1/responses" or "v1/chat/completions")
+      # @return [void]
+      #
+      # @example Use Chat Completions API
+      #   api_version "v1/chat/completions"
+      #
+      # @example Use Responses API (default for OpenAI)
+      #   api_version "v1/responses"
+      def api_version(value)
+        @config[:api_version] = value
+      end
+
+      # Configure memory via a sub-block
+      #
+      # @yield DSL block evaluated on a MemoryBuilder
+      # @return [void]
+      #
+      # @example
+      #   memory do
+      #     directory ".swarm/memory"
+      #     stm_turns 8
+      #     retrieval_top_k 15
+      #   end
+      def memory(&block)
+        @memory_config = MemoryBuilder.build(&block)
+      end
+
+      # Register a before_ask hook
+      #
+      # Fires before {Agent#execute_turn}. Can halt (returns nil from ask)
+      # or replace the prompt.
+      #
+      # @yield [ctx] Hook block receiving a {Hooks::Context}
+      # @return [void]
+      #
+      # @example Log every prompt
+      #   before_ask { |ctx| puts "Processing: #{ctx.prompt}" }
+      #
+      # @example Block certain prompts
+      #   before_ask { |ctx| ctx.halt("Blocked") if ctx.prompt.include?("secret") }
+      def before_ask(&block)
+        @hooks << { event: :before_ask, block: block }
+      end
+
+      # Register an after_ask hook
+      #
+      # Fires after {Agent#execute_turn} completes. Observation only —
+      # halt and replace have no effect.
+      #
+      # @yield [ctx] Hook block receiving a {Hooks::Context}
+      # @return [void]
+      #
+      # @example Log responses
+      #   after_ask { |ctx| log_response(ctx.response) }
+      def after_ask(&block)
+        @hooks << { event: :after_ask, block: block }
+      end
+
+      # Register a before_tool hook
+      #
+      # Fires before tool execution. Can halt (returns error string to LLM
+      # without executing the tool). Supports match filtering.
+      #
+      # @param match [Symbol, String, Regexp, Array, nil] Tool name matcher
+      # @yield [ctx] Hook block receiving a {Hooks::Context}
+      # @return [void]
+      #
+      # @example Block Bash tool
+      #   before_tool(match: :Bash) { |ctx| ctx.halt("Bash disabled") }
+      #
+      # @example Validate Write/Edit arguments
+      #   before_tool(match: [:Write, :Edit]) { |ctx| validate(ctx.tool_arguments) }
+      def before_tool(match: nil, &block)
+        @hooks << { event: :before_tool, match: compile_matcher(match), block: block }
+      end
+
+      # Register an after_tool hook
+      #
+      # Fires after tool execution. Can replace the tool result.
+      # Supports match filtering.
+      #
+      # @param match [Symbol, String, Regexp, Array, nil] Tool name matcher
+      # @yield [ctx] Hook block receiving a {Hooks::Context}
+      # @return [void]
+      #
+      # @example Sanitize Bash output
+      #   after_tool(match: /Bash/) { |ctx| ctx.replace(sanitize(ctx.tool_result)) }
+      def after_tool(match: nil, &block)
+        @hooks << { event: :after_tool, match: compile_matcher(match), block: block }
+      end
+
+      # Register an on_stop hook
+      #
+      # Fires after ask() completes successfully. Observation only —
+      # the response has already been produced. Useful for logging,
+      # metrics, or cleanup.
+      #
+      # @yield [ctx] Hook block receiving a {Hooks::Context}
+      # @return [void]
+      #
+      # @example Track completions
+      #   on_stop { |ctx| metrics.increment("agent.#{ctx.agent_name}.completed") }
+      def on_stop(&block)
+        @hooks << { event: :on_stop, block: block }
+      end
+
+      # Add an MCP server connection
+      #
+      # Can be called multiple times; servers accumulate across calls.
+      # Each server provides tools that the agent can invoke via MCP protocol.
+      #
+      # @param name [Symbol, String] Server identifier
+      # @param options [Hash] Server configuration options
+      # @option options [Symbol] :type Transport type (:stdio or :http)
+      # @option options [String] :command Subprocess command (stdio)
+      # @option options [Array<String>] :args Subprocess arguments (stdio)
+      # @option options [Hash] :env Subprocess environment (stdio)
+      # @option options [String] :url HTTP endpoint URL (http)
+      # @option options [Hash] :headers HTTP headers (http)
+      # @option options [Array<Symbol>] :tools Tool names to expose (nil = all)
+      # @return [void]
+      #
+      # @example HTTP server
+      #   mcp_server :api,
+      #     type: :http,
+      #     url: "https://example.com/mcp",
+      #     headers: { "Authorization" => "Bearer token" }
+      #
+      # @example Stdio server with tool filtering
+      #   mcp_server :filesystem,
+      #     type: :stdio,
+      #     command: "npx",
+      #     args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      #     tools: [:read_file, :list_directory]
+      def mcp_server(name, **options)
+        @mcp_servers << options.merge(name: name)
+      end
+
+      # @!endgroup
+
+      # Build the Agent from collected configuration
+      #
+      # @return [Agent] Initialized agent
+      # @raise [ConfigurationError] If required fields are missing
+      def to_agent
+        definition = AgentDefinition.new(**definition_kwargs)
+        Agent.new(definition)
+      end
+
+      private
+
+      # Assemble keyword arguments for AgentDefinition
+      #
+      # @return [Hash] Keyword arguments
+      def definition_kwargs
+        kwargs = @config.dup
+        kwargs[:tools] = @tools unless @tools.empty?
+        kwargs[:skills] = @skills unless @skills.empty?
+        kwargs[:mcp_servers] = @mcp_servers unless @mcp_servers.empty?
+        kwargs[:hooks] = @hooks unless @hooks.empty?
+        kwargs.merge!(@memory_config) if @memory_config
+        kwargs
+      end
+
+      # Compile a match specification into a normalized matcher
+      #
+      # Handles Symbol, String, Regexp, Array, and nil inputs.
+      # Arrays are recursively compiled so nested values are normalized.
+      #
+      # @param match [Symbol, String, Regexp, Array, nil] Raw match input
+      # @return [Symbol, String, Regexp, Array, nil] Compiled matcher
+      def compile_matcher(match)
+        case match
+        when nil, Symbol, String, Regexp then match
+        when Array then match.map { |m| compile_matcher(m) }
+        else
+          raise ArgumentError, "Invalid match type: #{match.class}. Use Symbol, String, Regexp, Array, or nil."
+        end
+      end
+    end
+
+    # Sub-builder for memory configuration within AgentBuilder
+    #
+    # Collects memory-related settings and returns them as a hash
+    # with the `memory_` prefix expected by AgentDefinition.
+    #
+    # @example
+    #   config = MemoryBuilder.build do
+    #     directory ".swarm/memory"
+    #     stm_turns 8
+    #   end
+    #   # => { memory_directory: ".swarm/memory", memory_stm_turns: 8 }
+    class MemoryBuilder
+      class << self
+        # Build memory config from a DSL block
+        #
+        # @yield DSL block evaluated via instance_eval
+        # @return [Hash] Memory configuration with `memory_` prefixed keys
+        def build(&block)
+          builder = new
+          builder.instance_eval(&block)
+          builder.to_h
+        end
+      end
+
+      def initialize
+        @config = {}
+      end
+
+      # Set memory storage directory
+      #
+      # @param value [String] Directory path
+      # @return [void]
+      def directory(value)
+        @config[:memory_directory] = value
+      end
+
+      # Set number of recent turns to keep in short-term memory
+      #
+      # @param value [Integer] STM turn count
+      # @return [void]
+      def stm_turns(value)
+        @config[:memory_stm_turns] = value
+      end
+
+      # Set number of memory cards to retrieve per turn
+      #
+      # @param value [Integer] Top-k retrieval count
+      # @return [void]
+      def retrieval_top_k(value)
+        @config[:memory_retrieval_top_k] = value
+      end
+
+      # Set semantic search weight for hybrid retrieval
+      #
+      # @param value [Float] Weight between 0.0 and 1.0
+      # @return [void]
+      def semantic_weight(value)
+        @config[:memory_semantic_weight] = value
+      end
+
+      # Set keyword search weight for hybrid retrieval
+      #
+      # @param value [Float] Weight between 0.0 and 1.0
+      # @return [void]
+      def keyword_weight(value)
+        @config[:memory_keyword_weight] = value
+      end
+
+      # Valid adapter type symbols
+      VALID_ADAPTER_TYPES = [:sqlite, :filesystem].freeze
+
+      # Set the memory adapter
+      #
+      # @param value [Symbol, Memory::Adapters::Base] Adapter type or instance
+      # @return [void]
+      # @raise [ArgumentError] If value is not a valid adapter type or instance
+      #
+      # @example Using a symbol
+      #   adapter :sqlite
+      #   adapter :filesystem
+      #
+      # @example Using an adapter instance
+      #   adapter MyCustomAdapter.new("/path/to/storage")
+      def adapter(value)
+        case value
+        when Symbol
+          unless VALID_ADAPTER_TYPES.include?(value)
+            raise ArgumentError, "Unknown memory adapter type: #{value.inspect}. " \
+              "Valid types are: #{VALID_ADAPTER_TYPES.map(&:inspect).join(", ")}"
+          end
+        when Memory::Adapters::Base
+          # Valid adapter instance
+        else
+          raise ArgumentError, "Memory adapter must be a Symbol (#{VALID_ADAPTER_TYPES.map(&:inspect).join(", ")}) " \
+            "or an instance of Memory::Adapters::Base, got: #{value.class}"
+        end
+        @config[:memory_adapter] = value
+      end
+
+      # Enable associative memory
+      #
+      # When enabled, the agent naturally surfaces tangential memories
+      # in conversation, like a person who brings up related topics.
+      # Exploration cards get a distinct "YOU ALSO REMEMBER" section
+      # and guidance is injected into the system prompt.
+      #
+      # @param value [Boolean] Whether to enable associative memory
+      # @return [void]
+      def associative(value)
+        @config[:memory_associative] = value
+      end
+
+      # Return collected memory configuration
+      #
+      # @return [Hash] Memory config with `memory_` prefixed keys
+      def to_h
+        @config.dup
+      end
+    end
+  end
+end