lex-agentic-language 0.1.0

data/spec/legion/extensions/agentic/language/narrative_reasoning/helpers/narrative_engine_spec.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::NarrativeEngine do
+  let(:engine) { described_class.new }
+
+  describe '#create_narrative' do
+    it 'creates a new narrative' do
+      narrative = engine.create_narrative(title: 'Test Story', domain: 'test')
+      expect(narrative).to be_a(Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::Narrative)
+      expect(narrative.title).to eq('Test Story')
+      expect(narrative.domain).to eq('test')
+    end
+
+    it 'stores the narrative' do
+      narrative = engine.create_narrative(title: 'Stored')
+      expect(engine.get(narrative.id)).to eq(narrative)
+    end
+
+    it 'increments count' do
+      engine.create_narrative(title: 'First')
+      engine.create_narrative(title: 'Second')
+      expect(engine.count).to eq(2)
+    end
+  end
+
+  describe '#add_narrative_event' do
+    let(:narrative) { engine.create_narrative(title: 'Events Test') }
+
+    it 'adds an event to the narrative' do
+      event = engine.add_narrative_event(
+        narrative_id: narrative.id,
+        content:      'Something happened',
+        event_type:   :action
+      )
+      expect(event).to be_a(Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::NarrativeEvent)
+      expect(narrative.events.size).to eq(1)
+    end
+
+    it 'returns nil for unknown narrative' do
+      result = engine.add_narrative_event(
+        narrative_id: 'no-such-id',
+        content:      'x',
+        event_type:   :action
+      )
+      expect(result).to be_nil
+    end
+
+    it 'returns nil for invalid event_type' do
+      result = engine.add_narrative_event(
+        narrative_id: narrative.id,
+        content:      'x',
+        event_type:   :invalid_type
+      )
+      expect(result).to be_nil
+    end
+
+    it 'tracks total_events count' do
+      engine.add_narrative_event(narrative_id: narrative.id, content: 'a', event_type: :action)
+      engine.add_narrative_event(narrative_id: narrative.id, content: 'b', event_type: :conflict)
+      expect(engine.total_events).to eq(2)
+    end
+
+    it 'accepts all valid event types' do
+      described_class::EVENT_TYPES.each do |type|
+        result = engine.add_narrative_event(narrative_id: narrative.id, content: 'x', event_type: type)
+        expect(result).not_to be_nil
+      end
+    end
+  end
+
+  describe '#add_narrative_theme' do
+    let(:narrative) { engine.create_narrative(title: 'Theme Test') }
+
+    it 'adds a theme to the narrative' do
+      engine.add_narrative_theme(narrative_id: narrative.id, theme: 'identity')
+      expect(narrative.themes).to include('identity')
+    end
+
+    it 'returns nil for unknown narrative' do
+      result = engine.add_narrative_theme(narrative_id: 'unknown', theme: 'x')
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#advance_narrative' do
+    let(:narrative) { engine.create_narrative(title: 'Arc Test') }
+
+    it 'advances arc stage' do
+      new_stage = engine.advance_narrative(narrative_id: narrative.id)
+      expect(new_stage).to eq(:rising_action)
+    end
+
+    it 'returns nil for unknown narrative' do
+      result = engine.advance_narrative(narrative_id: 'bad')
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#trace_causal_chain' do
+    let(:narrative) { engine.create_narrative(title: 'Causal Test') }
+
+    it 'returns empty array for narrative with no causes' do
+      engine.add_narrative_event(narrative_id: narrative.id, content: 'start', event_type: :action)
+      chain = engine.trace_causal_chain(narrative_id: narrative.id)
+      expect(chain).to be_empty
+    end
+
+    it 'returns causal links when events have causes' do
+      evt1 = engine.add_narrative_event(narrative_id: narrative.id, content: 'start', event_type: :action)
+      engine.add_narrative_event(
+        narrative_id: narrative.id,
+        content:      'consequence',
+        event_type:   :resolution,
+        causes:       [evt1.id]
+      )
+      chain = engine.trace_causal_chain(narrative_id: narrative.id)
+      expect(chain.size).to eq(1)
+    end
+
+    it 'returns empty array for unknown narrative' do
+      expect(engine.trace_causal_chain(narrative_id: 'nope')).to eq([])
+    end
+  end
+
+  describe '#complete_narratives' do
+    it 'returns narratives at resolution stage' do
+      n1 = engine.create_narrative(title: 'Finished')
+      5.times { n1.advance_arc! }
+      engine.create_narrative(title: 'In Progress')
+      expect(engine.complete_narratives).to include(n1)
+      expect(engine.complete_narratives.size).to eq(1)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'returns narratives matching domain' do
+      engine.create_narrative(title: 'A', domain: 'sci-fi')
+      engine.create_narrative(title: 'B', domain: 'sci-fi')
+      engine.create_narrative(title: 'C', domain: 'mystery')
+      expect(engine.by_domain(domain: 'sci-fi').size).to eq(2)
+    end
+  end
+
+  describe '#most_coherent' do
+    it 'returns narratives sorted by coherence descending' do
+      engine.create_narrative(title: 'Low')
+      high = engine.create_narrative(title: 'High')
+      5.times { high.add_event(Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::NarrativeEvent.new(content: 'x', event_type: :action)) }
+      result = engine.most_coherent(limit: 2)
+      expect(result.first).to eq(high)
+    end
+
+    it 'respects the limit' do
+      3.times { |i| engine.create_narrative(title: "N#{i}") }
+      expect(engine.most_coherent(limit: 2).size).to be <= 2
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces coherence of all narratives' do
+      n = engine.create_narrative(title: 'Decay Test')
+      before = n.coherence
+      engine.decay_all
+      expect(n.coherence).to be < before
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes count and narratives array' do
+      engine.create_narrative(title: 'One')
+      h = engine.to_h
+      expect(h[:count]).to eq(1)
+      expect(h[:narratives]).to be_an(Array)
+    end
+  end
+
+  describe 'EVENT_TYPES constant' do
+    it 'includes the five required types' do
+      expect(described_class::EVENT_TYPES).to include(:action, :discovery, :conflict, :resolution, :revelation)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/narrative_reasoning/helpers/narrative_event_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::NarrativeEvent do
+  let(:event) do
+    described_class.new(
+      content:    'The detective discovers the clue',
+      event_type: :discovery,
+      characters: %w[detective suspect],
+      causes:     [],
+      domain:     'mystery'
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(event.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores content' do
+      expect(event.content).to eq('The detective discovers the clue')
+    end
+
+    it 'stores event_type' do
+      expect(event.event_type).to eq(:discovery)
+    end
+
+    it 'stores characters as array' do
+      expect(event.characters).to contain_exactly('detective', 'suspect')
+    end
+
+    it 'stores causes' do
+      expect(event.causes).to eq([])
+    end
+
+    it 'stores domain' do
+      expect(event.domain).to eq('mystery')
+    end
+
+    it 'sets timestamp to now' do
+      expect(event.timestamp).to be_a(Time)
+    end
+
+    it 'accepts explicit id' do
+      custom = described_class.new(content: 'x', event_type: :action, id: 'custom-id')
+      expect(custom.id).to eq('custom-id')
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = event.to_h
+      expect(h[:id]).to eq(event.id)
+      expect(h[:content]).to eq('The detective discovers the clue')
+      expect(h[:event_type]).to eq(:discovery)
+      expect(h[:characters]).to eq(%w[detective suspect])
+      expect(h[:causes]).to eq([])
+      expect(h[:domain]).to eq('mystery')
+      expect(h[:timestamp]).to be_a(Time)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/narrative_reasoning/helpers/narrative_spec.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::Narrative do
+  let(:narrative) { described_class.new(title: 'The Journey', domain: 'adventure') }
+
+  let(:event1) do
+    Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::NarrativeEvent.new(
+      content:    'Hero leaves home',
+      event_type: :action,
+      characters: ['hero']
+    )
+  end
+
+  let(:event2) do
+    Legion::Extensions::Agentic::Language::NarrativeReasoning::Helpers::NarrativeEvent.new(
+      content:    'Hero discovers map',
+      event_type: :discovery,
+      characters: ['hero'],
+      causes:     [event1.id]
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns id, title, domain' do
+      expect(narrative.id).to match(/\A[0-9a-f-]{36}\z/)
+      expect(narrative.title).to eq('The Journey')
+      expect(narrative.domain).to eq('adventure')
+    end
+
+    it 'starts at beginning arc stage' do
+      expect(narrative.arc_stage).to eq(:beginning)
+    end
+
+    it 'starts with default coherence' do
+      expect(narrative.coherence).to eq(described_class::DEFAULT_COHERENCE)
+    end
+
+    it 'starts with empty events, characters, themes' do
+      expect(narrative.events).to be_empty
+      expect(narrative.characters).to be_empty
+      expect(narrative.themes).to be_empty
+    end
+  end
+
+  describe '#add_event' do
+    it 'appends the event' do
+      narrative.add_event(event1)
+      expect(narrative.events).to include(event1)
+    end
+
+    it 'collects unique characters' do
+      narrative.add_event(event1)
+      narrative.add_event(event2)
+      expect(narrative.characters).to contain_exactly('hero')
+    end
+
+    it 'boosts coherence on each event' do
+      initial = narrative.coherence
+      narrative.add_event(event1)
+      expect(narrative.coherence).to be > initial
+    end
+
+    it 'does not exceed coherence ceiling' do
+      15.times { narrative.add_event(event1) }
+      expect(narrative.coherence).to be <= described_class::COHERENCE_CEILING
+    end
+
+    it 'updates last_updated_at' do
+      before = narrative.last_updated_at
+      sleep(0.01)
+      narrative.add_event(event1)
+      expect(narrative.last_updated_at).to be >= before
+    end
+  end
+
+  describe '#add_theme' do
+    it 'adds a theme' do
+      narrative.add_theme('redemption')
+      expect(narrative.themes).to include('redemption')
+    end
+
+    it 'does not add duplicate themes' do
+      narrative.add_theme('redemption')
+      narrative.add_theme('redemption')
+      expect(narrative.themes.count('redemption')).to eq(1)
+    end
+  end
+
+  describe '#advance_arc!' do
+    it 'advances to next arc stage' do
+      narrative.advance_arc!
+      expect(narrative.arc_stage).to eq(:rising_action)
+    end
+
+    it 'does not advance past resolution' do
+      5.times { narrative.advance_arc! }
+      expect(narrative.arc_stage).to eq(:resolution)
+      narrative.advance_arc!
+      expect(narrative.arc_stage).to eq(:resolution)
+    end
+  end
+
+  describe '#causal_chain' do
+    it 'returns empty with no causes' do
+      narrative.add_event(event1)
+      expect(narrative.causal_chain).to be_empty
+    end
+
+    it 'returns cause->effect links' do
+      narrative.add_event(event1)
+      narrative.add_event(event2)
+      chain = narrative.causal_chain
+      expect(chain.size).to eq(1)
+      expect(chain.first[:cause][:id]).to eq(event1.id)
+      expect(chain.first[:effect][:id]).to eq(event2.id)
+    end
+  end
+
+  describe '#coherence_label' do
+    it 'returns :developing for default coherence' do
+      expect(narrative.coherence_label).to eq(:developing)
+    end
+
+    it 'returns :compelling for high coherence' do
+      10.times { narrative.add_event(event1) }
+      expect(narrative.coherence_label).to eq(:compelling)
+    end
+  end
+
+  describe '#complete?' do
+    it 'returns false at start' do
+      expect(narrative.complete?).to be false
+    end
+
+    it 'returns true at resolution' do
+      5.times { narrative.advance_arc! }
+      expect(narrative.complete?).to be true
+    end
+  end
+
+  describe '#decay_coherence' do
+    it 'reduces coherence by DECAY_RATE' do
+      before = narrative.coherence
+      narrative.decay_coherence
+      expect(narrative.coherence).to be_within(0.001).of(before - described_class::DECAY_RATE)
+    end
+
+    it 'does not go below coherence floor' do
+      200.times { narrative.decay_coherence }
+      expect(narrative.coherence).to eq(described_class::COHERENCE_FLOOR)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = narrative.to_h
+      expect(h).to include(:id, :title, :domain, :events, :characters, :themes,
+                           :arc_stage, :coherence, :coherence_label, :complete,
+                           :created_at, :last_updated_at)
+    end
+  end
+
+  describe 'ARC_STAGES constant' do
+    it 'contains the five expected stages in order' do
+      expect(described_class::ARC_STAGES).to eq(%i[beginning rising_action climax falling_action resolution])
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/narrative_reasoning/runners/narrative_reasoning_spec.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/narrative_reasoning/client'
+
+RSpec.describe Legion::Extensions::Agentic::Language::NarrativeReasoning::Runners::NarrativeReasoning do
+  let(:client) { Legion::Extensions::Agentic::Language::NarrativeReasoning::Client.new }
+
+  describe '#create_narrative' do
+    it 'returns success with narrative_id and title' do
+      result = client.create_narrative(title: 'My Story', domain: 'fantasy')
+      expect(result[:success]).to be true
+      expect(result[:narrative_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:title]).to eq('My Story')
+      expect(result[:arc_stage]).to eq(:beginning)
+    end
+  end
+
+  describe '#add_narrative_event' do
+    let(:narrative_id) { client.create_narrative(title: 'Event Test')[:narrative_id] }
+
+    it 'adds an event and returns event_id' do
+      result = client.add_narrative_event(
+        narrative_id: narrative_id,
+        content:      'Hero acts',
+        event_type:   :action,
+        characters:   ['hero']
+      )
+      expect(result[:success]).to be true
+      expect(result[:event_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns error for unknown narrative' do
+      result = client.add_narrative_event(narrative_id: 'bad', content: 'x', event_type: :action)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:narrative_not_found)
+    end
+
+    it 'returns error for invalid event_type' do
+      result = client.add_narrative_event(narrative_id: narrative_id, content: 'x', event_type: :bogus)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_event_type)
+    end
+  end
+
+  describe '#add_narrative_theme' do
+    let(:narrative_id) { client.create_narrative(title: 'Theme Test')[:narrative_id] }
+
+    it 'adds a theme successfully' do
+      result = client.add_narrative_theme(narrative_id: narrative_id, theme: 'courage')
+      expect(result[:success]).to be true
+      expect(result[:theme]).to eq('courage')
+    end
+
+    it 'returns error for unknown narrative' do
+      result = client.add_narrative_theme(narrative_id: 'nope', theme: 'x')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:narrative_not_found)
+    end
+  end
+
+  describe '#advance_narrative_arc' do
+    let(:narrative_id) { client.create_narrative(title: 'Arc Test')[:narrative_id] }
+
+    it 'advances to next arc stage' do
+      result = client.advance_narrative_arc(narrative_id: narrative_id)
+      expect(result[:success]).to be true
+      expect(result[:arc_stage]).to eq(:rising_action)
+    end
+
+    it 'returns error for unknown narrative' do
+      result = client.advance_narrative_arc(narrative_id: 'bad')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:narrative_not_found)
+    end
+  end
+
+  describe '#trace_narrative_causes' do
+    let(:narrative_id) { client.create_narrative(title: 'Causal Test')[:narrative_id] }
+
+    it 'returns empty chain with no causes' do
+      client.add_narrative_event(narrative_id: narrative_id, content: 'start', event_type: :action)
+      result = client.trace_narrative_causes(narrative_id: narrative_id)
+      expect(result[:success]).to be true
+      expect(result[:chain]).to eq([])
+      expect(result[:link_count]).to eq(0)
+    end
+
+    it 'returns causal links' do
+      evt = client.add_narrative_event(narrative_id: narrative_id, content: 'cause', event_type: :action)
+      client.add_narrative_event(
+        narrative_id: narrative_id,
+        content:      'effect',
+        event_type:   :resolution,
+        causes:       [evt[:event_id]]
+      )
+      result = client.trace_narrative_causes(narrative_id: narrative_id)
+      expect(result[:link_count]).to eq(1)
+    end
+
+    it 'returns error for unknown narrative' do
+      result = client.trace_narrative_causes(narrative_id: 'nope')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#complete_narratives' do
+    it 'returns empty list when none are complete' do
+      client.create_narrative(title: 'Incomplete')
+      result = client.complete_narratives
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'includes narratives that reached resolution' do
+      nid = client.create_narrative(title: 'Done')[:narrative_id]
+      5.times { client.advance_narrative_arc(narrative_id: nid) }
+      result = client.complete_narratives
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#domain_narratives' do
+    it 'filters by domain' do
+      client.create_narrative(title: 'A', domain: 'sci-fi')
+      client.create_narrative(title: 'B', domain: 'sci-fi')
+      client.create_narrative(title: 'C', domain: 'horror')
+      result = client.domain_narratives(domain: 'sci-fi')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#most_coherent_narratives' do
+    it 'returns up to limit narratives' do
+      3.times { |i| client.create_narrative(title: "N#{i}") }
+      result = client.most_coherent_narratives(limit: 2)
+      expect(result[:success]).to be true
+      expect(result[:narratives].size).to be <= 2
+    end
+
+    it 'clamps limit to minimum 1' do
+      client.create_narrative(title: 'Solo')
+      result = client.most_coherent_narratives(limit: 0)
+      expect(result[:narratives].size).to be >= 1
+    end
+  end
+
+  describe '#update_narrative_reasoning' do
+    it 'returns success with count of updated narratives' do
+      client.create_narrative(title: 'A')
+      client.create_narrative(title: 'B')
+      result = client.update_narrative_reasoning
+      expect(result[:success]).to be true
+      expect(result[:narratives_updated]).to eq(2)
+    end
+  end
+
+  describe '#narrative_reasoning_stats' do
+    it 'returns stats hash' do
+      client.create_narrative(title: 'Stats Test')
+      result = client.narrative_reasoning_stats
+      expect(result[:success]).to be true
+      expect(result[:total_narratives]).to eq(1)
+      expect(result[:total_events]).to be_a(Integer)
+      expect(result[:complete_narratives]).to be_a(Integer)
+    end
+
+    it 'reports top_coherence_label' do
+      client.create_narrative(title: 'Some Narrative')
+      result = client.narrative_reasoning_stats
+      expect(%i[compelling coherent developing fragmented incoherent]).to include(result[:top_coherence_label])
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/narrator/client_spec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Narrator::Client do
+  subject(:client) { described_class.new }
+
+  it 'initializes with a default journal' do
+    expect(client.journal).to be_a(Legion::Extensions::Agentic::Language::Narrator::Helpers::Journal)
+  end
+
+  it 'accepts an injected journal' do
+    custom = Legion::Extensions::Agentic::Language::Narrator::Helpers::Journal.new
+    client = described_class.new(journal: custom)
+    expect(client.journal).to be(custom)
+  end
+
+  it 'includes the Narrator runner' do
+    expect(client).to respond_to(:narrate)
+    expect(client).to respond_to(:recent_entries)
+    expect(client).to respond_to(:entries_since)
+    expect(client).to respond_to(:mood_history)
+    expect(client).to respond_to(:current_narrative)
+    expect(client).to respond_to(:narrator_stats)
+  end
+end