swarm_sdk 2.7.13 → 3.0.0.alpha1

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

@@ -1,290 +0,0 @@
-# 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
-            # Set read_timeout to match request_timeout for streaming support
-            # This ensures long gaps between chunks (model thinking) don't cause timeouts
-            config.read_timeout = SwarmSDK.config.llm_read_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 "anthropic"
-            config.anthropic_api_base = base_url
-            api_key = SwarmSDK.config.anthropic_api_key
-            config.anthropic_api_key = api_key if api_key
-          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
-        #
-        # Uses SwarmSDK::Models for model lookup (reads from models.json).
-        # Falls back to RubyLLM.models if not found in SwarmSDK.
-        #
-        # @param model_id [String] Model ID to lookup
-        def fetch_real_model_info(model_id)
-          @model_lookup_error = nil
-          @real_model_info = begin
-            # Try SwarmSDK::Models first (reads from local models.json)
-            # Returns ModelInfo object with method access (context_window, etc.)
-            SwarmSDK::Models.find(model_id) || 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 extended thinking on the RubyLLM chat instance
-        #
-        # @param thinking_config [Hash, nil] Thinking configuration with :effort and/or :budget
-        # @return [self]
-        #
-        # @example
-        #   configure_thinking(budget: 10_000)
-        #   configure_thinking(effort: :high)
-        #   configure_thinking(effort: :high, budget: 10_000)
-        def configure_thinking(thinking_config)
-          return self unless thinking_config
-
-          @llm_chat.with_thinking(**thinking_config)
-          self
-        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_helpers/logging_helpers.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    module ChatHelpers
-      # Helper methods for logging and serialization of tool calls and results
-      #
-      # Responsibilities:
-      # - Format tool calls for logging
-      # - Serialize tool results (handling different types)
-      # - Calculate LLM costs based on token usage
-      #
-      # These are stateless utility methods that operate on data structures.
-      module LoggingHelpers
-        # Format tool calls for logging
-        #
-        # @param tool_calls_hash [Hash] Tool calls from message
-        # @return [Array<Hash>, nil] Formatted tool calls
-        def format_tool_calls(tool_calls_hash)
-          return unless tool_calls_hash
-
-          tool_calls_hash.map do |_id, tc|
-            {
-              id: tc.id,
-              name: tc.name,
-              arguments: tc.arguments,
-            }
-          end
-        end
-
-        # Serialize a tool result for logging
-        #
-        # Handles multiple result types:
-        # - String: pass through
-        # - Hash/Array: pass through
-        # - RubyLLM::Content: extract text and attachment info
-        # - Other: convert to string
-        #
-        # @param result [String, Hash, Array, RubyLLM::Content, Object] Tool result
-        # @return [String, Hash, Array] Serialized result
-        def serialize_result(result)
-          case result
-          when String then result
-          when Hash, Array then result
-          when RubyLLM::Content
-            # Format Content objects to show text and attachment info
-            parts = []
-            parts << result.text if result.text && !result.text.empty?
-
-            if result.attachments.any?
-              attachment_info = result.attachments.map do |att|
-                "#{att.source} (#{att.mime_type})"
-              end.join(", ")
-              parts << "[Attachments: #{attachment_info}]"
-            end
-
-            parts.join(" ")
-          else
-            result.to_s
-          end
-        end
-
-        # Calculate LLM cost for a message
-        #
-        # Uses RubyLLM's model registry to get pricing information.
-        # Returns zero cost if pricing is unavailable.
-        #
-        # @param message [RubyLLM::Message] Message with token counts
-        # @return [Hash] Cost breakdown { input_cost:, output_cost:, total_cost: }
-        def calculate_cost(message)
-          return zero_cost unless message.input_tokens && message.output_tokens
-
-          # Use SwarmSDK's model registry (not RubyLLM's) for up-to-date pricing
-          model_info = SwarmSDK::Models.find(message.model_id)
-          return zero_cost unless model_info
-
-          # Extract pricing from SwarmSDK's ModelInfo (method access for top-level, Hash for nested)
-          pricing = model_info.pricing
-          return zero_cost unless pricing
-
-          text_pricing = pricing["text_tokens"] || pricing[:text_tokens]
-          return zero_cost unless text_pricing
-
-          standard_pricing = text_pricing["standard"] || text_pricing[:standard]
-          return zero_cost unless standard_pricing
-
-          input_price = standard_pricing["input_per_million"] || standard_pricing[:input_per_million]
-          output_price = standard_pricing["output_per_million"] || standard_pricing[:output_per_million]
-
-          return zero_cost unless input_price && output_price
-
-          # Calculate costs (prices are per million tokens in USD)
-          input_cost = (message.input_tokens / 1_000_000.0) * input_price
-          output_cost = (message.output_tokens / 1_000_000.0) * output_price
-
-          {
-            input_cost: input_cost,
-            output_cost: output_cost,
-            total_cost: input_cost + output_cost,
-          }
-        rescue StandardError => e
-          # Model not found in registry or pricing not available
-          RubyLLM.logger.debug("Cost calculation failed for #{message.model_id}: #{e.message}")
-          zero_cost
-        end
-
-        # Zero cost fallback
-        #
-        # @return [Hash] Zero cost breakdown
-        def zero_cost
-          { input_cost: 0.0, output_cost: 0.0, total_cost: 0.0 }
-        end
-      end
-    end
-  end
-end

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

@@ -1,83 +0,0 @@
-# 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_helpers/system_reminder_injector.rb

@@ -1,134 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    module ChatHelpers
-      # Handles injection of system reminders at strategic points in the conversation
-      #
-      # Responsibilities:
-      # - Inject reminders before/after first user message
-      # - Inject periodic TodoWrite reminders
-      # - Track when reminders were last injected
-      #
-      # This class is stateless - it operates on the chat's message history.
-      class SystemReminderInjector
-        # 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>
-        REMINDER
-
-        # Periodic reminder about TodoWrite tool usage
-        TODOWRITE_PERIODIC_REMINDER = <<~REMINDER.strip
-          <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
-
-        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.has_user_message?
-          end
-
-          # Inject first message reminders
-          #
-          # This manually constructs the first message sequence with system reminders.
-          #
-          # Sequence:
-          # 1. User's actual prompt
-          # 2. Toolset reminder (list of available tools)
-          # 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
-          # @return [void]
-          def inject_first_message_reminders(chat, prompt)
-            # Build user message with embedded reminders
-            # Reminders are embedded in the content, not separate messages
-            parts = [
-              prompt,
-              build_toolset_reminder(chat),
-            ]
-
-            # 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)
-            clean_prompt = chat.context_manager.strip_system_reminders(full_content)
-
-            # Store clean prompt (without reminders) in conversation history
-            chat.add_message(role: :user, content: clean_prompt)
-
-            # Track reminders to embed in this message when sending to LLM
-            reminders.each do |reminder|
-              chat.add_ephemeral_reminder(reminder)
-            end
-          end
-
-          # Build toolset reminder listing all available tools
-          #
-          # @param chat [Agent::Chat] The chat instance
-          # @return [String] System reminder with tool list
-          def build_toolset_reminder(chat)
-            tools_list = chat.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
-
-          # Check if we should inject a periodic TodoWrite reminder
-          #
-          # Injects a reminder if:
-          # 1. Enough messages have passed (>= 5)
-          # 2. TodoWrite hasn't been used in the last TODOWRITE_REMINDER_INTERVAL messages
-          #
-          # @param chat [Agent::Chat] The chat instance
-          # @param last_todowrite_index [Integer, nil] Index of last TodoWrite usage
-          # @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.message_count < 5
-
-            # Find the last message that contains TodoWrite tool usage
-            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.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.message_count - last_todowrite_index >= reminder_interval
-            else
-              false
-            end
-          end
-
-          # Update the last TodoWrite index by finding it in messages
-          #
-          # @param chat [Agent::Chat] The chat instance
-          # @return [Integer, nil] Index of last TodoWrite usage, or nil
-          def find_last_todowrite_index(chat)
-            chat.find_last_message_index do |msg|
-              msg.role == :tool && msg.content.to_s.include?("TodoWrite")
-            end
-          end
-        end
-      end
-    end
-  end
-end