lex-cognitive-rhythm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b10cd9e09140796135a50743e3221fb1898e54330483eb221a75cecc2ccbb4ba
+  data.tar.gz: 7e80c1170efa27c27c9ad8ef80a90f27799cff2215f10e320c5b966a6df217e6
+SHA512:
+  metadata.gz: 38dd4deb2b004ce766ec60114adb12be669caa24159ccc558a990d318824e737682437d535a7d413d70fc6572de647bdc18ed9a3b212b7caeeeb21c5904f1f30
+  data.tar.gz: e95dbb8690f885fcf0a4bb95d58f1a39abcfcca132c1beaf96e385e7184f5ac56d4a07092d58072eaa0a961486edf939939250ecefc47af57499e9df3424adb1

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveRhythm
+      class Client
+        include Runners::CognitiveRhythm
+
+        def initialize(engine: nil)
+          @engine = engine || Helpers::RhythmEngine.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveRhythm
+      module Helpers
+        module Constants
+          ULTRADIAN_PERIOD  = 5400
+          CIRCADIAN_PERIOD  = 86_400
+          MIN_AMPLITUDE     = 0.0
+          MAX_AMPLITUDE     = 1.0
+          DEFAULT_PHASE_OFFSET = 0.0
+          MAX_RHYTHMS       = 20
+          MAX_HISTORY       = 200
+
+          RHYTHM_TYPES = %i[ultradian circadian custom].freeze
+
+          COGNITIVE_DIMENSIONS = %i[alertness creativity focus analytical social emotional].freeze
+
+          PHASE_LABELS = {
+            (0.0...0.25) => :rising,
+            (0.25...0.5) => :peak,
+            (0.5...0.75) => :falling,
+            (0.75..1.0)  => :trough
+          }.freeze
+
+          AMPLITUDE_LABELS = {
+            (0.8..)     => :high,
+            (0.6...0.8) => :moderate_high,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :moderate_low,
+            (..0.2)     => :low
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_rhythm/helpers/rhythm.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveRhythm
+      module Helpers
+        class Rhythm
+          include Constants
+
+          attr_reader :id, :name, :rhythm_type, :dimension, :period,
+                      :amplitude, :phase_offset, :created_at
+
+          def initialize(id:, name:, rhythm_type:, dimension:, period:,
+                         amplitude: 0.5, phase_offset: 0.0)
+            @id           = id
+            @name         = name
+            @rhythm_type  = rhythm_type
+            @dimension    = dimension
+            @period       = period
+            @amplitude    = amplitude.to_f.clamp(MIN_AMPLITUDE, MAX_AMPLITUDE)
+            @phase_offset = phase_offset.to_f
+            @created_at   = Time.now.utc
+          end
+
+          def value_at(time)
+            elapsed = time.to_f - @created_at.to_f + @phase_offset
+            @amplitude * (0.5 + (0.5 * Math.sin(2 * Math::PI * (elapsed / @period))))
+          end
+
+          def current_value
+            value_at(Time.now.utc)
+          end
+
+          def phase_at(time)
+            elapsed = time.to_f - @created_at.to_f + @phase_offset
+            (elapsed % @period) / @period
+          end
+
+          def current_phase
+            phase_at(Time.now.utc)
+          end
+
+          def phase_label
+            phase = current_phase
+            PHASE_LABELS.each { |range, label| return label if range.cover?(phase) }
+            :trough
+          end
+
+          def amplitude_label
+            AMPLITUDE_LABELS.each { |range, label| return label if range.cover?(@amplitude) }
+            :low
+          end
+
+          def peak?
+            phase_label == :peak
+          end
+
+          def trough?
+            phase_label == :trough
+          end
+
+          def rising?
+            phase_label == :rising
+          end
+
+          def falling?
+            phase_label == :falling
+          end
+
+          def to_h
+            {
+              id:              @id,
+              name:            @name,
+              rhythm_type:     @rhythm_type,
+              dimension:       @dimension,
+              period:          @period,
+              amplitude:       @amplitude,
+              phase_offset:    @phase_offset,
+              current_value:   current_value.round(4),
+              current_phase:   current_phase.round(4),
+              phase_label:     phase_label,
+              amplitude_label: amplitude_label
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_rhythm/helpers/rhythm_engine.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveRhythm
+      module Helpers
+        class RhythmEngine
+          include Constants
+
+          def initialize
+            @rhythms  = {}
+            @counter  = 0
+            @history  = []
+          end
+
+          def add_rhythm(name:, rhythm_type:, dimension:, period: nil, amplitude: 0.5, phase_offset: 0.0)
+            return nil if @rhythms.size >= MAX_RHYTHMS
+
+            resolved_period = resolve_period(rhythm_type, period)
+            return nil if resolved_period.nil?
+
+            @counter += 1
+            id = :"rhythm_#{@counter}"
+            rhythm = Rhythm.new(
+              id:           id,
+              name:         name,
+              rhythm_type:  rhythm_type,
+              dimension:    dimension,
+              period:       resolved_period,
+              amplitude:    amplitude,
+              phase_offset: phase_offset
+            )
+            @rhythms[id] = rhythm
+            rhythm
+          end
+
+          def remove_rhythm(rhythm_id:)
+            removed = @rhythms.delete(rhythm_id)
+            removed ? { success: true, rhythm_id: rhythm_id } : { success: false, reason: :not_found }
+          end
+
+          def dimension_value(dimension:)
+            matching = @rhythms.values.select { |r| r.dimension == dimension }
+            return 0.0 if matching.empty?
+
+            matching.sum(&:current_value) / matching.size
+          end
+
+          def current_state
+            COGNITIVE_DIMENSIONS.to_h do |dim|
+              [dim, dimension_value(dimension: dim).round(4)]
+            end
+          end
+
+          def optimal_for(dimension:)
+            matching = @rhythms.values.select { |r| r.dimension == dimension }
+            return false if matching.empty?
+
+            matching.any?(&:peak?)
+          end
+
+          def best_time_for(dimension:, within: 3600)
+            matching = @rhythms.values.select { |r| r.dimension == dimension }
+            return nil if matching.empty?
+
+            now = Time.now.utc.to_f
+            step = 60
+            steps = within / step
+
+            best_time  = nil
+            best_value = -1.0
+
+            (0..steps).each do |i|
+              t = now + (i * step)
+              value = matching.sum { |r| r.value_at(t) } / matching.size
+              if value > best_value
+                best_value = value
+                best_time  = t
+              end
+            end
+
+            best_time ? Time.at(best_time).utc : nil
+          end
+
+          def synchronize(rhythm_ids:)
+            rhythms = rhythm_ids.map { |id| @rhythms[id] }.compact
+            return { success: false, reason: :not_found } if rhythms.empty?
+
+            reference_phase = rhythms.first.current_phase
+            rhythms.each do |r|
+              current = r.current_phase
+              offset_adjustment = (reference_phase - current) * r.period
+              instance_variable_set_phase_offset(r, r.phase_offset + offset_adjustment)
+            end
+
+            { success: true, synchronized: rhythms.map(&:id) }
+          end
+
+          def cognitive_profile
+            current = current_state
+            current.each_with_object({}) do |(dim, value), hash|
+              phase_label = dominant_phase_label(dim)
+              amplitude_label = dominant_amplitude_label(dim)
+              hash[dim] = {
+                value:           value,
+                phase_label:     phase_label,
+                amplitude_label: amplitude_label,
+                optimal:         optimal_for(dimension: dim)
+              }
+            end
+          end
+
+          def peak_dimensions
+            COGNITIVE_DIMENSIONS.select { |dim| optimal_for(dimension: dim) }
+          end
+
+          def trough_dimensions
+            COGNITIVE_DIMENSIONS.select do |dim|
+              matching = @rhythms.values.select { |r| r.dimension == dim }
+              matching.any?(&:trough?)
+            end
+          end
+
+          def to_h
+            {
+              rhythm_count:  @rhythms.size,
+              rhythms:       @rhythms.values.map(&:to_h),
+              current_state: current_state
+            }
+          end
+
+          private
+
+          def resolve_period(rhythm_type, period)
+            case rhythm_type
+            when :ultradian then ULTRADIAN_PERIOD
+            when :circadian  then CIRCADIAN_PERIOD
+            when :custom     then period
+            end
+          end
+
+          def dominant_phase_label(dimension)
+            matching = @rhythms.values.select { |r| r.dimension == dimension }
+            return :none if matching.empty?
+
+            matching.max_by(&:current_value)&.phase_label || :none
+          end
+
+          def dominant_amplitude_label(dimension)
+            matching = @rhythms.values.select { |r| r.dimension == dimension }
+            return :none if matching.empty?
+
+            matching.max_by(&:amplitude)&.amplitude_label || :none
+          end
+
+          def instance_variable_set_phase_offset(rhythm, new_offset)
+            rhythm.instance_variable_set(:@phase_offset, new_offset.to_f)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveRhythm
+      module Runners
+        module CognitiveRhythm
+          include Helpers::Constants
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def add_cognitive_rhythm(name:, rhythm_type:, dimension:, period: nil,
+                                   amplitude: 0.5, phase_offset: 0.0, **)
+            rhythm = engine.add_rhythm(
+              name:         name,
+              rhythm_type:  rhythm_type,
+              dimension:    dimension,
+              period:       period,
+              amplitude:    amplitude,
+              phase_offset: phase_offset
+            )
+            return { success: false, reason: :limit_reached_or_invalid } unless rhythm
+
+            { success: true, rhythm_id: rhythm.id, name: rhythm.name, dimension: rhythm.dimension }
+          end
+
+          def remove_cognitive_rhythm(rhythm_id:, **)
+            result = engine.remove_rhythm(rhythm_id: rhythm_id)
+            result[:success] ? result : { success: false, reason: result[:reason] }
+          end
+
+          def current_rhythm_state(**)
+            { success: true, state: engine.current_state }
+          end
+
+          def dimension_rhythm_value(dimension:, **)
+            value = engine.dimension_value(dimension: dimension)
+            { success: true, dimension: dimension, value: value.round(4) }
+          end
+
+          def optimal_for_task(dimension:, **)
+            { success: true, dimension: dimension, optimal: engine.optimal_for(dimension: dimension) }
+          end
+
+          def best_time_for_task(dimension:, within: 3600, **)
+            time = engine.best_time_for(dimension: dimension, within: within)
+            return { success: false, reason: :no_rhythms_for_dimension } unless time
+
+            { success: true, dimension: dimension, best_time: time.iso8601, within_seconds: within }
+          end
+
+          def cognitive_rhythm_profile(**)
+            { success: true, profile: engine.cognitive_profile }
+          end
+
+          def peak_cognitive_dimensions(**)
+            dims = engine.peak_dimensions
+            { success: true, dimensions: dims, count: dims.size }
+          end
+
+          def trough_cognitive_dimensions(**)
+            dims = engine.trough_dimensions
+            { success: true, dimensions: dims, count: dims.size }
+          end
+
+          def cognitive_rhythm_stats(**)
+            { success: true }.merge(engine.to_h)
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::RhythmEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-rhythm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: legion-gaia
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ultradian and circadian cognitive rhythm engine for LegionIO — models
+  attention peaks, energy troughs, and creative windows
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/cognitive_rhythm/client.rb
+- lib/legion/extensions/cognitive_rhythm/helpers/constants.rb
+- lib/legion/extensions/cognitive_rhythm/helpers/rhythm.rb
+- lib/legion/extensions/cognitive_rhythm/helpers/rhythm_engine.rb
+- lib/legion/extensions/cognitive_rhythm/runners/cognitive_rhythm.rb
+- lib/legion/extensions/cognitive_rhythm/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-rhythm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-rhythm
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-rhythm
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-rhythm/blob/master/README.md
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-rhythm/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-rhythm/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cognitive rhythm modelling for LegionIO
+test_files: []