lex-frame-semantics 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2fd7637ea32eaf9de85020e859dfd65525545fcde99f19b1ec0e6f83caa248e
+  data.tar.gz: 7127f8ba47ae7f06f339c62586bebbe44389d338a3a3a990faca109357517451
+SHA512:
+  metadata.gz: c979ec6a48383fa8b5b1c34af874d011ee9cfe1ffd7f6c5a7eb91921f88643474da0ae9ee860d048c414c80a6d5b4d84a39fdd309f01115356b3842f323256b7
+  data.tar.gz: c2516c54bac8155ac8209c5b3579eb393b3147a55d686a516c57bd285ab647ce933bb4b73facb6de5a18d1529748bf8db6d7e32574741cf5ae8ea2596a7dfbaf

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/lex-frame-semantics.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/frame_semantics/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-frame-semantics'
+  spec.version       = Legion::Extensions::FrameSemantics::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Frame Semantics'
+  spec.description   = "Fillmore's Frame Semantics engine for LegionIO — conceptual frame activation, slot filling, and instance creation"
+  spec.homepage      = 'https://github.com/LegionIO/lex-frame-semantics'
+  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-frame-semantics'
+  spec.metadata['documentation_uri']   = 'https://github.com/LegionIO/lex-frame-semantics'
+  spec.metadata['changelog_uri']       = 'https://github.com/LegionIO/lex-frame-semantics'
+  spec.metadata['bug_tracker_uri']     = 'https://github.com/LegionIO/lex-frame-semantics/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-frame-semantics.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

data/lib/legion/extensions/frame_semantics/helpers/client.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FrameSemantics
+      module Helpers
+        class Client
+          include Runners::FrameSemantics
+
+          private
+
+          def engine
+            @engine ||= FrameEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module FrameSemantics
+      module Helpers
+        SLOT_TYPES        = %i[core peripheral extra_thematic].freeze
+        FRAME_RELATIONS   = %i[inherits_from is_inherited_by uses is_used_by subframe_of has_subframe].freeze
+        ACTIVATION_LABELS = {
+          (0.8..)     => :dominant,
+          (0.6...0.8) => :active,
+          (0.4...0.6) => :primed,
+          (0.2...0.4) => :latent,
+          (..0.2)     => :inactive
+        }.freeze
+
+        MAX_FRAMES         = 150
+        MAX_INSTANCES      = 500
+        MAX_HISTORY        = 500
+        DEFAULT_ACTIVATION = 0.3
+        ACTIVATION_BOOST   = 0.15
+        ACTIVATION_DECAY   = 0.03
+        SLOT_FILL_BOOST    = 0.1
+        COMPLETION_THRESHOLD = 0.7
+      end
+    end
+  end
+end

data/lib/legion/extensions/frame_semantics/helpers/frame.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module FrameSemantics
+      module Helpers
+        class Frame
+          attr_reader :id, :name, :domain, :slots, :relations, :activation, :activation_count, :created_at
+
+          def initialize(name:, domain:)
+            @id               = SecureRandom.uuid
+            @name             = name
+            @domain           = domain
+            @slots            = {}
+            @relations        = []
+            @activation       = DEFAULT_ACTIVATION
+            @activation_count = 0
+            @created_at       = Time.now.utc
+          end
+
+          def add_slot(name:, slot_type: :core, required: true)
+            @slots[name] = { type: slot_type, filler: nil, required: required }
+            self
+          end
+
+          def fill_slot(name:, filler:)
+            return false unless @slots.key?(name)
+
+            @slots[name][:filler] = filler
+            @activation = [@activation + SLOT_FILL_BOOST, 1.0].min
+            true
+          end
+
+          def clear_slot(name:)
+            return false unless @slots.key?(name)
+
+            @slots[name][:filler] = nil
+            true
+          end
+
+          def core_slots
+            @slots.select { |_k, v| v[:type] == :core }
+          end
+
+          def filled_slots
+            @slots.reject { |_k, v| v[:filler].nil? }
+          end
+
+          def completion_ratio
+            cs = core_slots
+            return 0.0 if cs.empty?
+
+            filled_core = cs.count { |_k, v| !v[:filler].nil? }
+            filled_core.to_f / cs.size
+          end
+
+          def complete?
+            completion_ratio >= COMPLETION_THRESHOLD
+          end
+
+          def activate!
+            @activation = [@activation + ACTIVATION_BOOST, 1.0].min
+            @activation_count += 1
+            self
+          end
+
+          def decay!
+            @activation = [@activation - ACTIVATION_DECAY, 0.0].max
+            self
+          end
+
+          def activation_label
+            ACTIVATION_LABELS.each do |range, label|
+              return label if range.cover?(@activation)
+            end
+            :inactive
+          end
+
+          def add_relation(relation:, target_frame_id:)
+            @relations << { relation: relation, target_frame_id: target_frame_id }
+            self
+          end
+
+          def to_h
+            {
+              id:               @id,
+              name:             @name,
+              domain:           @domain,
+              slots:            @slots,
+              relations:        @relations,
+              activation:       @activation,
+              activation_label: activation_label,
+              activation_count: @activation_count,
+              completion_ratio: completion_ratio,
+              complete:         complete?,
+              created_at:       @created_at
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    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

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    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

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

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

data/lib/legion/extensions/frame_semantics.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/frame_semantics/version'
+require 'legion/extensions/frame_semantics/helpers/constants'
+require 'legion/extensions/frame_semantics/helpers/frame'
+require 'legion/extensions/frame_semantics/helpers/frame_instance'
+require 'legion/extensions/frame_semantics/helpers/frame_engine'
+require 'legion/extensions/frame_semantics/runners/frame_semantics'
+require 'legion/extensions/frame_semantics/helpers/client'
+
+module Legion
+  module Extensions
+    module FrameSemantics
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/frame_semantics/helpers/frame_engine_spec.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::FrameSemantics::Helpers::FrameEngine do
+  subject(:engine) { described_class.new }
+
+  let(:frame) { engine.create_frame(name: :commercial_transaction, domain: :commerce) }
+
+  before do
+    frame.add_slot(name: :buyer)
+    frame.add_slot(name: :seller)
+    frame.add_slot(name: :goods)
+  end
+
+  describe '#create_frame' do
+    it 'returns a Frame object' do
+      f = engine.create_frame(name: :motion, domain: :physics)
+      expect(f).to be_a(Legion::Extensions::FrameSemantics::Helpers::Frame)
+    end
+
+    it 'creates frame with slots from hash' do
+      f = engine.create_frame(
+        name:   :competition,
+        domain: :sports,
+        slots:  { winner: { type: :core, required: true }, loser: { type: :peripheral, required: false } }
+      )
+      expect(f.slots[:winner][:type]).to eq(:core)
+      expect(f.slots[:loser][:type]).to eq(:peripheral)
+    end
+  end
+
+  describe '#define_slot' do
+    it 'adds a slot to an existing frame' do
+      result = engine.define_slot(frame_id: frame.id, name: :price)
+      expect(result).to be_a(Legion::Extensions::FrameSemantics::Helpers::Frame)
+      expect(frame.slots[:price]).not_to be_nil
+    end
+
+    it 'returns nil for unknown frame_id' do
+      expect(engine.define_slot(frame_id: 'bogus', name: :price)).to be_nil
+    end
+  end
+
+  describe '#fill_slot' do
+    it 'fills a slot and returns true' do
+      expect(engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')).to be true
+    end
+
+    it 'returns false for unknown frame' do
+      expect(engine.fill_slot(frame_id: 'bogus', slot_name: :buyer, filler: 'x')).to be false
+    end
+
+    it 'activates the frame when slot is filled' do
+      initial = frame.activation
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')
+      expect(frame.activation_count).to be >= 1
+      expect(frame.activation).to be >= initial
+    end
+  end
+
+  describe '#instantiate_frame' do
+    before do
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')
+      engine.fill_slot(frame_id: frame.id, slot_name: :seller, filler: 'Bob')
+    end
+
+    it 'creates a FrameInstance snapshot' do
+      inst = engine.instantiate_frame(frame_id: frame.id, context: 'coffee shop')
+      expect(inst).to be_a(Legion::Extensions::FrameSemantics::Helpers::FrameInstance)
+      expect(inst.frame_id).to eq(frame.id)
+      expect(inst.context).to eq('coffee shop')
+    end
+
+    it 'returns nil for unknown frame' do
+      expect(engine.instantiate_frame(frame_id: 'bogus', context: 'x')).to be_nil
+    end
+
+    it 'snapshots current slot fillers' do
+      inst = engine.instantiate_frame(frame_id: frame.id, context: 'test')
+      expect(inst.slot_fillers[:buyer]).to eq('Alice')
+    end
+  end
+
+  describe '#add_frame_relation' do
+    it 'adds a valid relation' do
+      target = engine.create_frame(name: :transfer, domain: :commerce)
+      result = engine.add_frame_relation(
+        frame_id:        frame.id,
+        relation:        :has_subframe,
+        target_frame_id: target.id
+      )
+      expect(result).to be true
+      expect(frame.relations.size).to eq(1)
+    end
+
+    it 'rejects invalid relation type' do
+      result = engine.add_frame_relation(
+        frame_id:        frame.id,
+        relation:        :invalid_relation,
+        target_frame_id: SecureRandom.uuid
+      )
+      expect(result).to be false
+    end
+
+    it 'returns false for unknown frame_id' do
+      expect(
+        engine.add_frame_relation(frame_id: 'bogus', relation: :uses, target_frame_id: SecureRandom.uuid)
+      ).to be false
+    end
+  end
+
+  describe '#activate_frame' do
+    it 'activates an existing frame' do
+      initial_count = frame.activation_count
+      engine.activate_frame(frame_id: frame.id)
+      expect(frame.activation_count).to eq(initial_count + 1)
+    end
+
+    it 'returns false for unknown frame' do
+      expect(engine.activate_frame(frame_id: 'bogus')).to be false
+    end
+  end
+
+  describe '#active_frames' do
+    it 'returns frames with activation > 0.5' do
+      5.times { engine.activate_frame(frame_id: frame.id) }
+      expect(engine.active_frames).to include(frame)
+    end
+
+    it 'excludes frames below threshold' do
+      new_engine = described_class.new
+      f = new_engine.create_frame(name: :cold, domain: :test)
+      100.times { f.decay! }
+      expect(new_engine.active_frames).not_to include(f)
+    end
+  end
+
+  describe '#frames_by_domain' do
+    before do
+      engine.create_frame(name: :motion, domain: :physics)
+      engine.create_frame(name: :competition, domain: :sports)
+    end
+
+    it 'returns only frames matching the domain' do
+      result = engine.frames_by_domain(domain: :physics)
+      expect(result.map(&:domain)).to all(eq(:physics))
+    end
+  end
+
+  describe '#related_frames' do
+    it 'traverses relations to return related frames' do
+      target = engine.create_frame(name: :payment, domain: :commerce)
+      engine.add_frame_relation(frame_id: frame.id, relation: :has_subframe, target_frame_id: target.id)
+      related = engine.related_frames(frame_id: frame.id)
+      expect(related).to include(target)
+    end
+
+    it 'returns empty array for unknown frame' do
+      expect(engine.related_frames(frame_id: 'bogus')).to eq([])
+    end
+  end
+
+  describe '#most_activated' do
+    it 'returns top N frames sorted by activation desc' do
+      f2 = engine.create_frame(name: :motion, domain: :physics)
+      5.times { engine.activate_frame(frame_id: frame.id) }
+      result = engine.most_activated(limit: 2)
+      expect(result.first).to eq(frame)
+      expect(result).not_to include(f2) if result.size < 2
+    end
+  end
+
+  describe '#instances_for_frame' do
+    it 'returns all instances of a specific frame' do
+      engine.instantiate_frame(frame_id: frame.id, context: 'ctx1')
+      engine.instantiate_frame(frame_id: frame.id, context: 'ctx2')
+      expect(engine.instances_for_frame(frame_id: frame.id).size).to eq(2)
+    end
+  end
+
+  describe '#complete_frames' do
+    it 'returns only complete frames' do
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer,  filler: 'Alice')
+      engine.fill_slot(frame_id: frame.id, slot_name: :seller, filler: 'Bob')
+      engine.fill_slot(frame_id: frame.id, slot_name: :goods,  filler: 'coffee')
+      expect(engine.complete_frames).to include(frame)
+    end
+
+    it 'excludes incomplete frames' do
+      engine.fill_slot(frame_id: frame.id, slot_name: :buyer, filler: 'Alice')
+      expect(engine.complete_frames).not_to include(frame)
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all frame activations' do
+      initial = frame.activation
+      engine.decay_all
+      expect(frame.activation).to be < initial
+    end
+  end
+
+  describe '#prune_inactive' do
+    it 'removes frames with activation <= 0.05' do
+      f = engine.create_frame(name: :ghost, domain: :test)
+      100.times { f.decay! }
+      engine.prune_inactive
+      expect(engine.instances_for_frame(frame_id: f.id)).to be_empty
+    end
+
+    it 'retains frames with activation above threshold' do
+      5.times { engine.activate_frame(frame_id: frame.id) }
+      engine.prune_inactive
+      expect(engine.active_frames).to include(frame)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns stats hash with expected keys' do
+      h = engine.to_h
+      expect(h).to include(:frame_count, :instance_count, :active_count, :complete_count, :domains)
+    end
+
+    it 'reflects current state' do
+      expect(engine.to_h[:frame_count]).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/frame_semantics/helpers/frame_instance_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::FrameSemantics::Helpers::FrameInstance do
+  let(:frame_id)    { SecureRandom.uuid }
+  let(:frame_name)  { :commercial_transaction }
+  let(:slot_fillers) do
+    { buyer: 'Alice', seller: 'Bob', goods: nil }
+  end
+
+  subject(:instance) do
+    described_class.new(
+      frame_id:     frame_id,
+      frame_name:   frame_name,
+      slot_fillers: slot_fillers,
+      context:      'buying coffee',
+      confidence:   0.85
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(instance.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores frame metadata' do
+      expect(instance.frame_id).to eq(frame_id)
+      expect(instance.frame_name).to eq(frame_name)
+    end
+
+    it 'duplicates slot_fillers' do
+      inst = instance
+      slot_fillers[:buyer] = 'Charlie'
+      expect(inst.slot_fillers[:buyer]).to eq('Alice')
+    end
+
+    it 'stores context and confidence' do
+      expect(instance.context).to eq('buying coffee')
+      expect(instance.confidence).to eq(0.85)
+    end
+  end
+
+  describe '#filled_count' do
+    it 'counts non-nil fillers' do
+      expect(instance.filled_count).to eq(2)
+    end
+
+    it 'returns 0 when all fillers are nil' do
+      empty = described_class.new(
+        frame_id: frame_id, frame_name: frame_name,
+        slot_fillers: { buyer: nil }, context: 'x'
+      )
+      expect(empty.filled_count).to eq(0)
+    end
+  end
+
+  describe '#complete?' do
+    it 'returns true when at least one slot is filled' do
+      expect(instance.complete?).to be true
+    end
+
+    it 'returns false when all slots are nil' do
+      empty = described_class.new(
+        frame_id: frame_id, frame_name: frame_name,
+        slot_fillers: { buyer: nil }, context: 'x'
+      )
+      expect(empty.complete?).to be false
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns expected keys' do
+      h = instance.to_h
+      expect(h).to include(:id, :frame_id, :frame_name, :slot_fillers,
+                           :context, :confidence, :filled_count, :complete, :created_at)
+    end
+
+    it 'includes filled_count and complete flag' do
+      h = instance.to_h
+      expect(h[:filled_count]).to eq(2)
+      expect(h[:complete]).to be true
+    end
+  end
+end

data/spec/legion/extensions/frame_semantics/helpers/frame_spec.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::FrameSemantics::Helpers::Frame do
+  subject(:frame) { described_class.new(name: :commercial_transaction, domain: :commerce) }
+
+  describe '#initialize' do
+    it 'assigns a uuid id' do
+      expect(frame.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets name and domain' do
+      expect(frame.name).to eq(:commercial_transaction)
+      expect(frame.domain).to eq(:commerce)
+    end
+
+    it 'starts with default activation' do
+      expect(frame.activation).to eq(Legion::Extensions::FrameSemantics::Helpers::DEFAULT_ACTIVATION)
+    end
+
+    it 'starts with zero activation_count' do
+      expect(frame.activation_count).to eq(0)
+    end
+
+    it 'starts with empty slots and relations' do
+      expect(frame.slots).to be_empty
+      expect(frame.relations).to be_empty
+    end
+  end
+
+  describe '#add_slot' do
+    it 'adds a core slot by default' do
+      frame.add_slot(name: :buyer)
+      expect(frame.slots[:buyer][:type]).to eq(:core)
+      expect(frame.slots[:buyer][:required]).to be true
+      expect(frame.slots[:buyer][:filler]).to be_nil
+    end
+
+    it 'adds a peripheral slot when specified' do
+      frame.add_slot(name: :payment_method, slot_type: :peripheral, required: false)
+      expect(frame.slots[:payment_method][:type]).to eq(:peripheral)
+      expect(frame.slots[:payment_method][:required]).to be false
+    end
+
+    it 'returns self for chaining' do
+      result = frame.add_slot(name: :seller)
+      expect(result).to be(frame)
+    end
+  end
+
+  describe '#fill_slot' do
+    before { frame.add_slot(name: :buyer) }
+
+    it 'fills a slot and returns true' do
+      result = frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(result).to be true
+      expect(frame.slots[:buyer][:filler]).to eq('Alice')
+    end
+
+    it 'boosts activation when slot is filled' do
+      initial = frame.activation
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.activation).to be > initial
+    end
+
+    it 'returns false for unknown slot' do
+      expect(frame.fill_slot(name: :unknown, filler: 'x')).to be false
+    end
+  end
+
+  describe '#clear_slot' do
+    before do
+      frame.add_slot(name: :buyer)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+    end
+
+    it 'clears the slot filler' do
+      frame.clear_slot(name: :buyer)
+      expect(frame.slots[:buyer][:filler]).to be_nil
+    end
+
+    it 'returns true for existing slot' do
+      expect(frame.clear_slot(name: :buyer)).to be true
+    end
+
+    it 'returns false for unknown slot' do
+      expect(frame.clear_slot(name: :ghost)).to be false
+    end
+  end
+
+  describe '#core_slots' do
+    before do
+      frame.add_slot(name: :buyer, slot_type: :core)
+      frame.add_slot(name: :seller, slot_type: :core)
+      frame.add_slot(name: :note, slot_type: :peripheral)
+    end
+
+    it 'returns only core slots' do
+      expect(frame.core_slots.keys).to contain_exactly(:buyer, :seller)
+    end
+  end
+
+  describe '#filled_slots' do
+    before do
+      frame.add_slot(name: :buyer)
+      frame.add_slot(name: :seller)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+    end
+
+    it 'returns only filled slots' do
+      expect(frame.filled_slots.keys).to eq([:buyer])
+    end
+  end
+
+  describe '#completion_ratio' do
+    it 'returns 0.0 with no slots' do
+      expect(frame.completion_ratio).to eq(0.0)
+    end
+
+    it 'returns correct fraction of filled core slots' do
+      frame.add_slot(name: :buyer)
+      frame.add_slot(name: :seller)
+      frame.add_slot(name: :goods)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.completion_ratio).to be_within(0.001).of(1.0 / 3.0)
+    end
+
+    it 'ignores peripheral slots in ratio' do
+      frame.add_slot(name: :buyer, slot_type: :core)
+      frame.add_slot(name: :note, slot_type: :peripheral)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.completion_ratio).to eq(1.0)
+    end
+  end
+
+  describe '#complete?' do
+    it 'returns false when completion is below threshold' do
+      frame.add_slot(name: :buyer)
+      frame.add_slot(name: :seller)
+      frame.add_slot(name: :goods)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.complete?).to be false
+    end
+
+    it 'returns true when all core slots are filled' do
+      frame.add_slot(name: :buyer)
+      frame.fill_slot(name: :buyer, filler: 'Alice')
+      expect(frame.complete?).to be true
+    end
+  end
+
+  describe '#activate!' do
+    it 'boosts activation and increments count' do
+      initial = frame.activation
+      frame.activate!
+      expect(frame.activation).to be > initial
+      expect(frame.activation_count).to eq(1)
+    end
+
+    it 'clamps activation at 1.0' do
+      10.times { frame.activate! }
+      expect(frame.activation).to eq(1.0)
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces activation' do
+      initial = frame.activation
+      frame.decay!
+      expect(frame.activation).to be < initial
+    end
+
+    it 'clamps activation at 0.0' do
+      100.times { frame.decay! }
+      expect(frame.activation).to eq(0.0)
+    end
+  end
+
+  describe '#activation_label' do
+    it 'returns :dominant for high activation' do
+      10.times { frame.activate! }
+      expect(frame.activation_label).to eq(:dominant)
+    end
+
+    it 'returns :inactive for very low activation' do
+      100.times { frame.decay! }
+      expect(frame.activation_label).to eq(:inactive)
+    end
+
+    it 'returns :primed for mid activation around 0.5' do
+      frame.instance_variable_set(:@activation, 0.5)
+      expect(frame.activation_label).to eq(:primed)
+    end
+  end
+
+  describe '#add_relation' do
+    it 'appends a relation entry' do
+      other_id = SecureRandom.uuid
+      frame.add_relation(relation: :inherits_from, target_frame_id: other_id)
+      expect(frame.relations.size).to eq(1)
+      expect(frame.relations.first[:relation]).to eq(:inherits_from)
+      expect(frame.relations.first[:target_frame_id]).to eq(other_id)
+    end
+  end
+
+  describe '#to_h' do
+    it 'returns a hash with expected keys' do
+      h = frame.to_h
+      expect(h).to include(:id, :name, :domain, :slots, :relations,
+                           :activation, :activation_label, :activation_count,
+                           :completion_ratio, :complete, :created_at)
+    end
+  end
+end

data/spec/legion/extensions/frame_semantics/runners/frame_semantics_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/frame_semantics/helpers/client'
+
+RSpec.describe Legion::Extensions::FrameSemantics::Runners::FrameSemantics do
+  let(:client) { Legion::Extensions::FrameSemantics::Helpers::Client.new }
+
+  describe '#create_semantic_frame' do
+    it 'creates a frame and returns its id' do
+      result = client.create_semantic_frame(name: :commercial_transaction, domain: :commerce)
+      expect(result[:created]).to be true
+      expect(result[:frame_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:name]).to eq(:commercial_transaction)
+    end
+  end
+
+  describe '#define_frame_slot' do
+    let(:frame_id) { client.create_semantic_frame(name: :motion, domain: :physics)[:frame_id] }
+
+    it 'adds a slot to a known frame' do
+      result = client.define_frame_slot(frame_id: frame_id, name: :mover)
+      expect(result[:defined]).to be true
+      expect(result[:slot_name]).to eq(:mover)
+    end
+
+    it 'returns not found for unknown frame' do
+      result = client.define_frame_slot(frame_id: 'bogus', name: :mover)
+      expect(result[:defined]).to be false
+      expect(result[:reason]).to eq(:frame_not_found)
+    end
+  end
+
+  describe '#fill_frame_slot' do
+    let(:frame_id) do
+      id = client.create_semantic_frame(name: :motion, domain: :physics)[:frame_id]
+      client.define_frame_slot(frame_id: id, name: :mover)
+      id
+    end
+
+    it 'fills an existing slot' do
+      result = client.fill_frame_slot(frame_id: frame_id, slot_name: :mover, filler: 'the car')
+      expect(result[:filled]).to be true
+      expect(result[:filler]).to eq('the car')
+    end
+
+    it 'returns error for unknown slot' do
+      result = client.fill_frame_slot(frame_id: frame_id, slot_name: :nonexistent, filler: 'x')
+      expect(result[:filled]).to be false
+    end
+  end
+
+  describe '#instantiate_semantic_frame' do
+    let(:frame_id) do
+      id = client.create_semantic_frame(name: :motion, domain: :physics)[:frame_id]
+      client.define_frame_slot(frame_id: id, name: :mover)
+      client.fill_frame_slot(frame_id: id, slot_name: :mover, filler: 'rocket')
+      id
+    end
+
+    it 'creates an instance snapshot' do
+      result = client.instantiate_semantic_frame(frame_id: frame_id, context: 'test context')
+      expect(result[:instantiated]).to be true
+      expect(result[:instance_id]).to match(/\A[0-9a-f-]{36}\z/)
+      expect(result[:filled_count]).to eq(1)
+    end
+
+    it 'returns error for unknown frame' do
+      result = client.instantiate_semantic_frame(frame_id: 'bogus', context: 'x')
+      expect(result[:instantiated]).to be false
+    end
+  end
+
+  describe '#add_frame_relation' do
+    let(:frame_id)  { client.create_semantic_frame(name: :transfer,  domain: :commerce)[:frame_id] }
+    let(:target_id) { client.create_semantic_frame(name: :payment,   domain: :commerce)[:frame_id] }
+
+    it 'adds a valid frame relation' do
+      result = client.add_frame_relation(
+        frame_id: frame_id, relation: :has_subframe, target_frame_id: target_id
+      )
+      expect(result[:added]).to be true
+    end
+
+    it 'rejects an invalid relation' do
+      result = client.add_frame_relation(
+        frame_id: frame_id, relation: :nonsense, target_frame_id: target_id
+      )
+      expect(result[:added]).to be false
+    end
+  end
+
+  describe '#activate_semantic_frame' do
+    let(:frame_id) { client.create_semantic_frame(name: :competition, domain: :sports)[:frame_id] }
+
+    it 'activates the frame' do
+      result = client.activate_semantic_frame(frame_id: frame_id)
+      expect(result[:activated]).to be true
+    end
+
+    it 'returns error for unknown frame' do
+      result = client.activate_semantic_frame(frame_id: 'bogus')
+      expect(result[:activated]).to be false
+    end
+  end
+
+  describe '#active_frames_report' do
+    it 'returns list of active frames' do
+      id = client.create_semantic_frame(name: :competition, domain: :sports)[:frame_id]
+      4.times { client.activate_semantic_frame(frame_id: id) }
+      result = client.active_frames_report
+      expect(result).to have_key(:frames)
+      expect(result).to have_key(:count)
+    end
+  end
+
+  describe '#related_frames_report' do
+    let(:frame_id)  { client.create_semantic_frame(name: :buying, domain: :commerce)[:frame_id] }
+    let(:target_id) { client.create_semantic_frame(name: :paying, domain: :commerce)[:frame_id] }
+
+    before { client.add_frame_relation(frame_id: frame_id, relation: :has_subframe, target_frame_id: target_id) }
+
+    it 'returns related frames' do
+      result = client.related_frames_report(frame_id: frame_id)
+      expect(result[:count]).to eq(1)
+      expect(result[:frames].first[:id]).to eq(target_id)
+    end
+  end
+
+  describe '#complete_frames_report' do
+    it 'returns complete frames' do
+      id = client.create_semantic_frame(name: :simple, domain: :test)[:frame_id]
+      client.define_frame_slot(frame_id: id, name: :actor)
+      client.fill_frame_slot(frame_id: id, slot_name: :actor, filler: 'someone')
+      result = client.complete_frames_report
+      expect(result[:count]).to be >= 1
+    end
+  end
+
+  describe '#update_frame_semantics' do
+    it 'runs decay and prune, returning updated status' do
+      result = client.update_frame_semantics
+      expect(result[:updated]).to be true
+      expect(result[:stats]).to have_key(:frame_count)
+    end
+  end
+
+  describe '#frame_semantics_stats' do
+    it 'returns engine stats' do
+      client.create_semantic_frame(name: :motion, domain: :physics)
+      result = client.frame_semantics_stats
+      expect(result[:frame_count]).to be >= 1
+      expect(result).to have_key(:domains)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+module Legion
+  module Logging
+    def self.debug(_msg); end
+    def self.info(_msg); end
+    def self.warn(_msg); end
+    def self.error(_msg); end
+  end
+end
+
+require 'legion/extensions/frame_semantics'
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = '.rspec_status'
+  config.disable_monkey_patching!
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: lex-frame-semantics
+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: Fillmore's Frame Semantics engine for LegionIO — conceptual frame activation,
+  slot filling, and instance creation
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- lex-frame-semantics.gemspec
+- lib/legion/extensions/frame_semantics.rb
+- lib/legion/extensions/frame_semantics/helpers/client.rb
+- lib/legion/extensions/frame_semantics/helpers/constants.rb
+- lib/legion/extensions/frame_semantics/helpers/frame.rb
+- lib/legion/extensions/frame_semantics/helpers/frame_engine.rb
+- lib/legion/extensions/frame_semantics/helpers/frame_instance.rb
+- lib/legion/extensions/frame_semantics/runners/frame_semantics.rb
+- lib/legion/extensions/frame_semantics/version.rb
+- spec/legion/extensions/frame_semantics/helpers/frame_engine_spec.rb
+- spec/legion/extensions/frame_semantics/helpers/frame_instance_spec.rb
+- spec/legion/extensions/frame_semantics/helpers/frame_spec.rb
+- spec/legion/extensions/frame_semantics/runners/frame_semantics_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/LegionIO/lex-frame-semantics
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-frame-semantics
+  source_code_uri: https://github.com/LegionIO/lex-frame-semantics
+  documentation_uri: https://github.com/LegionIO/lex-frame-semantics
+  changelog_uri: https://github.com/LegionIO/lex-frame-semantics
+  bug_tracker_uri: https://github.com/LegionIO/lex-frame-semantics/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 Frame Semantics
+test_files: []