lex-agentic-inference 0.1.0

data/lib/legion/extensions/agentic/inference/momentum/helpers/momentum_engine.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Momentum
+          module Helpers
+            class MomentumEngine
+              include Constants
+
+              attr_reader :history
+
+              def initialize
+                @ideas   = {}
+                @history = []
+              end
+
+              def create_idea(content:, idea_type:, domain:, mass: DEFAULT_MASS)
+                evict_oldest if @ideas.size >= MAX_IDEAS
+
+                idea = Idea.new(content: content, idea_type: idea_type, domain: domain, mass: mass)
+                @ideas[idea.id] = idea
+                record_history(:created, idea.id)
+                idea
+              end
+
+              def reinforce_idea(idea_id:)
+                idea = @ideas[idea_id]
+                return { success: false, reason: :not_found } unless idea
+
+                idea.reinforce!
+                record_history(:reinforced, idea_id)
+                { success: true, momentum: idea.momentum, mass: idea.mass, velocity: idea.velocity }
+              end
+
+              def challenge_idea(idea_id:)
+                idea = @ideas[idea_id]
+                return { success: false, reason: :not_found } unless idea
+
+                idea.challenge!
+                record_history(:challenged, idea_id)
+                { success: true, momentum: idea.momentum, mass: idea.mass, velocity: idea.velocity }
+              end
+
+              def apply_force(idea_id:, force:)
+                idea = @ideas[idea_id]
+                return { success: false, reason: :not_found } unless idea
+
+                idea.apply_force(force: force)
+                record_history(:force_applied, idea_id)
+                { success: true, momentum: idea.momentum, velocity: idea.velocity }
+              end
+
+              def surging_ideas
+                @ideas.values.select(&:surging?)
+              end
+
+              def reversing_ideas
+                @ideas.values.select(&:reversing?)
+              end
+
+              def entrenched_ideas
+                @ideas.values.select(&:entrenched?)
+              end
+
+              def ideas_by_type(idea_type:)
+                @ideas.values.select { |idea| idea.idea_type == idea_type }
+              end
+
+              def ideas_by_domain(domain:)
+                @ideas.values.select { |idea| idea.domain == domain }
+              end
+
+              def highest_momentum(limit: 5)
+                @ideas.values.sort_by { |idea| -idea.momentum }.first(limit)
+              end
+
+              def most_entrenched(limit: 5)
+                @ideas.values.sort_by { |idea| -idea.mass }.first(limit)
+              end
+
+              def apply_friction_all
+                @ideas.each_value(&:apply_friction!)
+              end
+
+              def prune_at_rest
+                ids = @ideas.select { |_id, idea| idea.at_rest? && idea.mass <= MASS_FLOOR + 0.01 }.keys
+                ids.each { |idea_id| @ideas.delete(idea_id) }
+                ids.size
+              end
+
+              def to_h
+                {
+                  total_ideas:      @ideas.size,
+                  surging_count:    surging_ideas.size,
+                  reversing_count:  reversing_ideas.size,
+                  entrenched_count: entrenched_ideas.size,
+                  avg_momentum:     avg_momentum,
+                  history_count:    @history.size
+                }
+              end
+
+              private
+
+              def avg_momentum
+                return 0.0 if @ideas.empty?
+
+                @ideas.values.sum(&:momentum) / @ideas.size
+              end
+
+              def evict_oldest
+                oldest_id = @ideas.min_by { |_id, idea| idea.last_updated_at }&.first
+                @ideas.delete(oldest_id) if oldest_id
+              end
+
+              def record_history(event, idea_id)
+                @history << { event: event, idea_id: idea_id, at: Time.now.utc }
+                @history.shift while @history.size > MAX_HISTORY
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/momentum/runners/cognitive_momentum.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Momentum
+          module Runners
+            module CognitiveMomentum
+              include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                          Legion::Extensions::Helpers.const_defined?(:Lex)
+
+              def create_cognitive_idea(content:, idea_type:, domain:, mass: nil, **)
+                idea = engine.create_idea(
+                  content:   content,
+                  idea_type: idea_type.to_sym,
+                  domain:    domain.to_sym,
+                  mass:      mass || Helpers::Constants::DEFAULT_MASS
+                )
+                Legion::Logging.debug "[cognitive_momentum] create id=#{idea.id[0..7]} " \
+                                      "type=#{idea_type} domain=#{domain}"
+                { success: true, idea: idea.to_h }
+              end
+
+              def reinforce_cognitive_idea(idea_id:, **)
+                result = engine.reinforce_idea(idea_id: idea_id)
+                Legion::Logging.debug "[cognitive_momentum] reinforce id=#{idea_id[0..7]} " \
+                                      "momentum=#{result[:momentum]&.round(3)}"
+                result
+              end
+
+              def challenge_cognitive_idea(idea_id:, **)
+                result = engine.challenge_idea(idea_id: idea_id)
+                Legion::Logging.debug "[cognitive_momentum] challenge id=#{idea_id[0..7]} " \
+                                      "momentum=#{result[:momentum]&.round(3)}"
+                result
+              end
+
+              def apply_cognitive_force(idea_id:, force:, **)
+                result = engine.apply_force(idea_id: idea_id, force: force)
+                Legion::Logging.debug "[cognitive_momentum] force id=#{idea_id[0..7]} " \
+                                      "f=#{force} momentum=#{result[:momentum]&.round(3)}"
+                result
+              end
+
+              def surging_ideas_report(**)
+                ideas = engine.surging_ideas
+                Legion::Logging.debug "[cognitive_momentum] surging count=#{ideas.size}"
+                { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+              end
+
+              def reversing_ideas_report(**)
+                ideas = engine.reversing_ideas
+                Legion::Logging.debug "[cognitive_momentum] reversing count=#{ideas.size}"
+                { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+              end
+
+              def entrenched_ideas_report(**)
+                ideas = engine.entrenched_ideas
+                Legion::Logging.debug "[cognitive_momentum] entrenched count=#{ideas.size}"
+                { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+              end
+
+              def highest_momentum_ideas(limit: 5, **)
+                ideas = engine.highest_momentum(limit: limit)
+                Legion::Logging.debug "[cognitive_momentum] highest_momentum count=#{ideas.size}"
+                { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+              end
+
+              def ideas_by_domain(domain:, **)
+                ideas = engine.ideas_by_domain(domain: domain.to_sym)
+                Legion::Logging.debug '[cognitive_momentum] by_domain ' \
+                                      "domain=#{domain} count=#{ideas.size}"
+                { success: true, ideas: ideas.map(&:to_h), count: ideas.size }
+              end
+
+              def update_cognitive_momentum(**)
+                engine.apply_friction_all
+                pruned = engine.prune_at_rest
+                Legion::Logging.debug "[cognitive_momentum] friction+prune pruned=#{pruned}"
+                { success: true, pruned: pruned }
+              end
+
+              def cognitive_momentum_stats(**)
+                stats = engine.to_h
+                Legion::Logging.debug "[cognitive_momentum] stats total=#{stats[:total_ideas]}"
+                { success: true }.merge(stats)
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::MomentumEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/momentum/version.rb

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

data/lib/legion/extensions/agentic/inference/momentum.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'momentum/version'
+require_relative 'momentum/helpers/constants'
+require_relative 'momentum/helpers/idea'
+require_relative 'momentum/helpers/momentum_engine'
+require_relative 'momentum/runners/cognitive_momentum'
+require_relative 'momentum/helpers/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module Momentum
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/perceptual_inference/client.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/inference/perceptual_inference/helpers/constants'
+require 'legion/extensions/agentic/inference/perceptual_inference/helpers/perceptual_hypothesis'
+require 'legion/extensions/agentic/inference/perceptual_inference/helpers/perceptual_field'
+require 'legion/extensions/agentic/inference/perceptual_inference/runners/perceptual_inference'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module PerceptualInference
+          class Client
+            include Runners::PerceptualInference
+
+            def initialize(field: nil, **)
+              @field = field || Helpers::PerceptualField.new
+            end
+
+            private
+
+            attr_reader :field
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/perceptual_inference/helpers/constants.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module PerceptualInference
+          module Helpers
+            MAX_HYPOTHESES       = 30
+            MAX_EVIDENCE         = 100
+            MAX_HISTORY          = 200
+            DEFAULT_PRIOR        = 0.5
+            PRIOR_FLOOR          = 0.01
+            PRIOR_CEILING        = 0.99
+            SELECTION_THRESHOLD  = 0.6
+            RIVALRY_MARGIN       = 0.1
+            EVIDENCE_STRENGTH_FLOOR = 0.05
+            ADAPTATION_RATE      = 0.1
+            DECAY_RATE           = 0.01
+            MODALITIES           = %i[visual auditory somatosensory olfactory gustatory proprioceptive vestibular].freeze
+            HYPOTHESIS_STATES    = %i[active selected suppressed decayed].freeze
+            PERCEPT_LABELS       = {
+              (0.8..)     => :vivid,
+              (0.6...0.8) => :clear,
+              (0.4...0.6) => :ambiguous,
+              (0.2...0.4) => :faint,
+              (..0.2)     => :subliminal
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/perceptual_inference/helpers/perceptual_field.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module PerceptualInference
+          module Helpers
+            class PerceptualField
+              attr_reader :hypotheses, :evidence_log
+
+              def initialize
+                @hypotheses = {}
+                @evidence_log = []
+              end
+
+              def register_hypothesis(content:, modality:, domain: :general, prior: DEFAULT_PRIOR)
+                validate_modality!(modality)
+                prune_modality(modality) if hypotheses_for(modality).size >= MAX_HYPOTHESES
+
+                hypothesis = PerceptualHypothesis.new(
+                  content:  content,
+                  modality: modality,
+                  domain:   domain,
+                  prior:    prior
+                )
+                @hypotheses[hypothesis.id] = hypothesis
+                hypothesis
+              end
+
+              def present_evidence(modality:, content:, strength: 0.5)
+                validate_modality!(modality)
+                strength = [strength.to_f, EVIDENCE_STRENGTH_FLOOR].max
+                record_evidence(modality, content, strength)
+
+                active_hypotheses_for(modality).each do |h|
+                  h.likelihood = compute_likelihood(h, content, strength)
+                  h.compute_posterior(evidence_weight: strength)
+                end
+
+                hypotheses_for(modality).size
+              end
+
+              def select_percept(modality:)
+                validate_modality!(modality)
+                candidates = active_hypotheses_for(modality)
+                return nil if candidates.empty?
+
+                winner = candidates.max_by(&:posterior)
+                return nil if winner.posterior < SELECTION_THRESHOLD
+
+                candidates.each { |h| h.id == winner.id ? h.select! : h.suppress! }
+                winner
+              end
+
+              def rivalry?(modality:)
+                validate_modality!(modality)
+                candidates = active_hypotheses_for(modality)
+                return false if candidates.size < 2
+
+                top_two = candidates.max_by(2, &:posterior)
+                top_two.first.rival_with?(top_two.last)
+              end
+
+              def current_percept(modality:)
+                validate_modality!(modality)
+                @hypotheses.values.find { |h| h.modality == modality && h.state == :selected }
+              end
+
+              def hypotheses_for(modality)
+                @hypotheses.values.select { |h| h.modality == modality }
+              end
+
+              def suppress_hypothesis(hypothesis_id:)
+                h = @hypotheses[hypothesis_id]
+                return false unless h
+
+                h.suppress!
+                true
+              end
+
+              def adapt_priors(modality:, correct_hypothesis_id:)
+                validate_modality!(modality)
+                hypotheses_for(modality).each do |h|
+                  outcome = h.id == correct_hypothesis_id ? :correct : :incorrect
+                  h.adapt_prior(outcome: outcome)
+                end
+              end
+
+              def ambiguity_level
+                rival_count = MODALITIES.count { |m| rivalry?(modality: m) && hypotheses_for(m).any? }
+                total_active = MODALITIES.count { |m| hypotheses_for(m).any? }
+                return 0.0 if total_active.zero?
+
+                rival_count.to_f / total_active
+              end
+
+              def decay_all
+                @hypotheses.each_value(&:decay)
+                @hypotheses.reject! { |_, h| h.state == :decayed }
+              end
+
+              def to_h
+                by_modality = MODALITIES.each_with_object({}) do |m, acc|
+                  hs = hypotheses_for(m)
+                  next if hs.empty?
+
+                  acc[m] = {
+                    count:   hs.size,
+                    rivalry: rivalry?(modality: m),
+                    percept: current_percept(modality: m)&.to_h
+                  }
+                end
+
+                {
+                  hypotheses_total: @hypotheses.size,
+                  ambiguity_level:  ambiguity_level.round(4),
+                  by_modality:      by_modality
+                }
+              end
+
+              private
+
+              def active_hypotheses_for(modality)
+                @hypotheses.values.select { |h| h.modality == modality && %i[active selected].include?(h.state) }
+              end
+
+              def compute_likelihood(hypothesis, evidence_content, strength)
+                base = hypothesis.content.to_s.downcase.include?(evidence_content.to_s.downcase) ? 0.8 : 0.3
+                [(base * strength) + (hypothesis.likelihood * (1.0 - strength)), 1.0].min
+              end
+
+              def record_evidence(modality, content, strength)
+                entry = { modality: modality, content: content, strength: strength, at: Time.now.utc }
+                @evidence_log << entry
+                @evidence_log.shift while @evidence_log.size > MAX_EVIDENCE
+              end
+
+              def prune_modality(modality)
+                candidates = hypotheses_for(modality).select { |h| %i[suppressed decayed].include?(h.state) }
+                candidates = hypotheses_for(modality).min_by(5, &:posterior) if candidates.empty?
+                candidates.each { |h| @hypotheses.delete(h.id) }
+              end
+
+              def validate_modality!(modality)
+                raise ArgumentError, "Unknown modality: #{modality}" unless MODALITIES.include?(modality)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/inference/perceptual_inference/helpers/perceptual_hypothesis.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Inference
+        module PerceptualInference
+          module Helpers
+            class PerceptualHypothesis
+              attr_reader   :id, :content, :modality, :domain, :state, :created_at
+              attr_accessor :prior, :likelihood, :posterior
+
+              def initialize(content:, modality:, domain: :general, prior: DEFAULT_PRIOR)
+                @id         = SecureRandom.uuid
+                @content    = content
+                @modality   = modality
+                @domain     = domain
+                @prior      = clamp_prior(prior.to_f)
+                @likelihood = 0.5
+                @posterior  = @prior
+                @state      = :active
+                @created_at = Time.now.utc
+              end
+
+              def compute_posterior(evidence_weight:)
+                weight   = [evidence_weight.to_f, EVIDENCE_STRENGTH_FLOOR].max
+                raw      = @prior * ((@likelihood * weight) + ((1.0 - weight) * @prior))
+                @posterior = clamp_unit(raw)
+              end
+
+              def select!
+                @state = :selected
+              end
+
+              def suppress!
+                @state = :suppressed
+              end
+
+              def selected?
+                @state == :selected
+              end
+
+              def rival_with?(other)
+                return false unless other.is_a?(PerceptualHypothesis)
+
+                (posterior - other.posterior).abs <= RIVALRY_MARGIN
+              end
+
+              def adapt_prior(outcome:)
+                delta    = outcome == :correct ? ADAPTATION_RATE : -ADAPTATION_RATE
+                @prior   = clamp_prior(@prior + delta)
+              end
+
+              def decay
+                if @state == :suppressed
+                  @prior = clamp_prior(@prior - (DECAY_RATE * 5))
+                  @state = :decayed if @prior <= PRIOR_FLOOR + 0.001
+                else
+                  @prior = clamp_prior(@prior + ((DEFAULT_PRIOR - @prior) * DECAY_RATE))
+                end
+              end
+
+              def percept_label
+                PERCEPT_LABELS.each { |range, label| return label if range.cover?(@posterior) }
+                :subliminal
+              end
+
+              def to_h
+                {
+                  id:         @id,
+                  content:    @content,
+                  modality:   @modality,
+                  domain:     @domain,
+                  prior:      @prior.round(4),
+                  likelihood: @likelihood.round(4),
+                  posterior:  @posterior.round(4),
+                  state:      @state,
+                  label:      percept_label,
+                  created_at: @created_at
+                }
+              end
+
+              private
+
+              def clamp_prior(value)
+                value.clamp(PRIOR_FLOOR, PRIOR_CEILING)
+              end
+
+              def clamp_unit(value)
+                value.clamp(0.0, 1.0)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end