lex-agentic-learning 0.1.0

data/lib/legion/extensions/agentic/learning/catalyst/helpers/catalyst_engine.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+          module Helpers
+            class CatalystEngine
+              include Constants
+
+              def initialize
+                @catalysts = {}
+                @reactions = {}
+              end
+
+              def create_catalyst(catalyst_type:, domain:, potency: 0.5, specificity: 0.5, **)
+                unless CATALYST_TYPES.include?(catalyst_type.to_sym)
+                  raise ArgumentError,
+                        "invalid catalyst_type: #{catalyst_type}"
+                end
+
+                evict_oldest_catalyst if @catalysts.size >= MAX_CATALYSTS
+                catalyst = Catalyst.new(
+                  catalyst_type: catalyst_type.to_sym,
+                  domain:        domain,
+                  potency:       potency,
+                  specificity:   specificity
+                )
+                @catalysts[catalyst.id] = catalyst
+                catalyst
+              end
+
+              def create_reaction(reaction_type:, reactants:, activation_energy: ACTIVATION_ENERGY, **)
+                unless REACTION_TYPES.include?(reaction_type.to_sym)
+                  raise ArgumentError,
+                        "invalid reaction_type: #{reaction_type}"
+                end
+
+                evict_oldest_reaction if @reactions.size >= MAX_REACTIONS
+                reaction = Reaction.new(
+                  reaction_type:     reaction_type.to_sym,
+                  reactants:         reactants,
+                  activation_energy: activation_energy
+                )
+                @reactions[reaction.id] = reaction
+                reaction
+              end
+
+              def apply_catalyst(catalyst_id:, reaction_id:)
+                catalyst = @catalysts[catalyst_id]
+                reaction = @reactions[reaction_id]
+
+                return { success: false, reason: :catalyst_not_found } unless catalyst
+                return { success: false, reason: :reaction_not_found } unless reaction
+                return { success: false, reason: :already_completed }  if reaction.complete?
+
+                reaction.apply_catalyst!(catalyst)
+                {
+                  success:           true,
+                  activation_energy: reaction.activation_energy,
+                  catalyst_id:       catalyst_id,
+                  reaction_id:       reaction_id
+                }
+              end
+
+              def attempt_reaction(reaction_id:, energy_input:)
+                reaction = @reactions[reaction_id]
+                return { success: false, reason: :not_found } unless reaction
+                return { success: false, reason: :already_completed } if reaction.complete?
+
+                completed = reaction.attempt!(energy_input)
+                {
+                  success:           true,
+                  completed:         completed,
+                  yield_value:       reaction.yield_value,
+                  yield_label:       reaction.yield_label,
+                  catalyzed:         reaction.catalyzed?,
+                  activation_energy: reaction.activation_energy
+                }
+              end
+
+              def degrade_all!
+                @catalysts.each_value(&:degrade!)
+              end
+
+              def recharge_catalyst(catalyst_id:, amount:)
+                catalyst = @catalysts[catalyst_id]
+                return { success: false, reason: :not_found } unless catalyst
+
+                catalyst.recharge!(amount)
+                { success: true, potency: catalyst.potency, potency_label: catalyst.potency_label }
+              end
+
+              def all_catalysts
+                @catalysts.values
+              end
+
+              def all_reactions
+                @reactions.values
+              end
+
+              def completed_reactions
+                @reactions.values.select(&:complete?)
+              end
+
+              def catalyzed_rate
+                completed = completed_reactions
+                return 0.0 if completed.empty?
+
+                catalyzed_count = completed.count(&:catalyzed?)
+                (catalyzed_count.to_f / completed.size).round(10)
+              end
+
+              def catalyst_report
+                completed     = completed_reactions
+                catalyzed_cnt = completed.count(&:catalyzed?)
+                avg_potency   = if @catalysts.empty?
+                                  0.0
+                                else
+                                  (@catalysts.values.sum(&:potency) / @catalysts.size).round(10)
+                                end
+
+                {
+                  total_catalysts: @catalysts.size,
+                  total_reactions: @reactions.size,
+                  completed:       completed.size,
+                  catalyzed_count: catalyzed_cnt,
+                  catalyzed_rate:  catalyzed_rate,
+                  avg_potency:     avg_potency,
+                  powerful_count:  @catalysts.values.count(&:powerful?),
+                  inert_count:     @catalysts.values.count(&:inert?)
+                }
+              end
+
+              private
+
+              def evict_oldest_catalyst
+                oldest_id = @catalysts.min_by { |_id, c| c.created_at }&.first
+                @catalysts.delete(oldest_id) if oldest_id
+              end
+
+              def evict_oldest_reaction
+                oldest_id = @reactions.min_by { |_id, r| r.created_at }&.first
+                @reactions.delete(oldest_id) if oldest_id
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/catalyst/helpers/constants.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+          module Helpers
+            module Constants
+              # Catalyst types — categories of experiences/insights that accelerate reactions
+              CATALYST_TYPES = %i[experience insight analogy pattern emotion].freeze
+
+              # Reaction types — categories of cognitive transformations
+              REACTION_TYPES = %i[synthesis decomposition exchange neutralization precipitation].freeze
+
+              # Storage limits
+              MAX_CATALYSTS = 500
+              MAX_REACTIONS = 200
+
+              # Activation energy — minimum energy to complete a reaction without a catalyst
+              ACTIVATION_ENERGY = 0.6
+
+              # How much a catalyst lowers the activation energy threshold
+              CATALYST_REDUCTION = 0.3
+
+              # Potency degradation rate from environmental wear (not from use)
+              POTENCY_DECAY = 0.02
+
+              # Bonus added when catalyst specificity matches reaction domain
+              SPECIFICITY_BONUS = 0.15
+
+              # Potency labels — range-based classification of catalyst strength
+              POTENCY_LABELS = {
+                (0.8..)     => :powerful,
+                (0.6...0.8) => :strong,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :weak,
+                (..0.2)     => :inert
+              }.freeze
+
+              # Yield labels — range-based classification of reaction output quality
+              YIELD_LABELS = {
+                (0.8..)     => :excellent,
+                (0.6...0.8) => :good,
+                (0.4...0.6) => :fair,
+                (0.2...0.4) => :poor,
+                (..0.2)     => :negligible
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/catalyst/helpers/reaction.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+          module Helpers
+            class Reaction
+              include Constants
+
+              attr_reader :id, :reaction_type, :reactants, :activation_energy,
+                          :yield_value, :catalyzed, :catalyst_id, :completed, :created_at
+
+              def initialize(reaction_type:, reactants:, activation_energy: ACTIVATION_ENERGY)
+                @id               = SecureRandom.uuid
+                @reaction_type    = reaction_type
+                @reactants        = Array(reactants)
+                @activation_energy = activation_energy.clamp(0.0, 1.0)
+                @yield_value      = 0.0
+                @catalyzed        = false
+                @catalyst_id      = nil
+                @completed        = false
+                @created_at       = Time.now.utc
+              end
+
+              # Apply a catalyst to lower the activation energy threshold
+              def apply_catalyst!(catalyst)
+                reduction = catalyst.catalyze!(@reaction_type)
+                @activation_energy = (@activation_energy - reduction).clamp(0.0, 1.0).round(10)
+                @catalyzed         = true
+                @catalyst_id       = catalyst.id
+              end
+
+              # Attempt to complete the reaction with given energy input
+              # Completes if energy_input >= activation_energy; yield based on energy surplus
+              def attempt!(energy_input)
+                return false if @completed
+                return false if energy_input < @activation_energy
+
+                @completed = true
+                surplus = (energy_input - @activation_energy).clamp(0.0, 1.0)
+                @yield_value = (0.5 + (surplus * 0.5)).clamp(0.0, 1.0).round(10)
+                true
+              end
+
+              def complete?
+                @completed
+              end
+
+              def catalyzed?
+                @catalyzed
+              end
+
+              # Completed spontaneously — without a catalyst
+              def spontaneous?
+                @completed && !@catalyzed
+              end
+
+              def yield_label
+                YIELD_LABELS.find { |range, _| range.cover?(@yield_value) }&.last || :negligible
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  reaction_type:     @reaction_type,
+                  reactants:         @reactants,
+                  activation_energy: @activation_energy,
+                  yield_value:       @yield_value,
+                  yield_label:       yield_label,
+                  catalyzed:         @catalyzed,
+                  catalyst_id:       @catalyst_id,
+                  completed:         @completed,
+                  spontaneous:       spontaneous?,
+                  created_at:        @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/catalyst/runners/cognitive_catalyst.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+          module Runners
+            module CognitiveCatalyst
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_catalyst(catalyst_type:, domain:, potency: nil, specificity: nil, engine: nil, **)
+                e = engine || default_engine
+                raise ArgumentError, "invalid catalyst_type: #{catalyst_type}" unless Helpers::Constants::CATALYST_TYPES.include?(catalyst_type.to_sym)
+
+                opts = {
+                  catalyst_type: catalyst_type.to_sym,
+                  domain:        domain
+                }
+                opts[:potency]     = potency     unless potency.nil?
+                opts[:specificity] = specificity unless specificity.nil?
+
+                catalyst = e.create_catalyst(**opts)
+                Legion::Logging.debug "[cognitive_catalyst] create_catalyst id=#{catalyst.id[0..7]} " \
+                                      "type=#{catalyst_type} domain=#{domain} potency=#{catalyst.potency.round(2)}"
+                { success: true, catalyst: catalyst.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_catalyst] create_catalyst failed: #{e.message}"
+                { success: false, reason: e.message }
+              end
+
+              def create_reaction(reaction_type:, reactants:, activation_energy: nil, engine: nil, **)
+                e = engine || default_engine
+                raise ArgumentError, "invalid reaction_type: #{reaction_type}" unless Helpers::Constants::REACTION_TYPES.include?(reaction_type.to_sym)
+
+                opts = {
+                  reaction_type: reaction_type.to_sym,
+                  reactants:     Array(reactants)
+                }
+                opts[:activation_energy] = activation_energy unless activation_energy.nil?
+
+                reaction = e.create_reaction(**opts)
+                Legion::Logging.debug "[cognitive_catalyst] create_reaction id=#{reaction.id[0..7]} " \
+                                      "type=#{reaction_type} reactants=#{reaction.reactants.size}"
+                { success: true, reaction: reaction.to_h }
+              rescue ArgumentError => e
+                Legion::Logging.warn "[cognitive_catalyst] create_reaction failed: #{e.message}"
+                { success: false, reason: e.message }
+              end
+
+              def apply_catalyst(catalyst_id:, reaction_id:, engine: nil, **)
+                e = engine || default_engine
+                result = e.apply_catalyst(catalyst_id: catalyst_id, reaction_id: reaction_id)
+                Legion::Logging.debug '[cognitive_catalyst] apply_catalyst ' \
+                                      "catalyst=#{catalyst_id[0..7]} reaction=#{reaction_id[0..7]} " \
+                                      "success=#{result[:success]}"
+                result
+              end
+
+              def attempt_reaction(reaction_id:, energy_input:, engine: nil, **)
+                e = engine || default_engine
+                result = e.attempt_reaction(reaction_id: reaction_id, energy_input: energy_input)
+                Legion::Logging.debug "[cognitive_catalyst] attempt_reaction id=#{reaction_id[0..7]} " \
+                                      "energy=#{energy_input} completed=#{result[:completed]}"
+                result
+              end
+
+              def recharge(catalyst_id:, amount:, engine: nil, **)
+                e = engine || default_engine
+                result = e.recharge_catalyst(catalyst_id: catalyst_id, amount: amount)
+                Legion::Logging.debug "[cognitive_catalyst] recharge id=#{catalyst_id[0..7]} " \
+                                      "amount=#{amount} potency=#{result[:potency]&.round(2)}"
+                result
+              end
+
+              def list_catalysts(engine: nil, **)
+                e = engine || default_engine
+                catalysts = e.all_catalysts
+                Legion::Logging.debug "[cognitive_catalyst] list_catalysts count=#{catalysts.size}"
+                { success: true, catalysts: catalysts.map(&:to_h), count: catalysts.size }
+              end
+
+              def catalyst_status(engine: nil, **)
+                e = engine || default_engine
+                report = e.catalyst_report
+                Legion::Logging.debug "[cognitive_catalyst] catalyst_status total=#{report[:total_catalysts]} " \
+                                      "reactions=#{report[:total_reactions]} rate=#{report[:catalyzed_rate].round(2)}"
+                { success: true }.merge(report)
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::CatalystEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/catalyst/version.rb

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

data/lib/legion/extensions/agentic/learning/catalyst.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'catalyst/version'
+require_relative 'catalyst/helpers/constants'
+require_relative 'catalyst/helpers/catalyst'
+require_relative 'catalyst/helpers/reaction'
+require_relative 'catalyst/helpers/catalyst_engine'
+require_relative 'catalyst/runners/cognitive_catalyst'
+require_relative 'catalyst/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Catalyst
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/chrysalis/client.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+          class Client
+            include Runners::CognitiveChrysalis
+
+            attr_reader :engine
+
+            def initialize(**)
+              @engine         = Helpers::MetamorphosisEngine.new
+              @default_engine = @engine
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/chrysalis/helpers/chrysalis.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+          module Helpers
+            class Chrysalis
+              attr_reader :id, :chrysalis_type, :content, :stage,
+                          :transformation_progress, :protection, :beauty, :created_at
+
+              def initialize(chrysalis_type:, content:, **)
+                @id                     = SecureRandom.uuid
+                @chrysalis_type         = chrysalis_type.to_sym
+                @content                = content.to_s
+                @stage                  = :larva
+                @transformation_progress = 0.0
+                @protection             = 0.8
+                @beauty                 = 0.0
+                @created_at             = Time.now.utc
+                @premature              = false
+              end
+
+              def spin!
+                raise ArgumentError, "must be :larva to spin, currently #{@stage}" unless @stage == :larva
+
+                @stage = :spinning
+                true
+              end
+
+              def cocoon!
+                raise ArgumentError, "must be :spinning to cocoon, currently #{@stage}" unless @stage == :spinning
+
+                @stage = :cocooned
+                true
+              end
+
+              def transform!(rate = Helpers::Constants::TRANSFORMATION_RATE)
+                return false if @stage == :butterfly
+
+                @transformation_progress = (@transformation_progress + rate).clamp(0.0, 1.0).round(10)
+                @beauty = (@transformation_progress * 0.9).clamp(0.0, 1.0).round(10)
+                update_stage_from_progress!
+                true
+              end
+
+              def emerge!(force: false)
+                if @transformation_progress >= Helpers::Constants::EMERGENCE_THRESHOLD
+                  @stage  = :butterfly
+                  @beauty = 1.0
+                elsif force
+                  @premature = true
+                  @stage     = :butterfly
+                  @beauty    = (@beauty - Helpers::Constants::PREMATURE_PENALTY).clamp(0.0, 1.0).round(10)
+                else
+                  return false
+                end
+                true
+              end
+
+              def decay_protection!
+                @protection = (@protection - Helpers::Constants::PROTECTION_DECAY).clamp(0.0, 1.0).round(10)
+              end
+
+              def disturb!(force)
+                @protection = (@protection - force.to_f).clamp(0.0, 1.0).round(10)
+                emerge!(force: true) if @protection <= 0 && %i[cocooned transforming].include?(@stage)
+              end
+
+              def butterfly?
+                @stage == :butterfly
+              end
+
+              def cocooned?
+                @stage == :cocooned
+              end
+
+              def transforming?
+                @stage == :transforming
+              end
+
+              def premature?
+                butterfly? && @beauty < 0.5
+              end
+
+              def stage_label
+                Helpers::Constants.label_for(Helpers::Constants::STAGE_LABELS, @transformation_progress)
+              end
+
+              def beauty_label
+                Helpers::Constants.label_for(Helpers::Constants::BEAUTY_LABELS, @beauty)
+              end
+
+              def to_h
+                {
+                  id:                      @id,
+                  chrysalis_type:          @chrysalis_type,
+                  content:                 @content,
+                  stage:                   @stage,
+                  transformation_progress: @transformation_progress,
+                  protection:              @protection,
+                  beauty:                  @beauty,
+                  stage_label:             stage_label,
+                  beauty_label:            beauty_label,
+                  premature:               @premature,
+                  created_at:              @created_at
+                }
+              end
+
+              private
+
+              def update_stage_from_progress!
+                progress_stage = if @transformation_progress >= 0.8
+                                   :emerging
+                                 elsif @transformation_progress >= 0.6
+                                   :transforming
+                                 elsif @transformation_progress >= 0.4
+                                   :cocooned
+                                 elsif @transformation_progress >= 0.2
+                                   :spinning
+                                 else
+                                   :larva
+                                 end
+                current_rank  = Helpers::Constants::LIFE_STAGES.index(@stage) || 0
+                progress_rank = Helpers::Constants::LIFE_STAGES.index(progress_stage) || 0
+                @stage = Helpers::Constants::LIFE_STAGES[[current_rank, progress_rank].max]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/chrysalis/helpers/cocoon.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+          module Helpers
+            class Cocoon
+              attr_reader :id, :environment, :temperature, :humidity, :chrysalis_ids, :created_at
+
+              TEMP_ADJUST = 0.05
+              HUMID_ADJUST = 0.05
+
+              def initialize(environment:, temperature: 0.5, humidity: 0.5, **)
+                @id            = SecureRandom.uuid
+                @environment   = environment.to_s
+                @temperature   = temperature.to_f.clamp(0.0, 1.0)
+                @humidity      = humidity.to_f.clamp(0.0, 1.0)
+                @chrysalis_ids = []
+                @created_at    = Time.now.utc
+              end
+
+              def shelter(chrysalis_id)
+                @chrysalis_ids << chrysalis_id unless @chrysalis_ids.include?(chrysalis_id)
+                true
+              end
+
+              def expose(chrysalis_id)
+                @chrysalis_ids.delete(chrysalis_id)
+                true
+              end
+
+              def warm!
+                @temperature = (@temperature + TEMP_ADJUST).clamp(0.0, 1.0).round(10)
+              end
+
+              def cool!
+                @temperature = (@temperature - TEMP_ADJUST).clamp(0.0, 1.0).round(10)
+              end
+
+              def moisten!
+                @humidity = (@humidity + HUMID_ADJUST).clamp(0.0, 1.0).round(10)
+              end
+
+              def dry!
+                @humidity = (@humidity - HUMID_ADJUST).clamp(0.0, 1.0).round(10)
+              end
+
+              def ideal?
+                @temperature.between?(0.4, 0.7) && @humidity.between?(0.4, 0.7)
+              end
+
+              def hostile?
+                @temperature > 0.9 || @humidity < 0.1
+              end
+
+              def growth_modifier
+                if ideal?
+                  0.1
+                elsif hostile?
+                  -0.05
+                else
+                  0.0
+                end
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  environment:     @environment,
+                  temperature:     @temperature,
+                  humidity:        @humidity,
+                  chrysalis_ids:   @chrysalis_ids.dup,
+                  ideal:           ideal?,
+                  hostile:         hostile?,
+                  growth_modifier: growth_modifier,
+                  created_at:      @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end