lex-agentic-language 0.1.0

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Constants do
+  describe 'MAXIMS' do
+    it 'contains four Gricean maxims' do
+      expect(described_class::MAXIMS).to eq(%i[quality quantity relevance manner])
+    end
+  end
+
+  describe 'VIOLATION_TYPES' do
+    it 'contains expected violation types' do
+      expect(described_class::VIOLATION_TYPES).to include(:none, :flouting, :violating, :opting_out)
+    end
+  end
+
+  describe 'SPEECH_ACTS' do
+    it 'contains expected speech act types' do
+      expect(described_class::SPEECH_ACTS).to include(:assert, :question, :request, :promise, :warn, :inform, :suggest)
+    end
+  end
+
+  describe 'MAXIM_DESCRIPTIONS' do
+    it 'has a description for each maxim' do
+      described_class::MAXIMS.each do |maxim|
+        expect(described_class::MAXIM_DESCRIPTIONS[maxim]).to be_a(String)
+      end
+    end
+  end
+
+  describe '.valid_maxim?' do
+    it 'returns true for valid maxims' do
+      expect(described_class.valid_maxim?(:quality)).to be true
+      expect(described_class.valid_maxim?(:manner)).to be true
+    end
+
+    it 'returns false for invalid maxims' do
+      expect(described_class.valid_maxim?(:sincerity)).to be false
+    end
+  end
+
+  describe '.valid_violation_type?' do
+    it 'returns true for valid types' do
+      expect(described_class.valid_violation_type?(:flouting)).to be true
+    end
+
+    it 'returns false for invalid types' do
+      expect(described_class.valid_violation_type?(:unknown)).to be false
+    end
+  end
+
+  describe '.valid_speech_act?' do
+    it 'returns true for valid speech acts' do
+      expect(described_class.valid_speech_act?(:assert)).to be true
+    end
+
+    it 'returns false for invalid speech acts' do
+      expect(described_class.valid_speech_act?(:perform)).to be false
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'has correct confidence bounds' do
+      expect(described_class::CONFIDENCE_FLOOR).to eq(0.0)
+      expect(described_class::CONFIDENCE_CEILING).to eq(1.0)
+      expect(described_class::DEFAULT_CONFIDENCE).to eq(0.5)
+    end
+
+    it 'has positive reinforcement and decay rates' do
+      expect(described_class::REINFORCEMENT_RATE).to be > 0
+      expect(described_class::DECAY_RATE).to be > 0
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/pragmatic_inference/helpers/pragmatic_engine_spec.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::PragmaticEngine do
+  subject(:engine) { described_class.new }
+
+  let(:quality_violating_scores) { { quality: 0.1, quantity: 0.9, relevance: 0.8, manner: 0.9 } }
+  let(:compliant_scores)         { { quality: 0.9, quantity: 0.8, relevance: 0.9, manner: 0.95 } }
+
+  def add_utterance(speaker: 'alice', speech_act: :assert, scores: compliant_scores)
+    engine.analyze_utterance(
+      content:      'test utterance',
+      speaker:      speaker,
+      speech_act:   speech_act,
+      maxim_scores: scores
+    )
+  end
+
+  describe '#analyze_utterance' do
+    it 'stores and returns an Utterance' do
+      utterance = add_utterance
+      expect(utterance).to be_a(Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Utterance)
+    end
+
+    it 'stores the utterance by id' do
+      utterance = add_utterance
+      expect(engine.utterances[utterance.id]).to eq(utterance)
+    end
+
+    it 'records history entry' do
+      add_utterance
+      expect(engine.history).not_to be_empty
+    end
+
+    it 'trims utterances when at capacity' do
+      stub_const('Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Constants::MAX_UTTERANCES', 3)
+      3.times { add_utterance }
+      initial_ids = engine.utterances.keys.dup
+      add_utterance
+      expect(engine.utterances.keys).not_to include(initial_ids.first)
+    end
+  end
+
+  describe '#detect_violations' do
+    it 'returns violations for low-scoring maxims' do
+      utterance = add_utterance(scores: quality_violating_scores)
+      violations = engine.detect_violations(utterance_id: utterance.id)
+      expect(violations.map { |v| v[:maxim] }).to include(:quality)
+    end
+
+    it 'returns empty array for compliant utterance' do
+      utterance = add_utterance(scores: compliant_scores)
+      violations = engine.detect_violations(utterance_id: utterance.id)
+      expect(violations).to be_empty
+    end
+
+    it 'returns empty array for unknown utterance id' do
+      expect(engine.detect_violations(utterance_id: 'nonexistent')).to eq([])
+    end
+
+    it 'classifies severe violation as :violating' do
+      utterance = add_utterance(scores: { quality: 0.05, quantity: 0.9, relevance: 0.9, manner: 0.9 })
+      violations = engine.detect_violations(utterance_id: utterance.id)
+      quality_violation = violations.find { |v| v[:maxim] == :quality }
+      expect(quality_violation[:violation_type]).to eq(:violating)
+    end
+
+    it 'classifies moderate violation as :flouting' do
+      utterance = add_utterance(scores: { quality: 0.2, quantity: 0.9, relevance: 0.9, manner: 0.9 })
+      violations = engine.detect_violations(utterance_id: utterance.id)
+      quality_violation = violations.find { |v| v[:maxim] == :quality }
+      expect(quality_violation[:violation_type]).to eq(:flouting)
+    end
+
+    it 'classifies mild violation as :opting_out' do
+      utterance = add_utterance(scores: { quality: 0.4, quantity: 0.9, relevance: 0.9, manner: 0.9 })
+      violations = engine.detect_violations(utterance_id: utterance.id)
+      quality_violation = violations.find { |v| v[:maxim] == :quality }
+      expect(quality_violation[:violation_type]).to eq(:opting_out)
+    end
+  end
+
+  describe '#generate_implicature' do
+    it 'adds an implicature to the utterance' do
+      utterance = add_utterance
+      result = engine.generate_implicature(utterance_id: utterance.id, inferred_meaning: 'indirect request')
+      expect(result).to eq('indirect request')
+      expect(utterance.implicatures.size).to eq(1)
+    end
+
+    it 'returns nil for unknown utterance' do
+      result = engine.generate_implicature(utterance_id: 'unknown', inferred_meaning: 'something')
+      expect(result).to be_nil
+    end
+  end
+
+  describe '#speaker_profile' do
+    it 'returns profile for a speaker with utterances' do
+      add_utterance(speaker: 'bob', scores: compliant_scores)
+      add_utterance(speaker: 'bob', scores: compliant_scores)
+      profile = engine.speaker_profile(speaker: 'bob')
+      expect(profile[:speaker]).to eq('bob')
+      expect(profile[:utterance_count]).to eq(2)
+      expect(profile[:compliance_by_maxim].keys).to match_array(%i[quality quantity relevance manner])
+    end
+
+    it 'returns empty profile for unknown speaker' do
+      profile = engine.speaker_profile(speaker: 'unknown')
+      expect(profile[:utterance_count]).to eq(0)
+    end
+  end
+
+  describe '#by_speech_act' do
+    it 'filters utterances by speech act' do
+      add_utterance(speech_act: :question)
+      add_utterance(speech_act: :assert)
+      add_utterance(speech_act: :question)
+      result = engine.by_speech_act(speech_act: :question)
+      expect(result.size).to eq(2)
+    end
+  end
+
+  describe '#by_speaker' do
+    it 'filters utterances by speaker' do
+      add_utterance(speaker: 'alice')
+      add_utterance(speaker: 'bob')
+      result = engine.by_speaker(speaker: 'alice')
+      expect(result.size).to eq(1)
+    end
+  end
+
+  describe '#most_violated_maxim' do
+    it 'returns nil when no utterances' do
+      expect(engine.most_violated_maxim).to be_nil
+    end
+
+    it 'returns the most commonly violated maxim' do
+      3.times { add_utterance(scores: { quality: 0.1, quantity: 0.9, relevance: 0.9, manner: 0.9 }) }
+      add_utterance(scores: { quality: 0.9, quantity: 0.1, relevance: 0.9, manner: 0.9 })
+      engine.utterances.each_value { |u| engine.detect_violations(utterance_id: u.id) }
+      expect(engine.most_violated_maxim).to eq(:quality)
+    end
+  end
+
+  describe '#overall_cooperation' do
+    it 'returns 0.0 when no utterances' do
+      expect(engine.overall_cooperation).to eq(0.0)
+    end
+
+    it 'returns mean compliance across utterances' do
+      add_utterance(scores: { quality: 1.0, quantity: 1.0, relevance: 1.0, manner: 1.0 })
+      add_utterance(scores: { quality: 0.0, quantity: 0.0, relevance: 0.0, manner: 0.0 })
+      expect(engine.overall_cooperation).to be_within(0.01).of(0.5)
+    end
+  end
+
+  describe '#reinforce' do
+    it 'increases utterance confidence' do
+      utterance = add_utterance
+      original_confidence = utterance.confidence
+      engine.reinforce(utterance_id: utterance.id)
+      expect(utterance.confidence).to be > original_confidence
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decreases confidence of all utterances' do
+      u1 = add_utterance
+      u2 = add_utterance
+      c1 = u1.confidence
+      c2 = u2.confidence
+      engine.decay_all
+      expect(u1.confidence).to be < c1
+      expect(u2.confidence).to be < c2
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash with expected keys' do
+      add_utterance
+      h = engine.to_h
+      expect(h).to include(:utterance_count, :overall_cooperation, :most_violated_maxim,
+                           :history_size, :speakers)
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Utterance do
+  let(:utterance) do
+    described_class.new(
+      content:      'Can you pass the salt?',
+      speaker:      'alice',
+      speech_act:   :request,
+      maxim_scores: { quality: 0.9, quantity: 0.8, relevance: 0.9, manner: 0.95 }
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(utterance.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets content and speaker' do
+      expect(utterance.content).to eq('Can you pass the salt?')
+      expect(utterance.speaker).to eq('alice')
+    end
+
+    it 'sets speech act' do
+      expect(utterance.speech_act).to eq(:request)
+    end
+
+    it 'initializes violations and implicatures as empty arrays' do
+      expect(utterance.violations).to be_empty
+      expect(utterance.implicatures).to be_empty
+    end
+
+    it 'clamps confidence to valid range' do
+      u = described_class.new(content: 'x', speaker: 'a', speech_act: :assert, confidence: 5.0)
+      expect(u.confidence).to eq(1.0)
+    end
+
+    it 'defaults missing maxim scores to DEFAULT_CONFIDENCE' do
+      u = described_class.new(content: 'x', speaker: 'a', speech_act: :assert, maxim_scores: {})
+      expect(u.maxim_scores[:quality]).to eq(0.5)
+    end
+  end
+
+  describe '#overall_compliance' do
+    it 'returns mean of maxim scores' do
+      expected = (0.9 + 0.8 + 0.9 + 0.95) / 4.0
+      expect(utterance.overall_compliance).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#violated_maxims' do
+    it 'returns maxims with score below 0.5' do
+      u = described_class.new(
+        content:      'test',
+        speaker:      'bob',
+        speech_act:   :inform,
+        maxim_scores: { quality: 0.1, quantity: 0.9, relevance: 0.8, manner: 0.3 }
+      )
+      expect(u.violated_maxims).to include(:quality, :manner)
+      expect(u.violated_maxims).not_to include(:quantity, :relevance)
+    end
+
+    it 'returns empty array when all maxims compliant' do
+      expect(utterance.violated_maxims).to be_empty
+    end
+  end
+
+  describe '#add_implicature' do
+    it 'adds an inferred meaning' do
+      utterance.add_implicature(meaning: 'requesting action, not asking ability')
+      expect(utterance.implicatures.size).to eq(1)
+      expect(utterance.implicatures.first[:meaning]).to eq('requesting action, not asking ability')
+    end
+
+    it 'does not exceed MAX_IMPLICATURES' do
+      Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Constants::MAX_IMPLICATURES.times do |i|
+        utterance.add_implicature(meaning: "meaning #{i}")
+      end
+      utterance.add_implicature(meaning: 'one more')
+      expect(utterance.implicatures.size).to eq(
+        Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Constants::MAX_IMPLICATURES
+      )
+    end
+  end
+
+  describe '#update_confidence' do
+    it 'increases confidence by delta' do
+      original = utterance.confidence
+      utterance.update_confidence(0.1)
+      expect(utterance.confidence).to be_within(0.001).of(original + 0.1)
+    end
+
+    it 'clamps at ceiling' do
+      utterance.update_confidence(10.0)
+      expect(utterance.confidence).to eq(1.0)
+    end
+
+    it 'clamps at floor' do
+      utterance.update_confidence(-10.0)
+      expect(utterance.confidence).to eq(0.0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all expected keys' do
+      h = utterance.to_h
+      expect(h).to include(:id, :content, :speaker, :speech_act, :maxim_scores,
+                           :violations, :implicatures, :confidence,
+                           :overall_compliance, :violated_maxims, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/pragmatic_inference/runners/pragmatic_inference_spec.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/pragmatic_inference/client'
+
+RSpec.describe Legion::Extensions::Agentic::Language::PragmaticInference::Runners::PragmaticInference do
+  let(:client) { Legion::Extensions::Agentic::Language::PragmaticInference::Client.new }
+
+  let(:compliant_scores) { { quality: 0.9, quantity: 0.8, relevance: 0.9, manner: 0.95 } }
+  let(:violating_scores) { { quality: 0.05, quantity: 0.9, relevance: 0.9, manner: 0.9 } }
+
+  def analyze(speaker: 'alice', speech_act: :assert, scores: compliant_scores)
+    client.analyze_utterance(
+      content:      'test content',
+      speaker:      speaker,
+      speech_act:   speech_act,
+      maxim_scores: scores
+    )
+  end
+
+  describe '#analyze_utterance' do
+    it 'returns success with a valid speech act' do
+      result = analyze
+      expect(result[:success]).to be true
+      expect(result[:utterance_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns overall_compliance' do
+      result = analyze(scores: compliant_scores)
+      expect(result[:overall_compliance]).to be_a(Float)
+    end
+
+    it 'rejects invalid speech act' do
+      result = client.analyze_utterance(
+        content: 'test', speaker: 'alice', speech_act: :perform, maxim_scores: {}
+      )
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_speech_act)
+    end
+
+    it 'includes violated_maxims in result' do
+      result = analyze(scores: violating_scores)
+      expect(result[:violated_maxims]).to include(:quality)
+    end
+
+    it 'reports no violations for compliant utterance' do
+      result = analyze(scores: compliant_scores)
+      expect(result[:violated_maxims]).to be_empty
+    end
+  end
+
+  describe '#detect_maxim_violations' do
+    it 'detects violations for low-scoring utterance' do
+      analyzed = analyze(scores: violating_scores)
+      result = client.detect_maxim_violations(utterance_id: analyzed[:utterance_id])
+      expect(result[:success]).to be true
+      expect(result[:violation_count]).to be >= 1
+      expect(result[:violations].map { |v| v[:maxim] }).to include(:quality)
+    end
+
+    it 'returns zero violations for compliant utterance' do
+      analyzed = analyze(scores: compliant_scores)
+      result = client.detect_maxim_violations(utterance_id: analyzed[:utterance_id])
+      expect(result[:violation_count]).to eq(0)
+    end
+
+    it 'rejects short utterance_id' do
+      result = client.detect_maxim_violations(utterance_id: 'ab')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#generate_pragmatic_implicature' do
+    it 'adds implicature to existing utterance' do
+      analyzed = analyze
+      result = client.generate_pragmatic_implicature(
+        utterance_id:     analyzed[:utterance_id],
+        inferred_meaning: 'speaker implies indirect request'
+      )
+      expect(result[:success]).to be true
+      expect(result[:inferred_meaning]).to eq('speaker implies indirect request')
+    end
+
+    it 'fails for unknown utterance' do
+      result = client.generate_pragmatic_implicature(
+        utterance_id:     SecureRandom.uuid,
+        inferred_meaning: 'something'
+      )
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:utterance_not_found)
+    end
+
+    it 'rejects short inferred_meaning' do
+      analyzed = analyze
+      result = client.generate_pragmatic_implicature(
+        utterance_id:     analyzed[:utterance_id],
+        inferred_meaning: 'ab'
+      )
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_inferred_meaning)
+    end
+
+    it 'rejects short utterance_id' do
+      result = client.generate_pragmatic_implicature(utterance_id: 'x', inferred_meaning: 'valid meaning here')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#speaker_pragmatic_profile' do
+    it 'returns profile for existing speaker' do
+      analyze(speaker: 'bob')
+      analyze(speaker: 'bob')
+      result = client.speaker_pragmatic_profile(speaker: 'bob')
+      expect(result[:success]).to be true
+      expect(result[:utterance_count]).to eq(2)
+      expect(result[:compliance_by_maxim]).to be_a(Hash)
+    end
+
+    it 'returns empty count for unknown speaker' do
+      result = client.speaker_pragmatic_profile(speaker: 'unknown_person')
+      expect(result[:success]).to be true
+      expect(result[:utterance_count]).to eq(0)
+    end
+
+    it 'rejects short speaker name' do
+      result = client.speaker_pragmatic_profile(speaker: 'ab')
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_speaker)
+    end
+  end
+
+  describe '#utterances_by_speech_act' do
+    it 'returns utterances matching speech act' do
+      analyze(speech_act: :question)
+      analyze(speech_act: :question)
+      analyze(speech_act: :warn)
+      result = client.utterances_by_speech_act(speech_act: :question)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'rejects invalid speech act' do
+      result = client.utterances_by_speech_act(speech_act: :perform)
+      expect(result[:success]).to be false
+      expect(result[:error]).to eq(:invalid_speech_act)
+    end
+  end
+
+  describe '#utterances_by_speaker' do
+    it 'returns utterances for given speaker' do
+      analyze(speaker: 'charlie')
+      analyze(speaker: 'charlie')
+      analyze(speaker: 'dave')
+      result = client.utterances_by_speaker(speaker: 'charlie')
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'rejects short speaker name' do
+      result = client.utterances_by_speaker(speaker: 'xy')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#most_violated_maxim' do
+    it 'returns nil maxim when no utterances' do
+      result = client.most_violated_maxim
+      expect(result[:success]).to be true
+      expect(result[:maxim]).to be_nil
+    end
+
+    it 'identifies the most violated maxim' do
+      3.times do
+        analyzed = analyze(scores: { quality: 0.1, quantity: 0.9, relevance: 0.9, manner: 0.9 })
+        client.detect_maxim_violations(utterance_id: analyzed[:utterance_id])
+      end
+      analyzed = analyze(scores: { quality: 0.9, quantity: 0.1, relevance: 0.9, manner: 0.9 })
+      client.detect_maxim_violations(utterance_id: analyzed[:utterance_id])
+
+      result = client.most_violated_maxim
+      expect(result[:maxim]).to eq(:quality)
+    end
+
+    it 'includes a description for the violated maxim' do
+      analyzed = analyze(scores: violating_scores)
+      client.detect_maxim_violations(utterance_id: analyzed[:utterance_id])
+      result = client.most_violated_maxim
+      expect(result[:description]).to be_a(String) if result[:maxim]
+    end
+  end
+
+  describe '#overall_cooperative_compliance' do
+    it 'returns 0.0 when no utterances' do
+      result = client.overall_cooperative_compliance
+      expect(result[:success]).to be true
+      expect(result[:cooperation]).to eq(0.0)
+    end
+
+    it 'computes mean compliance' do
+      analyze(scores: { quality: 1.0, quantity: 1.0, relevance: 1.0, manner: 1.0 })
+      analyze(scores: { quality: 0.0, quantity: 0.0, relevance: 0.0, manner: 0.0 })
+      result = client.overall_cooperative_compliance
+      expect(result[:cooperation]).to be_within(0.01).of(0.5)
+    end
+  end
+
+  describe '#update_pragmatic_inference' do
+    it 'returns success with decay info' do
+      result = client.update_pragmatic_inference
+      expect(result[:success]).to be true
+      expect(result[:decay_rate]).to eq(Legion::Extensions::Agentic::Language::PragmaticInference::Helpers::Constants::DECAY_RATE)
+    end
+
+    it 'decays utterance confidence' do
+      analyze
+      before_cooperation = client.overall_cooperative_compliance[:cooperation]
+      client.update_pragmatic_inference
+      after_cooperation = client.overall_cooperative_compliance[:cooperation]
+      expect(after_cooperation).to be <= before_cooperation
+    end
+  end
+
+  describe '#pragmatic_inference_stats' do
+    it 'returns stats hash' do
+      analyze
+      result = client.pragmatic_inference_stats
+      expect(result[:success]).to be true
+      expect(result[:utterance_count]).to eq(1)
+      expect(result).to include(:overall_cooperation, :most_violated_maxim, :history_size, :speakers)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+    def self.fatal(_msg); end
+  end
+
+  module Extensions
+    module Core
+      def self.extended(_base); end
+    end
+
+    module Helpers
+      module Lex
+        def self.included(_base); end
+      end
+    end
+  end
+end
+
+require 'legion/extensions/agentic/language'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end