Class: Phronomy::LlmContextWindow::Assembler

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/llm_context_window/assembler.rb

Overview

Assembler collects all four context regions and produces the final messages:, tool_classes: hash consumed by Agent::Base.

Regions:

1. Instruction  — system prompt text set via #add_instruction
2. Capability   — tool classes registered via #add_capability
3. Knowledge    — external facts injected via #add_knowledge (generates XML tags)
4. Conversation — historical messages added via #add_messages

Token budgeting:

When a budget is given, Assembler validates that the supplied conversation
messages fit after instruction, knowledge, and capability costs are
accounted for. It does not prune messages; Manifest-first Context Policy
is responsible for context selection.
Knowledge chunks are always included in full (they are assumed to be
pre-screened by the caller). When no budget is given all messages are
passed through unchanged.

Examples:

assembler = Phronomy::LlmContextWindow::Assembler.new(budget: budget)
assembler.add_instruction("You are a helpful assistant.")
assembler.add_knowledge("The user lives in Tokyo.", type: :entity, trusted: false)
assembler.add_messages(manager.load(thread_id: "t1", query: user_input))
context = assembler.build
# => { system: "You are ...\n<context ...>...</context>", messages: [...] }

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(budget: nil) ⇒ Assembler

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.

mutant:disable - @instruction = nil deletion is a genuine equivalent (uninitialized Ruby instance variables return nil)

Parameters:



51
52
53
54
55
56
57
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 51

def initialize(budget: nil)
  @budget = budget
  @instruction = nil
  @tool_classes = []
  @knowledge_chunks = []
  @messages = []
end

Class Method Details

.xml_tag(text, type:, trusted: false) ⇒ String

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.

Builds a single XML context tag string. Exposed as a class method so callers (e.g. Agent::Base) can build static knowledge XML tags independently of an Assembler instance.

mutant:disable - text.to_str and plain text (no to_s) are genuine equivalents when text is a String; type.to_str is genuine equivalent when type is a String

Parameters:

  • text (String)
  • type (Symbol, String)
  • trusted (Boolean) (defaults to: false)

Returns:

  • (String) 


43
44
45
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 43

def self.xml_tag(text, type:, trusted: false)
  "<context type=\"#{CGI.escapeHTML(type.to_s)}\" trusted=\"#{trusted}\">\n#{CGI.escapeHTML(text.to_s)}\n</context>"
end

Instance Method Details

#add_capability(tool_classes) ⇒ 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.

Register tool classes (Region 2). Estimates their token cost and deducts it from the budget so that budget estimation accounts for tool definition overhead.

Parameters:

  • tool_classes (Array<Class, Object>) —

    tool classes or instances

Returns:

  • (self) 


66
67
68
69
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 66

def add_capability(tool_classes)
  @tool_classes = Array(tool_classes)
  self
end

#add_instruction(text) ⇒ 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.

Set the system instruction text (Region 1). Calling this multiple times replaces the previous value.

mutant:disable - text.to_str and plain text (no .to_s) are genuine equivalents when callers always pass a String

Parameters:

  • text (String)

Returns:

  • (self) 


78
79
80
81
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 78

def add_instruction(text)
  @instruction = text.to_s
  self
end

#add_knowledge(text, type:, trusted: false, source: nil) ⇒ 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.

Append a knowledge chunk (Region 3). The chunk is wrapped in an XML context tag automatically.

mutant:disable - text: (shorthand, no .to_s) and text.to_str are genuine equivalents when text is a String; type: shorthand is genuine equivalent because xml_context_tag always calls .to_s on chunk

Parameters:

  • text (String)
  • type (Symbol, String) —

    semantic label for the context tag (e.g. :entity, :rag, :static)

  • trusted (Boolean) (defaults to: false) —

    false (default) indicates externally sourced data

  • source (String, nil) (defaults to: nil) —

    optional source label (e.g. filename); included in the XML tag so the LLM can produce grounded citations. Omitted when nil.

Returns:

  • (self) 


94
95
96
97
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 94

def add_knowledge(text, type:, trusted: false, source: nil)
  @knowledge_chunks << {text: text.to_s, type: type.to_s, trusted: trusted, source: source}
  self
end

#add_messages(messages) ⇒ 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.

Set conversation messages (Region 4). Replaces any previously set messages.

mutant:disable - @messages = messages (no Array()) is a genuine equivalent when callers always pass an Array

Parameters:

  • messages (Array) —

    message-like objects with #role and #content

Returns:

  • (self) 


105
106
107
108
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 105

def add_messages(messages)
  @messages = Array(messages)
  self
end

#available_for_messages ⇒ Integer?

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 the number of tokens available for conversation messages after accounting for instruction, knowledge, and capability overhead. Returns nil when no budget is configured.

Returns:

  • (Integer, nil) 


116
117
118
119
120
121
122
123
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 116

def available_for_messages
  return nil unless @budget
  knowledge_text = @knowledge_chunks.map { |c| xml_context_tag(c) }.join("\n\n")
  system_parts = [@instruction, knowledge_text.empty? ? nil : knowledge_text].compact
  system_text = system_parts.join("\n\n")
  used = TokenEstimator.estimate(system_text) + estimate_capability_tokens
  @budget.available(used: used)
end

#build ⇒ Hash{Symbol => Object}

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.

Assemble the context.

Raises ContextLengthError when a budget is set and the conversation messages do not fit within the remaining token allowance. No automatic trimming is performed — callers must pre-process messages before passing them to the Assembler.

mutant:disable - multiple genuine equivalent mutations: map{}.join("\n\n") → map{} is genuine; unless knowledge_text.empty? vs ternary is genuine; { system: unless system_text.empty? } vs ternary is genuine; messages: shorthand vs messages: messages is genuine

Returns:

  • (Hash{Symbol => Object}) —

    :system [String, nil] combined system prompt (instruction + knowledge XML tags) :messages [Array] conversation messages, trimmed to budget if set :tool_classes [Array] tool classes/instances to register with the chat



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 138

def build
  knowledge_text = @knowledge_chunks.map { |c| xml_context_tag(c) }.join("\n\n")
  system_parts = [@instruction, knowledge_text.empty? ? nil : knowledge_text].compact
  system_text = system_parts.join("\n\n")

  if @budget && @messages.any?
    capability_tokens = estimate_capability_tokens
    used = TokenEstimator.estimate(system_text) + capability_tokens
    remaining = @budget.available(used: used)
    msg_tokens = @messages.sum { |m| TokenEstimator.estimate(m.content.to_s) }
    if msg_tokens > remaining
      raise Phronomy::ContextLengthError,
        "Context exceeds token budget: messages require #{msg_tokens} tokens but " \
        "only #{remaining} available (context_window=#{@budget.context_window}, " \
        "used_by_system=#{used}). Use the Context Policy path to manage message budget."
    end
  end

  {
    system: system_text.empty? ? nil : system_text,
    messages: @messages,
    tool_classes: @tool_classes
  }
end