lex-cognitive-fingerprint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e72365652af428c7183e63627b14ab4f0d67519db773b2569cb61c557c2dac5
+  data.tar.gz: 5cca9e06f5d51d970c4c814bc17ab8e4aef1edb678b270c3bc8db4ac208d52d0
+SHA512:
+  metadata.gz: 72c9955b658f540ff1907f381dc383acb956cba28166df7b69303a6a130638466d8f6fd1917eb2e965eaf854c8504c675a74eeaed99804193355225c0a05de20
+  data.tar.gz: 2085190392b9539481d25eaff325525fa68aa6bb27253af185f987eb5989797ac3942df9204d6e0c4c4c5ef74d0c9f72f7699c72d0c734d0cef64165e30dda11

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,49 @@
+# lex-cognitive-fingerprint
+
+Behavioral fingerprinting and identity verification for cognitive entities in the LegionIO ecosystem.
+
+## What It Does
+
+Builds a stable behavioral fingerprint by recording observations across eight trait dimensions: processing_speed, accuracy, creativity, caution, thoroughness, risk_tolerance, abstraction_preference, and social_orientation. Each observation updates a per-trait Exponential Moving Average baseline. Once a profile is established, identity verification compares a new set of observations against the fingerprint and returns a match score and verdict. Single-observation anomaly detection flags deviations that exceed the deviation threshold.
+
+The fingerprint hash is a 16-character SHA256 derived from all trait baselines, providing a compact comparison key.
+
+## Usage
+
+```ruby
+require 'legion/extensions/cognitive_fingerprint'
+
+client = Legion::Extensions::CognitiveFingerprint::Client.new
+
+# Build a fingerprint by recording observations
+client.record_observation(category: :accuracy, value: 0.85)
+client.record_observation(category: :caution, value: 0.72)
+client.record_observation(category: :creativity, value: 0.60)
+
+# Check identity confidence once enough observations are recorded
+client.identity_confidence
+# => { confidence: 0.24, label: :uncertain }
+
+# Verify identity against a set of new observations
+client.verify_identity(observations: [
+  { category: :accuracy,   value: 0.83 },
+  { category: :caution,    value: 0.75 }
+])
+# => { match_score: 0.93, verdict: :verified, observations_checked: 2 }
+
+# Check single-observation anomaly
+client.anomaly_check(category: :accuracy, value: 0.1)
+# => { anomaly: true, deviation: 0.75, threshold: 0.3, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-fingerprint.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_fingerprint/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-fingerprint'
+  spec.version       = Legion::Extensions::CognitiveFingerprint::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Fingerprint'
+  spec.description   = 'Unique cognitive identity tracking via emergent trait patterns for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-fingerprint'
+  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-fingerprint'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-fingerprint'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-fingerprint'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-fingerprint/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-fingerprint.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_fingerprint/helpers/constants'
+require 'legion/extensions/cognitive_fingerprint/helpers/cognitive_trait'
+require 'legion/extensions/cognitive_fingerprint/helpers/fingerprint_engine'
+require 'legion/extensions/cognitive_fingerprint/runners/cognitive_fingerprint'
+
+module Legion
+  module Extensions
+    module CognitiveFingerprint
+      class Client
+        include Runners::CognitiveFingerprint
+
+        def initialize(**)
+          @fingerprint_engine = Helpers::FingerprintEngine.new
+        end
+
+        private
+
+        attr_reader :fingerprint_engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_fingerprint/helpers/cognitive_trait.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveFingerprint
+      module Helpers
+        class CognitiveTrait
+          attr_reader :id, :category, :baseline, :variance, :sample_count, :last_updated
+
+          def initialize(category:)
+            raise ArgumentError, "unknown category: #{category}" unless Constants::TRAIT_CATEGORIES.include?(category)
+
+            @id           = SecureRandom.uuid
+            @category     = category
+            @baseline     = 0.5
+            @variance     = 0.0
+            @sample_count = 0
+            @last_updated = Time.now.utc
+          end
+
+          def record_sample!(value)
+            clamped = value.clamp(0.0, 1.0)
+            old_baseline = @baseline
+            @baseline = ((Constants::EMA_ALPHA * clamped) + ((1.0 - Constants::EMA_ALPHA) * old_baseline)).round(10)
+
+            deviation = (clamped - @baseline).abs
+            @variance = ((Constants::EMA_ALPHA * deviation) + ((1.0 - Constants::EMA_ALPHA) * @variance)).round(10)
+
+            @sample_count = [@sample_count + 1, Constants::MAX_SAMPLES].min
+            @last_updated = Time.now.utc
+            self
+          end
+
+          def deviation_from(value)
+            (value.clamp(0.0, 1.0) - @baseline).abs.round(10)
+          end
+
+          def stable?
+            @variance <= 0.1
+          end
+
+          def volatile?
+            @variance >= 0.3
+          end
+
+          def strength_label
+            Constants.trait_strength_label_for(@baseline)
+          end
+
+          def to_h
+            {
+              id:           @id,
+              category:     @category,
+              baseline:     @baseline,
+              variance:     @variance,
+              sample_count: @sample_count,
+              stable:       stable?,
+              volatile:     volatile?,
+              strength:     strength_label,
+              last_updated: @last_updated
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFingerprint
+      module Helpers
+        module Constants
+          MAX_TRAITS   = 100
+          MAX_SAMPLES  = 500
+          EMA_ALPHA    = 0.15
+
+          TRAIT_CATEGORIES = %i[
+            processing_speed
+            accuracy
+            creativity
+            caution
+            thoroughness
+            risk_tolerance
+            abstraction_preference
+            social_orientation
+          ].freeze
+
+          DEVIATION_THRESHOLD = 0.3
+
+          IDENTITY_CONFIDENCE_LABELS = [
+            { range: (0.85..1.0), label: :certain },
+            { range: (0.65...0.85), label: :confident },
+            { range: (0.40...0.65), label: :developing },
+            { range: (0.20...0.40), label: :uncertain },
+            { range: (0.0...0.20),  label: :unknown }
+          ].freeze
+
+          TRAIT_STRENGTH_LABELS = [
+            { range: (0.80..1.0), label: :dominant },
+            { range: (0.60...0.80), label: :strong },
+            { range: (0.40...0.60), label: :moderate },
+            { range: (0.20...0.40), label: :weak },
+            { range: (0.0...0.20),  label: :absent }
+          ].freeze
+
+          module_function
+
+          def identity_label_for(confidence)
+            entry = IDENTITY_CONFIDENCE_LABELS.find { |e| e[:range].cover?(confidence) }
+            entry ? entry[:label] : :unknown
+          end
+
+          def trait_strength_label_for(value)
+            entry = TRAIT_STRENGTH_LABELS.find { |e| e[:range].cover?(value) }
+            entry ? entry[:label] : :absent
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_fingerprint/helpers/fingerprint_engine.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFingerprint
+      module Helpers
+        class FingerprintEngine
+          attr_reader :samples
+
+          def initialize
+            @traits  = {}
+            @samples = []
+          end
+
+          def record_observation(category:, value:)
+            return { status: :invalid_category, category: category } unless Constants::TRAIT_CATEGORIES.include?(category)
+
+            trait = get_or_create_trait(category)
+            trait.record_sample!(value.clamp(0.0, 1.0))
+
+            @samples << { category: category, value: value.clamp(0.0, 1.0), recorded_at: Time.now.utc }
+            @samples.shift while @samples.size > Constants::MAX_SAMPLES
+
+            {
+              status:   :recorded,
+              category: category,
+              baseline: trait.baseline,
+              variance: trait.variance,
+              samples:  trait.sample_count
+            }
+          end
+
+          def verify_identity(observations:)
+            return { match_score: 0.0, verdict: :insufficient_data } if observations.empty? || @traits.empty?
+
+            scored = score_observations(observations)
+            return { match_score: 0.0, verdict: :insufficient_data } if scored.empty?
+
+            score = (scored.sum / scored.size).round(10)
+            { match_score: score, verdict: score_verdict(score), observations_checked: scored.size }
+          end
+
+          def trait_profile
+            @traits.transform_values(&:baseline)
+          end
+
+          def strongest_traits(top_n = 3)
+            @traits.values
+                   .sort_by { |t| -t.baseline }
+                   .first(top_n)
+                   .map(&:to_h)
+          end
+
+          def weakest_traits(top_n = 3)
+            @traits.values
+                   .sort_by(&:baseline)
+                   .first(top_n)
+                   .map(&:to_h)
+          end
+
+          def identity_confidence
+            return 0.0 if @traits.empty?
+
+            stable_count = @traits.values.count(&:stable?)
+            sampled      = @traits.values.select { |t| t.sample_count.positive? }
+            return 0.0 if sampled.empty?
+
+            coverage  = sampled.size.to_f / Constants::TRAIT_CATEGORIES.size
+            stability = stable_count.to_f / @traits.size
+
+            ((coverage * 0.6) + (stability * 0.4)).round(10).clamp(0.0, 1.0)
+          end
+
+          def identity_label
+            Constants.identity_label_for(identity_confidence)
+          end
+
+          def anomaly_check(category:, value:)
+            trait = @traits[category]
+            return { anomaly: false, reason: :no_baseline } unless trait
+
+            dev     = trait.deviation_from(value.clamp(0.0, 1.0))
+            anomaly = dev >= Constants::DEVIATION_THRESHOLD
+            {
+              anomaly:   anomaly,
+              category:  category,
+              value:     value.clamp(0.0, 1.0),
+              baseline:  trait.baseline,
+              deviation: dev.round(10),
+              threshold: Constants::DEVIATION_THRESHOLD
+            }
+          end
+
+          def fingerprint_hash
+            return nil if @traits.empty?
+
+            profile_string = Constants::TRAIT_CATEGORIES.map do |cat|
+              t = @traits[cat]
+              t ? "#{cat}:#{t.baseline.round(6)}" : "#{cat}:nil"
+            end.join('|')
+
+            require 'digest'
+            ::Digest::SHA256.hexdigest(profile_string)[0, 16]
+          end
+
+          def trait_count
+            @traits.size
+          end
+
+          def sample_count
+            @samples.size
+          end
+
+          def fingerprint_report
+            {
+              fingerprint_hash:    fingerprint_hash,
+              identity_confidence: identity_confidence,
+              identity_label:      identity_label,
+              trait_count:         trait_count,
+              sample_count:        @samples.size,
+              traits:              @traits.transform_values(&:to_h)
+            }
+          end
+
+          def to_h
+            fingerprint_report
+          end
+
+          private
+
+          def score_observations(observations)
+            observations.filter_map do |obs|
+              cat   = obs[:category]
+              val   = obs[:value]
+              trait = @traits[cat]
+              next unless trait && Constants::TRAIT_CATEGORIES.include?(cat)
+
+              dev = trait.deviation_from(val.clamp(0.0, 1.0))
+              [1.0 - (dev / [Constants::DEVIATION_THRESHOLD, 0.001].max), 0.0].max.clamp(0.0, 1.0)
+            end
+          end
+
+          def score_verdict(score)
+            if score >= 0.7
+              :verified
+            elsif score >= 0.4
+              :uncertain
+            else
+              :mismatch
+            end
+          end
+
+          def get_or_create_trait(category)
+            @traits[category] ||= CognitiveTrait.new(category: category)
+            if @traits.size > Constants::MAX_TRAITS
+              oldest_key = @traits.min_by { |_, t| t.last_updated }.first
+              @traits.delete(oldest_key)
+            end
+            @traits[category]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveFingerprint
+      module Runners
+        module CognitiveFingerprint
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def record_observation(category:, value:, **)
+            category = category.to_sym
+            result   = fingerprint_engine.record_observation(category: category, value: value.to_f)
+            Legion::Logging.debug "[cognitive_fingerprint] record category=#{category} " \
+                                  "baseline=#{result[:baseline]&.round(4)} samples=#{result[:samples]}"
+            result
+          end
+
+          def verify_identity(observations:, **)
+            parsed = Array(observations).map do |obs|
+              { category: obs[:category].to_sym, value: obs[:value].to_f }
+            end
+            result = fingerprint_engine.verify_identity(observations: parsed)
+            Legion::Logging.info "[cognitive_fingerprint] verify score=#{result[:match_score]&.round(4)} " \
+                                 "verdict=#{result[:verdict]}"
+            result
+          end
+
+          def anomaly_check(category:, value:, **)
+            result = fingerprint_engine.anomaly_check(category: category.to_sym, value: value.to_f)
+            if result[:anomaly]
+              Legion::Logging.warn "[cognitive_fingerprint] anomaly category=#{category} " \
+                                   "deviation=#{result[:deviation]&.round(4)}"
+            end
+            result
+          end
+
+          def trait_profile(**)
+            { profile: fingerprint_engine.trait_profile }
+          end
+
+          def strongest_traits(top_n: 3, **)
+            { traits: fingerprint_engine.strongest_traits(top_n.to_i) }
+          end
+
+          def weakest_traits(top_n: 3, **)
+            { traits: fingerprint_engine.weakest_traits(top_n.to_i) }
+          end
+
+          def identity_confidence(**)
+            confidence = fingerprint_engine.identity_confidence
+            label      = fingerprint_engine.identity_label
+            Legion::Logging.debug "[cognitive_fingerprint] confidence=#{confidence.round(4)} label=#{label}"
+            { confidence: confidence, label: label }
+          end
+
+          def fingerprint_hash(**)
+            { fingerprint_hash: fingerprint_engine.fingerprint_hash }
+          end
+
+          def fingerprint_report(**)
+            fingerprint_engine.fingerprint_report
+          end
+
+          def fingerprint_status(**)
+            {
+              trait_count:  fingerprint_engine.trait_count,
+              sample_count: fingerprint_engine.sample_count,
+              label:        fingerprint_engine.identity_label
+            }
+          end
+
+          private
+
+          def fingerprint_engine
+            @fingerprint_engine ||= Helpers::FingerprintEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_fingerprint.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_fingerprint/version'
+require 'legion/extensions/cognitive_fingerprint/helpers/constants'
+require 'legion/extensions/cognitive_fingerprint/helpers/cognitive_trait'
+require 'legion/extensions/cognitive_fingerprint/helpers/fingerprint_engine'
+require 'legion/extensions/cognitive_fingerprint/runners/cognitive_fingerprint'
+
+module Legion
+  module Extensions
+    module CognitiveFingerprint
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_fingerprint/client'
+
+RSpec.describe Legion::Extensions::CognitiveFingerprint::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to record_observation' do
+    expect(client).to respond_to(:record_observation)
+  end
+
+  it 'responds to verify_identity' do
+    expect(client).to respond_to(:verify_identity)
+  end
+
+  it 'responds to anomaly_check' do
+    expect(client).to respond_to(:anomaly_check)
+  end
+
+  it 'responds to trait_profile' do
+    expect(client).to respond_to(:trait_profile)
+  end
+
+  it 'responds to strongest_traits' do
+    expect(client).to respond_to(:strongest_traits)
+  end
+
+  it 'responds to weakest_traits' do
+    expect(client).to respond_to(:weakest_traits)
+  end
+
+  it 'responds to identity_confidence' do
+    expect(client).to respond_to(:identity_confidence)
+  end
+
+  it 'responds to fingerprint_hash' do
+    expect(client).to respond_to(:fingerprint_hash)
+  end
+
+  it 'responds to fingerprint_report' do
+    expect(client).to respond_to(:fingerprint_report)
+  end
+
+  it 'responds to fingerprint_status' do
+    expect(client).to respond_to(:fingerprint_status)
+  end
+
+  it 'each instance has independent state' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.record_observation(category: :accuracy, value: 0.9)
+    expect(c2.fingerprint_status[:trait_count]).to eq(0)
+  end
+end