lex-causal-attribution 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55c6a453c0a0102f9922c5fcd31988701ff6d3a683ecaa84512165532caeb10a
+  data.tar.gz: ed1593cdba918561fcbb2ac9c93a994d42386afe628c89f5079b3ebd790fef67
+SHA512:
+  metadata.gz: c6bded9b8ef506d179343b15c256978246aa371c900f0e366030355bdd73c8d9462f5712114c49c96aab62c2c92342f03981b8f935bb86ec729cb8dfe07a4734
+  data.tar.gz: e01f123090aab3668fe2d80090d0417cc1a3889b10acde2e0802bc79aea2b295d38d75fa5b4a49a7e7febbfd41c0837a1ab7945a7aa4695a1ab5afbb2a36023b

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-causal-attribution.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/causal_attribution/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-causal-attribution'
+  spec.version       = Legion::Extensions::CausalAttribution::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Causal Attribution'
+  spec.description   = "Weiner's attribution theory for brain-modeled agentic AI — locus, stability, controllability"
+  spec.homepage      = 'https://github.com/LegionIO/lex-causal-attribution'
+  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-causal-attribution'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-causal-attribution'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-causal-attribution'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-causal-attribution/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-causal-attribution.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_attribution/helpers/attribution'
+require 'legion/extensions/causal_attribution/helpers/attribution_engine'
+require 'legion/extensions/causal_attribution/runners/causal_attribution'
+
+module Legion
+  module Extensions
+    module CausalAttribution
+      class Client
+        include Runners::CausalAttribution
+
+        def initialize(**)
+          @engine = Helpers::AttributionEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/causal_attribution/helpers/attribution.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CausalAttribution
+      module Helpers
+        class Attribution
+          MAX_ATTRIBUTIONS = 200
+          MAX_HISTORY      = 300
+
+          LOCUS_VALUES           = %i[internal external].freeze
+          STABILITY_VALUES       = %i[stable unstable].freeze
+          CONTROLLABILITY_VALUES = %i[controllable uncontrollable].freeze
+
+          DEFAULT_CONFIDENCE  = 0.5
+          CONFIDENCE_FLOOR    = 0.0
+          CONFIDENCE_CEILING  = 1.0
+          DECAY_RATE          = 0.02
+
+          ATTRIBUTION_EMOTIONS = {
+            %i[internal stable controllable]     => :guilt,
+            %i[internal stable uncontrollable]   => :shame,
+            %i[internal unstable controllable]   => :regret,
+            %i[internal unstable uncontrollable] => :surprise,
+            %i[external stable controllable]     => :anger,
+            %i[external stable uncontrollable]   => :helplessness,
+            %i[external unstable controllable]   => :frustration,
+            %i[external unstable uncontrollable] => :relief
+          }.freeze
+
+          attr_reader :id, :event, :outcome, :domain, :locus, :stability, :controllability,
+                      :confidence, :emotional_response, :created_at
+
+          def initialize(event:, outcome:, domain:, locus:, stability:, controllability:,
+                         confidence: DEFAULT_CONFIDENCE)
+            @id                = SecureRandom.uuid
+            @event             = event
+            @outcome           = outcome
+            @domain            = domain
+            @locus             = locus
+            @stability         = stability
+            @controllability   = controllability
+            @confidence        = confidence.clamp(CONFIDENCE_FLOOR, CONFIDENCE_CEILING)
+            @emotional_response = ATTRIBUTION_EMOTIONS[pattern]
+            @created_at        = Time.now.utc
+          end
+
+          def pattern
+            [locus, stability, controllability]
+          end
+
+          def internal?
+            locus == :internal
+          end
+
+          def external?
+            locus == :external
+          end
+
+          def stable?
+            stability == :stable
+          end
+
+          def controllable?
+            controllability == :controllable
+          end
+
+          def to_h
+            {
+              id:                 id,
+              event:              event,
+              outcome:            outcome,
+              domain:             domain,
+              locus:              locus,
+              stability:          stability,
+              controllability:    controllability,
+              confidence:         confidence,
+              emotional_response: emotional_response,
+              created_at:         created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/causal_attribution/helpers/attribution_engine.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CausalAttribution
+      module Helpers
+        class AttributionEngine
+          def initialize
+            @attributions = {}
+            @history      = []
+          end
+
+          def create_attribution(event:, outcome:, domain:, locus:, stability:, controllability:,
+                                 confidence: Attribution::DEFAULT_CONFIDENCE)
+            trim_if_needed
+            attribution = Attribution.new(
+              event:           event,
+              outcome:         outcome,
+              domain:          domain,
+              locus:           locus,
+              stability:       stability,
+              controllability: controllability,
+              confidence:      confidence
+            )
+            @attributions[attribution.id] = attribution
+            attribution
+          end
+
+          def reattribute(attribution_id:, locus: nil, stability: nil, controllability: nil)
+            attr = @attributions[attribution_id]
+            return { found: false, attribution_id: attribution_id } unless attr
+
+            new_locus           = locus           || attr.locus
+            new_stability       = stability       || attr.stability
+            new_controllability = controllability || attr.controllability
+
+            updated = Attribution.new(
+              event:           attr.event,
+              outcome:         attr.outcome,
+              domain:          attr.domain,
+              locus:           new_locus,
+              stability:       new_stability,
+              controllability: new_controllability,
+              confidence:      attr.confidence
+            )
+            @history << attr.to_h if @history.size < Attribution::MAX_HISTORY
+            @attributions[attribution_id] = updated
+            updated
+          end
+
+          def by_pattern(locus: nil, stability: nil, controllability: nil)
+            @attributions.values.select do |a|
+              (locus.nil? || a.locus == locus) &&
+                (stability.nil?       || a.stability == stability) &&
+                (controllability.nil? || a.controllability == controllability)
+            end
+          end
+
+          def by_domain(domain:)
+            @attributions.values.select { |a| a.domain == domain }
+          end
+
+          def by_outcome(outcome:)
+            @attributions.values.select { |a| a.outcome == outcome }
+          end
+
+          def attribution_bias
+            return { bias: :none, detail: 'no attributions' } if @attributions.empty?
+
+            all     = @attributions.values
+            total   = all.size.to_f
+            locus   = bias_ratio(all, :locus, :external, total)
+            stab    = bias_ratio(all, :stability, :stable, total)
+            control = bias_ratio(all, :controllability, :uncontrollable, total)
+
+            failures = all.select { |a| a.outcome == :failure }
+            external_failure_ratio = failures.empty? ? 0.0 : failures.count(&:external?).to_f / failures.size
+
+            {
+              external_locus_ratio:       locus.round(3),
+              stable_ratio:               stab.round(3),
+              uncontrollable_ratio:       control.round(3),
+              external_failure_ratio:     external_failure_ratio.round(3),
+              self_serving_bias_detected: external_failure_ratio > 0.6,
+              total_attributions:         @attributions.size
+            }
+          end
+
+          def emotional_profile
+            counts = Hash.new(0)
+            @attributions.each_value { |a| counts[a.emotional_response] += 1 if a.emotional_response }
+            total = counts.values.sum.to_f
+            profile = counts.transform_values { |v| (v / total).round(3) }
+            dominant = counts.max_by { |_, v| v }&.first
+            { distribution: profile, dominant: dominant, total: counts.values.sum }
+          end
+
+          def most_common_pattern
+            return { pattern: nil, count: 0 } if @attributions.empty?
+
+            grouped = @attributions.values.group_by(&:pattern)
+            best    = grouped.max_by { |_, attrs| attrs.size }
+            { pattern: best[0], count: best[1].size }
+          end
+
+          def decay_all
+            decayed = 0
+            @attributions.each_value do |a|
+              new_conf = (a.confidence - Attribution::DECAY_RATE).clamp(
+                Attribution::CONFIDENCE_FLOOR, Attribution::CONFIDENCE_CEILING
+              )
+              a.instance_variable_set(:@confidence, new_conf)
+              decayed += 1
+            end
+            decayed
+          end
+
+          def count
+            @attributions.size
+          end
+
+          def to_h
+            {
+              total_attributions: @attributions.size,
+              history_size:       @history.size,
+              outcome_counts:     outcome_counts,
+              locus_counts:       locus_counts
+            }
+          end
+
+          private
+
+          def trim_if_needed
+            return unless @attributions.size >= Attribution::MAX_ATTRIBUTIONS
+
+            oldest_key = @attributions.min_by { |_, a| a.created_at }&.first
+            @attributions.delete(oldest_key)
+          end
+
+          def bias_ratio(all, dimension, value, total)
+            all.count { |a| a.public_send(dimension) == value } / total
+          end
+
+          def outcome_counts
+            @attributions.values.group_by(&:outcome).transform_values(&:size)
+          end
+
+          def locus_counts
+            @attributions.values.group_by(&:locus).transform_values(&:size)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CausalAttribution
+      module Runners
+        module CausalAttribution
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_causal_attribution(event:, outcome:, domain:, locus:, stability:, controllability:,
+                                        confidence: nil, **)
+            conf = (confidence || Helpers::Attribution::DEFAULT_CONFIDENCE)
+                   .clamp(Helpers::Attribution::CONFIDENCE_FLOOR, Helpers::Attribution::CONFIDENCE_CEILING)
+            attr = engine.create_attribution(
+              event:           event,
+              outcome:         outcome,
+              domain:          domain,
+              locus:           locus.to_sym,
+              stability:       stability.to_sym,
+              controllability: controllability.to_sym,
+              confidence:      conf
+            )
+            Legion::Logging.info "[causal_attribution] create id=#{attr.id} event=#{event} " \
+                                 "outcome=#{outcome} locus=#{locus} emotion=#{attr.emotional_response}"
+            { success: true, attribution: attr.to_h }
+          end
+
+          def reattribute_cause(attribution_id:, locus: nil, stability: nil, controllability: nil, **)
+            result = engine.reattribute(
+              attribution_id:  attribution_id,
+              locus:           locus&.to_sym,
+              stability:       stability&.to_sym,
+              controllability: controllability&.to_sym
+            )
+            if result.is_a?(Hash) && result[:found] == false
+              Legion::Logging.warn "[causal_attribution] reattribute not_found id=#{attribution_id}"
+              return { success: false, attribution_id: attribution_id, found: false }
+            end
+
+            Legion::Logging.debug "[causal_attribution] reattribute id=#{attribution_id} " \
+                                  "locus=#{result.locus} emotion=#{result.emotional_response}"
+            { success: true, attribution: result.to_h }
+          end
+
+          def attributions_by_pattern(locus: nil, stability: nil, controllability: nil, **)
+            results = engine.by_pattern(
+              locus:           locus&.to_sym,
+              stability:       stability&.to_sym,
+              controllability: controllability&.to_sym
+            )
+            Legion::Logging.debug "[causal_attribution] by_pattern count=#{results.size}"
+            { success: true, attributions: results.map(&:to_h), count: results.size }
+          end
+
+          def domain_attributions(domain:, **)
+            results = engine.by_domain(domain: domain.to_sym)
+            Legion::Logging.debug "[causal_attribution] by_domain domain=#{domain} count=#{results.size}"
+            { success: true, attributions: results.map(&:to_h), count: results.size }
+          end
+
+          def outcome_attributions(outcome:, **)
+            results = engine.by_outcome(outcome: outcome.to_sym)
+            Legion::Logging.debug "[causal_attribution] by_outcome outcome=#{outcome} count=#{results.size}"
+            { success: true, attributions: results.map(&:to_h), count: results.size }
+          end
+
+          def attribution_bias_assessment(**)
+            bias = engine.attribution_bias
+            Legion::Logging.debug "[causal_attribution] bias_assessment self_serving=#{bias[:self_serving_bias_detected]}"
+            { success: true, bias: bias }
+          end
+
+          def emotional_attribution_profile(**)
+            profile = engine.emotional_profile
+            Legion::Logging.debug "[causal_attribution] emotional_profile dominant=#{profile[:dominant]} total=#{profile[:total]}"
+            { success: true, profile: profile }
+          end
+
+          def most_common_attribution(**)
+            result = engine.most_common_pattern
+            Legion::Logging.debug "[causal_attribution] most_common pattern=#{result[:pattern].inspect} count=#{result[:count]}"
+            { success: true, pattern: result[:pattern], count: result[:count] }
+          end
+
+          def update_causal_attribution(**)
+            decayed = engine.decay_all
+            Legion::Logging.debug "[causal_attribution] decay cycle entries=#{decayed}"
+            { success: true, decayed: decayed }
+          end
+
+          def causal_attribution_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[causal_attribution] stats total=#{stats[:total_attributions]}"
+            { success: true, stats: stats }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::AttributionEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/causal_attribution.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_attribution/version'
+require 'legion/extensions/causal_attribution/helpers/attribution'
+require 'legion/extensions/causal_attribution/helpers/attribution_engine'
+require 'legion/extensions/causal_attribution/runners/causal_attribution'
+
+module Legion
+  module Extensions
+    module CausalAttribution
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_attribution/client'
+
+RSpec.describe Legion::Extensions::CausalAttribution::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    %i[
+      create_causal_attribution
+      reattribute_cause
+      attributions_by_pattern
+      domain_attributions
+      outcome_attributions
+      attribution_bias_assessment
+      emotional_attribution_profile
+      most_common_attribution
+      update_causal_attribution
+      causal_attribution_stats
+    ].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+end

data/spec/legion/extensions/causal_attribution/helpers/attribution_engine_spec.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CausalAttribution::Helpers::AttributionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:basic_args) do
+    {
+      event:           'task completed',
+      outcome:         :success,
+      domain:          :work,
+      locus:           :internal,
+      stability:       :stable,
+      controllability: :controllable
+    }
+  end
+
+  describe '#create_attribution' do
+    it 'returns an Attribution object' do
+      result = engine.create_attribution(**basic_args)
+      expect(result).to be_a(Legion::Extensions::CausalAttribution::Helpers::Attribution)
+    end
+
+    it 'stores the attribution' do
+      engine.create_attribution(**basic_args)
+      expect(engine.count).to eq(1)
+    end
+
+    it 'accepts optional confidence' do
+      attr = engine.create_attribution(**basic_args, confidence: 0.9)
+      expect(attr.confidence).to eq(0.9)
+    end
+  end
+
+  describe '#reattribute' do
+    let!(:attr) { engine.create_attribution(**basic_args) }
+
+    it 'updates locus when provided' do
+      result = engine.reattribute(attribution_id: attr.id, locus: :external)
+      expect(result.locus).to eq(:external)
+    end
+
+    it 'preserves unchanged dimensions' do
+      result = engine.reattribute(attribution_id: attr.id, locus: :external)
+      expect(result.stability).to eq(:stable)
+      expect(result.controllability).to eq(:controllable)
+    end
+
+    it 'updates the emotional_response after reattribution' do
+      result = engine.reattribute(attribution_id: attr.id, locus: :external)
+      expect(result.emotional_response).to eq(:anger)
+    end
+
+    it 'returns not found hash for unknown id' do
+      result = engine.reattribute(attribution_id: 'nonexistent')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#by_pattern' do
+    before do
+      engine.create_attribution(**basic_args)
+      engine.create_attribution(**basic_args, locus: :external)
+    end
+
+    it 'filters by locus' do
+      results = engine.by_pattern(locus: :internal)
+      expect(results.size).to eq(1)
+      expect(results.first.locus).to eq(:internal)
+    end
+
+    it 'returns all when no filter given' do
+      expect(engine.by_pattern.size).to eq(2)
+    end
+  end
+
+  describe '#by_domain' do
+    before do
+      engine.create_attribution(**basic_args)
+      engine.create_attribution(**basic_args, domain: :personal)
+    end
+
+    it 'returns only matching domain' do
+      results = engine.by_domain(domain: :work)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#by_outcome' do
+    before do
+      engine.create_attribution(**basic_args)
+      engine.create_attribution(**basic_args, outcome: :failure)
+    end
+
+    it 'returns only matching outcome' do
+      results = engine.by_outcome(outcome: :failure)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#attribution_bias' do
+    it 'returns bias hash with detection key' do
+      engine.create_attribution(**basic_args)
+      result = engine.attribution_bias
+      expect(result).to have_key(:self_serving_bias_detected)
+      expect(result).to have_key(:external_failure_ratio)
+    end
+
+    it 'detects self-serving bias when failures are mostly external' do
+      3.times do
+        engine.create_attribution(**basic_args, outcome: :failure, locus: :external, stability: :unstable, controllability: :controllable)
+      end
+      result = engine.attribution_bias
+      expect(result[:self_serving_bias_detected]).to be true
+    end
+
+    it 'returns no attributions message when empty' do
+      result = engine.attribution_bias
+      expect(result[:bias]).to eq(:none)
+    end
+  end
+
+  describe '#emotional_profile' do
+    before do
+      engine.create_attribution(**basic_args)
+      engine.create_attribution(**basic_args, locus: :external, stability: :unstable)
+    end
+
+    it 'returns distribution and dominant' do
+      result = engine.emotional_profile
+      expect(result).to have_key(:distribution)
+      expect(result).to have_key(:dominant)
+      expect(result[:total]).to eq(2)
+    end
+  end
+
+  describe '#most_common_pattern' do
+    before do
+      2.times { engine.create_attribution(**basic_args) }
+      engine.create_attribution(**basic_args, locus: :external)
+    end
+
+    it 'returns the most frequent pattern' do
+      result = engine.most_common_pattern
+      expect(result[:pattern]).to eq(%i[internal stable controllable])
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'returns nil pattern when empty' do
+      expect(described_class.new.most_common_pattern[:pattern]).to be_nil
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces confidence on all attributions' do
+      engine.create_attribution(**basic_args, confidence: 0.8)
+      engine.decay_all
+      expect(engine.by_pattern.first.confidence).to be < 0.8
+    end
+
+    it 'returns count of decayed entries' do
+      2.times { engine.create_attribution(**basic_args) }
+      expect(engine.decay_all).to eq(2)
+    end
+
+    it 'floors at CONFIDENCE_FLOOR' do
+      attr = engine.create_attribution(**basic_args, confidence: 0.001)
+      engine.decay_all
+      expect(attr.confidence).to be >= Legion::Extensions::CausalAttribution::Helpers::Attribution::CONFIDENCE_FLOOR
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes stats keys' do
+      engine.create_attribution(**basic_args)
+      h = engine.to_h
+      expect(h).to have_key(:total_attributions)
+      expect(h).to have_key(:outcome_counts)
+      expect(h).to have_key(:locus_counts)
+    end
+  end
+end

data/spec/legion/extensions/causal_attribution/helpers/attribution_spec.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CausalAttribution::Helpers::Attribution do
+  subject(:attr) do
+    described_class.new(
+      event:           'task failed',
+      outcome:         :failure,
+      domain:          :work,
+      locus:           :internal,
+      stability:       :stable,
+      controllability: :controllable
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns an id' do
+      expect(attr.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores all dimensions' do
+      expect(attr.locus).to eq(:internal)
+      expect(attr.stability).to eq(:stable)
+      expect(attr.controllability).to eq(:controllable)
+    end
+
+    it 'derives emotional_response from ATTRIBUTION_EMOTIONS' do
+      expect(attr.emotional_response).to eq(:guilt)
+    end
+
+    it 'uses DEFAULT_CONFIDENCE when none given' do
+      expect(attr.confidence).to eq(described_class::DEFAULT_CONFIDENCE)
+    end
+
+    it 'clamps confidence to ceiling' do
+      high = described_class.new(
+        event: 'x', outcome: :success, domain: :test,
+        locus: :external, stability: :unstable, controllability: :uncontrollable,
+        confidence: 5.0
+      )
+      expect(high.confidence).to eq(1.0)
+    end
+
+    it 'clamps confidence to floor' do
+      low = described_class.new(
+        event: 'x', outcome: :success, domain: :test,
+        locus: :external, stability: :unstable, controllability: :uncontrollable,
+        confidence: -1.0
+      )
+      expect(low.confidence).to eq(0.0)
+    end
+
+    it 'records created_at' do
+      expect(attr.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#pattern' do
+    it 'returns [locus, stability, controllability] tuple' do
+      expect(attr.pattern).to eq(%i[internal stable controllable])
+    end
+  end
+
+  describe 'predicates' do
+    it 'internal? returns true for internal locus' do
+      expect(attr.internal?).to be true
+      expect(attr.external?).to be false
+    end
+
+    it 'stable? returns true for stable stability' do
+      expect(attr.stable?).to be true
+    end
+
+    it 'controllable? returns true for controllable controllability' do
+      expect(attr.controllable?).to be true
+    end
+  end
+
+  describe 'ATTRIBUTION_EMOTIONS mapping' do
+    {
+      %i[internal stable controllable]     => :guilt,
+      %i[internal stable uncontrollable]   => :shame,
+      %i[internal unstable controllable]   => :regret,
+      %i[internal unstable uncontrollable] => :surprise,
+      %i[external stable controllable]     => :anger,
+      %i[external stable uncontrollable]   => :helplessness,
+      %i[external unstable controllable]   => :frustration,
+      %i[external unstable uncontrollable] => :relief
+    }.each do |pattern, emotion|
+      it "maps #{pattern.inspect} to #{emotion}" do
+        a = described_class.new(
+          event: 'e', outcome: :neutral, domain: :test,
+          locus: pattern[0], stability: pattern[1], controllability: pattern[2]
+        )
+        expect(a.emotional_response).to eq(emotion)
+      end
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all required keys' do
+      h = attr.to_h
+      %i[id event outcome domain locus stability controllability
+         confidence emotional_response created_at].each do |key|
+        expect(h).to have_key(key)
+      end
+    end
+  end
+end

data/spec/legion/extensions/causal_attribution/runners/causal_attribution_spec.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/causal_attribution/client'
+
+RSpec.describe Legion::Extensions::CausalAttribution::Runners::CausalAttribution do
+  let(:client) { Legion::Extensions::CausalAttribution::Client.new }
+
+  let(:base_args) do
+    {
+      event:           'missed deadline',
+      outcome:         :failure,
+      domain:          :work,
+      locus:           :internal,
+      stability:       :stable,
+      controllability: :controllable
+    }
+  end
+
+  describe '#create_causal_attribution' do
+    it 'returns success true' do
+      result = client.create_causal_attribution(**base_args)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes attribution hash' do
+      result = client.create_causal_attribution(**base_args)
+      expect(result[:attribution]).to have_key(:id)
+      expect(result[:attribution][:emotional_response]).to eq(:guilt)
+    end
+
+    it 'accepts string locus and coerces to symbol' do
+      result = client.create_causal_attribution(**base_args, locus: 'external')
+      expect(result[:attribution][:locus]).to eq(:external)
+    end
+  end
+
+  describe '#reattribute_cause' do
+    let!(:id) { client.create_causal_attribution(**base_args)[:attribution][:id] }
+
+    it 'updates the attribution' do
+      result = client.reattribute_cause(attribution_id: id, locus: :external)
+      expect(result[:success]).to be true
+      expect(result[:attribution][:locus]).to eq(:external)
+    end
+
+    it 'returns success false for unknown id' do
+      result = client.reattribute_cause(attribution_id: 'bad-id')
+      expect(result[:success]).to be false
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#attributions_by_pattern' do
+    before do
+      client.create_causal_attribution(**base_args)
+      client.create_causal_attribution(**base_args, locus: :external)
+    end
+
+    it 'filters by locus' do
+      result = client.attributions_by_pattern(locus: :internal)
+      expect(result[:count]).to eq(1)
+    end
+
+    it 'returns all when no filter given' do
+      result = client.attributions_by_pattern
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#domain_attributions' do
+    before { client.create_causal_attribution(**base_args) }
+
+    it 'returns attributions for domain' do
+      result = client.domain_attributions(domain: :work)
+      expect(result[:count]).to be >= 1
+    end
+  end
+
+  describe '#outcome_attributions' do
+    before do
+      client.create_causal_attribution(**base_args)
+      client.create_causal_attribution(**base_args, outcome: :success)
+    end
+
+    it 'returns attributions by outcome' do
+      result = client.outcome_attributions(outcome: :failure)
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#attribution_bias_assessment' do
+    before { client.create_causal_attribution(**base_args) }
+
+    it 'returns bias structure' do
+      result = client.attribution_bias_assessment
+      expect(result[:success]).to be true
+      expect(result[:bias]).to have_key(:self_serving_bias_detected)
+    end
+  end
+
+  describe '#emotional_attribution_profile' do
+    before { client.create_causal_attribution(**base_args) }
+
+    it 'returns profile with dominant emotion' do
+      result = client.emotional_attribution_profile
+      expect(result[:success]).to be true
+      expect(result[:profile]).to have_key(:dominant)
+    end
+  end
+
+  describe '#most_common_attribution' do
+    before do
+      2.times { client.create_causal_attribution(**base_args) }
+    end
+
+    it 'returns the most frequent pattern' do
+      result = client.most_common_attribution
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#update_causal_attribution' do
+    before { client.create_causal_attribution(**base_args, confidence: 0.8) }
+
+    it 'decays confidence and reports count' do
+      result = client.update_causal_attribution
+      expect(result[:success]).to be true
+      expect(result[:decayed]).to eq(1)
+    end
+  end
+
+  describe '#causal_attribution_stats' do
+    before { client.create_causal_attribution(**base_args) }
+
+    it 'returns stats hash' do
+      result = client.causal_attribution_stats
+      expect(result[:success]).to be true
+      expect(result[:stats][:total_attributions]).to eq(1)
+    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/causal_attribution'
+
+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,74 @@
+--- !ruby/object:Gem::Specification
+name: lex-causal-attribution
+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: Weiner's attribution theory for brain-modeled agentic AI — locus, stability,
+  controllability
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-causal-attribution.gemspec
+- lib/legion/extensions/causal_attribution.rb
+- lib/legion/extensions/causal_attribution/client.rb
+- lib/legion/extensions/causal_attribution/helpers/attribution.rb
+- lib/legion/extensions/causal_attribution/helpers/attribution_engine.rb
+- lib/legion/extensions/causal_attribution/runners/causal_attribution.rb
+- lib/legion/extensions/causal_attribution/version.rb
+- spec/legion/extensions/causal_attribution/client_spec.rb
+- spec/legion/extensions/causal_attribution/helpers/attribution_engine_spec.rb
+- spec/legion/extensions/causal_attribution/helpers/attribution_spec.rb
+- spec/legion/extensions/causal_attribution/runners/causal_attribution_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-causal-attribution
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-causal-attribution
+  source_code_uri: https://github.com/LegionIO/lex-causal-attribution
+  documentation_uri: https://github.com/LegionIO/lex-causal-attribution
+  changelog_uri: https://github.com/LegionIO/lex-causal-attribution
+  bug_tracker_uri: https://github.com/LegionIO/lex-causal-attribution/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 Causal Attribution
+test_files: []