lex-cognitive-defusion 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5299401a100267f302a905877b344a026e0b0efeabcc342191cdf136b683cad3
+  data.tar.gz: 5835e3f7c4ddaa10727973f0db95bfc157912df2587d38cb40616e4a7abe3068
+SHA512:
+  metadata.gz: b49626a6477d240889916c43e694cd16fa41842797e699a195bd7879f07378758005a6e1622d9716d2c259ffd7942d68343563062b9086e9beb13f5e2fd7318e
+  data.tar.gz: a60b6b8f3458a9981e836af5015caec61c8a749a830d2d27846eaaa5f84ae5a9387f3b718e707d3e095c7d7ef0fd198c27f9e87841e748bbea8ea0d97167bb2f

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,43 @@
+# lex-cognitive-defusion
+
+Cognitive defusion (ACT) for LegionIO. Enables the agent to step back from thoughts and observe them as mental events rather than literal truths.
+
+## What It Does
+
+Fusion is when a thought takes on the weight of absolute truth — the agent acts as if the belief, assumption, or judgment is reality rather than a cognitive event. Defusion creates distance between the agent and its thoughts, reducing the behavioral influence of entrenched beliefs. Six techniques are available, each with different potency: acceptance (strongest), distancing, contextualization, reframing, labeling, and metaphor.
+
+Thoughts that are visited repeatedly without defusion accumulate as rumination; the extension detects this state and recommends type-appropriate techniques.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveDefusion::Client.new
+
+thought = client.register_thought(
+  content: 'I must always provide a complete answer or I have failed',
+  thought_type: :rule,
+  belief_strength: 0.8
+)
+
+# Recommended technique for :rule type is :contextualization
+rec = client.recommend_technique(thought_id: thought[:thought_id])
+client.apply_defusion(thought_id: thought[:thought_id], technique: rec[:technique])
+
+# Or apply all techniques in sequence
+client.apply_all_techniques(thought_id: thought[:thought_id])
+
+client.defusion_report
+# => { total_thoughts: 1, enmeshed_count: 0, average_fusion: 0.31 }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-defusion.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_defusion/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-defusion'
+  spec.version       = Legion::Extensions::CognitiveDefusion::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Defusion'
+  spec.description   = 'Cognitive defusion (ACT) for brain-modeled agentic AI — ' \
+                       'step back from thoughts and observe them as mental events rather than literal truths'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-defusion'
+  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-defusion'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-defusion'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-defusion'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-defusion/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-defusion.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_defusion/helpers/constants'
+require 'legion/extensions/cognitive_defusion/helpers/thought'
+require 'legion/extensions/cognitive_defusion/helpers/defusion_engine'
+require 'legion/extensions/cognitive_defusion/runners/cognitive_defusion'
+
+module Legion
+  module Extensions
+    module CognitiveDefusion
+      class Client
+        include Runners::CognitiveDefusion
+
+        def initialize(engine: nil)
+          @defusion_engine = engine || Helpers::DefusionEngine.new
+        end
+
+        private
+
+        attr_reader :defusion_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDefusion
+      module Helpers
+        module Constants
+          MAX_THOUGHTS       = 300
+          DEFAULT_FUSION     = 0.7
+          FUSION_DELTA_FUSE  = 0.05
+          FUSION_DELTA_VISIT = 0.02
+
+          DEFUSION_TECHNIQUES = %i[labeling distancing contextualization acceptance reframing metaphor].freeze
+
+          TECHNIQUE_POTENCY = {
+            labeling:          0.08,
+            distancing:        0.12,
+            contextualization: 0.10,
+            acceptance:        0.15,
+            reframing:         0.10,
+            metaphor:          0.06
+          }.freeze
+
+          FUSION_LABELS = {
+            (0.8..)     => :enmeshed,
+            (0.6...0.8) => :fused,
+            (0.4...0.6) => :partially_fused,
+            (0.2...0.4) => :defused,
+            (..0.2)     => :fully_defused
+          }.freeze
+
+          BELIEF_LABELS = {
+            (0.8..)     => :entrenched,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :negligible
+          }.freeze
+
+          FUSION_THRESHOLD  = 0.7
+          DEFUSED_THRESHOLD = 0.3
+          RUMINATION_COUNT  = 3
+
+          THOUGHT_TYPES = %i[belief assumption evaluation prediction judgment self_concept rule].freeze
+
+          # Technique recommendations by thought type
+          RECOMMENDED_TECHNIQUES = {
+            belief:       :acceptance,
+            assumption:   :contextualization,
+            evaluation:   :distancing,
+            prediction:   :reframing,
+            judgment:     :labeling,
+            self_concept: :distancing,
+            rule:         :contextualization
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_defusion/helpers/defusion_engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDefusion
+      module Helpers
+        class DefusionEngine
+          include Constants
+
+          attr_reader :thoughts, :defusion_history
+
+          def initialize
+            @thoughts         = {}
+            @defusion_history = []
+          end
+
+          def register_thought(content:, thought_type:, belief_strength: 0.5)
+            return { error: :invalid_thought_type, valid: THOUGHT_TYPES } unless THOUGHT_TYPES.include?(thought_type)
+
+            if @thoughts.size >= MAX_THOUGHTS
+              oldest = @thoughts.values.min_by(&:created_at)
+              @thoughts.delete(oldest.id) if oldest
+            end
+
+            thought = Thought.new(content: content, thought_type: thought_type, belief_strength: belief_strength)
+            @thoughts[thought.id] = thought
+            { thought_id: thought.id, thought: thought.to_h }
+          end
+
+          def apply_defusion(thought_id:, technique:)
+            thought = @thoughts[thought_id]
+            return { error: :thought_not_found } unless thought
+            return { error: :invalid_technique, valid: DEFUSION_TECHNIQUES } unless DEFUSION_TECHNIQUES.include?(technique)
+
+            before_fusion = thought.fusion_level
+            result = thought.defuse!(technique: technique)
+
+            @defusion_history << {
+              thought_id:    thought_id,
+              technique:     technique,
+              before_fusion: before_fusion,
+              after_fusion:  thought.fusion_level,
+              at:            Time.now.utc
+            }
+
+            {
+              success:      true,
+              thought_id:   thought_id,
+              technique:    technique,
+              before:       result[:before],
+              after:        result[:after],
+              reduction:    result[:reduction],
+              fusion_label: thought.fusion_label,
+              defused:      thought.defused?
+            }
+          end
+
+          def apply_all_techniques(thought_id:)
+            thought = @thoughts[thought_id]
+            return { error: :thought_not_found } unless thought
+
+            results = DEFUSION_TECHNIQUES.map do |technique|
+              apply_defusion(thought_id: thought_id, technique: technique)
+            end
+
+            {
+              thought_id:    thought_id,
+              techniques:    results,
+              final_fusion:  thought.fusion_level,
+              fusion_label:  thought.fusion_label,
+              defused:       thought.defused?,
+              total_applied: results.size
+            }
+          end
+
+          def visit_thought(thought_id:)
+            thought = @thoughts[thought_id]
+            return { error: :thought_not_found } unless thought
+
+            result = thought.visit!
+            {
+              thought_id:  thought_id,
+              visit_count: result[:visit_count],
+              fusion:      thought.fusion_level,
+              ruminating:  thought.ruminating?
+            }
+          end
+
+          def enmeshed_thoughts
+            @thoughts.values.select(&:enmeshed?)
+          end
+
+          def defused_thoughts
+            @thoughts.values.select(&:defused?)
+          end
+
+          def ruminating_thoughts
+            @thoughts.values.select(&:ruminating?)
+          end
+
+          def most_fused(limit: 5)
+            @thoughts.values
+                     .sort_by { |t| -t.fusion_level }
+                     .first(limit)
+          end
+
+          def recommend_technique(thought_id:)
+            thought = @thoughts[thought_id]
+            return { error: :thought_not_found } unless thought
+
+            technique = RECOMMENDED_TECHNIQUES.fetch(thought.thought_type, :acceptance)
+            potency   = TECHNIQUE_POTENCY[technique]
+
+            {
+              thought_id:       thought_id,
+              thought_type:     thought.thought_type,
+              technique:        technique,
+              potency:          potency,
+              current_fusion:   thought.fusion_level,
+              projected_fusion: (thought.fusion_level - potency).clamp(0.0, 1.0).round(10)
+            }
+          end
+
+          def average_fusion
+            return 0.0 if @thoughts.empty?
+
+            total = @thoughts.values.sum(&:fusion_level)
+            (total / @thoughts.size).round(10)
+          end
+
+          def defusion_effectiveness
+            return 0.0 if @defusion_history.empty?
+
+            total_reduction = @defusion_history.sum { |h| h[:before_fusion] - h[:after_fusion] }
+            (total_reduction / @defusion_history.size).round(10)
+          end
+
+          def defusion_report
+            all = @thoughts.values
+            {
+              total_thoughts:         all.size,
+              enmeshed_count:         all.count(&:enmeshed?),
+              defused_count:          all.count(&:defused?),
+              ruminating_count:       all.count(&:ruminating?),
+              average_fusion:         average_fusion,
+              defusion_attempts:      @defusion_history.size,
+              defusion_effectiveness: defusion_effectiveness,
+              most_fused:             most_fused(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              thoughts:         @thoughts.transform_values(&:to_h),
+              defusion_history: @defusion_history,
+              report:           defusion_report
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_defusion/helpers/thought.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveDefusion
+      module Helpers
+        class Thought
+          include Constants
+
+          attr_reader :id, :content, :thought_type, :belief_strength,
+                      :fusion_level, :defusion_count, :visit_count, :created_at
+
+          def initialize(content:, thought_type:, belief_strength:)
+            @id              = SecureRandom.uuid
+            @content         = content
+            @thought_type    = thought_type
+            @belief_strength = belief_strength.clamp(0.0, 1.0)
+            @fusion_level    = DEFAULT_FUSION
+            @defusion_count  = 0
+            @visit_count     = 0
+            @created_at      = Time.now.utc
+          end
+
+          def defuse!(technique:)
+            potency = TECHNIQUE_POTENCY.fetch(technique, 0.0)
+            before  = @fusion_level
+            @fusion_level = (@fusion_level - potency).clamp(0.0, 1.0).round(10)
+            @defusion_count += 1
+            { before: before, after: @fusion_level, technique: technique, reduction: (before - @fusion_level).round(10) }
+          end
+
+          def fuse!
+            before = @fusion_level
+            @fusion_level = (@fusion_level + FUSION_DELTA_FUSE).clamp(0.0, 1.0).round(10)
+            { before: before, after: @fusion_level }
+          end
+
+          def visit!
+            @visit_count += 1
+            before = @fusion_level
+            @fusion_level = (@fusion_level + FUSION_DELTA_VISIT).clamp(0.0, 1.0).round(10)
+            { visit_count: @visit_count, fusion_before: before, fusion_after: @fusion_level }
+          end
+
+          def enmeshed?
+            @fusion_level >= FUSION_THRESHOLD
+          end
+
+          def defused?
+            @fusion_level <= DEFUSED_THRESHOLD
+          end
+
+          def ruminating?
+            @visit_count >= RUMINATION_COUNT
+          end
+
+          def fusion_label
+            FUSION_LABELS.find { |range, _| range.cover?(@fusion_level) }&.last || :unknown
+          end
+
+          def belief_label
+            BELIEF_LABELS.find { |range, _| range.cover?(@belief_strength) }&.last || :unknown
+          end
+
+          def to_h
+            {
+              id:              @id,
+              content:         @content,
+              thought_type:    @thought_type,
+              belief_strength: @belief_strength,
+              fusion_level:    @fusion_level,
+              defusion_count:  @defusion_count,
+              visit_count:     @visit_count,
+              fusion_label:    fusion_label,
+              belief_label:    belief_label,
+              enmeshed:        enmeshed?,
+              defused:         defused?,
+              ruminating:      ruminating?,
+              created_at:      @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveDefusion
+      module Runners
+        module CognitiveDefusion
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_thought(content:, thought_type:, belief_strength: 0.5, engine: nil, **)
+            eng    = engine || defusion_engine
+            result = eng.register_thought(content: content, thought_type: thought_type, belief_strength: belief_strength)
+            return { success: false, **result } if result[:error]
+
+            Legion::Logging.debug "[cognitive_defusion] registered thought type=#{thought_type} " \
+                                  "belief=#{belief_strength.round(2)} id=#{result[:thought_id]}"
+            { success: true, **result }
+          end
+
+          def apply_defusion(thought_id:, technique:, engine: nil, **)
+            eng    = engine || defusion_engine
+            result = eng.apply_defusion(thought_id: thought_id, technique: technique)
+            return { success: false, **result } if result[:error]
+
+            Legion::Logging.debug "[cognitive_defusion] defusion applied technique=#{technique} " \
+                                  "reduction=#{result[:reduction]&.round(4)} fusion=#{result[:after]&.round(4)}"
+            result
+          end
+
+          def apply_all_techniques(thought_id:, engine: nil, **)
+            eng    = engine || defusion_engine
+            result = eng.apply_all_techniques(thought_id: thought_id)
+            return { success: false, **result } if result[:error]
+
+            Legion::Logging.debug "[cognitive_defusion] all techniques applied thought_id=#{thought_id} " \
+                                  "final_fusion=#{result[:final_fusion]&.round(4)}"
+            { success: true, **result }
+          end
+
+          def visit_thought(thought_id:, engine: nil, **)
+            eng    = engine || defusion_engine
+            result = eng.visit_thought(thought_id: thought_id)
+            return { success: false, **result } if result[:error]
+
+            Legion::Logging.debug "[cognitive_defusion] thought visited count=#{result[:visit_count]} " \
+                                  "ruminating=#{result[:ruminating]}"
+            { success: true, **result }
+          end
+
+          def fuse_thought(thought_id:, engine: nil, **)
+            eng = engine || defusion_engine
+            thought = eng.thoughts[thought_id]
+            return { success: false, error: :thought_not_found } unless thought
+
+            result = thought.fuse!
+            Legion::Logging.debug "[cognitive_defusion] thought fused before=#{result[:before].round(4)} " \
+                                  "after=#{result[:after].round(4)}"
+            { success: true, thought_id: thought_id, before: result[:before], after: result[:after], enmeshed: thought.enmeshed? }
+          end
+
+          def enmeshed_thoughts(engine: nil, **)
+            eng      = engine || defusion_engine
+            thoughts = eng.enmeshed_thoughts.map(&:to_h)
+            Legion::Logging.debug "[cognitive_defusion] enmeshed thoughts count=#{thoughts.size}"
+            { success: true, count: thoughts.size, thoughts: thoughts }
+          end
+
+          def defused_thoughts(engine: nil, **)
+            eng      = engine || defusion_engine
+            thoughts = eng.defused_thoughts.map(&:to_h)
+            Legion::Logging.debug "[cognitive_defusion] defused thoughts count=#{thoughts.size}"
+            { success: true, count: thoughts.size, thoughts: thoughts }
+          end
+
+          def ruminating_thoughts(engine: nil, **)
+            eng      = engine || defusion_engine
+            thoughts = eng.ruminating_thoughts.map(&:to_h)
+            Legion::Logging.debug "[cognitive_defusion] ruminating thoughts count=#{thoughts.size}"
+            { success: true, count: thoughts.size, thoughts: thoughts }
+          end
+
+          def most_fused(limit: 5, engine: nil, **)
+            eng      = engine || defusion_engine
+            thoughts = eng.most_fused(limit: limit).map(&:to_h)
+            Legion::Logging.debug "[cognitive_defusion] most fused count=#{thoughts.size}"
+            { success: true, count: thoughts.size, thoughts: thoughts }
+          end
+
+          def recommend_technique(thought_id:, engine: nil, **)
+            eng    = engine || defusion_engine
+            result = eng.recommend_technique(thought_id: thought_id)
+            return { success: false, **result } if result[:error]
+
+            Legion::Logging.debug "[cognitive_defusion] technique recommended=#{result[:technique]} " \
+                                  "for type=#{result[:thought_type]}"
+            { success: true, **result }
+          end
+
+          def defusion_report(engine: nil, **)
+            eng    = engine || defusion_engine
+            report = eng.defusion_report
+            Legion::Logging.debug "[cognitive_defusion] report: total=#{report[:total_thoughts]} " \
+                                  "enmeshed=#{report[:enmeshed_count]} avg_fusion=#{report[:average_fusion].round(4)}"
+            { success: true, **report }
+          end
+
+          def defusion_state(engine: nil, **)
+            eng = engine || defusion_engine
+            Legion::Logging.debug '[cognitive_defusion] state queried'
+            { success: true, **eng.to_h }
+          end
+
+          private
+
+          def defusion_engine
+            @defusion_engine ||= Helpers::DefusionEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_defusion.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_defusion/version'
+require 'legion/extensions/cognitive_defusion/helpers/constants'
+require 'legion/extensions/cognitive_defusion/helpers/thought'
+require 'legion/extensions/cognitive_defusion/helpers/defusion_engine'
+require 'legion/extensions/cognitive_defusion/runners/cognitive_defusion'
+require 'legion/extensions/cognitive_defusion/client'
+
+module Legion
+  module Extensions
+    module CognitiveDefusion
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end