lex-habit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0a865cd888c03af9bc77d51dc7ea7721fa49413288f568d8dd5e765a8dc0d2e
+  data.tar.gz: 24761157f9e83cfec300b8b0dccba1a1d92e50476793be7802ced4710d71e950
+SHA512:
+  metadata.gz: f8f2f8170d0c98b3ae47937ddc8630c12ed373bd43bf15e2e3e5754c01ce23bb4b42c3ceaec8394fcf6beb58c8608d0ad14e65a5ac01a7097668c342d4b2e6b1
+  data.tar.gz: 6e49a7a3686f54b7b24d36d501fb4455b53f6d3c2efdacf5b7244f371c701967bc072b83f296b9ac96de895e929244d227c37662232542bb8c9f116709899ca6

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/habit/helpers/constants'
+require 'legion/extensions/habit/helpers/action_sequence'
+require 'legion/extensions/habit/helpers/habit_store'
+require 'legion/extensions/habit/runners/habit'
+
+module Legion
+  module Extensions
+    module Habit
+      class Client
+        include Runners::Habit
+
+        attr_reader :habit_store
+
+        def initialize(habit_store: nil, **)
+          @habit_store = habit_store || Helpers::HabitStore.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/habit/helpers/action_sequence.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Habit
+      module Helpers
+        class ActionSequence
+          include Constants
+
+          attr_reader :id, :actions, :context, :execution_count, :success_count,
+                      :strength, :maturity, :last_executed, :created_at
+
+          def initialize(actions:, context: {})
+            @id              = SecureRandom.uuid
+            @actions         = actions.map(&:to_sym)
+            @context         = context
+            @execution_count = 0
+            @success_count   = 0
+            @strength        = 0.3
+            @maturity        = :novel
+            @last_executed   = nil
+            @created_at      = Time.now.utc
+          end
+
+          def record_execution(success:)
+            @execution_count += 1
+            @success_count   += 1 if success
+            @last_executed    = Time.now.utc
+
+            @strength = if success
+                          [@strength + Constants::REINFORCEMENT_RATE, 1.0].min
+                        else
+                          [@strength - Constants::REINFORCEMENT_RATE, 0.0].max
+                        end
+
+            update_maturity
+          end
+
+          def cognitive_cost
+            Constants::COGNITIVE_COST[@maturity]
+          end
+
+          def success_rate
+            return 0.0 if @execution_count.zero?
+
+            @success_count.to_f / @execution_count
+          end
+
+          def matches_context?(ctx)
+            return true if ctx.empty?
+
+            relevant = Constants::CONTEXT_DIMENSIONS.select { |d| @context.key?(d) || ctx.key?(d) }
+            return true if relevant.empty?
+
+            matches = relevant.count { |d| @context[d] == ctx[d] }
+            matches.to_f / relevant.size >= 0.5
+          end
+
+          def decay
+            @strength -= Constants::DECAY_RATE
+            @strength >= Constants::HABIT_STRENGTH_FLOOR
+          end
+
+          def mature?
+            @maturity == :habitual || @maturity == :automatic
+          end
+
+          def stale?(threshold = 3600)
+            return true if @last_executed.nil?
+
+            (Time.now.utc - @last_executed) > threshold
+          end
+
+          def similarity(other)
+            set_a = @actions.uniq
+            set_b = other.actions.uniq
+            return 0.0 if set_a.empty? && set_b.empty?
+
+            intersection = (set_a & set_b).size
+            union        = (set_a | set_b).size
+            return 0.0 if union.zero?
+
+            intersection.to_f / union
+          end
+
+          def to_h
+            {
+              id:              @id,
+              actions:         @actions,
+              context:         @context,
+              execution_count: @execution_count,
+              success_count:   @success_count,
+              strength:        @strength,
+              maturity:        @maturity,
+              cognitive_cost:  cognitive_cost,
+              success_rate:    success_rate,
+              last_executed:   @last_executed,
+              created_at:      @created_at
+            }
+          end
+
+          private
+
+          def update_maturity
+            new_stage = Constants::MATURITY_STAGES.reverse.find do |stage|
+              @execution_count >= Constants::MATURITY_THRESHOLDS[stage]
+            end
+            @maturity = new_stage || :novel
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Habit
+      module Helpers
+        module Constants
+          MATURITY_STAGES = %i[novel learning practiced habitual automatic].freeze
+
+          MATURITY_THRESHOLDS = {
+            novel:     0,
+            learning:  3,
+            practiced: 10,
+            habitual:  25,
+            automatic: 50
+          }.freeze
+
+          COGNITIVE_COST = {
+            novel:     1.0,
+            learning:  0.8,
+            practiced: 0.5,
+            habitual:  0.2,
+            automatic: 0.05
+          }.freeze
+
+          REINFORCEMENT_RATE   = 0.1
+          DECAY_RATE           = 0.02
+          MIN_SEQUENCE_LENGTH  = 2
+          MAX_SEQUENCE_LENGTH  = 10
+          MAX_HABITS           = 200
+          SIMILARITY_THRESHOLD = 0.7
+          CHUNKING_THRESHOLD   = 5
+          HABIT_STRENGTH_FLOOR = 0.1
+
+          CONTEXT_DIMENSIONS = %i[domain mood time_of_day trigger].freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/habit/helpers/habit_store.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Habit
+      module Helpers
+        class HabitStore # rubocop:disable Metrics/ClassLength
+          include Constants
+
+          MAX_BUFFER_SIZE = 50
+
+          attr_reader :habits, :action_buffer
+
+          def initialize
+            @habits        = {}
+            @action_buffer = []
+          end
+
+          def record_action(action, context: {})
+            @action_buffer << { action: action.to_sym, context: context }
+            @action_buffer.shift if @action_buffer.size > MAX_BUFFER_SIZE
+          end
+
+          def detect_patterns
+            new_habits = []
+            actions    = @action_buffer.map { |e| e[:action] }
+            ctx        = @action_buffer.last&.dig(:context) || {}
+
+            (Constants::MIN_SEQUENCE_LENGTH..Constants::MAX_SEQUENCE_LENGTH).each do |len|
+              next if actions.size < len
+
+              process_length(len, actions, ctx, new_habits)
+            end
+
+            new_habits
+          end
+
+          def find_matching(context: {})
+            @habits.values
+                   .select { |h| h.matches_context?(context) }
+                   .sort_by { |h| -h.strength }
+          end
+
+          def get(id)
+            @habits[id]
+          end
+
+          def reinforce(id, success:)
+            habit = @habits[id]
+            return unless habit
+
+            habit.record_execution(success: success)
+          end
+
+          def decay_all
+            removed = 0
+            @habits.each do |id, habit|
+              unless habit.decay
+                @habits.delete(id)
+                removed += 1
+              end
+            end
+            removed
+          end
+
+          def merge_similar
+            merged = 0
+            @habits.keys.combination(2).each do |id_a, id_b|
+              merged += 1 if merge_pair(id_a, id_b)
+            end
+            merged
+          end
+
+          def by_maturity(stage)
+            @habits.values.select { |h| h.maturity == stage }
+          end
+
+          def stats
+            habits_list  = @habits.values
+            per_maturity = Constants::MATURITY_STAGES.to_h { |s| [s, 0] }
+            habits_list.each { |h| per_maturity[h.maturity] += 1 }
+            avg_strength = habits_list.empty? ? 0.0 : habits_list.sum(&:strength) / habits_list.size
+            oldest       = habits_list.min_by(&:created_at)
+            { total: habits_list.size, per_maturity: per_maturity, avg_strength: avg_strength, oldest: oldest&.to_h }
+          end
+
+          def evict_if_needed
+            return unless @habits.size > Constants::MAX_HABITS
+
+            weakest_id = @habits.min_by { |_id, h| h.strength }.first
+            @habits.delete(weakest_id)
+          end
+
+          private
+
+          def process_length(len, actions, ctx, new_habits)
+            count_subsequences(actions, len).each do |subseq, count|
+              next if count < Constants::CHUNKING_THRESHOLD
+
+              record_or_reinforce(subseq, count, ctx, new_habits)
+            end
+          end
+
+          def count_subsequences(actions, len)
+            counts = Hash.new(0)
+            (0..(actions.size - len)).each { |i| counts[actions[i, len]] += 1 }
+            counts
+          end
+
+          def record_or_reinforce(subseq, count, ctx, new_habits)
+            existing = find_existing_sequence(subseq)
+            if existing
+              existing.record_execution(success: true)
+            else
+              create_habit(subseq, count, ctx, new_habits)
+            end
+          end
+
+          def create_habit(subseq, count, ctx, new_habits)
+            habit = ActionSequence.new(actions: subseq, context: ctx)
+            (count - 1).times { habit.record_execution(success: true) }
+            @habits[habit.id] = habit
+            evict_if_needed
+            new_habits << habit
+          end
+
+          def merge_pair(id_a, id_b)
+            habit_a = @habits[id_a]
+            habit_b = @habits[id_b]
+            return false unless habit_a && habit_b
+            return false if habit_a.similarity(habit_b) < Constants::SIMILARITY_THRESHOLD
+
+            @habits.delete(habit_a.strength >= habit_b.strength ? id_b : id_a)
+            true
+          end
+
+          def find_existing_sequence(actions)
+            @habits.values.find { |h| h.actions == actions.map(&:to_sym) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Habit
+      module Runners
+        module Habit
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def observe_action(action:, context: {}, **)
+            Legion::Logging.debug "[habit] observe_action: action=#{action} context=#{context}"
+            habit_store.record_action(action, context: context)
+            detected = habit_store.detect_patterns
+            Legion::Logging.info "[habit] patterns detected: #{detected.size}" unless detected.empty?
+            {
+              recorded:            true,
+              action:              action,
+              new_habits_detected: detected.size,
+              habits:              detected.map(&:to_h)
+            }
+          end
+
+          def suggest_habit(context: {}, **)
+            matches = habit_store.find_matching(context: context)
+            Legion::Logging.debug "[habit] suggest_habit: context=#{context} matches=#{matches.size}"
+            if matches.empty?
+              { suggestion: nil, reason: :no_matching_habits }
+            else
+              best = matches.first
+              {
+                suggestion:        best.to_h,
+                cognitive_savings: 1.0 - best.cognitive_cost,
+                alternatives:      matches[1..2]&.map(&:to_h) || []
+              }
+            end
+          end
+
+          def execute_habit(id:, success: true, **)
+            habit = habit_store.get(id)
+            return { error: :not_found } unless habit
+
+            habit.record_execution(success: success)
+            Legion::Logging.debug "[habit] execute_habit: id=#{id} success=#{success} maturity=#{habit.maturity}"
+            { executed: true, habit: habit.to_h, cognitive_cost: habit.cognitive_cost }
+          end
+
+          def decay_habits(**)
+            removed = habit_store.decay_all
+            Legion::Logging.debug "[habit] decay_habits: removed=#{removed}"
+            { decayed: true, removed_count: removed }
+          end
+
+          def merge_habits(**)
+            merged = habit_store.merge_similar
+            Legion::Logging.debug "[habit] merge_habits: merged=#{merged}"
+            { merged_count: merged }
+          end
+
+          def habit_stats(**)
+            habit_store.stats
+          end
+
+          def habit_repertoire(maturity: nil, limit: 20, **)
+            habits = maturity ? habit_store.by_maturity(maturity.to_sym) : habit_store.habits.values
+            Legion::Logging.debug "[habit] habit_repertoire: maturity=#{maturity} total=#{habits.size}"
+            {
+              habits: habits.sort_by { |h| -h.strength }.first(limit).map(&:to_h),
+              total:  habits.size
+            }
+          end
+
+          private
+
+          def habit_store
+            @habit_store ||= Helpers::HabitStore.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/habit.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/habit/version'
+require 'legion/extensions/habit/helpers/constants'
+require 'legion/extensions/habit/helpers/action_sequence'
+require 'legion/extensions/habit/helpers/habit_store'
+require 'legion/extensions/habit/runners/habit'
+require 'legion/extensions/habit/client'
+
+module Legion
+  module Extensions
+    module Habit
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: lex-habit
+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: Procedural learning and skill acquisition for brain-modeled agentic AI
+  — repeated action sequences become chunked habits with decreasing cognitive overhead
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/habit.rb
+- lib/legion/extensions/habit/client.rb
+- lib/legion/extensions/habit/helpers/action_sequence.rb
+- lib/legion/extensions/habit/helpers/constants.rb
+- lib/legion/extensions/habit/helpers/habit_store.rb
+- lib/legion/extensions/habit/runners/habit.rb
+- lib/legion/extensions/habit/version.rb
+homepage: https://github.com/LegionIO/lex-habit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-habit
+  source_code_uri: https://github.com/LegionIO/lex-habit
+  documentation_uri: https://github.com/LegionIO/lex-habit
+  changelog_uri: https://github.com/LegionIO/lex-habit
+  bug_tracker_uri: https://github.com/LegionIO/lex-habit/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: LEX Habit
+test_files: []