lex-narrative-reasoning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 234a1fb4d137c47def7053f94c85de48519c5dc129f96dc4431b3e2d493da2de
+  data.tar.gz: 7960f4ebc954519fe45ac8bddcfbddf5d3c1456e24c24dcfc80ce41fd1b12e74
+SHA512:
+  metadata.gz: 5a5e7533a37b1c9677bd4619b1ae52cfaf9596727c25b242a6b33ca022c8654954cb26b10f6f747b742a071988045a75a3b07f2cc19c90054fd9ab8204fea2e3
+  data.tar.gz: 251d0440acc69a6fdcb4e4be5f6afe361f24490df56e35e4b439f299a8ab705fdaa8c0227457a8d84f71efb042b61d5fbf2080afa538feb4c61317ef3bb8f453

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-narrative-reasoning.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/narrative_reasoning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-narrative-reasoning'
+  spec.version       = Legion::Extensions::NarrativeReasoning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Narrative Reasoning'
+  spec.description   = 'Narrative reasoning engine for brain-modeled agentic AI — story structure, causal chains, arc progression'
+  spec.homepage      = 'https://github.com/LegionIO/lex-narrative-reasoning'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-narrative-reasoning'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-narrative-reasoning'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-narrative-reasoning'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-narrative-reasoning/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-narrative-reasoning.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/narrative_reasoning/client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrative_reasoning/helpers/narrative_event'
+require 'legion/extensions/narrative_reasoning/helpers/narrative'
+require 'legion/extensions/narrative_reasoning/helpers/narrative_engine'
+require 'legion/extensions/narrative_reasoning/runners/narrative_reasoning'
+
+module Legion
+  module Extensions
+    module NarrativeReasoning
+      class Client
+        include Runners::NarrativeReasoning
+
+        def initialize(**)
+          @narrative_engine = Helpers::NarrativeEngine.new
+        end
+
+        private
+
+        attr_reader :narrative_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_reasoning/helpers/narrative.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module NarrativeReasoning
+      module Helpers
+        class Narrative
+          ARC_STAGES = %i[beginning rising_action climax falling_action resolution].freeze
+
+          COHERENCE_LABELS = {
+            (0.8..)     => :compelling,
+            (0.6...0.8) => :coherent,
+            (0.4...0.6) => :developing,
+            (0.2...0.4) => :fragmented,
+            (..0.2)     => :incoherent
+          }.freeze
+
+          DEFAULT_COHERENCE  = 0.5
+          COHERENCE_FLOOR    = 0.0
+          COHERENCE_CEILING  = 1.0
+          COHERENCE_BOOST    = 0.1
+          DECAY_RATE         = 0.02
+
+          attr_reader :id, :title, :domain, :events, :characters, :themes,
+                      :arc_stage, :coherence, :created_at, :last_updated_at
+
+          def initialize(title:, domain: nil, id: nil)
+            @id             = id || SecureRandom.uuid
+            @title          = title
+            @domain         = domain
+            @events         = []
+            @characters     = []
+            @themes         = []
+            @arc_stage      = ARC_STAGES.first
+            @coherence      = DEFAULT_COHERENCE
+            @created_at     = Time.now.utc
+            @last_updated_at = Time.now.utc
+          end
+
+          def add_event(event)
+            @events << event
+            event.characters.each { |chr| @characters << chr unless @characters.include?(chr) }
+            auto_advance_arc
+            @coherence = (@coherence + COHERENCE_BOOST).clamp(COHERENCE_FLOOR, COHERENCE_CEILING)
+            @last_updated_at = Time.now.utc
+            event
+          end
+
+          def add_theme(theme)
+            @themes << theme unless @themes.include?(theme)
+            @last_updated_at = Time.now.utc
+            theme
+          end
+
+          def advance_arc!
+            idx = ARC_STAGES.index(@arc_stage)
+            return @arc_stage if idx.nil? || idx >= ARC_STAGES.size - 1
+
+            @arc_stage = ARC_STAGES[idx + 1]
+            @last_updated_at = Time.now.utc
+            @arc_stage
+          end
+
+          def causal_chain
+            chain = []
+            @events.each do |event|
+              event.causes.each do |cause_id|
+                cause = @events.find { |e| e.id == cause_id }
+                chain << { cause: cause&.to_h, effect: event.to_h } if cause
+              end
+            end
+            chain
+          end
+
+          def coherence_label
+            COHERENCE_LABELS.find { |range, _label| range.cover?(@coherence) }&.last || :incoherent
+          end
+
+          def complete?
+            @arc_stage == :resolution
+          end
+
+          def decay_coherence
+            @coherence = (@coherence - DECAY_RATE).clamp(COHERENCE_FLOOR, COHERENCE_CEILING)
+          end
+
+          def to_h
+            {
+              id:              @id,
+              title:           @title,
+              domain:          @domain,
+              events:          @events.map(&:to_h),
+              characters:      @characters,
+              themes:          @themes,
+              arc_stage:       @arc_stage,
+              coherence:       @coherence,
+              coherence_label: coherence_label,
+              complete:        complete?,
+              created_at:      @created_at,
+              last_updated_at: @last_updated_at
+            }
+          end
+
+          private
+
+          def auto_advance_arc
+            return if complete?
+
+            events_per_stage = [(@events.size / 5.0).ceil, 1].max
+            stage_idx = [(@events.size / events_per_stage), ARC_STAGES.size - 1].min
+            @arc_stage = ARC_STAGES[stage_idx]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_reasoning/helpers/narrative_engine.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module NarrativeReasoning
+      module Helpers
+        class NarrativeEngine
+          MAX_NARRATIVES = 100
+          MAX_EVENTS     = 500
+          MAX_CHARACTERS = 200
+          MAX_HISTORY    = 300
+
+          EVENT_TYPES = %i[action discovery conflict resolution revelation].freeze
+
+          def initialize
+            @narratives = {}
+            @event_count = 0
+          end
+
+          def create_narrative(title:, domain: nil)
+            evict_oldest_narrative if @narratives.size >= MAX_NARRATIVES
+            narrative = Narrative.new(title: title, domain: domain)
+            @narratives[narrative.id] = narrative
+            narrative
+          end
+
+          def add_narrative_event(narrative_id:, content:, event_type:, characters: [], causes: [])
+            narrative = @narratives[narrative_id]
+            return nil unless narrative
+            return nil unless EVENT_TYPES.include?(event_type)
+
+            domain = narrative.domain
+            event = NarrativeEvent.new(
+              content:    content,
+              event_type: event_type,
+              characters: characters,
+              causes:     causes,
+              domain:     domain
+            )
+            @event_count += 1
+            evict_oldest_events(narrative) if narrative.events.size >= MAX_EVENTS
+            narrative.add_event(event)
+          end
+
+          def add_narrative_theme(narrative_id:, theme:)
+            narrative = @narratives[narrative_id]
+            return nil unless narrative
+
+            narrative.add_theme(theme)
+          end
+
+          def advance_narrative(narrative_id:)
+            narrative = @narratives[narrative_id]
+            return nil unless narrative
+
+            narrative.advance_arc!
+          end
+
+          def trace_causal_chain(narrative_id:)
+            narrative = @narratives[narrative_id]
+            return [] unless narrative
+
+            narrative.causal_chain
+          end
+
+          def complete_narratives
+            @narratives.values.select(&:complete?)
+          end
+
+          def by_domain(domain:)
+            @narratives.values.select { |n| n.domain == domain }
+          end
+
+          def most_coherent(limit: 5)
+            @narratives.values
+                       .sort_by { |n| -n.coherence }
+                       .first(limit)
+          end
+
+          def get(narrative_id)
+            @narratives[narrative_id]
+          end
+
+          def decay_all
+            @narratives.each_value(&:decay_coherence)
+          end
+
+          def count
+            @narratives.size
+          end
+
+          def total_events
+            @event_count
+          end
+
+          def to_h
+            {
+              narratives:   @narratives.values.map(&:to_h),
+              count:        @narratives.size,
+              total_events: @event_count
+            }
+          end
+
+          private
+
+          def evict_oldest_narrative
+            oldest = @narratives.values.min_by(&:created_at)
+            @narratives.delete(oldest.id) if oldest
+          end
+
+          def evict_oldest_events(narrative)
+            narrative.events.shift
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/narrative_reasoning/helpers/narrative_event.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module NarrativeReasoning
+      module Helpers
+        class NarrativeEvent
+          attr_reader :id, :content, :event_type, :characters, :causes, :timestamp, :domain
+
+          def initialize(content:, event_type:, characters: [], causes: [], domain: nil, id: nil, timestamp: nil)
+            @id         = id || SecureRandom.uuid
+            @content    = content
+            @event_type = event_type
+            @characters = Array(characters).dup
+            @causes     = Array(causes).dup
+            @domain     = domain
+            @timestamp  = timestamp || Time.now.utc
+          end
+
+          def to_h
+            {
+              id:         @id,
+              content:    @content,
+              event_type: @event_type,
+              characters: @characters,
+              causes:     @causes,
+              domain:     @domain,
+              timestamp:  @timestamp
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module NarrativeReasoning
+      module Runners
+        module NarrativeReasoning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_narrative(title:, domain: nil, **)
+            narrative = narrative_engine.create_narrative(title: title, domain: domain)
+            Legion::Logging.debug "[narrative_reasoning] created narrative id=#{narrative.id[0..7]} title=#{title}"
+            { success: true, narrative_id: narrative.id, title: narrative.title, arc_stage: narrative.arc_stage }
+          end
+
+          def add_narrative_event(narrative_id:, content:, event_type:, characters: [], causes: [], **)
+            unless Helpers::NarrativeEngine::EVENT_TYPES.include?(event_type)
+              return { success: false, error: :invalid_event_type, valid_types: Helpers::NarrativeEngine::EVENT_TYPES }
+            end
+
+            event = narrative_engine.add_narrative_event(
+              narrative_id: narrative_id,
+              content:      content,
+              event_type:   event_type,
+              characters:   characters,
+              causes:       causes
+            )
+
+            if event
+              Legion::Logging.debug "[narrative_reasoning] event added id=#{event.id[0..7]} type=#{event_type}"
+              { success: true, event_id: event.id, event_type: event_type, narrative_id: narrative_id }
+            else
+              Legion::Logging.debug "[narrative_reasoning] add_event failed: narrative #{narrative_id[0..7]} not found"
+              { success: false, error: :narrative_not_found }
+            end
+          end
+
+          def add_narrative_theme(narrative_id:, theme:, **)
+            result = narrative_engine.add_narrative_theme(narrative_id: narrative_id, theme: theme)
+            if result
+              Legion::Logging.debug "[narrative_reasoning] theme added theme=#{theme} to #{narrative_id[0..7]}"
+              { success: true, narrative_id: narrative_id, theme: theme }
+            else
+              { success: false, error: :narrative_not_found }
+            end
+          end
+
+          def advance_narrative_arc(narrative_id:, **)
+            new_stage = narrative_engine.advance_narrative(narrative_id: narrative_id)
+            if new_stage
+              Legion::Logging.debug "[narrative_reasoning] arc advanced to #{new_stage} for #{narrative_id[0..7]}"
+              { success: true, narrative_id: narrative_id, arc_stage: new_stage }
+            else
+              { success: false, error: :narrative_not_found }
+            end
+          end
+
+          def trace_narrative_causes(narrative_id:, **)
+            chain = narrative_engine.trace_causal_chain(narrative_id: narrative_id)
+            narrative = narrative_engine.get(narrative_id)
+            return { success: false, error: :narrative_not_found } unless narrative
+
+            Legion::Logging.debug "[narrative_reasoning] causal chain length=#{chain.size} for #{narrative_id[0..7]}"
+            { success: true, narrative_id: narrative_id, chain: chain, link_count: chain.size }
+          end
+
+          def complete_narratives(**)
+            narratives = narrative_engine.complete_narratives
+            Legion::Logging.debug "[narrative_reasoning] complete narratives count=#{narratives.size}"
+            { success: true, narratives: narratives.map(&:to_h), count: narratives.size }
+          end
+
+          def domain_narratives(domain:, **)
+            narratives = narrative_engine.by_domain(domain: domain)
+            Legion::Logging.debug "[narrative_reasoning] domain=#{domain} count=#{narratives.size}"
+            { success: true, domain: domain, narratives: narratives.map(&:to_h), count: narratives.size }
+          end
+
+          def most_coherent_narratives(limit: 5, **)
+            lim = limit.to_i.clamp(1, 50)
+            narratives = narrative_engine.most_coherent(limit: lim)
+            Legion::Logging.debug "[narrative_reasoning] most_coherent limit=#{lim} returned=#{narratives.size}"
+            { success: true, narratives: narratives.map(&:to_h), count: narratives.size }
+          end
+
+          def update_narrative_reasoning(**)
+            narrative_engine.decay_all
+            count = narrative_engine.count
+            Legion::Logging.debug "[narrative_reasoning] decay cycle complete narratives=#{count}"
+            { success: true, narratives_updated: count }
+          end
+
+          def narrative_reasoning_stats(**)
+            engine = narrative_engine
+            complete = engine.complete_narratives.size
+            most_coh = engine.most_coherent(limit: 1).first
+            Legion::Logging.debug "[narrative_reasoning] stats count=#{engine.count} complete=#{complete}"
+            {
+              success:             true,
+              total_narratives:    engine.count,
+              total_events:        engine.total_events,
+              complete_narratives: complete,
+              top_coherence:       most_coh&.coherence,
+              top_coherence_label: most_coh&.coherence_label
+            }
+          end
+
+          private
+
+          def narrative_engine
+            @narrative_engine ||= Helpers::NarrativeEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/narrative_reasoning.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrative_reasoning/version'
+require 'legion/extensions/narrative_reasoning/helpers/narrative_event'
+require 'legion/extensions/narrative_reasoning/helpers/narrative'
+require 'legion/extensions/narrative_reasoning/helpers/narrative_engine'
+require 'legion/extensions/narrative_reasoning/runners/narrative_reasoning'
+
+module Legion
+  module Extensions
+    module NarrativeReasoning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrative_reasoning/client'
+
+RSpec.describe Legion::Extensions::NarrativeReasoning::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_narrative)
+    expect(client).to respond_to(:add_narrative_event)
+    expect(client).to respond_to(:add_narrative_theme)
+    expect(client).to respond_to(:advance_narrative_arc)
+    expect(client).to respond_to(:trace_narrative_causes)
+    expect(client).to respond_to(:complete_narratives)
+    expect(client).to respond_to(:domain_narratives)
+    expect(client).to respond_to(:most_coherent_narratives)
+    expect(client).to respond_to(:update_narrative_reasoning)
+    expect(client).to respond_to(:narrative_reasoning_stats)
+  end
+end

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

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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::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::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::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/narrative_reasoning/helpers/narrative_event_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/narrative_reasoning/helpers/narrative_spec.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::NarrativeReasoning::Helpers::Narrative do
+  let(:narrative) { described_class.new(title: 'The Journey', domain: 'adventure') }
+
+  let(:event1) do
+    Legion::Extensions::NarrativeReasoning::Helpers::NarrativeEvent.new(
+      content:    'Hero leaves home',
+      event_type: :action,
+      characters: ['hero']
+    )
+  end
+
+  let(:event2) do
+    Legion::Extensions::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/narrative_reasoning/runners/narrative_reasoning_spec.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/narrative_reasoning/client'
+
+RSpec.describe Legion::Extensions::NarrativeReasoning::Runners::NarrativeReasoning do
+  let(:client) { Legion::Extensions::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/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/narrative_reasoning'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-narrative-reasoning
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Narrative reasoning engine for brain-modeled agentic AI — story structure,
+  causal chains, arc progression
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-narrative-reasoning.gemspec
+- lib/legion/extensions/narrative_reasoning.rb
+- lib/legion/extensions/narrative_reasoning/client.rb
+- lib/legion/extensions/narrative_reasoning/helpers/narrative.rb
+- lib/legion/extensions/narrative_reasoning/helpers/narrative_engine.rb
+- lib/legion/extensions/narrative_reasoning/helpers/narrative_event.rb
+- lib/legion/extensions/narrative_reasoning/runners/narrative_reasoning.rb
+- lib/legion/extensions/narrative_reasoning/version.rb
+- spec/legion/extensions/narrative_reasoning/client_spec.rb
+- spec/legion/extensions/narrative_reasoning/helpers/narrative_engine_spec.rb
+- spec/legion/extensions/narrative_reasoning/helpers/narrative_event_spec.rb
+- spec/legion/extensions/narrative_reasoning/helpers/narrative_spec.rb
+- spec/legion/extensions/narrative_reasoning/runners/narrative_reasoning_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-narrative-reasoning
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-narrative-reasoning
+  source_code_uri: https://github.com/LegionIO/lex-narrative-reasoning
+  documentation_uri: https://github.com/LegionIO/lex-narrative-reasoning
+  changelog_uri: https://github.com/LegionIO/lex-narrative-reasoning
+  bug_tracker_uri: https://github.com/LegionIO/lex-narrative-reasoning/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Narrative Reasoning
+test_files: []