lex-agentic-executive 0.1.0

data/lib/legion/extensions/agentic/executive/load_balancing/helpers/load_balancer.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module LoadBalancing
+          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
+  end
+end

data/lib/legion/extensions/agentic/executive/load_balancing/helpers/subsystem.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module LoadBalancing
+          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
+  end
+end

data/lib/legion/extensions/agentic/executive/load_balancing/runners/cognitive_load_balancing.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module LoadBalancing
+          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
+  end
+end

data/lib/legion/extensions/agentic/executive/load_balancing/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module LoadBalancing
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/load_balancing.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'load_balancing/version'
+require_relative 'load_balancing/helpers/constants'
+require_relative 'load_balancing/helpers/subsystem'
+require_relative 'load_balancing/helpers/load_balancer'
+require_relative 'load_balancing/runners/cognitive_load_balancing'
+require_relative 'load_balancing/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module LoadBalancing
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/planning/client.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/executive/planning/helpers/constants'
+require 'legion/extensions/agentic/executive/planning/helpers/plan_step'
+require 'legion/extensions/agentic/executive/planning/helpers/plan'
+require 'legion/extensions/agentic/executive/planning/helpers/plan_store'
+require 'legion/extensions/agentic/executive/planning/runners/planning'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Planning
+          class Client
+            include Runners::Planning
+
+            attr_reader :plan_store
+
+            def initialize(plan_store: nil, **)
+              @plan_store = plan_store || Helpers::PlanStore.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/planning/helpers/constants.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Planning
+          module Helpers
+            module Constants
+              PLAN_STATUSES  = %i[forming active executing completed failed abandoned].freeze
+              STEP_STATUSES  = %i[pending active completed failed skipped blocked].freeze
+              PRIORITIES     = { critical: 1.0, high: 0.75, medium: 0.5, low: 0.25 }.freeze
+              MAX_PLANS      = 50
+              MAX_STEPS_PER_PLAN  = 100
+              MAX_CONTINGENCIES   = 20
+              REPLAN_LIMIT        = 3
+              STALE_PLAN_THRESHOLD   = 3600
+              COMPLETION_THRESHOLD   = 0.95
+              PLANNING_HORIZON       = 10
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/planning/helpers/plan.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Planning
+          module Helpers
+            class Plan
+              attr_reader :id, :goal, :description, :priority, :steps, :contingencies,
+                          :parent_plan_id, :created_at, :replan_count
+              attr_accessor :status, :updated_at
+
+              def initialize(goal:, steps: [], priority: :medium, contingencies: {}, parent_plan_id: nil, description: nil, **)
+                @id             = SecureRandom.uuid
+                @goal           = goal
+                @description    = description
+                @priority       = priority
+                @status         = :forming
+                @steps          = steps.dup
+                @contingencies  = contingencies.dup
+                @parent_plan_id = parent_plan_id
+                @created_at     = Time.now.utc
+                @updated_at     = Time.now.utc
+                @replan_count   = 0
+              end
+
+              def progress
+                return 0.0 if @steps.empty?
+
+                done = @steps.count { |s| %i[completed skipped].include?(s.status) }
+                done.to_f / @steps.size
+              end
+
+              def active_step
+                @steps.find { |s| s.status == :active }
+              end
+
+              def completed_step_ids
+                @steps.select { |s| %i[completed skipped].include?(s.status) }.map(&:id)
+              end
+
+              def advance!(step_id, result: nil)
+                step = @steps.find { |s| s.id == step_id }
+                return nil unless step
+
+                step.complete!(result: result)
+                @updated_at = Time.now.utc
+                @status = :completed if progress >= Constants::COMPLETION_THRESHOLD
+                step
+              end
+
+              def fail_step!(step_id, reason: nil)
+                step = @steps.find { |s| s.id == step_id }
+                return nil unless step
+
+                step.fail!(reason: reason)
+                @updated_at = Time.now.utc
+                step
+              end
+
+              def complete?
+                @status == :completed || progress >= Constants::COMPLETION_THRESHOLD
+              end
+
+              def failed?
+                @status == :failed
+              end
+
+              def stale?
+                (Time.now.utc - @updated_at) > Constants::STALE_PLAN_THRESHOLD
+              end
+
+              def increment_replan!
+                @replan_count += 1
+                @updated_at = Time.now.utc
+              end
+
+              def replace_remaining_steps!(new_steps)
+                pending = @steps.reject { |s| %i[completed skipped failed].include?(s.status) }
+                pending.each { |s| @steps.delete(s) }
+                new_steps.each { |s| @steps << s }
+                @updated_at = Time.now.utc
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  goal:           @goal,
+                  description:    @description,
+                  priority:       @priority,
+                  status:         @status,
+                  progress:       progress.round(4),
+                  steps:          @steps.map(&:to_h),
+                  contingencies:  @contingencies,
+                  parent_plan_id: @parent_plan_id,
+                  replan_count:   @replan_count,
+                  created_at:     @created_at,
+                  updated_at:     @updated_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/planning/helpers/plan_step.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Planning
+          module Helpers
+            class PlanStep
+              attr_reader :id, :action, :description, :depends_on, :estimated_effort,
+                          :started_at, :completed_at, :result
+              attr_accessor :status, :actual_effort
+
+              def initialize(action:, description: nil, depends_on: [], estimated_effort: 1, **)
+                @id               = SecureRandom.uuid
+                @action           = action
+                @description      = description
+                @status           = :pending
+                @depends_on       = Array(depends_on).dup
+                @estimated_effort = estimated_effort
+                @actual_effort    = nil
+                @result           = nil
+                @started_at       = nil
+                @completed_at     = nil
+              end
+
+              def ready?(completed_step_ids)
+                return false if %i[completed failed skipped].include?(@status)
+
+                @depends_on.all? { |dep_id| completed_step_ids.include?(dep_id) }
+              end
+
+              def duration
+                return nil unless @started_at && @completed_at
+
+                @completed_at - @started_at
+              end
+
+              def blocked?
+                @status == :blocked
+              end
+
+              def complete!(result: nil)
+                @status       = :completed
+                @result       = result
+                @completed_at = Time.now.utc
+              end
+
+              def fail!(reason: nil)
+                @status       = :failed
+                @result       = { reason: reason }
+                @completed_at = Time.now.utc
+              end
+
+              def start!
+                @status     = :active
+                @started_at = Time.now.utc
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  action:           @action,
+                  description:      @description,
+                  status:           @status,
+                  depends_on:       @depends_on,
+                  estimated_effort: @estimated_effort,
+                  actual_effort:    @actual_effort,
+                  result:           @result,
+                  started_at:       @started_at,
+                  completed_at:     @completed_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end