swarm_sdk 2.4.3 → 2.4.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 370423fc8b77c4d3cc159123a64795b04bcea24ed6b96090a194329bb1d5af73
-  data.tar.gz: 05fa10de4f50a64e3bdb919fbea65a4e480cf0eb0b054b2c1e32ef6f5a84c65d
+  metadata.gz: a0fcbfaece7a208cfd4ef7afedecda776309b3368ffea0f0800cce3fb1c2ba0f
+  data.tar.gz: f41125b70b3e4d83f21132a2231e1ae56f4b2dc35c00c28ef16a51e756fb93b5
 SHA512:
-  metadata.gz: 064afcb3024b9a3006ba398f1237f5b7c189ae307a7603ea744312ec885f8ea307b1e9cb186d0b0a9da6b9908c46711b58a50c849dfdefce089ec82c989e5b26
-  data.tar.gz: eaded0c55ebc089acd20ad14a73a97ae24fe8cd5acf0cc2c557733ac03d224b96291e0717025998b9ba1c703e96465178b1dfab02c563c1d206790729daf3d21
+  metadata.gz: 6bc58ad13914191b180912d6ad8d7df187a43a696a5ef6db8f627cd213ab847ac3370d02a4e40e26df9b6bfa882ad3c5aa4adaccdc6c7eab1f3c10179768b97b
+  data.tar.gz: 0dcbe3bdbbf6a1443ab33268fd7968c50f874f7de688ca4edce8f7adb53ff3a00ab1910ae363f2b6c07a35401020f8602f3ca3f3ac81f95b6087fd76862e4914

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

@@ -170,11 +170,16 @@ module SwarmSDK
 
         # 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
-            RubyLLM.models.find(model_id)
+            # 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 = {

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

@@ -74,8 +74,8 @@ module SwarmSDK
           model_info = SwarmSDK::Models.find(message.model_id)
           return zero_cost unless model_info
 
-          # Extract pricing from SwarmSDK's models.json structure
-          pricing = model_info["pricing"] || model_info[:pricing]
+          # 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]

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

@@ -84,6 +84,35 @@ module SwarmSDK
           limit - cumulative_total_tokens
         end
 
+        # Calculate cumulative input cost based on tokens and model pricing
+        #
+        # @return [Float] Total input cost in dollars
+        def cumulative_input_cost
+          pricing = model_pricing
+          return 0.0 unless pricing
+
+          input_price = pricing["input_per_million"] || pricing[:input_per_million] || 0.0
+          (cumulative_input_tokens / 1_000_000.0) * input_price
+        end
+
+        # Calculate cumulative output cost based on tokens and model pricing
+        #
+        # @return [Float] Total output cost in dollars
+        def cumulative_output_cost
+          pricing = model_pricing
+          return 0.0 unless pricing
+
+          output_price = pricing["output_per_million"] || pricing[:output_per_million] || 0.0
+          (cumulative_output_tokens / 1_000_000.0) * output_price
+        end
+
+        # Calculate cumulative total cost (input + output)
+        #
+        # @return [Float] Total cost in dollars
+        def cumulative_total_cost
+          cumulative_input_cost + cumulative_output_cost
+        end
+
         # Compact the conversation history to reduce token usage
         #
         # @param options [Hash] Compression options
@@ -92,6 +121,25 @@ module SwarmSDK
           compactor = ContextCompactor.new(self, options)
           compactor.compact
         end
+
+        private
+
+        # Get pricing info for the current model
+        #
+        # Extracts standard text token pricing from model info.
+        #
+        # @return [Hash, nil] Pricing hash with input_per_million and output_per_million
+        def model_pricing
+          return unless @real_model_info&.pricing
+
+          pricing = @real_model_info.pricing
+          text_pricing = pricing["text_tokens"] || pricing[:text_tokens]
+          return unless text_pricing
+
+          text_pricing["standard"] || text_pricing[:standard]
+        rescue StandardError
+          nil
+        end
       end
     end
   end

data/lib/swarm_sdk/config.rb

@@ -91,6 +91,7 @@ module SwarmSDK
       webfetch_base_url: ["SWARM_SDK_WEBFETCH_BASE_URL", nil],
       webfetch_max_tokens: ["SWARM_SDK_WEBFETCH_MAX_TOKENS", 4096],
       allow_filesystem_tools: ["SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", true],
+      env_interpolation: ["SWARM_SDK_ENV_INTERPOLATION", true],
     }.freeze
 
     class << self
@@ -279,7 +280,7 @@ module SwarmSDK
     # @return [Integer, Float, Boolean, String] The parsed value
     def parse_env_value(value, key)
       case key
-      when :allow_filesystem_tools
+      when :allow_filesystem_tools, :env_interpolation
         # Convert string to boolean
         case value.to_s.downcase
         when "true", "yes", "1", "on", "enabled"

data/lib/swarm_sdk/configuration/parser.rb

@@ -30,9 +30,18 @@ module SwarmSDK
         :nodes,
         :external_swarms
 
-      def initialize(yaml_content, base_dir:)
+      # Initialize parser with YAML content and options
+      #
+      # @param yaml_content [String] YAML configuration content
+      # @param base_dir [String, Pathname] Base directory for resolving paths
+      # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+      #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+      #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+      #   When false, skips interpolation entirely.
+      def initialize(yaml_content, base_dir:, env_interpolation: nil)
         @yaml_content = yaml_content
         @base_dir = Pathname.new(base_dir).expand_path
+        @env_interpolation = env_interpolation
         @config_type = nil
         @swarm_id = nil
         @swarm_name = nil
@@ -55,7 +64,7 @@ module SwarmSDK
         end
 
         @config = Utils.symbolize_keys(@config)
-        interpolate_env_vars!(@config)
+        interpolate_env_vars!(@config) if env_interpolation_enabled?
 
         validate_version
         detect_and_validate_type
@@ -86,6 +95,17 @@ module SwarmSDK
 
       private
 
+      # Check if environment variable interpolation is enabled
+      #
+      # Uses the local setting if explicitly set, otherwise falls back to global config.
+      #
+      # @return [Boolean] true if interpolation should be performed
+      def env_interpolation_enabled?
+        return @env_interpolation unless @env_interpolation.nil?
+
+        SwarmSDK.config.env_interpolation
+      end
+
       def validate_version
         version = @config[:version]
         raise ConfigurationError, "Missing 'version' field in configuration" unless version

data/lib/swarm_sdk/configuration.rb

@@ -38,9 +38,13 @@ module SwarmSDK
       # Load configuration from YAML file
       #
       # @param path [String, Pathname] Path to YAML configuration file
+      # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+      #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+      #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+      #   When false, skips interpolation entirely.
       # @return [Configuration] Validated configuration instance
       # @raise [ConfigurationError] If file not found or invalid
-      def load_file(path)
+      def load_file(path, env_interpolation: nil)
         path = Pathname.new(path).expand_path
 
         unless path.exist?
@@ -50,7 +54,7 @@ module SwarmSDK
         yaml_content = File.read(path)
         base_dir = path.dirname
 
-        new(yaml_content, base_dir: base_dir).tap(&:load_and_validate)
+        new(yaml_content, base_dir: base_dir, env_interpolation: env_interpolation).tap(&:load_and_validate)
       rescue Errno::ENOENT
         raise ConfigurationError, "Configuration file not found: #{path}"
       end
@@ -60,12 +64,17 @@ module SwarmSDK
     #
     # @param yaml_content [String] YAML configuration content
     # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
-    def initialize(yaml_content, base_dir: Dir.pwd)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
+    def initialize(yaml_content, base_dir: Dir.pwd, env_interpolation: nil)
       raise ArgumentError, "yaml_content cannot be nil" if yaml_content.nil?
       raise ArgumentError, "base_dir cannot be nil" if base_dir.nil?
 
       @yaml_content = yaml_content
       @base_dir = Pathname.new(base_dir).expand_path
+      @env_interpolation = env_interpolation
       @parser = nil
       @translator = nil
     end
@@ -77,7 +86,7 @@ module SwarmSDK
     #
     # @return [self]
     def load_and_validate
-      @parser = Parser.new(@yaml_content, base_dir: @base_dir)
+      @parser = Parser.new(@yaml_content, base_dir: @base_dir, env_interpolation: @env_interpolation)
       @parser.parse
 
       # Sync parsed data to instance variables for backward compatibility

data/lib/swarm_sdk/models.json

@@ -5,7 +5,7 @@
       "provider": "anthropic",
       "family": "claude-haiku-4-5",
       "created_at": null,
-      "context_window": null,
+      "context_window": 200000,
       "max_output_tokens": 64000,
       "knowledge_cutoff": null,
       "modalities": {
@@ -36,7 +36,7 @@
       "provider": "anthropic",
       "family": "claude-haiku-4-5",
       "created_at": null,
-      "context_window": null,
+      "context_window": 200000,
       "max_output_tokens": 64000,
       "knowledge_cutoff": null,
       "modalities": {

data/lib/swarm_sdk/models.rb

@@ -18,16 +18,57 @@ module SwarmSDK
     MODELS_JSON_PATH = File.expand_path("models.json", __dir__)
     ALIASES_JSON_PATH = File.expand_path("model_aliases.json", __dir__)
 
+    # Model information wrapper providing method access to model data
+    #
+    # Wraps the raw Hash from models.json to provide RubyLLM::Model::Info-like
+    # interface for compatibility with code expecting method access.
+    #
+    # @example
+    #   model = SwarmSDK::Models.find("claude-sonnet-4-5-20250929")
+    #   model.context_window  #=> 200000
+    #   model.id              #=> "claude-sonnet-4-5-20250929"
+    class ModelInfo
+      attr_reader :id,
+        :name,
+        :provider,
+        :family,
+        :context_window,
+        :max_output_tokens,
+        :knowledge_cutoff,
+        :modalities,
+        :capabilities,
+        :pricing,
+        :metadata
+
+      # Create a ModelInfo from a Hash
+      #
+      # @param data [Hash] Model data from models.json
+      def initialize(data)
+        @id = data["id"] || data[:id]
+        @name = data["name"] || data[:name]
+        @provider = data["provider"] || data[:provider]
+        @family = data["family"] || data[:family]
+        @context_window = data["context_window"] || data[:context_window]
+        @max_output_tokens = data["max_output_tokens"] || data[:max_output_tokens]
+        @knowledge_cutoff = data["knowledge_cutoff"] || data[:knowledge_cutoff]
+        @modalities = data["modalities"] || data[:modalities]
+        @capabilities = data["capabilities"] || data[:capabilities]
+        @pricing = data["pricing"] || data[:pricing]
+        @metadata = data["metadata"] || data[:metadata]
+      end
+    end
+
     class << self
       # Find a model by ID or alias
       #
       # @param model_id [String] Model ID or alias to find
-      # @return [Hash, nil] Model data or nil if not found
+      # @return [ModelInfo, nil] Model info or nil if not found
       def find(model_id)
         # Check if it's an alias first
         resolved_id = resolve_alias(model_id)
 
-        all.find { |m| m["id"] == resolved_id || m[:id] == resolved_id }
+        model_hash = all.find { |m| m["id"] == resolved_id || m[:id] == resolved_id }
+        model_hash ? ModelInfo.new(model_hash) : nil
       end
 
       # Resolve a model alias to full model ID

data/lib/swarm_sdk/result.rb

@@ -109,6 +109,58 @@ module SwarmSDK
       @logs.map { |entry| entry[:agent] }.compact.uniq.map(&:to_sym)
     end
 
+    # Get per-agent usage breakdown from logs
+    #
+    # Aggregates context usage, tokens, and cost for each agent from their
+    # final agent_stop or agent_step events. Each agent's entry includes:
+    # - input_tokens, output_tokens, total_tokens
+    # - context_limit, usage_percentage, tokens_remaining
+    # - input_cost, output_cost, total_cost
+    #
+    # @return [Hash{Symbol => Hash}] Per-agent usage breakdown
+    #
+    # @example
+    #   result.per_agent_usage[:backend]
+    #   # => {
+    #   #   input_tokens: 15000,
+    #   #   output_tokens: 5000,
+    #   #   total_tokens: 20000,
+    #   #   context_limit: 200000,
+    #   #   usage_percentage: "10.0%",
+    #   #   tokens_remaining: 180000,
+    #   #   input_cost: 0.045,
+    #   #   output_cost: 0.075,
+    #   #   total_cost: 0.12
+    #   # }
+    def per_agent_usage
+      # Find the last usage entry for each agent
+      agent_entries = {}
+
+      @logs.each do |entry|
+        next unless entry[:usage] && entry[:agent]
+        next unless entry[:type] == "agent_step" || entry[:type] == "agent_stop"
+
+        agent_name = entry[:agent].to_sym
+        agent_entries[agent_name] = entry[:usage]
+      end
+
+      # Build breakdown from final usage entries
+      agent_entries.transform_values do |usage|
+        {
+          input_tokens: usage[:cumulative_input_tokens] || 0,
+          output_tokens: usage[:cumulative_output_tokens] || 0,
+          total_tokens: usage[:cumulative_total_tokens] || 0,
+          cached_tokens: usage[:cumulative_cached_tokens] || 0,
+          context_limit: usage[:context_limit],
+          usage_percentage: usage[:tokens_used_percentage],
+          tokens_remaining: usage[:tokens_remaining],
+          input_cost: usage[:input_cost] || 0.0,
+          output_cost: usage[:output_cost] || 0.0,
+          total_cost: usage[:total_cost] || 0.0,
+        }
+      end
+    end
+
     # Count total LLM requests made
     # Each LLM API call produces either agent_step (tool calls) or agent_stop (final answer)
     def llm_requests

data/lib/swarm_sdk/swarm/hook_triggers.rb

@@ -77,6 +77,7 @@ module SwarmSDK
             total_cost: result.total_cost,
             total_tokens: result.total_tokens,
             agents_involved: result.agents_involved,
+            per_agent_usage: result.per_agent_usage,
             result: result,
             timestamp: Time.now.utc.iso8601,
           },

data/lib/swarm_sdk/swarm/logging_callbacks.rb

@@ -208,6 +208,7 @@ module SwarmSDK
           total_cost: context.metadata[:total_cost],
           total_tokens: context.metadata[:total_tokens],
           agents_involved: context.metadata[:agents_involved],
+          per_agent_usage: context.metadata[:per_agent_usage],
           timestamp: context.metadata[:timestamp],
         )
       end

data/lib/swarm_sdk/swarm.rb

@@ -366,6 +366,47 @@ module SwarmSDK
       @agent_definitions.keys
     end
 
+    # Get context usage breakdown for all agents
+    #
+    # Returns per-agent context statistics including tokens used, context limit,
+    # usage percentage, and cost. Useful for monitoring context window consumption
+    # across the swarm.
+    #
+    # @return [Hash{Symbol => Hash}] Per-agent context breakdown
+    #
+    # @example
+    #   breakdown = swarm.context_breakdown
+    #   breakdown[:backend]
+    #   # => {
+    #   #   input_tokens: 15000,
+    #   #   output_tokens: 5000,
+    #   #   total_tokens: 20000,
+    #   #   cached_tokens: 2000,
+    #   #   context_limit: 200000,
+    #   #   usage_percentage: 10.0,
+    #   #   tokens_remaining: 180000,
+    #   #   input_cost: 0.045,
+    #   #   output_cost: 0.075,
+    #   #   total_cost: 0.12
+    #   # }
+    def context_breakdown
+      initialize_agents unless @agents_initialized
+
+      breakdown = {}
+
+      # Include primary agents
+      @agents.each do |name, chat|
+        breakdown[name] = build_agent_context_info(chat)
+      end
+
+      # Include delegation instances
+      @delegation_instances.each do |instance_name, chat|
+        breakdown[instance_name.to_sym] = build_agent_context_info(chat)
+      end
+
+      breakdown
+    end
+
     # Implement Snapshotable interface
     def primary_agents
       @agents
@@ -546,6 +587,29 @@ module SwarmSDK
       end
     end
 
+    # Build context info hash for an agent chat instance
+    #
+    # @param chat [Agent::Chat] Agent chat instance with TokenTracking
+    # @return [Hash] Context usage information
+    def build_agent_context_info(chat)
+      return {} unless chat.respond_to?(:cumulative_input_tokens)
+
+      {
+        input_tokens: chat.cumulative_input_tokens,
+        output_tokens: chat.cumulative_output_tokens,
+        total_tokens: chat.cumulative_total_tokens,
+        cached_tokens: chat.cumulative_cached_tokens,
+        cache_creation_tokens: chat.cumulative_cache_creation_tokens,
+        effective_input_tokens: chat.effective_input_tokens,
+        context_limit: chat.context_limit,
+        usage_percentage: chat.context_usage_percentage,
+        tokens_remaining: chat.tokens_remaining,
+        input_cost: chat.cumulative_input_cost,
+        output_cost: chat.cumulative_output_cost,
+        total_cost: chat.cumulative_total_cost,
+      }
+    end
+
     # Validate that observer agent exists
     #
     # @param agent_name [Symbol] Name of the observer agent

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk.rb

@@ -275,6 +275,11 @@ module SwarmSDK
     #
     # @param yaml_content [String] YAML configuration content
     # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
     # @return [Swarm, Workflow] Configured swarm or workflow instance
     # @raise [ConfigurationError] If YAML is invalid or configuration is incorrect
     #
@@ -297,8 +302,11 @@ module SwarmSDK
     # @example Load with default base_dir (Dir.pwd)
     #   yaml = File.read("config.yml")
     #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
-    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil)
-      config = Configuration.new(yaml_content, base_dir: base_dir)
+    #
+    # @example Load without environment variable interpolation
+    #   swarm = SwarmSDK.load(yaml, env_interpolation: false)
+    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil, env_interpolation: nil)
+      config = Configuration.new(yaml_content, base_dir: base_dir, env_interpolation: env_interpolation)
       config.load_and_validate
       swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
@@ -320,6 +328,11 @@ module SwarmSDK
     # loading swarms from configuration files.
     #
     # @param path [String, Pathname] Path to YAML configuration file
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
     # @return [Swarm, Workflow] Configured swarm or workflow instance
     # @raise [ConfigurationError] If file not found or configuration invalid
     #
@@ -329,8 +342,11 @@ module SwarmSDK
     #
     # @example With absolute path
     #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
-    def load_file(path, allow_filesystem_tools: nil)
-      config = Configuration.load_file(path)
+    #
+    # @example Load without environment variable interpolation
+    #   swarm = SwarmSDK.load_file("config.yml", env_interpolation: false)
+    def load_file(path, allow_filesystem_tools: nil, env_interpolation: nil)
+      config = Configuration.load_file(path, env_interpolation: env_interpolation)
       swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
       # Apply hooks if any are configured (YAML-only feature)

metadata

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