lex-agentic-self 0.1.0

data/lib/legion/extensions/agentic/self/narrative_arc/helpers/arc_engine.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+          module Helpers
+            class ArcEngine
+              attr_reader :arcs
+
+              def initialize
+                @arcs = {}
+              end
+
+              def create_arc(title:, domain: :general, initial_tension: Constants::DEFAULT_TENSION)
+                return nil if @arcs.size >= Constants::MAX_ARCS
+
+                arc = Arc.new(title: title, domain: domain, initial_tension: initial_tension)
+                @arcs[arc.arc_id] = arc
+                arc
+              end
+
+              def add_beat(arc_id:, content:, intensity: 0.5, beat_type: :rising_action,
+                           domain: :general, emotional_charge: 0.0)
+                arc = @arcs[arc_id]
+                return { success: false, reason: :arc_not_found } unless arc
+
+                beat = BeatEvent.new(
+                  content:          content,
+                  intensity:        intensity,
+                  beat_type:        beat_type,
+                  domain:           domain,
+                  emotional_charge: emotional_charge
+                )
+
+                added = arc.add_beat!(beat)
+                return { success: false, reason: :arc_full_or_complete } unless added
+
+                { success: true, beat_id: beat.beat_id, arc_phase: arc.arc_phase,
+                  tension_level: arc.tension_level }
+              end
+
+              def get_arc(arc_id)
+                @arcs[arc_id]
+              end
+
+              def active_arcs
+                @arcs.values.reject(&:complete?)
+              end
+
+              def completed_arcs
+                @arcs.values.select(&:complete?)
+              end
+
+              def most_dramatic_arc
+                return nil if @arcs.empty?
+
+                @arcs.values.max_by(&:dramatic_score)
+              end
+
+              def tension_distribution
+                return {} if @arcs.empty?
+
+                counts = Hash.new(0)
+                @arcs.each_value do |arc|
+                  label = arc.tension_label
+                  counts[label] += 1
+                end
+                counts
+              end
+
+              def detect_narrative_patterns
+                return [] if @arcs.size < 2
+
+                patterns = []
+                patterns << :recurring_crisis if recurring_beat_pattern?(:crisis)
+                patterns << :recurring_climax if recurring_beat_pattern?(:climax)
+                patterns << :unresolved_tension if unresolved_high_tension?
+                patterns << :rapid_resolution if rapid_resolution_pattern?
+                patterns
+              end
+
+              def arc_report
+                {
+                  total_arcs:    @arcs.size,
+                  active:        active_arcs.size,
+                  completed:     completed_arcs.size,
+                  patterns:      detect_narrative_patterns,
+                  tension_dist:  tension_distribution,
+                  most_dramatic: most_dramatic_arc&.to_h
+                }
+              end
+
+              private
+
+              def recurring_beat_pattern?(beat_type)
+                arc_with_beat_type_count = @arcs.values.count do |arc|
+                  arc.beats.any? { |b| b.beat_type == beat_type }
+                end
+                arc_with_beat_type_count >= 2
+              end
+
+              def unresolved_high_tension?
+                active_arcs.any? { |arc| arc.tension_level >= Constants::CLIMAX_THRESHOLD }
+              end
+
+              def rapid_resolution_pattern?
+                @arcs.values.any? do |arc|
+                  arc.complete? && arc.beats.size <= 3
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_arc/helpers/beat_event.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+          module Helpers
+            class BeatEvent
+              attr_reader :beat_id, :content, :intensity, :beat_type, :domain,
+                          :emotional_charge, :created_at
+
+              def initialize(content:, intensity: 0.5, beat_type: :rising_action,
+                             domain: :general, emotional_charge: 0.0)
+                @beat_id        = SecureRandom.uuid
+                @content        = content
+                @intensity      = intensity.clamp(0.0, 1.0)
+                @beat_type      = validate_beat_type(beat_type)
+                @domain         = domain
+                @emotional_charge = emotional_charge.clamp(-1.0, 1.0)
+                @created_at = Time.now.utc
+              end
+
+              def to_h
+                {
+                  beat_id:          @beat_id,
+                  content:          @content,
+                  intensity:        @intensity,
+                  beat_type:        @beat_type,
+                  domain:           @domain,
+                  emotional_charge: @emotional_charge,
+                  created_at:       @created_at
+                }
+              end
+
+              def climactic?
+                @beat_type == :climax || @intensity >= Constants::CLIMAX_THRESHOLD
+              end
+
+              def resolving?
+                %i[falling_action resolution denouement].include?(@beat_type)
+              end
+
+              private
+
+              def validate_beat_type(type)
+                return type if Constants::BEAT_TYPES.include?(type)
+
+                Constants::BEAT_TYPES.first
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_arc/helpers/constants.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+          module Helpers
+            module Constants
+              MAX_ARCS           = 100
+              MAX_BEATS_PER_ARC  = 50
+              DEFAULT_TENSION    = 0.3
+              TENSION_RISE       = 0.1
+              TENSION_FALL       = 0.08
+              CLIMAX_THRESHOLD   = 0.8
+              RESOLUTION_THRESHOLD = 0.2
+
+              BEAT_TYPES = %i[
+                exposition
+                rising_action
+                complication
+                crisis
+                climax
+                falling_action
+                resolution
+                denouement
+              ].freeze
+
+              ARC_PHASES = %i[building peak resolving complete].freeze
+
+              TENSION_LABELS = {
+                (0.0..0.2) => :calm,
+                (0.2..0.5) => :developing,
+                (0.5..0.8) => :tense,
+                (0.8..1.0) => :critical
+              }.freeze
+
+              DRAMA_LABELS = {
+                (0.0..0.25) => :mundane,
+                (0.25..0.5) => :engaging,
+                (0.5..0.75) => :compelling,
+                (0.75..1.0) => :gripping
+              }.freeze
+
+              PHASE_LABELS = {
+                building:  'Rising action building toward climax',
+                peak:      'At or near peak tension — climax active',
+                resolving: 'Falling action moving toward resolution',
+                complete:  'Arc resolved and closed'
+              }.freeze
+
+              module_function
+
+              def label_for(labels_hash, value)
+                labels_hash.each do |range, label|
+                  return label if range.cover?(value)
+                end
+                labels_hash.values.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_arc/runners/narrative.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+          module Runners
+            module Narrative
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_arc(title:, domain: :general, initial_tension: Helpers::Constants::DEFAULT_TENSION,
+                             engine: nil, **)
+                eng = engine || arc_engine
+                arc = eng.create_arc(title: title, domain: domain, initial_tension: initial_tension)
+
+                unless arc
+                  Legion::Logging.warn "[narrative_arc] create_arc failed: engine at capacity (#{Helpers::Constants::MAX_ARCS})"
+                  return { success: false, reason: :engine_at_capacity }
+                end
+
+                Legion::Logging.debug "[narrative_arc] arc created: #{arc.arc_id[0..7]} title=#{title} domain=#{domain}"
+                { success: true, arc_id: arc.arc_id, title: arc.title, arc_phase: arc.arc_phase,
+                  tension_level: arc.tension_level }
+              end
+
+              def add_beat(arc_id:, content:, intensity: 0.5, beat_type: :rising_action,
+                           domain: :general, emotional_charge: 0.0, engine: nil, **)
+                eng = engine || arc_engine
+                result = eng.add_beat(
+                  arc_id:           arc_id,
+                  content:          content,
+                  intensity:        intensity,
+                  beat_type:        beat_type,
+                  domain:           domain,
+                  emotional_charge: emotional_charge
+                )
+
+                if result[:success]
+                  arc = eng.get_arc(arc_id)
+                  Legion::Logging.debug "[narrative_arc] beat added: arc=#{arc_id[0..7]} type=#{beat_type} " \
+                                        "phase=#{result[:arc_phase]} tension=#{result[:tension_level].round(2)}"
+                  result[:dramatic_score] = arc.dramatic_score if arc
+                else
+                  Legion::Logging.debug "[narrative_arc] add_beat failed: #{result[:reason]} arc=#{arc_id[0..7]}"
+                end
+
+                result
+              end
+
+              def get_arc(arc_id:, engine: nil, **)
+                eng = engine || arc_engine
+                arc = eng.get_arc(arc_id)
+                return { found: false, arc_id: arc_id } unless arc
+
+                { found: true, arc: arc.to_h, beats: arc.beats.map(&:to_h) }
+              end
+
+              def active_arcs(engine: nil, **)
+                eng = engine || arc_engine
+                arcs = eng.active_arcs
+                Legion::Logging.debug "[narrative_arc] active arcs count=#{arcs.size}"
+                { arcs: arcs.map(&:to_h), count: arcs.size }
+              end
+
+              def completed_arcs(engine: nil, **)
+                eng = engine || arc_engine
+                arcs = eng.completed_arcs
+                Legion::Logging.debug "[narrative_arc] completed arcs count=#{arcs.size}"
+                { arcs: arcs.map(&:to_h), count: arcs.size }
+              end
+
+              def most_dramatic_arc(engine: nil, **)
+                eng = engine || arc_engine
+                arc = eng.most_dramatic_arc
+                return { found: false } unless arc
+
+                Legion::Logging.debug "[narrative_arc] most dramatic: #{arc.arc_id[0..7]} score=#{arc.dramatic_score.round(2)}"
+                { found: true, arc: arc.to_h }
+              end
+
+              def arc_report(engine: nil, **)
+                eng = engine || arc_engine
+                report = eng.arc_report
+                Legion::Logging.debug "[narrative_arc] arc_report total=#{report[:total_arcs]} patterns=#{report[:patterns].inspect}"
+                { success: true, report: report }
+              end
+
+              private
+
+              def arc_engine
+                @arc_engine ||= Helpers::ArcEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/narrative_arc/version'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/constants'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/beat_event'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/arc'
+require 'legion/extensions/agentic/self/narrative_arc/helpers/arc_engine'
+require 'legion/extensions/agentic/self/narrative_arc/runners/narrative'
+require 'legion/extensions/agentic/self/narrative_arc/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeArc
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_identity/actors/narrative_decay.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Actor
+            class NarrativeDecay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Self::NarrativeIdentity::Runners::NarrativeIdentity
+              end
+
+              def runner_function
+                'decay_themes'
+              end
+
+              def time
+                600
+              end
+
+              def run_now?
+                false
+              end
+
+              def use_runner?
+                false
+              end
+
+              def check_subtask?
+                false
+              end
+
+              def generate_task?
+                false
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          class Client
+            include Runners::NarrativeIdentity
+
+            attr_reader :engine
+
+            def initialize(engine: nil)
+              @engine          = engine || Helpers::NarrativeEngine.new
+              @default_engine  = @engine
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_identity/helpers/chapter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Helpers
+            class Chapter
+              attr_reader :id, :title, :label, :episode_ids, :start_time
+              attr_accessor :end_time
+
+              def initialize(title:, label:, episode_ids: nil, start_time: nil, end_time: nil, id: nil)
+                @id          = id || SecureRandom.uuid
+                @title       = title
+                @label       = label
+                @episode_ids = episode_ids || []
+                @start_time  = start_time || Time.now.utc
+                @end_time    = end_time
+              end
+
+              def current?
+                @end_time.nil?
+              end
+
+              def episode_count
+                @episode_ids.size
+              end
+
+              def to_h
+                {
+                  id:          @id,
+                  title:       @title,
+                  label:       @label,
+                  episode_ids: @episode_ids.dup,
+                  start_time:  @start_time,
+                  end_time:    @end_time
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_identity/helpers/constants.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Helpers
+            module Constants
+              MAX_EPISODES = 500
+              MAX_THEMES   = 50
+              MAX_CHAPTERS = 20
+
+              EPISODE_TYPES = %i[
+                achievement
+                failure
+                discovery
+                relationship
+                challenge
+                transformation
+                routine
+              ].freeze
+
+              THEME_TYPES = %i[
+                growth
+                agency
+                communion
+                redemption
+                contamination
+                stability
+                exploration
+              ].freeze
+
+              EMOTIONAL_VALENCE_WEIGHT = 0.4
+              SIGNIFICANCE_WEIGHT      = 0.3
+              RECENCY_WEIGHT           = 0.3
+              COHERENCE_DECAY          = 0.01
+
+              SIGNIFICANCE_LABELS = [
+                { (0.8..1.0)  => :defining  },
+                { (0.6...0.8) => :major     },
+                { (0.4...0.6) => :notable   },
+                { (0.2...0.4) => :minor     },
+                { (0.0...0.2) => :trivial   }
+              ].freeze
+
+              COHERENCE_LABELS = [
+                { (0.8..1.0)  => :unified    },
+                { (0.6...0.8) => :coherent   },
+                { (0.4...0.6) => :developing },
+                { (0.2...0.4) => :fragmented },
+                { (0.0...0.2) => :absent     }
+              ].freeze
+
+              CHAPTER_LABELS = %i[origin early_learning growth mastery current].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_identity/helpers/episode.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Helpers
+            class Episode
+              attr_reader :id, :content, :episode_type, :emotional_valence,
+                          :significance, :domain, :themes, :created_at
+              attr_accessor :chapter_id
+
+              def initialize(content:, episode_type:, emotional_valence:, significance:, domain:, **)
+                @id                = SecureRandom.uuid
+                @content           = content
+                @episode_type      = episode_type
+                @emotional_valence = emotional_valence.clamp(-1.0, 1.0)
+                @significance      = significance.clamp(0.0, 1.0)
+                @domain            = domain
+                @chapter_id        = nil
+                @themes            = []
+                @created_at        = Time.now.utc
+              end
+
+              def positive?
+                @emotional_valence.positive?
+              end
+
+              def negative?
+                @emotional_valence.negative?
+              end
+
+              def defining?
+                @significance >= 0.8
+              end
+
+              def significance_label
+                Constants::SIGNIFICANCE_LABELS.each do |entry|
+                  range, label = entry.first
+                  return label if range.cover?(@significance)
+                end
+                :trivial
+              end
+
+              def to_h
+                {
+                  id:                @id,
+                  content:           @content,
+                  episode_type:      @episode_type,
+                  emotional_valence: @emotional_valence,
+                  significance:      @significance,
+                  domain:            @domain,
+                  chapter_id:        @chapter_id,
+                  themes:            @themes.dup,
+                  created_at:        @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end