lex-analogical-reasoning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 07b0687586726bfa7bfdc4a13bda4aa3d0baef51df046af756878f691fb307fa
+  data.tar.gz: ff5d3787c7f9e431cc871166ed6b5cbf259070c1bb66804e2e4436667e0a0ba0
+SHA512:
+  metadata.gz: 82fe91c2dd597efa14a8e442edfd4ed236732389434ff4027dbcd1bfcc2a295fda404afdb973ed6ecd42243be9f513186fc5f18a9bb6d904f6026aa9ad3ca387
+  data.tar.gz: b475a0e147e1f2b18d29a5a4e56afac8ea22f1d33f370240f5466f5e1200b941450b8048b345e120c918e224f97ac6d6f51271c8added6a3cd641d70c841e3f2

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-analogical-reasoning.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/analogical_reasoning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-analogical-reasoning'
+  spec.version       = Legion::Extensions::AnalogicalReasoning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Analogical Reasoning'
+  spec.description   = 'Analogical reasoning engine (Gentner structure mapping, Hofstadter, ' \
+                       'Holyoak multi-constraint) for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-analogical-reasoning'
+  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-analogical-reasoning'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-analogical-reasoning'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-analogical-reasoning'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-analogical-reasoning/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-analogical-reasoning.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/analogical_reasoning/helpers/constants'
+require 'legion/extensions/analogical_reasoning/helpers/structure_map'
+require 'legion/extensions/analogical_reasoning/helpers/analogy_engine'
+require 'legion/extensions/analogical_reasoning/runners/analogical_reasoning'
+
+module Legion
+  module Extensions
+    module AnalogicalReasoning
+      class Client
+        include Runners::AnalogicalReasoning
+
+        def initialize(engine: nil, **)
+          @engine = engine || Helpers::AnalogyEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/analogical_reasoning/helpers/analogy_engine.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AnalogicalReasoning
+      module Helpers
+        class AnalogyEngine
+          include Constants
+
+          attr_reader :history
+
+          def initialize
+            @analogies = {}
+            @domains   = Set.new
+            @history   = []
+          end
+
+          def create_analogy(source_domain:, target_domain:, mappings:, mapping_type:, strength: nil)
+            evict_oldest_analogy if @analogies.size >= Constants::MAX_ANALOGIES
+
+            analogy = StructureMap.new(
+              source_domain: source_domain,
+              target_domain: target_domain,
+              mappings:      mappings,
+              mapping_type:  mapping_type,
+              strength:      strength
+            )
+
+            @analogies[analogy.id] = analogy
+            register_domain(source_domain)
+            register_domain(target_domain)
+            record_history(:created, analogy.id)
+
+            analogy
+          end
+
+          def find_analogies(domain:)
+            @analogies.values.select do |analogy|
+              analogy.source_domain == domain || analogy.target_domain == domain
+            end
+          end
+
+          def apply_analogy(analogy_id:, source_element:)
+            analogy = @analogies[analogy_id]
+            return { found: false } unless analogy
+
+            target_element = analogy.mappings[source_element]
+            return { found: true, mapped: false } unless target_element
+
+            analogy.use!
+            record_history(:applied, analogy_id)
+
+            {
+              found:          true,
+              mapped:         true,
+              source_element: source_element,
+              target_element: target_element,
+              confidence:     analogy.strength,
+              analogy_id:     analogy_id
+            }
+          end
+
+          def evaluate_similarity(source:, target:)
+            return 0.0 if source.empty? || target.empty?
+
+            structural = structural_overlap(source, target)
+            surface    = surface_overlap(source, target)
+            (Constants::STRUCTURAL_WEIGHT * structural) + (Constants::SURFACE_WEIGHT * surface)
+          end
+
+          def cross_domain_transfer(analogy_id:, source_knowledge:)
+            analogy = @analogies[analogy_id]
+            return { transferred: false, reason: :not_found } unless analogy
+
+            transferred = {}
+            source_knowledge.each do |key, value|
+              mapped_key = analogy.mappings.fetch(key, nil)
+              transferred[mapped_key] = value if mapped_key
+            end
+
+            analogy.use!
+            record_history(:transferred, analogy_id)
+
+            {
+              transferred:   true,
+              analogy_id:    analogy_id,
+              source_domain: analogy.source_domain,
+              target_domain: analogy.target_domain,
+              result:        transferred,
+              coverage:      coverage_ratio(source_knowledge, transferred)
+            }
+          end
+
+          def reinforce_analogy(analogy_id:, success:)
+            analogy = @analogies[analogy_id]
+            return { reinforced: false, reason: :not_found } unless analogy
+
+            if success
+              analogy.reinforce
+              record_history(:reinforced, analogy_id)
+            else
+              analogy.weaken
+              record_history(:weakened, analogy_id)
+            end
+
+            { reinforced: true, analogy_id: analogy_id, strength: analogy.strength, state: analogy.state }
+          end
+
+          def productive_analogies
+            @analogies.values.select(&:productive?)
+          end
+
+          def by_domain(domain:)
+            find_analogies(domain: domain)
+          end
+
+          def by_type(type:)
+            @analogies.values.select { |analogy| analogy.mapping_type == type }
+          end
+
+          def decay_all
+            @analogies.each_value(&:decay)
+          end
+
+          def prune_stale
+            stale_ids = @analogies.select { |_id, analogy| analogy.state == :stale }.keys
+            stale_ids.each { |id| @analogies.delete(id) }
+            stale_ids.size
+          end
+
+          def to_h
+            {
+              total_analogies:  @analogies.size,
+              total_domains:    @domains.size,
+              productive_count: productive_analogies.size,
+              history_count:    @history.size,
+              domains:          @domains.to_a,
+              analogy_states:   state_counts
+            }
+          end
+
+          private
+
+          def register_domain(domain)
+            @domains.add(domain)
+            evict_oldest_domain if @domains.size > Constants::MAX_DOMAINS
+          end
+
+          def evict_oldest_analogy
+            oldest_id = @analogies.min_by { |_id, analogy| analogy.last_used_at }&.first
+            @analogies.delete(oldest_id) if oldest_id
+          end
+
+          def evict_oldest_domain
+            @domains.delete(@domains.first)
+          end
+
+          def record_history(event, analogy_id)
+            entry = { event: event, analogy_id: analogy_id, at: Time.now.utc }
+            @history << entry
+            @history.shift while @history.size > Constants::MAX_HISTORY
+          end
+
+          def structural_overlap(source, target)
+            source_keys = source.keys.to_set(&:to_s)
+            target_keys = target.keys.to_set(&:to_s)
+            union = source_keys | target_keys
+            return 0.0 if union.empty?
+
+            (source_keys & target_keys).size.to_f / union.size
+          end
+
+          def surface_overlap(source, target)
+            common = source.keys.to_set(&:to_s) & target.keys.to_set(&:to_s)
+            surface_match_ratio(common, source, target)
+          end
+
+          def surface_match_ratio(common_keys, source, target)
+            return 0.0 if common_keys.empty?
+
+            matches = common_keys.count do |key|
+              sym     = key.to_sym
+              src_val = source.fetch(sym) { source[key] }
+              tgt_val = target.fetch(sym) { target[key] }
+              src_val == tgt_val && !src_val.nil?
+            end
+            matches.to_f / common_keys.size
+          end
+
+          def coverage_ratio(source_knowledge, transferred)
+            return 0.0 if source_knowledge.empty?
+
+            transferred.size.to_f / source_knowledge.size
+          end
+
+          def state_counts
+            @analogies.values.each_with_object(Hash.new(0)) do |analogy, counts|
+              counts[analogy.state] += 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AnalogicalReasoning
+      module Helpers
+        module Constants
+          MAX_ANALOGIES  = 200
+          MAX_DOMAINS    = 50
+          MAX_HISTORY    = 300
+
+          SIMILARITY_THRESHOLD = 0.4
+          STRUCTURAL_WEIGHT    = 0.7
+          SURFACE_WEIGHT       = 0.3
+
+          DEFAULT_STRENGTH    = 0.5
+          STRENGTH_FLOOR      = 0.05
+          STRENGTH_CEILING    = 0.95
+
+          REINFORCEMENT_RATE = 0.1
+          DECAY_RATE         = 0.01
+
+          MAPPING_TYPES   = %i[attribute relational system].freeze
+          ANALOGY_STATES  = %i[candidate validated productive stale].freeze
+          STATE_THRESHOLDS = {
+            productive: 0.75,
+            validated:  0.5,
+            candidate:  0.25
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/analogical_reasoning/helpers/structure_map.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module AnalogicalReasoning
+      module Helpers
+        class StructureMap
+          include Constants
+
+          attr_reader :id, :source_domain, :target_domain, :mappings, :mapping_type, :times_used, :created_at,
+                      :last_used_at, :strength
+
+          def initialize(source_domain:, target_domain:, mappings:, mapping_type:, strength: nil)
+            @id            = SecureRandom.uuid
+            @source_domain = source_domain
+            @target_domain = target_domain
+            @mappings      = mappings
+            @mapping_type  = mapping_type
+            @strength      = (strength || Constants::DEFAULT_STRENGTH).clamp(
+              Constants::STRENGTH_FLOOR,
+              Constants::STRENGTH_CEILING
+            )
+            @times_used    = 0
+            @created_at    = Time.now.utc
+            @last_used_at  = Time.now.utc
+          end
+
+          def structural_score
+            return 0.0 if mappings.empty?
+
+            relational_count = mappings.count { |_src, tgt| tgt.is_a?(Hash) && tgt[:type] == :relational }
+            relational_count.to_f / mappings.size
+          end
+
+          def surface_score
+            return 0.0 if mappings.empty?
+
+            attribute_count = mappings.count { |_src, tgt| !(tgt.is_a?(Hash) && tgt[:type] == :relational) }
+            attribute_count.to_f / mappings.size
+          end
+
+          def similarity_score
+            (Constants::STRUCTURAL_WEIGHT * structural_score) +
+              (Constants::SURFACE_WEIGHT * surface_score)
+          end
+
+          def use!
+            @times_used   += 1
+            @last_used_at  = Time.now.utc
+            reinforce(amount: Constants::REINFORCEMENT_RATE * 0.5)
+            self
+          end
+
+          def reinforce(amount: Constants::REINFORCEMENT_RATE)
+            @strength = (@strength + amount).clamp(Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING)
+            self
+          end
+
+          def weaken(amount: Constants::REINFORCEMENT_RATE)
+            @strength = (@strength - amount).clamp(Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING)
+            self
+          end
+
+          def decay
+            @strength = (@strength - Constants::DECAY_RATE).clamp(Constants::STRENGTH_FLOOR, Constants::STRENGTH_CEILING)
+            self
+          end
+
+          def state
+            thresholds = Constants::STATE_THRESHOLDS
+            if @strength >= thresholds[:productive]
+              :productive
+            elsif @strength >= thresholds[:validated]
+              :validated
+            elsif @strength >= thresholds[:candidate]
+              :candidate
+            else
+              :stale
+            end
+          end
+
+          def productive?
+            state == :productive
+          end
+
+          def to_h
+            {
+              id:               @id,
+              source_domain:    @source_domain,
+              target_domain:    @target_domain,
+              mappings:         @mappings,
+              mapping_type:     @mapping_type,
+              strength:         @strength,
+              structural_score: structural_score,
+              surface_score:    surface_score,
+              similarity_score: similarity_score,
+              state:            state,
+              times_used:       @times_used,
+              created_at:       @created_at,
+              last_used_at:     @last_used_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module AnalogicalReasoning
+      module Runners
+        module AnalogicalReasoning
+          def create_analogy(source_domain:, target_domain:, mappings:, mapping_type: :relational, strength: nil, **)
+            unless Helpers::Constants::MAPPING_TYPES.include?(mapping_type)
+              return { success: false, error: :invalid_mapping_type,
+                       valid_types: Helpers::Constants::MAPPING_TYPES }
+            end
+
+            analogy = engine.create_analogy(
+              source_domain: source_domain,
+              target_domain: target_domain,
+              mappings:      mappings,
+              mapping_type:  mapping_type,
+              strength:      strength
+            )
+
+            Legion::Logging.debug "[analogical_reasoning] created analogy id=#{analogy.id[0..7]} " \
+                                  "#{source_domain}->#{target_domain} type=#{mapping_type}"
+
+            { success: true, analogy_id: analogy.id, source_domain: source_domain,
+              target_domain: target_domain, mapping_type: mapping_type,
+              strength: analogy.strength, state: analogy.state }
+          end
+
+          def find_analogies(domain:, **)
+            analogies = engine.find_analogies(domain: domain)
+            Legion::Logging.debug "[analogical_reasoning] find domain=#{domain} count=#{analogies.size}"
+            { success: true, domain: domain, analogies: analogies.map(&:to_h), count: analogies.size }
+          end
+
+          def apply_analogy(analogy_id:, source_element:, **)
+            result = engine.apply_analogy(analogy_id: analogy_id, source_element: source_element)
+
+            Legion::Logging.debug "[analogical_reasoning] apply id=#{analogy_id[0..7]} " \
+                                  "element=#{source_element} mapped=#{result[:mapped]}"
+
+            { success: true }.merge(result)
+          end
+
+          def evaluate_similarity(source:, target:, **)
+            score = engine.evaluate_similarity(source: source, target: target)
+            above_threshold = score >= Helpers::Constants::SIMILARITY_THRESHOLD
+
+            Legion::Logging.debug "[analogical_reasoning] similarity=#{score.round(3)} " \
+                                  "above_threshold=#{above_threshold}"
+
+            { success: true, similarity_score: score, above_threshold: above_threshold,
+              threshold: Helpers::Constants::SIMILARITY_THRESHOLD }
+          end
+
+          def cross_domain_transfer(analogy_id:, source_knowledge:, **)
+            result = engine.cross_domain_transfer(analogy_id: analogy_id, source_knowledge: source_knowledge)
+
+            Legion::Logging.debug "[analogical_reasoning] transfer id=#{analogy_id[0..7]} " \
+                                  "transferred=#{result[:transferred]} coverage=#{result[:coverage]&.round(2)}"
+
+            { success: true }.merge(result)
+          end
+
+          def reinforce_analogy(analogy_id:, success:, **)
+            result = engine.reinforce_analogy(analogy_id: analogy_id, success: success)
+
+            Legion::Logging.debug "[analogical_reasoning] reinforce id=#{analogy_id[0..7]} " \
+                                  "success=#{success} new_state=#{result[:state]}"
+
+            { success: true }.merge(result)
+          end
+
+          def productive_analogies(**)
+            analogies = engine.productive_analogies
+            Legion::Logging.debug "[analogical_reasoning] productive count=#{analogies.size}"
+            { success: true, analogies: analogies.map(&:to_h), count: analogies.size }
+          end
+
+          def update_analogical_reasoning(**)
+            engine.decay_all
+            pruned = engine.prune_stale
+            Legion::Logging.debug "[analogical_reasoning] decay+prune pruned=#{pruned}"
+            { success: true, pruned: pruned }
+          end
+
+          def analogical_reasoning_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[analogical_reasoning] stats total=#{stats[:total_analogies]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::AnalogyEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/analogical_reasoning.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/analogical_reasoning/version'
+require 'legion/extensions/analogical_reasoning/helpers/constants'
+require 'legion/extensions/analogical_reasoning/helpers/structure_map'
+require 'legion/extensions/analogical_reasoning/helpers/analogy_engine'
+require 'legion/extensions/analogical_reasoning/runners/analogical_reasoning'
+require 'legion/extensions/analogical_reasoning/client'
+
+module Legion
+  module Extensions
+    module AnalogicalReasoning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/analogical_reasoning/client'
+
+RSpec.describe Legion::Extensions::AnalogicalReasoning::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:create_analogy)
+    expect(client).to respond_to(:find_analogies)
+    expect(client).to respond_to(:apply_analogy)
+    expect(client).to respond_to(:evaluate_similarity)
+    expect(client).to respond_to(:cross_domain_transfer)
+    expect(client).to respond_to(:reinforce_analogy)
+    expect(client).to respond_to(:productive_analogies)
+    expect(client).to respond_to(:update_analogical_reasoning)
+    expect(client).to respond_to(:analogical_reasoning_stats)
+  end
+
+  it 'accepts an injected engine' do
+    custom_engine = Legion::Extensions::AnalogicalReasoning::Helpers::AnalogyEngine.new
+    client = described_class.new(engine: custom_engine)
+    expect(client).to be_a(described_class)
+  end
+
+  it 'creates a default engine when none provided' do
+    client = described_class.new
+    result = client.analogical_reasoning_stats
+    expect(result[:success]).to be true
+    expect(result[:total_analogies]).to eq(0)
+  end
+end