lex-agentic-attention 0.1.0

data/spec/legion/extensions/agentic/attention/economy/helpers/demand_spec.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/economy/helpers/demand'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Economy::Helpers::Demand do
+  subject(:demand) do
+    described_class.new(label: 'test task', demand_type: :task, priority: 0.7, cost: 0.3, roi: 0.9)
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(demand.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores label' do
+      expect(demand.label).to eq('test task')
+    end
+
+    it 'stores demand_type' do
+      expect(demand.demand_type).to eq(:task)
+    end
+
+    it 'clamps priority to [0.0, 1.0]' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 1.5, cost: 0.1)
+      expect(d.priority).to eq(1.0)
+    end
+
+    it 'clamps cost to [0.0, 1.0]' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: -0.1)
+      expect(d.cost).to eq(0.0)
+    end
+
+    it 'clamps roi to [0.0, 1.0]' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.1, roi: 2.0)
+      expect(d.roi).to eq(1.0)
+    end
+
+    it 'defaults roi to 0.5' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.1)
+      expect(d.roi).to eq(0.5)
+    end
+
+    it 'starts with 0.0 allocated' do
+      expect(demand.allocated).to eq(0.0)
+    end
+
+    it 'sets created_at' do
+      expect(demand.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#allocate!' do
+    it 'sets allocated amount' do
+      demand.allocate!(amount: 0.25)
+      expect(demand.allocated).to eq(0.25)
+    end
+
+    it 'clamps allocated to [0.0, 1.0]' do
+      demand.allocate!(amount: 1.5)
+      expect(demand.allocated).to eq(1.0)
+    end
+  end
+
+  describe '#deallocate!' do
+    it 'resets allocated to 0.0' do
+      demand.allocate!(amount: 0.3)
+      demand.deallocate!
+      expect(demand.allocated).to eq(0.0)
+    end
+  end
+
+  describe '#efficiency' do
+    it 'computes roi / cost' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.5, roi: 1.0)
+      expect(d.efficiency).to eq(1.0)
+    end
+
+    it 'returns 0.0 when cost is zero' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.0, roi: 0.8)
+      expect(d.efficiency).to eq(0.0)
+    end
+
+    it 'clamps efficiency to [0.0, 1.0]' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.1, roi: 1.0)
+      expect(d.efficiency).to be <= 1.0
+    end
+  end
+
+  describe '#efficiency_label' do
+    it 'returns :excellent for high efficiency' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.1, roi: 1.0)
+      expect(d.efficiency_label).to eq(:excellent)
+    end
+
+    it 'returns :wasted for zero efficiency' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.5, cost: 0.0, roi: 0.0)
+      expect(d.efficiency_label).to eq(:wasted)
+    end
+  end
+
+  describe '#priority_label' do
+    it 'returns :critical for priority 0.9' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.9, cost: 0.1)
+      expect(d.priority_label).to eq(:critical)
+    end
+
+    it 'returns :high for priority 0.7' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.7, cost: 0.1)
+      expect(d.priority_label).to eq(:high)
+    end
+
+    it 'returns :background for priority 0.1' do
+      d = described_class.new(label: 'x', demand_type: :task, priority: 0.1, cost: 0.1)
+      expect(d.priority_label).to eq(:background)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      h = demand.to_h
+      expect(h).to include(:id, :label, :demand_type, :priority, :priority_label, :cost, :roi, :allocated, :efficiency, :efficiency_label, :created_at)
+    end
+
+    it 'priority_label is correct in to_h' do
+      expect(demand.to_h[:priority_label]).to eq(:high)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/economy/runners/attention_economy_spec.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/economy/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Economy::Runners::AttentionEconomy do
+  let(:client) { Legion::Extensions::Agentic::Attention::Economy::Client.new }
+
+  def add_task(label: 'test', demand_type: :task, priority: 0.5, cost: 0.2, roi: 0.6)
+    client.add_demand(label: label, demand_type: demand_type, priority: priority, cost: cost, roi: roi)
+  end
+
+  describe '#add_demand' do
+    it 'returns created: true on success' do
+      result = add_task
+      expect(result[:created]).to be true
+    end
+
+    it 'returns demand hash on success' do
+      result = add_task
+      expect(result[:demand]).to include(:id, :label, :priority, :cost, :roi)
+    end
+
+    it 'returns created: false for invalid demand_type' do
+      result = client.add_demand(label: 'x', demand_type: :invalid, priority: 0.5, cost: 0.1)
+      expect(result[:created]).to be false
+      expect(result[:reason]).to include('demand_type')
+    end
+
+    it 'supports all valid demand types' do
+      %i[task sensory social emotional cognitive maintenance].each do |type|
+        result = client.add_demand(label: type.to_s, demand_type: type, priority: 0.5, cost: 0.1)
+        expect(result[:created]).to be true
+      end
+    end
+  end
+
+  describe '#allocate_demand' do
+    it 'allocates existing demand' do
+      demand_id = add_task[:demand][:id]
+      result = client.allocate_demand(demand_id: demand_id)
+      expect(result[:allocated]).to be true
+    end
+
+    it 'includes remaining budget in result' do
+      demand_id = add_task(cost: 0.3)[:demand][:id]
+      result = client.allocate_demand(demand_id: demand_id)
+      expect(result[:remaining]).to be_within(0.001).of(0.7)
+    end
+
+    it 'returns allocated: false for unknown demand' do
+      result = client.allocate_demand(demand_id: 'nonexistent')
+      expect(result[:allocated]).to be false
+    end
+
+    it 'supports explicit amount override' do
+      demand_id = add_task(cost: 0.3)[:demand][:id]
+      result = client.allocate_demand(demand_id: demand_id, amount: 0.1)
+      expect(result[:amount]).to eq(0.1)
+    end
+  end
+
+  describe '#deallocate_demand' do
+    it 'deallocates allocated demand' do
+      demand_id = add_task(cost: 0.3)[:demand][:id]
+      client.allocate_demand(demand_id: demand_id)
+      result = client.deallocate_demand(demand_id: demand_id)
+      expect(result[:deallocated]).to be true
+    end
+
+    it 'frees the allocated amount' do
+      demand_id = add_task(cost: 0.3)[:demand][:id]
+      client.allocate_demand(demand_id: demand_id)
+      result = client.deallocate_demand(demand_id: demand_id)
+      expect(result[:freed]).to be_within(0.001).of(0.3)
+    end
+  end
+
+  describe '#recover_budget' do
+    it 'recovers budget using default rate' do
+      demand_id = add_task(cost: 0.3)[:demand][:id]
+      client.allocate_demand(demand_id: demand_id)
+      result = client.recover_budget
+      expect(result[:recovered]).to be > 0
+    end
+
+    it 'accepts custom recovery amount' do
+      demand_id = add_task(cost: 0.5)[:demand][:id]
+      client.allocate_demand(demand_id: demand_id)
+      result = client.recover_budget(amount: 0.2)
+      expect(result[:spent]).to be_within(0.001).of(0.3)
+    end
+  end
+
+  describe '#prioritized_demands' do
+    it 'returns demands sorted by priority descending' do
+      client.add_demand(label: 'low', demand_type: :task, priority: 0.1, cost: 0.1)
+      client.add_demand(label: 'high', demand_type: :task, priority: 0.9, cost: 0.1)
+      result = client.prioritized_demands
+      expect(result[:demands].first[:priority]).to be >= result[:demands].last[:priority]
+    end
+
+    it 'returns count of demands' do
+      add_task(label: 'a')
+      add_task(label: 'b')
+      expect(client.prioritized_demands[:count]).to eq(2)
+    end
+  end
+
+  describe '#best_roi_demands' do
+    it 'returns top demands by efficiency' do
+      client.add_demand(label: 'poor', demand_type: :task, priority: 0.5, cost: 0.9, roi: 0.1)
+      client.add_demand(label: 'great', demand_type: :task, priority: 0.5, cost: 0.1, roi: 0.9)
+      result = client.best_roi_demands(limit: 1)
+      expect(result[:demands].first[:label]).to eq('great')
+    end
+
+    it 'defaults limit to 5' do
+      6.times { |i| add_task(label: "d#{i}") }
+      result = client.best_roi_demands
+      expect(result[:count]).to eq(5)
+    end
+  end
+
+  describe '#rebalance_budget' do
+    it 'returns rebalanced key' do
+      result = client.rebalance_budget
+      expect(result).to have_key(:rebalanced)
+    end
+
+    it 'returns 0 when not over budget' do
+      result = client.rebalance_budget
+      expect(result[:rebalanced]).to eq(0)
+    end
+  end
+
+  describe '#attention_status' do
+    it 'returns budget report keys' do
+      result = client.attention_status
+      %i[total_budget spent available utilization demand_count].each do |key|
+        expect(result).to have_key(key)
+      end
+    end
+
+    it 'reflects demand count' do
+      add_task
+      expect(client.attention_status[:demand_count]).to eq(1)
+    end
+  end
+
+  describe '#attention_snapshot' do
+    it 'includes demands array' do
+      add_task
+      result = client.attention_snapshot
+      expect(result[:demands]).to be_an(Array)
+      expect(result[:demands].size).to eq(1)
+    end
+
+    it 'includes budget metrics' do
+      result = client.attention_snapshot
+      expect(result).to include(:total_budget, :spent, :available)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/feature_binding/client_spec.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/feature_binding/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::FeatureBinding::Client do
+  subject(:client) { described_class.new }
+
+  it 'registers and binds features' do
+    client.register_feature(id: 'f:red', dimension: :color, value: :red)
+    client.register_feature(id: 'f:circle', dimension: :shape, value: :circle)
+    result = client.bind_features(feature_ids: %w[f:red f:circle], attention: true)
+    expect(result[:success]).to be true
+    expect(result[:object][:confirmed]).to be true
+  end
+
+  it 'reports stats' do
+    result = client.feature_binding_stats
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/agentic/attention/feature_binding/helpers/binding_field_spec.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::FeatureBinding::Helpers::BindingField do
+  subject(:field) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Attention::FeatureBinding::Helpers::Constants }
+
+  def register_pair
+    field.register_feature(id: 'f:red', dimension: :color, value: :red)
+    field.register_feature(id: 'f:circle', dimension: :shape, value: :circle)
+  end
+
+  describe '#register_feature' do
+    it 'adds a feature' do
+      f = field.register_feature(id: 'f:red', dimension: :color, value: :red)
+      expect(f).to be_a(Legion::Extensions::Agentic::Attention::FeatureBinding::Helpers::Feature)
+      expect(field.feature_count).to eq(1)
+    end
+
+    it 'returns existing feature on duplicate id' do
+      first = field.register_feature(id: 'f:red', dimension: :color, value: :red)
+      second = field.register_feature(id: 'f:red', dimension: :color, value: :blue)
+      expect(second).to equal(first)
+      expect(field.feature_count).to eq(1)
+    end
+
+    it 'enforces MAX_FEATURES limit' do
+      constants::MAX_FEATURES.times do |i|
+        field.register_feature(id: "f:#{i}", dimension: :color, value: i)
+      end
+      result = field.register_feature(id: 'f:overflow', dimension: :color, value: :x)
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#bind' do
+    it 'creates a bound object from feature ids' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      expect(obj).to be_a(Legion::Extensions::Agentic::Attention::FeatureBinding::Helpers::BoundObject)
+      expect(field.object_count).to eq(1)
+    end
+
+    it 'returns nil with fewer than 2 valid features' do
+      field.register_feature(id: 'f:red', dimension: :color, value: :red)
+      expect(field.bind(feature_ids: %w[f:red])).to be_nil
+    end
+
+    it 'ignores unknown feature ids' do
+      field.register_feature(id: 'f:red', dimension: :color, value: :red)
+      expect(field.bind(feature_ids: %w[f:red f:nonexistent])).to be_nil
+    end
+
+    it 'boosts strength with attention' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle], attention: true)
+      expect(obj.binding_strength).to be > constants::DEFAULT_BINDING_STRENGTH
+    end
+
+    it 'auto-confirms with attention' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle], attention: true)
+      expect(obj.confirmed?).to be true
+    end
+
+    it 'records binding in history' do
+      register_pair
+      field.bind(feature_ids: %w[f:red f:circle])
+      expect(field.binding_history.size).to eq(1)
+    end
+
+    it 'enforces MAX_OBJECTS limit' do
+      (constants::MAX_OBJECTS + 5).times do |i|
+        field.register_feature(id: "a:#{i}", dimension: :color, value: i)
+        field.register_feature(id: "b:#{i}", dimension: :shape, value: i)
+        field.bind(feature_ids: ["a:#{i}", "b:#{i}"])
+      end
+      expect(field.object_count).to be <= constants::MAX_OBJECTS
+    end
+  end
+
+  describe '#attend' do
+    it 'strengthens and confirms an object' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      result = field.attend(object_id: obj.id)
+      expect(result.confirmed?).to be true
+      expect(result.binding_strength).to be > constants::DEFAULT_BINDING_STRENGTH
+    end
+
+    it 'returns nil for unknown object' do
+      expect(field.attend(object_id: :nonexistent)).to be_nil
+    end
+  end
+
+  describe '#unbind' do
+    it 'removes an object' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      expect(field.unbind(object_id: obj.id)).to be true
+      expect(field.object_count).to eq(0)
+    end
+
+    it 'returns false for unknown object' do
+      expect(field.unbind(object_id: :nonexistent)).to be false
+    end
+  end
+
+  describe '#features_of' do
+    it 'returns features of a bound object' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      features = field.features_of(object_id: obj.id)
+      expect(features.size).to eq(2)
+      expect(features.first).to include(:id, :dimension)
+    end
+
+    it 'returns empty for unknown object' do
+      expect(field.features_of(object_id: :nope)).to be_empty
+    end
+  end
+
+  describe '#objects_with_feature' do
+    it 'finds objects containing a feature' do
+      register_pair
+      field.bind(feature_ids: %w[f:red f:circle])
+      results = field.objects_with_feature(feature_id: 'f:red')
+      expect(results.size).to eq(1)
+    end
+
+    it 'returns empty when no objects contain feature' do
+      expect(field.objects_with_feature(feature_id: 'f:none')).to be_empty
+    end
+  end
+
+  describe '#illusory_conjunctions' do
+    it 'returns objects in illusory state' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      obj.binding_strength = constants::ILLUSORY_CONJUNCTION_THRESHOLD - 0.1
+      illusions = field.illusory_conjunctions
+      expect(illusions.size).to eq(1)
+    end
+  end
+
+  describe '#unbound_features' do
+    it 'returns features not bound to any object' do
+      register_pair
+      field.register_feature(id: 'f:large', dimension: :size, value: :large)
+      field.bind(feature_ids: %w[f:red f:circle])
+      unbound = field.unbound_features
+      expect(unbound.size).to eq(1)
+      expect(unbound.first[:id]).to eq('f:large')
+    end
+  end
+
+  describe '#search_by_dimension' do
+    it 'filters by dimension' do
+      field.register_feature(id: 'f:red', dimension: :color, value: :red)
+      field.register_feature(id: 'f:blue', dimension: :color, value: :blue)
+      field.register_feature(id: 'f:circle', dimension: :shape, value: :circle)
+      results = field.search_by_dimension(dimension: :color)
+      expect(results.size).to eq(2)
+    end
+
+    it 'filters by dimension and value' do
+      field.register_feature(id: 'f:red', dimension: :color, value: :red)
+      field.register_feature(id: 'f:blue', dimension: :color, value: :blue)
+      results = field.search_by_dimension(dimension: :color, value: :red)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays features and objects' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      before_feature = field.features['f:red'].salience
+      before_obj = obj.binding_strength
+      field.decay_all
+      expect(field.features['f:red']&.salience || 0).to be <= before_feature
+      expect(obj.binding_strength).to be < before_obj
+    end
+
+    it 'removes faded features' do
+      field.register_feature(id: 'f:faint', dimension: :color, value: :x, salience: 0.06)
+      10.times { field.decay_all }
+      expect(field.features).not_to have_key('f:faint')
+    end
+
+    it 'removes dissolved objects' do
+      register_pair
+      obj = field.bind(feature_ids: %w[f:red f:circle])
+      obj.binding_strength = constants::BINDING_STRENGTH_FLOOR + constants::BINDING_DECAY
+      field.decay_all
+      expect(field.object_count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary hash' do
+      h = field.to_h
+      expect(h).to include(:features, :objects, :confirmed_objects, :illusory_count,
+                           :unbound_features, :history_size)
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/feature_binding/helpers/bound_object_spec.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Attention::FeatureBinding::Helpers::BoundObject do
+  subject(:obj) { described_class.new(id: :obj_one, feature_ids: %w[f:red f:circle]) }
+
+  let(:constants) { Legion::Extensions::Agentic::Attention::FeatureBinding::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'sets id and feature_ids' do
+      expect(obj.id).to eq(:obj_one)
+      expect(obj.feature_ids).to eq(%w[f:red f:circle])
+    end
+
+    it 'deduplicates feature_ids' do
+      o = described_class.new(id: :dup, feature_ids: %w[a a b])
+      expect(o.feature_ids).to eq(%w[a b])
+    end
+
+    it 'uses default binding strength' do
+      expect(obj.binding_strength).to eq(constants::DEFAULT_BINDING_STRENGTH)
+    end
+
+    it 'starts unconfirmed' do
+      expect(obj.confirmed?).to be false
+    end
+  end
+
+  describe '#confirm' do
+    it 'marks as confirmed' do
+      obj.confirm
+      expect(obj.confirmed?).to be true
+    end
+
+    it 'boosts binding strength' do
+      before = obj.binding_strength
+      obj.confirm
+      expect(obj.binding_strength).to be > before
+    end
+
+    it 'sets confirmed_at' do
+      obj.confirm
+      expect(obj.confirmed_at).to be_a(Time)
+    end
+  end
+
+  describe '#strengthen' do
+    it 'increases binding strength' do
+      before = obj.binding_strength
+      obj.strengthen
+      expect(obj.binding_strength).to be > before
+    end
+
+    it 'clamps at 1.0' do
+      10.times { obj.strengthen }
+      expect(obj.binding_strength).to be <= 1.0
+    end
+
+    it 'accepts custom amount' do
+      before = obj.binding_strength
+      obj.strengthen(0.01)
+      expect(obj.binding_strength).to eq(before + 0.01)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces binding strength' do
+      before = obj.binding_strength
+      obj.decay
+      expect(obj.binding_strength).to be < before
+    end
+
+    it 'does not go below zero' do
+      100.times { obj.decay }
+      expect(obj.binding_strength).to be >= 0.0
+    end
+  end
+
+  describe '#dissolved?' do
+    it 'returns false initially' do
+      expect(obj.dissolved?).to be false
+    end
+
+    it 'returns true at floor' do
+      obj.binding_strength = constants::BINDING_STRENGTH_FLOOR
+      expect(obj.dissolved?).to be true
+    end
+  end
+
+  describe '#state' do
+    it 'returns :tentative initially (unconfirmed, above illusory threshold)' do
+      expect(obj.state).to eq(:tentative)
+    end
+
+    it 'returns :bound when confirmed and above confirmation threshold' do
+      obj.binding_strength = constants::BINDING_CONFIRMATION_THRESHOLD + 0.1
+      obj.confirm
+      expect(obj.state).to eq(:bound)
+    end
+
+    it 'returns :illusory below illusory threshold but above floor' do
+      obj.binding_strength = constants::ILLUSORY_CONJUNCTION_THRESHOLD - 0.1
+      expect(obj.state).to eq(:illusory)
+    end
+
+    it 'returns :unbound at floor' do
+      obj.binding_strength = constants::BINDING_STRENGTH_FLOOR
+      expect(obj.state).to eq(:unbound)
+    end
+  end
+
+  describe '#feature_count' do
+    it 'returns number of features' do
+      expect(obj.feature_count).to eq(2)
+    end
+  end
+
+  describe '#includes_feature?' do
+    it 'returns true for included feature' do
+      expect(obj.includes_feature?('f:red')).to be true
+    end
+
+    it 'returns false for missing feature' do
+      expect(obj.includes_feature?('f:blue')).to be false
+    end
+  end
+
+  describe '#strength_label' do
+    it 'returns a symbol' do
+      expect(obj.strength_label).to be_a(Symbol)
+    end
+
+    it 'returns :weak for default strength (0.3)' do
+      expect(obj.strength_label).to eq(:weak)
+    end
+
+    it 'returns :solid for high strength' do
+      obj.binding_strength = 0.9
+      expect(obj.strength_label).to eq(:solid)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      h = obj.to_h
+      expect(h).to include(:id, :features, :feature_count, :binding_strength,
+                           :strength_label, :state, :state_label, :confirmed, :bound_at)
+    end
+  end
+end