lex-episodic-buffer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cd282b5729f073c270e41c5c9e96c351297f6fec517ac799d10a8357b908e45
+  data.tar.gz: bd8a210f73d8577c0e98eb5c040797f1e1dcc06592cace5a9c5af95f70488c41
+SHA512:
+  metadata.gz: 5c1841812d99d688556a87112f239909c8d8fb98ff6633c6269d29be81c26db79633597e4c4c9e9a56c42f89446a72abae1246ffb28f8603484865687b63744d
+  data.tar.gz: a2ffe44c971e1ee908855949938f461cfab27a9d4ff9244e9ed3bef00f5e64586f5bad10f6fd956c478d1053c64da2087e49297469f6b3f603bac68ef12fea85

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      module Actor
+        class Decay < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::EpisodicBuffer::Runners::EpisodicBuffer
+          end
+
+          def runner_function
+            'update_episodic_buffer'
+          end
+
+          def time
+            15
+          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/episodic_buffer/client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/episodic_buffer/runners/episodic_buffer'
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      class Client
+        include Legion::Extensions::EpisodicBuffer::Runners::EpisodicBuffer
+
+        def initialize(store: nil, **)
+          @default_store = store || Helpers::EpisodicStore.new
+        end
+
+        private
+
+        attr_reader :default_store
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      module Helpers
+        module Constants
+          MAX_EPISODES             = 30
+          MAX_BINDINGS_PER_EPISODE = 10
+          MAX_HISTORY              = 200
+          EPISODE_TTL              = 120
+          BINDING_STRENGTH_FLOOR   = 0.05
+          BINDING_DECAY            = 0.015
+          DEFAULT_BINDING_STRENGTH = 0.5
+          ATTENTION_BOOST          = 0.2
+          REHEARSAL_BOOST          = 0.15
+          INTEGRATION_THRESHOLD    = 0.4
+          RECENTLY_ACCESSED_WINDOW = 30
+
+          MODALITIES = %i[verbal visual spatial semantic emotional procedural temporal].freeze
+
+          COHERENCE_LABELS = {
+            (0.0...0.3)  => :fragmented,
+            (0.3...0.6)  => :partial,
+            (0.6...0.85) => :coherent,
+            (0.85..1.0)  => :vivid
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/episodic_buffer/helpers/episode.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      module Helpers
+        class Episode
+          include Constants
+
+          attr_reader :id, :bindings, :created_at, :last_accessed
+
+          def initialize
+            @id            = SecureRandom.uuid
+            @bindings      = {}
+            @created_at    = Time.now
+            @last_accessed = Time.now
+          end
+
+          def add_binding(modality:, content:, source:, strength: DEFAULT_BINDING_STRENGTH)
+            return { added: false, reason: :capacity_full } if @bindings.size >= MAX_BINDINGS_PER_EPISODE
+
+            binding = EpisodicBinding.new(modality: modality, content: content, source: source, strength: strength)
+            @bindings[binding.id] = binding
+            { added: true, binding_id: binding.id }
+          end
+
+          def remove_binding(binding_id:)
+            removed = !@bindings.delete(binding_id).nil?
+            { removed: removed, binding_id: binding_id }
+          end
+
+          def attend
+            @last_accessed = Time.now
+            @bindings.each_value { |b| b.strengthen(ATTENTION_BOOST) }
+          end
+
+          def rehearse
+            @last_accessed = Time.now
+            @bindings.each_value { |b| b.strengthen(REHEARSAL_BOOST) }
+          end
+
+          def modalities_present
+            @bindings.values.map(&:modality).uniq
+          end
+
+          def coherence
+            integrated = @bindings.values.select(&:integrated?)
+            return 0.0 if integrated.empty?
+
+            integrated.sum(&:strength) / integrated.size
+          end
+
+          def coherence_label
+            score = coherence
+            COHERENCE_LABELS.each do |range, label|
+              return label if range.cover?(score)
+            end
+            :fragmented
+          end
+
+          def multimodal?
+            modalities_present.size >= 2
+          end
+
+          def expired?
+            age = Time.now - @created_at
+            age > EPISODE_TTL && !recently_accessed?
+          end
+
+          def decay_bindings
+            @bindings.each_value(&:decay)
+            @bindings.delete_if { |_, b| b.faded? }
+          end
+
+          def to_h
+            {
+              id:              @id,
+              bindings:        @bindings.transform_values(&:to_h),
+              created_at:      @created_at,
+              last_accessed:   @last_accessed,
+              modalities:      modalities_present,
+              coherence:       coherence,
+              coherence_label: coherence_label,
+              multimodal:      multimodal?,
+              binding_count:   @bindings.size
+            }
+          end
+
+          private
+
+          def recently_accessed?
+            (Time.now - @last_accessed) <= RECENTLY_ACCESSED_WINDOW
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/episodic_buffer/helpers/episodic_binding.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      module Helpers
+        class EpisodicBinding
+          include Constants
+
+          attr_reader :id, :modality, :content, :source, :strength
+
+          def initialize(modality:, content:, source:, strength: DEFAULT_BINDING_STRENGTH)
+            raise ArgumentError, "invalid modality: #{modality}" unless MODALITIES.include?(modality.to_sym)
+
+            @id       = SecureRandom.uuid
+            @modality = modality.to_sym
+            @content  = content
+            @source   = source.to_sym
+            @strength = strength.to_f.clamp(0.0, 1.0)
+          end
+
+          def decay
+            @strength = [@strength - BINDING_DECAY, 0.0].max
+          end
+
+          def strengthen(amount)
+            @strength = [@strength + amount.to_f, 1.0].min
+          end
+
+          def integrated?
+            @strength >= INTEGRATION_THRESHOLD
+          end
+
+          def faded?
+            @strength <= BINDING_STRENGTH_FLOOR
+          end
+
+          def to_h
+            {
+              id:       @id,
+              modality: @modality,
+              content:  @content,
+              source:   @source,
+              strength: @strength
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/episodic_buffer/helpers/episodic_store.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      module Helpers
+        class EpisodicStore
+          include Constants
+
+          attr_reader :episodes, :history
+
+          def initialize
+            @episodes = {}
+            @history  = []
+          end
+
+          def create_episode
+            evict_if_full
+            episode = Episode.new
+            @episodes[episode.id] = episode
+            record_history(:create, episode.id)
+            episode
+          end
+
+          def add_to_episode(episode_id:, modality:, content:, source:, strength: DEFAULT_BINDING_STRENGTH)
+            episode = @episodes[episode_id]
+            return { success: false, reason: :episode_not_found } unless episode
+
+            result = episode.add_binding(modality: modality, content: content, source: source, strength: strength)
+            record_history(:add_binding, episode_id) if result[:added]
+            result
+          end
+
+          def attend_episode(episode_id:)
+            episode = @episodes[episode_id]
+            return { success: false, reason: :episode_not_found } unless episode
+
+            episode.attend
+            record_history(:attend, episode_id)
+            { success: true, episode_id: episode_id }
+          end
+
+          def rehearse_episode(episode_id:)
+            episode = @episodes[episode_id]
+            return { success: false, reason: :episode_not_found } unless episode
+
+            episode.rehearse
+            record_history(:rehearse, episode_id)
+            { success: true, episode_id: episode_id }
+          end
+
+          def integrate(episode_id:)
+            episode = @episodes[episode_id]
+            return { integrated: false, reason: :episode_not_found } unless episode
+
+            coherence = episode.coherence
+            integrated = coherence >= INTEGRATION_THRESHOLD
+            {
+              integrated:      integrated,
+              episode_id:      episode_id,
+              coherence:       coherence,
+              coherence_label: episode.coherence_label
+            }
+          end
+
+          def retrieve_by_modality(modality:)
+            mod = modality.to_sym
+            @episodes.values.select { |ep| ep.modalities_present.include?(mod) }
+          end
+
+          def retrieve_multimodal
+            @episodes.values.select(&:multimodal?)
+          end
+
+          def most_coherent(limit: 5)
+            @episodes.values
+                     .sort_by { |ep| -ep.coherence }
+                     .first(limit)
+          end
+
+          def tick
+            expired_count = 0
+            @episodes.delete_if do |_, ep|
+              ep.decay_bindings
+              if ep.expired?
+                expired_count += 1
+                true
+              else
+                false
+              end
+            end
+            { decayed: @episodes.size, expired: expired_count }
+          end
+
+          def count
+            @episodes.size
+          end
+
+          def to_h
+            {
+              episode_count:    @episodes.size,
+              history_size:     @history.size,
+              multimodal_count: retrieve_multimodal.size,
+              avg_coherence:    average_coherence
+            }
+          end
+
+          private
+
+          def evict_if_full
+            return unless @episodes.size >= MAX_EPISODES
+
+            expired = @episodes.values.select(&:expired?)
+            if expired.any?
+              oldest = expired.min_by(&:created_at)
+              @episodes.delete(oldest.id)
+            else
+              lowest = @episodes.values.min_by(&:coherence)
+              @episodes.delete(lowest.id) if lowest
+            end
+          end
+
+          def record_history(event, episode_id)
+            @history << { event: event, episode_id: episode_id, at: Time.now }
+            @history.shift if @history.size > MAX_HISTORY
+          end
+
+          def average_coherence
+            return 0.0 if @episodes.empty?
+
+            @episodes.values.sum(&:coherence) / @episodes.size
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      module Runners
+        module EpisodicBuffer
+          def create_episode(**)
+            store = default_store
+            episode = store.create_episode
+            Legion::Logging.debug "[episodic_buffer] created episode id=#{episode.id[0..7]}"
+            { success: true, episode_id: episode.id, created_at: episode.created_at }
+          end
+
+          def add_binding(episode_id:, modality:, content:, source:,
+                          strength: Helpers::Constants::DEFAULT_BINDING_STRENGTH, **)
+            unless Helpers::Constants::MODALITIES.include?(modality.to_sym)
+              raise ArgumentError, "invalid modality: #{modality}"
+            end
+
+            store  = default_store
+            result = store.add_to_episode(
+              episode_id: episode_id,
+              modality:   modality.to_sym,
+              content:    content,
+              source:     source,
+              strength:   strength
+            )
+
+            if result[:added]
+              Legion::Logging.debug "[episodic_buffer] add_binding ep=#{episode_id[0..7]} mod=#{modality}"
+              { success: true, episode_id: episode_id, binding_id: result[:binding_id] }
+            else
+              Legion::Logging.debug "[episodic_buffer] add_binding failed ep=#{episode_id[0..7]} r=#{result[:reason]}"
+              { success: false, episode_id: episode_id, reason: result[:reason] }
+            end
+          end
+
+          def attend_episode(episode_id:, **)
+            store  = default_store
+            result = store.attend_episode(episode_id: episode_id)
+            Legion::Logging.debug "[episodic_buffer] attend ep=#{episode_id[0..7]} success=#{result[:success]}"
+            result.merge(success: result[:success])
+          end
+
+          def rehearse_episode(episode_id:, **)
+            store  = default_store
+            result = store.rehearse_episode(episode_id: episode_id)
+            Legion::Logging.debug "[episodic_buffer] rehearse ep=#{episode_id[0..7]} success=#{result[:success]}"
+            result.merge(success: result[:success])
+          end
+
+          def check_integration(episode_id:, **)
+            store  = default_store
+            result = store.integrate(episode_id: episode_id)
+            Legion::Logging.debug "[episodic_buffer] check_integration ep=#{episode_id[0..7]} ok=#{result[:integrated]}"
+            result.merge(success: true)
+          end
+
+          def retrieve_by_modality(modality:, **)
+            store    = default_store
+            episodes = store.retrieve_by_modality(modality: modality.to_sym)
+            Legion::Logging.debug "[episodic_buffer] retrieve_by_modality mod=#{modality} count=#{episodes.size}"
+            { success: true, modality: modality, count: episodes.size, episodes: episodes.map(&:to_h) }
+          end
+
+          def retrieve_multimodal(**)
+            store    = default_store
+            episodes = store.retrieve_multimodal
+            Legion::Logging.debug "[episodic_buffer] retrieve_multimodal count=#{episodes.size}"
+            { success: true, count: episodes.size, episodes: episodes.map(&:to_h) }
+          end
+
+          def most_coherent(limit: 5, **)
+            store    = default_store
+            episodes = store.most_coherent(limit: limit)
+            Legion::Logging.debug "[episodic_buffer] most_coherent limit=#{limit} returned=#{episodes.size}"
+            { success: true, count: episodes.size, episodes: episodes.map(&:to_h) }
+          end
+
+          def update_episodic_buffer(**)
+            store  = default_store
+            result = store.tick
+            Legion::Logging.debug "[episodic_buffer] tick decayed=#{result[:decayed]} expired=#{result[:expired]}"
+            { success: true }.merge(result)
+          end
+
+          def episodic_buffer_stats(**)
+            store = default_store
+            stats = store.to_h
+            Legion::Logging.debug "[episodic_buffer] stats episodes=#{stats[:episode_count]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def default_store
+            @default_store ||= Helpers::EpisodicStore.new
+          end
+
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/episodic_buffer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/episodic_buffer/version'
+require 'legion/extensions/episodic_buffer/helpers/constants'
+require 'legion/extensions/episodic_buffer/helpers/episodic_binding'
+require 'legion/extensions/episodic_buffer/helpers/episode'
+require 'legion/extensions/episodic_buffer/helpers/episodic_store'
+require 'legion/extensions/episodic_buffer/runners/episodic_buffer'
+
+module Legion
+  module Extensions
+    module EpisodicBuffer
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: lex-episodic-buffer
+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: Baddeley's episodic buffer — binds multimodal information into coherent
+  episodic representations for the LegionIO cognitive architecture
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/episodic_buffer.rb
+- lib/legion/extensions/episodic_buffer/actors/decay.rb
+- lib/legion/extensions/episodic_buffer/client.rb
+- lib/legion/extensions/episodic_buffer/helpers/constants.rb
+- lib/legion/extensions/episodic_buffer/helpers/episode.rb
+- lib/legion/extensions/episodic_buffer/helpers/episodic_binding.rb
+- lib/legion/extensions/episodic_buffer/helpers/episodic_store.rb
+- lib/legion/extensions/episodic_buffer/runners/episodic_buffer.rb
+- lib/legion/extensions/episodic_buffer/version.rb
+homepage: https://github.com/LegionIO/lex-episodic-buffer
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-episodic-buffer
+  source_code_uri: https://github.com/LegionIO/lex-episodic-buffer
+  documentation_uri: https://github.com/LegionIO/lex-episodic-buffer
+  changelog_uri: https://github.com/LegionIO/lex-episodic-buffer
+  bug_tracker_uri: https://github.com/LegionIO/lex-episodic-buffer/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: LEX Episodic Buffer
+test_files: []