lex-agentic-language 0.1.0

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Grammar
+          module Runners
+            module CognitiveGrammar
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_grammar_construction(form:, meaning:, expression_type:, domain:, **)
+                construction = engine.create_construction(
+                  form:            form,
+                  meaning:         meaning,
+                  expression_type: expression_type,
+                  domain:          domain
+                )
+                Legion::Logging.debug "[cognitive_grammar] created construction form=#{form} type=#{expression_type} domain=#{domain}"
+                construction.to_h
+              end
+
+              def create_grammar_construal(scene:, perspective:, figure:, ground:, # rubocop:disable Metrics/ParameterLists
+                                           specificity: :intermediate, scope: :local,
+                                           dynamicity: 0.5, construction_id: nil, **)
+                construal = engine.create_construal(
+                  scene:           scene,
+                  perspective:     perspective,
+                  figure:          figure,
+                  ground:          ground,
+                  specificity:     specificity,
+                  scope:           scope,
+                  dynamicity:      dynamicity,
+                  construction_id: construction_id
+                )
+                Legion::Logging.debug "[cognitive_grammar] created construal scene=#{scene} figure=#{figure}"
+                construal.to_h
+              end
+
+              def use_grammar_construction(construction_id:, **)
+                construction = engine.use_construction(construction_id: construction_id)
+                return { found: false, construction_id: construction_id } unless construction
+
+                msg = "[cognitive_grammar] used construction id=#{construction_id[0..7]} " \
+                      "usage_count=#{construction.usage_count} activation=#{construction.activation.round(3)}"
+                Legion::Logging.debug msg
+                { found: true, construction: construction.to_h }
+              end
+
+              def construals_for_scene_report(scene:, **)
+                construals = engine.construals_for_scene(scene: scene)
+                Legion::Logging.debug "[cognitive_grammar] construals_for_scene scene=#{scene} count=#{construals.size}"
+                { scene: scene, count: construals.size, construals: construals.map(&:to_h) }
+              end
+
+              def entrenched_constructions_report(**)
+                constructions = engine.entrenched_constructions
+                Legion::Logging.debug "[cognitive_grammar] entrenched constructions count=#{constructions.size}"
+                { count: constructions.size, constructions: constructions.map(&:to_h) }
+              end
+
+              def constructions_by_domain_report(domain:, **)
+                constructions = engine.constructions_by_domain(domain: domain)
+                Legion::Logging.debug "[cognitive_grammar] constructions_by_domain domain=#{domain} count=#{constructions.size}"
+                { domain: domain, count: constructions.size, constructions: constructions.map(&:to_h) }
+              end
+
+              def most_used_constructions(limit: 5, **)
+                constructions = engine.most_used(limit: limit)
+                Legion::Logging.debug "[cognitive_grammar] most_used limit=#{limit} count=#{constructions.size}"
+                { limit: limit, count: constructions.size, constructions: constructions.map(&:to_h) }
+              end
+
+              def update_cognitive_grammar(**)
+                engine.decay_all
+                pruned = engine.prune_inactive
+                stats  = engine.to_h
+                Legion::Logging.debug "[cognitive_grammar] update: pruned=#{pruned} remaining=#{stats[:constructions_count]}"
+                { pruned: pruned, stats: stats }
+              end
+
+              def cognitive_grammar_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug "[cognitive_grammar] stats constructions=#{stats[:constructions_count]} construals=#{stats[:construals_count]}"
+                stats
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::GrammarEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/grammar/version'
+require 'legion/extensions/agentic/language/grammar/helpers/constants'
+require 'legion/extensions/agentic/language/grammar/helpers/construction'
+require 'legion/extensions/agentic/language/grammar/helpers/construal'
+require 'legion/extensions/agentic/language/grammar/helpers/grammar_engine'
+require 'legion/extensions/agentic/language/grammar/runners/cognitive_grammar'
+require 'legion/extensions/agentic/language/grammar/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Grammar
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          class Client
+            include Runners::InnerSpeech
+
+            def initialize(voice: nil)
+              @voice = voice || Helpers::InnerVoice.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          module Helpers
+            module Constants
+              MAX_UTTERANCES = 500
+              MAX_STREAM_LENGTH = 100
+              MAX_HISTORY = 200
+
+              # Speech condensation: inner speech is ~3x compressed vs external
+              CONDENSATION_RATIO = 0.33
+
+              # Rumination detection: same topic repeated N+ times
+              RUMINATION_THRESHOLD = 3
+
+              # Speed constants (utterances per tick)
+              AUTOMATIC_SPEED = 3
+              CONTROLLED_SPEED = 1
+              EGOCENTRIC_SPEED = 0.5
+
+              # Decay: how quickly old utterances lose salience
+              SALIENCE_DECAY = 0.05
+              SALIENCE_FLOOR = 0.01
+
+              SPEECH_MODES = %i[
+                planning rehearsal monitoring evaluating
+                questioning affirming narrating debating
+                comforting warning remembering imagining
+              ].freeze
+
+              VOICE_TYPES = %i[
+                rational emotional cautious bold
+                critical supportive curious skeptical
+              ].freeze
+
+              URGENCY_LABELS = {
+                (0.8..)     => :critical,
+                (0.6...0.8) => :high,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :background
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/inner_speech/helpers/inner_voice.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          module Helpers
+            class InnerVoice
+              include Constants
+
+              attr_reader :stream, :voices, :active_voice, :history
+
+              def initialize
+                @stream       = SpeechStream.new
+                @voices       = VOICE_TYPES.dup
+                @active_voice = :rational
+                @history      = []
+                @speed        = CONTROLLED_SPEED
+              end
+
+              def speak(content:, mode: :narrating, topic: :general, **)
+                utterance = @stream.append(
+                  content: content,
+                  mode:    mode,
+                  voice:   @active_voice,
+                  topic:   topic,
+                  **
+                )
+                record_event(:speak, utterance_id: utterance&.id) if utterance
+                utterance
+              end
+
+              def switch_voice(voice:)
+                sym = voice.to_sym
+                return nil unless VOICE_TYPES.include?(sym)
+
+                old_voice = @active_voice
+                @active_voice = sym
+                record_event(:switch_voice, from: old_voice, to: sym)
+                @active_voice
+              end
+
+              def plan(content:, topic: :general, **)
+                speak(content: content, mode: :planning, topic: topic, **)
+              end
+
+              def rehearse(content:, topic: :general, **)
+                speak(content: content, mode: :rehearsal, topic: topic, **)
+              end
+
+              def question(content:, topic: :general, **)
+                speak(content: content, mode: :questioning, topic: topic, **)
+              end
+
+              def evaluate(content:, topic: :general, **)
+                speak(content: content, mode: :evaluating, topic: topic, **)
+              end
+
+              def warn(content:, topic: :general, **)
+                speak(content: content, mode: :warning, topic: topic, urgency: 0.8, **)
+              end
+
+              def debate(content_a:, content_b:, topic: :general, **)
+                old_voice = @active_voice
+                @active_voice = :bold
+                utt_a = speak(content: content_a, mode: :debating, topic: topic, **)
+                @active_voice = :cautious
+                utt_b = speak(content: content_b, mode: :debating, topic: topic, **)
+                @active_voice = old_voice
+                [utt_a, utt_b].compact
+              end
+
+              def interrupt(content:, **)
+                utterance = @stream.interrupt(content: content, **)
+                record_event(:interrupt, utterance_id: utterance&.id) if utterance
+                utterance
+              end
+
+              SPEED_MAP = {
+                automatic:  AUTOMATIC_SPEED,
+                controlled: CONTROLLED_SPEED,
+                egocentric: EGOCENTRIC_SPEED
+              }.freeze
+
+              def set_speed(mode:)
+                @speed = SPEED_MAP.fetch(mode, CONTROLLED_SPEED)
+              end
+
+              def ruminating?
+                @stream.ruminating?
+              end
+
+              def break_rumination(redirect_topic:)
+                return false unless ruminating?
+
+                speak(content: 'Let me think about something else.', mode: :narrating, topic: redirect_topic)
+                true
+              end
+
+              def recent_speech(count: 5)
+                @stream.recent(count: count)
+              end
+
+              def narrative
+                @stream.narrative
+              end
+
+              def condensed_narrative
+                @stream.condensed_stream.join(' ')
+              end
+
+              def tick
+                @stream.decay_all
+                @stream.to_h.merge(active_voice: @active_voice, speed: @speed)
+              end
+
+              def to_h
+                {
+                  active_voice:     @active_voice,
+                  speed:            @speed,
+                  stream_size:      @stream.size,
+                  ruminating:       ruminating?,
+                  total_utterances: @stream.counter,
+                  history_size:     @history.size
+                }
+              end
+
+              private
+
+              def record_event(type, **details)
+                @history << { type: type, at: Time.now.utc }.merge(details)
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/inner_speech/helpers/speech_stream.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          module Helpers
+            class SpeechStream
+              include Constants
+
+              attr_reader :utterances, :counter
+
+              def initialize
+                @utterances = []
+                @counter    = 0
+              end
+
+              def append(content:, mode: :narrating, **)
+                return nil if @utterances.size >= MAX_STREAM_LENGTH
+
+                @counter += 1
+                utterance = Utterance.new(
+                  id:      :"utt_#{@counter}",
+                  content: content,
+                  mode:    mode,
+                  **
+                )
+                @utterances << utterance
+                utterance
+              end
+
+              def current
+                @utterances.last
+              end
+
+              def recent(count: 5)
+                @utterances.last(count).map(&:to_h)
+              end
+
+              def by_mode(mode:)
+                @utterances.select { |u| u.mode == mode }.map(&:to_h)
+              end
+
+              def by_voice(voice:)
+                @utterances.select { |u| u.voice == voice }.map(&:to_h)
+              end
+
+              def by_topic(topic:)
+                @utterances.select { |u| u.topic == topic }.map(&:to_h)
+              end
+
+              def salient
+                @utterances.select(&:salient?).map(&:to_h)
+              end
+
+              def urgent
+                @utterances.select(&:urgent?).map(&:to_h)
+              end
+
+              def ruminating?
+                return false if @utterances.size < RUMINATION_THRESHOLD
+
+                recent_topics = @utterances.last(RUMINATION_THRESHOLD).map(&:topic)
+                recent_topics.uniq.size == 1
+              end
+
+              def rumination_topic
+                return nil unless ruminating?
+
+                @utterances.last&.topic
+              end
+
+              def decay_all
+                @utterances.each(&:decay_salience!)
+                prune_stale
+              end
+
+              def interrupt(content:, mode: :warning, **)
+                append(content: content, mode: mode, urgency: 0.9, salience: 0.9, **)
+              end
+
+              def condensed_stream
+                @utterances.select(&:salient?).map(&:condensed_content)
+              end
+
+              def narrative
+                @utterances.map(&:content).join(' ')
+              end
+
+              def clear
+                @utterances.clear
+              end
+
+              def size
+                @utterances.size
+              end
+
+              def to_h
+                {
+                  size:              @utterances.size,
+                  total_generated:   @counter,
+                  ruminating:        ruminating?,
+                  rumination_topic:  rumination_topic,
+                  salient_count:     @utterances.count(&:salient?),
+                  urgent_count:      @utterances.count(&:urgent?),
+                  mode_distribution: mode_distribution
+                }
+              end
+
+              private
+
+              def prune_stale
+                @utterances.reject! { |u| u.salience <= SALIENCE_FLOOR }
+              end
+
+              def mode_distribution
+                dist = Hash.new(0)
+                @utterances.each { |u| dist[u.mode] += 1 }
+                dist
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/inner_speech/helpers/utterance.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          module Helpers
+            class Utterance
+              include Constants
+
+              attr_reader :id, :content, :mode, :voice, :topic,
+                          :urgency, :salience, :source_subsystem, :created_at
+
+              def initialize(id:, content:, mode: :narrating, **opts)
+                @id               = id
+                @content          = content
+                @mode             = resolve_mode(mode)
+                apply_opts(opts)
+                @created_at = Time.now.utc
+              end
+
+              def condensed_content
+                words = @content.split
+                keep = [(words.size * CONDENSATION_RATIO).ceil, 1].max
+                words.first(keep).join(' ')
+              end
+
+              def urgent?
+                @urgency >= 0.6
+              end
+
+              def background?
+                @urgency < 0.2
+              end
+
+              def decay_salience!
+                @salience = [@salience - SALIENCE_DECAY, SALIENCE_FLOOR].max
+              end
+
+              def salient?
+                @salience >= 0.3
+              end
+
+              def urgency_label
+                URGENCY_LABELS.each { |range, lbl| return lbl if range.cover?(@urgency) }
+                :background
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  content:          @content,
+                  condensed:        condensed_content,
+                  mode:             @mode,
+                  voice:            @voice,
+                  topic:            @topic,
+                  urgency:          @urgency.round(4),
+                  salience:         @salience.round(4),
+                  source_subsystem: @source_subsystem,
+                  urgency_label:    urgency_label
+                }
+              end
+
+              private
+
+              def apply_opts(opts)
+                @voice            = resolve_voice(opts.fetch(:voice, :rational))
+                @topic            = opts.fetch(:topic, :general)
+                @urgency          = opts.fetch(:urgency, 0.5).to_f.clamp(0.0, 1.0)
+                @salience         = opts.fetch(:salience, 0.5).to_f.clamp(0.0, 1.0)
+                @source_subsystem = opts.fetch(:source_subsystem, :unknown)
+              end
+
+              def resolve_mode(mode)
+                sym = mode.to_sym
+                SPEECH_MODES.include?(sym) ? sym : :narrating
+              end
+
+              def resolve_voice(voice)
+                sym = voice.to_sym
+                VOICE_TYPES.include?(sym) ? sym : :rational
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+          module Runners
+            module InnerSpeech
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def inner_speak(content:, mode: :narrating, topic: :general, **)
+                utterance = voice.speak(content: content, mode: mode, topic: topic)
+                return { success: false, reason: :stream_full } unless utterance
+
+                { success: true, utterance_id: utterance.id, mode: utterance.mode }
+              end
+
+              def inner_plan(content:, topic: :general, **)
+                utterance = voice.plan(content: content, topic: topic)
+                return { success: false, reason: :stream_full } unless utterance
+
+                { success: true, utterance_id: utterance.id }
+              end
+
+              def inner_question(content:, topic: :general, **)
+                utterance = voice.question(content: content, topic: topic)
+                return { success: false, reason: :stream_full } unless utterance
+
+                { success: true, utterance_id: utterance.id }
+              end
+
+              def inner_debate(content_a:, content_b:, topic: :general, **)
+                results = voice.debate(content_a: content_a, content_b: content_b, topic: topic)
+                { success: true, utterances: results.map(&:id), count: results.size }
+              end
+
+              def switch_inner_voice(voice_type:, **)
+                result = voice.switch_voice(voice: voice_type)
+                return { success: false, reason: :invalid_voice } unless result
+
+                { success: true, active_voice: result }
+              end
+
+              def inner_interrupt(content:, **)
+                utterance = voice.interrupt(content: content)
+                return { success: false, reason: :stream_full } unless utterance
+
+                { success: true, utterance_id: utterance.id }
+              end
+
+              def break_inner_rumination(redirect_topic: :general, **)
+                result = voice.break_rumination(redirect_topic: redirect_topic)
+                { success: true, rumination_broken: result }
+              end
+
+              def recent_inner_speech(count: 5, **)
+                speech = voice.recent_speech(count: count)
+                { success: true, utterances: speech, count: speech.size }
+              end
+
+              def inner_narrative(**)
+                { success: true, narrative: voice.narrative, condensed: voice.condensed_narrative }
+              end
+
+              def update_inner_speech(**)
+                result = voice.tick
+                { success: true }.merge(result)
+              end
+
+              def inner_speech_stats(**)
+                { success: true }.merge(voice.to_h)
+              end
+
+              private
+
+              def voice
+                @voice ||= Helpers::InnerVoice.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/inner_speech/version'
+require 'legion/extensions/agentic/language/inner_speech/helpers/constants'
+require 'legion/extensions/agentic/language/inner_speech/helpers/utterance'
+require 'legion/extensions/agentic/language/inner_speech/helpers/inner_voice'
+require 'legion/extensions/agentic/language/inner_speech/helpers/speech_stream'
+require 'legion/extensions/agentic/language/inner_speech/runners/inner_speech'
+require 'legion/extensions/agentic/language/inner_speech/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module InnerSpeech
+        end
+      end
+    end
+  end
+end