lex-situation-model 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 41d37b1bbd266913da91713adc534e8e67746991a81c7f5663e3f15693e7aff3
+  data.tar.gz: c81dfe9ec810c628d8ce80a8f1e5189965b4abfc9e12850c4510abf066d8565a
+SHA512:
+  metadata.gz: 1bd7e624765b6fb0af200387fc1825097f59a6b28682e1d87924efefd49b7eb043007a17a306dd617217b29f5e7508bc5927d04defbac7adcd29e9c725d884d2
+  data.tar.gz: e7c55171a5db8529e7c9a00f741d8e7640cda51da3e7e89dc0f3a7a1533a3a277465698d8fa6fc7324716332d26c120576ba5569b6fe77e61b00894d8a242ecb

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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Iverson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# lex-situation-model
+
+Five-dimension situation tracking for LegionIO cognitive agents. Models narrative coherence and event boundaries using Zwaan & Radvansky's situational indexing dimensions.
+
+## What It Does
+
+`lex-situation-model` tracks sequences of events scored across five dimensions — space, time, causation, intentionality, and protagonist. Events within a situation are compared pairwise for continuity; sharp discontinuities mark situation boundaries (the cognitive equivalent of a scene change). Situations are scored for overall coherence and can be ranked by health.
+
+- **Dimensions**: `:space`, `:time`, `:causation`, `:intentionality`, `:protagonist` (each 0.0–1.0)
+- **Continuity**: `1.0 - mean_dimension_diff` between consecutive events (1.0 = identical, 0.0 = completely different)
+- **Event boundaries**: indices where continuity drops below a configurable threshold (default 0.4)
+- **Coherence**: mean pairwise continuity across the full event sequence
+- **Health labels**: `:stable` (coherent), `:degrading`, `:fragmented`
+- **Decay**: coherence degrades passively each tick
+
+## Usage
+
+```ruby
+require 'legion/extensions/situation_model'
+
+client = Legion::Extensions::SituationModel::Client.new
+
+# Create a situation
+result = client.create_situation_model(name: 'office_meeting', domain: :work)
+model_id = result[:model_id]
+
+# Add events with dimension scores
+client.add_situation_event(
+  model_id: model_id,
+  description: 'team arrives',
+  space: 0.8, time: 0.2, causation: 0.5, intentionality: 0.7, protagonist: 0.9
+)
+# => { continuity: 1.0 }  (first event)
+
+client.add_situation_event(
+  model_id: model_id,
+  description: 'discussion begins',
+  space: 0.8, time: 0.3, causation: 0.6, intentionality: 0.8, protagonist: 0.9
+)
+# => { continuity: 0.94 }  (high — same space, same protagonists)
+
+client.add_situation_event(
+  model_id: model_id,
+  description: 'unexpected fire alarm',
+  space: 0.1, time: 0.3, causation: 0.1, intentionality: 0.1, protagonist: 0.5
+)
+# => { continuity: 0.42 }  (low — space and intentionality shifted sharply)
+
+# Check overall coherence
+client.situation_model_coherence(model_id: model_id)
+# => { coherence: 0.71, health_label: :stable }
+
+# Find event boundaries
+client.find_situation_boundaries(model_id: model_id, threshold: 0.4)
+# => { boundaries: [2], count: 1 }
+
+# Trace how time dimension evolved
+client.situation_dimension_trajectory(model_id: model_id, dimension: :time)
+# => { trajectory: [0.2, 0.3, 0.3] }
+
+# Per-tick decay
+client.update_situation_models
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lex-situation-model.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/situation_model/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-situation-model'
+  spec.version       = Legion::Extensions::SituationModel::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Situation Model'
+  spec.description   = 'Zwaan Event Indexing Model for brain-modeled agentic AI: tracks 5-dimensional situation models across narrative events'
+  spec.homepage      = 'https://github.com/LegionIO/lex-situation-model'
+  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-situation-model'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-situation-model'
+  spec.metadata['changelog_uri']     = 'https://github.com/LegionIO/lex-situation-model'
+  spec.metadata['bug_tracker_uri']   = 'https://github.com/LegionIO/lex-situation-model/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-situation-model.gemspec Gemfile LICENSE README.md]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'legion-gaia'
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/situation_model/helpers/constants'
+require 'legion/extensions/situation_model/helpers/situation_event'
+require 'legion/extensions/situation_model/helpers/situation_model'
+require 'legion/extensions/situation_model/helpers/situation_engine'
+require 'legion/extensions/situation_model/runners/situation_model'
+require 'legion/extensions/situation_model/helpers/client'
+
+module Legion
+  module Extensions
+    module SituationModel
+      class Client
+        include Runners::SituationModel
+
+        private
+
+        def engine
+          @engine ||= Helpers::SituationEngine.new
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SituationModel
+      module Helpers
+        module Constants
+          DIMENSIONS = %i[space time causation intentionality protagonist].freeze
+
+          CONTINUITY_LABELS = {
+            (0.8..)     => :continuous,
+            (0.5...0.8) => :shift,
+            (0.2...0.5) => :break,
+            (..0.2)     => :rupture
+          }.freeze
+
+          MODEL_HEALTH_LABELS = {
+            (0.8..)     => :vivid,
+            (0.6...0.8) => :clear,
+            (0.4...0.6) => :hazy,
+            (0.2...0.4) => :fading,
+            (..0.2)     => :collapsed
+          }.freeze
+
+          MAX_MODELS            = 100
+          MAX_EVENTS_PER_MODEL  = 200
+          MAX_HISTORY           = 500
+          DEFAULT_DIMENSION_VALUE = 0.5
+          DECAY_RATE            = 0.01
+          COHERENCE_FLOOR       = 0.0
+          COHERENCE_CEILING     = 1.0
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/situation_model/helpers/situation_engine.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SituationModel
+      module Helpers
+        class SituationEngine
+          include Constants
+
+          def initialize
+            @models = {}
+          end
+
+          def create_model(label:)
+            model = SituationModel.new(label: label)
+            @models[model.id] = model
+            model
+          end
+
+          def add_event_to_model(model_id:, content:, dimension_values: {})
+            model = @models[model_id]
+            return nil unless model
+
+            event = SituationEvent.new(content: content, dimension_values: dimension_values)
+            model.add_event(event)
+            event
+          end
+
+          def model_coherence(model_id:)
+            @models[model_id]&.coherence
+          end
+
+          def find_boundaries(model_id:, threshold: 0.3)
+            @models[model_id]&.event_boundaries(threshold: threshold)
+          end
+
+          def dimension_trajectory(model_id:, dimension:)
+            @models[model_id]&.dimension_trajectory(dimension)
+          end
+
+          def most_coherent(limit: 5)
+            @models.values
+                   .sort_by { |m| -m.coherence }
+                   .first(limit)
+          end
+
+          def models_by_label(label:)
+            @models.values.select { |m| m.label == label }
+          end
+
+          def decay_all
+            @models.each_value(&:decay!)
+          end
+
+          def prune_collapsed
+            @models.delete_if { |_, m| m.coherence <= 0.1 }
+          end
+
+          def to_h
+            {
+              model_count: @models.size,
+              models:      @models.values.map(&:to_h)
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/situation_model/helpers/situation_event.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SituationModel
+      module Helpers
+        class SituationEvent
+          include Constants
+
+          attr_reader :content, :dimension_values, :created_at
+
+          def initialize(content:, dimension_values: {})
+            @content          = content
+            @dimension_values = build_dimension_values(dimension_values)
+            @created_at       = Time.now.utc
+          end
+
+          def continuity_with(other_event)
+            total_diff = DIMENSIONS.sum do |dim|
+              (dimension_values[dim] - other_event.dimension_values[dim]).abs
+            end
+            avg_diff = total_diff / DIMENSIONS.size.to_f
+            1.0 - avg_diff
+          end
+
+          def discontinuous_dimensions(other_event, threshold: 0.3)
+            DIMENSIONS.select do |dim|
+              (dimension_values[dim] - other_event.dimension_values[dim]).abs > threshold
+            end
+          end
+
+          def to_h
+            {
+              content:          content,
+              dimension_values: dimension_values,
+              created_at:       created_at.iso8601
+            }
+          end
+
+          private
+
+          def build_dimension_values(values)
+            DIMENSIONS.to_h do |dim|
+              raw = values.fetch(dim, DEFAULT_DIMENSION_VALUE)
+              [dim, raw.clamp(0.0, 1.0)]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/situation_model/helpers/situation_model.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Legion
+  module Extensions
+    module SituationModel
+      module Helpers
+        class SituationModel
+          include Constants
+
+          attr_reader :id, :label, :events, :current_state, :created_at, :last_updated_at
+
+          def initialize(label:)
+            @id             = SecureRandom.uuid
+            @label          = label
+            @events         = []
+            @current_state  = DIMENSIONS.to_h { |dim| [dim, DEFAULT_DIMENSION_VALUE] }
+            @created_at     = Time.now.utc
+            @last_updated_at = Time.now.utc
+          end
+
+          def add_event(event)
+            previous = events.last
+            events << event
+            @current_state   = event.dimension_values.dup
+            @last_updated_at = Time.now.utc
+            previous ? event.continuity_with(previous) : 1.0
+          end
+
+          def coherence
+            return 1.0 if events.size <= 1
+
+            pairs = events.each_cons(2).to_a
+            total = pairs.sum { |a, b| b.continuity_with(a) }
+            (total / pairs.size.to_f).clamp(COHERENCE_FLOOR, COHERENCE_CEILING)
+          end
+
+          def health_label
+            c = coherence
+            MODEL_HEALTH_LABELS.find { |range, _| range.cover?(c) }&.last || :collapsed
+          end
+
+          def dominant_dimension
+            current_state.max_by { |_, v| v }&.first
+          end
+
+          def weakest_dimension
+            current_state.min_by { |_, v| v }&.first
+          end
+
+          def event_boundaries(threshold: 0.3)
+            indices = []
+            events.each_cons(2).with_index do |(a, b), idx|
+              indices << (idx + 1) unless b.discontinuous_dimensions(a, threshold: threshold).empty?
+            end
+            indices
+          end
+
+          def dimension_trajectory(dimension)
+            events.map { |e| e.dimension_values[dimension] }
+          end
+
+          def decay!
+            DIMENSIONS.each do |dim|
+              current_state[dim] = (current_state[dim] - DECAY_RATE).clamp(COHERENCE_FLOOR, COHERENCE_CEILING)
+            end
+          end
+
+          def to_h
+            {
+              id:              id,
+              label:           label,
+              event_count:     events.size,
+              current_state:   current_state,
+              coherence:       coherence,
+              health_label:    health_label,
+              created_at:      created_at.iso8601,
+              last_updated_at: last_updated_at.iso8601
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module SituationModel
+      module Runners
+        module SituationModel
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+
+          def create_situation_model(label:, **)
+            model = engine.create_model(label: label)
+            Legion::Logging.debug "[situation_model] create_model: id=#{model.id} label=#{label}"
+            { success: true, model: model.to_h }
+          end
+
+          def add_situation_event(model_id:, content:, **opts)
+            dim_values = {
+              space:          opts.fetch(:space, 0.5),
+              time:           opts.fetch(:time, 0.5),
+              causation:      opts.fetch(:causation, 0.5),
+              intentionality: opts.fetch(:intentionality, 0.5),
+              protagonist:    opts.fetch(:protagonist, 0.5)
+            }
+            event = engine.add_event_to_model(model_id: model_id, content: content, dimension_values: dim_values)
+            unless event
+              Legion::Logging.debug "[situation_model] add_event: model_id=#{model_id} not found"
+              return { success: false, error: 'model not found' }
+            end
+
+            coherence = engine.model_coherence(model_id: model_id)
+            Legion::Logging.debug "[situation_model] add_event: model_id=#{model_id} coherence=#{coherence.round(3)}"
+            { success: true, event: event.to_h, coherence: coherence }
+          end
+
+          def situation_model_coherence(model_id:, **)
+            coherence = engine.model_coherence(model_id: model_id)
+            Legion::Logging.debug "[situation_model] coherence: model_id=#{model_id} value=#{coherence}"
+            return { success: false, error: 'model not found' } if coherence.nil?
+
+            { success: true, model_id: model_id, coherence: coherence }
+          end
+
+          def find_situation_boundaries(model_id:, threshold: 0.3, **)
+            boundaries = engine.find_boundaries(model_id: model_id, threshold: threshold)
+            Legion::Logging.debug "[situation_model] boundaries: model_id=#{model_id} count=#{boundaries&.size}"
+            return { success: false, error: 'model not found' } if boundaries.nil?
+
+            { success: true, model_id: model_id, boundaries: boundaries, threshold: threshold }
+          end
+
+          def situation_dimension_trajectory(model_id:, dimension:, **)
+            dim = dimension.to_sym
+            trajectory = engine.dimension_trajectory(model_id: model_id, dimension: dim)
+            Legion::Logging.debug "[situation_model] trajectory: model_id=#{model_id} dimension=#{dim} points=#{trajectory&.size}"
+            return { success: false, error: 'model not found' } if trajectory.nil?
+
+            { success: true, model_id: model_id, dimension: dim, trajectory: trajectory }
+          end
+
+          def most_coherent_situations(limit: 5, **)
+            models = engine.most_coherent(limit: limit)
+            Legion::Logging.debug "[situation_model] most_coherent: limit=#{limit} found=#{models.size}"
+            { success: true, models: models.map(&:to_h), count: models.size }
+          end
+
+          def situations_by_label(label:, **)
+            models = engine.models_by_label(label: label)
+            Legion::Logging.debug "[situation_model] by_label: label=#{label} found=#{models.size}"
+            { success: true, label: label, models: models.map(&:to_h), count: models.size }
+          end
+
+          def update_situation_models(**)
+            engine.decay_all
+            pruned = engine.prune_collapsed
+            Legion::Logging.debug "[situation_model] update: decay_all pruned=#{pruned.size}"
+            { success: true, pruned_count: pruned.size }
+          end
+
+          def situation_model_stats(**)
+            stats = engine.to_h
+            Legion::Logging.debug "[situation_model] stats: model_count=#{stats[:model_count]}"
+            { success: true, **stats }
+          end
+
+          private
+
+          def engine
+            @engine ||= Helpers::SituationEngine.new
+          end
+        end
+      end
+    end
+  end
+end

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

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

data/lib/legion/extensions/situation_model.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/situation_model/version'
+require 'legion/extensions/situation_model/helpers/constants'
+require 'legion/extensions/situation_model/helpers/situation_event'
+require 'legion/extensions/situation_model/helpers/situation_model'
+require 'legion/extensions/situation_model/helpers/situation_engine'
+require 'legion/extensions/situation_model/runners/situation_model'
+require 'legion/extensions/situation_model/helpers/client'
+require 'legion/extensions/situation_model/client'
+
+module Legion
+  module Extensions
+    module SituationModel
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

data/spec/legion/extensions/situation_model/client_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/situation_model/client'
+
+RSpec.describe Legion::Extensions::SituationModel::Client do
+  let(:client) { described_class.new }
+
+  it 'responds to all runner methods' do
+    %i[
+      create_situation_model
+      add_situation_event
+      situation_model_coherence
+      find_situation_boundaries
+      situation_dimension_trajectory
+      most_coherent_situations
+      situations_by_label
+      update_situation_models
+      situation_model_stats
+    ].each do |method_name|
+      expect(client).to respond_to(method_name)
+    end
+  end
+
+  it 'round-trips a full situation model lifecycle' do
+    created  = client.create_situation_model(label: 'round_trip')
+    model_id = created[:model][:id]
+
+    client.add_situation_event(model_id: model_id, content: 'scene 1',
+                               space: 0.8, time: 0.8, causation: 0.8, intentionality: 0.7, protagonist: 0.9)
+    client.add_situation_event(model_id: model_id, content: 'scene 2',
+                               space: 0.7, time: 0.9, causation: 0.8, intentionality: 0.7, protagonist: 0.8)
+
+    coh = client.situation_model_coherence(model_id: model_id)
+    expect(coh[:success]).to be(true)
+    expect(coh[:coherence]).to be > 0.7
+
+    traj = client.situation_dimension_trajectory(model_id: model_id, dimension: :time)
+    expect(traj[:trajectory]).to eq([0.8, 0.9])
+
+    stats = client.situation_model_stats
+    expect(stats[:model_count]).to be >= 1
+  end
+
+  it 'maintains separate engine state per instance' do
+    c1 = described_class.new
+    c2 = described_class.new
+    c1.create_situation_model(label: 'only_c1')
+    expect(c1.situation_model_stats[:model_count]).to eq(1)
+    expect(c2.situation_model_stats[:model_count]).to eq(0)
+  end
+end

data/spec/legion/extensions/situation_model/helpers/constants_spec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::SituationModel::Helpers::Constants do
+  it 'defines 5 dimensions' do
+    expect(described_class::DIMENSIONS.size).to eq(5)
+    expect(described_class::DIMENSIONS).to include(:space, :time, :causation, :intentionality, :protagonist)
+  end
+
+  it 'CONTINUITY_LABELS covers the full 0..1 range' do
+    [0.0, 0.1, 0.2, 0.3, 0.5, 0.6, 0.8, 0.9, 1.0].each do |v|
+      match = described_class::CONTINUITY_LABELS.find { |range, _| range.cover?(v) }
+      expect(match).not_to be_nil, "no label for #{v}"
+    end
+  end
+
+  it 'assigns :rupture for very low continuity' do
+    label = described_class::CONTINUITY_LABELS.find { |r, _| r.cover?(0.1) }&.last
+    expect(label).to eq(:rupture)
+  end
+
+  it 'assigns :continuous for high continuity' do
+    label = described_class::CONTINUITY_LABELS.find { |r, _| r.cover?(0.9) }&.last
+    expect(label).to eq(:continuous)
+  end
+
+  it 'assigns :shift for mid-range continuity' do
+    label = described_class::CONTINUITY_LABELS.find { |r, _| r.cover?(0.6) }&.last
+    expect(label).to eq(:shift)
+  end
+
+  it 'MODEL_HEALTH_LABELS covers full range' do
+    [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 1.0].each do |v|
+      match = described_class::MODEL_HEALTH_LABELS.find { |range, _| range.cover?(v) }
+      expect(match).not_to be_nil, "no health label for #{v}"
+    end
+  end
+
+  it 'assigns :vivid for coherence >= 0.8' do
+    label = described_class::MODEL_HEALTH_LABELS.find { |r, _| r.cover?(0.85) }&.last
+    expect(label).to eq(:vivid)
+  end
+
+  it 'assigns :collapsed for coherence <= 0.2' do
+    label = described_class::MODEL_HEALTH_LABELS.find { |r, _| r.cover?(0.05) }&.last
+    expect(label).to eq(:collapsed)
+  end
+
+  it 'has sensible numeric constants' do
+    expect(described_class::MAX_MODELS).to eq(100)
+    expect(described_class::MAX_EVENTS_PER_MODEL).to eq(200)
+    expect(described_class::DECAY_RATE).to eq(0.01)
+    expect(described_class::DEFAULT_DIMENSION_VALUE).to eq(0.5)
+    expect(described_class::COHERENCE_FLOOR).to eq(0.0)
+    expect(described_class::COHERENCE_CEILING).to eq(1.0)
+  end
+end