lex-cognitive-immunology 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5ef857f308ed2f088519c8105a9875d622ea045760b68e44c789bd2903288af0
+  data.tar.gz: 71b3c2d6846f87bdce12a781b83f74276550bc796fc72337a3ce9726c5adc952
+SHA512:
+  metadata.gz: 0ebd1e41f872b4d8bdffd40f424bb1850bf25f3577810289c3c6c181bc30cebf34a0b1bf81ae07cad37767ed4a41e7d5c8020c6c6fcb04c078b9c24d140a49ae
+  data.tar.gz: 7397a05f8c5ba4b258cfda02e66c49a83e8711b596426cbae5d6a048a70a905baa59666e870f2619c38277a1d85ecc8f22cced31b42e9a474e2dcfbf20d694da

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-immunology.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_immunology/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-immunology'
+  spec.version       = Legion::Extensions::CognitiveImmunology::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Immunology'
+  spec.description   = 'Cognitive immune system for brain-modeled agentic AI — defense against memetic threats, manipulation, and cognitive viruses'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-immunology'
+  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-immunology'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-immunology'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-immunology'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-immunology/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-immunology.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_immunology/helpers/constants'
+require 'legion/extensions/cognitive_immunology/helpers/threat'
+require 'legion/extensions/cognitive_immunology/helpers/antibody'
+require 'legion/extensions/cognitive_immunology/helpers/immune_engine'
+require 'legion/extensions/cognitive_immunology/runners/cognitive_immunology'
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      class Client
+        include Runners::CognitiveImmunology
+
+        def initialize(**)
+          @engine = Helpers::ImmuneEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_immunology/helpers/antibody.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      module Helpers
+        class Antibody
+          attr_reader :id, :tactic, :pattern, :created_at
+          attr_accessor :strength, :matches
+
+          def initialize(tactic:, pattern:, strength: 0.5)
+            @id       = SecureRandom.uuid
+            @tactic   = tactic
+            @pattern  = pattern
+            @strength = strength.clamp(0.0, 1.0)
+            @matches  = 0
+            @created_at = Time.now.utc
+          end
+
+          def match!
+            @matches += 1
+            boost = Constants::RESISTANCE_BOOST / (@matches + 1)
+            @strength = (@strength + boost.round(10)).clamp(0.0, 1.0).round(10)
+          end
+
+          def decay!
+            @strength = (@strength - Constants::RESISTANCE_DECAY).clamp(0.0, 1.0).round(10)
+          end
+
+          def effective?
+            @strength >= 0.3
+          end
+
+          def to_h
+            {
+              id:         @id,
+              tactic:     @tactic,
+              pattern:    @pattern,
+              strength:   @strength,
+              matches:    @matches,
+              effective:  effective?,
+              created_at: @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      module Helpers
+        module Constants
+          DEFAULT_RESISTANCE = 0.5
+          RESISTANCE_BOOST   = 0.1
+          RESISTANCE_DECAY   = 0.02
+          MAX_THREATS        = 500
+          MAX_ANTIBODIES     = 200
+
+          THREAT_LABELS = {
+            (0.8..)     => :critical,
+            (0.6...0.8) => :severe,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :low,
+            (..0.2)     => :negligible
+          }.freeze
+
+          IMMUNITY_LABELS = {
+            (0.8..)     => :immune,
+            (0.6...0.8) => :resistant,
+            (0.4...0.6) => :normal,
+            (0.2...0.4) => :vulnerable,
+            (..0.2)     => :compromised
+          }.freeze
+
+          MANIPULATION_TACTICS = %i[
+            authority_appeal emotional_blackmail false_urgency
+            social_proof_abuse gaslighting strawman ad_hominem
+            sunk_cost_exploit bandwagon fear_mongering
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_immunology/helpers/immune_engine.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      module Helpers
+        class ImmuneEngine
+          attr_reader :resistance, :inflammatory
+
+          def initialize
+            @threats      = {}
+            @antibodies   = {}
+            @resistance   = Constants::DEFAULT_RESISTANCE
+            @inflammatory = false
+          end
+
+          def detect_threat(source:, tactic:, content_hash:, threat_level: 0.5)
+            prune_threats_if_full
+
+            threat = Threat.new(
+              source:       source,
+              tactic:       tactic,
+              content_hash: content_hash,
+              threat_level: threat_level
+            )
+
+            matched = match_antibodies_for_tactic(tactic)
+            matched.each do |ab|
+              ab.match!
+              reduction = (ab.strength * 0.2).round(10)
+              threat.threat_level = (threat.threat_level - reduction).clamp(0.0, 1.0).round(10)
+            end
+
+            @threats[threat.id] = threat
+            Legion::Logging.debug "[cognitive_immunology] threat detected: id=#{threat.id} tactic=#{tactic} level=#{threat.threat_level.round(2)}"
+            threat
+          end
+
+          def quarantine_threat(threat_id:)
+            threat = @threats.fetch(threat_id, nil)
+            return { success: false, reason: 'not found' } unless threat
+
+            threat.quarantine!
+            Legion::Logging.info "[cognitive_immunology] quarantined: id=#{threat_id} tactic=#{threat.tactic}"
+            { success: true, threat_id: threat_id }
+          end
+
+          def release_threat(threat_id:)
+            threat = @threats.fetch(threat_id, nil)
+            return { success: false, reason: 'not found' } unless threat
+
+            threat.release!
+            Legion::Logging.debug "[cognitive_immunology] released: id=#{threat_id}"
+            { success: true, threat_id: threat_id }
+          end
+
+          def inoculate(threat_id:)
+            threat = @threats.fetch(threat_id, nil)
+            return { success: false, reason: 'not found' } unless threat
+
+            threat.expose!
+            boost = (Constants::RESISTANCE_BOOST / (threat.exposure_count + 1)).round(10)
+            @resistance = (@resistance + boost).clamp(0.0, 1.0).round(10)
+            Legion::Logging.debug "[cognitive_immunology] inoculate: id=#{threat_id} exposure=#{threat.exposure_count} resistance=#{@resistance.round(2)}"
+            { success: true, threat_id: threat_id, exposure_count: threat.exposure_count, resistance: @resistance }
+          end
+
+          def create_antibody(tactic:, pattern:, strength: 0.5)
+            prune_antibodies_if_full
+
+            ab = Antibody.new(tactic: tactic, pattern: pattern, strength: strength)
+            @antibodies[ab.id] = ab
+            Legion::Logging.info "[cognitive_immunology] antibody created: id=#{ab.id} tactic=#{tactic} strength=#{strength}"
+            ab
+          end
+
+          def scan_for_tactic(tactic:)
+            @threats.values.select { |t| t.tactic == tactic }
+          end
+
+          def trigger_inflammatory_response
+            @inflammatory = true
+            Legion::Logging.warn '[cognitive_immunology] inflammatory response triggered — heightened scrutiny mode'
+            { inflammatory: true }
+          end
+
+          def resolve_inflammation
+            @inflammatory = false
+            Legion::Logging.info '[cognitive_immunology] inflammation resolved — returning to normal scrutiny'
+            { inflammatory: false }
+          end
+
+          def overall_immunity
+            ab_coverage = antibody_coverage_score
+            score = ((@resistance * 0.6) + (ab_coverage * 0.4)).round(10)
+            score.clamp(0.0, 1.0)
+          end
+
+          def immunity_label
+            score = overall_immunity
+            Constants::IMMUNITY_LABELS.find { |range, _| range.cover?(score) }&.last || :compromised
+          end
+
+          def vulnerability_report
+            covered_tactics = @antibodies.values.map(&:tactic).uniq
+            uncovered = Constants::MANIPULATION_TACTICS.reject { |t| covered_tactics.include?(t) }
+            {
+              covered:   covered_tactics,
+              uncovered: uncovered,
+              coverage:  (covered_tactics.size.to_f / Constants::MANIPULATION_TACTICS.size).round(10)
+            }
+          end
+
+          def threat_history(limit: 10)
+            @threats.values
+                    .sort_by(&:created_at)
+                    .last(limit)
+                    .map(&:to_h)
+          end
+
+          def decay_all
+            @antibodies.each_value(&:decay!)
+            @resistance = (@resistance - Constants::RESISTANCE_DECAY).clamp(0.0, 1.0).round(10)
+            Legion::Logging.debug "[cognitive_immunology] decay cycle: resistance=#{@resistance.round(2)} antibodies=#{@antibodies.size}"
+            { resistance: @resistance, antibodies_decayed: @antibodies.size }
+          end
+
+          def prune_ineffective
+            before = @antibodies.size
+            @antibodies.select! { |_, ab| ab.effective? }
+            pruned = before - @antibodies.size
+            Legion::Logging.debug "[cognitive_immunology] pruned #{pruned} ineffective antibodies"
+            { pruned: pruned, remaining: @antibodies.size }
+          end
+
+          def to_h
+            {
+              threat_count:             @threats.size,
+              quarantined_count:        @threats.values.count(&:quarantined),
+              antibody_count:           @antibodies.size,
+              effective_antibody_count: @antibodies.values.count(&:effective?),
+              resistance:               @resistance,
+              inflammatory:             @inflammatory,
+              overall_immunity:         overall_immunity,
+              immunity_label:           immunity_label
+            }
+          end
+
+          private
+
+          def match_antibodies_for_tactic(tactic)
+            @antibodies.values.select { |ab| ab.tactic == tactic && ab.effective? }
+          end
+
+          def antibody_coverage_score
+            return 0.0 if @antibodies.empty?
+
+            effective = @antibodies.values.select(&:effective?)
+            return 0.0 if effective.empty?
+
+            avg_strength = effective.sum(&:strength) / effective.size.to_f
+            tactic_coverage = vulnerability_report[:coverage]
+            ((avg_strength * 0.5) + (tactic_coverage * 0.5)).round(10)
+          end
+
+          def prune_threats_if_full
+            return unless @threats.size >= Constants::MAX_THREATS
+
+            oldest = @threats.values.min_by(&:created_at)
+            @threats.delete(oldest.id) if oldest
+          end
+
+          def prune_antibodies_if_full
+            return unless @antibodies.size >= Constants::MAX_ANTIBODIES
+
+            weakest = @antibodies.values.min_by(&:strength)
+            @antibodies.delete(weakest.id) if weakest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_immunology/helpers/threat.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      module Helpers
+        class Threat
+          attr_reader :id, :source, :tactic, :content_hash, :created_at
+          attr_accessor :threat_level, :quarantined, :exposure_count
+
+          def initialize(source:, tactic:, content_hash:, threat_level: 0.5)
+            @id             = SecureRandom.uuid
+            @source         = source
+            @tactic         = tactic
+            @content_hash   = content_hash
+            @threat_level   = threat_level.clamp(0.0, 1.0)
+            @quarantined    = false
+            @exposure_count = 0
+            @created_at     = Time.now.utc
+          end
+
+          def threat_label
+            Constants::THREAT_LABELS.find { |range, _| range.cover?(@threat_level) }&.last || :negligible
+          end
+
+          def quarantine!
+            @quarantined = true
+          end
+
+          def release!
+            @quarantined = false
+          end
+
+          def expose!
+            @exposure_count += 1
+            reduction = (0.05 / (@exposure_count + 1)).round(10)
+            @threat_level = (@threat_level - reduction).clamp(0.0, 1.0).round(10)
+          end
+
+          def escalate!(amount: 0.1)
+            @threat_level = (@threat_level + amount).clamp(0.0, 1.0).round(10)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              source:         @source,
+              tactic:         @tactic,
+              content_hash:   @content_hash,
+              threat_level:   @threat_level,
+              threat_label:   threat_label,
+              quarantined:    @quarantined,
+              exposure_count: @exposure_count,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      module Runners
+        module CognitiveImmunology
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def detect_threat(source:, tactic:, content_hash:, threat_level: 0.5, **)
+            threat = engine.detect_threat(source: source, tactic: tactic, content_hash: content_hash, threat_level: threat_level)
+            { success: true, threat: threat.to_h }
+          end
+
+          def quarantine_threat(threat_id:, **)
+            result = engine.quarantine_threat(threat_id: threat_id)
+            result.merge(success: result.fetch(:success, false))
+          end
+
+          def release_threat(threat_id:, **)
+            result = engine.release_threat(threat_id: threat_id)
+            result.merge(success: result.fetch(:success, false))
+          end
+
+          def inoculate(threat_id:, **)
+            engine.inoculate(threat_id: threat_id)
+          end
+
+          def create_antibody(tactic:, pattern:, strength: 0.5, **)
+            ab = engine.create_antibody(tactic: tactic, pattern: pattern, strength: strength)
+            { success: true, antibody: ab.to_h }
+          end
+
+          def scan_for_tactic(tactic:, **)
+            threats = engine.scan_for_tactic(tactic: tactic)
+            { success: true, tactic: tactic, threats: threats.map(&:to_h), count: threats.size }
+          end
+
+          def trigger_inflammatory_response(**)
+            result = engine.trigger_inflammatory_response
+            { success: true }.merge(result)
+          end
+
+          def resolve_inflammation(**)
+            result = engine.resolve_inflammation
+            { success: true }.merge(result)
+          end
+
+          def overall_immunity(**)
+            score = engine.overall_immunity
+            { success: true, score: score, label: engine.immunity_label }
+          end
+
+          def vulnerability_report(**)
+            report = engine.vulnerability_report
+            { success: true }.merge(report)
+          end
+
+          def threat_history(limit: 10, **)
+            threats = engine.threat_history(limit: limit)
+            { success: true, threats: threats, count: threats.size }
+          end
+
+          def decay_all(**)
+            result = engine.decay_all
+            { success: true }.merge(result)
+          end
+
+          def prune_ineffective(**)
+            result = engine.prune_ineffective
+            { success: true }.merge(result)
+          end
+
+          def immune_status(**)
+            { success: true }.merge(engine.to_h)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::ImmuneEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_immunology.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_immunology/version'
+require 'legion/extensions/cognitive_immunology/helpers/constants'
+require 'legion/extensions/cognitive_immunology/helpers/threat'
+require 'legion/extensions/cognitive_immunology/helpers/antibody'
+require 'legion/extensions/cognitive_immunology/helpers/immune_engine'
+require 'legion/extensions/cognitive_immunology/runners/cognitive_immunology'
+
+module Legion
+  module Extensions
+    module CognitiveImmunology
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveImmunology::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to detect_threat' do
+    expect(client).to respond_to(:detect_threat)
+  end
+
+  it 'responds to quarantine_threat' do
+    expect(client).to respond_to(:quarantine_threat)
+  end
+
+  it 'responds to release_threat' do
+    expect(client).to respond_to(:release_threat)
+  end
+
+  it 'responds to inoculate' do
+    expect(client).to respond_to(:inoculate)
+  end
+
+  it 'responds to create_antibody' do
+    expect(client).to respond_to(:create_antibody)
+  end
+
+  it 'responds to scan_for_tactic' do
+    expect(client).to respond_to(:scan_for_tactic)
+  end
+
+  it 'responds to trigger_inflammatory_response' do
+    expect(client).to respond_to(:trigger_inflammatory_response)
+  end
+
+  it 'responds to resolve_inflammation' do
+    expect(client).to respond_to(:resolve_inflammation)
+  end
+
+  it 'responds to overall_immunity' do
+    expect(client).to respond_to(:overall_immunity)
+  end
+
+  it 'responds to vulnerability_report' do
+    expect(client).to respond_to(:vulnerability_report)
+  end
+
+  it 'responds to threat_history' do
+    expect(client).to respond_to(:threat_history)
+  end
+
+  it 'responds to decay_all' do
+    expect(client).to respond_to(:decay_all)
+  end
+
+  it 'responds to prune_ineffective' do
+    expect(client).to respond_to(:prune_ineffective)
+  end
+
+  it 'responds to immune_status' do
+    expect(client).to respond_to(:immune_status)
+  end
+end

data/spec/legion/extensions/cognitive_immunology/helpers/antibody_spec.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveImmunology::Helpers::Antibody do
+  subject(:antibody) { described_class.new(tactic: :authority_appeal, pattern: 'claimed expert status') }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(antibody.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores tactic' do
+      expect(antibody.tactic).to eq(:authority_appeal)
+    end
+
+    it 'stores pattern' do
+      expect(antibody.pattern).to eq('claimed expert status')
+    end
+
+    it 'defaults strength to 0.5' do
+      expect(antibody.strength).to eq(0.5)
+    end
+
+    it 'defaults matches to 0' do
+      expect(antibody.matches).to eq(0)
+    end
+
+    it 'clamps strength above 1.0' do
+      ab = described_class.new(tactic: :gaslighting, pattern: 'x', strength: 2.0)
+      expect(ab.strength).to eq(1.0)
+    end
+
+    it 'clamps strength below 0.0' do
+      ab = described_class.new(tactic: :gaslighting, pattern: 'x', strength: -1.0)
+      expect(ab.strength).to eq(0.0)
+    end
+  end
+
+  describe '#match!' do
+    it 'increments matches' do
+      antibody.match!
+      expect(antibody.matches).to eq(1)
+    end
+
+    it 'boosts strength' do
+      original = antibody.strength
+      antibody.match!
+      expect(antibody.strength).to be > original
+    end
+
+    it 'does not exceed 1.0' do
+      ab = described_class.new(tactic: :gaslighting, pattern: 'x', strength: 1.0)
+      ab.match!
+      expect(ab.strength).to eq(1.0)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces strength by RESISTANCE_DECAY' do
+      original = antibody.strength
+      antibody.decay!
+      expect(antibody.strength).to be_within(0.001).of(original - Legion::Extensions::CognitiveImmunology::Helpers::Constants::RESISTANCE_DECAY)
+    end
+
+    it 'does not go below 0.0' do
+      ab = described_class.new(tactic: :gaslighting, pattern: 'x', strength: 0.0)
+      ab.decay!
+      expect(ab.strength).to eq(0.0)
+    end
+  end
+
+  describe '#effective?' do
+    it 'returns true when strength >= 0.3' do
+      expect(antibody.effective?).to be true
+    end
+
+    it 'returns false when strength < 0.3' do
+      ab = described_class.new(tactic: :gaslighting, pattern: 'x', strength: 0.1)
+      expect(ab.effective?).to be false
+    end
+
+    it 'returns true at exactly 0.3' do
+      ab = described_class.new(tactic: :gaslighting, pattern: 'x', strength: 0.3)
+      expect(ab.effective?).to be true
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with all fields' do
+      h = antibody.to_h
+      expect(h).to include(:id, :tactic, :pattern, :strength, :matches, :effective, :created_at)
+    end
+
+    it 'includes effective status' do
+      h = antibody.to_h
+      expect(h[:effective]).to be true
+    end
+  end
+end