lex-planning 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5d3a843a1b4b2613a45996d9c12206f3a0f9387fb55a53688a09ccc254503c09
+  data.tar.gz: bc73bac9c97162ce4e471daa009242797d64b3a939de353f8a1395c96e04904f
+SHA512:
+  metadata.gz: 427f9cbf65397f9520b22f883bd0e406e9a26b4ecc483b11ae5ccfdb3205151bef3a5611da724b0fdb1ef204861d7b78defd4f5e1c924c1e7ccce49daa9c9e40
+  data.tar.gz: c31c83212f3d078206d6fcd714571c40b7313b4aecf534acc902677e4d566207a1f6fd238defdf3f9a103376891ea9d3fd6e4a5960acca308b270e5ae7d85d78

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/planning/helpers/constants'
+require 'legion/extensions/planning/helpers/plan_step'
+require 'legion/extensions/planning/helpers/plan'
+require 'legion/extensions/planning/helpers/plan_store'
+require 'legion/extensions/planning/runners/planning'
+
+module Legion
+  module Extensions
+    module Planning
+      class Client
+        include Runners::Planning
+
+        attr_reader :plan_store
+
+        def initialize(plan_store: nil, **)
+          @plan_store = plan_store || Helpers::PlanStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Planning
+      module Helpers
+        module Constants
+          PLAN_STATUSES  = %i[forming active executing completed failed abandoned].freeze
+          STEP_STATUSES  = %i[pending active completed failed skipped blocked].freeze
+          PRIORITIES     = { critical: 1.0, high: 0.75, medium: 0.5, low: 0.25 }.freeze
+          MAX_PLANS      = 50
+          MAX_STEPS_PER_PLAN  = 100
+          MAX_CONTINGENCIES   = 20
+          REPLAN_LIMIT        = 3
+          STALE_PLAN_THRESHOLD   = 3600
+          COMPLETION_THRESHOLD   = 0.95
+          PLANNING_HORIZON       = 10
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/planning/helpers/plan.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Planning
+      module Helpers
+        class Plan
+          attr_reader :id, :goal, :description, :priority, :steps, :contingencies,
+                      :parent_plan_id, :created_at, :replan_count
+          attr_accessor :status, :updated_at
+
+          def initialize(goal:, steps: [], priority: :medium, contingencies: {}, parent_plan_id: nil, description: nil, **)
+            @id             = SecureRandom.uuid
+            @goal           = goal
+            @description    = description
+            @priority       = priority
+            @status         = :forming
+            @steps          = steps.dup
+            @contingencies  = contingencies.dup
+            @parent_plan_id = parent_plan_id
+            @created_at     = Time.now.utc
+            @updated_at     = Time.now.utc
+            @replan_count   = 0
+          end
+
+          def progress
+            return 0.0 if @steps.empty?
+
+            done = @steps.count { |s| %i[completed skipped].include?(s.status) }
+            done.to_f / @steps.size
+          end
+
+          def active_step
+            @steps.find { |s| s.status == :active }
+          end
+
+          def completed_step_ids
+            @steps.select { |s| %i[completed skipped].include?(s.status) }.map(&:id)
+          end
+
+          def advance!(step_id, result: nil)
+            step = @steps.find { |s| s.id == step_id }
+            return nil unless step
+
+            step.complete!(result: result)
+            @updated_at = Time.now.utc
+            @status = :completed if progress >= Constants::COMPLETION_THRESHOLD
+            step
+          end
+
+          def fail_step!(step_id, reason: nil)
+            step = @steps.find { |s| s.id == step_id }
+            return nil unless step
+
+            step.fail!(reason: reason)
+            @updated_at = Time.now.utc
+            step
+          end
+
+          def complete?
+            @status == :completed || progress >= Constants::COMPLETION_THRESHOLD
+          end
+
+          def failed?
+            @status == :failed
+          end
+
+          def stale?
+            (Time.now.utc - @updated_at) > Constants::STALE_PLAN_THRESHOLD
+          end
+
+          def increment_replan!
+            @replan_count += 1
+            @updated_at = Time.now.utc
+          end
+
+          def replace_remaining_steps!(new_steps)
+            pending = @steps.reject { |s| %i[completed skipped failed].include?(s.status) }
+            pending.each { |s| @steps.delete(s) }
+            new_steps.each { |s| @steps << s }
+            @updated_at = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:             @id,
+              goal:           @goal,
+              description:    @description,
+              priority:       @priority,
+              status:         @status,
+              progress:       progress.round(4),
+              steps:          @steps.map(&:to_h),
+              contingencies:  @contingencies,
+              parent_plan_id: @parent_plan_id,
+              replan_count:   @replan_count,
+              created_at:     @created_at,
+              updated_at:     @updated_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/planning/helpers/plan_step.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Planning
+      module Helpers
+        class PlanStep
+          attr_reader :id, :action, :description, :depends_on, :estimated_effort,
+                      :started_at, :completed_at, :result
+          attr_accessor :status, :actual_effort
+
+          def initialize(action:, description: nil, depends_on: [], estimated_effort: 1, **)
+            @id               = SecureRandom.uuid
+            @action           = action
+            @description      = description
+            @status           = :pending
+            @depends_on       = Array(depends_on).dup
+            @estimated_effort = estimated_effort
+            @actual_effort    = nil
+            @result           = nil
+            @started_at       = nil
+            @completed_at     = nil
+          end
+
+          def ready?(completed_step_ids)
+            return false if %i[completed failed skipped].include?(@status)
+
+            @depends_on.all? { |dep_id| completed_step_ids.include?(dep_id) }
+          end
+
+          def duration
+            return nil unless @started_at && @completed_at
+
+            @completed_at - @started_at
+          end
+
+          def blocked?
+            @status == :blocked
+          end
+
+          def complete!(result: nil)
+            @status       = :completed
+            @result       = result
+            @completed_at = Time.now.utc
+          end
+
+          def fail!(reason: nil)
+            @status       = :failed
+            @result       = { reason: reason }
+            @completed_at = Time.now.utc
+          end
+
+          def start!
+            @status     = :active
+            @started_at = Time.now.utc
+          end
+
+          def to_h
+            {
+              id:               @id,
+              action:           @action,
+              description:      @description,
+              status:           @status,
+              depends_on:       @depends_on,
+              estimated_effort: @estimated_effort,
+              actual_effort:    @actual_effort,
+              result:           @result,
+              started_at:       @started_at,
+              completed_at:     @completed_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/planning/helpers/plan_store.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Planning
+      module Helpers
+        class PlanStore
+          attr_reader :plans, :plan_history
+
+          def initialize
+            @plans        = {}
+            @plan_history = []
+          end
+
+          def create_plan(goal:, steps: [], priority: :medium, contingencies: {}, parent_plan_id: nil, **)
+            step_objects = steps.map do |s|
+              s.is_a?(PlanStep) ? s : PlanStep.new(**s)
+            end
+            plan = Plan.new(
+              goal:           goal,
+              steps:          step_objects,
+              priority:       priority,
+              contingencies:  contingencies,
+              parent_plan_id: parent_plan_id
+            )
+            plan.status = :active
+            @plans[plan.id] = plan
+            trim_history
+            plan
+          end
+
+          def find_plan(plan_id)
+            @plans[plan_id]
+          end
+
+          def advance_step(plan_id:, step_id:, result: {})
+            plan = @plans[plan_id]
+            return { error: 'plan not found' } unless plan
+
+            step = plan.advance!(step_id, result: result)
+            return { error: 'step not found' } unless step
+
+            if plan.complete?
+              plan.status = :completed
+              archive_plan(plan_id)
+            end
+
+            { success: true, step_id: step_id, plan_progress: plan.progress.round(4), plan_status: plan.status }
+          end
+
+          def fail_step(plan_id:, step_id:, reason: nil)
+            plan = @plans[plan_id]
+            return { error: 'plan not found' } unless plan
+
+            step = plan.fail_step!(step_id, reason: reason)
+            return { error: 'step not found' } unless step
+
+            contingency = plan.contingencies[step.action] || plan.contingencies[step_id]
+            { success: true, step_id: step_id, contingency: contingency, plan_status: plan.status }
+          end
+
+          def replan(plan_id:, new_steps:, reason: nil)
+            plan = @plans[plan_id]
+            return { error: 'plan not found' } unless plan
+            return { error: 'replan limit reached' } if plan.replan_count >= Constants::REPLAN_LIMIT
+
+            step_objects = new_steps.map do |s|
+              s.is_a?(PlanStep) ? s : PlanStep.new(**s)
+            end
+            plan.increment_replan!
+            plan.replace_remaining_steps!(step_objects)
+            plan.status = :active
+
+            { success: true, plan_id: plan_id, replan_count: plan.replan_count, reason: reason }
+          end
+
+          def abandon_plan(plan_id:, reason: nil)
+            plan = @plans[plan_id]
+            return { error: 'plan not found' } unless plan
+
+            plan.status = :abandoned
+            archive_plan(plan_id)
+            { success: true, plan_id: plan_id, reason: reason }
+          end
+
+          def active_plans
+            @plans.values.select { |p| %i[active executing].include?(p.status) }
+          end
+
+          def completed_plans(limit: 10)
+            @plan_history.last(limit)
+          end
+
+          def plan_progress(plan_id)
+            plan = @plans[plan_id] || @plan_history.find { |p| p.id == plan_id }
+            return { error: 'plan not found' } unless plan
+
+            ready_ids = plan.completed_step_ids
+            {
+              plan_id:      plan_id,
+              goal:         plan.goal,
+              status:       plan.status,
+              progress:     plan.progress.round(4),
+              total_steps:  plan.steps.size,
+              completed:    plan.steps.count { |s| s.status == :completed },
+              failed:       plan.steps.count { |s| s.status == :failed },
+              pending:      plan.steps.count { |s| s.status == :pending },
+              blocked:      plan.steps.count { |s| s.status == :blocked },
+              next_ready:   plan.steps.select { |s| s.status == :pending && s.ready?(ready_ids) }.map(&:id),
+              replan_count: plan.replan_count,
+              stale:        plan.stale?
+            }
+          end
+
+          def plans_by_priority
+            priority_value = ->(p) { Constants::PRIORITIES.fetch(p.priority, 0.5) }
+            @plans.values.sort_by { |p| -priority_value.call(p) }
+          end
+
+          def stats
+            all = @plans.values
+            total = all.size + @plan_history.size
+            by_status = Constants::PLAN_STATUSES.to_h { |s| [s, all.count { |p| p.status == s }] }
+            replanned = all.count { |p| p.replan_count.positive? }
+            avg_progress = all.empty? ? 0.0 : (all.sum(&:progress) / all.size).round(4)
+            replan_rate = total.zero? ? 0.0 : (replanned.to_f / [all.size, 1].max).round(4)
+
+            {
+              active_plan_count:   all.size,
+              archived_plan_count: @plan_history.size,
+              by_status:           by_status,
+              avg_progress:        avg_progress,
+              replan_rate:         replan_rate
+            }
+          end
+
+          def trim_history
+            return unless @plans.size > Constants::MAX_PLANS
+
+            oldest_id = @plans.keys.min_by { |k| @plans[k].created_at }
+            archive_plan(oldest_id)
+          end
+
+          private
+
+          def archive_plan(plan_id)
+            plan = @plans.delete(plan_id)
+            return unless plan
+
+            @plan_history << plan
+            @plan_history.shift while @plan_history.size > Constants::MAX_PLANS
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Planning
+      module Runners
+        module Planning
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def update_planning(tick_results: {}, **)
+            check_stale_plans
+            advance_ready_steps(tick_results)
+
+            active = plan_store.active_plans
+            Legion::Logging.debug "[planning] active_plans=#{active.size} stats=#{plan_store.stats[:by_status]}"
+
+            {
+              active_plans:  active.size,
+              total_steps:   active.sum { |p| p.steps.size },
+              stale_checked: true
+            }
+          end
+
+          def create_plan(goal:, steps: [], priority: :medium, contingencies: {}, parent_plan_id: nil, **)
+            steps_data = steps.map { |s| s.is_a?(Hash) ? s : s.to_h }
+            plan = plan_store.create_plan(
+              goal:           goal,
+              steps:          steps_data,
+              priority:       priority,
+              contingencies:  contingencies,
+              parent_plan_id: parent_plan_id
+            )
+            Legion::Logging.info "[planning] created plan=#{plan.id} goal=#{goal} steps=#{plan.steps.size}"
+            { success: true, plan_id: plan.id, goal: goal, steps: plan.steps.size }
+          end
+
+          def advance_plan(plan_id:, step_id:, result: {}, **)
+            outcome = plan_store.advance_step(plan_id: plan_id, step_id: step_id, result: result)
+            Legion::Logging.debug "[planning] advance plan=#{plan_id} step=#{step_id} outcome=#{outcome[:plan_status]}"
+            outcome
+          end
+
+          def fail_plan_step(plan_id:, step_id:, reason: nil, **)
+            outcome = plan_store.fail_step(plan_id: plan_id, step_id: step_id, reason: reason)
+            Legion::Logging.warn "[planning] step failed plan=#{plan_id} step=#{step_id} reason=#{reason}"
+            outcome
+          end
+
+          def replan(plan_id:, new_steps: [], reason: nil, **)
+            steps_data = new_steps.map { |s| s.is_a?(Hash) ? s : s.to_h }
+            outcome = plan_store.replan(plan_id: plan_id, new_steps: steps_data, reason: reason)
+            if outcome[:success]
+              Legion::Logging.info "[planning] replan plan=#{plan_id} count=#{outcome[:replan_count]} reason=#{reason}"
+            else
+              Legion::Logging.warn "[planning] replan rejected plan=#{plan_id} reason=#{outcome[:error]}"
+            end
+            outcome
+          end
+
+          def abandon_plan(plan_id:, reason: nil, **)
+            outcome = plan_store.abandon_plan(plan_id: plan_id, reason: reason)
+            Legion::Logging.info "[planning] abandoned plan=#{plan_id} reason=#{reason}"
+            outcome
+          end
+
+          def plan_status(plan_id:, **)
+            outcome = plan_store.plan_progress(plan_id)
+            Legion::Logging.debug "[planning] status plan=#{plan_id} progress=#{outcome[:progress]}"
+            outcome
+          end
+
+          def active_plans(**)
+            plans = plan_store.active_plans
+            Legion::Logging.debug "[planning] active_plans=#{plans.size}"
+            {
+              plans: plans.map(&:to_h),
+              count: plans.size
+            }
+          end
+
+          def planning_stats(**)
+            stats = plan_store.stats
+            Legion::Logging.debug "[planning] stats=#{stats}"
+            stats
+          end
+
+          private
+
+          def plan_store
+            @plan_store ||= Helpers::PlanStore.new
+          end
+
+          def check_stale_plans
+            plan_store.active_plans.each do |plan|
+              Legion::Logging.warn "[planning] stale plan detected plan=#{plan.id} goal=#{plan.goal}" if plan.stale?
+            end
+          end
+
+          def advance_ready_steps(tick_results)
+            completed_actions = tick_results.dig(:action_selection, :completed_actions)
+            return unless completed_actions.is_a?(Array)
+
+            plan_store.active_plans.each do |plan|
+              ready_ids = plan.completed_step_ids
+              plan.steps.each do |step|
+                next unless step.status == :pending && step.ready?(ready_ids)
+                next unless completed_actions.any? { |a| a[:action] == step.action }
+
+                result = completed_actions.find { |a| a[:action] == step.action }
+                plan_store.advance_step(plan_id: plan.id, step_id: step.id, result: result)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/planning.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/planning/version'
+require 'legion/extensions/planning/helpers/constants'
+require 'legion/extensions/planning/helpers/plan_step'
+require 'legion/extensions/planning/helpers/plan'
+require 'legion/extensions/planning/helpers/plan_store'
+require 'legion/extensions/planning/runners/planning'
+require 'legion/extensions/planning/client'
+
+module Legion
+  module Extensions
+    module Planning
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lex-planning
+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: 'Models the prefrontal cortex planning function: plan trees, progress
+  tracking, contingencies, re-planning'
+email:
+- matt@legionIO.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/legion/extensions/planning.rb
+- lib/legion/extensions/planning/client.rb
+- lib/legion/extensions/planning/helpers/constants.rb
+- lib/legion/extensions/planning/helpers/plan.rb
+- lib/legion/extensions/planning/helpers/plan_step.rb
+- lib/legion/extensions/planning/helpers/plan_store.rb
+- lib/legion/extensions/planning/runners/planning.rb
+- lib/legion/extensions/planning/version.rb
+homepage: https://github.com/LegionIO/lex-planning
+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: Hierarchical goal decomposition and plan formation for LegionIO cognitive
+  agents
+test_files: []