swarm_memory 2.1.2 → 2.1.4

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    module ChatHelpers
+      # LLM instrumentation for API request/response logging
+      #
+      # Extracted from Chat to reduce class size and centralize observability logic.
+      module Instrumentation
+        private
+
+        # Inject LLM instrumentation middleware for API request/response logging
+        #
+        # @return [void]
+        def inject_llm_instrumentation
+          return unless @provider
+
+          faraday_conn = @provider.connection&.connection
+          return unless faraday_conn
+          return if @llm_instrumentation_injected
+
+          provider_name = @provider.class.name.split("::").last.downcase
+
+          faraday_conn.builder.insert(
+            0,
+            SwarmSDK::Agent::LLMInstrumentationMiddleware,
+            on_request: method(:handle_llm_api_request),
+            on_response: method(:handle_llm_api_response),
+            provider_name: provider_name,
+          )
+
+          @llm_instrumentation_injected = true
+
+          RubyLLM.logger.debug("SwarmSDK: Injected LLM instrumentation middleware for agent #{@agent_name}")
+        rescue StandardError => e
+          LogStream.emit_error(e, source: "instrumentation", context: "inject_middleware", agent: @agent_name)
+          RubyLLM.logger.debug("SwarmSDK: Failed to inject LLM instrumentation: #{e.message}")
+        end
+
+        # Handle LLM API request event
+        #
+        # @param data [Hash] Request data from middleware
+        def handle_llm_api_request(data)
+          return unless LogStream.emitter
+
+          LogStream.emit(
+            type: "llm_api_request",
+            agent: @agent_name,
+            swarm_id: @agent_context&.swarm_id,
+            parent_swarm_id: @agent_context&.parent_swarm_id,
+            **data,
+          )
+        rescue StandardError => e
+          LogStream.emit_error(e, source: "instrumentation", context: "emit_llm_api_request", agent: @agent_name)
+          RubyLLM.logger.debug("SwarmSDK: Error emitting llm_api_request event: #{e.message}")
+        end
+
+        # Handle LLM API response event
+        #
+        # @param data [Hash] Response data from middleware
+        def handle_llm_api_response(data)
+          return unless LogStream.emitter
+
+          LogStream.emit(
+            type: "llm_api_response",
+            agent: @agent_name,
+            swarm_id: @agent_context&.swarm_id,
+            parent_swarm_id: @agent_context&.parent_swarm_id,
+            **data,
+          )
+        rescue StandardError => e
+          LogStream.emit_error(e, source: "instrumentation", context: "emit_llm_api_response", agent: @agent_name)
+          RubyLLM.logger.debug("SwarmSDK: Error emitting llm_api_response event: #{e.message}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    module ChatHelpers
+      # LLM configuration and provider setup
+      #
+      # Extracted from Chat to reduce class size and centralize RubyLLM setup logic.
+      module LlmConfiguration
+        private
+
+        # Create the internal RubyLLM::Chat instance
+        #
+        # @return [RubyLLM::Chat] Chat instance
+        def create_llm_chat(model_id:, provider_name:, base_url:, api_version:, timeout:, assume_model_exists:, max_concurrent_tools:)
+          chat_options = build_chat_options(max_concurrent_tools)
+
+          chat = instantiate_chat(
+            model_id: model_id,
+            provider_name: provider_name,
+            base_url: base_url,
+            timeout: timeout,
+            assume_model_exists: assume_model_exists,
+            chat_options: chat_options,
+          )
+
+          # Enable RubyLLM's native Responses API if configured
+          enable_responses_api(chat, api_version, base_url) if api_version == "v1/responses"
+
+          chat
+        end
+
+        # Build chat options hash
+        #
+        # @param max_concurrent_tools [Integer, nil] Max concurrent tool executions
+        # @return [Hash] Chat options
+        def build_chat_options(max_concurrent_tools)
+          return {} unless max_concurrent_tools
+
+          {
+            tool_concurrency: :async,
+            max_concurrency: max_concurrent_tools,
+          }
+        end
+
+        # Instantiate RubyLLM::Chat with appropriate configuration
+        #
+        # @return [RubyLLM::Chat] Chat instance
+        def instantiate_chat(model_id:, provider_name:, base_url:, timeout:, assume_model_exists:, chat_options:)
+          if base_url || timeout != Defaults::Timeouts::AGENT_REQUEST_SECONDS
+            instantiate_with_custom_context(
+              model_id: model_id,
+              provider_name: provider_name,
+              base_url: base_url,
+              timeout: timeout,
+              assume_model_exists: assume_model_exists,
+              chat_options: chat_options,
+            )
+          elsif provider_name
+            instantiate_with_provider(
+              model_id: model_id,
+              provider_name: provider_name,
+              assume_model_exists: assume_model_exists,
+              chat_options: chat_options,
+            )
+          else
+            instantiate_default(
+              model_id: model_id,
+              assume_model_exists: assume_model_exists,
+              chat_options: chat_options,
+            )
+          end
+        end
+
+        # Instantiate chat with custom context (base_url/timeout overrides)
+        def instantiate_with_custom_context(model_id:, provider_name:, base_url:, timeout:, assume_model_exists:, chat_options:)
+          raise ArgumentError, "Provider must be specified when base_url is set" if base_url && !provider_name
+
+          context = build_custom_context(provider: provider_name, base_url: base_url, timeout: timeout)
+          assume_model_exists = base_url ? true : false if assume_model_exists.nil?
+
+          RubyLLM.chat(
+            model: model_id,
+            provider: provider_name,
+            assume_model_exists: assume_model_exists,
+            context: context,
+            **chat_options,
+          )
+        end
+
+        # Instantiate chat with explicit provider
+        def instantiate_with_provider(model_id:, provider_name:, assume_model_exists:, chat_options:)
+          assume_model_exists = false if assume_model_exists.nil?
+
+          RubyLLM.chat(
+            model: model_id,
+            provider: provider_name,
+            assume_model_exists: assume_model_exists,
+            **chat_options,
+          )
+        end
+
+        # Instantiate chat with default configuration
+        def instantiate_default(model_id:, assume_model_exists:, chat_options:)
+          assume_model_exists = false if assume_model_exists.nil?
+
+          RubyLLM.chat(
+            model: model_id,
+            assume_model_exists: assume_model_exists,
+            **chat_options,
+          )
+        end
+
+        # Build custom RubyLLM context for base_url/timeout overrides
+        #
+        # @return [RubyLLM::Context] Configured context
+        def build_custom_context(provider:, base_url:, timeout:)
+          RubyLLM.context do |config|
+            config.request_timeout = timeout
+
+            configure_provider_base_url(config, provider, base_url) if base_url
+          end
+        end
+
+        # Configure provider-specific base URL
+        def configure_provider_base_url(config, provider, base_url)
+          case provider.to_s
+          when "openai", "deepseek", "perplexity", "mistral", "openrouter"
+            config.openai_api_base = base_url
+            config.openai_api_key = ENV["OPENAI_API_KEY"] || "dummy-key-for-local"
+            config.openai_use_system_role = true
+          when "ollama"
+            config.ollama_api_base = base_url
+          when "gpustack"
+            config.gpustack_api_base = base_url
+            config.gpustack_api_key = ENV["GPUSTACK_API_KEY"] || "dummy-key"
+          else
+            raise ArgumentError, "Provider '#{provider}' doesn't support custom base_url."
+          end
+        end
+
+        # Fetch real model info for accurate context tracking
+        #
+        # @param model_id [String] Model ID to lookup
+        def fetch_real_model_info(model_id)
+          @model_lookup_error = nil
+          @real_model_info = begin
+            RubyLLM.models.find(model_id)
+          rescue StandardError => e
+            suggestions = suggest_similar_models(model_id)
+            @model_lookup_error = {
+              model: model_id,
+              error_message: e.message,
+              suggestions: suggestions,
+            }
+            nil
+          end
+        end
+
+        # Enable RubyLLM's native Responses API on the chat instance
+        #
+        # Uses RubyLLM's built-in support for OpenAI's Responses API (v1/responses endpoint)
+        # which provides automatic stateful conversation tracking with 5-minute TTL.
+        #
+        # @param chat [RubyLLM::Chat] Chat instance to configure
+        # @param api_version [String] API version (should be "v1/responses")
+        # @param base_url [String, nil] Custom endpoint URL if any
+        def enable_responses_api(chat, api_version, base_url)
+          return unless api_version == "v1/responses"
+
+          # Warn if using custom endpoint (typically doesn't support Responses API)
+          if base_url && !base_url.include?("api.openai.com")
+            RubyLLM.logger.warn(
+              "SwarmSDK: Responses API requested but using custom endpoint #{base_url}. " \
+                "Custom endpoints typically don't support /v1/responses.",
+            )
+          end
+
+          # Enable native RubyLLM Responses API support
+          # - stateful: true enables automatic previous_response_id tracking
+          # - store: true enables server-side conversation storage
+          chat.with_responses_api(stateful: true, store: true)
+          RubyLLM.logger.debug("SwarmSDK: Enabled native Responses API support")
+        end
+
+        # Configure LLM parameters with proper temperature normalization
+        #
+        # @param params [Hash] Parameter hash
+        # @return [self]
+        def configure_parameters(params)
+          return self if params.nil? || params.empty?
+
+          if params[:temperature]
+            @llm_chat.with_temperature(params[:temperature])
+            params = params.except(:temperature)
+          end
+
+          @llm_chat.with_params(**params) if params.any?
+
+          self
+        end
+
+        # Configure custom HTTP headers for LLM requests
+        #
+        # @param headers [Hash, nil] Custom HTTP headers
+        # @return [self]
+        def configure_headers(custom_headers)
+          return self if custom_headers.nil? || custom_headers.empty?
+
+          @llm_chat.with_headers(**custom_headers)
+
+          self
+        end
+
+        # Suggest similar models when a model is not found
+        #
+        # @param query [String] Model name to search for
+        # @return [Array<RubyLLM::Model::Info>] Up to 3 similar models
+        def suggest_similar_models(query)
+          normalized_query = query.to_s.downcase.gsub(/[.\-_]/, "")
+
+          RubyLLM.models.all.select do |model_info|
+            normalized_id = model_info.id.downcase.gsub(/[.\-_]/, "")
+            normalized_id.include?(normalized_query) ||
+              model_info.name&.downcase&.gsub(/[.\-_]/, "")&.include?(normalized_query)
+          end.first(3)
+        rescue StandardError
+          []
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/agent/{chat → chat_helpers}/logging_helpers.rb

@@ -2,7 +2,7 @@
 
 module SwarmSDK
   module Agent
-    class Chat < RubyLLM::Chat
+    module ChatHelpers
       # Helper methods for logging and serialization of tool calls and results
       #
       # Responsibilities:

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    module ChatHelpers
+      # Message serialization and deserialization for snapshots
+      #
+      # Extracted from Chat to reduce class size and centralize persistence logic.
+      module Serialization
+        # Create snapshot of current conversation state
+        #
+        # @return [Hash] Serialized conversation data
+        def conversation_snapshot
+          {
+            messages: @llm_chat.messages.map { |msg| serialize_message(msg) },
+            model_id: model_id,
+            provider: model_provider,
+            timestamp: Time.now.utc.iso8601,
+          }
+        end
+
+        # Restore conversation from snapshot
+        #
+        # @param snapshot [Hash] Serialized conversation data
+        # @return [self]
+        def restore_conversation(snapshot)
+          raise ArgumentError, "Invalid snapshot: missing messages" unless snapshot[:messages]
+
+          @llm_chat.messages.clear
+          snapshot[:messages].each do |msg_data|
+            @llm_chat.messages << deserialize_message(msg_data)
+          end
+
+          self
+        end
+
+        private
+
+        # Serialize a RubyLLM::Message to a plain hash
+        #
+        # @param message [RubyLLM::Message] Message to serialize
+        # @return [Hash] Serialized message data
+        def serialize_message(message)
+          data = message.to_h
+
+          # Convert tool_calls to plain hashes (they're ToolCall objects)
+          if data[:tool_calls]
+            data[:tool_calls] = data[:tool_calls].transform_values(&:to_h)
+          end
+
+          # Handle Content objects
+          if data[:content].respond_to?(:to_h)
+            data[:content] = data[:content].to_h
+          end
+
+          data
+        end
+
+        # Deserialize a hash back to a RubyLLM::Message
+        #
+        # @param data [Hash] Serialized message data
+        # @return [RubyLLM::Message] Reconstructed message
+        def deserialize_message(data)
+          data = data.transform_keys(&:to_sym)
+
+          # Convert tool_calls back to ToolCall objects
+          if data[:tool_calls]
+            data[:tool_calls] = data[:tool_calls].transform_values do |tc_data|
+              tc_data = tc_data.transform_keys(&:to_sym)
+              RubyLLM::ToolCall.new(
+                id: tc_data[:id],
+                name: tc_data[:name],
+                arguments: tc_data[:arguments] || {},
+              )
+            end
+          end
+
+          RubyLLM::Message.new(**data)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/agent/{chat → chat_helpers}/system_reminder_injector.rb

@@ -2,7 +2,7 @@
 
 module SwarmSDK
   module Agent
-    class Chat < RubyLLM::Chat
+    module ChatHelpers
       # Handles injection of system reminders at strategic points in the conversation
       #
       # Responsibilities:
@@ -12,23 +12,6 @@ module SwarmSDK
       #
       # This class is stateless - it operates on the chat's message history.
       class SystemReminderInjector
-        # System reminder to inject BEFORE the first user message
-        BEFORE_FIRST_MESSAGE_REMINDER = <<~REMINDER.strip
-          <system-reminder>
-          As you answer the user's questions, you can use the following context:
-
-          # important-instruction-reminders
-
-          Do what has been asked; nothing more, nothing less.
-          NEVER create files unless they're absolutely necessary for achieving your goal.
-          ALWAYS prefer editing an existing file to creating a new one.
-          NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-
-          IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
-
-          </system-reminder>
-        REMINDER
-
         # System reminder to inject AFTER the first user message
         AFTER_FIRST_MESSAGE_REMINDER = <<~REMINDER.strip
           <system-reminder>Your todo list is currently empty. DO NOT mention this to the user. If this task requires multiple steps: (1) FIRST analyze the scope by searching/reading files, (2) SECOND create a COMPLETE todo list with ALL tasks before starting work, (3) THIRD execute tasks one by one. Only skip the todo list for simple single-step tasks. Do not mention this message to the user.</system-reminder>
@@ -39,8 +22,8 @@ module SwarmSDK
           <system-reminder>The TodoWrite tool hasn't been used recently. If you're working on tasks that would benefit from tracking progress, consider using the TodoWrite tool to track progress. Also consider cleaning up the todo list if has become stale and no longer matches what you are working on. Only use it if it's relevant to the current work. This is just a gentle reminder - ignore if not applicable.</system-reminder>
         REMINDER
 
-        # Number of messages between TodoWrite reminders
-        TODOWRITE_REMINDER_INTERVAL = 8
+        # Backward compatibility alias - use Defaults module for new code
+        TODOWRITE_REMINDER_INTERVAL = Defaults::Context::TODOWRITE_REMINDER_INTERVAL
 
         class << self
           # Check if this is the first user message in the conversation
@@ -48,19 +31,17 @@ module SwarmSDK
           # @param chat [Agent::Chat] The chat instance
           # @return [Boolean] true if no user messages exist yet
           def first_message?(chat)
-            chat.messages.none? { |msg| msg.role == :user }
+            !chat.has_user_message?
           end
 
-          # Inject first message reminders (before + after user message)
+          # Inject first message reminders
           #
-          # This manually constructs the first message sequence with system reminders
-          # sandwiching the actual user prompt.
+          # This manually constructs the first message sequence with system reminders.
           #
           # Sequence:
-          # 1. BEFORE_FIRST_MESSAGE_REMINDER (general reminders)
+          # 1. User's actual prompt
           # 2. Toolset reminder (list of available tools)
-          # 3. User's actual prompt
-          # 4. AFTER_FIRST_MESSAGE_REMINDER (todo list reminder)
+          # 3. AFTER_FIRST_MESSAGE_REMINDER (todo list reminder - only if TodoWrite available)
           #
           # @param chat [Agent::Chat] The chat instance
           # @param prompt [String] The user's actual prompt
@@ -68,12 +49,15 @@ module SwarmSDK
           def inject_first_message_reminders(chat, prompt)
             # Build user message with embedded reminders
             # Reminders are embedded in the content, not separate messages
-            full_content = [
+            parts = [
               prompt,
-              BEFORE_FIRST_MESSAGE_REMINDER,
               build_toolset_reminder(chat),
-              AFTER_FIRST_MESSAGE_REMINDER,
-            ].join("\n\n")
+            ]
+
+            # Only include todo list reminder if agent has TodoWrite tool
+            parts << AFTER_FIRST_MESSAGE_REMINDER if chat.has_tool?("TodoWrite")
+
+            full_content = parts.join("\n\n")
 
             # Extract reminders and add clean prompt to persistent history
             reminders = chat.context_manager.extract_system_reminders(full_content)
@@ -84,7 +68,7 @@ module SwarmSDK
 
             # Track reminders to embed in this message when sending to LLM
             reminders.each do |reminder|
-              chat.context_manager.add_ephemeral_reminder(reminder, messages_array: chat.messages)
+              chat.add_ephemeral_reminder(reminder)
             end
           end
 
@@ -93,7 +77,7 @@ module SwarmSDK
           # @param chat [Agent::Chat] The chat instance
           # @return [String] System reminder with tool list
           def build_toolset_reminder(chat)
-            tools_list = chat.tools.values.map(&:name).sort
+            tools_list = chat.tool_names
 
             reminder = "<system-reminder>\n"
             reminder += "Tools available: #{tools_list.join(", ")}\n\n"
@@ -114,23 +98,23 @@ module SwarmSDK
           # @return [Boolean] true if reminder should be injected
           def should_inject_todowrite_reminder?(chat, last_todowrite_index)
             # Need at least a few messages before reminding
-            return false if chat.messages.count < 5
+            return false if chat.message_count < 5
 
             # Find the last message that contains TodoWrite tool usage
-            last_todo_index = chat.messages.rindex do |msg|
+            last_todo_index = chat.find_last_message_index do |msg|
               msg.role == :tool && msg.content.to_s.include?("TodoWrite")
             end
 
             # Check if enough messages have passed since last TodoWrite
             if last_todo_index.nil? && last_todowrite_index.nil?
               # Never used TodoWrite - check if we've exceeded interval
-              chat.messages.count >= TODOWRITE_REMINDER_INTERVAL
+              chat.message_count >= TODOWRITE_REMINDER_INTERVAL
             elsif last_todo_index
               # Recently used - don't remind
               false
             elsif last_todowrite_index
               # Used before - check if interval has passed
-              chat.messages.count - last_todowrite_index >= TODOWRITE_REMINDER_INTERVAL
+              chat.message_count - last_todowrite_index >= TODOWRITE_REMINDER_INTERVAL
             else
               false
             end
@@ -141,7 +125,7 @@ module SwarmSDK
           # @param chat [Agent::Chat] The chat instance
           # @return [Integer, nil] Index of last TodoWrite usage, or nil
           def find_last_todowrite_index(chat)
-            chat.messages.rindex do |msg|
+            chat.find_last_message_index do |msg|
               msg.role == :tool && msg.content.to_s.include?("TodoWrite")
             end
           end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    module ChatHelpers
+      # System reminder collection and injection
+      #
+      # Extracted from Chat to reduce class size and centralize reminder logic.
+      module SystemReminders
+        # Collect reminders from all plugins
+        #
+        # @param prompt [String] User's message
+        # @param is_first_message [Boolean] True if first message
+        # @return [Array<String>] Array of reminder strings
+        def collect_plugin_reminders(prompt, is_first_message:)
+          return [] unless @agent_name
+
+          PluginRegistry.all.flat_map do |plugin|
+            plugin.on_user_message(
+              agent_name: @agent_name,
+              prompt: prompt,
+              is_first_message: is_first_message,
+            )
+          end.compact
+        end
+
+        # Collect all system reminders for this message
+        #
+        # Returns an array of reminder strings that should be injected as ephemeral content.
+        # These are sent to the LLM but not stored in message history.
+        #
+        # @param prompt [String] User prompt
+        # @param is_first [Boolean] Whether this is the first message
+        # @return [Array<String>] Array of reminder strings
+        def collect_system_reminders(prompt, is_first)
+          reminders = []
+
+          if is_first
+            # Add toolset reminder on first message
+            reminders << build_toolset_reminder
+
+            # Add todo list reminder if agent has TodoWrite tool
+            reminders << SystemReminderInjector::AFTER_FIRST_MESSAGE_REMINDER if has_tool?(:TodoWrite)
+
+            # Collect plugin reminders
+            reminders.concat(collect_plugin_reminders(prompt, is_first_message: true))
+          else
+            # Add periodic TodoWrite reminder if needed
+            if has_tool?(:TodoWrite) && SystemReminderInjector.should_inject_todowrite_reminder?(self, @last_todowrite_message_index)
+              reminders << SystemReminderInjector::TODOWRITE_PERIODIC_REMINDER
+              @last_todowrite_message_index = SystemReminderInjector.find_last_todowrite_index(self)
+            end
+
+            # Collect plugin reminders
+            reminders.concat(collect_plugin_reminders(prompt, is_first_message: false))
+          end
+
+          reminders
+        end
+
+        private
+
+        # Build toolset reminder listing all available tools
+        #
+        # @return [String] System reminder with tool list
+        def build_toolset_reminder
+          tools_list = tool_names
+
+          reminder = "<system-reminder>\n"
+          reminder += "Tools available: #{tools_list.join(", ")}\n\n"
+          reminder += "Only use tools from this list. Do not attempt to use tools that are not listed here.\n"
+          reminder += "</system-reminder>"
+
+          reminder
+        end
+      end
+    end
+  end
+end