lex-agentic-executive 0.1.0

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Control
+          module Helpers
+            module Constants
+              MAX_GOALS = 20
+              MAX_POLICIES = 50
+              MAX_HISTORY = 200
+
+              DEFAULT_EFFORT = 0.5
+              EFFORT_FLOOR = 0.1
+              EFFORT_CEILING = 1.0
+              EFFORT_DECAY = 0.02
+              EFFORT_RECOVERY = 0.03
+
+              AUTOMATIC_THRESHOLD = 0.3
+              CONTROLLED_THRESHOLD = 0.6
+              OVERRIDE_THRESHOLD = 0.8
+
+              CONFLICT_BOOST = 0.2
+              ERROR_BOOST = 0.15
+              NOVELTY_BOOST = 0.1
+              ADAPTATION_ALPHA = 0.1
+
+              CONTROL_MODES = %i[automatic controlled override].freeze
+              GOAL_STATES = %i[active suspended completed abandoned].freeze
+
+              EFFORT_LABELS = {
+                (0.8..)     => :maximal,
+                (0.6...0.8) => :effortful,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :low,
+                (..0.2)     => :automatic
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/control/helpers/control_signal.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Control
+          module Helpers
+            class ControlSignal
+              include Constants
+
+              attr_reader :effort_level, :conflict_detected, :error_detected,
+                          :novelty_detected
+
+              def initialize
+                @effort_level = DEFAULT_EFFORT
+                @conflict_detected = false
+                @error_detected = false
+                @novelty_detected = false
+              end
+
+              def detect_conflict
+                @conflict_detected = true
+                @effort_level = [@effort_level + CONFLICT_BOOST, EFFORT_CEILING].min
+              end
+
+              def detect_error
+                @error_detected = true
+                @effort_level = [@effort_level + ERROR_BOOST, EFFORT_CEILING].min
+              end
+
+              def detect_novelty
+                @novelty_detected = true
+                @effort_level = [@effort_level + NOVELTY_BOOST, EFFORT_CEILING].min
+              end
+
+              def reset_detections
+                @conflict_detected = false
+                @error_detected = false
+                @novelty_detected = false
+              end
+
+              def mode
+                return :override if @effort_level >= OVERRIDE_THRESHOLD
+                return :controlled if @effort_level >= CONTROLLED_THRESHOLD
+
+                :automatic
+              end
+
+              def effort_label
+                EFFORT_LABELS.each { |range, lbl| return lbl if range.cover?(@effort_level) }
+                :automatic
+              end
+
+              def decay
+                @effort_level = [@effort_level - EFFORT_DECAY, EFFORT_FLOOR].max
+              end
+
+              def recover(amount: EFFORT_RECOVERY)
+                @effort_level = [@effort_level + amount, EFFORT_CEILING].min
+              end
+
+              def to_h
+                {
+                  effort_level:      @effort_level.round(4),
+                  mode:              mode,
+                  effort_label:      effort_label,
+                  conflict_detected: @conflict_detected,
+                  error_detected:    @error_detected,
+                  novelty_detected:  @novelty_detected
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/control/helpers/controller.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Control
+          module Helpers
+            class Controller
+              include Constants
+
+              attr_reader :goals, :signal, :history
+
+              def initialize
+                @goals    = {}
+                @counter  = 0
+                @signal   = ControlSignal.new
+                @history  = []
+              end
+
+              def set_goal(description:, domain: :general, priority: 0.5)
+                return nil if @goals.size >= MAX_GOALS
+
+                @counter += 1
+                goal_id = :"goal_#{@counter}"
+                goal = Goal.new(id: goal_id, description: description, domain: domain, priority: priority)
+                @goals[goal_id] = goal
+                goal
+              end
+
+              def advance_goal(goal_id:, amount: 0.1)
+                goal = @goals[goal_id]
+                return nil unless goal
+
+                goal.advance(amount: amount)
+              end
+
+              def suspend_goal(goal_id:)
+                goal = @goals[goal_id]
+                return nil unless goal
+
+                goal.suspend!
+              end
+
+              def resume_goal(goal_id:)
+                goal = @goals[goal_id]
+                return nil unless goal
+
+                goal.resume!
+              end
+
+              def abandon_goal(goal_id:)
+                goal = @goals[goal_id]
+                return nil unless goal
+
+                goal.abandon!
+              end
+
+              def evaluate_control_demand(conflict: false, error: false, novelty: false)
+                @signal.reset_detections
+                @signal.detect_conflict if conflict
+                @signal.detect_error if error
+                @signal.detect_novelty if novelty
+                record_evaluation
+                @signal.to_h
+              end
+
+              def current_mode
+                @signal.mode
+              end
+
+              def should_override?
+                @signal.mode == :override
+              end
+
+              def should_control?
+                %i[controlled override].include?(@signal.mode)
+              end
+
+              def active_goals
+                @goals.values.select(&:active?).sort_by { |g| -g.priority }.map(&:to_h)
+              end
+
+              def top_goal
+                active = @goals.values.select(&:active?)
+                return nil if active.empty?
+
+                active.max_by(&:priority).to_h
+              end
+
+              def goal_conflict?
+                active = @goals.values.select(&:active?)
+                return false if active.size < 2
+
+                priorities = active.map(&:priority)
+                (priorities.max - priorities.min) < 0.2 && active.size > 1
+              end
+
+              def tick
+                @signal.decay
+                check_goal_conflicts
+                @signal.to_h
+              end
+
+              def to_h
+                {
+                  goal_count:    @goals.size,
+                  active_goals:  @goals.values.count(&:active?),
+                  effort_level:  @signal.effort_level.round(4),
+                  mode:          current_mode,
+                  effort_label:  @signal.effort_label,
+                  goal_conflict: goal_conflict?,
+                  history_size:  @history.size
+                }
+              end
+
+              private
+
+              def check_goal_conflicts
+                @signal.detect_conflict if goal_conflict?
+              end
+
+              def record_evaluation
+                @history << {
+                  mode:     @signal.mode,
+                  effort:   @signal.effort_level.round(4),
+                  conflict: @signal.conflict_detected,
+                  error:    @signal.error_detected,
+                  novelty:  @signal.novelty_detected,
+                  at:       Time.now.utc
+                }
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/control/helpers/goal.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Control
+          module Helpers
+            class Goal
+              include Constants
+
+              attr_reader :id, :description, :domain, :priority, :state, :progress, :created_at
+
+              def initialize(id:, description:, domain: :general, priority: 0.5)
+                @id          = id
+                @description = description
+                @domain      = domain
+                @priority    = priority.to_f.clamp(0.0, 1.0)
+                @state       = :active
+                @progress    = 0.0
+                @created_at  = Time.now.utc
+              end
+
+              def advance(amount: 0.1)
+                return nil unless @state == :active
+
+                @progress = [@progress + amount, 1.0].min
+                complete! if @progress >= 1.0
+                @progress
+              end
+
+              def complete!
+                @state = :completed
+              end
+
+              def suspend!
+                @state = :suspended if @state == :active
+              end
+
+              def resume!
+                @state = :active if @state == :suspended
+              end
+
+              def abandon!
+                @state = :abandoned unless @state == :completed
+              end
+
+              def active?
+                @state == :active
+              end
+
+              def completed?
+                @state == :completed
+              end
+
+              def to_h
+                {
+                  id:          @id,
+                  description: @description,
+                  domain:      @domain,
+                  priority:    @priority.round(4),
+                  state:       @state,
+                  progress:    @progress.round(4)
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/control/runners/cognitive_control.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Control
+          module Runners
+            module CognitiveControl
+              include Helpers::Constants
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def set_control_goal(description:, domain: :general, priority: 0.5, **)
+                goal = controller.set_goal(description: description, domain: domain, priority: priority)
+                return { success: false, reason: :limit_reached } unless goal
+
+                { success: true, goal_id: goal.id, priority: goal.priority }
+              end
+
+              def advance_control_goal(goal_id:, amount: 0.1, **)
+                result = controller.advance_goal(goal_id: goal_id, amount: amount)
+                return { success: false, reason: :not_found } unless result
+
+                { success: true, goal_id: goal_id, progress: result.round(4) }
+              end
+
+              def suspend_control_goal(goal_id:, **)
+                controller.suspend_goal(goal_id: goal_id)
+                { success: true, goal_id: goal_id }
+              end
+
+              def evaluate_control(conflict: false, error: false, novelty: false, **)
+                result = controller.evaluate_control_demand(conflict: conflict, error: error, novelty: novelty)
+                { success: true }.merge(result)
+              end
+
+              def current_control_mode(**)
+                { success: true, mode: controller.current_mode, should_override: controller.should_override?,
+                  should_control: controller.should_control? }
+              end
+
+              def active_control_goals(**)
+                goals = controller.active_goals
+                { success: true, goals: goals, count: goals.size }
+              end
+
+              def top_control_goal(**)
+                goal = controller.top_goal
+                return { success: false, reason: :no_active_goals } unless goal
+
+                { success: true }.merge(goal)
+              end
+
+              def update_cognitive_control(**)
+                result = controller.tick
+                { success: true }.merge(result)
+              end
+
+              def cognitive_control_stats(**)
+                { success: true }.merge(controller.to_h)
+              end
+
+              private
+
+              def controller
+                @controller ||= Helpers::Controller.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'control/version'
+require_relative 'control/helpers/constants'
+require_relative 'control/helpers/control_signal'
+require_relative 'control/helpers/controller'
+require_relative 'control/helpers/goal'
+require_relative 'control/runners/cognitive_control'
+require_relative 'control/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Control
+          # Sub-module for cognitive control: conflict monitoring and adaptive control signals
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/executive/decision_fatigue/helpers/constants'
+require 'legion/extensions/agentic/executive/decision_fatigue/helpers/decision_record'
+require 'legion/extensions/agentic/executive/decision_fatigue/helpers/fatigue_engine'
+require 'legion/extensions/agentic/executive/decision_fatigue/runners/decision_fatigue'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module DecisionFatigue
+          class Client
+            include Runners::DecisionFatigue
+
+            def initialize(**)
+              @fatigue_engine = Helpers::FatigueEngine.new
+            end
+
+            private
+
+            attr_reader :fatigue_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module DecisionFatigue
+          module Helpers
+            module Constants
+              MAX_DECISIONS = 500
+              DEFAULT_WILLPOWER = 1.0
+              DEPLETION_RATE   = 0.05
+              RECOVERY_RATE    = 0.08
+              QUALITY_FLOOR    = 0.2
+
+              QUALITY_LABELS = [
+                { range: (0.85..1.0),  label: :optimal     },
+                { range: (0.65..0.85), label: :good        },
+                { range: (0.45..0.65), label: :adequate    },
+                { range: (0.25..0.45), label: :compromised },
+                { range: (0.0..0.25),  label: :depleted    }
+              ].freeze
+
+              DECISION_TYPES = %i[analytical evaluative creative routine social moral].freeze
+
+              COMPLEXITY_LABELS = [
+                { range: (0.0..0.2),  label: :trivial      },
+                { range: (0.2..0.4),  label: :simple       },
+                { range: (0.4..0.6),  label: :moderate     },
+                { range: (0.6..0.8),  label: :complex      },
+                { range: (0.8..1.0),  label: :overwhelming }
+              ].freeze
+
+              module_function
+
+              def quality_label_for(value)
+                entry = QUALITY_LABELS.find { |e| e[:range].cover?(value) }
+                entry ? entry[:label] : :depleted
+              end
+
+              def complexity_label_for(value)
+                entry = COMPLEXITY_LABELS.find { |e| e[:range].cover?(value) }
+                entry ? entry[:label] : :overwhelming
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/decision_fatigue/helpers/decision_record.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module DecisionFatigue
+          module Helpers
+            class DecisionRecord
+              attr_reader :id, :label, :decision_type, :complexity,
+                          :quality_at_time, :willpower_cost, :created_at
+
+              def initialize(id:, label:, decision_type:, complexity:, quality_at_time:, willpower_cost:)
+                @id              = id
+                @label           = label
+                @decision_type   = decision_type
+                @complexity      = complexity.clamp(0.0, 1.0)
+                @quality_at_time = quality_at_time.clamp(Constants::QUALITY_FLOOR, 1.0)
+                @willpower_cost  = willpower_cost
+                @created_at      = Time.now.utc
+              end
+
+              def complexity_label
+                Constants.complexity_label_for(@complexity)
+              end
+
+              def quality_label
+                Constants.quality_label_for(@quality_at_time)
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  label:            @label,
+                  decision_type:    @decision_type,
+                  complexity:       @complexity,
+                  complexity_label: complexity_label,
+                  quality_at_time:  @quality_at_time,
+                  quality_label:    quality_label,
+                  willpower_cost:   @willpower_cost,
+                  created_at:       @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/decision_fatigue/helpers/fatigue_engine.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module DecisionFatigue
+          module Helpers
+            class FatigueEngine
+              attr_reader :willpower, :total_decisions, :session_start
+
+              def initialize
+                @decisions       = []
+                @willpower       = Constants::DEFAULT_WILLPOWER
+                @total_decisions = 0
+                @session_start   = Time.now.utc
+                @next_id         = 1
+              end
+
+              def make_decision(label:, decision_type: :routine, complexity: 0.5)
+                complexity = complexity.clamp(0.0, 1.0)
+                cost       = complexity * Constants::DEPLETION_RATE
+                @willpower = [@willpower - cost, Constants::QUALITY_FLOOR].max
+
+                record = DecisionRecord.new(
+                  id:              @next_id,
+                  label:           label,
+                  decision_type:   decision_type,
+                  complexity:      complexity,
+                  quality_at_time: current_quality,
+                  willpower_cost:  cost
+                )
+
+                @next_id         += 1
+                @total_decisions += 1
+                @decisions << record
+                @decisions.shift while @decisions.size > Constants::MAX_DECISIONS
+
+                record
+              end
+
+              def current_quality
+                @willpower.clamp(Constants::QUALITY_FLOOR, 1.0)
+              end
+
+              def quality_label
+                Constants.quality_label_for(current_quality)
+              end
+
+              def rest!(amount: Constants::RECOVERY_RATE)
+                @willpower = [@willpower + amount, 1.0].min
+              end
+
+              def full_rest!
+                @willpower = Constants::DEFAULT_WILLPOWER
+              end
+
+              def decisions_since_rest
+                @decisions.size
+              end
+
+              def decision_rate
+                elapsed = [(Time.now.utc - @session_start) / 60.0, 1.0].max
+                @total_decisions / elapsed
+              end
+
+              def should_rest?
+                @willpower < 0.3
+              end
+
+              def recent_decisions(limit: 10)
+                @decisions.last(limit)
+              end
+
+              def decisions_by_type(decision_type:)
+                @decisions.select { |d| d.decision_type == decision_type }
+              end
+
+              def quality_trend(window: 10)
+                recent = @decisions.last(window)
+                return current_quality if recent.empty?
+
+                recent.sum(&:quality_at_time) / recent.size
+              end
+
+              def fatigue_report
+                {
+                  willpower:         @willpower.round(4),
+                  current_quality:   current_quality.round(4),
+                  quality_label:     quality_label,
+                  total_decisions:   @total_decisions,
+                  session_decisions: @decisions.size,
+                  decision_rate:     decision_rate.round(4),
+                  should_rest:       should_rest?,
+                  quality_trend:     quality_trend.round(4),
+                  session_start:     @session_start
+                }
+              end
+
+              def to_h
+                {
+                  willpower:       @willpower,
+                  total_decisions: @total_decisions,
+                  session_start:   @session_start,
+                  decisions:       @decisions.map(&:to_h)
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end