lex-agentic-self 0.1.0

data/spec/legion/extensions/agentic/self/narrative_identity/helpers/narrative_engine_spec.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::NarrativeEngine do
+  let(:engine) { described_class.new }
+
+  def add_ep(content: 'test event', type: :achievement, valence: 0.5, sig: 0.5, domain: 'test')
+    engine.add_episode(
+      content:           content,
+      episode_type:      type,
+      emotional_valence: valence,
+      significance:      sig,
+      domain:            domain
+    )
+  end
+
+  describe '#add_episode' do
+    it 'creates and stores an episode' do
+      ep = add_ep
+      expect(engine.episodes[ep.id]).to eq(ep)
+    end
+
+    it 'returns an Episode object' do
+      expect(add_ep).to be_a(Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Episode)
+    end
+
+    it 'increments episode count' do
+      3.times { add_ep }
+      expect(engine.episodes.size).to eq(3)
+    end
+
+    it 'prunes oldest episode when MAX_EPISODES reached' do
+      max = Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Constants::MAX_EPISODES
+      first_ep = add_ep(content: 'oldest')
+      (max - 1).times { |i| add_ep(content: "ep #{i}") }
+      expect(engine.episodes.size).to eq(max)
+      add_ep(content: 'newest overflow')
+      expect(engine.episodes.size).to eq(max)
+      expect(engine.episodes.key?(first_ep.id)).to be false
+    end
+  end
+
+  describe '#create_chapter' do
+    it 'creates and stores a chapter' do
+      ch = engine.create_chapter(title: 'Act One', label: :origin)
+      expect(engine.chapters[ch.id]).to eq(ch)
+    end
+
+    it 'returns a Chapter object' do
+      expect(engine.create_chapter(title: 'x', label: :growth)).to be_a(
+        Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Chapter
+      )
+    end
+  end
+
+  describe '#assign_to_chapter' do
+    it 'assigns episode to chapter bidirectionally' do
+      ep = add_ep
+      ch = engine.create_chapter(title: 'Act One', label: :origin)
+      result = engine.assign_to_chapter(episode_id: ep.id, chapter_id: ch.id)
+      expect(result).to be true
+      expect(ep.chapter_id).to eq(ch.id)
+      expect(ch.episode_ids).to include(ep.id)
+    end
+
+    it 'returns false for unknown episode' do
+      ch = engine.create_chapter(title: 'x', label: :current)
+      expect(engine.assign_to_chapter(episode_id: 'no-such', chapter_id: ch.id)).to be false
+    end
+
+    it 'returns false for unknown chapter' do
+      ep = add_ep
+      expect(engine.assign_to_chapter(episode_id: ep.id, chapter_id: 'no-such')).to be false
+    end
+
+    it 'does not duplicate episode_id in chapter' do
+      ep = add_ep
+      ch = engine.create_chapter(title: 'x', label: :current)
+      engine.assign_to_chapter(episode_id: ep.id, chapter_id: ch.id)
+      engine.assign_to_chapter(episode_id: ep.id, chapter_id: ch.id)
+      expect(ch.episode_ids.count(ep.id)).to eq(1)
+    end
+  end
+
+  describe '#close_chapter' do
+    it 'sets end_time on the chapter' do
+      ch = engine.create_chapter(title: 'x', label: :growth)
+      expect(ch.current?).to be true
+      result = engine.close_chapter(chapter_id: ch.id)
+      expect(result).to be true
+      expect(ch.current?).to be false
+      expect(ch.end_time).to be_a(Time)
+    end
+
+    it 'returns false for unknown chapter' do
+      expect(engine.close_chapter(chapter_id: 'missing')).to be false
+    end
+  end
+
+  describe '#add_theme' do
+    it 'creates and stores a theme' do
+      t = engine.add_theme(name: 'resilience', theme_type: :growth)
+      expect(engine.themes[t.id]).to eq(t)
+    end
+
+    it 'returns a Theme object' do
+      expect(engine.add_theme(name: 'x', theme_type: :agency)).to be_a(
+        Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Theme
+      )
+    end
+  end
+
+  describe '#link_theme' do
+    it 'links theme to episode bidirectionally' do
+      ep = add_ep
+      t  = engine.add_theme(name: 'growth', theme_type: :growth)
+      result = engine.link_theme(episode_id: ep.id, theme_id: t.id)
+      expect(result).to be true
+      expect(ep.themes).to include(t.id)
+      expect(t.episode_ids).to include(ep.id)
+    end
+
+    it 'returns false for unknown episode' do
+      t = engine.add_theme(name: 'x', theme_type: :agency)
+      expect(engine.link_theme(episode_id: 'no-ep', theme_id: t.id)).to be false
+    end
+
+    it 'returns false for unknown theme' do
+      ep = add_ep
+      expect(engine.link_theme(episode_id: ep.id, theme_id: 'no-theme')).to be false
+    end
+
+    it 'does not duplicate theme_id on episode' do
+      ep = add_ep
+      t  = engine.add_theme(name: 'x', theme_type: :growth)
+      engine.link_theme(episode_id: ep.id, theme_id: t.id)
+      engine.link_theme(episode_id: ep.id, theme_id: t.id)
+      expect(ep.themes.count(t.id)).to eq(1)
+    end
+  end
+
+  describe '#reinforce_theme' do
+    it 'increases theme strength' do
+      t = engine.add_theme(name: 'courage', theme_type: :agency)
+      expect { engine.reinforce_theme(theme_id: t.id, amount: 0.3) }
+        .to change { t.strength }.by(0.3)
+    end
+
+    it 'returns false for unknown theme' do
+      expect(engine.reinforce_theme(theme_id: 'ghost', amount: 0.1)).to be false
+    end
+  end
+
+  describe '#narrative_coherence' do
+    it 'returns 0.0 with no episodes' do
+      expect(engine.narrative_coherence).to eq(0.0)
+    end
+
+    it 'returns 0.0 with no themes' do
+      add_ep
+      expect(engine.narrative_coherence).to eq(0.0)
+    end
+
+    it 'returns > 0 when episodes are linked to themes' do
+      ep = add_ep
+      t  = engine.add_theme(name: 'x', theme_type: :growth)
+      engine.link_theme(episode_id: ep.id, theme_id: t.id)
+      engine.reinforce_theme(theme_id: t.id, amount: 0.7)
+      expect(engine.narrative_coherence).to be > 0.0
+    end
+
+    it 'returns a value between 0 and 1' do
+      5.times do
+        ep = add_ep
+        t  = engine.add_theme(name: "theme #{ep.id}", theme_type: :growth)
+        engine.link_theme(episode_id: ep.id, theme_id: t.id)
+        engine.reinforce_theme(theme_id: t.id, amount: 0.8)
+      end
+      score = engine.narrative_coherence
+      expect(score).to be >= 0.0
+      expect(score).to be <= 1.0
+    end
+  end
+
+  describe '#most_defining_episodes' do
+    it 'returns episodes sorted by significance descending' do
+      add_ep(sig: 0.3)
+      add_ep(sig: 0.9)
+      add_ep(sig: 0.5)
+      result = engine.most_defining_episodes(limit: 3)
+      sigs   = result.map(&:significance)
+      expect(sigs).to eq(sigs.sort.reverse)
+    end
+
+    it 'respects limit' do
+      5.times { add_ep(sig: rand) }
+      expect(engine.most_defining_episodes(limit: 3).size).to eq(3)
+    end
+
+    it 'returns fewer than limit when not enough episodes' do
+      2.times { add_ep }
+      expect(engine.most_defining_episodes(limit: 5).size).to eq(2)
+    end
+  end
+
+  describe '#prominent_themes' do
+    it 'returns only themes with strength >= 0.6' do
+      strong = engine.add_theme(name: 'strong', theme_type: :agency)
+      engine.reinforce_theme(theme_id: strong.id, amount: 0.7)
+      weak = engine.add_theme(name: 'weak', theme_type: :stability)
+      engine.reinforce_theme(theme_id: weak.id, amount: 0.3)
+      result = engine.prominent_themes
+      expect(result.map(&:id)).to include(strong.id)
+      expect(result.map(&:id)).not_to include(weak.id)
+    end
+
+    it 'returns empty array when no prominent themes' do
+      engine.add_theme(name: 'faint', theme_type: :stability)
+      expect(engine.prominent_themes).to eq([])
+    end
+  end
+
+  describe '#current_chapter' do
+    it 'returns nil when no chapters exist' do
+      expect(engine.current_chapter).to be_nil
+    end
+
+    it 'returns the chapter with no end_time' do
+      ch1 = engine.create_chapter(title: 'Past', label: :origin)
+      engine.close_chapter(chapter_id: ch1.id)
+      ch2 = engine.create_chapter(title: 'Now', label: :current)
+      expect(engine.current_chapter).to eq(ch2)
+    end
+  end
+
+  describe '#decay_all_themes!' do
+    it 'reduces strength on all themes' do
+      t1 = engine.add_theme(name: 'a', theme_type: :growth)
+      engine.reinforce_theme(theme_id: t1.id, amount: 0.5)
+      t2 = engine.add_theme(name: 'b', theme_type: :agency)
+      engine.reinforce_theme(theme_id: t2.id, amount: 0.8)
+      s1_before = t1.strength
+      s2_before = t2.strength
+      engine.decay_all_themes!
+      decay = Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Constants::COHERENCE_DECAY
+      expect(t1.strength).to be_within(0.001).of(s1_before - decay)
+      expect(t2.strength).to be_within(0.001).of(s2_before - decay)
+    end
+  end
+
+  describe '#identity_summary' do
+    it 'returns expected keys' do
+      summary = engine.identity_summary
+      expect(summary).to include(
+        :top_themes, :defining_episodes, :current_chapter,
+        :coherence, :coherence_label, :episode_count, :theme_count, :chapter_count
+      )
+    end
+
+    it 'coherence_label is a symbol' do
+      expect(engine.identity_summary[:coherence_label]).to be_a(Symbol)
+    end
+
+    it 'reflects episode count' do
+      3.times { add_ep }
+      expect(engine.identity_summary[:episode_count]).to eq(3)
+    end
+  end
+
+  describe '#life_story' do
+    it 'returns an array of chapter entries' do
+      ch = engine.create_chapter(title: 'Act I', label: :origin)
+      ep = add_ep
+      engine.assign_to_chapter(episode_id: ep.id, chapter_id: ch.id)
+      story = engine.life_story
+      expect(story).to be_an(Array)
+      expect(story.first[:chapter][:id]).to eq(ch.id)
+      expect(story.first[:episodes].map { |e| e[:id] }).to include(ep.id)
+    end
+
+    it 'returns empty array when no chapters' do
+      expect(engine.life_story).to eq([])
+    end
+  end
+
+  describe '#narrative_report' do
+    it 'returns expected top-level keys' do
+      report = engine.narrative_report
+      expect(report).to include(:identity_summary, :life_story, :narrative_state)
+    end
+
+    it 'narrative_state includes coherence' do
+      expect(engine.narrative_report[:narrative_state]).to include(:coherence, :coherence_label)
+    end
+  end
+
+  describe '#to_h' do
+    it 'serializes episodes, themes, and chapters' do
+      add_ep
+      engine.add_theme(name: 't', theme_type: :growth)
+      engine.create_chapter(title: 'ch', label: :current)
+      h = engine.to_h
+      expect(h[:episodes].size).to eq(1)
+      expect(h[:themes].size).to eq(1)
+      expect(h[:chapters].size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/self/narrative_identity/helpers/theme_spec.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Theme do
+  let(:theme) do
+    described_class.new(name: 'perseverance', theme_type: :growth, strength: 0.5)
+  end
+
+  describe '#initialize' do
+    it 'assigns an id' do
+      expect(theme.id).to be_a(String)
+      expect(theme.id.length).to eq(36)
+    end
+
+    it 'assigns name' do
+      expect(theme.name).to eq('perseverance')
+    end
+
+    it 'assigns theme_type' do
+      expect(theme.theme_type).to eq(:growth)
+    end
+
+    it 'assigns strength' do
+      expect(theme.strength).to eq(0.5)
+    end
+
+    it 'initializes episode_ids as empty array' do
+      expect(theme.episode_ids).to eq([])
+    end
+
+    it 'clamps strength above 1.0' do
+      t = described_class.new(name: 'x', theme_type: :agency, strength: 2.0)
+      expect(t.strength).to eq(1.0)
+    end
+
+    it 'clamps strength below 0.0' do
+      t = described_class.new(name: 'x', theme_type: :agency, strength: -0.5)
+      expect(t.strength).to eq(0.0)
+    end
+
+    it 'accepts an explicit id' do
+      t = described_class.new(name: 'x', theme_type: :growth, id: 'my-id')
+      expect(t.id).to eq('my-id')
+    end
+  end
+
+  describe '#reinforce!' do
+    it 'increases strength' do
+      theme.reinforce!(0.2)
+      expect(theme.strength).to eq(0.7)
+    end
+
+    it 'clamps at 1.0' do
+      theme.reinforce!(0.8)
+      expect(theme.strength).to eq(1.0)
+    end
+
+    it 'rounds to 10 decimal places' do
+      t = described_class.new(name: 'x', theme_type: :growth, strength: 0.1)
+      t.reinforce!(0.2)
+      expect(t.strength).to be_a(Float)
+      expect(t.strength).to be_within(0.0000000001).of(0.3)
+    end
+  end
+
+  describe '#decay!' do
+    it 'decreases strength by COHERENCE_DECAY' do
+      decay = Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::Constants::COHERENCE_DECAY
+      theme.decay!
+      expect(theme.strength).to be_within(0.0001).of(0.5 - decay)
+    end
+
+    it 'clamps at 0.0' do
+      weak = described_class.new(name: 'x', theme_type: :stability, strength: 0.005)
+      weak.decay!
+      expect(weak.strength).to eq(0.0)
+    end
+  end
+
+  describe '#prominent?' do
+    it 'returns true when strength >= 0.6' do
+      t = described_class.new(name: 'x', theme_type: :agency, strength: 0.6)
+      expect(t.prominent?).to be true
+    end
+
+    it 'returns false when strength < 0.6' do
+      expect(theme.prominent?).to be false
+    end
+
+    it 'returns true at exactly 0.6' do
+      t = described_class.new(name: 'x', theme_type: :agency, strength: 0.6)
+      expect(t.prominent?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all fields' do
+      h = theme.to_h
+      expect(h).to include(:id, :name, :theme_type, :strength, :episode_ids)
+    end
+
+    it 'returns a copy of episode_ids' do
+      h = theme.to_h
+      h[:episode_ids] << 'injected'
+      expect(theme.episode_ids).to be_empty
+    end
+  end
+end

data/spec/legion/extensions/agentic/self/narrative_identity/runners/narrative_identity_spec.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Self::NarrativeIdentity::Runners::NarrativeIdentity do
+  let(:engine) { Legion::Extensions::Agentic::Self::NarrativeIdentity::Helpers::NarrativeEngine.new }
+  let(:runner) { Object.new.extend(described_class) }
+
+  def record(content: 'did a thing', type: :achievement, valence: 0.5, sig: 0.6, domain: 'test')
+    runner.record_episode(
+      content:           content,
+      episode_type:      type,
+      emotional_valence: valence,
+      significance:      sig,
+      domain:            domain,
+      engine:            engine
+    )
+  end
+
+  describe '#record_episode' do
+    it 'returns success: true' do
+      expect(record[:success]).to be true
+    end
+
+    it 'returns episode hash' do
+      result = record
+      expect(result[:episode]).to include(:id, :content, :episode_type, :significance)
+    end
+
+    it 'rejects unknown episode_type' do
+      result = runner.record_episode(
+        content: 'x', episode_type: :bogus, emotional_valence: 0.0, significance: 0.5,
+        domain: 'd', engine: engine
+      )
+      expect(result[:success]).to be false
+      expect(result[:error]).to include('unknown episode_type')
+    end
+
+    it 'stores the episode in the engine' do
+      result = record
+      expect(engine.episodes.key?(result[:episode][:id])).to be true
+    end
+  end
+
+  describe '#create_chapter' do
+    it 'returns success: true' do
+      result = runner.create_chapter(title: 'Act I', label: :origin, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns chapter hash' do
+      result = runner.create_chapter(title: 'Act I', label: :growth, engine: engine)
+      expect(result[:chapter]).to include(:id, :title, :label)
+    end
+
+    it 'rejects unknown label' do
+      result = runner.create_chapter(title: 'bad', label: :invalid, engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:error]).to include('unknown chapter label')
+    end
+  end
+
+  describe '#close_chapter' do
+    it 'closes an existing chapter' do
+      created = runner.create_chapter(title: 'Past', label: :origin, engine: engine)
+      ch_id   = created[:chapter][:id]
+      result  = runner.close_chapter(chapter_id: ch_id, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns false for nonexistent chapter' do
+      result = runner.close_chapter(chapter_id: 'ghost-id', engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#assign_episode_to_chapter' do
+    it 'links episode to chapter' do
+      ep  = record
+      ch  = runner.create_chapter(title: 'Now', label: :current, engine: engine)
+      res = runner.assign_episode_to_chapter(
+        episode_id: ep[:episode][:id],
+        chapter_id: ch[:chapter][:id],
+        engine:     engine
+      )
+      expect(res[:success]).to be true
+    end
+
+    it 'returns false for unknown IDs' do
+      res = runner.assign_episode_to_chapter(
+        episode_id: 'no-ep', chapter_id: 'no-ch', engine: engine
+      )
+      expect(res[:success]).to be false
+    end
+  end
+
+  describe '#add_theme' do
+    it 'returns success: true' do
+      result = runner.add_theme(name: 'courage', theme_type: :growth, engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns theme hash' do
+      result = runner.add_theme(name: 'resilience', theme_type: :agency, engine: engine)
+      expect(result[:theme]).to include(:id, :name, :theme_type)
+    end
+
+    it 'rejects unknown theme_type' do
+      result = runner.add_theme(name: 'x', theme_type: :nonsense, engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:error]).to include('unknown theme_type')
+    end
+  end
+
+  describe '#link_theme' do
+    it 'links theme and episode' do
+      ep = record
+      t  = runner.add_theme(name: 'growth', theme_type: :growth, engine: engine)
+      r  = runner.link_theme(episode_id: ep[:episode][:id], theme_id: t[:theme][:id], engine: engine)
+      expect(r[:success]).to be true
+    end
+
+    it 'returns false for missing episode or theme' do
+      r = runner.link_theme(episode_id: 'no-ep', theme_id: 'no-t', engine: engine)
+      expect(r[:success]).to be false
+    end
+  end
+
+  describe '#reinforce_theme' do
+    it 'increases theme strength' do
+      t       = runner.add_theme(name: 'x', theme_type: :growth, engine: engine)
+      theme   = engine.themes[t[:theme][:id]]
+      before  = theme.strength
+      runner.reinforce_theme(theme_id: t[:theme][:id], amount: 0.3, engine: engine)
+      expect(theme.strength).to be > before
+    end
+
+    it 'returns false for unknown theme' do
+      r = runner.reinforce_theme(theme_id: 'ghost', amount: 0.1, engine: engine)
+      expect(r[:success]).to be false
+    end
+  end
+
+  describe '#narrative_coherence' do
+    it 'returns success: true with coherence value' do
+      result = runner.narrative_coherence(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:coherence]).to be_a(Float)
+    end
+  end
+
+  describe '#identity_summary' do
+    it 'returns success: true with summary' do
+      result = runner.identity_summary(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:summary]).to include(:episode_count, :theme_count)
+    end
+  end
+
+  describe '#life_story' do
+    it 'returns success: true with life_story array' do
+      result = runner.life_story(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:life_story]).to be_an(Array)
+    end
+  end
+
+  describe '#most_defining_episodes' do
+    it 'returns success: true with episodes array' do
+      result = runner.most_defining_episodes(limit: 3, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:episodes]).to be_an(Array)
+    end
+
+    it 'respects the limit' do
+      5.times { record }
+      result = runner.most_defining_episodes(limit: 3, engine: engine)
+      expect(result[:episodes].size).to be <= 3
+    end
+  end
+
+  describe '#prominent_themes' do
+    it 'returns success: true with themes array' do
+      result = runner.prominent_themes(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:themes]).to be_an(Array)
+    end
+  end
+
+  describe '#current_chapter' do
+    it 'returns success: true' do
+      result = runner.current_chapter(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns nil chapter when none exists' do
+      expect(runner.current_chapter(engine: engine)[:chapter]).to be_nil
+    end
+
+    it 'returns the open chapter' do
+      runner.create_chapter(title: 'Now', label: :current, engine: engine)
+      result = runner.current_chapter(engine: engine)
+      expect(result[:chapter]).not_to be_nil
+    end
+  end
+
+  describe '#decay_themes' do
+    it 'returns success: true' do
+      result = runner.decay_themes(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'applies decay to all themes' do
+      t = runner.add_theme(name: 'x', theme_type: :growth, engine: engine)
+      runner.reinforce_theme(theme_id: t[:theme][:id], amount: 0.5, engine: engine)
+      theme  = engine.themes[t[:theme][:id]]
+      before = theme.strength
+      runner.decay_themes(engine: engine)
+      expect(theme.strength).to be < before
+    end
+  end
+
+  describe '#narrative_report' do
+    it 'returns success: true with report' do
+      result = runner.narrative_report(engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:report]).to include(:identity_summary, :life_story, :narrative_state)
+    end
+  end
+
+  describe 'default engine memoization' do
+    it 'uses a shared default engine across calls when no engine injected' do
+      r = Object.new.extend(described_class)
+      r.record_episode(
+        content: 'event', episode_type: :achievement,
+        emotional_valence: 0.5, significance: 0.5, domain: 'd'
+      )
+      summary = r.identity_summary
+      expect(summary[:summary][:episode_count]).to eq(1)
+    end
+  end
+end