Module: Legion::Extensions::Apollo::Helpers::Writeback

Defined in:
lib/legion/extensions/apollo/helpers/writeback.rb

Constant Summary collapse

RESEARCH_TOOLS = 
%w[read_file search_files search_content run_command].freeze
MAX_CONTENT_LENGTH = 
4000
MIN_CONTENT_LENGTH = 
50

Class Method Summary collapse

Class Method Details

.build_payload(request:, response:, source_channel: nil) ⇒ Object 



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 47

def build_payload(request:, response:, source_channel: nil)
  content = response_content(response)
  caller_identity = extract_identity(request)
  user_query = extract_user_query(request)
  tags = derive_tags(user_query)

  {
    content:          content[0...MAX_CONTENT_LENGTH],
    content_type:     'observation',
    tags:             Helpers::TagNormalizer.normalize_all(tags),
    source_agent:     response.respond_to?(:model) ? response.model : 'unknown',
    source_channel:   "#{source_channel || 'pipeline'}_synthesis",
    submitted_by:     caller_identity,
    submitted_from:   Socket.gethostname,
    knowledge_domain: nil,
    content_hash:     content_hash(content)
  }
end

.content_hash(content) ⇒ Object 



118
119
120
121
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 118

def content_hash(content)
  normalized = content.to_s.strip.downcase.gsub(/\s+/, ' ')
  Digest::MD5.hexdigest(normalized)
end

.derive_tags(query) ⇒ Object 



156
157
158
159
160
161
162
163
164
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 156

def derive_tags(query)
  stop_words = %w[a an the is are was were be been being have has had do does did will would shall
                  should may might can could of in to for on with at by from as into about between
                  how what when where why who which this that these those it its and or but not]
  words = query.to_s.downcase.gsub(/[^a-z0-9\s]/, '').split
  words.reject { |w| stop_words.include?(w) || w.length < 3 }
       .uniq
       .first(5)
end

.evaluate_and_route(request:, response:, enrichments: {}) ⇒ Object 



21
22
23
24
25
26
27
28
29
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 21

def evaluate_and_route(request:, response:, enrichments: {})
  return unless writeback_enabled?
  return unless should_capture?(request, response, enrichments)

  payload = build_payload(request: request, response: response)
  route_payload(payload)
rescue StandardError => e
  log.warn("apollo writeback failed: #{e.message}")
end

.extract_identity(request) ⇒ Object 



130
131
132
133
134
135
136
137
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 130

def extract_identity(request)
  return 'unknown' unless request.respond_to?(:caller) && request.caller.is_a?(Hash)

  request.caller.dig(:requested_by, :identity) || 'unknown'
rescue StandardError => e
  log.warn("Apollo Writeback.extract_identity failed: #{e.message}")
  'unknown'
end

.extract_tool_calls(response, enrichments) ⇒ Object 



149
150
151
152
153
154
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 149

def extract_tool_calls(response, enrichments)
  calls = []
  calls += Array(response.tool_calls) if response.respond_to?(:tool_calls)
  calls += Array(enrichments['tool_calls']) if enrichments['tool_calls']
  calls.uniq { |tc| tc[:name] || tc['name'] }
end

.extract_user_query(request) ⇒ Object 



139
140
141
142
143
144
145
146
147
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 139

def extract_user_query(request)
  return '' unless request.respond_to?(:messages)

  user_msgs = Array(request.messages).select { |m| m[:role] == 'user' || m['role'] == 'user' }
  (user_msgs.last || {})[:content] || ''
rescue StandardError => e
  log.warn("Apollo Writeback.extract_user_query failed: #{e.message}")
  ''
end

.log ⇒ Object 



17
18
19
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 17

def log
  Legion::Logging
end

.min_content_length ⇒ Object 



111
112
113
114
115
116
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 111

def min_content_length
  Legion::Settings.dig(:apollo, :writeback, :min_content_length) || MIN_CONTENT_LENGTH
rescue StandardError => e
  log.warn("Apollo Writeback.min_content_length failed: #{e.message}")
  MIN_CONTENT_LENGTH
end

.publish_to_transport(payload, has_embedding: false) ⇒ Object 



94
95
96
97
98
99
100
101
102
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 94

def publish_to_transport(payload, has_embedding: false)
  return unless Legion.const_defined?(:Transport, false)

  Transport::Messages::Writeback.new(
    **payload, has_embedding: has_embedding
  ).publish
rescue StandardError => e
  log.warn("apollo writeback publish failed: #{e.message}")
end

.response_content(response) ⇒ Object 



123
124
125
126
127
128
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 123

def response_content(response)
  msg = response.respond_to?(:message) ? response.message : nil
  return nil unless msg.is_a?(Hash)

  msg[:content] || msg['content']
end

.route_payload(payload) ⇒ Object 



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 66

def route_payload(payload)
  can_embed = Helpers::Capability.can_embed?
  can_write = Helpers::Capability.can_write?

  if can_embed
    result = Legion::LLM::Embeddings.generate(text: payload[:content])
    vector = result.is_a?(Hash) ? result[:vector] : result
    payload[:embedding] = vector.is_a?(Array) && vector.any? ? vector : Array.new(1024, 0.0)
  end

  if can_write && can_embed
    write_directly(payload)
  else
    publish_to_transport(payload, has_embedding: can_embed)
  end
end

.should_capture?(_request, response, enrichments) ⇒ Boolean

Returns:

  • (Boolean) 


31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 31

def should_capture?(_request, response, enrichments)
  content = response_content(response)
  return false if content.nil? || content.length < min_content_length

  tool_calls = extract_tool_calls(response, enrichments)
  research_calls = tool_calls.select { |tc| RESEARCH_TOOLS.include?(tc[:name] || tc['name']) }

  return false if research_calls.empty?

  apollo_results = enrichments['rag_context:apollo_results']
  return true if apollo_results.nil? || (apollo_results[:count] || 0).zero?

  # Apollo had results — only capture if LLM also did additional research
  research_calls.any?
end

.write_directly(payload) ⇒ Object 



83
84
85
86
87
88
89
90
91
92
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 83

def write_directly(payload)
  if defined?(Legion::Apollo)
    Legion::Apollo.ingest(**payload)
  else
    Runners::Knowledge.handle_ingest(**payload)
  end
rescue StandardError => e
  log.warn("apollo direct write failed, falling back to transport: #{e.message}")
  publish_to_transport(payload, has_embedding: !payload[:embedding].nil?)
end

.writeback_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


104
105
106
107
108
109
 
# File 'lib/legion/extensions/apollo/helpers/writeback.rb', line 104

def writeback_enabled?
  Legion::Settings.dig(:apollo, :writeback, :enabled) != false
rescue StandardError => e
  log.warn("Apollo Writeback.writeback_enabled? failed: #{e.message}")
  true
end