lex-agentic-self 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d78221dc914c624a359465f1b3eda8dd9e0cb6e89be19f1455e979b087ad4ae
+  data.tar.gz: 076c649303e81e8ab5396ef6bef33c1fe9bda3606df9c3ba533b249ab0d9b903
+SHA512:
+  metadata.gz: fa086ec76865a2b2f24057b110b88d1fc38f350ca540d6e2e2592ee64c1ced65eccd0735bdd4667a1f9b151adea39f3cfe56385cba4fb9bd0e712085951a067b
+  data.tar.gz: 40c44ecdd2afaa40586e85e8201d4ddf7fac5500b152316e070536f88484fb2dbfd1c4f982ead5fcda8b13ad98bb1c2ca162cc9f1debe15e369698bd8830a3e2

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

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,13 @@
+# lex-agentic-self
+
+LEX agentic self domain: identity, metacognition, self-model
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-self'
+```

data/lex-agentic-self.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/self/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-self'
+  spec.version       = Legion::Extensions::Agentic::Self::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Self'
+  spec.description   = 'LEX agentic self domain: identity, metacognition, self-model'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-self'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-self.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'faraday', '~> 2.0'
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

data/lib/legion/extensions/agentic/self/agency/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+          class Client
+            include Runners::Agency
+
+            attr_reader :efficacy_model
+
+            def initialize(efficacy_model: nil, **)
+              @efficacy_model = efficacy_model || Helpers::EfficacyModel.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/agency/helpers/constants.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+          module Helpers
+            module Constants
+              # Initial self-efficacy for new domains (moderate confidence)
+              DEFAULT_EFFICACY = 0.5
+
+              # EMA alpha for efficacy updates (slow adaptation)
+              EFFICACY_ALPHA = 0.12
+
+              # How much mastery success boosts efficacy
+              MASTERY_BOOST = 0.15
+
+              # How much failure reduces efficacy (asymmetric — failures hit harder)
+              FAILURE_PENALTY = 0.20
+
+              # Vicarious learning multiplier (learning from others' outcomes)
+              VICARIOUS_MULTIPLIER = 0.4
+
+              # Verbal persuasion multiplier (being told you can/can't do something)
+              PERSUASION_MULTIPLIER = 0.25
+
+              # Physiological state influence on efficacy
+              PHYSIOLOGICAL_MULTIPLIER = 0.15
+
+              # Minimum efficacy (never zero — always some belief in possibility)
+              EFFICACY_FLOOR = 0.05
+
+              # Maximum efficacy (never perfectly certain)
+              EFFICACY_CEILING = 0.98
+
+              # Domain decay rate per tick (unused domains slowly regress toward default)
+              DECAY_RATE = 0.002
+
+              # Maximum tracked domains
+              MAX_DOMAINS = 100
+
+              # Maximum outcome history per domain
+              MAX_HISTORY_PER_DOMAIN = 50
+
+              # Maximum total outcome events
+              MAX_TOTAL_HISTORY = 500
+
+              # Sources of efficacy information (Bandura's four sources)
+              EFFICACY_SOURCES = %i[mastery vicarious persuasion physiological].freeze
+
+              # Agency attribution levels
+              ATTRIBUTION_LEVELS = {
+                full_agency:    0.8,
+                partial_agency: 0.5,
+                low_agency:     0.3,
+                no_agency:      0.0
+              }.freeze
+
+              # Outcome types
+              OUTCOME_TYPES = %i[success failure partial_success unexpected].freeze
+
+              # Efficacy level labels
+              EFFICACY_LABELS = {
+                (0.8..)     => :highly_capable,
+                (0.6...0.8) => :capable,
+                (0.4...0.6) => :uncertain,
+                (0.2...0.4) => :doubtful,
+                (..0.2)     => :helpless
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/agency/helpers/efficacy_model.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+          module Helpers
+            class EfficacyModel
+              attr_reader :domains, :history
+
+              def initialize
+                @domains = {}
+                @history = []
+              end
+
+              def efficacy_for(domain)
+                @domains[domain] ||= Constants::DEFAULT_EFFICACY
+                @domains[domain]
+              end
+
+              def efficacy_label(domain)
+                value = efficacy_for(domain)
+                Constants::EFFICACY_LABELS.each do |range, label|
+                  return label if range.cover?(value)
+                end
+                :uncertain
+              end
+
+              def record_outcome(event)
+                @history << event
+                update_efficacy(event)
+                trim_history
+                event
+              end
+
+              def decay_all
+                @domains.each_key do |domain|
+                  current = @domains[domain]
+                  diff = Constants::DEFAULT_EFFICACY - current
+                  @domains[domain] = (current + (diff * Constants::DECAY_RATE)).clamp(
+                    Constants::EFFICACY_FLOOR, Constants::EFFICACY_CEILING
+                  )
+                end
+                trim_domains
+              end
+
+              def domain_history(domain)
+                @history.select { |e| e.domain == domain }
+              end
+
+              def success_rate(domain)
+                events = domain_history(domain)
+                return 0.0 if events.empty?
+
+                successes = events.count(&:success?)
+                successes.to_f / events.size
+              end
+
+              def strongest_domains(count = 5)
+                @domains.sort_by { |_, v| -v }.first(count).to_h
+              end
+
+              def weakest_domains(count = 5)
+                @domains.sort_by { |_, v| v }.first(count).to_h
+              end
+
+              def overall_efficacy
+                return Constants::DEFAULT_EFFICACY if @domains.empty?
+
+                @domains.values.sum / @domains.size
+              end
+
+              def domain_count
+                @domains.size
+              end
+
+              def to_h
+                {
+                  domain_count:     @domains.size,
+                  overall_efficacy: overall_efficacy.round(4),
+                  history_size:     @history.size,
+                  domains:          @domains.transform_values { |v| v.round(4) }
+                }
+              end
+
+              private
+
+              def update_efficacy(event)
+                domain = event.domain
+                current = efficacy_for(domain)
+                delta = compute_delta(event)
+
+                new_value = current + (Constants::EFFICACY_ALPHA * delta)
+                @domains[domain] = new_value.clamp(Constants::EFFICACY_FLOOR, Constants::EFFICACY_CEILING)
+              end
+
+              def compute_delta(event)
+                base = event.attributed_magnitude
+                multiplier = source_multiplier(event.source)
+
+                if event.success?
+                  base * multiplier * Constants::MASTERY_BOOST / Constants::EFFICACY_ALPHA
+                else
+                  -base * multiplier * Constants::FAILURE_PENALTY / Constants::EFFICACY_ALPHA
+                end
+              end
+
+              def source_multiplier(source)
+                case source
+                when :mastery       then 1.0
+                when :vicarious     then Constants::VICARIOUS_MULTIPLIER
+                when :persuasion    then Constants::PERSUASION_MULTIPLIER
+                when :physiological then Constants::PHYSIOLOGICAL_MULTIPLIER
+                else 0.5
+                end
+              end
+
+              def trim_history
+                @history.shift(@history.size - Constants::MAX_TOTAL_HISTORY) if @history.size > Constants::MAX_TOTAL_HISTORY
+              end
+
+              def trim_domains
+                return unless @domains.size > Constants::MAX_DOMAINS
+
+                sorted = @domains.sort_by { |_, v| (v - Constants::DEFAULT_EFFICACY).abs }
+                excess = @domains.size - Constants::MAX_DOMAINS
+                sorted.first(excess).each { |domain, _| @domains.delete(domain) } # rubocop:disable Style/HashEachMethods
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/agency/helpers/outcome_event.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+          module Helpers
+            class OutcomeEvent
+              attr_reader :id, :domain, :outcome_type, :source, :magnitude, :attribution, :timestamp
+
+              def initialize(domain:, outcome_type:, source: :mastery, magnitude: 1.0, attribution: :full_agency)
+                @id          = SecureRandom.uuid
+                @domain      = domain
+                @outcome_type = outcome_type
+                @source      = source
+                @magnitude   = magnitude.clamp(0.0, 1.0)
+                @attribution = attribution
+                @timestamp   = Time.now.utc
+              end
+
+              def success?
+                %i[success partial_success].include?(@outcome_type)
+              end
+
+              def attributed_magnitude
+                level = Constants::ATTRIBUTION_LEVELS[@attribution] || 0.5
+                @magnitude * level
+              end
+
+              def to_h
+                {
+                  id:                   @id,
+                  domain:               @domain,
+                  outcome_type:         @outcome_type,
+                  source:               @source,
+                  magnitude:            @magnitude,
+                  attribution:          @attribution,
+                  success:              success?,
+                  attributed_magnitude: attributed_magnitude.round(4),
+                  timestamp:            @timestamp
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/agency/runners/agency.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+          module Runners
+            module Agency
+              include Legion::Extensions::Helpers::Lex
+
+              def efficacy_model
+                @efficacy_model ||= Helpers::EfficacyModel.new
+              end
+
+              def record_mastery(domain:, outcome_type:, magnitude: 1.0, attribution: :full_agency, **)
+                event = Helpers::OutcomeEvent.new(
+                  domain: domain, outcome_type: outcome_type, source: :mastery,
+                  magnitude: magnitude, attribution: attribution
+                )
+                efficacy_model.record_outcome(event)
+                Legion::Logging.debug "[agency] mastery #{outcome_type} in #{domain} " \
+                                      "efficacy=#{efficacy_model.efficacy_for(domain).round(4)}"
+                { success: true, event: event.to_h, efficacy: efficacy_model.efficacy_for(domain).round(4) }
+              end
+
+              def record_vicarious(domain:, outcome_type:, magnitude: 1.0, **)
+                event = Helpers::OutcomeEvent.new(
+                  domain: domain, outcome_type: outcome_type, source: :vicarious,
+                  magnitude: magnitude, attribution: :partial_agency
+                )
+                efficacy_model.record_outcome(event)
+                Legion::Logging.debug "[agency] vicarious #{outcome_type} in #{domain}"
+                { success: true, event: event.to_h, efficacy: efficacy_model.efficacy_for(domain).round(4) }
+              end
+
+              def record_persuasion(domain:, positive: true, magnitude: 0.5, **)
+                outcome = positive ? :success : :failure
+                event = Helpers::OutcomeEvent.new(
+                  domain: domain, outcome_type: outcome, source: :persuasion,
+                  magnitude: magnitude, attribution: :partial_agency
+                )
+                efficacy_model.record_outcome(event)
+                Legion::Logging.debug "[agency] persuasion #{positive ? 'positive' : 'negative'} in #{domain}"
+                { success: true, event: event.to_h, efficacy: efficacy_model.efficacy_for(domain).round(4) }
+              end
+
+              def record_physiological(domain:, state: :energized, **)
+                outcome = %i[energized calm focused].include?(state) ? :success : :failure
+                magnitude = %i[energized calm focused].include?(state) ? 0.6 : 0.4
+                event = Helpers::OutcomeEvent.new(
+                  domain: domain, outcome_type: outcome, source: :physiological,
+                  magnitude: magnitude, attribution: :low_agency
+                )
+                efficacy_model.record_outcome(event)
+                Legion::Logging.debug "[agency] physiological #{state} in #{domain}"
+                { success: true, event: event.to_h, efficacy: efficacy_model.efficacy_for(domain).round(4) }
+              end
+
+              def update_agency(**)
+                efficacy_model.decay_all
+                Legion::Logging.debug "[agency] tick: domains=#{efficacy_model.domain_count} " \
+                                      "overall=#{efficacy_model.overall_efficacy.round(4)}"
+                { success: true, stats: efficacy_model.to_h }
+              end
+
+              def check_efficacy(domain:, **)
+                {
+                  success:       true,
+                  domain:        domain,
+                  efficacy:      efficacy_model.efficacy_for(domain).round(4),
+                  label:         efficacy_model.efficacy_label(domain),
+                  success_rate:  efficacy_model.success_rate(domain).round(4),
+                  history_count: efficacy_model.domain_history(domain).size
+                }
+              end
+
+              def should_attempt?(domain:, threshold: 0.3, **)
+                efficacy = efficacy_model.efficacy_for(domain)
+                {
+                  success:        true,
+                  domain:         domain,
+                  efficacy:       efficacy.round(4),
+                  threshold:      threshold,
+                  should_attempt: efficacy >= threshold,
+                  label:          efficacy_model.efficacy_label(domain)
+                }
+              end
+
+              def strongest_domains(count: 5, **)
+                domains = efficacy_model.strongest_domains(count)
+                {
+                  success: true,
+                  domains: domains.transform_values { |v| v.round(4) },
+                  count:   domains.size
+                }
+              end
+
+              def weakest_domains(count: 5, **)
+                domains = efficacy_model.weakest_domains(count)
+                {
+                  success: true,
+                  domains: domains.transform_values { |v| v.round(4) },
+                  count:   domains.size
+                }
+              end
+
+              def agency_stats(**)
+                { success: true, stats: efficacy_model.to_h }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/agency/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/agency.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'agency/version'
+require_relative 'agency/helpers/constants'
+require_relative 'agency/helpers/outcome_event'
+require_relative 'agency/helpers/efficacy_model'
+require_relative 'agency/runners/agency'
+require_relative 'agency/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Agency
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/anchor/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Anchor
+          class Client
+            include Runners::CognitiveAnchor
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/anchor/helpers/anchor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Anchor
+          module Helpers
+            class Anchor
+              attr_reader :id, :anchor_type, :domain, :content,
+                          :reference_value, :created_at
+              attr_accessor :grip, :weight
+
+              def initialize(anchor_type:, domain:, content:,
+                             reference_value: nil, grip: nil, weight: nil)
+                validate_anchor_type!(anchor_type)
+                @id              = SecureRandom.uuid
+                @anchor_type     = anchor_type.to_sym
+                @domain          = domain.to_sym
+                @content         = content.to_s
+                @reference_value = (reference_value || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @grip            = (grip || 0.7).to_f.clamp(0.0, 1.0).round(10)
+                @weight          = (weight || 0.5).to_f.clamp(0.0, 1.0).round(10)
+                @created_at      = Time.now.utc
+              end
+
+              def drag!(rate: Constants::DRAG_RATE)
+                @grip = (@grip + rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def drift!(rate: Constants::DRIFT_RATE)
+                @grip = (@grip - rate.abs).clamp(0.0, 1.0).round(10)
+              end
+
+              def bias_pull(new_value)
+                pull_strength = @grip * @weight
+                adjusted = new_value + ((reference_value - new_value) * pull_strength)
+                adjusted.clamp(0.0, 1.0).round(10)
+              end
+
+              def ironclad?
+                @grip >= 0.8
+              end
+
+              def drifting?
+                @grip < 0.2
+              end
+
+              def heavy?
+                @weight >= 0.7
+              end
+
+              def light?
+                @weight < 0.3
+              end
+
+              def grip_label
+                Constants.label_for(Constants::GRIP_LABELS, @grip)
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  anchor_type:     @anchor_type,
+                  domain:          @domain,
+                  content:         @content,
+                  reference_value: @reference_value,
+                  grip:            @grip,
+                  weight:          @weight,
+                  grip_label:      grip_label,
+                  ironclad:        ironclad?,
+                  drifting:        drifting?,
+                  created_at:      @created_at
+                }
+              end
+
+              private
+
+              def validate_anchor_type!(val)
+                return if Constants::ANCHOR_TYPES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown anchor type: #{val.inspect}; " \
+                      "must be one of #{Constants::ANCHOR_TYPES.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end