lex-agentic-attention 0.1.0

data/lib/legion/extensions/agentic/attention/telescope/helpers/constants.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+          module Helpers
+            module Constants
+              # Available lens types for cognitive telescopes
+              LENS_TYPES = %i[refractor reflector catadioptric radio adaptive].freeze
+
+              # Observation modes
+              OBSERVATION_MODES = %i[survey focused tracking spectral].freeze
+
+              # Maximum telescopes in the observatory
+              MAX_TELESCOPES = 100
+
+              # Maximum recorded observations
+              MAX_OBSERVATIONS = 500
+
+              # Base and max magnification bounds
+              BASE_MAGNIFICATION = 1.0
+              MAX_MAGNIFICATION  = 100.0
+
+              # Field of view base in radians (wide-open single radian)
+              FIELD_OF_VIEW_BASE = 1.0
+
+              # Atmospheric distortion coefficient (reduces clarity at low magnification)
+              ATMOSPHERIC_DISTORTION = 0.1
+
+              # Clarity labels (range-based, descending)
+              CLARITY_LABELS = [
+                [(0.85..),      :crystal],
+                [(0.65...0.85), :clear],
+                [(0.45...0.65), :hazy],
+                [(0.25...0.45), :blurry],
+                [(..0.25),      :blind]
+              ].freeze
+
+              # Distance labels (range-based, descending)
+              DISTANCE_LABELS = [
+                [(0.85..),      :cosmic],
+                [(0.65...0.85), :deep],
+                [(0.4...0.65),  :medium],
+                [(0.2...0.4),   :near],
+                [(..0.2),       :myopic]
+              ].freeze
+
+              def self.label_for(table, value)
+                table.each { |range, label| return label if range.cover?(value) }
+                table.last.last
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/telescope/helpers/observation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+          module Helpers
+            class Observation
+              attr_reader :id, :telescope_id, :target, :distance,
+                          :detail_level, :recorded_at
+
+              def initialize(telescope_id:, target:, distance:, telescope_magnification: 1.0)
+                @id                   = SecureRandom.uuid
+                @telescope_id         = telescope_id
+                @target               = target.to_s
+                @distance             = distance.to_f.clamp(0.0, 1.0).round(10)
+                @detail_level         = compute_detail(telescope_magnification)
+                @recorded_at          = Time.now.utc
+              end
+
+              # True when detail is strong enough to be actionable
+              def significant?
+                @detail_level >= 0.7
+              end
+
+              # True when detail is too faint to interpret
+              def faint?
+                @detail_level < 0.3
+              end
+
+              def distance_label
+                Helpers::Constants.label_for(Constants::DISTANCE_LABELS, @distance)
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  telescope_id:   @telescope_id,
+                  target:         @target,
+                  distance:       @distance,
+                  distance_label: distance_label,
+                  detail_level:   @detail_level,
+                  significant:    significant?,
+                  faint:          faint?,
+                  recorded_at:    @recorded_at
+                }
+              end
+
+              private
+
+              # Higher magnification + closer distance = richer detail
+              # Normalise magnification to 0..1 range relative to MAX_MAGNIFICATION
+              def compute_detail(magnification)
+                mag_factor = magnification.to_f.clamp(
+                  Constants::BASE_MAGNIFICATION, Constants::MAX_MAGNIFICATION
+                ) / Constants::MAX_MAGNIFICATION
+                proximity   = 1.0 - @distance
+                raw         = (mag_factor * proximity).clamp(0.0, 1.0)
+                raw.round(10)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/telescope/helpers/observatory_engine.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+          module Helpers
+            class ObservatoryEngine
+              def initialize
+                @telescopes   = {}
+                @observations = []
+              end
+
+              # Create and register a new telescope
+              def create_telescope(lens_type:, aperture: 0.5, magnification: 1.0, tracking: false)
+                raise ArgumentError, 'observatory full' if @telescopes.size >= Constants::MAX_TELESCOPES
+
+                scope = Telescope.new(
+                  lens_type:     lens_type,
+                  aperture:      aperture,
+                  magnification: magnification,
+                  tracking:      tracking
+                )
+                @telescopes[scope.id] = scope
+                scope
+              end
+
+              # Zoom in on a telescope by multiplying magnification
+              def zoom_in(telescope_id:, factor:)
+                fetch_telescope(telescope_id).zoom_in!(factor)
+              end
+
+              # Zoom out on a telescope by dividing magnification
+              def zoom_out(telescope_id:, factor:)
+                fetch_telescope(telescope_id).zoom_out!(factor)
+              end
+
+              # Focus a telescope at a given target distance
+              def focus_telescope(telescope_id:, target_distance:)
+                fetch_telescope(telescope_id).focus!(target_distance)
+              end
+
+              # Record an observation for a target at a given distance
+              def observe(telescope_id:, target:, distance:)
+                raise ArgumentError, 'observation log full' if @observations.size >= Constants::MAX_OBSERVATIONS
+
+                scope = fetch_telescope(telescope_id)
+                obs   = Observation.new(
+                  telescope_id:            scope.id,
+                  target:                  target,
+                  distance:                distance,
+                  telescope_magnification: scope.magnification
+                )
+                @observations << obs
+                obs
+              end
+
+              # Survey mode: zoom out to BASE_MAGNIFICATION (wide-field scan)
+              def survey_mode!(telescope_id:)
+                scope = fetch_telescope(telescope_id)
+                scope.zoom_out!(scope.magnification)
+                scope
+              end
+
+              # Deep-focus mode: zoom in to MAX_MAGNIFICATION
+              def deep_focus!(telescope_id:)
+                scope = fetch_telescope(telescope_id)
+                scope.zoom_in!(Constants::MAX_MAGNIFICATION)
+                scope
+              end
+
+              def all_telescopes
+                @telescopes.values
+              end
+
+              def all_observations
+                @observations.dup
+              end
+
+              def significant_observations
+                @observations.select(&:significant?)
+              end
+
+              # Summary report for the observatory
+              def observatory_report
+                {
+                  total_telescopes:    @telescopes.size,
+                  total_observations:  @observations.size,
+                  significant_count:   significant_observations.size,
+                  faint_count:         @observations.count(&:faint?),
+                  avg_detail:          avg_detail,
+                  deepest_observation: deepest_observation,
+                  widest_telescope:    widest_telescope
+                }
+              end
+
+              private
+
+              def fetch_telescope(id)
+                @telescopes.fetch(id) do
+                  raise ArgumentError, "telescope not found: #{id}"
+                end
+              end
+
+              def avg_detail
+                total = @observations.size
+                return 0.0 if total.zero?
+
+                (@observations.sum(&:detail_level) / total).round(10)
+              end
+
+              def deepest_observation
+                @observations.max_by(&:distance)&.to_h
+              end
+
+              def widest_telescope
+                @telescopes.values.min_by(&:magnification)&.to_h
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/telescope/helpers/telescope.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+          module Helpers
+            class Telescope
+              attr_reader :id, :lens_type, :aperture, :magnification,
+                          :tracking, :focal_distance, :created_at
+
+              def initialize(lens_type:, aperture: 0.5, magnification: 1.0, tracking: false)
+                validate_lens_type!(lens_type)
+                @id            = SecureRandom.uuid
+                @lens_type     = lens_type.to_sym
+                @aperture      = aperture.to_f.clamp(0.1, 1.0).round(10)
+                @magnification = magnification.to_f.clamp(
+                  Constants::BASE_MAGNIFICATION, Constants::MAX_MAGNIFICATION
+                ).round(10)
+                @tracking = tracking
+                @focal_distance = nil
+                @created_at = Time.now.utc
+              end
+
+              # Increase magnification by factor; field of view narrows inversely
+              def zoom_in!(factor)
+                factor = factor.to_f.clamp(1.0, Constants::MAX_MAGNIFICATION)
+                @magnification = (@magnification * factor).clamp(
+                  Constants::BASE_MAGNIFICATION, Constants::MAX_MAGNIFICATION
+                ).round(10)
+                self
+              end
+
+              # Decrease magnification by factor; field of view widens
+              def zoom_out!(factor)
+                factor = [factor.to_f, 1.0].max
+                @magnification = (@magnification / factor).clamp(
+                  Constants::BASE_MAGNIFICATION, Constants::MAX_MAGNIFICATION
+                ).round(10)
+                self
+              end
+
+              # Calculated field of view: wider aperture + lower magnification = wider field
+              def field_of_view
+                (Constants::FIELD_OF_VIEW_BASE / @magnification * @aperture).round(10)
+              end
+
+              # Clarity based on aperture and atmospheric distortion modulated by magnification
+              def clarity
+                distortion_factor = 1.0 - (Constants::ATMOSPHERIC_DISTORTION / @magnification.clamp(1.0, 10.0))
+                (@aperture * distortion_factor).clamp(0.0, 1.0).round(10)
+              end
+
+              # Focus on a target distance; focal alignment adjusts effective clarity
+              def focus!(target_distance)
+                @focal_distance = target_distance.to_f.clamp(0.0, 1.0).round(10)
+                self
+              end
+
+              def enable_tracking!
+                @tracking = true
+                self
+              end
+
+              def disable_tracking!
+                @tracking = false
+                self
+              end
+
+              # True when magnification >= 50 (deep-sky mode)
+              def deep_field?
+                @magnification >= 50.0
+              end
+
+              # True when magnification <= 5 (wide-field survey mode)
+              def wide_field?
+                @magnification <= 5.0
+              end
+
+              # True when clarity is at or above 0.8
+              def sharp?
+                clarity >= 0.8
+              end
+
+              # True when clarity falls below 0.3
+              def blurry?
+                clarity < 0.3
+              end
+
+              def clarity_label
+                Helpers::Constants.label_for(Constants::CLARITY_LABELS, clarity)
+              end
+
+              def to_h
+                {
+                  id:             @id,
+                  lens_type:      @lens_type,
+                  aperture:       @aperture,
+                  magnification:  @magnification,
+                  tracking:       @tracking,
+                  focal_distance: @focal_distance,
+                  field_of_view:  field_of_view,
+                  clarity:        clarity,
+                  clarity_label:  clarity_label,
+                  deep_field:     deep_field?,
+                  wide_field:     wide_field?,
+                  sharp:          sharp?,
+                  blurry:         blurry?,
+                  created_at:     @created_at
+                }
+              end
+
+              private
+
+              def validate_lens_type!(val)
+                return if Constants::LENS_TYPES.include?(val.to_sym)
+
+                raise ArgumentError,
+                      "unknown lens type: #{val.inspect}; " \
+                      "must be one of #{Constants::LENS_TYPES.inspect}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/telescope/runners/cognitive_telescope.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+          module Runners
+            module CognitiveTelescope
+              extend self
+
+              include Legion::Extensions::Helpers::Lex if defined?(Legion::Extensions::Helpers::Lex)
+
+              def create_telescope(lens_type:, aperture: 0.5, magnification: 1.0,
+                                   tracking: false, engine: nil, **)
+                eng   = resolve_engine(engine)
+                scope = eng.create_telescope(
+                  lens_type:     lens_type,
+                  aperture:      aperture,
+                  magnification: magnification,
+                  tracking:      tracking
+                )
+                { success: true, telescope: scope.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def zoom_in(telescope_id:, factor: 2.0, engine: nil, **)
+                eng   = resolve_engine(engine)
+                scope = eng.zoom_in(telescope_id: telescope_id, factor: factor)
+                { success: true, telescope: scope.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def zoom_out(telescope_id:, factor: 2.0, engine: nil, **)
+                eng   = resolve_engine(engine)
+                scope = eng.zoom_out(telescope_id: telescope_id, factor: factor)
+                { success: true, telescope: scope.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def observe(telescope_id:, target:, distance: 0.5, engine: nil, **)
+                eng = resolve_engine(engine)
+                obs = eng.observe(telescope_id: telescope_id, target: target, distance: distance)
+                { success: true, observation: obs.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def focus(telescope_id:, target_distance:, engine: nil, **)
+                eng   = resolve_engine(engine)
+                scope = eng.focus_telescope(telescope_id:    telescope_id,
+                                            target_distance: target_distance)
+                { success: true, telescope: scope.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def survey_mode(telescope_id:, engine: nil, **)
+                eng   = resolve_engine(engine)
+                scope = eng.survey_mode!(telescope_id: telescope_id)
+                { success: true, telescope: scope.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def deep_focus(telescope_id:, engine: nil, **)
+                eng   = resolve_engine(engine)
+                scope = eng.deep_focus!(telescope_id: telescope_id)
+                { success: true, telescope: scope.to_h }
+              rescue ArgumentError => e
+                { success: false, error: e.message }
+              end
+
+              def list_observations(engine: nil, significant_only: false, **)
+                eng  = resolve_engine(engine)
+                list = significant_only ? eng.significant_observations : eng.all_observations
+                { success: true, observations: list.map(&:to_h), count: list.size }
+              end
+
+              def observatory_status(engine: nil, **)
+                eng = resolve_engine(engine)
+                { success: true, report: eng.observatory_report }
+              end
+
+              private
+
+              def resolve_engine(engine)
+                engine || default_engine
+              end
+
+              def default_engine
+                @default_engine ||= Helpers::ObservatoryEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/telescope/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/telescope.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+require_relative 'telescope/version'
+require_relative 'telescope/helpers/constants'
+require_relative 'telescope/helpers/telescope'
+require_relative 'telescope/helpers/observation'
+require_relative 'telescope/helpers/observatory_engine'
+require_relative 'telescope/runners/cognitive_telescope'
+require_relative 'telescope/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        module Telescope
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        VERSION = '0.1.0'
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/attention.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'attention/version'
+require_relative 'attention/focus'
+require_relative 'attention/economy'
+require_relative 'attention/regulation'
+require_relative 'attention/schema'
+require_relative 'attention/spotlight'
+require_relative 'attention/switching'
+require_relative 'attention/blink'
+require_relative 'attention/telescope'
+require_relative 'attention/lens'
+require_relative 'attention/prism'
+require_relative 'attention/lighthouse'
+require_relative 'attention/blindspot'
+require_relative 'attention/kaleidoscope'
+require_relative 'attention/synesthesia'
+require_relative 'attention/arousal'
+require_relative 'attention/salience'
+require_relative 'attention/sensory_gating'
+require_relative 'attention/signal_detection'
+require_relative 'attention/subliminal'
+require_relative 'attention/latent_inhibition'
+require_relative 'attention/surprise'
+require_relative 'attention/relevance_theory'
+require_relative 'attention/priming'
+require_relative 'attention/feature_binding'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Attention
+        extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+
+        def remote_invocable?
+          false
+        end
+      end
+    end
+  end
+end

data/spec/legion/extensions/agentic/attention/arousal/client_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/attention/arousal/client'
+
+RSpec.describe Legion::Extensions::Agentic::Attention::Arousal::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    expect(client).to respond_to(:stimulate)
+    expect(client).to respond_to(:calm)
+    expect(client).to respond_to(:update_arousal)
+    expect(client).to respond_to(:check_performance)
+    expect(client).to respond_to(:arousal_status)
+    expect(client).to respond_to(:arousal_guidance)
+  end
+
+  it 'runs a full arousal cycle' do
+    client.stimulate(amount: 0.3, source: :external)
+    status = client.arousal_status
+    expect(status[:arousal]).to be > Legion::Extensions::Agentic::Attention::Arousal::Helpers::Constants::DEFAULT_AROUSAL
+    expect(status[:label]).to be_a(Symbol)
+
+    client.calm(amount: 0.1)
+    calmed = client.arousal_status
+    expect(calmed[:arousal]).to be_a(Float)
+
+    guidance = client.arousal_guidance(task_complexity: :moderate)
+    expect(guidance[:guidance]).to be_a(Symbol)
+  end
+
+  it 'persists state across calls' do
+    client.stimulate(amount: 0.5, source: :test)
+    client.stimulate(amount: 0.2, source: :test)
+    status = client.arousal_status
+    expect(status[:history_size]).to be >= 2
+  end
+
+  it 'returns higher performance near the optimal arousal for a given complexity' do
+    perf_moderate = client.check_performance(task_complexity: :moderate)
+    expect(perf_moderate[:performance]).to be_between(0.0, 1.0)
+  end
+end