lex-cognitive-catalyst 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0831b554c585e8335d544e63f5a141d04c795876c99f9123e5d9117bf65a8cd2'
+  data.tar.gz: bf6d4293e8d91d75a90ca92f01f273d9d651f2970077562416a13079f8da7ddf
+SHA512:
+  metadata.gz: 1de51909f167df0bab5a81c5719e01ec1394b318fdc12bee119e55854a0d204896696d340090a4e0c37e55b8a8f584042cdd2536f1b7380035f7c9c443f7ccd2
+  data.tar.gz: 6f7c198df94bdbffb1a389d3e444d52f5f8d13083a8db4c07890b7d88c36e88c8881a7fb3b5cae7201f99adf87c8abface4558efa9d31c69175cc72ab97606ca

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc/
+coverage/
+doc/
+lib/bundler/man
+pkg/
+rdoc/
+spec/reports/
+test/
+tmp/
+.rspec_status

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--format documentation
+--color
+--order random

data/.rubocop.yml

@@ -0,0 +1,29 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+Style/Documentation:
+  Enabled: false
+Naming/PredicateMethod:
+  Enabled: false
+Naming/PredicatePrefix:
+  Enabled: false
+Metrics/ClassLength:
+  Max: 150
+Metrics/MethodLength:
+  Max: 25
+Metrics/AbcSize:
+  Max: 25
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+Layout/HashAlignment:
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+Style/FrozenStringLiteralComment:
+  Enabled: true
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'

data/CLAUDE.md

@@ -0,0 +1,78 @@
+# lex-cognitive-catalyst
+
+**Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Grandparent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Models how certain thoughts and experiences act as chemical catalysts — accelerating cognitive reactions without being consumed. Catalysts lower the activation energy required for synthesis, decomposition, exchange, neutralization, and precipitation reactions between ideas. A potent catalyst enables reactions that would otherwise stall from insufficient energy input.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-catalyst`
+- **Version**: `0.1.0`
+- **Module**: `Legion::Extensions::CognitiveCatalyst`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_catalyst/
+  cognitive_catalyst.rb
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    catalyst.rb
+    catalyst_engine.rb
+    reaction.rb
+  runners/
+    cognitive_catalyst.rb
+```
+
+## Key Constants
+
+From `helpers/constants.rb`:
+
+- `CATALYST_TYPES` — `%i[experience insight analogy pattern emotion]`
+- `REACTION_TYPES` — `%i[synthesis decomposition exchange neutralization precipitation]`
+- `MAX_CATALYSTS` = `500`, `MAX_REACTIONS` = `200`
+- `ACTIVATION_ENERGY` = `0.6` (minimum energy to complete a reaction without a catalyst)
+- `CATALYST_REDUCTION` = `0.3` (how much a catalyst lowers the activation energy threshold)
+- `POTENCY_DECAY` = `0.02` (environmental wear — not from use)
+- `SPECIFICITY_BONUS` = `0.15` (bonus when catalyst domain matches reaction domain)
+- `POTENCY_LABELS` — `0.8+` = `:powerful`, `0.6` = `:strong`, `0.4` = `:moderate`, `0.2` = `:weak`, below = `:inert`
+- `YIELD_LABELS` — `0.8+` = `:excellent` through below `0.2` = `:negligible`
+
+## Runners
+
+All methods in `Runners::CognitiveCatalyst`:
+
+- `create_catalyst(catalyst_type:, domain:, potency: nil, specificity: nil)` — registers a new catalyst; validates against `CATALYST_TYPES`
+- `create_reaction(reaction_type:, reactants:, activation_energy: nil)` — creates a pending reaction; validates against `REACTION_TYPES`
+- `apply_catalyst(catalyst_id:, reaction_id:)` — associates a catalyst with a reaction, lowering effective activation energy
+- `attempt_reaction(reaction_id:, energy_input:)` — attempts to complete a reaction; succeeds if `energy_input >= effective_threshold`; returns yield score
+- `recharge(catalyst_id:, amount:)` — restores potency to a catalyst
+- `list_catalysts` — all catalysts with current potency
+- `catalyst_status` — aggregate report: totals, catalyzed rate, most potent
+
+## Helpers
+
+- `CatalystEngine` — manages catalysts and reactions. `apply_catalyst` attaches a catalyst to a reaction; `attempt_reaction` evaluates whether energy input meets the (optionally reduced) threshold.
+- `Catalyst` — has `catalyst_type`, `domain`, `potency`, `specificity`. `potency` decays over time (environmental wear). Not consumed on use.
+- `Reaction` — has `reaction_type`, `reactants`, `activation_energy`. Stores applied catalyst IDs. Effective threshold = `activation_energy - (CATALYST_REDUCTION * catalyst_potency) + SPECIFICITY_BONUS` if domains match.
+
+## Integration Points
+
+- `lex-cognitive-coherence` can provide the constraint network that reactions operate within — catalysts accelerate coherence maximization by lowering the cost of belief integration.
+- `lex-memory` trace retrieval during `lex-dream` is a natural catalyst source: high-strength traces become experience catalysts for synthesis reactions during dream phases.
+- `recharge` enables explicit catalyst maintenance — callers can recharge important catalysts (e.g., a core analogy) to keep them potent.
+
+## Development Notes
+
+- Catalyst potency decays from environmental wear (not from use) — catalysts are not consumed. `POTENCY_DECAY = 0.02` per decay cycle.
+- `SPECIFICITY_BONUS` is added when catalyst domain matches reaction domain — rewarding domain-specific knowledge application.
+- Invalid `catalyst_type` or `reaction_type` raises `ArgumentError` (from constants validation in the runner).
+- Runners log all operations via `Legion::Logging.debug`/`warn`.

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75'
+gem 'rubocop-rspec'
+
+gem 'legion-gaia', path: '../../legion-gaia'

data/README.md

@@ -0,0 +1,44 @@
+# lex-cognitive-catalyst
+
+Cognitive catalysis acceleration for LegionIO. Models how certain thoughts and experiences act as chemical catalysts — accelerating cognitive reactions without being consumed.
+
+## What It Does
+
+Catalysts lower the activation energy required for cognitive reactions. An insight, analogy, or recurring pattern can make otherwise-stalled synthesis reactions complete with much less energy. Unlike consumed reagents, catalysts remain available for repeated use (though their potency decays from environmental wear).
+
+Five reaction types are supported: synthesis (combining ideas), decomposition (breaking down assumptions), exchange (swapping belief components), neutralization (resolving opposing forces), and precipitation (crystallizing vague concepts into concrete ones). Applying the right catalyst — especially one with matching domain specificity — dramatically increases reaction yield.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::CognitiveCatalyst::Client.new
+
+catalyst = client.create_catalyst(
+  catalyst_type: :analogy,
+  domain: :problem_solving,
+  potency: 0.9,
+  specificity: 0.8
+)
+
+reaction = client.create_reaction(
+  reaction_type: :synthesis,
+  reactants: ['concept_a', 'concept_b'],
+  activation_energy: 0.7
+)
+
+client.apply_catalyst(catalyst_id: catalyst[:catalyst][:id],
+                      reaction_id: reaction[:reaction][:id])
+client.attempt_reaction(reaction_id: reaction[:reaction][:id], energy_input: 0.5)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-catalyst.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_catalyst/version'
+
+Gem::Specification.new do |spec|
+  spec.name    = 'lex-cognitive-catalyst'
+  spec.version = Legion::Extensions::CognitiveCatalyst::VERSION
+  spec.authors = ['Esity']
+  spec.email   = ['matthewdiverson@gmail.com']
+
+  spec.summary     = 'Cognitive catalysis acceleration for LegionIO agentic architecture'
+  spec.description = 'Models how certain thoughts and experiences act as chemical catalysts — ' \
+                     'accelerating cognitive reactions without being consumed. Catalysts lower ' \
+                     'the activation energy for synthesis, decomposition, exchange, neutralization, ' \
+                     'and precipitation reactions between ideas.'
+  spec.homepage    = 'https://github.com/LegionIO/lex-cognitive-catalyst'
+  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-catalyst'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-cognitive-catalyst'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-cognitive-catalyst'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-cognitive-catalyst/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) { `git ls-files -z`.split("\x0") }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      class Client
+        include Runners::CognitiveCatalyst
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_catalyst/helpers/catalyst.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      module Helpers
+        class Catalyst
+          include Constants
+
+          attr_reader :id, :catalyst_type, :domain, :potency, :specificity,
+                      :uses_count, :created_at
+
+          def initialize(catalyst_type:, domain:, potency: 0.5, specificity: 0.5)
+            @id            = SecureRandom.uuid
+            @catalyst_type = catalyst_type
+            @domain        = domain
+            @potency       = potency.clamp(0.0, 1.0)
+            @specificity   = specificity.clamp(0.0, 1.0)
+            @uses_count    = 0
+            @created_at    = Time.now.utc
+          end
+
+          # Apply this catalyst to a reaction — increments uses_count but does NOT reduce potency
+          # Catalysts are not consumed by use; they are reusable accelerators
+          # Returns activation_reduction = potency * specificity
+          def catalyze!(_reaction_type)
+            @uses_count += 1
+            (@potency * @specificity).round(10)
+          end
+
+          # Degrade from environmental wear (not from use)
+          def degrade!
+            @potency = (@potency - POTENCY_DECAY).clamp(0.0, 1.0).round(10)
+          end
+
+          # Recharge by increasing potency
+          def recharge!(amount)
+            @potency = (@potency + amount).clamp(0.0, 1.0).round(10)
+          end
+
+          def powerful?
+            @potency >= 0.8
+          end
+
+          def inert?
+            @potency < 0.2
+          end
+
+          def specific?
+            @specificity >= 0.7
+          end
+
+          def broad?
+            @specificity < 0.3
+          end
+
+          def potency_label
+            POTENCY_LABELS.find { |range, _| range.cover?(@potency) }&.last || :inert
+          end
+
+          def to_h
+            {
+              id:            @id,
+              catalyst_type: @catalyst_type,
+              domain:        @domain,
+              potency:       @potency,
+              specificity:   @specificity,
+              uses_count:    @uses_count,
+              potency_label: potency_label,
+              powerful:      powerful?,
+              inert:         inert?,
+              specific:      specific?,
+              broad:         broad?,
+              created_at:    @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_catalyst/helpers/catalyst_engine.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      module Helpers
+        class CatalystEngine
+          include Constants
+
+          def initialize
+            @catalysts = {}
+            @reactions = {}
+          end
+
+          def create_catalyst(catalyst_type:, domain:, potency: 0.5, specificity: 0.5, **)
+            unless CATALYST_TYPES.include?(catalyst_type.to_sym)
+              raise ArgumentError,
+                    "invalid catalyst_type: #{catalyst_type}"
+            end
+
+            evict_oldest_catalyst if @catalysts.size >= MAX_CATALYSTS
+            catalyst = Catalyst.new(
+              catalyst_type: catalyst_type.to_sym,
+              domain:        domain,
+              potency:       potency,
+              specificity:   specificity
+            )
+            @catalysts[catalyst.id] = catalyst
+            catalyst
+          end
+
+          def create_reaction(reaction_type:, reactants:, activation_energy: ACTIVATION_ENERGY, **)
+            unless REACTION_TYPES.include?(reaction_type.to_sym)
+              raise ArgumentError,
+                    "invalid reaction_type: #{reaction_type}"
+            end
+
+            evict_oldest_reaction if @reactions.size >= MAX_REACTIONS
+            reaction = Reaction.new(
+              reaction_type:     reaction_type.to_sym,
+              reactants:         reactants,
+              activation_energy: activation_energy
+            )
+            @reactions[reaction.id] = reaction
+            reaction
+          end
+
+          def apply_catalyst(catalyst_id:, reaction_id:)
+            catalyst = @catalysts[catalyst_id]
+            reaction = @reactions[reaction_id]
+
+            return { success: false, reason: :catalyst_not_found } unless catalyst
+            return { success: false, reason: :reaction_not_found } unless reaction
+            return { success: false, reason: :already_completed }  if reaction.complete?
+
+            reaction.apply_catalyst!(catalyst)
+            {
+              success:           true,
+              activation_energy: reaction.activation_energy,
+              catalyst_id:       catalyst_id,
+              reaction_id:       reaction_id
+            }
+          end
+
+          def attempt_reaction(reaction_id:, energy_input:)
+            reaction = @reactions[reaction_id]
+            return { success: false, reason: :not_found } unless reaction
+            return { success: false, reason: :already_completed } if reaction.complete?
+
+            completed = reaction.attempt!(energy_input)
+            {
+              success:           true,
+              completed:         completed,
+              yield_value:       reaction.yield_value,
+              yield_label:       reaction.yield_label,
+              catalyzed:         reaction.catalyzed?,
+              activation_energy: reaction.activation_energy
+            }
+          end
+
+          def degrade_all!
+            @catalysts.each_value(&:degrade!)
+          end
+
+          def recharge_catalyst(catalyst_id:, amount:)
+            catalyst = @catalysts[catalyst_id]
+            return { success: false, reason: :not_found } unless catalyst
+
+            catalyst.recharge!(amount)
+            { success: true, potency: catalyst.potency, potency_label: catalyst.potency_label }
+          end
+
+          def all_catalysts
+            @catalysts.values
+          end
+
+          def all_reactions
+            @reactions.values
+          end
+
+          def completed_reactions
+            @reactions.values.select(&:complete?)
+          end
+
+          def catalyzed_rate
+            completed = completed_reactions
+            return 0.0 if completed.empty?
+
+            catalyzed_count = completed.count(&:catalyzed?)
+            (catalyzed_count.to_f / completed.size).round(10)
+          end
+
+          def catalyst_report
+            completed     = completed_reactions
+            catalyzed_cnt = completed.count(&:catalyzed?)
+            avg_potency   = if @catalysts.empty?
+                              0.0
+                            else
+                              (@catalysts.values.sum(&:potency) / @catalysts.size).round(10)
+                            end
+
+            {
+              total_catalysts: @catalysts.size,
+              total_reactions: @reactions.size,
+              completed:       completed.size,
+              catalyzed_count: catalyzed_cnt,
+              catalyzed_rate:  catalyzed_rate,
+              avg_potency:     avg_potency,
+              powerful_count:  @catalysts.values.count(&:powerful?),
+              inert_count:     @catalysts.values.count(&:inert?)
+            }
+          end
+
+          private
+
+          def evict_oldest_catalyst
+            oldest_id = @catalysts.min_by { |_id, c| c.created_at }&.first
+            @catalysts.delete(oldest_id) if oldest_id
+          end
+
+          def evict_oldest_reaction
+            oldest_id = @reactions.min_by { |_id, r| r.created_at }&.first
+            @reactions.delete(oldest_id) if oldest_id
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      module Helpers
+        module Constants
+          # Catalyst types — categories of experiences/insights that accelerate reactions
+          CATALYST_TYPES = %i[experience insight analogy pattern emotion].freeze
+
+          # Reaction types — categories of cognitive transformations
+          REACTION_TYPES = %i[synthesis decomposition exchange neutralization precipitation].freeze
+
+          # Storage limits
+          MAX_CATALYSTS = 500
+          MAX_REACTIONS = 200
+
+          # Activation energy — minimum energy to complete a reaction without a catalyst
+          ACTIVATION_ENERGY = 0.6
+
+          # How much a catalyst lowers the activation energy threshold
+          CATALYST_REDUCTION = 0.3
+
+          # Potency degradation rate from environmental wear (not from use)
+          POTENCY_DECAY = 0.02
+
+          # Bonus added when catalyst specificity matches reaction domain
+          SPECIFICITY_BONUS = 0.15
+
+          # Potency labels — range-based classification of catalyst strength
+          POTENCY_LABELS = {
+            (0.8..)     => :powerful,
+            (0.6...0.8) => :strong,
+            (0.4...0.6) => :moderate,
+            (0.2...0.4) => :weak,
+            (..0.2)     => :inert
+          }.freeze
+
+          # Yield labels — range-based classification of reaction output quality
+          YIELD_LABELS = {
+            (0.8..)     => :excellent,
+            (0.6...0.8) => :good,
+            (0.4...0.6) => :fair,
+            (0.2...0.4) => :poor,
+            (..0.2)     => :negligible
+          }.freeze
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_catalyst/helpers/reaction.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveCatalyst
+      module Helpers
+        class Reaction
+          include Constants
+
+          attr_reader :id, :reaction_type, :reactants, :activation_energy,
+                      :yield_value, :catalyzed, :catalyst_id, :completed, :created_at
+
+          def initialize(reaction_type:, reactants:, activation_energy: ACTIVATION_ENERGY)
+            @id               = SecureRandom.uuid
+            @reaction_type    = reaction_type
+            @reactants        = Array(reactants)
+            @activation_energy = activation_energy.clamp(0.0, 1.0)
+            @yield_value      = 0.0
+            @catalyzed        = false
+            @catalyst_id      = nil
+            @completed        = false
+            @created_at       = Time.now.utc
+          end
+
+          # Apply a catalyst to lower the activation energy threshold
+          def apply_catalyst!(catalyst)
+            reduction = catalyst.catalyze!(@reaction_type)
+            @activation_energy = (@activation_energy - reduction).clamp(0.0, 1.0).round(10)
+            @catalyzed         = true
+            @catalyst_id       = catalyst.id
+          end
+
+          # Attempt to complete the reaction with given energy input
+          # Completes if energy_input >= activation_energy; yield based on energy surplus
+          def attempt!(energy_input)
+            return false if @completed
+            return false if energy_input < @activation_energy
+
+            @completed = true
+            surplus = (energy_input - @activation_energy).clamp(0.0, 1.0)
+            @yield_value = (0.5 + (surplus * 0.5)).clamp(0.0, 1.0).round(10)
+            true
+          end
+
+          def complete?
+            @completed
+          end
+
+          def catalyzed?
+            @catalyzed
+          end
+
+          # Completed spontaneously — without a catalyst
+          def spontaneous?
+            @completed && !@catalyzed
+          end
+
+          def yield_label
+            YIELD_LABELS.find { |range, _| range.cover?(@yield_value) }&.last || :negligible
+          end
+
+          def to_h
+            {
+              id:                @id,
+              reaction_type:     @reaction_type,
+              reactants:         @reactants,
+              activation_energy: @activation_energy,
+              yield_value:       @yield_value,
+              yield_label:       yield_label,
+              catalyzed:         @catalyzed,
+              catalyst_id:       @catalyst_id,
+              completed:         @completed,
+              spontaneous:       spontaneous?,
+              created_at:        @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end