lex-agentic-language 0.1.0

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        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
+  end
+end

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        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
+  end
+end

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        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
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/conceptual_metaphor/version'
+require 'legion/extensions/agentic/language/conceptual_metaphor/helpers/constants'
+require 'legion/extensions/agentic/language/conceptual_metaphor/helpers/metaphor'
+require 'legion/extensions/agentic/language/conceptual_metaphor/helpers/metaphor_engine'
+require 'legion/extensions/agentic/language/conceptual_metaphor/runners/conceptual_metaphor'
+require 'legion/extensions/agentic/language/conceptual_metaphor/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module ConceptualMetaphor
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics/helpers/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          module Helpers
+            class Client
+              include Runners::FrameSemantics
+
+              private
+
+              def engine
+                @engine ||= FrameEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics/helpers/constants.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          module Helpers
+            SLOT_TYPES        = %i[core peripheral extra_thematic].freeze
+            FRAME_RELATIONS   = %i[inherits_from is_inherited_by uses is_used_by subframe_of has_subframe].freeze
+            ACTIVATION_LABELS = {
+              (0.8..)     => :dominant,
+              (0.6...0.8) => :active,
+              (0.4...0.6) => :primed,
+              (0.2...0.4) => :latent,
+              (..0.2)     => :inactive
+            }.freeze
+
+            MAX_FRAMES         = 150
+            MAX_INSTANCES      = 500
+            MAX_HISTORY        = 500
+            DEFAULT_ACTIVATION = 0.3
+            ACTIVATION_BOOST   = 0.15
+            ACTIVATION_DECAY   = 0.03
+            SLOT_FILL_BOOST    = 0.1
+            COMPLETION_THRESHOLD = 0.7
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics/helpers/frame.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          module Helpers
+            class Frame
+              attr_reader :id, :name, :domain, :slots, :relations, :activation, :activation_count, :created_at
+
+              def initialize(name:, domain:)
+                @id               = SecureRandom.uuid
+                @name             = name
+                @domain           = domain
+                @slots            = {}
+                @relations        = []
+                @activation       = DEFAULT_ACTIVATION
+                @activation_count = 0
+                @created_at       = Time.now.utc
+              end
+
+              def add_slot(name:, slot_type: :core, required: true)
+                @slots[name] = { type: slot_type, filler: nil, required: required }
+                self
+              end
+
+              def fill_slot(name:, filler:)
+                return false unless @slots.key?(name)
+
+                @slots[name][:filler] = filler
+                @activation = [@activation + SLOT_FILL_BOOST, 1.0].min
+                true
+              end
+
+              def clear_slot(name:)
+                return false unless @slots.key?(name)
+
+                @slots[name][:filler] = nil
+                true
+              end
+
+              def core_slots
+                @slots.select { |_k, v| v[:type] == :core }
+              end
+
+              def filled_slots
+                @slots.reject { |_k, v| v[:filler].nil? }
+              end
+
+              def completion_ratio
+                cs = core_slots
+                return 0.0 if cs.empty?
+
+                filled_core = cs.count { |_k, v| !v[:filler].nil? }
+                filled_core.to_f / cs.size
+              end
+
+              def complete?
+                completion_ratio >= COMPLETION_THRESHOLD
+              end
+
+              def activate!
+                @activation = [@activation + ACTIVATION_BOOST, 1.0].min
+                @activation_count += 1
+                self
+              end
+
+              def decay!
+                @activation = [@activation - ACTIVATION_DECAY, 0.0].max
+                self
+              end
+
+              def activation_label
+                ACTIVATION_LABELS.each do |range, label|
+                  return label if range.cover?(@activation)
+                end
+                :inactive
+              end
+
+              def add_relation(relation:, target_frame_id:)
+                @relations << { relation: relation, target_frame_id: target_frame_id }
+                self
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  name:             @name,
+                  domain:           @domain,
+                  slots:            @slots,
+                  relations:        @relations,
+                  activation:       @activation,
+                  activation_label: activation_label,
+                  activation_count: @activation_count,
+                  completion_ratio: completion_ratio,
+                  complete:         complete?,
+                  created_at:       @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end