lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/regulation/helpers/attention_controller.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Regulation
+          module Helpers
+            class AttentionController
+              include Constants
+
+              def initialize
+                @targets           = {}
+                @current_target_id = nil
+                @zoom              = DEFAULT_ZOOM
+                @resource          = DEFAULT_RESOURCE
+                @mode              = :diffuse
+                @counter           = 0
+                @history           = []
+              end
+
+              def add_target(name:, domain: :general, salience: 0.5)
+                return nil if @targets.size >= MAX_TARGETS
+
+                id = :"target_#{@counter}"
+                @counter += 1
+                target = AttentionTarget.new(id: id, name: name, domain: domain, salience: salience)
+                @targets[id] = target
+                target
+              end
+
+              def focus_on(target_id:)
+                target = @targets[target_id]
+                return nil unless target
+
+                defocus_current_target
+                @current_target_id = target_id
+                @mode = :focused
+                target.attend!
+                record_history(:focus, target_id)
+                target
+              end
+
+              def defocus
+                defocus_current_target
+                @current_target_id = nil
+                @mode = :diffuse
+                record_history(:defocus, nil)
+                true
+              end
+
+              def scan
+                @mode = :scanning
+                record_history(:scan, nil)
+                check_capture
+              end
+
+              def rest
+                @mode = :resting
+                @current_target_id = nil
+                record_history(:rest, nil)
+                true
+              end
+
+              def zoom_in(amount: 0.1)
+                @zoom = (@zoom + amount.to_f).clamp(ZOOM_FLOOR, ZOOM_CEILING)
+                @zoom
+              end
+
+              def zoom_out(amount: 0.1)
+                @zoom = (@zoom - amount.to_f).clamp(ZOOM_FLOOR, ZOOM_CEILING)
+                @zoom
+              end
+
+              def check_capture
+                return nil unless @resource > 0.3
+
+                candidate = @targets.values
+                                    .select { |t| t.state != :attended && t.salient_enough_to_capture? }
+                                    .max_by(&:salience)
+                return nil unless candidate
+
+                focus_on(target_id: candidate.id)
+                @mode = :captured
+                record_history(:captured, candidate.id)
+                candidate
+              end
+
+              def current_target
+                return nil unless @current_target_id
+
+                @targets[@current_target_id]
+              end
+
+              def most_salient
+                @targets.values.max_by(&:salience)
+              end
+
+              def attended_targets
+                @targets.values.select { |t| t.state == :attended }
+              end
+
+              def peripheral_targets
+                @targets.values.select { |t| t.state == :peripheral }
+              end
+
+              def tick
+                case @mode
+                when :focused, :captured
+                  @resource = (@resource - RESOURCE_DRAIN).clamp(RESOURCE_FLOOR, RESOURCE_CEILING)
+                when :resting
+                  @resource = (@resource + RESOURCE_RECOVERY).clamp(RESOURCE_FLOOR, RESOURCE_CEILING)
+                end
+
+                check_capture if @mode == :scanning
+              end
+
+              def resource_label
+                RESOURCE_LABELS.each { |range, lbl| return lbl if range.cover?(@resource) }
+                :depleted
+              end
+
+              def to_h
+                {
+                  mode:              @mode,
+                  zoom:              @zoom.round(4),
+                  resource:          @resource.round(4),
+                  resource_label:    resource_label,
+                  current_target_id: @current_target_id,
+                  target_count:      @targets.size,
+                  attended_count:    attended_targets.size,
+                  peripheral_count:  peripheral_targets.size,
+                  history_count:     @history.size
+                }
+              end
+
+              private
+
+              def defocus_current_target
+                return unless @current_target_id
+
+                current = @targets[@current_target_id]
+                current&.peripheral!
+              end
+
+              def record_history(action, target_id)
+                entry = { action: action, target_id: target_id, at: Time.now.utc }
+                @history << entry
+                @history.shift if @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/regulation/helpers/attention_target.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Regulation
+          module Helpers
+            class AttentionTarget
+              include Constants
+
+              attr_reader :id, :name, :domain, :salience, :state, :attended_since
+
+              def initialize(id:, name:, domain: :general, salience: 0.5)
+                @id            = id
+                @name          = name
+                @domain        = domain
+                @salience      = salience.to_f.clamp(0.0, 1.0)
+                @state         = :peripheral
+                @attended_since = nil
+              end
+
+              def attend!
+                @state = :attended
+                @attended_since = Time.now.utc
+              end
+
+              def ignore!
+                @state = :ignored
+                @attended_since = nil
+              end
+
+              def peripheral!
+                @state = :peripheral
+                @attended_since = nil
+              end
+
+              def salient_enough_to_capture?
+                @salience >= CAPTURE_THRESHOLD
+              end
+
+              def duration
+                return nil unless @state == :attended && @attended_since
+
+                Time.now.utc - @attended_since
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  name:           @name,
+                  domain:         @domain,
+                  salience:       @salience.round(4),
+                  state:          @state,
+                  attended_since: @attended_since
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/regulation/helpers/constants.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Regulation
+          module Helpers
+            module Constants
+              MAX_TARGETS     = 30
+              MAX_HISTORY     = 200
+
+              DEFAULT_RESOURCE  = 1.0
+              RESOURCE_FLOOR    = 0.05
+              RESOURCE_CEILING  = 1.0
+              RESOURCE_DRAIN    = 0.02
+              RESOURCE_RECOVERY = 0.03
+
+              CAPTURE_THRESHOLD = 0.7
+
+              DEFAULT_ZOOM  = 0.5
+              ZOOM_FLOOR    = 0.1
+              ZOOM_CEILING  = 1.0
+
+              ATTENTION_MODES = %i[focused diffuse scanning resting captured].freeze
+              TARGET_STATES   = %i[attended peripheral ignored].freeze
+
+              RESOURCE_LABELS = {
+                (0.8..)     => :abundant,
+                (0.6...0.8) => :adequate,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :depleted
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/regulation/runners/attention_regulation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Regulation
+          module Runners
+            module AttentionRegulation
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def add_attention_target(name:, domain: :general, salience: 0.5, **)
+                target = controller.add_target(name: name, domain: domain, salience: salience)
+                return { success: false, reason: :limit_reached } unless target
+
+                { success: true, target_id: target.id, name: target.name, salience: target.salience }
+              end
+
+              def focus_attention(target_id:, **)
+                target = controller.focus_on(target_id: target_id)
+                return { success: false, reason: :not_found } unless target
+
+                { success: true, target_id: target.id, mode: :focused }
+              end
+
+              def defocus_attention(**)
+                controller.defocus
+                { success: true, mode: :diffuse }
+              end
+
+              def scan_attention(**)
+                captured = controller.scan
+                result = { success: true, mode: :scanning }
+                result[:captured_target_id] = captured.id if captured
+                result
+              end
+
+              def rest_attention(**)
+                controller.rest
+                { success: true, mode: :resting }
+              end
+
+              def zoom_attention_in(amount: 0.1, **)
+                zoom = controller.zoom_in(amount: amount)
+                { success: true, zoom: zoom.round(4) }
+              end
+
+              def zoom_attention_out(amount: 0.1, **)
+                zoom = controller.zoom_out(amount: amount)
+                { success: true, zoom: zoom.round(4) }
+              end
+
+              def current_attention_target(**)
+                target = controller.current_target
+                return { success: true, target: nil } unless target
+
+                { success: true, target: target.to_h }
+              end
+
+              def most_salient_target(**)
+                target = controller.most_salient
+                return { success: true, target: nil } unless target
+
+                { success: true, target: target.to_h }
+              end
+
+              def update_attention(**)
+                controller.tick
+                { success: true }.merge(controller.to_h)
+              end
+
+              def attention_regulation_stats(**)
+                { success: true }.merge(controller.to_h)
+              end
+
+              private
+
+              def controller
+                @controller ||= Helpers::AttentionController.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/regulation/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Regulation
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/regulation.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'regulation/version'
+require_relative 'regulation/helpers/constants'
+require_relative 'regulation/helpers/attention_controller'
+require_relative 'regulation/helpers/attention_target'
+require_relative 'regulation/runners/attention_regulation'
+require_relative 'regulation/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Regulation
+          # Sub-module for attention regulation: top-down and bottom-up attention control
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/relevance_theory/helpers/client.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module RelevanceTheory
+          module Helpers
+            class Client
+              include Runners::RelevanceTheory
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/relevance_theory/helpers/cognitive_input.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module RelevanceTheory
+          module Helpers
+            class CognitiveInput
+              include Constants
+
+              attr_reader :id, :content, :input_type, :context, :cognitive_effect,
+                          :processing_effort, :effect_type, :source_id, :created_at
+
+              def initialize(content:, input_type:, context:, cognitive_effect: DEFAULT_EFFECT,
+                             processing_effort: DEFAULT_EFFORT, effect_type: :new_implication,
+                             source_id: nil)
+                @id                = SecureRandom.uuid
+                @content           = content
+                @input_type        = input_type
+                @context           = context
+                @cognitive_effect  = cognitive_effect.clamp(EFFECT_FLOOR, EFFECT_CEILING)
+                @processing_effort = processing_effort.clamp(EFFORT_FLOOR, EFFORT_CEILING)
+                @effect_type       = effect_type
+                @source_id         = source_id
+                @created_at        = Time.now.utc
+              end
+
+              def relevance
+                @cognitive_effect / @processing_effort
+              end
+
+              def normalized_relevance
+                relevance.clamp(0.0, 1.0)
+              end
+
+              def relevance_label
+                nr = normalized_relevance
+                RELEVANCE_LABELS.find { |range, _| range.cover?(nr) }&.last || :irrelevant
+              end
+
+              def worth_processing?
+                normalized_relevance >= ATTENTION_THRESHOLD
+              end
+
+              def strengthen!(amount: 0.1)
+                @cognitive_effect = (@cognitive_effect + amount).clamp(EFFECT_FLOOR, EFFECT_CEILING)
+              end
+
+              def weaken!(amount: 0.1)
+                @cognitive_effect = (@cognitive_effect - amount).clamp(EFFECT_FLOOR, EFFECT_CEILING)
+              end
+
+              def increase_effort!(amount: 0.1)
+                @processing_effort = (@processing_effort + amount).clamp(EFFORT_FLOOR, EFFORT_CEILING)
+              end
+
+              def decay!
+                @cognitive_effect  = (@cognitive_effect - EFFECT_DECAY).clamp(EFFECT_FLOOR, EFFECT_CEILING)
+                @processing_effort = (@processing_effort + EFFORT_INFLATION).clamp(EFFORT_FLOOR, EFFORT_CEILING)
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  content:           @content,
+                  input_type:        @input_type,
+                  context:           @context,
+                  cognitive_effect:  @cognitive_effect,
+                  processing_effort: @processing_effort,
+                  relevance:         relevance.round(3),
+                  normalized:        normalized_relevance.round(3),
+                  relevance_label:   relevance_label,
+                  worth_processing:  worth_processing?,
+                  effect_type:       @effect_type,
+                  source_id:         @source_id,
+                  created_at:        @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/relevance_theory/helpers/constants.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module RelevanceTheory
+          module Helpers
+            module Constants
+              # Relevance = cognitive_effect / processing_effort
+              # Higher effect + lower effort = more relevant
+
+              INPUT_TYPES = %i[assertion question command observation inference].freeze
+
+              RELEVANCE_LABELS = {
+                (0.8..)     => :maximally_relevant,
+                (0.6...0.8) => :highly_relevant,
+                (0.4...0.6) => :moderately_relevant,
+                (0.2...0.4) => :marginally_relevant,
+                (..0.2)     => :irrelevant
+              }.freeze
+
+              EFFECT_TYPES = %i[
+                strengthening contradiction new_implication contextual_implication elimination
+              ].freeze
+
+              MAX_INPUTS   = 300
+              MAX_HISTORY  = 500
+              MAX_CONTEXTS = 50
+
+              DEFAULT_EFFECT  = 0.5
+              DEFAULT_EFFORT  = 0.5
+              EFFECT_FLOOR    = 0.0
+              EFFECT_CEILING  = 1.0
+              EFFORT_FLOOR    = 0.01
+              EFFORT_CEILING  = 1.0
+
+              # Decay rates
+              EFFECT_DECAY = 0.02
+              EFFORT_INFLATION = 0.01
+
+              # Attention allocation: inputs above this threshold get processed
+              ATTENTION_THRESHOLD = 0.3
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/relevance_theory/helpers/relevance_engine.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module RelevanceTheory
+          module Helpers
+            class RelevanceEngine
+              include Constants
+
+              attr_reader :history
+
+              def initialize
+                @inputs  = {}
+                @history = []
+              end
+
+              def submit_input(content:, input_type:, context:, cognitive_effect: DEFAULT_EFFECT,
+                               processing_effort: DEFAULT_EFFORT, effect_type: :new_implication,
+                               source_id: nil)
+                evict_oldest if @inputs.size >= MAX_INPUTS
+
+                input = CognitiveInput.new(
+                  content:           content,
+                  input_type:        input_type,
+                  context:           context,
+                  cognitive_effect:  cognitive_effect,
+                  processing_effort: processing_effort,
+                  effect_type:       effect_type,
+                  source_id:         source_id
+                )
+                @inputs[input.id] = input
+                record_history(:submitted, input.id)
+                input
+              end
+
+              def assess_relevance(input_id:)
+                input = @inputs[input_id]
+                return { success: false, reason: :not_found } unless input
+
+                {
+                  success:          true,
+                  relevance:        input.relevance.round(3),
+                  normalized:       input.normalized_relevance.round(3),
+                  label:            input.relevance_label,
+                  worth_processing: input.worth_processing?,
+                  effect:           input.cognitive_effect,
+                  effort:           input.processing_effort
+                }
+              end
+
+              def strengthen_input(input_id:, amount: 0.1)
+                input = @inputs[input_id]
+                return { success: false, reason: :not_found } unless input
+
+                input.strengthen!(amount: amount)
+                record_history(:strengthened, input_id)
+                { success: true, relevance: input.normalized_relevance.round(3) }
+              end
+
+              def weaken_input(input_id:, amount: 0.1)
+                input = @inputs[input_id]
+                return { success: false, reason: :not_found } unless input
+
+                input.weaken!(amount: amount)
+                record_history(:weakened, input_id)
+                { success: true, relevance: input.normalized_relevance.round(3) }
+              end
+
+              def worth_processing
+                @inputs.values.select(&:worth_processing?)
+              end
+
+              def irrelevant_inputs
+                @inputs.values.reject(&:worth_processing?)
+              end
+
+              def most_relevant(limit: 5)
+                @inputs.values.sort_by { |inp| -inp.normalized_relevance }.first(limit)
+              end
+
+              def by_context(context:)
+                @inputs.values.select { |inp| inp.context == context }
+              end
+
+              def by_effect_type(effect_type:)
+                @inputs.values.select { |inp| inp.effect_type == effect_type }
+              end
+
+              def context_relevance(context:)
+                ctx_inputs = by_context(context: context)
+                return 0.0 if ctx_inputs.empty?
+
+                ctx_inputs.sum(&:normalized_relevance) / ctx_inputs.size
+              end
+
+              def attention_budget
+                processable = worth_processing
+                total = @inputs.size.to_f
+                {
+                  total_inputs:     @inputs.size,
+                  worth_processing: processable.size,
+                  filtered_out:     @inputs.size - processable.size,
+                  processing_ratio: total.zero? ? 0.0 : (processable.size / total).round(3),
+                  avg_relevance:    avg_relevance.round(3)
+                }
+              end
+
+              def decay_all
+                @inputs.each_value(&:decay!)
+              end
+
+              def prune_irrelevant
+                ids = @inputs.select { |_id, inp| inp.normalized_relevance <= 0.05 }.keys
+                ids.each { |input_id| @inputs.delete(input_id) }
+                ids.size
+              end
+
+              def to_h
+                {
+                  total_inputs:  @inputs.size,
+                  processable:   worth_processing.size,
+                  avg_relevance: avg_relevance.round(3),
+                  history_count: @history.size
+                }
+              end
+
+              private
+
+              def avg_relevance
+                return 0.0 if @inputs.empty?
+
+                @inputs.values.sum(&:normalized_relevance) / @inputs.size
+              end
+
+              def evict_oldest
+                oldest_id = @inputs.min_by { |_id, inp| inp.created_at }&.first
+                @inputs.delete(oldest_id) if oldest_id
+              end
+
+              def record_history(event, input_id)
+                @history << { event: event, input_id: input_id, at: Time.now.utc }
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end