lex-signal-detection 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 613fd2226426c9cfd6c2ee891daf43ccfeb885e1b312efe4528f7563eef23b1f
+  data.tar.gz: a7c1a8bea4db11d07dc11f01f6933149cf0c75131b3ea2fd91b593f5538643a8
+SHA512:
+  metadata.gz: b41037170a7448215b71c6c92878f2aad996bf3db25cf377570d87e2a45867d9b6df1579ef3a5c7ddfb51fc34fa4822ea6e4953ae00ef28df0a51690acd68c9b
+  data.tar.gz: 411168927c8d661236a931f599f69c949c7b0da097e1eee693af5b27ab7dbf95f42c8f0efade5d116957e1adb9a583a9e91826de33b376f554ad15f21d9e0f7b

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-signal-detection.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/signal_detection/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-signal-detection'
+  spec.version       = Legion::Extensions::SignalDetection::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Signal Detection'
+  spec.description   = "Green & Swets' Signal Detection Theory engine for LegionIO: sensitivity (d') and response bias (criterion) modeling"
+  spec.homepage      = 'https://github.com/LegionIO/lex-signal-detection'
+  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-signal-detection'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-signal-detection'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-signal-detection'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-signal-detection/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-signal-detection.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/signal_detection/helpers/constants'
+require 'legion/extensions/signal_detection/helpers/detector'
+require 'legion/extensions/signal_detection/helpers/detection_engine'
+require 'legion/extensions/signal_detection/runners/signal_detection'
+
+module Legion
+  module Extensions
+    module SignalDetection
+      class Client
+        include Runners::SignalDetection
+
+        def initialize(**)
+          @detection_engine = Helpers::DetectionEngine.new
+        end
+
+        private
+
+        attr_reader :detection_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SignalDetection
+      module Helpers
+        module Constants
+          MAX_DETECTORS = 100
+          MAX_TRIALS    = 1000
+          MAX_HISTORY   = 300
+
+          DEFAULT_SENSITIVITY = 1.0
+          SENSITIVITY_FLOOR   = 0.0
+          SENSITIVITY_CEILING = 5.0
+
+          DEFAULT_CRITERION = 0.0
+          CRITERION_FLOOR   = -3.0
+          CRITERION_CEILING = 3.0
+
+          LEARNING_RATE = 0.05
+          DECAY_RATE    = 0.01
+
+          TRIAL_OUTCOMES = %i[hit miss false_alarm correct_rejection].freeze
+
+          SENSITIVITY_LABELS = {
+            (3.0..)     => :exceptional,
+            (2.0...3.0) => :excellent,
+            (1.0...2.0) => :good,
+            (0.5...1.0) => :moderate,
+            (..0.5)     => :poor
+          }.freeze
+
+          BIAS_LABELS = {
+            (1.0..)       => :very_conservative,
+            (0.3...1.0)   => :conservative,
+            (-0.3...0.3)  => :neutral,
+            (-1.0...-0.3) => :liberal,
+            (...-1.0)     => :very_liberal
+          }.freeze
+
+          module_function
+
+          def sensitivity_label(d_prime)
+            SENSITIVITY_LABELS.find { |range, _| range.cover?(d_prime) }&.last || :poor
+          end
+
+          def bias_label(criterion)
+            BIAS_LABELS.find { |range, _| range.cover?(criterion) }&.last || :neutral
+          end
+
+          def clamp_sensitivity(value)
+            value.clamp(SENSITIVITY_FLOOR, SENSITIVITY_CEILING)
+          end
+
+          def clamp_criterion(value)
+            value.clamp(CRITERION_FLOOR, CRITERION_CEILING)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/signal_detection/helpers/detection_engine.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SignalDetection
+      module Helpers
+        class DetectionEngine
+          def initialize
+            @detectors = {}
+          end
+
+          def create_detector(domain:)
+            raise ArgumentError, "max detectors reached (#{Constants::MAX_DETECTORS})" if @detectors.size >= Constants::MAX_DETECTORS
+
+            detector = Detector.new(domain: domain)
+            @detectors[detector.id] = detector
+            detector
+          end
+
+          def record_trial(detector_id:, signal_present:, responded_present:)
+            detector = fetch!(detector_id)
+            outcome  = classify_outcome(signal_present: signal_present, responded_present: responded_present)
+            detector.record_trial(outcome: outcome)
+            { detector_id: detector_id, outcome: outcome, trial_count: detector.trial_count }
+          end
+
+          def compute_sensitivity(detector_id:)
+            detector = fetch!(detector_id)
+            {
+              detector_id:       detector_id,
+              d_prime:           detector.compute_dprime,
+              criterion:         detector.compute_criterion,
+              accuracy:          detector.accuracy,
+              hit_rate:          detector.hit_rate,
+              false_alarm_rate:  detector.false_alarm_rate,
+              sensitivity_label: detector.sensitivity_label,
+              bias_label:        detector.bias_label
+            }
+          end
+
+          def adjust_bias(detector_id:, amount:)
+            detector = fetch!(detector_id)
+            detector.adjust_criterion(amount: amount)
+            { detector_id: detector_id, criterion: detector.criterion, bias_label: detector.bias_label }
+          end
+
+          def best_detectors(limit: 5)
+            @detectors.values
+                      .sort_by { |d| -d.sensitivity }
+                      .first(limit)
+                      .map(&:to_h)
+          end
+
+          def by_domain(domain:)
+            @detectors.values.select { |d| d.domain == domain }.map(&:to_h)
+          end
+
+          def optimal_criterion(detector_id:, signal_probability: 0.5)
+            detector = fetch!(detector_id)
+            # Optimal criterion for equal cost: c* = 0.5 * ln((1-p)/p) in likelihood ratio terms
+            # In SDT criterion units: shift from neutral based on prior probability
+            prior_ratio = (1.0 - signal_probability) / signal_probability.clamp(0.001, 0.999)
+            optimal = 0.5 * Math.log(prior_ratio)
+            {
+              detector_id:        detector_id,
+              optimal_criterion:  Constants.clamp_criterion(optimal),
+              current_criterion:  detector.criterion,
+              signal_probability: signal_probability
+            }
+          end
+
+          def roc_point(detector_id:)
+            detector = fetch!(detector_id)
+            {
+              detector_id:      detector_id,
+              hit_rate:         detector.hit_rate,
+              false_alarm_rate: detector.false_alarm_rate,
+              d_prime:          detector.sensitivity
+            }
+          end
+
+          def decay_all
+            count = 0
+            @detectors.each_value do |detector|
+              next if detector.trial_count.zero?
+
+              detector.adjust_criterion(amount: Constants::DECAY_RATE * -detector.criterion.clamp(-1, 1))
+              count += 1
+            end
+            count
+          end
+
+          def get(detector_id)
+            @detectors[detector_id]
+          end
+
+          def count
+            @detectors.size
+          end
+
+          def to_h
+            {
+              detector_count: @detectors.size,
+              detectors:      @detectors.transform_values(&:to_h)
+            }
+          end
+
+          private
+
+          def fetch!(detector_id)
+            @detectors.fetch(detector_id) { raise KeyError, "detector not found: #{detector_id}" }
+          end
+
+          def classify_outcome(signal_present:, responded_present:)
+            if signal_present && responded_present then :hit
+            elsif signal_present && !responded_present then :miss
+            elsif !signal_present && responded_present then :false_alarm
+            else :correct_rejection
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/signal_detection/helpers/detector.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SignalDetection
+      module Helpers
+        class Detector
+          include Constants
+
+          attr_reader :id, :domain, :hits, :misses, :false_alarms, :correct_rejections,
+                      :trial_count, :created_at, :last_trial_at, :sensitivity, :criterion
+
+          def initialize(domain:)
+            @id               = SecureRandom.uuid
+            @domain           = domain
+            @sensitivity      = Constants::DEFAULT_SENSITIVITY
+            @criterion        = Constants::DEFAULT_CRITERION
+            @hits             = 0
+            @misses           = 0
+            @false_alarms     = 0
+            @correct_rejections = 0
+            @trial_count      = 0
+            @created_at       = Time.now.utc
+            @last_trial_at    = nil
+          end
+
+          def record_trial(outcome:)
+            raise ArgumentError, "invalid outcome: #{outcome}" unless Constants::TRIAL_OUTCOMES.include?(outcome)
+
+            case outcome
+            when :hit               then @hits += 1
+            when :miss              then @misses += 1
+            when :false_alarm       then @false_alarms += 1
+            when :correct_rejection then @correct_rejections += 1
+            end
+
+            @trial_count   += 1
+            @last_trial_at  = Time.now.utc
+
+            update_sensitivity
+          end
+
+          def hit_rate
+            signal_total = @hits + @misses + 1
+            (@hits + 0.5) / signal_total.to_f
+          end
+
+          def false_alarm_rate
+            noise_total = @false_alarms + @correct_rejections + 1
+            (@false_alarms + 0.5) / noise_total.to_f
+          end
+
+          def compute_dprime
+            d = z_score(hit_rate) - z_score(false_alarm_rate)
+            Constants.clamp_sensitivity(d)
+          end
+
+          def compute_criterion
+            c = -0.5 * (z_score(hit_rate) + z_score(false_alarm_rate))
+            Constants.clamp_criterion(c)
+          end
+
+          def accuracy
+            return 0.0 if @trial_count.zero?
+
+            (@hits + @correct_rejections).to_f / @trial_count
+          end
+
+          def sensitivity_label
+            Constants.sensitivity_label(@sensitivity)
+          end
+
+          def bias_label
+            Constants.bias_label(@criterion)
+          end
+
+          def adjust_criterion(amount:)
+            @criterion = Constants.clamp_criterion(@criterion + amount)
+          end
+
+          def to_h
+            {
+              id:                 @id,
+              domain:             @domain,
+              sensitivity:        @sensitivity,
+              criterion:          @criterion,
+              hits:               @hits,
+              misses:             @misses,
+              false_alarms:       @false_alarms,
+              correct_rejections: @correct_rejections,
+              trial_count:        @trial_count,
+              hit_rate:           hit_rate,
+              false_alarm_rate:   false_alarm_rate,
+              accuracy:           accuracy,
+              sensitivity_label:  sensitivity_label,
+              bias_label:         bias_label,
+              created_at:         @created_at,
+              last_trial_at:      @last_trial_at
+            }
+          end
+
+          private
+
+          def update_sensitivity
+            return if @trial_count < 2
+
+            @sensitivity = compute_dprime
+            @criterion   = compute_criterion
+          end
+
+          def z_score(probability)
+            prob = probability.clamp(0.001, 0.999)
+            Math.sqrt(2.0) * erfinv((2.0 * prob) - 1.0)
+          end
+
+          def erfinv(val)
+            # Winitzki (2008) rational approximation for inverse error function
+            a = 0.147
+            ln_term = Math.log(1.0 - (val * val))
+            two_pi_a = (2.0 / (Math::PI * a))
+            half_ln = ln_term / 2.0
+
+            inner = two_pi_a + half_ln
+            Math.sqrt(Math.sqrt((inner * inner) - (ln_term / a)) - inner) * (val.negative? ? -1 : 1)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SignalDetection
+      module Runners
+        module SignalDetection
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_detector(domain:, **)
+            detector = detection_engine.create_detector(domain: domain)
+            Legion::Logging.info "[signal_detection] created detector id=#{detector.id[0..7]} domain=#{domain}"
+            { created: true, detector_id: detector.id, domain: domain }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[signal_detection] create_detector failed: #{e.message}"
+            { created: false, reason: e.message }
+          end
+
+          def record_detection_trial(detector_id:, signal_present:, responded_present:, **)
+            result = detection_engine.record_trial(
+              detector_id:       detector_id,
+              signal_present:    signal_present,
+              responded_present: responded_present
+            )
+            Legion::Logging.debug "[signal_detection] trial: id=#{detector_id[0..7]} outcome=#{result[:outcome]} count=#{result[:trial_count]}"
+            result
+          rescue KeyError => e
+            Legion::Logging.warn "[signal_detection] record_trial failed: #{e.message}"
+            { recorded: false, reason: :not_found }
+          end
+
+          def compute_detector_sensitivity(detector_id:, **)
+            result = detection_engine.compute_sensitivity(detector_id: detector_id)
+            Legion::Logging.debug "[signal_detection] sensitivity: id=#{detector_id[0..7]} " \
+                                  "d_prime=#{result[:d_prime].round(3)} label=#{result[:sensitivity_label]}"
+            result
+          rescue KeyError => e
+            Legion::Logging.warn "[signal_detection] compute_sensitivity failed: #{e.message}"
+            { found: false, reason: :not_found }
+          end
+
+          def adjust_detector_bias(detector_id:, amount:, **)
+            result = detection_engine.adjust_bias(detector_id: detector_id, amount: amount)
+            Legion::Logging.debug "[signal_detection] bias adjusted: id=#{detector_id[0..7]} " \
+                                  "criterion=#{result[:criterion].round(3)} label=#{result[:bias_label]}"
+            result
+          rescue KeyError => e
+            Legion::Logging.warn "[signal_detection] adjust_bias failed: #{e.message}"
+            { adjusted: false, reason: :not_found }
+          end
+
+          def best_detectors(limit: 5, **)
+            detectors = detection_engine.best_detectors(limit: limit)
+            Legion::Logging.debug "[signal_detection] best detectors: count=#{detectors.size} limit=#{limit}"
+            { detectors: detectors, count: detectors.size }
+          end
+
+          def domain_detectors(domain:, **)
+            detectors = detection_engine.by_domain(domain: domain)
+            Legion::Logging.debug "[signal_detection] domain detectors: domain=#{domain} count=#{detectors.size}"
+            { detectors: detectors, count: detectors.size, domain: domain }
+          end
+
+          def optimal_detector_criterion(detector_id:, signal_probability: 0.5, **)
+            result = detection_engine.optimal_criterion(
+              detector_id:        detector_id,
+              signal_probability: signal_probability
+            )
+            Legion::Logging.debug "[signal_detection] optimal criterion: id=#{detector_id[0..7]} optimal=#{result[:optimal_criterion].round(3)}"
+            result
+          rescue KeyError => e
+            Legion::Logging.warn "[signal_detection] optimal_criterion failed: #{e.message}"
+            { found: false, reason: :not_found }
+          end
+
+          def detector_roc_point(detector_id:, **)
+            result = detection_engine.roc_point(detector_id: detector_id)
+            Legion::Logging.debug "[signal_detection] roc point: id=#{detector_id[0..7]} " \
+                                  "hr=#{result[:hit_rate].round(3)} far=#{result[:false_alarm_rate].round(3)}"
+            result
+          rescue KeyError => e
+            Legion::Logging.warn "[signal_detection] roc_point failed: #{e.message}"
+            { found: false, reason: :not_found }
+          end
+
+          def update_signal_detection(**)
+            decayed = detection_engine.decay_all
+            Legion::Logging.debug "[signal_detection] decay cycle: detectors_updated=#{decayed}"
+            { decayed: decayed }
+          end
+
+          def signal_detection_stats(**)
+            {
+              total_detectors: detection_engine.count,
+              top_detectors:   detection_engine.best_detectors(limit: 3)
+            }
+          end
+
+          private
+
+          def detection_engine
+            @detection_engine ||= Helpers::DetectionEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/signal_detection.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/signal_detection/version'
+require 'legion/extensions/signal_detection/helpers/constants'
+require 'legion/extensions/signal_detection/helpers/detector'
+require 'legion/extensions/signal_detection/helpers/detection_engine'
+require 'legion/extensions/signal_detection/runners/signal_detection'
+
+module Legion
+  module Extensions
+    module SignalDetection
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/signal_detection/client'
+
+RSpec.describe Legion::Extensions::SignalDetection::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:create_detector)
+    expect(client).to respond_to(:record_detection_trial)
+    expect(client).to respond_to(:compute_detector_sensitivity)
+    expect(client).to respond_to(:adjust_detector_bias)
+    expect(client).to respond_to(:best_detectors)
+    expect(client).to respond_to(:domain_detectors)
+    expect(client).to respond_to(:optimal_detector_criterion)
+    expect(client).to respond_to(:detector_roc_point)
+    expect(client).to respond_to(:update_signal_detection)
+    expect(client).to respond_to(:signal_detection_stats)
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SignalDetection::Helpers::Constants do
+  describe '.sensitivity_label' do
+    it 'labels exceptional for d_prime >= 3.0' do
+      expect(described_class.sensitivity_label(3.5)).to eq(:exceptional)
+    end
+
+    it 'labels excellent for 2.0 <= d_prime < 3.0' do
+      expect(described_class.sensitivity_label(2.5)).to eq(:excellent)
+    end
+
+    it 'labels good for 1.0 <= d_prime < 2.0' do
+      expect(described_class.sensitivity_label(1.5)).to eq(:good)
+    end
+
+    it 'labels moderate for 0.5 <= d_prime < 1.0' do
+      expect(described_class.sensitivity_label(0.7)).to eq(:moderate)
+    end
+
+    it 'labels poor for d_prime < 0.5' do
+      expect(described_class.sensitivity_label(0.2)).to eq(:poor)
+    end
+  end
+
+  describe '.bias_label' do
+    it 'labels very_conservative for criterion >= 1.0' do
+      expect(described_class.bias_label(1.5)).to eq(:very_conservative)
+    end
+
+    it 'labels conservative for 0.3 <= criterion < 1.0' do
+      expect(described_class.bias_label(0.5)).to eq(:conservative)
+    end
+
+    it 'labels neutral for -0.3 <= criterion < 0.3' do
+      expect(described_class.bias_label(0.0)).to eq(:neutral)
+    end
+
+    it 'labels liberal for -1.0 <= criterion < -0.3' do
+      expect(described_class.bias_label(-0.5)).to eq(:liberal)
+    end
+
+    it 'labels very_liberal for criterion < -1.0' do
+      expect(described_class.bias_label(-1.5)).to eq(:very_liberal)
+    end
+  end
+
+  describe '.clamp_sensitivity' do
+    it 'clamps to floor' do
+      expect(described_class.clamp_sensitivity(-1.0)).to eq(0.0)
+    end
+
+    it 'clamps to ceiling' do
+      expect(described_class.clamp_sensitivity(10.0)).to eq(5.0)
+    end
+
+    it 'passes through valid values' do
+      expect(described_class.clamp_sensitivity(2.5)).to eq(2.5)
+    end
+  end
+
+  describe '.clamp_criterion' do
+    it 'clamps to floor' do
+      expect(described_class.clamp_criterion(-5.0)).to eq(-3.0)
+    end
+
+    it 'clamps to ceiling' do
+      expect(described_class.clamp_criterion(5.0)).to eq(3.0)
+    end
+
+    it 'passes through valid values' do
+      expect(described_class.clamp_criterion(1.0)).to eq(1.0)
+    end
+  end
+
+  describe 'TRIAL_OUTCOMES' do
+    it 'includes all four outcomes' do
+      expect(described_class::TRIAL_OUTCOMES).to include(:hit, :miss, :false_alarm, :correct_rejection)
+    end
+
+    it 'is frozen' do
+      expect(described_class::TRIAL_OUTCOMES).to be_frozen
+    end
+  end
+end

data/spec/legion/extensions/signal_detection/helpers/detection_engine_spec.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SignalDetection::Helpers::DetectionEngine do
+  subject(:engine) { described_class.new }
+
+  let(:detector_id) { engine.create_detector(domain: :vision).id }
+
+  describe '#create_detector' do
+    it 'creates a detector and returns it' do
+      detector = engine.create_detector(domain: :auditory)
+      expect(detector).to be_a(Legion::Extensions::SignalDetection::Helpers::Detector)
+    end
+
+    it 'increments count' do
+      engine.create_detector(domain: :auditory)
+      engine.create_detector(domain: :visual)
+      expect(engine.count).to eq(2)
+    end
+
+    it 'raises when max detectors reached' do
+      stub_const('Legion::Extensions::SignalDetection::Helpers::Constants::MAX_DETECTORS', 1)
+      engine.create_detector(domain: :test)
+      expect { engine.create_detector(domain: :overflow) }.to raise_error(ArgumentError, /max detectors/)
+    end
+  end
+
+  describe '#record_trial' do
+    it 'records a hit when signal present and responded present' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: true)
+      expect(result[:outcome]).to eq(:hit)
+    end
+
+    it 'records a miss when signal present and not responded' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: false)
+      expect(result[:outcome]).to eq(:miss)
+    end
+
+    it 'records a false alarm when no signal and responded present' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: false, responded_present: true)
+      expect(result[:outcome]).to eq(:false_alarm)
+    end
+
+    it 'records a correct rejection when no signal and not responded' do
+      result = engine.record_trial(detector_id: detector_id, signal_present: false, responded_present: false)
+      expect(result[:outcome]).to eq(:correct_rejection)
+    end
+
+    it 'raises KeyError for unknown detector' do
+      expect do
+        engine.record_trial(detector_id: 'bogus', signal_present: true, responded_present: true)
+      end.to raise_error(KeyError)
+    end
+  end
+
+  describe '#compute_sensitivity' do
+    it 'returns d_prime, criterion, accuracy' do
+      5.times { engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: true) }
+      2.times { engine.record_trial(detector_id: detector_id, signal_present: false, responded_present: false) }
+      result = engine.compute_sensitivity(detector_id: detector_id)
+      expect(result).to include(:d_prime, :criterion, :accuracy, :hit_rate, :false_alarm_rate)
+    end
+
+    it 'raises KeyError for unknown detector' do
+      expect { engine.compute_sensitivity(detector_id: 'unknown') }.to raise_error(KeyError)
+    end
+  end
+
+  describe '#adjust_bias' do
+    it 'shifts the criterion' do
+      before = engine.get(detector_id).criterion
+      engine.adjust_bias(detector_id: detector_id, amount: 0.5)
+      expect(engine.get(detector_id).criterion).to be > before
+    end
+  end
+
+  describe '#best_detectors' do
+    it 'returns detectors sorted by sensitivity' do
+      id1 = engine.create_detector(domain: :A).id
+      id2 = engine.create_detector(domain: :B).id
+      10.times { engine.record_trial(detector_id: id1, signal_present: true, responded_present: true) }
+      engine.record_trial(detector_id: id1, signal_present: false, responded_present: true)
+      2.times  { engine.record_trial(detector_id: id2, signal_present: true, responded_present: true) }
+      10.times { engine.record_trial(detector_id: id2, signal_present: false, responded_present: true) }
+      result = engine.best_detectors(limit: 2)
+      expect(result.first[:sensitivity]).to be >= result.last[:sensitivity]
+    end
+
+    it 'respects limit' do
+      3.times { |i| engine.create_detector(domain: :"d#{i}") }
+      expect(engine.best_detectors(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#by_domain' do
+    it 'filters by domain' do
+      engine.create_detector(domain: :audio)
+      engine.create_detector(domain: :audio)
+      engine.create_detector(domain: :visual)
+      result = engine.by_domain(domain: :audio)
+      expect(result.size).to eq(2)
+      expect(result.all? { |d| d[:domain] == :audio }).to be true
+    end
+  end
+
+  describe '#optimal_criterion' do
+    it 'returns optimal criterion for balanced prior' do
+      result = engine.optimal_criterion(detector_id: detector_id, signal_probability: 0.5)
+      expect(result[:optimal_criterion]).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns positive criterion for low signal probability' do
+      result = engine.optimal_criterion(detector_id: detector_id, signal_probability: 0.2)
+      expect(result[:optimal_criterion]).to be > 0
+    end
+  end
+
+  describe '#roc_point' do
+    it 'returns hit_rate and false_alarm_rate' do
+      result = engine.roc_point(detector_id: detector_id)
+      expect(result).to include(:hit_rate, :false_alarm_rate, :d_prime)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'returns count of detectors updated' do
+      engine.record_trial(detector_id: detector_id, signal_present: true, responded_present: true)
+      count = engine.decay_all
+      expect(count).to eq(1)
+    end
+
+    it 'skips detectors with no trials' do
+      count = engine.decay_all
+      expect(count).to eq(0)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns detector count and map' do
+      result = engine.to_h
+      expect(result).to include(:detector_count, :detectors)
+    end
+  end
+end

data/spec/legion/extensions/signal_detection/helpers/detector_spec.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SignalDetection::Helpers::Detector do
+  subject(:detector) { described_class.new(domain: :threat) }
+
+  describe '#initialize' do
+    it 'assigns an id' do
+      expect(detector.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets domain' do
+      expect(detector.domain).to eq(:threat)
+    end
+
+    it 'starts with default sensitivity' do
+      expect(detector.sensitivity).to eq(Legion::Extensions::SignalDetection::Helpers::Constants::DEFAULT_SENSITIVITY)
+    end
+
+    it 'starts with default criterion' do
+      expect(detector.criterion).to eq(Legion::Extensions::SignalDetection::Helpers::Constants::DEFAULT_CRITERION)
+    end
+
+    it 'starts with zero counts' do
+      expect(detector.hits).to eq(0)
+      expect(detector.misses).to eq(0)
+      expect(detector.false_alarms).to eq(0)
+      expect(detector.correct_rejections).to eq(0)
+      expect(detector.trial_count).to eq(0)
+    end
+  end
+
+  describe '#record_trial' do
+    it 'increments hits on :hit' do
+      detector.record_trial(outcome: :hit)
+      expect(detector.hits).to eq(1)
+      expect(detector.trial_count).to eq(1)
+    end
+
+    it 'increments misses on :miss' do
+      detector.record_trial(outcome: :miss)
+      expect(detector.misses).to eq(1)
+    end
+
+    it 'increments false_alarms on :false_alarm' do
+      detector.record_trial(outcome: :false_alarm)
+      expect(detector.false_alarms).to eq(1)
+    end
+
+    it 'increments correct_rejections on :correct_rejection' do
+      detector.record_trial(outcome: :correct_rejection)
+      expect(detector.correct_rejections).to eq(1)
+    end
+
+    it 'raises on invalid outcome' do
+      expect { detector.record_trial(outcome: :bogus) }.to raise_error(ArgumentError, /invalid outcome/)
+    end
+
+    it 'updates last_trial_at' do
+      expect(detector.last_trial_at).to be_nil
+      detector.record_trial(outcome: :hit)
+      expect(detector.last_trial_at).to be_a(Time)
+    end
+  end
+
+  describe '#hit_rate' do
+    it 'applies Hautus correction' do
+      expect(detector.hit_rate).to be_between(0.0, 1.0)
+    end
+
+    it 'increases as hits accumulate' do
+      before = detector.hit_rate
+      5.times { detector.record_trial(outcome: :hit) }
+      expect(detector.hit_rate).to be > before
+    end
+  end
+
+  describe '#false_alarm_rate' do
+    it 'applies Hautus correction' do
+      expect(detector.false_alarm_rate).to be_between(0.0, 1.0)
+    end
+
+    it 'increases as false alarms accumulate' do
+      before = detector.false_alarm_rate
+      5.times { detector.record_trial(outcome: :false_alarm) }
+      expect(detector.false_alarm_rate).to be > before
+    end
+  end
+
+  describe '#compute_dprime' do
+    it 'returns a float within sensitivity bounds' do
+      5.times { detector.record_trial(outcome: :hit) }
+      2.times { detector.record_trial(outcome: :miss) }
+      2.times { detector.record_trial(outcome: :false_alarm) }
+      3.times { detector.record_trial(outcome: :correct_rejection) }
+      expect(detector.compute_dprime).to be_between(
+        Legion::Extensions::SignalDetection::Helpers::Constants::SENSITIVITY_FLOOR,
+        Legion::Extensions::SignalDetection::Helpers::Constants::SENSITIVITY_CEILING
+      )
+    end
+
+    it 'is positive when hit_rate > false_alarm_rate' do
+      10.times { detector.record_trial(outcome: :hit) }
+      detector.record_trial(outcome: :false_alarm)
+      expect(detector.compute_dprime).to be > 0
+    end
+  end
+
+  describe '#compute_criterion' do
+    it 'returns a float within criterion bounds' do
+      5.times { detector.record_trial(outcome: :hit) }
+      5.times { detector.record_trial(outcome: :miss) }
+      result = detector.compute_criterion
+      expect(result).to be_between(
+        Legion::Extensions::SignalDetection::Helpers::Constants::CRITERION_FLOOR,
+        Legion::Extensions::SignalDetection::Helpers::Constants::CRITERION_CEILING
+      )
+    end
+  end
+
+  describe '#accuracy' do
+    it 'returns 0.0 with no trials' do
+      expect(detector.accuracy).to eq(0.0)
+    end
+
+    it 'computes correctly' do
+      3.times { detector.record_trial(outcome: :hit) }
+      2.times { detector.record_trial(outcome: :correct_rejection) }
+      expect(detector.accuracy).to eq(1.0)
+    end
+
+    it 'decreases with errors' do
+      2.times { detector.record_trial(outcome: :hit) }
+      2.times { detector.record_trial(outcome: :miss) }
+      2.times { detector.record_trial(outcome: :false_alarm) }
+      2.times { detector.record_trial(outcome: :correct_rejection) }
+      expect(detector.accuracy).to eq(0.5)
+    end
+  end
+
+  describe '#sensitivity_label' do
+    it 'returns a symbol' do
+      expect(detector.sensitivity_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#bias_label' do
+    it 'returns a symbol' do
+      expect(detector.bias_label).to be_a(Symbol)
+    end
+  end
+
+  describe '#adjust_criterion' do
+    it 'shifts criterion by amount' do
+      initial = detector.criterion
+      detector.adjust_criterion(amount: 0.5)
+      expect(detector.criterion).to eq(initial + 0.5)
+    end
+
+    it 'clamps at ceiling' do
+      detector.adjust_criterion(amount: 10.0)
+      expect(detector.criterion).to eq(Legion::Extensions::SignalDetection::Helpers::Constants::CRITERION_CEILING)
+    end
+
+    it 'clamps at floor' do
+      detector.adjust_criterion(amount: -10.0)
+      expect(detector.criterion).to eq(Legion::Extensions::SignalDetection::Helpers::Constants::CRITERION_FLOOR)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      result = detector.to_h
+      expect(result).to include(:id, :domain, :sensitivity, :criterion, :hits, :misses,
+                                :false_alarms, :correct_rejections, :trial_count,
+                                :hit_rate, :false_alarm_rate, :accuracy,
+                                :sensitivity_label, :bias_label, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/signal_detection/runners/signal_detection_spec.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/signal_detection/client'
+
+RSpec.describe Legion::Extensions::SignalDetection::Runners::SignalDetection do
+  let(:client) { Legion::Extensions::SignalDetection::Client.new }
+
+  describe '#create_detector' do
+    it 'creates a detector and returns id' do
+      result = client.create_detector(domain: :threat)
+      expect(result[:created]).to be true
+      expect(result[:detector_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:domain]).to eq(:threat)
+    end
+  end
+
+  describe '#record_detection_trial' do
+    it 'records a hit' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: true, responded_present: true)
+      expect(result[:outcome]).to eq(:hit)
+      expect(result[:trial_count]).to eq(1)
+    end
+
+    it 'records a miss' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: true, responded_present: false)
+      expect(result[:outcome]).to eq(:miss)
+    end
+
+    it 'records a false alarm' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: false, responded_present: true)
+      expect(result[:outcome]).to eq(:false_alarm)
+    end
+
+    it 'records a correct rejection' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.record_detection_trial(detector_id: id, signal_present: false, responded_present: false)
+      expect(result[:outcome]).to eq(:correct_rejection)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.record_detection_trial(detector_id: 'nonexistent', signal_present: true, responded_present: true)
+      expect(result[:reason]).to eq(:not_found)
+    end
+  end
+
+  describe '#compute_detector_sensitivity' do
+    let(:detector_id) do
+      id = client.create_detector(domain: :test)[:detector_id]
+      8.times { client.record_detection_trial(detector_id: id, signal_present: true, responded_present: true) }
+      2.times { client.record_detection_trial(detector_id: id, signal_present: false, responded_present: true) }
+      id
+    end
+
+    it 'returns d_prime and criterion' do
+      result = client.compute_detector_sensitivity(detector_id: detector_id)
+      expect(result).to include(:d_prime, :criterion, :accuracy)
+    end
+
+    it 'returns sensitivity_label' do
+      result = client.compute_detector_sensitivity(detector_id: detector_id)
+      expect(result[:sensitivity_label]).to be_a(Symbol)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.compute_detector_sensitivity(detector_id: 'unknown')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#adjust_detector_bias' do
+    it 'shifts the criterion' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.adjust_detector_bias(detector_id: id, amount: 0.5)
+      expect(result[:criterion]).to be > 0.0
+      expect(result[:bias_label]).to be_a(Symbol)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.adjust_detector_bias(detector_id: 'none', amount: 0.1)
+      expect(result[:adjusted]).to be false
+    end
+  end
+
+  describe '#best_detectors' do
+    it 'returns list sorted by sensitivity' do
+      client.create_detector(domain: :A)
+      client.create_detector(domain: :B)
+      result = client.best_detectors(limit: 2)
+      expect(result[:count]).to eq(2)
+      expect(result[:detectors]).to be_an(Array)
+    end
+  end
+
+  describe '#domain_detectors' do
+    it 'filters by domain' do
+      client.create_detector(domain: :audio)
+      client.create_detector(domain: :audio)
+      client.create_detector(domain: :visual)
+      result = client.domain_detectors(domain: :audio)
+      expect(result[:count]).to eq(2)
+      expect(result[:domain]).to eq(:audio)
+    end
+  end
+
+  describe '#optimal_detector_criterion' do
+    it 'returns optimal criterion for balanced prior' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.optimal_detector_criterion(detector_id: id, signal_probability: 0.5)
+      expect(result[:optimal_criterion]).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.optimal_detector_criterion(detector_id: 'none')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#detector_roc_point' do
+    it 'returns hit_rate and false_alarm_rate' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      result = client.detector_roc_point(detector_id: id)
+      expect(result).to include(:hit_rate, :false_alarm_rate, :d_prime)
+    end
+
+    it 'returns not_found for unknown detector' do
+      result = client.detector_roc_point(detector_id: 'none')
+      expect(result[:found]).to be false
+    end
+  end
+
+  describe '#update_signal_detection' do
+    it 'runs decay cycle' do
+      id = client.create_detector(domain: :test)[:detector_id]
+      client.record_detection_trial(detector_id: id, signal_present: true, responded_present: true)
+      result = client.update_signal_detection
+      expect(result).to include(:decayed)
+    end
+  end
+
+  describe '#signal_detection_stats' do
+    it 'returns total_detectors and top_detectors' do
+      2.times { |i| client.create_detector(domain: :"d#{i}") }
+      result = client.signal_detection_stats
+      expect(result[:total_detectors]).to eq(2)
+      expect(result[:top_detectors]).to be_an(Array)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/signal_detection'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-signal-detection
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 'Green & Swets'' Signal Detection Theory engine for LegionIO: sensitivity
+  (d'') and response bias (criterion) modeling'
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-signal-detection.gemspec
+- lib/legion/extensions/signal_detection.rb
+- lib/legion/extensions/signal_detection/client.rb
+- lib/legion/extensions/signal_detection/helpers/constants.rb
+- lib/legion/extensions/signal_detection/helpers/detection_engine.rb
+- lib/legion/extensions/signal_detection/helpers/detector.rb
+- lib/legion/extensions/signal_detection/runners/signal_detection.rb
+- lib/legion/extensions/signal_detection/version.rb
+- spec/legion/extensions/signal_detection/client_spec.rb
+- spec/legion/extensions/signal_detection/helpers/constants_spec.rb
+- spec/legion/extensions/signal_detection/helpers/detection_engine_spec.rb
+- spec/legion/extensions/signal_detection/helpers/detector_spec.rb
+- spec/legion/extensions/signal_detection/runners/signal_detection_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-signal-detection
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-signal-detection
+  source_code_uri: https://github.com/LegionIO/lex-signal-detection
+  documentation_uri: https://github.com/LegionIO/lex-signal-detection
+  changelog_uri: https://github.com/LegionIO/lex-signal-detection
+  bug_tracker_uri: https://github.com/LegionIO/lex-signal-detection/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Signal Detection
+test_files: []