lex-agentic-learning 0.1.0

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+          module Helpers
+            module Constants
+              LIFE_STAGES = %i[larva spinning cocooned transforming emerging butterfly].freeze
+              CHRYSALIS_TYPES = %i[silk paper bark leaf underground].freeze
+
+              MAX_CHRYSALISES    = 200
+              MAX_BUTTERFLIES    = 500
+              TRANSFORMATION_RATE = 0.08
+              PROTECTION_DECAY = 0.03
+              EMERGENCE_THRESHOLD = 0.9
+              PREMATURE_PENALTY = 0.4
+
+              STAGE_LABELS = {
+                (0.0...0.20)  => :larva,
+                (0.20...0.40) => :spinning,
+                (0.40...0.60) => :cocooned,
+                (0.60...0.80) => :transforming,
+                (0.80...0.90) => :emerging,
+                (0.90..1.0)   => :butterfly
+              }.freeze
+
+              BEAUTY_LABELS = {
+                (0.0...0.20)  => :dull,
+                (0.20...0.40) => :plain,
+                (0.40...0.65) => :striking,
+                (0.65...0.85) => :beautiful,
+                (0.85..1.0)   => :magnificent
+              }.freeze
+
+              def self.label_for(table, value)
+                table.each do |range, label|
+                  return label if range.cover?(value)
+                end
+                table.values.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+          module Helpers
+            class MetamorphosisEngine
+              def initialize
+                @chrysalises = {}
+                @cocoons     = {}
+                @sheltered   = {} # chrysalis_id => cocoon_id
+              end
+
+              def create_chrysalis(chrysalis_type:, content:, **)
+                return { success: false, reason: :capacity_exceeded } if @chrysalises.size >= Helpers::Constants::MAX_CHRYSALISES
+
+                c = Chrysalis.new(chrysalis_type: chrysalis_type, content: content)
+                @chrysalises[c.id] = c
+                { success: true, chrysalis: c.to_h }
+              end
+
+              def create_cocoon(environment:, **)
+                cocoon = Cocoon.new(environment: environment)
+                @cocoons[cocoon.id] = cocoon
+                { success: true, cocoon: cocoon.to_h }
+              end
+
+              def spin(chrysalis_id:, **)
+                c = @chrysalises.fetch(chrysalis_id, nil)
+                return { success: false, reason: :not_found } unless c
+
+                c.spin!
+                { success: true, stage: c.stage }
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def enclose(chrysalis_id:, cocoon_id:, **)
+                c      = @chrysalises.fetch(chrysalis_id, nil)
+                cocoon = @cocoons.fetch(cocoon_id, nil)
+                return { success: false, reason: :chrysalis_not_found } unless c
+                return { success: false, reason: :cocoon_not_found }    unless cocoon
+
+                c.spin! if c.stage == :larva
+                c.cocoon! if c.stage == :spinning
+                cocoon.shelter(chrysalis_id)
+                @sheltered[chrysalis_id] = cocoon_id
+                { success: true, stage: c.stage, cocoon_id: cocoon_id }
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def incubate(chrysalis_id:, **)
+                c = @chrysalises.fetch(chrysalis_id, nil)
+                return { success: false, reason: :not_found } unless c
+                return { success: false, reason: :already_butterfly } if c.butterfly?
+
+                rate = Helpers::Constants::TRANSFORMATION_RATE
+                if (cid = @sheltered[chrysalis_id])
+                  cocoon = @cocoons[cid]
+                  rate  += cocoon.growth_modifier if cocoon
+                end
+
+                c.transform!(rate)
+                { success: true, progress: c.transformation_progress, stage: c.stage }
+              end
+
+              def force_emerge(chrysalis_id:, **)
+                c = @chrysalises.fetch(chrysalis_id, nil)
+                return { success: false, reason: :not_found } unless c
+
+                c.emerge!(force: true)
+                { success: true, stage: c.stage, beauty: c.beauty, premature: c.premature? }
+              end
+
+              def natural_emerge(chrysalis_id:, **)
+                c = @chrysalises.fetch(chrysalis_id, nil)
+                return { success: false, reason: :not_found } unless c
+
+                result = c.emerge!
+                return { success: false, reason: :not_ready, progress: c.transformation_progress } unless result
+
+                { success: true, stage: c.stage, beauty: c.beauty, premature: c.premature? }
+              end
+
+              def disturb_cocoon(cocoon_id:, force:, **)
+                cocoon = @cocoons.fetch(cocoon_id, nil)
+                return { success: false, reason: :not_found } unless cocoon
+
+                disturbed = []
+                cocoon.chrysalis_ids.each do |cid|
+                  c = @chrysalises[cid]
+                  next unless c
+
+                  c.disturb!(force.to_f)
+                  disturbed << { chrysalis_id: cid, protection: c.protection, stage: c.stage }
+                end
+                { success: true, disturbed: disturbed, force: force }
+              end
+
+              def incubate_all!(**)
+                results = []
+                @chrysalises.each_value do |c|
+                  next unless %i[cocooned transforming].include?(c.stage)
+
+                  rate = Helpers::Constants::TRANSFORMATION_RATE
+                  if (cid = @sheltered[c.id])
+                    cocoon = @cocoons[cid]
+                    rate  += cocoon.growth_modifier if cocoon
+                  end
+                  c.transform!(rate)
+                  results << { chrysalis_id: c.id, progress: c.transformation_progress, stage: c.stage }
+                end
+                { success: true, incubated: results.size, results: results }
+              end
+
+              def butterflies
+                @chrysalises.values.select(&:butterfly?)
+              end
+
+              def metamorphosis_report(**)
+                all = @chrysalises.values
+                butterfly_list = all.select(&:butterfly?)
+                {
+                  total_chrysalises:  all.size,
+                  total_cocoons:      @cocoons.size,
+                  butterflies_count:  butterfly_list.size,
+                  premature_count:    butterfly_list.count(&:premature?),
+                  avg_beauty:         avg_beauty(butterfly_list),
+                  avg_progress:       avg_progress(all),
+                  cocooned_count:     all.count(&:cocooned?),
+                  transforming_count: all.count(&:transforming?)
+                }
+              end
+
+              private
+
+              def avg_beauty(list)
+                return 0.0 if list.empty?
+
+                (list.sum(&:beauty) / list.size).round(10)
+              end
+
+              def avg_progress(list)
+                return 0.0 if list.empty?
+
+                (list.sum(&:transformation_progress) / list.size).round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/chrysalis/runners/cognitive_chrysalis.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+          module Runners
+            module CognitiveChrysalis
+              extend self
+
+              begin
+                include Legion::Extensions::Helpers::Lex # rubocop:disable Layout/EmptyLinesAfterModuleInclusion
+              rescue StandardError
+                nil
+              end
+
+              def create_chrysalis(chrysalis_type: :silk, content: '', engine: nil, **)
+                engine ||= default_engine
+                type = chrysalis_type.to_sym
+                unless Helpers::Constants::CHRYSALIS_TYPES.include?(type)
+                  return { success: false, reason: :invalid_type, valid_types: Helpers::Constants::CHRYSALIS_TYPES }
+                end
+
+                Legion::Logging.debug "[cognitive_chrysalis] creating chrysalis type=#{type}"
+                engine.create_chrysalis(chrysalis_type: type, content: content)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def create_cocoon(environment: 'default', temperature: 0.5, humidity: 0.5, engine: nil, **)
+                engine ||= default_engine
+                Legion::Logging.debug "[cognitive_chrysalis] creating cocoon environment=#{environment}"
+                engine.create_cocoon(environment: environment, temperature: temperature, humidity: humidity)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def spin(chrysalis_id:, engine: nil, **)
+                return { success: false, reason: :missing_chrysalis_id } if chrysalis_id.nil?
+
+                engine ||= default_engine
+                Legion::Logging.debug "[cognitive_chrysalis] spinning chrysalis=#{chrysalis_id}"
+                engine.spin(chrysalis_id: chrysalis_id)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def enclose(chrysalis_id:, cocoon_id:, engine: nil, **)
+                return { success: false, reason: :missing_chrysalis_id } if chrysalis_id.nil?
+                return { success: false, reason: :missing_cocoon_id }    if cocoon_id.nil?
+
+                engine ||= default_engine
+                Legion::Logging.debug "[cognitive_chrysalis] enclosing chrysalis=#{chrysalis_id} in cocoon=#{cocoon_id}"
+                engine.enclose(chrysalis_id: chrysalis_id, cocoon_id: cocoon_id)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def incubate(chrysalis_id:, engine: nil, **)
+                return { success: false, reason: :missing_chrysalis_id } if chrysalis_id.nil?
+
+                engine ||= default_engine
+                Legion::Logging.debug "[cognitive_chrysalis] incubating chrysalis=#{chrysalis_id}"
+                engine.incubate(chrysalis_id: chrysalis_id)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def incubate_all(engine: nil, **)
+                engine ||= default_engine
+                Legion::Logging.debug '[cognitive_chrysalis] incubating all eligible chrysalises'
+                engine.incubate_all!
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def emerge(chrysalis_id:, force: false, engine: nil, **)
+                return { success: false, reason: :missing_chrysalis_id } if chrysalis_id.nil?
+
+                engine ||= default_engine
+                Legion::Logging.debug "[cognitive_chrysalis] emerging chrysalis=#{chrysalis_id} force=#{force}"
+                if force
+                  engine.force_emerge(chrysalis_id: chrysalis_id)
+                else
+                  engine.natural_emerge(chrysalis_id: chrysalis_id)
+                end
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def disturb(cocoon_id:, force: 0.1, engine: nil, **)
+                return { success: false, reason: :missing_cocoon_id } if cocoon_id.nil?
+
+                engine ||= default_engine
+                Legion::Logging.debug "[cognitive_chrysalis] disturbing cocoon=#{cocoon_id} force=#{force}"
+                engine.disturb_cocoon(cocoon_id: cocoon_id, force: force)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def list_chrysalises(engine: nil, **)
+                engine ||= default_engine
+                all = engine.instance_variable_get(:@chrysalises) || {}
+                { success: true, chrysalises: all.values.map(&:to_h), count: all.size }
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              def metamorphosis_status(engine: nil, **)
+                engine ||= default_engine
+                report = engine.metamorphosis_report
+                { success: true }.merge(report)
+              rescue ArgumentError => e
+                { success: false, reason: e.message }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::MetamorphosisEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/learning/chrysalis/version'
+require 'legion/extensions/agentic/learning/chrysalis/helpers/constants'
+require 'legion/extensions/agentic/learning/chrysalis/helpers/chrysalis'
+require 'legion/extensions/agentic/learning/chrysalis/helpers/cocoon'
+require 'legion/extensions/agentic/learning/chrysalis/helpers/metamorphosis_engine'
+require 'legion/extensions/agentic/learning/chrysalis/runners/cognitive_chrysalis'
+require 'legion/extensions/agentic/learning/chrysalis/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Chrysalis
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/curiosity/helpers/constants'
+require 'legion/extensions/agentic/learning/curiosity/helpers/wonder'
+require 'legion/extensions/agentic/learning/curiosity/helpers/wonder_store'
+require 'legion/extensions/agentic/learning/curiosity/helpers/gap_detector'
+require 'legion/extensions/agentic/learning/curiosity/runners/curiosity'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Curiosity
+          # Standalone client for curiosity operations without the full framework.
+          class Client
+            include Runners::Curiosity
+
+            attr_reader :wonder_store
+
+            def initialize(store: nil, **)
+              @wonder_store = store || Helpers::WonderStore.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Curiosity
+          module Helpers
+            module Constants
+              GAP_TYPES = %i[unknown uncertain contradictory incomplete].freeze
+
+              MAX_WONDERS                  = 20
+              WONDER_DECAY_RATE            = 0.02    # salience decay per hour
+              WONDER_STALE_THRESHOLD       = 259_200 # 3 days in seconds
+              MAX_EXPLORATION_ATTEMPTS     = 5
+              INFORMATION_GAIN_THRESHOLD   = 0.3     # minimum expected gain to create wonder
+              CURIOSITY_REWARD_MULTIPLIER  = 1.5     # emotional reward on resolution
+              DOMAIN_BALANCE_FACTOR        = 0.7     # penalize overrepresented domains
+              DIVERSIVE_NOVELTY_THRESHOLD  = 0.6     # novelty above which diversive curiosity triggers
+              SPECIFIC_GAP_THRESHOLD       = 0.5     # gap score above which specific curiosity triggers
+              EXPLORATION_COOLDOWN         = 300     # seconds between re-exploration of same wonder
+              LOW_CONFIDENCE_THRESHOLD     = 0.5     # prediction confidence below this triggers wonder
+              EMPTY_RETRIEVAL_THRESHOLD    = 2       # fewer traces than this = unknown domain
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/curiosity/helpers/gap_detector.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Curiosity
+          module Helpers
+            # Analyzes tick phase results for knowledge gaps that drive curiosity.
+            module GapDetector
+              module_function
+
+              def detect(prior_results)
+                detectors = %i[memory_retrieval prediction_engine emotional_evaluation contradiction_resolution]
+                methods   = %i[detect_memory_gaps detect_prediction_gaps detect_emotional_gaps detect_contradiction_gaps]
+
+                gaps = detectors.zip(methods).flat_map { |key, method| send(method, prior_results[key]) }
+
+                gaps
+                  .select { |g| g[:information_gain] >= Constants::INFORMATION_GAIN_THRESHOLD }
+                  .sort_by { |g| -((g[:salience] * 0.6) + (g[:information_gain] * 0.4)) }
+              end
+
+              def detect_memory_gaps(result)
+                return [] unless result.is_a?(Hash)
+
+                gaps = []
+                traces = result[:traces]
+                domain = result[:domain] || :general
+
+                gaps << unknown_domain_gap(traces, domain) if sparse_traces?(traces)
+                gaps << incomplete_knowledge_gap(traces, domain) if weak_traces?(traces)
+                gaps.compact
+              end
+
+              def detect_prediction_gaps(result)
+                return [] unless result.is_a?(Hash)
+
+                gaps = []
+                gaps << low_confidence_gap(result) if low_confidence?(result)
+                gaps << failed_prediction_gap(result) if failed_prediction?(result)
+                gaps
+              end
+
+              def detect_emotional_gaps(result)
+                return [] unless result.is_a?(Hash)
+
+                valence = result[:valence]
+                return [] unless valence.is_a?(Hash) && novel_unfamiliar?(valence)
+
+                [novel_unfamiliar_gap(result, valence)]
+              end
+
+              def detect_contradiction_gaps(result)
+                return [] unless result.is_a?(Hash)
+
+                conflicts = result[:active_conflicts] || result[:conflicts]
+                return [] unless conflicts.is_a?(Array) && !conflicts.empty?
+
+                conflicts.first(3).map { |c| contradiction_gap(c) }
+              end
+
+              # -- private helpers below --
+
+              def sparse_traces?(traces)
+                traces.is_a?(Array) && traces.size < Constants::EMPTY_RETRIEVAL_THRESHOLD
+              end
+
+              def weak_traces?(traces)
+                return false unless traces.is_a?(Array)
+
+                traces.any? { |t| t.is_a?(Hash) && (t[:strength] || 1.0) < 0.3 }
+              end
+
+              def low_confidence?(result)
+                c = result[:confidence]
+                c.is_a?(Numeric) && c < Constants::LOW_CONFIDENCE_THRESHOLD
+              end
+
+              def failed_prediction?(result)
+                result[:status] == :failed || result[:error]
+              end
+
+              def novel_unfamiliar?(valence)
+                (valence[:novelty] || 0.0) > Constants::DIVERSIVE_NOVELTY_THRESHOLD &&
+                  (valence[:familiarity] || 1.0) < 0.3
+              end
+
+              def unknown_domain_gap(traces, domain)
+                {
+                  gap_type:         :unknown,
+                  domain:           domain,
+                  question:         "What do I know about #{domain}?",
+                  salience:         0.6,
+                  information_gain: 0.7,
+                  source_trace_ids: traces&.filter_map { |t| t[:trace_id] } || []
+                }
+              end
+
+              def incomplete_knowledge_gap(traces, domain)
+                weak = traces.select { |t| t.is_a?(Hash) && (t[:strength] || 1.0) < 0.3 }
+                return nil if weak.empty?
+
+                {
+                  gap_type:         :incomplete,
+                  domain:           domain,
+                  question:         'Why are my memories about this topic weak?',
+                  salience:         0.4,
+                  information_gain: 0.5,
+                  source_trace_ids: weak.filter_map { |t| t[:trace_id] }
+                }
+              end
+
+              def low_confidence_gap(result)
+                confidence = result[:confidence]
+                {
+                  gap_type:         :uncertain,
+                  domain:           result[:domain] || :general,
+                  question:         "Why is my prediction confidence low (#{(confidence * 100).round}%)?",
+                  salience:         0.7,
+                  information_gain: 0.6,
+                  source_trace_ids: []
+                }
+              end
+
+              def failed_prediction_gap(result)
+                {
+                  gap_type:         :uncertain,
+                  domain:           result[:domain] || :general,
+                  question:         'What caused this prediction failure?',
+                  salience:         0.8,
+                  information_gain: 0.7,
+                  source_trace_ids: []
+                }
+              end
+
+              def novel_unfamiliar_gap(result, valence)
+                novelty = valence[:novelty] || 0.0
+                familiarity = valence[:familiarity] || 1.0
+                {
+                  gap_type:         :unknown,
+                  domain:           result[:domain] || :general,
+                  question:         'This is novel and unfamiliar — what is it?',
+                  salience:         novelty,
+                  information_gain: (1.0 - familiarity) * 0.8,
+                  source_trace_ids: []
+                }
+              end
+
+              def contradiction_gap(conflict)
+                domain = conflict.is_a?(Hash) ? (conflict[:domain] || :general) : :general
+                {
+                  gap_type:         :contradictory,
+                  domain:           domain,
+                  question:         "Why do I have contradictory knowledge about #{domain}?",
+                  salience:         0.8,
+                  information_gain: 0.7,
+                  source_trace_ids: conflict.is_a?(Hash) ? Array(conflict[:trace_ids]) : []
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/curiosity/helpers/wonder.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Curiosity
+          module Helpers
+            module Wonder
+              module_function
+
+              def new_wonder(question:, domain: :general, gap_type: :unknown,
+                             salience: 0.5, information_gain: 0.5,
+                             source_trace_ids: [], emotional_valence: {})
+                raise ArgumentError, "invalid gap_type: #{gap_type}" unless Constants::GAP_TYPES.include?(gap_type)
+
+                {
+                  wonder_id:         SecureRandom.uuid,
+                  question:          question,
+                  domain:            domain.to_sym,
+                  gap_type:          gap_type,
+                  salience:          salience.clamp(0.0, 1.0),
+                  information_gain:  information_gain.clamp(0.0, 1.0),
+                  attempts:          0,
+                  created_at:        Time.now.utc,
+                  last_explored_at:  nil,
+                  resolved:          false,
+                  resolution:        nil,
+                  source_trace_ids:  Array(source_trace_ids),
+                  emotional_valence: emotional_valence
+                }
+              end
+
+              def score(wonder)
+                return 0.0 if wonder[:resolved]
+
+                base = (wonder[:salience] * 0.6) + (wonder[:information_gain] * 0.4)
+                attempt_penalty = [wonder[:attempts] * 0.1, 0.5].min
+                base - attempt_penalty
+              end
+
+              def stale?(wonder)
+                age = Time.now.utc - wonder[:created_at]
+                age > Constants::WONDER_STALE_THRESHOLD
+              end
+
+              def explorable?(wonder)
+                return false if wonder[:resolved]
+                return false if wonder[:attempts] >= Constants::MAX_EXPLORATION_ATTEMPTS
+
+                if wonder[:last_explored_at]
+                  cooldown = Constants::EXPLORATION_COOLDOWN * (2**[wonder[:attempts] - 1, 0].max)
+                  return false if (Time.now.utc - wonder[:last_explored_at]) < cooldown
+                end
+
+                true
+              end
+
+              def decay_salience(wonder, hours_elapsed: 1.0)
+                return wonder if wonder[:resolved]
+
+                decayed = wonder[:salience] - (Constants::WONDER_DECAY_RATE * hours_elapsed)
+                wonder.merge(salience: [decayed, 0.0].max)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end