lex-cognitive-magnet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8878597a795cca69e3919ff364db407c2a96b322271ec9929669f9a4ccfbd75b
+  data.tar.gz: 8ca1026de6ed94260b07e084e502a0c6a876dbecc893a3c78824c36b288b528b
+SHA512:
+  metadata.gz: cedc41cdfaec14b72dc6987cf68c2de9b7c2154483b8d50c59d34db2434348c5032e315dd05005a413c17c2de8f8b2dd0f2fc9921532afa8676aa61fa9ad0e57
+  data.tar.gz: 2edad7d627afaec664d81211115566f5bc90ae00f3e2872f961ee8301bc34ef813fe833dce63cdbbbe87c2d1a0e919c87c79f5cc3729b8499422b1d04f812e49

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,2 @@
+.rspec_status
+Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,64 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,116 @@
+# lex-cognitive-magnet
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+
+## Purpose
+
+Magnetic field metaphor for cognitive attraction and repulsion. Poles represent cognitive elements with a polarity (positive, negative, neutral, bipolar) and a material type. When poles interact, attraction strengthens both; repulsion weakens both. Fields group poles and compute alignment scores via pair-wise interaction analysis. Models how ideas, beliefs, or preferences cluster and conflict in cognitive space.
+
+## Gem Info
+
+- **Gem name**: `lex-cognitive-magnet`
+- **Module**: `Legion::Extensions::CognitiveMagnet`
+- **Version**: `0.1.0`
+- **Ruby**: `>= 3.4`
+- **License**: MIT
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_magnet/
+  version.rb
+  client.rb
+  helpers/
+    constants.rb
+    pole.rb
+    field.rb
+    magnet_engine.rb
+  runners/
+    cognitive_magnet.rb
+```
+
+## Key Constants
+
+| Constant | Value | Purpose |
+|---|---|---|
+| `POLARITY_TYPES` | `%i[positive negative neutral bipolar]` | Valid pole polarity values |
+| `MATERIAL_TYPES` | `%i[iron cobalt nickel lodestone ferrite]` | Valid material types |
+| `MAX_POLES` | `500` | Per-engine pole capacity |
+| `MAX_FIELDS` | `50` | Per-engine field capacity |
+| `ATTRACTION_RATE` | `0.08` | Base strength increase per attraction interaction |
+| `REPULSION_RATE` | `0.06` | Base strength decrease per repulsion interaction |
+| `DECAY_RATE` | `0.02` | Default strength reduction per demagnetize cycle |
+| `STRENGTH_LABELS` | range hash | From `:negligible` to `:overwhelming` |
+| `ALIGNMENT_LABELS` | range hash | From `:chaotic` to `:perfect` |
+
+## Helpers
+
+### `Helpers::Pole`
+Individual magnetic pole. Has `id`, `polarity`, `strength` (0.0–1.0), `material_type`, `domain`, `content`, and `created_at`.
+
+- `magnetize!(rate)` — increases strength by rate
+- `demagnetize!(rate)` — decreases strength by rate
+- `attracts?(other_pole)` — true if polarities are opposite; always true for `:bipolar`, always false for `:neutral`
+- `repels?(other_pole)` — true if polarities match; always false for `:neutral` or `:bipolar`
+- `saturated?` — strength >= 1.0
+- `weak?` — strength <= 0.1
+- `strength_label`
+- `to_h`
+
+### `Helpers::Field`
+Named container for poles. Has `id`, `name`, `pole_ids`, `alignment`, and `flux_density`.
+
+- `add_pole(pole_id)` — adds pole ID (idempotent)
+- `remove_pole(pole_id)` — removes pole ID
+- `calculate_alignment!(poles)` — pair-wise computation: attraction pairs add `(a.strength + b.strength) / 2.0`, repulsion pairs subtract half that weight; result normalized to [0.0, 1.0]
+- `coherent?` — alignment >= 0.6
+- `chaotic?` — alignment < 0.2
+- `alignment_label`
+- `pole_count`
+- `to_h`
+
+### `Helpers::MagnetEngine`
+Top-level store. Enforces `MAX_POLES` and `MAX_FIELDS`.
+
+- `create_pole(polarity:, content:, strength:, material_type:, domain:)` → pole or capacity error
+- `create_field(name:)` → field or capacity error
+- `magnetize(pole_id, rate:)` → strength hash
+- `interact(pole_a_id, pole_b_id)` — mutual magnetize/demagnetize based on attraction/repulsion; logs interaction event
+- `demagnetize_all!(rate:)` → count hash
+- `most_aligned_fields(limit:)` → top N fields by alignment (recalculates before sort)
+- `strongest_poles(limit:)` → top N poles by strength (excludes weak poles)
+- `field_report` → aggregate stats including coherent/chaotic field counts
+- `add_pole_to_field(field_id:, pole_id:)` → status hash
+- `remove_pole_from_field(field_id:, pole_id:)` → status hash
+
+## Runners
+
+Module: `Runners::CognitiveMagnet`
+
+| Runner Method | Description |
+|---|---|
+| `create_pole(polarity:, content:, strength:, material_type:, domain:)` | Register a new pole |
+| `create_field(name:)` | Create a field |
+| `magnetize(pole_id:, rate:)` | Strengthen a pole |
+| `interact(pole_a_id:, pole_b_id:)` | Trigger mutual interaction |
+| `list_poles(limit:)` | Strongest poles |
+| `magnetic_status` | Full field report |
+
+All runners return `{success: true/false, ...}` hashes.
+
+## Integration Points
+
+- No direct dependencies on other agentic LEX gems
+- Fields with high coherence represent stable belief clusters; can feed `lex-emotion` valence
+- Repulsion events between poles can register as `lex-conflict` conflicts
+- `interact` drives organic reinforcement and weakening as ideas encounter each other in `lex-tick` cycles
+- Chaotic fields (low alignment) can trigger `lex-prediction` uncertainty signals
+
+## Development Notes
+
+- `Client` instantiates `@magnet_engine = Helpers::MagnetEngine.new`
+- `attract?` / `repels?` are asymmetric: `:bipolar` always attracts any polarity, `:neutral` never attracts or repels
+- `interact` logs to `@interaction_log` (unbounded array — callers should periodically prune for long-running sessions)
+- `most_aligned_fields` calls `recalculate_all_fields` before sorting — this is O(fields * poles^2/2) pairs
+- Alignment formula maps raw weighted average to [0.0, 1.0] via `(raw + 1.0) / 2.0`

data/Gemfile

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

data/README.md

@@ -0,0 +1,51 @@
+# lex-cognitive-magnet
+
+Magnetic field metaphor for cognitive attraction and repulsion in LegionIO agents. Poles represent ideas or beliefs with polarities; interacting poles strengthen or weaken each other; fields group poles and measure their collective alignment.
+
+## What It Does
+
+- Four polarity types: `positive`, `negative`, `neutral`, `bipolar`
+- Five material types: `iron`, `cobalt`, `nickel`, `lodestone`, `ferrite`
+- Attraction: opposite polarities strengthen each other on interaction
+- Repulsion: matching polarities weaken each other on interaction
+- `bipolar` attracts everything; `neutral` never attracts or repels
+- Fields group poles and compute alignment via pair-wise strength-weighted analysis
+- Coherent fields (alignment >= 0.6) and chaotic fields (< 0.2) are classified
+- `demagnetize_all` provides a global decay cycle
+
+## Usage
+
+```ruby
+# Create poles
+a = runner.create_pole(polarity: :positive, content: 'hypothesis_A',
+                        strength: 0.6, material_type: :iron, domain: :reasoning)
+b = runner.create_pole(polarity: :negative, content: 'counter_hypothesis',
+                        strength: 0.5, material_type: :iron, domain: :reasoning)
+
+# Interact — opposite polarities attract, both strengthen
+runner.interact(pole_a_id: a[:pole][:id], pole_b_id: b[:pole][:id])
+# => { type: :attraction, force: 0.3, ... }
+
+# Create a field and add poles
+field = runner.create_field(name: 'reasoning_cluster')
+# (add poles to field via engine directly or via future runner method)
+
+# Status
+runner.magnetic_status
+# => { success: true, total_poles: 2, coherent_fields: 0, chaotic_fields: 0, ... }
+
+# Strongest poles
+runner.list_poles(limit: 5)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-magnet.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_magnet/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-magnet'
+  spec.version       = Legion::Extensions::CognitiveMagnet::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Magnet'
+  spec.description   = 'Magnetic attraction and repulsion between ideas — polarity-driven cognitive clustering for LegionIO agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-magnet'
+  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-magnet'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-magnet'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-magnet'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-magnet/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.start_with?('spec/') }
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_magnet/helpers/constants'
+require 'legion/extensions/cognitive_magnet/helpers/pole'
+require 'legion/extensions/cognitive_magnet/helpers/field'
+require 'legion/extensions/cognitive_magnet/helpers/magnet_engine'
+require 'legion/extensions/cognitive_magnet/runners/cognitive_magnet'
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      class Client
+        include Runners::CognitiveMagnet
+
+        def initialize(**)
+          @magnet_engine = Helpers::MagnetEngine.new
+        end
+
+        private
+
+        attr_reader :magnet_engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      module Helpers
+        module Constants
+          POLARITY_TYPES   = %i[positive negative neutral bipolar].freeze
+          MATERIAL_TYPES   = %i[iron cobalt nickel lodestone ferrite].freeze
+          MAX_POLES        = 500
+          MAX_FIELDS       = 50
+          ATTRACTION_RATE  = 0.08
+          REPULSION_RATE   = 0.06
+          DECAY_RATE       = 0.02
+
+          STRENGTH_LABELS = {
+            (0.0..0.1) => :negligible,
+            (0.1..0.3) => :faint,
+            (0.3..0.5) => :moderate,
+            (0.5..0.7) => :strong,
+            (0.7..0.9) => :intense,
+            (0.9..1.0) => :overwhelming
+          }.freeze
+
+          ALIGNMENT_LABELS = {
+            (0.0..0.2) => :chaotic,
+            (0.2..0.4) => :discordant,
+            (0.4..0.6) => :neutral,
+            (0.6..0.8) => :coherent,
+            (0.8..1.0) => :perfect
+          }.freeze
+
+          module_function
+
+          def label_for(table, value)
+            table.each do |range, label|
+              return label if range.cover?(value)
+            end
+            :unknown
+          end
+
+          def valid_polarity?(polarity)
+            POLARITY_TYPES.include?(polarity)
+          end
+
+          def valid_material?(material)
+            MATERIAL_TYPES.include?(material)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_magnet/helpers/field.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      module Helpers
+        class Field
+          attr_reader :id, :name, :pole_ids, :alignment, :flux_density, :created_at
+
+          def initialize(name:)
+            @id          = SecureRandom.uuid
+            @name        = name
+            @pole_ids    = []
+            @alignment   = 0.0
+            @flux_density = 0.0
+            @created_at  = Time.now.utc
+          end
+
+          def add_pole(pole_id)
+            return false if @pole_ids.include?(pole_id)
+
+            @pole_ids << pole_id
+            true
+          end
+
+          def remove_pole(pole_id)
+            removed = @pole_ids.delete(pole_id)
+            !removed.nil?
+          end
+
+          def calculate_alignment!(poles)
+            field_poles = poles.values.select { |p| @pole_ids.include?(p.id) }
+            return self if field_poles.empty?
+
+            @flux_density = field_poles.sum(&:strength) / field_poles.size.to_f
+            @alignment    = compute_alignment(field_poles).round(10)
+            self
+          end
+
+          def coherent?
+            @alignment >= 0.6
+          end
+
+          def chaotic?
+            @alignment < 0.2
+          end
+
+          def alignment_label
+            Constants.label_for(Constants::ALIGNMENT_LABELS, @alignment)
+          end
+
+          def pole_count
+            @pole_ids.size
+          end
+
+          def to_h
+            {
+              id:              @id,
+              name:            @name,
+              pole_ids:        @pole_ids.dup,
+              alignment:       @alignment,
+              flux_density:    @flux_density,
+              pole_count:      pole_count,
+              coherent:        coherent?,
+              chaotic:         chaotic?,
+              alignment_label: alignment_label,
+              created_at:      @created_at
+            }
+          end
+
+          private
+
+          def compute_alignment(field_poles)
+            return 0.0 if field_poles.size < 2
+
+            total_pairs    = 0
+            aligned_weight = 0.0
+
+            field_poles.combination(2) do |a, b|
+              total_pairs += 1
+              pair_weight  = (a.strength + b.strength) / 2.0
+
+              if a.attracts?(b)
+                aligned_weight += pair_weight
+              elsif a.repels?(b)
+                aligned_weight -= pair_weight * 0.5
+              end
+            end
+
+            return 0.5 if total_pairs.zero?
+
+            raw = aligned_weight / total_pairs.to_f
+            ((raw + 1.0) / 2.0).clamp(0.0, 1.0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_magnet/helpers/magnet_engine.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      module Helpers
+        class MagnetEngine
+          attr_reader :poles, :fields, :interaction_log
+
+          def initialize
+            @poles           = {}
+            @fields          = {}
+            @interaction_log = []
+          end
+
+          def create_pole(polarity:, content:, strength: 0.5, material_type: :iron, domain: :general)
+            return { error: :capacity_exceeded, max: Constants::MAX_POLES } if at_pole_capacity?
+
+            pole = Pole.new(
+              polarity:      polarity,
+              content:       content,
+              strength:      strength,
+              material_type: material_type,
+              domain:        domain
+            )
+            @poles[pole.id] = pole
+            pole
+          end
+
+          def create_field(name:)
+            return { error: :capacity_exceeded, max: Constants::MAX_FIELDS } if at_field_capacity?
+
+            field = Field.new(name: name)
+            @fields[field.id] = field
+            field
+          end
+
+          def magnetize(pole_id, rate: Constants::ATTRACTION_RATE)
+            pole = @poles[pole_id]
+            return { error: :not_found } unless pole
+
+            pole.magnetize!(rate)
+            { magnetized: true, id: pole_id, strength: pole.strength }
+          end
+
+          def interact(pole_a_id, pole_b_id)
+            pole_a = @poles[pole_a_id]
+            pole_b = @poles[pole_b_id]
+            return { error: :pole_a_not_found } unless pole_a
+            return { error: :pole_b_not_found } unless pole_b
+            return { error: :same_pole } if pole_a_id == pole_b_id
+
+            force = compute_force(pole_a, pole_b)
+            type  = determine_interaction_type(pole_a, pole_b)
+
+            apply_interaction(pole_a, pole_b, type)
+
+            event = build_interaction_event(pole_a, pole_b, type, force)
+            @interaction_log << event
+            event
+          end
+
+          def demagnetize_all!(rate: Constants::DECAY_RATE)
+            count = 0
+            @poles.each_value do |pole|
+              pole.demagnetize!(rate)
+              count += 1
+            end
+            { demagnetized: count, rate: rate }
+          end
+
+          def most_aligned_fields(limit: 5)
+            recalculate_all_fields
+            @fields.values
+                   .sort_by { |f| -f.alignment }
+                   .first(limit)
+          end
+
+          def strongest_poles(limit: 5)
+            @poles.values
+                  .reject(&:weak?)
+                  .sort_by { |p| -p.strength }
+                  .first(limit)
+          end
+
+          def field_report
+            recalculate_all_fields
+            coherent  = @fields.values.select(&:coherent?)
+            chaotic   = @fields.values.select(&:chaotic?)
+            saturated = @poles.values.select(&:saturated?)
+            weak      = @poles.values.select(&:weak?)
+
+            {
+              total_poles:        @poles.size,
+              total_fields:       @fields.size,
+              coherent_fields:    coherent.size,
+              chaotic_fields:     chaotic.size,
+              saturated_poles:    saturated.size,
+              weak_poles:         weak.size,
+              total_interactions: @interaction_log.size,
+              strongest:          strongest_poles(limit: 3).map(&:to_h),
+              top_fields:         most_aligned_fields(limit: 3).map(&:to_h)
+            }
+          end
+
+          def add_pole_to_field(field_id:, pole_id:)
+            field = @fields[field_id]
+            return { error: :field_not_found } unless field
+            return { error: :pole_not_found } unless @poles[pole_id]
+
+            added = field.add_pole(pole_id)
+            { added: added, field_id: field_id, pole_id: pole_id }
+          end
+
+          def remove_pole_from_field(field_id:, pole_id:)
+            field = @fields[field_id]
+            return { error: :field_not_found } unless field
+
+            removed = field.remove_pole(pole_id)
+            { removed: removed, field_id: field_id, pole_id: pole_id }
+          end
+
+          private
+
+          def at_pole_capacity?
+            @poles.size >= Constants::MAX_POLES
+          end
+
+          def at_field_capacity?
+            @fields.size >= Constants::MAX_FIELDS
+          end
+
+          def compute_force(pole_a, pole_b)
+            (pole_a.strength * pole_b.strength).round(10)
+          end
+
+          def determine_interaction_type(pole_a, pole_b)
+            if pole_a.attracts?(pole_b)
+              :attraction
+            elsif pole_a.repels?(pole_b)
+              :repulsion
+            else
+              :neutral
+            end
+          end
+
+          def apply_interaction(pole_a, pole_b, type)
+            case type
+            when :attraction
+              pole_a.magnetize!(Constants::ATTRACTION_RATE * pole_b.strength)
+              pole_b.magnetize!(Constants::ATTRACTION_RATE * pole_a.strength)
+            when :repulsion
+              pole_a.demagnetize!(Constants::REPULSION_RATE * pole_b.strength)
+              pole_b.demagnetize!(Constants::REPULSION_RATE * pole_a.strength)
+            end
+          end
+
+          def build_interaction_event(pole_a, pole_b, type, force)
+            {
+              type:      type,
+              pole_a_id: pole_a.id,
+              pole_b_id: pole_b.id,
+              force:     force,
+              at:        Time.now.utc
+            }
+          end
+
+          def recalculate_all_fields
+            @fields.each_value { |f| f.calculate_alignment!(@poles) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_magnet/helpers/pole.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      module Helpers
+        class Pole
+          attr_reader :id, :polarity, :strength, :material_type, :domain, :content, :created_at
+
+          def initialize(polarity:, content:, strength: 0.5, material_type: :iron, domain: :general)
+            @id            = SecureRandom.uuid
+            @polarity      = polarity
+            @content       = content
+            @strength      = strength.to_f.clamp(0.0, 1.0).round(10)
+            @material_type = material_type
+            @domain        = domain
+            @created_at    = Time.now.utc
+          end
+
+          def magnetize!(rate = Constants::ATTRACTION_RATE)
+            @strength = (@strength + rate.to_f).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def demagnetize!(rate = Constants::DECAY_RATE)
+            @strength = (@strength - rate.to_f).clamp(0.0, 1.0).round(10)
+            self
+          end
+
+          def attracts?(other_pole)
+            return false if @polarity == :neutral || other_pole.polarity == :neutral
+            return true if @polarity == :bipolar || other_pole.polarity == :bipolar
+
+            @polarity != other_pole.polarity
+          end
+
+          def repels?(other_pole)
+            return false if @polarity == :neutral || other_pole.polarity == :neutral
+            return false if @polarity == :bipolar || other_pole.polarity == :bipolar
+
+            @polarity == other_pole.polarity
+          end
+
+          def saturated?
+            @strength >= 1.0
+          end
+
+          def weak?
+            @strength <= 0.1
+          end
+
+          def strength_label
+            Constants.label_for(Constants::STRENGTH_LABELS, @strength)
+          end
+
+          def to_h
+            {
+              id:             @id,
+              polarity:       @polarity,
+              strength:       @strength,
+              material_type:  @material_type,
+              domain:         @domain,
+              content:        @content,
+              saturated:      saturated?,
+              weak:           weak?,
+              strength_label: strength_label,
+              created_at:     @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      module Runners
+        module CognitiveMagnet
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          extend self
+
+          def create_pole(polarity:, content:, strength: 0.5, material_type: :iron,
+                          domain: :general, engine: nil, **)
+            unless Helpers::Constants.valid_polarity?(polarity)
+              return { success: false, error: :invalid_polarity,
+                       valid_polarities: Helpers::Constants::POLARITY_TYPES }
+            end
+
+            unless Helpers::Constants.valid_material?(material_type)
+              return { success: false, error: :invalid_material,
+                       valid_materials: Helpers::Constants::MATERIAL_TYPES }
+            end
+
+            eng    = engine || magnet_engine
+            result = eng.create_pole(
+              polarity:      polarity,
+              content:       content,
+              strength:      strength,
+              material_type: material_type,
+              domain:        domain
+            )
+
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[cognitive_magnet] create_pole failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_magnet] pole created id=#{result.id[0..7]} " \
+                                  "polarity=#{polarity} strength=#{strength}"
+            { success: true, pole: result.to_h }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def create_field(name:, engine: nil, **)
+            eng    = engine || magnet_engine
+            result = eng.create_field(name: name)
+
+            if result.is_a?(Hash) && result[:error]
+              Legion::Logging.warn "[cognitive_magnet] create_field failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_magnet] field created id=#{result.id[0..7]} name=#{name}"
+            { success: true, field: result.to_h }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def magnetize(pole_id:, rate: Helpers::Constants::ATTRACTION_RATE, engine: nil, **)
+            eng    = engine || magnet_engine
+            result = eng.magnetize(pole_id, rate: rate)
+
+            if result[:error]
+              Legion::Logging.warn "[cognitive_magnet] magnetize failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_magnet] magnetized id=#{pole_id[0..7]} strength=#{result[:strength]}"
+            { success: true, **result }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def interact(pole_a_id:, pole_b_id:, engine: nil, **)
+            eng    = engine || magnet_engine
+            result = eng.interact(pole_a_id, pole_b_id)
+
+            if result[:error]
+              Legion::Logging.warn "[cognitive_magnet] interact failed: #{result[:error]}"
+              return { success: false, **result }
+            end
+
+            Legion::Logging.debug "[cognitive_magnet] interaction type=#{result[:type]} " \
+                                  "force=#{result[:force].round(4)}"
+            { success: true, **result }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def list_poles(engine: nil, limit: 50, **)
+            eng   = engine || magnet_engine
+            poles = eng.poles.values.first(limit).map(&:to_h)
+            Legion::Logging.debug "[cognitive_magnet] list_poles count=#{poles.size}"
+            { success: true, poles: poles, count: poles.size }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          def magnetic_status(engine: nil, **)
+            eng    = engine || magnet_engine
+            report = eng.field_report
+            Legion::Logging.debug "[cognitive_magnet] status: poles=#{report[:total_poles]} " \
+                                  "fields=#{report[:total_fields]} interactions=#{report[:total_interactions]}"
+            { success: true, report: report }
+          rescue ArgumentError => e
+            { success: false, error: :argument_error, message: e.message }
+          end
+
+          private
+
+          def magnet_engine
+            @magnet_engine ||= Helpers::MagnetEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_magnet.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'legion/extensions/cognitive_magnet/version'
+require 'legion/extensions/cognitive_magnet/helpers/constants'
+require 'legion/extensions/cognitive_magnet/helpers/pole'
+require 'legion/extensions/cognitive_magnet/helpers/field'
+require 'legion/extensions/cognitive_magnet/helpers/magnet_engine'
+require 'legion/extensions/cognitive_magnet/runners/cognitive_magnet'
+require 'legion/extensions/cognitive_magnet/client'
+
+module Legion
+  module Extensions
+    module CognitiveMagnet
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-magnet
+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: Magnetic attraction and repulsion between ideas — polarity-driven cognitive
+  clustering for LegionIO agentic AI
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- README.md
+- lex-cognitive-magnet.gemspec
+- lib/legion/extensions/cognitive_magnet.rb
+- lib/legion/extensions/cognitive_magnet/client.rb
+- lib/legion/extensions/cognitive_magnet/helpers/constants.rb
+- lib/legion/extensions/cognitive_magnet/helpers/field.rb
+- lib/legion/extensions/cognitive_magnet/helpers/magnet_engine.rb
+- lib/legion/extensions/cognitive_magnet/helpers/pole.rb
+- lib/legion/extensions/cognitive_magnet/runners/cognitive_magnet.rb
+- lib/legion/extensions/cognitive_magnet/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-magnet
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-magnet
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-magnet
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-magnet
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-magnet
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-magnet/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: LEX Cognitive Magnet
+test_files: []