lex-cognitive-flexibility 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75026cb77d550113020b61f55ce67d26557e1a5a450e0f9a8f5d2c7392af968a
+  data.tar.gz: 956529d1659ba97303971cc057a9531777cdf4fc4acd1edbb171d37ee5f9b01f
+SHA512:
+  metadata.gz: 2211b8a3486ce48132f53e00bcd3ebd77ac7794babd2a93a66e6183f3cae3635a7e0d8aa04cb5e259d6edf05f7b085c72c69b0b7d088855cdf0bd07c8ecae5aa
+  data.tar.gz: be6cbdd2da1aec72be4b8a2c5451c4940e484dc70ca487dc386ab254622b41dfe74b2a0555c2f21c2ce2ca2a2ed0452ef1a04420641444fcf8c11866bb379a33

data/README.md

@@ -0,0 +1,43 @@
+# lex-cognitive-flexibility
+
+Cognitive task-set switching and flexibility tracking for brain-modeled agentic AI in the LegionIO ecosystem.
+
+## What It Does
+
+Tracks an agent's ability to shift between different rule frameworks (task sets). Switching between task sets incurs a transient cost that decays over time. The agent's flexibility score updates via EMA with each successful switch. When flexibility is low and the agent stays locked in one dominant task set, the engine flags perseveration. A background actor runs every 10 seconds to decay accumulated switch cost.
+
+## Usage
+
+```ruby
+require 'legion/extensions/cognitive_flexibility'
+
+client = Legion::Extensions::CognitiveFlexibility::Client.new
+
+# Define two task sets
+client.create_task_set(name: 'analysis_mode', domain: :analytical)
+result = client.create_task_set(name: 'creative_mode', domain: :creative)
+creative_id = result[:task_set][:id]
+
+# Switch to creative mode
+client.switch_set(set_id: creative_id)
+# => { success: true, task_set: { ... }, switch_cost: 0.15 }
+
+# Check current flexibility state
+client.flexibility_level
+# => { flexibility: 0.64, label: :flexible, perseverating: false, switch_cost: 0.15 }
+
+# Tick to decay switch cost (normally handled by actor)
+client.update_cognitive_flexibility
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/legion/extensions/cognitive_flexibility/actors/tick.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      module Actors
+        class Tick < Legion::Extensions::Actors::Every
+          INTERVAL = 10
+
+          def run
+            Runners::CognitiveFlexibility.instance_method(:update_cognitive_flexibility).bind_call(runner_instance)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_flexibility/helpers/constants'
+require 'legion/extensions/cognitive_flexibility/helpers/task_set'
+require 'legion/extensions/cognitive_flexibility/helpers/flexibility_engine'
+require 'legion/extensions/cognitive_flexibility/runners/cognitive_flexibility'
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      class Client
+        include Runners::CognitiveFlexibility
+
+        def initialize(engine: nil, **)
+          @engine = engine || Helpers::FlexibilityEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      module Helpers
+        module Constants
+          MAX_TASK_SETS         = 30
+          MAX_SWITCH_HISTORY    = 200
+          MAX_RULES_PER_SET     = 20
+
+          SWITCH_COST_BASE      = 0.15
+          SWITCH_COST_DECAY     = 0.02
+          PERSEVERATION_THRESHOLD = 0.7
+          FLEXIBILITY_FLOOR     = 0.1
+          DEFAULT_FLEXIBILITY   = 0.6
+          ADAPTATION_ALPHA      = 0.1
+
+          RULE_TYPES = %i[
+            if_then mapping category sorting
+            priority sequence conditional
+          ].freeze
+
+          FLEXIBILITY_LABELS = {
+            (0.8..)     => :fluid,
+            (0.6...0.8) => :flexible,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :rigid,
+            (..0.2)     => :perseverative
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_flexibility/helpers/flexibility_engine.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      module Helpers
+        class FlexibilityEngine
+          include Constants
+
+          attr_reader :task_sets, :current_set_id, :switch_history, :switch_cost, :flexibility
+
+          def initialize
+            @task_sets      = {}
+            @current_set_id = nil
+            @switch_cost    = 0.0
+            @flexibility    = DEFAULT_FLEXIBILITY
+            @switch_history = []
+            @counter        = 0
+          end
+
+          def create_task_set(name:, domain: :general)
+            return nil if @task_sets.size >= MAX_TASK_SETS
+
+            @counter += 1
+            set_id = :"set_#{@counter}"
+            ts = TaskSet.new(id: set_id, name: name, domain: domain)
+            @task_sets[set_id] = ts
+            @current_set_id ||= set_id
+            ts
+          end
+
+          def add_rule(set_id:, type:, condition:, action:)
+            ts = @task_sets[set_id]
+            return nil unless ts
+
+            ts.add_rule(type: type, condition: condition, action: action)
+          end
+
+          def switch_to(set_id:)
+            return nil unless @task_sets.key?(set_id)
+            return @task_sets[set_id] if set_id == @current_set_id
+
+            old_id = @current_set_id
+            @task_sets[old_id]&.deactivate
+            @task_sets[set_id].activate
+            @current_set_id = set_id
+            @switch_cost = SWITCH_COST_BASE
+            update_flexibility(:success)
+            record_switch(from: old_id, to: set_id)
+            @task_sets[set_id]
+          end
+
+          def current_set
+            @current_set_id ? @task_sets[@current_set_id] : nil
+          end
+
+          def flexibility_label
+            FLEXIBILITY_LABELS.each { |range, lbl| return lbl if range.cover?(@flexibility) }
+            :perseverative
+          end
+
+          def perseverating?
+            cs = current_set
+            return false unless cs
+
+            cs.dominant? && @flexibility < 0.4
+          end
+
+          def available_sets
+            @task_sets.values.reject { |ts| ts.id == @current_set_id }.map(&:to_h)
+          end
+
+          def tick
+            @switch_cost = [@switch_cost - SWITCH_COST_DECAY, 0.0].max
+          end
+
+          def to_h
+            {
+              current_set:   @current_set_id,
+              set_count:     @task_sets.size,
+              switch_cost:   @switch_cost.round(4),
+              flexibility:   @flexibility.round(4),
+              label:         flexibility_label,
+              perseverating: perseverating?,
+              switch_count:  @switch_history.size
+            }
+          end
+
+          private
+
+          def update_flexibility(outcome)
+            target = outcome == :success ? 1.0 : 0.0
+            @flexibility += ADAPTATION_ALPHA * (target - @flexibility)
+            @flexibility = @flexibility.clamp(FLEXIBILITY_FLOOR, 1.0)
+          end
+
+          def record_switch(from:, to:)
+            @switch_history << { from: from, to: to, cost: @switch_cost, at: Time.now.utc }
+            @switch_history.shift while @switch_history.size > MAX_SWITCH_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_flexibility/helpers/task_set.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      module Helpers
+        class TaskSet
+          include Constants
+
+          attr_reader :id, :name, :domain, :rules, :created_at, :use_count
+          attr_accessor :activation
+
+          def initialize(id:, name:, domain: :general, activation: 0.5)
+            @id         = id
+            @name       = name
+            @domain     = domain
+            @rules      = []
+            @activation = activation.to_f.clamp(0.0, 1.0)
+            @created_at = Time.now.utc
+            @use_count  = 0
+          end
+
+          def add_rule(type:, condition:, action:)
+            return nil unless RULE_TYPES.include?(type)
+            return nil if @rules.size >= MAX_RULES_PER_SET
+
+            rule = { type: type, condition: condition, action: action }
+            @rules << rule
+            rule
+          end
+
+          def activate(amount = 0.2)
+            @activation = [@activation + amount, 1.0].min
+            @use_count += 1
+          end
+
+          def deactivate(amount = 0.2)
+            @activation = [@activation - amount, 0.0].max
+          end
+
+          def active?
+            @activation >= 0.5
+          end
+
+          def dominant?
+            @activation >= PERSEVERATION_THRESHOLD
+          end
+
+          def to_h
+            {
+              id:         @id,
+              name:       @name,
+              domain:     @domain,
+              activation: @activation.round(4),
+              active:     active?,
+              dominant:   dominant?,
+              rule_count: @rules.size,
+              use_count:  @use_count
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      module Runners
+        module CognitiveFlexibility
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_task_set(name:, domain: :general, **)
+            Legion::Logging.debug "[cognitive_flexibility] create: #{name}"
+            ts = engine.create_task_set(name: name, domain: domain)
+            ts ? { success: true, task_set: ts.to_h } : { success: false, reason: :limit_reached }
+          end
+
+          def add_rule(set_id:, type:, condition:, action:, **)
+            Legion::Logging.debug "[cognitive_flexibility] rule: set=#{set_id} type=#{type}"
+            rule = engine.add_rule(set_id: set_id.to_sym, type: type.to_sym, condition: condition, action: action)
+            rule ? { success: true, rule: rule } : { success: false, reason: :invalid }
+          end
+
+          def switch_set(set_id:, **)
+            Legion::Logging.debug "[cognitive_flexibility] switch to #{set_id}"
+            ts = engine.switch_to(set_id: set_id.to_sym)
+            if ts
+              { success: true, task_set: ts.to_h, switch_cost: engine.switch_cost.round(4) }
+            else
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def current_task_set(**)
+            cs = engine.current_set
+            cs ? { success: true, task_set: cs.to_h } : { success: true, task_set: nil }
+          end
+
+          def available_sets(**)
+            sets = engine.available_sets
+            { success: true, sets: sets, count: sets.size }
+          end
+
+          def flexibility_level(**)
+            {
+              success:       true,
+              flexibility:   engine.flexibility.round(4),
+              label:         engine.flexibility_label,
+              perseverating: engine.perseverating?,
+              switch_cost:   engine.switch_cost.round(4)
+            }
+          end
+
+          def update_cognitive_flexibility(**)
+            Legion::Logging.debug '[cognitive_flexibility] tick'
+            engine.tick
+            { success: true, switch_cost: engine.switch_cost.round(4) }
+          end
+
+          def cognitive_flexibility_stats(**)
+            Legion::Logging.debug '[cognitive_flexibility] stats'
+            { success: true, stats: engine.to_h }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::FlexibilityEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_flexibility.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_flexibility/version'
+require 'legion/extensions/cognitive_flexibility/helpers/constants'
+require 'legion/extensions/cognitive_flexibility/helpers/task_set'
+require 'legion/extensions/cognitive_flexibility/helpers/flexibility_engine'
+require 'legion/extensions/cognitive_flexibility/runners/cognitive_flexibility'
+require 'legion/extensions/cognitive_flexibility/client'
+
+module Legion
+  module Extensions
+    module CognitiveFlexibility
+      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-flexibility
+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: Cognitive flexibility for LegionIO — switching between task sets, mental
+  rules, and strategies with perseveration detection
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/cognitive_flexibility.rb
+- lib/legion/extensions/cognitive_flexibility/actors/tick.rb
+- lib/legion/extensions/cognitive_flexibility/client.rb
+- lib/legion/extensions/cognitive_flexibility/helpers/constants.rb
+- lib/legion/extensions/cognitive_flexibility/helpers/flexibility_engine.rb
+- lib/legion/extensions/cognitive_flexibility/helpers/task_set.rb
+- lib/legion/extensions/cognitive_flexibility/runners/cognitive_flexibility.rb
+- lib/legion/extensions/cognitive_flexibility/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-flexibility
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-flexibility
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-flexibility
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-flexibility/blob/master/README.md
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-flexibility/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-flexibility/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: LegionIO cognitive flexibility extension
+test_files: []