Class: Legion::Extensions::Agentic::Attention::Spotlight::Helpers::SpotlightEngine

Inherits:
Object
  • Object
show all
Includes:
Constants
Defined in:
lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb

Constant Summary

Constants included from Constants

Constants::CAPTURE_THRESHOLD, Constants::DEFAULT_BREADTH, Constants::DEFAULT_INTENSITY, Constants::INTENSITY_GAIN, Constants::INTENSITY_LABELS, Constants::INTENSITY_LOSS, Constants::MAX_PERIPHERAL, Constants::MAX_TARGETS, Constants::MODE_LABELS, Constants::PERIPHERAL_DETECTION_THRESHOLD, Constants::ZOOM_LEVELS, Constants::ZOOM_RANGES, Constants::ZOOM_STEP

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ SpotlightEngine

Returns a new instance of SpotlightEngine.



14
15
16
17
18
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 14

def initialize
  @targets    = {}
  @spotlight  = Spotlight.new
  @peripheral = []
end

Instance Attribute Details

#peripheral ⇒ Object (readonly)

Returns the value of attribute peripheral.



12
13
14
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 12

def peripheral
  @peripheral
end

#spotlight ⇒ Object (readonly)

Returns the value of attribute spotlight.



12
13
14
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 12

def spotlight
  @spotlight
end

#targets ⇒ Object (readonly)

Returns the value of attribute targets.



12
13
14
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 12

def targets
  @targets
end

Instance Method Details

#broaden ⇒ Object 



40
41
42
43
44
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 40

def broaden
  @spotlight.broaden!
  mark_spotlight_coverage
  { broadened: true, breadth: @spotlight.breadth, zoom_level: @spotlight.zoom_level }
end

#check_capture ⇒ Object 



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 69

def check_capture
  candidate = @targets.values
                      .reject(&:in_spotlight)
                      .select(&:compelling?)
                      .max_by(&:salience)
  return { captured: false } unless candidate

  clear_spotlight_flags
  @spotlight.capture!(candidate.id)
  candidate.in_spotlight = true
  candidate.capture_count += 1
  candidate.last_attended_at = Time.now.utc
  mark_spotlight_coverage
  { captured: true, target_id: candidate.id, salience: candidate.salience }
end

#check_peripheral ⇒ Object 



60
61
62
63
64
65
66
67
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 60

def check_peripheral
  outside = @targets.values.reject(&:in_spotlight)
  detected = outside.select(&:salient?).first(Constants::MAX_PERIPHERAL)
  @peripheral = detected.map(&:id)
  detected.each { |t| t.in_periphery = true }
  (outside - detected).each { |t| t.in_periphery = false }
  { detected: @peripheral.size, peripheral_ids: @peripheral }
end

#focus(target_id:) ⇒ Object 



29
30
31
32
33
34
35
36
37
38
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 29

def focus(target_id:)
  target = @targets[target_id]
  return { focused: false, reason: :not_found } unless target

  clear_spotlight_flags
  @spotlight.focus_on!(target_id)
  target.in_spotlight = true
  target.last_attended_at = Time.now.utc
  { focused: true, target_id: target_id, mode: @spotlight.mode, intensity: @spotlight.intensity }
end

#most_salient(limit: 5) ⇒ Object 



99
100
101
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 99

def most_salient(limit: 5)
  @targets.values.sort_by { |t| -t.salience }.first(limit)
end

#narrow ⇒ Object 



46
47
48
49
50
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 46

def narrow
  @spotlight.narrow!
  mark_spotlight_coverage
  { narrowed: true, breadth: @spotlight.breadth, zoom_level: @spotlight.zoom_level }
end

#peripheral_alerts ⇒ Object 



95
96
97
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 95

def peripheral_alerts
  @peripheral.filter_map { |id| @targets[id] }
end

#register_target(label:, domain:, salience: 0.5, relevance: 0.5) ⇒ Object 



20
21
22
23
24
25
26
27
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 20

def register_target(label:, domain:, salience: 0.5, relevance: 0.5)
  return { registered: false, reason: :max_targets_reached, limit: Constants::MAX_TARGETS } if @targets.size >= Constants::MAX_TARGETS

  target = AttentionTarget.new(label: label, domain: domain,
                               salience: salience, relevance: relevance)
  @targets[target.id] = target
  { registered: true, target_id: target.id, label: label, domain: domain }
end

#release_focus ⇒ Object 



85
86
87
88
89
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 85

def release_focus
  clear_spotlight_flags
  @spotlight.release!
  { released: true }
end

#scan ⇒ Object 



52
53
54
55
56
57
58
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 52

def scan
  @spotlight.instance_variable_set(:@mode, :scanning)
  mark_spotlight_coverage
  sorted = @targets.values.sort_by { |t| -t.salience }
  sorted.each { |t| t.last_attended_at = Time.now.utc }
  { scanning: true, targets_swept: sorted.size }
end

#spotlight_report ⇒ Object 



103
104
105
106
107
108
109
110
111
112
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 103

def spotlight_report
  {
    spotlight:        @spotlight.to_h,
    in_spotlight:     targets_in_spotlight.map(&:to_h),
    in_periphery:     peripheral_alerts.map(&:to_h),
    most_salient:     most_salient.map(&:to_h),
    total_targets:    @targets.size,
    peripheral_count: @peripheral.size
  }
end

#targets_in_spotlight ⇒ Object 



91
92
93
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 91

def targets_in_spotlight
  @targets.values.select(&:in_spotlight)
end

#to_h ⇒ Object 



114
115
116
117
118
119
120
121
 
# File 'lib/legion/extensions/agentic/attention/spotlight/helpers/spotlight_engine.rb', line 114

def to_h
  {
    spotlight:         @spotlight.to_h,
    target_count:      @targets.size,
    peripheral_count:  @peripheral.size,
    spotlight_targets: targets_in_spotlight.map(&:to_h)
  }
end