lex-perspective-shifting 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1ec311143b14d434d25a2f54c6ca96e8cb5da4e3ceb7bed2d6a84f69b4a11e49
+  data.tar.gz: e6f8648010602650dcf9056f3cc5d825469d65394c6e1d5e84b042999562c235
+SHA512:
+  metadata.gz: d3958db3162c613a323d06ae97fb5c67a72f22165663c6d95c8f5d9399527f87419cf50859a2d9d0489b7a4a99031aae0f8c1dc7147e03238c00093fa88489e7
+  data.tar.gz: 45e7d3d9e28241bc6db4cccd39047851af420a15a81fbc23c5732237c7fc4a94a18a83c4d8575b8a75458ed25f63115f762130c2e586e1f7668c1267279edd13

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-perspective-shifting.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/perspective_shifting/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-perspective-shifting'
+  spec.version       = Legion::Extensions::PerspectiveShifting::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Perspective Shifting'
+  spec.description   = 'Systematic multi-viewpoint analysis engine for brain-modeled agentic AI — ' \
+                       'cycles through stakeholder, ethical, temporal, and other interpretive frames ' \
+                       'to generate richer situational understanding'
+  spec.homepage      = 'https://github.com/LegionIO/lex-perspective-shifting'
+  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-perspective-shifting'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-perspective-shifting'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-perspective-shifting'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-perspective-shifting/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-perspective-shifting.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/perspective_shifting/helpers/constants'
+require 'legion/extensions/perspective_shifting/helpers/perspective'
+require 'legion/extensions/perspective_shifting/helpers/perspective_view'
+require 'legion/extensions/perspective_shifting/helpers/shifting_engine'
+require 'legion/extensions/perspective_shifting/runners/perspective_shifting'
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      class Client
+        include Runners::PerspectiveShifting
+
+        def initialize(**)
+          @shifting_engine = Helpers::ShiftingEngine.new
+        end
+
+        private
+
+        attr_reader :shifting_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      module Helpers
+        module Constants
+          MAX_PERSPECTIVES             = 50
+          MAX_SITUATIONS               = 200
+          MAX_VIEWS_PER_SITUATION      = 20
+          DEFAULT_EMPATHY              = 0.5
+          MIN_PERSPECTIVES_FOR_SYNTHESIS = 2
+
+          PERSPECTIVE_TYPES = %i[
+            stakeholder emotional temporal cultural ethical pragmatic creative adversarial
+          ].freeze
+
+          PRIORITY_TYPES = %i[
+            safety efficiency fairness innovation stability growth autonomy compliance
+          ].freeze
+
+          EMPATHY_LABELS = {
+            (0.8..)     => :deeply_empathic,
+            (0.6...0.8) => :empathic,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :limited,
+            (..0.2)     => :detached
+          }.freeze
+
+          COVERAGE_LABELS = {
+            (0.8..)     => :comprehensive,
+            (0.6...0.8) => :thorough,
+            (0.4...0.6) => :partial,
+            (0.2...0.4) => :narrow,
+            (..0.2)     => :blind
+          }.freeze
+
+          AGREEMENT_LABELS = {
+            (0.8..)     => :consensus,
+            (0.6...0.8) => :agreement,
+            (0.4...0.6) => :mixed,
+            (0.2...0.4) => :disagreement,
+            (..0.2)     => :conflict
+          }.freeze
+
+          module_function
+
+          def empathy_label(value)
+            EMPATHY_LABELS.find { |range, _| range.include?(value) }&.last || :detached
+          end
+
+          def coverage_label(value)
+            COVERAGE_LABELS.find { |range, _| range.include?(value) }&.last || :blind
+          end
+
+          def agreement_label(value)
+            AGREEMENT_LABELS.find { |range, _| range.include?(value) }&.last || :conflict
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/perspective_shifting/helpers/perspective.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      module Helpers
+        class Perspective
+          attr_reader :id, :name, :perspective_type, :priorities,
+                      :expertise_domains, :empathy_level, :bias_toward, :created_at
+
+          def initialize(name:, perspective_type:, priorities: [], expertise_domains: [],
+                         empathy_level: Constants::DEFAULT_EMPATHY, bias_toward: nil)
+            @id               = SecureRandom.uuid
+            @name             = name
+            @perspective_type = perspective_type
+            @priorities       = Array(priorities)
+            @expertise_domains = Array(expertise_domains)
+            @empathy_level    = empathy_level.clamp(0.0, 1.0)
+            @bias_toward      = bias_toward
+            @created_at       = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:                @id,
+              name:              @name,
+              perspective_type:  @perspective_type,
+              priorities:        @priorities,
+              expertise_domains: @expertise_domains,
+              empathy_level:     @empathy_level.round(10),
+              bias_toward:       @bias_toward,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/perspective_shifting/helpers/perspective_view.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      module Helpers
+        class PerspectiveView
+          attr_reader :id, :situation_id, :perspective_id, :valence,
+                      :concerns, :opportunities, :confidence, :created_at
+
+          def initialize(situation_id:, perspective_id:, valence: 0.0,
+                         concerns: [], opportunities: [], confidence: 0.5)
+            @id             = SecureRandom.uuid
+            @situation_id   = situation_id
+            @perspective_id = perspective_id
+            @valence        = valence.clamp(-1.0, 1.0).round(10)
+            @concerns       = Array(concerns)
+            @opportunities  = Array(opportunities)
+            @confidence     = confidence.clamp(0.0, 1.0).round(10)
+            @created_at     = Time.now.utc
+          end
+
+          def positive?
+            @valence > 0.1
+          end
+
+          def negative?
+            @valence < -0.1
+          end
+
+          def neutral?
+            !positive? && !negative?
+          end
+
+          def to_h
+            {
+              id:             @id,
+              situation_id:   @situation_id,
+              perspective_id: @perspective_id,
+              valence:        @valence,
+              concerns:       @concerns,
+              opportunities:  @opportunities,
+              confidence:     @confidence,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/perspective_shifting/helpers/shifting_engine.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      module Helpers
+        class ShiftingEngine
+          attr_reader :perspectives, :situations
+
+          def initialize
+            @perspectives = {}
+            @situations   = {}
+          end
+
+          def add_perspective(name:, type: :stakeholder, priorities: [], empathy: Constants::DEFAULT_EMPATHY,
+                              bias: nil, expertise_domains: [])
+            return { error: :too_many_perspectives } if @perspectives.size >= Constants::MAX_PERSPECTIVES
+            return { error: :invalid_type } unless Constants::PERSPECTIVE_TYPES.include?(type)
+
+            p = Perspective.new(
+              name:              name,
+              perspective_type:  type,
+              priorities:        priorities,
+              expertise_domains: expertise_domains,
+              empathy_level:     empathy,
+              bias_toward:       bias
+            )
+            @perspectives[p.id] = p
+            p
+          end
+
+          def add_situation(content:)
+            return { error: :too_many_situations } if @situations.size >= Constants::MAX_SITUATIONS
+
+            id = SecureRandom.uuid
+            @situations[id] = { id: id, content: content, views: [], created_at: Time.now.utc }
+            @situations[id]
+          end
+
+          def generate_view(situation_id:, perspective_id:, valence: 0.0,
+                            concerns: [], opportunities: [], confidence: 0.5)
+            situation = @situations[situation_id]
+            perspective = @perspectives[perspective_id]
+
+            return { error: :situation_not_found } unless situation
+            return { error: :perspective_not_found } unless perspective
+            return { error: :too_many_views } if situation[:views].size >= Constants::MAX_VIEWS_PER_SITUATION
+
+            view = PerspectiveView.new(
+              situation_id:   situation_id,
+              perspective_id: perspective_id,
+              valence:        valence,
+              concerns:       concerns,
+              opportunities:  opportunities,
+              confidence:     confidence
+            )
+            situation[:views] << view
+            view
+          end
+
+          def views_for_situation(situation_id:)
+            situation = @situations[situation_id]
+            return [] unless situation
+
+            situation[:views]
+          end
+
+          def perspective_agreement(situation_id:)
+            views = views_for_situation(situation_id: situation_id)
+            return 0.0 if views.size < Constants::MIN_PERSPECTIVES_FOR_SYNTHESIS
+
+            valences = views.map(&:valence)
+            mean     = valences.sum / valences.size.to_f
+            variance = valences.sum { |v| (v - mean)**2 } / valences.size.to_f
+            std_dev  = Math.sqrt(variance)
+
+            # Agreement is inverse of normalized std_dev (max std_dev is 1.0 for symmetric ±1 distribution)
+            (1.0 - std_dev).clamp(0.0, 1.0).round(10)
+          end
+
+          def blind_spots(situation_id:)
+            views = views_for_situation(situation_id: situation_id)
+            applied_ids = views.map(&:perspective_id).uniq
+            applied_types = applied_ids.filter_map { |pid| @perspectives[pid]&.perspective_type }.uniq
+            Constants::PERSPECTIVE_TYPES - applied_types
+          end
+
+          def coverage_score(situation_id:)
+            views = views_for_situation(situation_id: situation_id)
+            return 0.0 if @perspectives.empty?
+
+            applied_count = views.map(&:perspective_id).uniq.size
+            (applied_count.to_f / @perspectives.size).clamp(0.0, 1.0).round(10)
+          end
+
+          def dominant_view(situation_id:)
+            views = views_for_situation(situation_id: situation_id)
+            return nil if views.empty?
+
+            views.max_by(&:confidence)
+          end
+
+          def synthesize(situation_id:)
+            views = views_for_situation(situation_id: situation_id)
+            return { error: :insufficient_views } if views.size < Constants::MIN_PERSPECTIVES_FOR_SYNTHESIS
+
+            total_confidence = views.sum(&:confidence)
+            return { error: :zero_confidence } if total_confidence.zero?
+
+            weighted_valence = views.sum { |v| v.valence * v.confidence } / total_confidence
+            all_concerns     = views.flat_map(&:concerns).uniq
+            all_opportunities = views.flat_map(&:opportunities).uniq
+            agreement = perspective_agreement(situation_id: situation_id)
+
+            {
+              situation_id:     situation_id,
+              weighted_valence: weighted_valence.round(10),
+              concerns:         all_concerns,
+              opportunities:    all_opportunities,
+              agreement:        agreement.round(10),
+              agreement_label:  Constants.agreement_label(agreement),
+              view_count:       views.size,
+              coverage_score:   coverage_score(situation_id: situation_id),
+              coverage_label:   Constants.coverage_label(coverage_score(situation_id: situation_id))
+            }
+          end
+
+          def most_divergent_pair(situation_id:)
+            views = views_for_situation(situation_id: situation_id)
+            return nil if views.size < 2
+
+            max_diff = -1.0
+            pair     = nil
+
+            views.combination(2) do |a, b|
+              diff = (a.valence - b.valence).abs
+              if diff > max_diff
+                max_diff = diff
+                pair     = [a, b]
+              end
+            end
+
+            pair
+          end
+
+          def to_h
+            {
+              perspective_count: @perspectives.size,
+              situation_count:   @situations.size,
+              perspectives:      @perspectives.values.map(&:to_h),
+              situations:        @situations.values.map do |s|
+                s.merge(views: s[:views].map(&:to_h))
+              end
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      module Runners
+        module PerspectiveShifting
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          # --- Perspective management ---
+
+          def add_perspective(name:, type: :stakeholder, priorities: [], empathy: Helpers::Constants::DEFAULT_EMPATHY,
+                              bias: nil, expertise_domains: [], engine: nil, **)
+            eng    = engine || shifting_engine
+            result = eng.add_perspective(name: name, type: type, priorities: priorities,
+                                         empathy: empathy, bias: bias, expertise_domains: expertise_domains)
+            return { success: false, error: result[:error] } if result.is_a?(Hash) && result[:error]
+
+            Legion::Logging.debug "[perspective_shifting] added perspective name=#{name} type=#{type} id=#{result.id[0..7]}"
+            { success: true, perspective: result.to_h }
+          end
+
+          def list_perspectives(engine: nil, **)
+            eng   = engine || shifting_engine
+            persp = eng.perspectives.values.map(&:to_h)
+            Legion::Logging.debug "[perspective_shifting] list_perspectives count=#{persp.size}"
+            { success: true, perspectives: persp, count: persp.size }
+          end
+
+          def get_perspective(perspective_id:, engine: nil, **)
+            eng   = engine || shifting_engine
+            persp = eng.perspectives[perspective_id]
+            if persp
+              { success: true, found: true, perspective: persp.to_h }
+            else
+              Legion::Logging.debug "[perspective_shifting] perspective not found id=#{perspective_id[0..7]}"
+              { success: false, found: false }
+            end
+          end
+
+          # --- Situation management ---
+
+          def add_situation(content:, engine: nil, **)
+            eng    = engine || shifting_engine
+            result = eng.add_situation(content: content)
+            return { success: false, error: result[:error] } if result.is_a?(Hash) && result[:error]
+
+            Legion::Logging.debug "[perspective_shifting] added situation id=#{result[:id][0..7]}"
+            { success: true, situation_id: result[:id], content: result[:content] }
+          end
+
+          def list_situations(engine: nil, **)
+            eng  = engine || shifting_engine
+            sits = eng.situations.values.map { |s| s.merge(views: s[:views].map(&:to_h)) }
+            Legion::Logging.debug "[perspective_shifting] list_situations count=#{sits.size}"
+            { success: true, situations: sits, count: sits.size }
+          end
+
+          # --- View generation and retrieval ---
+
+          def generate_view(situation_id:, perspective_id:, valence: 0.0,
+                            concerns: [], opportunities: [], confidence: 0.5, engine: nil, **)
+            eng    = engine || shifting_engine
+            result = eng.generate_view(
+              situation_id:   situation_id,
+              perspective_id: perspective_id,
+              valence:        valence,
+              concerns:       concerns,
+              opportunities:  opportunities,
+              confidence:     confidence
+            )
+            return { success: false, error: result[:error] } if result.is_a?(Hash) && result[:error]
+
+            Legion::Logging.debug "[perspective_shifting] generated view id=#{result.id[0..7]} " \
+                                  "valence=#{result.valence.round(2)}"
+            { success: true, view: result.to_h }
+          end
+
+          def views_for_situation(situation_id:, engine: nil, **)
+            eng   = engine || shifting_engine
+            views = eng.views_for_situation(situation_id: situation_id)
+            Legion::Logging.debug "[perspective_shifting] views_for_situation id=#{situation_id[0..7]} count=#{views.size}"
+            { success: true, views: views.map(&:to_h), count: views.size }
+          end
+
+          # --- Analysis ---
+
+          def perspective_agreement(situation_id:, engine: nil, **)
+            eng       = engine || shifting_engine
+            score     = eng.perspective_agreement(situation_id: situation_id)
+            label     = Helpers::Constants.agreement_label(score)
+            Legion::Logging.debug "[perspective_shifting] agreement situation=#{situation_id[0..7]} score=#{score.round(2)} label=#{label}"
+            { success: true, situation_id: situation_id, agreement: score, label: label }
+          end
+
+          def blind_spots(situation_id:, engine: nil, **)
+            eng   = engine || shifting_engine
+            spots = eng.blind_spots(situation_id: situation_id)
+            Legion::Logging.debug "[perspective_shifting] blind_spots situation=#{situation_id[0..7]} count=#{spots.size}"
+            { success: true, situation_id: situation_id, blind_spots: spots, count: spots.size }
+          end
+
+          def coverage_score(situation_id:, engine: nil, **)
+            eng   = engine || shifting_engine
+            score = eng.coverage_score(situation_id: situation_id)
+            label = Helpers::Constants.coverage_label(score)
+            Legion::Logging.debug "[perspective_shifting] coverage situation=#{situation_id[0..7]} score=#{score.round(2)} label=#{label}"
+            { success: true, situation_id: situation_id, coverage: score, label: label }
+          end
+
+          def dominant_view(situation_id:, engine: nil, **)
+            eng  = engine || shifting_engine
+            view = eng.dominant_view(situation_id: situation_id)
+            if view
+              Legion::Logging.debug "[perspective_shifting] dominant_view situation=#{situation_id[0..7]} confidence=#{view.confidence.round(2)}"
+              { success: true, found: true, view: view.to_h }
+            else
+              { success: true, found: false }
+            end
+          end
+
+          def synthesize(situation_id:, engine: nil, **)
+            eng    = engine || shifting_engine
+            result = eng.synthesize(situation_id: situation_id)
+            return { success: false, error: result[:error] } if result[:error]
+
+            Legion::Logging.info "[perspective_shifting] synthesized situation=#{situation_id[0..7]} " \
+                                 "valence=#{result[:weighted_valence].round(2)} views=#{result[:view_count]}"
+            result.merge(success: true)
+          end
+
+          def most_divergent_pair(situation_id:, engine: nil, **)
+            eng  = engine || shifting_engine
+            pair = eng.most_divergent_pair(situation_id: situation_id)
+            unless pair
+              Legion::Logging.debug '[perspective_shifting] most_divergent_pair: not enough views'
+              return { success: true, found: false }
+            end
+
+            divergence = (pair[0].valence - pair[1].valence).abs.round(10)
+            Legion::Logging.debug "[perspective_shifting] most_divergent_pair divergence=#{divergence.round(2)}"
+            { success: true, found: true, views: pair.map(&:to_h), divergence: divergence }
+          end
+
+          def engine_status(engine: nil, **)
+            eng = engine || shifting_engine
+            Legion::Logging.debug '[perspective_shifting] engine_status'
+            { success: true }.merge(eng.to_h)
+          end
+
+          private
+
+          def shifting_engine
+            @shifting_engine ||= Helpers::ShiftingEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/perspective_shifting.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/perspective_shifting/version'
+require 'legion/extensions/perspective_shifting/helpers/constants'
+require 'legion/extensions/perspective_shifting/helpers/perspective'
+require 'legion/extensions/perspective_shifting/helpers/perspective_view'
+require 'legion/extensions/perspective_shifting/helpers/shifting_engine'
+require 'legion/extensions/perspective_shifting/runners/perspective_shifting'
+
+module Legion
+  module Extensions
+    module PerspectiveShifting
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/perspective_shifting/client'
+
+RSpec.describe Legion::Extensions::PerspectiveShifting::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    expect(client).to respond_to(:add_perspective)
+    expect(client).to respond_to(:list_perspectives)
+    expect(client).to respond_to(:get_perspective)
+    expect(client).to respond_to(:add_situation)
+    expect(client).to respond_to(:list_situations)
+    expect(client).to respond_to(:generate_view)
+    expect(client).to respond_to(:views_for_situation)
+    expect(client).to respond_to(:perspective_agreement)
+    expect(client).to respond_to(:blind_spots)
+    expect(client).to respond_to(:coverage_score)
+    expect(client).to respond_to(:dominant_view)
+    expect(client).to respond_to(:synthesize)
+    expect(client).to respond_to(:most_divergent_pair)
+    expect(client).to respond_to(:engine_status)
+  end
+
+  it 'initializes with its own isolated engine per instance' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.add_perspective(name: 'CEO', type: :stakeholder)
+    expect(c2.list_perspectives[:count]).to eq(0)
+  end
+end