lex-cognitive-load-balancing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c544354dc10debe5f37d9481d770ae4d9ef9d9ff05e2f9463c7ede05ce1243bf
+  data.tar.gz: 6d51ca7b3e00f79ab95e6cd401c1499b78af6554dd017ef80600fd67e24d601c
+SHA512:
+  metadata.gz: 57cc1ca0b87c2fc8d5be5d5341072cba5f8338a52dbf2c236a54b7b4ba4c27a3b71b85de72fcf2f237bb5401531663f6dc7986d911357fbceab06dcb4d7e1280
+  data.tar.gz: 44efcecde4666d5374e1e8abdaa3f8b3fe7ba1ada740112b2ffb0b285fa06eaa71c5a5f53a7b491f54922cde082df6d17631f6dd40837d8acd9e5ec0755ef982

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLoadBalancing
+      class Client
+        include Runners::CognitiveLoadBalancing
+
+        def engine
+          @engine ||= Helpers::LoadBalancer.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLoadBalancing
+      module Helpers
+        module Constants
+          MAX_SUBSYSTEMS = 50
+          MAX_TASKS = 500
+
+          DEFAULT_CAPACITY = 1.0
+          OVERLOAD_THRESHOLD = 0.85
+          UNDERLOAD_THRESHOLD = 0.2
+          REBALANCE_STEP = 0.1
+
+          LOAD_LABELS = {
+            (0.85..)     => :overloaded,
+            (0.7...0.85) => :heavy,
+            (0.4...0.7)  => :balanced,
+            (0.2...0.4)  => :light,
+            (..0.2)      => :idle
+          }.freeze
+
+          HEALTH_LABELS = {
+            (0.8..)     => :excellent,
+            (0.6...0.8) => :good,
+            (0.4...0.6) => :fair,
+            (0.2...0.4) => :strained,
+            (..0.2)     => :failing
+          }.freeze
+
+          SUBSYSTEM_TYPES = %i[
+            perception reasoning memory attention
+            language planning motor emotional
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_load_balancing/helpers/load_balancer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLoadBalancing
+      module Helpers
+        class LoadBalancer
+          include Constants
+
+          def initialize
+            @subsystems = {}
+          end
+
+          def register_subsystem(name:, subsystem_type: :general, capacity: DEFAULT_CAPACITY)
+            prune_if_needed
+            subsystem = Subsystem.new(
+              name:           name,
+              subsystem_type: subsystem_type,
+              capacity:       capacity
+            )
+            @subsystems[subsystem.id] = subsystem
+            subsystem
+          end
+
+          def assign_load(subsystem_id:, amount:)
+            subsystem = @subsystems[subsystem_id]
+            return nil unless subsystem
+
+            subsystem.add_load!(amount: amount)
+          end
+
+          def shed_load(subsystem_id:, amount:)
+            subsystem = @subsystems[subsystem_id]
+            return nil unless subsystem
+
+            subsystem.shed_load!(amount: amount)
+          end
+
+          def auto_assign(amount:, subsystem_type: nil)
+            candidates = if subsystem_type
+                           @subsystems.values.select { |s| s.subsystem_type == subsystem_type.to_sym }
+                         else
+                           @subsystems.values
+                         end
+            return nil if candidates.empty?
+
+            best = candidates.min_by(&:utilization)
+            best.add_load!(amount: amount)
+            best
+          end
+
+          def rebalance
+            overloaded = @subsystems.values.select(&:overloaded?)
+            underloaded = @subsystems.values.select(&:underloaded?)
+            transfers = 0
+
+            overloaded.each do |over|
+              target = underloaded.min_by(&:utilization)
+              break unless target
+
+              transfer_amount = [REBALANCE_STEP, over.current_load * 0.2].min
+              shed = over.shed_load!(amount: transfer_amount)
+              target.add_load!(amount: shed)
+              transfers += 1
+            end
+
+            transfers
+          end
+
+          def overloaded_subsystems
+            @subsystems.values.select(&:overloaded?)
+          end
+
+          def underloaded_subsystems
+            @subsystems.values.select(&:underloaded?)
+          end
+
+          def subsystems_by_type(subsystem_type:)
+            st = subsystem_type.to_sym
+            @subsystems.values.select { |s| s.subsystem_type == st }
+          end
+
+          def most_loaded(limit: 5)
+            @subsystems.values.sort_by { |s| -s.utilization }.first(limit)
+          end
+
+          def overall_utilization
+            return 0.0 if @subsystems.empty?
+
+            utils = @subsystems.values.map(&:utilization)
+            (utils.sum / utils.size).round(10)
+          end
+
+          def overall_health
+            return 1.0 if @subsystems.empty?
+
+            healths = @subsystems.values.map(&:health)
+            (healths.sum / healths.size).round(10)
+          end
+
+          def balance_report
+            {
+              total_subsystems:    @subsystems.size,
+              overloaded_count:    overloaded_subsystems.size,
+              underloaded_count:   underloaded_subsystems.size,
+              overall_utilization: overall_utilization,
+              overall_health:      overall_health,
+              most_loaded:         most_loaded(limit: 3).map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              total_subsystems:    @subsystems.size,
+              overall_utilization: overall_utilization,
+              overall_health:      overall_health,
+              overloaded_count:    overloaded_subsystems.size
+            }
+          end
+
+          private
+
+          def prune_if_needed
+            return if @subsystems.size < MAX_SUBSYSTEMS
+
+            least_used = @subsystems.values.min_by(&:tasks_processed)
+            @subsystems.delete(least_used.id) if least_used
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_load_balancing/helpers/subsystem.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveLoadBalancing
+      module Helpers
+        class Subsystem
+          include Constants
+
+          attr_reader :id, :name, :subsystem_type, :capacity, :current_load,
+                      :tasks_processed, :tasks_shed, :created_at
+
+          def initialize(name:, subsystem_type: :general, capacity: DEFAULT_CAPACITY)
+            @id              = SecureRandom.uuid
+            @name            = name
+            @subsystem_type  = subsystem_type.to_sym
+            @capacity        = capacity.to_f.clamp(0.1, 5.0)
+            @current_load    = 0.0
+            @tasks_processed = 0
+            @tasks_shed      = 0
+            @created_at      = Time.now.utc
+          end
+
+          def utilization
+            return 0.0 if @capacity.zero?
+
+            (@current_load / @capacity).clamp(0.0, 1.5).round(10)
+          end
+
+          def load_label
+            match = LOAD_LABELS.find { |range, _| range.cover?(utilization) }
+            match ? match.last : :overloaded
+          end
+
+          def overloaded?
+            utilization >= OVERLOAD_THRESHOLD
+          end
+
+          def underloaded?
+            utilization <= UNDERLOAD_THRESHOLD
+          end
+
+          def health
+            if overloaded?
+              [1.0 - ((utilization - OVERLOAD_THRESHOLD) * 3), 0.0].max.round(10)
+            else
+              1.0
+            end
+          end
+
+          def health_label
+            match = HEALTH_LABELS.find { |range, _| range.cover?(health) }
+            match ? match.last : :failing
+          end
+
+          def add_load!(amount:)
+            @current_load = (@current_load + amount.to_f).clamp(0.0, @capacity * 1.5).round(10)
+            @tasks_processed += 1
+            self
+          end
+
+          def shed_load!(amount:)
+            removed = [amount.to_f, @current_load].min
+            @current_load = (@current_load - removed).clamp(0.0, @capacity * 1.5).round(10)
+            @tasks_shed += 1
+            removed
+          end
+
+          def available_capacity
+            [(@capacity - @current_load), 0.0].max.round(10)
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              name:               @name,
+              subsystem_type:     @subsystem_type,
+              capacity:           @capacity,
+              current_load:       @current_load,
+              utilization:        utilization,
+              load_label:         load_label,
+              overloaded:         overloaded?,
+              health:             health,
+              health_label:       health_label,
+              available_capacity: available_capacity,
+              tasks_processed:    @tasks_processed,
+              tasks_shed:         @tasks_shed,
+              created_at:         @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLoadBalancing
+      module Runners
+        module CognitiveLoadBalancing
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def register_cognitive_subsystem(name:, subsystem_type: :general,
+                                           capacity: nil, **)
+            cap = capacity || Helpers::Constants::DEFAULT_CAPACITY
+            sub = engine.register_subsystem(name: name, subsystem_type: subsystem_type,
+                                            capacity: cap)
+            { success: true }.merge(sub.to_h)
+          end
+
+          def assign_cognitive_load(subsystem_id:, amount:, **)
+            result = engine.assign_load(subsystem_id: subsystem_id, amount: amount)
+            return { success: false, error: 'subsystem not found' } unless result
+
+            { success: true }.merge(result.to_h)
+          end
+
+          def shed_cognitive_load(subsystem_id:, amount:, **)
+            result = engine.shed_load(subsystem_id: subsystem_id, amount: amount)
+            return { success: false, error: 'subsystem not found' } unless result
+
+            { success: true, shed: result }
+          end
+
+          def auto_assign_load(amount:, subsystem_type: nil, **)
+            result = engine.auto_assign(amount: amount, subsystem_type: subsystem_type)
+            return { success: false, error: 'no available subsystem' } unless result
+
+            { success: true, assigned_to: result.name }.merge(result.to_h)
+          end
+
+          def rebalance_cognitive_load(**)
+            transfers = engine.rebalance
+            { success: true, transfers: transfers, stats: engine.to_h }
+          end
+
+          def overloaded_subsystems_report(**)
+            subs = engine.overloaded_subsystems
+            { success: true, count: subs.size, subsystems: subs.map(&:to_h) }
+          end
+
+          def most_loaded_report(limit: 5, **)
+            subs = engine.most_loaded(limit: limit)
+            { success: true, limit: limit, subsystems: subs.map(&:to_h) }
+          end
+
+          def cognitive_load_balance_report(**)
+            engine.balance_report
+          end
+
+          def cognitive_load_balancing_stats(**)
+            engine.to_h
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_load_balancing.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'cognitive_load_balancing/version'
+require_relative 'cognitive_load_balancing/helpers/constants'
+require_relative 'cognitive_load_balancing/helpers/subsystem'
+require_relative 'cognitive_load_balancing/helpers/load_balancer'
+require_relative 'cognitive_load_balancing/runners/cognitive_load_balancing'
+require_relative 'cognitive_load_balancing/client'
+
+module Legion
+  module Extensions
+    module CognitiveLoadBalancing
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-load-balancing
+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: Dynamic distribution of cognitive work across subsystems with overload
+  detection, auto-assignment, and rebalancing.
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/cognitive_load_balancing.rb
+- lib/legion/extensions/cognitive_load_balancing/client.rb
+- lib/legion/extensions/cognitive_load_balancing/helpers/constants.rb
+- lib/legion/extensions/cognitive_load_balancing/helpers/load_balancer.rb
+- lib/legion/extensions/cognitive_load_balancing/helpers/subsystem.rb
+- lib/legion/extensions/cognitive_load_balancing/runners/cognitive_load_balancing.rb
+- lib/legion/extensions/cognitive_load_balancing/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-load-balancing
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-load-balancing
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-load-balancing
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-load-balancing
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-load-balancing/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-load-balancing/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: Cognitive load balancing across subsystems for LegionIO
+test_files: []