lex-agentic-learning 0.1.0

data/spec/legion/extensions/agentic/learning/catalyst/helpers/reaction_spec.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Reaction do
+  let(:default_activation) { Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Constants::ACTIVATION_ENERGY }
+
+  subject(:reaction) { described_class.new(reaction_type: :synthesis, reactants: %w[idea_a idea_b]) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(reaction.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'assigns reaction_type' do
+      expect(reaction.reaction_type).to eq(:synthesis)
+    end
+
+    it 'assigns reactants as array' do
+      expect(reaction.reactants).to eq(%w[idea_a idea_b])
+    end
+
+    it 'defaults activation_energy to ACTIVATION_ENERGY' do
+      expect(reaction.activation_energy).to eq(default_activation)
+    end
+
+    it 'defaults yield_value to 0.0' do
+      expect(reaction.yield_value).to eq(0.0)
+    end
+
+    it 'defaults catalyzed to false' do
+      expect(reaction.catalyzed).to be false
+    end
+
+    it 'defaults catalyst_id to nil' do
+      expect(reaction.catalyst_id).to be_nil
+    end
+
+    it 'defaults completed to false' do
+      expect(reaction.completed).to be false
+    end
+
+    it 'records created_at' do
+      expect(reaction.created_at).to be_a(Time)
+    end
+
+    it 'accepts custom activation_energy' do
+      r = described_class.new(reaction_type: :exchange, reactants: [], activation_energy: 0.3)
+      expect(r.activation_energy).to eq(0.3)
+    end
+
+    it 'clamps activation_energy to 0..1' do
+      r = described_class.new(reaction_type: :exchange, reactants: [], activation_energy: 2.0)
+      expect(r.activation_energy).to eq(1.0)
+    end
+
+    it 'wraps single reactant string in array' do
+      r = described_class.new(reaction_type: :synthesis, reactants: 'single_idea')
+      expect(r.reactants).to eq(['single_idea'])
+    end
+  end
+
+  describe '#apply_catalyst!' do
+    let(:catalyst) do
+      Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Catalyst.new(
+        catalyst_type: :insight, domain: :reasoning, potency: 0.8, specificity: 0.5
+      )
+    end
+
+    it 'reduces activation_energy' do
+      original = reaction.activation_energy
+      reaction.apply_catalyst!(catalyst)
+      expect(reaction.activation_energy).to be < original
+    end
+
+    it 'sets catalyzed to true' do
+      reaction.apply_catalyst!(catalyst)
+      expect(reaction.catalyzed).to be true
+    end
+
+    it 'records catalyst_id' do
+      reaction.apply_catalyst!(catalyst)
+      expect(reaction.catalyst_id).to eq(catalyst.id)
+    end
+
+    it 'increments catalyst uses_count' do
+      expect { reaction.apply_catalyst!(catalyst) }.to change(catalyst, :uses_count).by(1)
+    end
+
+    it 'does not reduce activation_energy below 0.0' do
+      strong = Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Catalyst.new(
+        catalyst_type: :insight, domain: :d, potency: 1.0, specificity: 1.0
+      )
+      10.times { reaction.apply_catalyst!(strong) }
+      expect(reaction.activation_energy).to eq(0.0)
+    end
+  end
+
+  describe '#attempt!' do
+    context 'when energy_input >= activation_energy' do
+      it 'returns true' do
+        expect(reaction.attempt!(0.8)).to be true
+      end
+
+      it 'sets completed to true' do
+        reaction.attempt!(0.8)
+        expect(reaction.completed).to be true
+      end
+
+      it 'calculates yield_value > 0.5' do
+        reaction.attempt!(1.0)
+        expect(reaction.yield_value).to be > 0.5
+      end
+
+      it 'returns maximum yield on full surplus (activation_energy=0)' do
+        r = described_class.new(reaction_type: :synthesis, reactants: [], activation_energy: 0.0)
+        r.attempt!(1.0)
+        expect(r.yield_value).to eq(1.0)
+      end
+
+      it 'returns minimum passing yield at exact threshold' do
+        reaction.attempt!(reaction.activation_energy)
+        expect(reaction.yield_value).to be_within(0.0001).of(0.5)
+      end
+    end
+
+    context 'when energy_input < activation_energy' do
+      it 'returns false' do
+        expect(reaction.attempt!(0.1)).to be false
+      end
+
+      it 'leaves completed as false' do
+        reaction.attempt!(0.1)
+        expect(reaction.completed).to be false
+      end
+
+      it 'leaves yield_value at 0.0' do
+        reaction.attempt!(0.1)
+        expect(reaction.yield_value).to eq(0.0)
+      end
+    end
+
+    it 'returns false if already completed' do
+      reaction.attempt!(1.0)
+      expect(reaction.attempt!(1.0)).to be false
+    end
+  end
+
+  describe '#complete?' do
+    it 'returns false before attempt' do
+      expect(reaction.complete?).to be false
+    end
+
+    it 'returns true after successful attempt' do
+      reaction.attempt!(1.0)
+      expect(reaction.complete?).to be true
+    end
+  end
+
+  describe '#catalyzed?' do
+    it 'returns false when no catalyst applied' do
+      expect(reaction.catalyzed?).to be false
+    end
+
+    it 'returns true after catalyst applied' do
+      catalyst = Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Catalyst.new(
+        catalyst_type: :insight, domain: :d
+      )
+      reaction.apply_catalyst!(catalyst)
+      expect(reaction.catalyzed?).to be true
+    end
+  end
+
+  describe '#spontaneous?' do
+    it 'returns false when not completed' do
+      expect(reaction.spontaneous?).to be false
+    end
+
+    it 'returns true when completed without catalyst' do
+      reaction.attempt!(1.0)
+      expect(reaction.spontaneous?).to be true
+    end
+
+    it 'returns false when completed with catalyst' do
+      catalyst = Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Catalyst.new(
+        catalyst_type: :insight, domain: :d
+      )
+      reaction.apply_catalyst!(catalyst)
+      reaction.attempt!(1.0)
+      expect(reaction.spontaneous?).to be false
+    end
+  end
+
+  describe '#yield_label' do
+    it 'returns :negligible before completion' do
+      expect(reaction.yield_label).to eq(:negligible)
+    end
+
+    it 'returns :excellent for high yield (activation_energy=0, full surplus)' do
+      r = described_class.new(reaction_type: :synthesis, reactants: [], activation_energy: 0.0)
+      r.attempt!(1.0)
+      expect(r.yield_label).to eq(:excellent)
+    end
+
+    it 'returns :fair for moderate yield' do
+      r = described_class.new(reaction_type: :synthesis, reactants: [], activation_energy: 0.1)
+      r.attempt!(0.2)
+      expect(%i[fair good poor excellent negligible]).to include(r.yield_label)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all required keys' do
+      h = reaction.to_h
+      expect(h).to include(:id, :reaction_type, :reactants, :activation_energy,
+                           :yield_value, :yield_label, :catalyzed, :catalyst_id,
+                           :completed, :spontaneous, :created_at)
+    end
+
+    it 'reflects completed state' do
+      reaction.attempt!(1.0)
+      expect(reaction.to_h[:completed]).to be true
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/catalyst/runners/cognitive_catalyst_spec.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Catalyst::Runners::CognitiveCatalyst do
+  let(:client) { Legion::Extensions::Agentic::Learning::Catalyst::Client.new }
+  let(:engine) { Legion::Extensions::Agentic::Learning::Catalyst::Helpers::CatalystEngine.new }
+
+  def create_catalyst(client_instance = client, **)
+    defaults = { catalyst_type: :insight, domain: :reasoning, engine: engine }
+    client_instance.create_catalyst(**defaults, **)
+  end
+
+  def create_reaction(client_instance = client, **)
+    defaults = { reaction_type: :synthesis, reactants: %w[idea_a idea_b], engine: engine }
+    client_instance.create_reaction(**defaults, **)
+  end
+
+  describe '#create_catalyst' do
+    it 'returns success: true' do
+      result = create_catalyst
+      expect(result[:success]).to be true
+    end
+
+    it 'includes catalyst hash in result' do
+      result = create_catalyst
+      expect(result[:catalyst]).to include(:id, :catalyst_type, :domain, :potency)
+    end
+
+    it 'uses default potency 0.5 when not specified' do
+      result = create_catalyst
+      expect(result[:catalyst][:potency]).to eq(0.5)
+    end
+
+    it 'uses custom potency when provided' do
+      result = create_catalyst(potency: 0.9)
+      expect(result[:catalyst][:potency]).to eq(0.9)
+    end
+
+    it 'uses custom specificity when provided' do
+      result = create_catalyst(specificity: 0.8)
+      expect(result[:catalyst][:specificity]).to eq(0.8)
+    end
+
+    it 'accepts all valid catalyst types' do
+      Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Constants::CATALYST_TYPES.each do |type|
+        result = client.create_catalyst(catalyst_type: type, domain: :d, engine: engine)
+        expect(result[:success]).to be true
+      end
+    end
+
+    it 'returns success: false for invalid catalyst_type' do
+      result = client.create_catalyst(catalyst_type: :invalid, domain: :d, engine: engine)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to be_a(String)
+    end
+  end
+
+  describe '#create_reaction' do
+    it 'returns success: true' do
+      result = create_reaction
+      expect(result[:success]).to be true
+    end
+
+    it 'includes reaction hash in result' do
+      result = create_reaction
+      expect(result[:reaction]).to include(:id, :reaction_type, :reactants, :activation_energy)
+    end
+
+    it 'accepts all valid reaction types' do
+      Legion::Extensions::Agentic::Learning::Catalyst::Helpers::Constants::REACTION_TYPES.each do |type|
+        result = client.create_reaction(reaction_type: type, reactants: ['x'], engine: engine)
+        expect(result[:success]).to be true
+      end
+    end
+
+    it 'returns success: false for invalid reaction_type' do
+      result = client.create_reaction(reaction_type: :explode, reactants: [], engine: engine)
+      expect(result[:success]).to be false
+    end
+
+    it 'uses custom activation_energy' do
+      result = create_reaction(activation_energy: 0.3)
+      expect(result[:reaction][:activation_energy]).to eq(0.3)
+    end
+  end
+
+  describe '#apply_catalyst' do
+    it 'lowers activation energy and returns success' do
+      cat    = create_catalyst
+      rxn    = create_reaction
+      result = client.apply_catalyst(catalyst_id: cat[:catalyst][:id],
+                                     reaction_id: rxn[:reaction][:id],
+                                     engine:      engine)
+      expect(result[:success]).to be true
+      expect(result[:activation_energy]).to be < 0.6
+    end
+
+    it 'returns failure for unknown catalyst_id' do
+      rxn    = create_reaction
+      result = client.apply_catalyst(catalyst_id: 'bad',
+                                     reaction_id: rxn[:reaction][:id],
+                                     engine:      engine)
+      expect(result[:success]).to be false
+    end
+
+    it 'returns failure for unknown reaction_id' do
+      cat    = create_catalyst
+      result = client.apply_catalyst(catalyst_id: cat[:catalyst][:id],
+                                     reaction_id: 'bad',
+                                     engine:      engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#attempt_reaction' do
+    it 'completes reaction with sufficient energy' do
+      rxn    = create_reaction
+      result = client.attempt_reaction(reaction_id:  rxn[:reaction][:id],
+                                       energy_input: 1.0,
+                                       engine:       engine)
+      expect(result[:completed]).to be true
+    end
+
+    it 'does not complete with insufficient energy' do
+      rxn    = create_reaction
+      result = client.attempt_reaction(reaction_id:  rxn[:reaction][:id],
+                                       energy_input: 0.1,
+                                       engine:       engine)
+      expect(result[:completed]).to be false
+    end
+
+    it 'includes yield data when completed' do
+      rxn    = create_reaction
+      result = client.attempt_reaction(reaction_id:  rxn[:reaction][:id],
+                                       energy_input: 1.0,
+                                       engine:       engine)
+      expect(result).to include(:yield_value, :yield_label)
+    end
+
+    it 'returns not_found for unknown reaction' do
+      result = client.attempt_reaction(reaction_id: 'missing', energy_input: 1.0, engine: engine)
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#recharge' do
+    it 'increases catalyst potency' do
+      cat    = create_catalyst(potency: 0.3)
+      result = client.recharge(catalyst_id: cat[:catalyst][:id], amount: 0.2, engine: engine)
+      expect(result[:success]).to be true
+      expect(result[:potency]).to be > 0.3
+    end
+
+    it 'returns failure for unknown catalyst' do
+      result = client.recharge(catalyst_id: 'bad', amount: 0.2, engine: engine)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#list_catalysts' do
+    it 'returns success: true' do
+      result = client.list_catalysts(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns empty list initially' do
+      result = client.list_catalysts(engine: engine)
+      expect(result[:count]).to eq(0)
+    end
+
+    it 'reflects created catalysts' do
+      create_catalyst
+      create_catalyst(catalyst_type: :analogy)
+      result = client.list_catalysts(engine: engine)
+      expect(result[:count]).to eq(2)
+    end
+
+    it 'includes catalyst hashes in the list' do
+      create_catalyst
+      result = client.list_catalysts(engine: engine)
+      expect(result[:catalysts].first).to include(:id, :catalyst_type, :potency)
+    end
+  end
+
+  describe '#catalyst_status' do
+    it 'returns success: true' do
+      result = client.catalyst_status(engine: engine)
+      expect(result[:success]).to be true
+    end
+
+    it 'includes report keys' do
+      result = client.catalyst_status(engine: engine)
+      expect(result).to include(:total_catalysts, :total_reactions, :completed,
+                                :catalyzed_count, :catalyzed_rate, :avg_potency,
+                                :powerful_count, :inert_count)
+    end
+
+    it 'reflects catalysts and reactions created' do
+      create_catalyst
+      create_reaction
+      result = client.catalyst_status(engine: engine)
+      expect(result[:total_catalysts]).to eq(1)
+      expect(result[:total_reactions]).to eq(1)
+    end
+
+    it 'shows catalyzed_rate 0.0 initially' do
+      result = client.catalyst_status(engine: engine)
+      expect(result[:catalyzed_rate]).to eq(0.0)
+    end
+
+    it 'reflects completed reactions in report' do
+      rxn = create_reaction
+      client.attempt_reaction(reaction_id: rxn[:reaction][:id], energy_input: 1.0, engine: engine)
+      result = client.catalyst_status(engine: engine)
+      expect(result[:completed]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/client_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis::Client do
+  subject(:client) { described_class.new }
+
+  it 'responds to create_chrysalis' do
+    expect(client).to respond_to(:create_chrysalis)
+  end
+
+  it 'responds to create_cocoon' do
+    expect(client).to respond_to(:create_cocoon)
+  end
+
+  it 'responds to spin' do
+    expect(client).to respond_to(:spin)
+  end
+
+  it 'responds to enclose' do
+    expect(client).to respond_to(:enclose)
+  end
+
+  it 'responds to incubate' do
+    expect(client).to respond_to(:incubate)
+  end
+
+  it 'responds to emerge' do
+    expect(client).to respond_to(:emerge)
+  end
+
+  it 'responds to disturb' do
+    expect(client).to respond_to(:disturb)
+  end
+
+  it 'responds to list_chrysalises' do
+    expect(client).to respond_to(:list_chrysalises)
+  end
+
+  it 'responds to metamorphosis_status' do
+    expect(client).to respond_to(:metamorphosis_status)
+  end
+
+  it 'exposes the engine as a MetamorphosisEngine' do
+    expect(client.engine).to be_a(Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine)
+  end
+
+  it 'uses the same engine for all calls by default' do
+    client.create_chrysalis(chrysalis_type: :silk, content: 'c1')
+    status = client.metamorphosis_status
+    expect(status[:total_chrysalises]).to eq(1)
+  end
+
+  describe 'full lifecycle via client default engine' do
+    it 'creates a chrysalis, encloses it, incubates it, and emerges it' do
+      cid = client.create_chrysalis(chrysalis_type: :silk, content: 'an insight')[:chrysalis][:id]
+      coc = client.create_cocoon(environment: 'forest')[:cocoon][:id]
+      client.enclose(chrysalis_id: cid, cocoon_id: coc)
+      12.times { client.incubate(chrysalis_id: cid) }
+      result = client.emerge(chrysalis_id: cid)
+      expect(result[:stage]).to eq(:butterfly)
+    end
+
+    it 'reports metamorphosis status after activity' do
+      client.create_chrysalis(chrysalis_type: :leaf, content: 'leaf thought')
+      status = client.metamorphosis_status
+      expect(status[:total_chrysalises]).to eq(1)
+    end
+
+    it 'can disturb a cocoon and observe effects' do
+      cid = client.create_chrysalis(chrysalis_type: :underground, content: 'idea')[:chrysalis][:id]
+      coc = client.create_cocoon(environment: 'cave')[:cocoon][:id]
+      client.enclose(chrysalis_id: cid, cocoon_id: coc)
+      result = client.disturb(cocoon_id: coc, force: 1.0)
+      expect(result[:success]).to be true
+    end
+
+    it 'lists created chrysalises' do
+      client.create_chrysalis(chrysalis_type: :bark, content: 'a')
+      client.create_chrysalis(chrysalis_type: :paper, content: 'b')
+      result = client.list_chrysalises
+      expect(result[:count]).to eq(2)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/cognitive_chrysalis_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Chrysalis do
+  it 'has a version number' do
+    expect(Legion::Extensions::Agentic::Learning::Chrysalis::VERSION).not_to be_nil
+  end
+
+  it 'has a version that is a string' do
+    expect(Legion::Extensions::Agentic::Learning::Chrysalis::VERSION).to be_a(String)
+  end
+
+  it 'version is 0.1.0' do
+    expect(Legion::Extensions::Agentic::Learning::Chrysalis::VERSION).to eq('0.1.0')
+  end
+end

data/spec/legion/extensions/agentic/learning/chrysalis/helpers/chrysalis_engine_spec.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# This file intentionally tests the MetamorphosisEngine via focused unit scenarios
+# previously covered by a now-replaced helper. See metamorphosis_engine_spec.rb for full coverage.
+
+RSpec.describe 'MetamorphosisEngine capacity and butterfly tracking' do
+  let(:engine) { Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::MetamorphosisEngine.new }
+
+  it 'tracks butterflies separately from active chrysalises' do
+    cid = engine.create_chrysalis(chrysalis_type: :silk, content: 'idea')[:chrysalis][:id]
+    engine.force_emerge(chrysalis_id: cid)
+    expect(engine.butterflies.size).to eq(1)
+    report = engine.metamorphosis_report
+    expect(report[:butterflies_count]).to eq(1)
+  end
+
+  it 'counts premature butterflies in report' do
+    cid = engine.create_chrysalis(chrysalis_type: :paper, content: 'fragile')[:chrysalis][:id]
+    engine.force_emerge(chrysalis_id: cid)
+    report = engine.metamorphosis_report
+    expect(report[:premature_count]).to eq(1)
+  end
+
+  it 'returns 0 avg_beauty when no butterflies exist' do
+    engine.create_chrysalis(chrysalis_type: :bark, content: 'c')
+    expect(engine.metamorphosis_report[:avg_beauty]).to eq(0.0)
+  end
+
+  it 'calculates non-zero avg_progress after incubation' do
+    cid = engine.create_chrysalis(chrysalis_type: :leaf, content: 'c')[:chrysalis][:id]
+    coc = engine.create_cocoon(environment: 'forest')[:cocoon][:id]
+    engine.enclose(chrysalis_id: cid, cocoon_id: coc)
+    engine.incubate(chrysalis_id: cid)
+    expect(engine.metamorphosis_report[:avg_progress]).to be > 0.0
+  end
+
+  it 'incubate_all returns success: true even with no chrysalises' do
+    expect(engine.incubate_all![:success]).to be true
+  end
+
+  it 'disturb_cocoon with full force can trigger forced emergence' do
+    cid = engine.create_chrysalis(chrysalis_type: :underground, content: 'deep')[:chrysalis][:id]
+    coc = engine.create_cocoon(environment: 'cave')[:cocoon][:id]
+    engine.enclose(chrysalis_id: cid, cocoon_id: coc)
+    engine.disturb_cocoon(cocoon_id: coc, force: 1.0)
+    c = engine.instance_variable_get(:@chrysalises)[cid]
+    expect(c.butterfly?).to be true
+  end
+
+  it 'applies ideal cocoon modifier, increasing progress faster' do
+    cid  = engine.create_chrysalis(chrysalis_type: :silk, content: 'c1')[:chrysalis][:id]
+    coc  = engine.create_cocoon(environment: 'ideal', temperature: 0.55, humidity: 0.55)[:cocoon][:id]
+    engine.enclose(chrysalis_id: cid, cocoon_id: coc)
+    result = engine.incubate(chrysalis_id: cid)
+    expect(result[:progress]).to be > Legion::Extensions::Agentic::Learning::Chrysalis::Helpers::Constants::TRANSFORMATION_RATE
+  end
+end