lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/blink/helpers/stimulus.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blink
+          module Helpers
+            class Stimulus
+              include Constants
+
+              attr_reader :id, :stimulus_type, :content, :salience, :processed,
+                          :processing_quality, :arrival_time, :created_at
+
+              def initialize(stimulus_type:, content:, salience: 0.5, arrival_time: nil)
+                @id                 = SecureRandom.uuid
+                @stimulus_type      = stimulus_type.to_sym
+                @content            = content
+                @salience           = salience.to_f.clamp(0.0, 1.0)
+                @processed          = false
+                @processing_quality = 0.0
+                @arrival_time       = arrival_time || Time.now.utc.to_f
+                @created_at         = Time.now.utc
+              end
+
+              def process!(quality:)
+                @processed = true
+                @processing_quality = quality.to_f.clamp(0.0, 1.0)
+                self
+              end
+
+              def salient?
+                @salience >= SALIENCE_THRESHOLD
+              end
+
+              def processing_label
+                match = PROCESSING_LABELS.find { |range, _| range.cover?(@processing_quality) }
+                match ? match.last : :blinked
+              end
+
+              def missed?
+                @processed && @processing_quality < 0.2
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  stimulus_type:      @stimulus_type,
+                  content:            @content,
+                  salience:           @salience,
+                  processed:          @processed,
+                  processing_quality: @processing_quality,
+                  processing_label:   processing_label,
+                  salient:            salient?,
+                  missed:             missed?,
+                  arrival_time:       @arrival_time,
+                  created_at:         @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/blink/runners/attentional_blink.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blink
+          module Runners
+            module AttentionalBlink
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def submit_stimulus(stimulus_type:, content:, salience: 0.5, **)
+                stimulus = engine.submit_stimulus(
+                  stimulus_type: stimulus_type,
+                  content:       content,
+                  salience:      salience
+                )
+                { success: true }.merge(stimulus.to_h)
+              end
+
+              def check_blink_status(**)
+                {
+                  success:        true,
+                  blink_active:   engine.blink_active?,
+                  recovery_level: engine.recovery_level,
+                  recovery_label: engine.recovery_label
+                }
+              end
+
+              def force_blink(duration: nil, **)
+                d = duration || Helpers::Constants::DEFAULT_BLINK_DURATION
+                result = engine.force_blink!(duration: d)
+                { success: true }.merge(result)
+              end
+
+              def force_recover(**)
+                result = engine.force_recover!
+                { success: true }.merge(result)
+              end
+
+              def adjust_blink_duration(duration:, **)
+                engine.adjust_blink_duration(duration: duration)
+                { success: true, blink_duration: duration }
+              end
+
+              def recent_stimuli_report(limit: 10, **)
+                stimuli = engine.recent_stimuli(limit: limit)
+                { success: true, count: stimuli.size, stimuli: stimuli.map(&:to_h) }
+              end
+
+              def missed_stimuli_report(**)
+                missed = engine.missed_stimuli
+                { success: true, count: missed.size, stimuli: missed.map(&:to_h) }
+              end
+
+              def stimuli_by_type_report(stimulus_type:, **)
+                stimuli = engine.stimuli_by_type(stimulus_type: stimulus_type)
+                { success: true, stimulus_type: stimulus_type.to_sym, count: stimuli.size,
+                  stimuli: stimuli.map(&:to_h) }
+              end
+
+              def blink_report(**)
+                engine.blink_report
+              end
+
+              def attentional_blink_stats(**)
+                engine.to_h
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'blink/version'
+require_relative 'blink/helpers/constants'
+require_relative 'blink/helpers/stimulus'
+require_relative 'blink/helpers/blink_engine'
+require_relative 'blink/runners/attentional_blink'
+require_relative 'blink/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Blink
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/economy/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/economy/helpers/constants'
+require 'legion/extensions/agentic/attention/economy/helpers/demand'
+require 'legion/extensions/agentic/attention/economy/helpers/attention_budget'
+require 'legion/extensions/agentic/attention/economy/runners/attention_economy'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Economy
+          class Client
+            include Runners::AttentionEconomy
+
+            def initialize(**)
+              @attention_budget = Helpers::AttentionBudget.new
+            end
+
+            private
+
+            attr_reader :attention_budget
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/economy/helpers/attention_budget.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+require_relative 'demand'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Economy
+          module Helpers
+            class AttentionBudget
+              include Constants
+
+              attr_reader :total_budget, :spent, :recovered
+
+              def initialize(total_budget: Constants::DEFAULT_BUDGET)
+                @demands       = {}
+                @total_budget  = total_budget
+                @spent         = 0.0
+                @recovered     = 0.0
+              end
+
+              def create_demand(label:, demand_type:, priority:, cost:, roi: 0.5)
+                raise ArgumentError, "demand_type must be one of #{Constants::DEMAND_TYPES.inspect}" unless Constants::DEMAND_TYPES.include?(demand_type)
+                raise ArgumentError, "max demands (#{Constants::MAX_DEMANDS}) reached" if @demands.size >= Constants::MAX_DEMANDS
+
+                demand = Demand.new(label: label, demand_type: demand_type, priority: priority, cost: cost, roi: roi)
+                @demands[demand.id] = demand
+                demand
+              end
+
+              def allocate(demand_id:, amount: nil)
+                demand = @demands.fetch(demand_id, nil)
+                return { allocated: false, reason: :not_found } unless demand
+
+                alloc_amount = (amount || demand.cost).clamp(Constants::MIN_ALLOCATION, 1.0)
+
+                return { allocated: false, reason: :insufficient_budget, available: available_budget.round(10) } if alloc_amount > available_budget
+
+                demand.allocate!(amount: alloc_amount)
+                @spent = (@spent + alloc_amount).round(10)
+                { allocated: true, demand_id: demand_id, amount: alloc_amount, remaining: available_budget.round(10) }
+              end
+
+              def deallocate(demand_id:)
+                demand = @demands.fetch(demand_id, nil)
+                return { deallocated: false, reason: :not_found } unless demand
+
+                freed = demand.allocated
+                demand.deallocate!
+                @spent = [(@spent - freed).round(10), 0.0].max
+                { deallocated: true, demand_id: demand_id, freed: freed.round(10), remaining: available_budget.round(10) }
+              end
+
+              def recover!(amount: Constants::BUDGET_RECOVERY_RATE)
+                previous = @spent
+                @spent   = [(@spent - amount).round(10), 0.0].max
+                delta    = (previous - @spent).round(10)
+                @recovered = (@recovered + delta).round(10)
+                { recovered: delta, spent: @spent, available: available_budget.round(10) }
+              end
+
+              def available_budget
+                (@total_budget - @spent).clamp(0.0, @total_budget).round(10)
+              end
+
+              def utilization
+                return 0.0 if @total_budget.zero?
+
+                (@spent / @total_budget).clamp(0.0, 1.0).round(10)
+              end
+
+              def prioritized_demands
+                @demands.values.sort_by { |d| -d.priority }
+              end
+
+              def best_roi(limit: 5)
+                @demands.values
+                        .sort_by { |d| -d.efficiency }
+                        .first(limit)
+              end
+
+              def over_budget?
+                @spent > @total_budget
+              end
+
+              def budget_pressure
+                utilization
+              end
+
+              def rebalance
+                return { rebalanced: 0 } unless over_budget?
+
+                sorted = @demands.values.select { |d| d.allocated.positive? }.sort_by(&:priority)
+                freed_count = 0
+
+                sorted.each do |demand|
+                  break unless over_budget?
+
+                  freed = demand.allocated
+                  demand.deallocate!
+                  @spent = [(@spent - freed).round(10), 0.0].max
+                  freed_count += 1
+                end
+
+                { rebalanced: freed_count, spent: @spent, available: available_budget.round(10) }
+              end
+
+              def budget_report
+                {
+                  total_budget:    @total_budget,
+                  spent:           @spent.round(10),
+                  available:       available_budget,
+                  utilization:     utilization,
+                  recovered:       @recovered.round(10),
+                  over_budget:     over_budget?,
+                  budget_pressure: budget_pressure,
+                  demand_count:    @demands.size,
+                  allocated_count: @demands.values.count { |d| d.allocated.positive? }
+                }
+              end
+
+              def to_h
+                budget_report.merge(
+                  demands: @demands.values.map(&:to_h)
+                )
+              end
+
+              def demands
+                @demands.values
+              end
+
+              def find_demand(demand_id)
+                @demands[demand_id]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Economy
+          module Helpers
+            module Constants
+              MAX_DEMANDS           = 200
+              DEFAULT_BUDGET        = 1.0
+              BUDGET_RECOVERY_RATE  = 0.05
+              MIN_ALLOCATION        = 0.01
+
+              PRIORITY_LABELS = {
+                (0.8..)     => :critical,
+                (0.6...0.8) => :high,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :background
+              }.freeze
+
+              EFFICIENCY_LABELS = {
+                (0.8..)     => :excellent,
+                (0.6...0.8) => :good,
+                (0.4...0.6) => :adequate,
+                (0.2...0.4) => :poor,
+                (..0.2)     => :wasted
+              }.freeze
+
+              DEMAND_TYPES = %i[task sensory social emotional cognitive maintenance].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/economy/helpers/demand.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'constants'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Economy
+          module Helpers
+            class Demand
+              include Constants
+
+              attr_reader :id, :label, :demand_type, :priority, :cost, :roi, :created_at
+              attr_accessor :allocated
+
+              def initialize(label:, demand_type:, priority:, cost:, roi: 0.5)
+                @id          = SecureRandom.uuid
+                @label       = label
+                @demand_type = demand_type
+                @priority    = priority.clamp(0.0, 1.0)
+                @cost        = cost.clamp(0.0, 1.0)
+                @roi         = roi.clamp(0.0, 1.0)
+                @allocated   = 0.0
+                @created_at  = Time.now.utc
+              end
+
+              def allocate!(amount:)
+                @allocated = amount.clamp(0.0, 1.0).round(10)
+              end
+
+              def deallocate!
+                @allocated = 0.0
+              end
+
+              def efficiency
+                return 0.0 if cost.zero?
+
+                (roi / cost).clamp(0.0, 1.0).round(10)
+              end
+
+              def efficiency_label
+                Constants::EFFICIENCY_LABELS.find { |range, _| range.cover?(efficiency) }&.last || :wasted
+              end
+
+              def priority_label
+                Constants::PRIORITY_LABELS.find { |range, _| range.cover?(priority) }&.last || :background
+              end
+
+              def to_h
+                {
+                  id:               id,
+                  label:            label,
+                  demand_type:      demand_type,
+                  priority:         priority,
+                  priority_label:   priority_label,
+                  cost:             cost,
+                  roi:              roi,
+                  allocated:        allocated,
+                  efficiency:       efficiency,
+                  efficiency_label: efficiency_label,
+                  created_at:       created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/economy/runners/attention_economy.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Economy
+          module Runners
+            module AttentionEconomy
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def add_demand(label:, demand_type:, priority:, cost:, roi: 0.5, **)
+                d = attention_budget.create_demand(
+                  label:       label,
+                  demand_type: demand_type,
+                  priority:    priority,
+                  cost:        cost,
+                  roi:         roi
+                )
+                Legion::Logging.info "[attention] demand added: id=#{d.id} label=#{label} priority=#{priority} cost=#{cost}"
+                { created: true, demand: d.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[attention] add_demand failed: #{e.message}"
+                { created: false, reason: e.message }
+              end
+
+              def allocate_demand(demand_id:, amount: nil, **)
+                result = attention_budget.allocate(demand_id: demand_id, amount: amount)
+                if result[:allocated]
+                  Legion::Logging.info "[attention] allocated: demand_id=#{demand_id} amount=#{result[:amount]} remaining=#{result[:remaining]}"
+                else
+                  Legion::Logging.debug "[attention] allocation failed: demand_id=#{demand_id} reason=#{result[:reason]}"
+                end
+                result
+              end
+
+              def deallocate_demand(demand_id:, **)
+                result = attention_budget.deallocate(demand_id: demand_id)
+                Legion::Logging.debug "[attention] deallocated: demand_id=#{demand_id} freed=#{result[:freed]}"
+                result
+              end
+
+              def recover_budget(amount: nil, **)
+                opts   = amount ? { amount: amount } : {}
+                result = attention_budget.recover!(**opts)
+                Legion::Logging.debug "[attention] recovery: delta=#{result[:recovered]} spent=#{result[:spent]}"
+                result
+              end
+
+              def prioritized_demands(**)
+                demands = attention_budget.prioritized_demands
+                Legion::Logging.debug "[attention] prioritized_demands: count=#{demands.size}"
+                { demands: demands.map(&:to_h), count: demands.size }
+              end
+
+              def best_roi_demands(limit: 5, **)
+                demands = attention_budget.best_roi(limit: limit)
+                Legion::Logging.debug "[attention] best_roi: limit=#{limit} count=#{demands.size}"
+                { demands: demands.map(&:to_h), count: demands.size }
+              end
+
+              def rebalance_budget(**)
+                result = attention_budget.rebalance
+                Legion::Logging.info "[attention] rebalance: freed=#{result[:rebalanced]} spent=#{result[:spent]}"
+                result
+              end
+
+              def attention_status(**)
+                report = attention_budget.budget_report
+                Legion::Logging.debug "[attention] status: utilization=#{report[:utilization]} demands=#{report[:demand_count]}"
+                report
+              end
+
+              def attention_snapshot(**)
+                attention_budget.to_h
+              end
+
+              private
+
+              def attention_budget
+                @attention_budget ||= Helpers::AttentionBudget.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/economy/version'
+require 'legion/extensions/agentic/attention/economy/helpers/constants'
+require 'legion/extensions/agentic/attention/economy/helpers/demand'
+require 'legion/extensions/agentic/attention/economy/helpers/attention_budget'
+require 'legion/extensions/agentic/attention/economy/runners/attention_economy'
+require 'legion/extensions/agentic/attention/economy/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Economy
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/actors/decay.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Attention::FeatureBinding::Runners::FeatureBinding
+              end
+
+              def runner_function
+                'update_feature_binding'
+              end
+
+              def time
+                30
+              end
+
+              def run_now?
+                false
+              end
+
+              def use_runner?
+                false
+              end
+
+              def check_subtask?
+                false
+              end
+
+              def generate_task?
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/feature_binding/client.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/feature_binding/helpers/constants'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/feature'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/bound_object'
+require 'legion/extensions/agentic/attention/feature_binding/helpers/binding_field'
+require 'legion/extensions/agentic/attention/feature_binding/runners/feature_binding'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module FeatureBinding
+          class Client
+            include Runners::FeatureBinding
+
+            def initialize(field: nil, **)
+              @field = field || Helpers::BindingField.new
+            end
+
+            private
+
+            attr_reader :field
+          end
+        end
+      end
+    end
+  end
+end