lex-conceptual-metaphor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb3da9900840165ae3f63ca71850bda064b046df078cf2aea51ce64e2948adbd
+  data.tar.gz: 1ddee2263dcb341d811fb8457fb239f855efd48f51d64d58d91a91651c1a7506
+SHA512:
+  metadata.gz: 5622988996a7f7871587dc50d28c395487819ceb4625c7a9f394f84acfc2b038a6f4307ddcab7ecd80d96a9d75517edc5d03bb30641737723081322e37a83c3f
+  data.tar.gz: 3e379a94b39799a96f1a31f252494e7fb3194125ed17669fdec7c384a89f92aa0ead653f4321f918e742799c77f149bf3a1f721149fa182c118d9a1240d94ef4

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-rspec'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-conceptual-metaphor.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/conceptual_metaphor/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-conceptual-metaphor'
+  spec.version       = Legion::Extensions::ConceptualMetaphor::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Conceptual Metaphor'
+  spec.description   = 'Lakoff & Johnson conceptual metaphor theory — understanding abstractions ' \
+                       'through embodied metaphors for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-conceptual-metaphor'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-conceptual-metaphor'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-conceptual-metaphor'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-conceptual-metaphor'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-conceptual-metaphor/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-conceptual-metaphor.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/conceptual_metaphor/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      class Client
+        include Runners::ConceptualMetaphor
+
+        def initialize(engine: nil)
+          @engine = engine || Helpers::MetaphorEngine.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conceptual_metaphor/helpers/constants.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      module Helpers
+        module Constants
+          MAX_METAPHORS = 200
+          MAX_MAPPINGS = 500
+          MAX_DOMAINS = 100
+          MAX_HISTORY = 300
+
+          DEFAULT_STRENGTH = 0.5
+          STRENGTH_FLOOR = 0.0
+          STRENGTH_CEILING = 1.0
+
+          REINFORCEMENT_BOOST = 0.1
+          DECAY_RATE = 0.02
+          STALE_THRESHOLD = 120
+
+          CONVENTIONALITY_THRESHOLD = 0.7
+          NOVELTY_THRESHOLD = 0.3
+
+          METAPHOR_TYPES = %i[structural orientational ontological].freeze
+
+          CONVENTIONALITY_LABELS = {
+            (0.8..)     => :dead,
+            (0.6...0.8) => :conventional,
+            (0.4...0.6) => :familiar,
+            (0.2...0.4) => :novel,
+            (..0.2)     => :creative
+          }.freeze
+
+          STRENGTH_LABELS = {
+            (0.8..)     => :dominant,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :fading
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conceptual_metaphor/helpers/metaphor.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      module Helpers
+        class Metaphor
+          include Constants
+
+          attr_reader :id, :source_domain, :target_domain, :metaphor_type,
+                      :mappings, :entailments, :strength, :conventionality,
+                      :use_count, :created_at, :last_used_at
+
+          def initialize(source_domain:, target_domain:, metaphor_type:,
+                         mappings:, strength: nil, conventionality: nil)
+            @id              = SecureRandom.uuid
+            @source_domain   = source_domain
+            @target_domain   = target_domain
+            @metaphor_type   = metaphor_type
+            @mappings        = mappings
+            @entailments     = []
+            @strength        = (strength || DEFAULT_STRENGTH).to_f.clamp(STRENGTH_FLOOR, STRENGTH_CEILING)
+            @conventionality = (conventionality || DEFAULT_STRENGTH).to_f.clamp(STRENGTH_FLOOR, STRENGTH_CEILING)
+            @use_count       = 0
+            @created_at      = Time.now.utc
+            @last_used_at    = @created_at
+          end
+
+          def use!
+            @use_count   += 1
+            @last_used_at = Time.now.utc
+            @strength     = (@strength + REINFORCEMENT_BOOST).clamp(STRENGTH_FLOOR, STRENGTH_CEILING)
+            increase_conventionality
+          end
+
+          def add_entailment(entailment)
+            @entailments << entailment
+          end
+
+          def map_concept(source_concept)
+            @mappings[source_concept]
+          end
+
+          def coverage
+            return 0.0 if @mappings.empty?
+
+            @mappings.values.compact.size.to_f / @mappings.size
+          end
+
+          def conventional?
+            @conventionality >= CONVENTIONALITY_THRESHOLD
+          end
+
+          def novel?
+            @conventionality <= NOVELTY_THRESHOLD
+          end
+
+          def conventionality_label
+            CONVENTIONALITY_LABELS.find { |range, _| range.cover?(@conventionality) }&.last || :unknown
+          end
+
+          def strength_label
+            STRENGTH_LABELS.find { |range, _| range.cover?(@strength) }&.last || :unknown
+          end
+
+          def decay!
+            @strength = (@strength - DECAY_RATE).clamp(STRENGTH_FLOOR, STRENGTH_CEILING)
+          end
+
+          def stale?
+            (Time.now.utc - @last_used_at) > STALE_THRESHOLD
+          end
+
+          def to_h
+            {
+              id:                    @id,
+              source_domain:         @source_domain,
+              target_domain:         @target_domain,
+              metaphor_type:         @metaphor_type,
+              mappings:              @mappings,
+              entailments:           @entailments,
+              strength:              @strength,
+              conventionality:       @conventionality,
+              conventionality_label: conventionality_label,
+              strength_label:        strength_label,
+              use_count:             @use_count,
+              coverage:              coverage,
+              created_at:            @created_at,
+              last_used_at:          @last_used_at
+            }
+          end
+
+          private
+
+          def increase_conventionality
+            increment = REINFORCEMENT_BOOST * 0.5
+            @conventionality = (@conventionality + increment).clamp(STRENGTH_FLOOR, STRENGTH_CEILING)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conceptual_metaphor/helpers/metaphor_engine.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      module Helpers
+        class MetaphorEngine
+          include Constants
+
+          attr_reader :history
+
+          def initialize
+            @metaphors = {}
+            @domains   = Set.new
+            @history   = []
+          end
+
+          def create_metaphor(source_domain:, target_domain:, metaphor_type:,
+                              mappings:, strength: nil, conventionality: nil)
+            evict_oldest if @metaphors.size >= MAX_METAPHORS
+
+            return { success: false, reason: :invalid_metaphor_type } unless METAPHOR_TYPES.include?(metaphor_type)
+
+            metaphor = Metaphor.new(
+              source_domain:   source_domain,
+              target_domain:   target_domain,
+              metaphor_type:   metaphor_type,
+              mappings:        mappings,
+              strength:        strength,
+              conventionality: conventionality
+            )
+
+            @metaphors[metaphor.id] = metaphor
+            register_domain(source_domain)
+            register_domain(target_domain)
+            record_history(:created, metaphor.id)
+            metaphor
+          end
+
+          def apply_metaphor(metaphor_id:, source_concept:)
+            metaphor = @metaphors[metaphor_id]
+            return { found: false } unless metaphor
+
+            target = metaphor.map_concept(source_concept)
+            return { found: true, mapped: false } unless target
+
+            metaphor.use!
+            record_history(:applied, metaphor_id)
+            build_apply_result(metaphor, source_concept, target)
+          end
+
+          def add_entailment(metaphor_id:, entailment:)
+            metaphor = @metaphors[metaphor_id]
+            return { success: false, reason: :not_found } unless metaphor
+
+            metaphor.add_entailment(entailment)
+            record_history(:entailment_added, metaphor_id)
+            { success: true, metaphor_id: metaphor_id, entailment_count: metaphor.entailments.size }
+          end
+
+          def find_by_target(target_domain:)
+            @metaphors.values.select { |m| m.target_domain == target_domain }
+          end
+
+          def find_by_source(source_domain:)
+            @metaphors.values.select { |m| m.source_domain == source_domain }
+          end
+
+          def find_by_domain(domain:)
+            @metaphors.values.select do |m|
+              m.source_domain == domain || m.target_domain == domain
+            end
+          end
+
+          def conventional_metaphors
+            @metaphors.values.select(&:conventional?)
+          end
+
+          def novel_metaphors
+            @metaphors.values.select(&:novel?)
+          end
+
+          def strongest(limit: 5)
+            @metaphors.values.sort_by { |m| -m.strength }.first(limit)
+          end
+
+          def by_type(metaphor_type:)
+            @metaphors.values.select { |m| m.metaphor_type == metaphor_type }
+          end
+
+          def decay_all
+            @metaphors.each_value(&:decay!)
+          end
+
+          def prune_weak
+            weak_ids = @metaphors.select { |_id, m| m.strength <= 0.05 }.keys
+            weak_ids.each { |id| @metaphors.delete(id) }
+            weak_ids.size
+          end
+
+          def to_h
+            {
+              total_metaphors:    @metaphors.size,
+              total_domains:      @domains.size,
+              conventional_count: conventional_metaphors.size,
+              novel_count:        novel_metaphors.size,
+              history_count:      @history.size,
+              domains:            @domains.to_a,
+              type_counts:        type_counts
+            }
+          end
+
+          private
+
+          def build_apply_result(metaphor, source_concept, target)
+            {
+              found:          true,
+              mapped:         true,
+              source_concept: source_concept,
+              target_concept: target,
+              strength:       metaphor.strength,
+              metaphor_id:    metaphor.id
+            }
+          end
+
+          def register_domain(domain)
+            @domains.add(domain)
+            @domains.delete(@domains.first) if @domains.size > MAX_DOMAINS
+          end
+
+          def evict_oldest
+            oldest_id = @metaphors.min_by { |_id, m| m.last_used_at }&.first
+            @metaphors.delete(oldest_id) if oldest_id
+          end
+
+          def record_history(event, metaphor_id)
+            @history << { event: event, metaphor_id: metaphor_id, at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+
+          def type_counts
+            @metaphors.values.each_with_object(Hash.new(0)) do |m, counts|
+              counts[m.metaphor_type] += 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conceptual_metaphor/runners/conceptual_metaphor.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      module Runners
+        module ConceptualMetaphor
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_metaphor(source_domain:, target_domain:, metaphor_type:,
+                              mappings:, strength: nil, conventionality: nil, **)
+            unless Helpers::Constants::METAPHOR_TYPES.include?(metaphor_type)
+              return { success: false, error: :invalid_metaphor_type,
+                       valid_types: Helpers::Constants::METAPHOR_TYPES }
+            end
+
+            result = engine.create_metaphor(
+              source_domain:   source_domain,
+              target_domain:   target_domain,
+              metaphor_type:   metaphor_type,
+              mappings:        mappings,
+              strength:        strength,
+              conventionality: conventionality
+            )
+
+            return result unless result.is_a?(Helpers::Metaphor)
+
+            Legion::Logging.debug "[conceptual_metaphor] created #{source_domain}->#{target_domain} " \
+                                  "type=#{metaphor_type} id=#{result.id[0..7]}"
+            { success: true, metaphor_id: result.id, source_domain: source_domain,
+              target_domain: target_domain, metaphor_type: metaphor_type,
+              strength: result.strength, conventionality: result.conventionality }
+          end
+
+          def apply_metaphor(metaphor_id:, source_concept:, **)
+            result = engine.apply_metaphor(metaphor_id: metaphor_id, source_concept: source_concept)
+            Legion::Logging.debug "[conceptual_metaphor] apply id=#{metaphor_id[0..7]} " \
+                                  "concept=#{source_concept} mapped=#{result[:mapped]}"
+            { success: true }.merge(result)
+          end
+
+          def add_metaphor_entailment(metaphor_id:, entailment:, **)
+            result = engine.add_entailment(metaphor_id: metaphor_id, entailment: entailment)
+            Legion::Logging.debug "[conceptual_metaphor] entailment id=#{metaphor_id[0..7]} " \
+                                  "success=#{result[:success]}"
+            result
+          end
+
+          def find_metaphors_for(domain:, **)
+            metaphors = engine.find_by_domain(domain: domain)
+            Legion::Logging.debug "[conceptual_metaphor] find domain=#{domain} count=#{metaphors.size}"
+            { success: true, domain: domain, metaphors: metaphors.map(&:to_h), count: metaphors.size }
+          end
+
+          def conventional_metaphors(**)
+            metaphors = engine.conventional_metaphors
+            Legion::Logging.debug "[conceptual_metaphor] conventional count=#{metaphors.size}"
+            { success: true, metaphors: metaphors.map(&:to_h), count: metaphors.size }
+          end
+
+          def novel_metaphors(**)
+            metaphors = engine.novel_metaphors
+            Legion::Logging.debug "[conceptual_metaphor] novel count=#{metaphors.size}"
+            { success: true, metaphors: metaphors.map(&:to_h), count: metaphors.size }
+          end
+
+          def strongest_metaphors(limit: 5, **)
+            metaphors = engine.strongest(limit: limit)
+            Legion::Logging.debug "[conceptual_metaphor] strongest limit=#{limit} count=#{metaphors.size}"
+            { success: true, metaphors: metaphors.map(&:to_h), count: metaphors.size }
+          end
+
+          def metaphors_by_type(metaphor_type:, **)
+            metaphors = engine.by_type(metaphor_type: metaphor_type)
+            Legion::Logging.debug "[conceptual_metaphor] by_type=#{metaphor_type} count=#{metaphors.size}"
+            { success: true, metaphor_type: metaphor_type, metaphors: metaphors.map(&:to_h),
+              count: metaphors.size }
+          end
+
+          def update_conceptual_metaphor(**)
+            engine.decay_all
+            pruned = engine.prune_weak
+            Legion::Logging.debug "[conceptual_metaphor] decay+prune pruned=#{pruned}"
+            { success: true, pruned: pruned }
+          end
+
+          def conceptual_metaphor_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[conceptual_metaphor] stats total=#{stats[:total_metaphors]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::MetaphorEngine.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/conceptual_metaphor/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/conceptual_metaphor.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/conceptual_metaphor/version'
+require 'legion/extensions/conceptual_metaphor/helpers/constants'
+require 'legion/extensions/conceptual_metaphor/helpers/metaphor'
+require 'legion/extensions/conceptual_metaphor/helpers/metaphor_engine'
+require 'legion/extensions/conceptual_metaphor/runners/conceptual_metaphor'
+require 'legion/extensions/conceptual_metaphor/client'
+
+module Legion
+  module Extensions
+    module ConceptualMetaphor
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/conceptual_metaphor/client_spec.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::ConceptualMetaphor::Client do
+  subject(:client) { described_class.new }
+
+  it 'creates a metaphor' do
+    result = client.create_metaphor(
+      source_domain: :money, target_domain: :time,
+      metaphor_type: :structural, mappings: { spend: :waste }
+    )
+    expect(result[:success]).to be true
+  end
+
+  it 'applies a metaphor' do
+    created = client.create_metaphor(
+      source_domain: :money, target_domain: :time,
+      metaphor_type: :structural, mappings: { spend: :waste }
+    )
+    result = client.apply_metaphor(
+      metaphor_id: created[:metaphor_id], source_concept: :spend
+    )
+    expect(result[:target_concept]).to eq(:waste)
+  end
+
+  it 'returns stats' do
+    result = client.conceptual_metaphor_stats
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/conceptual_metaphor/helpers/metaphor_engine_spec.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::ConceptualMetaphor::Helpers::MetaphorEngine do
+  subject(:engine) { described_class.new }
+
+  let(:metaphor) do
+    engine.create_metaphor(
+      source_domain: :money,
+      target_domain: :time,
+      metaphor_type: :structural,
+      mappings:      { spend: :waste, save: :conserve }
+    )
+  end
+
+  describe '#create_metaphor' do
+    it 'creates and stores a metaphor' do
+      result = metaphor
+      expect(result).to be_a(Legion::Extensions::ConceptualMetaphor::Helpers::Metaphor)
+      expect(result.source_domain).to eq(:money)
+    end
+
+    it 'rejects invalid metaphor types' do
+      result = engine.create_metaphor(
+        source_domain: :a, target_domain: :b,
+        metaphor_type: :invalid, mappings: {}
+      )
+      expect(result[:success]).to be false
+    end
+
+    it 'records history' do
+      metaphor
+      expect(engine.history.size).to eq(1)
+    end
+  end
+
+  describe '#apply_metaphor' do
+    it 'maps a source concept to target' do
+      result = engine.apply_metaphor(metaphor_id: metaphor.id, source_concept: :spend)
+      expect(result[:mapped]).to be true
+      expect(result[:target_concept]).to eq(:waste)
+    end
+
+    it 'returns found: false for unknown metaphor' do
+      result = engine.apply_metaphor(metaphor_id: 'nonexistent', source_concept: :spend)
+      expect(result[:found]).to be false
+    end
+
+    it 'returns mapped: false for unmapped concept' do
+      result = engine.apply_metaphor(metaphor_id: metaphor.id, source_concept: :borrow)
+      expect(result[:mapped]).to be false
+    end
+  end
+
+  describe '#add_entailment' do
+    it 'adds entailment to metaphor' do
+      result = engine.add_entailment(metaphor_id: metaphor.id, entailment: 'time is valuable')
+      expect(result[:success]).to be true
+      expect(result[:entailment_count]).to eq(1)
+    end
+
+    it 'returns error for unknown metaphor' do
+      result = engine.add_entailment(metaphor_id: 'bad', entailment: 'test')
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#find_by_domain' do
+    it 'finds metaphors involving the domain' do
+      metaphor
+      results = engine.find_by_domain(domain: :time)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#find_by_source' do
+    it 'finds metaphors by source domain' do
+      metaphor
+      results = engine.find_by_source(source_domain: :money)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#find_by_target' do
+    it 'finds metaphors by target domain' do
+      metaphor
+      results = engine.find_by_target(target_domain: :time)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#conventional_metaphors' do
+    it 'returns metaphors with high conventionality' do
+      engine.create_metaphor(
+        source_domain: :war, target_domain: :argument,
+        metaphor_type: :structural, mappings: { attack: :criticize },
+        conventionality: 0.9
+      )
+      expect(engine.conventional_metaphors.size).to eq(1)
+    end
+  end
+
+  describe '#novel_metaphors' do
+    it 'returns metaphors with low conventionality' do
+      engine.create_metaphor(
+        source_domain: :ocean, target_domain: :emotion,
+        metaphor_type: :ontological, mappings: { depth: :intensity },
+        conventionality: 0.1
+      )
+      expect(engine.novel_metaphors.size).to eq(1)
+    end
+  end
+
+  describe '#strongest' do
+    it 'returns metaphors sorted by strength' do
+      metaphor
+      engine.create_metaphor(
+        source_domain: :war, target_domain: :argument,
+        metaphor_type: :structural, mappings: {}, strength: 0.9
+      )
+      results = engine.strongest(limit: 2)
+      expect(results.first.strength).to be >= results.last.strength
+    end
+  end
+
+  describe '#by_type' do
+    it 'filters by metaphor type' do
+      metaphor
+      engine.create_metaphor(
+        source_domain: :container, target_domain: :mind,
+        metaphor_type: :ontological, mappings: { full: :knowledgeable }
+      )
+      structural = engine.by_type(metaphor_type: :structural)
+      expect(structural.size).to eq(1)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces strength of all metaphors' do
+      original = metaphor.strength
+      engine.decay_all
+      expect(metaphor.strength).to be < original
+    end
+  end
+
+  describe '#prune_weak' do
+    it 'removes very weak metaphors' do
+      weak = engine.create_metaphor(
+        source_domain: :a, target_domain: :b,
+        metaphor_type: :structural, mappings: {}, strength: 0.03
+      )
+      30.times { weak.decay! }
+      pruned = engine.prune_weak
+      expect(pruned).to be >= 1
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary stats' do
+      metaphor
+      stats = engine.to_h
+      expect(stats[:total_metaphors]).to eq(1)
+      expect(stats[:total_domains]).to eq(2)
+      expect(stats).to include(:type_counts, :conventional_count, :novel_count)
+    end
+  end
+end

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

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/conceptual_metaphor/runners/conceptual_metaphor_spec.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/spec_helper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Helpers
+      module Lex; end
+    end
+  end
+
+  module Logging
+    def self.debug(*); end
+
+    def self.info(*); end
+
+    def self.warn(*); end
+
+    def self.error(*); end
+  end
+end
+
+require 'legion/extensions/conceptual_metaphor'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.filter_run_when_matching :focus
+  config.order = :random
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: lex-conceptual-metaphor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Lakoff & Johnson conceptual metaphor theory — understanding abstractions
+  through embodied metaphors for brain-modeled agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-conceptual-metaphor.gemspec
+- lib/legion/extensions/conceptual_metaphor.rb
+- lib/legion/extensions/conceptual_metaphor/client.rb
+- lib/legion/extensions/conceptual_metaphor/helpers/constants.rb
+- lib/legion/extensions/conceptual_metaphor/helpers/metaphor.rb
+- lib/legion/extensions/conceptual_metaphor/helpers/metaphor_engine.rb
+- lib/legion/extensions/conceptual_metaphor/runners/conceptual_metaphor.rb
+- lib/legion/extensions/conceptual_metaphor/version.rb
+- spec/legion/extensions/conceptual_metaphor/client_spec.rb
+- spec/legion/extensions/conceptual_metaphor/helpers/metaphor_engine_spec.rb
+- spec/legion/extensions/conceptual_metaphor/helpers/metaphor_spec.rb
+- spec/legion/extensions/conceptual_metaphor/runners/conceptual_metaphor_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-conceptual-metaphor
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-conceptual-metaphor
+  source_code_uri: https://github.com/LegionIO/lex-conceptual-metaphor
+  documentation_uri: https://github.com/LegionIO/lex-conceptual-metaphor
+  changelog_uri: https://github.com/LegionIO/lex-conceptual-metaphor
+  bug_tracker_uri: https://github.com/LegionIO/lex-conceptual-metaphor/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Conceptual Metaphor
+test_files: []