lex-preference-learning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 18319db7d0f4c66978913f108382a6bd615682687f175c43797c540ca357f5b3
+  data.tar.gz: 83f4100aad3f4ef92f8a5f8d50671c4f4e0d75dcc6ae64460794df468c10b84d
+SHA512:
+  metadata.gz: 9b567fb54f9e788f1d260bb31b3a6d2e1e05ab1510f0c94bbc2eebc4a7ce40827b779db3b024183be14dcbd2fc8e1370c3607020b38983f1659d8ee14c623407
+  data.tar.gz: 3cdb684473150ae3b33ba406725c1259aca185e1439ffdb01b285ea327541edffb9b3534a1601e61057408265d39b3c102a0f79463e1a4966056143598df7d0c

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-preference-learning.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/preference_learning/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-preference-learning'
+  spec.version       = Legion::Extensions::PreferenceLearning::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Preference Learning'
+  spec.description   = 'Learns and models preferences from choices and feedback for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-preference-learning'
+  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-preference-learning'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-preference-learning'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-preference-learning'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-preference-learning/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-preference-learning.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/preference_learning/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::PreferenceLearning::Runners::PreferenceLearning
+          end
+
+          def runner_function
+            'update_preference_learning'
+          end
+
+          def time
+            300
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/preference_learning/helpers/constants'
+require 'legion/extensions/preference_learning/helpers/option'
+require 'legion/extensions/preference_learning/helpers/preference_engine'
+require 'legion/extensions/preference_learning/runners/preference_learning'
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      class Client
+        include Runners::PreferenceLearning
+
+        def initialize(**)
+          @preference_engine = Helpers::PreferenceEngine.new
+        end
+
+        private
+
+        attr_reader :preference_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      module Helpers
+        module Constants
+          PREFERENCE_LABELS = {
+            (0.8..)     => :strongly_preferred,
+            (0.6...0.8) => :preferred,
+            (0.4...0.6) => :neutral,
+            (0.2...0.4) => :disliked,
+            (..0.2)     => :strongly_disliked
+          }.freeze
+
+          MAX_OPTIONS     = 200
+          MAX_COMPARISONS = 1000
+          MAX_HISTORY     = 500
+
+          DEFAULT_PREFERENCE  = 0.5
+          PREFERENCE_FLOOR    = 0.0
+          PREFERENCE_CEILING  = 1.0
+
+          WIN_BOOST     = 0.08
+          LOSS_PENALTY  = 0.06
+          DECAY_RATE    = 0.01
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/preference_learning/helpers/option.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      module Helpers
+        class Option
+          attr_reader :id, :label, :domain, :created_at
+          attr_accessor :preference_score, :wins, :losses, :times_seen
+
+          def initialize(label:, domain: :general)
+            @id               = SecureRandom.uuid
+            @label            = label
+            @domain           = domain
+            @preference_score = Constants::DEFAULT_PREFERENCE
+            @wins             = 0
+            @losses           = 0
+            @times_seen       = 0
+            @created_at       = Time.now.utc
+          end
+
+          def win!
+            @wins         += 1
+            @times_seen   += 1
+            @preference_score = clamp(@preference_score + Constants::WIN_BOOST)
+          end
+
+          def lose!
+            @losses       += 1
+            @times_seen   += 1
+            @preference_score = clamp(@preference_score - Constants::LOSS_PENALTY)
+          end
+
+          def win_rate
+            total = @wins + @losses
+            return 0.0 if total.zero?
+
+            @wins.to_f / (total + 1)
+          end
+
+          def preference_label
+            Constants::PREFERENCE_LABELS.each do |range, label|
+              return label if range.cover?(@preference_score)
+            end
+            :neutral
+          end
+
+          def to_h
+            {
+              id:               @id,
+              label:            @label,
+              domain:           @domain,
+              preference_score: @preference_score,
+              wins:             @wins,
+              losses:           @losses,
+              times_seen:       @times_seen,
+              win_rate:         win_rate,
+              preference_label: preference_label,
+              created_at:       @created_at
+            }
+          end
+
+          private
+
+          def clamp(value)
+            value.clamp(Constants::PREFERENCE_FLOOR, Constants::PREFERENCE_CEILING)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/preference_learning/helpers/preference_engine.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      module Helpers
+        class PreferenceEngine
+          def initialize
+            @options      = {} # id => Option
+            @comparisons  = 0
+          end
+
+          def register_option(label:, domain: :general)
+            return { error: 'max options reached' } if @options.size >= Constants::MAX_OPTIONS
+
+            option = Option.new(label: label, domain: domain)
+            @options[option.id] = option
+            option.to_h
+          end
+
+          def record_comparison(winner_id:, loser_id:)
+            winner = @options[winner_id]
+            loser  = @options[loser_id]
+            return { error: 'option not found' } unless winner && loser
+
+            @comparisons += 1
+            winner.win!
+            loser.lose!
+
+            {
+              winner_id:    winner_id,
+              loser_id:     loser_id,
+              comparisons:  @comparisons,
+              winner_score: winner.preference_score,
+              loser_score:  loser.preference_score
+            }
+          end
+
+          def predict_preference(option_a_id:, option_b_id:)
+            a = @options[option_a_id]
+            b = @options[option_b_id]
+            return { error: 'option not found' } unless a && b
+
+            diff       = (a.preference_score - b.preference_score).abs
+            confidence = diff.clamp(0.0, 1.0)
+            preferred  = a.preference_score >= b.preference_score ? a : b
+
+            {
+              preferred_id:    preferred.id,
+              preferred_label: preferred.label,
+              confidence:      confidence,
+              score_a:         a.preference_score,
+              score_b:         b.preference_score
+            }
+          end
+
+          def top_preferences(domain: nil, limit: 5)
+            filtered(domain).sort_by { |o| -o.preference_score }.first(limit).map(&:to_h)
+          end
+
+          def bottom_preferences(domain: nil, limit: 5)
+            filtered(domain).sort_by(&:preference_score).first(limit).map(&:to_h)
+          end
+
+          def preferences_by_domain(domain:)
+            @options.values
+                    .select { |o| o.domain == domain }
+                    .sort_by { |o| -o.preference_score }
+                    .map(&:to_h)
+          end
+
+          def preference_stability
+            scores = @options.values.map(&:preference_score)
+            return 0.0 if scores.size < 2
+
+            mean = scores.sum / scores.size.to_f
+            variance = scores.sum { |s| (s - mean)**2 } / scores.size.to_f
+            Math.sqrt(variance)
+          end
+
+          def most_compared(limit: 10)
+            @options.values
+                    .sort_by { |o| -o.times_seen }
+                    .first(limit)
+                    .map(&:to_h)
+          end
+
+          def decay_all
+            @options.each_value do |option|
+              delta = (option.preference_score - Constants::DEFAULT_PREFERENCE) * Constants::DECAY_RATE
+              option.preference_score = (option.preference_score - delta)
+                                        .clamp(Constants::PREFERENCE_FLOOR, Constants::PREFERENCE_CEILING)
+            end
+            @options.size
+          end
+
+          def to_h
+            {
+              total_options: @options.size,
+              comparisons:   @comparisons,
+              stability:     preference_stability,
+              options:       @options.values.map(&:to_h)
+            }
+          end
+
+          private
+
+          def filtered(domain)
+            return @options.values if domain.nil?
+
+            @options.values.select { |o| o.domain == domain }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      module Runners
+        module PreferenceLearning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_preference_option(label:, domain: :general, **)
+            result = preference_engine.register_option(label: label, domain: domain)
+            if result[:error]
+              Legion::Logging.warn "[preference_learning] register failed: #{result[:error]}"
+            else
+              Legion::Logging.debug "[preference_learning] registered option id=#{result[:id]} label=#{label} domain=#{domain}"
+            end
+            result
+          end
+
+          def record_preference_comparison(winner_id:, loser_id:, **)
+            result = preference_engine.record_comparison(winner_id: winner_id, loser_id: loser_id)
+            if result[:error]
+              Legion::Logging.warn "[preference_learning] comparison failed: #{result[:error]}"
+            else
+              Legion::Logging.info "[preference_learning] comparison: winner=#{winner_id} loser=#{loser_id} total=#{result[:comparisons]}"
+            end
+            result
+          end
+
+          def predict_preference_outcome(option_a_id:, option_b_id:, **)
+            result = preference_engine.predict_preference(option_a_id: option_a_id, option_b_id: option_b_id)
+            if result[:error]
+              Legion::Logging.warn "[preference_learning] predict failed: #{result[:error]}"
+            else
+              Legion::Logging.debug "[preference_learning] predict: preferred=#{result[:preferred_label]} confidence=#{result[:confidence].round(2)}"
+            end
+            result
+          end
+
+          def top_preferences_report(domain: nil, limit: 5, **)
+            options = preference_engine.top_preferences(domain: domain, limit: limit)
+            Legion::Logging.debug "[preference_learning] top #{limit} preferences domain=#{domain.inspect} count=#{options.size}"
+            { domain: domain, limit: limit, options: options }
+          end
+
+          def preference_stability_report(**)
+            stability = preference_engine.preference_stability
+            label     = stability < 0.1 ? :stable : :variable
+            Legion::Logging.debug "[preference_learning] stability=#{stability.round(4)} label=#{label}"
+            { stability: stability, label: label }
+          end
+
+          def update_preference_learning(**)
+            count = preference_engine.decay_all
+            Legion::Logging.debug "[preference_learning] decay cycle: options_updated=#{count}"
+            { decayed: count }
+          end
+
+          def preference_learning_stats(**)
+            engine_hash = preference_engine.to_h
+            Legion::Logging.debug "[preference_learning] stats: total_options=#{engine_hash[:total_options]} comparisons=#{engine_hash[:comparisons]}"
+            engine_hash.merge(stability_label: preference_engine_stability_label)
+          end
+
+          private
+
+          def preference_engine
+            @preference_engine ||= Helpers::PreferenceEngine.new
+          end
+
+          def preference_engine_stability_label
+            stability = preference_engine.preference_stability
+            stability < 0.1 ? :stable : :variable
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/preference_learning.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/preference_learning/version'
+require 'legion/extensions/preference_learning/helpers/constants'
+require 'legion/extensions/preference_learning/helpers/option'
+require 'legion/extensions/preference_learning/helpers/preference_engine'
+require 'legion/extensions/preference_learning/runners/preference_learning'
+
+module Legion
+  module Extensions
+    module PreferenceLearning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/preference_learning/client'
+
+RSpec.describe Legion::Extensions::PreferenceLearning::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:register_preference_option)
+    expect(client).to respond_to(:record_preference_comparison)
+    expect(client).to respond_to(:predict_preference_outcome)
+    expect(client).to respond_to(:top_preferences_report)
+    expect(client).to respond_to(:preference_stability_report)
+    expect(client).to respond_to(:update_preference_learning)
+    expect(client).to respond_to(:preference_learning_stats)
+  end
+end

data/spec/legion/extensions/preference_learning/helpers/constants_spec.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::PreferenceLearning::Helpers::Constants do
+  describe 'PREFERENCE_LABELS' do
+    subject(:labels) { described_class::PREFERENCE_LABELS }
+
+    it 'labels 0.9 as strongly_preferred' do
+      label = labels.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:strongly_preferred)
+    end
+
+    it 'labels 0.7 as preferred' do
+      label = labels.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:preferred)
+    end
+
+    it 'labels 0.5 as neutral' do
+      label = labels.find { |range, _| range.cover?(0.5) }&.last
+      expect(label).to eq(:neutral)
+    end
+
+    it 'labels 0.3 as disliked' do
+      label = labels.find { |range, _| range.cover?(0.3) }&.last
+      expect(label).to eq(:disliked)
+    end
+
+    it 'labels 0.1 as strongly_disliked' do
+      label = labels.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:strongly_disliked)
+    end
+  end
+
+  describe 'numeric constants' do
+    it 'defines MAX_OPTIONS' do
+      expect(described_class::MAX_OPTIONS).to eq(200)
+    end
+
+    it 'defines MAX_COMPARISONS' do
+      expect(described_class::MAX_COMPARISONS).to eq(1000)
+    end
+
+    it 'defines MAX_HISTORY' do
+      expect(described_class::MAX_HISTORY).to eq(500)
+    end
+
+    it 'defines DEFAULT_PREFERENCE as 0.5' do
+      expect(described_class::DEFAULT_PREFERENCE).to eq(0.5)
+    end
+
+    it 'defines PREFERENCE_FLOOR as 0.0' do
+      expect(described_class::PREFERENCE_FLOOR).to eq(0.0)
+    end
+
+    it 'defines PREFERENCE_CEILING as 1.0' do
+      expect(described_class::PREFERENCE_CEILING).to eq(1.0)
+    end
+
+    it 'WIN_BOOST is greater than LOSS_PENALTY inverted' do
+      expect(described_class::WIN_BOOST).to eq(0.08)
+      expect(described_class::LOSS_PENALTY).to eq(0.06)
+    end
+
+    it 'defines DECAY_RATE' do
+      expect(described_class::DECAY_RATE).to eq(0.01)
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/preference_learning/helpers/preference_engine_spec.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::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/preference_learning/runners/preference_learning_spec.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/preference_learning/client'
+
+RSpec.describe Legion::Extensions::PreferenceLearning::Runners::PreferenceLearning do
+  let(:client) { Legion::Extensions::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/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/preference_learning'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-preference-learning
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Learns and models preferences from choices and feedback for brain-modeled
+  agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-preference-learning.gemspec
+- lib/legion/extensions/preference_learning.rb
+- lib/legion/extensions/preference_learning/actors/decay.rb
+- lib/legion/extensions/preference_learning/client.rb
+- lib/legion/extensions/preference_learning/helpers/constants.rb
+- lib/legion/extensions/preference_learning/helpers/option.rb
+- lib/legion/extensions/preference_learning/helpers/preference_engine.rb
+- lib/legion/extensions/preference_learning/runners/preference_learning.rb
+- lib/legion/extensions/preference_learning/version.rb
+- spec/legion/extensions/preference_learning/client_spec.rb
+- spec/legion/extensions/preference_learning/helpers/constants_spec.rb
+- spec/legion/extensions/preference_learning/helpers/option_spec.rb
+- spec/legion/extensions/preference_learning/helpers/preference_engine_spec.rb
+- spec/legion/extensions/preference_learning/runners/preference_learning_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-preference-learning
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-preference-learning
+  source_code_uri: https://github.com/LegionIO/lex-preference-learning
+  documentation_uri: https://github.com/LegionIO/lex-preference-learning
+  changelog_uri: https://github.com/LegionIO/lex-preference-learning
+  bug_tracker_uri: https://github.com/LegionIO/lex-preference-learning/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Preference Learning
+test_files: []