Class: Phronomy::Context::TrimContext

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/context/trim_context.rb

Overview

Context object passed to the +on_trim+ callback registered on an agent class.

The callback receives a TrimContext and may call #remove to drop specific messages from the conversation before the LLM is called. Changes affect only the current invocation; the underlying memory store is not modified.

Message elements are identified by a +:seq+ integer that is assigned sequentially (0-based) when messages are loaded from memory each turn.

Examples:

Remove the oldest two messages when the budget is tight

on_trim do |ctx|
  if ctx.total_tokens > ctx.budget.available(used: 0) * 0.9
    seqs_to_drop = ctx.message_elements.first(2).map { |e| e[:seq] }
    ctx.remove(seqs_to_drop)
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message_elements:, budget:) ⇒ TrimContext

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of TrimContext.

Parameters:

  • message_elements (Array<Hash>) —

    each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }

  • budget (Phronomy::Context::TokenBudget, nil) 


32
33
34
35
36
 
# File 'lib/phronomy/context/trim_context.rb', line 32

def initialize(message_elements:, budget:)
  @message_elements = message_elements.dup
  @budget = budget
  recalculate!
end

Instance Attribute Details

#budget ⇒ Phronomy::Context::TokenBudget? (readonly)

Returns token budget for this invocation.

Returns:



23
24
25
 
# File 'lib/phronomy/context/trim_context.rb', line 23

def budget
  @budget
end

#total_tokens ⇒ Integer (readonly)

Returns total estimated token count of all current message elements.

Returns:

  • (Integer) —

    total estimated token count of all current message elements



26
27
28
 
# File 'lib/phronomy/context/trim_context.rb', line 26

def total_tokens
  @total_tokens
end

Instance Method Details

#message_elements ⇒ Array<Hash>

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a snapshot of the current message elements (defensive copy). Each element is a Hash with +:seq+, +:message+, +:tokens+, and +:role+.

Returns:

  • (Array<Hash>) 


43
44
45
 
# File 'lib/phronomy/context/trim_context.rb', line 43

def message_elements
  @message_elements.dup
end

#messages ⇒ Array

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Convenience: returns the plain message objects (without element metadata).

Returns:

  • (Array) 


64
65
66
 
# File 'lib/phronomy/context/trim_context.rb', line 64

def messages
  @message_elements.map { |e| e[:message] }
end

#remove(seqs) ⇒ self

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Remove messages identified by seq numbers. Calling this multiple times accumulates removals.

Parameters:

  • seqs (Integer, Array<Integer>) —

    seq number(s) to remove

Returns:

  • (self) 


53
54
55
56
57
58
 
# File 'lib/phronomy/context/trim_context.rb', line 53

def remove(seqs)
  seqs_set = Array(seqs).to_set
  @message_elements.reject! { |e| seqs_set.include?(e[:seq]) }
  recalculate!
  self
end