lex-agentic-integration 0.1.0

data/lib/legion/extensions/agentic/integration/phenomenal_binding/runners/phenomenal_binding.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module PhenomenalBinding
+          module Runners
+            module PhenomenalBinding
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def register_stream(stream_type:, content:, salience: Helpers::Constants::DEFAULT_SALIENCE,
+                                  domain: nil, **)
+                stream = engine.register_stream(
+                  stream_type: stream_type,
+                  content:     content,
+                  salience:    salience,
+                  domain:      domain
+                )
+                Legion::Logging.debug "[phenomenal_binding] register_stream: type=#{stream_type} " \
+                                      "salience=#{stream.salience.round(2)} domain=#{domain}"
+                { status: :registered, stream: stream.to_h }
+              end
+
+              def create_binding(stream_ids:, binding_type:, attention_weight: 0.5, **)
+                result = engine.create_binding(
+                  stream_ids:       stream_ids,
+                  binding_type:     binding_type,
+                  attention_weight: attention_weight
+                )
+                Legion::Logging.debug "[phenomenal_binding] create_binding: type=#{binding_type} " \
+                                      "streams=#{result.stream_count} coherence=#{result.coherence.round(2)}"
+                { status: :bound, binding: result.to_h }
+              end
+
+              def reinforce_binding(binding_id:, **)
+                result = engine.reinforce_binding(binding_id: binding_id)
+                Legion::Logging.debug "[phenomenal_binding] reinforce_binding: id=#{binding_id} " \
+                                      "coherence=#{result[:coherence]&.round(2)}"
+                result
+              end
+
+              def dissolve_binding(binding_id:, **)
+                result = engine.dissolve_binding(binding_id: binding_id)
+                Legion::Logging.debug "[phenomenal_binding] dissolve_binding: id=#{binding_id} status=#{result[:status]}"
+                result
+              end
+
+              def unified_experience(**)
+                experience = engine.unified_experience
+                Legion::Logging.debug '[phenomenal_binding] unified_experience: ' \
+                                      "coherence=#{experience&.coherence&.round(2) || 'none'}"
+                { unified_experience: experience&.to_h }
+              end
+
+              def fragmentation_index(**)
+                index = engine.fragmentation_index
+                Legion::Logging.debug "[phenomenal_binding] fragmentation_index=#{index.round(3)}"
+                { fragmentation_index: index }
+              end
+
+              def binding_by_type(binding_type:, **)
+                bindings = engine.binding_by_type(binding_type: binding_type)
+                Legion::Logging.debug "[phenomenal_binding] binding_by_type: type=#{binding_type} count=#{bindings.size}"
+                { binding_type: binding_type, bindings: bindings.map(&:to_h) }
+              end
+
+              def streams_for_binding(binding_id:, **)
+                streams = engine.streams_for_binding(binding_id: binding_id)
+                Legion::Logging.debug "[phenomenal_binding] streams_for_binding: id=#{binding_id} count=#{streams.size}"
+                { binding_id: binding_id, streams: streams.map(&:to_h) }
+              end
+
+              def unbound_streams(**)
+                streams = engine.unbound_streams
+                Legion::Logging.debug "[phenomenal_binding] unbound_streams: count=#{streams.size}"
+                { unbound_streams: streams.map(&:to_h) }
+              end
+
+              def decay_all(**)
+                engine.decay_all
+                Legion::Logging.debug '[phenomenal_binding] decay_all: all bindings decayed'
+                { status: :decayed }
+              end
+
+              def prune_incoherent(**)
+                engine.prune_incoherent
+                Legion::Logging.debug '[phenomenal_binding] prune_incoherent: incoherent bindings removed'
+                { status: :pruned }
+              end
+
+              def consciousness_report(**)
+                report = engine.consciousness_report
+                Legion::Logging.debug '[phenomenal_binding] consciousness_report: ' \
+                                      "fragmentation=#{report[:fragmentation_index].round(3)} " \
+                                      "bindings=#{report[:binding_count]}"
+                report
+              end
+
+              def engine_stats(**)
+                engine.to_h
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/phenomenal_binding/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module PhenomenalBinding
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/phenomenal_binding.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/integration/phenomenal_binding/version'
+require 'legion/extensions/agentic/integration/phenomenal_binding/helpers/constants'
+require 'legion/extensions/agentic/integration/phenomenal_binding/helpers/stream'
+require 'legion/extensions/agentic/integration/phenomenal_binding/helpers/binding_unit'
+require 'legion/extensions/agentic/integration/phenomenal_binding/helpers/binding_engine'
+require 'legion/extensions/agentic/integration/phenomenal_binding/runners/phenomenal_binding'
+require 'legion/extensions/agentic/integration/phenomenal_binding/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module PhenomenalBinding
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+          class Client
+            include Runners::Qualia
+
+            def initialize
+              @default_engine = Helpers::QualiaEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia/helpers/constants.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+          module Helpers
+            module Constants
+              MAX_EXPERIENCES = 500
+              MAX_PALETTE_SIZE = 100
+
+              # Phenomenal dimensions
+              DEFAULT_VIVIDNESS = 0.5
+              DEFAULT_VALENCE = 0.0
+              DEFAULT_TEXTURE = 0.5
+              VIVIDNESS_DECAY = 0.03
+              VIVIDNESS_BOOST = 0.1
+
+              # Thresholds
+              VIVID_THRESHOLD = 0.7
+              FAINT_THRESHOLD = 0.2
+              INTENSE_THRESHOLD = 0.8
+
+              PHENOMENAL_QUALITIES = %i[
+                sharp smooth warm cool heavy light
+                bright dark flowing rigid pulsing still
+              ].freeze
+
+              TEXTURE_TYPES = %i[
+                crystalline fluid granular electric
+                velvet metallic organic ethereal
+              ].freeze
+
+              MODALITIES = %i[
+                visual auditory tactile gustatory
+                olfactory kinesthetic emotional abstract
+              ].freeze
+
+              VIVIDNESS_LABELS = {
+                (0.8..)     => :overwhelming,
+                (0.6...0.8) => :vivid,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :faint,
+                (..0.2)     => :ghost
+              }.freeze
+
+              VALENCE_LABELS = {
+                (0.5..)       => :pleasant,
+                (0.2...0.5)   => :mildly_pleasant,
+                (-0.2...0.2)  => :neutral,
+                (-0.5...-0.2) => :mildly_unpleasant,
+                (..-0.5)      => :unpleasant
+              }.freeze
+
+              RICHNESS_LABELS = {
+                (0.8..)     => :synesthetic,
+                (0.6...0.8) => :rich,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :sparse,
+                (..0.2)     => :flat
+              }.freeze
+
+              def self.label_for(labels, value)
+                labels.each { |range, label| return label if range.cover?(value) }
+                :unknown
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia/helpers/quale.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+          module Helpers
+            class Quale
+              include Constants
+
+              attr_reader :id, :content, :modality, :quality, :texture,
+                          :valence, :original_vividness, :created_at
+              attr_accessor :vividness
+
+              def initialize(content:, modality: :abstract, quality: :smooth, texture: :fluid,
+                             vividness: DEFAULT_VIVIDNESS, valence: DEFAULT_VALENCE)
+                @id = SecureRandom.uuid
+                @content = content.to_s
+                @modality = valid_modality(modality)
+                @quality = valid_quality(quality)
+                @texture = valid_texture(texture)
+                @vividness = vividness.to_f.clamp(0.0, 1.0).round(10)
+                @original_vividness = @vividness
+                @valence = valence.to_f.clamp(-1.0, 1.0).round(10)
+                @created_at = Time.now
+              end
+
+              def intensify!(amount: VIVIDNESS_BOOST)
+                @vividness = (@vividness + amount).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def fade!
+                @vividness = (@vividness - VIVIDNESS_DECAY).clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def vivid? = @vividness >= VIVID_THRESHOLD
+              def faint? = @vividness <= FAINT_THRESHOLD
+              def intense? = @vividness >= INTENSE_THRESHOLD
+              def pleasant? = @valence > 0.2
+              def unpleasant? = @valence < -0.2
+              def neutral_valence? = @valence.abs <= 0.2
+
+              def phenomenal_richness
+                base = @vividness * 0.5
+                quality_bonus = PHENOMENAL_QUALITIES.index(@quality).to_f / PHENOMENAL_QUALITIES.size * 0.25
+                texture_bonus = TEXTURE_TYPES.index(@texture).to_f / TEXTURE_TYPES.size * 0.25
+                (base + quality_bonus + texture_bonus).clamp(0.0, 1.0).round(10)
+              end
+
+              def persistence = (@vividness / [@original_vividness, 0.01].max).clamp(0.0, 1.0).round(10)
+              def vividness_label = Constants.label_for(VIVIDNESS_LABELS, @vividness)
+              def valence_label = Constants.label_for(VALENCE_LABELS, @valence)
+              def richness_label = Constants.label_for(RICHNESS_LABELS, phenomenal_richness)
+
+              def to_h
+                {
+                  id:                  @id,
+                  content:             @content,
+                  modality:            @modality,
+                  quality:             @quality,
+                  texture:             @texture,
+                  vividness:           @vividness,
+                  original_vividness:  @original_vividness,
+                  valence:             @valence,
+                  phenomenal_richness: phenomenal_richness,
+                  vivid:               vivid?,
+                  faint:               faint?,
+                  intense:             intense?,
+                  vividness_label:     vividness_label,
+                  valence_label:       valence_label,
+                  persistence:         persistence,
+                  created_at:          @created_at.iso8601
+                }
+              end
+
+              private
+
+              def valid_modality(mod)
+                sym = mod.to_sym
+                MODALITIES.include?(sym) ? sym : :abstract
+              end
+
+              def valid_quality(qual)
+                sym = qual.to_sym
+                PHENOMENAL_QUALITIES.include?(sym) ? sym : :smooth
+              end
+
+              def valid_texture(tex)
+                sym = tex.to_sym
+                TEXTURE_TYPES.include?(sym) ? sym : :fluid
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia/helpers/qualia_engine.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+          module Helpers
+            class QualiaEngine
+              include Constants
+
+              def initialize
+                @experiences = {}
+              end
+
+              def create_quale(content:, modality: :abstract, quality: :smooth, texture: :fluid,
+                               vividness: DEFAULT_VIVIDNESS, valence: DEFAULT_VALENCE)
+                prune_faint
+                quale = Quale.new(content: content, modality: modality, quality: quality,
+                                  texture: texture, vividness: vividness, valence: valence)
+                @experiences[quale.id] = quale
+                quale
+              end
+
+              def intensify(quale_id:, amount: VIVIDNESS_BOOST)
+                quale = @experiences[quale_id]
+                return nil unless quale
+
+                quale.intensify!(amount: amount)
+                quale
+              end
+
+              def fade_all!
+                @experiences.each_value(&:fade!)
+                prune_faint
+                { remaining: @experiences.size }
+              end
+
+              def vivid_experiences = @experiences.values.select(&:vivid?)
+              def faint_experiences = @experiences.values.select(&:faint?)
+              def intense_experiences = @experiences.values.select(&:intense?)
+
+              def by_modality(modality:)
+                @experiences.values.select { |q| q.modality == modality.to_sym }
+              end
+
+              def by_quality(quality:)
+                @experiences.values.select { |q| q.quality == quality.to_sym }
+              end
+
+              def by_texture(texture:)
+                @experiences.values.select { |q| q.texture == texture.to_sym }
+              end
+
+              def pleasant_experiences = @experiences.values.select(&:pleasant?)
+              def unpleasant_experiences = @experiences.values.select(&:unpleasant?)
+
+              def most_vivid(limit: 5) = @experiences.values.sort_by { |q| -q.vividness }.first(limit)
+
+              def average_vividness
+                return 0.0 if @experiences.empty?
+
+                (@experiences.values.sum(&:vividness) / @experiences.size).round(10)
+              end
+
+              def average_valence
+                return 0.0 if @experiences.empty?
+
+                (@experiences.values.sum(&:valence) / @experiences.size).round(10)
+              end
+
+              def phenomenal_richness
+                return 0.0 if @experiences.empty?
+
+                (@experiences.values.sum(&:phenomenal_richness) / @experiences.size).round(10)
+              end
+
+              def modality_distribution
+                MODALITIES.to_h do |mod|
+                  [mod, @experiences.values.count { |q| q.modality == mod }]
+                end
+              end
+
+              def quality_palette
+                @experiences.values.map(&:quality).tally.sort_by { |_, v| -v }.to_h
+              end
+
+              def texture_palette
+                @experiences.values.map(&:texture).tally.sort_by { |_, v| -v }.to_h
+              end
+
+              def experiential_diversity
+                return 0.0 if @experiences.empty?
+
+                modalities_used = @experiences.values.map(&:modality).uniq.size
+                (modalities_used.to_f / MODALITIES.size).clamp(0.0, 1.0).round(10)
+              end
+
+              def qualia_report
+                {
+                  total_experiences:      @experiences.size,
+                  vivid_count:            vivid_experiences.size,
+                  faint_count:            faint_experiences.size,
+                  pleasant_count:         pleasant_experiences.size,
+                  unpleasant_count:       unpleasant_experiences.size,
+                  average_vividness:      average_vividness,
+                  average_valence:        average_valence,
+                  phenomenal_richness:    phenomenal_richness,
+                  experiential_diversity: experiential_diversity,
+                  richness_label:         Constants.label_for(RICHNESS_LABELS, phenomenal_richness),
+                  most_vivid:             most_vivid(limit: 3).map(&:to_h)
+                }
+              end
+
+              def to_h
+                {
+                  total_experiences: @experiences.size,
+                  vivid:             vivid_experiences.size,
+                  avg_vividness:     average_vividness,
+                  avg_valence:       average_valence,
+                  richness:          phenomenal_richness
+                }
+              end
+
+              private
+
+              def prune_faint
+                return if @experiences.size < MAX_EXPERIENCES
+
+                @experiences.reject! { |_, q| q.vividness <= 0.0 }
+                return unless @experiences.size >= MAX_EXPERIENCES
+
+                weakest = @experiences.values.min_by(&:vividness)
+                @experiences.delete(weakest.id) if weakest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia/runners/qualia.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+          module Runners
+            module Qualia
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_quale(content:, modality: :abstract, quality: :smooth, texture: :fluid, vividness: nil,
+                               valence: nil, engine: nil, **)
+                eng = engine || @default_engine
+                quale = eng.create_quale(content: content, modality: modality, quality: quality,
+                                         texture: texture,
+                                         vividness: vividness || Helpers::Constants::DEFAULT_VIVIDNESS,
+                                         valence: valence || Helpers::Constants::DEFAULT_VALENCE)
+                { success: true, quale: quale.to_h }
+              end
+
+              def intensify_quale(quale_id:, amount: nil, engine: nil, **)
+                eng = engine || @default_engine
+                quale = eng.intensify(quale_id: quale_id,
+                                      amount:   amount || Helpers::Constants::VIVIDNESS_BOOST)
+                return { success: false, error: 'quale not found' } unless quale
+
+                { success: true, quale: quale.to_h }
+              end
+
+              def fade_all(engine: nil, **)
+                eng = engine || @default_engine
+                result = eng.fade_all!
+                { success: true, **result }
+              end
+
+              def vivid_experiences(engine: nil, **)
+                eng = engine || @default_engine
+                qualia = eng.vivid_experiences
+                { success: true, count: qualia.size, qualia: qualia.map(&:to_h) }
+              end
+
+              def by_modality(modality:, engine: nil, **)
+                eng = engine || @default_engine
+                qualia = eng.by_modality(modality: modality)
+                { success: true, count: qualia.size, qualia: qualia.map(&:to_h) }
+              end
+
+              def phenomenal_richness(engine: nil, **)
+                eng = engine || @default_engine
+                richness = eng.phenomenal_richness
+                label = Helpers::Constants.label_for(Helpers::Constants::RICHNESS_LABELS, richness)
+                { success: true, richness: richness, label: label }
+              end
+
+              def qualia_status(engine: nil, **)
+                eng = engine || @default_engine
+                report = eng.qualia_report
+                { success: true, **report }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/qualia.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'qualia/version'
+require_relative 'qualia/helpers/constants'
+require_relative 'qualia/helpers/quale'
+require_relative 'qualia/helpers/qualia_engine'
+require_relative 'qualia/runners/qualia'
+require_relative 'qualia/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Qualia
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/situation_model/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/integration/situation_model/helpers/constants'
+require 'legion/extensions/agentic/integration/situation_model/helpers/situation_event'
+require 'legion/extensions/agentic/integration/situation_model/helpers/situation_model'
+require 'legion/extensions/agentic/integration/situation_model/helpers/situation_engine'
+require 'legion/extensions/agentic/integration/situation_model/runners/situation_model'
+require 'legion/extensions/agentic/integration/situation_model/helpers/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module SituationModel
+          class Client
+            include Runners::SituationModel
+
+            private
+
+            def engine
+              @engine ||= Helpers::SituationEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/situation_model/helpers/client.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module SituationModel
+          module Helpers
+            class Client
+              include Legion::Extensions::Agentic::Integration::SituationModel::Runners::SituationModel
+
+              private
+
+              def engine
+                @engine ||= SituationEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/situation_model/helpers/constants.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module SituationModel
+          module Helpers
+            module Constants
+              DIMENSIONS = %i[space time causation intentionality protagonist].freeze
+
+              CONTINUITY_LABELS = {
+                (0.8..)     => :continuous,
+                (0.5...0.8) => :shift,
+                (0.2...0.5) => :break,
+                (..0.2)     => :rupture
+              }.freeze
+
+              MODEL_HEALTH_LABELS = {
+                (0.8..)     => :vivid,
+                (0.6...0.8) => :clear,
+                (0.4...0.6) => :hazy,
+                (0.2...0.4) => :fading,
+                (..0.2)     => :collapsed
+              }.freeze
+
+              MAX_MODELS            = 100
+              MAX_EVENTS_PER_MODEL  = 200
+              MAX_HISTORY           = 500
+              DEFAULT_DIMENSION_VALUE = 0.5
+              DECAY_RATE            = 0.01
+              COHERENCE_FLOOR       = 0.0
+              COHERENCE_CEILING     = 1.0
+            end
+          end
+        end
+      end
+    end
+  end
+end