lex-cognitive-momentum 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e7b33e7708bc1bf42bd957b9743baad50481c23c13b75bbacf14e142f552bc2
+  data.tar.gz: 1982bd8b1f91415fd02d99663fb38f246f2b39f3ac5fea48c6a7d4d66103d7a0
+SHA512:
+  metadata.gz: b011ae7562052c6772ae73d9200920610fb41817479ea45ac8df17d921b5e893072e09a4789adf876328bfcbd94f70a75bc1dbea4e677f6fbe7622351c96494d
+  data.tar.gz: 0d908b1f44a6a583e1ff9ecb7122c64b8c4ed68f8673b508bb709d45eac8782f265592f11555ca56eddeab4b51e9d88dee8359352d55179dc1863546bc3044e4

data/README.md

@@ -0,0 +1,55 @@
+# lex-cognitive-momentum
+
+Physics-inspired idea momentum engine for LegionIO cognitive agents. Each idea has mass (entrenchment) and velocity (rate of change). Momentum = mass × velocity. Reinforcement builds momentum; challenges reduce it; friction decays velocity each cycle.
+
+## What It Does
+
+- Five idea types: `belief`, `goal`, `hypothesis`, `plan`, `intuition`
+- Reinforce ideas to increase mass and velocity
+- Challenge ideas to penalize velocity and reduce mass
+- Apply external forces via Newton's second law (F = ma)
+- Friction decays velocity each tick cycle
+- Prune ideas that reach zero momentum (at rest)
+- Identify surging (positive velocity), reversing (negative velocity), and entrenched (high mass) ideas
+
+## Usage
+
+```ruby
+# Create an idea
+result = runner.create_cognitive_idea(
+  content: 'microservices will reduce coupling',
+  idea_type: :hypothesis, domain: :architecture,
+  mass: 0.5, velocity: 0.0
+)
+idea_id = result[:idea][:id]
+
+# Reinforce it
+runner.reinforce_cognitive_idea(idea_id: idea_id)
+# => { success: true, idea: { mass: 0.55, velocity: 0.1, momentum: 0.055, ... } }
+
+# Challenge it
+runner.challenge_cognitive_idea(idea_id: idea_id)
+# => { success: true, idea: { velocity: -0.05, ... } }
+
+# Apply external force
+runner.apply_cognitive_force(idea_id: idea_id, force: 0.3)
+
+# Tick maintenance (friction + prune)
+runner.update_cognitive_momentum
+
+# Identify what's moving
+runner.surging_ideas_report
+runner.entrenched_ideas_report
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/legion/extensions/cognitive_momentum/helpers/client.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMomentum
+      module Helpers
+        class Client
+          include Runners::CognitiveMomentum
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMomentum
+      module Helpers
+        module Constants
+          # Idea categories
+          IDEA_TYPES = %i[belief goal hypothesis plan intuition].freeze
+
+          # Momentum = mass * velocity
+          # Mass = importance/entrenchment (resists change)
+          # Velocity = rate of change/spread
+
+          DEFAULT_MASS     = 0.5
+          DEFAULT_VELOCITY = 0.0
+          MASS_FLOOR       = 0.1
+          MASS_CEILING     = 1.0
+          VELOCITY_FLOOR   = -1.0
+          VELOCITY_CEILING = 1.0
+
+          # Friction reduces velocity each cycle
+          FRICTION_RATE = 0.05
+
+          # Force needed to change velocity (F = m * a, so a = F / m)
+          # Higher mass = more force needed to accelerate
+          MIN_FORCE = 0.01
+
+          # Reinforcement increases mass (entrenchment)
+          REINFORCE_MASS_BOOST = 0.05
+          REINFORCE_VELOCITY_BOOST = 0.1
+
+          # Challenge reduces velocity and slightly reduces mass
+          CHALLENGE_VELOCITY_PENALTY = 0.15
+          CHALLENGE_MASS_REDUCTION   = 0.02
+
+          # Momentum labels
+          MOMENTUM_LABELS = {
+            (0.5..)      => :surging,
+            (0.2...0.5)  => :building,
+            (0.0...0.2)  => :coasting,
+            (-0.2...0.0) => :slowing,
+            (..-0.2)     => :reversing
+          }.freeze
+
+          # Inertia labels (based on mass)
+          INERTIA_LABELS = {
+            (0.8..)     => :immovable,
+            (0.6...0.8) => :entrenched,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :flexible,
+            (..0.2)     => :volatile
+          }.freeze
+
+          MAX_IDEAS   = 200
+          MAX_HISTORY = 500
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_momentum/helpers/idea.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMomentum
+      module Helpers
+        class Idea
+          include Constants
+
+          attr_reader :id, :content, :idea_type, :domain, :mass, :velocity,
+                      :reinforcement_count, :challenge_count, :created_at, :last_updated_at
+
+          def initialize(content:, idea_type:, domain:, mass: DEFAULT_MASS)
+            @id                  = SecureRandom.uuid
+            @content             = content
+            @idea_type           = idea_type
+            @domain              = domain
+            @mass                = mass.clamp(MASS_FLOOR, MASS_CEILING)
+            @velocity            = DEFAULT_VELOCITY
+            @reinforcement_count = 0
+            @challenge_count     = 0
+            @created_at          = Time.now.utc
+            @last_updated_at     = @created_at
+          end
+
+          def momentum
+            @mass * @velocity
+          end
+
+          def momentum_label
+            MOMENTUM_LABELS.find { |range, _| range.cover?(momentum) }&.last || :coasting
+          end
+
+          def inertia_label
+            INERTIA_LABELS.find { |range, _| range.cover?(@mass) }&.last || :moderate
+          end
+
+          def reinforce!
+            @reinforcement_count += 1
+            @mass     = (@mass + REINFORCE_MASS_BOOST).clamp(MASS_FLOOR, MASS_CEILING)
+            @velocity = (@velocity + REINFORCE_VELOCITY_BOOST).clamp(VELOCITY_FLOOR, VELOCITY_CEILING)
+            @last_updated_at = Time.now.utc
+          end
+
+          def challenge!
+            @challenge_count += 1
+            @velocity = (@velocity - CHALLENGE_VELOCITY_PENALTY).clamp(VELOCITY_FLOOR, VELOCITY_CEILING)
+            @mass     = (@mass - CHALLENGE_MASS_REDUCTION).clamp(MASS_FLOOR, MASS_CEILING)
+            @last_updated_at = Time.now.utc
+          end
+
+          def apply_force(force:)
+            acceleration = force / @mass
+            @velocity = (@velocity + acceleration).clamp(VELOCITY_FLOOR, VELOCITY_CEILING)
+            @last_updated_at = Time.now.utc
+          end
+
+          def apply_friction!
+            return if @velocity.zero?
+
+            @velocity = if @velocity.positive?
+                          [(@velocity - FRICTION_RATE), 0.0].max
+                        else
+                          [(@velocity + FRICTION_RATE), 0.0].min
+                        end
+            @last_updated_at = Time.now.utc
+          end
+
+          def surging?
+            momentum >= 0.5
+          end
+
+          def reversing?
+            momentum <= -0.2
+          end
+
+          def at_rest?
+            @velocity.abs < 0.01
+          end
+
+          def entrenched?
+            @mass >= 0.8
+          end
+
+          def to_h
+            {
+              id:                  @id,
+              content:             @content,
+              idea_type:           @idea_type,
+              domain:              @domain,
+              mass:                @mass,
+              velocity:            @velocity,
+              momentum:            momentum,
+              momentum_label:      momentum_label,
+              inertia_label:       inertia_label,
+              reinforcement_count: @reinforcement_count,
+              challenge_count:     @challenge_count,
+              created_at:          @created_at,
+              last_updated_at:     @last_updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_momentum/helpers/momentum_engine.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMomentum
+      module Helpers
+        class MomentumEngine
+          include Constants
+
+          attr_reader :history
+
+          def initialize
+            @ideas   = {}
+            @history = []
+          end
+
+          def create_idea(content:, idea_type:, domain:, mass: DEFAULT_MASS)
+            evict_oldest if @ideas.size >= MAX_IDEAS
+
+            idea = Idea.new(content: content, idea_type: idea_type, domain: domain, mass: mass)
+            @ideas[idea.id] = idea
+            record_history(:created, idea.id)
+            idea
+          end
+
+          def reinforce_idea(idea_id:)
+            idea = @ideas[idea_id]
+            return { success: false, reason: :not_found } unless idea
+
+            idea.reinforce!
+            record_history(:reinforced, idea_id)
+            { success: true, momentum: idea.momentum, mass: idea.mass, velocity: idea.velocity }
+          end
+
+          def challenge_idea(idea_id:)
+            idea = @ideas[idea_id]
+            return { success: false, reason: :not_found } unless idea
+
+            idea.challenge!
+            record_history(:challenged, idea_id)
+            { success: true, momentum: idea.momentum, mass: idea.mass, velocity: idea.velocity }
+          end
+
+          def apply_force(idea_id:, force:)
+            idea = @ideas[idea_id]
+            return { success: false, reason: :not_found } unless idea
+
+            idea.apply_force(force: force)
+            record_history(:force_applied, idea_id)
+            { success: true, momentum: idea.momentum, velocity: idea.velocity }
+          end
+
+          def surging_ideas
+            @ideas.values.select(&:surging?)
+          end
+
+          def reversing_ideas
+            @ideas.values.select(&:reversing?)
+          end
+
+          def entrenched_ideas
+            @ideas.values.select(&:entrenched?)
+          end
+
+          def ideas_by_type(idea_type:)
+            @ideas.values.select { |idea| idea.idea_type == idea_type }
+          end
+
+          def ideas_by_domain(domain:)
+            @ideas.values.select { |idea| idea.domain == domain }
+          end
+
+          def highest_momentum(limit: 5)
+            @ideas.values.sort_by { |idea| -idea.momentum }.first(limit)
+          end
+
+          def most_entrenched(limit: 5)
+            @ideas.values.sort_by { |idea| -idea.mass }.first(limit)
+          end
+
+          def apply_friction_all
+            @ideas.each_value(&:apply_friction!)
+          end
+
+          def prune_at_rest
+            ids = @ideas.select { |_id, idea| idea.at_rest? && idea.mass <= MASS_FLOOR + 0.01 }.keys
+            ids.each { |idea_id| @ideas.delete(idea_id) }
+            ids.size
+          end
+
+          def to_h
+            {
+              total_ideas:      @ideas.size,
+              surging_count:    surging_ideas.size,
+              reversing_count:  reversing_ideas.size,
+              entrenched_count: entrenched_ideas.size,
+              avg_momentum:     avg_momentum,
+              history_count:    @history.size
+            }
+          end
+
+          private
+
+          def avg_momentum
+            return 0.0 if @ideas.empty?
+
+            @ideas.values.sum(&:momentum) / @ideas.size
+          end
+
+          def evict_oldest
+            oldest_id = @ideas.min_by { |_id, idea| idea.last_updated_at }&.first
+            @ideas.delete(oldest_id) if oldest_id
+          end
+
+          def record_history(event, idea_id)
+            @history << { event: event, idea_id: idea_id, at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMomentum
+      module Runners
+        module CognitiveMomentum
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_cognitive_idea(content:, idea_type:, domain:, mass: nil, **)
+            idea = engine.create_idea(
+              content:   content,
+              idea_type: idea_type.to_sym,
+              domain:    domain.to_sym,
+              mass:      mass || Helpers::Constants::DEFAULT_MASS
+            )
+            Legion::Logging.debug "[cognitive_momentum] create id=#{idea.id[0..7]} " \
+                                  "type=#{idea_type} domain=#{domain}"
+            { success: true, idea: idea.to_h }
+          end
+
+          def reinforce_cognitive_idea(idea_id:, **)
+            result = engine.reinforce_idea(idea_id: idea_id)
+            Legion::Logging.debug "[cognitive_momentum] reinforce id=#{idea_id[0..7]} " \
+                                  "momentum=#{result[:momentum]&.round(3)}"
+            result
+          end
+
+          def challenge_cognitive_idea(idea_id:, **)
+            result = engine.challenge_idea(idea_id: idea_id)
+            Legion::Logging.debug "[cognitive_momentum] challenge id=#{idea_id[0..7]} " \
+                                  "momentum=#{result[:momentum]&.round(3)}"
+            result
+          end
+
+          def apply_cognitive_force(idea_id:, force:, **)
+            result = engine.apply_force(idea_id: idea_id, force: force)
+            Legion::Logging.debug "[cognitive_momentum] force id=#{idea_id[0..7]} " \
+                                  "f=#{force} momentum=#{result[:momentum]&.round(3)}"
+            result
+          end
+
+          def surging_ideas_report(**)
+            ideas = engine.surging_ideas
+            Legion::Logging.debug "[cognitive_momentum] surging count=#{ideas.size}"
+            { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+          end
+
+          def reversing_ideas_report(**)
+            ideas = engine.reversing_ideas
+            Legion::Logging.debug "[cognitive_momentum] reversing count=#{ideas.size}"
+            { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+          end
+
+          def entrenched_ideas_report(**)
+            ideas = engine.entrenched_ideas
+            Legion::Logging.debug "[cognitive_momentum] entrenched count=#{ideas.size}"
+            { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+          end
+
+          def highest_momentum_ideas(limit: 5, **)
+            ideas = engine.highest_momentum(limit: limit)
+            Legion::Logging.debug "[cognitive_momentum] highest_momentum count=#{ideas.size}"
+            { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+          end
+
+          def ideas_by_domain(domain:, **)
+            ideas = engine.ideas_by_domain(domain: domain.to_sym)
+            Legion::Logging.debug '[cognitive_momentum] by_domain ' \
+                                  "domain=#{domain} count=#{ideas.size}"
+            { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+          end
+
+          def update_cognitive_momentum(**)
+            engine.apply_friction_all
+            pruned = engine.prune_at_rest
+            Legion::Logging.debug "[cognitive_momentum] friction+prune pruned=#{pruned}"
+            { success: true, pruned: pruned }
+          end
+
+          def cognitive_momentum_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[cognitive_momentum] stats total=#{stats[:total_ideas]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::MomentumEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_momentum.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'cognitive_momentum/version'
+require_relative 'cognitive_momentum/helpers/constants'
+require_relative 'cognitive_momentum/helpers/idea'
+require_relative 'cognitive_momentum/helpers/momentum_engine'
+require_relative 'cognitive_momentum/runners/cognitive_momentum'
+require_relative 'cognitive_momentum/helpers/client'
+
+module Legion
+  module Extensions
+    module CognitiveMomentum
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-momentum
+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: Models ideas with mass (importance) and velocity (change rate). Heavy
+  ideas resist change (inertia), reinforced ideas accelerate, friction slows unreinforced
+  ideas. Based on Newtonian dynamics metaphor.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/cognitive_momentum.rb
+- lib/legion/extensions/cognitive_momentum/helpers/client.rb
+- lib/legion/extensions/cognitive_momentum/helpers/constants.rb
+- lib/legion/extensions/cognitive_momentum/helpers/idea.rb
+- lib/legion/extensions/cognitive_momentum/helpers/momentum_engine.rb
+- lib/legion/extensions/cognitive_momentum/runners/cognitive_momentum.rb
+- lib/legion/extensions/cognitive_momentum/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-momentum
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-momentum
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-momentum
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-momentum
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-momentum/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-momentum/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: Physics-inspired cognitive dynamics for LegionIO
+test_files: []