lex-agentic-self 0.1.0

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+          module Helpers
+            MAX_JUDGMENTS          = 500
+            MAX_CALIBRATION_POINTS = 200
+            JUDGMENT_TYPES         = %i[feeling_of_knowing judgment_of_learning confidence_rating effort_estimate
+                                        error_detection].freeze
+
+            CALIBRATION_LABELS = {
+              (0.8..)     => :well_calibrated,
+              (0.6...0.8) => :slightly_miscalibrated,
+              (0.4...0.6) => :miscalibrated,
+              (0.2...0.4) => :poorly_calibrated,
+              (..0.2)     => :uncalibrated
+            }.freeze
+
+            CONFIDENCE_LABELS = {
+              (0.8..)     => :very_high,
+              (0.6...0.8) => :high,
+              (0.4...0.6) => :moderate,
+              (0.2...0.4) => :low,
+              (..0.2)     => :very_low
+            }.freeze
+
+            EFFORT_LABELS = {
+              (0.8..)     => :extreme,
+              (0.6...0.8) => :high,
+              (0.4...0.6) => :moderate,
+              (0.2...0.4) => :low,
+              (..0.2)     => :minimal
+            }.freeze
+
+            OVERCONFIDENCE_THRESHOLD  = 0.2  # predicted - actual > this = overconfident
+            UNDERCONFIDENCE_THRESHOLD = -0.2
+            DEFAULT_CONFIDENCE        = 0.5
+            CALIBRATION_WINDOW        = 50   # last N judgments for calibration calculation
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/metacognitive_monitoring/helpers/monitoring_engine.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+          module Helpers
+            class MonitoringEngine
+              attr_reader :judgments, :calibration, :domain_calibrations
+
+              def initialize
+                @judgments           = {}
+                @calibration         = CalibrationTracker.new
+                @domain_calibrations = {}
+              end
+
+              def record_judgment(type:, domain:, predicted_confidence: DEFAULT_CONFIDENCE, effort: 0.5)
+                judgment = MonitoringJudgment.new(
+                  judgment_type:        type,
+                  domain:               domain,
+                  predicted_confidence: predicted_confidence,
+                  effort_level:         effort
+                )
+
+                @judgments[judgment.id] = judgment
+                prune_judgments
+                judgment
+              end
+
+              def resolve_judgment(judgment_id:, actual_outcome:)
+                judgment = @judgments[judgment_id]
+                return nil unless judgment
+
+                judgment.resolve!(actual: actual_outcome)
+
+                @calibration.add_point(predicted: judgment.predicted_confidence, actual: actual_outcome)
+
+                domain_calibration_for(judgment.domain).add_point(
+                  predicted: judgment.predicted_confidence,
+                  actual:    actual_outcome
+                )
+
+                judgment
+              end
+
+              def feeling_of_knowing(domain:, query: nil)
+                domain_cal   = domain_calibration_for(domain)
+                base_conf    = domain_cal.empty? ? DEFAULT_CONFIDENCE : domain_cal.calibration_score
+                richness_mod = query.to_s.split.size * 0.02
+                confidence   = [(base_conf + richness_mod).clamp(0.0, 1.0), 1.0].min
+
+                record_judgment(
+                  type:                 :feeling_of_knowing,
+                  domain:               domain,
+                  predicted_confidence: confidence,
+                  effort:               0.3
+                )
+              end
+
+              def judgment_of_learning(domain:, content: nil)
+                domain_cal  = domain_calibration_for(domain)
+                base_conf   = domain_cal.empty? ? DEFAULT_CONFIDENCE : domain_cal.calibration_score
+                length_mod  = [(content.to_s.length * 0.001), 0.1].min
+                confidence  = (base_conf + length_mod).clamp(0.0, 1.0)
+
+                record_judgment(
+                  type:                 :judgment_of_learning,
+                  domain:               domain,
+                  predicted_confidence: confidence,
+                  effort:               0.4
+                )
+              end
+
+              def detect_overconfidence
+                @judgments.values.select(&:overconfident?)
+              end
+
+              def detect_underconfidence
+                @judgments.values.select(&:underconfident?)
+              end
+
+              def average_effort(window: CALIBRATION_WINDOW)
+                recent = @judgments.values.last(window)
+                return 0.0 if recent.empty?
+
+                (recent.sum(&:effort_level) / recent.size).round(10)
+              end
+
+              def calibration_report
+                domain_reports = @domain_calibrations.transform_values(&:to_h)
+                {
+                  overall:        @calibration.to_h,
+                  by_domain:      domain_reports,
+                  total_resolved: @judgments.values.count(&:resolved)
+                }
+              end
+
+              def monitoring_report
+                resolved, unresolved = @judgments.values.partition(&:resolved)
+
+                {
+                  total_judgments:      @judgments.size,
+                  resolved_count:       resolved.size,
+                  unresolved_count:     unresolved.size,
+                  overconfident_count:  detect_overconfidence.size,
+                  underconfident_count: detect_underconfidence.size,
+                  average_effort:       average_effort,
+                  calibration:          @calibration.to_h,
+                  domain_count:         @domain_calibrations.size
+                }
+              end
+
+              def to_h
+                {
+                  judgment_count: @judgments.size,
+                  calibration:    @calibration.to_h,
+                  domain_count:   @domain_calibrations.size,
+                  average_effort: average_effort
+                }
+              end
+
+              private
+
+              def domain_calibration_for(domain)
+                @domain_calibrations[domain] ||= CalibrationTracker.new
+              end
+
+              def prune_judgments
+                return unless @judgments.size > MAX_JUDGMENTS
+
+                oldest_keys = @judgments.keys.first(@judgments.size - MAX_JUDGMENTS)
+                oldest_keys.each { |k| @judgments.delete(k) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/metacognitive_monitoring/helpers/monitoring_judgment.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+          module Helpers
+            class MonitoringJudgment
+              attr_reader :id, :judgment_type, :domain, :predicted_confidence, :actual_outcome,
+                          :effort_level, :resolved, :created_at
+
+              def initialize(judgment_type:, domain:, predicted_confidence: DEFAULT_CONFIDENCE, effort_level: 0.5)
+                @id                   = SecureRandom.uuid
+                @judgment_type        = judgment_type
+                @domain               = domain
+                @predicted_confidence = predicted_confidence.clamp(0.0, 1.0)
+                @effort_level         = effort_level.clamp(0.0, 1.0)
+                @actual_outcome       = nil
+                @resolved             = false
+                @created_at           = Time.now.utc
+              end
+
+              def resolve!(actual:)
+                @actual_outcome = actual.clamp(0.0, 1.0)
+                @resolved       = true
+                self
+              end
+
+              def calibration_error
+                return nil unless resolved
+
+                (predicted_confidence - actual_outcome).round(10)
+              end
+
+              def overconfident?
+                return false unless resolved
+
+                calibration_error > OVERCONFIDENCE_THRESHOLD
+              end
+
+              def underconfident?
+                return false unless resolved
+
+                calibration_error < UNDERCONFIDENCE_THRESHOLD
+              end
+
+              def confidence_label
+                CONFIDENCE_LABELS.find { |range, _| range.cover?(predicted_confidence) }&.last
+              end
+
+              def effort_label
+                EFFORT_LABELS.find { |range, _| range.cover?(effort_level) }&.last
+              end
+
+              def to_h
+                {
+                  id:                   id,
+                  judgment_type:        judgment_type,
+                  domain:               domain,
+                  predicted_confidence: predicted_confidence,
+                  actual_outcome:       actual_outcome,
+                  effort_level:         effort_level,
+                  resolved:             resolved,
+                  calibration_error:    calibration_error,
+                  confidence_label:     confidence_label,
+                  effort_label:         effort_label,
+                  created_at:           created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+          module Runners
+            module MetacognitiveMonitoring
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def record_judgment(type:, domain:, predicted_confidence: Helpers::DEFAULT_CONFIDENCE,
+                                  effort: 0.5, engine: nil, **)
+                eng       = engine || monitoring_engine
+                type_sym  = type.to_sym
+
+                return { success: false, error: :invalid_judgment_type, valid_types: Helpers::JUDGMENT_TYPES } unless Helpers::JUDGMENT_TYPES.include?(type_sym)
+
+                judgment = eng.record_judgment(
+                  type:                 type_sym,
+                  domain:               domain,
+                  predicted_confidence: predicted_confidence,
+                  effort:               effort
+                )
+
+                Legion::Logging.debug "[metacognitive] record_judgment type=#{type_sym} domain=#{domain} " \
+                                      "confidence=#{judgment.predicted_confidence.round(2)} id=#{judgment.id[0..7]}"
+
+                { success: true, judgment_id: judgment.id, judgment: judgment.to_h }
+              end
+
+              def resolve_judgment(judgment_id:, actual_outcome:, engine: nil, **)
+                eng      = engine || monitoring_engine
+                judgment = eng.resolve_judgment(judgment_id: judgment_id, actual_outcome: actual_outcome)
+
+                unless judgment
+                  Legion::Logging.debug "[metacognitive] resolve_judgment not_found id=#{judgment_id[0..7]}"
+                  return { success: false, error: :not_found }
+                end
+
+                Legion::Logging.info "[metacognitive] resolved judgment=#{judgment_id[0..7]} " \
+                                     "error=#{judgment.calibration_error&.round(3)}"
+
+                { success: true, judgment_id: judgment_id, judgment: judgment.to_h }
+              end
+
+              def feeling_of_knowing(domain:, query: nil, engine: nil, **)
+                eng      = engine || monitoring_engine
+                judgment = eng.feeling_of_knowing(domain: domain, query: query)
+
+                Legion::Logging.debug "[metacognitive] fok domain=#{domain} confidence=#{judgment.predicted_confidence.round(2)}"
+
+                {
+                  success:              true,
+                  judgment_id:          judgment.id,
+                  domain:               domain,
+                  predicted_confidence: judgment.predicted_confidence,
+                  confidence_label:     judgment.confidence_label
+                }
+              end
+
+              def judgment_of_learning(domain:, content: nil, engine: nil, **)
+                eng      = engine || monitoring_engine
+                judgment = eng.judgment_of_learning(domain: domain, content: content)
+
+                Legion::Logging.debug "[metacognitive] jol domain=#{domain} confidence=#{judgment.predicted_confidence.round(2)}"
+
+                {
+                  success:              true,
+                  judgment_id:          judgment.id,
+                  domain:               domain,
+                  predicted_confidence: judgment.predicted_confidence,
+                  confidence_label:     judgment.confidence_label
+                }
+              end
+
+              def detect_overconfidence(engine: nil, **)
+                eng      = engine || monitoring_engine
+                findings = eng.detect_overconfidence
+
+                Legion::Logging.debug "[metacognitive] overconfidence_scan count=#{findings.size}"
+
+                {
+                  success:  true,
+                  count:    findings.size,
+                  findings: findings.map(&:to_h)
+                }
+              end
+
+              def detect_underconfidence(engine: nil, **)
+                eng      = engine || monitoring_engine
+                findings = eng.detect_underconfidence
+
+                Legion::Logging.debug "[metacognitive] underconfidence_scan count=#{findings.size}"
+
+                {
+                  success:  true,
+                  count:    findings.size,
+                  findings: findings.map(&:to_h)
+                }
+              end
+
+              def calibration_report(engine: nil, **)
+                eng    = engine || monitoring_engine
+                report = eng.calibration_report
+
+                Legion::Logging.debug "[metacognitive] calibration_report domains=#{report[:by_domain].size}"
+
+                { success: true, report: report }
+              end
+
+              def monitoring_report(engine: nil, **)
+                eng    = engine || monitoring_engine
+                report = eng.monitoring_report
+
+                Legion::Logging.debug "[metacognitive] monitoring_report total=#{report[:total_judgments]}"
+
+                { success: true, report: report }
+              end
+
+              def average_effort(window: Helpers::CALIBRATION_WINDOW, engine: nil, **)
+                eng    = engine || monitoring_engine
+                effort = eng.average_effort(window: window)
+
+                label = Helpers::EFFORT_LABELS.find { |range, _| range.cover?(effort) }&.last
+
+                { success: true, average_effort: effort, effort_label: label, window: window }
+              end
+
+              def calibration_curve(bins: 5, engine: nil, **)
+                eng   = engine || monitoring_engine
+                curve = eng.calibration.calibration_curve(bins: bins)
+
+                { success: true, bins: bins, curve: curve }
+              end
+
+              private
+
+              def monitoring_engine
+                @monitoring_engine ||= Helpers::MonitoringEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/metacognitive_monitoring/version'
+require 'legion/extensions/agentic/self/metacognitive_monitoring/helpers/constants'
+require 'legion/extensions/agentic/self/metacognitive_monitoring/helpers/monitoring_judgment'
+require 'legion/extensions/agentic/self/metacognitive_monitoring/helpers/calibration_tracker'
+require 'legion/extensions/agentic/self/metacognitive_monitoring/helpers/monitoring_engine'
+require 'legion/extensions/agentic/self/metacognitive_monitoring/runners/metacognitive_monitoring'
+require 'legion/extensions/agentic/self/metacognitive_monitoring/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/narrative_arc/helpers/constants'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/beat_event'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/arc'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/arc_engine'
+require 'legion/extensions/agentic/self/narrative_arc/runners/narrative'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+          class Client
+            include Runners::Narrative
+
+            def initialize(**)
+              @arc_engine = Helpers::ArcEngine.new
+            end
+
+            private
+
+            attr_reader :arc_engine
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_arc/helpers/arc.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+          module Helpers
+            class Arc
+              attr_reader :arc_id, :title, :domain, :beats, :arc_phase, :tension_level,
+                          :created_at, :resolved_at
+
+              def initialize(title:, domain: :general, initial_tension: Constants::DEFAULT_TENSION)
+                @arc_id       = SecureRandom.uuid
+                @title        = title
+                @domain       = domain
+                @beats        = []
+                @arc_phase    = :building
+                @tension_level = initial_tension.clamp(0.0, 1.0)
+                @created_at   = Time.now.utc
+                @resolved_at  = nil
+              end
+
+              def add_beat!(beat)
+                return false if @beats.size >= Constants::MAX_BEATS_PER_ARC
+                return false if complete?
+
+                @beats << beat
+                adjust_tension_for_beat(beat)
+                advance_phase!
+                true
+              end
+
+              def advance_phase!
+                new_phase = detect_phase
+                @arc_phase = new_phase if new_phase != @arc_phase
+                @resolved_at = Time.now.utc if @arc_phase == :complete
+                @arc_phase
+              end
+
+              def tension_rise!(amount = Constants::TENSION_RISE)
+                @tension_level = (@tension_level + amount).round(10).clamp(0.0, 1.0)
+              end
+
+              def tension_fall!(amount = Constants::TENSION_FALL)
+                @tension_level = (@tension_level - amount).round(10).clamp(0.0, 1.0)
+              end
+
+              def climaxed?
+                @tension_level >= Constants::CLIMAX_THRESHOLD || @arc_phase == :peak
+              end
+
+              def resolved?
+                @arc_phase == :complete
+              end
+
+              def complete?
+                @arc_phase == :complete
+              end
+
+              def dramatic_score
+                return 0.0 if @beats.empty?
+
+                tension_contrib = @tension_level * 0.4
+                beat_count_contrib = [@beats.size.to_f / Constants::MAX_BEATS_PER_ARC, 1.0].min * 0.3
+                intensity_contrib = average_beat_intensity * 0.3
+                (tension_contrib + beat_count_contrib + intensity_contrib).round(10)
+              end
+
+              def tension_label
+                Constants.label_for(Constants::TENSION_LABELS, @tension_level)
+              end
+
+              def drama_label
+                Constants.label_for(Constants::DRAMA_LABELS, dramatic_score)
+              end
+
+              def to_h
+                {
+                  arc_id:         @arc_id,
+                  title:          @title,
+                  domain:         @domain,
+                  arc_phase:      @arc_phase,
+                  tension_level:  @tension_level,
+                  beat_count:     @beats.size,
+                  dramatic_score: dramatic_score,
+                  tension_label:  tension_label,
+                  drama_label:    drama_label,
+                  created_at:     @created_at,
+                  resolved_at:    @resolved_at
+                }
+              end
+
+              private
+
+              def average_beat_intensity
+                return 0.0 if @beats.empty?
+
+                @beats.sum(&:intensity) / @beats.size.to_f
+              end
+
+              def adjust_tension_for_beat(beat)
+                case beat.beat_type
+                when :rising_action, :complication, :crisis
+                  tension_rise!(beat.intensity * Constants::TENSION_RISE)
+                when :climax
+                  @tension_level = [@tension_level, Constants::CLIMAX_THRESHOLD].max.clamp(0.0, 1.0)
+                when :falling_action, :resolution, :denouement
+                  tension_fall!(beat.intensity * Constants::TENSION_FALL)
+                end
+              end
+
+              def detect_phase
+                return :complete if resolution_beat?
+                return :resolving if climax_beat? && @tension_level < Constants::CLIMAX_THRESHOLD
+                return :peak if @tension_level >= Constants::CLIMAX_THRESHOLD
+                return :building if @tension_level < Constants::CLIMAX_THRESHOLD
+
+                @arc_phase
+              end
+
+              def climax_beat?
+                @beats.any?(&:climactic?)
+              end
+
+              def resolution_beat?
+                @beats.any? { |b| %i[resolution denouement].include?(b.beat_type) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end