lex-agentic-learning 0.1.0

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

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Curiosity
+          module Helpers
+            # In-memory priority queue for wonder items with domain balancing and decay.
+            class WonderStore
+              attr_reader :resolved_count, :total_generated
+
+              def initialize
+                @wonders = {}
+                @resolved_count = 0
+                @total_generated = 0
+                @domain_resolution_rates = Hash.new { |h, k| h[k] = { resolved: 0, total: 0 } }
+              end
+
+              def store(wonder)
+                prune_if_full
+                @wonders[wonder[:wonder_id]] = wonder
+                @total_generated += 1
+                @domain_resolution_rates[wonder[:domain]][:total] += 1
+                wonder
+              end
+
+              def get(wonder_id)
+                @wonders[wonder_id]
+              end
+
+              def update(wonder_id, attrs)
+                wonder = @wonders[wonder_id]
+                return nil unless wonder
+
+                @wonders[wonder_id] = wonder.merge(attrs)
+              end
+
+              def delete(wonder_id)
+                @wonders.delete(wonder_id)
+              end
+
+              def active_wonders
+                @wonders.values.reject { |w| w[:resolved] }
+              end
+
+              def resolved_wonders
+                @wonders.values.select { |w| w[:resolved] }
+              end
+
+              def top(limit: 5, exclude_domains: [])
+                active_wonders
+                  .reject { |w| exclude_domains.include?(w[:domain]) }
+                  .sort_by { |w| -Wonder.score(w) }
+                  .first(limit)
+              end
+
+              def top_balanced(limit: 5)
+                domain_counts = active_wonders.group_by { |w| w[:domain] }
+                                              .transform_values(&:size)
+                max_domain = domain_counts.values.max || 1
+
+                active_wonders
+                  .sort_by do |w|
+                    domain_penalty = (domain_counts[w[:domain]].to_f / max_domain) * Constants::DOMAIN_BALANCE_FACTOR
+                    -(Wonder.score(w) - domain_penalty)
+                  end
+                  .first(limit)
+              end
+
+              def by_domain(domain)
+                active_wonders.select { |w| w[:domain] == domain.to_sym }
+              end
+
+              def mark_resolved(wonder_id, resolution:, actual_gain: 0.5)
+                wonder = @wonders[wonder_id]
+                return nil unless wonder
+
+                @wonders[wonder_id] = wonder.merge(
+                  resolved:    true,
+                  resolution:  resolution,
+                  actual_gain: actual_gain
+                )
+                @resolved_count += 1
+                @domain_resolution_rates[wonder[:domain]][:resolved] += 1
+                @wonders[wonder_id]
+              end
+
+              def decay_all(hours_elapsed: 1.0)
+                pruned = 0
+                @wonders.each do |id, wonder|
+                  next if wonder[:resolved]
+
+                  decayed = Wonder.decay_salience(wonder, hours_elapsed: hours_elapsed)
+                  if decayed[:salience] <= 0.0 || Wonder.stale?(decayed)
+                    @wonders.delete(id)
+                    pruned += 1
+                  else
+                    @wonders[id] = decayed
+                  end
+                end
+                pruned
+              end
+
+              def count
+                @wonders.size
+              end
+
+              def active_count
+                active_wonders.size
+              end
+
+              def domain_stats
+                stats = Hash.new { |h, k| h[k] = { active: 0, resolved: 0 } }
+                @wonders.each_value do |w|
+                  key = w[:resolved] ? :resolved : :active
+                  stats[w[:domain]][key] += 1
+                end
+                stats
+              end
+
+              def resolution_rate
+                return 0.0 if @total_generated.zero?
+
+                @resolved_count.to_f / @total_generated
+              end
+
+              def domain_resolution_rate(domain)
+                rates = @domain_resolution_rates[domain.to_sym]
+                return 0.0 if rates[:total].zero?
+
+                rates[:resolved].to_f / rates[:total]
+              end
+
+              private
+
+              def prune_if_full
+                return unless active_count >= Constants::MAX_WONDERS
+
+                lowest = active_wonders.min_by { |w| Wonder.score(w) }
+                @wonders.delete(lowest[:wonder_id]) if lowest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module Curiosity
+          module Runners
+            # Runner methods for the curiosity engine: gap detection, wonder lifecycle, agenda formation.
+            module Curiosity
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def detect_gaps(prior_results: {}, **)
+                gaps = Helpers::GapDetector.detect(prior_results)
+                Legion::Logging.debug "[curiosity] detected #{gaps.size} knowledge gaps"
+
+                created = create_wonders_from_gaps(gaps)
+                build_detect_result(gaps, created)
+              end
+
+              def generate_wonder(question:, domain: :general, gap_type: :unknown,
+                                  salience: 0.5, information_gain: 0.5,
+                                  source_trace_ids: [], **)
+                wonder = Helpers::Wonder.new_wonder(
+                  question: question, domain: domain, gap_type: gap_type,
+                  salience: salience, information_gain: information_gain,
+                  source_trace_ids: source_trace_ids
+                )
+                wonder_store.store(wonder)
+                Legion::Logging.info "[curiosity] manually generated wonder: #{question}"
+                wonder
+              end
+
+              def explore_wonder(wonder_id:, **)
+                wonder = wonder_store.get(wonder_id)
+                return { error: :not_found } unless wonder
+                return { error: :already_resolved } if wonder[:resolved]
+                return { error: :not_explorable, reason: :max_attempts } unless Helpers::Wonder.explorable?(wonder)
+
+                wonder_store.update(wonder_id, attempts: wonder[:attempts] + 1, last_explored_at: Time.now.utc)
+                Legion::Logging.info "[curiosity] exploring: #{wonder[:question]} (attempt ##{wonder[:attempts] + 1})"
+                { exploring: true, wonder_id: wonder_id, attempt: wonder[:attempts] + 1 }
+              end
+
+              def resolve_wonder(wonder_id:, resolution:, actual_gain: 0.5, **)
+                wonder = wonder_store.get(wonder_id)
+                return { error: :not_found } unless wonder
+                return { error: :already_resolved } if wonder[:resolved]
+
+                resolved = wonder_store.mark_resolved(wonder_id, resolution: resolution, actual_gain: actual_gain)
+                build_resolve_result(wonder, resolved, actual_gain)
+              end
+
+              def curiosity_intensity(**)
+                intensity = compute_intensity
+                Legion::Logging.debug "[curiosity] intensity=#{intensity.round(3)}"
+                { intensity: intensity, active_wonders: wonder_store.active_count,
+                  resolution_rate: wonder_store.resolution_rate.round(3), top_domain: top_curiosity_domain }
+              end
+
+              def top_wonders(limit: 5, **)
+                wonders = wonder_store.top_balanced(limit: limit)
+                Legion::Logging.debug "[curiosity] top #{wonders.size} wonders requested"
+                { wonders: wonders.map { |w| format_wonder(w) } }
+              end
+
+              def form_agenda(**)
+                wonders = wonder_store.top_balanced(limit: 5)
+                Legion::Logging.debug "[curiosity] forming agenda from #{wonders.size} wonders"
+                { agenda_items: wonders.map { |w| format_agenda_item(w) }, source: :curiosity }
+              end
+
+              def wonder_stats(**)
+                { total_generated: wonder_store.total_generated, active: wonder_store.active_count,
+                  resolved: wonder_store.resolved_count, resolution_rate: wonder_store.resolution_rate.round(3),
+                  intensity: compute_intensity.round(3), domains: wonder_store.domain_stats }
+              end
+
+              def decay_wonders(hours_elapsed: 1.0, **)
+                pruned = wonder_store.decay_all(hours_elapsed: hours_elapsed)
+                Legion::Logging.debug "[curiosity] decay: pruned=#{pruned} remaining=#{wonder_store.active_count}"
+                { pruned: pruned, remaining: wonder_store.active_count }
+              end
+
+              private
+
+              def wonder_store
+                @wonder_store ||= Helpers::WonderStore.new
+              end
+
+              def create_wonders_from_gaps(gaps)
+                gaps.each_with_object([]) do |gap, created|
+                  next if duplicate_wonder?(gap)
+
+                  wonder = Helpers::Wonder.new_wonder(**gap.slice(:question, :domain, :gap_type,
+                                                                  :salience, :information_gain, :source_trace_ids))
+                  wonder_store.store(wonder)
+                  created << wonder
+                  Legion::Logging.info "[curiosity] new wonder: #{wonder[:question]} (#{wonder[:gap_type]}/#{wonder[:domain]})"
+                end
+              end
+
+              def build_detect_result(gaps, created)
+                intensity = compute_intensity
+                top = wonder_store.top_balanced(limit: 3)
+                Legion::Logging.debug "[curiosity] intensity=#{intensity.round(3)} active=#{wonder_store.active_count}"
+                { gaps_detected: gaps.size, wonders_created: created.size, curiosity_intensity: intensity,
+                  top_wonders: top.map { |w| { wonder_id: w[:wonder_id], question: w[:question], score: Helpers::Wonder.score(w).round(3) } },
+                  active_count: wonder_store.active_count }
+              end
+
+              def build_resolve_result(wonder, resolved, actual_gain)
+                reward = actual_gain * Helpers::Constants::CURIOSITY_REWARD_MULTIPLIER
+                Legion::Logging.info "[curiosity] resolved: #{wonder[:question]} gain=#{actual_gain.round(2)}"
+                { resolved: true, wonder_id: wonder[:wonder_id], actual_gain: actual_gain,
+                  expected_gain: wonder[:information_gain], reward: reward,
+                  domain: resolved[:domain], resolution_rate: wonder_store.resolution_rate.round(3) }
+              end
+
+              def format_wonder(wonder)
+                { wonder_id: wonder[:wonder_id], question: wonder[:question], domain: wonder[:domain],
+                  gap_type: wonder[:gap_type], score: Helpers::Wonder.score(wonder).round(3),
+                  attempts: wonder[:attempts], explorable: Helpers::Wonder.explorable?(wonder),
+                  created_at: wonder[:created_at] }
+              end
+
+              def format_agenda_item(wonder)
+                { type: :curious, source: :curiosity, weight: Helpers::Wonder.score(wonder),
+                  summary: wonder[:question],
+                  metadata: { wonder_id: wonder[:wonder_id], domain: wonder[:domain], gap_type: wonder[:gap_type] } }
+              end
+
+              def compute_intensity
+                active = wonder_store.active_count
+                return 0.0 if active.zero?
+
+                fullness = active.to_f / Helpers::Constants::MAX_WONDERS
+                avg_salience = wonder_store.active_wonders.sum { |w| w[:salience] } / active
+                explorable = wonder_store.active_wonders.count { |w| Helpers::Wonder.explorable?(w) }
+                ((fullness * 0.3) + (avg_salience * 0.4) + ((explorable.to_f / active) * 0.3)).clamp(0.0, 1.0)
+              end
+
+              def top_curiosity_domain
+                groups = wonder_store.active_wonders.group_by { |w| w[:domain] }
+                return nil if groups.empty?
+
+                groups.max_by { |_, wonders| wonders.sum { |w| Helpers::Wonder.score(w) } }&.first
+              end
+
+              def duplicate_wonder?(gap)
+                wonder_store.active_wonders.any? do |existing|
+                  existing[:domain] == gap[:domain] && existing[:gap_type] == gap[:gap_type] &&
+                    existing[:question] == gap[:question]
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/curiosity/version'
+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'
+require 'legion/extensions/agentic/learning/curiosity/client'
+
+module Legion
+  module Extensions
+    # Intrinsic curiosity engine — knowledge gap detection, wonder lifecycle, curiosity-driven learning.
+    module Agentic
+      module Learning
+        module Curiosity
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/epistemic_curiosity/helpers/constants'
+require 'legion/extensions/agentic/learning/epistemic_curiosity/helpers/knowledge_gap'
+require 'legion/extensions/agentic/learning/epistemic_curiosity/helpers/curiosity_engine'
+require 'legion/extensions/agentic/learning/epistemic_curiosity/runners/epistemic_curiosity'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module EpistemicCuriosity
+          class Client
+            include Runners::EpistemicCuriosity
+
+            def initialize(**)
+              @engine = Helpers::CuriosityEngine.new
+            end
+
+            private
+
+            attr_reader :engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module EpistemicCuriosity
+          module Helpers
+            module Constants
+              MAX_GAPS             = 300
+              DEFAULT_URGENCY      = 0.5
+              URGENCY_BOOST        = 0.08
+              URGENCY_DECAY        = 0.03
+              SATISFACTION_THRESHOLD = 0.8
+
+              GAP_TYPES = %i[factual conceptual procedural causal relational].freeze
+
+              URGENCY_LABELS = [
+                { range: (0.8..1.0), label: :burning },
+                { range: (0.6...0.8), label: :intense   },
+                { range: (0.4...0.6), label: :moderate  },
+                { range: (0.2...0.4), label: :mild      },
+                { range: (0.0...0.2), label: :satisfied }
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/epistemic_curiosity/helpers/curiosity_engine.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module EpistemicCuriosity
+          module Helpers
+            class CuriosityEngine
+              def initialize
+                @gaps    = {}
+                @counter = 0
+              end
+
+              def create_gap(question:, domain:, gap_type: :factual, urgency: Constants::DEFAULT_URGENCY)
+                prune_resolved if @gaps.size >= Constants::MAX_GAPS
+                return { created: false, reason: :at_capacity } if @gaps.size >= Constants::MAX_GAPS
+
+                gap_type = :factual unless Constants::GAP_TYPES.include?(gap_type)
+                id       = next_id
+                gap      = KnowledgeGap.new(id: id, question: question, domain: domain, gap_type: gap_type, urgency: urgency)
+                @gaps[id] = gap
+                { created: true, gap: gap.to_h }
+              end
+
+              def explore_gap(gap_id:)
+                gap = @gaps[gap_id]
+                return { found: false, gap_id: gap_id } unless gap
+
+                gap.explore!
+                { found: true, gap: gap.to_h }
+              end
+
+              def satisfy_gap(gap_id:, amount: 0.3)
+                gap = @gaps[gap_id]
+                return { found: false, gap_id: gap_id } unless gap
+
+                gap.satisfy!(amount: amount)
+                { found: true, gap: gap.to_h }
+              end
+
+              def resolve_gap(gap_id:)
+                gap = @gaps[gap_id]
+                return { found: false, gap_id: gap_id } unless gap
+
+                gap.satisfaction = 1.0
+                gap.resolved_at  = Time.now.utc
+                { found: true, resolved: true, gap: gap.to_h }
+              end
+
+              def open_gaps
+                @gaps.values.reject(&:resolved?)
+              end
+
+              def resolved_gaps
+                @gaps.values.select(&:resolved?)
+              end
+
+              def most_urgent(limit: 5)
+                open_gaps.sort_by { |g| -g.urgency }.first(limit)
+              end
+
+              def by_domain(domain)
+                @gaps.values.select { |g| g.domain == domain }
+              end
+
+              def by_type(gap_type)
+                @gaps.values.select { |g| g.gap_type == gap_type }
+              end
+
+              def information_debt
+                open_gaps.sum(&:urgency).round(4)
+              end
+
+              def exploration_efficiency
+                total = @gaps.size
+                return 0.0 if total.zero?
+
+                (resolved_gaps.size.to_f / total).round(4)
+              end
+
+              def decay_all
+                @gaps.each_value(&:decay!)
+                @gaps.size
+              end
+
+              def prune_resolved
+                @gaps.delete_if { |_id, gap| gap.resolved? }
+              end
+
+              def curiosity_report
+                {
+                  total_gaps:             @gaps.size,
+                  open_gaps:              open_gaps.size,
+                  resolved_gaps:          resolved_gaps.size,
+                  information_debt:       information_debt,
+                  exploration_efficiency: exploration_efficiency,
+                  most_urgent:            most_urgent(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  gaps:                   @gaps.transform_values(&:to_h),
+                  information_debt:       information_debt,
+                  exploration_efficiency: exploration_efficiency
+                }
+              end
+
+              private
+
+              def next_id
+                @counter += 1
+                :"gap_#{@counter}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/learning/epistemic_curiosity/helpers/knowledge_gap.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Learning
+        module EpistemicCuriosity
+          module Helpers
+            class KnowledgeGap
+              attr_reader :id, :question, :domain, :gap_type, :explorations, :created_at
+              attr_accessor :urgency, :satisfaction, :resolved_at
+
+              def initialize(id:, question:, domain:, gap_type:, urgency: Constants::DEFAULT_URGENCY)
+                @id           = id
+                @question     = question
+                @domain       = domain
+                @gap_type     = gap_type
+                @urgency      = urgency.clamp(0.0, 1.0)
+                @satisfaction = 0.0
+                @explorations = 0
+                @created_at   = Time.now.utc
+                @resolved_at  = nil
+              end
+
+              def explore!
+                @explorations += 1
+                @urgency = (@urgency + Constants::URGENCY_BOOST).clamp(0.0, 1.0)
+                self
+              end
+
+              def satisfy!(amount: 0.3)
+                @satisfaction = (@satisfaction + amount).clamp(0.0, 1.0)
+                self
+              end
+
+              def resolved?
+                @satisfaction >= Constants::SATISFACTION_THRESHOLD
+              end
+
+              def urgency_label
+                Constants::URGENCY_LABELS.find { |entry| entry[:range].cover?(@urgency) }&.fetch(:label, :mild) || :mild
+              end
+
+              def decay!
+                @urgency = (@urgency - Constants::URGENCY_DECAY).clamp(0.0, 1.0)
+                self
+              end
+
+              def to_h
+                {
+                  id:            @id,
+                  question:      @question,
+                  domain:        @domain,
+                  gap_type:      @gap_type,
+                  urgency:       @urgency.round(4),
+                  urgency_label: urgency_label,
+                  satisfaction:  @satisfaction.round(4),
+                  explorations:  @explorations,
+                  resolved:      resolved?,
+                  created_at:    @created_at,
+                  resolved_at:   @resolved_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end