swarm_sdk 2.2.0 → 2.4.0

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

@@ -0,0 +1,262 @@
+# 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 != SwarmSDK.config.agent_request_timeout
+            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
+        #
+        # @param config [RubyLLM::Config] RubyLLM configuration context
+        # @param provider [String] Provider name
+        # @param base_url [String] Custom base URL
+        # @raise [ConfigurationError] If API key is required but not configured
+        # @raise [ArgumentError] If provider doesn't support custom 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
+            api_key = SwarmSDK.config.openai_api_key
+
+            # For local endpoints, API key is optional
+            # For cloud endpoints, require API key
+            unless api_key || local_endpoint?(base_url)
+              raise ConfigurationError,
+                "OpenAI API key required for '#{provider}' with base_url '#{base_url}'. " \
+                  "Configure with: SwarmSDK.configure { |c| c.openai_api_key = '...' }"
+            end
+
+            config.openai_api_key = api_key if api_key
+            config.openai_use_system_role = true
+          when "ollama"
+            config.ollama_api_base = base_url
+            # Ollama doesn't need an API key
+          when "gpustack"
+            config.gpustack_api_base = base_url
+            api_key = SwarmSDK.config.gpustack_api_key
+            config.gpustack_api_key = api_key if api_key
+          else
+            raise ArgumentError, "Provider '#{provider}' doesn't support custom base_url."
+          end
+        end
+
+        # Check if a URL points to a local endpoint
+        #
+        # @param url [String] URL to check
+        # @return [Boolean] true if URL is a local endpoint
+        def local_endpoint?(url)
+          uri = URI.parse(url)
+          ["localhost", "127.0.0.1", "0.0.0.0"].include?(uri.host)
+        rescue URI::InvalidURIError
+          false
+        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:
@@ -22,16 +22,13 @@ 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
-
         class << self
           # Check if this is the first user message in the conversation
           #
           # @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
@@ -55,7 +52,7 @@ module SwarmSDK
             ]
 
             # Only include todo list reminder if agent has TodoWrite tool
-            parts << AFTER_FIRST_MESSAGE_REMINDER if chat.tools.key?("TodoWrite")
+            parts << AFTER_FIRST_MESSAGE_REMINDER if chat.has_tool?("TodoWrite")
 
             full_content = parts.join("\n\n")
 
@@ -68,7 +65,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
 
@@ -77,7 +74,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"
@@ -98,23 +95,24 @@ 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
+            reminder_interval = SwarmSDK.config.todowrite_reminder_interval
             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 >= 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 >= reminder_interval
             else
               false
             end
@@ -125,7 +123,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

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    module ChatHelpers
+      # Token usage tracking and context limit management
+      #
+      # Extracted from Chat to reduce class size and centralize token metrics.
+      module TokenTracking
+        # Get context window limit for the current model
+        #
+        # @return [Integer, nil] Maximum context tokens
+        def context_limit
+          return @explicit_context_window if @explicit_context_window
+          return @real_model_info.context_window if @real_model_info&.context_window
+
+          model_context_window
+        rescue StandardError
+          nil
+        end
+
+        # Calculate cumulative input tokens for the conversation
+        #
+        # Gets input_tokens from the most recent assistant message, which represents
+        # the total context size sent to the model (not sum of all messages).
+        #
+        # @return [Integer] Total input tokens used
+        def cumulative_input_tokens
+          find_last_message { |msg| msg.role == :assistant && msg.input_tokens }&.input_tokens || 0
+        end
+
+        # Calculate cumulative output tokens across all assistant messages
+        #
+        # @return [Integer] Total output tokens used
+        def cumulative_output_tokens
+          assistant_messages.sum { |msg| msg.output_tokens || 0 }
+        end
+
+        # Calculate cumulative cached tokens
+        #
+        # @return [Integer] Total cached tokens used
+        def cumulative_cached_tokens
+          assistant_messages.sum { |msg| msg.cached_tokens || 0 }
+        end
+
+        # Calculate cumulative cache creation tokens
+        #
+        # @return [Integer] Total tokens written to cache
+        def cumulative_cache_creation_tokens
+          assistant_messages.sum { |msg| msg.cache_creation_tokens || 0 }
+        end
+
+        # Calculate effective input tokens (excluding cache hits)
+        #
+        # @return [Integer] Actual input tokens charged
+        def effective_input_tokens
+          cumulative_input_tokens - cumulative_cached_tokens
+        end
+
+        # Calculate total tokens used (input + output)
+        #
+        # @return [Integer] Total tokens used
+        def cumulative_total_tokens
+          cumulative_input_tokens + cumulative_output_tokens
+        end
+
+        # Calculate percentage of context window used
+        #
+        # @return [Float] Percentage (0.0 to 100.0)
+        def context_usage_percentage
+          limit = context_limit
+          return 0.0 if limit.nil? || limit.zero?
+
+          (cumulative_total_tokens.to_f / limit * 100).round(2)
+        end
+
+        # Calculate remaining tokens in context window
+        #
+        # @return [Integer, nil] Tokens remaining
+        def tokens_remaining
+          limit = context_limit
+          return if limit.nil?
+
+          limit - cumulative_total_tokens
+        end
+
+        # Compact the conversation history to reduce token usage
+        #
+        # @param options [Hash] Compression options
+        # @return [ContextCompactor::Metrics] Compression statistics
+        def compact_context(**options)
+          compactor = ContextCompactor.new(self, options)
+          compactor.compact
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/agent/context.rb

@@ -30,8 +30,7 @@ module SwarmSDK
       # 60% triggers automatic compression, 80%/90% are informational warnings
       CONTEXT_WARNING_THRESHOLDS = [60, 80, 90].freeze
 
-      # Threshold at which automatic compression is triggered
-      COMPRESSION_THRESHOLD = 60
+      # NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold
 
       attr_reader :name, :delegation_tools, :metadata, :warning_thresholds_hit, :swarm_id, :parent_swarm_id