lex-cognitive-grammar 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d1a6033a3d40b2be785361c3c86637af7d504cdfa3389e4501e6634a69f7bf2
+  data.tar.gz: d95e46dd8e3846f5dce29a3d7d1c17290a06f8df16ebb747fac388e6ae393999
+SHA512:
+  metadata.gz: ee8709710023d006ce784491caff43246edf7e69105ae7a88935d5bbb528eb74d62e0990c6f590ee422ba3c885f8b437eed35f44014a644c6a36bd0b4fc38c91
+  data.tar.gz: 4eeba781ebdf5d0065e9f18bc4874c1f78c8d8b5a132f8f75675f3e5a223d4fb790a4215b3460db4614d0af66f545047ad4708dbabb8c80374306c20a91417f2

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,2 @@
+--require spec_helper
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,52 @@
+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: 150
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/ParameterLists:
+  Max: 8
+  MaxOptionalParameters: 8
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/OneClassPerFile:
+  Exclude:
+    - 'spec/spec_helper.rb'
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false

data/CLAUDE.md

@@ -0,0 +1,116 @@
+# lex-cognitive-grammar
+
+**Level 3 Leaf Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/extensions-agentic/CLAUDE.md`
+- **Gem**: `lex-cognitive-grammar`
+
+## Purpose
+
+Models cognitive grammar — the structured mental constructions through which meaning is assembled. Based on Cognitive Linguistics: constructions are symbolic units (form-meaning pairings) stored in a construction grammar network. Construals represent specific applications of constructions to scenes. Each use of a construction strengthens its activation via Exponential Moving Average. Constructions that exceed the entrenchment threshold (0.8) become automatic. A periodic maintenance actor decays unused constructions over time.
+
+## Gem Info
+
+| Field | Value |
+|---|---|
+| Gem name | `lex-cognitive-grammar` |
+| Version | `0.1.0` |
+| Namespace | `Legion::Extensions::CognitiveGrammar` |
+| Ruby | `>= 3.4` |
+| License | MIT |
+| GitHub | https://github.com/LegionIO/lex-cognitive-grammar |
+
+## File Structure
+
+```
+lib/legion/extensions/cognitive_grammar/
+  cognitive_grammar.rb              # Top-level require
+  version.rb                        # VERSION = '0.1.0'
+  client.rb                         # Client class
+  helpers/
+    constants.rb                    # Construal operations, prominence types, activation labels, thresholds
+    construction.rb                 # Construction value object (form-meaning unit)
+    construal.rb                    # Construal value object (specific scene interpretation)
+    grammar_engine.rb               # Engine: constructions, construals, activation, decay
+  runners/
+    cognitive_grammar.rb            # Runner module
+```
+
+## Key Constants
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `CONSTRUAL_OPERATIONS` | array | Mental operations: `profiling`, `trajector_landmark`, `figure_ground`, `scope`, `perspective`, `dynamism` |
+| `PROMINENCE_TYPES` | array | `[:trajector, :landmark, :profiled, :active_zone, :reference_point, :base]` |
+| `EXPRESSION_TYPES` | array | `[:nominal, :verbal, :clausal, :prepositional, :adjectival, :constructional]` |
+| `MAX_CONSTRUCTIONS` | 200 | Construction store cap |
+| `MAX_CONSTRUALS` | 500 | Construal history cap |
+| `DEFAULT_ACTIVATION` | 0.3 | Starting activation for new constructions |
+| `ENTRENCHMENT_THRESHOLD` | 0.8 | Activation above this = entrenched (automatic) |
+| `ACTIVATION_LABELS` | hash | `entrenched` (0.8+) through `dormant` |
+
+## Helpers
+
+### `Construction`
+
+A symbolic form-meaning unit in the grammar network.
+
+- `initialize(name:, form:, meaning:, domain:, activation: DEFAULT_ACTIVATION, construction_id: nil)`
+- `use!(alpha: 0.2)` — updates activation via EMA; increments use count
+- `decay!(rate: 0.01)` — decreases activation
+- `entrenched?` — activation >= `ENTRENCHMENT_THRESHOLD`
+- `inactive?` — activation below threshold
+- `to_h`
+
+### `Construal`
+
+A specific application of a construction to a scene.
+
+- `initialize(construction_id:, scene:, operation:, prominence:, construal_id: nil)`
+- `to_h`
+
+### `GrammarEngine`
+
+- `create_construction(name:, form:, meaning:, domain:)` — returns `{ created:, construction_id:, construction: }` or capacity error
+- `create_construal(construction_id:, scene:, operation:, prominence:)` — validates construction exists; appends to construal ring buffer
+- `use_construction(construction_id:)` — fires EMA update; returns before/after activation + entrenchment state
+- `entrenched_constructions(limit: 20)` — sorted by activation descending
+- `decay_all(rate: 0.01)` — decays all constructions
+- `prune_inactive(threshold: 0.05)` — removes constructions below activation floor
+- `constructions_by_domain` — groups by domain
+- `most_used(limit: 10)` — sorted by use_count
+- `grammar_report` — full stats
+
+## Runners
+
+**Module**: `Legion::Extensions::CognitiveGrammar::Runners::CognitiveGrammar`
+
+| Method | Key Args | Returns |
+|---|---|---|
+| `create_grammar_construction` | `name:`, `form:`, `meaning:`, `domain:` | `{ success:, construction_id:, construction: }` |
+| `create_grammar_construal` | `construction_id:`, `scene:`, `operation:`, `prominence:` | `{ success:, construal_id:, construal: }` |
+| `use_grammar_construction` | `construction_id:` | `{ success:, before:, after:, entrenched: }` |
+| `construals_for_scene_report` | `scene:` | `{ success:, construals: }` |
+| `entrenched_constructions_report` | `limit: 20` | `{ success:, constructions: }` |
+| `constructions_by_domain_report` | — | `{ success:, domains: }` |
+| `most_used_constructions` | `limit: 10` | `{ success:, constructions: }` |
+| `update_cognitive_grammar` | — | `{ success:, decayed: }` — runs decay pass |
+| `cognitive_grammar_stats` | — | engine `to_h` |
+
+Private: `grammar_engine` — memoized `GrammarEngine`. Logs via `log_debug` helper.
+
+## Integration Points
+
+- **`lex-tick`**: `update_cognitive_grammar` is the maintenance operation; can be wired into `memory_consolidation` or a dedicated grammar-maintenance phase.
+- **`lex-memory`**: Construction activation mirrors memory trace strength. Entrenched constructions could be co-stored as procedural memory traces in lex-memory for cross-extension retrieval.
+- **`lex-cognitive-flexibility`**: Switching task sets may require activating constructions appropriate to the new domain. Grammar constructions and task-set rules operate at complementary abstraction levels.
+
+## Development Notes
+
+- `use_construction` updates activation via EMA on each call. Frequent use rapidly entrenches a construction; infrequent use combined with periodic `decay_all` calls keeps the grammar network trimmed.
+- `prune_inactive` is destructive — constructions removed cannot be recovered. Call with a conservative threshold.
+- `construals_for_scene_report` searches the construal buffer for exact scene string matches.
+- In-memory only.
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,12 @@
+# 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/Gemfile.lock

@@ -0,0 +1,78 @@
+PATH
+  remote: .
+  specs:
+    lex-cognitive-grammar (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    diff-lcs (1.6.2)
+    json (2.19.1)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    mcp (0.8.0)
+      json-schema (>= 4.1)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  lex-cognitive-grammar!
+  rspec (~> 3.13)
+  rubocop (~> 1.75)
+  rubocop-rspec
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,56 @@
+# lex-cognitive-grammar
+
+Cognitive grammar construction network for brain-modeled agentic AI in the LegionIO ecosystem.
+
+## What It Does
+
+Models the mental grammar through which meaning is assembled. Constructions are symbolic form-meaning units that activate with use and decay when dormant. Construals represent specific applications of constructions to scenes using cognitive operations (profiling, figure-ground, scope, perspective). Each use of a construction strengthens its activation via Exponential Moving Average. Once activation crosses the entrenchment threshold (0.8), the construction becomes automatic. A periodic decay pass prunes underused constructions from the network.
+
+## Usage
+
+```ruby
+require 'legion/extensions/cognitive_grammar'
+
+client = Legion::Extensions::CognitiveGrammar::Client.new
+
+# Create a form-meaning construction
+result = client.create_grammar_construction(
+  name: 'caused_motion',
+  form: '[Agent VERB Theme Path]',
+  meaning: 'agent causes theme to move along path',
+  domain: :motion
+)
+construction_id = result[:construction_id]
+
+# Apply it to a scene (construal)
+client.create_grammar_construal(
+  construction_id: construction_id,
+  scene: 'pushing the idea forward',
+  operation: :figure_ground,
+  prominence: :trajector
+)
+
+# Record a use — updates EMA activation
+client.use_grammar_construction(construction_id: construction_id)
+# => { success: true, before: 0.3, after: 0.37, entrenched: false }
+
+# Check which constructions are entrenched
+client.entrenched_constructions_report(limit: 10)
+# => { success: true, constructions: [...] }
+
+# Periodic decay maintenance
+client.update_cognitive_grammar
+# => { success: true, decayed: 1 }
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-cognitive-grammar.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/cognitive_grammar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-cognitive-grammar'
+  spec.version       = Legion::Extensions::CognitiveGrammar::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Cognitive Grammar'
+  spec.description   = 'Langacker-inspired cognitive grammar engine for LegionIO — construal operations, construction entrenchment, and meaning as construal'
+  spec.homepage      = 'https://github.com/LegionIO/lex-cognitive-grammar'
+  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-grammar'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-cognitive-grammar'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-cognitive-grammar'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-cognitive-grammar/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_grammar/helpers/constants'
+require 'legion/extensions/cognitive_grammar/helpers/construction'
+require 'legion/extensions/cognitive_grammar/helpers/construal'
+require 'legion/extensions/cognitive_grammar/helpers/grammar_engine'
+require 'legion/extensions/cognitive_grammar/runners/cognitive_grammar'
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      class Client
+        include Runners::CognitiveGrammar
+
+        def initialize(**)
+          @engine = Helpers::GrammarEngine.new
+        end
+
+        private
+
+        attr_reader :engine
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      module Helpers
+        module Constants
+          CONSTRUAL_OPERATIONS = %i[perspective prominence specificity scope dynamicity].freeze
+          PROMINENCE_TYPES     = %i[figure ground].freeze
+          SPECIFICITY_LEVELS   = %i[schematic intermediate detailed].freeze
+          SCOPE_LEVELS         = %i[immediate local global].freeze
+          EXPRESSION_TYPES     = %i[nominal relational clausal].freeze
+
+          ACTIVATION_LABELS = {
+            (0.8..)     => :entrenched,
+            (0.6...0.8) => :conventional,
+            (0.4...0.6) => :familiar,
+            (0.2...0.4) => :novel,
+            (..0.2)     => :ad_hoc
+          }.freeze
+
+          MAX_CONSTRUCTIONS   = 200
+          MAX_CONSTRUALS      = 500
+          MAX_HISTORY         = 500
+
+          DEFAULT_ACTIVATION      = 0.3
+          ACTIVATION_BOOST        = 0.1
+          ACTIVATION_DECAY        = 0.02
+          ENTRENCHMENT_THRESHOLD  = 0.8
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_grammar/helpers/construal.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      module Helpers
+        class Construal
+          include Constants
+
+          attr_reader :id, :scene, :perspective, :figure, :ground, :specificity,
+                      :scope, :dynamicity, :construction_id, :created_at
+
+          def initialize(scene:, perspective:, figure:, ground:,
+                         specificity: :intermediate, scope: :local,
+                         dynamicity: 0.5, construction_id: nil)
+            @id              = SecureRandom.uuid
+            @scene           = scene
+            @perspective     = perspective
+            @figure          = figure
+            @ground          = ground
+            @specificity     = specificity.to_sym
+            @scope           = scope.to_sym
+            @dynamicity      = dynamicity.clamp(0.0, 1.0)
+            @construction_id = construction_id
+            @created_at      = Time.now.utc
+          end
+
+          def prominent_element
+            @figure
+          end
+
+          def background_element
+            @ground
+          end
+
+          def detailed?
+            @specificity == :detailed
+          end
+
+          def global_scope?
+            @scope == :global
+          end
+
+          def to_h
+            {
+              id:              @id,
+              scene:           @scene,
+              perspective:     @perspective,
+              figure:          @figure,
+              ground:          @ground,
+              specificity:     @specificity,
+              scope:           @scope,
+              dynamicity:      @dynamicity,
+              construction_id: @construction_id,
+              created_at:      @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_grammar/helpers/construction.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      module Helpers
+        class Construction
+          include Constants
+
+          attr_reader :id, :form, :meaning, :expression_type, :usage_count, :domain, :created_at
+          attr_accessor :activation
+
+          def initialize(form:, meaning:, expression_type:, domain:, activation: DEFAULT_ACTIVATION)
+            @id              = SecureRandom.uuid
+            @form            = form
+            @meaning         = meaning
+            @expression_type = expression_type.to_sym
+            @activation      = activation.clamp(0.0, 1.0)
+            @usage_count     = 0
+            @domain          = domain
+            @created_at      = Time.now.utc
+          end
+
+          def use!
+            @usage_count += 1
+            @activation = [@activation + ACTIVATION_BOOST, 1.0].min.round(10)
+            self
+          end
+
+          def decay!
+            @activation = [@activation - ACTIVATION_DECAY, 0.0].max
+            self
+          end
+
+          def entrenched?
+            @activation >= ENTRENCHMENT_THRESHOLD
+          end
+
+          def activation_label
+            match = ACTIVATION_LABELS.find { |range, _| range.cover?(@activation) }
+            match ? match.last : :ad_hoc
+          end
+
+          def to_h
+            {
+              id:               @id,
+              form:             @form,
+              meaning:          @meaning,
+              expression_type:  @expression_type,
+              activation:       @activation,
+              usage_count:      @usage_count,
+              domain:           @domain,
+              entrenched:       entrenched?,
+              activation_label: activation_label,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/cognitive_grammar/helpers/grammar_engine.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      module Helpers
+        class GrammarEngine
+          include Constants
+
+          def initialize
+            @constructions = {}
+            @construals    = {}
+          end
+
+          def create_construction(form:, meaning:, expression_type:, domain:, activation: DEFAULT_ACTIVATION)
+            prune_constructions_if_needed
+            construction = Construction.new(
+              form:            form,
+              meaning:         meaning,
+              expression_type: expression_type,
+              domain:          domain,
+              activation:      activation
+            )
+            @constructions[construction.id] = construction
+            construction
+          end
+
+          def create_construal(scene:, perspective:, figure:, ground:,
+                               specificity: :intermediate, scope: :local,
+                               dynamicity: 0.5, construction_id: nil)
+            prune_construals_if_needed
+            construal = Construal.new(
+              scene:           scene,
+              perspective:     perspective,
+              figure:          figure,
+              ground:          ground,
+              specificity:     specificity,
+              scope:           scope,
+              dynamicity:      dynamicity,
+              construction_id: construction_id
+            )
+            @construals[construal.id] = construal
+            construal
+          end
+
+          def use_construction(construction_id:)
+            construction = @constructions[construction_id]
+            return nil unless construction
+
+            construction.use!
+          end
+
+          def construals_for_scene(scene:)
+            @construals.values.select { |c| c.scene == scene }
+          end
+
+          def entrenched_constructions
+            @constructions.values.select(&:entrenched?)
+          end
+
+          def constructions_by_domain(domain:)
+            @constructions.values.select { |c| c.domain == domain }
+          end
+
+          def constructions_by_type(expression_type:)
+            type = expression_type.to_sym
+            @constructions.values.select { |c| c.expression_type == type }
+          end
+
+          def most_used(limit: 5)
+            @constructions.values.sort_by { |c| -c.usage_count }.first(limit)
+          end
+
+          def most_activated(limit: 5)
+            @constructions.values.sort_by { |c| -c.activation }.first(limit)
+          end
+
+          def decay_all
+            @constructions.each_value(&:decay!)
+          end
+
+          def prune_inactive
+            before = @constructions.size
+            @constructions.delete_if { |_, c| c.activation <= 0.05 }
+            before - @constructions.size
+          end
+
+          def to_h
+            {
+              constructions_count: @constructions.size,
+              construals_count:    @construals.size,
+              entrenched_count:    entrenched_constructions.size
+            }
+          end
+
+          private
+
+          def prune_constructions_if_needed
+            return if @constructions.size < MAX_CONSTRUCTIONS
+
+            oldest = @constructions.values.min_by(&:activation)
+            @constructions.delete(oldest.id) if oldest
+          end
+
+          def prune_construals_if_needed
+            return if @construals.size < MAX_CONSTRUALS
+
+            oldest = @construals.values.min_by(&:created_at)
+            @construals.delete(oldest.id) if oldest
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      module Runners
+        module CognitiveGrammar
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_grammar_construction(form:, meaning:, expression_type:, domain:, **)
+            construction = engine.create_construction(
+              form:            form,
+              meaning:         meaning,
+              expression_type: expression_type,
+              domain:          domain
+            )
+            Legion::Logging.debug "[cognitive_grammar] created construction form=#{form} type=#{expression_type} domain=#{domain}"
+            construction.to_h
+          end
+
+          def create_grammar_construal(scene:, perspective:, figure:, ground:, # rubocop:disable Metrics/ParameterLists
+                                       specificity: :intermediate, scope: :local,
+                                       dynamicity: 0.5, construction_id: nil, **)
+            construal = engine.create_construal(
+              scene:           scene,
+              perspective:     perspective,
+              figure:          figure,
+              ground:          ground,
+              specificity:     specificity,
+              scope:           scope,
+              dynamicity:      dynamicity,
+              construction_id: construction_id
+            )
+            Legion::Logging.debug "[cognitive_grammar] created construal scene=#{scene} figure=#{figure}"
+            construal.to_h
+          end
+
+          def use_grammar_construction(construction_id:, **)
+            construction = engine.use_construction(construction_id: construction_id)
+            return { found: false, construction_id: construction_id } unless construction
+
+            msg = "[cognitive_grammar] used construction id=#{construction_id[0..7]} " \
+                  "usage_count=#{construction.usage_count} activation=#{construction.activation.round(3)}"
+            Legion::Logging.debug msg
+            { found: true, construction: construction.to_h }
+          end
+
+          def construals_for_scene_report(scene:, **)
+            construals = engine.construals_for_scene(scene: scene)
+            Legion::Logging.debug "[cognitive_grammar] construals_for_scene scene=#{scene} count=#{construals.size}"
+            { scene: scene, count: construals.size, construals: construals.map(&:to_h) }
+          end
+
+          def entrenched_constructions_report(**)
+            constructions = engine.entrenched_constructions
+            Legion::Logging.debug "[cognitive_grammar] entrenched constructions count=#{constructions.size}"
+            { count: constructions.size, constructions: constructions.map(&:to_h) }
+          end
+
+          def constructions_by_domain_report(domain:, **)
+            constructions = engine.constructions_by_domain(domain: domain)
+            Legion::Logging.debug "[cognitive_grammar] constructions_by_domain domain=#{domain} count=#{constructions.size}"
+            { domain: domain, count: constructions.size, constructions: constructions.map(&:to_h) }
+          end
+
+          def most_used_constructions(limit: 5, **)
+            constructions = engine.most_used(limit: limit)
+            Legion::Logging.debug "[cognitive_grammar] most_used limit=#{limit} count=#{constructions.size}"
+            { limit: limit, count: constructions.size, constructions: constructions.map(&:to_h) }
+          end
+
+          def update_cognitive_grammar(**)
+            engine.decay_all
+            pruned = engine.prune_inactive
+            stats  = engine.to_h
+            Legion::Logging.debug "[cognitive_grammar] update: pruned=#{pruned} remaining=#{stats[:constructions_count]}"
+            { pruned: pruned, stats: stats }
+          end
+
+          def cognitive_grammar_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[cognitive_grammar] stats constructions=#{stats[:constructions_count]} construals=#{stats[:construals_count]}"
+            stats
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::GrammarEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/cognitive_grammar.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/cognitive_grammar/version'
+require 'legion/extensions/cognitive_grammar/helpers/constants'
+require 'legion/extensions/cognitive_grammar/helpers/construction'
+require 'legion/extensions/cognitive_grammar/helpers/construal'
+require 'legion/extensions/cognitive_grammar/helpers/grammar_engine'
+require 'legion/extensions/cognitive_grammar/runners/cognitive_grammar'
+require 'legion/extensions/cognitive_grammar/client'
+
+module Legion
+  module Extensions
+    module CognitiveGrammar
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: lex-cognitive-grammar
+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: Langacker-inspired cognitive grammar engine for LegionIO — construal
+  operations, construction entrenchment, and meaning as construal
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CLAUDE.md
+- Gemfile
+- Gemfile.lock
+- README.md
+- lex-cognitive-grammar.gemspec
+- lib/legion/extensions/cognitive_grammar.rb
+- lib/legion/extensions/cognitive_grammar/client.rb
+- lib/legion/extensions/cognitive_grammar/helpers/constants.rb
+- lib/legion/extensions/cognitive_grammar/helpers/construal.rb
+- lib/legion/extensions/cognitive_grammar/helpers/construction.rb
+- lib/legion/extensions/cognitive_grammar/helpers/grammar_engine.rb
+- lib/legion/extensions/cognitive_grammar/runners/cognitive_grammar.rb
+- lib/legion/extensions/cognitive_grammar/version.rb
+homepage: https://github.com/LegionIO/lex-cognitive-grammar
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-cognitive-grammar
+  source_code_uri: https://github.com/LegionIO/lex-cognitive-grammar
+  documentation_uri: https://github.com/LegionIO/lex-cognitive-grammar
+  changelog_uri: https://github.com/LegionIO/lex-cognitive-grammar
+  bug_tracker_uri: https://github.com/LegionIO/lex-cognitive-grammar/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 Grammar
+test_files: []