lex-temporal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5f4a4b711b75ed1f26943f373aaebb70ee08274151a67c952a5894ba64cb45d2
+  data.tar.gz: 8b78d44cbde78674c8d7b8149da24ff36bd80b4b587e24d5d238715518586d3b
+SHA512:
+  metadata.gz: 627401699a4d741f3db2e29533cd79eb01eb153fa4f7218b395a6148ebb8134db5fb692c7fb5e8ee2eb5638c5dbd06d1bf50e3adfbc05a719467bf6d5d5d8e70
+  data.tar.gz: ec4a7c83958e5b54da0fb0afc997653ff24e8ac141c90b809885a46d53350c333c40b781e9c0f400274ed99a2170de1aa857d25fe43ac61513261778b49d90d2

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Temporal
+      class Client
+        include Runners::Temporal
+
+        attr_reader :temporal_store
+
+        def initialize(temporal_store: nil, **)
+          @temporal_store = temporal_store || Helpers::TemporalStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Temporal
+      module Helpers
+        module Constants
+          # Time horizons for urgency classification
+          URGENCY_HORIZONS = {
+            immediate:  10,      # seconds
+            short_term: 60,      # 1 minute
+            medium:     300,     # 5 minutes
+            long_term:  3600,    # 1 hour
+            distant:    86_400   # 1 day
+          }.freeze
+
+          # Urgency levels (higher = more urgent)
+          URGENCY_LEVELS = %i[none low moderate high critical].freeze
+
+          # Deadline urgency thresholds (fraction of remaining time)
+          DEADLINE_URGENCY = {
+            critical: 0.1,   # <= 10% time remaining
+            high:     0.25,  # <= 25%
+            moderate: 0.5,   # <= 50%
+            low:      0.75,  # <= 75%
+            none:     1.0    # > 75%
+          }.freeze
+
+          # Temporal pattern types
+          PATTERN_TYPES = %i[periodic bursty circadian random].freeze
+
+          # Minimum occurrences to detect a pattern
+          MIN_PATTERN_OBSERVATIONS = 5
+
+          # Maximum tracked events per domain
+          MAX_EVENTS_PER_DOMAIN = 100
+
+          # Maximum active deadlines
+          MAX_DEADLINES = 50
+
+          # Maximum temporal patterns tracked
+          MAX_PATTERNS = 30
+
+          # How many recent events to keep globally
+          MAX_GLOBAL_EVENTS = 500
+
+          # Coefficient of variation threshold for periodic vs bursty
+          PERIODIC_CV_THRESHOLD = 0.3
+
+          # Burst detection: events within this multiplier of mean interval
+          BURST_MULTIPLIER = 0.25
+
+          # Subjective time dilation factor ranges
+          # When arousal is high, time feels slower (more ticks perceived)
+          # When bored/low arousal, time flies
+          DILATION_RANGE = { min: 0.5, max: 2.0 }.freeze
+
+          # EMA alpha for subjective time tracking
+          SUBJECTIVE_ALPHA = 0.2
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/temporal/helpers/temporal_pattern.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Temporal
+      module Helpers
+        class TemporalPattern
+          attr_reader :domain, :event, :pattern_type, :mean_interval,
+                      :observation_count, :last_predicted, :accuracy_count, :total_predictions
+
+          def initialize(domain:, event:)
+            @domain = domain
+            @event = event
+            @intervals = []
+            @pattern_type = :random
+            @mean_interval = nil
+            @observation_count = 0
+            @last_predicted = nil
+            @accuracy_count = 0
+            @total_predictions = 0
+          end
+
+          def add_observation(timestamps)
+            return if timestamps.size < 2
+
+            @intervals = compute_intervals(timestamps)
+            @observation_count = timestamps.size
+            @mean_interval = @intervals.sum / @intervals.size.to_f
+            @pattern_type = classify_pattern
+          end
+
+          def predict_next(from: Time.now.utc)
+            return nil unless @mean_interval && @observation_count >= Constants::MIN_PATTERN_OBSERVATIONS
+
+            predicted = from + @mean_interval
+            @last_predicted = predicted
+            @total_predictions += 1
+            { predicted_at: predicted, confidence: prediction_confidence, pattern: @pattern_type }
+          end
+
+          def record_actual(actual_time)
+            return unless @last_predicted
+
+            error = (actual_time - @last_predicted).abs
+            tolerance = (@mean_interval || 60) * 0.3
+            @accuracy_count += 1 if error <= tolerance
+          end
+
+          def prediction_accuracy
+            return 0.0 if @total_predictions.zero?
+
+            @accuracy_count.to_f / @total_predictions
+          end
+
+          def periodic?
+            @pattern_type == :periodic
+          end
+
+          def bursty?
+            @pattern_type == :bursty
+          end
+
+          def to_h
+            {
+              domain:            @domain,
+              event:             @event,
+              pattern_type:      @pattern_type,
+              mean_interval:     @mean_interval,
+              observation_count: @observation_count,
+              accuracy:          prediction_accuracy
+            }
+          end
+
+          private
+
+          def compute_intervals(timestamps)
+            sorted = timestamps.sort
+            sorted.each_cons(2).map { |a, b| b - a }
+          end
+
+          def classify_pattern
+            return :random if @intervals.size < Constants::MIN_PATTERN_OBSERVATIONS
+
+            cv = coefficient_of_variation
+            if cv < Constants::PERIODIC_CV_THRESHOLD
+              :periodic
+            elsif bursts?
+              :bursty
+            else
+              :random
+            end
+          end
+
+          def coefficient_of_variation
+            return Float::INFINITY if @intervals.empty? || @mean_interval.nil? || @mean_interval.zero?
+
+            std_dev = Math.sqrt(@intervals.map { |i| (i - @mean_interval)**2 }.sum / @intervals.size.to_f)
+            std_dev / @mean_interval
+          end
+
+          def bursts?
+            return false unless @mean_interval
+
+            burst_threshold = @mean_interval * Constants::BURST_MULTIPLIER
+            burst_count = @intervals.count { |i| i < burst_threshold }
+            burst_count > @intervals.size * 0.3
+          end
+
+          def prediction_confidence
+            base = case @pattern_type
+                   when :periodic then 0.8
+                   when :bursty then 0.4
+                   else 0.2
+                   end
+            base * [1.0, @observation_count / 10.0].min
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/temporal/helpers/temporal_store.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Temporal
+      module Helpers
+        class TemporalStore
+          attr_reader :perception, :patterns
+
+          def initialize
+            @perception = TimePerception.new
+            @patterns = {}
+          end
+
+          def record_event(event, domain: :general)
+            key = @perception.mark_event(event, domain: domain)
+            update_pattern(domain, event)
+            key
+          end
+
+          def elapsed(event, domain: :general)
+            @perception.elapsed_since(event, domain: domain)
+          end
+
+          def predict_next(event, domain: :general)
+            pattern_key = "#{domain}:#{event}"
+            pattern = @patterns[pattern_key]
+            return nil unless pattern
+
+            pattern.predict_next
+          end
+
+          def record_prediction_outcome(event, actual_time:, domain: :general)
+            pattern_key = "#{domain}:#{event}"
+            pattern = @patterns[pattern_key]
+            pattern&.record_actual(actual_time)
+          end
+
+          def detect_patterns_for(event, domain: :general)
+            pattern_key = "#{domain}:#{event}"
+            @patterns[pattern_key]&.to_h
+          end
+
+          def all_patterns
+            @patterns.values.map(&:to_h)
+          end
+
+          def periodic_patterns
+            @patterns.values.select(&:periodic?).map(&:to_h)
+          end
+
+          def temporal_summary
+            {
+              perception:        @perception.to_h,
+              pattern_count:     @patterns.size,
+              periodic_count:    @patterns.values.count(&:periodic?),
+              bursty_count:      @patterns.values.count(&:bursty?),
+              overall_urgency:   @perception.overall_urgency,
+              overdue_deadlines: @perception.overdue_deadlines.size
+            }
+          end
+
+          private
+
+          def update_pattern(domain, event)
+            pattern_key = "#{domain}:#{event}"
+            event_key = "#{domain}:#{event}"
+            timestamps = @perception.events[event_key]
+            return unless timestamps && timestamps.size >= 2
+
+            @patterns[pattern_key] ||= TemporalPattern.new(domain: domain, event: event)
+            @patterns[pattern_key].add_observation(timestamps)
+            evict_patterns_if_needed
+          end
+
+          def evict_patterns_if_needed
+            return unless @patterns.size > Constants::MAX_PATTERNS
+
+            weakest = @patterns.min_by { |_k, p| p.observation_count }
+            @patterns.delete(weakest.first) if weakest
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/temporal/helpers/time_perception.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Temporal
+      module Helpers
+        class TimePerception
+          attr_reader :events, :deadlines, :subjective_rate
+
+          def initialize
+            @events = {}
+            @deadlines = {}
+            @subjective_rate = 1.0
+            @tick_count = 0
+          end
+
+          def mark_event(event, domain: :general)
+            key = "#{domain}:#{event}"
+            @events[key] ||= []
+            @events[key] << Time.now.utc
+            trim_events(key)
+            key
+          end
+
+          def elapsed_since(event, domain: :general)
+            key = "#{domain}:#{event}"
+            timestamps = @events[key]
+            return nil unless timestamps&.any?
+
+            Time.now.utc - timestamps.last
+          end
+
+          def time_since_first(event, domain: :general)
+            key = "#{domain}:#{event}"
+            timestamps = @events[key]
+            return nil unless timestamps&.any?
+
+            Time.now.utc - timestamps.first
+          end
+
+          def event_count(event, domain: :general)
+            key = "#{domain}:#{event}"
+            @events.fetch(key, []).size
+          end
+
+          def set_deadline(id, at:, description: nil)
+            @deadlines[id] = { at: at, created: Time.now.utc, description: description }
+            evict_deadlines_if_needed
+            id
+          end
+
+          def remove_deadline(id)
+            @deadlines.delete(id)
+          end
+
+          def deadline_urgency(id)
+            dl = @deadlines[id]
+            return nil unless dl
+
+            remaining = dl[:at] - Time.now.utc
+            return :overdue if remaining <= 0
+
+            total = dl[:at] - dl[:created]
+            return :critical if total <= 0
+
+            fraction = remaining / total
+            classify_deadline_urgency(fraction)
+          end
+
+          def overdue_deadlines
+            now = Time.now.utc
+            @deadlines.select { |_id, dl| dl[:at] <= now }
+                      .map { |id, dl| { id: id, overdue_by: now - dl[:at], description: dl[:description] } }
+          end
+
+          def upcoming_deadlines(within: 3600)
+            now = Time.now.utc
+            cutoff = now + within
+            @deadlines.select { |_id, dl| dl[:at] > now && dl[:at] <= cutoff }
+                      .map { |id, dl| { id: id, remaining: dl[:at] - now, description: dl[:description] } }
+                      .sort_by { |d| d[:remaining] }
+          end
+
+          def update_subjective_time(arousal: 0.5, cognitive_load: 0.5, **)
+            @tick_count += 1
+            raw_dilation = compute_dilation(arousal, cognitive_load)
+            @subjective_rate = ema(@subjective_rate, raw_dilation, Constants::SUBJECTIVE_ALPHA)
+            @subjective_rate
+          end
+
+          def subjective_elapsed(real_seconds)
+            real_seconds * @subjective_rate
+          end
+
+          def overall_urgency
+            urgencies = @deadlines.keys.map { |id| deadline_urgency(id) }.compact
+            return :none if urgencies.empty?
+
+            priority = Constants::URGENCY_LEVELS
+            urgencies.min_by { |u| u == :overdue ? -1 : priority.index(u) || 99 }
+          end
+
+          def to_h
+            {
+              event_domains:    @events.size,
+              active_deadlines: @deadlines.size,
+              overdue_count:    overdue_deadlines.size,
+              subjective_rate:  @subjective_rate,
+              overall_urgency:  overall_urgency,
+              tick_count:       @tick_count
+            }
+          end
+
+          private
+
+          def trim_events(key)
+            return unless @events[key].size > Constants::MAX_EVENTS_PER_DOMAIN
+
+            @events[key] = @events[key].last(Constants::MAX_EVENTS_PER_DOMAIN)
+          end
+
+          def evict_deadlines_if_needed
+            return unless @deadlines.size > Constants::MAX_DEADLINES
+
+            oldest_key = @deadlines.min_by { |_id, dl| dl[:created] }.first
+            @deadlines.delete(oldest_key)
+          end
+
+          def classify_deadline_urgency(fraction)
+            Constants::DEADLINE_URGENCY.each do |level, threshold|
+              return level if fraction <= threshold
+            end
+            :none
+          end
+
+          def compute_dilation(arousal, cognitive_load)
+            raw = 1.0 + ((arousal - 0.5) * 1.0) + ((cognitive_load - 0.5) * 0.5)
+            raw.clamp(Constants::DILATION_RANGE[:min], Constants::DILATION_RANGE[:max])
+          end
+
+          def ema(current, observed, alpha)
+            (current * (1.0 - alpha)) + (observed * alpha)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Temporal
+      module Runners
+        module Temporal
+          include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+          def mark_event(event:, domain: :general, **)
+            key = temporal_store.record_event(event, domain: domain)
+            count = temporal_store.perception.event_count(event, domain: domain)
+            { marked: true, key: key, event: event, domain: domain, total_occurrences: count }
+          end
+
+          def elapsed_since(event:, domain: :general, **)
+            elapsed = temporal_store.elapsed(event, domain: domain)
+            if elapsed
+              { event: event, domain: domain, elapsed_seconds: elapsed, human: humanize_duration(elapsed) }
+            else
+              { event: event, domain: domain, elapsed_seconds: nil, reason: :no_record }
+            end
+          end
+
+          def set_deadline(id:, at:, description: nil, **)
+            temporal_store.perception.set_deadline(id, at: at, description: description)
+            { set: true, id: id, at: at, description: description }
+          end
+
+          def check_deadlines(**)
+            {
+              overdue:  temporal_store.perception.overdue_deadlines,
+              upcoming: temporal_store.perception.upcoming_deadlines,
+              urgency:  temporal_store.perception.overall_urgency,
+              total:    temporal_store.perception.deadlines.size
+            }
+          end
+
+          def update_time_perception(tick_results: {}, **)
+            arousal = extract_arousal(tick_results)
+            load = extract_cognitive_load(tick_results)
+            rate = temporal_store.perception.update_subjective_time(arousal: arousal, cognitive_load: load)
+            {
+              subjective_rate: rate,
+              interpretation:  interpret_rate(rate),
+              overall_urgency: temporal_store.perception.overall_urgency,
+              overdue_count:   temporal_store.perception.overdue_deadlines.size
+            }
+          end
+
+          def predict_event(event:, domain: :general, **)
+            prediction = temporal_store.predict_next(event, domain: domain)
+            if prediction
+              { prediction: prediction, event: event, domain: domain }
+            else
+              { prediction: nil, reason: :insufficient_data }
+            end
+          end
+
+          def temporal_patterns(**)
+            {
+              all:      temporal_store.all_patterns,
+              periodic: temporal_store.periodic_patterns,
+              count:    temporal_store.patterns.size
+            }
+          end
+
+          def temporal_stats(**)
+            temporal_store.temporal_summary
+          end
+
+          private
+
+          def extract_arousal(tick_results)
+            emotion = tick_results[:emotional_evaluation]
+            return 0.5 unless emotion.is_a?(Hash)
+
+            emotion[:arousal] || 0.5
+          end
+
+          def extract_cognitive_load(tick_results)
+            elapsed = tick_results[:elapsed] || 0
+            budget = tick_results[:budget] || 1
+            return 0.5 if budget.zero?
+
+            (elapsed.to_f / budget).clamp(0.0, 1.0)
+          end
+
+          def humanize_duration(seconds)
+            if seconds < 60
+              "#{seconds.round(1)}s"
+            elsif seconds < 3600
+              "#{(seconds / 60).round(1)}m"
+            elsif seconds < 86_400
+              "#{(seconds / 3600).round(1)}h"
+            else
+              "#{(seconds / 86_400).round(1)}d"
+            end
+          end
+
+          def interpret_rate(rate)
+            if rate > 1.5
+              :time_crawling
+            elsif rate > 1.1
+              :time_slow
+            elsif rate < 0.7
+              :time_flying
+            elsif rate < 0.9
+              :time_fast
+            else
+              :normal
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/temporal.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'temporal/version'
+require_relative 'temporal/helpers/constants'
+require_relative 'temporal/helpers/time_perception'
+require_relative 'temporal/helpers/temporal_pattern'
+require_relative 'temporal/helpers/temporal_store'
+require_relative 'temporal/runners/temporal'
+require_relative 'temporal/client'
+
+module Legion
+  module Extensions
+    module Temporal
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: lex-temporal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: 'Provides time-aware cognitive processing: elapsed awareness, urgency,
+  temporal patterns, and deadline tracking'
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/temporal.rb
+- lib/legion/extensions/temporal/client.rb
+- lib/legion/extensions/temporal/helpers/constants.rb
+- lib/legion/extensions/temporal/helpers/temporal_pattern.rb
+- lib/legion/extensions/temporal/helpers/temporal_store.rb
+- lib/legion/extensions/temporal/helpers/time_perception.rb
+- lib/legion/extensions/temporal/runners/temporal.rb
+- lib/legion/extensions/temporal/version.rb
+homepage: https://github.com/LegionIO/lex-temporal
+licenses:
+- MIT
+metadata:
+  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: Temporal perception and time reasoning for LegionIO
+test_files: []