swarm_sdk 2.7.1 → 2.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce0f1a16b02f241a7f0ce7cfb2ffcee3c3c073dc70066a1dfa7f9e8a90de566a
-  data.tar.gz: 1ecf98d40c8bc3f4ccc5ff588fa4bf75a1087e0229de6afbeae342bac4679a27
+  metadata.gz: 204f0173ac046d5eae63cf3ddca318e3ab0e76a88661e7f4a106d5079a68ee63
+  data.tar.gz: 515a43fac5824b6fab886901449ef808288e8e5e2beaacd02502c0e337a3d98f
 SHA512:
-  metadata.gz: b083185a7ff36cd0fde32e3bca97427857917e40a9a2b6ca0fdfbb4dc42dd593edb7306bf1ab7bf854037a034d0982fc477e5a6ec3049361b65fc81900b1b647
-  data.tar.gz: 57b97e291d2047e658b6a31af6d047af78217ba73fd7e39c83103b5003808d9fbd9d6c6b1218f199e3f1f7f5f0b9f917dde563a25122ce7c8a6e73a0babd79b2
+  metadata.gz: 94b2a3d8ee2d4cd61ec45a075b5e9cc370d992e47ae2da7e478abe7aa7f81ebaf2c0cd3571072ed02fdfac1eefc07c8eb5bcfd65aefa46c0cc60298b7e2b30ae
+  data.tar.gz: 7e527394023723bfabd8fa18c1696b0dc10b14499fe4c2ba3db46e3c8518158d1d5de8553c41d2139eba3c800f17a739c86503a7366c470ccb9e616446695510

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/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/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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.7.1"
+  VERSION = "2.7.2"
 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.2
 platform: ruby
 authors:
 - Paulo Arruda