lex-agentic-language 0.1.0

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        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
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        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
+  end
+end

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

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        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
+  end
+end

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

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

data/lib/legion/extensions/agentic/language/narrative_reasoning.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/narrative_reasoning/version'
+require 'legion/extensions/agentic/language/narrative_reasoning/helpers/narrative_event'
+require 'legion/extensions/agentic/language/narrative_reasoning/helpers/narrative'
+require 'legion/extensions/agentic/language/narrative_reasoning/helpers/narrative_engine'
+require 'legion/extensions/agentic/language/narrative_reasoning/runners/narrative_reasoning'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module NarrativeReasoning
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/narrator/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/narrator/helpers/constants'
+require 'legion/extensions/agentic/language/narrator/helpers/prose'
+require 'legion/extensions/agentic/language/narrator/helpers/journal'
+require 'legion/extensions/agentic/language/narrator/helpers/synthesizer'
+require 'legion/extensions/agentic/language/narrator/runners/narrator'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Narrator
+          class Client
+            include Runners::Narrator
+
+            attr_reader :journal
+
+            def initialize(journal: nil, **)
+              @journal = journal || Helpers::Journal.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/narrator/helpers/constants.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Narrator
+          module Helpers
+            module Constants
+              # Maximum entries in the narrative journal
+              MAX_JOURNAL_SIZE = 500
+
+              # Narrative generation modes
+              MODES = %i[mechanical enhanced].freeze
+
+              # Default sections in a narrative entry
+              SECTIONS = %i[
+                attention emotion curiosity prediction
+                memory reflection identity overall
+              ].freeze
+
+              # Emotional dimension labels for prose generation
+              EMOTION_LABELS = {
+                high_positive: 'engaged and optimistic',
+                low_positive:  'calm and steady',
+                neutral:       'emotionally neutral',
+                low_negative:  'slightly uneasy',
+                high_negative: 'distressed'
+              }.freeze
+
+              # Arousal labels
+              AROUSAL_LABELS = {
+                high:    'highly alert',
+                medium:  'moderately attentive',
+                low:     'calm and measured',
+                dormant: 'in a low-activity state'
+              }.freeze
+
+              # Curiosity intensity labels
+              CURIOSITY_LABELS = {
+                high:   'deeply curious',
+                medium: 'moderately curious',
+                low:    'mildly interested',
+                none:   'not particularly curious about anything'
+              }.freeze
+
+              # Prediction confidence labels
+              CONFIDENCE_LABELS = {
+                high:   'confident in my predictions',
+                medium: 'moderately confident',
+                low:    'uncertain about outcomes',
+                none:   'lacking predictive context'
+              }.freeze
+
+              # Cognitive health labels
+              HEALTH_LABELS = {
+                excellent: 'operating at full capacity',
+                good:      'functioning well overall',
+                fair:      'showing some strain',
+                poor:      'experiencing significant cognitive difficulty',
+                critical:  'in cognitive distress'
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/narrator/helpers/journal.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Narrator
+          module Helpers
+            class Journal
+              attr_reader :entries
+
+              def initialize
+                @entries = []
+              end
+
+              def append(entry)
+                @entries << entry
+                trim_to_capacity
+                entry
+              end
+
+              def recent(limit: 10)
+                @entries.last(limit)
+              end
+
+              def since(timestamp)
+                @entries.select { |e| e[:timestamp] >= timestamp }
+              end
+
+              def by_mood(mood)
+                @entries.select { |e| e[:mood] == mood }
+              end
+
+              def size
+                @entries.size
+              end
+
+              def clear
+                @entries.clear
+              end
+
+              def stats
+                return { total: 0, moods: {} } if @entries.empty?
+
+                mood_counts = @entries.each_with_object(Hash.new(0)) { |e, h| h[e[:mood]] += 1 }
+                {
+                  total:    @entries.size,
+                  moods:    mood_counts,
+                  oldest:   @entries.first[:timestamp],
+                  newest:   @entries.last[:timestamp],
+                  capacity: Constants::MAX_JOURNAL_SIZE
+                }
+              end
+
+              private
+
+              def trim_to_capacity
+                return unless @entries.size > Constants::MAX_JOURNAL_SIZE
+
+                @entries.shift(@entries.size - Constants::MAX_JOURNAL_SIZE)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/narrator/helpers/llm_enhancer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Narrator
+          module Helpers
+            module LlmEnhancer
+              SYSTEM_PROMPT = <<~PROMPT
+                You are the internal narrator for an autonomous AI agent built on LegionIO.
+                You translate raw cognitive metrics into a flowing first-person internal monologue.
+                Write 3-5 sentences that feel like genuine introspection, not a report.
+                Vary your sentence structure. Use present tense. Be concise and vivid.
+              PROMPT
+
+              module_function
+
+              def available?
+                !!(defined?(Legion::LLM) && Legion::LLM.respond_to?(:started?) && Legion::LLM.started?)
+              rescue StandardError
+                false
+              end
+
+              def narrate(sections_data:)
+                prompt = build_narrate_prompt(sections_data)
+                response = llm_ask(prompt)
+                parse_narrate_response(response)
+              rescue StandardError => e
+                Legion::Logging.warn "[narrator:llm] narrate failed: #{e.message}"
+                nil
+              end
+
+              # --- Private helpers ---
+
+              def llm_ask(prompt)
+                chat = Legion::LLM.chat
+                chat.with_instructions(SYSTEM_PROMPT)
+                chat.ask(prompt)
+              end
+              private_class_method :llm_ask
+
+              def build_narrate_prompt(sections_data)
+                parts = [
+                  'Generate a first-person internal monologue based on the following cognitive state:',
+                  '',
+                  emotion_section(sections_data[:emotion] || {}),
+                  curiosity_section(sections_data[:curiosity] || {}),
+                  prediction_section(sections_data[:prediction] || {}),
+                  memory_section(sections_data[:memory] || {}),
+                  attention_section(sections_data[:attention] || {}),
+                  reflection_section(sections_data[:reflection] || {}),
+                  '',
+                  "Write a 3-5 sentence first-person narrative. Do not mention numbers directly \u2014 translate them into felt experience."
+                ]
+                parts.join("\n")
+              end
+
+              def emotion_section(emo)
+                "EMOTION:\n- Valence: #{emo[:valence] || 0.0}\n- Arousal: #{emo[:arousal] || 0.5}\n- Gut signal: #{emo[:gut] || 'none'}"
+              end
+
+              def curiosity_section(cur)
+                "CURIOSITY:\n- Intensity: #{cur[:intensity] || 0.0}\n- Active questions: #{cur[:wonder_count] || 0}\n- Top question: #{cur[:top_wonder] || 'none'}"
+              end
+
+              def prediction_section(pred)
+                "PREDICTION:\n- Confidence: #{pred[:confidence] || 0.0}\n- Pending: #{pred[:pending] || 0}\n- Mode: #{pred[:mode] || 'unknown'}"
+              end
+
+              def memory_section(mem)
+                "MEMORY:\n- Active traces: #{mem[:trace_count] || 0}\n- Health: #{mem[:health] || 1.0}"
+              end
+
+              def attention_section(att)
+                domains = Array(att[:focused_domains]).join(', ')
+                domains = 'none' if domains.empty?
+                "ATTENTION:\n- Spotlight: #{att[:spotlight] || 0}\n- Peripheral: #{att[:peripheral] || 0}\n- Focused: #{domains}"
+              end
+
+              def reflection_section(ref)
+                "REFLECTION:\n- Cognitive health: #{ref[:health] || 1.0}\n- Pending adaptations: #{ref[:pending_adaptations] || 0}"
+              end
+
+              def parse_narrate_response(response)
+                return nil unless response&.content
+
+                response.content.strip
+              end
+
+              private_class_method :build_narrate_prompt
+              private_class_method :emotion_section
+              private_class_method :curiosity_section
+              private_class_method :prediction_section
+              private_class_method :memory_section
+              private_class_method :attention_section
+              private_class_method :reflection_section
+              private_class_method :parse_narrate_response
+            end
+          end
+        end
+      end
+    end
+  end
+end