Module: Anthropic::Helpers::Tools::CompactionControl

Defined in:
lib/anthropic/helpers/tools/compaction_control.rb

Overview

Configuration for automatic conversation history compaction in tool runners.

When the cumulative token count (input + output) across all messages exceeds the threshold, the message history will be automatically summarized and compressed.

By default, a warning is printed to STDERR the first time compaction occurs for each runner instance. To silence the warning, provide an ‘on_compact` callback - when present, the warning is suppressed and you handle compaction events your way.

Examples:

Basic usage with defaults

client.beta.messages.tool_runner(
  model: "claude-sonnet-4-20250514",
  max_tokens: 4000,
  tools: [my_tool],
  messages: [...],
  compaction_control: { enabled: true }
)
# => Prints: "[anthropic-ruby] Context compaction triggered (N tokens)..."

Custom threshold and callback

client.beta.messages.tool_runner(
  # ... other params ...
  compaction_control: {
    enabled: true,
    context_token_threshold: 50_000,
    on_compact: ->(tokens_before, tokens_after) do
      logger.info "Compacted conversation: #{tokens_before} → #{tokens_after} tokens"
    end
  }
)
# => No warning printed; callback handles it

Custom model and summary prompt

client.beta.messages.tool_runner(
  # ... other params ...
  compaction_control: {
    enabled: true,
    model: "claude-3-7-sonnet-20250219",
    summary_prompt: "Summarize the conversation concisely..."
  }
)

See Also:

Instance Attribute Summary collapse

Instance Attribute Details

#context_token_threshold ⇒ Integer?

Returns The cumulative token count threshold at which to trigger compaction. When the total of input tokens (including cache tokens) and output tokens exceeds this value, compaction will occur. Defaults to 100,000 tokens.

Returns:

  • (Integer, nil) —

    The cumulative token count threshold at which to trigger compaction. When the total of input tokens (including cache tokens) and output tokens exceeds this value, compaction will occur. Defaults to 100,000 tokens.



102
 
# File 'lib/anthropic/helpers/tools/compaction_control.rb', line 102

module CompactionControl; end

#enabled ⇒ Boolean

Returns Whether to enable automatic compaction. Required.

Returns:

  • (Boolean) —

    Whether to enable automatic compaction. Required.



102
 
# File 'lib/anthropic/helpers/tools/compaction_control.rb', line 102

module CompactionControl; end

#model ⇒ String, ...

Returns The model to use for generating the compaction summary. If not specified, defaults to the same model used for the tool runner.

Returns:

  • (String, Symbol, nil) —

    The model to use for generating the compaction summary. If not specified, defaults to the same model used for the tool runner.



102
 
# File 'lib/anthropic/helpers/tools/compaction_control.rb', line 102

module CompactionControl; end

#on_compact ⇒ Proc?

Returns Optional callback invoked when compaction occurs. Receives two arguments: tokens_before (Integer) and tokens_after (Integer). Use this to log, monitor, or track compaction events. When provided, the default warning to STDERR is suppressed (you’re handling it yourself).

Returns:

  • (Proc, nil) —

    Optional callback invoked when compaction occurs. Receives two arguments: tokens_before (Integer) and tokens_after (Integer). Use this to log, monitor, or track compaction events. When provided, the default warning to STDERR is suppressed (you’re handling it yourself).



102
 
# File 'lib/anthropic/helpers/tools/compaction_control.rb', line 102

module CompactionControl; end

#summary_prompt ⇒ String?

Returns The prompt used to instruct the model on how to generate the summary. If not specified, uses DEFAULT_SUMMARY_PROMPT.

Returns:

  • (String, nil) —

    The prompt used to instruct the model on how to generate the summary. If not specified, uses DEFAULT_SUMMARY_PROMPT.



102
 
# File 'lib/anthropic/helpers/tools/compaction_control.rb', line 102

module CompactionControl; end