lex-dual-process 0.1.0

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/dual_process/client'
+
+RSpec.describe Legion::Extensions::DualProcess::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:register_heuristic)
+    expect(client).to respond_to(:route_decision)
+    expect(client).to respond_to(:execute_system_one)
+    expect(client).to respond_to(:execute_system_two)
+    expect(client).to respond_to(:record_decision_outcome)
+    expect(client).to respond_to(:effort_assessment)
+    expect(client).to respond_to(:best_heuristics)
+    expect(client).to respond_to(:system_usage_stats)
+    expect(client).to respond_to(:update_dual_process)
+    expect(client).to respond_to(:dual_process_stats)
+  end
+
+  it 'accepts an injected engine' do
+    custom_engine = Legion::Extensions::DualProcess::Helpers::DualProcessEngine.new
+    c = described_class.new(engine: custom_engine)
+    expect(c.send(:engine)).to be(custom_engine)
+  end
+
+  it 'creates its own engine when none injected' do
+    expect(client.send(:engine)).to be_a(Legion::Extensions::DualProcess::Helpers::DualProcessEngine)
+  end
+
+  it 'runs a full System 1 decision cycle' do
+    client.register_heuristic(pattern: 'greet', domain: :social, response: :smile, confidence: 0.9)
+    route = client.route_decision(query: 'greet friend', domain: :social, complexity: 0.2)
+    expect(route[:system]).to eq(:system_one)
+
+    exec = client.execute_system_one(query: 'greet friend', domain: :social)
+    expect(exec[:success]).to be true
+    expect(exec[:response]).to eq(:smile)
+
+    outcome = client.record_decision_outcome(decision_id: exec[:decision_id], outcome: :correct)
+    expect(outcome[:success]).to be true
+
+    stats = client.dual_process_stats
+    expect(stats[:system_stats][:system_one]).to eq(1)
+  end
+
+  it 'runs a full System 2 decision cycle' do
+    route = client.route_decision(query: 'novel complex problem', domain: :analysis, complexity: 0.9)
+    expect(route[:system]).to eq(:system_two)
+
+    exec = client.execute_system_two(
+      query: 'novel complex problem', domain: :analysis,
+      deliberation: { confidence: 0.88, response: :thorough_analysis }
+    )
+    expect(exec[:success]).to be true
+    expect(exec[:response]).to eq(:thorough_analysis)
+
+    stats = client.dual_process_stats
+    expect(stats[:system_stats][:system_two]).to eq(1)
+  end
+
+  it 'tracks effort depletion and recovery' do
+    initial = client.effort_assessment[:effort_level]
+    expect(initial).to eq(1.0)
+
+    5.times { client.execute_system_two(query: 'x', domain: :d) }
+    after_work = client.effort_assessment[:effort_level]
+    expect(after_work).to be < initial
+
+    client.update_dual_process
+    after_recovery = client.effort_assessment[:effort_level]
+    expect(after_recovery).to be > after_work
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DualProcess::Helpers::Constants do
+  it 'defines MAX_DECISIONS' do
+    expect(described_class::MAX_DECISIONS).to eq(200)
+  end
+
+  it 'defines MAX_HEURISTICS' do
+    expect(described_class::MAX_HEURISTICS).to eq(100)
+  end
+
+  it 'defines MAX_HISTORY' do
+    expect(described_class::MAX_HISTORY).to eq(300)
+  end
+
+  it 'defines confidence bounds' do
+    expect(described_class::CONFIDENCE_FLOOR).to eq(0.05)
+    expect(described_class::CONFIDENCE_CEILING).to eq(0.95)
+    expect(described_class::DEFAULT_CONFIDENCE).to eq(0.5)
+  end
+
+  it 'defines routing thresholds' do
+    expect(described_class::SYSTEM_ONE_THRESHOLD).to eq(0.6)
+    expect(described_class::COMPLEXITY_THRESHOLD).to eq(0.5)
+  end
+
+  it 'defines effort constants' do
+    expect(described_class::EFFORT_COST).to eq(0.1)
+    expect(described_class::EFFORT_RECOVERY_RATE).to eq(0.05)
+    expect(described_class::MAX_EFFORT_BUDGET).to eq(1.0)
+    expect(described_class::FATIGUE_PENALTY).to eq(0.15)
+    expect(described_class::HEURISTIC_BOOST).to eq(0.2)
+    expect(described_class::DECAY_RATE).to eq(0.01)
+  end
+
+  it 'defines SYSTEMS' do
+    expect(described_class::SYSTEMS).to contain_exactly(:system_one, :system_two)
+  end
+
+  it 'defines ROUTING_LABELS as a hash of ranges' do
+    labels = described_class::ROUTING_LABELS.values
+    expect(labels).to include(:automatic, :fluent, :effortful, :strained, :depleted)
+  end
+
+  it 'covers the full 0..1 range in ROUTING_LABELS' do
+    labels = described_class::ROUTING_LABELS
+    expect(labels.any? { |range, _| range.cover?(0.0) }).to be true
+    expect(labels.any? { |range, _| range.cover?(1.0) }).to be true
+    expect(labels.any? { |range, _| range.cover?(0.5) }).to be true
+  end
+
+  it 'defines DECISION_OUTCOMES' do
+    expect(described_class::DECISION_OUTCOMES).to contain_exactly(:correct, :incorrect, :uncertain)
+  end
+end

data/spec/legion/extensions/dual_process/helpers/decision_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DualProcess::Helpers::Decision do
+  let(:decision) do
+    described_class.new(
+      query:       'should I wave?',
+      domain:      :social,
+      system_used: :system_one,
+      confidence:  0.75,
+      complexity:  0.3
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(decision.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores core fields' do
+      expect(decision.query).to eq('should I wave?')
+      expect(decision.domain).to eq(:social)
+      expect(decision.system_used).to eq(:system_one)
+    end
+
+    it 'clamps confidence to valid range' do
+      d = described_class.new(query: 'x', domain: :d, system_used: :system_one, confidence: 2.0, complexity: 0.5)
+      expect(d.confidence).to eq(Legion::Extensions::DualProcess::Helpers::Constants::CONFIDENCE_CEILING)
+    end
+
+    it 'clamps complexity to [0, 1]' do
+      d = described_class.new(query: 'x', domain: :d, system_used: :system_one, confidence: 0.5, complexity: -0.5)
+      expect(d.complexity).to eq(0.0)
+    end
+
+    it 'starts with nil outcome' do
+      expect(decision.outcome).to be_nil
+    end
+
+    it 'defaults effort_cost to 0.0' do
+      expect(decision.effort_cost).to eq(0.0)
+    end
+
+    it 'sets created_at' do
+      expect(decision.created_at).to be_a(Time)
+    end
+
+    it 'accepts optional heuristic_id' do
+      d = described_class.new(
+        query: 'x', domain: :d, system_used: :system_one,
+        confidence: 0.5, complexity: 0.2, heuristic_id: 'abc-123'
+      )
+      expect(d.heuristic_id).to eq('abc-123')
+    end
+  end
+
+  describe '#outcome=' do
+    it 'sets the outcome' do
+      decision.outcome = :correct
+      expect(decision.outcome).to eq(:correct)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all key fields' do
+      result = decision.to_h
+      expect(result).to include(:id, :query, :domain, :system_used, :confidence,
+                                :complexity, :heuristic_id, :outcome, :effort_cost,
+                                :processing_time_ms, :created_at)
+    end
+
+    it 'reflects outcome after setting it' do
+      decision.outcome = :incorrect
+      expect(decision.to_h[:outcome]).to eq(:incorrect)
+    end
+  end
+end

data/spec/legion/extensions/dual_process/helpers/dual_process_engine_spec.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DualProcess::Helpers::DualProcessEngine do
+  subject(:engine) { described_class.new }
+
+  describe '#initialize' do
+    it 'starts with full effort budget' do
+      expect(engine.effort_level).to eq(1.0)
+    end
+
+    it 'starts with no heuristics' do
+      expect(engine.system_stats[:total]).to eq(0)
+    end
+  end
+
+  describe '#register_heuristic' do
+    it 'returns a Heuristic object' do
+      h = engine.register_heuristic(pattern: 'hello', domain: :social, response: :wave)
+      expect(h).to be_a(Legion::Extensions::DualProcess::Helpers::Heuristic)
+    end
+
+    it 'stores the heuristic' do
+      engine.register_heuristic(pattern: 'hello', domain: :social, response: :wave)
+      expect(engine.to_h[:heuristic_count]).to eq(1)
+    end
+
+    it 'accepts custom confidence' do
+      h = engine.register_heuristic(pattern: :x, domain: :d, response: :r, confidence: 0.8)
+      expect(h.confidence).to eq(0.8)
+    end
+
+    it 'evicts oldest when at capacity' do
+      stub_const('Legion::Extensions::DualProcess::Helpers::Constants::MAX_HEURISTICS', 2)
+      h1 = engine.register_heuristic(pattern: 'a', domain: :d, response: :r1)
+      h2 = engine.register_heuristic(pattern: 'b', domain: :d, response: :r2)
+      engine.register_heuristic(pattern: 'c', domain: :d, response: :r3)
+      ids = [h1.id, h2.id]
+      expect(engine.to_h[:heuristic_count]).to eq(2)
+      # one of the originals was evicted
+      expect(ids.count { |id| engine.instance_variable_get(:@heuristics).key?(id) }).to be <= 1
+    end
+  end
+
+  describe '#route_decision' do
+    context 'with a matching confident heuristic and low complexity' do
+      before do
+        engine.register_heuristic(pattern: 'hello', domain: :social, response: :wave, confidence: 0.8)
+      end
+
+      it 'routes to system_one' do
+        result = engine.route_decision(query: 'say hello', domain: :social, complexity: 0.2)
+        expect(result[:system]).to eq(:system_one)
+        expect(result[:reason]).to eq(:heuristic_match)
+      end
+    end
+
+    context 'with high complexity' do
+      it 'routes to system_two' do
+        result = engine.route_decision(query: 'complex decision', domain: :work, complexity: 0.8)
+        expect(result[:system]).to eq(:system_two)
+      end
+    end
+
+    context 'with no matching heuristic and low complexity' do
+      it 'routes to system_two due to no heuristic' do
+        result = engine.route_decision(query: 'unknown query', domain: :work, complexity: 0.3)
+        expect(result[:system]).to eq(:system_two)
+        expect(result[:reason]).to eq(:no_heuristic)
+      end
+    end
+
+    context 'when effort is depleted' do
+      before do
+        stub_const('Legion::Extensions::DualProcess::Helpers::Constants::MAX_EFFORT_BUDGET', 0.0)
+        engine.instance_variable_set(:@effort_budget, 0.0)
+      end
+
+      it 'forces system_one with fatigue flag' do
+        result = engine.route_decision(query: 'complex', domain: :work, complexity: 0.9)
+        expect(result[:system]).to eq(:system_one)
+        expect(result[:reason]).to eq(:effort_depleted)
+        expect(result[:fatigue]).to be true
+      end
+    end
+  end
+
+  describe '#execute_system_one' do
+    context 'with a matching heuristic' do
+      before do
+        engine.register_heuristic(pattern: 'hello', domain: :social, response: :wave, confidence: 0.8)
+      end
+
+      it 'returns the heuristic response' do
+        result = engine.execute_system_one(query: 'say hello', domain: :social)
+        expect(result[:response]).to eq(:wave)
+        expect(result[:system]).to eq(:system_one)
+      end
+
+      it 'includes decision_id' do
+        result = engine.execute_system_one(query: 'say hello', domain: :social)
+        expect(result[:decision_id]).to match(/\A[0-9a-f-]{36}\z/)
+      end
+    end
+
+    context 'without a matching heuristic' do
+      it 'returns :no_heuristic response' do
+        result = engine.execute_system_one(query: 'unknown', domain: :work)
+        expect(result[:response]).to eq(:no_heuristic)
+      end
+
+      it 'applies fatigue penalty to confidence' do
+        result = engine.execute_system_one(query: 'unknown', domain: :work)
+        expected = (Legion::Extensions::DualProcess::Helpers::Constants::DEFAULT_CONFIDENCE -
+                    Legion::Extensions::DualProcess::Helpers::Constants::FATIGUE_PENALTY)
+        expect(result[:confidence]).to be_within(0.001).of(expected)
+      end
+    end
+  end
+
+  describe '#execute_system_two' do
+    it 'deducts effort from the budget' do
+      before_effort = engine.effort_level
+      engine.execute_system_two(query: 'complex', domain: :work)
+      expect(engine.effort_level).to be < before_effort
+    end
+
+    it 'returns a decision_id' do
+      result = engine.execute_system_two(query: 'complex', domain: :work)
+      expect(result[:decision_id]).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'returns system_two' do
+      result = engine.execute_system_two(query: 'complex', domain: :work)
+      expect(result[:system]).to eq(:system_two)
+    end
+
+    it 'uses deliberation confidence when provided' do
+      result = engine.execute_system_two(query: 'x', domain: :d, deliberation: { confidence: 0.85 })
+      expect(result[:confidence]).to eq(0.85)
+    end
+
+    it 'uses deliberation response when provided' do
+      result = engine.execute_system_two(query: 'x', domain: :d, deliberation: { response: :approve })
+      expect(result[:response]).to eq(:approve)
+    end
+
+    it 'does not go below zero effort' do
+      15.times { engine.execute_system_two(query: 'x', domain: :d) }
+      expect(engine.effort_level).to be >= 0.0
+    end
+  end
+
+  describe '#record_outcome' do
+    let(:decision_id) do
+      engine.execute_system_one(query: 'test', domain: :work)[:decision_id]
+    end
+
+    it 'returns success for known decision' do
+      result = engine.record_outcome(decision_id: decision_id, outcome: :correct)
+      expect(result[:success]).to be true
+    end
+
+    it 'returns not_found for unknown decision' do
+      result = engine.record_outcome(decision_id: 'nonexistent', outcome: :correct)
+      expect(result[:success]).to be false
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#effort_level' do
+    it 'starts at 1.0' do
+      expect(engine.effort_level).to eq(1.0)
+    end
+
+    it 'decreases after system_two execution' do
+      engine.execute_system_two(query: 'x', domain: :d)
+      expect(engine.effort_level).to be < 1.0
+    end
+  end
+
+  describe '#routing_label' do
+    it 'returns :automatic at full effort' do
+      expect(engine.routing_label).to eq(:automatic)
+    end
+
+    it 'returns :depleted at very low effort' do
+      engine.instance_variable_set(:@effort_budget, 0.1)
+      expect(engine.routing_label).to eq(:depleted)
+    end
+
+    it 'returns :effortful at mid effort' do
+      engine.instance_variable_set(:@effort_budget, 0.5)
+      expect(engine.routing_label).to eq(:effortful)
+    end
+  end
+
+  describe '#recover_effort' do
+    it 'increases effort budget' do
+      engine.execute_system_two(query: 'x', domain: :d)
+      before = engine.effort_level
+      engine.recover_effort
+      expect(engine.effort_level).to be > before
+    end
+
+    it 'does not exceed MAX_EFFORT_BUDGET' do
+      5.times { engine.recover_effort }
+      expect(engine.effort_level).to be <= 1.0
+    end
+  end
+
+  describe '#decay_heuristics' do
+    it 'reduces confidence of used heuristics' do
+      h = engine.register_heuristic(pattern: 'x', domain: :d, response: :r, confidence: 0.8)
+      h.use!(success: true)
+      before = h.confidence
+      engine.decay_heuristics
+      expect(h.confidence).to be < before
+    end
+
+    it 'does not decay unused heuristics' do
+      h = engine.register_heuristic(pattern: 'x', domain: :d, response: :r, confidence: 0.8)
+      before = h.confidence
+      engine.decay_heuristics
+      expect(h.confidence).to eq(before)
+    end
+  end
+
+  describe '#system_stats' do
+    it 'returns zeros with no decisions' do
+      stats = engine.system_stats
+      expect(stats[:total]).to eq(0)
+      expect(stats[:s1_ratio]).to eq(0.0)
+    end
+
+    it 'counts system_one and system_two decisions separately' do
+      engine.execute_system_one(query: 'x', domain: :d)
+      engine.execute_system_two(query: 'y', domain: :d)
+      stats = engine.system_stats
+      expect(stats[:system_one]).to eq(1)
+      expect(stats[:system_two]).to eq(1)
+      expect(stats[:total]).to eq(2)
+    end
+  end
+
+  describe '#best_heuristics' do
+    it 'returns empty array with no reliable heuristics' do
+      expect(engine.best_heuristics(limit: 5)).to eq([])
+    end
+
+    it 'returns reliable heuristics sorted by success_rate' do
+      h = engine.register_heuristic(pattern: 'x', domain: :d, response: :r, confidence: 0.9)
+      5.times { h.use!(success: true) }
+      result = engine.best_heuristics(limit: 5)
+      expect(result.size).to eq(1)
+      expect(result.first[:id]).to eq(h.id)
+    end
+
+    it 'respects the limit' do
+      3.times do |i|
+        h = engine.register_heuristic(pattern: "p#{i}", domain: :d, response: :r, confidence: 0.9)
+        5.times { h.use!(success: true) }
+      end
+      expect(engine.best_heuristics(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all key fields' do
+      result = engine.to_h
+      expect(result).to include(:effort_budget, :effort_level, :routing_label,
+                                :heuristic_count, :decision_count, :system_stats)
+    end
+  end
+end

data/spec/legion/extensions/dual_process/helpers/heuristic_spec.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::DualProcess::Helpers::Heuristic do
+  let(:heuristic) do
+    described_class.new(pattern: 'greeting', domain: :social, response: :wave)
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(heuristic.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores pattern, domain, and response' do
+      expect(heuristic.pattern).to eq('greeting')
+      expect(heuristic.domain).to eq(:social)
+      expect(heuristic.response).to eq(:wave)
+    end
+
+    it 'defaults confidence to DEFAULT_CONFIDENCE' do
+      expect(heuristic.confidence).to eq(Legion::Extensions::DualProcess::Helpers::Constants::DEFAULT_CONFIDENCE)
+    end
+
+    it 'accepts custom confidence' do
+      h = described_class.new(pattern: :x, domain: :d, response: :r, confidence: 0.8)
+      expect(h.confidence).to eq(0.8)
+    end
+
+    it 'clamps confidence to floor' do
+      h = described_class.new(pattern: :x, domain: :d, response: :r, confidence: -1.0)
+      expect(h.confidence).to eq(Legion::Extensions::DualProcess::Helpers::Constants::CONFIDENCE_FLOOR)
+    end
+
+    it 'clamps confidence to ceiling' do
+      h = described_class.new(pattern: :x, domain: :d, response: :r, confidence: 2.0)
+      expect(h.confidence).to eq(Legion::Extensions::DualProcess::Helpers::Constants::CONFIDENCE_CEILING)
+    end
+
+    it 'starts with zero use_count and success_count' do
+      expect(heuristic.use_count).to eq(0)
+      expect(heuristic.success_count).to eq(0)
+    end
+
+    it 'sets created_at' do
+      expect(heuristic.created_at).to be_a(Time)
+    end
+
+    it 'starts with nil last_used_at' do
+      expect(heuristic.last_used_at).to be_nil
+    end
+  end
+
+  describe '#use!' do
+    it 'increments use_count' do
+      heuristic.use!(success: true)
+      expect(heuristic.use_count).to eq(1)
+    end
+
+    it 'increments success_count on success' do
+      heuristic.use!(success: true)
+      expect(heuristic.success_count).to eq(1)
+    end
+
+    it 'does not increment success_count on failure' do
+      heuristic.use!(success: false)
+      expect(heuristic.success_count).to eq(0)
+    end
+
+    it 'sets last_used_at' do
+      heuristic.use!(success: true)
+      expect(heuristic.last_used_at).to be_a(Time)
+    end
+
+    it 'boosts confidence on success' do
+      original = heuristic.confidence
+      heuristic.use!(success: true)
+      expect(heuristic.confidence).to be > original
+    end
+
+    it 'reduces confidence on failure' do
+      original = heuristic.confidence
+      heuristic.use!(success: false)
+      expect(heuristic.confidence).to be < original
+    end
+
+    it 'does not exceed CONFIDENCE_CEILING' do
+      10.times { heuristic.use!(success: true) }
+      expect(heuristic.confidence).to be <= Legion::Extensions::DualProcess::Helpers::Constants::CONFIDENCE_CEILING
+    end
+
+    it 'does not go below CONFIDENCE_FLOOR' do
+      10.times { heuristic.use!(success: false) }
+      expect(heuristic.confidence).to be >= Legion::Extensions::DualProcess::Helpers::Constants::CONFIDENCE_FLOOR
+    end
+  end
+
+  describe '#success_rate' do
+    it 'returns 0.0 with no uses' do
+      expect(heuristic.success_rate).to eq(0.0)
+    end
+
+    it 'computes ratio correctly' do
+      2.times { heuristic.use!(success: true) }
+      heuristic.use!(success: false)
+      expect(heuristic.success_rate).to be_within(0.001).of(2.0 / 3.0)
+    end
+  end
+
+  describe '#reliable?' do
+    it 'returns false with no uses' do
+      expect(heuristic.reliable?).to be false
+    end
+
+    it 'returns false with fewer than 3 uses' do
+      2.times { heuristic.use!(success: true) }
+      expect(heuristic.reliable?).to be false
+    end
+
+    it 'returns true with high success rate and enough uses' do
+      5.times { heuristic.use!(success: true) }
+      expect(heuristic.reliable?).to be true
+    end
+
+    it 'returns false with low success rate even with many uses' do
+      5.times { heuristic.use!(success: false) }
+      expect(heuristic.reliable?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all key fields' do
+      result = heuristic.to_h
+      expect(result).to include(:id, :pattern, :domain, :response, :confidence,
+                                :use_count, :success_count, :success_rate, :reliable,
+                                :created_at, :last_used_at)
+    end
+
+    it 'reflects current state' do
+      heuristic.use!(success: true)
+      result = heuristic.to_h
+      expect(result[:use_count]).to eq(1)
+      expect(result[:success_count]).to eq(1)
+    end
+  end
+end