lex-agentic-integration 0.1.0

data/lib/legion/extensions/agentic/integration/map/helpers/cognitive_map_store.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+          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(limit: 10)
+                locations.values.sort_by { |l| -l.familiarity }.first(limit).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
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+          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
+  end
+end

data/lib/legion/extensions/agentic/integration/map/helpers/graph_traversal.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+          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, node, dist, prev, queue)
+                loc = locations[node]
+                return unless loc
+
+                loc.neighbors.each do |v, weight|
+                  alt = dist[node] + weight
+                  next unless alt < dist[v]
+
+                  dist[v] = alt
+                  prev[v] = node
+                  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
+  end
+end

data/lib/legion/extensions/agentic/integration/map/helpers/location.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+          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
+  end
+end

data/lib/legion/extensions/agentic/integration/map/runners/cognitive_map.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+          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(limit: 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
+  end
+end

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

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

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/integration/map/version'
+require 'legion/extensions/agentic/integration/map/helpers/constants'
+require 'legion/extensions/agentic/integration/map/helpers/location'
+require 'legion/extensions/agentic/integration/map/helpers/graph_traversal'
+require 'legion/extensions/agentic/integration/map/helpers/cognitive_map_store'
+require 'legion/extensions/agentic/integration/map/runners/cognitive_map'
+require 'legion/extensions/agentic/integration/map/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Mosaic
+          class Client
+            include Runners::CognitiveMosaic
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Mosaic
+          module Helpers
+            module Constants
+              # Tessera material types
+              MATERIAL_TYPES = %i[
+                glass stone ceramic metal wood
+                shell bone crystal clay enamel
+              ].freeze
+
+              # Mosaic pattern categories
+              PATTERN_CATEGORIES = %i[
+                geometric organic abstract narrative
+                symbolic decorative functional
+              ].freeze
+
+              MAX_TESSERAE = 500
+              MAX_MOSAICS  = 50
+              GROUT_DECAY  = 0.01
+              MIN_GROUT    = 0.05
+
+              # Completeness labels
+              COMPLETENESS_LABELS = [
+                [(0.9..),      :masterwork],
+                [(0.7...0.9),  :substantial],
+                [(0.5...0.7),  :emerging],
+                [(0.3...0.5),  :fragmentary],
+                [(..0.3),      :nascent]
+              ].freeze
+
+              # Coherence labels
+              COHERENCE_LABELS = [
+                [(0.8..),      :harmonious],
+                [(0.6...0.8),  :coherent],
+                [(0.4...0.6),  :developing],
+                [(0.2...0.4),  :disjointed],
+                [(..0.2),      :chaotic]
+              ].freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end