lex-bias 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f5685a3afbc78717dc5f496538693e629fcdd155a5c5cbb61ee2d0d46bfe721
+  data.tar.gz: 45d211f0ae027cfdd83cf3dde20f08b64630cbee1a14366508994ac6f76b36e9
+SHA512:
+  metadata.gz: 64c5161d46db36774416a9c22298be0d120b0e7f75df0a6ac1039696adc09c3ead53e4dd6f555580bbb3ad8597c432b215437ad0d59a205ee5a2c42d0e89abbf
+  data.tar.gz: 7297fe2cdf218a2c88bb26c92e9a5a24b654dd1d0115bfd2cfa27106c2efbae3af86e2148dbe0f9c0316b5cf0c60412e17feb804e1c2fa8cb70f98f3cfc97480

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/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/lex-bias.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/bias/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-bias'
+  spec.version       = Legion::Extensions::Bias::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Bias'
+  spec.description   = 'Cognitive bias detection and correction for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-bias'
+  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-bias'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-bias'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-bias'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-bias/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-bias.gemspec Gemfile LICENSE]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/bias/actors/update.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Bias
+      module Actor
+        class Update < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::Bias::Runners::Bias
+          end
+
+          def runner_function
+            'update_bias'
+          end
+
+          def time
+            60
+          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/bias/client.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/helpers/constants'
+require 'legion/extensions/bias/helpers/bias_event'
+require 'legion/extensions/bias/helpers/bias_detector'
+require 'legion/extensions/bias/helpers/bias_store'
+require 'legion/extensions/bias/runners/bias'
+
+module Legion
+  module Extensions
+    module Bias
+      class Client
+        include Runners::Bias
+
+        def initialize(**)
+          @bias_detector = Helpers::BiasDetector.new
+          @bias_store    = Helpers::BiasStore.new
+        end
+
+        private
+
+        attr_reader :bias_detector, :bias_store
+      end
+    end
+  end
+end

data/lib/legion/extensions/bias/helpers/bias_detector.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Bias
+      module Helpers
+        class BiasDetector
+          include Constants
+
+          def initialize
+            @susceptibility = Constants::BIAS_TYPES.to_h { |b| [b, Constants::DEFAULT_SUSCEPTIBILITY] }
+          end
+
+          def detect_anchoring(current_value:, anchor_value:, domain: nil) # rubocop:disable Lint/UnusedMethodArgument
+            return 0.0 if anchor_value.nil? || anchor_value.zero?
+
+            distance = (current_value - anchor_value).abs.to_f / anchor_value.abs
+            pull      = 1.0 - distance.clamp(0.0, 1.0)
+            magnitude = pull * susceptibility_for(:anchoring)
+            update_susceptibility(:anchoring, detected: magnitude >= Constants::DETECTION_THRESHOLD)
+            magnitude.clamp(0.0, 1.0)
+          end
+
+          def detect_confirmation(evidence_direction:, hypothesis_direction:, domain: nil) # rubocop:disable Lint/UnusedMethodArgument
+            magnitude = if evidence_direction == hypothesis_direction
+                          Constants::CONFIRMATION_WEIGHT * susceptibility_for(:confirmation)
+                        else
+                          (1.0 - Constants::CONFIRMATION_WEIGHT) * susceptibility_for(:confirmation)
+                        end
+            update_susceptibility(:confirmation, detected: magnitude >= Constants::DETECTION_THRESHOLD)
+            magnitude.clamp(0.0, 1.0)
+          end
+
+          def detect_availability(recent_events:, domain: nil) # rubocop:disable Lint/UnusedMethodArgument
+            window    = Constants::AVAILABILITY_RECENCY_WINDOW
+            density   = [recent_events.size, window].min.to_f / window
+            magnitude = density * susceptibility_for(:availability)
+            update_susceptibility(:availability, detected: magnitude >= Constants::DETECTION_THRESHOLD)
+            magnitude.clamp(0.0, 1.0)
+          end
+
+          def detect_recency(data_points:, domain: nil) # rubocop:disable Lint/UnusedMethodArgument
+            return 0.0 if data_points.size < 2
+
+            total = data_points.size
+            half  = total / 2
+            recent_half  = data_points.last(half)
+            earlier_half = data_points.first(half)
+
+            recent_mean  = mean(recent_half)
+            earlier_mean = mean(earlier_half)
+
+            range = (data_points.max - data_points.min).to_f
+            return 0.0 if range.zero?
+
+            skew      = (recent_mean - earlier_mean).abs / range
+            magnitude = skew * susceptibility_for(:recency)
+            update_susceptibility(:recency, detected: magnitude >= Constants::DETECTION_THRESHOLD)
+            magnitude.clamp(0.0, 1.0)
+          end
+
+          def detect_sunk_cost(invested:, expected_return:, domain: nil) # rubocop:disable Lint/UnusedMethodArgument
+            return 0.0 if invested <= 0
+
+            ratio     = invested.to_f / (invested + expected_return.abs + 1.0)
+            magnitude = ratio * susceptibility_for(:sunk_cost)
+            update_susceptibility(:sunk_cost, detected: magnitude >= Constants::DETECTION_THRESHOLD)
+            magnitude.clamp(0.0, 1.0)
+          end
+
+          def susceptibility_for(bias_type)
+            @susceptibility.fetch(bias_type, Constants::DEFAULT_SUSCEPTIBILITY)
+          end
+
+          def update_susceptibility(bias_type, detected:)
+            return unless @susceptibility.key?(bias_type)
+
+            alpha   = Constants::SUSCEPTIBILITY_ALPHA
+            signal  = detected ? 1.0 : 0.0
+            current = @susceptibility[bias_type]
+            @susceptibility[bias_type] = ((alpha * signal) + ((1.0 - alpha) * current)).clamp(0.0, 1.0)
+          end
+
+          def correction_for(magnitude)
+            (magnitude * Constants::CORRECTION_FACTOR).clamp(0.0, 1.0)
+          end
+
+          def to_h
+            { susceptibility: @susceptibility.dup }
+          end
+
+          private
+
+          def mean(values)
+            return 0.0 if values.empty?
+
+            values.sum.to_f / values.size
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/bias/helpers/bias_event.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Bias
+      module Helpers
+        class BiasEvent
+          attr_reader :id, :bias_type, :domain, :magnitude, :corrected,
+                      :correction_applied, :context, :timestamp
+
+          def initialize(bias_type:, domain:, magnitude:, **opts)
+            @id                 = SecureRandom.uuid
+            @bias_type          = bias_type
+            @domain             = domain
+            @magnitude          = magnitude
+            @corrected          = opts.fetch(:corrected, false)
+            @correction_applied = opts.fetch(:correction_applied, 0.0)
+            @context            = opts.fetch(:context, {})
+            @timestamp          = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              bias_type:          @bias_type,
+              domain:             @domain,
+              magnitude:          @magnitude,
+              corrected:          @corrected,
+              correction_applied: @correction_applied,
+              context:            @context,
+              timestamp:          @timestamp
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/bias/helpers/bias_store.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Bias
+      module Helpers
+        class BiasStore
+          def initialize
+            @events  = []
+            @anchors = {} # domain -> array of { value:, influence:, recorded_at: }
+          end
+
+          def record(event)
+            @events << event
+            @events.shift while @events.size > Constants::MAX_BIAS_EVENTS
+            event
+          end
+
+          def recent(count = 10)
+            @events.last(count).map(&:to_h)
+          end
+
+          def by_type(bias_type)
+            @events.select { |e| e.bias_type == bias_type }.map(&:to_h)
+          end
+
+          def by_domain(domain)
+            @events.select { |e| e.domain == domain }.map(&:to_h)
+          end
+
+          def register_anchor(domain, value:, influence: 1.0)
+            @anchors[domain] ||= []
+            @anchors[domain] << { value: value, influence: influence, recorded_at: Time.now.utc }
+            @anchors[domain].shift while @anchors[domain].size > Constants::MAX_ANCHORS
+          end
+
+          def anchors_for(domain)
+            @anchors.fetch(domain, [])
+          end
+
+          def decay_anchors
+            @anchors.each_value do |anchor_list|
+              anchor_list.each { |a| a[:influence] = (a[:influence] - Constants::ANCHOR_DECAY).clamp(0.0, 1.0) }
+              anchor_list.reject! { |a| a[:influence] <= 0.0 }
+            end
+          end
+
+          def stats
+            return { total: 0, by_type: {}, by_domain: {} } if @events.empty?
+
+            by_type = Constants::BIAS_TYPES.to_h do |bt|
+              events = @events.select { |e| e.bias_type == bt }
+              avg_mag = events.empty? ? 0.0 : events.sum(&:magnitude) / events.size
+              [bt, { count: events.size, avg_magnitude: avg_mag.round(4) }]
+            end
+
+            domains = @events.map(&:domain).uniq
+            by_domain = domains.to_h do |d|
+              events = @events.select { |e| e.domain == d }
+              [d, { count: events.size }]
+            end
+
+            {
+              total:     @events.size,
+              by_type:   by_type,
+              by_domain: by_domain
+            }
+          end
+
+          def to_h
+            {
+              total_events:   @events.size,
+              anchor_domains: @anchors.keys
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Bias
+      module Helpers
+        module Constants
+          BIAS_TYPES = %i[anchoring confirmation availability recency sunk_cost].freeze
+
+          DETECTION_THRESHOLD          = 0.3   # above this = bias likely influencing decision
+          CORRECTION_FACTOR            = 0.5   # how much to correct when bias detected
+          DEFAULT_SUSCEPTIBILITY       = 0.5   # starting susceptibility per bias
+          SUSCEPTIBILITY_ALPHA         = 0.1   # EMA alpha for updating susceptibility
+          DECAY_RATE                   = 0.02  # how fast bias activation decays per tick
+          MAX_BIAS_EVENTS              = 200   # max tracked bias events
+          MAX_ANCHORS                  = 50    # max tracked anchor values
+          ANCHOR_DECAY                 = 0.05  # how fast anchor influence decays
+          CONFIRMATION_WEIGHT          = 0.7   # weight of confirming vs disconfirming evidence
+          AVAILABILITY_RECENCY_WINDOW  = 10    # recent events window for availability heuristic
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Bias
+      module Runners
+        module Bias
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def check_for_bias(domain:, decision_context: {}, **)
+            Legion::Logging.debug "[bias] check_for_bias domain=#{domain}"
+            detected = collect_bias_detections(domain, decision_context)
+            active   = detected.select { |b| b[:magnitude] >= Helpers::Constants::DETECTION_THRESHOLD }
+            Legion::Logging.debug "[bias] check_for_bias domain=#{domain} detected=#{active.size}"
+            { success: true, domain: domain, detected: active, all: detected }
+          end
+
+          def record_anchor(domain:, value:, **)
+            bias_store.register_anchor(domain, value: value)
+            Legion::Logging.debug "[bias] anchor recorded domain=#{domain} value=#{value}"
+            { success: true, domain: domain, value: value }
+          end
+
+          def update_bias(**)
+            bias_store.decay_anchors
+            Legion::Logging.debug '[bias] update_bias: anchors decayed'
+            { success: true }
+          end
+
+          def bias_report(domain: nil, **)
+            events = domain ? bias_store.by_domain(domain) : bias_store.recent(50)
+            Legion::Logging.debug "[bias] bias_report domain=#{domain.inspect} events=#{events.size}"
+            { success: true, domain: domain, events: events, count: events.size }
+          end
+
+          def susceptibility_profile(**)
+            profile = bias_detector.to_h
+            Legion::Logging.debug '[bias] susceptibility_profile'
+            { success: true, **profile }
+          end
+
+          def bias_stats(**)
+            stats = bias_store.stats
+            Legion::Logging.debug "[bias] bias_stats total=#{stats[:total]}"
+            { success: true, **stats }
+          end
+
+          private
+
+          def bias_detector
+            @bias_detector ||= Helpers::BiasDetector.new
+          end
+
+          def bias_store
+            @bias_store ||= Helpers::BiasStore.new
+          end
+
+          def collect_bias_detections(domain, ctx)
+            results = []
+            results.concat(detect_anchoring_bias(domain, ctx))
+            results.concat(detect_confirmation_bias(domain, ctx))
+            results.concat(detect_availability_bias(domain, ctx))
+            results.concat(detect_recency_bias(domain, ctx))
+            results.concat(detect_sunk_cost_bias(domain, ctx))
+            results
+          end
+
+          def detect_anchoring_bias(domain, ctx)
+            anchors = bias_store.anchors_for(domain)
+            return [] unless anchors.any? && ctx[:current_value]
+
+            anchor_value = anchors.max_by { |a| a[:influence] }&.dig(:value)
+            return [] unless anchor_value
+
+            mag = bias_detector.detect_anchoring(
+              current_value: ctx[:current_value],
+              anchor_value:  anchor_value,
+              domain:        domain
+            )
+            [build_bias_result(:anchoring, domain, mag, ctx)]
+          end
+
+          def detect_confirmation_bias(domain, ctx)
+            return [] unless ctx[:evidence_direction] && ctx[:hypothesis_direction]
+
+            mag = bias_detector.detect_confirmation(
+              evidence_direction:   ctx[:evidence_direction],
+              hypothesis_direction: ctx[:hypothesis_direction],
+              domain:               domain
+            )
+            [build_bias_result(:confirmation, domain, mag, ctx)]
+          end
+
+          def detect_availability_bias(domain, ctx)
+            return [] unless ctx[:recent_events]
+
+            mag = bias_detector.detect_availability(recent_events: ctx[:recent_events], domain: domain)
+            [build_bias_result(:availability, domain, mag, ctx)]
+          end
+
+          def detect_recency_bias(domain, ctx)
+            return [] unless ctx[:data_points]
+
+            mag = bias_detector.detect_recency(data_points: ctx[:data_points], domain: domain)
+            [build_bias_result(:recency, domain, mag, ctx)]
+          end
+
+          def detect_sunk_cost_bias(domain, ctx)
+            return [] unless ctx[:invested] && !ctx[:expected_return].nil?
+
+            mag = bias_detector.detect_sunk_cost(
+              invested:        ctx[:invested],
+              expected_return: ctx[:expected_return],
+              domain:          domain
+            )
+            [build_bias_result(:sunk_cost, domain, mag, ctx)]
+          end
+
+          def build_bias_result(bias_type, domain, magnitude, context)
+            correction = bias_detector.correction_for(magnitude)
+            corrected  = magnitude >= Helpers::Constants::DETECTION_THRESHOLD
+
+            if corrected
+              event = Helpers::BiasEvent.new(
+                bias_type:          bias_type,
+                domain:             domain,
+                magnitude:          magnitude,
+                corrected:          corrected,
+                correction_applied: correction,
+                context:            context
+              )
+              bias_store.record(event)
+            end
+
+            {
+              bias_type:          bias_type,
+              magnitude:          magnitude,
+              corrected:          corrected,
+              correction_applied: correction
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/bias.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/version'
+require 'legion/extensions/bias/helpers/constants'
+require 'legion/extensions/bias/helpers/bias_event'
+require 'legion/extensions/bias/helpers/bias_detector'
+require 'legion/extensions/bias/helpers/bias_store'
+require 'legion/extensions/bias/runners/bias'
+
+module Legion
+  module Extensions
+    module Bias
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/client'
+
+RSpec.describe Legion::Extensions::Bias::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:check_for_bias)
+    expect(client).to respond_to(:record_anchor)
+    expect(client).to respond_to(:update_bias)
+    expect(client).to respond_to(:bias_report)
+    expect(client).to respond_to(:susceptibility_profile)
+    expect(client).to respond_to(:bias_stats)
+  end
+end

data/spec/legion/extensions/bias/helpers/bias_detector_spec.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/helpers/constants'
+require 'legion/extensions/bias/helpers/bias_detector'
+
+RSpec.describe Legion::Extensions::Bias::Helpers::BiasDetector do
+  subject(:detector) { described_class.new }
+
+  describe '#susceptibility_for' do
+    it 'returns DEFAULT_SUSCEPTIBILITY for all bias types at init' do
+      Legion::Extensions::Bias::Helpers::Constants::BIAS_TYPES.each do |bt|
+        expect(detector.susceptibility_for(bt)).to eq(
+          Legion::Extensions::Bias::Helpers::Constants::DEFAULT_SUSCEPTIBILITY
+        )
+      end
+    end
+  end
+
+  describe '#detect_anchoring' do
+    it 'returns high magnitude when current value is very close to anchor' do
+      mag = detector.detect_anchoring(current_value: 100.0, anchor_value: 100.0)
+      expect(mag).to be_within(0.01).of(0.5) # pull=1.0 * susceptibility=0.5
+    end
+
+    it 'returns low magnitude when current value is far from anchor' do
+      mag = detector.detect_anchoring(current_value: 200.0, anchor_value: 100.0)
+      expect(mag).to be < 0.3
+    end
+
+    it 'returns 0.0 when anchor_value is zero' do
+      mag = detector.detect_anchoring(current_value: 50.0, anchor_value: 0.0)
+      expect(mag).to eq(0.0)
+    end
+
+    it 'returns 0.0 when anchor_value is nil' do
+      mag = detector.detect_anchoring(current_value: 50.0, anchor_value: nil)
+      expect(mag).to eq(0.0)
+    end
+
+    it 'clamps result to [0, 1]' do
+      mag = detector.detect_anchoring(current_value: 100.0, anchor_value: 100.0)
+      expect(mag).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#detect_confirmation' do
+    it 'returns higher magnitude when evidence matches hypothesis' do
+      mag_match = detector.detect_confirmation(
+        evidence_direction:   :positive,
+        hypothesis_direction: :positive
+      )
+      mag_mismatch = detector.detect_confirmation(
+        evidence_direction:   :negative,
+        hypothesis_direction: :positive
+      )
+      expect(mag_match).to be > mag_mismatch
+    end
+
+    it 'returns magnitude >= CONFIRMATION_WEIGHT * susceptibility when matching' do
+      mag = detector.detect_confirmation(
+        evidence_direction:   :up,
+        hypothesis_direction: :up
+      )
+      expected = Legion::Extensions::Bias::Helpers::Constants::CONFIRMATION_WEIGHT *
+                 Legion::Extensions::Bias::Helpers::Constants::DEFAULT_SUSCEPTIBILITY
+      expect(mag).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#detect_availability' do
+    it 'returns higher magnitude with more recent events' do
+      mag_full = detector.detect_availability(recent_events: Array.new(10, :event))
+      mag_none = detector.detect_availability(recent_events: [])
+      expect(mag_full).to be > mag_none
+    end
+
+    it 'returns 0 with empty recent_events' do
+      mag = detector.detect_availability(recent_events: [])
+      expect(mag).to eq(0.0)
+    end
+  end
+
+  describe '#detect_recency' do
+    it 'returns 0 with fewer than 2 data points' do
+      mag = detector.detect_recency(data_points: [1.0])
+      expect(mag).to eq(0.0)
+    end
+
+    it 'returns 0 when all values are equal (zero range)' do
+      mag = detector.detect_recency(data_points: [5.0, 5.0, 5.0, 5.0])
+      expect(mag).to eq(0.0)
+    end
+
+    it 'returns higher magnitude when recent half differs significantly from earlier half' do
+      early = [1.0, 1.0, 1.0, 1.0]
+      recent = [9.0, 9.0, 9.0, 9.0]
+      mag = detector.detect_recency(data_points: early + recent)
+      expect(mag).to be > 0.3
+    end
+  end
+
+  describe '#detect_sunk_cost' do
+    it 'returns 0 when invested is 0' do
+      mag = detector.detect_sunk_cost(invested: 0, expected_return: 100)
+      expect(mag).to eq(0.0)
+    end
+
+    it 'returns higher magnitude with large investment and low expected return' do
+      mag = detector.detect_sunk_cost(invested: 1_000_000, expected_return: 1)
+      expect(mag).to be > 0.3
+    end
+
+    it 'returns lower magnitude with small investment and large expected return' do
+      mag = detector.detect_sunk_cost(invested: 1, expected_return: 1_000_000)
+      expect(mag).to be < 0.1
+    end
+  end
+
+  describe '#correction_for' do
+    it 'applies CORRECTION_FACTOR to magnitude' do
+      result = detector.correction_for(0.6)
+      expect(result).to be_within(0.001).of(
+        0.6 * Legion::Extensions::Bias::Helpers::Constants::CORRECTION_FACTOR
+      )
+    end
+
+    it 'clamps to [0, 1]' do
+      expect(detector.correction_for(2.0)).to eq(1.0)
+      expect(detector.correction_for(-1.0)).to eq(0.0)
+    end
+  end
+
+  describe '#update_susceptibility' do
+    it 'increases susceptibility toward 1.0 when repeatedly detected' do
+      initial = detector.susceptibility_for(:anchoring)
+      10.times { detector.update_susceptibility(:anchoring, detected: true) }
+      expect(detector.susceptibility_for(:anchoring)).to be > initial
+    end
+
+    it 'decreases susceptibility toward 0.0 when not detected' do
+      initial = detector.susceptibility_for(:anchoring)
+      10.times { detector.update_susceptibility(:anchoring, detected: false) }
+      expect(detector.susceptibility_for(:anchoring)).to be < initial
+    end
+
+    it 'ignores unknown bias types' do
+      expect { detector.update_susceptibility(:unknown_bias, detected: true) }.not_to raise_error
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns susceptibility hash' do
+      h = detector.to_h
+      expect(h[:susceptibility]).to be_a(Hash)
+      expect(h[:susceptibility].keys).to match_array(
+        Legion::Extensions::Bias::Helpers::Constants::BIAS_TYPES
+      )
+    end
+  end
+end

data/spec/legion/extensions/bias/helpers/bias_event_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/helpers/bias_event'
+
+RSpec.describe Legion::Extensions::Bias::Helpers::BiasEvent do
+  let(:event) do
+    described_class.new(
+      bias_type:          :anchoring,
+      domain:             :finance,
+      magnitude:          0.6,
+      corrected:          true,
+      correction_applied: 0.3,
+      context:            { current_value: 100 }
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns bias_type' do
+      expect(event.bias_type).to eq(:anchoring)
+    end
+
+    it 'assigns domain' do
+      expect(event.domain).to eq(:finance)
+    end
+
+    it 'assigns magnitude' do
+      expect(event.magnitude).to eq(0.6)
+    end
+
+    it 'assigns corrected flag' do
+      expect(event.corrected).to be true
+    end
+
+    it 'assigns correction_applied' do
+      expect(event.correction_applied).to eq(0.3)
+    end
+
+    it 'assigns context' do
+      expect(event.context).to eq({ current_value: 100 })
+    end
+
+    it 'sets timestamp to a Time' do
+      expect(event.timestamp).to be_a(Time)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = event.to_h
+      expect(h[:id]).to eq(event.id)
+      expect(h[:bias_type]).to eq(:anchoring)
+      expect(h[:domain]).to eq(:finance)
+      expect(h[:magnitude]).to eq(0.6)
+      expect(h[:corrected]).to be true
+      expect(h[:correction_applied]).to eq(0.3)
+      expect(h[:context]).to eq({ current_value: 100 })
+      expect(h[:timestamp]).to be_a(Time)
+    end
+  end
+end

data/spec/legion/extensions/bias/helpers/bias_store_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/helpers/constants'
+require 'legion/extensions/bias/helpers/bias_event'
+require 'legion/extensions/bias/helpers/bias_store'
+
+RSpec.describe Legion::Extensions::Bias::Helpers::BiasStore do
+  subject(:store) { described_class.new }
+
+  let(:event) do
+    Legion::Extensions::Bias::Helpers::BiasEvent.new(
+      bias_type: :anchoring,
+      domain:    :finance,
+      magnitude: 0.6
+    )
+  end
+
+  let(:event2) do
+    Legion::Extensions::Bias::Helpers::BiasEvent.new(
+      bias_type: :confirmation,
+      domain:    :research,
+      magnitude: 0.4
+    )
+  end
+
+  describe '#record' do
+    it 'stores an event and returns it' do
+      result = store.record(event)
+      expect(result).to eq(event)
+    end
+
+    it 'trims events at MAX_BIAS_EVENTS' do
+      max = Legion::Extensions::Bias::Helpers::Constants::MAX_BIAS_EVENTS
+      (max + 10).times do
+        store.record(Legion::Extensions::Bias::Helpers::BiasEvent.new(
+                       bias_type: :recency,
+                       domain:    :test,
+                       magnitude: 0.1
+                     ))
+      end
+      expect(store.recent(max + 10).size).to eq(max)
+    end
+  end
+
+  describe '#recent' do
+    it 'returns the most recent events as hashes' do
+      store.record(event)
+      store.record(event2)
+      result = store.recent(2)
+      expect(result.size).to eq(2)
+      expect(result.first).to be_a(Hash)
+    end
+
+    it 'returns fewer than requested when not enough events' do
+      store.record(event)
+      expect(store.recent(10).size).to eq(1)
+    end
+  end
+
+  describe '#by_type' do
+    it 'returns only events matching bias_type' do
+      store.record(event)
+      store.record(event2)
+      result = store.by_type(:anchoring)
+      expect(result.size).to eq(1)
+      expect(result.first[:bias_type]).to eq(:anchoring)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns only events matching domain' do
+      store.record(event)
+      store.record(event2)
+      result = store.by_domain(:finance)
+      expect(result.size).to eq(1)
+      expect(result.first[:domain]).to eq(:finance)
+    end
+  end
+
+  describe '#register_anchor and #anchors_for' do
+    it 'stores anchor values for a domain' do
+      store.register_anchor(:pricing, value: 99.99)
+      anchors = store.anchors_for(:pricing)
+      expect(anchors.size).to eq(1)
+      expect(anchors.first[:value]).to eq(99.99)
+    end
+
+    it 'returns empty array for unknown domain' do
+      expect(store.anchors_for(:nonexistent)).to eq([])
+    end
+
+    it 'trims anchors at MAX_ANCHORS' do
+      max = Legion::Extensions::Bias::Helpers::Constants::MAX_ANCHORS
+      (max + 5).times { |i| store.register_anchor(:domain, value: i) }
+      expect(store.anchors_for(:domain).size).to eq(max)
+    end
+  end
+
+  describe '#decay_anchors' do
+    it 'reduces anchor influence' do
+      store.register_anchor(:pricing, value: 100.0, influence: 1.0)
+      store.decay_anchors
+      anchor = store.anchors_for(:pricing).first
+      expect(anchor[:influence]).to be < 1.0
+    end
+
+    it 'removes anchors with influence at or below 0' do
+      store.register_anchor(:pricing, value: 1.0, influence: 0.01)
+      store.decay_anchors
+      expect(store.anchors_for(:pricing)).to be_empty
+    end
+  end
+
+  describe '#stats' do
+    it 'returns total 0 with empty store' do
+      result = store.stats
+      expect(result[:total]).to eq(0)
+    end
+
+    it 'aggregates counts and avg_magnitude per type' do
+      store.record(event)
+      stats = store.stats
+      expect(stats[:by_type][:anchoring][:count]).to eq(1)
+      expect(stats[:by_type][:anchoring][:avg_magnitude]).to eq(0.6)
+    end
+
+    it 'aggregates by domain' do
+      store.record(event)
+      stats = store.stats
+      expect(stats[:by_domain][:finance][:count]).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns total_events and anchor_domains' do
+      store.record(event)
+      store.register_anchor(:pricing, value: 50.0)
+      h = store.to_h
+      expect(h[:total_events]).to eq(1)
+      expect(h[:anchor_domains]).to include(:pricing)
+    end
+  end
+end

data/spec/legion/extensions/bias/runners/bias_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/bias/client'
+
+RSpec.describe Legion::Extensions::Bias::Runners::Bias do
+  let(:client) { Legion::Extensions::Bias::Client.new }
+
+  describe '#record_anchor' do
+    it 'returns success: true' do
+      result = client.record_anchor(domain: :finance, value: 100.0)
+      expect(result[:success]).to be true
+      expect(result[:domain]).to eq(:finance)
+      expect(result[:value]).to eq(100.0)
+    end
+  end
+
+  describe '#check_for_bias' do
+    context 'with no decision context' do
+      it 'returns success: true with empty detected list' do
+        result = client.check_for_bias(domain: :test)
+        expect(result[:success]).to be true
+        expect(result[:detected]).to be_empty
+      end
+    end
+
+    context 'with anchoring context' do
+      before { client.record_anchor(domain: :finance, value: 100.0) }
+
+      it 'detects anchoring when current value is close to anchor' do
+        result = client.check_for_bias(
+          domain:           :finance,
+          decision_context: { current_value: 101.0 }
+        )
+        expect(result[:success]).to be true
+        anchoring = result[:all].find { |b| b[:bias_type] == :anchoring }
+        expect(anchoring).not_to be_nil
+        expect(anchoring[:magnitude]).to be > 0.0
+      end
+    end
+
+    context 'with confirmation bias context' do
+      it 'detects confirmation bias when evidence matches hypothesis' do
+        result = client.check_for_bias(
+          domain:           :research,
+          decision_context: {
+            evidence_direction:   :positive,
+            hypothesis_direction: :positive
+          }
+        )
+        confirmation = result[:all].find { |b| b[:bias_type] == :confirmation }
+        expect(confirmation[:magnitude]).to be > 0.0
+      end
+    end
+
+    context 'with availability bias context' do
+      it 'detects availability bias with recent events' do
+        result = client.check_for_bias(
+          domain:           :safety,
+          decision_context: { recent_events: Array.new(10, :incident) }
+        )
+        availability = result[:all].find { |b| b[:bias_type] == :availability }
+        expect(availability[:magnitude]).to be > 0.0
+      end
+    end
+
+    context 'with recency bias context' do
+      it 'detects recency bias with skewed data points' do
+        data = [1.0, 1.0, 1.0, 1.0, 9.0, 9.0, 9.0, 9.0]
+        result = client.check_for_bias(
+          domain:           :market,
+          decision_context: { data_points: data }
+        )
+        recency = result[:all].find { |b| b[:bias_type] == :recency }
+        expect(recency[:magnitude]).to be > 0.0
+      end
+    end
+
+    context 'with sunk cost bias context' do
+      it 'detects sunk cost bias with high investment and low return' do
+        result = client.check_for_bias(
+          domain:           :project,
+          decision_context: { invested: 1_000_000, expected_return: 100 }
+        )
+        sunk = result[:all].find { |b| b[:bias_type] == :sunk_cost }
+        expect(sunk[:magnitude]).to be > 0.0
+      end
+    end
+
+    it 'marks bias as corrected when magnitude exceeds threshold' do
+      client.record_anchor(domain: :finance, value: 100.0)
+      result = client.check_for_bias(
+        domain:           :finance,
+        decision_context: { current_value: 100.0 }
+      )
+      anchoring = result[:all].find { |b| b[:bias_type] == :anchoring }
+      if anchoring[:magnitude] >= Legion::Extensions::Bias::Helpers::Constants::DETECTION_THRESHOLD
+        expect(anchoring[:corrected]).to be true
+        expect(anchoring[:correction_applied]).to be > 0.0
+      end
+    end
+  end
+
+  describe '#update_bias' do
+    it 'returns success: true' do
+      result = client.update_bias
+      expect(result[:success]).to be true
+    end
+
+    it 'decays anchor influence' do
+      client.record_anchor(domain: :pricing, value: 50.0)
+      client.update_bias
+    end
+  end
+
+  describe '#bias_report' do
+    it 'returns success: true with empty events on fresh client' do
+      result = client.bias_report
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'filters by domain when provided' do
+      client.record_anchor(domain: :finance, value: 100.0)
+      client.check_for_bias(domain: :finance, decision_context: { current_value: 100.0 })
+      result = client.bias_report(domain: :finance)
+      expect(result[:domain]).to eq(:finance)
+    end
+  end
+
+  describe '#susceptibility_profile' do
+    it 'returns success: true with susceptibility hash' do
+      result = client.susceptibility_profile
+      expect(result[:success]).to be true
+      expect(result[:susceptibility]).to be_a(Hash)
+      expect(result[:susceptibility].keys).to match_array(
+        Legion::Extensions::Bias::Helpers::Constants::BIAS_TYPES
+      )
+    end
+  end
+
+  describe '#bias_stats' do
+    it 'returns success: true' do
+      result = client.bias_stats
+      expect(result[:success]).to be true
+      expect(result[:total]).to eq(0)
+    end
+
+    it 'reflects recorded events' do
+      client.record_anchor(domain: :finance, value: 100.0)
+      client.check_for_bias(domain: :finance, decision_context: { current_value: 100.0 })
+      result = client.bias_stats
+      expect(result[:total]).to be >= 0
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/bias/client'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-bias
+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 bias detection and correction for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE
+- lex-bias.gemspec
+- lib/legion/extensions/bias.rb
+- lib/legion/extensions/bias/actors/update.rb
+- lib/legion/extensions/bias/client.rb
+- lib/legion/extensions/bias/helpers/bias_detector.rb
+- lib/legion/extensions/bias/helpers/bias_event.rb
+- lib/legion/extensions/bias/helpers/bias_store.rb
+- lib/legion/extensions/bias/helpers/constants.rb
+- lib/legion/extensions/bias/runners/bias.rb
+- lib/legion/extensions/bias/version.rb
+- spec/legion/extensions/bias/client_spec.rb
+- spec/legion/extensions/bias/helpers/bias_detector_spec.rb
+- spec/legion/extensions/bias/helpers/bias_event_spec.rb
+- spec/legion/extensions/bias/helpers/bias_store_spec.rb
+- spec/legion/extensions/bias/runners/bias_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-bias
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-bias
+  source_code_uri: https://github.com/LegionIO/lex-bias
+  documentation_uri: https://github.com/LegionIO/lex-bias
+  changelog_uri: https://github.com/LegionIO/lex-bias
+  bug_tracker_uri: https://github.com/LegionIO/lex-bias/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: LEX Bias
+test_files: []