lex-agentic-language 0.1.0

data/lib/legion/extensions/agentic/language/pragmatic_inference/helpers/pragmatic_engine.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module PragmaticInference
+          module Helpers
+            class PragmaticEngine
+              attr_reader :utterances, :history
+
+              def initialize
+                @utterances = {}
+                @history    = []
+              end
+
+              def analyze_utterance(content:, speaker:, speech_act:, literal_meaning: nil,
+                                    domain: nil, maxim_scores: {})
+                trim_utterances if @utterances.size >= Constants::MAX_UTTERANCES
+
+                utterance = Utterance.new(
+                  content:         content,
+                  speaker:         speaker,
+                  speech_act:      speech_act,
+                  literal_meaning: literal_meaning,
+                  domain:          domain,
+                  maxim_scores:    maxim_scores
+                )
+
+                @utterances[utterance.id] = utterance
+                record_history(utterance.id, :analyzed)
+                utterance
+              end
+
+              def detect_violations(utterance_id:)
+                utterance = @utterances[utterance_id]
+                return [] unless utterance
+
+                violations = []
+                utterance.maxim_scores.each do |maxim, score|
+                  next if score >= 0.5
+
+                  violation_type = classify_violation(score)
+                  violation = { maxim: maxim, violation_type: violation_type, score: score }
+                  violations << violation
+                  utterance.violations << violation
+                end
+
+                violations
+              end
+
+              def generate_implicature(utterance_id:, inferred_meaning:)
+                utterance = @utterances[utterance_id]
+                return nil unless utterance
+
+                utterance.add_implicature(meaning: inferred_meaning)
+                record_history(utterance_id, :implicature_added)
+                inferred_meaning
+              end
+
+              def speaker_profile(speaker:)
+                speaker_utterances = by_speaker(speaker: speaker)
+                return { speaker: speaker, utterance_count: 0, compliance_by_maxim: {} } if speaker_utterances.empty?
+
+                compliance_by_maxim = Constants::MAXIMS.to_h do |maxim|
+                  scores = speaker_utterances.map { |u| u.maxim_scores[maxim] }
+                  mean = scores.sum / scores.size.to_f
+                  [maxim, mean.round(3)]
+                end
+
+                {
+                  speaker:             speaker,
+                  utterance_count:     speaker_utterances.size,
+                  compliance_by_maxim: compliance_by_maxim,
+                  overall_compliance:  (compliance_by_maxim.values.sum / compliance_by_maxim.size.to_f).round(3)
+                }
+              end
+
+              def by_speech_act(speech_act:)
+                @utterances.values.select { |u| u.speech_act == speech_act }
+              end
+
+              def by_speaker(speaker:)
+                @utterances.values.select { |u| u.speaker == speaker }
+              end
+
+              def most_violated_maxim
+                return nil if @utterances.empty?
+
+                violation_counts = Hash.new(0)
+                @utterances.each_value do |utterance|
+                  utterance.violated_maxims.each { |maxim| violation_counts[maxim] += 1 }
+                end
+
+                return nil if violation_counts.empty?
+
+                violation_counts.max_by { |_maxim, count| count }&.first
+              end
+
+              def overall_cooperation
+                return 0.0 if @utterances.empty?
+
+                total = @utterances.values.sum(&:overall_compliance)
+                total / @utterances.size.to_f
+              end
+
+              def reinforce(utterance_id:)
+                utterance = @utterances[utterance_id]
+                return unless utterance
+
+                utterance.update_confidence(Constants::REINFORCEMENT_RATE)
+              end
+
+              def decay_all
+                @utterances.each_value do |utterance|
+                  utterance.update_confidence(-Constants::DECAY_RATE)
+                end
+              end
+
+              def count
+                @utterances.size
+              end
+
+              def to_h
+                {
+                  utterance_count:     @utterances.size,
+                  overall_cooperation: overall_cooperation.round(3),
+                  most_violated_maxim: most_violated_maxim,
+                  history_size:        @history.size,
+                  speakers:            @utterances.values.map(&:speaker).uniq.size
+                }
+              end
+
+              private
+
+              def classify_violation(score)
+                if score < 0.1
+                  :violating
+                elsif score < 0.3
+                  :flouting
+                elsif score < 0.5
+                  :opting_out
+                else
+                  :none
+                end
+              end
+
+              def record_history(utterance_id, event)
+                @history << { utterance_id: utterance_id, event: event, at: Time.now.utc }
+                @history.shift while @history.size > Constants::MAX_HISTORY
+              end
+
+              def trim_utterances
+                overflow = @utterances.size - Constants::MAX_UTTERANCES + 1
+                keys_to_remove = @utterances.keys.first(overflow)
+                keys_to_remove.each { |k| @utterances.delete(k) }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module PragmaticInference
+          module Helpers
+            class Utterance
+              attr_reader :id, :content, :speaker, :speech_act, :literal_meaning,
+                          :domain, :maxim_scores, :violations, :implicatures,
+                          :confidence, :created_at
+
+              def initialize(content:, speaker:, speech_act:, literal_meaning: nil,
+                             domain: nil, maxim_scores: {}, confidence: Constants::DEFAULT_CONFIDENCE)
+                @id             = SecureRandom.uuid
+                @content        = content
+                @speaker        = speaker
+                @speech_act     = speech_act
+                @literal_meaning = literal_meaning
+                @domain         = domain
+                @maxim_scores   = build_maxim_scores(maxim_scores)
+                @violations     = []
+                @implicatures   = []
+                @confidence     = confidence.clamp(Constants::CONFIDENCE_FLOOR, Constants::CONFIDENCE_CEILING)
+                @created_at     = Time.now.utc
+              end
+
+              def overall_compliance
+                return 0.0 if @maxim_scores.empty?
+
+                @maxim_scores.values.sum / @maxim_scores.size.to_f
+              end
+
+              def violated_maxims
+                @maxim_scores.select { |_maxim, score| score < 0.5 }.keys
+              end
+
+              def add_implicature(meaning:)
+                return if @implicatures.size >= Constants::MAX_IMPLICATURES
+
+                @implicatures << { meaning: meaning, added_at: Time.now.utc }
+              end
+
+              def update_confidence(delta)
+                @confidence = (@confidence + delta).clamp(Constants::CONFIDENCE_FLOOR, Constants::CONFIDENCE_CEILING)
+              end
+
+              def to_h
+                {
+                  id:                 @id,
+                  content:            @content,
+                  speaker:            @speaker,
+                  speech_act:         @speech_act,
+                  literal_meaning:    @literal_meaning,
+                  domain:             @domain,
+                  maxim_scores:       @maxim_scores,
+                  violations:         @violations,
+                  implicatures:       @implicatures,
+                  confidence:         @confidence,
+                  overall_compliance: overall_compliance,
+                  violated_maxims:    violated_maxims,
+                  created_at:         @created_at
+                }
+              end
+
+              private
+
+              def build_maxim_scores(scores)
+                Constants::MAXIMS.to_h do |maxim|
+                  [maxim, (scores[maxim] || Constants::DEFAULT_CONFIDENCE).clamp(
+                    Constants::CONFIDENCE_FLOOR, Constants::CONFIDENCE_CEILING
+                  )]
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module PragmaticInference
+          module Runners
+            module PragmaticInference
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def analyze_utterance(content:, speaker:, speech_act:, literal_meaning: nil,
+                                    domain: nil, maxim_scores: {}, **)
+                return { success: false, error: :invalid_speech_act } unless Helpers::Constants.valid_speech_act?(speech_act)
+
+                utterance = engine.analyze_utterance(
+                  content:         content,
+                  speaker:         speaker,
+                  speech_act:      speech_act,
+                  literal_meaning: literal_meaning,
+                  domain:          domain,
+                  maxim_scores:    maxim_scores
+                )
+
+                Legion::Logging.debug "[pragmatic_inference] analyzed utterance id=#{utterance.id[0..7]} " \
+                                      "speaker=#{speaker} speech_act=#{speech_act} " \
+                                      "compliance=#{utterance.overall_compliance.round(2)}"
+
+                { success: true, utterance_id: utterance.id, overall_compliance: utterance.overall_compliance,
+                  violated_maxims: utterance.violated_maxims }
+              end
+
+              def detect_maxim_violations(utterance_id:, **)
+                return { success: false, error: :invalid_utterance_id } if utterance_id.to_s.length < 3
+
+                violations = engine.detect_violations(utterance_id: utterance_id)
+
+                Legion::Logging.debug "[pragmatic_inference] violations detected id=#{utterance_id[0..7]} count=#{violations.size}"
+
+                { success: true, utterance_id: utterance_id, violations: violations, violation_count: violations.size }
+              end
+
+              def generate_pragmatic_implicature(utterance_id:, inferred_meaning:, **)
+                return { success: false, error: :invalid_utterance_id } if utterance_id.to_s.length < 3
+                return { success: false, error: :invalid_inferred_meaning } if inferred_meaning.to_s.length < 3
+
+                result = engine.generate_implicature(utterance_id: utterance_id, inferred_meaning: inferred_meaning)
+
+                if result
+                  Legion::Logging.debug "[pragmatic_inference] implicature added id=#{utterance_id[0..7]}"
+                  { success: true, utterance_id: utterance_id, inferred_meaning: result }
+                else
+                  Legion::Logging.debug "[pragmatic_inference] implicature failed: utterance not found id=#{utterance_id[0..7]}"
+                  { success: false, error: :utterance_not_found }
+                end
+              end
+
+              def speaker_pragmatic_profile(speaker:, **)
+                return { success: false, error: :invalid_speaker } if speaker.to_s.length < 3
+
+                profile = engine.speaker_profile(speaker: speaker)
+
+                Legion::Logging.debug "[pragmatic_inference] speaker profile speaker=#{speaker} " \
+                                      "utterances=#{profile[:utterance_count]}"
+
+                { success: true, **profile }
+              end
+
+              def utterances_by_speech_act(speech_act:, **)
+                return { success: false, error: :invalid_speech_act } unless Helpers::Constants.valid_speech_act?(speech_act)
+
+                utterances = engine.by_speech_act(speech_act: speech_act)
+
+                Legion::Logging.debug "[pragmatic_inference] by_speech_act act=#{speech_act} count=#{utterances.size}"
+
+                { success: true, speech_act: speech_act, utterances: utterances.map(&:to_h), count: utterances.size }
+              end
+
+              def utterances_by_speaker(speaker:, **)
+                return { success: false, error: :invalid_speaker } if speaker.to_s.length < 3
+
+                utterances = engine.by_speaker(speaker: speaker)
+
+                Legion::Logging.debug "[pragmatic_inference] by_speaker speaker=#{speaker} count=#{utterances.size}"
+
+                { success: true, speaker: speaker, utterances: utterances.map(&:to_h), count: utterances.size }
+              end
+
+              def most_violated_maxim(**)
+                maxim = engine.most_violated_maxim
+
+                Legion::Logging.debug "[pragmatic_inference] most violated maxim=#{maxim.inspect}"
+
+                { success: true, maxim: maxim,
+                  description: maxim ? Helpers::Constants::MAXIM_DESCRIPTIONS[maxim] : nil }
+              end
+
+              def overall_cooperative_compliance(**)
+                cooperation = engine.overall_cooperation
+                total = engine.count
+
+                Legion::Logging.debug "[pragmatic_inference] cooperation=#{cooperation.round(2)} total=#{total}"
+
+                { success: true, cooperation: cooperation, utterance_count: total }
+              end
+
+              def update_pragmatic_inference(**)
+                engine.decay_all
+
+                Legion::Logging.debug "[pragmatic_inference] decay applied to #{engine.count} utterances"
+
+                { success: true, decayed_count: engine.count, decay_rate: Helpers::Constants::DECAY_RATE }
+              end
+
+              def pragmatic_inference_stats(**)
+                stats = engine.to_h
+
+                Legion::Logging.debug "[pragmatic_inference] stats: utterances=#{stats[:utterance_count]} " \
+                                      "cooperation=#{stats[:overall_cooperation]}"
+
+                { success: true, **stats }
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::PragmaticEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/pragmatic_inference/version'
+require 'legion/extensions/agentic/language/pragmatic_inference/helpers/constants'
+require 'legion/extensions/agentic/language/pragmatic_inference/helpers/utterance'
+require 'legion/extensions/agentic/language/pragmatic_inference/helpers/pragmatic_engine'
+require 'legion/extensions/agentic/language/pragmatic_inference/runners/pragmatic_inference'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module PragmaticInference
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'language/version'
+require_relative 'language/grammar'
+require_relative 'language/conceptual_blending'
+require_relative 'language/conceptual_metaphor'
+require_relative 'language/language'
+require_relative 'language/inner_speech'
+require_relative 'language/narrator'
+require_relative 'language/narrative_reasoning'
+require_relative 'language/frame_semantics'
+require_relative 'language/pragmatic_inference'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+        def remote_invocable?
+          false
+        end
+
+        # Sub-modules are required here as extensions are consolidated.
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/conceptual_blending/client'
+
+RSpec.describe Legion::Extensions::Agentic::Language::ConceptualBlending::Client do
+  let(:client) { described_class.new }
+
+  describe '#initialize' do
+    it 'creates a client with a default engine' do
+      expect(client).to respond_to(:create_mental_space)
+    end
+
+    it 'accepts an injected engine' do
+      engine = Legion::Extensions::Agentic::Language::ConceptualBlending::Helpers::BlendingEngine.new
+      injected_client = described_class.new(engine: engine)
+      expect(injected_client).to respond_to(:conceptual_blending_stats)
+    end
+  end
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:create_mental_space)
+    expect(client).to respond_to(:add_space_element)
+    expect(client).to respond_to(:add_space_relation)
+    expect(client).to respond_to(:create_blend)
+    expect(client).to respond_to(:elaborate_blend)
+    expect(client).to respond_to(:compress_blend)
+    expect(client).to respond_to(:best_blends)
+    expect(client).to respond_to(:blend_quality)
+    expect(client).to respond_to(:update_conceptual_blending)
+    expect(client).to respond_to(:conceptual_blending_stats)
+  end
+
+  it 'round-trips a full blending workflow' do
+    # Create two spaces
+    bio_result  = client.create_mental_space(name: 'biology', domain: 'science')
+    comp_result = client.create_mental_space(name: 'computing', domain: 'technology')
+
+    bio_id  = bio_result[:space][:id]
+    comp_id = comp_result[:space][:id]
+
+    # Populate spaces
+    client.add_space_element(space_id: bio_id, name: 'virus', properties: { spreads: true })
+    client.add_space_element(space_id: comp_id, name: 'software', properties: { executes: true })
+    client.add_space_relation(space_id: bio_id, from: 'virus', to: 'host', type: :infects)
+    client.add_space_relation(space_id: comp_id, from: 'software', to: 'system', type: :corrupts)
+
+    # Blend
+    blend_result = client.create_blend(space_a_id: bio_id, space_b_id: comp_id)
+    expect(blend_result[:success]).to be true
+    blend_id = blend_result[:blend][:id]
+
+    # Elaborate
+    elab_result = client.elaborate_blend(blend_id: blend_id, emergent_property: 'computer_virus')
+    expect(elab_result[:success]).to be true
+
+    # Quality
+    quality_result = client.blend_quality(blend_id: blend_id)
+    expect(quality_result[:quality_label]).to be_a(Symbol)
+
+    # Stats reflect both spaces
+    stats = client.conceptual_blending_stats
+    expect(stats[:spaces_count]).to eq(2)
+    expect(stats[:blends_count]).to eq(1)
+  end
+
+  it 'maintains isolated state per client instance' do
+    client_a = described_class.new
+    client_b = described_class.new
+
+    client_a.create_mental_space(name: 'space_a', domain: 'domain_a')
+
+    stats_a = client_a.conceptual_blending_stats
+    stats_b = client_b.conceptual_blending_stats
+
+    expect(stats_a[:spaces_count]).to eq(1)
+    expect(stats_b[:spaces_count]).to eq(0)
+  end
+end

data/spec/legion/extensions/agentic/language/conceptual_blending/helpers/blend_spec.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::ConceptualBlending::Helpers::Blend do
+  let(:input_ids) { [SecureRandom.uuid, SecureRandom.uuid] }
+  let(:generic_space) { { shared_relation_types: [:infects], mapped_elements: [] } }
+  let(:blended_elements) { { merged_elements: %w[virus software], emergent_properties: [] } }
+
+  subject(:blend) do
+    described_class.new(
+      input_space_ids:  input_ids,
+      generic_space:    generic_space,
+      blended_elements: blended_elements,
+      blend_type:       :double_scope
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(blend.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets input_space_ids' do
+      expect(blend.input_space_ids).to eq(input_ids)
+    end
+
+    it 'sets blend_type' do
+      expect(blend.blend_type).to eq(:double_scope)
+    end
+
+    it 'defaults strength to DEFAULT_STRENGTH' do
+      expect(blend.strength).to eq(Legion::Extensions::Agentic::Language::ConceptualBlending::Helpers::Constants::DEFAULT_STRENGTH)
+    end
+
+    it 'starts with use_count 0' do
+      expect(blend.use_count).to eq(0)
+    end
+  end
+
+  describe '#use!' do
+    it 'increments use_count' do
+      blend.use!
+      expect(blend.use_count).to eq(1)
+    end
+
+    it 'updates last_used_at' do
+      original = blend.last_used_at
+      sleep(0.01)
+      blend.use!
+      expect(blend.last_used_at).to be >= original
+    end
+
+    it 'returns self' do
+      expect(blend.use!).to eq(blend)
+    end
+  end
+
+  describe '#elaborate' do
+    it 'appends to emergent_properties' do
+      blend.elaborate(emergent_property: 'software_spreads_like_virus')
+      expect(blend.blended_elements[:emergent_properties]).to include('software_spreads_like_virus')
+    end
+
+    it 'boosts strength by ELABORATION_BOOST' do
+      original = blend.strength
+      blend.elaborate(emergent_property: 'new_prop')
+      expected = (original + Legion::Extensions::Agentic::Language::ConceptualBlending::Helpers::Constants::ELABORATION_BOOST)
+                 .clamp(0.0, 1.0)
+      expect(blend.strength).to be_within(0.001).of(expected)
+    end
+
+    it 'does not exceed strength ceiling' do
+      10.times { blend.elaborate(emergent_property: 'prop') }
+      expect(blend.strength).to be <= 1.0
+    end
+
+    it 'returns self' do
+      expect(blend.elaborate(emergent_property: 'x')).to eq(blend)
+    end
+  end
+
+  describe '#compress' do
+    it 'reduces strength by COMPRESSION_PENALTY' do
+      original = blend.strength
+      blend.compress(removed_element: 'virus')
+      expected = (original - Legion::Extensions::Agentic::Language::ConceptualBlending::Helpers::Constants::COMPRESSION_PENALTY)
+                 .clamp(0.0, 1.0)
+      expect(blend.strength).to be_within(0.001).of(expected)
+    end
+
+    it 'does not go below strength floor' do
+      20.times { blend.compress(removed_element: 'x') }
+      expect(blend.strength).to be >= 0.0
+    end
+
+    it 'returns self' do
+      expect(blend.compress(removed_element: 'x')).to eq(blend)
+    end
+  end
+
+  describe '#quality_score' do
+    it 'returns a float between 0 and 1' do
+      expect(blend.quality_score).to be_between(0.0, 1.0)
+    end
+
+    it 'increases with more emergent properties' do
+      base_score = blend.quality_score
+      5.times { |idx| blend.elaborate(emergent_property: "prop_#{idx}") }
+      expect(blend.quality_score).to be > base_score
+    end
+
+    it 'increases with more use' do
+      base_score = blend.quality_score
+      10.times { blend.use! }
+      expect(blend.quality_score).to be >= base_score
+    end
+  end
+
+  describe '#quality_label' do
+    it 'returns a symbol from QUALITY_LABELS' do
+      labels = Legion::Extensions::Agentic::Language::ConceptualBlending::Helpers::Constants::QUALITY_LABELS.values
+      expect(labels).to include(blend.quality_label)
+    end
+  end
+
+  describe '#stale?' do
+    it 'returns false for a freshly created blend' do
+      expect(blend.stale?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all key fields' do
+      result = blend.to_h
+      expect(result).to include(
+        :id, :input_space_ids, :generic_space, :blended_elements,
+        :blend_type, :strength, :use_count, :quality_score, :quality_label,
+        :stale, :created_at, :last_used_at
+      )
+    end
+  end
+end