lex-agentic-integration 0.1.0

data/lib/legion/extensions/agentic/integration/context/helpers/context_manager.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Context
+          module Helpers
+            class ContextManager
+              include Constants
+
+              attr_reader :frames, :active_stack, :switch_history
+
+              def initialize
+                @frames         = []
+                @active_stack   = []
+                @switch_history = []
+                @last_switch_at = nil
+              end
+
+              def create_frame(name:, domain: :general, cues: [])
+                frame = Frame.new(name: name, domain: domain, cues: cues)
+                @frames << frame
+                trim_frames
+                frame
+              end
+
+              def activate(frame_id)
+                frame = find(frame_id)
+                return nil unless frame
+
+                previous = current_frame
+                cost = 0.0
+
+                if previous && previous.id != frame_id
+                  cost = compute_switch_cost(previous, frame)
+                  previous.deactivate
+                  record_switch(from: previous, to: frame, cost: cost)
+                end
+
+                @active_stack.reject! { |f| f.id == frame_id }
+                @active_stack.push(frame)
+                @active_stack.shift while @active_stack.size > MAX_FRAME_STACK
+                frame.activate
+                { frame: frame, switch_cost: cost }
+              end
+
+              def current_frame
+                @active_stack.last
+              end
+
+              def detect_context(input_cues)
+                scored = @frames.map { |f| [f, f.match_score(input_cues)] }
+                scored.select! { |_, score| score >= RELEVANCE_THRESHOLD }
+                scored.sort_by! { |_, score| -score }
+                scored.map { |f, score| { frame: f, relevance: score } }
+              end
+
+              def auto_switch(input_cues)
+                candidates = detect_context(input_cues)
+                return nil if candidates.empty?
+
+                best = candidates.first
+                current = current_frame
+
+                return nil if current && current.id == best[:frame].id
+
+                activate(best[:frame].id)
+              end
+
+              def find(frame_id)
+                @frames.find { |f| f.id == frame_id }
+              end
+
+              def find_by_name(name)
+                @frames.select { |f| f.name == name }
+              end
+
+              def in_domain(domain)
+                @frames.select { |f| f.domain == domain }
+              end
+
+              def decay_all
+                @frames.each(&:decay)
+                @frames.reject!(&:stale?)
+                @active_stack.reject!(&:stale?)
+              end
+
+              def remove(frame_id)
+                @frames.reject! { |f| f.id == frame_id }
+                @active_stack.reject! { |f| f.id == frame_id }
+              end
+
+              def switch_cost_average
+                return 0.0 if @switch_history.empty?
+
+                @switch_history.sum { |s| s[:cost] }.to_f / @switch_history.size
+              end
+
+              def to_h
+                {
+                  frame_count:     @frames.size,
+                  active_frame:    current_frame&.name,
+                  stack_depth:     @active_stack.size,
+                  switch_count:    @switch_history.size,
+                  avg_switch_cost: switch_cost_average.round(4),
+                  by_domain:       @frames.group_by(&:domain).transform_values(&:size)
+                }
+              end
+
+              private
+
+              def compute_switch_cost(from_frame, to_frame)
+                base = SWITCH_COST
+                familiarity_discount = to_frame.familiarity * 0.2
+                domain_bonus = from_frame.domain == to_frame.domain ? 0.02 : 0.0
+                cooldown_penalty = in_cooldown? ? 0.1 : 0.0
+                (base - familiarity_discount - domain_bonus + cooldown_penalty).clamp(0.0, 1.0)
+              end
+
+              def in_cooldown?
+                return false unless @last_switch_at
+
+                (Time.now.utc - @last_switch_at) < SWITCH_COOLDOWN
+              end
+
+              def record_switch(from:, to:, cost:)
+                @last_switch_at = Time.now.utc
+                @switch_history << {
+                  from: from.name,
+                  to:   to.name,
+                  cost: cost,
+                  at:   @last_switch_at
+                }
+                @switch_history.shift while @switch_history.size > MAX_HISTORY
+              end
+
+              def trim_frames
+                return unless @frames.size > MAX_FRAMES
+
+                @frames.sort_by!(&:strength)
+                @frames.shift(@frames.size - MAX_FRAMES)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/context/helpers/frame.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Context
+          module Helpers
+            class Frame
+              include Constants
+
+              attr_reader :id, :name, :domain, :cues, :strength, :familiarity,
+                          :created_at, :last_activated, :activation_count
+
+              def initialize(name:, domain: :general, cues: [])
+                @id               = SecureRandom.uuid
+                @name             = name
+                @domain           = domain
+                @cues             = cues.first(MAX_CUES_PER_FRAME)
+                @strength         = 1.0
+                @familiarity      = DEFAULT_FAMILIARITY
+                @created_at       = Time.now.utc
+                @last_activated   = @created_at
+                @activation_count = 0
+              end
+
+              def activate
+                @last_activated = Time.now.utc
+                @activation_count += 1
+                @strength = [@strength + 0.1, 1.0].min
+                update_familiarity(1.0)
+              end
+
+              def deactivate
+                update_familiarity(0.0)
+              end
+
+              def decay
+                @strength = [(@strength - FRAME_DECAY), 0.0].max
+              end
+
+              def match_score(input_cues)
+                return 0.0 if @cues.empty? || input_cues.empty?
+
+                overlap = (@cues & input_cues).size
+                overlap.to_f / @cues.size
+              end
+
+              def add_cue(cue)
+                return if @cues.include?(cue)
+
+                @cues << cue
+                @cues.shift if @cues.size > MAX_CUES_PER_FRAME
+              end
+
+              def remove_cue(cue)
+                @cues.delete(cue)
+              end
+
+              def label
+                FRAME_LABELS.each do |range, lbl|
+                  return lbl if range.cover?(@strength)
+                end
+                :fading
+              end
+
+              def stale?
+                @strength < FRAME_STRENGTH_FLOOR
+              end
+
+              def to_h
+                {
+                  id:               @id,
+                  name:             @name,
+                  domain:           @domain,
+                  strength:         @strength,
+                  familiarity:      @familiarity,
+                  label:            label,
+                  cues:             @cues.dup,
+                  activation_count: @activation_count,
+                  created_at:       @created_at,
+                  last_activated:   @last_activated
+                }
+              end
+
+              private
+
+              def update_familiarity(signal)
+                @familiarity = ((FAMILIARITY_ALPHA * signal) + ((1.0 - FAMILIARITY_ALPHA) * @familiarity)).clamp(0.0, 1.0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/context/runners/context.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Context
+          module Runners
+            module Context
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_context(name:, domain: :general, cues: [], **)
+                frame = context_manager.create_frame(name: name, domain: domain, cues: cues)
+                Legion::Logging.debug "[context] created frame=#{name} domain=#{domain} cues=#{cues.size}"
+                { success: true, frame: frame.to_h }
+              end
+
+              def activate_context(frame_id:, **)
+                result = context_manager.activate(frame_id)
+                return { success: false, reason: :not_found } unless result
+
+                frame = result[:frame]
+                Legion::Logging.debug "[context] activated frame=#{frame.name} cost=#{result[:switch_cost].round(3)}"
+                { success: true, frame: frame.to_h, switch_cost: result[:switch_cost] }
+              end
+
+              def detect_context(input_cues:, **)
+                matches = context_manager.detect_context(input_cues)
+                Legion::Logging.debug "[context] detect: #{matches.size} candidates for #{input_cues.size} cues"
+                {
+                  success:    true,
+                  candidates: matches.map { |m| { frame: m[:frame].to_h, relevance: m[:relevance] } },
+                  count:      matches.size,
+                  best:       matches.first && { name: matches.first[:frame].name, relevance: matches.first[:relevance] }
+                }
+              end
+
+              def auto_switch(input_cues:, **)
+                result = context_manager.auto_switch(input_cues)
+                return { success: true, switched: false, reason: :no_better_match } unless result
+
+                frame = result[:frame]
+                Legion::Logging.debug "[context] auto-switched to frame=#{frame.name} cost=#{result[:switch_cost].round(3)}"
+                { success: true, switched: true, frame: frame.to_h, switch_cost: result[:switch_cost] }
+              end
+
+              def current_context(**)
+                frame = context_manager.current_frame
+                return { success: true, frame: nil } unless frame
+
+                { success: true, frame: frame.to_h }
+              end
+
+              def update_context(**)
+                context_manager.decay_all
+                Legion::Logging.debug "[context] tick: frames=#{context_manager.frames.size} active=#{context_manager.current_frame&.name}"
+                { success: true, frame_count: context_manager.frames.size, active: context_manager.current_frame&.name }
+              end
+
+              def add_cue(frame_id:, cue:, **)
+                frame = context_manager.find(frame_id)
+                return { success: false, reason: :not_found } unless frame
+
+                frame.add_cue(cue)
+                { success: true, frame: frame.to_h }
+              end
+
+              def frames_in_domain(domain:, **)
+                frames = context_manager.in_domain(domain)
+                { success: true, frames: frames.map(&:to_h), count: frames.size }
+              end
+
+              def remove_context(frame_id:, **)
+                context_manager.remove(frame_id)
+                { success: true }
+              end
+
+              def context_stats(**)
+                { success: true, stats: context_manager.to_h }
+              end
+
+              private
+
+              def context_manager
+                @context_manager ||= Helpers::ContextManager.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/integration/context/version'
+require 'legion/extensions/agentic/integration/context/helpers/constants'
+require 'legion/extensions/agentic/integration/context/helpers/frame'
+require 'legion/extensions/agentic/integration/context/helpers/context_manager'
+require 'legion/extensions/agentic/integration/context/runners/context'
+require 'legion/extensions/agentic/integration/context/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module Context
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module DistributedCognition
+          class Client
+            include Runners::DistributedCognition
+
+            def initialize(engine: nil)
+              @engine = engine || Helpers::DistributionEngine.new
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module DistributedCognition
+          module Helpers
+            module Constants
+              MAX_PARTICIPANTS = 100
+              MAX_ARTIFACTS = 200
+              MAX_CONTRIBUTIONS = 1000
+              MAX_HISTORY = 300
+
+              DEFAULT_RELIABILITY = 0.5
+              RELIABILITY_FLOOR = 0.0
+              RELIABILITY_CEILING = 1.0
+
+              REINFORCEMENT_RATE = 0.1
+              PENALTY_RATE = 0.15
+              DECAY_RATE = 0.02
+              STALE_THRESHOLD = 120
+
+              PARTICIPANT_TYPES = %i[agent artifact environment].freeze
+
+              CONTRIBUTION_TYPES = %i[
+                computation storage retrieval transformation communication
+              ].freeze
+
+              RELIABILITY_LABELS = {
+                (0.8..)     => :highly_reliable,
+                (0.6...0.8) => :reliable,
+                (0.4...0.6) => :moderate,
+                (0.2...0.4) => :unreliable,
+                (..0.2)     => :failing
+              }.freeze
+
+              DISTRIBUTION_LABELS = {
+                (0.8..)     => :fully_distributed,
+                (0.6...0.8) => :well_distributed,
+                (0.4...0.6) => :partially_distributed,
+                (0.2...0.4) => :concentrated,
+                (..0.2)     => :centralized
+              }.freeze
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/integration/distributed_cognition/helpers/distribution_engine.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Integration
+        module DistributedCognition
+          module Helpers
+            class DistributionEngine
+              include Constants
+
+              attr_reader :history
+
+              def initialize
+                @participants = {}
+                @contributions = []
+                @history = []
+              end
+
+              def register_participant(name:, participant_type:, domain:, capabilities: [])
+                return { success: false, reason: :invalid_participant_type } unless PARTICIPANT_TYPES.include?(participant_type)
+
+                evict_oldest if @participants.size >= MAX_PARTICIPANTS
+
+                participant = Participant.new(
+                  name:             name,
+                  participant_type: participant_type,
+                  domain:           domain,
+                  capabilities:     capabilities
+                )
+                @participants[participant.id] = participant
+                record_history(:registered, participant.id)
+                participant
+              end
+
+              def record_contribution(participant_id:, contribution_type:, success:, context: {})
+                participant = @participants[participant_id]
+                return { success: false, reason: :not_found } unless participant
+
+                return { success: false, reason: :invalid_contribution_type } unless CONTRIBUTION_TYPES.include?(contribution_type)
+
+                participant.contribute!(success: success)
+                store_contribution(participant_id, contribution_type, success, context)
+                record_history(:contributed, participant_id)
+                build_contribution_result(participant, contribution_type)
+              end
+
+              def find_capable(capability:)
+                @participants.values.select { |p| p.capable_of?(capability) }
+                                    .sort_by { |p| -p.reliability }
+              end
+
+              def by_type(participant_type:)
+                @participants.values.select { |p| p.participant_type == participant_type }
+              end
+
+              def by_domain(domain:)
+                @participants.values.select { |p| p.domain == domain }
+              end
+
+              def most_reliable(limit: 5)
+                @participants.values.sort_by { |p| -p.reliability }.first(limit)
+              end
+
+              def distribution_score
+                return 0.0 if @contributions.empty? || @participants.size <= 1
+
+                counts = @contributions.each_with_object(Hash.new(0)) do |contrib, hash|
+                  hash[contrib[:participant_id]] += 1
+                end
+                compute_evenness(counts.values)
+              end
+
+              def distribution_label
+                score = distribution_score
+                DISTRIBUTION_LABELS.find { |range, _| range.cover?(score) }&.last || :unknown
+              end
+
+              def cognitive_load_balance
+                return {} if @participants.empty?
+
+                @participants.transform_values(&:contribution_count)
+              end
+
+              def decay_all
+                @participants.each_value(&:decay!)
+              end
+
+              def prune_failing
+                failing_ids = @participants.select { |_id, p| p.reliability <= 0.05 }.keys
+                failing_ids.each { |id| @participants.delete(id) }
+                failing_ids.size
+              end
+
+              def to_h
+                {
+                  total_participants:  @participants.size,
+                  agent_count:         by_type(participant_type: :agent).size,
+                  artifact_count:      by_type(participant_type: :artifact).size,
+                  environment_count:   by_type(participant_type: :environment).size,
+                  total_contributions: @contributions.size,
+                  distribution_score:  distribution_score,
+                  distribution_label:  distribution_label,
+                  history_count:       @history.size
+                }
+              end
+
+              private
+
+              def store_contribution(participant_id, contribution_type, success, context)
+                entry = {
+                  participant_id:    participant_id,
+                  contribution_type: contribution_type,
+                  success:           success,
+                  context:           context,
+                  at:                Time.now.utc
+                }
+                @contributions << entry
+                @contributions.shift while @contributions.size > MAX_CONTRIBUTIONS
+              end
+
+              def build_contribution_result(participant, contribution_type)
+                {
+                  success:           true,
+                  participant_id:    participant.id,
+                  contribution_type: contribution_type,
+                  reliability:       participant.reliability,
+                  success_rate:      participant.success_rate
+                }
+              end
+
+              def compute_evenness(counts)
+                total = counts.sum.to_f
+                return 0.0 if total.zero?
+
+                proportions = counts.map { |c| c / total }
+                max_entropy = Math.log2(counts.size)
+                return 1.0 if max_entropy.zero?
+
+                entropy = -proportions.sum { |p| p.positive? ? p * Math.log2(p) : 0.0 }
+                (entropy / max_entropy).clamp(0.0, 1.0)
+              end
+
+              def evict_oldest
+                oldest_id = @participants.min_by { |_id, p| p.last_active_at }&.first
+                @participants.delete(oldest_id) if oldest_id
+              end
+
+              def record_history(event, subject_id)
+                @history << { event: event, subject_id: subject_id, at: Time.now.utc }
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end