lex-preference-learning

Pairwise preference learning engine for the LegionIO cognitive architecture. Builds preference scores through comparison history and supports preference prediction.

What It Does

Maintains a registry of labeled options with preference scores. Scores are updated through pairwise comparisons (winner gets a boost, loser gets a penalty) and drift back toward neutral over time. Supports predicting which of two options would be preferred based on accumulated comparison history, domain-filtered rankings, and stability measurement.

Usage

client = Legion::Extensions::PreferenceLearning::Client.new

# Register options
a = client.register_preference_option(label: 'direct_response', domain: :communication)
b = client.register_preference_option(label: 'step_by_step', domain: :communication)
c = client.register_preference_option(label: 'with_examples', domain: :communication)

# Record pairwise comparisons
client.record_preference_comparison(winner_id: a[:id], loser_id: b[:id])
client.record_preference_comparison(winner_id: c[:id], loser_id: b[:id])
client.record_preference_comparison(winner_id: a[:id], loser_id: c[:id])

# Predict preference between two options
client.predict_preference_outcome(option_a_id: a[:id], option_b_id: c[:id])
# => { preferred_id: '...', preferred_label: 'direct_response', confidence: 0.14,
#      score_a: 0.66, score_b: 0.52 }

# Top preferences in a domain
client.top_preferences_report(domain: :communication, limit: 3)

# Stability (how spread out the scores are)
client.preference_stability_report
# => { stability: 0.06, label: :stable }

# Periodic decay (scores drift toward neutral)
client.update_preference_learning
client.preference_learning_stats

Preference Labels

:strongly_preferred (>= 0.8), :preferred (0.6–0.8), :neutral (0.4–0.6), :disliked (0.2–0.4), :strongly_disliked (< 0.2)

Development

bundle install
bundle exec rspec
bundle exec rubocop

License

MIT