lex-agentic-inference 0.1.0

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        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
+  end
+end

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

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

data/lib/legion/extensions/agentic/inference/enactive_cognition.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/enactive_cognition/version'
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/sensorimotor_loop'
+require 'legion/extensions/agentic/inference/enactive_cognition/helpers/enaction_engine'
+require 'legion/extensions/agentic/inference/enactive_cognition/runners/enactive_cognition'
+require 'legion/extensions/agentic/inference/enactive_cognition/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module EnactiveCognition
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/expectation_violation/helpers/client.rb

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

data/lib/legion/extensions/agentic/inference/expectation_violation/helpers/constants.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module ExpectationViolation
+          module Helpers
+            module Constants
+              VIOLATION_TYPES = %i[positive negative neutral].freeze
+
+              VIOLATION_LABELS = {
+                (0.8..)       => :extreme_positive,
+                (0.3...0.8)   => :positive,
+                (-0.3...0.3)  => :neutral,
+                (-0.8...-0.3) => :negative,
+                (..-0.8)      => :extreme_negative
+              }.freeze
+
+              AROUSAL_LABELS = {
+                (0.8..)     => :highly_aroused,
+                (0.6...0.8) => :aroused,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :calm,
+                (..0.2)     => :unaffected
+              }.freeze
+
+              MAX_EXPECTATIONS = 200
+              MAX_VIOLATIONS   = 500
+              MAX_HISTORY      = 500
+
+              DEFAULT_EXPECTATION = 0.5
+              EXPECTATION_FLOOR   = 0.0
+              EXPECTATION_CEILING = 1.0
+
+              AROUSAL_BASE = 0.3
+              AROUSAL_MULTIPLIER = 0.7
+
+              ADAPTATION_RATE = 0.1
+              DECAY_RATE      = 0.02
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/expectation_violation/helpers/expectation.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module ExpectationViolation
+          module Helpers
+            class Expectation
+              include Constants
+
+              attr_reader :id, :context, :domain, :expected_value, :tolerance,
+                          :violation_count, :adaptation_count, :created_at
+
+              def initialize(context:, domain:, expected_value: DEFAULT_EXPECTATION, tolerance: 0.2)
+                @id               = SecureRandom.uuid
+                @context          = context
+                @domain           = domain
+                @expected_value   = expected_value.clamp(EXPECTATION_FLOOR, EXPECTATION_CEILING)
+                @tolerance        = tolerance.clamp(0.01, 0.5)
+                @violation_count  = 0
+                @adaptation_count = 0
+                @created_at       = Time.now.utc
+              end
+
+              def evaluate(actual_value:)
+                deviation = actual_value - @expected_value
+                violated = deviation.abs > @tolerance
+
+                if violated
+                  @violation_count += 1
+                  arousal = compute_arousal(deviation)
+                  violation_type = deviation.positive? ? :positive : :negative
+                  { violated: true, deviation: deviation.round(3), type: violation_type,
+                    arousal: arousal.round(3), arousal_label: arousal_label(arousal) }
+                else
+                  { violated: false, deviation: deviation.round(3), type: :neutral,
+                    arousal: 0.0, arousal_label: :unaffected }
+                end
+              end
+
+              def adapt!(actual_value:)
+                @expected_value += (actual_value - @expected_value) * ADAPTATION_RATE
+                @expected_value = @expected_value.clamp(EXPECTATION_FLOOR, EXPECTATION_CEILING)
+                @adaptation_count += 1
+              end
+
+              def violation_label(deviation)
+                VIOLATION_LABELS.find { |range, _| range.cover?(deviation) }&.last || :neutral
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  context:          @context,
+                  domain:           @domain,
+                  expected_value:   @expected_value.round(3),
+                  tolerance:        @tolerance,
+                  violation_count:  @violation_count,
+                  adaptation_count: @adaptation_count,
+                  created_at:       @created_at
+                }
+              end
+
+              private
+
+              def compute_arousal(deviation)
+                (AROUSAL_BASE + (deviation.abs * AROUSAL_MULTIPLIER)).clamp(0.0, 1.0)
+              end
+
+              def arousal_label(arousal)
+                AROUSAL_LABELS.find { |range, _| range.cover?(arousal) }&.last || :moderate
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/expectation_violation/helpers/violation_engine.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module ExpectationViolation
+          module Helpers
+            class ViolationEngine
+              include Constants
+
+              attr_reader :history
+
+              def initialize
+                @expectations = {}
+                @violations   = []
+                @history      = []
+              end
+
+              def create_expectation(context:, domain:, expected_value: DEFAULT_EXPECTATION, tolerance: 0.2)
+                evict_oldest if @expectations.size >= MAX_EXPECTATIONS
+
+                expectation = Expectation.new(
+                  context:        context,
+                  domain:         domain,
+                  expected_value: expected_value,
+                  tolerance:      tolerance
+                )
+                @expectations[expectation.id] = expectation
+                record_history(:created, expectation.id)
+                expectation
+              end
+
+              def evaluate_against(expectation_id:, actual_value:)
+                expectation = @expectations[expectation_id]
+                return { success: false, reason: :not_found } unless expectation
+
+                result = expectation.evaluate(actual_value: actual_value)
+
+                if result[:violated]
+                  @violations << {
+                    expectation_id: expectation_id,
+                    type:           result[:type],
+                    deviation:      result[:deviation],
+                    arousal:        result[:arousal],
+                    at:             Time.now.utc
+                  }
+                  trim_violations
+                end
+
+                record_history(:evaluated, expectation_id)
+                { success: true }.merge(result)
+              end
+
+              def adapt_expectation(expectation_id:, actual_value:)
+                expectation = @expectations[expectation_id]
+                return { success: false, reason: :not_found } unless expectation
+
+                expectation.adapt!(actual_value: actual_value)
+                record_history(:adapted, expectation_id)
+                { success: true, new_expected: expectation.expected_value.round(3) }
+              end
+
+              def recent_violations(limit: 10)
+                @violations.last(limit)
+              end
+
+              def violations_by_type(type:)
+                @violations.select { |vio| vio[:type] == type }
+              end
+
+              def expectations_by_domain(domain:)
+                @expectations.values.select { |exp| exp.domain == domain }
+              end
+
+              def most_violated(limit: 5)
+                @expectations.values.sort_by { |exp| -exp.violation_count }.first(limit)
+              end
+
+              def violation_rate
+                total = @expectations.values.sum(&:violation_count)
+                evals = @history.count { |entry| entry[:event] == :evaluated }
+                return 0.0 if evals.zero?
+
+                (total.to_f / evals).round(3)
+              end
+
+              def positive_violation_ratio
+                return 0.0 if @violations.empty?
+
+                positive = @violations.count { |vio| vio[:type] == :positive }
+                (positive.to_f / @violations.size).round(3)
+              end
+
+              def to_h
+                {
+                  total_expectations: @expectations.size,
+                  total_violations:   @violations.size,
+                  violation_rate:     violation_rate,
+                  positive_ratio:     positive_violation_ratio,
+                  history_count:      @history.size
+                }
+              end
+
+              private
+
+              def evict_oldest
+                oldest_id = @expectations.min_by { |_id, exp| exp.created_at }&.first
+                @expectations.delete(oldest_id) if oldest_id
+              end
+
+              def trim_violations
+                @violations.shift while @violations.size > MAX_VIOLATIONS
+              end
+
+              def record_history(event, expectation_id)
+                @history << { event: event, expectation_id: expectation_id, at: Time.now.utc }
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/expectation_violation/runners/expectation_violation.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module ExpectationViolation
+          module Runners
+            module ExpectationViolation
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_expectation(context:, domain:, expected_value: nil, tolerance: 0.2, **)
+                exp = engine.create_expectation(
+                  context:        context,
+                  domain:         domain.to_sym,
+                  expected_value: expected_value || Helpers::Constants::DEFAULT_EXPECTATION,
+                  tolerance:      tolerance
+                )
+                Legion::Logging.debug "[expectation_violation] create id=#{exp.id[0..7]} " \
+                                      "ctx=#{context} expected=#{exp.expected_value}"
+                { success: true, expectation: exp.to_h }
+              end
+
+              def evaluate_expectation(expectation_id:, actual_value:, **)
+                result = engine.evaluate_against(expectation_id: expectation_id, actual_value: actual_value)
+                Legion::Logging.debug "[expectation_violation] evaluate id=#{expectation_id[0..7]} " \
+                                      "violated=#{result[:violated]} type=#{result[:type]}"
+                result
+              end
+
+              def adapt_expectation_value(expectation_id:, actual_value:, **)
+                result = engine.adapt_expectation(expectation_id: expectation_id, actual_value: actual_value)
+                Legion::Logging.debug "[expectation_violation] adapt id=#{expectation_id[0..7]} " \
+                                      "new=#{result[:new_expected]}"
+                result
+              end
+
+              def recent_violations_report(limit: 10, **)
+                violations = engine.recent_violations(limit: limit)
+                Legion::Logging.debug "[expectation_violation] recent count=#{violations.size}"
+                { success: true, violations: violations, count: violations.size }
+              end
+
+              def violations_by_type_report(type:, **)
+                violations = engine.violations_by_type(type: type.to_sym)
+                Legion::Logging.debug '[expectation_violation] by_type ' \
+                                      "type=#{type} count=#{violations.size}"
+                { success: true, violations: violations, count: violations.size }
+              end
+
+              def most_violated_expectations(limit: 5, **)
+                exps = engine.most_violated(limit: limit)
+                Legion::Logging.debug "[expectation_violation] most_violated count=#{exps.size}"
+                { success: true, expectations: exps.map(&:to_h), count: exps.size }
+              end
+
+              def expectation_violation_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug '[expectation_violation] stats ' \
+                                      "total=#{stats[:total_expectations]}"
+                { success: true }.merge(stats)
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::ViolationEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/expectation_violation/version.rb

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

data/lib/legion/extensions/agentic/inference/expectation_violation.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'expectation_violation/version'
+require_relative 'expectation_violation/helpers/constants'
+require_relative 'expectation_violation/helpers/expectation'
+require_relative 'expectation_violation/helpers/violation_engine'
+require_relative 'expectation_violation/runners/expectation_violation'
+require_relative 'expectation_violation/helpers/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module ExpectationViolation
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/free_energy/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module FreeEnergy
+          class Client
+            include Runners::FreeEnergy
+
+            def initialize(engine: nil)
+              @engine = engine
+            end
+          end
+        end
+      end
+    end
+  end
+end