lex-agentic-self 0.1.0

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

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Helpers
+            class NarrativeEngine
+              attr_reader :episodes, :themes, :chapters
+
+              def initialize
+                @episodes = {}
+                @themes   = {}
+                @chapters = {}
+              end
+
+              def add_episode(content:, episode_type:, emotional_valence:, significance:, domain:)
+                prune_episodes! if @episodes.size >= Constants::MAX_EPISODES
+                episode = Episode.new(
+                  content:           content,
+                  episode_type:      episode_type,
+                  emotional_valence: emotional_valence,
+                  significance:      significance,
+                  domain:            domain
+                )
+                @episodes[episode.id] = episode
+                episode
+              end
+
+              def assign_to_chapter(episode_id:, chapter_id:)
+                episode = @episodes.fetch(episode_id, nil)
+                chapter = @chapters.fetch(chapter_id, nil)
+                return false unless episode && chapter
+
+                episode.chapter_id = chapter_id
+                chapter.episode_ids << episode_id unless chapter.episode_ids.include?(episode_id)
+                true
+              end
+
+              def create_chapter(title:, label:)
+                prune_chapters! if @chapters.size >= Constants::MAX_CHAPTERS
+                chapter = Chapter.new(title: title, label: label)
+                @chapters[chapter.id] = chapter
+                chapter
+              end
+
+              def close_chapter(chapter_id:)
+                chapter = @chapters.fetch(chapter_id, nil)
+                return false unless chapter
+
+                chapter.end_time = Time.now.utc
+                true
+              end
+
+              def add_theme(name:, theme_type:)
+                prune_themes! if @themes.size >= Constants::MAX_THEMES
+                theme = Theme.new(name: name, theme_type: theme_type)
+                @themes[theme.id] = theme
+                theme
+              end
+
+              def link_theme(episode_id:, theme_id:)
+                episode = @episodes.fetch(episode_id, nil)
+                theme   = @themes.fetch(theme_id, nil)
+                return false unless episode && theme
+
+                episode.themes << theme_id unless episode.themes.include?(theme_id)
+                theme.episode_ids << episode_id unless theme.episode_ids.include?(episode_id)
+                true
+              end
+
+              def reinforce_theme(theme_id:, amount:)
+                theme = @themes.fetch(theme_id, nil)
+                return false unless theme
+
+                theme.reinforce!(amount)
+                true
+              end
+
+              def narrative_coherence
+                return 0.0 if @episodes.empty? || @themes.empty?
+
+                linked       = @episodes.values.count { |ep| ep.themes.any? }
+                base         = (linked.to_f / @episodes.size).round(10)
+                theme_factor = prominent_themes.size.to_f / [@themes.size, 1].max
+                ((base * 0.7) + (theme_factor * 0.3)).round(10).clamp(0.0, 1.0)
+              end
+
+              def identity_summary
+                {
+                  top_themes:        prominent_themes.first(5).map(&:to_h),
+                  defining_episodes: most_defining_episodes(limit: 5).map(&:to_h),
+                  current_chapter:   current_chapter&.to_h,
+                  coherence:         narrative_coherence,
+                  coherence_label:   coherence_label,
+                  episode_count:     @episodes.size,
+                  theme_count:       @themes.size,
+                  chapter_count:     @chapters.size
+                }
+              end
+
+              def life_story
+                @chapters.values.sort_by(&:start_time).map do |chapter|
+                  eps = chapter.episode_ids.filter_map { |id| @episodes[id] }.sort_by(&:created_at)
+                  {
+                    chapter:  chapter.to_h,
+                    episodes: eps.map { |ep| ep.to_h.merge(theme_names: theme_names_for(ep)) }
+                  }
+                end
+              end
+
+              def most_defining_episodes(limit: 5)
+                @episodes.values.sort_by { |ep| -ep.significance }.first(limit)
+              end
+
+              def prominent_themes
+                @themes.values.select(&:prominent?).sort_by { |t| -t.strength }
+              end
+
+              def current_chapter
+                @chapters.values.find(&:current?)
+              end
+
+              def decay_all_themes!
+                @themes.each_value(&:decay!)
+              end
+
+              def narrative_report
+                {
+                  identity_summary: identity_summary,
+                  life_story:       life_story,
+                  narrative_state:  {
+                    coherence:         narrative_coherence,
+                    coherence_label:   coherence_label,
+                    prominent_themes:  prominent_themes.map(&:to_h),
+                    defining_episodes: most_defining_episodes(limit: 3).map(&:to_h),
+                    current_chapter:   current_chapter&.to_h
+                  }
+                }
+              end
+
+              def to_h
+                {
+                  episodes: @episodes.transform_values(&:to_h),
+                  themes:   @themes.transform_values(&:to_h),
+                  chapters: @chapters.transform_values(&:to_h)
+                }
+              end
+
+              private
+
+              def coherence_label
+                score = narrative_coherence
+                Constants::COHERENCE_LABELS.each do |entry|
+                  range, label = entry.first
+                  return label if range.cover?(score)
+                end
+                :absent
+              end
+
+              def theme_names_for(episode)
+                episode.themes.filter_map { |tid| @themes[tid]&.name }
+              end
+
+              def prune_episodes!
+                oldest = @episodes.values.min_by(&:created_at)
+                @episodes.delete(oldest.id) if oldest
+              end
+
+              def prune_themes!
+                weakest = @themes.values.min_by(&:strength)
+                @themes.delete(weakest.id) if weakest
+              end
+
+              def prune_chapters!
+                closed = @chapters.values.reject(&:current?).min_by(&:start_time)
+                target = closed || @chapters.values.min_by(&:start_time)
+                @chapters.delete(target.id) if target
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Helpers
+            class Theme
+              attr_reader :id, :name, :theme_type, :episode_ids
+              attr_accessor :strength
+
+              def initialize(name:, theme_type:, strength: 0.0, episode_ids: nil, id: nil)
+                @id          = id || SecureRandom.uuid
+                @name        = name
+                @theme_type  = theme_type
+                @strength    = strength.clamp(0.0, 1.0)
+                @episode_ids = episode_ids || []
+              end
+
+              def reinforce!(amount)
+                @strength = (@strength + amount).clamp(0.0, 1.0).round(10)
+              end
+
+              def decay!
+                @strength = (@strength - Constants::COHERENCE_DECAY).clamp(0.0, 1.0).round(10)
+              end
+
+              def prominent?
+                @strength >= 0.6
+              end
+
+              def to_h
+                {
+                  id:          @id,
+                  name:        @name,
+                  theme_type:  @theme_type,
+                  strength:    @strength,
+                  episode_ids: @episode_ids.dup
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+          module Runners
+            module NarrativeIdentity
+              extend self
+
+              def record_episode(content:, episode_type:, emotional_valence:, significance:, domain:,
+                                 engine: nil, **)
+                return { success: false, error: "unknown episode_type: #{episode_type.inspect}" } unless
+                  Helpers::Constants::EPISODE_TYPES.include?(episode_type)
+
+                episode = resolve_engine(engine).add_episode(
+                  content: content, episode_type: episode_type,
+                  emotional_valence: emotional_valence, significance: significance, domain: domain
+                )
+                Legion::Logging.debug "[narrative_identity] recorded episode #{episode.id[0..7]} type=#{episode_type}"
+                { success: true, episode: episode.to_h }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def assign_episode_to_chapter(episode_id:, chapter_id:, engine: nil, **)
+                result = resolve_engine(engine).assign_to_chapter(episode_id: episode_id, chapter_id: chapter_id)
+                Legion::Logging.debug "[narrative_identity] assign episode=#{episode_id[0..7]} ok=#{result}"
+                { success: result, episode_id: episode_id, chapter_id: chapter_id }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def create_chapter(title:, label:, engine: nil, **)
+                return { success: false, error: "unknown chapter label: #{label.inspect}" } unless
+                  Helpers::Constants::CHAPTER_LABELS.include?(label)
+
+                chapter = resolve_engine(engine).create_chapter(title: title, label: label)
+                Legion::Logging.debug "[narrative_identity] created chapter #{chapter.id[0..7]} label=#{label}"
+                { success: true, chapter: chapter.to_h }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def close_chapter(chapter_id:, engine: nil, **)
+                result = resolve_engine(engine).close_chapter(chapter_id: chapter_id)
+                Legion::Logging.debug "[narrative_identity] close_chapter #{chapter_id[0..7]} ok=#{result}"
+                { success: result, chapter_id: chapter_id }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def add_theme(name:, theme_type:, engine: nil, **)
+                return { success: false, error: "unknown theme_type: #{theme_type.inspect}" } unless
+                  Helpers::Constants::THEME_TYPES.include?(theme_type)
+
+                theme = resolve_engine(engine).add_theme(name: name, theme_type: theme_type)
+                Legion::Logging.debug "[narrative_identity] added theme #{theme.id[0..7]} type=#{theme_type}"
+                { success: true, theme: theme.to_h }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def link_theme(episode_id:, theme_id:, engine: nil, **)
+                result = resolve_engine(engine).link_theme(episode_id: episode_id, theme_id: theme_id)
+                Legion::Logging.debug "[narrative_identity] link theme=#{theme_id[0..7]} episode=#{episode_id[0..7]} ok=#{result}"
+                { success: result, episode_id: episode_id, theme_id: theme_id }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def reinforce_theme(theme_id:, amount:, engine: nil, **)
+                result = resolve_engine(engine).reinforce_theme(theme_id: theme_id, amount: amount)
+                Legion::Logging.debug "[narrative_identity] reinforce theme=#{theme_id[0..7]} amount=#{amount} ok=#{result}"
+                { success: result, theme_id: theme_id, amount: amount }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def narrative_coherence(engine: nil, **)
+                score = resolve_engine(engine).narrative_coherence
+                Legion::Logging.debug "[narrative_identity] coherence=#{score}"
+                { success: true, coherence: score }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def identity_summary(engine: nil, **)
+                summary = resolve_engine(engine).identity_summary
+                Legion::Logging.debug '[narrative_identity] identity_summary requested'
+                { success: true, summary: summary }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def life_story(engine: nil, **)
+                story = resolve_engine(engine).life_story
+                Legion::Logging.debug "[narrative_identity] life_story chapters=#{story.size}"
+                { success: true, life_story: story }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def most_defining_episodes(limit: 5, engine: nil, **)
+                episodes = resolve_engine(engine).most_defining_episodes(limit: limit)
+                Legion::Logging.debug "[narrative_identity] defining_episodes count=#{episodes.size}"
+                { success: true, episodes: episodes.map(&:to_h) }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def prominent_themes(engine: nil, **)
+                themes = resolve_engine(engine).prominent_themes
+                Legion::Logging.debug "[narrative_identity] prominent_themes count=#{themes.size}"
+                { success: true, themes: themes.map(&:to_h) }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def current_chapter(engine: nil, **)
+                chapter = resolve_engine(engine).current_chapter
+                Legion::Logging.debug "[narrative_identity] current_chapter=#{chapter&.id&.slice(0..7)}"
+                { success: true, chapter: chapter&.to_h }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def decay_themes(engine: nil, **)
+                resolve_engine(engine).decay_all_themes!
+                Legion::Logging.debug '[narrative_identity] theme decay applied'
+                { success: true }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              def narrative_report(engine: nil, **)
+                report = resolve_engine(engine).narrative_report
+                Legion::Logging.debug '[narrative_identity] narrative_report generated'
+                { success: true, report: report }
+              rescue StandardError => e
+                { success: false, error: e.message }
+              end
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              private
+
+              def resolve_engine(engine)
+                engine || (@default_engine ||= Helpers::NarrativeEngine.new)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/narrative_identity/version'
+require 'legion/extensions/agentic/self/narrative_identity/helpers/constants'
+require 'legion/extensions/agentic/self/narrative_identity/helpers/episode'
+require 'legion/extensions/agentic/self/narrative_identity/helpers/theme'
+require 'legion/extensions/agentic/self/narrative_identity/helpers/chapter'
+require 'legion/extensions/agentic/self/narrative_identity/helpers/narrative_engine'
+require 'legion/extensions/agentic/self/narrative_identity/runners/narrative_identity'
+require 'legion/extensions/agentic/self/narrative_identity/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeIdentity
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/self/narrative_self/helpers/constants'
+require 'legion/extensions/agentic/self/narrative_self/helpers/episode'
+require 'legion/extensions/agentic/self/narrative_self/helpers/narrative_thread'
+require 'legion/extensions/agentic/self/narrative_self/helpers/autobiography'
+require 'legion/extensions/agentic/self/narrative_self/runners/narrative_self'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeSelf
+          class Client
+            include Runners::NarrativeSelf
+
+            attr_reader :autobiography
+
+            def initialize(autobiography: nil, **)
+              @autobiography = autobiography || Helpers::Autobiography.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/self/narrative_self/helpers/autobiography.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeSelf
+          module Helpers
+            class Autobiography
+              include Constants
+
+              attr_reader :episodes, :threads, :self_concept
+
+              def initialize
+                @episodes     = []
+                @threads      = []
+                @self_concept = {}
+              end
+
+              def record_episode(description:, episode_type: :insight, domain: :general,
+                                 significance: nil, emotional_valence: 0.0, tags: [])
+                episode = Episode.new(
+                  description:       description,
+                  episode_type:      episode_type,
+                  domain:            domain,
+                  significance:      significance,
+                  emotional_valence: emotional_valence,
+                  tags:              tags
+                )
+                @episodes << episode
+                auto_link_threads(episode)
+                update_self_concept(episode)
+                trim_episodes
+                episode
+              end
+
+              def find_episode(id)
+                @episodes.find { |e| e.id == id }
+              end
+
+              def recent_episodes(count = 10)
+                @episodes.last(count)
+              end
+
+              def significant_episodes(min_significance: 0.6)
+                @episodes.select { |e| e.significance >= min_significance }
+                         .sort_by { |e| -e.significance }
+              end
+
+              def episodes_by_type(episode_type)
+                @episodes.select { |e| e.episode_type == episode_type }
+              end
+
+              def episodes_in_domain(domain)
+                @episodes.select { |e| e.domain == domain }
+              end
+
+              def create_thread(theme:, domain: :general)
+                thread = NarrativeThread.new(theme: theme, domain: domain)
+                @threads << thread
+                trim_threads
+                thread
+              end
+
+              def find_thread(id)
+                @threads.find { |t| t.id == id }
+              end
+
+              def find_threads_by_theme(theme)
+                @threads.select { |t| t.theme == theme }
+              end
+
+              def strongest_threads(count = 5)
+                @threads.sort_by { |t| -t.strength }.first(count)
+              end
+
+              def timeline(window: MAX_TIMELINE_WINDOW)
+                @episodes.last(window).map(&:to_h)
+              end
+
+              def self_summary
+                top_types = episode_type_distribution.first(3).map(&:first)
+                top_domains = domain_distribution.first(3).map(&:first)
+                top_threads = strongest_threads(3).map(&:theme)
+                {
+                  total_episodes:     @episodes.size,
+                  dominant_types:     top_types,
+                  dominant_domains:   top_domains,
+                  active_threads:     top_threads,
+                  self_concept:       @self_concept.dup,
+                  pivotal_count:      @episodes.count { |e| e.label == :pivotal },
+                  narrative_richness: narrative_richness
+                }
+              end
+
+              def decay_all
+                @episodes.each(&:decay)
+                @episodes.reject!(&:faded?)
+                @threads.each(&:decay)
+                @threads.reject!(&:weak?)
+              end
+
+              def to_h
+                {
+                  episode_count:    @episodes.size,
+                  thread_count:     @threads.size,
+                  self_concept:     @self_concept.dup,
+                  by_type:          @episodes.group_by(&:episode_type).transform_values(&:size),
+                  by_domain:        @episodes.group_by(&:domain).transform_values(&:size),
+                  avg_significance: avg_significance
+                }
+              end
+
+              private
+
+              def auto_link_threads(episode)
+                @threads.each do |thread|
+                  relevance = episode.matches_tags?([thread.theme])
+                  relevance += 0.2 if episode.domain == thread.domain
+                  next unless relevance >= THREAD_MATCH_THRESHOLD
+
+                  thread.add_episode(episode.id)
+                  episode.link_thread(thread.id)
+                end
+              end
+
+              def update_self_concept(episode)
+                trait = episode.episode_type
+                current = @self_concept.fetch(trait, 0.0)
+                signal = episode.significance
+                @self_concept[trait] = ((TRAIT_ALPHA * signal) + ((1.0 - TRAIT_ALPHA) * current)).clamp(0.0, 1.0)
+                trim_self_concept
+              end
+
+              def trim_self_concept
+                return unless @self_concept.size > MAX_SELF_CONCEPT_TRAITS
+
+                sorted = @self_concept.sort_by { |_, v| v }
+                @self_concept = sorted.last(MAX_SELF_CONCEPT_TRAITS).to_h
+              end
+
+              def trim_episodes
+                return unless @episodes.size > MAX_EPISODES
+
+                @episodes.sort_by!(&:significance)
+                @episodes.shift(@episodes.size - MAX_EPISODES)
+              end
+
+              def trim_threads
+                return unless @threads.size > MAX_THREADS
+
+                @threads.sort_by!(&:strength)
+                @threads.shift(@threads.size - MAX_THREADS)
+              end
+
+              def episode_type_distribution
+                @episodes.group_by(&:episode_type)
+                         .transform_values(&:size)
+                         .sort_by { |_, count| -count }
+              end
+
+              def domain_distribution
+                @episodes.group_by(&:domain)
+                         .transform_values(&:size)
+                         .sort_by { |_, count| -count }
+              end
+
+              def avg_significance
+                return 0.0 if @episodes.empty?
+
+                @episodes.sum(&:significance) / @episodes.size
+              end
+
+              def narrative_richness
+                return 0.0 if @episodes.empty?
+
+                type_diversity = @episodes.map(&:episode_type).uniq.size.to_f / EPISODE_TYPES.size
+                thread_activity = @threads.empty? ? 0.0 : @threads.count { |t| t.size > 1 }.to_f / @threads.size
+                ((type_diversity + thread_activity) / 2.0).clamp(0.0, 1.0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Self
+        module NarrativeSelf
+          module Helpers
+            module Constants
+              MAX_EPISODES        = 500
+              MAX_THREADS         = 50
+              MAX_CHAPTER_SIZE    = 20
+              EPISODE_DECAY       = 0.005
+              THREAD_DECAY        = 0.01
+              SIGNIFICANCE_FLOOR  = 0.05
+              SIGNIFICANCE_ALPHA  = 0.15
+              DEFAULT_SIGNIFICANCE = 0.5
+              EMOTIONAL_BOOST = 0.3
+              THREAD_MATCH_THRESHOLD = 0.3
+              MAX_SELF_CONCEPT_TRAITS = 30
+              TRAIT_ALPHA         = 0.1
+              MAX_TIMELINE_WINDOW = 100
+
+              SIGNIFICANCE_LABELS = {
+                (0.8..)     => :pivotal,
+                (0.6...0.8) => :important,
+                (0.3...0.6) => :routine,
+                (..0.3)     => :minor
+              }.freeze
+
+              EPISODE_TYPES = %i[
+                achievement failure discovery connection
+                conflict resolution insight surprise
+                decision transition reflection
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end