lex-agentic-executive 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d156eef0f39f669acfc3f33e496196921f1b34e882c810d1416740349fc4fb84
+  data.tar.gz: 97171fb40218dca7e06373731545b30e6eadc36a51c649b3e68e75d7e067e509
+SHA512:
+  metadata.gz: 97708ee5421c6401db3bd4899e1c0c6f62e059dfe6687d9524327e52b0b7c07ebcae937e8f5da1312467e082d8a56c5123064a0390b696cbbcb2de3b4adbbc72
+  data.tar.gz: 77360d4645be017e164d28feb1420890e990661091261a6dcc0bc15b84f169af3346a3e63af38e71162c079513357d780dffd7b073a43fd0015aa5dc79bc07ea

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-18
+
+### Added
+- Initial release as domain consolidation gem
+- Consolidated source extensions into unified domain gem under `Legion::Extensions::Agentic::<Domain>`
+- All sub-modules loaded from single entry point
+- Full spec suite with zero failures
+- RuboCop compliance across all files

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,13 @@
+# lex-agentic-executive
+
+LEX agentic executive domain: planning, working memory, cognitive control
+
+## Sub-modules
+
+*(populated as extensions are consolidated)*
+
+## Installation
+
+```ruby
+gem 'lex-agentic-executive'
+```

data/lex-agentic-executive.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/agentic/executive/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-agentic-executive'
+  spec.version       = Legion::Extensions::Agentic::Executive::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Agentic Executive'
+  spec.description   = 'LEX agentic executive domain: planning, working memory, cognitive control'
+  spec.homepage      = 'https://github.com/LegionIO/lex-agentic-executive'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob('{lib,spec}/**/*.rb') + %w[lex-agentic-executive.gemspec Gemfile LICENSE README.md CHANGELOG.md]
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'rspec', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.26'
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+          class Client
+            include Runners::CognitiveAutopilot
+
+            def initialize(engine: nil)
+              @default_engine = engine || Helpers::AutopilotEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/autopilot/helpers/autopilot_engine.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+          module Helpers
+            class AutopilotEngine
+              include Constants
+
+              attr_reader :current_mode, :energy
+
+              def initialize
+                @routines     = {}
+                @events       = {}
+                @current_mode = :deliberate
+                @energy       = DEFAULT_ENERGY
+              end
+
+              def register_routine(pattern:, domain: :routine, familiarity: 0.0)
+                prune_routines
+                routine = Routine.new(pattern: pattern, domain: domain, familiarity: familiarity)
+                @routines[routine.id] = routine
+                routine
+              end
+
+              def execute_routine(routine_id:, success: true)
+                routine = @routines[routine_id]
+                return nil unless routine
+
+                routine.execute!(success: success)
+                cost = routine.autopilot_ready? ? AUTOPILOT_COST : DELIBERATE_COST
+                drain_energy!(cost)
+                auto_switch_mode(routine)
+                routine
+              end
+
+              def switch_to_deliberate!(trigger: 'manual')
+                return nil if @current_mode == :deliberate
+
+                drain_energy!(OVERRIDE_COST)
+                record_event(from: @current_mode, to: :deliberate, trigger: trigger, cost: OVERRIDE_COST)
+                @current_mode = :deliberate
+                @current_mode
+              end
+
+              def switch_to_autopilot!(trigger: 'manual')
+                return nil if @current_mode == :autopilot
+
+                record_event(from: @current_mode, to: :autopilot, trigger: trigger, cost: 0.0)
+                @current_mode = :autopilot
+                @current_mode
+              end
+
+              def rest!(amount: 0.1)
+                @energy = (@energy + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def decay_all!
+                @routines.each_value(&:decay!)
+                { routines_decayed: @routines.size }
+              end
+
+              def autopilot_routines = @routines.values.select(&:autopilot_ready?)
+              def novel_routines = @routines.values.select(&:novel?)
+
+              def autopilot_ratio
+                return 0.0 if @routines.empty?
+
+                (autopilot_routines.size.to_f / @routines.size).round(10)
+              end
+
+              def override_count = @events.values.count(&:override?)
+
+              def most_familiar(limit: 5) = @routines.values.sort_by { |r| -r.familiarity }.first(limit)
+              def least_familiar(limit: 5) = @routines.values.sort_by(&:familiarity).first(limit)
+
+              def find_routine(routine_id:)
+                @routines[routine_id]
+              end
+
+              def energy_label = Constants.label_for(ENERGY_LABELS, @energy)
+              def mode_label = Constants.label_for(MODE_LABELS, autopilot_ratio)
+
+              def exhausted?
+                @energy <= 0.2
+              end
+
+              def autopilot_report
+                {
+                  current_mode:    @current_mode,
+                  energy:          @energy,
+                  energy_label:    energy_label,
+                  exhausted:       exhausted?,
+                  total_routines:  @routines.size,
+                  autopilot_ready: autopilot_routines.size,
+                  novel_count:     novel_routines.size,
+                  autopilot_ratio: autopilot_ratio,
+                  mode_label:      mode_label,
+                  total_events:    @events.size,
+                  override_count:  override_count,
+                  most_familiar:   most_familiar(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  current_mode:    @current_mode,
+                  energy:          @energy,
+                  total_routines:  @routines.size,
+                  autopilot_ratio: autopilot_ratio
+                }
+              end
+
+              private
+
+              def auto_switch_mode(routine)
+                if routine.autopilot_ready? && @current_mode == :deliberate
+                  record_event(from: :deliberate, to: :autopilot, trigger: "routine_familiar:#{routine.pattern}", cost: 0.0)
+                  @current_mode = :autopilot
+                elsif routine.novel? && @current_mode == :autopilot
+                  drain_energy!(OVERRIDE_COST)
+                  record_event(from: :autopilot, to: :deliberate, trigger: "routine_novel:#{routine.pattern}",
+                               cost: OVERRIDE_COST)
+                  @current_mode = :deliberate
+                end
+              end
+
+              def record_event(from:, to:, trigger:, cost:)
+                prune_events
+                event = ModeEvent.new(from_mode: from, to_mode: to, trigger: trigger, energy_cost: cost)
+                @events[event.id] = event
+                event
+              end
+
+              def drain_energy!(amount)
+                @energy = (@energy - amount).clamp(0.0, 1.0).round(10)
+              end
+
+              def prune_routines
+                return if @routines.size < MAX_ROUTINES
+
+                least = @routines.values.min_by(&:familiarity)
+                @routines.delete(least.id) if least
+              end
+
+              def prune_events
+                return if @events.size < MAX_EVENTS
+
+                oldest = @events.values.min_by(&:created_at)
+                @events.delete(oldest.id) if oldest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+          module Helpers
+            module Constants
+              MAX_ROUTINES      = 200
+              MAX_EVENTS        = 500
+              FAMILIARITY_BOOST = 0.08
+              FAMILIARITY_DECAY = 0.02
+              AUTOPILOT_THRESHOLD = 0.7
+              DELIBERATE_THRESHOLD = 0.3
+              OVERRIDE_COST     = 0.15
+              AUTOPILOT_COST    = 0.02
+              DELIBERATE_COST   = 0.10
+              DEFAULT_ENERGY    = 1.0
+
+              PROCESSING_MODES = %i[autopilot deliberate transitioning].freeze
+
+              TASK_DOMAINS = %i[
+                routine analysis creative social emergency
+                administrative technical unknown
+              ].freeze
+
+              FAMILIARITY_LABELS = {
+                (0.8..)     => :expert,
+                (0.6...0.8) => :proficient,
+                (0.4...0.6) => :familiar,
+                (0.2...0.4) => :learning,
+                (..0.2)     => :novel
+              }.freeze
+
+              MODE_LABELS = {
+                (0.8..)     => :deep_autopilot,
+                (0.6...0.8) => :light_autopilot,
+                (0.4...0.6) => :mixed,
+                (0.2...0.4) => :mostly_deliberate,
+                (..0.2)     => :full_deliberate
+              }.freeze
+
+              ENERGY_LABELS = {
+                (0.8..)     => :energized,
+                (0.6...0.8) => :steady,
+                (0.4...0.6) => :tiring,
+                (0.2...0.4) => :fatigued,
+                (..0.2)     => :exhausted
+              }.freeze
+
+              def self.label_for(labels, value)
+                match = labels.find { |range, _| range.cover?(value) }
+                match&.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/autopilot/helpers/mode_event.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+          module Helpers
+            class ModeEvent
+              include Constants
+
+              attr_reader :id, :from_mode, :to_mode, :trigger, :energy_cost, :created_at
+
+              def initialize(from_mode:, to_mode:, trigger:, energy_cost: 0.0)
+                @id          = SecureRandom.uuid
+                @from_mode   = from_mode.to_sym
+                @to_mode     = to_mode.to_sym
+                @trigger     = trigger.to_s
+                @energy_cost = energy_cost.to_f.clamp(0.0, 1.0).round(10)
+                @created_at  = Time.now.utc
+              end
+
+              def override?
+                @from_mode == :autopilot && @to_mode == :deliberate
+              end
+
+              def engage_autopilot?
+                @from_mode == :deliberate && @to_mode == :autopilot
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  from_mode:        @from_mode,
+                  to_mode:          @to_mode,
+                  trigger:          @trigger,
+                  energy_cost:      @energy_cost,
+                  override:         override?,
+                  engage_autopilot: engage_autopilot?,
+                  created_at:       @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/autopilot/helpers/routine.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+          module Helpers
+            class Routine
+              include Constants
+
+              attr_reader :id, :pattern, :domain, :familiarity, :execution_count,
+                          :success_count, :failure_count, :created_at, :last_executed_at
+
+              def initialize(pattern:, domain: :routine, familiarity: 0.0)
+                @id               = SecureRandom.uuid
+                @pattern          = pattern
+                @domain           = validate_domain(domain)
+                @familiarity      = familiarity.to_f.clamp(0.0, 1.0).round(10)
+                @execution_count  = 0
+                @success_count    = 0
+                @failure_count    = 0
+                @created_at       = Time.now.utc
+                @last_executed_at = nil
+              end
+
+              def execute!(success: true)
+                @execution_count += 1
+                @last_executed_at = Time.now.utc
+                if success
+                  @success_count += 1
+                  @familiarity = (@familiarity + FAMILIARITY_BOOST).clamp(0.0, 1.0).round(10)
+                else
+                  @failure_count += 1
+                  @familiarity = (@familiarity - FAMILIARITY_BOOST).clamp(0.0, 1.0).round(10)
+                end
+                self
+              end
+
+              def decay!
+                @familiarity = (@familiarity - FAMILIARITY_DECAY).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def autopilot_ready?
+                @familiarity >= AUTOPILOT_THRESHOLD
+              end
+
+              def novel?
+                @familiarity <= DELIBERATE_THRESHOLD
+              end
+
+              def success_rate
+                return 0.0 if @execution_count.zero?
+
+                (@success_count.to_f / @execution_count).round(10)
+              end
+
+              def familiarity_label = Constants.label_for(FAMILIARITY_LABELS, @familiarity)
+
+              def to_h
+                {
+                  id:                @id,
+                  pattern:           @pattern,
+                  domain:            @domain,
+                  familiarity:       @familiarity,
+                  familiarity_label: familiarity_label,
+                  autopilot_ready:   autopilot_ready?,
+                  novel:             novel?,
+                  execution_count:   @execution_count,
+                  success_rate:      success_rate,
+                  created_at:        @created_at,
+                  last_executed_at:  @last_executed_at
+                }
+              end
+
+              private
+
+              def validate_domain(domain)
+                sym = domain.to_sym
+                TASK_DOMAINS.include?(sym) ? sym : :unknown
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/autopilot/runners/cognitive_autopilot.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+          module Runners
+            module CognitiveAutopilot
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def register_routine(pattern:, domain: :routine, familiarity: 0.0, engine: nil, **)
+                eng = engine || default_engine
+                routine = eng.register_routine(pattern: pattern, domain: domain, familiarity: familiarity)
+                { success: true, routine: routine.to_h }
+              end
+
+              def execute_routine(routine_id:, success: true, engine: nil, **)
+                eng = engine || default_engine
+                routine = eng.execute_routine(routine_id: routine_id, success: success)
+                return { success: false, error: 'routine not found' } unless routine
+
+                { success: true, routine: routine.to_h, mode: eng.current_mode, energy: eng.energy }
+              end
+
+              def switch_to_deliberate(trigger: 'manual', engine: nil, **)
+                eng = engine || default_engine
+                result = eng.switch_to_deliberate!(trigger: trigger)
+                return { success: false, error: 'already in deliberate mode' } unless result
+
+                { success: true, mode: :deliberate, energy: eng.energy }
+              end
+
+              def switch_to_autopilot(trigger: 'manual', engine: nil, **)
+                eng = engine || default_engine
+                result = eng.switch_to_autopilot!(trigger: trigger)
+                return { success: false, error: 'already in autopilot mode' } unless result
+
+                { success: true, mode: :autopilot, energy: eng.energy }
+              end
+
+              def rest(amount: 0.1, engine: nil, **)
+                eng = engine || default_engine
+                eng.rest!(amount: amount)
+                { success: true, energy: eng.energy, energy_label: eng.energy_label }
+              end
+
+              def decay_all(engine: nil, **)
+                eng = engine || default_engine
+                result = eng.decay_all!
+                { success: true, **result }
+              end
+
+              def autopilot_routines(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, routines: eng.autopilot_routines.map(&:to_h), count: eng.autopilot_routines.size }
+              end
+
+              def novel_routines(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, routines: eng.novel_routines.map(&:to_h), count: eng.novel_routines.size }
+              end
+
+              def most_familiar(limit: 5, engine: nil, **)
+                eng = engine || default_engine
+                { success: true, routines: eng.most_familiar(limit: limit).map(&:to_h) }
+              end
+
+              def get_routine(routine_id:, engine: nil, **)
+                eng = engine || default_engine
+                routine = eng.find_routine(routine_id: routine_id)
+                return { success: false, error: 'routine not found' } unless routine
+
+                { success: true, routine: routine.to_h }
+              end
+
+              def autopilot_status(engine: nil, **)
+                eng = engine || default_engine
+                { success: true, **eng.autopilot_report }
+              end
+
+              private
+
+              def default_engine
+                @default_engine ||= Helpers::AutopilotEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'autopilot/version'
+require_relative 'autopilot/helpers/constants'
+require_relative 'autopilot/helpers/routine'
+require_relative 'autopilot/helpers/mode_event'
+require_relative 'autopilot/helpers/autopilot_engine'
+require_relative 'autopilot/runners/cognitive_autopilot'
+require_relative 'autopilot/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Autopilot
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/executive/chunking/runners/cognitive_chunking'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+          class Client
+            include Runners::CognitiveChunking
+
+            def initialize(**)
+              @chunking_engine = Helpers::ChunkingEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end