lex-cognitive-lens 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3557d980fea6c8eea142c7b190c7a7f0f24063a9a3388a557f1376925111628a
+  data.tar.gz: de477b2d12901914644e5bc8ff9ac7e817a8cc64df9a92463f1b9c88102be293
+SHA512:
+  metadata.gz: d9fb3b07164d57fae3bf711262028284c59c08f61351b33b77ab8e8bd5abf1aea186057832df802a2600f1708536dd67565bd4608523577e743610c324019ffc
+  data.tar.gz: 7e6e69debebafc78146271ed8f976e1cca0741aa3516d84ba874059dbde9a7986898e4243dedc8b7a205cee00c21c4a51dc286efd1555b70d0ebd3db0b98f98f

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) 2025 Esity
+
+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,50 @@
+# lex-cognitive-lens
+
+Optical perspective filtering for LegionIO cognitive agents. Models cognitive viewpoints as lenses that can be stacked to produce combined magnification, distortion, and clarity effects on any content.
+
+## What It Does
+
+- Six lens types: `magnifying`, `wide_angle`, `fish_eye`, `polarized`, `telescopic`, `microscopic`
+- Each lens has magnification, aperture, distortion, and clarity attributes
+- Lenses can be focused/defocused, smudged/cleaned
+- Stack multiple lenses: combined effects use diminishing-return magnification and weighted distortion blending
+- `view_through_stack` applies the full pipeline to any content string
+- `degrade_all` simulates environmental smudging across all lenses
+
+## Usage
+
+```ruby
+# Create lenses
+mag = runner.create_lens(lens_type: :magnifying, magnification: 2.5, aperture: 0.7,
+                          distortion: 0.1, clarity: 0.9)
+wide = runner.create_lens(lens_type: :wide_angle, magnification: 0.5, aperture: 0.9,
+                           distortion: 0.2, clarity: 0.8)
+
+# View content through a stack
+result = runner.view_through_stack(
+  lens_ids: [mag[:lens][:id], wide[:lens][:id]],
+  content: 'The root cause is a missing validation layer'
+)
+# => { success: true, magnified_content: ..., distortion_applied: ..., clarity_score: ..., filtered_view: ... }
+
+# Get clearest lenses
+runner.clearest_lenses(limit: 3)
+
+# Degrade all lenses over time
+runner.degrade_all(rate: 0.05)
+
+# Full report
+runner.lens_report
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-lens.gemspec

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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_lens/helpers/constants'
+require 'legion/extensions/cognitive_lens/helpers/lens'
+require 'legion/extensions/cognitive_lens/helpers/lens_stack'
+require 'legion/extensions/cognitive_lens/helpers/lens_engine'
+require 'legion/extensions/cognitive_lens/runners/cognitive_lens'
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      class Client
+        include Runners::CognitiveLens
+
+        def initialize(**)
+          @lens_engine = Helpers::LensEngine.new
+        end
+
+        private
+
+        attr_reader :lens_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      module Helpers
+        module Constants
+          LENS_TYPES = %i[magnifying wide_angle fish_eye polarized telescopic microscopic].freeze
+
+          DISTORTION_TYPES = %i[none barrel pincushion mustache wave spiral].freeze
+
+          MAX_LENSES = 8
+
+          CLARITY_LABELS = [
+            [0.0..0.2,  :opaque],
+            [0.2..0.4,  :foggy],
+            [0.4..0.6,  :hazy],
+            [0.6..0.8,  :clear],
+            [0.8..1.0,  :crystal]
+          ].freeze
+
+          MAGNIFICATION_LABELS = [
+            [0.1..0.5,  :micro],
+            [0.5..1.0,  :normal],
+            [1.0..2.0,  :zoom],
+            [2.0..5.0,  :telephoto],
+            [5.0..10.0, :extreme]
+          ].freeze
+
+          # Default optical properties per lens type
+          LENS_DEFAULTS = {
+            magnifying:  { magnification: 2.0, aperture: 0.6, distortion: 0.1 },
+            wide_angle:  { magnification: 0.5, aperture: 0.9, distortion: 0.2 },
+            fish_eye:    { magnification: 0.3, aperture: 1.0, distortion: 0.8 },
+            polarized:   { magnification: 1.0, aperture: 0.4, distortion: 0.0 },
+            telescopic:  { magnification: 8.0, aperture: 0.3, distortion: 0.15 },
+            microscopic: { magnification: 9.0, aperture: 0.5, distortion: 0.05 }
+          }.freeze
+
+          # Smudge degrades clarity; clean restores it
+          SMUDGE_RATE_DEFAULT    = 0.05
+          CLEAN_BOOST_DEFAULT    = 0.1
+          CLARITY_SHARP_THRESHOLD = 0.7
+          CLARITY_BLURRY_THRESHOLD = 0.35
+
+          # Stack combination weights
+          STACK_MAGNIFICATION_EXPONENT = 0.8 # sub-linear compounding prevents extremes
+          STACK_DISTORTION_BLEND        = 0.6  # weight toward worst distortion
+          STACK_CLARITY_DECAY           = 0.9  # each additional lens costs 10% clarity
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lens/helpers/lens.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      module Helpers
+        class Lens
+          include Constants
+
+          attr_reader :id, :lens_type, :magnification, :clarity, :distortion, :aperture,
+                      :focus_target, :created_at
+
+          def initialize(lens_type:, magnification: nil, clarity: 1.0, distortion: nil, aperture: nil)
+            raise ArgumentError, "unknown lens_type: #{lens_type}" unless Constants::LENS_TYPES.include?(lens_type)
+
+            defaults = Constants::LENS_DEFAULTS.fetch(lens_type)
+
+            @id            = SecureRandom.uuid
+            @lens_type     = lens_type
+            @magnification = (magnification || defaults[:magnification]).clamp(0.1, 10.0).round(10)
+            @clarity       = clarity.clamp(0.0, 1.0).round(10)
+            @distortion    = (distortion || defaults[:distortion]).clamp(0.0, 1.0).round(10)
+            @aperture      = (aperture || defaults[:aperture]).clamp(0.0, 1.0).round(10)
+            @focus_target  = nil
+            @created_at    = Time.now.utc
+          end
+
+          def focus!(target)
+            @focus_target = target
+            self
+          end
+
+          def defocus!
+            @focus_target = nil
+            self
+          end
+
+          def smudge!(rate = Constants::SMUDGE_RATE_DEFAULT)
+            @clarity = (@clarity - rate.clamp(0.0, 1.0)).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def clean!(boost = Constants::CLEAN_BOOST_DEFAULT)
+            @clarity = (@clarity + boost.clamp(0.0, 1.0)).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def sharp?
+            @clarity >= Constants::CLARITY_SHARP_THRESHOLD
+          end
+
+          def blurry?
+            @clarity <= Constants::CLARITY_BLURRY_THRESHOLD
+          end
+
+          def clarity_label
+            Constants::CLARITY_LABELS.find { |range, _| range.cover?(@clarity) }&.last || :crystal
+          end
+
+          def magnification_label
+            Constants::MAGNIFICATION_LABELS.find { |range, _| range.cover?(@magnification) }&.last || :extreme
+          end
+
+          def focused?
+            !@focus_target.nil?
+          end
+
+          def depth_of_field
+            # Larger aperture = shallower depth of field; higher magnification = shallower
+            base = 1.0 - @aperture
+            mag_factor = 1.0 / [magnification, 0.1].max
+            ((base * 0.6) + (mag_factor * 0.4)).clamp(0.0, 1.0).round(10)
+          end
+
+          def to_h
+            {
+              id:                  @id,
+              lens_type:           @lens_type,
+              magnification:       @magnification,
+              clarity:             @clarity,
+              distortion:          @distortion,
+              aperture:            @aperture,
+              focus_target:        @focus_target,
+              sharp:               sharp?,
+              blurry:              blurry?,
+              clarity_label:       clarity_label,
+              magnification_label: magnification_label,
+              depth_of_field:      depth_of_field
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lens/helpers/lens_engine.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      module Helpers
+        class LensEngine
+          include Constants
+
+          attr_reader :lenses, :stacks
+
+          def initialize
+            @lenses = {}
+            @stacks = {}
+          end
+
+          def create_lens(lens_type:, magnification: nil, clarity: 1.0, distortion: nil, aperture: nil, **)
+            lens = Lens.new(
+              lens_type:     lens_type,
+              magnification: magnification,
+              clarity:       clarity,
+              distortion:    distortion,
+              aperture:      aperture
+            )
+            @lenses[lens.id] = lens
+            lens
+          end
+
+          def stack_lenses(lens_ids:, stack_id: nil, **)
+            stack_id ||= SecureRandom.uuid
+            stack = LensStack.new
+
+            lens_ids.each do |lid|
+              lens = @lenses[lid]
+              raise ArgumentError, "lens not found: #{lid}" unless lens
+
+              stack.push_lens(lens)
+            end
+
+            @stacks[stack_id] = stack
+            { stack_id: stack_id, stack: stack }
+          end
+
+          def view_through_stack(stack_id:, content:, **)
+            stack = @stacks[stack_id]
+            raise ArgumentError, "stack not found: #{stack_id}" unless stack
+
+            result = stack.view_through(content)
+            Legion::Logging.debug "[cognitive_lens] view_through stack=#{stack_id} " \
+                                  "perceived=#{result[:perceived].round(4)} " \
+                                  "magnification=#{result[:combined_magnification].round(2)} " \
+                                  "distortion=#{result[:combined_distortion].round(2)} " \
+                                  "clarity=#{result[:stack_clarity].round(2)}"
+            result
+          end
+
+          def degrade_all!(rate: Constants::SMUDGE_RATE_DEFAULT)
+            @lenses.each_value { |l| l.smudge!(rate) }
+            { degraded: @lenses.size, rate: rate }
+          end
+
+          def clearest_lenses(limit: 3)
+            @lenses.values
+                   .sort_by { |l| -l.clarity }
+                   .first(limit)
+                   .map(&:to_h)
+          end
+
+          def most_distorted(limit: 3)
+            @lenses.values
+                   .sort_by { |l| -l.distortion }
+                   .first(limit)
+                   .map(&:to_h)
+          end
+
+          def lens_report
+            return { lens_count: 0, stack_count: 0, lenses: [], stacks: [] } if @lenses.empty?
+
+            avg_clarity    = (@lenses.values.sum(&:clarity) / @lenses.size).round(10)
+            avg_distortion = (@lenses.values.sum(&:distortion) / @lenses.size).round(10)
+
+            {
+              lens_count:     @lenses.size,
+              stack_count:    @stacks.size,
+              avg_clarity:    avg_clarity,
+              avg_distortion: avg_distortion,
+              sharp_count:    @lenses.values.count(&:sharp?),
+              blurry_count:   @lenses.values.count(&:blurry?),
+              lenses:         @lenses.values.map(&:to_h),
+              stacks:         @stacks.transform_values(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_lens/helpers/lens_stack.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      module Helpers
+        class LensStack
+          include Constants
+
+          attr_reader :lenses
+
+          def initialize
+            @lenses = []
+          end
+
+          def push_lens(lens)
+            raise ArgumentError, 'expected a Lens instance' unless lens.is_a?(Lens)
+            raise ArgumentError, "stack is full (max #{Constants::MAX_LENSES})" if @lenses.size >= Constants::MAX_LENSES
+
+            @lenses << lens
+            self
+          end
+
+          def pop_lens
+            @lenses.pop
+          end
+
+          def size
+            @lenses.size
+          end
+
+          def empty?
+            @lenses.empty?
+          end
+
+          def combined_magnification
+            return 1.0 if @lenses.empty?
+
+            # Sub-linear compounding via exponent to avoid extreme values
+            base = @lenses.reduce(1.0) { |acc, l| acc * l.magnification }
+            base**Constants::STACK_MAGNIFICATION_EXPONENT
+          end
+
+          def combined_distortion
+            return 0.0 if @lenses.empty?
+
+            max_dist   = @lenses.map(&:distortion).max
+            mean_dist  = @lenses.sum(&:distortion) / @lenses.size
+            # Blend toward worst distortion
+            ((max_dist * Constants::STACK_DISTORTION_BLEND) +
+             (mean_dist * (1.0 - Constants::STACK_DISTORTION_BLEND))).clamp(0.0, 1.0).round(10)
+          end
+
+          def stack_clarity
+            return 1.0 if @lenses.empty?
+
+            base = @lenses.map(&:clarity).min
+            decay = Constants::STACK_CLARITY_DECAY**(@lenses.size - 1)
+            (base * decay).clamp(0.0, 1.0).round(10)
+          end
+
+          # Apply all lenses to a content value (numeric 0.0-1.0) or hash with :value key
+          def view_through(content)
+            return content if @lenses.empty?
+
+            raw_value = extract_value(content)
+            magnified  = apply_magnification(raw_value)
+            distorted  = apply_distortion(magnified)
+            filtered   = apply_clarity(distorted)
+
+            {
+              original:               raw_value,
+              perceived:              filtered.round(10),
+              combined_magnification: combined_magnification.round(10),
+              combined_distortion:    combined_distortion.round(10),
+              stack_clarity:          stack_clarity.round(10),
+              lens_count:             @lenses.size,
+              focus_active:           @lenses.any?(&:focused?)
+            }
+          end
+
+          def to_h
+            {
+              lens_count:             @lenses.size,
+              combined_magnification: combined_magnification.round(10),
+              combined_distortion:    combined_distortion.round(10),
+              stack_clarity:          stack_clarity.round(10),
+              lenses:                 @lenses.map(&:to_h)
+            }
+          end
+
+          private
+
+          def extract_value(content)
+            if content.is_a?(Hash)
+              content.fetch(:value, 0.5).clamp(0.0, 1.0)
+            else
+              content.to_f.clamp(0.0, 1.0)
+            end
+          end
+
+          def apply_magnification(value)
+            mag = combined_magnification
+            # Magnification centers around 0.5; scale distance from center
+            center    = 0.5
+            distance  = value - center
+            (center + (distance * mag)).clamp(0.0, 1.0)
+          end
+
+          def apply_distortion(value)
+            dist = combined_distortion
+            return value if dist.zero?
+
+            # Barrel distortion pushes values toward extremes
+            noise = (value - 0.5).abs * dist * 0.2
+            sign  = value >= 0.5 ? 1 : -1
+            (value + (sign * noise)).clamp(0.0, 1.0)
+          end
+
+          def apply_clarity(value)
+            clarity = stack_clarity
+            # Low clarity pulls perceived value toward neutral (0.5)
+            center = 0.5
+            (center + ((value - center) * clarity)).clamp(0.0, 1.0)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      module Runners
+        module CognitiveLens
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_lens(lens_type:, magnification: nil, clarity: 1.0, distortion: nil, aperture: nil,
+                          engine: nil, **)
+            raise ArgumentError, "unknown lens_type: #{lens_type}" unless Helpers::Constants::LENS_TYPES.include?(lens_type)
+
+            eng  = engine || lens_engine
+            lens = eng.create_lens(
+              lens_type:     lens_type,
+              magnification: magnification,
+              clarity:       clarity,
+              distortion:    distortion,
+              aperture:      aperture
+            )
+            Legion::Logging.debug "[cognitive_lens] created lens id=#{lens.id} type=#{lens_type} " \
+                                  "mag=#{lens.magnification.round(2)} clarity=#{lens.clarity.round(2)}"
+            { success: true, lens: lens.to_h }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_lens] create_lens failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def stack_lenses(lens_ids:, stack_id: nil, engine: nil, **)
+            raise ArgumentError, 'lens_ids must be an array' unless lens_ids.is_a?(Array)
+
+            eng    = engine || lens_engine
+            result = eng.stack_lenses(lens_ids: lens_ids, stack_id: stack_id)
+            Legion::Logging.debug "[cognitive_lens] stacked #{lens_ids.size} lenses stack_id=#{result[:stack_id]}"
+            { success: true, stack_id: result[:stack_id], stack: result[:stack].to_h }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_lens] stack_lenses failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def view_through_stack(stack_id:, content:, engine: nil, **)
+            eng    = engine || lens_engine
+            result = eng.view_through_stack(stack_id: stack_id, content: content)
+            { success: true, **result }
+          rescue ArgumentError => e
+            Legion::Logging.warn "[cognitive_lens] view_through_stack failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def degrade_all(rate: Helpers::Constants::SMUDGE_RATE_DEFAULT, engine: nil, **)
+            eng    = engine || lens_engine
+            result = eng.degrade_all!(rate: rate)
+            Legion::Logging.debug "[cognitive_lens] degraded #{result[:degraded]} lenses at rate=#{rate}"
+            { success: true, **result }
+          end
+
+          def lens_report(engine: nil, **)
+            eng    = engine || lens_engine
+            report = eng.lens_report
+            { success: true, **report }
+          end
+
+          def clearest_lenses(limit: 3, engine: nil, **)
+            eng = engine || lens_engine
+            lenses = eng.clearest_lenses(limit: limit)
+            { success: true, lenses: lenses }
+          end
+
+          def most_distorted(limit: 3, engine: nil, **)
+            eng = engine || lens_engine
+            lenses = eng.most_distorted(limit: limit)
+            { success: true, lenses: lenses }
+          end
+
+          private
+
+          def lens_engine
+            @lens_engine ||= Helpers::LensEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_lens.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'cognitive_lens/version'
+require_relative 'cognitive_lens/helpers/constants'
+require_relative 'cognitive_lens/helpers/lens'
+require_relative 'cognitive_lens/helpers/lens_stack'
+require_relative 'cognitive_lens/helpers/lens_engine'
+require_relative 'cognitive_lens/runners/cognitive_lens'
+require_relative 'cognitive_lens/client'
+
+module Legion
+  module Extensions
+    module CognitiveLens
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end