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

Extended by:
Logging::Helper, Settings::Helper
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 



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

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 



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

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

.derive_tags(query) ⇒ Object 



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

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 



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

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
  handle_exception(e, level: :warn, operation: 'apollo.writeback.evaluate_and_route')
end

.extract_identity(request) ⇒ Object 



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

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
  handle_exception(e, level: :warn, operation: 'apollo.writeback.extract_identity')
  'unknown'
end

.extract_tool_calls(response, enrichments) ⇒ Object 



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

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 



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

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
  handle_exception(e, level: :warn, operation: 'apollo.writeback.extract_user_query')
  ''
end

.min_content_length ⇒ Object 



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

def min_content_length
  settings[:writeback][:min_content_length]
rescue StandardError => e
  handle_exception(e, level: :warn, operation: 'apollo.writeback.min_content_length')
  MIN_CONTENT_LENGTH
end

.publish_to_transport(payload, has_embedding: false) ⇒ Object 



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

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
  handle_exception(e, level: :warn, operation: 'apollo.writeback.publish_to_transport')
end

.response_content(response) ⇒ Object 



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

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 



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

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

  if can_embed
    result = Legion::LLM::Call::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) 


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

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 



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

def write_directly(payload)
  if defined?(Legion::Apollo)
    Legion::Apollo.ingest(**payload)
  else
    Runners::Knowledge.handle_ingest(**payload)
  end
rescue StandardError => e
  handle_exception(e, level: :warn, operation: 'apollo.writeback.write_directly')
  publish_to_transport(payload, has_embedding: !payload[:embedding].nil?)
end

.writeback_enabled? ⇒ Boolean

Returns:

  • (Boolean) 


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

def writeback_enabled?
  settings[:writeback][:enabled] != false
rescue StandardError => e
  handle_exception(e, level: :warn, operation: 'apollo.writeback.writeback_enabled')
  true
end