lex-default-mode-network 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 281cdccc190e505af09438971b70bed9cff9b95e1ff851fe3b298cc3ef7b3997
+  data.tar.gz: 45b4583ac9323704568ce7962fa9b79279c36681e14daf84d84e27693414331c
+SHA512:
+  metadata.gz: b1b4db33bd397bd34da5e157d7342e04368be38e4667be51d025d5205eed0b710cf3953d799d7970a5d2e400d2616832714cc5b7dcbec675b825e81155a1f7ba
+  data.tar.gz: d5c1e14574ddc8be3e61a6b51981be75be108d12652c386cdbdc29bb8090183fd1490bc80792a9fd0190a22fc42167d362381b799e85ca976cf6380b9b66a6ca

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-default-mode-network.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/default_mode_network/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-default-mode-network'
+  spec.version       = Legion::Extensions::DefaultModeNetwork::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Default Mode Network'
+  spec.description   = 'Raichle (2001) Default Mode Network for brain-modeled agentic AI — ' \
+                       'resting-state activation for self-referential processing, mind-wandering, ' \
+                       'spontaneous planning, and social replay when the agent is not task-focused.'
+  spec.homepage      = 'https://github.com/LegionIO/lex-default-mode-network'
+  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-default-mode-network'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-default-mode-network'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-default-mode-network'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-default-mode-network/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-default-mode-network.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/default_mode_network/actors/idle.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      module Actor
+        class Idle < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::DefaultModeNetwork::Runners::DefaultModeNetwork
+          end
+
+          def runner_function
+            'update_dmn'
+          end
+
+          def time
+            30
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/default_mode_network/helpers/constants'
+require 'legion/extensions/default_mode_network/helpers/wandering_thought'
+require 'legion/extensions/default_mode_network/helpers/dmn_engine'
+require 'legion/extensions/default_mode_network/runners/default_mode_network'
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      class Client
+        include Runners::DefaultModeNetwork
+
+        def initialize(dmn_engine: nil, **)
+          @dmn_engine = dmn_engine || Helpers::DmnEngine.new
+        end
+
+        private
+
+        attr_reader :dmn_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      module Helpers
+        module Constants
+          # Idle time thresholds
+          IDLE_THRESHOLD      = 30   # seconds before DMN activates
+          DEEP_IDLE_THRESHOLD = 300  # seconds before deep idle mode
+
+          # Thought storage limits
+          MAX_WANDERING_THOUGHTS = 100
+          MAX_THOUGHT_HISTORY    = 200
+          MAX_ASSOCIATION_CHAIN  = 5 # max hops in a wandering chain
+
+          # Salience parameters
+          THOUGHT_SALIENCE_FLOOR = 0.05
+          THOUGHT_DECAY          = 0.01
+          DEFAULT_SALIENCE       = 0.3
+          SALIENCE_ALPHA         = 0.1
+
+          # Probabilistic thought-type selection (must sum to <= 1.0)
+          SELF_REFERENTIAL_PROBABILITY = 0.3
+          SOCIAL_REPLAY_PROBABILITY    = 0.2
+          PLANNING_PROBABILITY         = 0.2
+          WANDERING_PROBABILITY        = 0.3
+
+          # Activity mode labels
+          ACTIVITY_LABELS = {
+            active:        :task_focused,
+            transitioning: :shifting,
+            idle:          :daydreaming,
+            deep_idle:     :deep_reflection
+          }.freeze
+
+          # Salience quality labels — range-keyed hash
+          SALIENCE_LABELS = {
+            (0.8..)     => :breakthrough,
+            (0.6...0.8) => :significant,
+            (0.4...0.6) => :notable,
+            (0.2...0.4) => :passing,
+            (..0.2)     => :fleeting
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/default_mode_network/helpers/dmn_engine.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      module Helpers
+        class DmnEngine
+          include Constants
+
+          attr_reader :mode, :last_stimulus_at, :thoughts, :thought_history, :wandering_seeds
+
+          def initialize
+            @mode              = :active
+            @last_stimulus_at  = Time.now.utc
+            @thoughts          = []
+            @thought_history   = []
+            @wandering_seeds   = []
+          end
+
+          # --- Stimulus / Mode ---
+
+          def register_stimulus(source: nil)
+            @last_stimulus_at = Time.now.utc
+            previous          = @mode
+            @mode             = :active
+            { previous_mode: previous, current_mode: @mode, source: source, at: @last_stimulus_at }
+          end
+
+          def tick_mode
+            elapsed = idle_duration
+            previous = @mode
+
+            @mode = if elapsed >= Constants::DEEP_IDLE_THRESHOLD
+                      :deep_idle
+                    elsif elapsed >= Constants::IDLE_THRESHOLD
+                      :idle
+                    elsif @mode == :active && elapsed.positive?
+                      :transitioning
+                    else
+                      @mode
+                    end
+
+            { previous_mode: previous, current_mode: @mode, idle_duration: elapsed.round(2) }
+          end
+
+          def idle_duration
+            Time.now.utc - @last_stimulus_at
+          end
+
+          # --- Thought Generation ---
+
+          def generate_thought
+            roll = rand
+            thought = if roll < Constants::SELF_REFERENTIAL_PROBABILITY
+                        self_reflect
+                      elsif roll < Constants::SELF_REFERENTIAL_PROBABILITY + Constants::SOCIAL_REPLAY_PROBABILITY
+                        social_replay(interaction: random_seed(:social))
+                      elsif roll < Constants::SELF_REFERENTIAL_PROBABILITY +
+                                   Constants::SOCIAL_REPLAY_PROBABILITY +
+                                   Constants::PLANNING_PROBABILITY
+                        plan_spontaneously(goal: random_seed(:goal))
+                      else
+                        wander(seed: random_seed(:concept))
+                      end
+            store_thought(thought)
+            thought
+          end
+
+          def self_reflect(topic: nil)
+            topics        = %i[identity values goals capabilities limitations purpose growth]
+            chosen_topic  = topic || topics.sample
+            chain         = build_association_chain(chosen_topic, Constants::MAX_ASSOCIATION_CHAIN)
+
+            WanderingThought.new(
+              seed:              chosen_topic,
+              association_chain: chain,
+              domain:            :self,
+              thought_type:      :self_referential,
+              salience:          rand(0.3..0.7)
+            )
+          end
+
+          def social_replay(interaction: nil)
+            seed  = interaction || :recent_interaction
+            chain = build_association_chain(seed, Constants::MAX_ASSOCIATION_CHAIN)
+
+            WanderingThought.new(
+              seed:              seed,
+              association_chain: chain,
+              domain:            :social,
+              thought_type:      :social_replay,
+              salience:          rand(0.2..0.6)
+            )
+          end
+
+          def plan_spontaneously(goal: nil)
+            seed  = goal || :unresolved_objective
+            chain = build_association_chain(seed, Constants::MAX_ASSOCIATION_CHAIN)
+
+            WanderingThought.new(
+              seed:              seed,
+              association_chain: chain,
+              domain:            :planning,
+              thought_type:      :spontaneous_plan,
+              salience:          rand(0.3..0.8)
+            )
+          end
+
+          def wander(seed: nil)
+            anchor = seed || random_seed(:concept)
+            chain  = build_association_chain(anchor, Constants::MAX_ASSOCIATION_CHAIN)
+
+            WanderingThought.new(
+              seed:              anchor,
+              association_chain: chain,
+              domain:            :associative,
+              thought_type:      :wandering,
+              salience:          rand(0.1..0.5)
+            )
+          end
+
+          # --- Retrieval ---
+
+          def salient_thoughts(count: 5)
+            @thoughts.sort_by { |t| -t.salience }.first(count)
+          end
+
+          def thoughts_of_type(type:)
+            @thoughts.select { |t| t.thought_type == type.to_sym }
+          end
+
+          # --- Lifecycle ---
+
+          def decay_all
+            @thoughts.each(&:decay)
+            faded = @thoughts.select(&:faded?)
+            faded.each { |t| archive_thought(t) }
+            @thoughts.reject!(&:faded?)
+            faded.size
+          end
+
+          def thought_count
+            @thoughts.size
+          end
+
+          def to_h
+            {
+              mode:             @mode,
+              mode_label:       Constants::ACTIVITY_LABELS[@mode],
+              idle_duration:    idle_duration.round(2),
+              thought_count:    @thoughts.size,
+              history_count:    @thought_history.size,
+              last_stimulus_at: @last_stimulus_at
+            }
+          end
+
+          private
+
+          def store_thought(thought)
+            @thoughts << thought
+            prune_thoughts if @thoughts.size > Constants::MAX_WANDERING_THOUGHTS
+            thought
+          end
+
+          def archive_thought(thought)
+            @thought_history << thought.to_h
+            @thought_history.shift while @thought_history.size > Constants::MAX_THOUGHT_HISTORY
+          end
+
+          def prune_thoughts
+            @thoughts.sort_by! { |t| -t.salience }
+            @thoughts.pop while @thoughts.size > Constants::MAX_WANDERING_THOUGHTS
+          end
+
+          def build_association_chain(seed, max_hops)
+            chain = [seed]
+            max_hops.times do
+              next_concept = derive_association(chain.last)
+              break if chain.include?(next_concept)
+
+              chain << next_concept
+            end
+            chain
+          end
+
+          # Lightweight deterministic-ish association for standalone use
+          def derive_association(concept)
+            associations = {
+              identity:      :values,
+              values:        :purpose,
+              purpose:       :goals,
+              goals:         :capabilities,
+              capabilities:  :limitations,
+              limitations:   :growth,
+              growth:        :identity,
+              social:        :empathy,
+              empathy:       :trust,
+              trust:         :collaboration,
+              collaboration: :outcome,
+              outcome:       :reflection
+            }
+            associations.fetch(concept.to_sym, :"#{concept}_context")
+          end
+
+          def random_seed(category)
+            pools = {
+              social:  %i[recent_conversation last_request team_interaction feedback_given feedback_received],
+              goal:    %i[pending_task unresolved_objective upcoming_deadline open_question improvement_opportunity],
+              concept: %i[efficiency creativity curiosity uncertainty possibility connection meaning pattern]
+            }
+            pools.fetch(category, pools[:concept]).sample
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/default_mode_network/helpers/wandering_thought.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      module Helpers
+        class WanderingThought
+          include Constants
+
+          attr_reader :id, :seed, :association_chain, :domain, :thought_type, :created_at
+          attr_accessor :salience
+
+          def initialize(seed:, association_chain:, domain:, thought_type:, salience: Constants::DEFAULT_SALIENCE)
+            @id               = SecureRandom.uuid
+            @seed             = seed
+            @association_chain = Array(association_chain)
+            @domain           = domain
+            @thought_type     = thought_type.to_sym
+            @salience         = salience.to_f.clamp(0.0, 1.0)
+            @created_at       = Time.now.utc
+          end
+
+          def boost_salience(amount = Constants::SALIENCE_ALPHA)
+            @salience = [@salience + amount.to_f, 1.0].min
+          end
+
+          def decay
+            @salience = [@salience - Constants::THOUGHT_DECAY, Constants::THOUGHT_SALIENCE_FLOOR].max
+          end
+
+          def faded?
+            @salience <= Constants::THOUGHT_SALIENCE_FLOOR
+          end
+
+          def label
+            Constants::SALIENCE_LABELS.each { |range, lbl| return lbl if range.cover?(@salience) }
+            :fleeting
+          end
+
+          def to_h
+            {
+              id:                @id,
+              seed:              @seed,
+              association_chain: @association_chain,
+              domain:            @domain,
+              thought_type:      @thought_type,
+              salience:          @salience.round(4),
+              label:             label,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      module Runners
+        module DefaultModeNetwork
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_external_stimulus(source: nil, **)
+            Legion::Logging.debug "[dmn] register_stimulus: source=#{source}"
+            result = dmn_engine.register_stimulus(source: source)
+            {
+              success:       true,
+              previous_mode: result[:previous_mode],
+              current_mode:  result[:current_mode],
+              source:        result[:source]
+            }
+          end
+
+          def generate_idle_thought(**)
+            Legion::Logging.debug "[dmn] generate_idle_thought: mode=#{dmn_engine.mode}"
+            thought = dmn_engine.generate_thought
+            Legion::Logging.debug "[dmn] thought_generated: type=#{thought.thought_type} salience=#{thought.salience.round(2)} label=#{thought.label}"
+            { success: true, thought: thought.to_h }
+          end
+
+          def trigger_self_reflection(**)
+            Legion::Logging.debug '[dmn] trigger_self_reflection'
+            thought = dmn_engine.self_reflect
+            dmn_engine.send(:store_thought, thought)
+            Legion::Logging.debug "[dmn] self_reflect: topic=#{thought.seed} salience=#{thought.salience.round(2)}"
+            { success: true, thought: thought.to_h }
+          end
+
+          def trigger_social_replay(interaction: nil, **)
+            Legion::Logging.debug "[dmn] trigger_social_replay: interaction=#{interaction}"
+            thought = dmn_engine.social_replay(interaction: interaction)
+            dmn_engine.send(:store_thought, thought)
+            Legion::Logging.debug "[dmn] social_replay: seed=#{thought.seed} salience=#{thought.salience.round(2)}"
+            { success: true, thought: thought.to_h }
+          end
+
+          def trigger_spontaneous_plan(goal: nil, **)
+            Legion::Logging.debug "[dmn] trigger_spontaneous_plan: goal=#{goal}"
+            thought = dmn_engine.plan_spontaneously(goal: goal)
+            dmn_engine.send(:store_thought, thought)
+            Legion::Logging.debug "[dmn] spontaneous_plan: goal=#{thought.seed} salience=#{thought.salience.round(2)}"
+            { success: true, thought: thought.to_h }
+          end
+
+          def trigger_wandering(seed: nil, **)
+            Legion::Logging.debug "[dmn] trigger_wandering: seed=#{seed}"
+            thought = dmn_engine.wander(seed: seed)
+            dmn_engine.send(:store_thought, thought)
+            Legion::Logging.debug "[dmn] wandering: seed=#{thought.seed} chain_length=#{thought.association_chain.size}"
+            { success: true, thought: thought.to_h }
+          end
+
+          def salient_thoughts(count: 5, **)
+            count = count.to_i
+            Legion::Logging.debug "[dmn] salient_thoughts: count=#{count}"
+            thoughts = dmn_engine.salient_thoughts(count: count)
+            { success: true, thoughts: thoughts.map(&:to_h), count: thoughts.size }
+          end
+
+          def dmn_mode_status(**)
+            Legion::Logging.debug "[dmn] dmn_mode_status: mode=#{dmn_engine.mode}"
+            mode        = dmn_engine.mode
+            mode_label  = Helpers::Constants::ACTIVITY_LABELS[mode]
+            idle_secs   = dmn_engine.idle_duration.round(2)
+            {
+              success:       true,
+              mode:          mode,
+              mode_label:    mode_label,
+              idle_duration: idle_secs,
+              thought_count: dmn_engine.thought_count
+            }
+          end
+
+          def update_dmn(**)
+            Legion::Logging.debug '[dmn] update_dmn: tick'
+            tick_result   = dmn_engine.tick_mode
+            faded_count   = dmn_engine.decay_all
+            thought       = nil
+
+            if %i[idle deep_idle].include?(dmn_engine.mode)
+              thought = dmn_engine.generate_thought
+              Legion::Logging.debug "[dmn] idle_thought: type=#{thought.thought_type} salience=#{thought.salience.round(2)}"
+            end
+
+            Legion::Logging.debug "[dmn] update_dmn: mode=#{tick_result[:current_mode]} faded=#{faded_count} thoughts=#{dmn_engine.thought_count}"
+            {
+              success:       true,
+              mode:          tick_result[:current_mode],
+              previous_mode: tick_result[:previous_mode],
+              faded_count:   faded_count,
+              thought_count: dmn_engine.thought_count,
+              new_thought:   thought&.to_h
+            }
+          end
+
+          def dmn_stats(**)
+            Legion::Logging.debug '[dmn] dmn_stats'
+            { success: true, stats: dmn_engine.to_h }
+          end
+
+          private
+
+          def dmn_engine
+            @dmn_engine ||= Helpers::DmnEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/default_mode_network.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/default_mode_network/version'
+require 'legion/extensions/default_mode_network/helpers/constants'
+require 'legion/extensions/default_mode_network/helpers/wandering_thought'
+require 'legion/extensions/default_mode_network/helpers/dmn_engine'
+require 'legion/extensions/default_mode_network/runners/default_mode_network'
+require 'legion/extensions/default_mode_network/client'
+
+module Legion
+  module Extensions
+    module DefaultModeNetwork
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DefaultModeNetwork::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes Runners::DefaultModeNetwork' do
+    expect(described_class.ancestors).to include(
+      Legion::Extensions::DefaultModeNetwork::Runners::DefaultModeNetwork
+    )
+  end
+
+  it 'responds to all runner methods' do
+    %i[
+      register_external_stimulus
+      generate_idle_thought
+      trigger_self_reflection
+      trigger_social_replay
+      trigger_spontaneous_plan
+      trigger_wandering
+      salient_thoughts
+      dmn_mode_status
+      update_dmn
+      dmn_stats
+    ].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+
+  it 'accepts a custom dmn_engine' do
+    engine = Legion::Extensions::DefaultModeNetwork::Helpers::DmnEngine.new
+    c      = described_class.new(dmn_engine: engine)
+    expect(c).to respond_to(:dmn_stats)
+  end
+
+  describe 'full DMN lifecycle scenario' do
+    it 'goes from active through idle and generates thoughts' do
+      # Start active — register stimulus
+      stimulus_result = client.register_external_stimulus(source: :test_harness)
+      expect(stimulus_result[:current_mode]).to eq(:active)
+
+      # Explicitly trigger various thought types
+      self_thought    = client.trigger_self_reflection
+      social_thought  = client.trigger_social_replay(interaction: :pair_programming)
+      plan_thought    = client.trigger_spontaneous_plan(goal: :optimize_query)
+      wander_thought  = client.trigger_wandering(seed: :pattern)
+
+      expect(self_thought[:thought][:thought_type]).to eq(:self_referential)
+      expect(social_thought[:thought][:thought_type]).to eq(:social_replay)
+      expect(plan_thought[:thought][:thought_type]).to eq(:spontaneous_plan)
+      expect(wander_thought[:thought][:thought_type]).to eq(:wandering)
+
+      # Check salient thoughts includes our injected thoughts
+      salient = client.salient_thoughts(count: 10)
+      expect(salient[:count]).to eq(4)
+
+      # Run several update ticks — thoughts decay
+      5.times { client.update_dmn }
+
+      # Stats should still be coherent
+      stats = client.dmn_stats
+      expect(stats[:stats][:thought_count]).to be_a(Integer)
+
+      # Mode status
+      status = client.dmn_mode_status
+      expect(status[:success]).to be true
+      expect(status[:idle_duration]).to be >= 0
+    end
+  end
+end