lex-affordance 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c87927c90cc5dfc5bd73e728ad8952b88ac73eaf98d287f1c50f250694765e5b
+  data.tar.gz: 334f20991fedba8202b3d846780d50b69874bbb452af0d529763b080a1845867
+SHA512:
+  metadata.gz: 03e2342c50eab44e9773bbcc9d7e7d8f12418807d06e5dc4a9665ccbb6a093239b851e2a2e44bc881260a73bc80968c324e92730ae25dc262e54d415142d65b2
+  data.tar.gz: e677b9ed5bc2cc6c2d645c07c9514cc41969ad723ffda66bf8276daa1b73c9d9972d2c3b45fbba7f0db66bbd911ae532ad472f9e623f0e218431fe0ce33e1f39

data/README.md

@@ -0,0 +1,65 @@
+# lex-affordance
+
+Gibson's ecological affordance perception for LegionIO — detecting action possibilities in the environment.
+
+## What It Does
+
+Models J.J. Gibson's ecological theory of affordances: the agent perceives its environment in terms of what actions are possible, blocked, risky, or threatening given its current capabilities. The extension maintains an affordance field that tracks opportunities, threats, and action feasibility. Affordances decay over time as the environment changes.
+
+## Core Concept: The Affordance Field
+
+An affordance describes an action-environment relationship from the agent's perspective:
+
+```ruby
+# Register what the agent can do
+client.register_capability(name: :make_api_call, domain: :http, level: 0.9)
+
+# Detect what the environment affords
+client.detect_affordance(
+  action: :deploy_service,
+  domain: :infrastructure,
+  affordance_type: :action_possible,
+  requires: [:make_api_call],
+  relevance: 0.8
+)
+
+# Check if an action is feasible
+result = client.evaluate_action(action: :deploy_service, domain: :infrastructure)
+# => { feasible: true, reason: :capable, risks: [], relevance: 0.8 }
+```
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Affordance::Client.new
+
+# Set environmental conditions
+client.set_environment(property: :network_available, value: true, domain: :infrastructure)
+
+# List what's immediately actionable (relevance >= 0.5)
+client.actionable_affordances
+# => { affordances: [...], count: 2 }
+
+# Check for threats
+client.current_threats
+# => { threats: [...], count: 1 }
+
+# Maintenance (also runs automatically every 30s via Scan actor)
+client.update_affordances
+```
+
+## Integration
+
+The `Scan` actor decays affordances every 30 seconds automatically. Wire into lex-tick's `action_selection` phase to filter candidate actions by feasibility before execution.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/legion/extensions/affordance/actors/scan.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Affordance
+      module Actors
+        class Scan < Legion::Extensions::Actors::Every
+          INTERVAL = 30
+
+          def run
+            Runners::Affordance.instance_method(:update_affordances).bind_call(runner_instance)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/affordance/helpers/constants'
+require 'legion/extensions/affordance/helpers/affordance_item'
+require 'legion/extensions/affordance/helpers/affordance_field'
+require 'legion/extensions/affordance/runners/affordance'
+
+module Legion
+  module Extensions
+    module Affordance
+      class Client
+        include Runners::Affordance
+
+        def initialize(field: nil, **)
+          @field = field || Helpers::AffordanceField.new
+        end
+
+        private
+
+        attr_reader :field
+      end
+    end
+  end
+end

data/lib/legion/extensions/affordance/helpers/affordance_field.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Affordance
+      module Helpers
+        class AffordanceField
+          include Constants
+
+          attr_reader :affordances, :capabilities, :environment
+
+          def initialize
+            @affordances   = {}
+            @capabilities  = {}
+            @environment   = {}
+            @counter       = 0
+            @history       = []
+          end
+
+          def register_capability(name:, domain: :general, level: 1.0)
+            return nil if @capabilities.size >= MAX_CAPABILITIES
+
+            @capabilities[name] = { domain: domain, level: level.to_f.clamp(0.0, 1.0) }
+          end
+
+          def set_environment(property:, value:, domain: :general)
+            return nil if @environment.size >= MAX_ENVIRONMENT_PROPS && !@environment.key?(property)
+
+            @environment[property] = { value: value, domain: domain, updated_at: Time.now.utc }
+          end
+
+          def detect_affordance(action:, domain:, affordance_type:, requires: [], relevance: DEFAULT_RELEVANCE)
+            return nil unless AFFORDANCE_TYPES.include?(affordance_type)
+            return nil if @affordances.size >= MAX_AFFORDANCES
+
+            @counter += 1
+            aff_id = :"aff_#{@counter}"
+            aff = AffordanceItem.new(
+              id: aff_id, action: action, domain: domain,
+              affordance_type: affordance_type, requires: requires, relevance: relevance
+            )
+            @affordances[aff_id] = aff
+            record_detection(aff)
+            aff
+          end
+
+          def evaluate_action(action:, domain:)
+            matching = @affordances.values.select { |a| a.action == action && a.domain == domain }
+            return { feasible: false, reason: :no_affordance } if matching.empty?
+
+            check_blockers(matching) || build_evaluation(matching)
+          end
+
+          def actionable_affordances
+            @affordances.values.select(&:actionable?).sort_by { |a| -a.relevance }.map(&:to_h)
+          end
+
+          def threats
+            @affordances.values.select(&:threatening?).map(&:to_h)
+          end
+
+          def affordances_in(domain:)
+            @affordances.values.select { |a| a.domain == domain }.map(&:to_h)
+          end
+
+          def decay_all
+            @affordances.each_value(&:decay)
+            @affordances.reject! { |_, a| a.faded? }
+          end
+
+          def to_h
+            {
+              affordance_count:  @affordances.size,
+              capability_count:  @capabilities.size,
+              environment_props: @environment.size,
+              actionable_count:  @affordances.values.count(&:actionable?),
+              blocked_count:     @affordances.values.count(&:blocked?),
+              threat_count:      @affordances.values.count(&:threatening?),
+              history_size:      @history.size
+            }
+          end
+
+          private
+
+          def check_blockers(matching)
+            blockers = matching.select(&:blocked?)
+            return nil if blockers.empty?
+
+            { feasible: false, reason: :blocked, blockers: blockers.map(&:to_h) }
+          end
+
+          def build_evaluation(matching)
+            capabilities_met = check_requirements(matching)
+            {
+              feasible:         capabilities_met,
+              reason:           capabilities_met ? :capable : :missing_capabilities,
+              risks:            matching.select(&:risky?).map(&:to_h),
+              relevance:        matching.map(&:relevance).max,
+              affordance_count: matching.size
+            }
+          end
+
+          def check_requirements(affordances)
+            required = affordances.flat_map(&:requires).uniq
+            return true if required.empty?
+
+            required.all? { |r| @capabilities.key?(r) }
+          end
+
+          def record_detection(affordance)
+            @history << { id: affordance.id, action: affordance.action, type: affordance.affordance_type,
+                          at: Time.now.utc }
+            @history.shift while @history.size > MAX_HISTORY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/affordance/helpers/affordance_item.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Affordance
+      module Helpers
+        class AffordanceItem
+          include Constants
+
+          attr_reader :id, :action, :domain, :affordance_type, :requires, :detected_at
+          attr_accessor :relevance
+
+          def initialize(id:, action:, domain:, affordance_type:, requires: [], relevance: DEFAULT_RELEVANCE)
+            @id              = id
+            @action          = action
+            @domain          = domain
+            @affordance_type = affordance_type
+            @requires        = Array(requires)
+            @relevance       = relevance.to_f.clamp(0.0, 1.0)
+            @detected_at     = Time.now.utc
+          end
+
+          def actionable?
+            %i[action_possible resource_available opportunity].include?(@affordance_type) &&
+              @relevance >= ACTIONABLE_THRESHOLD
+          end
+
+          def blocked?
+            @affordance_type == :action_blocked
+          end
+
+          def risky?
+            @affordance_type == :action_risky
+          end
+
+          def threatening?
+            @affordance_type == :threat
+          end
+
+          def decay
+            @relevance = [@relevance - RELEVANCE_DECAY, 0.0].max
+          end
+
+          def faded?
+            @relevance <= RELEVANCE_FLOOR
+          end
+
+          def relevance_label
+            RELEVANCE_LABELS.each { |range, lbl| return lbl if range.cover?(@relevance) }
+            :negligible
+          end
+
+          def to_h
+            {
+              id:              @id,
+              action:          @action,
+              domain:          @domain,
+              affordance_type: @affordance_type,
+              requires:        @requires,
+              relevance:       @relevance.round(4),
+              relevance_label: relevance_label,
+              actionable:      actionable?,
+              blocked:         blocked?,
+              risky:           risky?
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Affordance
+      module Helpers
+        module Constants
+          MAX_AFFORDANCES       = 200
+          MAX_CAPABILITIES      = 50
+          MAX_ENVIRONMENT_PROPS = 100
+          MAX_HISTORY           = 200
+
+          RELEVANCE_FLOOR       = 0.05
+          RELEVANCE_DECAY       = 0.01
+          DEFAULT_RELEVANCE     = 0.5
+          URGENCY_BOOST         = 0.2
+
+          CAPABILITY_MATCH_THRESHOLD = 0.3
+          ACTIONABLE_THRESHOLD       = 0.5
+
+          AFFORDANCE_TYPES = %i[
+            action_possible action_blocked action_risky
+            resource_available resource_depleted
+            opportunity threat neutral
+          ].freeze
+
+          RELEVANCE_LABELS = {
+            (0.8..)     => :critical,
+            (0.6...0.8) => :important,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :minor,
+            (..0.2)     => :negligible
+          }.freeze
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Affordance
+      module Runners
+        module Affordance
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def register_capability(name:, domain: :general, level: 1.0, **)
+            Legion::Logging.debug "[affordance] capability: #{name} domain=#{domain}"
+            cap = field.register_capability(name: name, domain: domain, level: level)
+            if cap
+              { success: true, capability: name, capabilities: field.capabilities.size }
+            else
+              { success: false, reason: :limit_reached }
+            end
+          end
+
+          def set_environment(property:, value:, domain: :general, **)
+            Legion::Logging.debug "[affordance] env: #{property}=#{value}"
+            result = field.set_environment(property: property, value: value, domain: domain)
+            if result
+              { success: true, property: property }
+            else
+              { success: false, reason: :limit_reached }
+            end
+          end
+
+          def detect_affordance(action:, domain:, affordance_type:, requires: [], relevance: nil, **)
+            rel = relevance || Helpers::Constants::DEFAULT_RELEVANCE
+            Legion::Logging.debug "[affordance] detect: #{action} type=#{affordance_type}"
+            aff = field.detect_affordance(
+              action: action, domain: domain, affordance_type: affordance_type.to_sym,
+              requires: requires, relevance: rel
+            )
+            if aff
+              { success: true, affordance: aff.to_h }
+            else
+              { success: false, reason: :invalid_or_full }
+            end
+          end
+
+          def evaluate_action(action:, domain:, **)
+            result = field.evaluate_action(action: action, domain: domain)
+            Legion::Logging.debug "[affordance] evaluate: #{action} feasible=#{result[:feasible]}"
+            { success: true, **result }
+          end
+
+          def actionable_affordances(**)
+            items = field.actionable_affordances
+            { success: true, affordances: items, count: items.size }
+          end
+
+          def current_threats(**)
+            items = field.threats
+            { success: true, threats: items, count: items.size }
+          end
+
+          def affordances_in_domain(domain:, **)
+            items = field.affordances_in(domain: domain)
+            { success: true, affordances: items, count: items.size }
+          end
+
+          def update_affordances(**)
+            Legion::Logging.debug '[affordance] tick'
+            field.decay_all
+            { success: true, remaining: field.affordances.size }
+          end
+
+          def affordance_stats(**)
+            Legion::Logging.debug '[affordance] stats'
+            { success: true, stats: field.to_h }
+          end
+
+          private
+
+          def field
+            @field ||= Helpers::AffordanceField.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/affordance.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/affordance/version'
+require 'legion/extensions/affordance/helpers/constants'
+require 'legion/extensions/affordance/helpers/affordance_item'
+require 'legion/extensions/affordance/helpers/affordance_field'
+require 'legion/extensions/affordance/runners/affordance'
+require 'legion/extensions/affordance/client'
+
+module Legion
+  module Extensions
+    module Affordance
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: lex-affordance
+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: Gibson's ecological affordance perception for LegionIO — detecting action
+  possibilities in the environment
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/legion/extensions/affordance.rb
+- lib/legion/extensions/affordance/actors/scan.rb
+- lib/legion/extensions/affordance/client.rb
+- lib/legion/extensions/affordance/helpers/affordance_field.rb
+- lib/legion/extensions/affordance/helpers/affordance_item.rb
+- lib/legion/extensions/affordance/helpers/constants.rb
+- lib/legion/extensions/affordance/runners/affordance.rb
+- lib/legion/extensions/affordance/version.rb
+homepage: https://github.com/LegionIO/lex-affordance
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-affordance
+  source_code_uri: https://github.com/LegionIO/lex-affordance
+  documentation_uri: https://github.com/LegionIO/lex-affordance/blob/master/README.md
+  changelog_uri: https://github.com/LegionIO/lex-affordance/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-affordance/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: LegionIO affordance perception extension
+test_files: []