lex-cognitive-offloading 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f8942fc76e24c051b63e26f5ed53f408a22bf9c97cb442dd4c5808ccbf24d1ed
+  data.tar.gz: 0e3b27ef6d00e2cf9d41f13ad354c7b8c3973b78dd30f8c414b9171fe31c9a5a
+SHA512:
+  metadata.gz: 162c624136fbedff1e2f7f319c1b83399fca03a891bc6c4ecd7f28c16feeba70197e86836c1301fd6a996535e72d9c0e98bbfc8c8a3295277a5428371a3db430
+  data.tar.gz: 8a9a349b69e99aa01d9ce4b6f2d17595a76d8d88f15a8c93c8f272d49b81e127b88e5a6f94f0454224c93615c41563760812de716af4ce209cc5891a829bc543

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false
+gem 'rubocop-rspec', require: false
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/lex-cognitive-offloading.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_offloading/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-offloading'
+  spec.version       = Legion::Extensions::CognitiveOffloading::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Offloading'
+  spec.description   = 'Strategic externalization of cognitive tasks — offloading decisions, store trust, and retrieval tracking for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-offloading'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']        = spec.homepage
+  spec.metadata['source_code_uri']     = 'https://github.com/LegionIO/lex-cognitive-offloading'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-offloading'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-offloading'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-offloading/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-offloading.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_offloading/helpers/constants'
+require 'legion/extensions/cognitive_offloading/helpers/external_store'
+require 'legion/extensions/cognitive_offloading/helpers/offloaded_item'
+require 'legion/extensions/cognitive_offloading/helpers/offloading_engine'
+require 'legion/extensions/cognitive_offloading/runners/cognitive_offloading'
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      class Client
+        include Runners::CognitiveOffloading
+
+        def initialize(engine: nil, **)
+          @offloading_engine = engine || Helpers::OffloadingEngine.new
+        end
+
+        private
+
+        attr_reader :offloading_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      module Helpers
+        module Constants
+          MAX_ITEMS         = 500
+          MAX_STORES        = 50
+          DEFAULT_STORE_TRUST = 0.7
+          TRUST_DECAY       = 0.02
+          TRUST_BOOST       = 0.05
+
+          ITEM_TYPES = %i[
+            fact procedure plan context delegation reminder calculation reference
+          ].freeze
+
+          STORE_TYPES = %i[
+            database file agent tool memory_aid external_service notes
+          ].freeze
+
+          TRUST_LABELS = {
+            (0.8..)     => :highly_trusted,
+            (0.6...0.8) => :trusted,
+            (0.4...0.6) => :cautious,
+            (0.2...0.4) => :distrusted,
+            (..0.2)     => :unreliable
+          }.freeze
+
+          IMPORTANCE_LABELS = {
+            (0.8..)     => :critical,
+            (0.6...0.8) => :important,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :low,
+            (..0.2)     => :trivial
+          }.freeze
+
+          OFFLOAD_LABELS = {
+            (0.8..)     => :heavily_offloaded,
+            (0.6...0.8) => :mostly_offloaded,
+            (0.4...0.6) => :balanced,
+            (0.2...0.4) => :mostly_internal,
+            (..0.2)     => :self_reliant
+          }.freeze
+
+          RETRIEVAL_SUCCESS_THRESHOLD = 0.7
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_offloading/helpers/external_store.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'constants'
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      module Helpers
+        class ExternalStore
+          include Constants
+
+          attr_reader :id, :name, :store_type, :trust, :items_stored,
+                      :successful_retrievals, :failed_retrievals, :created_at
+
+          def initialize(name:, store_type:)
+            @id                   = ::SecureRandom.uuid
+            @name                 = name
+            @store_type           = store_type
+            @trust                = DEFAULT_STORE_TRUST
+            @items_stored         = 0
+            @successful_retrievals = 0
+            @failed_retrievals     = 0
+            @created_at = Time.now.utc
+          end
+
+          def increment_items!
+            @items_stored += 1
+            self
+          end
+
+          def record_success!
+            @successful_retrievals += 1
+            @trust = (@trust + TRUST_BOOST).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def record_failure!
+            @failed_retrievals += 1
+            @trust = (@trust - TRUST_DECAY).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def retrieval_rate
+            total = @successful_retrievals + @failed_retrievals
+            return 0.0 if total.zero?
+
+            (@successful_retrievals.to_f / total).round(10)
+          end
+
+          def reliable?
+            @trust >= RETRIEVAL_SUCCESS_THRESHOLD
+          end
+
+          def trust_label
+            TRUST_LABELS.find { |range, _| range.cover?(@trust) }&.last || :unreliable
+          end
+
+          def to_h
+            {
+              id:                    @id,
+              name:                  @name,
+              store_type:            @store_type,
+              trust:                 @trust.round(10),
+              trust_label:           trust_label,
+              items_stored:          @items_stored,
+              successful_retrievals: @successful_retrievals,
+              failed_retrievals:     @failed_retrievals,
+              retrieval_rate:        retrieval_rate,
+              reliable:              reliable?,
+              created_at:            @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_offloading/helpers/offloaded_item.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'constants'
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      module Helpers
+        class OffloadedItem
+          include Constants
+
+          attr_reader :id, :content, :item_type, :importance, :store_id,
+                      :offloaded_at, :retrieved_count, :last_retrieved_at
+
+          def initialize(content:, item_type:, importance:, store_id:)
+            @id               = ::SecureRandom.uuid
+            @content          = content
+            @item_type        = item_type
+            @importance       = importance.clamp(0.0, 1.0)
+            @store_id         = store_id
+            @offloaded_at     = Time.now.utc
+            @retrieved_count  = 0
+            @last_retrieved_at = nil
+          end
+
+          def retrieve!
+            @retrieved_count  += 1
+            @last_retrieved_at = Time.now.utc
+            self
+          end
+
+          def stale?(threshold_seconds: 3600)
+            return false if @last_retrieved_at.nil? && @retrieved_count.zero?
+
+            reference = @last_retrieved_at || @offloaded_at
+            (Time.now.utc - reference) > threshold_seconds
+          end
+
+          def importance_label
+            IMPORTANCE_LABELS.find { |range, _| range.cover?(@importance) }&.last || :trivial
+          end
+
+          def to_h
+            {
+              id:                @id,
+              content:           @content,
+              item_type:         @item_type,
+              importance:        @importance.round(10),
+              importance_label:  importance_label,
+              store_id:          @store_id,
+              offloaded_at:      @offloaded_at,
+              retrieved_count:   @retrieved_count,
+              last_retrieved_at: @last_retrieved_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_offloading/helpers/offloading_engine.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+require_relative 'external_store'
+require_relative 'offloaded_item'
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      module Helpers
+        class OffloadingEngine
+          include Constants
+
+          attr_reader :items, :stores
+
+          def initialize
+            @items  = {}
+            @stores = {}
+          end
+
+          def register_store(name:, store_type:)
+            return nil if @stores.size >= MAX_STORES
+
+            store = ExternalStore.new(name: name, store_type: store_type)
+            @stores[store.id] = store
+            store
+          end
+
+          def offload(content:, item_type:, importance:, store_id:)
+            return nil if @items.size >= MAX_ITEMS
+            return nil unless @stores.key?(store_id)
+
+            item = OffloadedItem.new(
+              content:    content,
+              item_type:  item_type,
+              importance: importance,
+              store_id:   store_id
+            )
+            @items[item.id] = item
+            @stores[store_id].increment_items!
+            item
+          end
+
+          def retrieve(item_id:)
+            item = @items[item_id]
+            return nil unless item
+
+            store = @stores[item.store_id]
+            store&.record_success!
+            item.retrieve!
+            item
+          end
+
+          def retrieve_failed(item_id:)
+            item = @items[item_id]
+            return nil unless item
+
+            store = @stores[item.store_id]
+            store&.record_failure!
+            item
+          end
+
+          def items_in_store(store_id:)
+            @items.values.select { |i| i.store_id == store_id }
+          end
+
+          def items_by_type(item_type:)
+            @items.values.select { |i| i.item_type == item_type }
+          end
+
+          def most_important_offloaded(limit: 10)
+            @items.values
+                  .sort_by { |i| -i.importance }
+                  .first(limit)
+          end
+
+          def offloading_ratio
+            return 0.0 if MAX_ITEMS.zero?
+
+            (@items.size.to_f / MAX_ITEMS).round(10)
+          end
+
+          def overall_store_trust
+            return 0.0 if @stores.empty?
+
+            total = @stores.values.sum(&:trust)
+            (total / @stores.size).round(10)
+          end
+
+          def most_trusted_store
+            @stores.values.max_by(&:trust)
+          end
+
+          def least_trusted_store
+            @stores.values.min_by(&:trust)
+          end
+
+          def offloading_report
+            {
+              total_items:         @items.size,
+              total_stores:        @stores.size,
+              offloading_ratio:    offloading_ratio,
+              offloading_label:    offloading_label,
+              overall_store_trust: overall_store_trust,
+              most_trusted_store:  most_trusted_store&.to_h,
+              least_trusted_store: least_trusted_store&.to_h,
+              items_by_type:       items_type_summary,
+              stores_summary:      @stores.values.map(&:to_h)
+            }
+          end
+
+          def to_h
+            {
+              items:  @items.transform_values(&:to_h),
+              stores: @stores.transform_values(&:to_h)
+            }
+          end
+
+          private
+
+          def offloading_label
+            OFFLOAD_LABELS.find { |range, _| range.cover?(offloading_ratio) }&.last || :self_reliant
+          end
+
+          def items_type_summary
+            ITEM_TYPES.to_h do |type|
+              [type, @items.values.count { |i| i.item_type == type }]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      module Runners
+        module CognitiveOffloading
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_store(name:, store_type:, engine: nil, **)
+            eng = engine || offloading_engine
+            store = eng.register_store(name: name, store_type: store_type)
+            if store
+              Legion::Logging.info "[cognitive_offloading] registered store name=#{name} type=#{store_type} id=#{store.id}"
+              { success: true, store: store.to_h }
+            else
+              Legion::Logging.warn '[cognitive_offloading] register_store failed: limit reached or invalid store_type'
+              { success: false, reason: :limit_reached }
+            end
+          end
+
+          def offload_item(content:, item_type:, importance:, store_id:, engine: nil, **)
+            eng = engine || offloading_engine
+            item = eng.offload(content: content, item_type: item_type, importance: importance, store_id: store_id)
+            if item
+              Legion::Logging.info "[cognitive_offloading] offloaded item=#{item.id} type=#{item_type} importance=#{importance.round(2)} store=#{store_id}"
+              { success: true, item: item.to_h }
+            else
+              Legion::Logging.warn "[cognitive_offloading] offload failed: limit reached or store not found store_id=#{store_id}"
+              { success: false, reason: :offload_failed }
+            end
+          end
+
+          def retrieve_item(item_id:, engine: nil, **)
+            eng = engine || offloading_engine
+            item = eng.retrieve(item_id: item_id)
+            if item
+              Legion::Logging.debug "[cognitive_offloading] retrieved item=#{item_id} count=#{item.retrieved_count}"
+              { success: true, item: item.to_h }
+            else
+              Legion::Logging.warn "[cognitive_offloading] retrieve failed: item not found item_id=#{item_id}"
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def report_retrieval_failure(item_id:, engine: nil, **)
+            eng = engine || offloading_engine
+            item = eng.retrieve_failed(item_id: item_id)
+            if item
+              store = eng.stores[item.store_id]
+              trust = store&.trust&.round(2)
+              Legion::Logging.warn "[cognitive_offloading] retrieval failure item=#{item_id} store_trust=#{trust}"
+              { success: true, item_id: item_id, store_trust: trust }
+            else
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def items_in_store(store_id:, engine: nil, **)
+            eng = engine || offloading_engine
+            items = eng.items_in_store(store_id: store_id)
+            Legion::Logging.debug "[cognitive_offloading] items_in_store store=#{store_id} count=#{items.size}"
+            { success: true, items: items.map(&:to_h), count: items.size }
+          end
+
+          def items_by_type(item_type:, engine: nil, **)
+            eng = engine || offloading_engine
+            items = eng.items_by_type(item_type: item_type)
+            Legion::Logging.debug "[cognitive_offloading] items_by_type type=#{item_type} count=#{items.size}"
+            { success: true, items: items.map(&:to_h), count: items.size }
+          end
+
+          def most_important_offloaded(limit: 10, engine: nil, **)
+            eng = engine || offloading_engine
+            items = eng.most_important_offloaded(limit: limit)
+            Legion::Logging.debug "[cognitive_offloading] most_important limit=#{limit} count=#{items.size}"
+            { success: true, items: items.map(&:to_h), count: items.size }
+          end
+
+          def offloading_status(engine: nil, **)
+            eng = engine || offloading_engine
+            report = eng.offloading_report
+            ratio = report[:offloading_ratio]
+            Legion::Logging.debug "[cognitive_offloading] status items=#{report[:total_items]} stores=#{report[:total_stores]} ratio=#{ratio}"
+            { success: true, report: report }
+          end
+
+          private
+
+          def offloading_engine
+            @offloading_engine ||= Helpers::OffloadingEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_offloading.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_offloading/version'
+require 'legion/extensions/cognitive_offloading/helpers/constants'
+require 'legion/extensions/cognitive_offloading/helpers/external_store'
+require 'legion/extensions/cognitive_offloading/helpers/offloaded_item'
+require 'legion/extensions/cognitive_offloading/helpers/offloading_engine'
+require 'legion/extensions/cognitive_offloading/runners/cognitive_offloading'
+
+module Legion
+  module Extensions
+    module CognitiveOffloading
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/cognitive_offloading/client_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_offloading/client'
+
+RSpec.describe Legion::Extensions::CognitiveOffloading::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:register_store)
+    expect(client).to respond_to(:offload_item)
+    expect(client).to respond_to(:retrieve_item)
+    expect(client).to respond_to(:report_retrieval_failure)
+    expect(client).to respond_to(:items_in_store)
+    expect(client).to respond_to(:items_by_type)
+    expect(client).to respond_to(:most_important_offloaded)
+    expect(client).to respond_to(:offloading_status)
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::CognitiveOffloading::Helpers::OffloadingEngine.new
+    c = described_class.new(engine: engine)
+    result = c.register_store(name: 'test', store_type: :file)
+    expect(result[:success]).to be true
+  end
+
+  it 'creates its own engine when none injected' do
+    result = client.register_store(name: 'auto', store_type: :notes)
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/cognitive_offloading/helpers/constants_spec.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveOffloading::Helpers::Constants do
+  subject(:constants) { described_class }
+
+  it 'defines MAX_ITEMS as 500' do
+    expect(constants::MAX_ITEMS).to eq(500)
+  end
+
+  it 'defines MAX_STORES as 50' do
+    expect(constants::MAX_STORES).to eq(50)
+  end
+
+  it 'defines DEFAULT_STORE_TRUST as 0.7' do
+    expect(constants::DEFAULT_STORE_TRUST).to eq(0.7)
+  end
+
+  it 'defines TRUST_DECAY as 0.02' do
+    expect(constants::TRUST_DECAY).to eq(0.02)
+  end
+
+  it 'defines TRUST_BOOST as 0.05' do
+    expect(constants::TRUST_BOOST).to eq(0.05)
+  end
+
+  it 'defines RETRIEVAL_SUCCESS_THRESHOLD as 0.7' do
+    expect(constants::RETRIEVAL_SUCCESS_THRESHOLD).to eq(0.7)
+  end
+
+  it 'defines ITEM_TYPES as frozen array of symbols' do
+    expect(constants::ITEM_TYPES).to include(:fact, :procedure, :plan, :context, :delegation,
+                                             :reminder, :calculation, :reference)
+    expect(constants::ITEM_TYPES).to be_frozen
+  end
+
+  it 'defines STORE_TYPES as frozen array of symbols' do
+    expect(constants::STORE_TYPES).to include(:database, :file, :agent, :tool, :memory_aid,
+                                              :external_service, :notes)
+    expect(constants::STORE_TYPES).to be_frozen
+  end
+
+  it 'maps high trust to :highly_trusted' do
+    label = constants::TRUST_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:highly_trusted)
+  end
+
+  it 'maps moderate trust to :trusted' do
+    label = constants::TRUST_LABELS.find { |range, _| range.cover?(0.7) }&.last
+    expect(label).to eq(:trusted)
+  end
+
+  it 'maps low trust to :unreliable' do
+    label = constants::TRUST_LABELS.find { |range, _| range.cover?(0.1) }&.last
+    expect(label).to eq(:unreliable)
+  end
+
+  it 'maps high importance to :critical' do
+    label = constants::IMPORTANCE_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:critical)
+  end
+
+  it 'maps high offloading ratio to :heavily_offloaded' do
+    label = constants::OFFLOAD_LABELS.find { |range, _| range.cover?(0.9) }&.last
+    expect(label).to eq(:heavily_offloaded)
+  end
+
+  it 'maps low offloading ratio to :self_reliant' do
+    label = constants::OFFLOAD_LABELS.find { |range, _| range.cover?(0.1) }&.last
+    expect(label).to eq(:self_reliant)
+  end
+end