lex-cognitive-synthesis 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 794a2635b1df3494d23c85016118e87cabd698c1f11da3c360a2985d398af0e2
+  data.tar.gz: b61b06852ae00e857131c9413bb347ff146d28809ebac36f9c1e62ebfae1a214
+SHA512:
+  metadata.gz: ef493128ca5d01bb34dff75ec3a4f71991deae44d3f2bcf6fef7846902e57d54f038cf24c1f0e7c3defcce7d31e6f89cff302a97849ff47d5b0c8bf207ef179a
+  data.tar.gz: e369eca98a77a7d8be01ad95c2eb60c33a0cd603d30514e7bc7013e8d8da6575c9458466ba645c7db59830a81648976598972c0d2ed128ce320a363f5ea69958

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-synthesis.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_synthesis/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-synthesis'
+  spec.version       = Legion::Extensions::CognitiveSynthesis::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Synthesis'
+  spec.description   = 'Cognitive binding engine — combines disparate cognitive streams ' \
+                       '(emotional, perceptual, memorial, predictive) into unified coherent ' \
+                       'representations for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-synthesis'
+  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-synthesis'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-synthesis'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-synthesis'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-synthesis/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-synthesis.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_synthesis/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_synthesis/helpers/constants'
+require 'legion/extensions/cognitive_synthesis/helpers/synthesis_stream'
+require 'legion/extensions/cognitive_synthesis/helpers/synthesis'
+require 'legion/extensions/cognitive_synthesis/helpers/synthesis_engine'
+require 'legion/extensions/cognitive_synthesis/runners/cognitive_synthesis'
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      class Client
+        include Runners::CognitiveSynthesis
+
+        def initialize(engine: nil, **)
+          @synthesis_engine = engine || Helpers::SynthesisEngine.new
+        end
+
+        private
+
+        attr_reader :synthesis_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      module Helpers
+        module Constants
+          MAX_STREAMS             = 50
+          MAX_SYNTHESES           = 200
+          DEFAULT_WEIGHT          = 0.5
+          COHERENCE_THRESHOLD     = 0.6
+          NOVELTY_THRESHOLD       = 0.7
+          FRESHNESS_DECAY         = 0.02
+          MIN_STREAMS_FOR_SYNTHESIS = 2
+
+          STREAM_TYPES = %i[emotional perceptual memorial predictive reasoning social identity motor].freeze
+
+          COHERENCE_LABELS = {
+            (0.8..)     => :unified,
+            (0.6...0.8) => :coherent,
+            (0.4...0.6) => :fragmented,
+            (0.2...0.4) => :dissonant,
+            (..0.2)     => :chaotic
+          }.freeze
+
+          CONFIDENCE_LABELS = {
+            (0.8..)     => :certain,
+            (0.6...0.8) => :confident,
+            (0.4...0.6) => :uncertain,
+            (0.2...0.4) => :doubtful,
+            (..0.2)     => :guessing
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_synthesis/helpers/synthesis.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      module Helpers
+        class Synthesis
+          include Constants
+
+          attr_reader :id, :streams, :coherence, :novelty, :confidence, :content, :created_at
+
+          def initialize(streams:, coherence:, novelty:, confidence:, content:)
+            @id         = SecureRandom.uuid
+            @streams    = streams
+            @coherence  = coherence.clamp(0.0, 1.0)
+            @novelty    = novelty.clamp(0.0, 1.0)
+            @confidence = confidence.clamp(0.0, 1.0)
+            @content    = content
+            @created_at = Time.now.utc
+          end
+
+          def fragmented?
+            @coherence < COHERENCE_THRESHOLD
+          end
+
+          def novel?
+            @novelty > NOVELTY_THRESHOLD
+          end
+
+          def coherence_label
+            COHERENCE_LABELS.find { |range, _| range.cover?(@coherence) }&.last || :chaotic
+          end
+
+          def confidence_label
+            CONFIDENCE_LABELS.find { |range, _| range.cover?(@confidence) }&.last || :guessing
+          end
+
+          def to_h
+            {
+              id:               @id,
+              streams:          @streams,
+              coherence:        @coherence,
+              novelty:          @novelty,
+              confidence:       @confidence,
+              content:          @content,
+              fragmented:       fragmented?,
+              novel:            novel?,
+              coherence_label:  coherence_label,
+              confidence_label: confidence_label,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_synthesis/helpers/synthesis_engine.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      module Helpers
+        class SynthesisEngine
+          include Constants
+
+          attr_reader :streams, :syntheses
+
+          def initialize
+            @streams    = {}
+            @syntheses  = []
+          end
+
+          def add_stream(stream_type:, content:, weight: DEFAULT_WEIGHT, confidence: DEFAULT_WEIGHT, **)
+            return { success: false, error: :invalid_stream_type, valid_types: STREAM_TYPES } unless STREAM_TYPES.include?(stream_type)
+
+            stream = SynthesisStream.new(
+              stream_type: stream_type,
+              content:     content,
+              weight:      weight,
+              confidence:  confidence
+            )
+
+            @streams[stream.id] = stream
+            prune_streams! if @streams.size > MAX_STREAMS
+
+            Legion::Logging.debug "[cognitive_synthesis] stream added id=#{stream.id[0..7]} " \
+                                  "type=#{stream_type} weight=#{weight.round(2)}"
+
+            { success: true, stream_id: stream.id, stream_type: stream_type }
+          end
+
+          def remove_stream(stream_id:, **)
+            removed = @streams.delete(stream_id)
+            if removed
+              Legion::Logging.debug "[cognitive_synthesis] stream removed id=#{stream_id[0..7]}"
+              { success: true, stream_id: stream_id }
+            else
+              { success: false, error: :not_found }
+            end
+          end
+
+          def synthesize!(**)
+            active = @streams.values.reject(&:stale?)
+
+            if active.size < MIN_STREAMS_FOR_SYNTHESIS
+              Legion::Logging.debug "[cognitive_synthesis] synthesize! skipped: only #{active.size} active streams"
+              return { success: false, error: :insufficient_streams, active_count: active.size, required: MIN_STREAMS_FOR_SYNTHESIS }
+            end
+
+            coherence   = compute_coherence(active)
+            novelty     = compute_novelty(active)
+            confidence  = compute_weighted_confidence(active)
+            content     = merge_content(active)
+
+            synthesis = Synthesis.new(
+              streams:    active.map(&:id),
+              coherence:  coherence,
+              novelty:    novelty,
+              confidence: confidence,
+              content:    content
+            )
+
+            @syntheses << synthesis
+            @syntheses.shift while @syntheses.size > MAX_SYNTHESES
+
+            Legion::Logging.info "[cognitive_synthesis] synthesis id=#{synthesis.id[0..7]} " \
+                                 "coherence=#{coherence.round(2)} novelty=#{novelty.round(2)} " \
+                                 "streams=#{active.size} label=#{synthesis.coherence_label}"
+
+            { success: true, synthesis: synthesis.to_h }
+          end
+
+          def decay_all!(**)
+            before = @streams.size
+            @streams.each_value(&:decay_freshness!)
+            @streams.reject! { |_, s| s.stale? }
+            removed = before - @streams.size
+
+            Legion::Logging.debug "[cognitive_synthesis] decay_all! removed=#{removed} remaining=#{@streams.size}"
+            { success: true, streams_removed: removed, streams_remaining: @streams.size }
+          end
+
+          def stream_conflict?(stream_id_a:, stream_id_b:, **)
+            a = @streams[stream_id_a]
+            b = @streams[stream_id_b]
+
+            return { success: false, error: :stream_not_found } unless a && b
+
+            weight_opposition = opposing_weights?(a, b)
+            content_conflict  = conflicting_content?(a, b)
+            conflict          = weight_opposition || content_conflict
+
+            Legion::Logging.debug "[cognitive_synthesis] conflict check #{stream_id_a[0..7]}<>#{stream_id_b[0..7]} " \
+                                  "result=#{conflict}"
+
+            {
+              success:           true,
+              conflict:          conflict,
+              weight_opposition: weight_opposition,
+              content_conflict:  content_conflict
+            }
+          end
+
+          def dominant_stream(**)
+            return { success: false, error: :no_streams } if @streams.empty?
+
+            stream = @streams.values.max_by(&:effective_weight)
+            Legion::Logging.debug "[cognitive_synthesis] dominant stream id=#{stream.id[0..7]} " \
+                                  "effective_weight=#{stream.effective_weight.round(4)}"
+            { success: true, stream: stream.to_h }
+          end
+
+          def synthesis_history(limit: 10, **)
+            recent = @syntheses.last(limit)
+            { success: true, syntheses: recent.map(&:to_h), count: recent.size }
+          end
+
+          def average_coherence(window: 10, **)
+            recent = @syntheses.last(window)
+            return { success: true, average_coherence: 0.0, sample_size: 0 } if recent.empty?
+
+            avg = recent.sum(&:coherence).round(10) / recent.size
+            { success: true, average_coherence: avg.round(10), sample_size: recent.size }
+          end
+
+          def to_h
+            {
+              stream_count:      @streams.size,
+              synthesis_count:   @syntheses.size,
+              active_streams:    @streams.values.reject(&:stale?).size,
+              stale_streams:     @streams.values.count(&:stale?),
+              average_coherence: @syntheses.empty? ? 0.0 : (@syntheses.sum(&:coherence).round(10) / @syntheses.size).round(6)
+            }
+          end
+
+          private
+
+          def prune_streams!
+            overflow = @streams.size - MAX_STREAMS
+            return if overflow <= 0
+
+            ids_to_prune = @streams.min_by(overflow) { |_, s| s.effective_weight }.map(&:first)
+            ids_to_prune.each { |id| @streams.delete(id) }
+          end
+
+          def compute_coherence(active)
+            return 1.0 if active.size == 1
+
+            weights = active.map(&:effective_weight)
+            mean    = weights.sum.round(10) / weights.size
+            variance = weights.sum { |w| ((w - mean)**2).round(10) }.round(10) / weights.size
+            std_dev  = Math.sqrt(variance)
+
+            (1.0 - [std_dev, 1.0].min).round(10)
+          end
+
+          def compute_novelty(active)
+            return 1.0 if @syntheses.empty?
+
+            last_syn = @syntheses.last
+            last_ids = Set.new(last_syn.streams)
+            current_ids = Set.new(active.map(&:id))
+
+            overlap = (last_ids & current_ids).size.to_f
+            union   = (last_ids | current_ids).size.to_f
+
+            return 1.0 if union.zero?
+
+            jaccard_similarity = overlap / union
+            (1.0 - jaccard_similarity).round(10)
+          end
+
+          def compute_weighted_confidence(active)
+            total_weight = active.sum(&:effective_weight).round(10)
+            return 0.0 if total_weight.zero?
+
+            weighted_sum = active.sum { |s| (s.confidence * s.effective_weight).round(10) }.round(10)
+            (weighted_sum / total_weight).round(10)
+          end
+
+          def merge_content(active)
+            dominant = active.max_by(&:effective_weight)
+            {
+              dominant_type:    dominant.stream_type,
+              dominant_weight:  dominant.effective_weight.round(6),
+              stream_types:     active.map(&:stream_type).uniq,
+              stream_count:     active.size,
+              payload_snapshot: dominant.content
+            }
+          end
+
+          def opposing_weights?(str_a, str_b)
+            (str_a.weight - str_b.weight).abs > 0.5
+          end
+
+          def conflicting_content?(str_a, str_b)
+            keys_a = str_a.content.is_a?(Hash) ? str_a.content.keys : []
+            keys_b = str_b.content.is_a?(Hash) ? str_b.content.keys : []
+            (keys_a & keys_b).any? { |k| str_a.content[k] != str_b.content[k] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_synthesis/helpers/synthesis_stream.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      module Helpers
+        class SynthesisStream
+          include Constants
+
+          attr_reader :id, :stream_type, :content, :weight, :confidence, :freshness, :created_at
+
+          def initialize(stream_type:, content:, weight: DEFAULT_WEIGHT, confidence: DEFAULT_WEIGHT)
+            @id          = SecureRandom.uuid
+            @stream_type = stream_type
+            @content     = content
+            @weight      = weight.clamp(0.0, 1.0)
+            @confidence  = confidence.clamp(0.0, 1.0)
+            @freshness   = 1.0
+            @created_at  = Time.now.utc
+          end
+
+          def decay_freshness!
+            @freshness = (@freshness - FRESHNESS_DECAY).clamp(0.0, 1.0)
+          end
+
+          def stale?
+            @freshness < 0.1
+          end
+
+          def effective_weight
+            (@weight * @freshness * @confidence).round(10)
+          end
+
+          def coherence_label
+            COHERENCE_LABELS.find { |range, _| range.cover?(@weight) }&.last || :chaotic
+          end
+
+          def confidence_label
+            CONFIDENCE_LABELS.find { |range, _| range.cover?(@confidence) }&.last || :guessing
+          end
+
+          def to_h
+            {
+              id:               @id,
+              stream_type:      @stream_type,
+              content:          @content,
+              weight:           @weight,
+              confidence:       @confidence,
+              freshness:        @freshness,
+              effective_weight: effective_weight,
+              stale:            stale?,
+              coherence_label:  coherence_label,
+              confidence_label: confidence_label,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      module Runners
+        module CognitiveSynthesis
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_stream(stream_type:, content:, weight: Helpers::Constants::DEFAULT_WEIGHT,
+                         confidence: Helpers::Constants::DEFAULT_WEIGHT, engine: nil, **)
+            target = engine || synthesis_engine
+            result = target.add_stream(stream_type: stream_type, content: content,
+                                       weight: weight, confidence: confidence)
+            Legion::Logging.debug "[cognitive_synthesis] runner add_stream type=#{stream_type}"
+            result
+          end
+
+          def remove_stream(stream_id:, engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug "[cognitive_synthesis] runner remove_stream id=#{stream_id[0..7]}"
+            target.remove_stream(stream_id: stream_id)
+          end
+
+          def synthesize(engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug '[cognitive_synthesis] runner synthesize'
+            target.synthesize!
+          end
+
+          def decay_streams(engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug '[cognitive_synthesis] runner decay_streams'
+            target.decay_all!
+          end
+
+          def check_conflict(stream_id_a:, stream_id_b:, engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug "[cognitive_synthesis] runner check_conflict #{stream_id_a[0..7]}<>#{stream_id_b[0..7]}"
+            target.stream_conflict?(stream_id_a: stream_id_a, stream_id_b: stream_id_b)
+          end
+
+          def dominant_stream(engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug '[cognitive_synthesis] runner dominant_stream'
+            target.dominant_stream
+          end
+
+          def synthesis_history(limit: 10, engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug "[cognitive_synthesis] runner synthesis_history limit=#{limit}"
+            target.synthesis_history(limit: limit)
+          end
+
+          def average_coherence(window: 10, engine: nil, **)
+            target = engine || synthesis_engine
+            Legion::Logging.debug "[cognitive_synthesis] runner average_coherence window=#{window}"
+            target.average_coherence(window: window)
+          end
+
+          def status(engine: nil, **)
+            target = engine || synthesis_engine
+            stats  = target.to_h
+            Legion::Logging.debug "[cognitive_synthesis] runner status streams=#{stats[:stream_count]}"
+            { success: true }.merge(stats)
+          end
+
+          private
+
+          def synthesis_engine
+            @synthesis_engine ||= Helpers::SynthesisEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_synthesis.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_synthesis/version'
+require 'legion/extensions/cognitive_synthesis/helpers/constants'
+require 'legion/extensions/cognitive_synthesis/helpers/synthesis_stream'
+require 'legion/extensions/cognitive_synthesis/helpers/synthesis'
+require 'legion/extensions/cognitive_synthesis/helpers/synthesis_engine'
+require 'legion/extensions/cognitive_synthesis/runners/cognitive_synthesis'
+
+module Legion
+  module Extensions
+    module CognitiveSynthesis
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/cognitive_synthesis/client_spec.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_synthesis/client'
+
+RSpec.describe Legion::Extensions::CognitiveSynthesis::Client do
+  it 'responds to all runner methods' do
+    client = described_class.new
+    %i[add_stream remove_stream synthesize decay_streams check_conflict
+       dominant_stream synthesis_history average_coherence status].each do |method|
+      expect(client).to respond_to(method)
+    end
+  end
+
+  it 'accepts an injected engine' do
+    engine = Legion::Extensions::CognitiveSynthesis::Helpers::SynthesisEngine.new
+    client = described_class.new(engine: engine)
+    client.add_stream(stream_type: :emotional, content: {})
+    expect(engine.streams.size).to eq(1)
+  end
+
+  it 'creates its own engine when none injected' do
+    client = described_class.new
+    result = client.add_stream(stream_type: :emotional, content: {})
+    expect(result[:success]).to be true
+  end
+end

data/spec/legion/extensions/cognitive_synthesis/helpers/constants_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::CognitiveSynthesis::Helpers::Constants do
+  subject(:mod) { described_class }
+
+  describe 'MAX_STREAMS' do
+    it 'is 50' do
+      expect(mod::MAX_STREAMS).to eq(50)
+    end
+  end
+
+  describe 'MAX_SYNTHESES' do
+    it 'is 200' do
+      expect(mod::MAX_SYNTHESES).to eq(200)
+    end
+  end
+
+  describe 'DEFAULT_WEIGHT' do
+    it 'is 0.5' do
+      expect(mod::DEFAULT_WEIGHT).to eq(0.5)
+    end
+  end
+
+  describe 'COHERENCE_THRESHOLD' do
+    it 'is 0.6' do
+      expect(mod::COHERENCE_THRESHOLD).to eq(0.6)
+    end
+  end
+
+  describe 'NOVELTY_THRESHOLD' do
+    it 'is 0.7' do
+      expect(mod::NOVELTY_THRESHOLD).to eq(0.7)
+    end
+  end
+
+  describe 'FRESHNESS_DECAY' do
+    it 'is 0.02' do
+      expect(mod::FRESHNESS_DECAY).to eq(0.02)
+    end
+  end
+
+  describe 'MIN_STREAMS_FOR_SYNTHESIS' do
+    it 'is 2' do
+      expect(mod::MIN_STREAMS_FOR_SYNTHESIS).to eq(2)
+    end
+  end
+
+  describe 'STREAM_TYPES' do
+    it 'includes all expected types' do
+      expect(mod::STREAM_TYPES).to include(:emotional, :perceptual, :memorial, :predictive,
+                                           :reasoning, :social, :identity, :motor)
+    end
+
+    it 'is frozen' do
+      expect(mod::STREAM_TYPES).to be_frozen
+    end
+  end
+
+  describe 'COHERENCE_LABELS' do
+    it 'maps high values to :unified' do
+      label = mod::COHERENCE_LABELS.find { |range, _| range.cover?(0.9) }&.last
+      expect(label).to eq(:unified)
+    end
+
+    it 'maps low values to :chaotic' do
+      label = mod::COHERENCE_LABELS.find { |range, _| range.cover?(0.1) }&.last
+      expect(label).to eq(:chaotic)
+    end
+
+    it 'maps mid values to :coherent' do
+      label = mod::COHERENCE_LABELS.find { |range, _| range.cover?(0.7) }&.last
+      expect(label).to eq(:coherent)
+    end
+  end
+
+  describe 'CONFIDENCE_LABELS' do
+    it 'maps high values to :certain' do
+      label = mod::CONFIDENCE_LABELS.find { |range, _| range.cover?(0.95) }&.last
+      expect(label).to eq(:certain)
+    end
+
+    it 'maps low values to :guessing' do
+      label = mod::CONFIDENCE_LABELS.find { |range, _| range.cover?(0.05) }&.last
+      expect(label).to eq(:guessing)
+    end
+  end
+end