lex-dual-process 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d2f51b67089c8d64b94d67427a3f892d7a65924e24e12203092c3fdcddda73cd
+  data.tar.gz: e742fa6726c11c5fad560a709daad2ec95fb3c0435d49450df99c69f9828e8f8
+SHA512:
+  metadata.gz: 54df463d20f44b00ed14c43901db6cd50012049b4ae934fadfc299e231156264c21ca10916c8b184ec064ab7a3f2ef96e6a6f3ab4db82f1640b2a75db3e7c9e7
+  data.tar.gz: 960ade33ca509551591ea7dfe577b4d4afe1a35374ae18fbccaf1a98952f6e75d16d49b4c729532c742d1bbdd40967b1b1504eef9e04ede9fedb41a49b96374d

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec', '~> 3.13'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'simplecov'
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

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,67 @@
+# lex-dual-process
+
+Dual-process cognition modeling for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Implements Kahneman's System 1 / System 2 theory. Routes decisions to fast heuristic reasoning (System 1) or slow deliberative reasoning (System 2) based on query complexity, confidence threshold, and available effort budget. Maintains a library of learned heuristics that improve through reinforcement. Models cognitive fatigue via a depletable effort budget that recovers over time.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::DualProcess::Client.new
+
+# Register a heuristic pattern
+client.register_heuristic(
+  pattern: 'familiar HTTP request',
+  domain: :networking,
+  confidence: 0.8
+)
+
+# Route a decision — automatically selects System 1 or System 2
+client.route_decision(query: 'handle incoming request', domain: :networking, complexity: 0.3)
+# => { success: true, system: :system_one, confidence: 0.8, complexity: 0.3,
+#      heuristic_used: "...", effort_remaining: 1.0 }
+
+# High-complexity query forces System 2
+client.route_decision(query: 'design new architecture', domain: :planning, complexity: 0.9)
+# => { success: true, system: :system_two, confidence: 0.7, effort_cost: 0.1, ... }
+
+# Record outcome to reinforce the heuristic
+client.record_decision_outcome(decision_id: '...', success: true)
+
+# Check effort budget
+client.effort_assessment
+# => { effort_budget: 0.8, effort_label: :fluent, system_bias: :system_one }
+
+# Best heuristics in a domain
+client.best_heuristics(domain: :networking, limit: 5)
+
+# Periodic tick: recover effort budget
+client.update_dual_process
+# => { success: true, effort_recovered: 0.05, effort_budget: 0.85 }
+```
+
+## Routing Labels
+
+| Effort Budget | Label |
+|---|---|
+| 0.8 – 1.0 | `:automatic` |
+| 0.6 – 0.8 | `:fluent` |
+| 0.4 – 0.6 | `:effortful` |
+| 0.2 – 0.4 | `:strained` |
+| 0.0 – 0.2 | `:depleted` |
+
+When effort is depleted, all decisions route to System 1 regardless of complexity.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-dual-process.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/dual_process/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-dual-process'
+  spec.version       = Legion::Extensions::DualProcess::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Dual Process'
+  spec.description   = "Kahneman's Dual Process Theory for brain-modeled agentic AI: System 1 (fast/intuitive) vs System 2 (slow/deliberate)"
+  spec.homepage      = 'https://github.com/LegionIO/lex-dual-process'
+  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-dual-process'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-dual-process'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-dual-process'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-dual-process/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-dual-process.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/dual_process/helpers/constants'
+require 'legion/extensions/dual_process/helpers/heuristic'
+require 'legion/extensions/dual_process/helpers/decision'
+require 'legion/extensions/dual_process/helpers/dual_process_engine'
+require 'legion/extensions/dual_process/runners/dual_process'
+
+module Legion
+  module Extensions
+    module DualProcess
+      class Client
+        include Runners::DualProcess
+
+        def initialize(engine: nil)
+          @engine = engine || Helpers::DualProcessEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DualProcess
+      module Helpers
+        module Constants
+          MAX_DECISIONS  = 200
+          MAX_HEURISTICS = 100
+          MAX_HISTORY    = 300
+
+          DEFAULT_CONFIDENCE   = 0.5
+          CONFIDENCE_FLOOR     = 0.05
+          CONFIDENCE_CEILING   = 0.95
+          SYSTEM_ONE_THRESHOLD = 0.6
+          COMPLEXITY_THRESHOLD = 0.5
+
+          EFFORT_COST          = 0.1
+          EFFORT_RECOVERY_RATE = 0.05
+          MAX_EFFORT_BUDGET    = 1.0
+          FATIGUE_PENALTY      = 0.15
+          HEURISTIC_BOOST      = 0.2
+          DECAY_RATE           = 0.01
+
+          SYSTEMS = %i[system_one system_two].freeze
+
+          ROUTING_LABELS = {
+            (0.8..)     => :automatic,
+            (0.6...0.8) => :fluent,
+            (0.4...0.6) => :effortful,
+            (0.2...0.4) => :strained,
+            (..0.2)     => :depleted
+          }.freeze
+
+          DECISION_OUTCOMES = %i[correct incorrect uncertain].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/dual_process/helpers/decision.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module DualProcess
+      module Helpers
+        class Decision
+          attr_accessor :outcome
+          attr_reader :id, :query, :domain, :system_used, :confidence, :complexity, :heuristic_id, :effort_cost, :processing_time_ms, :created_at
+
+          def initialize(query:, domain:, system_used:, confidence:, complexity:, **opts)
+            @id                 = SecureRandom.uuid
+            @query              = query
+            @domain             = domain
+            @system_used        = system_used
+            @confidence         = confidence.clamp(Constants::CONFIDENCE_FLOOR, Constants::CONFIDENCE_CEILING)
+            @complexity         = complexity.clamp(0.0, 1.0)
+            @heuristic_id       = opts.fetch(:heuristic_id, nil)
+            @outcome            = nil
+            @effort_cost        = opts.fetch(:effort_cost, 0.0)
+            @processing_time_ms = opts.fetch(:processing_time_ms, 0)
+            @created_at         = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              query:              @query,
+              domain:             @domain,
+              system_used:        @system_used,
+              confidence:         @confidence,
+              complexity:         @complexity,
+              heuristic_id:       @heuristic_id,
+              outcome:            @outcome,
+              effort_cost:        @effort_cost,
+              processing_time_ms: @processing_time_ms,
+              created_at:         @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/dual_process/helpers/dual_process_engine.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DualProcess
+      module Helpers
+        class DualProcessEngine
+          include Constants
+
+          def initialize
+            @effort_budget = MAX_EFFORT_BUDGET
+            @heuristics    = {}
+            @decisions     = []
+          end
+
+          def register_heuristic(pattern:, domain:, response:, confidence: DEFAULT_CONFIDENCE)
+            heuristic = Heuristic.new(pattern: pattern, domain: domain, response: response, confidence: confidence)
+            if @heuristics.size >= MAX_HEURISTICS
+              oldest_key = @heuristics.min_by { |_, h| h.last_used_at || h.created_at }.first
+              @heuristics.delete(oldest_key)
+            end
+            @heuristics[heuristic.id] = heuristic
+            heuristic
+          end
+
+          def route_decision(query:, domain:, complexity:)
+            matching = find_matching_heuristic(query, domain)
+            use_system_one = complexity < COMPLEXITY_THRESHOLD &&
+                             matching &&
+                             matching.confidence >= SYSTEM_ONE_THRESHOLD
+
+            if use_system_one
+              { system: :system_one, reason: :heuristic_match, heuristic_id: matching.id }
+            elsif @effort_budget >= EFFORT_COST
+              { system: :system_two, reason: complexity_reason(complexity, matching) }
+            else
+              { system: :system_one, reason: :effort_depleted, fatigue: true }
+            end
+          end
+
+          def execute_system_one(query:, domain:)
+            matching = find_matching_heuristic(query, domain)
+            start    = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+            if matching
+              matching.use!(success: true)
+              confidence = matching.confidence
+              response   = matching.response
+            else
+              confidence = (DEFAULT_CONFIDENCE - FATIGUE_PENALTY).clamp(CONFIDENCE_FLOOR, CONFIDENCE_CEILING)
+              response   = :no_heuristic
+            end
+
+            elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+
+            decision = Decision.new(
+              query:              query,
+              domain:             domain,
+              system_used:        :system_one,
+              confidence:         confidence,
+              complexity:         0.0,
+              heuristic_id:       matching&.id,
+              effort_cost:        0.0,
+              processing_time_ms: elapsed
+            )
+            store_decision(decision)
+            { decision_id: decision.id, system: :system_one, response: response, confidence: confidence }
+          end
+
+          def execute_system_two(query:, domain:, deliberation: {})
+            start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            @effort_budget = (@effort_budget - EFFORT_COST).clamp(0.0, MAX_EFFORT_BUDGET)
+
+            confidence = deliberation.fetch(:confidence, DEFAULT_CONFIDENCE + HEURISTIC_BOOST)
+                                     .clamp(CONFIDENCE_FLOOR, CONFIDENCE_CEILING)
+            response   = deliberation.fetch(:response, :deliberated)
+            elapsed    = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+
+            decision = Decision.new(
+              query:              query,
+              domain:             domain,
+              system_used:        :system_two,
+              confidence:         confidence,
+              complexity:         deliberation.fetch(:complexity, COMPLEXITY_THRESHOLD),
+              effort_cost:        EFFORT_COST,
+              processing_time_ms: elapsed
+            )
+            store_decision(decision)
+            { decision_id: decision.id, system: :system_two, response: response, confidence: confidence }
+          end
+
+          def record_outcome(decision_id:, outcome:)
+            decision = @decisions.find { |d| d.id == decision_id }
+            return { success: false, reason: :not_found } unless decision
+
+            decision.outcome = outcome
+
+            if decision.heuristic_id
+              heuristic = @heuristics[decision.heuristic_id]
+              heuristic&.use!(success: outcome == :correct)
+            end
+
+            { success: true, decision_id: decision_id, outcome: outcome }
+          end
+
+          def effort_level
+            @effort_budget / MAX_EFFORT_BUDGET
+          end
+
+          def routing_label
+            ROUTING_LABELS.find { |range, _| range.cover?(effort_level) }&.last || :unknown
+          end
+
+          def recover_effort
+            @effort_budget = (@effort_budget + EFFORT_RECOVERY_RATE).clamp(0.0, MAX_EFFORT_BUDGET)
+          end
+
+          def decay_heuristics
+            @heuristics.each_value do |h|
+              next unless h.use_count.positive?
+
+              delta = -DECAY_RATE
+              h.instance_variable_set(:@confidence, (h.confidence + delta).clamp(CONFIDENCE_FLOOR, CONFIDENCE_CEILING))
+            end
+          end
+
+          def system_stats
+            s1 = @decisions.count { |d| d.system_used == :system_one }
+            s2 = @decisions.count { |d| d.system_used == :system_two }
+            total = @decisions.size
+
+            {
+              system_one: s1,
+              system_two: s2,
+              total:      total,
+              s1_ratio:   total.zero? ? 0.0 : (s1.to_f / total).round(3),
+              s2_ratio:   total.zero? ? 0.0 : (s2.to_f / total).round(3)
+            }
+          end
+
+          def best_heuristics(limit: 5)
+            @heuristics.values
+                       .select(&:reliable?)
+                       .sort_by { |h| [-h.success_rate, -h.use_count] }
+                       .first(limit)
+                       .map(&:to_h)
+          end
+
+          def to_h
+            {
+              effort_budget:   @effort_budget,
+              effort_level:    effort_level,
+              routing_label:   routing_label,
+              heuristic_count: @heuristics.size,
+              decision_count:  @decisions.size,
+              system_stats:    system_stats
+            }
+          end
+
+          private
+
+          def find_matching_heuristic(query, domain)
+            @heuristics.values
+                       .select { |h| h.domain == domain || domain.nil? }
+                       .select { |h| query_matches?(h.pattern, query) }
+                       .max_by(&:confidence)
+          end
+
+          def query_matches?(pattern, query)
+            case pattern
+            when Symbol then query.is_a?(Hash) && query.key?(pattern)
+            when String then query.to_s.include?(pattern)
+            when Regexp then pattern.match?(query.to_s)
+            else false
+            end
+          end
+
+          def complexity_reason(complexity, matching)
+            if complexity >= COMPLEXITY_THRESHOLD
+              :high_complexity
+            elsif matching.nil?
+              :no_heuristic
+            else
+              :low_confidence
+            end
+          end
+
+          def store_decision(decision)
+            @decisions.shift if @decisions.size >= MAX_DECISIONS
+            @decisions << decision
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/dual_process/helpers/heuristic.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module DualProcess
+      module Helpers
+        class Heuristic
+          attr_reader :id, :pattern, :domain, :response, :confidence,
+                      :use_count, :success_count, :created_at, :last_used_at
+
+          def initialize(pattern:, domain:, response:, confidence: Constants::DEFAULT_CONFIDENCE)
+            @id            = SecureRandom.uuid
+            @pattern       = pattern
+            @domain        = domain
+            @response      = response
+            @confidence    = confidence.clamp(Constants::CONFIDENCE_FLOOR, Constants::CONFIDENCE_CEILING)
+            @use_count     = 0
+            @success_count = 0
+            @created_at    = Time.now.utc
+            @last_used_at  = nil
+          end
+
+          def use!(success: true)
+            @use_count    += 1
+            @last_used_at  = Time.now.utc
+            @success_count += 1 if success
+
+            delta = success ? Constants::HEURISTIC_BOOST : -Constants::HEURISTIC_BOOST
+            @confidence = (@confidence + delta).clamp(Constants::CONFIDENCE_FLOOR, Constants::CONFIDENCE_CEILING)
+          end
+
+          def success_rate
+            return 0.0 if @use_count.zero?
+
+            @success_count.to_f / @use_count
+          end
+
+          def reliable?
+            success_rate >= 0.7 && @use_count >= 3
+          end
+
+          def to_h
+            {
+              id:            @id,
+              pattern:       @pattern,
+              domain:        @domain,
+              response:      @response,
+              confidence:    @confidence,
+              use_count:     @use_count,
+              success_count: @success_count,
+              success_rate:  success_rate,
+              reliable:      reliable?,
+              created_at:    @created_at,
+              last_used_at:  @last_used_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module DualProcess
+      module Runners
+        module DualProcess
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_heuristic(pattern:, domain:, response:, confidence: nil, **)
+            Legion::Logging.debug "[dual_process] register_heuristic pattern=#{pattern} domain=#{domain}"
+            opts = { pattern: pattern, domain: domain, response: response }
+            opts[:confidence] = confidence unless confidence.nil?
+            heuristic = engine.register_heuristic(**opts)
+            { success: true, heuristic: heuristic.to_h }
+          end
+
+          def route_decision(query:, domain:, complexity:, **)
+            Legion::Logging.debug "[dual_process] route_decision domain=#{domain} complexity=#{complexity}"
+            route = engine.route_decision(query: query, domain: domain, complexity: complexity)
+            { success: true, **route }
+          end
+
+          def execute_system_one(query:, domain:, **)
+            Legion::Logging.debug "[dual_process] execute_system_one domain=#{domain}"
+            result = engine.execute_system_one(query: query, domain: domain)
+            { success: true, **result }
+          end
+
+          def execute_system_two(query:, domain:, deliberation: {}, **)
+            Legion::Logging.debug "[dual_process] execute_system_two domain=#{domain}"
+            result = engine.execute_system_two(query: query, domain: domain, deliberation: deliberation)
+            { success: true, **result }
+          end
+
+          def record_decision_outcome(decision_id:, outcome:, **)
+            Legion::Logging.debug "[dual_process] record_outcome decision_id=#{decision_id} outcome=#{outcome}"
+            engine.record_outcome(decision_id: decision_id, outcome: outcome)
+          end
+
+          def effort_assessment(**)
+            Legion::Logging.debug '[dual_process] effort_assessment'
+            {
+              success:       true,
+              effort_level:  engine.effort_level,
+              effort_budget: engine.instance_variable_get(:@effort_budget),
+              routing_label: engine.routing_label
+            }
+          end
+
+          def best_heuristics(limit: 5, **)
+            Legion::Logging.debug "[dual_process] best_heuristics limit=#{limit}"
+            { success: true, heuristics: engine.best_heuristics(limit: limit) }
+          end
+
+          def system_usage_stats(**)
+            Legion::Logging.debug '[dual_process] system_usage_stats'
+            { success: true, stats: engine.system_stats }
+          end
+
+          def update_dual_process(**)
+            Legion::Logging.debug '[dual_process] update_dual_process'
+            engine.recover_effort
+            engine.decay_heuristics
+            { success: true, effort_level: engine.effort_level, routing_label: engine.routing_label }
+          end
+
+          def dual_process_stats(**)
+            Legion::Logging.debug '[dual_process] dual_process_stats'
+            { success: true, **engine.to_h }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::DualProcessEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/dual_process.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/dual_process/version'
+require 'legion/extensions/dual_process/helpers/constants'
+require 'legion/extensions/dual_process/helpers/heuristic'
+require 'legion/extensions/dual_process/helpers/decision'
+require 'legion/extensions/dual_process/helpers/dual_process_engine'
+require 'legion/extensions/dual_process/runners/dual_process'
+
+module Legion
+  module Extensions
+    module DualProcess
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end