lex-agentic-language 0.1.0

data/lib/legion/extensions/agentic/language/frame_semantics/helpers/frame_engine.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          module Helpers
+            class FrameEngine
+              def initialize
+                @frames    = {}
+                @instances = []
+              end
+
+              def create_frame(name:, domain:, slots: {})
+                frame = Frame.new(name: name, domain: domain)
+                slots.each do |slot_name, opts|
+                  frame.add_slot(
+                    name:      slot_name,
+                    slot_type: opts.fetch(:type, :core),
+                    required:  opts.fetch(:required, true)
+                  )
+                end
+                prune_frames_if_full
+                @frames[frame.id] = frame
+                frame
+              end
+
+              def define_slot(frame_id:, name:, slot_type: :core, required: true)
+                frame = @frames[frame_id]
+                return nil unless frame
+
+                frame.add_slot(name: name, slot_type: slot_type, required: required)
+                frame
+              end
+
+              def fill_slot(frame_id:, slot_name:, filler:)
+                frame = @frames[frame_id]
+                return false unless frame
+
+                result = frame.fill_slot(name: slot_name, filler: filler)
+                frame.activate! if result
+                result
+              end
+
+              def instantiate_frame(frame_id:, context:, confidence: 0.7)
+                frame = @frames[frame_id]
+                return nil unless frame
+
+                fillers = frame.slots.transform_values { |v| v[:filler] }
+                instance = FrameInstance.new(
+                  frame_id:     frame_id,
+                  frame_name:   frame.name,
+                  slot_fillers: fillers,
+                  context:      context,
+                  confidence:   confidence
+                )
+                @instances << instance
+                @instances.shift while @instances.size > MAX_INSTANCES
+                instance
+              end
+
+              def add_frame_relation(frame_id:, relation:, target_frame_id:)
+                frame = @frames[frame_id]
+                return false unless frame
+                return false unless FRAME_RELATIONS.include?(relation)
+
+                frame.add_relation(relation: relation, target_frame_id: target_frame_id)
+                true
+              end
+
+              def activate_frame(frame_id:)
+                frame = @frames[frame_id]
+                return false unless frame
+
+                frame.activate!
+                true
+              end
+
+              def active_frames
+                @frames.values.select { |f| f.activation > 0.5 }
+              end
+
+              def frames_by_domain(domain:)
+                @frames.values.select { |f| f.domain == domain }
+              end
+
+              def related_frames(frame_id:)
+                frame = @frames[frame_id]
+                return [] unless frame
+
+                frame.relations.filter_map { |rel| @frames[rel[:target_frame_id]] }
+              end
+
+              def most_activated(limit: 5)
+                @frames.values.sort_by { |f| -f.activation }.first(limit)
+              end
+
+              def instances_for_frame(frame_id:)
+                @instances.select { |i| i.frame_id == frame_id }
+              end
+
+              def complete_frames
+                @frames.values.select(&:complete?)
+              end
+
+              def decay_all
+                @frames.each_value(&:decay!)
+              end
+
+              def prune_inactive
+                @frames.reject! { |_id, f| f.activation <= 0.05 }
+              end
+
+              def to_h
+                {
+                  frame_count:    @frames.size,
+                  instance_count: @instances.size,
+                  active_count:   active_frames.size,
+                  complete_count: complete_frames.size,
+                  domains:        @frames.values.map(&:domain).uniq.sort
+                }
+              end
+
+              private
+
+              def prune_frames_if_full
+                return unless @frames.size >= MAX_FRAMES
+
+                oldest = @frames.values.min_by(&:activation)
+                @frames.delete(oldest.id) if oldest
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics/helpers/frame_instance.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          module Helpers
+            class FrameInstance
+              attr_reader :id, :frame_id, :frame_name, :slot_fillers, :context, :confidence, :created_at
+
+              def initialize(frame_id:, frame_name:, slot_fillers:, context:, confidence: 0.7)
+                @id           = SecureRandom.uuid
+                @frame_id     = frame_id
+                @frame_name   = frame_name
+                @slot_fillers = slot_fillers.dup
+                @context      = context
+                @confidence   = confidence
+                @created_at   = Time.now.utc
+              end
+
+              def complete?
+                filled_count.positive?
+              end
+
+              def filled_count
+                @slot_fillers.count { |_k, v| !v.nil? }
+              end
+
+              def to_h
+                {
+                  id:           @id,
+                  frame_id:     @frame_id,
+                  frame_name:   @frame_name,
+                  slot_fillers: @slot_fillers,
+                  context:      @context,
+                  confidence:   @confidence,
+                  filled_count: filled_count,
+                  complete:     complete?,
+                  created_at:   @created_at
+                }
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics/runners/frame_semantics.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          module Runners
+            module FrameSemantics
+              def create_semantic_frame(name:, domain:, **)
+                frame = engine.create_frame(name: name, domain: domain)
+                Legion::Logging.debug "[frame_semantics] created frame name=#{name} domain=#{domain} id=#{frame.id[0..7]}"
+                { frame_id: frame.id, name: frame.name, domain: frame.domain, created: true }
+              end
+
+              def define_frame_slot(frame_id:, name:, slot_type: :core, required: true, **)
+                frame = engine.define_slot(frame_id: frame_id, name: name, slot_type: slot_type, required: required)
+                if frame
+                  Legion::Logging.debug "[frame_semantics] defined slot #{name} on frame #{frame_id[0..7]}"
+                  { defined: true, frame_id: frame_id, slot_name: name, slot_type: slot_type }
+                else
+                  { defined: false, reason: :frame_not_found }
+                end
+              end
+
+              def fill_frame_slot(frame_id:, slot_name:, filler:, **)
+                result = engine.fill_slot(frame_id: frame_id, slot_name: slot_name, filler: filler)
+                if result
+                  Legion::Logging.debug "[frame_semantics] filled slot #{slot_name} on frame #{frame_id[0..7]}"
+                  { filled: true, frame_id: frame_id, slot_name: slot_name, filler: filler }
+                else
+                  { filled: false, reason: :slot_or_frame_not_found }
+                end
+              end
+
+              def instantiate_semantic_frame(frame_id:, context:, confidence: 0.7, **)
+                instance = engine.instantiate_frame(frame_id: frame_id, context: context, confidence: confidence)
+                if instance
+                  Legion::Logging.debug "[frame_semantics] instantiated frame #{frame_id[0..7]} instance=#{instance.id[0..7]}"
+                  { instantiated: true, instance_id: instance.id, frame_id: frame_id,
+                    filled_count: instance.filled_count }
+                else
+                  { instantiated: false, reason: :frame_not_found }
+                end
+              end
+
+              def add_frame_relation(frame_id:, relation:, target_frame_id:, **)
+                result = engine.add_frame_relation(frame_id: frame_id, relation: relation,
+                                                   target_frame_id: target_frame_id)
+                if result
+                  Legion::Logging.debug "[frame_semantics] added relation #{relation} #{frame_id[0..7]}->#{target_frame_id[0..7]}"
+                  { added: true, frame_id: frame_id, relation: relation, target_frame_id: target_frame_id }
+                else
+                  { added: false, reason: :invalid_frame_or_relation }
+                end
+              end
+
+              def activate_semantic_frame(frame_id:, **)
+                result = engine.activate_frame(frame_id: frame_id)
+                if result
+                  Legion::Logging.debug "[frame_semantics] activated frame #{frame_id[0..7]}"
+                  { activated: true, frame_id: frame_id }
+                else
+                  { activated: false, reason: :frame_not_found }
+                end
+              end
+
+              def active_frames_report(**)
+                frames = engine.active_frames
+                Legion::Logging.debug "[frame_semantics] active_frames count=#{frames.size}"
+                { frames: frames.map(&:to_h), count: frames.size }
+              end
+
+              def related_frames_report(frame_id:, **)
+                frames = engine.related_frames(frame_id: frame_id)
+                Legion::Logging.debug "[frame_semantics] related_frames frame=#{frame_id[0..7]} count=#{frames.size}"
+                { frames: frames.map(&:to_h), count: frames.size }
+              end
+
+              def complete_frames_report(**)
+                frames = engine.complete_frames
+                Legion::Logging.debug "[frame_semantics] complete_frames count=#{frames.size}"
+                { frames: frames.map(&:to_h), count: frames.size }
+              end
+
+              def update_frame_semantics(**)
+                engine.decay_all
+                engine.prune_inactive
+                Legion::Logging.debug '[frame_semantics] decay_all + prune_inactive complete'
+                { updated: true, stats: engine.to_h }
+              end
+
+              def frame_semantics_stats(**)
+                engine.to_h
+              end
+
+              private
+
+              def engine
+                @engine ||= Helpers::FrameEngine.new
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+          VERSION = '0.1.0'
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/frame_semantics.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/agentic/language/frame_semantics/version'
+require 'legion/extensions/agentic/language/frame_semantics/helpers/constants'
+require 'legion/extensions/agentic/language/frame_semantics/helpers/frame'
+require 'legion/extensions/agentic/language/frame_semantics/helpers/frame_instance'
+require 'legion/extensions/agentic/language/frame_semantics/helpers/frame_engine'
+require 'legion/extensions/agentic/language/frame_semantics/runners/frame_semantics'
+require 'legion/extensions/agentic/language/frame_semantics/helpers/client'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module FrameSemantics
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/agentic/language/grammar/client.rb

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

data/lib/legion/extensions/agentic/language/grammar/helpers/constants.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Grammar
+          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
+  end
+end

data/lib/legion/extensions/agentic/language/grammar/helpers/construal.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Grammar
+          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
+  end
+end

data/lib/legion/extensions/agentic/language/grammar/helpers/construction.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Grammar
+          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
+  end
+end

data/lib/legion/extensions/agentic/language/grammar/helpers/grammar_engine.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Agentic
+      module Language
+        module Grammar
+          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
+  end
+end