lex-agentic-inference 0.1.0

data/spec/legion/extensions/agentic/inference/analogical/client_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/analogical/client'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Analogical::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::Agentic::Inference::Analogical::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

data/spec/legion/extensions/agentic/inference/analogical/helpers/analogy_engine_spec.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/analogical/helpers/analogy_engine'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Analogical::Helpers::AnalogyEngine do
+  subject(:engine) { described_class.new }
+
+  let(:base_analogy_params) do
+    {
+      source_domain: :solar_system,
+      target_domain: :atom,
+      mappings:      { sun: :nucleus, planet: :electron },
+      mapping_type:  :relational
+    }
+  end
+
+  describe '#create_analogy' do
+    it 'creates and returns a StructureMap' do
+      analogy = engine.create_analogy(**base_analogy_params)
+      expect(analogy).to be_a(Legion::Extensions::Agentic::Inference::Analogical::Helpers::StructureMap)
+    end
+
+    it 'assigns correct domains' do
+      analogy = engine.create_analogy(**base_analogy_params)
+      expect(analogy.source_domain).to eq(:solar_system)
+      expect(analogy.target_domain).to eq(:atom)
+    end
+
+    it 'records the analogy in history' do
+      engine.create_analogy(**base_analogy_params)
+      expect(engine.history.last[:event]).to eq(:created)
+    end
+
+    it 'stores the analogy for retrieval' do
+      analogy = engine.create_analogy(**base_analogy_params)
+      result = engine.apply_analogy(analogy_id: analogy.id, source_element: :sun)
+      expect(result[:found]).to be true
+    end
+  end
+
+  describe '#find_analogies' do
+    it 'finds analogies by source domain' do
+      engine.create_analogy(**base_analogy_params)
+      results = engine.find_analogies(domain: :solar_system)
+      expect(results.size).to eq(1)
+    end
+
+    it 'finds analogies by target domain' do
+      engine.create_analogy(**base_analogy_params)
+      results = engine.find_analogies(domain: :atom)
+      expect(results.size).to eq(1)
+    end
+
+    it 'returns empty array when domain not found' do
+      results = engine.find_analogies(domain: :unknown)
+      expect(results).to be_empty
+    end
+
+    it 'finds across multiple analogies' do
+      engine.create_analogy(**base_analogy_params)
+      engine.create_analogy(
+        source_domain: :solar_system,
+        target_domain: :family,
+        mappings:      { sun: :parent },
+        mapping_type:  :relational
+      )
+      results = engine.find_analogies(domain: :solar_system)
+      expect(results.size).to eq(2)
+    end
+  end
+
+  describe '#apply_analogy' do
+    let(:analogy) { engine.create_analogy(**base_analogy_params) }
+
+    it 'returns mapped element when found' do
+      result = engine.apply_analogy(analogy_id: analogy.id, source_element: :sun)
+      expect(result[:found]).to be true
+      expect(result[:mapped]).to be true
+      expect(result[:target_element]).to eq(:nucleus)
+    end
+
+    it 'returns mapped: false when source element has no mapping' do
+      result = engine.apply_analogy(analogy_id: analogy.id, source_element: :comet)
+      expect(result[:found]).to be true
+      expect(result[:mapped]).to be false
+    end
+
+    it 'returns found: false for unknown analogy_id' do
+      result = engine.apply_analogy(analogy_id: 'nonexistent', source_element: :sun)
+      expect(result[:found]).to be false
+    end
+
+    it 'includes confidence in result' do
+      result = engine.apply_analogy(analogy_id: analogy.id, source_element: :sun)
+      expect(result[:confidence]).to be_a(Float)
+    end
+
+    it 'records apply event in history' do
+      engine.apply_analogy(analogy_id: analogy.id, source_element: :sun)
+      applied = engine.history.select { |h| h[:event] == :applied }
+      expect(applied).not_to be_empty
+    end
+  end
+
+  describe '#evaluate_similarity' do
+    it 'returns 1.0 for identical concept hashes' do
+      concept = { color: :red, shape: :round }
+      score = engine.evaluate_similarity(source: concept, target: concept)
+      expect(score).to be > 0.8
+    end
+
+    it 'returns 0.0 for empty hashes' do
+      expect(engine.evaluate_similarity(source: {}, target: {})).to eq(0.0)
+    end
+
+    it 'returns lower score for dissimilar concepts' do
+      source = { color: :red, shape: :round, size: :large }
+      target = { color: :blue, shape: :square, weight: :heavy }
+      score = engine.evaluate_similarity(source: source, target: target)
+      expect(score).to be < 0.5
+    end
+
+    it 'returns higher score for structurally similar concepts' do
+      source = { role: :attractor, relation: :orbits, parent: :center }
+      target = { role: :attractor, relation: :orbits, parent: :core }
+      score = engine.evaluate_similarity(source: source, target: target)
+      expect(score).to be > 0.4
+    end
+  end
+
+  describe '#cross_domain_transfer' do
+    let(:analogy) { engine.create_analogy(**base_analogy_params) }
+
+    it 'maps source knowledge to target domain' do
+      result = engine.cross_domain_transfer(
+        analogy_id:       analogy.id,
+        source_knowledge: { sun: 'massive gravity well' }
+      )
+      expect(result[:transferred]).to be true
+      expect(result[:result][:nucleus]).to eq('massive gravity well')
+    end
+
+    it 'returns transferred: false for unknown analogy' do
+      result = engine.cross_domain_transfer(analogy_id: 'nope', source_knowledge: {})
+      expect(result[:transferred]).to be false
+    end
+
+    it 'includes coverage ratio' do
+      result = engine.cross_domain_transfer(
+        analogy_id:       analogy.id,
+        source_knowledge: { sun: 'center', comet: 'visitor' }
+      )
+      expect(result[:coverage]).to eq(0.5)
+    end
+
+    it 'records transfer event in history' do
+      engine.cross_domain_transfer(analogy_id: analogy.id, source_knowledge: { sun: 'data' })
+      transferred = engine.history.select { |h| h[:event] == :transferred }
+      expect(transferred).not_to be_empty
+    end
+  end
+
+  describe '#reinforce_analogy' do
+    let(:analogy) { engine.create_analogy(**base_analogy_params) }
+
+    it 'strengthens analogy on success' do
+      initial = analogy.strength
+      engine.reinforce_analogy(analogy_id: analogy.id, success: true)
+      expect(analogy.strength).to be > initial
+    end
+
+    it 'weakens analogy on failure' do
+      initial = analogy.strength
+      engine.reinforce_analogy(analogy_id: analogy.id, success: false)
+      expect(analogy.strength).to be < initial
+    end
+
+    it 'returns not_found for unknown analogy' do
+      result = engine.reinforce_analogy(analogy_id: 'nope', success: true)
+      expect(result[:reinforced]).to be false
+    end
+
+    it 'returns reinforced: true on success' do
+      result = engine.reinforce_analogy(analogy_id: analogy.id, success: true)
+      expect(result[:reinforced]).to be true
+    end
+  end
+
+  describe '#productive_analogies' do
+    it 'returns only productive analogies' do
+      strong_analogy = engine.create_analogy(
+        source_domain: :water,
+        target_domain: :electricity,
+        mappings:      { pressure: :voltage },
+        mapping_type:  :relational,
+        strength:      0.9
+      )
+      engine.create_analogy(**base_analogy_params)
+      productive = engine.productive_analogies
+      expect(productive.map(&:id)).to include(strong_analogy.id)
+    end
+
+    it 'returns empty array when no productive analogies' do
+      engine.create_analogy(**base_analogy_params)
+      expect(engine.productive_analogies).to be_empty
+    end
+  end
+
+  describe '#by_domain' do
+    it 'delegates to find_analogies' do
+      engine.create_analogy(**base_analogy_params)
+      results = engine.by_domain(domain: :solar_system)
+      expect(results.size).to eq(1)
+    end
+  end
+
+  describe '#by_type' do
+    it 'filters analogies by mapping type' do
+      engine.create_analogy(**base_analogy_params)
+      engine.create_analogy(
+        source_domain: :water,
+        target_domain: :electricity,
+        mappings:      { pressure: :voltage },
+        mapping_type:  :attribute
+      )
+      results = engine.by_type(type: :relational)
+      expect(results.all? { |analogy| analogy.mapping_type == :relational }).to be true
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces strength of all analogies' do
+      analogy = engine.create_analogy(**base_analogy_params)
+      initial = analogy.strength
+      engine.decay_all
+      expect(analogy.strength).to be < initial
+    end
+  end
+
+  describe '#prune_stale' do
+    it 'removes stale analogies and returns count' do
+      engine.create_analogy(
+        source_domain: :old, target_domain: :domain, mappings: {}, mapping_type: :attribute,
+        strength: 0.06
+      )
+      engine.create_analogy(**base_analogy_params)
+
+      pruned = engine.prune_stale
+      expect(pruned).to eq(1)
+      expect(engine.find_analogies(domain: :old)).to be_empty
+    end
+
+    it 'returns 0 when no stale analogies' do
+      engine.create_analogy(**base_analogy_params, strength: 0.9)
+      expect(engine.prune_stale).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash with expected keys' do
+      engine.create_analogy(**base_analogy_params)
+      stats = engine.to_h
+      expect(stats).to have_key(:total_analogies)
+      expect(stats).to have_key(:total_domains)
+      expect(stats).to have_key(:productive_count)
+      expect(stats).to have_key(:history_count)
+      expect(stats).to have_key(:domains)
+      expect(stats).to have_key(:analogy_states)
+    end
+
+    it 'counts domains correctly' do
+      engine.create_analogy(**base_analogy_params)
+      expect(engine.to_h[:total_domains]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/analogical/helpers/structure_map_spec.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/analogical/helpers/structure_map'
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Analogical::Helpers::StructureMap do
+  let(:relational_mappings) do
+    {
+      sun:   { type: :relational, maps_to: :nucleus },
+      orbit: { type: :relational, maps_to: :electron_path }
+    }
+  end
+
+  let(:surface_mappings) do
+    {
+      yellow: :gold,
+      hot:    :energetic
+    }
+  end
+
+  let(:structure_map) do
+    described_class.new(
+      source_domain: :solar_system,
+      target_domain: :atom,
+      mappings:      relational_mappings,
+      mapping_type:  :relational
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns required attributes' do
+      expect(structure_map.source_domain).to eq(:solar_system)
+      expect(structure_map.target_domain).to eq(:atom)
+      expect(structure_map.mapping_type).to eq(:relational)
+      expect(structure_map.mappings).to eq(relational_mappings)
+    end
+
+    it 'generates a UUID id' do
+      expect(structure_map.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets default strength' do
+      expect(structure_map.strength).to eq(Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::DEFAULT_STRENGTH)
+    end
+
+    it 'clamps custom strength to ceiling' do
+      map = described_class.new(
+        source_domain: :a,
+        target_domain: :b,
+        mappings:      {},
+        mapping_type:  :attribute,
+        strength:      2.0
+      )
+      expect(map.strength).to eq(Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_CEILING)
+    end
+
+    it 'clamps custom strength to floor' do
+      map = described_class.new(
+        source_domain: :a,
+        target_domain: :b,
+        mappings:      {},
+        mapping_type:  :attribute,
+        strength:      0.0
+      )
+      expect(map.strength).to eq(Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_FLOOR)
+    end
+
+    it 'sets times_used to 0' do
+      expect(structure_map.times_used).to eq(0)
+    end
+  end
+
+  describe '#structural_score' do
+    it 'returns proportion of relational mappings' do
+      expect(structure_map.structural_score).to eq(1.0)
+    end
+
+    it 'returns 0.0 for empty mappings' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute
+      )
+      expect(map.structural_score).to eq(0.0)
+    end
+
+    it 'returns partial score for mixed mappings' do
+      mixed = relational_mappings.merge(surface_mappings)
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: mixed, mapping_type: :relational
+      )
+      expect(map.structural_score).to eq(0.5)
+    end
+  end
+
+  describe '#surface_score' do
+    it 'returns proportion of non-relational mappings' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: surface_mappings, mapping_type: :attribute
+      )
+      expect(map.surface_score).to eq(1.0)
+    end
+
+    it 'returns 0.0 for empty mappings' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute
+      )
+      expect(map.surface_score).to eq(0.0)
+    end
+  end
+
+  describe '#similarity_score' do
+    it 'weights structural and surface scores correctly' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: relational_mappings, mapping_type: :relational
+      )
+      expected = (0.7 * 1.0) + (0.3 * 0.0)
+      expect(map.similarity_score).to be_within(0.001).of(expected)
+    end
+  end
+
+  describe '#use!' do
+    it 'increments times_used' do
+      structure_map.use!
+      expect(structure_map.times_used).to eq(1)
+    end
+
+    it 'updates last_used_at' do
+      before = structure_map.last_used_at
+      sleep 0.01
+      structure_map.use!
+      expect(structure_map.last_used_at).to be >= before
+    end
+
+    it 'boosts strength' do
+      initial = structure_map.strength
+      structure_map.use!
+      expect(structure_map.strength).to be > initial
+    end
+
+    it 'returns self' do
+      expect(structure_map.use!).to eq(structure_map)
+    end
+  end
+
+  describe '#reinforce' do
+    it 'increases strength by reinforcement rate' do
+      initial = structure_map.strength
+      structure_map.reinforce
+      expect(structure_map.strength).to be_within(0.001).of(
+        (initial + Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::REINFORCEMENT_RATE)
+          .clamp(
+            Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_FLOOR,
+            Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_CEILING
+          )
+      )
+    end
+
+    it 'does not exceed strength ceiling' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute,
+        strength: Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_CEILING
+      )
+      map.reinforce(amount: 0.5)
+      expect(map.strength).to eq(Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_CEILING)
+    end
+  end
+
+  describe '#weaken' do
+    it 'decreases strength' do
+      initial = structure_map.strength
+      structure_map.weaken
+      expect(structure_map.strength).to be < initial
+    end
+
+    it 'does not drop below strength floor' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute,
+        strength: Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_FLOOR
+      )
+      map.weaken(amount: 0.5)
+      expect(map.strength).to eq(Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_FLOOR)
+    end
+  end
+
+  describe '#decay' do
+    it 'reduces strength by decay rate' do
+      initial = structure_map.strength
+      structure_map.decay
+      expect(structure_map.strength).to be_within(0.001).of(
+        (initial - Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::DECAY_RATE)
+          .clamp(
+            Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_FLOOR,
+            Legion::Extensions::Agentic::Inference::Analogical::Helpers::Constants::STRENGTH_CEILING
+          )
+      )
+    end
+  end
+
+  describe '#state' do
+    it 'returns :productive when strength is high' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute, strength: 0.9
+      )
+      expect(map.state).to eq(:productive)
+    end
+
+    it 'returns :validated for mid-range strength' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute, strength: 0.6
+      )
+      expect(map.state).to eq(:validated)
+    end
+
+    it 'returns :candidate for low-mid strength' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute, strength: 0.35
+      )
+      expect(map.state).to eq(:candidate)
+    end
+
+    it 'returns :stale for very low strength' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute, strength: 0.1
+      )
+      expect(map.state).to eq(:stale)
+    end
+  end
+
+  describe '#productive?' do
+    it 'returns true when state is productive' do
+      map = described_class.new(
+        source_domain: :a, target_domain: :b, mappings: {}, mapping_type: :attribute, strength: 0.9
+      )
+      expect(map.productive?).to be true
+    end
+
+    it 'returns false when state is not productive' do
+      expect(structure_map.productive?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      hash = structure_map.to_h
+      expected_keys = %i[id source_domain target_domain mappings mapping_type strength
+                         structural_score surface_score similarity_score state
+                         times_used created_at last_used_at]
+      expected_keys.each { |key| expect(hash).to have_key(key) }
+    end
+
+    it 'reflects current state' do
+      hash = structure_map.to_h
+      expect(hash[:source_domain]).to eq(:solar_system)
+      expect(hash[:target_domain]).to eq(:atom)
+    end
+  end
+end