lex-agentic-language 0.1.0

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/language/helpers/constants'
+require 'legion/extensions/agentic/language/language/helpers/summarizer'
+require 'legion/extensions/agentic/language/language/helpers/lexicon'
+require 'legion/extensions/agentic/language/language/runners/language'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Language
+          class Client
+            include Runners::Language
+
+            attr_reader :lexicon
+
+            def initialize(lexicon: nil, **)
+              @lexicon = lexicon || Helpers::Lexicon.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Language
+          module Helpers
+            module Constants
+              # Maximum traces to consider in a single summarization
+              MAX_TRACES_PER_SUMMARY = 50
+
+              # Minimum strength threshold for including a trace in a summary
+              MIN_SUMMARY_STRENGTH = 0.1
+
+              # Summary depth levels
+              DEPTHS = %i[brief standard detailed].freeze
+
+              # Trace type priority for summary ordering
+              TYPE_PRIORITY = {
+                firmware:   0,
+                identity:   1,
+                procedural: 2,
+                semantic:   3,
+                trust:      4,
+                episodic:   5,
+                sensory:    6
+              }.freeze
+
+              # Knowledge quality thresholds
+              KNOWLEDGE_RICH     = 10  # traces for "rich knowledge"
+              KNOWLEDGE_MODERATE = 5   # traces for "moderate knowledge"
+              KNOWLEDGE_SPARSE   = 1   # traces for "sparse knowledge"
+
+              # Wonder resolution: minimum traces to consider a domain "known"
+              RESOLUTION_THRESHOLD = 3
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/language/helpers/lexicon.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Language
+          module Helpers
+            class Lexicon
+              attr_reader :domain_summaries
+
+              def initialize
+                @domain_summaries = {}
+              end
+
+              def store_summary(domain, summary)
+                domain = domain.to_sym
+                @domain_summaries[domain] = summary.merge(cached_at: Time.now.utc)
+              end
+
+              def get_summary(domain)
+                @domain_summaries[domain.to_sym]
+              end
+
+              def known_domains
+                @domain_summaries.keys
+              end
+
+              def knowledge_map
+                @domain_summaries.transform_values do |summary|
+                  {
+                    knowledge_level: summary[:knowledge_level],
+                    trace_count:     summary[:trace_count],
+                    cached_at:       summary[:cached_at]
+                  }
+                end
+              end
+
+              def stale?(domain, max_age: 300)
+                summary = get_summary(domain)
+                return true unless summary
+
+                (Time.now.utc - summary[:cached_at]) > max_age
+              end
+
+              def clear(domain = nil)
+                if domain
+                  @domain_summaries.delete(domain.to_sym)
+                else
+                  @domain_summaries.clear
+                end
+              end
+
+              def size
+                @domain_summaries.size
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/language/helpers/summarizer.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Language
+          module Helpers
+            module Summarizer
+              module_function
+
+              def summarize_domain(traces, domain:, depth: :standard)
+                return empty_summary(domain) if traces.empty?
+
+                grouped = group_by_type(traces)
+                knowledge_level = classify_knowledge(traces.size)
+
+                {
+                  domain:          domain,
+                  knowledge_level: knowledge_level,
+                  trace_count:     traces.size,
+                  type_breakdown:  type_breakdown(grouped),
+                  key_facts:       extract_key_facts(grouped, depth: depth),
+                  strength_stats:  strength_stats(traces),
+                  emotional_tone:  emotional_tone(traces),
+                  freshness:       freshness_assessment(traces)
+                }
+              end
+
+              def group_by_type(traces)
+                grouped = traces.group_by { |t| t[:trace_type] || :unknown }
+                grouped.sort_by { |type, _| Constants::TYPE_PRIORITY[type] || 99 }.to_h
+              end
+
+              def type_breakdown(grouped)
+                grouped.transform_values(&:size)
+              end
+
+              def extract_key_facts(grouped, depth: :standard)
+                limit = case depth
+                        when :brief    then 3
+                        when :detailed then 15
+                        else 7
+                        end
+
+                facts = []
+                grouped.each do |type, traces|
+                  sorted = traces.sort_by { |t| -(t[:strength] || 0) }
+                  count = [sorted.size, limit_per_type(type, limit)].min
+                  sorted.first(count).each do |trace|
+                    facts << format_fact(trace, type)
+                  end
+                end
+
+                facts.first(limit)
+              end
+
+              def format_fact(trace, type)
+                content = extract_content_text(trace[:content_payload])
+                {
+                  trace_id:    trace[:trace_id],
+                  type:        type,
+                  content:     content,
+                  strength:    (trace[:strength] || 0).round(3),
+                  confidence:  (trace[:confidence] || 0.5).round(3),
+                  domain_tags: trace[:domain_tags] || []
+                }
+              end
+
+              def extract_content_text(payload)
+                case payload
+                when String then payload
+                when Hash   then payload[:text] || payload[:content] || payload[:summary] || payload.to_s
+                when Array  then payload.first.to_s
+                else payload.to_s
+                end
+              end
+
+              def classify_knowledge(count)
+                if count >= Constants::KNOWLEDGE_RICH then :rich
+                elsif count >= Constants::KNOWLEDGE_MODERATE then :moderate
+                elsif count >= Constants::KNOWLEDGE_SPARSE   then :sparse
+                else :none
+                end
+              end
+
+              def strength_stats(traces)
+                strengths = traces.map { |t| t[:strength] || 0 }
+                {
+                  mean:   (strengths.sum / strengths.size).round(3),
+                  max:    strengths.max.round(3),
+                  min:    strengths.min.round(3),
+                  strong: strengths.count { |s| s >= 0.5 },
+                  weak:   strengths.count { |s| s < 0.3 }
+                }
+              end
+
+              def emotional_tone(traces)
+                valences = traces.map { |t| t[:emotional_valence] || 0.0 }
+                intensities = traces.map { |t| t[:emotional_intensity] || 0.0 }
+
+                avg_valence = valences.sum / valences.size
+                avg_intensity = intensities.sum / intensities.size
+
+                {
+                  avg_valence:   avg_valence.round(3),
+                  avg_intensity: avg_intensity.round(3),
+                  tone:          tone_label(avg_valence, avg_intensity)
+                }
+              end
+
+              def tone_label(valence, intensity)
+                if intensity < 0.2      then :neutral
+                elsif valence > 0.3     then :positive
+                elsif valence < -0.3    then :negative
+                else :mixed
+                end
+              end
+
+              def freshness_assessment(traces)
+                now = Time.now.utc
+                ages = traces.map { |t| now - (t[:last_reinforced] || t[:created_at] || now) }
+                avg_age = ages.sum / ages.size
+
+                {
+                  avg_age_seconds: avg_age.round(1),
+                  freshest:        ages.min.round(1),
+                  stalest:         ages.max.round(1),
+                  label:           freshness_label(avg_age)
+                }
+              end
+
+              def freshness_label(avg_age)
+                if avg_age < 60       then :very_fresh
+                elsif avg_age < 3600  then :fresh
+                elsif avg_age < 86_400 then :aging
+                else :stale
+                end
+              end
+
+              def empty_summary(domain)
+                {
+                  domain:          domain,
+                  knowledge_level: :none,
+                  trace_count:     0,
+                  type_breakdown:  {},
+                  key_facts:       [],
+                  strength_stats:  { mean: 0.0, max: 0.0, min: 0.0, strong: 0, weak: 0 },
+                  emotional_tone:  { avg_valence: 0.0, avg_intensity: 0.0, tone: :neutral },
+                  freshness:       { avg_age_seconds: 0.0, freshest: 0.0, stalest: 0.0, label: :stale }
+                }
+              end
+
+              def limit_per_type(type, total_limit)
+                case type
+                when :firmware, :identity then [total_limit, 3].min
+                when :procedural          then [total_limit, 2].min
+                else [total_limit, 5].min
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Language
+          module Runners
+            module Language
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def summarize(domain:, depth: :standard, traces: [], **)
+                traces = filter_traces(traces, domain)
+                summary = Helpers::Summarizer.summarize_domain(traces, domain: domain.to_sym, depth: depth.to_sym)
+                lexicon.store_summary(domain, summary)
+
+                Legion::Logging.debug "[language] summarize domain=#{domain} traces=#{traces.size} " \
+                                      "knowledge=#{summary[:knowledge_level]}"
+                summary
+              end
+
+              def what_do_i_know(domain:, depth: :standard, traces: [], **)
+                summary = if lexicon.stale?(domain)
+                            summarize(domain: domain, depth: depth, traces: traces)
+                          else
+                            lexicon.get_summary(domain)
+                          end
+
+                prose = generate_knowledge_prose(summary)
+
+                {
+                  domain:          domain.to_sym,
+                  knowledge_level: summary[:knowledge_level],
+                  prose:           prose,
+                  fact_count:      summary[:key_facts]&.size || 0,
+                  summary:         summary
+                }
+              end
+
+              def can_answer_wonder?(wonder:, traces: [], **)
+                domain = wonder.is_a?(Hash) ? wonder[:domain] : :general
+                relevant = filter_traces(traces, domain)
+
+                answerable = relevant.size >= Helpers::Constants::RESOLUTION_THRESHOLD
+                confidence = answerable ? compute_answer_confidence(relevant) : 0.0
+
+                {
+                  answerable:  answerable,
+                  confidence:  confidence.round(3),
+                  domain:      domain,
+                  trace_count: relevant.size,
+                  threshold:   Helpers::Constants::RESOLUTION_THRESHOLD
+                }
+              end
+
+              def knowledge_map(**)
+                {
+                  domains:       lexicon.knowledge_map,
+                  known_domains: lexicon.known_domains,
+                  total_domains: lexicon.size
+                }
+              end
+
+              def language_stats(**)
+                {
+                  cached_domains: lexicon.size,
+                  known_domains:  lexicon.known_domains,
+                  knowledge_map:  lexicon.knowledge_map
+                }
+              end
+
+              private
+
+              def lexicon
+                @lexicon ||= Helpers::Lexicon.new
+              end
+
+              def filter_traces(traces, domain)
+                return [] unless traces.is_a?(Array)
+
+                domain_sym = domain.to_sym
+                domain_str = domain.to_s
+
+                matching = traces.select do |t|
+                  tags = t[:domain_tags] || []
+                  tags.any? { |tag| tag.to_s == domain_str || tag.to_sym == domain_sym }
+                end
+
+                matching
+                  .select { |t| (t[:strength] || 0) >= Helpers::Constants::MIN_SUMMARY_STRENGTH }
+                  .sort_by { |t| -(t[:strength] || 0) }
+                  .first(Helpers::Constants::MAX_TRACES_PER_SUMMARY)
+              end
+
+              def generate_knowledge_prose(summary)
+                domain = summary[:domain]
+                level = summary[:knowledge_level]
+                count = summary[:trace_count]
+                facts = summary[:key_facts] || []
+
+                base = "About #{domain}: I have #{level} knowledge (#{count} traces)."
+
+                if facts.empty?
+                  "#{base} No specific facts available."
+                else
+                  fact_lines = facts.first(5).map { |f| "- #{truncate(f[:content], 120)}" }
+                  "#{base}\nKey facts:\n#{fact_lines.join("\n")}"
+                end
+              end
+
+              def compute_answer_confidence(traces)
+                return 0.0 if traces.empty?
+
+                strengths = traces.map { |t| t[:strength] || 0.0 }
+                confidences = traces.map { |t| t[:confidence] || 0.5 }
+
+                avg_strength = strengths.sum / strengths.size
+                avg_confidence = confidences.sum / confidences.size
+
+                ((avg_strength * 0.5) + (avg_confidence * 0.5)).clamp(0.0, 1.0)
+              end
+
+              def truncate(text, max_length)
+                text = text.to_s
+                text.length > max_length ? "#{text[0...max_length]}..." : text
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/language/version'
+require 'legion/extensions/agentic/language/language/helpers/constants'
+require 'legion/extensions/agentic/language/language/helpers/summarizer'
+require 'legion/extensions/agentic/language/language/helpers/lexicon'
+require 'legion/extensions/agentic/language/language/runners/language'
+require 'legion/extensions/agentic/language/language/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Language
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+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
+          class Client
+            include Runners::NarrativeReasoning
+
+            def initialize(**)
+              @narrative_engine = Helpers::NarrativeEngine.new
+            end
+
+            private
+
+            attr_reader :narrative_engine
+          end
+        end
+      end
+    end
+  end
+end

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

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