lex-agentic-integration 0.1.0

data/lib/legion/extensions/agentic/integration/labyrinth/helpers/labyrinth.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Labyrinth
+          module Helpers
+            class Labyrinth
+              attr_reader :labyrinth_id, :name, :domain, :nodes, :breadcrumbs, :current_node_id
+              attr_accessor :solved
+
+              def initialize(labyrinth_id:, name:, domain: nil)
+                @labyrinth_id   = labyrinth_id
+                @name           = name
+                @domain         = domain
+                @nodes          = {}
+                @breadcrumbs    = []
+                @current_node_id = nil
+                @solved          = false
+              end
+
+              def add_node(node)
+                raise ArgumentError, "nodes must be a #{Node}" unless node.is_a?(Node)
+                raise ArgumentError, "max nodes (#{Constants::MAX_NODES}) reached" if @nodes.size >= Constants::MAX_NODES
+
+                @nodes[node.node_id] = node
+                @current_node_id ||= node.node_id if node.node_type == :entrance
+                node
+              end
+
+              def move_to!(node_id)
+                node = @nodes.fetch(node_id) { raise ArgumentError, "node #{node_id.inspect} not found in labyrinth" }
+
+                current = current_node
+                unless current.nil? || current.connections.include?(node_id)
+                  raise ArgumentError, "cannot move to #{node_id.inspect}: not connected from current node #{@current_node_id.inspect}"
+                end
+
+                drop_breadcrumb
+                node.visited = true
+                @current_node_id = node_id
+                @solved = true if node.node_type == :exit
+                node
+              end
+
+              def backtrack!
+                return nil if @breadcrumbs.empty?
+
+                target_id = @breadcrumbs.pop
+                @current_node_id = target_id
+                current_node
+              end
+
+              def drop_breadcrumb
+                return unless @current_node_id
+
+                current = @nodes[@current_node_id]
+                current.visited = true if current
+                @breadcrumbs << @current_node_id if @breadcrumbs.last != @current_node_id
+              end
+
+              def follow_thread
+                return nil if current_node.nil?
+
+                unvisited = current_node.connections.find do |conn_id|
+                  node = @nodes[conn_id]
+                  node && !node.visited
+                end
+
+                return nil unless unvisited
+
+                move_to!(unvisited)
+              end
+
+              def solved?
+                @solved
+              end
+
+              def lost?
+                return false if @current_node_id.nil?
+                return false if solved?
+
+                current = current_node
+                return true if current.nil?
+
+                unvisited_exits = current.connections.any? do |conn_id|
+                  node = @nodes[conn_id]
+                  node && !node.visited
+                end
+
+                !unvisited_exits && !current.dead_end? && @breadcrumbs.empty?
+              end
+
+              def path_length
+                @breadcrumbs.size
+              end
+
+              def current_node
+                @nodes[@current_node_id]
+              end
+
+              def complexity
+                return 0.0 if @nodes.empty?
+
+                dead_end_count  = @nodes.values.count(&:dead_end?)
+                junction_count  = @nodes.values.count(&:junction?)
+                minotaur_count  = @nodes.values.count { |n| n.node_type == :minotaur_lair }
+
+                raw = ((dead_end_count * 0.3) + (junction_count * 0.2) + (minotaur_count * 0.5)) / @nodes.size.to_f
+                raw.clamp(0.0, 1.0).round(10)
+              end
+
+              def complexity_label
+                score = complexity
+                Constants::COMPLEXITY_LABELS.find { |range, _| range.cover?(score) }&.last || :labyrinthine
+              end
+
+              def to_h
+                {
+                  labyrinth_id:     @labyrinth_id,
+                  name:             @name,
+                  domain:           @domain,
+                  node_count:       @nodes.size,
+                  current_node_id:  @current_node_id,
+                  path_length:      path_length,
+                  solved:           @solved,
+                  complexity:       complexity,
+                  complexity_label: complexity_label
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/labyrinth/helpers/labyrinth_engine.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Labyrinth
+          module Helpers
+            class LabyrinthEngine
+              attr_reader :labyrinths
+
+              def initialize
+                @labyrinths = {}
+              end
+
+              def create_labyrinth(name:, domain: nil, labyrinth_id: nil)
+                raise ArgumentError, "max labyrinths (#{Constants::MAX_LABYRINTHS}) reached" if @labyrinths.size >= Constants::MAX_LABYRINTHS
+
+                id = labyrinth_id || SecureRandom.uuid
+                labyrinth = Labyrinth.new(labyrinth_id: id, name: name, domain: domain)
+                @labyrinths[id] = labyrinth
+                Legion::Logging.debug "[cognitive_labyrinth] created labyrinth id=#{id[0..7]} name=#{name}"
+                labyrinth
+              end
+
+              def add_node_to(labyrinth_id:, node_type:, content: nil, danger_level: nil, node_id: nil)
+                labyrinth = fetch_labyrinth!(labyrinth_id)
+                id        = node_id || SecureRandom.uuid
+                level     = (danger_level || default_danger_for(node_type)).clamp(0.0, 1.0)
+
+                node = Node.new(node_id: id, node_type: node_type, content: content, danger_level: level)
+                labyrinth.add_node(node)
+                Legion::Logging.debug "[cognitive_labyrinth] added node #{id[0..7]} type=#{node_type} to labyrinth #{labyrinth_id[0..7]}"
+                node
+              end
+
+              def connect_nodes(labyrinth_id:, from_id:, to_id:, bidirectional: true)
+                labyrinth  = fetch_labyrinth!(labyrinth_id)
+                from_node  = fetch_node!(labyrinth, from_id)
+                to_node    = fetch_node!(labyrinth, to_id)
+
+                from_node.connect!(to_id)
+                to_node.connect!(from_id) if bidirectional
+                { connected: true, from: from_id, to: to_id, bidirectional: bidirectional }
+              end
+
+              def move(labyrinth_id:, node_id:, **)
+                labyrinth = fetch_labyrinth!(labyrinth_id)
+                node      = labyrinth.move_to!(node_id)
+
+                minotaur_result = check_minotaur(labyrinth_id: labyrinth_id)
+                Legion::Logging.debug "[cognitive_labyrinth] moved to #{node_id[0..7]} type=#{node.node_type}"
+
+                {
+                  success:      true,
+                  node_id:      node.node_id,
+                  node_type:    node.node_type,
+                  content:      node.content,
+                  danger_level: node.danger_level,
+                  solved:       labyrinth.solved?,
+                  minotaur:     minotaur_result,
+                  path_length:  labyrinth.path_length
+                }
+              end
+
+              def backtrack(labyrinth_id:, **)
+                labyrinth = fetch_labyrinth!(labyrinth_id)
+                node      = labyrinth.backtrack!
+
+                if node
+                  Legion::Logging.debug "[cognitive_labyrinth] backtracked to #{node.node_id[0..7]}"
+                  { success: true, node_id: node.node_id, node_type: node.node_type, path_length: labyrinth.path_length }
+                else
+                  Legion::Logging.debug '[cognitive_labyrinth] backtrack failed: no breadcrumbs'
+                  { success: false, reason: :no_breadcrumbs }
+                end
+              end
+
+              def follow_thread(labyrinth_id:, **)
+                labyrinth = fetch_labyrinth!(labyrinth_id)
+                node      = labyrinth.follow_thread
+
+                if node
+                  minotaur_result = check_minotaur(labyrinth_id: labyrinth_id)
+                  Legion::Logging.debug "[cognitive_labyrinth] thread followed to #{node.node_id[0..7]}"
+                  {
+                    success:      true,
+                    node_id:      node.node_id,
+                    node_type:    node.node_type,
+                    content:      node.content,
+                    danger_level: node.danger_level,
+                    solved:       labyrinth.solved?,
+                    minotaur:     minotaur_result
+                  }
+                else
+                  Legion::Logging.debug '[cognitive_labyrinth] thread exhausted: no unvisited nodes from current'
+                  { success: false, reason: :thread_exhausted }
+                end
+              end
+
+              def check_minotaur(labyrinth_id:, **)
+                labyrinth = fetch_labyrinth!(labyrinth_id)
+                node      = labyrinth.current_node
+                return { encountered: false } unless node
+
+                if node.node_type == :minotaur_lair
+                  Legion::Logging.debug "[cognitive_labyrinth] MINOTAUR ENCOUNTERED at #{node.node_id[0..7]}"
+                  {
+                    encountered:   true,
+                    node_id:       node.node_id,
+                    danger_level:  node.danger_level,
+                    danger_label:  danger_label_for(node.danger_level),
+                    misconception: node.content
+                  }
+                elsif node.dangerous?
+                  {
+                    encountered:  false,
+                    warning:      true,
+                    danger_level: node.danger_level,
+                    danger_label: danger_label_for(node.danger_level)
+                  }
+                else
+                  { encountered: false }
+                end
+              end
+
+              def labyrinth_report(labyrinth_id:, **)
+                labyrinth = fetch_labyrinth!(labyrinth_id)
+                nodes_by_type = labyrinth.nodes.values.group_by(&:node_type).transform_values(&:count)
+
+                labyrinth.to_h.merge(
+                  nodes_by_type:    nodes_by_type,
+                  visited_count:    labyrinth.nodes.values.count(&:visited),
+                  breadcrumb_trail: labyrinth.breadcrumbs.dup,
+                  lost:             labyrinth.lost?
+                )
+              end
+
+              def list_labyrinths(**)
+                @labyrinths.values.map(&:to_h)
+              end
+
+              def delete_labyrinth(labyrinth_id:, **)
+                raise ArgumentError, "labyrinth #{labyrinth_id.inspect} not found" unless @labyrinths.key?(labyrinth_id)
+
+                @labyrinths.delete(labyrinth_id)
+                { deleted: true, labyrinth_id: labyrinth_id }
+              end
+
+              private
+
+              def fetch_labyrinth!(labyrinth_id)
+                @labyrinths.fetch(labyrinth_id) do
+                  raise ArgumentError, "labyrinth #{labyrinth_id.inspect} not found"
+                end
+              end
+
+              def fetch_node!(labyrinth, node_id)
+                labyrinth.nodes.fetch(node_id) do
+                  raise ArgumentError, "node #{node_id.inspect} not found in labyrinth #{labyrinth.labyrinth_id.inspect}"
+                end
+              end
+
+              def default_danger_for(node_type)
+                node_type == :minotaur_lair ? Constants::MINOTAUR_DANGER_LEVEL : Constants::DEFAULT_DANGER_LEVEL
+              end
+
+              def danger_label_for(level)
+                Constants::DANGER_LABELS.find { |range, _| range.cover?(level) }&.last || :lethal
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/labyrinth/helpers/node.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Labyrinth
+          module Helpers
+            class Node
+              attr_reader   :node_id, :node_type, :content, :connections, :danger_level
+              attr_accessor :visited
+
+              def initialize(node_id:, node_type:, content: nil, danger_level: Constants::DEFAULT_DANGER_LEVEL)
+                unless Constants::NODE_TYPES.include?(node_type)
+                  raise ArgumentError, "unknown node_type: #{node_type.inspect}; must be one of #{Constants::NODE_TYPES.inspect}"
+                end
+
+                @node_id      = node_id
+                @node_type    = node_type
+                @content      = content
+                @connections  = []
+                @visited      = false
+                @danger_level = danger_level.clamp(0.0, 1.0)
+              end
+
+              def connect!(other_id)
+                @connections << other_id unless @connections.include?(other_id)
+                self
+              end
+
+              def disconnect!(other_id)
+                @connections.delete(other_id)
+                self
+              end
+
+              def dead_end?
+                @node_type == :dead_end || (@connections.empty? && @node_type != :entrance && @node_type != :exit)
+              end
+
+              def junction?
+                @node_type == :junction || @connections.size >= 3
+              end
+
+              def dangerous?
+                @node_type == :minotaur_lair || @danger_level >= 0.5
+              end
+
+              def to_h
+                {
+                  node_id:      @node_id,
+                  node_type:    @node_type,
+                  content:      @content,
+                  connections:  @connections.dup,
+                  visited:      @visited,
+                  danger_level: @danger_level
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/labyrinth/runners/cognitive_labyrinth.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Labyrinth
+          module Runners
+            module CognitiveLabyrinth
+              extend self
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_labyrinth(name:, domain: nil, labyrinth_id: nil, engine: nil, **)
+                raise ArgumentError, 'name is required' if name.nil? || name.to_s.strip.empty?
+
+                result = resolve_engine(engine).create_labyrinth(name: name, domain: domain, labyrinth_id: labyrinth_id)
+                Legion::Logging.debug "[cognitive_labyrinth] runner: created labyrinth #{result.labyrinth_id[0..7]}"
+                { success: true, labyrinth_id: result.labyrinth_id, name: result.name, domain: result.domain }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] create_labyrinth error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def add_node(labyrinth_id:, node_type:, content: nil, danger_level: nil, node_id: nil, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+                raise ArgumentError, 'node_type is required' if node_type.nil?
+
+                node = resolve_engine(engine).add_node_to(
+                  labyrinth_id: labyrinth_id, node_type: node_type,
+                  content: content, danger_level: danger_level, node_id: node_id
+                )
+                { success: true, node_id: node.node_id, node_type: node.node_type }
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] add_node error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def connect_nodes(labyrinth_id:, from_id:, to_id:, bidirectional: true, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+                resolve_engine(engine).connect_nodes(
+                  labyrinth_id: labyrinth_id, from_id: from_id, to_id: to_id, bidirectional: bidirectional
+                )
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] connect_nodes error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def move(labyrinth_id:, node_id:, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+                raise ArgumentError, 'node_id is required' if node_id.nil?
+
+                resolve_engine(engine).move(labyrinth_id: labyrinth_id, node_id: node_id)
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] move error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def backtrack(labyrinth_id:, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+                resolve_engine(engine).backtrack(labyrinth_id: labyrinth_id)
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] backtrack error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def follow_thread(labyrinth_id:, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+                resolve_engine(engine).follow_thread(labyrinth_id: labyrinth_id)
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] follow_thread error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def check_minotaur(labyrinth_id:, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+                resolve_engine(engine).check_minotaur(labyrinth_id: labyrinth_id)
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] check_minotaur error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def labyrinth_report(labyrinth_id:, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+                result = resolve_engine(engine).labyrinth_report(labyrinth_id: labyrinth_id)
+                { success: true }.merge(result)
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] labyrinth_report error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              def list_labyrinths(engine: nil, **)
+                result = resolve_engine(engine).list_labyrinths
+                { success: true, labyrinths: result, count: result.size }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def delete_labyrinth(labyrinth_id:, engine: nil, **)
+                raise ArgumentError, 'labyrinth_id is required' if labyrinth_id.nil?
+
+                resolve_engine(engine).delete_labyrinth(labyrinth_id: labyrinth_id)
+              rescue ArgumentError => e
+                Legion::Logging.debug "[cognitive_labyrinth] delete_labyrinth error: #{e.message}"
+                { success: false, error: e.message }
+              end
+
+              private
+
+              def labyrinth_engine
+                @labyrinth_engine ||= Helpers::LabyrinthEngine.new
+              end
+
+              def resolve_engine(engine)
+                engine || labyrinth_engine
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'labyrinth/version'
+require_relative 'labyrinth/helpers/constants'
+require_relative 'labyrinth/helpers/node'
+require_relative 'labyrinth/helpers/labyrinth'
+require_relative 'labyrinth/helpers/labyrinth_engine'
+require_relative 'labyrinth/runners/cognitive_labyrinth'
+require_relative 'labyrinth/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Labyrinth
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Map
+          module Actor
+            class Decay < Legion::Extensions::Actors::Every
+              def runner_class
+                Legion::Extensions::Agentic::Integration::Map::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
+  end
+end

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

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