lex-agentic-self 0.1.0

data/lib/legion/extensions/agentic/self/metacognition/helpers/self_model.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Metacognition
+          module Helpers
+            module SelfModel
+              module_function
+
+              def build(subsystem_states: {}, tick_results: {})
+                loaded = discover_loaded_extensions
+                capabilities = map_capabilities(loaded)
+
+                {
+                  identity:     build_identity,
+                  architecture: build_architecture(loaded),
+                  capabilities: capabilities,
+                  subsystems:   build_subsystem_states(subsystem_states),
+                  cognitive:    build_cognitive_snapshot(tick_results),
+                  assembled_at: Time.now.utc
+                }
+              end
+
+              def extension_loaded?(ext_sym)
+                return true if Legion::Extensions.const_defined?(ext_sym, false)
+
+                agentic = Legion::Extensions.const_get(:Agentic, false)
+                agentic.constants(false).any? do |domain|
+                  ns = agentic.const_get(domain, false)
+                  ns.is_a?(Module) && ns.const_defined?(ext_sym, false)
+                end
+              rescue StandardError
+                false
+              end
+
+              def discover_loaded_extensions
+                Constants::EXTENSION_CAPABILITIES.each_with_object({}) do |(ext_sym, _cat), acc|
+                  acc[ext_sym] = { loaded: extension_loaded?(ext_sym) }
+                end
+              rescue StandardError
+                {}
+              end
+
+              def map_capabilities(loaded_map)
+                active = loaded_map.select { |_, v| v[:loaded] }
+                grouped = active.keys.group_by { |ext| Constants::EXTENSION_CAPABILITIES[ext] || :unknown }
+
+                Constants::CAPABILITY_CATEGORIES.to_h do |cat|
+                  extensions = grouped[cat] || []
+                  [cat, { active: extensions.size.positive?, extensions: extensions }]
+                end
+              end
+
+              def build_identity
+                {
+                  framework:  'LegionIO',
+                  role:       :cognitive_agent,
+                  model:      :brain_modeled,
+                  extensions: Constants::EXTENSION_CAPABILITIES.size
+                }
+              end
+
+              def build_architecture(loaded_map)
+                total = loaded_map.size
+                active = loaded_map.count { |_, v| v[:loaded] }
+
+                {
+                  total_extensions: total,
+                  loaded_count:     active,
+                  unloaded_count:   total - active,
+                  loaded:           loaded_map.select { |_, v| v[:loaded] }.keys,
+                  unloaded:         loaded_map.reject { |_, v| v[:loaded] }.keys
+                }
+              end
+
+              def build_subsystem_states(states)
+                return {} unless states.is_a?(Hash)
+
+                states.each_with_object({}) do |(key, state), acc|
+                  acc[key] = normalize_subsystem_state(state)
+                end
+              end
+
+              def normalize_subsystem_state(state)
+                return { status: :unknown } unless state.is_a?(Hash)
+
+                state.slice(:health, :status, :mode, :count, :active_count, :score)
+              end
+
+              def build_cognitive_snapshot(tick_results)
+                return { status: :no_tick_data } unless tick_results.is_a?(Hash) && !tick_results.empty?
+
+                {
+                  mode:           extract_mode(tick_results),
+                  phases_run:     tick_results.keys.size,
+                  has_reflection: tick_results.key?(:post_tick_reflection),
+                  health:         extract_health(tick_results),
+                  active_drives:  extract_drives(tick_results),
+                  attention:      extract_attention(tick_results),
+                  curiosity:      extract_curiosity(tick_results),
+                  prediction:     extract_prediction(tick_results)
+                }
+              end
+
+              def extract_mode(tick_results)
+                tick_results.dig(:tick_meta, :mode) || :unknown
+              end
+
+              def extract_health(tick_results)
+                reflection = tick_results[:post_tick_reflection]
+                return nil unless reflection.is_a?(Hash)
+
+                reflection[:cognitive_health]
+              end
+
+              def extract_drives(tick_results)
+                volition = tick_results[:action_selection]
+                return [] unless volition.is_a?(Hash) && volition[:intentions].is_a?(Array)
+
+                volition[:intentions].first(3).map { |i| i[:drive] }.compact
+              end
+
+              def extract_attention(tick_results)
+                attention = tick_results[:sensory_processing]
+                return nil unless attention.is_a?(Hash)
+
+                { spotlight: attention[:spotlight_count], total: attention[:total_signals] }
+              end
+
+              def extract_curiosity(tick_results)
+                curiosity = tick_results[:working_memory_integration]
+                return nil unless curiosity.is_a?(Hash)
+
+                { intensity: curiosity[:curiosity_intensity], open_wonders: curiosity[:open_wonders] }
+              end
+
+              def extract_prediction(tick_results)
+                prediction = tick_results[:prediction_engine]
+                return nil unless prediction.is_a?(Hash)
+
+                { confidence: prediction[:confidence], mode: prediction[:mode] }
+              end
+
+              def health_label(score)
+                return :unknown unless score.is_a?(Numeric)
+
+                Constants::HEALTH_LABELS.each do |range, label|
+                  return label if range.include?(score)
+                end
+                :unknown
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/metacognition/helpers/snapshot_store.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Metacognition
+          module Helpers
+            class SnapshotStore
+              attr_reader :snapshots
+
+              def initialize
+                @snapshots = []
+              end
+
+              def store(model)
+                @snapshots << model
+                @snapshots = @snapshots.last(Constants::MAX_SNAPSHOTS) if @snapshots.size > Constants::MAX_SNAPSHOTS
+                model
+              end
+
+              def latest
+                @snapshots.last
+              end
+
+              def stale?
+                return true if @snapshots.empty?
+
+                age = Time.now.utc - (latest[:assembled_at] || Time.at(0))
+                age > Constants::SNAPSHOT_TTL
+              end
+
+              def history(limit: 10)
+                @snapshots.last(limit)
+              end
+
+              def architecture_changes
+                return [] if @snapshots.size < 2
+
+                changes = []
+                @snapshots.each_cons(2) do |prev, curr|
+                  prev_loaded = prev.dig(:architecture, :loaded) || []
+                  curr_loaded = curr.dig(:architecture, :loaded) || []
+
+                  added = curr_loaded - prev_loaded
+                  removed = prev_loaded - curr_loaded
+
+                  next if added.empty? && removed.empty?
+
+                  changes << {
+                    at:      curr[:assembled_at],
+                    added:   added,
+                    removed: removed
+                  }
+                end
+                changes
+              end
+
+              def health_trend(limit: 20)
+                recent = @snapshots.last(limit)
+                recent.filter_map do |s|
+                  health = s.dig(:cognitive, :health)
+                  next unless health
+
+                  { at: s[:assembled_at], health: health }
+                end
+              end
+
+              def size
+                @snapshots.size
+              end
+
+              def clear
+                @snapshots.clear
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Metacognition
+          module Runners
+            module Metacognition
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def introspect(tick_results: {}, subsystem_states: {}, **)
+                model = if snapshot_store.stale?
+                          fresh = Helpers::SelfModel.build(
+                            subsystem_states: subsystem_states,
+                            tick_results:     tick_results
+                          )
+                          snapshot_store.store(fresh)
+                          fresh
+                        else
+                          snapshot_store.latest
+                        end
+
+                Legion::Logging.debug "[metacognition] introspect: #{model.dig(:architecture, :loaded_count)} extensions loaded"
+                model
+              end
+
+              def self_narrative(tick_results: {}, subsystem_states: {}, **)
+                model = introspect(tick_results: tick_results, subsystem_states: subsystem_states)
+                prose = Helpers::NarratorBridge.narrate_self_model(model)
+
+                {
+                  prose:     prose,
+                  health:    model.dig(:cognitive, :health),
+                  mode:      model.dig(:cognitive, :mode),
+                  model:     model,
+                  timestamp: Time.now.utc
+                }
+              end
+
+              def explain_subsystem(subsystem:, **)
+                sym = subsystem.to_sym
+                ext_sym = sym.to_s.split('_').map(&:capitalize).join.to_sym
+
+                loaded = Helpers::SelfModel.extension_loaded?(ext_sym)
+                category = Helpers::Constants::EXTENSION_CAPABILITIES[ext_sym] || :unknown
+
+                latest = snapshot_store.latest
+                state = latest&.dig(:subsystems, sym)
+
+                {
+                  subsystem: sym,
+                  extension: ext_sym,
+                  loaded:    loaded,
+                  category:  category,
+                  state:     state || { status: :no_data }
+                }
+              end
+
+              def architecture_overview(**)
+                model = snapshot_store.latest || Helpers::SelfModel.build
+                snapshot_store.store(model) if snapshot_store.stale?
+
+                {
+                  identity:     model[:identity],
+                  architecture: model[:architecture],
+                  capabilities: model[:capabilities],
+                  assembled_at: model[:assembled_at]
+                }
+              end
+
+              def health_trend(limit: 20, **)
+                {
+                  trend:     snapshot_store.health_trend(limit: limit),
+                  snapshots: snapshot_store.size,
+                  current:   snapshot_store.latest&.dig(:cognitive, :health)
+                }
+              end
+
+              def architecture_changes(**)
+                {
+                  changes:   snapshot_store.architecture_changes,
+                  snapshots: snapshot_store.size
+                }
+              end
+
+              def metacognition_stats(**)
+                {
+                  snapshots_stored:   snapshot_store.size,
+                  latest_stale:       snapshot_store.stale?,
+                  loaded_extensions:  snapshot_store.latest&.dig(:architecture, :loaded_count) || 0,
+                  cognitive_health:   snapshot_store.latest&.dig(:cognitive, :health),
+                  capability_summary: capability_summary
+                }
+              end
+
+              private
+
+              def snapshot_store
+                @snapshot_store ||= Helpers::SnapshotStore.new
+              end
+
+              def capability_summary
+                latest = snapshot_store.latest
+                return {} unless latest&.dig(:capabilities)
+
+                latest[:capabilities].transform_values { |v| v[:active] }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/metacognition/runners/registry.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Metacognition
+          module Runners
+            module Registry
+              extend self
+
+              def register_extension(name:, module_name:, category: 'cognition', **)
+                entry = build_entry(name: name, module_name: module_name, category: category, **)
+
+                if db_available?
+                  db_register(entry)
+                else
+                  store.register(entry)
+                end
+
+                Legion::Logging.info "[metacognition:registry] registered #{name} (#{category})" if defined?(Legion::Logging)
+                { success: true, name: name, category: category }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def deregister_extension(name:, **)
+                if db_available?
+                  db_deregister(name)
+                else
+                  store.deregister(name)
+                end
+                { success: true, name: name }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_extensions(status: nil, category: nil, **)
+                extensions = if db_available?
+                               db_list(status: status, category: category)
+                             else
+                               store.list(status: status, category: category)
+                             end
+                { success: true, extensions: extensions, count: extensions.size }
+              end
+
+              def extension_status(name:, **)
+                ext = if db_available?
+                        db_get(name)
+                      else
+                        store.get(name)
+                      end
+                return { success: false, error: :not_found } unless ext
+
+                { success: true, extension: ext }
+              end
+
+              def update_extension(name:, attrs: {}, **)
+                result = if db_available?
+                           db_update(name, attrs)
+                         else
+                           store.update(name, attrs)
+                         end
+                return { success: false, error: :not_found } unless result
+
+                { success: true, extension: result }
+              end
+
+              def category_distribution(**)
+                dist = if db_available?
+                         db_category_distribution
+                       else
+                         store.category_distribution
+                       end
+
+                total = dist.values.sum
+                percentages = dist.transform_values { |v| total.positive? ? (v.to_f / total * 100).round(1) : 0.0 }
+
+                { success: true, distribution: dist, percentages: percentages, total: total }
+              end
+
+              def degraded_extensions(threshold: 0.4, **)
+                extensions = if db_available?
+                               db_by_health(threshold)
+                             else
+                               store.by_health(threshold: threshold)
+                             end
+                { success: true, extensions: extensions, count: extensions.size }
+              end
+
+              def seed_from_constants(**)
+                capabilities = Helpers::Constants::EXTENSION_CAPABILITIES
+                seeded = 0
+
+                capabilities.each do |mod_name, category|
+                  snake = mod_name.to_s.gsub(/([A-Z])/, '_\1').sub(/^_/, '').downcase
+                  lex_name = "lex-#{snake.tr('_', '-')}"
+                  next if extension_status(name: lex_name)[:success]
+
+                  register_extension(
+                    name:        lex_name,
+                    module_name: mod_name.to_s,
+                    category:    category.to_s
+                  )
+                  seeded += 1
+                end
+
+                { success: true, seeded: seeded, total: capabilities.size }
+              end
+
+              private
+
+              def build_entry(name:, module_name:, category:, **opts)
+                {
+                  name:                 name,
+                  module_name:          module_name,
+                  category:             category.to_s,
+                  description:          opts[:description],
+                  cognitive_concept:    opts[:cognitive_concept],
+                  metaphor_description: opts[:metaphor_description],
+                  build_batch:          opts[:build_batch],
+                  build_date:           Time.now.utc,
+                  status:               'active',
+                  spec_count:           opts.fetch(:spec_count, 0),
+                  spec_pass_count:      opts.fetch(:spec_pass_count, 0)
+                }
+              end
+
+              def store
+                @store ||= Helpers::RegistryStore.new
+              end
+
+              def db_available?
+                defined?(Legion::Data) && Legion::Data.respond_to?(:connection) && Legion::Data.connection
+              rescue StandardError
+                false
+              end
+
+              def db_table
+                Legion::Data.connection[:extensions_registry]
+              end
+
+              def db_register(entry)
+                db_table.insert(entry.merge(created_at: Time.now.utc, updated_at: Time.now.utc))
+              end
+
+              def db_deregister(name)
+                db_table.where(name: name).delete
+              end
+
+              def db_get(name)
+                db_table.where(name: name).first
+              end
+
+              def db_list(status: nil, category: nil)
+                ds = db_table
+                ds = ds.where(status: status.to_s) if status
+                ds = ds.where(category: category.to_s) if category
+                ds.all
+              end
+
+              def db_update(name, attrs)
+                db_table.where(name: name).update(attrs.merge(updated_at: Time.now.utc))
+                db_get(name)
+              end
+
+              def db_category_distribution
+                db_table.group_and_count(:category).all.to_h { |r| [r[:category], r[:count]] }
+              end
+
+              def db_by_health(threshold)
+                db_table.where { health_score < threshold }.all
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/metacognition/version'
+require 'legion/extensions/agentic/self/metacognition/helpers/constants'
+require 'legion/extensions/agentic/self/metacognition/helpers/self_model'
+require 'legion/extensions/agentic/self/metacognition/helpers/snapshot_store'
+require 'legion/extensions/agentic/self/metacognition/helpers/narrator_bridge'
+require 'legion/extensions/agentic/self/metacognition/helpers/registry_store'
+require 'legion/extensions/agentic/self/metacognition/runners/metacognition'
+require 'legion/extensions/agentic/self/metacognition/runners/registry'
+require 'legion/extensions/agentic/self/metacognition/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module Metacognition
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/metacognitive_monitoring/runners/metacognitive_monitoring'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+          class Client
+            include Runners::MetacognitiveMonitoring
+
+            def initialize(engine: nil)
+              @monitoring_engine = engine || Helpers::MonitoringEngine.new
+            end
+
+            private
+
+            attr_reader :monitoring_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module MetacognitiveMonitoring
+          module Helpers
+            class CalibrationTracker
+              attr_reader :points
+
+              def initialize
+                @points = []
+              end
+
+              def add_point(predicted:, actual:)
+                @points << { predicted: predicted.clamp(0.0, 1.0), actual: actual.clamp(0.0, 1.0) }
+                @points.shift while @points.size > MAX_CALIBRATION_POINTS
+                self
+              end
+
+              def mean_calibration_error
+                return 0.0 if @points.empty?
+
+                errors = @points.map { |p| p[:predicted] - p[:actual] }
+                (errors.sum / errors.size).round(10)
+              end
+
+              def calibration_score
+                score = (1.0 - mean_calibration_error.abs).clamp(0.0, 1.0)
+                score.round(10)
+              end
+
+              def overconfident?
+                mean_calibration_error > OVERCONFIDENCE_THRESHOLD
+              end
+
+              def underconfident?
+                mean_calibration_error < UNDERCONFIDENCE_THRESHOLD
+              end
+
+              def calibration_label
+                score = calibration_score
+                CALIBRATION_LABELS.find { |range, _| range.cover?(score) }&.last
+              end
+
+              def calibration_curve(bins: 5)
+                return [] if @points.empty?
+
+                bin_size  = 1.0 / bins
+                bin_edges = bins.times.map { |i| (i * bin_size).round(10) }
+
+                bin_edges.map do |edge|
+                  upper = (edge + bin_size).round(10)
+                  range = (edge...upper)
+                  in_bin = @points.select { |p| range.cover?(p[:predicted]) }
+
+                  actual_mean = if in_bin.empty?
+                                  nil
+                                else
+                                  (in_bin.sum { |p| p[:actual] } / in_bin.size).round(10)
+                                end
+
+                  {
+                    predicted_range: range,
+                    sample_count:    in_bin.size,
+                    actual_accuracy: actual_mean
+                  }
+                end
+              end
+
+              def count
+                @points.size
+              end
+
+              def empty?
+                @points.empty?
+              end
+
+              def to_h
+                {
+                  count:                  count,
+                  mean_calibration_error: mean_calibration_error,
+                  calibration_score:      calibration_score,
+                  calibration_label:      calibration_label,
+                  overconfident:          overconfident?,
+                  underconfident:         underconfident?
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end