Class: SwarmSDK::ContextManagement::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/context_management/builder.rb

Overview

DSL for defining context management handlers

This builder provides a clean, idiomatic way to register handlers for context warning thresholds. Handlers receive a rich context object with message manipulation methods.

Examples:

Basic usage

context_management do
  on :warning_60 do |ctx|
    ctx.compress_tool_results(keep_recent: 10)
  end

  on :warning_80 do |ctx|
    ctx.prune_old_messages(keep_recent: 20)
  end
end

Progressive compression

context_management do
  on :warning_60 do |ctx|
    ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
  end

  on :warning_80 do |ctx|
    ctx.prune_old_messages(keep_recent: 30)
    ctx.compress_tool_results(keep_recent: 5, truncate_to: 200)
  end

  on :warning_90 do |ctx|
    ctx.log_action("emergency_pruning", tokens_remaining: ctx.tokens_remaining)
    ctx.prune_old_messages(keep_recent: 15)
  end
end

Constant Summary collapse

EVENT_MAP =

Map semantic event names to threshold percentages

{
  warning_60: 60,
  warning_80: 80,
  warning_90: 90,
}.freeze

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Builder

Returns a new instance of Builder.



46
47
48
 
# File 'lib/swarm_sdk/context_management/builder.rb', line 46

def initialize
  @handlers = {} # { threshold => block }
end

Instance Method Details

#build ⇒ Array<Hooks::Definition>

Build hook definitions from handlers

Creates Hooks::Definition objects that wrap user blocks to provide rich context objects instead of raw Hooks::Context. Each handler becomes a hook for the :context_warning event.

Returns:



96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/swarm_sdk/context_management/builder.rb', line 96

def build
  @handlers.map do |threshold, user_block|
    # Create a hook that filters by threshold and wraps context
    Hooks::Definition.new(
      event: :context_warning,
      matcher: nil, # No tool matching needed
      priority: 0,
      proc: create_threshold_matcher(threshold, user_block),
    )
  end
end

#on(event) {|ContextManagement::Context| ... } ⇒ void

This method returns an undefined value.

Register a handler for a context warning threshold

Handlers take full responsibility for managing context at their threshold. When a handler is registered for a threshold, automatic compression is disabled for that threshold.

Examples:

Compress tool results at 60%

on :warning_60 do |ctx|
  ctx.compress_tool_results(keep_recent: 10)
end

Custom logic at 80%

on :warning_80 do |ctx|
  if ctx.usage_percentage > 85
    ctx.prune_old_messages(keep_recent: 10)
  else
    ctx.summarize_old_exchanges(older_than: 20)
  end
end

Log and prune at 90%

on :warning_90 do |ctx|
  ctx.log_action("critical_threshold", remaining: ctx.tokens_remaining)
  ctx.prune_old_messages(keep_recent: 10)
end

Parameters:

  • event (Symbol) —

    Event name (:warning_60, :warning_80, :warning_90)

Yields:

Raises:

  • (ArgumentError) —

    If event is unknown or block is missing



81
82
83
84
85
86
87
 
# File 'lib/swarm_sdk/context_management/builder.rb', line 81

def on(event, &block)
  threshold = EVENT_MAP[event]
  raise ArgumentError, "Unknown event: #{event}. Valid events: #{EVENT_MAP.keys.join(", ")}" unless threshold
  raise ArgumentError, "Block required for #{event}" unless block

  @handlers[threshold] = block
end