lex-agentic-language 0.1.0

data/spec/legion/extensions/agentic/language/grammar/helpers/construction_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar::Helpers::Construction do
+  subject(:construction) do
+    described_class.new(
+      form:            'the cat',
+      meaning:         'definite feline entity',
+      expression_type: :nominal,
+      domain:          'linguistics'
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(construction.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores form and meaning' do
+      expect(construction.form).to eq('the cat')
+      expect(construction.meaning).to eq('definite feline entity')
+    end
+
+    it 'symbolizes expression_type' do
+      expect(construction.expression_type).to eq(:nominal)
+    end
+
+    it 'defaults activation to DEFAULT_ACTIVATION' do
+      expect(construction.activation).to eq(0.3)
+    end
+
+    it 'starts with zero usage_count' do
+      expect(construction.usage_count).to eq(0)
+    end
+
+    it 'sets domain' do
+      expect(construction.domain).to eq('linguistics')
+    end
+
+    it 'sets created_at to a Time' do
+      expect(construction.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#use!' do
+    it 'increments usage_count' do
+      construction.use!
+      expect(construction.usage_count).to eq(1)
+    end
+
+    it 'boosts activation by ACTIVATION_BOOST' do
+      construction.use!
+      expect(construction.activation).to be_within(0.001).of(0.4)
+    end
+
+    it 'caps activation at 1.0' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.95)
+      c.use!
+      expect(c.activation).to eq(1.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(construction.use!).to eq(construction)
+    end
+
+    it 'accumulates usage on repeated calls' do
+      5.times { construction.use! }
+      expect(construction.usage_count).to eq(5)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces activation by ACTIVATION_DECAY' do
+      construction.decay!
+      expect(construction.activation).to be_within(0.001).of(0.28)
+    end
+
+    it 'floors activation at 0.0' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.01)
+      c.decay!
+      expect(c.activation).to eq(0.0)
+    end
+
+    it 'returns self for chaining' do
+      expect(construction.decay!).to eq(construction)
+    end
+  end
+
+  describe '#entrenched?' do
+    it 'returns false when activation is below threshold' do
+      expect(construction.entrenched?).to be false
+    end
+
+    it 'returns true when activation reaches ENTRENCHMENT_THRESHOLD' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.8)
+      expect(c.entrenched?).to be true
+    end
+
+    it 'returns true when activation exceeds threshold' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.95)
+      expect(c.entrenched?).to be true
+    end
+
+    it 'becomes entrenched after enough use! calls' do
+      c = described_class.new(form: 'run', meaning: 'motion', expression_type: :relational, domain: 'motion')
+      # Start at 0.3, each use! adds 0.1 → need 5 uses to reach 0.8
+      5.times { c.use! }
+      expect(c.entrenched?).to be true
+    end
+  end
+
+  describe '#activation_label' do
+    it 'returns :ad_hoc for low activation' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.1)
+      expect(c.activation_label).to eq(:ad_hoc)
+    end
+
+    it 'returns :novel for activation 0.3' do
+      expect(construction.activation_label).to eq(:novel)
+    end
+
+    it 'returns :familiar for activation 0.5' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.5)
+      expect(c.activation_label).to eq(:familiar)
+    end
+
+    it 'returns :conventional for activation 0.7' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.7)
+      expect(c.activation_label).to eq(:conventional)
+    end
+
+    it 'returns :entrenched for activation >= 0.8' do
+      c = described_class.new(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.8)
+      expect(c.activation_label).to eq(:entrenched)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = construction.to_h
+      expect(h).to include(:id, :form, :meaning, :expression_type, :activation, :usage_count, :domain, :entrenched,
+                           :activation_label, :created_at)
+    end
+
+    it 'reflects current state' do
+      construction.use!
+      h = construction.to_h
+      expect(h[:usage_count]).to eq(1)
+      expect(h[:activation]).to be > 0.3
+    end
+
+    it 'includes entrenched flag' do
+      expect(construction.to_h[:entrenched]).to be false
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/grammar/helpers/grammar_engine_spec.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar::Helpers::GrammarEngine do
+  subject(:engine) { described_class.new }
+
+  let(:construction_params) do
+    { form: 'the bird', meaning: 'definite avian', expression_type: :nominal, domain: 'nature' }
+  end
+
+  let(:construal_params) do
+    { scene: 'bird on branch', perspective: 'ground-level', figure: 'bird', ground: 'branch' }
+  end
+
+  describe '#create_construction' do
+    it 'returns a Construction instance' do
+      c = engine.create_construction(**construction_params)
+      expect(c).to be_a(Legion::Extensions::Agentic::Language::Grammar::Helpers::Construction)
+    end
+
+    it 'stores the construction internally' do
+      engine.create_construction(**construction_params)
+      expect(engine.to_h[:constructions_count]).to eq(1)
+    end
+
+    it 'assigns correct attributes' do
+      c = engine.create_construction(**construction_params)
+      expect(c.form).to eq('the bird')
+      expect(c.meaning).to eq('definite avian')
+      expect(c.expression_type).to eq(:nominal)
+      expect(c.domain).to eq('nature')
+    end
+  end
+
+  describe '#create_construal' do
+    it 'returns a Construal instance' do
+      c = engine.create_construal(**construal_params)
+      expect(c).to be_a(Legion::Extensions::Agentic::Language::Grammar::Helpers::Construal)
+    end
+
+    it 'stores the construal' do
+      engine.create_construal(**construal_params)
+      expect(engine.to_h[:construals_count]).to eq(1)
+    end
+
+    it 'forwards all keyword args' do
+      c = engine.create_construal(**construal_params, specificity: :detailed, scope: :global, dynamicity: 0.8)
+      expect(c.specificity).to eq(:detailed)
+      expect(c.scope).to eq(:global)
+      expect(c.dynamicity).to eq(0.8)
+    end
+  end
+
+  describe '#use_construction' do
+    it 'returns nil for unknown id' do
+      expect(engine.use_construction(construction_id: 'nonexistent')).to be_nil
+    end
+
+    it 'increments usage_count' do
+      c = engine.create_construction(**construction_params)
+      engine.use_construction(construction_id: c.id)
+      expect(c.usage_count).to eq(1)
+    end
+
+    it 'returns the updated construction' do
+      c = engine.create_construction(**construction_params)
+      result = engine.use_construction(construction_id: c.id)
+      expect(result).to eq(c)
+    end
+  end
+
+  describe '#construals_for_scene' do
+    it 'returns empty array when no construals exist' do
+      expect(engine.construals_for_scene(scene: 'nothing')).to eq([])
+    end
+
+    it 'returns only construals matching the scene' do
+      engine.create_construal(**construal_params)
+      engine.create_construal(scene: 'other scene', perspective: 'p', figure: 'f', ground: 'g')
+      results = engine.construals_for_scene(scene: 'bird on branch')
+      expect(results.size).to eq(1)
+      expect(results.first.scene).to eq('bird on branch')
+    end
+
+    it 'returns multiple construals for same scene (different perspectives)' do
+      engine.create_construal(**construal_params)
+      engine.create_construal(scene: 'bird on branch', perspective: 'aerial', figure: 'bird', ground: 'branch')
+      results = engine.construals_for_scene(scene: 'bird on branch')
+      expect(results.size).to eq(2)
+    end
+  end
+
+  describe '#entrenched_constructions' do
+    it 'returns empty when none are entrenched' do
+      engine.create_construction(**construction_params)
+      expect(engine.entrenched_constructions).to be_empty
+    end
+
+    it 'returns constructions once they reach entrenchment threshold via use!' do
+      c = engine.create_construction(**construction_params)
+      5.times { engine.use_construction(construction_id: c.id) }
+      expect(engine.entrenched_constructions).to include(c)
+    end
+  end
+
+  describe '#constructions_by_domain' do
+    it 'returns only constructions in the specified domain' do
+      engine.create_construction(**construction_params)
+      engine.create_construction(form: 'run', meaning: 'motion', expression_type: :relational, domain: 'motion')
+      results = engine.constructions_by_domain(domain: 'nature')
+      expect(results.size).to eq(1)
+      expect(results.first.domain).to eq('nature')
+    end
+  end
+
+  describe '#constructions_by_type' do
+    it 'returns only constructions with the specified expression_type' do
+      engine.create_construction(**construction_params) # :nominal
+      engine.create_construction(form: 'runs', meaning: 'action', expression_type: :relational, domain: 'action')
+      results = engine.constructions_by_type(expression_type: :nominal)
+      expect(results.size).to eq(1)
+      expect(results.first.expression_type).to eq(:nominal)
+    end
+
+    it 'accepts string type and symbolizes it' do
+      engine.create_construction(**construction_params)
+      results = engine.constructions_by_type(expression_type: 'nominal')
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#most_used' do
+    it 'returns constructions sorted by usage_count desc' do
+      c1 = engine.create_construction(**construction_params)
+      c2 = engine.create_construction(form: 'runs', meaning: 'action', expression_type: :relational, domain: 'action')
+      3.times { engine.use_construction(construction_id: c1.id) }
+      engine.use_construction(construction_id: c2.id)
+      top = engine.most_used(limit: 2)
+      expect(top.first).to eq(c1)
+      expect(top.last).to eq(c2)
+    end
+
+    it 'respects the limit' do
+      5.times do |i|
+        engine.create_construction(form: "form#{i}", meaning: "m#{i}", expression_type: :nominal, domain: 'd')
+      end
+      expect(engine.most_used(limit: 3).size).to eq(3)
+    end
+  end
+
+  describe '#most_activated' do
+    it 'returns constructions sorted by activation desc' do
+      c1 = engine.create_construction(**construction_params)
+      c2 = engine.create_construction(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.8)
+      top = engine.most_activated(limit: 2)
+      expect(top.first).to eq(c2)
+      expect(top.last).to eq(c1)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces activation of all constructions' do
+      c = engine.create_construction(**construction_params)
+      original = c.activation
+      engine.decay_all
+      expect(c.activation).to be < original
+    end
+  end
+
+  describe '#prune_inactive' do
+    it 'removes constructions with activation <= 0.05' do
+      c1 = engine.create_construction(**construction_params) # activation 0.3 — kept
+      c2 = engine.create_construction(form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd', activation: 0.05)
+      engine.prune_inactive
+      expect(engine.to_h[:constructions_count]).to eq(1)
+      expect(engine.constructions_by_domain(domain: 'nature')).to include(c1)
+      expect(engine.constructions_by_domain(domain: 'd')).not_to include(c2)
+    end
+
+    it 'does not remove constructions with activation above 0.05' do
+      engine.create_construction(**construction_params)
+      engine.prune_inactive
+      expect(engine.to_h[:constructions_count]).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns counts' do
+      engine.create_construction(**construction_params)
+      engine.create_construal(**construal_params)
+      h = engine.to_h
+      expect(h[:constructions_count]).to eq(1)
+      expect(h[:construals_count]).to eq(1)
+      expect(h[:entrenched_count]).to eq(0)
+    end
+  end
+
+  describe 'entrenchment via repeated use' do
+    it 'tracks a construction becoming entrenched after 5 uses from default activation' do
+      c = engine.create_construction(form: 'be', meaning: 'existence', expression_type: :relational, domain: 'core')
+      expect(c.entrenched?).to be false
+      5.times { engine.use_construction(construction_id: c.id) }
+      expect(c.entrenched?).to be true
+      expect(engine.entrenched_constructions).to include(c)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/grammar/runners/cognitive_grammar_spec.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::Grammar::Runners::CognitiveGrammar do
+  subject(:runner) do
+    Class.new do
+      include Legion::Extensions::Agentic::Language::Grammar::Runners::CognitiveGrammar
+
+      def engine
+        @engine ||= Legion::Extensions::Agentic::Language::Grammar::Helpers::GrammarEngine.new
+      end
+    end.new
+  end
+
+  let(:construction_params) do
+    { form: 'she runs', meaning: 'agent motion predication', expression_type: :clausal, domain: 'motion' }
+  end
+
+  describe '#create_grammar_construction' do
+    it 'returns a hash with construction data' do
+      result = runner.create_grammar_construction(**construction_params)
+      expect(result).to include(:id, :form, :meaning, :expression_type, :activation, :usage_count)
+    end
+
+    it 'includes the provided form' do
+      result = runner.create_grammar_construction(**construction_params)
+      expect(result[:form]).to eq('she runs')
+    end
+
+    it 'starts with default activation' do
+      result = runner.create_grammar_construction(**construction_params)
+      expect(result[:activation]).to eq(0.3)
+    end
+  end
+
+  describe '#create_grammar_construal' do
+    it 'returns a hash with construal data' do
+      result = runner.create_grammar_construal(
+        scene: 'bird on branch', perspective: 'worm-eye', figure: 'bird', ground: 'branch'
+      )
+      expect(result).to include(:id, :scene, :perspective, :figure, :ground, :specificity, :scope, :dynamicity)
+    end
+
+    it 'uses defaults for optional params' do
+      result = runner.create_grammar_construal(
+        scene: 's', perspective: 'p', figure: 'f', ground: 'g'
+      )
+      expect(result[:specificity]).to eq(:intermediate)
+      expect(result[:scope]).to eq(:local)
+      expect(result[:dynamicity]).to eq(0.5)
+    end
+
+    it 'respects provided specificity, scope, dynamicity' do
+      result = runner.create_grammar_construal(
+        scene: 's', perspective: 'p', figure: 'f', ground: 'g',
+        specificity: :detailed, scope: :global, dynamicity: 0.9
+      )
+      expect(result[:specificity]).to eq(:detailed)
+      expect(result[:scope]).to eq(:global)
+      expect(result[:dynamicity]).to eq(0.9)
+    end
+  end
+
+  describe '#use_grammar_construction' do
+    it 'returns found: false for unknown id' do
+      result = runner.use_grammar_construction(construction_id: 'nonexistent')
+      expect(result[:found]).to be false
+    end
+
+    it 'returns found: true with updated construction' do
+      created = runner.create_grammar_construction(**construction_params)
+      result  = runner.use_grammar_construction(construction_id: created[:id])
+      expect(result[:found]).to be true
+      expect(result[:construction][:usage_count]).to eq(1)
+    end
+
+    it 'increases activation on use' do
+      created = runner.create_grammar_construction(**construction_params)
+      result  = runner.use_grammar_construction(construction_id: created[:id])
+      expect(result[:construction][:activation]).to be > created[:activation]
+    end
+  end
+
+  describe '#construals_for_scene_report' do
+    it 'returns empty construals for unknown scene' do
+      result = runner.construals_for_scene_report(scene: 'unknown')
+      expect(result[:count]).to eq(0)
+      expect(result[:construals]).to eq([])
+    end
+
+    it 'returns matching construals' do
+      runner.create_grammar_construal(scene: 'cat on mat', perspective: 'p', figure: 'cat', ground: 'mat')
+      result = runner.construals_for_scene_report(scene: 'cat on mat')
+      expect(result[:count]).to eq(1)
+      expect(result[:construals].first[:figure]).to eq('cat')
+    end
+
+    it 'includes the scene in the result' do
+      result = runner.construals_for_scene_report(scene: 'test scene')
+      expect(result[:scene]).to eq('test scene')
+    end
+  end
+
+  describe '#entrenched_constructions_report' do
+    it 'returns empty when none entrenched' do
+      runner.create_grammar_construction(**construction_params)
+      result = runner.entrenched_constructions_report
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'returns entrenched constructions after enough uses' do
+      created = runner.create_grammar_construction(**construction_params)
+      5.times { runner.use_grammar_construction(construction_id: created[:id]) }
+      result = runner.entrenched_constructions_report
+      expect(result[:count]).to eq(1)
+      expect(result[:constructions].first[:entrenched]).to be true
+    end
+  end
+
+  describe '#constructions_by_domain_report' do
+    it 'returns constructions for the given domain' do
+      runner.create_grammar_construction(**construction_params) # domain: 'motion'
+      runner.create_grammar_construction(form: 'the', meaning: 'def', expression_type: :nominal, domain: 'grammar')
+      result = runner.constructions_by_domain_report(domain: 'motion')
+      expect(result[:domain]).to eq('motion')
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#most_used_constructions' do
+    it 'returns constructions sorted by usage_count' do
+      c1 = runner.create_grammar_construction(**construction_params)
+      c2 = runner.create_grammar_construction(form: 'the', meaning: 'def', expression_type: :nominal, domain: 'grammar')
+      3.times { runner.use_grammar_construction(construction_id: c1[:id]) }
+      runner.use_grammar_construction(construction_id: c2[:id])
+      result = runner.most_used_constructions(limit: 2)
+      expect(result[:constructions].first[:form]).to eq('she runs')
+    end
+
+    it 'defaults limit to 5' do
+      result = runner.most_used_constructions
+      expect(result[:limit]).to eq(5)
+    end
+  end
+
+  describe '#update_cognitive_grammar' do
+    it 'returns stats with pruned count' do
+      runner.create_grammar_construction(**construction_params)
+      result = runner.update_cognitive_grammar
+      expect(result).to include(:pruned, :stats)
+      expect(result[:stats]).to include(:constructions_count, :construals_count)
+    end
+
+    it 'removes constructions whose activation decays to <= 0.05' do
+      # create with very low activation that will decay below threshold after one pass
+      c = runner.create_grammar_construction(
+        form: 'x', meaning: 'y', expression_type: :nominal, domain: 'd'
+      )
+      # Manually decay the underlying construction to near-zero
+      engine = runner.send(:engine)
+      const  = engine.instance_variable_get(:@constructions)[c[:id]]
+      const.instance_variable_set(:@activation, 0.05)
+      result = runner.update_cognitive_grammar
+      expect(result[:pruned]).to be >= 1
+    end
+  end
+
+  describe '#cognitive_grammar_stats' do
+    it 'returns hash with counts' do
+      runner.create_grammar_construction(**construction_params)
+      runner.create_grammar_construal(scene: 's', perspective: 'p', figure: 'f', ground: 'g')
+      stats = runner.cognitive_grammar_stats
+      expect(stats[:constructions_count]).to eq(1)
+      expect(stats[:construals_count]).to eq(1)
+    end
+  end
+
+  describe 'activation decay after update_cognitive_grammar' do
+    it 'reduces activation of all constructions' do
+      created = runner.create_grammar_construction(**construction_params)
+      original_activation = created[:activation]
+      runner.update_cognitive_grammar
+      runner.cognitive_grammar_stats
+      # activation should have decreased (decay was applied)
+      engine = runner.send(:engine)
+      const  = engine.instance_variable_get(:@constructions)[created[:id]]
+      expect(const.activation).to be < original_activation
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::InnerSpeech::Client do
+  subject(:client) { described_class.new }
+
+  it 'includes the InnerSpeech runner' do
+    expect(client).to respond_to(:inner_speak)
+  end
+
+  it 'accepts an injected voice' do
+    voice = Legion::Extensions::Agentic::Language::InnerSpeech::Helpers::InnerVoice.new
+    c = described_class.new(voice: voice)
+    expect(c.inner_speak(content: 'test')[:success]).to be true
+  end
+
+  it 'supports full conversation flow' do
+    client.inner_speak(content: 'hmm, what should I do?', mode: :questioning)
+    client.inner_plan(content: 'first, check the data')
+    client.inner_speak(content: 'that looks right', mode: :affirming)
+
+    stats = client.inner_speech_stats
+    expect(stats[:total_utterances]).to eq(3)
+
+    narrative = client.inner_narrative
+    expect(narrative[:narrative]).to include('check the data')
+  end
+
+  it 'supports debate and voice switching' do
+    client.switch_inner_voice(voice_type: :curious)
+    client.inner_debate(
+      content_a: 'this approach is fast',
+      content_b: 'but this approach is safe',
+      topic:     :architecture
+    )
+    stats = client.inner_speech_stats
+    expect(stats[:active_voice]).to eq(:curious)
+    expect(stats[:total_utterances]).to eq(2)
+  end
+end