swarm_sdk 2.7.1 → 2.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce0f1a16b02f241a7f0ce7cfb2ffcee3c3c073dc70066a1dfa7f9e8a90de566a
-  data.tar.gz: 1ecf98d40c8bc3f4ccc5ff588fa4bf75a1087e0229de6afbeae342bac4679a27
+  metadata.gz: 9d0b44f3edf346a30b0442027c9ca2e8cf06e3e2c074c89f483c0eab0964a592
+  data.tar.gz: b7c690fd69303078c70c252a09a9e4f46b63f0f4a438a3fc9188cacc30e44109
 SHA512:
-  metadata.gz: b083185a7ff36cd0fde32e3bca97427857917e40a9a2b6ca0fdfbb4dc42dd593edb7306bf1ab7bf854037a034d0982fc477e5a6ec3049361b65fc81900b1b647
-  data.tar.gz: 57b97e291d2047e658b6a31af6d047af78217ba73fd7e39c83103b5003808d9fbd9d6c6b1218f199e3f1f7f5f0b9f917dde563a25122ce7c8a6e73a0babd79b2
+  metadata.gz: e0881dd9ae7fefc423bdbad4d56d535be627b622f2301eae1c12858d8198f7f55472198f6413535bccd768b17368233ac24ca5d2ab58417cbee9a7a68e8cdc79
+  data.tar.gz: a2af0ea8bf741a017196ce6db4d17a7b1bdc9fed2e517c35ae17c2336b950d25300186970f15b746fbc7dfd5c2679a53b9596d9f675c5a44089dc10672d542a0

data/lib/swarm_sdk/agent/builder.rb

@@ -275,6 +275,10 @@ module SwarmSDK
       #                backend: "GetBackendHelp",
       #                :qa
       #
+      # @example With delegation options (preserve_context controls context persistence)
+      #   delegates_to :frontend,
+      #                { agent: :backend, tool_name: "AskBackend", preserve_context: false }
+      #
       # @param agent_names_and_options [Array<Symbol, Hash>] Agent names and/or hash with custom tool names
       # @return [void]
       def delegates_to(*agent_names_and_options)
@@ -282,11 +286,20 @@ module SwarmSDK
           case item
           when Symbol, String
             # Simple format: :frontend
-            @delegates_to << { agent: item.to_sym, tool_name: nil }
+            @delegates_to << { agent: item.to_sym, tool_name: nil, preserve_context: true }
           when Hash
-            # Hash format: { frontend: "AskFrontend", backend: nil }
-            item.each do |agent, tool_name|
-              @delegates_to << { agent: agent.to_sym, tool_name: tool_name }
+            if item.key?(:agent)
+              # Full config format: { agent: :backend, tool_name: "Custom", preserve_context: false }
+              @delegates_to << {
+                agent: item[:agent].to_sym,
+                tool_name: item[:tool_name],
+                preserve_context: item.fetch(:preserve_context, true),
+              }
+            else
+              # Hash format: { frontend: "AskFrontend", backend: nil }
+              item.each do |agent, tool_name|
+                @delegates_to << { agent: agent.to_sym, tool_name: tool_name, preserve_context: true }
+              end
             end
           else
             raise ConfigurationError, "delegates_to accepts Symbols or Hashes, got #{item.class}"

data/lib/swarm_sdk/agent/chat.rb

@@ -207,6 +207,13 @@ module SwarmSDK
       # --- SwarmSDK Abstraction API ---
       # These methods provide SwarmSDK-specific semantics without exposing RubyLLM internals
 
+      # Check if streaming is enabled for this agent
+      #
+      # @return [Boolean] true if streaming is enabled
+      def streaming_enabled?
+        @streaming_enabled
+      end
+
       # Model information
       def model_id
         @llm_chat.model.id
@@ -681,6 +688,7 @@ module SwarmSDK
               if @streaming_enabled
                 # Reset chunk type tracking for new streaming request
                 @last_chunk_type = nil
+
                 @llm_chat.complete(**options) do |chunk|
                   emit_content_chunk(chunk)
                 end

data/lib/swarm_sdk/agent/chat_helpers/context_tracker.rb

@@ -82,6 +82,88 @@ module SwarmSDK
 
         private
 
+        # Format citations for appending to response content
+        #
+        # Creates a markdown-formatted citations section with numbered links.
+        #
+        # @param citations [Array<String>] Array of citation URLs
+        # @return [String] Formatted citations section
+        def format_citations(citations)
+          return "" if citations.nil? || citations.empty?
+
+          formatted = "\n\n# Citations\n"
+          citations.each_with_index do |citation, index|
+            formatted += "- [#{index + 1}] #{citation}\n"
+          end
+          formatted
+        end
+
+        # Emit citations as a content_chunk event
+        #
+        # @param formatted_citations [String] Formatted citations text
+        # @param model_id [String] Model identifier
+        # @return [void]
+        def emit_citations_chunk(formatted_citations, model_id)
+          LogStream.emit(
+            type: "content_chunk",
+            agent: @agent_context.name,
+            chunk_type: "citations",
+            content: formatted_citations,
+            tool_calls: nil,
+            model: model_id,
+          )
+        rescue StandardError => e
+          RubyLLM.logger.debug("SwarmSDK: Failed to emit citations chunk: #{e.message}")
+        end
+
+        # Extract citations and search results from an assistant message
+        #
+        # These fields are provided by some LLM providers (e.g., Perplexity's sonar models)
+        # when the model performs web search or cites sources.
+        #
+        # @param message [RubyLLM::Message] Assistant message with potential citations
+        # @return [Hash] Citations and search results (empty if not present)
+        def extract_citations_and_search(message)
+          return {} unless message.raw&.body
+
+          body = message.raw.body
+
+          # For streaming responses, body might be empty - check Fiber-local
+          # (set by LLMInstrumentationMiddleware with accumulated SSE chunks)
+          if body.is_a?(String) && body.empty?
+            fiber_body = Fiber[:last_sse_body]
+            body = fiber_body if fiber_body
+          end
+
+          return {} unless body
+
+          # Handle SSE streaming responses (body is a string starting with "data:")
+          if body.is_a?(String) && body.start_with?("data:")
+            # Parse the LAST SSE event which contains citations
+            last_data_line = body.split("\n").reverse.find { |l| l.start_with?("data:") && !l.include?("[DONE]") && !l.include?("message_stop") }
+            if last_data_line
+              body = JSON.parse(last_data_line.sub(/^data:\s*/, ""))
+            end
+          elsif body.is_a?(String)
+            # Regular JSON string response
+            body = JSON.parse(body)
+          end
+
+          # Handle Faraday::Response objects (has .body method)
+          body = body.body if body.respond_to?(:body) && !body.is_a?(Hash)
+
+          return {} unless body.is_a?(Hash)
+
+          result = {}
+          result[:citations] = body["citations"] if body["citations"]
+          result[:search_results] = body["search_results"] if body["search_results"]
+          result
+        rescue StandardError => e
+          # Includes JSON::ParserError and other parsing errors
+          RubyLLM.logger.debug("SwarmSDK: Failed to extract citations: #{e.message}")
+          {}
+        end
+
         # Extract usage information from an assistant message
         #
         # @param message [RubyLLM::Message] Assistant message with usage data
@@ -202,6 +284,7 @@ module SwarmSDK
           return unless @chat.hook_executor
 
           usage_info = extract_usage_info(message)
+          citations_data = extract_citations_and_search(message)
 
           context = Hooks::Context.new(
             event: :agent_step,
@@ -213,9 +296,11 @@ module SwarmSDK
               tool_calls: format_tool_calls(message.tool_calls),
               finish_reason: "tool_calls",
               usage: usage_info,
+              citations: citations_data[:citations],
+              search_results: citations_data[:search_results],
               tool_executions: tool_executions.empty? ? nil : tool_executions,
               timestamp: Time.now.utc.iso8601,
-            },
+            }.compact,
           )
 
           agent_hooks = @chat.hook_agent_hooks[:agent_step] || []
@@ -238,6 +323,22 @@ module SwarmSDK
           return unless @chat.hook_executor
 
           usage_info = extract_usage_info(message)
+          citations_data = extract_citations_and_search(message)
+
+          # Format content with citations appended
+          content_with_citations = message.content
+          if citations_data[:citations] && !citations_data[:citations].empty?
+            formatted_citations = format_citations(citations_data[:citations])
+            content_with_citations = message.content + formatted_citations
+
+            # Also modify the original message for Result.content
+            message.content = content_with_citations
+
+            # Emit citations chunk if streaming is enabled
+            if @chat.streaming_enabled?
+              emit_citations_chunk(formatted_citations, message.model_id)
+            end
+          end
 
           # Use override if set (e.g., "finish_agent"), otherwise default to "stop"
           finish_reason = @finish_reason_override || "stop"
@@ -249,13 +350,15 @@ module SwarmSDK
             swarm: @chat.hook_swarm,
             metadata: {
               model: message.model_id,
-              content: message.content,
+              content: content_with_citations, # Content with citations appended
               tool_calls: nil, # Final response has no tool calls
               finish_reason: finish_reason,
               usage: usage_info,
+              citations: citations_data[:citations],
+              search_results: citations_data[:search_results],
               tool_executions: tool_executions.empty? ? nil : tool_executions,
               timestamp: Time.now.utc.iso8601,
-            },
+            }.compact,
           )
 
           agent_hooks = @chat.hook_agent_hooks[:agent_stop] || []

data/lib/swarm_sdk/agent/chat_helpers/instrumentation.rb

@@ -13,10 +13,15 @@ module SwarmSDK
         #
         # @return [void]
         def inject_llm_instrumentation
+          puts "=== inject_llm_instrumentation called ===" if ENV["DEBUG_CITATIONS"]
           return unless @provider
 
+          puts "=== Has provider ===" if ENV["DEBUG_CITATIONS"]
+
           faraday_conn = @provider.connection&.connection
           return unless faraday_conn
+
+          puts "=== Has faraday connection ===" if ENV["DEBUG_CITATIONS"]
           return if @llm_instrumentation_injected
 
           provider_name = @provider.class.name.split("::").last.downcase
@@ -31,8 +36,10 @@ module SwarmSDK
 
           @llm_instrumentation_injected = true
 
+          puts "=== MIDDLEWARE INJECTED ===" if ENV["DEBUG_CITATIONS"]
           RubyLLM.logger.debug("SwarmSDK: Injected LLM instrumentation middleware for agent #{@agent_name}")
         rescue StandardError => e
+          puts "=== MIDDLEWARE INJECTION ERROR: #{e.message} ===" if ENV["DEBUG_CITATIONS"]
           LogStream.emit_error(e, source: "instrumentation", context: "inject_middleware", agent: @agent_name)
           RubyLLM.logger.debug("SwarmSDK: Failed to inject LLM instrumentation: #{e.message}")
         end

data/lib/swarm_sdk/agent/definition.rb

@@ -325,16 +325,20 @@ module SwarmSDK
           delegation_config.flat_map do |item|
             case item
             when Symbol, String
-              # Simple format: :frontend → {agent: :frontend, tool_name: nil}
-              [{ agent: item.to_sym, tool_name: nil }]
+              # Simple format: :frontend → {agent: :frontend, tool_name: nil, preserve_context: true}
+              [{ agent: item.to_sym, tool_name: nil, preserve_context: true }]
             when Hash
               # Could be already normalized or hash format
               if item.key?(:agent)
-                # Already normalized: {agent: :frontend, tool_name: "Custom"}
-                [item]
+                # Already normalized: {agent: :frontend, tool_name: "Custom", preserve_context: false}
+                [{
+                  agent: item[:agent].to_sym,
+                  tool_name: item[:tool_name],
+                  preserve_context: item.fetch(:preserve_context, true),
+                }]
               else
                 # Hash format in array: {frontend: "AskFrontend"}
-                item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+                item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name, preserve_context: true } }
               end
             else
               raise ConfigurationError, "Invalid delegation config format: #{item.inspect}"
@@ -343,7 +347,7 @@ module SwarmSDK
         elsif delegation_config.is_a?(Hash)
           # Hash format: {frontend: "AskFrontend", backend: nil}
           delegation_config.map do |agent, tool_name|
-            { agent: agent.to_sym, tool_name: tool_name }
+            { agent: agent.to_sym, tool_name: tool_name, preserve_context: true }
           end
         else
           raise ConfigurationError, "delegates_to must be an Array or Hash, got #{delegation_config.class}"

data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb

@@ -39,8 +39,6 @@ module SwarmSDK
         emit_request_event(env, start_time)
 
         # Wrap existing on_data to capture raw SSE chunks for streaming
-        # This allows us to capture the full streaming response for instrumentation
-        # Check if env.request exists and has on_data (only set for streaming requests)
         if env.request&.on_data
           original_on_data = env.request.on_data
           env.request.on_data = proc do |chunk, bytes, response_env|
@@ -64,6 +62,11 @@ module SwarmSDK
             response_env.body
           end
 
+          # Store SSE body in Fiber-local for citation extraction
+          # This allows append_citations_to_content to access the full SSE body
+          # even though response.body is empty for streaming responses
+          Fiber[:last_sse_body] = raw_body if accumulated_raw_chunks.any?
+
           # Emit response event
           emit_response_event(response_env, start_time, end_time, duration, raw_body)
         end

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -91,8 +91,9 @@ module SwarmSDK
       # @param agent_name [Symbol] Name of the delegating agent
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating
       # @param custom_tool_name [String, nil] Optional custom tool name (overrides auto-generated name)
+      # @param preserve_context [Boolean] Whether to preserve conversation context between delegations (default: true)
       # @return [Tools::Delegate] Delegation tool
-      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:, delegating_chat: nil, custom_tool_name: nil)
+      def create_delegation_tool(name:, description:, delegate_chat:, agent_name:, delegating_chat: nil, custom_tool_name: nil, preserve_context: true)
         Tools::Delegate.new(
           delegate_name: name,
           delegate_description: description,
@@ -101,6 +102,7 @@ module SwarmSDK
           swarm: @swarm,
           delegating_chat: delegating_chat,
           custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
         )
       end
 
@@ -219,7 +221,7 @@ module SwarmSDK
       #
       # @param delegator_name [Symbol, String] Name of the agent doing the delegating
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
-      # @param delegation_config [Hash] Delegation configuration with :agent and :tool_name keys
+      # @param delegation_config [Hash] Delegation configuration with :agent, :tool_name, and :preserve_context keys
       # @param tool_configurator [ToolConfigurator] Tool configuration helper
       # @param create_nested_instances [Boolean] Whether to create new instances for nested delegation
       # @return [void]
@@ -227,10 +229,11 @@ module SwarmSDK
         delegate_name_sym = delegation_config[:agent]
         delegate_name_str = delegate_name_sym.to_s
         custom_tool_name = delegation_config[:tool_name]
+        preserve_context = delegation_config.fetch(:preserve_context, true)
 
         # Check if target is a registered swarm
         if @swarm.swarm_registry&.registered?(delegate_name_str)
-          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str, custom_tool_name)
+          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str, custom_tool_name, preserve_context)
         elsif @swarm.agent_definitions.key?(delegate_name_sym)
           wire_agent_delegation(
             delegator_name: delegator_name,
@@ -239,6 +242,7 @@ module SwarmSDK
             custom_tool_name: custom_tool_name,
             tool_configurator: tool_configurator,
             create_nested_instances: create_nested_instances,
+            preserve_context: preserve_context,
           )
         else
           raise ConfigurationError,
@@ -252,8 +256,9 @@ module SwarmSDK
       # @param delegator_chat [Agent::Chat] Chat instance of the delegator
       # @param swarm_name [String] Name of the registered swarm
       # @param custom_tool_name [String, nil] Optional custom tool name
+      # @param preserve_context [Boolean] Whether to preserve context between delegations
       # @return [void]
-      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name, custom_tool_name)
+      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name, custom_tool_name, preserve_context)
         tool = create_delegation_tool(
           name: swarm_name,
           description: "External swarm: #{swarm_name}",
@@ -261,13 +266,14 @@ module SwarmSDK
           agent_name: delegator_name,
           delegating_chat: delegator_chat,
           custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
         )
 
         # Register in tool registry (Plan 025)
         delegator_chat.tool_registry.register(
           tool,
           source: :delegation,
-          metadata: { delegate_name: swarm_name, delegation_type: :swarm },
+          metadata: { delegate_name: swarm_name, delegation_type: :swarm, preserve_context: preserve_context },
         )
       end
 
@@ -282,8 +288,9 @@ module SwarmSDK
       # @param custom_tool_name [String, nil] Optional custom tool name
       # @param tool_configurator [ToolConfigurator] Tool configuration helper
       # @param create_nested_instances [Boolean] Whether to create new instances if not found
+      # @param preserve_context [Boolean] Whether to preserve context between delegations
       # @return [void]
-      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, tool_configurator:, create_nested_instances:)
+      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, custom_tool_name:, tool_configurator:, create_nested_instances:, preserve_context:)
         delegate_definition = @swarm.agent_definitions[delegate_name_sym]
 
         # Determine which chat instance to use
@@ -316,6 +323,7 @@ module SwarmSDK
           agent_name: delegator_name,
           delegating_chat: delegator_chat,
           custom_tool_name: custom_tool_name,
+          preserve_context: preserve_context,
         )
 
         # Register in tool registry (Plan 025)
@@ -325,6 +333,7 @@ module SwarmSDK
           metadata: {
             delegate_name: delegate_name_sym,
             delegation_mode: delegate_definition.shared_across_delegations ? :shared : :isolated,
+            preserve_context: preserve_context,
           },
         )
       end

data/lib/swarm_sdk/swarm/logging_callbacks.rb

@@ -238,7 +238,14 @@ module SwarmSDK
         return unless LogStream.emitter
 
         metadata_without_duplicates = context.metadata.except(
-          :model, :content, :tool_calls, :finish_reason, :usage, :tool_executions
+          :model,
+          :content,
+          :tool_calls,
+          :finish_reason,
+          :usage,
+          :tool_executions,
+          :citations,
+          :search_results,
         )
 
         LogStream.emit(
@@ -251,6 +258,8 @@ module SwarmSDK
           tool_calls: context.metadata[:tool_calls],
           finish_reason: context.metadata[:finish_reason],
           usage: context.metadata[:usage],
+          citations: context.metadata[:citations],
+          search_results: context.metadata[:search_results],
           tool_executions: context.metadata[:tool_executions],
           metadata: metadata_without_duplicates,
         )
@@ -261,7 +270,14 @@ module SwarmSDK
         return unless LogStream.emitter
 
         metadata_without_duplicates = context.metadata.except(
-          :model, :content, :tool_calls, :finish_reason, :usage, :tool_executions
+          :model,
+          :content,
+          :tool_calls,
+          :finish_reason,
+          :usage,
+          :tool_executions,
+          :citations,
+          :search_results,
         )
 
         LogStream.emit(
@@ -274,6 +290,8 @@ module SwarmSDK
           tool_calls: context.metadata[:tool_calls],
           finish_reason: context.metadata[:finish_reason],
           usage: context.metadata[:usage],
+          citations: context.metadata[:citations],
+          search_results: context.metadata[:search_results],
           tool_executions: context.metadata[:tool_executions],
           metadata: metadata_without_duplicates,
         )

data/lib/swarm_sdk/tools/delegate.rb

@@ -37,7 +37,7 @@ module SwarmSDK
         end
       end
 
-      attr_reader :delegate_name, :delegate_target, :tool_name
+      attr_reader :delegate_name, :delegate_target, :tool_name, :preserve_context
 
       # Initialize a delegation tool
       #
@@ -48,6 +48,7 @@ module SwarmSDK
       # @param swarm [Swarm] The swarm instance (provides hook_registry, delegation_call_stack, swarm_registry)
       # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating (for accessing hooks)
       # @param custom_tool_name [String, nil] Optional custom tool name (overrides auto-generated name)
+      # @param preserve_context [Boolean] Whether to preserve conversation context between delegations (default: true)
       def initialize(
         delegate_name:,
         delegate_description:,
@@ -55,7 +56,8 @@ module SwarmSDK
         agent_name:,
         swarm:,
         delegating_chat: nil,
-        custom_tool_name: nil
+        custom_tool_name: nil,
+        preserve_context: true
       )
         super()
 
@@ -65,6 +67,7 @@ module SwarmSDK
         @agent_name = agent_name
         @swarm = swarm
         @delegating_chat = delegating_chat
+        @preserve_context = preserve_context
 
         # Use custom tool name if provided, otherwise generate using canonical method
         @tool_name = custom_tool_name || self.class.tool_name_for(delegate_name)
@@ -224,6 +227,9 @@ module SwarmSDK
         # Push delegate target onto call stack to track delegation chain
         call_stack.push(@delegate_target)
         begin
+          # Clear conversation if preserve_context is false
+          @delegate_chat.clear_conversation unless @preserve_context
+
           response = @delegate_chat.ask(message, source: "delegation")
           response.content
         ensure

data/lib/swarm_sdk/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.7.1
+  version: 2.7.3
 platform: ruby
 authors:
 - Paulo Arruda