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: hash consumed by Agent::Base.

Regions:

  1. Instruction — system prompt text set via #add_instruction
  2. Capability — tool definitions (handled by RubyLLM, not here)
  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, conversation messages are trimmed from oldest to newest until they fit. 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:



48
49
50
51
52
53
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 48

def initialize(budget: nil)
  @budget = budget
  @instruction = nil
  @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) 


40
41
42
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 40

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_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) 


62
63
64
65
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 62

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[:type]

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) 


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

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) 


89
90
91
92
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 89

def add_messages(messages)
  @messages = Array(messages)
  self
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.

mutant:disable - multiple genuine equivalent mutations: map{}.join("\n\n") → map{} is genuine because Ruby Array#join recursively joins nested arrays with the same separator (so [outer_array].join("\n\n") == original String); unless knowledge_text.empty? vs ternary is genuine (same conditional logic); { 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



101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/phronomy/llm_context_window/assembler.rb', line 101

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")

  messages = if @budget
    trim_messages_to_budget(@messages, system_text)
  else
    @messages
  end

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