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

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) 


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

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>

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

Returns:

  • (Array<Hash>) 


41
42
43
 
# File 'lib/phronomy/context/trim_context.rb', line 41

def message_elements
  @message_elements.dup
end

#messages ⇒ Array

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

Returns:

  • (Array) 


60
61
62
 
# File 'lib/phronomy/context/trim_context.rb', line 60

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

#remove(seqs) ⇒ self

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

Parameters:

  • seqs (Integer, Array<Integer>) —

    seq number(s) to remove

Returns:

  • (self) 


50
51
52
53
54
55
 
# File 'lib/phronomy/context/trim_context.rb', line 50

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