lex-cognitive-pendulum 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f99df9563513ea075e00bd072f2e4c2157e0bcebb7ccd533c824e45bf26ac574
+  data.tar.gz: c63527d035a0a23b9d51e0be50316fcf006713c2f1cff1227451a189009430c8
+SHA512:
+  metadata.gz: c97ffd26c6de16c060383d895d7377d383f1457d153006ffba08b021986558b38c954227e88e1a71993aa0cbc3676be90bda5f5640aa89ab4bc14955f3d855b4
+  data.tar.gz: e27db8176a304f1ec1de57cc1c25bd91db0e769929a8dfd4aa618a17b300e2978ccfcd6e9ed3548f97ab18a732081af9e5293fb225b34fa5c57b1124d549fd11

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-cognitive-pendulum.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_pendulum/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-pendulum'
+  spec.version       = Legion::Extensions::CognitivePendulum::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Pendulum'
+  spec.description   = 'Models oscillation between cognitive poles with amplitude, period, damping, and resonance detection'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-pendulum'
+  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-cognitive-pendulum'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-pendulum'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-pendulum'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-pendulum/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-pendulum.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_pendulum/helpers/constants'
+require 'legion/extensions/cognitive_pendulum/helpers/pendulum'
+require 'legion/extensions/cognitive_pendulum/helpers/pendulum_engine'
+require 'legion/extensions/cognitive_pendulum/runners/cognitive_pendulum'
+
+module Legion
+  module Extensions
+    module CognitivePendulum
+      class Client
+        include Runners::CognitivePendulum
+
+        def initialize(**)
+          @pendulum_engine = Helpers::PendulumEngine.new
+        end
+
+        private
+
+        attr_reader :pendulum_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_pendulum/helpers/constants.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePendulum
+      module Helpers
+        module Constants
+          POLE_PAIRS = {
+            certainty_doubt:      %i[certainty doubt],
+            focus_diffusion:      %i[focus diffusion],
+            analysis_intuition:   %i[analysis intuition],
+            approach_avoidance:   %i[approach avoidance],
+            convergent_divergent: %i[convergent divergent]
+          }.freeze
+
+          DAMPING_RATE = 0.01
+
+          MAX_PENDULUMS = 100
+
+          AMPLITUDE_LABELS = {
+            (0.0..0.2) => :minimal,
+            (0.2..0.4) => :low,
+            (0.4..0.6) => :moderate,
+            (0.6..0.8) => :high,
+            (0.8..1.0) => :maximal
+          }.freeze
+
+          module_function
+
+          def valid_pole_pair?(pole_pair)
+            POLE_PAIRS.key?(pole_pair)
+          end
+
+          def amplitude_label(amplitude)
+            clamped = amplitude.clamp(0.0, 1.0)
+            AMPLITUDE_LABELS.each do |range, label|
+              return label if range.cover?(clamped)
+            end
+            :maximal
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_pendulum/helpers/pendulum.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePendulum
+      module Helpers
+        class Pendulum
+          attr_reader :id, :pole_pair, :amplitude, :period, :damping, :current_position, :created_at, :swings
+
+          def initialize(pole_pair:, amplitude: 0.5, period: 10.0, damping: Constants::DAMPING_RATE)
+            raise ArgumentError, "unknown pole_pair: #{pole_pair}" unless Constants.valid_pole_pair?(pole_pair)
+            raise ArgumentError, 'amplitude must be 0.0..1.0' unless amplitude.between?(0.0, 1.0)
+            raise ArgumentError, 'period must be positive' unless period.positive?
+            raise ArgumentError, 'damping must be >= 0' unless damping >= 0.0
+
+            @id               = SecureRandom.uuid
+            @pole_pair        = pole_pair
+            @amplitude        = amplitude.clamp(0.0, 1.0)
+            @period           = period.to_f
+            @damping          = damping.to_f
+            @current_position = 0.0
+            @created_at       = Time.now.utc
+            @swings           = 0
+          end
+
+          def swing!(force: 0.0)
+            force_clamped = force.to_f.clamp(-1.0, 1.0)
+            @current_position = (@current_position + force_clamped).clamp(-1.0, 1.0)
+            @swings += 1
+            @current_position
+          end
+
+          def damp!
+            @amplitude = (@amplitude * (1.0 - @damping)).round(10).clamp(0.0, 1.0)
+            @current_position = (@current_position * (1.0 - @damping)).round(10).clamp(-1.0, 1.0)
+            @amplitude
+          end
+
+          def position_at(time)
+            elapsed = time.to_f
+            angular_frequency = (2.0 * Math::PI) / @period
+            decay = Math.exp(-@damping * elapsed)
+            (@amplitude * decay * Math.cos(angular_frequency * elapsed)).round(10).clamp(-1.0, 1.0)
+          end
+
+          def at_pole_a?
+            @current_position <= -0.5
+          end
+
+          def at_pole_b?
+            @current_position >= 0.5
+          end
+
+          def amplitude_label
+            Constants.amplitude_label(@amplitude)
+          end
+
+          def resonant_with?(frequency)
+            return false unless frequency.positive?
+
+            natural_frequency = 1.0 / @period
+            ratio = frequency / natural_frequency
+            (ratio - 1.0).abs <= 0.05
+          end
+
+          def dominant_pole
+            poles = Constants::POLE_PAIRS.fetch(@pole_pair)
+            return :neutral if @current_position.abs < 0.1
+
+            @current_position.negative? ? poles[0] : poles[1]
+          end
+
+          def to_h
+            poles = Constants::POLE_PAIRS.fetch(@pole_pair)
+            {
+              id:               @id,
+              pole_pair:        @pole_pair,
+              pole_a:           poles[0],
+              pole_b:           poles[1],
+              amplitude:        @amplitude.round(10),
+              amplitude_label:  amplitude_label,
+              period:           @period,
+              damping:          @damping,
+              current_position: @current_position.round(10),
+              dominant_pole:    dominant_pole,
+              at_pole_a:        at_pole_a?,
+              at_pole_b:        at_pole_b?,
+              swings:           @swings,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_pendulum/helpers/pendulum_engine.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePendulum
+      module Helpers
+        class PendulumEngine
+          attr_reader :pendulums
+
+          def initialize
+            @pendulums = {}
+          end
+
+          def create_pendulum(pole_pair:, amplitude: 0.5, period: 10.0, damping: Constants::DAMPING_RATE)
+            raise ArgumentError, "max pendulums (#{Constants::MAX_PENDULUMS}) reached" if @pendulums.size >= Constants::MAX_PENDULUMS
+
+            pendulum = Pendulum.new(
+              pole_pair: pole_pair,
+              amplitude: amplitude,
+              period:    period,
+              damping:   damping
+            )
+            @pendulums[pendulum.id] = pendulum
+            pendulum
+          end
+
+          def swing(pendulum_id, force: 0.0)
+            p = @pendulums[pendulum_id]
+            return nil unless p
+
+            p.swing!(force: force)
+            p
+          end
+
+          def damp_all!
+            @pendulums.each_value(&:damp!)
+          end
+
+          def check_resonance(frequency)
+            return [] unless frequency.positive?
+
+            @pendulums.values.select { |p| p.resonant_with?(frequency) }.map(&:id)
+          end
+
+          def dominant_pole(pendulum_id)
+            p = @pendulums[pendulum_id]
+            return nil unless p
+
+            p.dominant_pole
+          end
+
+          def most_active(limit: 5)
+            @pendulums.values
+                      .sort_by { |p| -p.amplitude }
+                      .first(limit)
+          end
+
+          def most_damped(limit: 5)
+            @pendulums.values
+                      .sort_by(&:amplitude)
+                      .first(limit)
+          end
+
+          def pendulum_report
+            {
+              total:       @pendulums.size,
+              max:         Constants::MAX_PENDULUMS,
+              pole_pairs:  @pendulums.values.group_by(&:pole_pair).transform_values(&:count),
+              most_active: most_active(limit: 3).map(&:to_h),
+              most_damped: most_damped(limit: 3).map(&:to_h)
+            }
+          end
+
+          def get(pendulum_id)
+            @pendulums[pendulum_id]
+          end
+
+          def count
+            @pendulums.size
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitivePendulum
+      module Runners
+        module CognitivePendulum
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_pendulum(pole_pair:, amplitude: 0.5, period: 10.0, damping: Helpers::Constants::DAMPING_RATE, **)
+            unless Helpers::Constants.valid_pole_pair?(pole_pair)
+              return { success: false, error: :invalid_pole_pair, valid_pairs: Helpers::Constants::POLE_PAIRS.keys }
+            end
+
+            raise ArgumentError, 'amplitude must be 0.0..1.0' unless amplitude.between?(0.0, 1.0)
+            raise ArgumentError, 'period must be positive' unless period.positive?
+
+            if pendulum_engine.count >= Helpers::Constants::MAX_PENDULUMS
+              return { success: false, error: :max_pendulums_reached, max: Helpers::Constants::MAX_PENDULUMS }
+            end
+
+            pendulum = pendulum_engine.create_pendulum(
+              pole_pair: pole_pair,
+              amplitude: amplitude,
+              period:    period,
+              damping:   damping
+            )
+
+            Legion::Logging.debug "[cognitive_pendulum] created pole_pair=#{pole_pair} id=#{pendulum.id[0..7]}"
+            { success: true, pendulum_id: pendulum.id, pole_pair: pole_pair, amplitude: pendulum.amplitude }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def swing(pendulum_id:, force: 0.0, **)
+            result = pendulum_engine.swing(pendulum_id, force: force)
+            unless result
+              Legion::Logging.debug "[cognitive_pendulum] swing failed: #{pendulum_id[0..7]} not found"
+              return { success: false, error: :not_found }
+            end
+
+            Legion::Logging.debug "[cognitive_pendulum] swing id=#{pendulum_id[0..7]} position=#{result.current_position.round(4)}"
+            { success: true, pendulum_id: pendulum_id, current_position: result.current_position, dominant_pole: result.dominant_pole }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def damp_all(**)
+            pendulum_engine.damp_all!
+            count = pendulum_engine.count
+            Legion::Logging.debug "[cognitive_pendulum] damped all (#{count} pendulums)"
+            { success: true, damped: count }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def check_resonance(frequency:, **)
+            return { success: false, error: :invalid_frequency, message: 'frequency must be positive' } unless frequency.to_f.positive?
+
+            resonant_ids = pendulum_engine.check_resonance(frequency.to_f)
+            Legion::Logging.debug "[cognitive_pendulum] resonance check frequency=#{frequency} matches=#{resonant_ids.size}"
+            { success: true, frequency: frequency, resonant_pendulum_ids: resonant_ids, count: resonant_ids.size }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def get_dominant_pole(pendulum_id:, **)
+            pole = pendulum_engine.dominant_pole(pendulum_id)
+            if pole.nil?
+              Legion::Logging.debug "[cognitive_pendulum] dominant_pole failed: #{pendulum_id[0..7]} not found"
+              return { success: false, error: :not_found }
+            end
+
+            Legion::Logging.debug "[cognitive_pendulum] dominant_pole id=#{pendulum_id[0..7]} pole=#{pole}"
+            { success: true, pendulum_id: pendulum_id, dominant_pole: pole }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def most_active(limit: 5, **)
+            pendulums = pendulum_engine.most_active(limit: limit)
+            Legion::Logging.debug "[cognitive_pendulum] most_active limit=#{limit} found=#{pendulums.size}"
+            { success: true, pendulums: pendulums.map(&:to_h), count: pendulums.size }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def most_damped(limit: 5, **)
+            pendulums = pendulum_engine.most_damped(limit: limit)
+            Legion::Logging.debug "[cognitive_pendulum] most_damped limit=#{limit} found=#{pendulums.size}"
+            { success: true, pendulums: pendulums.map(&:to_h), count: pendulums.size }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def pendulum_report(**)
+            report = pendulum_engine.pendulum_report
+            Legion::Logging.debug "[cognitive_pendulum] report total=#{report[:total]}"
+            { success: true, report: report }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def get_pendulum(pendulum_id:, **)
+            p = pendulum_engine.get(pendulum_id)
+            p ? { success: true, pendulum: p.to_h } : { success: false, error: :not_found }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          private
+
+          def pendulum_engine
+            @pendulum_engine ||= Helpers::PendulumEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_pendulum.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'cognitive_pendulum/version'
+require_relative 'cognitive_pendulum/helpers/constants'
+require_relative 'cognitive_pendulum/helpers/pendulum'
+require_relative 'cognitive_pendulum/helpers/pendulum_engine'
+require_relative 'cognitive_pendulum/runners/cognitive_pendulum'
+require_relative 'cognitive_pendulum/client'
+
+module Legion
+  module Extensions
+    module CognitivePendulum
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_pendulum/client'
+
+RSpec.describe Legion::Extensions::CognitivePendulum::Client do
+  it 'responds to runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_pendulum)
+    expect(client).to respond_to(:swing)
+    expect(client).to respond_to(:damp_all)
+    expect(client).to respond_to(:check_resonance)
+    expect(client).to respond_to(:get_dominant_pole)
+    expect(client).to respond_to(:most_active)
+    expect(client).to respond_to(:most_damped)
+    expect(client).to respond_to(:pendulum_report)
+    expect(client).to respond_to(:get_pendulum)
+  end
+
+  it 'creates a fresh engine per instance' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.create_pendulum(pole_pair: :certainty_doubt)
+    expect(c2.pendulum_report[:report][:total]).to eq(0)
+  end
+end

data/spec/legion/extensions/cognitive_pendulum/helpers/constants_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitivePendulum::Helpers::Constants do
+  describe 'POLE_PAIRS' do
+    it 'defines five pole pairs' do
+      expect(described_class::POLE_PAIRS.size).to eq(5)
+    end
+
+    it 'includes certainty_doubt' do
+      expect(described_class::POLE_PAIRS[:certainty_doubt]).to eq(%i[certainty doubt])
+    end
+
+    it 'includes focus_diffusion' do
+      expect(described_class::POLE_PAIRS[:focus_diffusion]).to eq(%i[focus diffusion])
+    end
+
+    it 'includes analysis_intuition' do
+      expect(described_class::POLE_PAIRS[:analysis_intuition]).to eq(%i[analysis intuition])
+    end
+
+    it 'includes approach_avoidance' do
+      expect(described_class::POLE_PAIRS[:approach_avoidance]).to eq(%i[approach avoidance])
+    end
+
+    it 'includes convergent_divergent' do
+      expect(described_class::POLE_PAIRS[:convergent_divergent]).to eq(%i[convergent divergent])
+    end
+
+    it 'is frozen' do
+      expect(described_class::POLE_PAIRS).to be_frozen
+    end
+  end
+
+  describe 'DAMPING_RATE' do
+    it 'is 0.01' do
+      expect(described_class::DAMPING_RATE).to eq(0.01)
+    end
+  end
+
+  describe 'MAX_PENDULUMS' do
+    it 'is 100' do
+      expect(described_class::MAX_PENDULUMS).to eq(100)
+    end
+  end
+
+  describe 'AMPLITUDE_LABELS' do
+    it 'has 5 ranges' do
+      expect(described_class::AMPLITUDE_LABELS.size).to eq(5)
+    end
+
+    it 'is frozen' do
+      expect(described_class::AMPLITUDE_LABELS).to be_frozen
+    end
+  end
+
+  describe '.valid_pole_pair?' do
+    it 'returns true for known pole pairs' do
+      expect(described_class.valid_pole_pair?(:certainty_doubt)).to be true
+    end
+
+    it 'returns false for unknown pole pairs' do
+      expect(described_class.valid_pole_pair?(:unknown)).to be false
+    end
+
+    it 'returns false for nil' do
+      expect(described_class.valid_pole_pair?(nil)).to be false
+    end
+  end
+
+  describe '.amplitude_label' do
+    it 'returns :minimal for 0.0' do
+      expect(described_class.amplitude_label(0.0)).to eq(:minimal)
+    end
+
+    it 'returns :minimal for 0.1' do
+      expect(described_class.amplitude_label(0.1)).to eq(:minimal)
+    end
+
+    it 'returns :low for 0.3' do
+      expect(described_class.amplitude_label(0.3)).to eq(:low)
+    end
+
+    it 'returns :moderate for 0.5' do
+      expect(described_class.amplitude_label(0.5)).to eq(:moderate)
+    end
+
+    it 'returns :high for 0.7' do
+      expect(described_class.amplitude_label(0.7)).to eq(:high)
+    end
+
+    it 'returns :maximal for 1.0' do
+      expect(described_class.amplitude_label(1.0)).to eq(:maximal)
+    end
+
+    it 'clamps values above 1.0' do
+      expect(described_class.amplitude_label(1.5)).to eq(:maximal)
+    end
+
+    it 'clamps values below 0.0' do
+      expect(described_class.amplitude_label(-0.5)).to eq(:minimal)
+    end
+  end
+end