lex-gestalt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45bfd8dcac2d9eed154eda678859a0058dda75582c80bb3eef9f28a02b97629e
+  data.tar.gz: 2bd8c8a7bc03b74a923b9967ff5dff9d71ca3cbbde49d68a1c144d6e645e5f0c
+SHA512:
+  metadata.gz: a7f9e56e02ad01c2cbba6ce1430497f863805b4b81ce001a4007d499939909c137c93546be4d4f5409f123bd4f476c895e558b4e143a8d21244bb6498259228b
+  data.tar.gz: 444b301abc9873ee484bdce266b067142e191dbbe8e2a7be5b35609e2bbbb3b828c8b579d27072e9d09e1ea2f41a67fc8c43a6071fd18499a26e7ff1faecc2b0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+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,58 @@
+# lex-gestalt
+
+Gestalt perception modeling for the LegionIO brain-modeled cognitive architecture.
+
+## What It Does
+
+Implements the Gestalt principles of perceptual organization — the tendency to perceive elements as unified wholes rather than isolated parts. Groups input elements by proximity, similarity, continuity, closure, symmetry, and common fate. Computes coherence scores for groups and detects emergent patterns where the whole is more than the sum of its parts. Supports holistic pattern recognition across structured inputs.
+
+Based on Wertheimer, Köhler, and Koffka's Gestalt psychology.
+
+## Usage
+
+```ruby
+client = Legion::Extensions::Gestalt::Client.new
+
+# Register perceptual elements
+client.register_element(content: 'auth_service', properties: { type: :service, domain: :security })
+client.register_element(content: 'session_store', properties: { type: :storage, domain: :security })
+client.register_element(content: 'token_validator', properties: { type: :service, domain: :security })
+
+# Group by a Gestalt principle
+client.apply_grouping(
+  element_ids: ['...', '...', '...'],
+  principle: :similarity
+)
+# => { success: true, group_id: "...", principle: :similarity, coherence: 0.8, emergence_detected: true }
+
+# Detect emergent patterns in the group
+client.detect_emergence(group_id: '...')
+# => { emergence_score: 0.85, emergence_label: :strong_emergence,
+#      emergent_pattern: 'authentication_cluster' }
+
+# Find elements similar to a reference
+client.find_similar_elements(reference_id: '...', threshold: 0.6)
+
+# Automatically group all ungrouped elements
+client.auto_group(domain: :security)
+# => { groups_formed: 2, elements_grouped: 5, ungrouped_count: 1 }
+
+# View active groups by coherence
+client.active_groups
+# => { groups: [...sorted by coherence], count: 2 }
+
+# Periodic maintenance
+client.update_gestalt
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Gestalt
+      class Client
+        include Runners::Gestalt
+
+        attr_reader :store
+
+        def initialize(store: nil, **)
+          @store = store || Helpers::PatternStore.new
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Gestalt
+      module Helpers
+        module Constants
+          # Minimum pattern match ratio to attempt completion
+          COMPLETION_THRESHOLD = 0.3
+
+          # Confidence boost for each additional matching element
+          MATCH_CONFIDENCE_BOOST = 0.15
+
+          # Maximum stored patterns
+          MAX_PATTERNS = 200
+
+          # Maximum elements per pattern
+          MAX_PATTERN_SIZE = 50
+
+          # Decay rate for pattern recency (older patterns contribute less)
+          PATTERN_DECAY = 0.01
+
+          # Minimum confidence to report a completion
+          MIN_COMPLETION_CONFIDENCE = 0.2
+
+          # Maximum completion candidates to return
+          MAX_COMPLETIONS = 5
+
+          # Grouping principles (Wertheimer's laws)
+          GROUPING_PRINCIPLES = %i[proximity similarity closure continuity common_fate].freeze
+
+          # Proximity threshold for grouping (normalized distance)
+          PROXIMITY_THRESHOLD = 0.3
+
+          # Similarity threshold for grouping
+          SIMILARITY_THRESHOLD = 0.6
+
+          # Reinforcement when a completion is confirmed correct
+          CORRECT_REINFORCEMENT = 0.1
+
+          # Penalty when a completion is wrong
+          INCORRECT_PENALTY = 0.15
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/gestalt/helpers/pattern.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Gestalt
+      module Helpers
+        class Pattern
+          attr_reader :id, :name, :domain, :elements, :created_at
+          attr_accessor :strength, :match_count
+
+          def initialize(name:, elements:, domain: :general)
+            @id          = SecureRandom.uuid
+            @name        = name
+            @domain      = domain
+            @elements    = elements.first(Constants::MAX_PATTERN_SIZE)
+            @strength    = 1.0
+            @match_count = 0
+            @created_at  = Time.now.utc
+          end
+
+          def match_ratio(fragment)
+            return 0.0 if @elements.empty? || fragment.empty?
+
+            matches = fragment.count { |e| @elements.include?(e) }
+            matches.to_f / @elements.size
+          end
+
+          def missing_elements(fragment)
+            @elements - fragment
+          end
+
+          def complete(fragment)
+            ratio = match_ratio(fragment)
+            return nil if ratio < Constants::COMPLETION_THRESHOLD
+
+            confidence = compute_confidence(ratio)
+            missing = missing_elements(fragment)
+
+            @match_count += 1
+            {
+              pattern_id:   @id,
+              pattern_name: @name,
+              completed:    @elements,
+              missing:      missing,
+              confidence:   confidence.round(4),
+              match_ratio:  ratio.round(4)
+            }
+          end
+
+          def reinforce
+            @strength = [@strength + Constants::CORRECT_REINFORCEMENT, 2.0].min
+          end
+
+          def penalize
+            @strength = [@strength - Constants::INCORRECT_PENALTY, 0.1].max
+          end
+
+          def decay
+            @strength = [@strength - Constants::PATTERN_DECAY, 0.1].max
+          end
+
+          def to_h
+            {
+              id:          @id,
+              name:        @name,
+              domain:      @domain,
+              elements:    @elements,
+              strength:    @strength.round(4),
+              match_count: @match_count,
+              size:        @elements.size
+            }
+          end
+
+          private
+
+          def compute_confidence(ratio)
+            base = ratio * Constants::MATCH_CONFIDENCE_BOOST / Constants::COMPLETION_THRESHOLD
+            (base * @strength).clamp(0.0, 1.0)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/gestalt/helpers/pattern_store.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Gestalt
+      module Helpers
+        class PatternStore
+          attr_reader :patterns
+
+          def initialize
+            @patterns = []
+          end
+
+          def add(name:, elements:, domain: :general)
+            pattern = Pattern.new(name: name, elements: elements, domain: domain)
+            @patterns << pattern
+            trim
+            pattern
+          end
+
+          def find(id)
+            @patterns.find { |p| p.id == id }
+          end
+
+          def find_by_name(name)
+            @patterns.select { |p| p.name == name }
+          end
+
+          def in_domain(domain)
+            @patterns.select { |p| p.domain == domain }
+          end
+
+          def complete(fragment, domain: nil)
+            candidates = domain ? in_domain(domain) : @patterns
+            completions = candidates.filter_map { |p| p.complete(fragment) }
+            completions.sort_by { |c| -c[:confidence] }.first(Constants::MAX_COMPLETIONS)
+          end
+
+          def group_by_proximity(items, threshold: Constants::PROXIMITY_THRESHOLD)
+            return [items] if items.size <= 1
+
+            groups = []
+            remaining = items.dup
+
+            until remaining.empty?
+              seed = remaining.shift
+              group = [seed]
+              remaining.reject! do |item|
+                if proximity(seed, item) <= threshold
+                  group << item
+                  true
+                else
+                  false
+                end
+              end
+              groups << group
+            end
+            groups
+          end
+
+          def group_by_similarity(items, key: :type, **)
+            items.group_by { |item| item.is_a?(Hash) ? item[key] : item }.values
+          end
+
+          def reinforce(id)
+            pattern = find(id)
+            return nil unless pattern
+
+            pattern.reinforce
+            pattern
+          end
+
+          def penalize(id)
+            pattern = find(id)
+            return nil unless pattern
+
+            pattern.penalize
+            pattern
+          end
+
+          def decay_all
+            @patterns.each(&:decay)
+          end
+
+          def remove(id)
+            @patterns.reject! { |p| p.id == id }
+          end
+
+          def size
+            @patterns.size
+          end
+
+          def to_h
+            {
+              pattern_count: @patterns.size,
+              by_domain:     @patterns.group_by(&:domain).transform_values(&:size),
+              total_matches: @patterns.sum(&:match_count)
+            }
+          end
+
+          private
+
+          def proximity(item_a, item_b)
+            return 1.0 unless item_a.is_a?(Numeric) && item_b.is_a?(Numeric)
+
+            (item_a - item_b).abs.to_f / [item_a.abs, item_b.abs, 1].max
+          end
+
+          def trim
+            return unless @patterns.size > Constants::MAX_PATTERNS
+
+            @patterns.sort_by!(&:strength)
+            @patterns.shift(@patterns.size - Constants::MAX_PATTERNS)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Gestalt
+      module Runners
+        module Gestalt
+          include Legion::Extensions::Helpers::Lex
+
+          def store
+            @store ||= Helpers::PatternStore.new
+          end
+
+          def learn_pattern(name:, elements:, domain: :general, **)
+            pattern = store.add(name: name, elements: elements, domain: domain)
+            Legion::Logging.debug "[gestalt] learned pattern=#{name} domain=#{domain} size=#{elements.size}"
+            { success: true, pattern: pattern.to_h }
+          end
+
+          def complete_pattern(fragment:, domain: nil, **)
+            completions = store.complete(fragment, domain: domain)
+            Legion::Logging.debug "[gestalt] complete: #{completions.size} candidates for #{fragment.size} elements"
+            {
+              success:     true,
+              completions: completions,
+              count:       completions.size,
+              best:        completions.first
+            }
+          end
+
+          def confirm_completion(pattern_id:, correct: true, **)
+            result = if correct
+                       store.reinforce(pattern_id)
+                     else
+                       store.penalize(pattern_id)
+                     end
+            return { success: false, reason: :not_found } unless result
+
+            Legion::Logging.debug "[gestalt] #{correct ? 'reinforced' : 'penalized'} pattern=#{pattern_id}"
+            { success: true, pattern: result.to_h }
+          end
+
+          def group_items(items:, principle: :proximity, **)
+            groups = case principle
+                     when :proximity
+                       store.group_by_proximity(items)
+                     when :similarity
+                       store.group_by_similarity(items)
+                     else
+                       [items]
+                     end
+            { success: true, groups: groups, group_count: groups.size, principle: principle }
+          end
+
+          def update_gestalt(**)
+            store.decay_all
+            Legion::Logging.debug "[gestalt] tick: patterns=#{store.size}"
+            { success: true, pattern_count: store.size }
+          end
+
+          def patterns_in_domain(domain:, **)
+            patterns = store.in_domain(domain)
+            { success: true, patterns: patterns.map(&:to_h), count: patterns.size }
+          end
+
+          def remove_pattern(id:, **)
+            store.remove(id)
+            { success: true }
+          end
+
+          def gestalt_stats(**)
+            { success: true, stats: store.to_h }
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/gestalt.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'gestalt/version'
+require_relative 'gestalt/helpers/constants'
+require_relative 'gestalt/helpers/pattern'
+require_relative 'gestalt/helpers/pattern_store'
+require_relative 'gestalt/runners/gestalt'
+require_relative 'gestalt/client'
+
+module Legion
+  module Extensions
+    module Gestalt
+      extend Legion::Extensions::Core if defined?(Legion::Extensions::Core)
+    end
+  end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lex-gestalt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matthew Iverson
+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: Models gestalt perception — completing partial patterns from context,
+  recognizing wholes from fragments, and grouping related signals.
+email:
+- matt@iverson.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/legion/extensions/gestalt.rb
+- lib/legion/extensions/gestalt/client.rb
+- lib/legion/extensions/gestalt/helpers/constants.rb
+- lib/legion/extensions/gestalt/helpers/pattern.rb
+- lib/legion/extensions/gestalt/helpers/pattern_store.rb
+- lib/legion/extensions/gestalt/runners/gestalt.rb
+- lib/legion/extensions/gestalt/version.rb
+homepage: https://github.com/LegionIO/lex-gestalt
+licenses:
+- MIT
+metadata:
+  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: Gestalt pattern completion for LegionIO
+test_files: []