lex-agentic-executive 0.1.0

data/lib/legion/extensions/agentic/executive/chunking/helpers/chunk.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+          module Helpers
+            class Chunk
+              include Constants
+
+              attr_reader :id, :label, :item_ids, :sub_chunk_ids, :coherence, :recall_strength,
+                          :access_count, :created_at
+
+              def initialize(label:, item_ids: [])
+                @id             = ::SecureRandom.uuid
+                @label          = label
+                @item_ids       = item_ids.dup
+                @sub_chunk_ids  = []
+                @coherence      = DEFAULT_COHERENCE
+                @recall_strength = 0.8
+                @access_count   = 0
+                @created_at     = Time.now.utc
+              end
+
+              def add_item!(item_id:)
+                @item_ids << item_id unless @item_ids.include?(item_id)
+              end
+
+              def remove_item!(item_id:)
+                @item_ids.delete(item_id)
+              end
+
+              def add_sub_chunk!(chunk_id:)
+                @sub_chunk_ids << chunk_id unless @sub_chunk_ids.include?(chunk_id)
+              end
+
+              def reinforce!
+                @access_count   += 1
+                @coherence       = [(@coherence + COHERENCE_BOOST).round(10), 1.0].min
+                @recall_strength = [(@recall_strength + RECALL_BOOST).round(10), 1.0].min
+              end
+
+              def decay!
+                @recall_strength = [(@recall_strength - RECALL_DECAY).round(10), 0.0].max
+                @coherence       = [(@coherence - COHERENCE_DECAY).round(10), 0.0].max
+              end
+
+              def size
+                @item_ids.size
+              end
+
+              def hierarchical?
+                !@sub_chunk_ids.empty?
+              end
+
+              def coherence_label
+                COHERENCE_LABELS.find { |range, _| range.cover?(@coherence) }&.last || :unchunked
+              end
+
+              def recall_label
+                RECALL_LABELS.find { |range, _| range.cover?(@recall_strength) }&.last || :forgotten
+              end
+
+              def size_label
+                CHUNK_SIZE_LABELS.find { |range, _| range.cover?(size) }&.last || :micro
+              end
+
+              def to_h
+                {
+                  id:              @id,
+                  label:           @label,
+                  item_ids:        @item_ids.dup,
+                  sub_chunk_ids:   @sub_chunk_ids.dup,
+                  coherence:       @coherence.round(10),
+                  recall_strength: @recall_strength.round(10),
+                  access_count:    @access_count,
+                  created_at:      @created_at,
+                  size:            size,
+                  hierarchical:    hierarchical?,
+                  coherence_label: coherence_label,
+                  recall_label:    recall_label,
+                  size_label:      size_label
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/chunking/helpers/chunking_engine.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+          module Helpers
+            class ChunkingEngine
+              include Constants
+
+              attr_reader :items, :chunks, :working_memory
+
+              def initialize
+                @items          = {}
+                @chunks         = {}
+                @working_memory = []
+              end
+
+              def add_item(content:, domain: :general)
+                return { success: false, error: :capacity_exceeded } if @items.size >= MAX_ITEMS
+
+                item = InformationItem.new(content: content, domain: domain)
+                @items[item.id] = item
+                { success: true, item_id: item.id, item: item.to_h }
+              end
+
+              def create_chunk(label:, item_ids:)
+                return { success: false, error: :capacity_exceeded } if @chunks.size >= MAX_CHUNKS
+                return { success: false, error: :empty_item_ids } if item_ids.empty?
+
+                valid_ids = item_ids.select { |id| @items.key?(id) }
+                return { success: false, error: :no_valid_items } if valid_ids.empty?
+
+                chunk = Chunk.new(label: label, item_ids: valid_ids)
+                @chunks[chunk.id] = chunk
+                valid_ids.each { |id| @items[id]&.assign_to_chunk!(chunk_id: chunk.id) }
+
+                { success: true, chunk_id: chunk.id, chunk: chunk.to_h }
+              end
+
+              def merge_chunks(chunk_ids:, label:)
+                return { success: false, error: :capacity_exceeded } if @chunks.size >= MAX_CHUNKS
+                return { success: false, error: :insufficient_chunks } if chunk_ids.size < 2
+
+                valid_chunk_ids = chunk_ids.select { |id| @chunks.key?(id) }
+                return { success: false, error: :no_valid_chunks } if valid_chunk_ids.size < 2
+
+                merged_item_ids = valid_chunk_ids.flat_map { |id| @chunks[id].item_ids }.uniq
+                parent = Chunk.new(label: label, item_ids: merged_item_ids)
+                valid_chunk_ids.each { |id| parent.add_sub_chunk!(chunk_id: id) }
+                @chunks[parent.id] = parent
+
+                { success: true, chunk_id: parent.id, chunk: parent.to_h, merged_from: valid_chunk_ids }
+              end
+
+              def load_to_working_memory(chunk_id:)
+                return { success: false, error: :chunk_not_found } unless @chunks.key?(chunk_id)
+                return { success: false, error: :already_loaded } if @working_memory.include?(chunk_id)
+                return { success: false, error: :capacity_exceeded } if @working_memory.size >= WORKING_MEMORY_CAPACITY
+
+                @working_memory << chunk_id
+                @chunks[chunk_id].reinforce!
+                { success: true, chunk_id: chunk_id, working_memory_size: @working_memory.size }
+              end
+
+              def unload_from_working_memory(chunk_id:)
+                return { success: false, error: :not_in_working_memory } unless @working_memory.include?(chunk_id)
+
+                @working_memory.delete(chunk_id)
+                { success: true, chunk_id: chunk_id, working_memory_size: @working_memory.size }
+              end
+
+              def working_memory_load
+                return 0.0 if WORKING_MEMORY_CAPACITY.zero?
+
+                (@working_memory.size.to_f / WORKING_MEMORY_CAPACITY).round(10)
+              end
+
+              def working_memory_overloaded?
+                @working_memory.size > WORKING_MEMORY_CAPACITY
+              end
+
+              def decay_all!
+                @chunks.each_value(&:decay!)
+                { success: true, chunks_decayed: @chunks.size }
+              end
+
+              def reinforce_chunk(chunk_id:)
+                return { success: false, error: :chunk_not_found } unless @chunks.key?(chunk_id)
+
+                @chunks[chunk_id].reinforce!
+                { success: true, chunk_id: chunk_id, chunk: @chunks[chunk_id].to_h }
+              end
+
+              def strongest_chunks(limit: 10)
+                @chunks.values
+                       .sort_by { |c| -c.recall_strength }
+                       .first(limit)
+                       .map(&:to_h)
+              end
+
+              def unchunked_items
+                @items.values.reject(&:chunked?).map(&:to_h)
+              end
+
+              def chunking_efficiency
+                return 0.0 if @items.empty?
+
+                chunked_count = @items.values.count(&:chunked?)
+                (chunked_count.to_f / @items.size).round(10)
+              end
+
+              def chunking_report
+                wm_load = working_memory_load
+                capacity_label = CAPACITY_LABELS.find { |range, _| range.cover?(wm_load) }&.last || :empty
+
+                {
+                  total_items:         @items.size,
+                  total_chunks:        @chunks.size,
+                  unchunked_items:     unchunked_items.size,
+                  chunking_efficiency: chunking_efficiency,
+                  working_memory:      {
+                    current:   @working_memory.size,
+                    capacity:  WORKING_MEMORY_CAPACITY,
+                    load:      wm_load,
+                    label:     capacity_label,
+                    chunk_ids: @working_memory.dup
+                  },
+                  strongest_chunks:    strongest_chunks(limit: 5)
+                }
+              end
+
+              def to_h
+                {
+                  items:          @items.transform_values(&:to_h),
+                  chunks:         @chunks.transform_values(&:to_h),
+                  working_memory: @working_memory.dup
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+          module Helpers
+            module Constants
+              MAX_ITEMS               = 500
+              MAX_CHUNKS              = 200
+              WORKING_MEMORY_CAPACITY = 7    # Miller's magic number
+              CAPACITY_VARIANCE       = 2    # +/- 2
+              DEFAULT_COHERENCE       = 0.5
+              COHERENCE_BOOST         = 0.08
+              COHERENCE_DECAY         = 0.03
+              RECALL_DECAY            = 0.02
+              RECALL_BOOST            = 0.1
+
+              CHUNK_SIZE_LABELS = {
+                (7..)   => :large,
+                (5...7) => :medium,
+                (3...5) => :small,
+                (..3)   => :micro
+              }.freeze
+
+              COHERENCE_LABELS = {
+                (0.8..)     => :tightly_chunked,
+                (0.6...0.8) => :well_chunked,
+                (0.4...0.6) => :loosely_chunked,
+                (0.2...0.4) => :weakly_chunked,
+                (..0.2)     => :unchunked
+              }.freeze
+
+              RECALL_LABELS = {
+                (0.8..)     => :instant,
+                (0.6...0.8) => :easy,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :difficult,
+                (..0.2)     => :forgotten
+              }.freeze
+
+              CAPACITY_LABELS = {
+                (0.8..)     => :overloaded,
+                (0.6...0.8) => :near_capacity,
+                (0.4...0.6) => :comfortable,
+                (0.2...0.4) => :spacious,
+                (..0.2)     => :empty
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/chunking/helpers/information_item.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+          module Helpers
+            class InformationItem
+              attr_reader :id, :content, :domain, :chunk_id, :created_at
+
+              def initialize(content:, domain: :general)
+                @id         = ::SecureRandom.uuid
+                @content    = content
+                @domain     = domain
+                @chunked    = false
+                @chunk_id   = nil
+                @created_at = Time.now.utc
+              end
+
+              def chunked?
+                @chunked
+              end
+
+              def assign_to_chunk!(chunk_id:)
+                @chunked  = true
+                @chunk_id = chunk_id
+              end
+
+              def unchunk!
+                @chunked  = false
+                @chunk_id = nil
+              end
+
+              def to_h
+                {
+                  id:         @id,
+                  content:    @content,
+                  domain:     @domain,
+                  chunked:    @chunked,
+                  chunk_id:   @chunk_id,
+                  created_at: @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/chunking/runners/cognitive_chunking.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+          module Runners
+            module CognitiveChunking
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def add_item(content:, domain: :general, engine: nil, **)
+                eng = engine || chunking_engine
+                result = eng.add_item(content: content, domain: domain)
+                Legion::Logging.debug "[cognitive_chunking] add_item: domain=#{domain} success=#{result[:success]}"
+                result
+              end
+
+              def create_chunk(label:, item_ids:, engine: nil, **)
+                eng = engine || chunking_engine
+                result = eng.create_chunk(label: label, item_ids: item_ids)
+                Legion::Logging.debug "[cognitive_chunking] create_chunk: label=#{label} items=#{item_ids.size} success=#{result[:success]}"
+                result
+              end
+
+              def merge_chunks(chunk_ids:, label:, engine: nil, **)
+                eng = engine || chunking_engine
+                result = eng.merge_chunks(chunk_ids: chunk_ids, label: label)
+                Legion::Logging.debug "[cognitive_chunking] merge_chunks: label=#{label} sources=#{chunk_ids.size} success=#{result[:success]}"
+                result
+              end
+
+              def load_to_working_memory(chunk_id:, engine: nil, **)
+                eng = engine || chunking_engine
+                result = eng.load_to_working_memory(chunk_id: chunk_id)
+                Legion::Logging.debug "[cognitive_chunking] load_wm: chunk_id=#{chunk_id} wm_size=#{result[:working_memory_size]} success=#{result[:success]}"
+                result
+              end
+
+              def unload_from_working_memory(chunk_id:, engine: nil, **)
+                eng = engine || chunking_engine
+                result = eng.unload_from_working_memory(chunk_id: chunk_id)
+                Legion::Logging.debug "[cognitive_chunking] unload_wm: chunk_id=#{chunk_id} success=#{result[:success]}"
+                result
+              end
+
+              def working_memory_status(engine: nil, **)
+                eng    = engine || chunking_engine
+                load   = eng.working_memory_load
+                label  = Helpers::Constants::CAPACITY_LABELS.find { |range, _| range.cover?(load) }&.last || :empty
+
+                Legion::Logging.debug "[cognitive_chunking] wm_status: load=#{load.round(2)} label=#{label}"
+                {
+                  success:    true,
+                  size:       eng.working_memory.size,
+                  capacity:   Helpers::Constants::WORKING_MEMORY_CAPACITY,
+                  load:       load,
+                  label:      label,
+                  overloaded: eng.working_memory_overloaded?
+                }
+              end
+
+              def decay_all(engine: nil, **)
+                eng    = engine || chunking_engine
+                result = eng.decay_all!
+                Legion::Logging.debug "[cognitive_chunking] decay_all: chunks_decayed=#{result[:chunks_decayed]}"
+                result
+              end
+
+              def reinforce_chunk(chunk_id:, engine: nil, **)
+                eng    = engine || chunking_engine
+                result = eng.reinforce_chunk(chunk_id: chunk_id)
+                Legion::Logging.debug "[cognitive_chunking] reinforce_chunk: chunk_id=#{chunk_id} success=#{result[:success]}"
+                result
+              end
+
+              def chunking_report(engine: nil, **)
+                eng    = engine || chunking_engine
+                report = eng.chunking_report
+                eff = report[:chunking_efficiency].round(2)
+                Legion::Logging.debug "[cognitive_chunking] report: items=#{report[:total_items]} chunks=#{report[:total_chunks]} efficiency=#{eff}"
+                { success: true, report: report }
+              end
+
+              def strongest_chunks(limit: 10, engine: nil, **)
+                eng    = engine || chunking_engine
+                chunks = eng.strongest_chunks(limit: limit)
+                Legion::Logging.debug "[cognitive_chunking] strongest_chunks: count=#{chunks.size}"
+                { success: true, chunks: chunks }
+              end
+
+              def unchunked_items(engine: nil, **)
+                eng   = engine || chunking_engine
+                items = eng.unchunked_items
+                Legion::Logging.debug "[cognitive_chunking] unchunked_items: count=#{items.size}"
+                { success: true, items: items }
+              end
+
+              private
+
+              def chunking_engine
+                @chunking_engine ||= Helpers::ChunkingEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/agentic/executive/chunking/version'
+require 'legion/extensions/agentic/executive/chunking/helpers/constants'
+require 'legion/extensions/agentic/executive/chunking/helpers/information_item'
+require 'legion/extensions/agentic/executive/chunking/helpers/chunk'
+require 'legion/extensions/agentic/executive/chunking/helpers/chunking_engine'
+require 'legion/extensions/agentic/executive/chunking/runners/cognitive_chunking'
+require 'legion/extensions/agentic/executive/chunking/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module Chunking
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/executive/cognitive_debt/helpers/constants'
+require 'legion/extensions/agentic/executive/cognitive_debt/helpers/debt_item'
+require 'legion/extensions/agentic/executive/cognitive_debt/helpers/debt_engine'
+require 'legion/extensions/agentic/executive/cognitive_debt/runners/cognitive_debt'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module CognitiveDebt
+          class Client
+            include Runners::CognitiveDebt
+
+            def initialize(engine: nil, **)
+              @default_engine = engine || Helpers::DebtEngine.new
+            end
+
+            private
+
+            attr_reader :default_engine
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module CognitiveDebt
+          module Helpers
+            module Constants
+              MAX_DEBTS      = 300
+              INTEREST_RATE  = 0.05
+              DEFAULT_PRINCIPAL = 0.3
+              REPAYMENT_RATE = 0.1
+
+              SEVERITY_LABELS = {
+                (0.0...0.2)            => :negligible,
+                (0.2...0.4)            => :minor,
+                (0.4...0.6)            => :moderate,
+                (0.6...0.8)            => :severe,
+                (0.8..Float::INFINITY) => :critical
+              }.freeze
+
+              DEBT_TYPES = %i[
+                deferred_decision
+                unprocessed_input
+                incomplete_analysis
+                pending_integration
+                unresolved_conflict
+              ].freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/executive/cognitive_debt/helpers/debt_engine.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Executive
+        module CognitiveDebt
+          module Helpers
+            class DebtEngine
+              def initialize
+                @debts = {}
+              end
+
+              def create_debt(label:, debt_type:, principal: Constants::DEFAULT_PRINCIPAL, domain: 'general')
+                return { created: false, reason: :debt_type_invalid } unless Constants::DEBT_TYPES.include?(debt_type.to_sym)
+                return { created: false, reason: :limit_reached } if @debts.size >= Constants::MAX_DEBTS
+
+                item = DebtItem.new(
+                  label:     label,
+                  debt_type: debt_type,
+                  principal: principal,
+                  domain:    domain
+                )
+                @debts[item.id] = item
+                { created: true, debt_id: item.id, debt: item.to_h }
+              end
+
+              def repay_debt(debt_id:, amount: Constants::REPAYMENT_RATE)
+                item = @debts[debt_id]
+                return { found: false } unless item
+                return { found: true, repaid: false, reason: :already_repaid } if item.repaid?
+
+                item.repay!(amount: amount)
+                { found: true, repaid: true, debt_id: debt_id, debt: item.to_h }
+              end
+
+              def accrue_all_interest
+                count = 0
+                @debts.each_value do |item|
+                  next if item.repaid?
+
+                  item.accrue!
+                  count += 1
+                end
+                { accrued: count, total_debt: total_debt }
+              end
+
+              def total_debt
+                @debts.values.reject(&:repaid?).sum(&:total_cost).round(10)
+              end
+
+              def debt_by_type(debt_type:)
+                type = debt_type.to_sym
+                items = @debts.values.select { |d| d.debt_type == type && !d.repaid? }
+                { debt_type: type, count: items.size, items: items.map(&:to_h) }
+              end
+
+              def debt_by_domain(domain:)
+                items = @debts.values.select { |d| d.domain == domain && !d.repaid? }
+                { domain: domain, count: items.size, items: items.map(&:to_h) }
+              end
+
+              def most_costly(limit: 10)
+                items = @debts.values
+                              .reject(&:repaid?)
+                              .sort_by { |d| -d.total_cost }
+                              .first(limit)
+                { count: items.size, items: items.map(&:to_h) }
+              end
+
+              def oldest_debts(limit: 10)
+                items = @debts.values
+                              .reject(&:repaid?)
+                              .sort_by(&:created_at)
+                              .first(limit)
+                { count: items.size, items: items.map(&:to_h) }
+              end
+
+              def debt_report
+                active = @debts.values.reject(&:repaid?)
+                by_type = Constants::DEBT_TYPES.to_h do |type|
+                  typed = active.select { |d| d.debt_type == type }
+                  [type, { count: typed.size, total_cost: typed.sum(&:total_cost).round(10) }]
+                end
+
+                priority = active.sort_by { |d| -d.total_cost }.first(5)
+
+                {
+                  total_debt:           total_debt,
+                  active_count:         active.size,
+                  repaid_count:         @debts.values.count(&:repaid?),
+                  by_type:              by_type,
+                  recommended_priority: priority.map(&:to_h)
+                }
+              end
+
+              def prune_repaid
+                before = @debts.size
+                @debts.delete_if { |_id, item| item.repaid? }
+                pruned = before - @debts.size
+                { pruned: pruned, remaining: @debts.size }
+              end
+
+              def to_h
+                {
+                  total_debt:   total_debt,
+                  active_count: @debts.values.reject(&:repaid?).size,
+                  total_count:  @debts.size,
+                  debts:        @debts.values.map(&:to_h)
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end