swarm_sdk 2.5.1 → 2.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47faf60bdab82a9c32d9e973eac8b3cc5f4130782807d8d2868417490c22cd76
-  data.tar.gz: 120e8f3e9eec742210896b4d97dcc18c599c16ea41b70d55d54eff3e2552fec0
+  metadata.gz: d2d30192f340ca7aca46ae7aee4538753a28a9815ff45be7260f1ceb8415a805
+  data.tar.gz: 551313de97c99e736c826248fc9d3ef67afb980d97c43fa44bb20566b9c3c26d
 SHA512:
-  metadata.gz: c3b35f154d84a650010b67c70de048ea78b741bd9d6c00fb5543f87eeb1d73f8996b33a027f441fdf861a96142b8e6b4ebbd005bfbf3d8090207df3a4a564984
-  data.tar.gz: 650bcb9717ac7a4221622f0eadb6549687d3a49fc16f57d99c0d9008acf07649ec34bacab9805d560dcc58070942cc3be92063ccdec7b37aaccdfa50476819ee
+  metadata.gz: 05572dc6a8e17492bd9df3d4d1bf1ff4af5e4fccc35d3309b1cef11f7561adcbb1b5f07ab35e723c1780e96fc88f44dd737cc9d25f2b2298a2ec5b578a65e154
+  data.tar.gz: 7e55b40a56b7bf861f205308490f3a37036375f93465b54ffeb10032154af84ea1b7110ce31c353bb1cb344d1bcf95f7e5383cfb6c6d9c12caad65e74e137171

data/lib/swarm_sdk/result.rb

@@ -109,6 +109,43 @@ module SwarmSDK
       @logs.map { |entry| entry[:agent] }.compact.uniq.map(&:to_sym)
     end
 
+    # Generate an LLM-readable transcript of the conversation
+    #
+    # Converts the execution logs into a human/LLM-readable format suitable for
+    # reflection, analysis, memory creation, or passing to another agent.
+    #
+    # @param agents [Array<Symbol>] Optional list of agents to filter by.
+    #   If no agents specified, includes all agents.
+    #   If one or more agents specified, only includes events from those agents.
+    # @param include_tool_results [Boolean] Include tool execution results (default: true)
+    # @param include_thinking [Boolean] Include agent_step content/thinking (default: false)
+    # @return [String] Formatted transcript ready for LLM consumption
+    #
+    # @example Get full transcript
+    #   result.transcript
+    #   # => "USER: Help me with CORS\n\nAGENT [assistant]: ..."
+    #
+    # @example Filter to specific agents
+    #   result.transcript(:backend, :database)
+    #   # => Only events from backend and database agents
+    #
+    # @example Single agent transcript
+    #   result.transcript(:backend)
+    #   # => Only events from backend agent
+    #
+    # @example Include thinking steps
+    #   result.transcript(include_thinking: true)
+    #   # => Includes agent_step intermediate reasoning
+    def transcript(*agents, include_tool_results: true, include_thinking: false)
+      agent_filter = agents.empty? ? nil : agents
+      TranscriptBuilder.build(
+        @logs,
+        agents: agent_filter,
+        include_tool_results: include_tool_results,
+        include_thinking: include_thinking,
+      )
+    end
+
     # Get per-agent usage breakdown from logs
     #
     # Aggregates context usage, tokens, and cost for each agent from their

data/lib/swarm_sdk/swarm/logging_callbacks.rb

@@ -222,6 +222,7 @@ module SwarmSDK
           agent: context.agent_name,
           swarm_id: @swarm_id,
           parent_swarm_id: @parent_swarm_id,
+          prompt: context.metadata[:prompt],
           model: context.metadata[:model] || "unknown",
           provider: context.metadata[:provider] || "unknown",
           message_count: context.metadata[:message_count] || 0,

data/lib/swarm_sdk/transcript_builder.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Transforms raw log events into LLM-readable conversation transcripts
+  #
+  # TranscriptBuilder converts the structured event log from swarm execution
+  # into a human/LLM-readable format suitable for reflection, analysis, or
+  # memory creation.
+  #
+  # @example Basic usage
+  #   transcript = TranscriptBuilder.build(result.logs)
+  #   # => "USER: Help me with CORS\n\nAGENT [assistant]: ..."
+  #
+  # @example Filter by agents
+  #   transcript = TranscriptBuilder.build(result.logs, agents: [:backend, :database])
+  #
+  # @example Custom options
+  #   transcript = TranscriptBuilder.build(
+  #     result.logs,
+  #     include_tool_results: true,
+  #     max_result_length: 1000,
+  #     include_thinking: false
+  #   )
+  class TranscriptBuilder
+    # Default maximum length for tool result content
+    DEFAULT_MAX_RESULT_LENGTH = 500
+
+    # Default maximum length for tool arguments
+    DEFAULT_MAX_ARGS_LENGTH = 200
+
+    class << self
+      # Build a transcript from log events
+      #
+      # @param logs [Array<Hash>] Array of log events from Result#logs
+      # @param agents [Array<Symbol>, nil] Filter to specific agents (nil = all)
+      # @param include_tool_results [Boolean] Include tool execution results (default: true)
+      # @param include_thinking [Boolean] Include agent_step content/thinking (default: false)
+      # @param max_result_length [Integer] Maximum characters for tool results
+      # @param max_args_length [Integer] Maximum characters for tool arguments
+      # @return [String] Formatted transcript
+      def build(logs, agents: nil, include_tool_results: true, include_thinking: false,
+        max_result_length: DEFAULT_MAX_RESULT_LENGTH, max_args_length: DEFAULT_MAX_ARGS_LENGTH)
+        new(
+          logs,
+          agents: agents,
+          include_tool_results: include_tool_results,
+          include_thinking: include_thinking,
+          max_result_length: max_result_length,
+          max_args_length: max_args_length,
+        ).build
+      end
+    end
+
+    # Initialize a new TranscriptBuilder
+    #
+    # @param logs [Array<Hash>] Array of log events
+    # @param agents [Array<Symbol>, nil] Filter to specific agents
+    # @param include_tool_results [Boolean] Include tool execution results
+    # @param include_thinking [Boolean] Include agent_step content
+    # @param max_result_length [Integer] Maximum characters for tool results
+    # @param max_args_length [Integer] Maximum characters for tool arguments
+    def initialize(logs, agents: nil, include_tool_results: true, include_thinking: false,
+      max_result_length: DEFAULT_MAX_RESULT_LENGTH, max_args_length: DEFAULT_MAX_ARGS_LENGTH)
+      @logs = logs || []
+      @agents = normalize_agents(agents)
+      @include_tool_results = include_tool_results
+      @include_thinking = include_thinking
+      @max_result_length = max_result_length
+      @max_args_length = max_args_length
+    end
+
+    # Build the transcript
+    #
+    # @return [String] Formatted transcript
+    def build
+      @logs
+        .filter_map { |event| format_event(event) }
+        .join("\n\n")
+    end
+
+    private
+
+    # Normalize agent filter to array of symbols
+    #
+    # @param agents [Array, Symbol, String, nil] Agent filter input
+    # @return [Array<Symbol>, nil] Normalized agent list or nil for all
+    def normalize_agents(agents)
+      return if agents.nil? || (agents.is_a?(Array) && agents.empty?)
+
+      Array(agents).map(&:to_sym)
+    end
+
+    # Check if event passes agent filter
+    #
+    # @param event [Hash] Log event
+    # @return [Boolean] True if event should be included
+    def passes_agent_filter?(event)
+      return true if @agents.nil?
+
+      agent = event[:agent] || event["agent"]
+      return true if agent.nil? # Include events without agent (like swarm_start)
+
+      @agents.include?(agent.to_sym)
+    end
+
+    # Format a single event into transcript text
+    #
+    # @param event [Hash] Log event
+    # @return [String, nil] Formatted text or nil to skip
+    def format_event(event)
+      return unless passes_agent_filter?(event)
+
+      type = event[:type] || event["type"]
+
+      case type
+      when "user_prompt"
+        format_user_prompt(event)
+      when "agent_step"
+        format_agent_step(event)
+      when "agent_stop"
+        format_agent_stop(event)
+      when "tool_call"
+        format_tool_call(event)
+      when "tool_result"
+        format_tool_result(event)
+      when "pre_delegation", "delegation_start"
+        format_delegation_start(event)
+      when "post_delegation", "delegation_complete"
+        format_delegation_complete(event)
+      end
+    end
+
+    # Format user_prompt event
+    #
+    # @param event [Hash] Event data
+    # @return [String, nil] Formatted text
+    def format_user_prompt(event)
+      prompt = event[:prompt] || event["prompt"]
+      return if prompt.nil? || prompt.to_s.strip.empty?
+
+      agent = event[:agent] || event["agent"]
+      source = event[:source] || event["source"] || "user"
+
+      # Show source if it's a delegation or system message
+      prefix = case source.to_s
+      when "delegation"
+        "DELEGATION REQUEST"
+      when "system"
+        "SYSTEM"
+      else
+        "USER"
+      end
+
+      if agent && source.to_s != "user"
+        "#{prefix} → [#{agent}]: #{prompt}"
+      else
+        "#{prefix}: #{prompt}"
+      end
+    end
+
+    # Format agent_step event (intermediate response with tool calls)
+    #
+    # @param event [Hash] Event data
+    # @return [String, nil] Formatted text
+    def format_agent_step(event)
+      return unless @include_thinking
+
+      content = event[:content] || event["content"]
+      return if content.nil? || content.to_s.strip.empty?
+
+      agent = event[:agent] || event["agent"]
+      "AGENT [#{agent}] (thinking): #{content}"
+    end
+
+    # Format agent_stop event (final response)
+    #
+    # @param event [Hash] Event data
+    # @return [String, nil] Formatted text
+    def format_agent_stop(event)
+      content = event[:content] || event["content"]
+      return if content.nil? || content.to_s.strip.empty?
+
+      agent = event[:agent] || event["agent"]
+      "AGENT [#{agent}]: #{content}"
+    end
+
+    # Format tool_call event
+    #
+    # @param event [Hash] Event data
+    # @return [String] Formatted text
+    def format_tool_call(event)
+      tool = event[:tool] || event["tool"] || event[:tool_name] || event["tool_name"]
+      agent = event[:agent] || event["agent"]
+      arguments = event[:arguments] || event["arguments"]
+
+      args_str = format_arguments(arguments)
+      "TOOL [#{agent}] → #{tool}(#{args_str})"
+    end
+
+    # Format tool_result event
+    #
+    # @param event [Hash] Event data
+    # @return [String, nil] Formatted text
+    def format_tool_result(event)
+      return unless @include_tool_results
+
+      tool = event[:tool] || event["tool"] || event[:tool_name] || event["tool_name"]
+      result = event[:result] || event["result"]
+      # Use key existence check since false || nil would lose the false value
+      success = event.key?(:success) ? event[:success] : event["success"]
+
+      # Handle RubyLLM::ToolResult objects
+      result_content = if result.respond_to?(:content)
+        result.content
+      else
+        result.to_s
+      end
+
+      truncated = truncate(result_content, @max_result_length)
+
+      status = success == false ? " [FAILED]" : ""
+      "RESULT [#{tool}]#{status}: #{truncated}"
+    end
+
+    # Format delegation_start event
+    #
+    # @param event [Hash] Event data
+    # @return [String, nil] Formatted text
+    def format_delegation_start(event)
+      from = event[:from_agent] || event["from_agent"] || event[:agent] || event["agent"]
+      to = event[:to_agent] || event["to_agent"]
+      task = event[:task] || event["task"] || event[:message] || event["message"]
+
+      return unless to
+
+      task_preview = truncate(task.to_s, 200)
+      "DELEGATE: #{from} → #{to}: #{task_preview}"
+    end
+
+    # Format delegation_complete event
+    #
+    # @param event [Hash] Event data
+    # @return [String, nil] Formatted text
+    def format_delegation_complete(event)
+      from = event[:from_agent] || event["from_agent"] || event[:agent] || event["agent"]
+      to = event[:to_agent] || event["to_agent"]
+
+      return unless to
+
+      "DELEGATE COMPLETE: #{to} → #{from}"
+    end
+
+    # Format tool arguments for display
+    #
+    # @param arguments [Hash, String, nil] Tool arguments
+    # @return [String] Formatted arguments
+    def format_arguments(arguments)
+      return "{}" if arguments.nil?
+
+      str = arguments.is_a?(String) ? arguments : arguments.to_json
+      truncate(str, @max_args_length)
+    end
+
+    # Truncate text to maximum length with ellipsis
+    #
+    # @param text [String, nil] Text to truncate
+    # @param max [Integer] Maximum length
+    # @return [String] Truncated text
+    def truncate(text, max)
+      return "" if text.nil?
+
+      str = text.to_s
+      return str if str.length <= max
+
+      "#{str[0...max]}..."
+    end
+  end
+end

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.5.1"
+  VERSION = "2.5.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.5.1
+  version: 2.5.2
 platform: ruby
 authors:
 - Paulo Arruda
@@ -234,6 +234,7 @@ files:
 - lib/swarm_sdk/tools/todo_write.rb
 - lib/swarm_sdk/tools/web_fetch.rb
 - lib/swarm_sdk/tools/write.rb
+- lib/swarm_sdk/transcript_builder.rb
 - lib/swarm_sdk/utils.rb
 - lib/swarm_sdk/validation_result.rb
 - lib/swarm_sdk/version.rb