lex-reflection 0.1.1

data/lib/legion/extensions/reflection/helpers/reflection_store.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Reflection
+      module Helpers
+        class ReflectionStore
+          attr_reader :total_generated
+
+          def initialize
+            @reflections = {}
+            @total_generated = 0
+            @category_scores = Hash.new(1.0)
+          end
+
+          def store(reflection)
+            prune_oldest if @reflections.size >= Constants::MAX_REFLECTIONS
+            @reflections[reflection[:reflection_id]] = reflection
+            @total_generated += 1
+            reflection
+          end
+
+          def get(reflection_id)
+            @reflections[reflection_id]
+          end
+
+          def recent(limit: 10)
+            @reflections.values
+                        .sort_by { |r| r[:created_at] }
+                        .last(limit)
+                        .reverse
+          end
+
+          def by_category(category)
+            @reflections.values.select { |r| r[:category] == category }
+          end
+
+          def by_severity(severity)
+            @reflections.values.select { |r| r[:severity] == severity }
+          end
+
+          def mark_acted_on(reflection_id)
+            reflection = @reflections[reflection_id]
+            return nil unless reflection
+
+            @reflections[reflection_id] = reflection.merge(acted_on: true)
+          end
+
+          def unacted
+            @reflections.values.reject { |r| r[:acted_on] }
+          end
+
+          def count
+            @reflections.size
+          end
+
+          def severity_counts
+            counts = Hash.new(0)
+            @reflections.each_value { |r| counts[r[:severity]] += 1 }
+            counts
+          end
+
+          def category_counts
+            counts = Hash.new(0)
+            @reflections.each_value { |r| counts[r[:category]] += 1 }
+            counts
+          end
+
+          def update_category_score(category, score)
+            @category_scores[category] = score.clamp(0.0, 1.0)
+          end
+
+          def cognitive_health
+            total_weight = Constants::HEALTH_WEIGHTS.values.sum
+            weighted_sum = Constants::HEALTH_WEIGHTS.sum do |cat, weight|
+              @category_scores[cat] * weight
+            end
+            (weighted_sum / total_weight).round(3)
+          end
+
+          def category_score(category)
+            @category_scores[category]
+          end
+
+          private
+
+          def prune_oldest
+            oldest = @reflections.values.min_by { |r| r[:created_at] }
+            @reflections.delete(oldest[:reflection_id]) if oldest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/reflection/runners/reflection.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Reflection
+      module Runners
+        module Reflection
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def reflect(tick_results: {}, **)
+            @metric_history ||= []
+            @metric_history << tick_results
+            @metric_history = @metric_history.last(Helpers::Constants::METRIC_WINDOW_SIZE)
+
+            new_reflections = Helpers::Monitors.run_all(tick_results, @metric_history)
+            new_reflections.each { |r| reflection_store.store(r) }
+
+            update_category_scores(tick_results)
+
+            if Helpers::LlmEnhancer.available? && new_reflections.any?
+              health_scores = Helpers::Constants::CATEGORIES.to_h { |c| [c, reflection_store.category_score(c)] }
+              llm_result = Helpers::LlmEnhancer.enhance_reflection(
+                monitors_data: new_reflections,
+                health_scores: health_scores
+              )
+              if llm_result
+                new_reflections.each do |entry|
+                  enhanced = llm_result[:observations][entry[:category]]
+                  next unless enhanced
+
+                  entry[:observation] = enhanced
+                  entry[:source]      = :llm
+                end
+              end
+            end
+
+            Legion::Logging.debug "[reflection] generated #{new_reflections.size} reflections, health=#{reflection_store.cognitive_health}"
+
+            {
+              reflections_generated: new_reflections.size,
+              cognitive_health:      reflection_store.cognitive_health,
+              new_reflections:       new_reflections.map { |r| format_reflection(r) },
+              total_reflections:     reflection_store.count
+            }
+          end
+
+          def reflect_on_dream(dream_results: {}, **)
+            source     = :mechanical
+            reflection = nil
+
+            if Helpers::LlmEnhancer.available?
+              llm_result = Helpers::LlmEnhancer.reflect_on_dream(dream_results: dream_results)
+              if llm_result&.fetch(:reflection, nil)
+                reflection = llm_result[:reflection]
+                source     = :llm
+              end
+            end
+
+            reflection ||= build_mechanical_dream_reflection(dream_results)
+
+            Legion::Logging.debug "[reflection] dream reflection generated source=#{source}"
+            { reflection: reflection, source: source }
+          end
+
+          def cognitive_health(**)
+            health = reflection_store.cognitive_health
+            Legion::Logging.debug "[reflection] cognitive health: #{health}"
+            {
+              health:            health,
+              category_scores:   Helpers::Constants::CATEGORIES.to_h { |c| [c, reflection_store.category_score(c)] },
+              unacted_count:     reflection_store.unacted.size,
+              critical_count:    reflection_store.by_severity(:critical).size,
+              significant_count: reflection_store.by_severity(:significant).size
+            }
+          end
+
+          def recent_reflections(limit: 10, **)
+            reflections = reflection_store.recent(limit: limit)
+            { reflections: reflections.map { |r| format_reflection(r) } }
+          end
+
+          def reflections_by_category(category:, **)
+            cat = category.to_sym
+            reflections = reflection_store.by_category(cat)
+            { category: cat, reflections: reflections.map { |r| format_reflection(r) } }
+          end
+
+          def adapt(reflection_id:, **)
+            reflection = reflection_store.get(reflection_id)
+            return { error: :not_found } unless reflection
+            return { error: :already_acted } if reflection[:acted_on]
+
+            reflection_store.mark_acted_on(reflection_id)
+            Legion::Logging.info "[reflection] adapted: #{reflection[:observation]}"
+            { adapted: true, reflection_id: reflection_id, recommendation: reflection[:recommendation] }
+          end
+
+          def reflection_stats(**)
+            {
+              total_generated:  reflection_store.total_generated,
+              current_count:    reflection_store.count,
+              cognitive_health: reflection_store.cognitive_health,
+              severity_counts:  reflection_store.severity_counts,
+              category_counts:  reflection_store.category_counts,
+              unacted:          reflection_store.unacted.size
+            }
+          end
+
+          private
+
+          def build_mechanical_dream_reflection(dream_results)
+            return 'Dream cycle completed.' unless dream_results.is_a?(Hash) && dream_results.any?
+
+            parts = []
+            if (audit = dream_results[:memory_audit]).is_a?(Hash)
+              parts << "Memory audit: #{audit[:decayed] || 0} traces decayed, #{audit[:unresolved_count] || 0} unresolved."
+            end
+            if (contra = dream_results[:contradiction_resolution]).is_a?(Hash)
+              parts << "Contradictions: #{contra[:detected] || 0} detected, #{contra[:resolved] || 0} resolved."
+            end
+            if (agenda = dream_results[:agenda_formation]).is_a?(Hash)
+              parts << "Agenda formed with #{agenda[:agenda_items] || 0} items."
+            end
+            parts.empty? ? 'Dream cycle completed.' : parts.join(' ')
+          end
+
+          def reflection_store
+            @reflection_store ||= Helpers::ReflectionStore.new
+          end
+
+          def format_reflection(reflection)
+            {
+              reflection_id:  reflection[:reflection_id],
+              category:       reflection[:category],
+              observation:    reflection[:observation],
+              severity:       reflection[:severity],
+              recommendation: reflection[:recommendation],
+              acted_on:       reflection[:acted_on],
+              created_at:     reflection[:created_at]
+            }
+          end
+
+          def update_category_scores(tick_results)
+            update_prediction_score(tick_results)
+            update_curiosity_score(tick_results)
+            update_emotion_score(tick_results)
+            update_memory_score(tick_results)
+            update_load_score(tick_results)
+          end
+
+          def update_prediction_score(tick_results)
+            prediction = tick_results[:prediction_engine]
+            return unless prediction.is_a?(Hash) && prediction[:confidence].is_a?(Numeric)
+
+            reflection_store.update_category_score(:prediction_calibration, prediction[:confidence])
+          end
+
+          def update_curiosity_score(tick_results)
+            curiosity = tick_results[:working_memory_integration]
+            return unless curiosity.is_a?(Hash) && curiosity[:curiosity_intensity].is_a?(Numeric)
+
+            score = 1.0 - ([curiosity[:curiosity_intensity], 1.0].min * 0.3)
+            reflection_store.update_category_score(:curiosity_effectiveness, score)
+          end
+
+          def update_emotion_score(tick_results)
+            emotion = tick_results[:emotional_evaluation]
+            stability = emotion.is_a?(Hash) ? (emotion[:stability] || emotion.dig(:momentum, :stability)) : nil
+            return unless stability.is_a?(Numeric)
+
+            reflection_store.update_category_score(:emotional_stability, stability)
+          end
+
+          def update_memory_score(tick_results)
+            memory = tick_results[:memory_consolidation]
+            return unless memory.is_a?(Hash) && memory[:total].is_a?(Numeric) && memory[:total].positive?
+
+            ratio = (memory[:pruned] || 0).to_f / memory[:total]
+            reflection_store.update_category_score(:memory_health, 1.0 - ratio)
+          end
+
+          def update_load_score(tick_results)
+            elapsed = tick_results[:elapsed]
+            budget = tick_results[:budget]
+            return unless elapsed.is_a?(Numeric) && budget.is_a?(Numeric) && budget.positive?
+
+            utilization = elapsed / budget
+            reflection_store.update_category_score(:cognitive_load, [1.0 - utilization, 0.0].max)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/reflection/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Reflection
+      VERSION = '0.1.1'
+    end
+  end
+end

data/lib/legion/extensions/reflection.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/reflection/version'
+require 'legion/extensions/reflection/helpers/constants'
+require 'legion/extensions/reflection/helpers/reflection'
+require 'legion/extensions/reflection/helpers/reflection_store'
+require 'legion/extensions/reflection/helpers/monitors'
+require 'legion/extensions/reflection/helpers/llm_enhancer'
+require 'legion/extensions/reflection/runners/reflection'
+require 'legion/extensions/reflection/client'
+
+module Legion
+  module Extensions
+    module Reflection
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/reflection/client_spec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Reflection::Client do
+  subject(:client) { described_class.new }
+
+  it 'initializes with a default reflection store' do
+    expect(client.reflection_store).to be_a(Legion::Extensions::Reflection::Helpers::ReflectionStore)
+  end
+
+  it 'accepts an injected store' do
+    custom = Legion::Extensions::Reflection::Helpers::ReflectionStore.new
+    client = described_class.new(store: custom)
+    expect(client.reflection_store).to be(custom)
+  end
+
+  it 'includes the Reflection runner' do
+    expect(client).to respond_to(:reflect)
+    expect(client).to respond_to(:cognitive_health)
+    expect(client).to respond_to(:recent_reflections)
+    expect(client).to respond_to(:reflections_by_category)
+    expect(client).to respond_to(:adapt)
+    expect(client).to respond_to(:reflection_stats)
+  end
+end

data/spec/legion/extensions/reflection/helpers/llm_enhancer_spec.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Reflection::Helpers::LlmEnhancer do
+  describe '.available?' do
+    context 'when Legion::LLM is not defined' do
+      it 'returns a falsy value' do
+        # Legion::LLM is not defined in the test environment
+        expect(described_class.available?).to be_falsy
+      end
+    end
+
+    context 'when Legion::LLM is defined but not started' do
+      before do
+        stub_const('Legion::LLM', double(respond_to?: true, started?: false))
+      end
+
+      it 'returns false' do
+        expect(described_class.available?).to be false
+      end
+    end
+
+    context 'when Legion::LLM is started' do
+      before do
+        stub_const('Legion::LLM', double(respond_to?: true, started?: true))
+      end
+
+      it 'returns true' do
+        expect(described_class.available?).to be true
+      end
+    end
+
+    context 'when an error is raised' do
+      before do
+        stub_const('Legion::LLM', double)
+        allow(Legion::LLM).to receive(:respond_to?).and_raise(StandardError)
+      end
+
+      it 'returns false' do
+        expect(described_class.available?).to be false
+      end
+    end
+  end
+
+  describe '.enhance_reflection' do
+    let(:fake_response) do
+      double(content: <<~TEXT)
+        EMOTION: My arousal is elevated at 0.7 while stability holds at 0.8, suggesting urgency without destabilization.
+        PREDICTION: Confidence at 65% with a declining trend and 3 pending predictions signals I am losing ground in forward modeling.
+        MEMORY: Memory health appears nominal with no concerning decay patterns detected this cycle.
+        TRUST: Trust scores remain stable with no significant drift observed.
+        CURIOSITY: Curiosity intensity is moderate; resolution rates suggest effective exploration.
+        IDENTITY: Identity entropy is within expected bounds; no drift detected.
+      TEXT
+    end
+    let(:fake_chat) { double }
+    let(:monitors_data) do
+      [
+        {
+          category:       :emotional_stability,
+          observation:    'original',
+          severity:       :notable,
+          metrics:        { stability: 0.8 },
+          recommendation: :no_action
+        },
+        {
+          category:       :prediction_calibration,
+          observation:    'original',
+          severity:       :notable,
+          metrics:        { confidence: 0.65 },
+          recommendation: :increase_curiosity
+        }
+      ]
+    end
+    let(:health_scores) do
+      {
+        prediction_calibration:  0.65,
+        curiosity_effectiveness: 0.8,
+        emotional_stability:     0.8,
+        trust_drift:             1.0,
+        memory_health:           0.95,
+        cognitive_load:          0.9,
+        mode_patterns:           1.0
+      }
+    end
+
+    before do
+      stub_const('Legion::LLM', double)
+      allow(Legion::LLM).to receive(:chat).and_return(fake_chat)
+      allow(fake_chat).to receive(:with_instructions)
+      allow(fake_chat).to receive(:ask).and_return(fake_response)
+    end
+
+    it 'returns observations hash with at least some categories' do
+      result = described_class.enhance_reflection(
+        monitors_data: monitors_data,
+        health_scores: health_scores
+      )
+      expect(result).to be_a(Hash)
+      expect(result[:observations]).to be_a(Hash)
+      expect(result[:observations]).not_to be_empty
+    end
+
+    it 'parses per-category observation text' do
+      result = described_class.enhance_reflection(
+        monitors_data: monitors_data,
+        health_scores: health_scores
+      )
+      expect(result[:observations][:emotional_stability]).to include('arousal')
+      expect(result[:observations][:prediction_calibration]).to include('Confidence')
+    end
+
+    context 'when LLM returns nil content' do
+      before { allow(fake_chat).to receive(:ask).and_return(double(content: nil)) }
+
+      it 'returns nil' do
+        result = described_class.enhance_reflection(
+          monitors_data: monitors_data,
+          health_scores: health_scores
+        )
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when LLM raises an error' do
+      before { allow(fake_chat).to receive(:ask).and_raise(StandardError, 'LLM timeout') }
+
+      it 'returns nil and logs a warning' do
+        expect(Legion::Logging).to receive(:warn).with(/enhance_reflection failed/)
+        result = described_class.enhance_reflection(
+          monitors_data: monitors_data,
+          health_scores: health_scores
+        )
+        expect(result).to be_nil
+      end
+    end
+  end
+
+  describe '.reflect_on_dream' do
+    let(:fake_response) do
+      double(content: <<~TEXT)
+        REFLECTION: The dream cycle surfaced 3 unresolved traces and resolved 1 contradiction. Memory consolidation is progressing normally with agenda items focused on identity coherence.
+      TEXT
+    end
+    let(:fake_chat) { double }
+    let(:dream_results) do
+      {
+        memory_audit:             { decayed: 5, pruned: 2, unresolved_count: 3 },
+        contradiction_resolution: { detected: 2, resolved: 1 },
+        agenda_formation:         { agenda_items: 4 }
+      }
+    end
+
+    before do
+      stub_const('Legion::LLM', double)
+      allow(Legion::LLM).to receive(:chat).and_return(fake_chat)
+      allow(fake_chat).to receive(:with_instructions)
+      allow(fake_chat).to receive(:ask).and_return(fake_response)
+    end
+
+    it 'returns a reflection string' do
+      result = described_class.reflect_on_dream(dream_results: dream_results)
+      expect(result).to be_a(Hash)
+      expect(result[:reflection]).to be_a(String)
+      expect(result[:reflection]).not_to be_empty
+    end
+
+    it 'includes dream cycle content in the reflection' do
+      result = described_class.reflect_on_dream(dream_results: dream_results)
+      expect(result[:reflection]).to include('unresolved traces')
+    end
+
+    context 'when LLM returns nil content' do
+      before { allow(fake_chat).to receive(:ask).and_return(double(content: nil)) }
+
+      it 'returns nil' do
+        result = described_class.reflect_on_dream(dream_results: dream_results)
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when LLM raises an error' do
+      before { allow(fake_chat).to receive(:ask).and_raise(StandardError, 'model error') }
+
+      it 'returns nil and logs a warning' do
+        expect(Legion::Logging).to receive(:warn).with(/reflect_on_dream failed/)
+        result = described_class.reflect_on_dream(dream_results: dream_results)
+        expect(result).to be_nil
+      end
+    end
+  end
+end

data/spec/legion/extensions/reflection/helpers/monitors_spec.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Reflection::Helpers::Monitors do
+  describe '.monitor_predictions' do
+    it 'generates reflection for low confidence' do
+      results = described_class.monitor_predictions(
+        { prediction_engine: { confidence: 0.2 } },
+        []
+      )
+      expect(results.size).to be >= 1
+      expect(results.first[:category]).to eq(:prediction_calibration)
+      expect(results.first[:recommendation]).to eq(:increase_curiosity)
+    end
+
+    it 'returns empty for good confidence' do
+      results = described_class.monitor_predictions(
+        { prediction_engine: { confidence: 0.9 } },
+        []
+      )
+      expect(results).to be_empty
+    end
+
+    it 'detects accuracy trend drop' do
+      history = Array.new(5) { { prediction_engine: { confidence: 0.9 } } } +
+                Array.new(5) { { prediction_engine: { confidence: 0.5 } } }
+
+      results = described_class.monitor_predictions(
+        { prediction_engine: { confidence: 0.5 } },
+        history
+      )
+      trend = results.find { |r| r[:metrics][:trend_drop] }
+      expect(trend).not_to be_nil
+    end
+  end
+
+  describe '.monitor_curiosity' do
+    it 'generates reflection for low resolution rate' do
+      results = described_class.monitor_curiosity(
+        working_memory_integration: { resolution_rate: 0.1 }
+      )
+      expect(results.size).to eq(1)
+      expect(results.first[:recommendation]).to eq(:decrease_curiosity)
+    end
+
+    it 'celebrates high resolution rate' do
+      results = described_class.monitor_curiosity(
+        working_memory_integration: { resolution_rate: 0.9 }
+      )
+      expect(results.size).to eq(1)
+      expect(results.first[:recommendation]).to eq(:celebrate_success)
+    end
+  end
+
+  describe '.monitor_emotions' do
+    it 'generates reflection for instability' do
+      results = described_class.monitor_emotions(
+        emotional_evaluation: { stability: 0.1 }
+      )
+      expect(results.size).to eq(1)
+      expect(results.first[:category]).to eq(:emotional_stability)
+      expect(results.first[:severity]).to eq(:significant)
+    end
+
+    it 'detects emotional flatness' do
+      results = described_class.monitor_emotions(
+        emotional_evaluation: { stability: 0.99 }
+      )
+      expect(results.size).to eq(1)
+      expect(results.first[:observation]).to include('flat')
+    end
+  end
+
+  describe '.monitor_memory' do
+    it 'generates reflection for high decay ratio' do
+      results = described_class.monitor_memory(
+        memory_consolidation: { pruned: 90, total: 100 }
+      )
+      expect(results.size).to eq(1)
+      expect(results.first[:recommendation]).to eq(:consolidate_memory)
+    end
+
+    it 'returns empty for healthy memory' do
+      results = described_class.monitor_memory(
+        memory_consolidation: { pruned: 5, total: 100 }
+      )
+      expect(results).to be_empty
+    end
+  end
+
+  describe '.monitor_cognitive_load' do
+    it 'generates reflection when near budget' do
+      results = described_class.monitor_cognitive_load(
+        elapsed: 4.8, budget: 5.0
+      )
+      expect(results.size).to eq(1)
+      expect(results.first[:category]).to eq(:cognitive_load)
+    end
+
+    it 'returns empty when within budget' do
+      results = described_class.monitor_cognitive_load(
+        elapsed: 1.0, budget: 5.0
+      )
+      expect(results).to be_empty
+    end
+  end
+
+  describe '.run_all' do
+    it 'aggregates results from all monitors' do
+      tick_results = {
+        prediction_engine:    { confidence: 0.2 },
+        emotional_evaluation: { stability: 0.1 },
+        memory_consolidation: { pruned: 90, total: 100 },
+        elapsed:              4.8,
+        budget:               5.0
+      }
+      results = described_class.run_all(tick_results, [])
+      expect(results.size).to be >= 3
+    end
+  end
+end