lex-cognitive-weather 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 893b7ba8190aef887d3f947faef5ebe04762243ea85726e15457bc38836e6cfb
+  data.tar.gz: 846c2cc18aa47669c40ae0b58b7d7a1c7e43628d15591f96e2f663488ebf1bf7
+SHA512:
+  metadata.gz: 38e14187ed93e249dc32507203e46d25d6c44105d4a28e3534cd0d4434ef5218692d12a17d81f243dd6148403bf45e8bb3114557dd3a279d65bfc1e93a62dcd0
+  data.tar.gz: ef942645b2188f675dbcd486db4a374980116cd1b38a93ff82a2485f8483daecfa138fcf790cefeb7d413818c29117626cea0076258ac9ae1fc839c0b6b30dbb

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+# lex-cognitive-weather
+
+A LegionIO cognitive architecture extension that models internal cognitive conditions as atmospheric weather patterns. Fronts represent cognitive pressure systems across domains, and storms model active episodes of confusion, conflict, or sudden insight.
+
+## What It Does
+
+Tracks **fronts** (atmospheric pressure systems) and **storms** (active weather episodes) in cognitive domains.
+
+Each front has:
+- A type (`:warm`, `:cold`, `:occluded`, `:stationary`)
+- Pressure, temperature, and humidity values
+- A severity label based on pressure
+
+Each storm has:
+- A condition type (`:clear`, `:cloudy`, `:foggy`, `:stormy`, `:lightning`, `:blizzard`)
+- Intensity and coverage values
+- An insight log populated by `lightning_strike!` events
+- A clarity label inverse to intensity
+
+Fronts can be intensified or retreated. Storms can be intensified or dissipated. The engine surfaces current conditions via a weather forecast and a full atmospheric report.
+
+## Usage
+
+```ruby
+require 'lex-cognitive-weather'
+
+client = Legion::Extensions::CognitiveWeather::Client.new
+
+# Create an atmospheric front
+result = client.create_front(
+  front_type: :cold,
+  domain: 'reasoning',
+  pressure: 0.6,
+  temperature: 0.4,
+  humidity: 0.5
+)
+# => { success: true, front: { id: "uuid...", front_type: :cold, pressure: 0.6, severity_label: "moderate", ... } }
+
+front_id = result[:front][:id]
+
+# Brew a storm from the front
+storm = client.brew_storm(
+  front_id: front_id,
+  condition: :foggy,
+  intensity: 0.5,
+  coverage: 0.4
+)
+# => { success: true, storm: { id: "uuid...", condition: :foggy, intensity: 0.5, clarity: "hazy", raging: false, ... } }
+
+# Intensify the storm
+client.intensify(storm_id: storm[:storm][:id])
+# => { success: true, storm: { intensity: 0.55, ... } }
+
+# Get current forecast
+client.forecast
+# => { success: true, condition: :foggy, avg_intensity: 0.55, active_storms: 1, clarity_label: "hazy", ... }
+
+# List all fronts
+client.list_fronts
+# => { success: true, fronts: [...], count: 1 }
+
+# Full atmospheric report
+client.weather_status
+# => { success: true, front_count: 1, storm_count: 1, fronts: [...], storms: [...], forecast: {...}, ... }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-weather.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_weather/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-weather'
+  spec.version       = Legion::Extensions::CognitiveWeather::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX CognitiveWeather'
+  spec.description   = 'Internal cognitive weather systems for brain-modeled agentic AI — ' \
+                       'atmospheric fronts, storms of confusion, fog of uncertainty, and lightning strikes of insight'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-weather'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']      = spec.homepage
+  spec.metadata['source_code_uri']   = 'https://github.com/LegionIO/lex-cognitive-weather'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-weather'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-weather'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-weather/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-cognitive-weather.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_weather/helpers/constants'
+require 'legion/extensions/cognitive_weather/helpers/front'
+require 'legion/extensions/cognitive_weather/helpers/storm'
+require 'legion/extensions/cognitive_weather/helpers/weather_engine'
+require 'legion/extensions/cognitive_weather/runners/cognitive_weather'
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      class Client
+        include Runners::CognitiveWeather
+
+        def initialize(**)
+          @weather_engine = Helpers::WeatherEngine.new
+        end
+
+        private
+
+        attr_reader :weather_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      module Helpers
+        module Constants
+          FRONT_TYPES      = %i[warm cold occluded stationary].freeze
+          CONDITION_TYPES  = %i[clear cloudy foggy stormy lightning blizzard].freeze
+
+          MAX_FRONTS = 100
+          MAX_STORMS = 50
+
+          PRESSURE_CHANGE_RATE = 0.05
+          DISSIPATION_RATE     = 0.03
+
+          # Range-based severity label lookup — ordered from highest to lowest
+          SEVERITY_LABELS = [
+            { range: (0.9..1.0),   label: 'catastrophic' },
+            { range: (0.75..0.9),  label: 'severe' },
+            { range: (0.55..0.75), label: 'moderate' },
+            { range: (0.35..0.55), label: 'mild' },
+            { range: (0.15..0.35), label: 'light' },
+            { range: (0.0..0.15),  label: 'calm' }
+          ].freeze
+
+          # Range-based clarity label lookup — ordered from highest to lowest
+          CLARITY_LABELS = [
+            { range: (0.85..1.0),   label: 'crystal' },
+            { range: (0.65..0.85),  label: 'clear' },
+            { range: (0.45..0.65),  label: 'hazy' },
+            { range: (0.25..0.45),  label: 'murky' },
+            { range: (0.0..0.25),   label: 'opaque' }
+          ].freeze
+
+          def self.label_for(table, value)
+            clamped = value.clamp(0.0, 1.0)
+            entry = table.find { |e| e[:range].cover?(clamped) }
+            entry ? entry[:label] : table.last[:label]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_weather/helpers/front.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      module Helpers
+        class Front
+          attr_reader :id, :front_type, :domain, :created_at
+          attr_accessor :pressure, :temperature, :humidity
+
+          def initialize(front_type:, domain:, pressure: 0.5, temperature: 0.5, humidity: 0.5)
+            raise ArgumentError, "unknown front_type: #{front_type}" unless Constants::FRONT_TYPES.include?(front_type.to_sym)
+
+            @id          = SecureRandom.uuid
+            @front_type  = front_type.to_sym
+            @domain      = domain.to_s
+            @pressure    = pressure.clamp(0.0, 1.0)
+            @temperature = temperature.clamp(0.0, 1.0)
+            @humidity    = humidity.clamp(0.0, 1.0)
+            @created_at  = Time.now.utc
+          end
+
+          # Advance: pressure rises, front strengthens
+          def advance!(rate = Constants::PRESSURE_CHANGE_RATE)
+            @pressure = (@pressure + rate.clamp(0.0, 1.0)).clamp(0.0, 1.0)
+          end
+
+          # Retreat: pressure falls, front weakens
+          def retreat!(rate = Constants::PRESSURE_CHANGE_RATE)
+            @pressure = (@pressure - rate.clamp(0.0, 1.0)).clamp(0.0, 1.0)
+          end
+
+          def high_pressure?
+            @pressure >= 0.65
+          end
+
+          def low_pressure?
+            @pressure <= 0.35
+          end
+
+          def severity_label
+            Constants.label_for(Constants::SEVERITY_LABELS, @pressure)
+          end
+
+          def to_h
+            {
+              id:            @id,
+              front_type:    @front_type,
+              domain:        @domain,
+              pressure:      @pressure.round(10),
+              temperature:   @temperature.round(10),
+              humidity:      @humidity.round(10),
+              high_pressure: high_pressure?,
+              low_pressure:  low_pressure?,
+              severity:      severity_label,
+              created_at:    @created_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_weather/helpers/storm.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      module Helpers
+        class Storm
+          attr_reader :id, :condition, :front_ids, :created_at, :insight_log
+          attr_accessor :intensity, :coverage
+
+          def initialize(condition:, front_ids: [], intensity: 0.5, coverage: 0.5)
+            raise ArgumentError, "unknown condition: #{condition}" unless Constants::CONDITION_TYPES.include?(condition.to_sym)
+
+            @id          = SecureRandom.uuid
+            @condition   = condition.to_sym
+            @front_ids   = Array(front_ids).dup
+            @intensity   = intensity.clamp(0.0, 1.0)
+            @coverage    = coverage.clamp(0.0, 1.0)
+            @created_at  = Time.now.utc
+            @insight_log = []
+          end
+
+          # Intensify: storm grows stronger
+          def intensify!(rate = Constants::PRESSURE_CHANGE_RATE)
+            @intensity = (@intensity + rate.clamp(0.0, 1.0)).clamp(0.0, 1.0)
+            @coverage  = (@coverage  + (rate * 0.5).clamp(0.0, 1.0)).clamp(0.0, 1.0)
+          end
+
+          # Dissipate: storm weakens and clears
+          def dissipate!(rate = Constants::DISSIPATION_RATE)
+            @intensity = (@intensity - rate.clamp(0.0, 1.0)).clamp(0.0, 1.0)
+            @coverage  = (@coverage  - (rate * 0.5).clamp(0.0, 1.0)).clamp(0.0, 1.0)
+          end
+
+          # A lightning strike of sudden insight — random intensity, logged for audit
+          def lightning_strike!(domain: nil)
+            insight_id = SecureRandom.uuid
+            insight_intensity = rand.round(10)
+            entry = {
+              id:        insight_id,
+              domain:    domain,
+              intensity: insight_intensity,
+              struck_at: Time.now.utc.iso8601
+            }
+            @insight_log << entry
+            entry
+          end
+
+          def raging?
+            @intensity >= 0.75
+          end
+
+          def clearing?
+            @intensity <= 0.25
+          end
+
+          def clarity_label
+            # Clarity is inverse of intensity: high intensity = low clarity
+            Constants.label_for(Constants::CLARITY_LABELS, 1.0 - @intensity)
+          end
+
+          def to_h
+            {
+              id:            @id,
+              condition:     @condition,
+              front_ids:     @front_ids,
+              intensity:     @intensity.round(10),
+              coverage:      @coverage.round(10),
+              raging:        raging?,
+              clearing:      clearing?,
+              clarity:       clarity_label,
+              insight_count: @insight_log.size,
+              created_at:    @created_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_weather/helpers/weather_engine.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      module Helpers
+        class WeatherEngine
+          attr_reader :fronts, :storms
+
+          def initialize
+            @fronts = []
+            @storms = []
+          end
+
+          # Create a new atmospheric front; respects MAX_FRONTS
+          def create_front(front_type:, domain:, pressure: 0.5, temperature: 0.5, humidity: 0.5)
+            return nil if @fronts.size >= Constants::MAX_FRONTS
+
+            front = Front.new(
+              front_type:  front_type,
+              domain:      domain,
+              pressure:    pressure,
+              temperature: temperature,
+              humidity:    humidity
+            )
+            @fronts << front
+            front
+          end
+
+          # Brew a storm anchored to a front; respects MAX_STORMS
+          def brew_storm(front_id:, condition: :stormy, intensity: 0.5, coverage: 0.5)
+            return nil if @storms.size >= Constants::MAX_STORMS
+            return nil unless find_front(front_id)
+
+            storm = Storm.new(
+              condition: condition,
+              front_ids: [front_id],
+              intensity: intensity,
+              coverage:  coverage
+            )
+            @storms << storm
+            storm
+          end
+
+          # Intensify a storm by id
+          def intensify_storm(storm_id:, rate: Constants::PRESSURE_CHANGE_RATE)
+            storm = find_storm(storm_id)
+            return nil unless storm
+
+            storm.intensify!(rate)
+            storm
+          end
+
+          # Dissipate all storms by one cycle
+          def dissipate_all!(rate = Constants::DISSIPATION_RATE)
+            @storms.each { |s| s.dissipate!(rate) }
+            @storms.size
+          end
+
+          # Current conditions summary: dominant condition, average intensity, active storm count
+          def weather_forecast
+            if @storms.empty?
+              return {
+                condition:      :clear,
+                avg_intensity:  0.0,
+                active_storms:  0,
+                dominant_front: nil,
+                clarity_label:  'crystal',
+                severity_label: 'calm'
+              }
+            end
+
+            avg_intensity  = @storms.sum(&:intensity) / @storms.size.to_f
+            dominant_storm = @storms.max_by(&:intensity)
+            dominant_front = most_severe
+
+            {
+              condition:      dominant_storm.condition,
+              avg_intensity:  avg_intensity.round(10),
+              active_storms:  @storms.size,
+              dominant_front: dominant_front&.to_h,
+              clarity_label:  dominant_storm.clarity_label,
+              severity_label: dominant_front ? dominant_front.severity_label : 'calm'
+            }
+          end
+
+          # Front with highest pressure
+          def most_severe
+            return nil if @fronts.empty?
+
+            @fronts.max_by(&:pressure)
+          end
+
+          # Front with lowest pressure
+          def calmest
+            return nil if @fronts.empty?
+
+            @fronts.min_by(&:pressure)
+          end
+
+          # Full atmospheric report
+          def atmospheric_report
+            {
+              front_count: @fronts.size,
+              storm_count: @storms.size,
+              fronts:      @fronts.map(&:to_h),
+              storms:      @storms.map(&:to_h),
+              forecast:    weather_forecast,
+              most_severe: most_severe&.to_h,
+              calmest:     calmest&.to_h
+            }
+          end
+
+          private
+
+          def find_front(front_id)
+            @fronts.find { |f| f.id == front_id.to_s }
+          end
+
+          def find_storm(storm_id)
+            @storms.find { |s| s.id == storm_id.to_s }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      module Runners
+        module CognitiveWeather
+          extend self
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_front(front_type: :warm, domain: 'default', pressure: 0.5,
+                           temperature: 0.5, humidity: 0.5, engine: nil, **)
+            eng   = engine || weather_engine
+            front = eng.create_front(
+              front_type:  front_type.to_sym,
+              domain:      domain,
+              pressure:    pressure.to_f,
+              temperature: temperature.to_f,
+              humidity:    humidity.to_f
+            )
+            if front
+              Legion::Logging.debug "[cognitive_weather] front created: type=#{front_type} " \
+                                    "domain=#{domain} pressure=#{pressure}"
+              { success: true, front: front.to_h }
+            else
+              Legion::Logging.warn '[cognitive_weather] create_front: MAX_FRONTS reached'
+              { success: false, reason: :max_fronts_reached }
+            end
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_weather] create_front failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def brew_storm(front_id:, condition: :stormy, intensity: 0.5, coverage: 0.5, engine: nil, **)
+            eng   = engine || weather_engine
+            storm = eng.brew_storm(
+              front_id:  front_id.to_s,
+              condition: condition.to_sym,
+              intensity: intensity.to_f,
+              coverage:  coverage.to_f
+            )
+            if storm
+              Legion::Logging.debug "[cognitive_weather] storm brewed: condition=#{condition} " \
+                                    "intensity=#{intensity} front=#{front_id}"
+              { success: true, storm: storm.to_h }
+            else
+              Legion::Logging.warn '[cognitive_weather] brew_storm: front not found or MAX_STORMS reached'
+              { success: false, reason: :brew_failed }
+            end
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_weather] brew_storm failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def intensify(storm_id:, rate: Helpers::Constants::PRESSURE_CHANGE_RATE, engine: nil, **)
+            eng   = engine || weather_engine
+            storm = eng.intensify_storm(storm_id: storm_id.to_s, rate: rate.to_f)
+            if storm
+              Legion::Logging.debug "[cognitive_weather] storm intensified: id=#{storm_id} " \
+                                    "intensity=#{storm.intensity.round(3)} raging=#{storm.raging?}"
+              { success: true, storm: storm.to_h }
+            else
+              Legion::Logging.warn "[cognitive_weather] intensify: storm #{storm_id} not found"
+              { success: false, reason: :storm_not_found }
+            end
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_weather] intensify failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def forecast(engine: nil, **)
+            eng      = engine || weather_engine
+            forecast = eng.weather_forecast
+            Legion::Logging.debug "[cognitive_weather] forecast: condition=#{forecast[:condition]} " \
+                                  "avg_intensity=#{forecast[:avg_intensity]&.round(3)} " \
+                                  "storms=#{forecast[:active_storms]}"
+            forecast.merge(success: true)
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_weather] forecast failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def list_fronts(engine: nil, **)
+            eng = engine || weather_engine
+            fronts = eng.fronts.map(&:to_h)
+            Legion::Logging.debug "[cognitive_weather] list_fronts: count=#{fronts.size}"
+            { success: true, fronts: fronts, count: fronts.size }
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_weather] list_fronts failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          def weather_status(engine: nil, **)
+            eng    = engine || weather_engine
+            report = eng.atmospheric_report
+            Legion::Logging.debug "[cognitive_weather] weather_status: fronts=#{report[:front_count]} " \
+                                  "storms=#{report[:storm_count]}"
+            report.merge(success: true)
+          rescue ArgumentError => e
+            Legion::Logging.error "[cognitive_weather] weather_status failed: #{e.message}"
+            { success: false, error: e.message }
+          end
+
+          private
+
+          def weather_engine
+            @weather_engine ||= Helpers::WeatherEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_weather.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/cognitive_weather/version'
+require 'legion/extensions/cognitive_weather/helpers/constants'
+require 'legion/extensions/cognitive_weather/helpers/front'
+require 'legion/extensions/cognitive_weather/helpers/storm'
+require 'legion/extensions/cognitive_weather/helpers/weather_engine'
+require 'legion/extensions/cognitive_weather/runners/cognitive_weather'
+require 'legion/extensions/cognitive_weather/client'
+
+module Legion
+  module Extensions
+    module CognitiveWeather
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end