lex-flow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad617eaa39c186549a7304251ce00054370ba03c6fbc36916527c6e6f43b0194
+  data.tar.gz: e923b25557ef4bc122d66226759a0f0a669570668e0a39fd77f04fa4bdadf13e
+SHA512:
+  metadata.gz: 4404b6486afb71a5b14aae7a3bc971483fdc1e2cff8d50bd466bdd639ab7f7dca2b5e92362c654e93ed515da20368206af49ce082e6058cb735928fa708d0a82
+  data.tar.gz: 3443d0f74f6be25660aa93b62633ea49977fce4b8821c269fdefaa475002f3087b6dfabb2f3670420d58e5a5c85f8432d5f89e72f1043ac3c2ccb3396af9d403

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/flow/helpers/constants'
+require 'legion/extensions/flow/helpers/flow_detector'
+require 'legion/extensions/flow/runners/flow'
+
+module Legion
+  module Extensions
+    module Flow
+      class Client
+        include Runners::Flow
+
+        attr_reader :flow_detector
+
+        def initialize(flow_detector: nil, **)
+          @flow_detector = flow_detector || Helpers::FlowDetector.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Flow
+      module Helpers
+        module Constants
+          # Flow states (Csikszentmihalyi's model)
+          FLOW_STATES = %i[
+            flow
+            arousal
+            control
+            relaxation
+            boredom
+            apathy
+            worry
+            anxiety
+          ].freeze
+
+          # Input dimensions for flow detection
+          DIMENSIONS = %i[challenge skill].freeze
+
+          # Flow zone boundaries (challenge-skill space)
+          # Flow occurs when challenge ~= skill and both are moderate-to-high
+          FLOW_ZONE = {
+            challenge_min:     0.4,
+            challenge_max:     0.8,
+            skill_min:         0.4,
+            skill_max:         0.8,
+            balance_tolerance: 0.15
+          }.freeze
+
+          # EMA alpha for challenge/skill tracking
+          FLOW_ALPHA = 0.15
+
+          # Minimum ticks in flow before "deep flow" bonus
+          DEEP_FLOW_THRESHOLD = 20
+
+          # Flow score bonuses
+          DEEP_FLOW_BONUS = 0.1
+          CURIOSITY_BONUS = 0.05
+          LOW_ERROR_BONUS = 0.05
+
+          # Flow effects on other subsystems
+          FLOW_EFFECTS = {
+            fatigue_reduction:    0.5,   # fatigue drains 50% slower in flow
+            time_dilation:        0.7,   # subjective time flies (rate < 1.0)
+            performance_boost:    1.15,  # 15% performance improvement
+            attention_broadening: 0.8,   # attention threshold lowered (more open)
+            creativity_boost:     1.2    # curiosity/imagination amplified
+          }.freeze
+
+          # Anti-flow indicators (break flow state)
+          FLOW_BREAKERS = %i[
+            high_anxiety
+            trust_violation
+            critical_error
+            burnout
+            conflict_escalation
+          ].freeze
+
+          # History cap
+          MAX_FLOW_HISTORY = 100
+
+          # State classification regions in challenge-skill space
+          STATE_REGIONS = {
+            flow:       { challenge: (0.4..0.8), skill: (0.4..0.8), balanced: true },
+            arousal:    { challenge: (0.6..1.0), skill: (0.3..0.6), balanced: false },
+            control:    { challenge: (0.2..0.5), skill: (0.5..0.8), balanced: false },
+            relaxation: { challenge: (0.1..0.4), skill: (0.4..0.7), balanced: false },
+            boredom:    { challenge: (0.0..0.3), skill: (0.5..1.0), balanced: false },
+            apathy:     { challenge: (0.0..0.3), skill: (0.0..0.3), balanced: false },
+            worry:      { challenge: (0.5..0.8), skill: (0.1..0.4), balanced: false },
+            anxiety:    { challenge: (0.7..1.0), skill: (0.0..0.4), balanced: false }
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/flow/helpers/flow_detector.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Flow
+      module Helpers
+        class FlowDetector
+          attr_reader :challenge, :skill, :flow_state, :flow_score,
+                      :consecutive_flow_ticks, :total_flow_ticks, :history
+
+          def initialize
+            @challenge = 0.5
+            @skill = 0.5
+            @flow_state = :relaxation
+            @flow_score = 0.0
+            @consecutive_flow_ticks = 0
+            @total_flow_ticks = 0
+            @history = []
+          end
+
+          def update(challenge_input:, skill_input:, modifiers: {})
+            @challenge = ema(@challenge, challenge_input.clamp(0.0, 1.0), Constants::FLOW_ALPHA)
+            @skill = ema(@skill, skill_input.clamp(0.0, 1.0), Constants::FLOW_ALPHA)
+
+            @flow_state = classify_state
+            @flow_score = compute_flow_score(modifiers)
+
+            if @flow_state == :flow
+              @consecutive_flow_ticks += 1
+              @total_flow_ticks += 1
+            else
+              @consecutive_flow_ticks = 0
+            end
+
+            record_snapshot
+          end
+
+          def in_flow?
+            @flow_state == :flow
+          end
+
+          def deep_flow?
+            in_flow? && @consecutive_flow_ticks >= Constants::DEEP_FLOW_THRESHOLD
+          end
+
+          def flow_effects
+            if in_flow?
+              effects = Constants::FLOW_EFFECTS.dup
+              if deep_flow?
+                effects[:performance_boost] += 0.05
+                effects[:creativity_boost] += 0.1
+              end
+              effects
+            else
+              { fatigue_reduction: 1.0, time_dilation: 1.0, performance_boost: 1.0,
+                attention_broadening: 1.0, creativity_boost: 1.0 }
+            end
+          end
+
+          def challenge_skill_balance
+            (@challenge - @skill).abs
+          end
+
+          def flow_trend
+            return :insufficient_data if @history.size < 5
+
+            recent = @history.last(10)
+            scores = recent.map { |h| h[:flow_score] }
+            first_half = scores[0...(scores.size / 2)]
+            second_half = scores[(scores.size / 2)..]
+            diff = (second_half.sum / second_half.size.to_f) - (first_half.sum / first_half.size.to_f)
+
+            if diff > 0.05
+              :entering_flow
+            elsif diff < -0.05
+              :leaving_flow
+            else
+              :stable
+            end
+          end
+
+          def flow_percentage
+            return 0.0 if @history.empty?
+
+            flow_count = @history.count { |h| h[:state] == :flow }
+            (flow_count.to_f / @history.size * 100).round(1)
+          end
+
+          def to_h
+            {
+              state:                  @flow_state,
+              score:                  @flow_score.round(3),
+              challenge:              @challenge.round(3),
+              skill:                  @skill.round(3),
+              balance:                challenge_skill_balance.round(3),
+              in_flow:                in_flow?,
+              deep_flow:              deep_flow?,
+              consecutive_flow_ticks: @consecutive_flow_ticks,
+              total_flow_ticks:       @total_flow_ticks,
+              flow_percentage:        flow_percentage,
+              trend:                  flow_trend,
+              effects:                flow_effects
+            }
+          end
+
+          private
+
+          def classify_state
+            best_state = :apathy
+            best_score = -1.0
+
+            Constants::STATE_REGIONS.each do |state, region|
+              next unless region[:challenge].cover?(@challenge) && region[:skill].cover?(@skill)
+
+              score = region[:balanced] ? balance_bonus : 0.5
+              if score > best_score
+                best_score = score
+                best_state = state
+              end
+            end
+
+            best_state
+          end
+
+          def balance_bonus
+            balance = challenge_skill_balance
+            balance <= Constants::FLOW_ZONE[:balance_tolerance] ? 1.0 : 0.7
+          end
+
+          def compute_flow_score(modifiers)
+            base = if in_flow?
+                     0.7 + ((1.0 - challenge_skill_balance) * 0.3)
+                   else
+                     [0.0, 0.5 - (challenge_skill_balance * 0.5)].max
+                   end
+
+            base += Constants::DEEP_FLOW_BONUS if deep_flow?
+            base += Constants::CURIOSITY_BONUS if modifiers[:curiosity_active]
+            base += Constants::LOW_ERROR_BONUS if modifiers[:low_errors]
+
+            base.clamp(0.0, 1.0)
+          end
+
+          def ema(current, observed, alpha)
+            (current * (1.0 - alpha)) + (observed * alpha)
+          end
+
+          def record_snapshot
+            @history << {
+              state:      @flow_state,
+              flow_score: @flow_score,
+              challenge:  @challenge,
+              skill:      @skill,
+              at:         Time.now.utc
+            }
+            @history.shift while @history.size > Constants::MAX_FLOW_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Flow
+      module Runners
+        module Flow
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def update_flow(tick_results: {}, **)
+            challenge_input = extract_challenge(tick_results)
+            skill_input = extract_skill(tick_results)
+            modifiers = extract_modifiers(tick_results)
+
+            flow_detector.update(challenge_input: challenge_input, skill_input: skill_input, modifiers: modifiers)
+
+            breakers = detect_flow_breakers(tick_results)
+            if breakers.any? && flow_detector.in_flow?
+              flow_detector.instance_variable_set(:@flow_state, :disrupted)
+              flow_detector.instance_variable_set(:@consecutive_flow_ticks, 0)
+            end
+
+            Legion::Logging.debug "[flow] state=#{flow_detector.flow_state} score=#{flow_detector.flow_score.round(3)} " \
+                                  "deep=#{flow_detector.deep_flow?} breakers=#{breakers}"
+
+            {
+              state:     flow_detector.flow_state,
+              score:     flow_detector.flow_score.round(3),
+              in_flow:   flow_detector.in_flow?,
+              deep_flow: flow_detector.deep_flow?,
+              effects:   flow_detector.flow_effects,
+              breakers:  breakers,
+              challenge: flow_detector.challenge.round(3),
+              skill:     flow_detector.skill.round(3)
+            }
+          end
+
+          def flow_status(**)
+            Legion::Logging.debug "[flow] status: state=#{flow_detector.flow_state} score=#{flow_detector.flow_score.round(3)}"
+            flow_detector.to_h
+          end
+
+          def flow_effects(**)
+            effects = flow_detector.flow_effects
+            Legion::Logging.debug "[flow] effects: #{effects}"
+            { effects: effects, in_flow: flow_detector.in_flow?, deep_flow: flow_detector.deep_flow? }
+          end
+
+          def flow_history(limit: 20, **)
+            recent = flow_detector.history.last(limit)
+            Legion::Logging.debug "[flow] history: #{recent.size} entries"
+            { history: recent, total: flow_detector.history.size }
+          end
+
+          def flow_stats(**)
+            Legion::Logging.debug '[flow] stats'
+            {
+              state:                  flow_detector.flow_state,
+              score:                  flow_detector.flow_score.round(3),
+              consecutive_flow_ticks: flow_detector.consecutive_flow_ticks,
+              total_flow_ticks:       flow_detector.total_flow_ticks,
+              flow_percentage:        flow_detector.flow_percentage,
+              trend:                  flow_detector.flow_trend,
+              balance:                flow_detector.challenge_skill_balance.round(3)
+            }
+          end
+
+          private
+
+          def flow_detector
+            @flow_detector ||= Helpers::FlowDetector.new
+          end
+
+          def extract_challenge(tick_results)
+            prediction_accuracy = tick_results.dig(:prediction_engine, :rolling_accuracy) || 0.5
+            error_rate = tick_results.dig(:prediction_engine, :error_rate) || 0.5
+            task_complexity = tick_results.dig(:action_selection, :complexity) || 0.5
+
+            ((1.0 - prediction_accuracy) * 0.4) + (error_rate * 0.3) + (task_complexity * 0.3)
+          end
+
+          def extract_skill(tick_results)
+            prediction_accuracy = tick_results.dig(:prediction_engine, :rolling_accuracy) || 0.5
+            memory_strength = tick_results.dig(:memory_retrieval, :avg_strength) || 0.5
+            habit_automation = tick_results.dig(:habit, :automation_level) || 0.5
+
+            (prediction_accuracy * 0.4) + (memory_strength * 0.3) + (habit_automation * 0.3)
+          end
+
+          def extract_modifiers(tick_results)
+            {
+              curiosity_active: (tick_results.dig(:curiosity, :intensity) || 0.0) > 0.5,
+              low_errors:       (tick_results.dig(:prediction_engine, :error_rate) || 1.0) < 0.2
+            }
+          end
+
+          def detect_flow_breakers(tick_results)
+            breakers = []
+            check_anxiety_breaker(tick_results, breakers)
+            check_simple_breakers(tick_results, breakers)
+            check_conflict_breaker(tick_results, breakers)
+            breakers
+          end
+
+          def check_anxiety_breaker(tick_results, breakers)
+            anxiety = tick_results.dig(:emotional_evaluation, :anxiety) || 0.0
+            breakers << :high_anxiety if anxiety > 0.8
+          end
+
+          def check_simple_breakers(tick_results, breakers)
+            breakers << :trust_violation if tick_results.dig(:trust, :violation)
+            breakers << :critical_error if tick_results.dig(:error, :critical)
+            breakers << :burnout if tick_results.dig(:fatigue, :burnout)
+          end
+
+          def check_conflict_breaker(tick_results, breakers)
+            conflict = tick_results.dig(:conflict, :severity)
+            breakers << :conflict_escalation if conflict && conflict >= 4
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/flow.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/flow/version'
+require 'legion/extensions/flow/helpers/constants'
+require 'legion/extensions/flow/helpers/flow_detector'
+require 'legion/extensions/flow/runners/flow'
+require 'legion/extensions/flow/client'
+
+module Legion
+  module Extensions
+    module Flow
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: lex-flow
+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: Detects and manages psychological flow states based on challenge-skill
+  balance
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/flow.rb
+- lib/legion/extensions/flow/client.rb
+- lib/legion/extensions/flow/helpers/constants.rb
+- lib/legion/extensions/flow/helpers/flow_detector.rb
+- lib/legion/extensions/flow/runners/flow.rb
+- lib/legion/extensions/flow/version.rb
+homepage: https://github.com/LegionIO/lex-flow
+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: Flow state detection and management for LegionIO cognitive agents
+test_files: []