lex-agentic-learning 0.1.0

data/spec/legion/extensions/agentic/learning/preference_learning/helpers/option_spec.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::PreferenceLearning::Helpers::Option do
+  subject(:option) { described_class.new(label: 'Option A', domain: :taste) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(option.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets label and domain' do
+      expect(option.label).to eq('Option A')
+      expect(option.domain).to eq(:taste)
+    end
+
+    it 'starts with default preference score' do
+      expect(option.preference_score).to eq(0.5)
+    end
+
+    it 'starts with zero wins and losses' do
+      expect(option.wins).to eq(0)
+      expect(option.losses).to eq(0)
+      expect(option.times_seen).to eq(0)
+    end
+
+    it 'records created_at' do
+      expect(option.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#win!' do
+    it 'increments wins and times_seen' do
+      option.win!
+      expect(option.wins).to eq(1)
+      expect(option.times_seen).to eq(1)
+    end
+
+    it 'increases preference score' do
+      before = option.preference_score
+      option.win!
+      expect(option.preference_score).to be > before
+    end
+
+    it 'does not exceed ceiling' do
+      20.times { option.win! }
+      expect(option.preference_score).to be <= 1.0
+    end
+  end
+
+  describe '#lose!' do
+    it 'increments losses and times_seen' do
+      option.lose!
+      expect(option.losses).to eq(1)
+      expect(option.times_seen).to eq(1)
+    end
+
+    it 'decreases preference score' do
+      before = option.preference_score
+      option.lose!
+      expect(option.preference_score).to be < before
+    end
+
+    it 'does not go below floor' do
+      20.times { option.lose! }
+      expect(option.preference_score).to be >= 0.0
+    end
+  end
+
+  describe '#win_rate' do
+    it 'returns 0.0 when no comparisons' do
+      expect(option.win_rate).to eq(0.0)
+    end
+
+    it 'returns a value between 0 and 1 after comparisons' do
+      option.win!
+      option.lose!
+      expect(option.win_rate).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#preference_label' do
+    it 'returns :neutral for default score' do
+      expect(option.preference_label).to eq(:neutral)
+    end
+
+    it 'returns :strongly_preferred after many wins' do
+      15.times { option.win! }
+      expect(option.preference_label).to eq(:strongly_preferred)
+    end
+
+    it 'returns :strongly_disliked after many losses' do
+      15.times { option.lose! }
+      expect(option.preference_label).to eq(:strongly_disliked)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = option.to_h
+      expect(h.keys).to include(:id, :label, :domain, :preference_score, :wins, :losses,
+                                :times_seen, :win_rate, :preference_label, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/preference_learning/helpers/preference_engine_spec.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::PreferenceLearning::Helpers::PreferenceEngine do
+  subject(:engine) { described_class.new }
+
+  let(:opt_a_id) { engine.register_option(label: 'Apple', domain: :food)[:id] }
+  let(:opt_b_id) { engine.register_option(label: 'Banana', domain: :food)[:id] }
+
+  describe '#register_option' do
+    it 'returns a hash with id, label, domain' do
+      result = engine.register_option(label: 'Cherry', domain: :food)
+      expect(result[:id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:label]).to eq('Cherry')
+      expect(result[:domain]).to eq(:food)
+    end
+
+    it 'starts with default preference score' do
+      result = engine.register_option(label: 'Date')
+      expect(result[:preference_score]).to eq(0.5)
+    end
+  end
+
+  describe '#record_comparison' do
+    it 'increases winner score and decreases loser score' do
+      engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id)
+      top = engine.top_preferences(domain: :food, limit: 1)
+      expect(top.first[:id]).to eq(opt_a_id)
+    end
+
+    it 'returns comparison summary' do
+      result = engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id)
+      expect(result[:comparisons]).to eq(1)
+      expect(result[:winner_score]).to be > 0.5
+      expect(result[:loser_score]).to be < 0.5
+    end
+
+    it 'returns error for unknown option' do
+      result = engine.record_comparison(winner_id: 'bad-id', loser_id: opt_b_id)
+      expect(result[:error]).to eq('option not found')
+    end
+  end
+
+  describe '#predict_preference' do
+    it 'predicts winner after comparisons' do
+      3.times { engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id) }
+      result = engine.predict_preference(option_a_id: opt_a_id, option_b_id: opt_b_id)
+      expect(result[:preferred_id]).to eq(opt_a_id)
+    end
+
+    it 'returns confidence as a 0..1 value' do
+      engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id)
+      result = engine.predict_preference(option_a_id: opt_a_id, option_b_id: opt_b_id)
+      expect(result[:confidence]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns error for unknown option' do
+      result = engine.predict_preference(option_a_id: 'bad-id', option_b_id: opt_b_id)
+      expect(result[:error]).to eq('option not found')
+    end
+  end
+
+  describe '#top_preferences' do
+    it 'returns options sorted by score descending' do
+      engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id)
+      top = engine.top_preferences(domain: :food, limit: 2)
+      expect(top.first[:id]).to eq(opt_a_id)
+    end
+
+    it 'respects limit' do
+      3.times { engine.register_option(label: "opt#{it}") }
+      top = engine.top_preferences(limit: 2)
+      expect(top.size).to be <= 2
+    end
+
+    it 'returns all domains when domain is nil' do
+      opt_a_id
+      engine.register_option(label: 'X', domain: :color)
+      result = engine.top_preferences(domain: nil, limit: 10)
+      domains = result.map { |o| o[:domain] }.uniq
+      expect(domains).to include(:food, :color)
+    end
+  end
+
+  describe '#bottom_preferences' do
+    it 'returns options sorted by score ascending' do
+      engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id)
+      bottom = engine.bottom_preferences(domain: :food, limit: 1)
+      expect(bottom.first[:id]).to eq(opt_b_id)
+    end
+  end
+
+  describe '#preferences_by_domain' do
+    it 'returns only options for given domain' do
+      fresh = described_class.new
+      fresh.register_option(label: 'Apple', domain: :food)
+      fresh.register_option(label: 'Red', domain: :color)
+      result = fresh.preferences_by_domain(domain: :food)
+      expect(result.map { |o| o[:domain] }.uniq).to eq([:food])
+    end
+  end
+
+  describe '#preference_stability' do
+    it 'returns 0.0 with fewer than 2 options' do
+      engine2 = described_class.new
+      engine2.register_option(label: 'Solo')
+      expect(engine2.preference_stability).to eq(0.0)
+    end
+
+    it 'returns a non-negative float with multiple options' do
+      opt_a_id
+      opt_b_id
+      3.times { engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id) }
+      expect(engine.preference_stability).to be >= 0.0
+    end
+  end
+
+  describe '#most_compared' do
+    it 'returns options sorted by times_seen descending' do
+      3.times { engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id) }
+      result = engine.most_compared(limit: 2)
+      expect(result.first[:times_seen]).to be >= result.last[:times_seen]
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns the count of options' do
+      opt_a_id
+      opt_b_id
+      expect(engine.decay_all).to eq(2)
+    end
+
+    it 'nudges scores toward default (0.5)' do
+      3.times { engine.record_comparison(winner_id: opt_a_id, loser_id: opt_b_id) }
+      before_a = engine.top_preferences(domain: :food, limit: 1).first[:preference_score]
+      engine.decay_all
+      after_a = engine.top_preferences(domain: :food, limit: 1).first[:preference_score]
+      expect(after_a).to be < before_a
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes total_options, comparisons, stability, options' do
+      opt_a_id
+      opt_b_id
+      h = engine.to_h
+      expect(h[:total_options]).to eq(2)
+      expect(h[:comparisons]).to eq(0)
+      expect(h[:options]).to be_an(Array)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/preference_learning/runners/preference_learning_spec.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/learning/preference_learning/client'
+
+RSpec.describe Legion::Extensions::Agentic::Learning::PreferenceLearning::Runners::PreferenceLearning do
+  let(:client) { Legion::Extensions::Agentic::Learning::PreferenceLearning::Client.new }
+
+  let(:opt_a_id) { client.register_preference_option(label: 'Alpha', domain: :general)[:id] }
+  let(:opt_b_id) { client.register_preference_option(label: 'Beta', domain: :general)[:id] }
+
+  describe '#register_preference_option' do
+    it 'registers an option and returns id' do
+      result = client.register_preference_option(label: 'Gamma')
+      expect(result[:id]).not_to be_nil
+      expect(result[:label]).to eq('Gamma')
+    end
+  end
+
+  describe '#record_preference_comparison' do
+    it 'records winner/loser and returns comparison data' do
+      result = client.record_preference_comparison(winner_id: opt_a_id, loser_id: opt_b_id)
+      expect(result[:comparisons]).to eq(1)
+      expect(result[:winner_score]).to be > 0.5
+    end
+
+    it 'returns error for invalid ids' do
+      result = client.record_preference_comparison(winner_id: 'nope', loser_id: opt_b_id)
+      expect(result[:error]).to eq('option not found')
+    end
+  end
+
+  describe '#predict_preference_outcome' do
+    it 'returns preferred_id and confidence' do
+      3.times { client.record_preference_comparison(winner_id: opt_a_id, loser_id: opt_b_id) }
+      result = client.predict_preference_outcome(option_a_id: opt_a_id, option_b_id: opt_b_id)
+      expect(result[:preferred_id]).to eq(opt_a_id)
+      expect(result[:confidence]).to be_between(0.0, 1.0)
+    end
+
+    it 'returns error for invalid id' do
+      result = client.predict_preference_outcome(option_a_id: 'bad', option_b_id: opt_b_id)
+      expect(result[:error]).to eq('option not found')
+    end
+  end
+
+  describe '#top_preferences_report' do
+    it 'returns domain, limit, and options array' do
+      opt_a_id
+      opt_b_id
+      result = client.top_preferences_report(domain: :general, limit: 5)
+      expect(result[:domain]).to eq(:general)
+      expect(result[:limit]).to eq(5)
+      expect(result[:options]).to be_an(Array)
+    end
+  end
+
+  describe '#preference_stability_report' do
+    it 'returns stability float and label' do
+      opt_a_id
+      opt_b_id
+      result = client.preference_stability_report
+      expect(result[:stability]).to be_a(Float)
+      expect(%i[stable variable]).to include(result[:label])
+    end
+  end
+
+  describe '#update_preference_learning' do
+    it 'returns decayed count' do
+      opt_a_id
+      opt_b_id
+      result = client.update_preference_learning
+      expect(result[:decayed]).to eq(2)
+    end
+  end
+
+  describe '#preference_learning_stats' do
+    it 'returns total_options, comparisons, stability, stability_label' do
+      opt_a_id
+      opt_b_id
+      result = client.preference_learning_stats
+      expect(result[:total_options]).to eq(2)
+      expect(result[:comparisons]).to eq(0)
+      expect(result[:stability_label]).not_to be_nil
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Procedural::Client do
+  subject(:client) { described_class.new }
+
+  it 'creates a skill' do
+    result = client.create_skill(name: 'test', domain: :test)
+    expect(result[:success]).to be true
+  end
+
+  it 'practices and compiles a skill' do
+    created = client.create_skill(name: 'test', domain: :test)
+    8.times { client.practice_skill(skill_id: created[:skill_id], success: true) }
+    compiled = client.compiled_skills
+    expect(compiled[:count]).to eq(1)
+  end
+
+  it 'returns stats' do
+    result = client.procedural_learning_stats
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/agentic/learning/procedural/helpers/learning_engine_spec.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Procedural::Helpers::LearningEngine do
+  subject(:engine) { described_class.new }
+
+  let(:skill) { engine.create_skill(name: 'api_retry', domain: :http) }
+
+  describe '#create_skill' do
+    it 'creates and returns a skill' do
+      result = skill
+      expect(result).to be_a(Legion::Extensions::Agentic::Learning::Procedural::Helpers::Skill)
+      expect(result.name).to eq('api_retry')
+    end
+
+    it 'records history' do
+      skill
+      expect(engine.history.size).to eq(1)
+    end
+  end
+
+  describe '#add_production' do
+    it 'creates a production for a skill' do
+      result = engine.add_production(
+        skill_id: skill.id, condition: 'if_error',
+        action: 'retry', domain: :http
+      )
+      expect(result).to be_a(Legion::Extensions::Agentic::Learning::Procedural::Helpers::Production)
+    end
+
+    it 'returns error for unknown skill' do
+      result = engine.add_production(
+        skill_id: 'bad', condition: 'test',
+        action: 'test', domain: :test
+      )
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#practice_skill' do
+    it 'increases proficiency' do
+      result = engine.practice_skill(skill_id: skill.id, success: true)
+      expect(result[:success]).to be true
+      expect(result[:proficiency]).to be > 0.1
+    end
+
+    it 'returns error for unknown skill' do
+      result = engine.practice_skill(skill_id: 'bad', success: true)
+      expect(result[:success]).to be false
+    end
+  end
+
+  describe '#execute_production' do
+    it 'executes and records outcome' do
+      prod = engine.add_production(
+        skill_id: skill.id, condition: 'test',
+        action: 'act', domain: :test
+      )
+      result = engine.execute_production(production_id: prod.id, success: true)
+      expect(result[:success]).to be true
+      expect(result[:success_rate]).to eq(1.0)
+    end
+  end
+
+  describe '#skill_assessment' do
+    it 'returns assessment with productions' do
+      prod = engine.add_production(
+        skill_id: skill.id, condition: 'test',
+        action: 'act', domain: :test
+      )
+      engine.execute_production(production_id: prod.id, success: true)
+      result = engine.skill_assessment(skill_id: skill.id)
+      expect(result[:success]).to be true
+      expect(result[:productions].size).to eq(1)
+    end
+  end
+
+  describe '#compiled_skills' do
+    it 'returns skills above compilation threshold' do
+      8.times { engine.practice_skill(skill_id: skill.id, success: true) }
+      expect(engine.compiled_skills.size).to eq(1)
+    end
+  end
+
+  describe '#autonomous_skills' do
+    it 'returns skills above automation threshold' do
+      12.times { engine.practice_skill(skill_id: skill.id, success: true) }
+      expect(engine.autonomous_skills.size).to eq(1)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters by domain' do
+      skill
+      engine.create_skill(name: 'other', domain: :dns)
+      expect(engine.by_domain(domain: :http).size).to eq(1)
+    end
+  end
+
+  describe '#most_practiced' do
+    it 'returns skills sorted by practice count' do
+      3.times { engine.practice_skill(skill_id: skill.id, success: true) }
+      other = engine.create_skill(name: 'other', domain: :dns)
+      engine.practice_skill(skill_id: other.id, success: true)
+      results = engine.most_practiced(limit: 2)
+      expect(results.first.practice_count).to be >= results.last.practice_count
+    end
+  end
+
+  describe '#decay_all' do
+    it 'reduces proficiency of all skills' do
+      5.times { engine.practice_skill(skill_id: skill.id, success: true) }
+      original = skill.proficiency
+      engine.decay_all
+      expect(skill.proficiency).to be < original
+    end
+  end
+
+  describe '#prune_stale' do
+    it 'removes skills with near-zero proficiency' do
+      skill
+      50.times { skill.decay! }
+      pruned = engine.prune_stale
+      expect(pruned).to be >= 0
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns summary stats' do
+      skill
+      stats = engine.to_h
+      expect(stats[:total_skills]).to eq(1)
+      expect(stats).to include(:compiled_count, :autonomous_count, :stage_counts)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/procedural/helpers/production_spec.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Procedural::Helpers::Production do
+  subject(:production) do
+    described_class.new(condition: 'if_error', action: 'retry_request', domain: :http, skill_id: 'skill-123')
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID' do
+      expect(production.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores condition and action' do
+      expect(production.condition).to eq('if_error')
+      expect(production.action).to eq('retry_request')
+    end
+
+    it 'starts with zero execution count' do
+      expect(production.execution_count).to eq(0)
+    end
+  end
+
+  describe '#execute!' do
+    it 'increments execution count' do
+      expect { production.execute!(success: true) }.to change(production, :execution_count).by(1)
+    end
+
+    it 'increments success count on success' do
+      expect { production.execute!(success: true) }.to change(production, :success_count).by(1)
+    end
+
+    it 'does not increment success count on failure' do
+      expect { production.execute!(success: false) }.not_to change(production, :success_count)
+    end
+  end
+
+  describe '#success_rate' do
+    it 'returns 0.0 when no executions' do
+      expect(production.success_rate).to eq(0.0)
+    end
+
+    it 'computes success ratio' do
+      3.times { production.execute!(success: true) }
+      production.execute!(success: false)
+      expect(production.success_rate).to eq(0.75)
+    end
+  end
+
+  describe '#reliable?' do
+    it 'returns false initially' do
+      expect(production).not_to be_reliable
+    end
+
+    it 'returns true after sufficient successful executions' do
+      5.times { production.execute!(success: true) }
+      expect(production).to be_reliable
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash representation' do
+      hash = production.to_h
+      expect(hash).to include(:id, :condition, :action, :domain, :success_rate, :reliable)
+    end
+  end
+end

data/spec/legion/extensions/agentic/learning/procedural/helpers/skill_spec.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Learning::Procedural::Helpers::Skill do
+  subject(:skill) { described_class.new(name: 'api_retry', domain: :http) }
+
+  describe '#initialize' do
+    it 'assigns a UUID' do
+      expect(skill.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'starts at declarative stage' do
+      expect(skill.stage).to eq(:declarative)
+    end
+
+    it 'starts with low proficiency' do
+      expect(skill.proficiency).to be < 0.2
+    end
+  end
+
+  describe '#practice!' do
+    it 'increases proficiency on success' do
+      original = skill.proficiency
+      skill.practice!(success: true)
+      expect(skill.proficiency).to be > original
+    end
+
+    it 'increases proficiency less on failure' do
+      success_skill = described_class.new(name: 'test', domain: :test)
+      failure_skill = described_class.new(name: 'test', domain: :test)
+      success_skill.practice!(success: true)
+      failure_skill.practice!(success: false)
+      expect(success_skill.proficiency).to be > failure_skill.proficiency
+    end
+
+    it 'transitions stage with practice' do
+      10.times { skill.practice!(success: true) }
+      expect(skill.stage).not_to eq(:declarative)
+    end
+  end
+
+  describe '#compiled?' do
+    it 'returns false initially' do
+      expect(skill).not_to be_compiled
+    end
+
+    it 'returns true after sufficient practice' do
+      8.times { skill.practice!(success: true) }
+      expect(skill).to be_compiled
+    end
+  end
+
+  describe '#autonomous?' do
+    it 'returns false initially' do
+      expect(skill).not_to be_autonomous
+    end
+
+    it 'returns true after extensive practice' do
+      12.times { skill.practice!(success: true) }
+      expect(skill).to be_autonomous
+    end
+  end
+
+  describe '#stage_label' do
+    it 'returns a label symbol' do
+      expect(skill.stage_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#proficiency_label' do
+    it 'returns a label symbol' do
+      expect(skill.proficiency_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces proficiency' do
+      5.times { skill.practice!(success: true) }
+      original = skill.proficiency
+      skill.decay!
+      expect(skill.proficiency).to be < original
+    end
+  end
+
+  describe '#add_production' do
+    it 'adds production id' do
+      skill.add_production('prod-123')
+      expect(skill.productions).to include('prod-123')
+    end
+
+    it 'does not add duplicates' do
+      2.times { skill.add_production('prod-123') }
+      expect(skill.productions.size).to eq(1)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns hash representation' do
+      hash = skill.to_h
+      expect(hash).to include(:id, :name, :domain, :proficiency, :stage, :compiled, :autonomous)
+    end
+  end
+end