swarm_sdk 3.0.0.alpha2 → 3.0.0.alpha3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4feb796b3437eea5e610a13ed80923a4d2bda9841fc164d44cb330a5da20e97e
-  data.tar.gz: 3006b77e78aedd12c2371300d6599870aef32f9bf33285c7229ce9eadd453364
+  metadata.gz: 569ac707625b9bcfc78080af26a7c1d48895b5057302c23f98543b9b44e6a706
+  data.tar.gz: ab685ff041e4106046ce4da5e4ec9b3937fd4d6290e1f5deeb7d7991f579da6b
 SHA512:
-  metadata.gz: 87bfebe06e4c043c131a6d51d2effe8cd7de7893075593b2b008126887f5837850486c8e354f918ef2fa283c9d286638a25efc632917f0a86ab57815102333ce
-  data.tar.gz: e2afe829f9c2394de45c07eb2b6ff692446ee2108d0b615a375447a87c797bd59b4f0745d96b1c7a8a40b7ef350e167b29c247a7a376ea366feb370ea0eaac1a
+  metadata.gz: fd68128f22e9758ae66548a4ae2f48b210e92b2c79f4bd78c46fd47cd1d34a9d282740ee35881c27c515ac7eb8b294db6f36c8a70e762ea01ad1d52085da0b5b
+  data.tar.gz: d802eb7a4112874bf7b2ad414564af4fb9806074b8d8d108a471efc33943133942ee646360c7f4ce8390728d44cc031cede119fca993a79a8c6f1e6a7a6c7ee1

data/lib/swarm_sdk/v3/agent.rb

@@ -305,6 +305,77 @@ module SwarmSDK
         false
       end
 
+      # Run an iterative refinement loop over the agent
+      #
+      # Executes a kickoff prompt followed by repeated iterate prompts,
+      # optionally checking for convergence via embedding similarity
+      # between consecutive responses. Each iteration is a normal ask()
+      # call — hooks fire, memory ingests, and events stream normally.
+      #
+      # @param kickoff [String] Prompt for the first iteration
+      # @param iterate [String] Prompt for subsequent iterations
+      # @param max_iterations [Integer] Maximum number of iterations (>= 1)
+      # @param convergence_threshold [Float] Similarity threshold for convergence (0.0..1.0)
+      # @param converge [Boolean] Whether to check for convergence via embeddings
+      # @yield [event] Optional block receives ALL events (content_chunk, loop_*, etc.)
+      # @yieldparam event [Hash] Event hash with :type, :timestamp, and event-specific fields
+      # @return [Loop::Result] Aggregate result with iterations and convergence status
+      #
+      # @example Basic iterative refinement
+      #   result = agent.loop(
+      #     kickoff: "Write a poem about the sea",
+      #     iterate: "Improve the poem, making it more vivid",
+      #     max_iterations: 5,
+      #   )
+      #   puts result.final_response.content
+      #   puts "Converged: #{result.converged?}"
+      #
+      # @example Without convergence checking
+      #   result = agent.loop(
+      #     kickoff: "Draft an outline",
+      #     iterate: "Expand the next section",
+      #     max_iterations: 3,
+      #     converge: false,
+      #   )
+      #
+      # @example With event streaming
+      #   agent.loop(kickoff: "Start", iterate: "Continue", max_iterations: 5) do |event|
+      #     case event[:type]
+      #     when "loop_iteration_completed"
+      #       puts "Iteration #{event[:iteration]}, delta: #{event[:delta_score]}"
+      #     when "content_chunk"
+      #       print event[:content]
+      #     end
+      #   end
+      #
+      # @raise [ArgumentError] If max_iterations < 1 or convergence_threshold out of range
+      def loop(kickoff:, iterate:, max_iterations: 10, convergence_threshold: 0.95, converge: true, &block)
+        validate_loop_params!(max_iterations, convergence_threshold)
+
+        embedder = converge ? loop_embedder : nil
+        ask_callable = ->(prompt) { ask(prompt, &block) }
+
+        executor = Loop::Executor.new(
+          ask_callable: ask_callable,
+          embedder: embedder,
+          agent_id: @id,
+        )
+
+        # Wrap with block emitter so loop lifecycle events
+        # (loop_started, loop_iteration_completed, loop_completed)
+        # reach the caller's block. Each ask() inside the executor
+        # will also set/restore the block emitter for its own events.
+        with_block_emitter(block) do
+          executor.run(
+            kickoff: kickoff,
+            iterate: iterate,
+            max_iterations: max_iterations,
+            convergence_threshold: convergence_threshold,
+            converge: converge,
+          )
+        end
+      end
+
       # Run memory defragmentation (compression, consolidation, promotion, pruning)
       #
       # Call this between sessions, on a schedule, or whenever appropriate.
@@ -1160,6 +1231,33 @@ module SwarmSDK
         @mcp_connectors.each(&:disconnect!)
         @mcp_connectors.clear
       end
+
+      # Validate loop parameters
+      #
+      # @param max_iterations [Integer] Must be >= 1
+      # @param convergence_threshold [Float] Must be between 0.0 and 1.0
+      # @raise [ArgumentError] If parameters are invalid
+      # @return [void]
+      def validate_loop_params!(max_iterations, convergence_threshold)
+        unless max_iterations.is_a?(Integer) && max_iterations >= 1
+          raise ArgumentError, "max_iterations must be an integer >= 1, got #{max_iterations.inspect}"
+        end
+
+        unless convergence_threshold.is_a?(Numeric) && convergence_threshold >= 0.0 && convergence_threshold <= 1.0
+          raise ArgumentError,
+            "convergence_threshold must be between 0.0 and 1.0, got #{convergence_threshold.inspect}"
+        end
+      end
+
+      # Resolve or create an embedder for loop convergence detection
+      #
+      # Reuses the memory store's embedder if available (ONNX model
+      # already loaded), otherwise creates a standalone instance.
+      #
+      # @return [Memory::Embedder]
+      def loop_embedder
+        @memory_store&.embedder || Memory::Embedder.new
+      end
     end
   end
 end

data/lib/swarm_sdk/v3/loop/executor.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Loop
+      # Core loop engine for iterative refinement
+      #
+      # Runs a sequence of ask() calls through a provided callable,
+      # optionally checking for convergence via embedding similarity
+      # between consecutive responses. Emits events for each iteration
+      # and the overall loop lifecycle.
+      #
+      # The Executor is stateless between runs — all configuration is
+      # passed to {#run}. The ask callable and embedder are injected
+      # at construction for testability.
+      #
+      # @example Basic usage (called internally by Agent#loop)
+      #   executor = Executor.new(
+      #     ask_callable: ->(prompt) { agent.ask(prompt) },
+      #     embedder: Memory::Embedder.new,
+      #     agent_id: "writer_abc123",
+      #   )
+      #   result = executor.run(
+      #     kickoff: "Write a poem about the sea",
+      #     iterate: "Improve the poem",
+      #     max_iterations: 5,
+      #     convergence_threshold: 0.95,
+      #     converge: true,
+      #   )
+      class Executor
+        include Memory::Adapters::VectorUtils
+
+        # Create a new Executor
+        #
+        # @param ask_callable [#call] Lambda wrapping agent.ask(prompt)
+        # @param embedder [Memory::Embedder, nil] Embedder for convergence detection (nil if converge: false)
+        # @param agent_id [String] Agent identifier for event emission
+        def initialize(ask_callable:, embedder:, agent_id:)
+          @ask_callable = ask_callable
+          @embedder = embedder
+          @agent_id = agent_id
+        end
+
+        # Execute the iterative loop
+        #
+        # Runs the kickoff prompt first, then the iterate prompt for
+        # subsequent iterations. If convergence checking is enabled,
+        # computes embedding similarity between consecutive responses
+        # and stops when it exceeds the threshold.
+        #
+        # @param kickoff [String] Prompt for the first iteration
+        # @param iterate [String] Prompt for subsequent iterations
+        # @param max_iterations [Integer] Maximum number of iterations (>= 1)
+        # @param convergence_threshold [Float] Similarity threshold for convergence (0.0..1.0)
+        # @param converge [Boolean] Whether to check for convergence
+        # @return [Result] Aggregate result with all iterations
+        #
+        # @example Run with convergence
+        #   result = executor.run(
+        #     kickoff: "Draft an essay",
+        #     iterate: "Revise and improve",
+        #     max_iterations: 10,
+        #     convergence_threshold: 0.95,
+        #     converge: true,
+        #   )
+        #   result.converged?  #=> true or false
+        def run(kickoff:, iterate:, max_iterations:, convergence_threshold:, converge:)
+          EventStream.emit(
+            type: "loop_started",
+            agent: @agent_id,
+            max_iterations: max_iterations,
+            convergence_threshold: convergence_threshold,
+          )
+
+          iterations = []
+          converged = false
+          previous_content = nil
+
+          max_iterations.times do |index|
+            prompt = index.zero? ? kickoff : iterate
+            response = @ask_callable.call(prompt)
+
+            # Handle interrupted agent (ask() returns nil)
+            break if response.nil?
+
+            current_content = response.content.to_s
+            input_tokens = response.respond_to?(:input_tokens) ? (response.input_tokens || 0) : 0
+            output_tokens = response.respond_to?(:output_tokens) ? (response.output_tokens || 0) : 0
+
+            delta_score = nil
+            if converge && previous_content && @embedder
+              delta_score = compute_delta(previous_content, current_content)
+            end
+
+            iteration = Iteration.new(
+              number: index + 1,
+              response: response,
+              prompt: prompt,
+              tokens: { input: input_tokens, output: output_tokens },
+              delta_score: delta_score,
+            )
+            iterations << iteration
+
+            EventStream.emit(
+              type: "loop_iteration_completed",
+              agent: @agent_id,
+              iteration: index + 1,
+              delta_score: delta_score,
+              converged: false,
+            )
+
+            if delta_score && delta_score >= convergence_threshold
+              converged = true
+              break
+            end
+
+            previous_content = current_content
+          end
+
+          EventStream.emit(
+            type: "loop_completed",
+            agent: @agent_id,
+            iterations: iterations.size,
+            converged: converged,
+          )
+
+          Result.new(iterations: iterations, converged: converged)
+        end
+
+        private
+
+        # Compute cosine similarity between two response texts
+        #
+        # Uses batch embedding for efficiency — both texts are embedded
+        # in a single call to the underlying model.
+        #
+        # @param previous_content [String] Previous iteration's response text
+        # @param current_content [String] Current iteration's response text
+        # @return [Float] Cosine similarity (0.0..1.0 for typical text)
+        def compute_delta(previous_content, current_content)
+          vectors = @embedder.embed_batch([previous_content, current_content])
+          similarity(vectors[0], vectors[1])
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/loop/iteration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Loop
+      # Immutable record of a single loop iteration
+      #
+      # Captures the prompt sent, the LLM response received, token usage,
+      # and the embedding-similarity delta from the previous iteration.
+      # Frozen on creation to prevent accidental mutation.
+      #
+      # @example First iteration (no delta)
+      #   iteration = Iteration.new(
+      #     number: 1,
+      #     response: response,
+      #     prompt: "Write a poem",
+      #     tokens: { input: 10, output: 20 },
+      #     delta_score: nil,
+      #   )
+      #
+      # @example Subsequent iteration with convergence score
+      #   iteration = Iteration.new(
+      #     number: 2,
+      #     response: response,
+      #     prompt: "Improve the poem",
+      #     tokens: { input: 15, output: 25 },
+      #     delta_score: 0.87,
+      #   )
+      class Iteration
+        # @return [Integer] 1-indexed iteration number
+        attr_reader :number
+
+        # @return [RubyLLM::Message] LLM response from ask()
+        attr_reader :response
+
+        # @return [String] Prompt used for this iteration (kickoff or iterate)
+        attr_reader :prompt
+
+        # @return [Hash{Symbol => Integer}] Token usage { input:, output: }
+        attr_reader :tokens
+
+        # @return [Float, nil] Cosine similarity to previous iteration (nil for iteration 1)
+        attr_reader :delta_score
+
+        # Create a new Iteration record
+        #
+        # @param number [Integer] 1-indexed iteration number
+        # @param response [RubyLLM::Message] LLM response
+        # @param prompt [String] Prompt used
+        # @param tokens [Hash{Symbol => Integer}] Token usage { input:, output: }
+        # @param delta_score [Float, nil] Similarity to previous iteration
+        def initialize(number:, response:, prompt:, tokens:, delta_score:)
+          @number = number
+          @response = response
+          @prompt = prompt
+          @tokens = tokens.freeze
+          @delta_score = delta_score
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/loop/result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Loop
+      # Aggregate result of a completed loop execution
+      #
+      # Contains all iterations and whether the loop converged.
+      # Frozen on creation — both the Result and its iterations array
+      # are immutable after construction.
+      #
+      # @example Converged loop
+      #   result = executor.run(kickoff: "Write a poem", iterate: "Improve it", ...)
+      #   result.converged?       #=> true
+      #   result.iteration_count  #=> 3
+      #   result.final_response   #=> RubyLLM::Message
+      #   result.total_tokens     #=> { input: 45, output: 60 }
+      #
+      # @example Non-converged loop (hit max_iterations)
+      #   result.converged?       #=> false
+      #   result.iteration_count  #=> 10
+      class Result
+        # @return [Array<Iteration>] All iterations (frozen)
+        attr_reader :iterations
+
+        # @return [Boolean] Whether the loop converged below the threshold
+        attr_reader :converged
+        alias_method :converged?, :converged
+
+        # Create a new Result
+        #
+        # @param iterations [Array<Iteration>] Completed iterations
+        # @param converged [Boolean] Whether convergence was detected
+        def initialize(iterations:, converged:)
+          @iterations = iterations.freeze
+          @converged = converged
+          freeze
+        end
+
+        # The last iteration's LLM response
+        #
+        # @return [RubyLLM::Message, nil] Final response, or nil if no iterations
+        #
+        # @example
+        #   puts result.final_response.content
+        def final_response
+          @iterations.last&.response
+        end
+
+        # Number of iterations executed
+        #
+        # @return [Integer]
+        #
+        # @example
+        #   result.iteration_count  #=> 3
+        def iteration_count
+          @iterations.size
+        end
+
+        # Aggregate token usage across all iterations
+        #
+        # @return [Hash{Symbol => Integer}] { input:, output: }
+        #
+        # @example
+        #   result.total_tokens  #=> { input: 45, output: 60 }
+        def total_tokens
+          input = @iterations.sum { |i| i.tokens[:input] }
+          output = @iterations.sum { |i| i.tokens[:output] }
+          { input: input, output: output }
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 3.0.0.alpha2
+  version: 3.0.0.alpha3
 platform: ruby
 authors:
 - Paulo Arruda
@@ -139,6 +139,9 @@ files:
 - lib/swarm_sdk/v3/hooks/context.rb
 - lib/swarm_sdk/v3/hooks/result.rb
 - lib/swarm_sdk/v3/hooks/runner.rb
+- lib/swarm_sdk/v3/loop/executor.rb
+- lib/swarm_sdk/v3/loop/iteration.rb
+- lib/swarm_sdk/v3/loop/result.rb
 - lib/swarm_sdk/v3/mcp/connector.rb
 - lib/swarm_sdk/v3/mcp/mcp_error.rb
 - lib/swarm_sdk/v3/mcp/server_definition.rb