lex-cognitive-map 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad240137c690c873c8fba327efe82c4a668c09702c4eec867fcb5ac55130bd47
+  data.tar.gz: 9b016dc621682fc8c6875f3dd2bb962c06da483d7397ba46ee7cebb5829940d7
+SHA512:
+  metadata.gz: d895cc4c83448bdbe6a2fa7fc2a3519d3678738c964b9d176af16e09247387f3378e42cb04823f65beccca8f272ece16830e30d25eceeb7319b1915789ad8ca5
+  data.tar.gz: a4e631f5fdd5c63372a2ac88b2f407d2626255faff4e57b1d18f50b97e937d21a4ee0d119e8d00620bd7624ffdbebc3e0be3a4c115c527cc5d6b7d011b7ef699

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-cognitive-map.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_map/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-map'
+  spec.version       = Legion::Extensions::CognitiveMap::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Map'
+  spec.description   = "Tolman's cognitive map + O'Keefe/Moser place and grid cell theory for brain-modeled agentic AI"
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-map'
+  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-cognitive-map'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-map'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-map'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-map/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-map.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_map/helpers/constants'
+require 'legion/extensions/cognitive_map/helpers/location'
+require 'legion/extensions/cognitive_map/helpers/graph_traversal'
+require 'legion/extensions/cognitive_map/helpers/cognitive_map_store'
+require 'legion/extensions/cognitive_map/runners/cognitive_map'
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      class Client
+        include Runners::CognitiveMap
+
+        def initialize(map_store: nil, **)
+          @map_store = map_store || Helpers::CognitiveMapStore.new
+        end
+
+        private
+
+        attr_reader :map_store
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_map/helpers/cognitive_map_store.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      module Helpers
+        class CognitiveMapStore
+          attr_reader :current_context
+
+          def initialize
+            @contexts = {}
+            @current_context = :default
+            @path_cache = {}
+            @visit_history = []
+            ensure_context(@current_context)
+          end
+
+          def add_location(id:, domain: :general, properties: {})
+            return false if locations.size >= Constants::MAX_LOCATIONS && !locations.key?(id)
+
+            locations[id] ||= Location.new(id: id, domain: domain, properties: properties)
+            true
+          end
+
+          def location(id)
+            locations[id]
+          end
+
+          def remove_location(id)
+            loc = locations.delete(id)
+            return false unless loc
+
+            locations.each_value { |l| l.remove_neighbor(id) }
+            invalidate_path_cache
+            true
+          end
+
+          def connect(from:, to:, distance: Constants::DEFAULT_DISTANCE, bidirectional: true)
+            return false unless locations.key?(from) && locations.key?(to)
+
+            locations[from].add_neighbor(to, distance: distance)
+            locations[to].add_neighbor(from, distance: distance) if bidirectional
+            invalidate_path_cache
+            true
+          end
+
+          def disconnect(from:, to:)
+            return false unless locations.key?(from)
+
+            locations[from].remove_neighbor(to)
+            invalidate_path_cache
+            true
+          end
+
+          def visit(id:)
+            loc = locations[id]
+            return { found: false } unless loc
+
+            loc.visit
+            record_visit(id)
+            { found: true, id: id, visit_count: loc.visit_count, familiarity: loc.familiarity.round(4) }
+          end
+
+          def shortest_path(from:, to:)
+            return { found: false, reason: :missing_start } unless locations.key?(from)
+            return { found: false, reason: :missing_end } unless locations.key?(to)
+            return { found: true, path: [from], distance: 0.0 } if from == to
+
+            fetch_or_compute_path(from, to)
+          end
+
+          def neighbors_of(id:)
+            loc = locations[id]
+            return [] unless loc
+
+            loc.neighbors.map { |nid, dist| { id: nid, distance: dist, category: Constants.distance_category(dist) } }
+          end
+
+          def reachable_from(id:, max_distance: 3.0)
+            return [] unless locations.key?(id)
+
+            GraphTraversal.bfs_reachable(locations, id, max_distance)
+          end
+
+          def clusters
+            GraphTraversal.connected_components(locations)
+          end
+
+          def most_familiar(n: 10)
+            locations.values.sort_by { |l| -l.familiarity }.first(n).map(&:to_h)
+          end
+
+          def decay_all
+            faded_ids = collect_faded
+            faded_ids.each { |id| remove_location(id) }
+            invalidate_path_cache if faded_ids.any?
+            { decayed: locations.size, pruned: faded_ids.size }
+          end
+
+          def context_switch(context_id:)
+            return { switched: false, reason: :max_contexts } if over_context_limit?(context_id)
+
+            ensure_context(context_id)
+            @current_context = context_id
+            invalidate_path_cache
+            { switched: true, context: context_id, location_count: locations.size }
+          end
+
+          def to_h
+            {
+              context:        @current_context,
+              context_count:  @contexts.size,
+              location_count: locations.size,
+              edge_count:     total_edges,
+              visit_history:  @visit_history.size,
+              cached_paths:   @path_cache.size
+            }
+          end
+
+          def location_count
+            locations.size
+          end
+
+          private
+
+          def locations
+            @contexts[@current_context]
+          end
+
+          def ensure_context(context_id)
+            @contexts[context_id] ||= {}
+          end
+
+          def over_context_limit?(context_id)
+            @contexts.size >= Constants::MAX_CONTEXTS && !@contexts.key?(context_id)
+          end
+
+          def record_visit(id)
+            @visit_history << { id: id, at: Time.now.utc }
+            @visit_history.shift if @visit_history.size > Constants::MAX_VISIT_HISTORY
+          end
+
+          def invalidate_path_cache
+            @path_cache.clear
+          end
+
+          def total_edges
+            locations.values.sum { |l| l.neighbors.size }
+          end
+
+          def collect_faded
+            faded = []
+            locations.each_value do |loc|
+              loc.decay
+              faded << loc.id if loc.faded?
+            end
+            faded
+          end
+
+          def fetch_or_compute_path(from, to)
+            cache_key = "#{@current_context}:#{from}->#{to}"
+            return @path_cache[cache_key] if @path_cache[cache_key]
+
+            result = GraphTraversal.dijkstra(locations, from, to)
+            if result[:found]
+              @path_cache[cache_key] = result
+              @path_cache.shift if @path_cache.size > Constants::MAX_PATHS_CACHED
+            end
+            result
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      module Helpers
+        module Constants
+          # Graph size limits
+          MAX_LOCATIONS          = 500
+          MAX_EDGES_PER_LOCATION = 20
+          MAX_PATHS_CACHED       = 100
+
+          # Edge weights
+          DEFAULT_DISTANCE = 1.0
+          DISTANCE_FLOOR   = 0.01
+
+          # Familiarity EMA
+          FAMILIARITY_ALPHA = 0.12
+          FAMILIARITY_DECAY = 0.005
+          FAMILIARITY_FLOOR = 0.05
+          VISIT_BOOST       = 0.1
+
+          # Visit history ring buffer
+          MAX_VISIT_HISTORY = 300
+
+          # Context remapping
+          REMAP_THRESHOLD = 0.5
+          MAX_CONTEXTS    = 10
+
+          # Familiarity level labels (ascending thresholds)
+          FAMILIARITY_LEVELS = {
+            (0.0...0.2) => :unknown,
+            (0.2...0.4) => :sparse,
+            (0.4...0.6) => :moderate,
+            (0.6...0.8) => :familiar,
+            (0.8..1.0)  => :intimate
+          }.freeze
+
+          # Distance category labels (ascending thresholds)
+          DISTANCE_CATEGORIES = {
+            (0.0...0.5) => :adjacent,
+            (0.5...1.5) => :near,
+            (1.5...3.0) => :moderate,
+            (3.0...6.0) => :distant,
+            (6.0..)     => :remote
+          }.freeze
+
+          module_function
+
+          def familiarity_level(value)
+            FAMILIARITY_LEVELS.each do |range, label|
+              return label if range.cover?(value)
+            end
+            :intimate
+          end
+
+          def distance_category(value)
+            DISTANCE_CATEGORIES.each do |range, label|
+              return label if range.cover?(value)
+            end
+            :remote
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_map/helpers/graph_traversal.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      module Helpers
+        module GraphTraversal
+          module_function
+
+          def dijkstra(locations, from, to)
+            dist = Hash.new(Float::INFINITY)
+            prev = {}
+            dist[from] = 0.0
+            queue = [[0.0, from]]
+
+            until queue.empty?
+              d, u = queue.min_by { |x, _| x }
+              queue.delete([d, u])
+              break if u == to
+              next if d > dist[u]
+
+              relax_edges(locations, u, dist, prev, queue)
+            end
+
+            build_path_result(locations, prev, from, to, dist[to])
+          end
+
+          def bfs_reachable(locations, start, max_distance)
+            visited = { start => 0.0 }
+            queue = [[0.0, start]]
+            reachable = []
+
+            until queue.empty?
+              dist, current = queue.min_by { |d, _| d }
+              queue.delete([dist, current])
+              next if dist > max_distance
+
+              reachable << { id: current, distance: dist.round(4) } unless current == start
+              expand_neighbors(locations, current, dist, max_distance, visited, queue)
+            end
+
+            reachable.sort_by { |r| r[:distance] }
+          end
+
+          def connected_components(locations)
+            visited = {}
+            components = []
+            locations.each_key do |id|
+              next if visited[id]
+
+              component = []
+              bfs_component(locations, id, visited, component)
+              components << component
+            end
+            components
+          end
+
+          def relax_edges(locations, u, dist, prev, queue)
+            loc = locations[u]
+            return unless loc
+
+            loc.neighbors.each do |v, weight|
+              alt = dist[u] + weight
+              next unless alt < dist[v]
+
+              dist[v] = alt
+              prev[v] = u
+              queue << [alt, v]
+            end
+          end
+
+          def build_path_result(_locations, prev, from, to, cost)
+            return { found: false, reason: :no_path } if cost == Float::INFINITY
+
+            path = reconstruct_path(prev, from, to)
+            path.empty? ? { found: false, reason: :no_path } : { found: true, path: path, distance: cost.round(4) }
+          end
+
+          def reconstruct_path(prev, from, to)
+            path = []
+            current = to
+            while current
+              path.unshift(current)
+              current = prev[current]
+            end
+            path.first == from ? path : []
+          end
+
+          def expand_neighbors(locations, current, dist, max_distance, visited, queue)
+            loc = locations[current]
+            return unless loc
+
+            loc.neighbors.each do |nid, edge_dist|
+              new_dist = dist + edge_dist
+              next if new_dist > max_distance
+              next if visited.key?(nid) && visited[nid] <= new_dist
+
+              visited[nid] = new_dist
+              queue << [new_dist, nid]
+            end
+          end
+
+          def bfs_component(locations, start, visited, component)
+            queue = [start]
+            while (current = queue.shift)
+              next if visited[current]
+
+              visited[current] = true
+              component << current
+              loc = locations[current]
+              next unless loc
+
+              loc.neighbors.each_key { |nid| queue << nid unless visited[nid] }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_map/helpers/location.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      module Helpers
+        class Location
+          attr_reader :id, :domain, :properties, :visit_count, :last_visited, :neighbors, :familiarity
+
+          def initialize(id:, domain: :general, properties: {})
+            @id           = id
+            @domain       = domain
+            @properties   = properties
+            @familiarity  = Constants::FAMILIARITY_FLOOR
+            @visit_count  = 0
+            @last_visited = nil
+            @neighbors    = {} # neighbor_id => distance
+          end
+
+          def visit
+            @visit_count  += 1
+            @last_visited  = Time.now.utc
+            @familiarity   = [@familiarity + Constants::VISIT_BOOST, 1.0].min
+          end
+
+          def add_neighbor(neighbor_id, distance: Constants::DEFAULT_DISTANCE)
+            distance = [distance, Constants::DISTANCE_FLOOR].max
+            return if @neighbors.size >= Constants::MAX_EDGES_PER_LOCATION && !@neighbors.key?(neighbor_id)
+
+            @neighbors[neighbor_id] = distance
+          end
+
+          def remove_neighbor(neighbor_id)
+            @neighbors.delete(neighbor_id)
+          end
+
+          def decay
+            new_val = @familiarity - Constants::FAMILIARITY_DECAY
+            @familiarity = [new_val, Constants::FAMILIARITY_FLOOR].max
+          end
+
+          def faded?
+            @familiarity <= Constants::FAMILIARITY_FLOOR && @visit_count.zero?
+          end
+
+          def label
+            Constants.familiarity_level(@familiarity)
+          end
+
+          def to_h
+            {
+              id:           @id,
+              domain:       @domain,
+              properties:   @properties,
+              familiarity:  @familiarity.round(4),
+              label:        label,
+              visit_count:  @visit_count,
+              last_visited: @last_visited,
+              neighbor_ids: @neighbors.keys,
+              edge_count:   @neighbors.size
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      module Runners
+        module CognitiveMap
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_location(id:, domain: :general, properties: {}, **)
+            result = map_store.add_location(id: id, domain: domain, properties: properties)
+            if result
+              Legion::Logging.debug "[cognitive_map] add_location id=#{id} domain=#{domain}"
+              { success: true, id: id, domain: domain }
+            else
+              Legion::Logging.warn "[cognitive_map] add_location failed: capacity or duplicate id=#{id}"
+              { success: false, id: id, reason: :capacity_or_duplicate }
+            end
+          end
+
+          def connect_locations(from:, to:, distance: Helpers::Constants::DEFAULT_DISTANCE,
+                                bidirectional: true, **)
+            result = map_store.connect(from: from, to: to, distance: distance, bidirectional: bidirectional)
+            if result
+              Legion::Logging.debug "[cognitive_map] connect from=#{from} to=#{to} distance=#{distance}"
+              { success: true, from: from, to: to, distance: distance, bidirectional: bidirectional }
+            else
+              Legion::Logging.warn "[cognitive_map] connect failed: missing location from=#{from} to=#{to}"
+              { success: false, from: from, to: to, reason: :missing_location }
+            end
+          end
+
+          def visit_location(id:, **)
+            result = map_store.visit(id: id)
+            Legion::Logging.debug "[cognitive_map] visit id=#{id} found=#{result[:found]}"
+            result.merge(success: result[:found])
+          end
+
+          def find_path(from:, to:, **)
+            result = map_store.shortest_path(from: from, to: to)
+            Legion::Logging.debug "[cognitive_map] find_path from=#{from} to=#{to} found=#{result[:found]}"
+            result.merge(success: result[:found])
+          end
+
+          def explore_neighborhood(id:, max_distance: 3.0, **)
+            reachable = map_store.reachable_from(id: id, max_distance: max_distance)
+            Legion::Logging.debug "[cognitive_map] explore id=#{id} max_distance=#{max_distance} found=#{reachable.size}"
+            { success: true, id: id, reachable: reachable, count: reachable.size }
+          end
+
+          def map_clusters(**)
+            components = map_store.clusters
+            Legion::Logging.debug "[cognitive_map] clusters count=#{components.size}"
+            { success: true, clusters: components, count: components.size }
+          end
+
+          def familiar_locations(limit: 10, **)
+            locations = map_store.most_familiar(n: limit)
+            Legion::Logging.debug "[cognitive_map] familiar_locations count=#{locations.size}"
+            { success: true, locations: locations, count: locations.size }
+          end
+
+          def switch_context(context_id:, **)
+            result = map_store.context_switch(context_id: context_id)
+            Legion::Logging.info "[cognitive_map] context_switch context_id=#{context_id} switched=#{result[:switched]}"
+            result.merge(success: result[:switched])
+          end
+
+          def update_cognitive_map(**)
+            result = map_store.decay_all
+            Legion::Logging.debug "[cognitive_map] decay_cycle decayed=#{result[:decayed]} pruned=#{result[:pruned]}"
+            { success: true, decayed: result[:decayed], pruned: result[:pruned] }
+          end
+
+          def cognitive_map_stats(**)
+            stats = map_store.to_h
+            Legion::Logging.debug "[cognitive_map] stats context=#{stats[:context]} locations=#{stats[:location_count]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def map_store
+            @map_store ||= Helpers::CognitiveMapStore.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_map.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_map/version'
+require 'legion/extensions/cognitive_map/helpers/constants'
+require 'legion/extensions/cognitive_map/helpers/location'
+require 'legion/extensions/cognitive_map/helpers/graph_traversal'
+require 'legion/extensions/cognitive_map/helpers/cognitive_map_store'
+require 'legion/extensions/cognitive_map/runners/cognitive_map'
+
+module Legion
+  module Extensions
+    module CognitiveMap
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end