lex-cognitive-tide 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 97eb0a7dffaaf474e5b7cd62f7b8bcf50f4a720074bd9b98e1477d6a1337d261
+  data.tar.gz: 98016f8241ef14e555df861dff8d2bedc9dfa51df4321b6aa57a679ec072ae22
+SHA512:
+  metadata.gz: bd43de2527c14052222500d002861c2b666708ae7ca7b97551f3e3b279bccf21580d15e4a323b6e71512d5d2434d841f7c4176c280b2c8fdba05fdcf4148b5a9
+  data.tar.gz: 425160a6fb2ad24418ce89d8ed908c4ae28344fa1f433bc99d280c4907fd74e1585e6ac8ef0d3e42dc791a34f7e213e0f8b0e1cef2667c1de77d8c7cb151bc9b

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Esity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# lex-cognitive-tide
+
+Circadian-like cognitive rhythm engine for LegionIO. Models cognition as tidal forces: multiple oscillators create composite tide levels, tidal pools accumulate ideas during low tide, and high tide marks peak cognitive performance.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'lex-cognitive-tide'
+```
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveTide::Client.new
+
+# Add oscillators
+client.add_oscillator(oscillator_type: :primary, period: 86_400, amplitude: 1.0, phase_offset: 0.0)
+client.add_oscillator(oscillator_type: :secondary, period: 43_200, amplitude: 0.5, phase_offset: 1.5)
+
+# Check current tide
+status = client.tide_status
+# => { level: 0.72, phase: :high_tide, label: "peak", oscillator_count: 2, pool_count: 0 }
+
+# Deposit an idea during low tide
+client.deposit_idea(domain: 'architecture', idea: 'refactor the auth layer', tide_threshold: 0.5)
+
+# Harvest ideas when tide rises
+client.harvest(min_depth: 0.1)
+```
+
+## Actors
+
+| Actor | Interval | What It Does |
+|-------|----------|--------------|
+| `TideCycle` | Every 60s | Advances oscillators via `tick!` and evaporates all tidal pools at `POOL_EVAPORATION_RATE` |
+
+## License
+
+MIT

data/lex-cognitive-tide.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_tide/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-tide'
+  spec.version       = Legion::Extensions::CognitiveTide::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX CognitiveTide'
+  spec.description   = 'Circadian-like cognitive rhythm engine for brain-modeled agentic AI — ' \
+                       'tidal oscillators, composite tide levels, and tidal pool idea accumulation'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-tide'
+  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-tide'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-tide'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-tide'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-tide/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-tide.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/cognitive_tide/actors/tide_cycle.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      module Actor
+        class TideCycle < Legion::Extensions::Actors::Every
+          def runner_class
+            Legion::Extensions::CognitiveTide::Runners::CognitiveTide
+          end
+
+          def runner_function
+            'tide_maintenance'
+          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

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_tide/helpers/constants'
+require 'legion/extensions/cognitive_tide/helpers/oscillator'
+require 'legion/extensions/cognitive_tide/helpers/tidal_pool'
+require 'legion/extensions/cognitive_tide/helpers/tide_engine'
+require 'legion/extensions/cognitive_tide/runners/cognitive_tide'
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      class Client
+        include Runners::CognitiveTide
+
+        def initialize(**)
+          @tide_engine = Helpers::TideEngine.new
+        end
+
+        private
+
+        attr_reader :tide_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      module Helpers
+        module Constants
+          TIDE_PHASES = %i[rising high_tide falling low_tide].freeze
+          OSCILLATOR_TYPES = %i[primary secondary lunar].freeze
+
+          MAX_POOLS = 50
+          POOL_EVAPORATION_RATE = 0.01
+
+          # Range-based tide label lookup — ranges are ordered from highest to lowest
+          TIDE_LABELS = [
+            { range: (0.85..1.0),   label: 'peak' },
+            { range: (0.65..0.85),  label: 'high' },
+            { range: (0.45..0.65),  label: 'moderate' },
+            { range: (0.25..0.45),  label: 'low' },
+            { range: (0.0..0.25),   label: 'ebb' }
+          ].freeze
+
+          # Spring tide threshold: two oscillators are considered in phase when their values
+          # differ by less than this proportion of their combined amplitude
+          SPRING_TIDE_PHASE_TOLERANCE = 0.15
+
+          # Minimum tide level above which harvest is permitted
+          HARVEST_RISING_THRESHOLD = 0.3
+
+          # Forecast resolution: seconds between each forecast sample
+          FORECAST_RESOLUTION = 300
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_tide/helpers/oscillator.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      module Helpers
+        class Oscillator
+          attr_reader :oscillator_type, :period, :amplitude, :phase_offset, :id
+
+          def initialize(oscillator_type:, period:, amplitude: 1.0, phase_offset: 0.0)
+            unless Constants::OSCILLATOR_TYPES.include?(oscillator_type)
+              raise ArgumentError, "unknown oscillator_type: #{oscillator_type.inspect}; " \
+                                   "must be one of #{Constants::OSCILLATOR_TYPES.inspect}"
+            end
+
+            raise ArgumentError, 'period must be positive' unless period.positive?
+
+            @id = SecureRandom.uuid
+            @oscillator_type = oscillator_type
+            @period         = period.to_f
+            @amplitude      = amplitude.clamp(0.0, 1.0)
+            @phase_offset   = phase_offset.to_f
+            @last_ticked_at = nil
+          end
+
+          # Advance the oscillator by computing its current sinusoidal value
+          def tick!
+            @last_ticked_at = Time.now.utc
+            current_value
+          end
+
+          # Sinusoidal value at a given time, normalized to [0, 1]
+          def value_at(time)
+            t = time.to_f
+            radians = ((2.0 * Math::PI * t) / @period) + @phase_offset
+            # sin ranges [-1, 1] — shift to [0, 1]
+            ((Math.sin(radians) + 1.0) / 2.0 * @amplitude).round(10)
+          end
+
+          # Current value based on Time.now
+          def current_value
+            value_at(Time.now.utc)
+          end
+
+          # Two oscillators are in phase when their normalized values are within tolerance
+          def in_phase_with?(other)
+            combined_amplitude = [@amplitude, other.amplitude].sum
+            return false if combined_amplitude.zero?
+
+            tolerance = Constants::SPRING_TIDE_PHASE_TOLERANCE * combined_amplitude
+            (current_value - other.current_value).abs <= tolerance
+          end
+
+          def to_h
+            {
+              id:              @id,
+              oscillator_type: @oscillator_type,
+              period:          @period,
+              amplitude:       @amplitude,
+              phase_offset:    @phase_offset,
+              current_value:   current_value,
+              last_ticked_at:  @last_ticked_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_tide/helpers/tidal_pool.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      module Helpers
+        class TidalPool
+          attr_reader :id, :domain, :capacity, :evaporation_count
+
+          def initialize(domain:, capacity: 20)
+            raise ArgumentError, 'capacity must be positive' unless capacity.positive?
+
+            @id               = SecureRandom.uuid
+            @domain           = domain.to_s
+            @capacity         = capacity
+            @items            = []
+            @evaporation_count = 0
+            @created_at = Time.now.utc
+          end
+
+          # Deposit an idea item into the pool; silently drops if full
+          def deposit(item)
+            return false if full?
+
+            @items << { content: item, deposited_at: Time.now.utc, id: SecureRandom.uuid }
+            true
+          end
+
+          # Harvest all items from the pool, clearing it; returns the harvested items
+          def harvest!
+            harvested = @items.dup
+            @items.clear
+            harvested
+          end
+
+          # Apply evaporation: remove a proportion of items (oldest first)
+          def evaporate!(rate = Constants::POOL_EVAPORATION_RATE)
+            clamped_rate = rate.clamp(0.0, 1.0)
+            count_to_remove = (@items.size * clamped_rate).ceil
+            removed = @items.shift(count_to_remove)
+            @evaporation_count += removed.size
+            removed.size
+          end
+
+          def empty?
+            @items.empty?
+          end
+
+          def full?
+            @items.size >= @capacity
+          end
+
+          # Depth as a fraction of capacity: item_count / capacity
+          def depth
+            return 0.0 if @capacity.zero?
+
+            (@items.size.to_f / @capacity).round(10)
+          end
+
+          def items
+            @items.dup
+          end
+
+          def size
+            @items.size
+          end
+
+          def to_h
+            {
+              id:                @id,
+              domain:            @domain,
+              capacity:          @capacity,
+              size:              @items.size,
+              depth:             depth,
+              evaporation_count: @evaporation_count,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_tide/helpers/tide_engine.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      module Helpers
+        class TideEngine
+          attr_reader :oscillators, :pools
+
+          def initialize
+            @oscillators = []
+            @pools       = []
+          end
+
+          # Add an oscillator; returns the new Oscillator instance
+          def add_oscillator(oscillator_type:, period:, amplitude: 1.0, phase_offset: 0.0)
+            osc = Oscillator.new(
+              oscillator_type: oscillator_type,
+              period:          period,
+              amplitude:       amplitude,
+              phase_offset:    phase_offset
+            )
+            @oscillators << osc
+            osc
+          end
+
+          # Composite tide level: clamped sum of all oscillator current values, normalized to [0, 1]
+          def composite_tide_level
+            return 0.0 if @oscillators.empty?
+
+            raw = @oscillators.sum(&:current_value)
+            max = @oscillators.sum(&:amplitude)
+            return 0.0 if max.zero?
+
+            (raw / max).clamp(0.0, 1.0).round(10)
+          end
+
+          # Determine phase based on comparison of current and recent tide level
+          def current_phase
+            level = composite_tide_level
+            previous = previous_level
+
+            if level >= 0.65
+              :high_tide
+            elsif level <= 0.35
+              :low_tide
+            elsif level > previous
+              :rising
+            else
+              :falling
+            end
+          end
+
+          # Create a new tidal pool for a domain; respects MAX_POOLS limit
+          def create_pool(domain:, capacity: 20)
+            return nil if @pools.size >= Constants::MAX_POOLS
+
+            existing = find_pool(domain)
+            return existing if existing
+
+            pool = TidalPool.new(domain: domain, capacity: capacity)
+            @pools << pool
+            pool
+          end
+
+          # Deposit an item into a domain pool (creates the pool if needed)
+          def deposit_to_pool(domain:, item:, capacity: 20)
+            pool = find_pool(domain) || create_pool(domain: domain, capacity: capacity)
+            return false unless pool
+
+            pool.deposit(item)
+          end
+
+          # Harvest pools only when tide is rising; returns hash of domain => items
+          def harvest_pools(min_depth: 0.0)
+            return {} unless rising?
+
+            result = {}
+            @pools.each do |pool|
+              next if pool.depth < min_depth
+              next if pool.empty?
+
+              result[pool.domain] = pool.harvest!
+            end
+            result
+          end
+
+          # Apply evaporation to all pools
+          def evaporate_all!(rate = Constants::POOL_EVAPORATION_RATE)
+            @pools.sum { |pool| pool.evaporate!(rate) }
+          end
+
+          # Forecast tide level at regular intervals over a duration (seconds)
+          def tide_forecast(duration)
+            return [] if @oscillators.empty?
+
+            steps = (duration.to_f / Constants::FORECAST_RESOLUTION).ceil
+            now   = Time.now.utc
+
+            (0...steps).map do |step|
+              t     = now + (step * Constants::FORECAST_RESOLUTION)
+              level = forecast_level_at(t)
+              { time: t, level: level, label: tide_label(level) }
+            end
+          end
+
+          def high_tide?
+            composite_tide_level >= 0.65
+          end
+
+          def low_tide?
+            composite_tide_level <= 0.35
+          end
+
+          def rising?
+            current_phase == :rising
+          end
+
+          def tide_report
+            level = composite_tide_level
+            {
+              level:            level,
+              phase:            current_phase,
+              label:            tide_label(level),
+              oscillator_count: @oscillators.size,
+              pool_count:       @pools.size,
+              high_tide:        high_tide?,
+              low_tide:         low_tide?,
+              pools:            @pools.map(&:to_h),
+              oscillators:      @oscillators.map(&:to_h)
+            }
+          end
+
+          private
+
+          def find_pool(domain)
+            @pools.find { |p| p.domain == domain.to_s }
+          end
+
+          def previous_level
+            return 0.0 if @oscillators.empty?
+
+            t   = Time.now.utc - Constants::FORECAST_RESOLUTION
+            raw = @oscillators.sum { |osc| osc.value_at(t) }
+            max = @oscillators.sum(&:amplitude)
+            return 0.0 if max.zero?
+
+            (raw / max).clamp(0.0, 1.0)
+          end
+
+          def forecast_level_at(time)
+            raw = @oscillators.sum { |osc| osc.value_at(time) }
+            max = @oscillators.sum(&:amplitude)
+            return 0.0 if max.zero?
+
+            (raw / max).clamp(0.0, 1.0).round(10)
+          end
+
+          def tide_label(level)
+            entry = Constants::TIDE_LABELS.find { |tl| tl[:range].cover?(level) }
+            entry ? entry[:label] : 'ebb'
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      module Runners
+        module CognitiveTide
+          extend self
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def add_oscillator(oscillator_type: :primary, period: 86_400, amplitude: 1.0,
+                             phase_offset: 0.0, engine: nil, **)
+            eng = engine || tide_engine
+            osc = eng.add_oscillator(
+              oscillator_type: oscillator_type.to_sym,
+              period:          period,
+              amplitude:       amplitude,
+              phase_offset:    phase_offset
+            )
+            Legion::Logging.debug "[cognitive_tide] oscillator added: type=#{oscillator_type} " \
+                                  "period=#{period} amplitude=#{amplitude}"
+            { success: true, oscillator: osc.to_h }
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_tide] add_oscillator failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def check_tide(engine: nil, **)
+            eng   = engine || tide_engine
+            level = eng.composite_tide_level
+            phase = eng.current_phase
+            label = Helpers::Constants::TIDE_LABELS.find { |tl| tl[:range].cover?(level) }&.fetch(:label, 'ebb')
+            Legion::Logging.debug "[cognitive_tide] check_tide: level=#{level.round(3)} phase=#{phase} label=#{label}"
+            {
+              success: true,
+              level:   level,
+              phase:   phase,
+              label:   label
+            }
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_tide] check_tide failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def deposit_idea(domain:, idea:, capacity: 20, tide_threshold: nil, engine: nil, **)
+            eng = engine || tide_engine
+
+            if tide_threshold
+              level = eng.composite_tide_level
+              if level > tide_threshold
+                Legion::Logging.debug "[cognitive_tide] deposit_idea skipped: tide=#{level.round(3)} above threshold=#{tide_threshold}"
+                return { success: false, reason: :tide_too_high, level: level }
+              end
+            end
+
+            deposited = eng.deposit_to_pool(domain: domain, item: idea, capacity: capacity)
+            Legion::Logging.debug "[cognitive_tide] deposit_idea: domain=#{domain} deposited=#{deposited}"
+            { success: deposited, domain: domain }
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_tide] deposit_idea failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def harvest(min_depth: 0.0, engine: nil, **)
+            eng    = engine || tide_engine
+            result = eng.harvest_pools(min_depth: min_depth.to_f)
+            total  = result.values.sum(&:size)
+            Legion::Logging.debug "[cognitive_tide] harvest: domains=#{result.keys.size} total_items=#{total}"
+            { success: true, harvested: result, total_items: total }
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_tide] harvest failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def tide_forecast(duration: 86_400, engine: nil, **)
+            eng      = engine || tide_engine
+            forecast = eng.tide_forecast(duration)
+            Legion::Logging.debug "[cognitive_tide] tide_forecast: duration=#{duration} steps=#{forecast.size}"
+            { success: true, forecast: forecast, duration: duration }
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_tide] tide_forecast failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def tide_status(engine: nil, **)
+            eng    = engine || tide_engine
+            report = eng.tide_report
+            Legion::Logging.debug "[cognitive_tide] tide_status: level=#{report[:level].round(3)} " \
+                                  "phase=#{report[:phase]} pools=#{report[:pool_count]}"
+            report.merge(success: true)
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_tide] tide_status failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def tide_maintenance(engine: nil, **)
+            eng = engine || tide_engine
+            eng.evaporate_all!
+            eng.oscillators.each(&:tick!)
+            pools_maintained = eng.pools.size
+            phase            = eng.current_phase
+            level            = eng.composite_tide_level
+            Legion::Logging.debug "[tide] maintenance: pools=#{pools_maintained} phase=#{phase} level=#{level}"
+            { pools_maintained: pools_maintained, current_phase: phase, tide_level: level }
+          end
+
+          private
+
+          def tide_engine
+            @tide_engine ||= Helpers::TideEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_tide.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'cognitive_tide/version'
+require_relative 'cognitive_tide/helpers/constants'
+require_relative 'cognitive_tide/helpers/oscillator'
+require_relative 'cognitive_tide/helpers/tidal_pool'
+require_relative 'cognitive_tide/helpers/tide_engine'
+require_relative 'cognitive_tide/runners/cognitive_tide'
+
+module Legion
+  module Extensions
+    module CognitiveTide
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end