lex-learning-rate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1b65632c8f5e9197247406e7b85c36ca70b05c191410904d854146d5c9bae097
+  data.tar.gz: e00c09af41cdd7b301f987c302fdbf147ffb6db418af395b08d4ade3d3cf5ef5
+SHA512:
+  metadata.gz: bcb141f0edeae5372798eee9488d884eba72ce9afd87a953db5a4df939f852103846742ea1dee7f8608695e4422bb4099c37d6b17a7566f03d1112810a903407
+  data.tar.gz: bc7c36f9d70572b67c25c9ff60c243551d6a7ac5c06a0fbb987ce158327ec324c238190a9d499544ec2bcfbfe1b1fc9ff667816e37bc278ec9d5f5fec4ef6cae

data/README.md

@@ -0,0 +1,83 @@
+# lex-learning-rate
+
+Adaptive learning rate management for LegionIO agents. Part of the LegionIO cognitive architecture extension ecosystem (LEX).
+
+## What It Does
+
+`lex-learning-rate` maintains per-domain learning rates that adapt to the agent's prediction performance. Wrong predictions raise the rate (more learning needed), correct predictions lower it (stable enough), and surprise or error events provide temporary boosts. Rates mean-revert toward a default over time. Rolling accuracy windows give a per-domain reliability signal.
+
+Key capabilities:
+
+- **Per-domain rates**: independent learning rate per knowledge domain
+- **Prediction-driven adjustment**: wrong prediction +0.03, correct prediction -0.02
+- **Event boosts**: surprise +0.05, error +0.04
+- **Mean reversion**: rates drift back toward 0.15 default via decay
+- **Rate labels**: very_slow / slow / moderate / fast / very_fast per rate value
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-learning-rate'
+```
+
+Or install directly:
+
+```
+gem install lex-learning-rate
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/learning_rate'
+
+client = Legion::Extensions::LearningRate::Client.new
+
+# Record prediction outcomes
+client.record_prediction(domain: :networking, correct: false)
+client.record_prediction(domain: :networking, correct: false)
+
+# Record surprise or error events
+client.record_surprise(domain: :networking)
+
+# Check current rate
+result = client.current_rate(domain: :networking)
+# => { domain: :networking, rate: 0.27, label: :fast, accuracy: 0.3 }
+
+# Find domains with highest/lowest learning rates
+client.fastest_domains(limit: 3)
+client.slowest_domains(limit: 3)
+
+# Feed tick results (auto-extracts prediction outcomes)
+client.update_learning_rate(tick_results: tick_phase_results)
+
+# Stats
+client.learning_rate_stats
+```
+
+## Runner Methods
+
+| Method | Description |
+|---|---|
+| `record_prediction` | Record a prediction outcome and adjust the domain rate |
+| `record_surprise` | Apply a surprise boost to a domain's rate |
+| `record_error` | Apply an error boost to a domain's rate |
+| `current_rate` | Current rate value and label for a domain |
+| `fastest_domains` | Top N domains by current learning rate |
+| `slowest_domains` | Bottom N domains by current learning rate |
+| `update_learning_rate` | Extract prediction outcomes from tick results and record |
+| `learning_rate_stats` | Domain count, avg rate, fastest/slowest, overall accuracy |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/learning_rate/helpers/constants'
+require 'legion/extensions/learning_rate/helpers/rate_model'
+require 'legion/extensions/learning_rate/runners/learning_rate'
+
+module Legion
+  module Extensions
+    module LearningRate
+      class Client
+        include Runners::LearningRate
+
+        attr_reader :rate_model
+
+        def initialize(rate_model: nil, **)
+          @rate_model = rate_model || Helpers::RateModel.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LearningRate
+      module Helpers
+        module Constants
+          DEFAULT_RATE         = 0.15
+          MIN_RATE             = 0.01
+          MAX_RATE             = 0.5
+          RATE_INCREASE        = 0.03
+          RATE_DECREASE        = 0.02
+          RATE_DECAY           = 0.005
+          ACCURACY_WINDOW      = 20
+          SURPRISE_BOOST       = 0.05
+          ERROR_BOOST          = 0.04
+          CONFIDENCE_DAMPENING = 0.03
+          MAX_DOMAINS          = 50
+          MAX_RATE_HISTORY     = 200
+
+          RATE_LABELS = {
+            (0.3..)       => :fast_learning,
+            (0.15...0.3)  => :moderate_learning,
+            (0.05...0.15) => :slow_learning,
+            (..0.05)      => :consolidated
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/learning_rate/helpers/rate_model.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LearningRate
+      module Helpers
+        class RateModel
+          include Constants
+
+          attr_reader :rates, :accuracy_buffers, :rate_history
+
+          def initialize
+            @rates            = {}
+            @accuracy_buffers = {}
+            @rate_history     = []
+          end
+
+          def rate_for(domain)
+            @rates.fetch(domain, DEFAULT_RATE)
+          end
+
+          def record_prediction(domain:, correct:)
+            ensure_domain(domain)
+            @accuracy_buffers[domain] << (correct ? 1.0 : 0.0)
+            @accuracy_buffers[domain].shift while @accuracy_buffers[domain].size > ACCURACY_WINDOW
+            adjust_rate(domain, correct: correct)
+          end
+
+          def record_surprise(domain:, magnitude:)
+            ensure_domain(domain)
+            boost = magnitude * SURPRISE_BOOST
+            @rates[domain] = (@rates[domain] + boost).clamp(MIN_RATE, MAX_RATE)
+            record_event(domain, :surprise, @rates[domain])
+          end
+
+          def record_error(domain:, magnitude:)
+            ensure_domain(domain)
+            boost = magnitude * ERROR_BOOST
+            @rates[domain] = (@rates[domain] + boost).clamp(MIN_RATE, MAX_RATE)
+            record_event(domain, :error, @rates[domain])
+          end
+
+          def accuracy_for(domain)
+            buffer = @accuracy_buffers.fetch(domain, [])
+            return 0.0 if buffer.empty?
+
+            buffer.sum / buffer.size
+          end
+
+          def decay
+            @rates.each_key do |domain|
+              current = @rates[domain]
+              delta = (current - DEFAULT_RATE) * RATE_DECAY
+              @rates[domain] = (current - delta).clamp(MIN_RATE, MAX_RATE)
+            end
+          end
+
+          def label_for(domain)
+            rate = rate_for(domain)
+            RATE_LABELS.each do |range, lbl|
+              return lbl if range.cover?(rate)
+            end
+            :consolidated
+          end
+
+          def fastest_domains(count = 5)
+            @rates.sort_by { |_, r| -r }.first(count).to_h
+          end
+
+          def slowest_domains(count = 5)
+            @rates.sort_by { |_, r| r }.first(count).to_h
+          end
+
+          def overall_rate
+            return DEFAULT_RATE if @rates.empty?
+
+            @rates.values.sum / @rates.size
+          end
+
+          def domain_count
+            @rates.size
+          end
+
+          def to_h
+            {
+              domain_count: @rates.size,
+              overall_rate: overall_rate.round(4),
+              rates:        @rates.dup,
+              history_size: @rate_history.size
+            }
+          end
+
+          private
+
+          def ensure_domain(domain)
+            @rates[domain] ||= DEFAULT_RATE
+            @accuracy_buffers[domain] ||= []
+            trim_domains(protect: domain) if @rates.size > MAX_DOMAINS
+          end
+
+          def adjust_rate(domain, correct:)
+            @rates[domain] = if correct
+                               (@rates[domain] - RATE_DECREASE).clamp(MIN_RATE, MAX_RATE)
+                             else
+                               (@rates[domain] + RATE_INCREASE).clamp(MIN_RATE, MAX_RATE)
+                             end
+            record_event(domain, correct ? :correct : :incorrect, @rates[domain])
+          end
+
+          def record_event(domain, event_type, rate)
+            @rate_history << { domain: domain, event: event_type, rate: rate, at: Time.now.utc }
+            @rate_history.shift while @rate_history.size > MAX_RATE_HISTORY
+          end
+
+          def trim_domains(protect: nil)
+            candidates = @rates.reject { |k, _| k == protect }
+            sorted = candidates.sort_by { |_, r| (r - DEFAULT_RATE).abs }
+            excess = @rates.size - MAX_DOMAINS
+            remove_keys = sorted.first(excess).map(&:first)
+            remove_keys.each do |key|
+              @rates.delete(key)
+              @accuracy_buffers.delete(key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module LearningRate
+      module Runners
+        module LearningRate
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def record_prediction(correct:, domain: :general, **)
+            rate_model.record_prediction(domain: domain, correct: correct)
+            rate = rate_model.rate_for(domain)
+            accuracy = rate_model.accuracy_for(domain)
+            Legion::Logging.debug "[learning_rate] prediction: domain=#{domain} correct=#{correct} rate=#{rate.round(3)} accuracy=#{accuracy.round(3)}"
+            {
+              success:  true,
+              domain:   domain,
+              rate:     rate,
+              accuracy: accuracy,
+              label:    rate_model.label_for(domain)
+            }
+          end
+
+          def record_surprise(magnitude:, domain: :general, **)
+            rate_model.record_surprise(domain: domain, magnitude: magnitude)
+            rate = rate_model.rate_for(domain)
+            Legion::Logging.debug "[learning_rate] surprise: domain=#{domain} magnitude=#{magnitude.round(3)} rate=#{rate.round(3)}"
+            { success: true, domain: domain, rate: rate, label: rate_model.label_for(domain) }
+          end
+
+          def record_error(magnitude:, domain: :general, **)
+            rate_model.record_error(domain: domain, magnitude: magnitude)
+            rate = rate_model.rate_for(domain)
+            Legion::Logging.debug "[learning_rate] error: domain=#{domain} magnitude=#{magnitude.round(3)} rate=#{rate.round(3)}"
+            { success: true, domain: domain, rate: rate, label: rate_model.label_for(domain) }
+          end
+
+          def current_rate(domain: :general, **)
+            rate = rate_model.rate_for(domain)
+            accuracy = rate_model.accuracy_for(domain)
+            {
+              success:  true,
+              domain:   domain,
+              rate:     rate,
+              accuracy: accuracy,
+              label:    rate_model.label_for(domain)
+            }
+          end
+
+          def fastest_domains(count: 5, **)
+            domains = rate_model.fastest_domains(count)
+            { success: true, domains: domains, count: domains.size }
+          end
+
+          def slowest_domains(count: 5, **)
+            domains = rate_model.slowest_domains(count)
+            { success: true, domains: domains, count: domains.size }
+          end
+
+          def update_learning_rate(**)
+            rate_model.decay
+            overall = rate_model.overall_rate
+            Legion::Logging.debug "[learning_rate] tick: domains=#{rate_model.domain_count} overall=#{overall.round(3)}"
+            { success: true, domain_count: rate_model.domain_count, overall_rate: overall }
+          end
+
+          def learning_rate_stats(**)
+            { success: true, stats: rate_model.to_h }
+          end
+
+          private
+
+          def rate_model
+            @rate_model ||= Helpers::RateModel.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/learning_rate.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/learning_rate/version'
+require 'legion/extensions/learning_rate/helpers/constants'
+require 'legion/extensions/learning_rate/helpers/rate_model'
+require 'legion/extensions/learning_rate/runners/learning_rate'
+require 'legion/extensions/learning_rate/client'
+
+module Legion
+  module Extensions
+    module LearningRate
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: lex-learning-rate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: Adapts the agent learning speed per domain based on prediction accuracy,
+  surprise, and errors. Fast learning when predictions fail, slow consolidation when
+  accurate — the agent learns how fast to learn.
+email:
+- matt@iverson.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/learning_rate.rb
+- lib/legion/extensions/learning_rate/client.rb
+- lib/legion/extensions/learning_rate/helpers/constants.rb
+- lib/legion/extensions/learning_rate/helpers/rate_model.rb
+- lib/legion/extensions/learning_rate/runners/learning_rate.rb
+- lib/legion/extensions/learning_rate/version.rb
+homepage: https://github.com/LegionIO/lex-learning-rate
+licenses:
+- MIT
+metadata:
+  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: Meta-learning rate adaptation for LegionIO
+test_files: []