lex-agentic-language 0.1.0

data/spec/legion/extensions/agentic/language/conceptual_metaphor/helpers/metaphor_spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::ConceptualMetaphor::Helpers::Metaphor do
+  subject(:metaphor) do
+    described_class.new(
+      source_domain:   :money,
+      target_domain:   :time,
+      metaphor_type:   :structural,
+      mappings:        { spend: :waste, save: :conserve, invest: :dedicate },
+      strength:        0.6,
+      conventionality: 0.8
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(metaphor.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores source and target domains' do
+      expect(metaphor.source_domain).to eq(:money)
+      expect(metaphor.target_domain).to eq(:time)
+    end
+
+    it 'stores metaphor type' do
+      expect(metaphor.metaphor_type).to eq(:structural)
+    end
+
+    it 'stores mappings' do
+      expect(metaphor.mappings).to eq({ spend: :waste, save: :conserve, invest: :dedicate })
+    end
+
+    it 'clamps strength within bounds' do
+      over = described_class.new(source_domain: :a, target_domain: :b, metaphor_type: :structural,
+                                 mappings: {}, strength: 2.0)
+      expect(over.strength).to eq(1.0)
+    end
+  end
+
+  describe '#use!' do
+    it 'increments use count' do
+      expect { metaphor.use! }.to change(metaphor, :use_count).by(1)
+    end
+
+    it 'boosts strength' do
+      original = metaphor.strength
+      metaphor.use!
+      expect(metaphor.strength).to be > original
+    end
+
+    it 'increases conventionality' do
+      original = metaphor.conventionality
+      metaphor.use!
+      expect(metaphor.conventionality).to be >= original
+    end
+  end
+
+  describe '#map_concept' do
+    it 'returns mapped target concept' do
+      expect(metaphor.map_concept(:spend)).to eq(:waste)
+    end
+
+    it 'returns nil for unmapped concept' do
+      expect(metaphor.map_concept(:borrow)).to be_nil
+    end
+  end
+
+  describe '#coverage' do
+    it 'returns ratio of mapped concepts' do
+      expect(metaphor.coverage).to eq(1.0)
+    end
+
+    it 'returns 0.0 for empty mappings' do
+      empty = described_class.new(source_domain: :a, target_domain: :b,
+                                  metaphor_type: :structural, mappings: {})
+      expect(empty.coverage).to eq(0.0)
+    end
+  end
+
+  describe '#conventional?' do
+    it 'returns true when conventionality is high' do
+      expect(metaphor).to be_conventional
+    end
+  end
+
+  describe '#novel?' do
+    it 'returns false when conventionality is high' do
+      expect(metaphor).not_to be_novel
+    end
+
+    it 'returns true when conventionality is low' do
+      fresh = described_class.new(source_domain: :a, target_domain: :b,
+                                  metaphor_type: :structural, mappings: {},
+                                  conventionality: 0.2)
+      expect(fresh).to be_novel
+    end
+  end
+
+  describe '#conventionality_label' do
+    it 'returns a label symbol' do
+      expect(metaphor.conventionality_label).to eq(:dead)
+    end
+  end
+
+  describe '#strength_label' do
+    it 'returns a label symbol' do
+      expect(metaphor.strength_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces strength' do
+      original = metaphor.strength
+      metaphor.decay!
+      expect(metaphor.strength).to be < original
+    end
+  end
+
+  describe '#add_entailment' do
+    it 'adds entailment to the list' do
+      metaphor.add_entailment('wasting time is losing money')
+      expect(metaphor.entailments).to include('wasting time is losing money')
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash representation' do
+      hash = metaphor.to_h
+      expect(hash).to include(:id, :source_domain, :target_domain, :mappings,
+                              :strength, :conventionality, :coverage)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/conceptual_metaphor/runners/conceptual_metaphor_spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::ConceptualMetaphor::Runners::ConceptualMetaphor do
+  let(:runner_host) do
+    obj = Object.new
+    obj.extend(described_class)
+    obj
+  end
+
+  describe '#create_metaphor' do
+    it 'creates a metaphor successfully' do
+      result = runner_host.create_metaphor(
+        source_domain: :money, target_domain: :time,
+        metaphor_type: :structural, mappings: { spend: :waste }
+      )
+      expect(result[:success]).to be true
+      expect(result[:metaphor_id]).to be_a(String)
+    end
+
+    it 'rejects invalid metaphor type' do
+      result = runner_host.create_metaphor(
+        source_domain: :a, target_domain: :b,
+        metaphor_type: :invalid, mappings: {}
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#apply_metaphor' do
+    it 'maps a concept through a metaphor' do
+      created = runner_host.create_metaphor(
+        source_domain: :money, target_domain: :time,
+        metaphor_type: :structural, mappings: { spend: :waste }
+      )
+      result = runner_host.apply_metaphor(
+        metaphor_id: created[:metaphor_id], source_concept: :spend
+      )
+      expect(result[:success]).to be true
+      expect(result[:target_concept]).to eq(:waste)
+    end
+  end
+
+  describe '#add_metaphor_entailment' do
+    it 'adds an entailment' do
+      created = runner_host.create_metaphor(
+        source_domain: :money, target_domain: :time,
+        metaphor_type: :structural, mappings: {}
+      )
+      result = runner_host.add_metaphor_entailment(
+        metaphor_id: created[:metaphor_id],
+        entailment:  'wasting time is losing money'
+      )
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#find_metaphors_for' do
+    it 'finds metaphors for a domain' do
+      runner_host.create_metaphor(
+        source_domain: :money, target_domain: :time,
+        metaphor_type: :structural, mappings: {}
+      )
+      result = runner_host.find_metaphors_for(domain: :time)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#conventional_metaphors' do
+    it 'returns conventional metaphors' do
+      runner_host.create_metaphor(
+        source_domain: :war, target_domain: :argument,
+        metaphor_type: :structural, mappings: {},
+        conventionality: 0.9
+      )
+      result = runner_host.conventional_metaphors
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#novel_metaphors' do
+    it 'returns novel metaphors' do
+      runner_host.create_metaphor(
+        source_domain: :ocean, target_domain: :emotion,
+        metaphor_type: :ontological, mappings: {},
+        conventionality: 0.1
+      )
+      result = runner_host.novel_metaphors
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#strongest_metaphors' do
+    it 'returns strongest metaphors' do
+      runner_host.create_metaphor(
+        source_domain: :a, target_domain: :b,
+        metaphor_type: :structural, mappings: {}, strength: 0.9
+      )
+      result = runner_host.strongest_metaphors(limit: 3)
+      expect(result[:success]).to be true
+    end
+  end
+
+  describe '#metaphors_by_type' do
+    it 'filters by type' do
+      runner_host.create_metaphor(
+        source_domain: :a, target_domain: :b,
+        metaphor_type: :orientational, mappings: {}
+      )
+      result = runner_host.metaphors_by_type(metaphor_type: :orientational)
+      expect(result[:success]).to be true
+      expect(result[:count]).to eq(1)
+    end
+  end
+
+  describe '#update_conceptual_metaphor' do
+    it 'runs decay and prune cycle' do
+      result = runner_host.update_conceptual_metaphor
+      expect(result[:success]).to be true
+      expect(result).to include(:pruned)
+    end
+  end
+
+  describe '#conceptual_metaphor_stats' do
+    it 'returns stats' do
+      result = runner_host.conceptual_metaphor_stats
+      expect(result[:success]).to be true
+      expect(result).to include(:total_metaphors, :total_domains)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/frame_semantics/helpers/frame_engine_spec.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::FrameEngine do
+  subject(:engine) { described_class.new }
+
+  let(:frame) { engine.create_frame(name: :commercial_transaction, domain: :commerce) }
+
+  before do
+    frame.add_slot(name: :buyer)
+    frame.add_slot(name: :seller)
+    frame.add_slot(name: :goods)
+  end
+
+  describe '#create_frame' do
+    it 'returns a Frame object' do
+      f = engine.create_frame(name: :motion, domain: :physics)
+      expect(f).to be_a(Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::Frame)
+    end
+
+    it 'creates frame with slots from hash' do
+      f = engine.create_frame(
+        name:   :competition,
+        domain: :sports,
+        slots:  { winner: { type: :core, required: true }, loser: { type: :peripheral, required: false } }
+      )
+      expect(f.slots[:winner][:type]).to eq(:core)
+      expect(f.slots[:loser][:type]).to eq(:peripheral)
+    end
+  end
+
+  describe '#define_slot' do
+    it 'adds a slot to an existing frame' do
+      result = engine.define_slot(frame_id: frame.id, name: :price)
+      expect(result).to be_a(Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::Frame)
+      expect(frame.slots[:price]).not_to be_nil
+    end
+
+    it 'returns nil for unknown frame_id' do
+      expect(engine.define_slot(frame_id: 'bogus', name: :price)).to be_nil
+    end
+  end
+
+  describe '#fill_slot' do
+    it 'fills a slot and returns true' do
+      expect(engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')).to be true
+    end
+
+    it 'returns false for unknown frame' do
+      expect(engine.fill_slot(frame_id: 'bogus', slot_name: :buyer, filler: 'x')).to be false
+    end
+
+    it 'activates the frame when slot is filled' do
+      initial = frame.activation
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')
+      expect(frame.activation_count).to be >= 1
+      expect(frame.activation).to be >= initial
+    end
+  end
+
+  describe '#instantiate_frame' do
+    before do
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')
+      engine.fill_slot(frame_id: frame.id, slot_name: :seller, filler: 'Bob')
+    end
+
+    it 'creates a FrameInstance snapshot' do
+      inst = engine.instantiate_frame(frame_id: frame.id, context: 'coffee shop')
+      expect(inst).to be_a(Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::FrameInstance)
+      expect(inst.frame_id).to eq(frame.id)
+      expect(inst.context).to eq('coffee shop')
+    end
+
+    it 'returns nil for unknown frame' do
+      expect(engine.instantiate_frame(frame_id: 'bogus', context: 'x')).to be_nil
+    end
+
+    it 'snapshots current slot fillers' do
+      inst = engine.instantiate_frame(frame_id: frame.id, context: 'test')
+      expect(inst.slot_fillers[:buyer]).to eq('Alice')
+    end
+  end
+
+  describe '#add_frame_relation' do
+    it 'adds a valid relation' do
+      target = engine.create_frame(name: :transfer, domain: :commerce)
+      result = engine.add_frame_relation(
+        frame_id:        frame.id,
+        relation:        :has_subframe,
+        target_frame_id: target.id
+      )
+      expect(result).to be true
+      expect(frame.relations.size).to eq(1)
+    end
+
+    it 'rejects invalid relation type' do
+      result = engine.add_frame_relation(
+        frame_id:        frame.id,
+        relation:        :invalid_relation,
+        target_frame_id: SecureRandom.uuid
+      )
+      expect(result).to be false
+    end
+
+    it 'returns false for unknown frame_id' do
+      expect(
+        engine.add_frame_relation(frame_id: 'bogus', relation: :uses, target_frame_id: SecureRandom.uuid)
+      ).to be false
+    end
+  end
+
+  describe '#activate_frame' do
+    it 'activates an existing frame' do
+      initial_count = frame.activation_count
+      engine.activate_frame(frame_id: frame.id)
+      expect(frame.activation_count).to eq(initial_count + 1)
+    end
+
+    it 'returns false for unknown frame' do
+      expect(engine.activate_frame(frame_id: 'bogus')).to be false
+    end
+  end
+
+  describe '#active_frames' do
+    it 'returns frames with activation > 0.5' do
+      5.times { engine.activate_frame(frame_id: frame.id) }
+      expect(engine.active_frames).to include(frame)
+    end
+
+    it 'excludes frames below threshold' do
+      new_engine = described_class.new
+      f = new_engine.create_frame(name: :cold, domain: :test)
+      100.times { f.decay! }
+      expect(new_engine.active_frames).not_to include(f)
+    end
+  end
+
+  describe '#frames_by_domain' do
+    before do
+      engine.create_frame(name: :motion, domain: :physics)
+      engine.create_frame(name: :competition, domain: :sports)
+    end
+
+    it 'returns only frames matching the domain' do
+      result = engine.frames_by_domain(domain: :physics)
+      expect(result.map(&:domain)).to all(eq(:physics))
+    end
+  end
+
+  describe '#related_frames' do
+    it 'traverses relations to return related frames' do
+      target = engine.create_frame(name: :payment, domain: :commerce)
+      engine.add_frame_relation(frame_id: frame.id, relation: :has_subframe, target_frame_id: target.id)
+      related = engine.related_frames(frame_id: frame.id)
+      expect(related).to include(target)
+    end
+
+    it 'returns empty array for unknown frame' do
+      expect(engine.related_frames(frame_id: 'bogus')).to eq([])
+    end
+  end
+
+  describe '#most_activated' do
+    it 'returns top N frames sorted by activation desc' do
+      f2 = engine.create_frame(name: :motion, domain: :physics)
+      5.times { engine.activate_frame(frame_id: frame.id) }
+      result = engine.most_activated(limit: 2)
+      expect(result.first).to eq(frame)
+      expect(result).not_to include(f2) if result.size < 2
+    end
+  end
+
+  describe '#instances_for_frame' do
+    it 'returns all instances of a specific frame' do
+      engine.instantiate_frame(frame_id: frame.id, context: 'ctx1')
+      engine.instantiate_frame(frame_id: frame.id, context: 'ctx2')
+      expect(engine.instances_for_frame(frame_id: frame.id).size).to eq(2)
+    end
+  end
+
+  describe '#complete_frames' do
+    it 'returns only complete frames' do
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer,  filler: 'Alice')
+      engine.fill_slot(frame_id: frame.id, slot_name: :seller, filler: 'Bob')
+      engine.fill_slot(frame_id: frame.id, slot_name: :goods,  filler: 'coffee')
+      expect(engine.complete_frames).to include(frame)
+    end
+
+    it 'excludes incomplete frames' do
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')
+      expect(engine.complete_frames).not_to include(frame)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all frame activations' do
+      initial = frame.activation
+      engine.decay_all
+      expect(frame.activation).to be < initial
+    end
+  end
+
+  describe '#prune_inactive' do
+    it 'removes frames with activation <= 0.05' do
+      f = engine.create_frame(name: :ghost, domain: :test)
+      100.times { f.decay! }
+      engine.prune_inactive
+      expect(engine.instances_for_frame(frame_id: f.id)).to be_empty
+    end
+
+    it 'retains frames with activation above threshold' do
+      5.times { engine.activate_frame(frame_id: frame.id) }
+      engine.prune_inactive
+      expect(engine.active_frames).to include(frame)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash with expected keys' do
+      h = engine.to_h
+      expect(h).to include(:frame_count, :instance_count, :active_count, :complete_count, :domains)
+    end
+
+    it 'reflects current state' do
+      expect(engine.to_h[:frame_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/language/frame_semantics/helpers/frame_instance_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Language::FrameSemantics::Helpers::FrameInstance do
+  let(:frame_id)    { SecureRandom.uuid }
+  let(:frame_name)  { :commercial_transaction }
+  let(:slot_fillers) do
+    { buyer: 'Alice', seller: 'Bob', goods: nil }
+  end
+
+  subject(:instance) do
+    described_class.new(
+      frame_id:     frame_id,
+      frame_name:   frame_name,
+      slot_fillers: slot_fillers,
+      context:      'buying coffee',
+      confidence:   0.85
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(instance.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores frame metadata' do
+      expect(instance.frame_id).to eq(frame_id)
+      expect(instance.frame_name).to eq(frame_name)
+    end
+
+    it 'duplicates slot_fillers' do
+      inst = instance
+      slot_fillers[:buyer] = 'Charlie'
+      expect(inst.slot_fillers[:buyer]).to eq('Alice')
+    end
+
+    it 'stores context and confidence' do
+      expect(instance.context).to eq('buying coffee')
+      expect(instance.confidence).to eq(0.85)
+    end
+  end
+
+  describe '#filled_count' do
+    it 'counts non-nil fillers' do
+      expect(instance.filled_count).to eq(2)
+    end
+
+    it 'returns 0 when all fillers are nil' do
+      empty = described_class.new(
+        frame_id: frame_id, frame_name: frame_name,
+        slot_fillers: { buyer: nil }, context: 'x'
+      )
+      expect(empty.filled_count).to eq(0)
+    end
+  end
+
+  describe '#complete?' do
+    it 'returns true when at least one slot is filled' do
+      expect(instance.complete?).to be true
+    end
+
+    it 'returns false when all slots are nil' do
+      empty = described_class.new(
+        frame_id: frame_id, frame_name: frame_name,
+        slot_fillers: { buyer: nil }, context: 'x'
+      )
+      expect(empty.complete?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      h = instance.to_h
+      expect(h).to include(:id, :frame_id, :frame_name, :slot_fillers,
+                           :context, :confidence, :filled_count, :complete, :created_at)
+    end
+
+    it 'includes filled_count and complete flag' do
+      h = instance.to_h
+      expect(h[:filled_count]).to eq(2)
+      expect(h[:complete]).to be true
+    end
+  end
+end