lex-phenomenal-binding 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab9e772cecd763834bbf765c3fae0d38c0a159d013e7fc5e7bcd998c45e679aa
+  data.tar.gz: b68e2b016e3b06def096fa89dc5c1dc2443ad43c4a2758888a63c1fea7e59107
+SHA512:
+  metadata.gz: 9100dd38955e0dd3c4e0f94ebacff4cbcf9eceb64b9420b56e941ba5237500cf07043ea7839160a62f8d410241c37bb37fe323f9b3c9ef8eb43f954b75b25e6e
+  data.tar.gz: 1a434db26488ebe3ea1dea2928ef5e7716c85a5bca4e82a8cb9e3b005a200632704eb76fc880ff99dec47019847139fbc12a32d698eae9b05fa0d585b6284aac

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) 2024 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,82 @@
+# lex-phenomenal-binding
+
+Phenomenal binding model for the LegionIO cognitive architecture. Integrates disparate cognitive streams into unified moments of experience.
+
+## What It Does
+
+Models the binding problem from cognitive science: how separate streams of processing (perception, thought, emotion, memory, intention, prediction) are grouped into coherent, unified experiences. Maintains a registry of named streams and binding units. Each binding tracks coherence (decays over time, reinforced by attention) and provides a fragmentation index indicating how much of the cognitive state is unintegrated.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::PhenomenalBinding::Client.new
+
+# Register cognitive streams
+r1 = client.register_stream(stream_type: :emotion, content: 'mild_anticipation', salience: 0.7)
+r2 = client.register_stream(stream_type: :prediction, content: 'success_likely', salience: 0.8)
+r3 = client.register_stream(stream_type: :memory, content: 'prior_success_trace', salience: 0.6)
+
+s1_id = r1[:stream][:id]
+s2_id = r2[:stream][:id]
+s3_id = r3[:stream][:id]
+
+# Create a binding grouping the streams
+b = client.create_binding(
+  stream_ids: [s1_id, s2_id, s3_id],
+  binding_type: :emotional,
+  attention_weight: 0.8
+)
+binding_id = b[:binding][:id]
+
+# Reinforce the binding with attention
+client.reinforce_binding(binding_id: binding_id)
+# => { status: :reinforced, binding_id: ..., coherence: 0.78 }
+
+# Check unified experience
+client.unified_experience
+# => { unified_experience: { binding_type: :emotional, coherence: 0.78, stream_count: 3, ... } }
+
+# Check fragmentation
+client.fragmentation_index
+# => { fragmentation_index: 0.0 }
+
+# Full consciousness report
+client.consciousness_report
+# => { unified_experience: {...}, fragmentation_index: 0.0,
+#      coherence_distribution: { unified: 1, coherent: 0, ... },
+#      stream_count: 3, binding_count: 1, unbound_count: 0 }
+
+# Decay and prune on each tick
+client.decay_all
+client.prune_incoherent
+```
+
+## Binding Types
+
+`:perceptual`, `:conceptual`, `:temporal`, `:narrative`, `:emotional`
+
+## Stream Types
+
+`:perception`, `:thought`, `:emotion`, `:memory`, `:intention`, `:prediction`
+
+## Coherence Labels
+
+| Label | Coherence |
+|-------|-----------|
+| `:unified` | >= 0.8 |
+| `:coherent` | 0.6 – 0.8 |
+| `:fragmented` | 0.4 – 0.6 |
+| `:dissociated` | 0.2 – 0.4 |
+| `:unbound` | < 0.2 |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-phenomenal-binding.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/phenomenal_binding/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-phenomenal-binding'
+  spec.version       = Legion::Extensions::PhenomenalBinding::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Phenomenal Binding'
+  spec.description   = 'Phenomenal binding engine for LegionIO — unifies disparate cognitive streams into coherent conscious experience'
+  spec.homepage      = 'https://github.com/LegionIO/lex-phenomenal-binding'
+  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-phenomenal-binding'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-phenomenal-binding'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-phenomenal-binding'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-phenomenal-binding/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-phenomenal-binding.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/phenomenal_binding/runners/phenomenal_binding'
+
+module Legion
+  module Extensions
+    module PhenomenalBinding
+      class Client
+        include Runners::PhenomenalBinding
+
+        def initialize(**)
+          @engine = Helpers::BindingEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

data/lib/legion/extensions/phenomenal_binding/helpers/binding_engine.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PhenomenalBinding
+      module Helpers
+        class BindingEngine
+          include Constants
+
+          def initialize
+            @streams  = {}
+            @bindings = {}
+          end
+
+          def register_stream(stream_type:, content:, salience: DEFAULT_SALIENCE, domain: nil)
+            prune_streams_if_full
+            stream = Stream.new(
+              stream_type: stream_type,
+              content:     content,
+              salience:    salience,
+              domain:      domain
+            )
+            @streams[stream.id] = stream
+            stream
+          end
+
+          def create_binding(stream_ids:, binding_type:, attention_weight: 0.5)
+            prune_bindings_if_full
+            valid_ids   = stream_ids.select { |id| @streams.key?(id) }
+            coherence   = compute_initial_coherence(valid_ids)
+            binding     = BindingUnit.new(
+              stream_ids:       valid_ids,
+              binding_type:     binding_type,
+              coherence:        coherence,
+              attention_weight: attention_weight
+            )
+            @bindings[binding.id] = binding
+            binding
+          end
+
+          def reinforce_binding(binding_id:)
+            binding = @bindings[binding_id]
+            return { status: :not_found, binding_id: binding_id } unless binding
+
+            binding.reinforce!
+            { status: :reinforced, binding_id: binding_id, coherence: binding.coherence }
+          end
+
+          def dissolve_binding(binding_id:)
+            return { status: :not_found, binding_id: binding_id } unless @bindings.key?(binding_id)
+
+            @bindings.delete(binding_id)
+            { status: :dissolved, binding_id: binding_id }
+          end
+
+          def unified_experience
+            coherent = @bindings.values.select(&:coherent?)
+            return nil if coherent.empty?
+
+            coherent.max_by { |b| b.coherence * b.attention_weight }
+          end
+
+          def fragmentation_index
+            total = @streams.size
+            return 0.0 if total.zero?
+
+            (unbound_streams.size.to_f / total).round(10)
+          end
+
+          def binding_by_type(binding_type:)
+            @bindings.values.select { |b| b.binding_type == binding_type }
+          end
+
+          def streams_for_binding(binding_id:)
+            binding = @bindings[binding_id]
+            return [] unless binding
+
+            binding.stream_ids.filter_map { |id| @streams[id] }
+          end
+
+          def unbound_streams
+            bound_ids = @bindings.values.flat_map(&:stream_ids).to_set
+            @streams.values.reject { |s| bound_ids.include?(s.id) }
+          end
+
+          def decay_all
+            @bindings.each_value(&:decay!)
+          end
+
+          def prune_incoherent
+            @bindings.delete_if { |_, b| !b.coherent? }
+          end
+
+          def consciousness_report
+            experience = unified_experience
+            distribution = coherence_distribution
+
+            {
+              unified_experience:     experience&.to_h,
+              fragmentation_index:    fragmentation_index,
+              coherence_distribution: distribution,
+              stream_count:           @streams.size,
+              binding_count:          @bindings.size,
+              unbound_count:          unbound_streams.size
+            }
+          end
+
+          def to_h
+            {
+              stream_count:  @streams.size,
+              binding_count: @bindings.size,
+              unbound_count: unbound_streams.size,
+              fragmentation: fragmentation_index
+            }
+          end
+
+          private
+
+          def compute_initial_coherence(stream_ids)
+            return 0.0 if stream_ids.empty?
+
+            saliences = stream_ids.filter_map { |id| @streams[id]&.salience }
+            return 0.0 if saliences.empty?
+
+            (saliences.sum / saliences.size).round(10)
+          end
+
+          def coherence_distribution
+            Constants::COHERENCE_LABELS.to_h do |_range, label|
+              count = @bindings.values.count { |b| b.coherence_label == label }
+              [label, count]
+            end
+          end
+
+          def prune_streams_if_full
+            return if @streams.size < MAX_STREAMS
+
+            oldest = @streams.values.min_by(&:created_at)
+            @streams.delete(oldest.id) if oldest
+          end
+
+          def prune_bindings_if_full
+            return if @bindings.size < MAX_BINDINGS
+
+            oldest = @bindings.values.min_by(&:created_at)
+            @bindings.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/phenomenal_binding/helpers/binding_unit.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PhenomenalBinding
+      module Helpers
+        class BindingUnit
+          include Constants
+
+          attr_reader :id, :stream_ids, :binding_type, :coherence, :attention_weight, :created_at
+
+          def initialize(stream_ids:, binding_type:, coherence:, attention_weight: 0.5)
+            @id              = ::SecureRandom.uuid
+            @stream_ids      = stream_ids.dup
+            @binding_type    = binding_type
+            @coherence       = coherence.clamp(0.0, 1.0)
+            @attention_weight = attention_weight.clamp(0.0, 1.0)
+            @created_at = Time.now.utc
+          end
+
+          def add_stream(stream_id:)
+            @stream_ids << stream_id unless @stream_ids.include?(stream_id)
+          end
+
+          def remove_stream(stream_id:)
+            @stream_ids.delete(stream_id)
+          end
+
+          def reinforce!
+            @coherence = (@coherence + BINDING_BOOST).clamp(0.0, 1.0)
+          end
+
+          def decay!
+            @coherence = (@coherence - BINDING_DECAY).clamp(0.0, 1.0)
+          end
+
+          def coherent?
+            @coherence >= COHERENCE_THRESHOLD
+          end
+
+          def coherence_label
+            COHERENCE_LABELS.find { |range, _| range.cover?(@coherence) }&.last || :unbound
+          end
+
+          def stream_count
+            @stream_ids.size
+          end
+
+          def to_h
+            {
+              id:               @id,
+              stream_ids:       @stream_ids.dup,
+              binding_type:     @binding_type,
+              coherence:        @coherence.round(10),
+              attention_weight: @attention_weight.round(10),
+              coherent:         coherent?,
+              coherence_label:  coherence_label,
+              stream_count:     stream_count,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module PhenomenalBinding
+      module Helpers
+        module Constants
+          MAX_STREAMS   = 100
+          MAX_BINDINGS  = 200
+
+          COHERENCE_THRESHOLD = 0.6
+          BINDING_DECAY       = 0.03
+          BINDING_BOOST       = 0.08
+          DEFAULT_SALIENCE    = 0.5
+
+          BINDING_TYPES = %i[perceptual conceptual temporal narrative emotional].freeze
+
+          COHERENCE_LABELS = {
+            (0.8..)     => :unified,
+            (0.6...0.8) => :coherent,
+            (0.4...0.6) => :fragmented,
+            (0.2...0.4) => :dissociated,
+            (..0.2)     => :unbound
+          }.freeze
+
+          STREAM_TYPES = %i[perception thought emotion memory intention prediction].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/phenomenal_binding/helpers/stream.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module PhenomenalBinding
+      module Helpers
+        class Stream
+          include Constants
+
+          attr_reader :id, :stream_type, :content, :salience, :timestamp, :domain, :created_at
+
+          def initialize(stream_type:, content:, salience: DEFAULT_SALIENCE, domain: nil, timestamp: nil)
+            @id          = ::SecureRandom.uuid
+            @stream_type = stream_type
+            @content     = content
+            @salience    = salience.clamp(0.0, 1.0)
+            @domain      = domain
+            @timestamp   = timestamp || Time.now.utc
+            @created_at  = Time.now.utc
+          end
+
+          def salient?
+            @salience >= DEFAULT_SALIENCE
+          end
+
+          def fresh?(window: 30)
+            (Time.now.utc - created_at) <= window
+          end
+
+          def to_h
+            {
+              id:          @id,
+              stream_type: @stream_type,
+              content:     @content,
+              salience:    @salience.round(10),
+              domain:      @domain,
+              timestamp:   @timestamp,
+              created_at:  @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

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

data/lib/legion/extensions/phenomenal_binding.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/phenomenal_binding/version'
+require 'legion/extensions/phenomenal_binding/helpers/constants'
+require 'legion/extensions/phenomenal_binding/helpers/stream'
+require 'legion/extensions/phenomenal_binding/helpers/binding_unit'
+require 'legion/extensions/phenomenal_binding/helpers/binding_engine'
+require 'legion/extensions/phenomenal_binding/runners/phenomenal_binding'
+require 'legion/extensions/phenomenal_binding/client'
+
+module Legion
+  module Extensions
+    module PhenomenalBinding
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/phenomenal_binding/client'
+
+RSpec.describe Legion::Extensions::PhenomenalBinding::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to runner methods' do
+    expect(client).to respond_to(:register_stream)
+    expect(client).to respond_to(:create_binding)
+    expect(client).to respond_to(:reinforce_binding)
+    expect(client).to respond_to(:dissolve_binding)
+    expect(client).to respond_to(:unified_experience)
+    expect(client).to respond_to(:fragmentation_index)
+    expect(client).to respond_to(:binding_by_type)
+    expect(client).to respond_to(:streams_for_binding)
+    expect(client).to respond_to(:unbound_streams)
+    expect(client).to respond_to(:decay_all)
+    expect(client).to respond_to(:prune_incoherent)
+    expect(client).to respond_to(:consciousness_report)
+    expect(client).to respond_to(:engine_stats)
+  end
+
+  it 'maintains independent engine state per instance' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.register_stream(stream_type: :perception, content: 'only in c1')
+    expect(c1.engine_stats[:stream_count]).to eq(1)
+    expect(c2.engine_stats[:stream_count]).to eq(0)
+  end
+
+  it 'runs a full bind/reinforce/dissolve cycle' do
+    s = client.register_stream(stream_type: :thought, content: 'philosophy', salience: 0.75)
+    b = client.create_binding(stream_ids: [s[:stream][:id]], binding_type: :conceptual)
+    client.reinforce_binding(binding_id: b[:binding][:id])
+    expect(client.unified_experience[:unified_experience]).to be_a(Hash)
+    client.dissolve_binding(binding_id: b[:binding][:id])
+    expect(client.unified_experience[:unified_experience]).to be_nil
+  end
+
+  it 'builds a consciousness report across multiple streams and bindings' do
+    s1 = client.register_stream(stream_type: :perception, content: 'light', salience: 0.8)
+    s2 = client.register_stream(stream_type: :emotion, content: 'warmth', salience: 0.7)
+    s3 = client.register_stream(stream_type: :memory, content: 'familiar', salience: 0.9)
+    client.create_binding(stream_ids: [s1[:stream][:id], s2[:stream][:id]], binding_type: :emotional)
+    report = client.consciousness_report
+    expect(report[:stream_count]).to eq(3)
+    expect(report[:binding_count]).to eq(1)
+    expect(report[:unbound_count]).to eq(1) # s3 is unbound
+    _ = s3
+  end
+end