lex-enactive-cognition 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bbed0f46a25d2c4adf962bc34b11afb26c788647d1df2d5a6576ff2adb37fe10
+  data.tar.gz: 32fc5bbcf961735ed8c9817bba4be8e558835fb25ac0392375b464d9a65fdef0
+SHA512:
+  metadata.gz: 2999787b0454927f7cae93ce1f84831fdd0b21dfe4e3742a13b16820acaaf55ff4f7bd56fd730b930f4f3f06b2e1ed85bc80326059a3365b09c70673d2a301d3
+  data.tar.gz: c93bbe503a804b7b4bb8f16dd9c3e2aa05aec38a00ffe69dbe086ca1e73d990efb58298e9ae71222d56fdb1bd9815ab57aaf1f0bea4093b24dfd08c4d81c4da4

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-enactive-cognition.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/enactive_cognition/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-enactive-cognition'
+  spec.version       = Legion::Extensions::EnactiveCognition::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Enactive Cognition'
+  spec.description   = "Varela's enactivism: cognition through action-perception loops, sensorimotor contingencies, and structural coupling"
+  spec.homepage      = 'https://github.com/LegionIO/lex-enactive-cognition'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-enactive-cognition'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-enactive-cognition'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-enactive-cognition'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-enactive-cognition/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-enactive-cognition.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/enactive_cognition/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/enactive_cognition/helpers/sensorimotor_loop'
+require 'legion/extensions/enactive_cognition/helpers/enaction_engine'
+require 'legion/extensions/enactive_cognition/runners/enactive_cognition'
+
+module Legion
+  module Extensions
+    module EnactiveCognition
+      class Client
+        include Runners::EnactiveCognition
+
+        def initialize(**)
+          @enaction_engine = Helpers::EnactionEngine.new
+        end
+
+        private
+
+        attr_reader :enaction_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/enactive_cognition/helpers/enaction_engine.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module EnactiveCognition
+      module Helpers
+        class EnactionEngine
+          attr_reader :couplings
+
+          def initialize
+            @couplings = {}
+          end
+
+          def create_coupling(action:, perception:, domain:, loop_type: :sensorimotor)
+            prune_to_limit
+
+            loop = SensorimotorLoop.new(
+              action:     action,
+              perception: perception,
+              domain:     domain,
+              loop_type:  loop_type
+            )
+            @couplings[loop.id] = loop
+            loop
+          end
+
+          def execute_action(coupling_id:, actual_perception:)
+            loop = @couplings[coupling_id]
+            return { success: false, reason: :not_found } unless loop
+
+            result = loop.execute!(actual_perception: actual_perception)
+            {
+              success:             true,
+              coupling_id:         coupling_id,
+              match:               result[:match],
+              coupling_strength:   result[:coupling_strength],
+              prediction_accuracy: result[:prediction_accuracy],
+              coupling_label:      loop.coupling_label
+            }
+          end
+
+          def adapt_coupling(coupling_id:, new_perception:)
+            loop = @couplings[coupling_id]
+            return { success: false, reason: :not_found } unless loop
+
+            loop.adapt_perception!(new_perception: new_perception)
+            { success: true, coupling_id: coupling_id, new_perception: new_perception }
+          end
+
+          def find_action_for(perception:)
+            best = @couplings.values
+                             .select(&:coupled?)
+                             .select { |lp| lp.perception.to_s == perception.to_s }
+                             .max_by(&:coupling_strength)
+            return nil unless best
+
+            best
+          end
+
+          def coupled_loops
+            @couplings.values.select(&:coupled?)
+          end
+
+          def by_domain(domain:)
+            @couplings.values.select { |lp| lp.domain.to_s == domain.to_s }
+          end
+
+          def by_type(loop_type:)
+            @couplings.values.select { |lp| lp.loop_type == loop_type }
+          end
+
+          def strongest_couplings(limit: 5)
+            @couplings.values.sort_by { |lp| -lp.coupling_strength }.first(limit)
+          end
+
+          def overall_coupling
+            return 0.0 if @couplings.empty?
+
+            total = @couplings.values.sum(&:coupling_strength)
+            total / @couplings.size
+          end
+
+          def decay_all
+            @couplings.each_value(&:decay!)
+          end
+
+          def prune_decoupled
+            @couplings.delete_if { |_id, lp| lp.coupling_strength < SensorimotorLoop::COUPLING_FLOOR + 0.05 }
+          end
+
+          def count
+            @couplings.size
+          end
+
+          def to_h
+            {
+              coupling_count:   @couplings.size,
+              coupled_count:    coupled_loops.size,
+              overall_coupling: overall_coupling.round(4),
+              strongest:        strongest_couplings(limit: 3).map(&:to_h)
+            }
+          end
+
+          private
+
+          def prune_to_limit
+            return unless @couplings.size >= SensorimotorLoop::MAX_COUPLINGS
+
+            weakest = @couplings.values.sort_by(&:coupling_strength).first(10)
+            weakest.each { |lp| @couplings.delete(lp.id) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/enactive_cognition/helpers/sensorimotor_loop.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module EnactiveCognition
+      module Helpers
+        class SensorimotorLoop
+          MAX_COUPLINGS  = 200
+          MAX_ACTIONS    = 500
+          MAX_PERCEPTIONS = 500
+          MAX_HISTORY = 300
+
+          DEFAULT_COUPLING_STRENGTH = 0.5
+          COUPLING_FLOOR   = 0.0
+          COUPLING_CEILING = 1.0
+
+          REINFORCEMENT_RATE = 0.1
+          DECOUPLING_RATE    = 0.15
+
+          PREDICTION_ACCURACY_THRESHOLD = 0.6
+
+          COUPLING_DECAY   = 0.02
+          STALE_THRESHOLD  = 120
+
+          COUPLING_LABELS = {
+            (0.8..)     => :entrained,
+            (0.6...0.8) => :coupled,
+            (0.4...0.6) => :forming,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :decoupled
+          }.freeze
+
+          LOOP_TYPES = %i[sensorimotor cognitive social].freeze
+
+          attr_reader :id, :action, :perception, :domain, :loop_type,
+                      :coupling_strength, :prediction_accuracy,
+                      :execution_count, :accurate_predictions,
+                      :created_at, :last_executed_at
+
+          def initialize(action:, perception:, domain:, loop_type: :sensorimotor)
+            @id                  = SecureRandom.uuid
+            @action              = action
+            @perception          = perception
+            @domain              = domain
+            @loop_type           = LOOP_TYPES.include?(loop_type) ? loop_type : :sensorimotor
+            @coupling_strength   = DEFAULT_COUPLING_STRENGTH
+            @execution_count     = 0
+            @accurate_predictions = 0
+            @prediction_accuracy = 0.0
+            @created_at          = Time.now.utc
+            @last_executed_at    = nil
+          end
+
+          def execute!(actual_perception:)
+            @execution_count    += 1
+            @last_executed_at    = Time.now.utc
+            match = actual_perception.to_s == @perception.to_s
+
+            if match
+              @accurate_predictions += 1
+              @coupling_strength     = (@coupling_strength + REINFORCEMENT_RATE).clamp(COUPLING_FLOOR, COUPLING_CEILING)
+            else
+              @coupling_strength = (@coupling_strength - DECOUPLING_RATE).clamp(COUPLING_FLOOR, COUPLING_CEILING)
+            end
+
+            @prediction_accuracy = @accurate_predictions.to_f / @execution_count
+            { match: match, coupling_strength: @coupling_strength, prediction_accuracy: @prediction_accuracy }
+          end
+
+          def coupled?
+            coupling_strength >= 0.6
+          end
+
+          def coupling_label
+            COUPLING_LABELS.each do |range, label|
+              return label if range.cover?(coupling_strength)
+            end
+            :decoupled
+          end
+
+          def adapt_perception!(new_perception:)
+            @perception = new_perception
+          end
+
+          def decay!
+            @coupling_strength = (@coupling_strength - COUPLING_DECAY).clamp(COUPLING_FLOOR, COUPLING_CEILING)
+          end
+
+          def stale?
+            return false if @last_executed_at.nil?
+
+            (Time.now.utc - @last_executed_at) > STALE_THRESHOLD
+          end
+
+          def to_h
+            {
+              id:                   @id,
+              action:               @action,
+              perception:           @perception,
+              domain:               @domain,
+              loop_type:            @loop_type,
+              coupling_strength:    @coupling_strength,
+              coupling_label:       coupling_label,
+              prediction_accuracy:  @prediction_accuracy,
+              execution_count:      @execution_count,
+              accurate_predictions: @accurate_predictions,
+              coupled:              coupled?,
+              created_at:           @created_at,
+              last_executed_at:     @last_executed_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/enactive_cognition/runners/enactive_cognition.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module EnactiveCognition
+      module Runners
+        module EnactiveCognition
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_sensorimotor_coupling(action:, perception:, domain:, loop_type: :sensorimotor, **)
+            type = loop_type.is_a?(Symbol) ? loop_type : loop_type.to_sym
+            loop = enaction_engine.create_coupling(
+              action:     action,
+              perception: perception,
+              domain:     domain,
+              loop_type:  type
+            )
+            Legion::Logging.debug "[enactive_cognition] created coupling id=#{loop.id[0..7]} " \
+                                  "action=#{action} domain=#{domain} type=#{type}"
+            { success: true, coupling: loop.to_h }
+          end
+
+          def execute_enactive_action(coupling_id:, actual_perception:, **)
+            result = enaction_engine.execute_action(
+              coupling_id:       coupling_id,
+              actual_perception: actual_perception
+            )
+            unless result[:success]
+              Legion::Logging.debug "[enactive_cognition] execute failed: #{coupling_id[0..7]} not found"
+              return result
+            end
+
+            Legion::Logging.debug "[enactive_cognition] executed #{coupling_id[0..7]} " \
+                                  "match=#{result[:match]} label=#{result[:coupling_label]}"
+            result
+          end
+
+          def adapt_sensorimotor_coupling(coupling_id:, new_perception:, **)
+            result = enaction_engine.adapt_coupling(
+              coupling_id:    coupling_id,
+              new_perception: new_perception
+            )
+            unless result[:success]
+              Legion::Logging.debug "[enactive_cognition] adapt failed: #{coupling_id[0..7]} not found"
+              return result
+            end
+
+            Legion::Logging.info "[enactive_cognition] adapted #{coupling_id[0..7]} new_perception=#{new_perception}"
+            result
+          end
+
+          def find_action_for_perception(perception:, **)
+            loop = enaction_engine.find_action_for(perception: perception)
+            unless loop
+              Legion::Logging.debug "[enactive_cognition] no coupled action found for perception=#{perception}"
+              return { found: false, perception: perception }
+            end
+
+            Legion::Logging.debug "[enactive_cognition] found action=#{loop.action} for perception=#{perception}"
+            { found: true, action: loop.action, coupling: loop.to_h }
+          end
+
+          def coupled_sensorimotor_loops(**)
+            loops = enaction_engine.coupled_loops
+            Legion::Logging.debug "[enactive_cognition] coupled loops count=#{loops.size}"
+            { loops: loops.map(&:to_h), count: loops.size }
+          end
+
+          def domain_couplings(domain:, **)
+            loops = enaction_engine.by_domain(domain: domain)
+            Legion::Logging.debug "[enactive_cognition] domain=#{domain} loops=#{loops.size}"
+            { domain: domain, loops: loops.map(&:to_h), count: loops.size }
+          end
+
+          def strongest_couplings(limit: 5, **)
+            loops = enaction_engine.strongest_couplings(limit: limit)
+            Legion::Logging.debug "[enactive_cognition] strongest couplings limit=#{limit} found=#{loops.size}"
+            { loops: loops.map(&:to_h), count: loops.size }
+          end
+
+          def overall_enactive_coupling(**)
+            strength = enaction_engine.overall_coupling
+            label    = coupling_label_for(strength)
+            Legion::Logging.debug "[enactive_cognition] overall_coupling=#{strength.round(3)} label=#{label}"
+            { overall_coupling: strength, coupling_label: label }
+          end
+
+          def update_enactive_cognition(decay: false, prune: false, **)
+            enaction_engine.decay_all if decay
+            enaction_engine.prune_decoupled if prune
+            Legion::Logging.debug "[enactive_cognition] update decay=#{decay} prune=#{prune} " \
+                                  "remaining=#{enaction_engine.count}"
+            { success: true, decay: decay, prune: prune, coupling_count: enaction_engine.count }
+          end
+
+          def enactive_cognition_stats(**)
+            stats = enaction_engine.to_h
+            Legion::Logging.debug "[enactive_cognition] stats couplings=#{stats[:coupling_count]} " \
+                                  "coupled=#{stats[:coupled_count]}"
+            { success: true, stats: stats }
+          end
+
+          private
+
+          def enaction_engine
+            @enaction_engine ||= Helpers::EnactionEngine.new
+          end
+
+          def coupling_label_for(strength)
+            Helpers::SensorimotorLoop::COUPLING_LABELS.each do |range, label|
+              return label if range.cover?(strength)
+            end
+            :decoupled
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/enactive_cognition/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module EnactiveCognition
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/enactive_cognition.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/enactive_cognition/version'
+require 'legion/extensions/enactive_cognition/helpers/sensorimotor_loop'
+require 'legion/extensions/enactive_cognition/helpers/enaction_engine'
+require 'legion/extensions/enactive_cognition/runners/enactive_cognition'
+
+module Legion
+  module Extensions
+    module EnactiveCognition
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/enactive_cognition/client_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/enactive_cognition/client'
+
+RSpec.describe Legion::Extensions::EnactiveCognition::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_sensorimotor_coupling)
+    expect(client).to respond_to(:execute_enactive_action)
+    expect(client).to respond_to(:adapt_sensorimotor_coupling)
+    expect(client).to respond_to(:find_action_for_perception)
+    expect(client).to respond_to(:coupled_sensorimotor_loops)
+    expect(client).to respond_to(:domain_couplings)
+    expect(client).to respond_to(:strongest_couplings)
+    expect(client).to respond_to(:overall_enactive_coupling)
+    expect(client).to respond_to(:update_enactive_cognition)
+    expect(client).to respond_to(:enactive_cognition_stats)
+  end
+end

data/spec/legion/extensions/enactive_cognition/helpers/enaction_engine_spec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/enactive_cognition/helpers/sensorimotor_loop'
+require 'legion/extensions/enactive_cognition/helpers/enaction_engine'
+
+RSpec.describe Legion::Extensions::EnactiveCognition::Helpers::EnactionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:coupling) do
+    engine.create_coupling(action: 'grasp', perception: 'grip', domain: 'motor')
+  end
+
+  describe '#create_coupling' do
+    it 'returns a SensorimotorLoop instance' do
+      expect(coupling).to be_a(Legion::Extensions::EnactiveCognition::Helpers::SensorimotorLoop)
+    end
+
+    it 'stores the coupling by id' do
+      expect(engine.couplings[coupling.id]).to eq(coupling)
+    end
+
+    it 'increments coupling count' do
+      engine.create_coupling(action: 'push', perception: 'moved', domain: 'motor')
+      expect(engine.count).to eq(1)
+    end
+
+    it 'defaults loop_type to :sensorimotor' do
+      expect(coupling.loop_type).to eq(:sensorimotor)
+    end
+
+    it 'accepts explicit loop_type' do
+      lp = engine.create_coupling(action: 'think', perception: 'clarity', domain: 'cog', loop_type: :cognitive)
+      expect(lp.loop_type).to eq(:cognitive)
+    end
+  end
+
+  describe '#execute_action' do
+    it 'returns success: true on match' do
+      result = engine.execute_action(coupling_id: coupling.id, actual_perception: 'grip')
+      expect(result[:success]).to be true
+      expect(result[:match]).to be true
+    end
+
+    it 'returns success: true on mismatch' do
+      result = engine.execute_action(coupling_id: coupling.id, actual_perception: 'slip')
+      expect(result[:success]).to be true
+      expect(result[:match]).to be false
+    end
+
+    it 'returns success: false for missing coupling' do
+      result = engine.execute_action(coupling_id: 'nonexistent', actual_perception: 'grip')
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+
+    it 'includes coupling_label in result' do
+      result = engine.execute_action(coupling_id: coupling.id, actual_perception: 'grip')
+      expect(result[:coupling_label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#adapt_coupling' do
+    it 'updates the coupling perception' do
+      engine.adapt_coupling(coupling_id: coupling.id, new_perception: 'firm_grip')
+      expect(engine.couplings[coupling.id].perception).to eq('firm_grip')
+    end
+
+    it 'returns success: true' do
+      result = engine.adapt_coupling(coupling_id: coupling.id, new_perception: 'firm_grip')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns success: false for missing coupling' do
+      result = engine.adapt_coupling(coupling_id: 'bad', new_perception: 'x')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#find_action_for' do
+    before do
+      5.times { engine.execute_action(coupling_id: coupling.id, actual_perception: 'grip') }
+    end
+
+    it 'returns the loop when it is coupled and perception matches' do
+      result = engine.find_action_for(perception: 'grip')
+      if coupling.coupled?
+        expect(result).not_to be_nil
+        expect(result.action).to eq('grasp')
+      else
+        expect(result).to be_nil
+      end
+    end
+
+    it 'returns nil when perception does not match any coupled loop' do
+      result = engine.find_action_for(perception: 'unknown_perception')
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#coupled_loops' do
+    it 'returns empty when nothing is coupled' do
+      engine.create_coupling(action: 'act', perception: 'per', domain: 'dom')
+      expect(engine.coupled_loops).to be_empty
+    end
+
+    it 'returns loops above coupling threshold' do
+      c2 = engine.create_coupling(action: 'act2', perception: 'per2', domain: 'dom2')
+      allow(c2).to receive(:coupled?).and_return(true)
+      expect(engine.coupled_loops).to include(c2)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns loops in the specified domain' do
+      engine.create_coupling(action: 'act', perception: 'per', domain: 'motor')
+      engine.create_coupling(action: 'speak', perception: 'heard', domain: 'social')
+      expect(engine.by_domain(domain: 'motor').size).to eq(1)
+    end
+  end
+
+  describe '#by_type' do
+    it 'returns loops of the specified type' do
+      engine.create_coupling(action: 'act', perception: 'per', domain: 'dom', loop_type: :cognitive)
+      engine.create_coupling(action: 'act2', perception: 'per2', domain: 'dom2', loop_type: :social)
+      expect(engine.by_type(loop_type: :cognitive).size).to eq(1)
+    end
+  end
+
+  describe '#strongest_couplings' do
+    it 'returns at most limit couplings sorted by strength desc' do
+      3.times { |i| engine.create_coupling(action: "a#{i}", perception: "p#{i}", domain: 'dom') }
+      result = engine.strongest_couplings(limit: 2)
+      expect(result.size).to be <= 2
+    end
+  end
+
+  describe '#overall_coupling' do
+    it 'returns 0.0 when no couplings exist' do
+      expect(engine.overall_coupling).to eq(0.0)
+    end
+
+    it 'returns mean coupling strength' do
+      engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      expect(engine.overall_coupling).to eq(
+        Legion::Extensions::EnactiveCognition::Helpers::SensorimotorLoop::DEFAULT_COUPLING_STRENGTH
+      )
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces coupling strength of all loops' do
+      lp = engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      before = lp.coupling_strength
+      engine.decay_all
+      expect(lp.coupling_strength).to be < before
+    end
+  end
+
+  describe '#prune_decoupled' do
+    it 'removes very weak couplings' do
+      lp = engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      100.times { lp.execute!(actual_perception: 'miss') }
+      count_before = engine.count
+      engine.prune_decoupled
+      expect(engine.count).to be <= count_before
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes expected keys' do
+      result = engine.to_h
+      expect(result).to include(:coupling_count, :coupled_count, :overall_coupling, :strongest)
+    end
+
+    it 'rounds overall_coupling to 4 decimal places' do
+      engine.create_coupling(action: 'a', perception: 'p', domain: 'd')
+      result = engine.to_h
+      expect(result[:overall_coupling]).to be_a(Float)
+    end
+  end
+end

data/spec/legion/extensions/enactive_cognition/helpers/sensorimotor_loop_spec.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/enactive_cognition/helpers/sensorimotor_loop'
+
+RSpec.describe Legion::Extensions::EnactiveCognition::Helpers::SensorimotorLoop do
+  subject(:loop_obj) do
+    described_class.new(action: 'reach', perception: 'contact', domain: 'motor')
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(loop_obj.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets default coupling strength' do
+      expect(loop_obj.coupling_strength).to eq(described_class::DEFAULT_COUPLING_STRENGTH)
+    end
+
+    it 'defaults loop_type to :sensorimotor' do
+      expect(loop_obj.loop_type).to eq(:sensorimotor)
+    end
+
+    it 'accepts valid loop types' do
+      cognitive = described_class.new(action: 'think', perception: 'insight', domain: 'cog', loop_type: :cognitive)
+      expect(cognitive.loop_type).to eq(:cognitive)
+    end
+
+    it 'falls back to :sensorimotor for invalid loop_type' do
+      bad = described_class.new(action: 'x', perception: 'y', domain: 'z', loop_type: :invalid)
+      expect(bad.loop_type).to eq(:sensorimotor)
+    end
+
+    it 'starts with zero execution count' do
+      expect(loop_obj.execution_count).to eq(0)
+    end
+
+    it 'starts with zero accurate_predictions' do
+      expect(loop_obj.accurate_predictions).to eq(0)
+    end
+  end
+
+  describe '#execute!' do
+    context 'when actual matches expected perception' do
+      it 'increments execution_count' do
+        loop_obj.execute!(actual_perception: 'contact')
+        expect(loop_obj.execution_count).to eq(1)
+      end
+
+      it 'increments accurate_predictions' do
+        loop_obj.execute!(actual_perception: 'contact')
+        expect(loop_obj.accurate_predictions).to eq(1)
+      end
+
+      it 'strengthens coupling' do
+        before = loop_obj.coupling_strength
+        loop_obj.execute!(actual_perception: 'contact')
+        expect(loop_obj.coupling_strength).to be > before
+      end
+
+      it 'returns match: true' do
+        result = loop_obj.execute!(actual_perception: 'contact')
+        expect(result[:match]).to be true
+      end
+
+      it 'does not exceed COUPLING_CEILING' do
+        20.times { loop_obj.execute!(actual_perception: 'contact') }
+        expect(loop_obj.coupling_strength).to be <= described_class::COUPLING_CEILING
+      end
+    end
+
+    context 'when actual does not match expected perception' do
+      it 'weakens coupling' do
+        before = loop_obj.coupling_strength
+        loop_obj.execute!(actual_perception: 'no_contact')
+        expect(loop_obj.coupling_strength).to be < before
+      end
+
+      it 'returns match: false' do
+        result = loop_obj.execute!(actual_perception: 'no_contact')
+        expect(result[:match]).to be false
+      end
+
+      it 'does not fall below COUPLING_FLOOR' do
+        20.times { loop_obj.execute!(actual_perception: 'no_contact') }
+        expect(loop_obj.coupling_strength).to be >= described_class::COUPLING_FLOOR
+      end
+
+      it 'does not increment accurate_predictions' do
+        loop_obj.execute!(actual_perception: 'no_contact')
+        expect(loop_obj.accurate_predictions).to eq(0)
+      end
+    end
+
+    it 'updates prediction_accuracy' do
+      3.times { loop_obj.execute!(actual_perception: 'contact') }
+      loop_obj.execute!(actual_perception: 'miss')
+      expect(loop_obj.prediction_accuracy).to eq(0.75)
+    end
+
+    it 'sets last_executed_at' do
+      loop_obj.execute!(actual_perception: 'contact')
+      expect(loop_obj.last_executed_at).not_to be_nil
+    end
+  end
+
+  describe '#coupled?' do
+    it 'returns false at default strength (0.5)' do
+      expect(loop_obj.coupled?).to be false
+    end
+
+    it 'returns true when strength reaches 0.6' do
+      loop_obj.execute!(actual_perception: 'contact')
+      loop_obj.execute!(actual_perception: 'contact')
+      if loop_obj.coupling_strength >= 0.6
+        expect(loop_obj.coupled?).to be true
+      else
+        expect(loop_obj.coupled?).to be false
+      end
+    end
+  end
+
+  describe '#coupling_label' do
+    it 'returns :forming at default strength 0.5' do
+      expect(loop_obj.coupling_label).to eq(:forming)
+    end
+
+    it 'returns :entrained at strength 0.9' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.9)
+      expect(loop_obj.coupling_label).to eq(:entrained)
+    end
+
+    it 'returns :decoupled at strength 0.1' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.1)
+      expect(loop_obj.coupling_label).to eq(:decoupled)
+    end
+
+    it 'returns :weak at strength 0.25' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.25)
+      expect(loop_obj.coupling_label).to eq(:weak)
+    end
+
+    it 'returns :coupled at strength 0.7' do
+      allow(loop_obj).to receive(:coupling_strength).and_return(0.7)
+      expect(loop_obj.coupling_label).to eq(:coupled)
+    end
+  end
+
+  describe '#adapt_perception!' do
+    it 'updates the expected perception' do
+      loop_obj.adapt_perception!(new_perception: 'soft_contact')
+      expect(loop_obj.perception).to eq('soft_contact')
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces coupling_strength by COUPLING_DECAY' do
+      before = loop_obj.coupling_strength
+      loop_obj.decay!
+      expect(loop_obj.coupling_strength).to eq((before - described_class::COUPLING_DECAY).clamp(0.0, 1.0))
+    end
+
+    it 'does not fall below COUPLING_FLOOR' do
+      100.times { loop_obj.decay! }
+      expect(loop_obj.coupling_strength).to be >= described_class::COUPLING_FLOOR
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      hash = loop_obj.to_h
+      expect(hash).to include(
+        :id, :action, :perception, :domain, :loop_type,
+        :coupling_strength, :coupling_label, :prediction_accuracy,
+        :execution_count, :accurate_predictions, :coupled,
+        :created_at, :last_executed_at
+      )
+    end
+
+    it 'reflects current coupling_label' do
+      hash = loop_obj.to_h
+      expect(hash[:coupling_label]).to eq(loop_obj.coupling_label)
+    end
+  end
+end

data/spec/legion/extensions/enactive_cognition/runners/enactive_cognition_spec.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/enactive_cognition/client'
+
+RSpec.describe Legion::Extensions::EnactiveCognition::Runners::EnactiveCognition do
+  let(:client) { Legion::Extensions::EnactiveCognition::Client.new }
+
+  def make_coupling(action: 'press', perception: 'click', domain: 'motor', loop_type: :sensorimotor)
+    client.create_sensorimotor_coupling(
+      action:     action,
+      perception: perception,
+      domain:     domain,
+      loop_type:  loop_type
+    )
+  end
+
+  describe '#create_sensorimotor_coupling' do
+    it 'returns success: true' do
+      result = make_coupling
+      expect(result[:success]).to be true
+    end
+
+    it 'includes coupling hash with uuid id' do
+      result = make_coupling
+      expect(result[:coupling][:id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'reflects the given action and perception' do
+      result = make_coupling(action: 'push', perception: 'moved')
+      expect(result[:coupling][:action]).to eq('push')
+      expect(result[:coupling][:perception]).to eq('moved')
+    end
+
+    it 'accepts string loop_type and converts to symbol' do
+      result = client.create_sensorimotor_coupling(
+        action:     'x',
+        perception: 'y',
+        domain:     'z',
+        loop_type:  'cognitive'
+      )
+      expect(result[:coupling][:loop_type]).to eq(:cognitive)
+    end
+  end
+
+  describe '#execute_enactive_action' do
+    let(:coupling_id) { make_coupling[:coupling][:id] }
+
+    it 'returns success: true on matching perception' do
+      result = client.execute_enactive_action(coupling_id: coupling_id, actual_perception: 'click')
+      expect(result[:success]).to be true
+      expect(result[:match]).to be true
+    end
+
+    it 'returns success: true on mismatching perception' do
+      result = client.execute_enactive_action(coupling_id: coupling_id, actual_perception: 'silence')
+      expect(result[:success]).to be true
+      expect(result[:match]).to be false
+    end
+
+    it 'returns success: false for unknown coupling_id' do
+      result = client.execute_enactive_action(coupling_id: 'bad-id', actual_perception: 'click')
+      expect(result[:success]).to be false
+    end
+
+    it 'includes coupling_label in result' do
+      result = client.execute_enactive_action(coupling_id: coupling_id, actual_perception: 'click')
+      expect(result[:coupling_label]).to be_a(Symbol)
+    end
+  end
+
+  describe '#adapt_sensorimotor_coupling' do
+    let(:coupling_id) { make_coupling[:coupling][:id] }
+
+    it 'returns success: true' do
+      result = client.adapt_sensorimotor_coupling(coupling_id: coupling_id, new_perception: 'soft_click')
+      expect(result[:success]).to be true
+    end
+
+    it 'returns new_perception in result' do
+      result = client.adapt_sensorimotor_coupling(coupling_id: coupling_id, new_perception: 'soft_click')
+      expect(result[:new_perception]).to eq('soft_click')
+    end
+
+    it 'returns success: false for missing coupling' do
+      result = client.adapt_sensorimotor_coupling(coupling_id: 'missing', new_perception: 'x')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#find_action_for_perception' do
+    it 'returns found: false when nothing is coupled' do
+      result = client.find_action_for_perception(perception: 'click')
+      expect(result[:found]).to be false
+    end
+
+    it 'returns found: true when a coupled loop matches' do
+      id = make_coupling[:coupling][:id]
+      5.times { client.execute_enactive_action(coupling_id: id, actual_perception: 'click') }
+      result = client.find_action_for_perception(perception: 'click')
+      # may or may not be coupled depending on starting strength + reinforcement
+      if result[:found]
+        expect(result[:action]).to eq('press')
+      else
+        expect(result[:found]).to be false
+      end
+    end
+  end
+
+  describe '#coupled_sensorimotor_loops' do
+    it 'returns loops and count' do
+      result = client.coupled_sensorimotor_loops
+      expect(result).to include(:loops, :count)
+      expect(result[:loops]).to be_an(Array)
+    end
+
+    it 'count is zero initially' do
+      expect(client.coupled_sensorimotor_loops[:count]).to eq(0)
+    end
+  end
+
+  describe '#domain_couplings' do
+    before { make_coupling(domain: 'motor') }
+
+    it 'returns loops in the domain' do
+      result = client.domain_couplings(domain: 'motor')
+      expect(result[:domain]).to eq('motor')
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'returns zero for unknown domain' do
+      result = client.domain_couplings(domain: 'unknown')
+      expect(result[:count]).to eq(0)
+    end
+  end
+
+  describe '#strongest_couplings' do
+    before { 3.times { |i| make_coupling(action: "act#{i}", perception: "per#{i}", domain: 'dom') } }
+
+    it 'returns loops array' do
+      result = client.strongest_couplings(limit: 2)
+      expect(result[:loops].size).to be <= 2
+    end
+
+    it 'uses default limit of 5' do
+      result = client.strongest_couplings
+      expect(result[:loops].size).to be <= 5
+    end
+  end
+
+  describe '#overall_enactive_coupling' do
+    it 'returns overall_coupling and coupling_label' do
+      result = client.overall_enactive_coupling
+      expect(result).to include(:overall_coupling, :coupling_label)
+    end
+
+    it 'returns 0.0 when no couplings exist' do
+      expect(client.overall_enactive_coupling[:overall_coupling]).to eq(0.0)
+    end
+
+    it 'returns :decoupled label when no couplings' do
+      expect(client.overall_enactive_coupling[:coupling_label]).to eq(:decoupled)
+    end
+
+    it 'returns :forming label at default strength' do
+      make_coupling
+      result = client.overall_enactive_coupling
+      expect(result[:coupling_label]).to eq(:forming)
+    end
+  end
+
+  describe '#update_enactive_cognition' do
+    before { make_coupling }
+
+    it 'returns success: true' do
+      result = client.update_enactive_cognition
+      expect(result[:success]).to be true
+    end
+
+    it 'decays couplings when decay: true' do
+      before_strength = client.strongest_couplings(limit: 1)[:loops].first[:coupling_strength]
+      client.update_enactive_cognition(decay: true)
+      after_strength = client.strongest_couplings(limit: 1)[:loops].first[:coupling_strength]
+      expect(after_strength).to be < before_strength
+    end
+
+    it 'reflects coupling_count in result' do
+      result = client.update_enactive_cognition
+      expect(result[:coupling_count]).to be >= 1
+    end
+  end
+
+  describe '#enactive_cognition_stats' do
+    it 'returns success: true' do
+      result = client.enactive_cognition_stats
+      expect(result[:success]).to be true
+    end
+
+    it 'includes stats hash' do
+      result = client.enactive_cognition_stats
+      expect(result[:stats]).to include(:coupling_count, :coupled_count, :overall_coupling)
+    end
+
+    it 'reports zero coupling_count when empty' do
+      result = client.enactive_cognition_stats
+      expect(result[:stats][:coupling_count]).to eq(0)
+    end
+
+    it 'increments coupling_count after creating a coupling' do
+      make_coupling
+      result = client.enactive_cognition_stats
+      expect(result[:stats][:coupling_count]).to eq(1)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/enactive_cognition'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: lex-enactive-cognition
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Varela''s enactivism: cognition through action-perception loops, sensorimotor
+  contingencies, and structural coupling'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-enactive-cognition.gemspec
+- lib/legion/extensions/enactive_cognition.rb
+- lib/legion/extensions/enactive_cognition/client.rb
+- lib/legion/extensions/enactive_cognition/helpers/enaction_engine.rb
+- lib/legion/extensions/enactive_cognition/helpers/sensorimotor_loop.rb
+- lib/legion/extensions/enactive_cognition/runners/enactive_cognition.rb
+- lib/legion/extensions/enactive_cognition/version.rb
+- spec/legion/extensions/enactive_cognition/client_spec.rb
+- spec/legion/extensions/enactive_cognition/helpers/enaction_engine_spec.rb
+- spec/legion/extensions/enactive_cognition/helpers/sensorimotor_loop_spec.rb
+- spec/legion/extensions/enactive_cognition/runners/enactive_cognition_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-enactive-cognition
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-enactive-cognition
+  source_code_uri: https://github.com/LegionIO/lex-enactive-cognition
+  documentation_uri: https://github.com/LegionIO/lex-enactive-cognition
+  changelog_uri: https://github.com/LegionIO/lex-enactive-cognition
+  bug_tracker_uri: https://github.com/LegionIO/lex-enactive-cognition/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Enactive Cognition
+test_files: []