lex-agentic-language 0.1.0

data/spec/legion/extensions/agentic/language/inner_speech/helpers/inner_voice_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::InnerSpeech::Helpers::InnerVoice do
+  subject(:iv) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts with rational voice' do
+      expect(iv.active_voice).to eq(:rational)
+    end
+
+    it 'has an empty stream' do
+      expect(iv.stream.size).to eq(0)
+    end
+  end
+
+  describe '#speak' do
+    it 'adds an utterance with active voice' do
+      u = iv.speak(content: 'hello world')
+      expect(u.voice).to eq(:rational)
+      expect(u.content).to eq('hello world')
+    end
+
+    it 'uses the specified mode' do
+      u = iv.speak(content: 'planning step', mode: :planning)
+      expect(u.mode).to eq(:planning)
+    end
+
+    it 'records event in history' do
+      iv.speak(content: 'test')
+      expect(iv.history.size).to eq(1)
+    end
+  end
+
+  describe '#switch_voice' do
+    it 'changes the active voice' do
+      iv.switch_voice(voice: :emotional)
+      expect(iv.active_voice).to eq(:emotional)
+    end
+
+    it 'rejects invalid voice' do
+      result = iv.switch_voice(voice: :bogus)
+      expect(result).to be_nil
+      expect(iv.active_voice).to eq(:rational)
+    end
+
+    it 'records event in history' do
+      iv.switch_voice(voice: :bold)
+      expect(iv.history.last[:type]).to eq(:switch_voice)
+    end
+  end
+
+  describe 'convenience methods' do
+    it '#plan creates a planning utterance' do
+      u = iv.plan(content: 'step one: gather data')
+      expect(u.mode).to eq(:planning)
+    end
+
+    it '#rehearse creates a rehearsal utterance' do
+      u = iv.rehearse(content: 'practice the response')
+      expect(u.mode).to eq(:rehearsal)
+    end
+
+    it '#question creates a questioning utterance' do
+      u = iv.question(content: 'what if this fails?')
+      expect(u.mode).to eq(:questioning)
+    end
+
+    it '#evaluate creates an evaluating utterance' do
+      u = iv.evaluate(content: 'that went well')
+      expect(u.mode).to eq(:evaluating)
+    end
+
+    it '#warn creates a high-urgency warning' do
+      u = iv.warn(content: 'careful with that')
+      expect(u.mode).to eq(:warning)
+      expect(u.urgency).to eq(0.8)
+    end
+  end
+
+  describe '#debate' do
+    it 'creates two utterances with different voices' do
+      results = iv.debate(
+        content_a: 'we should proceed',
+        content_b: 'but what about the risks?',
+        topic:     :decision
+      )
+      expect(results.size).to eq(2)
+      expect(results.first.voice).to eq(:bold)
+      expect(results.last.voice).to eq(:cautious)
+    end
+
+    it 'restores the original voice after debate' do
+      iv.switch_voice(voice: :curious)
+      iv.debate(content_a: 'yes', content_b: 'no')
+      expect(iv.active_voice).to eq(:curious)
+    end
+  end
+
+  describe '#interrupt' do
+    it 'adds a high-urgency interruption' do
+      u = iv.interrupt(content: 'STOP!')
+      expect(u.urgency).to eq(0.9)
+    end
+
+    it 'records event in history' do
+      iv.interrupt(content: 'alert')
+      expect(iv.history.any? { |e| e[:type] == :interrupt }).to be true
+    end
+  end
+
+  describe '#set_speed' do
+    it 'sets automatic speed' do
+      iv.set_speed(mode: :automatic)
+      expect(iv.to_h[:speed]).to eq(3)
+    end
+
+    it 'sets controlled speed' do
+      iv.set_speed(mode: :controlled)
+      expect(iv.to_h[:speed]).to eq(1)
+    end
+
+    it 'sets egocentric speed' do
+      iv.set_speed(mode: :egocentric)
+      expect(iv.to_h[:speed]).to eq(0.5)
+    end
+  end
+
+  describe '#ruminating?' do
+    it 'delegates to stream' do
+      4.times { iv.speak(content: 'same worry', topic: :anxiety) }
+      expect(iv.ruminating?).to be true
+    end
+  end
+
+  describe '#break_rumination' do
+    it 'redirects when ruminating' do
+      4.times { iv.speak(content: 'same thing', topic: :worry) }
+      result = iv.break_rumination(redirect_topic: :work)
+      expect(result).to be true
+    end
+
+    it 'returns false when not ruminating' do
+      result = iv.break_rumination(redirect_topic: :work)
+      expect(result).to be false
+    end
+  end
+
+  describe '#recent_speech' do
+    it 'returns recent utterances' do
+      3.times { |i| iv.speak(content: "thought #{i}") }
+      result = iv.recent_speech(count: 2)
+      expect(result.size).to eq(2)
+    end
+  end
+
+  describe '#narrative and #condensed_narrative' do
+    it 'returns full narrative' do
+      iv.speak(content: 'first')
+      iv.speak(content: 'second')
+      expect(iv.narrative).to eq('first second')
+    end
+
+    it 'returns condensed narrative from salient utterances' do
+      iv.speak(content: 'this is a longer thought that will be condensed', salience: 0.8)
+      expect(iv.condensed_narrative).to be_a(String)
+    end
+  end
+
+  describe '#tick' do
+    it 'decays stream and returns status' do
+      iv.speak(content: 'test')
+      result = iv.tick
+      expect(result).to include(:active_voice, :speed)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      expect(iv.to_h).to include(
+        :active_voice, :speed, :stream_size, :ruminating,
+        :total_utterances, :history_size
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/inner_speech/helpers/speech_stream_spec.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::InnerSpeech::Helpers::SpeechStream do
+  subject(:stream) { described_class.new }
+
+  describe '#append' do
+    it 'adds an utterance' do
+      u = stream.append(content: 'thinking about lunch')
+      expect(u).to be_a(Legion::Extensions::Agentic::Language::InnerSpeech::Helpers::Utterance)
+      expect(stream.size).to eq(1)
+    end
+
+    it 'enforces MAX_STREAM_LENGTH' do
+      100.times { |i| stream.append(content: "thought #{i}") }
+      expect(stream.append(content: 'overflow')).to be_nil
+    end
+  end
+
+  describe '#current' do
+    it 'returns the most recent utterance' do
+      stream.append(content: 'first')
+      stream.append(content: 'second')
+      expect(stream.current.content).to eq('second')
+    end
+
+    it 'returns nil when empty' do
+      expect(stream.current).to be_nil
+    end
+  end
+
+  describe '#recent' do
+    it 'returns last N utterances' do
+      5.times { |i| stream.append(content: "thought #{i}") }
+      result = stream.recent(count: 3)
+      expect(result.size).to eq(3)
+    end
+  end
+
+  describe '#by_mode' do
+    it 'filters by mode' do
+      stream.append(content: 'plan A', mode: :planning)
+      stream.append(content: 'what is that?', mode: :questioning)
+      expect(stream.by_mode(mode: :planning).size).to eq(1)
+    end
+  end
+
+  describe '#by_voice' do
+    it 'filters by voice' do
+      stream.append(content: 'careful now', voice: :cautious)
+      stream.append(content: 'go for it', voice: :bold)
+      expect(stream.by_voice(voice: :bold).size).to eq(1)
+    end
+  end
+
+  describe '#by_topic' do
+    it 'filters by topic' do
+      stream.append(content: 'safe code', topic: :safety)
+      stream.append(content: 'fast code', topic: :performance)
+      expect(stream.by_topic(topic: :safety).size).to eq(1)
+    end
+  end
+
+  describe '#salient' do
+    it 'returns salient utterances' do
+      stream.append(content: 'important', salience: 0.8)
+      stream.append(content: 'fading', salience: 0.1)
+      expect(stream.salient.size).to eq(1)
+    end
+  end
+
+  describe '#urgent' do
+    it 'returns urgent utterances' do
+      stream.append(content: 'critical', urgency: 0.9)
+      stream.append(content: 'calm', urgency: 0.2)
+      expect(stream.urgent.size).to eq(1)
+    end
+  end
+
+  describe '#ruminating?' do
+    it 'returns false with few utterances' do
+      stream.append(content: 'one', topic: :worry)
+      expect(stream.ruminating?).to be false
+    end
+
+    it 'detects rumination on same topic' do
+      4.times { stream.append(content: 'still worried', topic: :worry) }
+      expect(stream.ruminating?).to be true
+    end
+
+    it 'returns false for varied topics' do
+      stream.append(content: 'a', topic: :work)
+      stream.append(content: 'b', topic: :food)
+      stream.append(content: 'c', topic: :fun)
+      expect(stream.ruminating?).to be false
+    end
+  end
+
+  describe '#rumination_topic' do
+    it 'returns the repeated topic' do
+      4.times { stream.append(content: 'same thing', topic: :anxiety) }
+      expect(stream.rumination_topic).to eq(:anxiety)
+    end
+
+    it 'returns nil when not ruminating' do
+      expect(stream.rumination_topic).to be_nil
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays and prunes stale utterances' do
+      stream.append(content: 'will fade', salience: 0.06)
+      stream.decay_all
+      expect(stream.size).to eq(0)
+    end
+  end
+
+  describe '#interrupt' do
+    it 'adds a high-urgency utterance' do
+      u = stream.interrupt(content: 'ALERT!')
+      expect(u.urgency).to eq(0.9)
+      expect(u.mode).to eq(:warning)
+    end
+  end
+
+  describe '#condensed_stream' do
+    it 'returns condensed versions of salient utterances' do
+      stream.append(content: 'I need to think about this carefully', salience: 0.8)
+      condensed = stream.condensed_stream
+      expect(condensed).to be_an(Array)
+      expect(condensed.first.split.size).to be < 'I need to think about this carefully'.split.size
+    end
+  end
+
+  describe '#narrative' do
+    it 'joins all utterances into a string' do
+      stream.append(content: 'first thought')
+      stream.append(content: 'second thought')
+      expect(stream.narrative).to eq('first thought second thought')
+    end
+  end
+
+  describe '#clear' do
+    it 'empties the stream' do
+      stream.append(content: 'test')
+      stream.clear
+      expect(stream.size).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      expect(stream.to_h).to include(
+        :size, :total_generated, :ruminating, :rumination_topic,
+        :salient_count, :urgent_count, :mode_distribution
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/inner_speech/helpers/utterance_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::InnerSpeech::Helpers::Utterance do
+  subject(:utterance) do
+    described_class.new(id: :utt_one, content: 'I should check the data first')
+  end
+
+  describe '#initialize' do
+    it 'sets content and defaults' do
+      expect(utterance.content).to eq('I should check the data first')
+      expect(utterance.mode).to eq(:narrating)
+      expect(utterance.voice).to eq(:rational)
+      expect(utterance.topic).to eq(:general)
+      expect(utterance.urgency).to eq(0.5)
+      expect(utterance.salience).to eq(0.5)
+    end
+
+    it 'accepts custom attributes' do
+      u = described_class.new(
+        id:               :utt_two,
+        content:          'danger ahead',
+        mode:             :warning,
+        voice:            :cautious,
+        topic:            :safety,
+        urgency:          0.9,
+        salience:         0.8,
+        source_subsystem: :emotion
+      )
+      expect(u.mode).to eq(:warning)
+      expect(u.voice).to eq(:cautious)
+      expect(u.topic).to eq(:safety)
+      expect(u.urgency).to eq(0.9)
+      expect(u.source_subsystem).to eq(:emotion)
+    end
+
+    it 'defaults invalid mode to :narrating' do
+      u = described_class.new(id: :x, content: 'test', mode: :bogus)
+      expect(u.mode).to eq(:narrating)
+    end
+
+    it 'defaults invalid voice to :rational' do
+      u = described_class.new(id: :x, content: 'test', voice: :bogus)
+      expect(u.voice).to eq(:rational)
+    end
+
+    it 'clamps urgency' do
+      u = described_class.new(id: :x, content: 'test', urgency: 2.0)
+      expect(u.urgency).to eq(1.0)
+    end
+  end
+
+  describe '#condensed_content' do
+    it 'returns abbreviated version' do
+      condensed = utterance.condensed_content
+      expect(condensed.split.size).to be < utterance.content.split.size
+    end
+
+    it 'keeps at least one word' do
+      u = described_class.new(id: :x, content: 'hello')
+      expect(u.condensed_content).to eq('hello')
+    end
+  end
+
+  describe '#urgent?' do
+    it 'returns true for high urgency' do
+      u = described_class.new(id: :x, content: 'test', urgency: 0.8)
+      expect(u.urgent?).to be true
+    end
+
+    it 'returns false for low urgency' do
+      u = described_class.new(id: :x, content: 'test', urgency: 0.2)
+      expect(u.urgent?).to be false
+    end
+  end
+
+  describe '#background?' do
+    it 'returns true for very low urgency' do
+      u = described_class.new(id: :x, content: 'test', urgency: 0.1)
+      expect(u.background?).to be true
+    end
+  end
+
+  describe '#decay_salience!' do
+    it 'reduces salience' do
+      original = utterance.salience
+      utterance.decay_salience!
+      expect(utterance.salience).to be < original
+    end
+
+    it 'does not go below floor' do
+      20.times { utterance.decay_salience! }
+      expect(utterance.salience).to be >= 0.01
+    end
+  end
+
+  describe '#salient?' do
+    it 'returns true when salience is high' do
+      expect(utterance.salient?).to be true
+    end
+
+    it 'returns false after heavy decay' do
+      15.times { utterance.decay_salience! }
+      expect(utterance.salient?).to be false
+    end
+  end
+
+  describe '#urgency_label' do
+    it 'returns a symbol' do
+      expect(utterance.urgency_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      expect(utterance.to_h).to include(
+        :id, :content, :condensed, :mode, :voice, :topic,
+        :urgency, :salience, :source_subsystem, :urgency_label
+      )
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/inner_speech/runners/inner_speech_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::InnerSpeech::Runners::InnerSpeech do
+  let(:host) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  describe '#inner_speak' do
+    it 'creates an utterance' do
+      result = host.inner_speak(content: 'testing', mode: :planning)
+      expect(result[:success]).to be true
+      expect(result[:utterance_id]).to be_a(Symbol)
+      expect(result[:mode]).to eq(:planning)
+    end
+  end
+
+  describe '#inner_plan' do
+    it 'creates a planning utterance' do
+      result = host.inner_plan(content: 'step one')
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#inner_question' do
+    it 'creates a questioning utterance' do
+      result = host.inner_question(content: 'what if?')
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#inner_debate' do
+    it 'creates a two-sided debate' do
+      result = host.inner_debate(content_a: 'yes', content_b: 'no', topic: :choice)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+  end
+
+  describe '#switch_inner_voice' do
+    it 'switches voice' do
+      result = host.switch_inner_voice(voice_type: :emotional)
+      expect(result[:success]).to be true
+      expect(result[:active_voice]).to eq(:emotional)
+    end
+
+    it 'rejects invalid voice' do
+      result = host.switch_inner_voice(voice_type: :bogus)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#inner_interrupt' do
+    it 'creates an interruption' do
+      result = host.inner_interrupt(content: 'ALERT')
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#break_inner_rumination' do
+    it 'attempts to break rumination' do
+      result = host.break_inner_rumination(redirect_topic: :work)
+      expect(result[:success]).to be true
+      expect(result[:rumination_broken]).to be false
+    end
+  end
+
+  describe '#recent_inner_speech' do
+    it 'returns recent speech' do
+      host.inner_speak(content: 'hello')
+      result = host.recent_inner_speech(count: 5)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#inner_narrative' do
+    it 'returns the narrative' do
+      host.inner_speak(content: 'first thought')
+      result = host.inner_narrative
+      expect(result[:success]).to be true
+      expect(result[:narrative]).to include('first thought')
+    end
+  end
+
+  describe '#update_inner_speech' do
+    it 'ticks the inner voice' do
+      result = host.update_inner_speech
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#inner_speech_stats' do
+    it 'returns stats' do
+      result = host.inner_speech_stats
+      expect(result[:success]).to be true
+      expect(result).to have_key(:active_voice)
+      expect(result).to have_key(:stream_size)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/language/client_spec.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Language::Client do
+  describe '#initialize' do
+    it 'creates a default lexicon' do
+      client = described_class.new
+      expect(client.lexicon).to be_a(Legion::Extensions::Agentic::Language::Language::Helpers::Lexicon)
+    end
+
+    it 'accepts an injected lexicon' do
+      lexicon = Legion::Extensions::Agentic::Language::Language::Helpers::Lexicon.new
+      client = described_class.new(lexicon: lexicon)
+      expect(client.lexicon).to equal(lexicon)
+    end
+  end
+
+  it 'includes Runners::Language' do
+    expect(described_class.ancestors).to include(Legion::Extensions::Agentic::Language::Language::Runners::Language)
+  end
+end

data/spec/legion/extensions/agentic/language/language/helpers/constants_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Language::Helpers::Constants do
+  it 'defines MAX_TRACES_PER_SUMMARY' do
+    expect(described_class::MAX_TRACES_PER_SUMMARY).to eq(50)
+  end
+
+  it 'defines MIN_SUMMARY_STRENGTH' do
+    expect(described_class::MIN_SUMMARY_STRENGTH).to eq(0.1)
+  end
+
+  it 'defines DEPTHS as frozen array of symbols' do
+    expect(described_class::DEPTHS).to eq(%i[brief standard detailed])
+    expect(described_class::DEPTHS).to be_frozen
+  end
+
+  it 'defines TYPE_PRIORITY as frozen hash' do
+    expect(described_class::TYPE_PRIORITY).to include(firmware: 0, sensory: 6)
+    expect(described_class::TYPE_PRIORITY).to be_frozen
+  end
+
+  it 'defines knowledge thresholds' do
+    expect(described_class::KNOWLEDGE_RICH).to eq(10)
+    expect(described_class::KNOWLEDGE_MODERATE).to eq(5)
+    expect(described_class::KNOWLEDGE_SPARSE).to eq(1)
+  end
+
+  it 'defines RESOLUTION_THRESHOLD' do
+    expect(described_class::RESOLUTION_THRESHOLD).to eq(3)
+  end
+end