lex-feature-binding 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d449f9894bc3dc97a55225d9f6a6878a05fc4a73fae9641bf9825119188e8862
+  data.tar.gz: a9459e1caf0817290a4c96ecd8c4b3afee36f8b308b1d00f828f30bc697515b1
+SHA512:
+  metadata.gz: ac2f5a591b2c72076d2870b3601591569121b08b94d2400a32e8f44155b1f0eb7f2d406f440f1991a1d2e78c58406d0e7d9d278bdb3f0d253652fb49638b8d8d
+  data.tar.gz: 85d294af88ba119e6282609b25c2afe7e5100511aac34b6a12c8731f8278284e6ac56953a8d5e975b0d7e1b73d426e33c0992b5bb471cea8d371f8dead9759bc

data/README.md

@@ -0,0 +1,62 @@
+# lex-feature-binding
+
+Feature binding modeling for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Implements the cognitive binding problem — how separate features from different processing streams are combined into unified object percepts. Registers unbound feature sets across visual, auditory, semantic, spatial, temporal, and affective dimensions, then binds them into coherent bound objects. Detects binding conflicts when feature dimensions contradict each other, and manages a vividness-based object store with decay.
+
+Based on Treisman's Feature Integration Theory.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::FeatureBinding::Client.new
+
+# Register incoming features from multiple sensory streams
+client.register_features(
+  features: {
+    semantic: 'incoming HTTP request',
+    temporal: :recent,
+    affective: :neutral,
+    spatial: :network_boundary
+  }
+)
+# => { success: true, feature_set_id: "...", dimensions_present: [:semantic, :temporal, :affective, :spatial],
+#      ready_to_bind: true }
+
+# Bind into a unified object percept
+client.bind_features(feature_set_id: '...', binding_mode: :automatic)
+# => { success: true, object_id: "...", coherence: 0.75, bound: true, conflicts: [] }
+
+# Check for feature conflicts before binding
+client.detect_conflicts(feature_set_id: '...')
+# => { conflicts: [], conflict_count: 0, severity: :none }
+
+# Attend to an object to boost its coherence
+client.attend_to_object(object_id: '...')
+# => { coherence_boost: 0.2, new_coherence: 0.95 }
+
+# View current bound objects
+client.bound_objects
+# => { objects: [...sorted by vividness], count: 5 }
+
+# Overall binding quality
+client.binding_quality
+# => { avg_coherence: 0.72, coherence_label: :coherent, conflict_rate: 0.05 }
+
+# Periodic tick: decay vividness, archive faded objects
+client.update_feature_binding
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/legion/extensions/feature_binding/actors/decay.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::FeatureBinding::Runners::FeatureBinding
+          end
+
+          def runner_function
+            'update_feature_binding'
+          end
+
+          def time
+            30
+          end
+
+          def run_now?
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/feature_binding/helpers/constants'
+require 'legion/extensions/feature_binding/helpers/feature'
+require 'legion/extensions/feature_binding/helpers/bound_object'
+require 'legion/extensions/feature_binding/helpers/binding_field'
+require 'legion/extensions/feature_binding/runners/feature_binding'
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      class Client
+        include Runners::FeatureBinding
+
+        def initialize(field: nil, **)
+          @field = field || Helpers::BindingField.new
+        end
+
+        private
+
+        attr_reader :field
+      end
+    end
+  end
+end

data/lib/legion/extensions/feature_binding/helpers/binding_field.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      module Helpers
+        class BindingField
+          include Constants
+
+          attr_reader :features, :objects, :binding_history
+
+          def initialize
+            @features        = {}
+            @objects         = {}
+            @binding_history = []
+            @object_counter  = 0
+          end
+
+          def register_feature(id:, dimension:, value:, source: :perception, salience: 0.5)
+            return @features[id] if @features.key?(id)
+            return nil if @features.size >= MAX_FEATURES
+
+            @features[id] = Feature.new(id: id, dimension: dimension, value: value, source: source, salience: salience)
+          end
+
+          def bind(feature_ids:, attention: false)
+            ids = Array(feature_ids).select { |fid| @features.key?(fid) }
+            return nil if ids.size < 2
+            return nil if @objects.size >= MAX_OBJECTS
+
+            @object_counter += 1
+            obj_id = :"object_#{@object_counter}"
+            strength = attention ? DEFAULT_BINDING_STRENGTH + ATTENTION_BOOST : DEFAULT_BINDING_STRENGTH
+
+            obj = BoundObject.new(id: obj_id, feature_ids: ids, binding_strength: strength)
+            obj.confirm if attention
+            @objects[obj_id] = obj
+
+            record_binding(obj_id, ids, attention)
+            obj
+          end
+
+          def attend(object_id:)
+            obj = @objects[object_id]
+            return nil unless obj
+
+            obj.strengthen
+            obj.confirm unless obj.confirmed?
+            obj
+          end
+
+          def unbind(object_id:)
+            obj = @objects.delete(object_id)
+            !obj.nil?
+          end
+
+          def features_of(object_id:)
+            obj = @objects[object_id]
+            return [] unless obj
+
+            obj.feature_ids.filter_map { |fid| @features[fid]&.to_h }
+          end
+
+          def objects_with_feature(feature_id:)
+            @objects.values.select { |o| o.includes_feature?(feature_id) }.map(&:to_h)
+          end
+
+          def illusory_conjunctions
+            @objects.values.select { |o| o.state == :illusory }.map(&:to_h)
+          end
+
+          def unbound_features
+            bound_ids = @objects.values.flat_map(&:feature_ids).uniq
+            @features.values.reject { |f| bound_ids.include?(f.id) }.map(&:to_h)
+          end
+
+          def search_by_dimension(dimension:, value: nil)
+            matches = @features.values.select { |f| f.dimension == dimension }
+            matches = matches.select { |f| f.value == value } if value
+            matches.map(&:to_h)
+          end
+
+          def decay_all
+            @features.each_value(&:decay)
+            @features.reject! { |_, f| f.faded? }
+
+            @objects.each_value(&:decay)
+            @objects.reject! { |_, o| o.dissolved? }
+          end
+
+          def feature_count
+            @features.size
+          end
+
+          def object_count
+            @objects.size
+          end
+
+          def to_h
+            {
+              features:          @features.size,
+              objects:           @objects.size,
+              confirmed_objects: @objects.values.count(&:confirmed?),
+              illusory_count:    @objects.values.count { |o| o.state == :illusory },
+              unbound_features:  unbound_features.size,
+              history_size:      @binding_history.size
+            }
+          end
+
+          private
+
+          def record_binding(obj_id, feature_ids, attended)
+            @binding_history << { object_id: obj_id, features: feature_ids, attended: attended, at: Time.now.utc }
+            @binding_history.shift while @binding_history.size > MAX_BINDING_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/feature_binding/helpers/bound_object.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      module Helpers
+        class BoundObject
+          include Constants
+
+          attr_reader :id, :feature_ids, :bound_at, :confirmed_at
+          attr_accessor :binding_strength
+
+          def initialize(id:, feature_ids:, binding_strength: DEFAULT_BINDING_STRENGTH)
+            @id               = id
+            @feature_ids      = Array(feature_ids).uniq
+            @binding_strength = binding_strength.to_f.clamp(0.0, 1.0)
+            @bound_at         = Time.now.utc
+            @confirmed_at     = nil
+          end
+
+          def confirm
+            @confirmed_at = Time.now.utc
+            @binding_strength = [@binding_strength + ATTENTION_BOOST, 1.0].min
+          end
+
+          def confirmed?
+            !@confirmed_at.nil?
+          end
+
+          def strengthen(amount = ATTENTION_BOOST)
+            @binding_strength = [@binding_strength + amount, 1.0].min
+          end
+
+          def decay
+            @binding_strength = [@binding_strength - BINDING_DECAY, 0.0].max
+          end
+
+          def dissolved?
+            @binding_strength <= BINDING_STRENGTH_FLOOR
+          end
+
+          def state
+            if @binding_strength >= BINDING_CONFIRMATION_THRESHOLD && confirmed?
+              :bound
+            elsif @binding_strength >= ILLUSORY_CONJUNCTION_THRESHOLD
+              :tentative
+            elsif @binding_strength > BINDING_STRENGTH_FLOOR
+              :illusory
+            else
+              :unbound
+            end
+          end
+
+          def feature_count
+            @feature_ids.size
+          end
+
+          def includes_feature?(feature_id)
+            @feature_ids.include?(feature_id)
+          end
+
+          def strength_label
+            STRENGTH_LABELS.each { |range, lbl| return lbl if range.cover?(@binding_strength) }
+            :dissolving
+          end
+
+          def to_h
+            {
+              id:               @id,
+              features:         @feature_ids.dup,
+              feature_count:    feature_count,
+              binding_strength: @binding_strength.round(4),
+              strength_label:   strength_label,
+              state:            state,
+              state_label:      BINDING_STATE_LABELS[state],
+              confirmed:        confirmed?,
+              bound_at:         @bound_at,
+              confirmed_at:     @confirmed_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      module Helpers
+        module Constants
+          MAX_FEATURES = 200
+          MAX_BINDINGS = 100
+          MAX_OBJECTS = 50
+          MAX_BINDING_HISTORY = 200
+
+          BINDING_STRENGTH_FLOOR = 0.05
+          BINDING_DECAY = 0.01
+          BINDING_ALPHA = 0.15
+          ATTENTION_BOOST = 0.3
+          DEFAULT_BINDING_STRENGTH = 0.3
+
+          ILLUSORY_CONJUNCTION_THRESHOLD = 0.3
+          BINDING_CONFIRMATION_THRESHOLD = 0.6
+          FEATURE_SALIENCE_FLOOR = 0.05
+
+          FEATURE_DIMENSIONS = %i[
+            shape color size motion texture location
+            pitch volume timbre temporal_pattern
+            semantic syntactic pragmatic
+            valence arousal familiarity
+          ].freeze
+
+          BINDING_STATE_LABELS = {
+            bound:     'features unified into coherent object',
+            tentative: 'binding forming, not yet confirmed',
+            illusory:  'incorrect binding (conjunction error)',
+            unbound:   'features floating in pre-attentive field'
+          }.freeze
+
+          STRENGTH_LABELS = {
+            (0.8..)     => :solid,
+            (0.6...0.8) => :firm,
+            (0.4...0.6) => :forming,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :dissolving
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/feature_binding/helpers/feature.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      module Helpers
+        class Feature
+          include Constants
+
+          attr_reader :id, :dimension, :value, :source, :detected_at
+          attr_accessor :salience
+
+          def initialize(id:, dimension:, value:, source: :perception, salience: 0.5)
+            @id          = id
+            @dimension   = dimension
+            @value       = value
+            @source      = source
+            @salience    = salience.to_f.clamp(0.0, 1.0)
+            @detected_at = Time.now.utc
+          end
+
+          def salient?
+            @salience > FEATURE_SALIENCE_FLOOR
+          end
+
+          def decay
+            @salience = [@salience - BINDING_DECAY, 0.0].max
+          end
+
+          def faded?
+            @salience <= FEATURE_SALIENCE_FLOOR
+          end
+
+          def to_h
+            {
+              id:          @id,
+              dimension:   @dimension,
+              value:       @value,
+              source:      @source,
+              salience:    @salience.round(4),
+              detected_at: @detected_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      module Runners
+        module FeatureBinding
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_feature(id:, dimension:, value:, source: :perception, salience: 0.5, **)
+            Legion::Logging.debug "[feature_binding] register: id=#{id} dim=#{dimension} val=#{value}"
+            feature = field.register_feature(id: id, dimension: dimension, value: value, source: source,
+                                             salience: salience)
+            if feature
+              { success: true, feature: feature.to_h, total_features: field.feature_count }
+            else
+              { success: false, reason: :limit_reached }
+            end
+          end
+
+          def bind_features(feature_ids:, attention: false, **)
+            Legion::Logging.debug "[feature_binding] bind: features=#{feature_ids} attention=#{attention}"
+            obj = field.bind(feature_ids: feature_ids, attention: attention)
+            if obj
+              { success: true, object: obj.to_h, total_objects: field.object_count }
+            else
+              { success: false, reason: :insufficient_features }
+            end
+          end
+
+          def attend_object(object_id:, **)
+            Legion::Logging.debug "[feature_binding] attend: object=#{object_id}"
+            obj = field.attend(object_id: object_id.to_sym)
+            if obj
+              { success: true, object: obj.to_h }
+            else
+              { success: false, reason: :not_found }
+            end
+          end
+
+          def unbind_object(object_id:, **)
+            Legion::Logging.debug "[feature_binding] unbind: object=#{object_id}"
+            removed = field.unbind(object_id: object_id.to_sym)
+            { success: removed }
+          end
+
+          def features_of_object(object_id:, **)
+            features = field.features_of(object_id: object_id.to_sym)
+            Legion::Logging.debug "[feature_binding] features_of: object=#{object_id} count=#{features.size}"
+            { success: true, features: features, count: features.size }
+          end
+
+          def objects_with(feature_id:, **)
+            objects = field.objects_with_feature(feature_id: feature_id)
+            Legion::Logging.debug "[feature_binding] objects_with: feature=#{feature_id} count=#{objects.size}"
+            { success: true, objects: objects, count: objects.size }
+          end
+
+          def illusory_conjunctions(**)
+            illusions = field.illusory_conjunctions
+            Legion::Logging.debug "[feature_binding] illusory: #{illusions.size}"
+            { success: true, illusory: illusions, count: illusions.size }
+          end
+
+          def unbound_features(**)
+            unbound = field.unbound_features
+            Legion::Logging.debug "[feature_binding] unbound: #{unbound.size}"
+            { success: true, unbound: unbound, count: unbound.size }
+          end
+
+          def search_features(dimension:, value: nil, **)
+            results = field.search_by_dimension(dimension: dimension, value: value)
+            Legion::Logging.debug "[feature_binding] search: dim=#{dimension} found=#{results.size}"
+            { success: true, results: results, count: results.size }
+          end
+
+          def update_feature_binding(**)
+            Legion::Logging.debug '[feature_binding] tick'
+            field.decay_all
+            { success: true, features: field.feature_count, objects: field.object_count }
+          end
+
+          def feature_binding_stats(**)
+            Legion::Logging.debug '[feature_binding] stats'
+            { success: true, stats: field.to_h }
+          end
+
+          private
+
+          def field
+            @field ||= Helpers::BindingField.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/feature_binding.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/feature_binding/version'
+require 'legion/extensions/feature_binding/helpers/constants'
+require 'legion/extensions/feature_binding/helpers/feature'
+require 'legion/extensions/feature_binding/helpers/bound_object'
+require 'legion/extensions/feature_binding/helpers/binding_field'
+require 'legion/extensions/feature_binding/runners/feature_binding'
+require 'legion/extensions/feature_binding/client'
+
+module Legion
+  module Extensions
+    module FeatureBinding
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: lex-feature-binding
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Treisman's Feature Integration Theory for LegionIO — attention as glue
+  binding features into unified percepts
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/feature_binding.rb
+- lib/legion/extensions/feature_binding/actors/decay.rb
+- lib/legion/extensions/feature_binding/client.rb
+- lib/legion/extensions/feature_binding/helpers/binding_field.rb
+- lib/legion/extensions/feature_binding/helpers/bound_object.rb
+- lib/legion/extensions/feature_binding/helpers/constants.rb
+- lib/legion/extensions/feature_binding/helpers/feature.rb
+- lib/legion/extensions/feature_binding/runners/feature_binding.rb
+- lib/legion/extensions/feature_binding/version.rb
+homepage: https://github.com/LegionIO/lex-feature-binding
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-feature-binding
+  source_code_uri: https://github.com/LegionIO/lex-feature-binding
+  documentation_uri: https://github.com/LegionIO/lex-feature-binding/blob/master/README.md
+  changelog_uri: https://github.com/LegionIO/lex-feature-binding/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-feature-binding/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LegionIO feature binding extension
+test_files: []