lex-agentic-integration 0.1.0

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::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

data/spec/legion/extensions/agentic/integration/situation_model/helpers/situation_engine_spec.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEngine do
+  let(:engine) { described_class.new }
+
+  def add_coherent_events(model_id, count)
+    count.times do |i|
+      engine.add_event_to_model(
+        model_id:         model_id,
+        content:          "event #{i}",
+        dimension_values: { space: 0.8, time: 0.8, causation: 0.8, intentionality: 0.8, protagonist: 0.8 }
+      )
+    end
+  end
+
+  describe '#create_model' do
+    it 'returns a SituationModel' do
+      model = engine.create_model(label: 'test')
+      expect(model).to be_a(Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationModel)
+    end
+
+    it 'assigns the given label' do
+      model = engine.create_model(label: 'narrative_x')
+      expect(model.label).to eq('narrative_x')
+    end
+
+    it 'stores the model by id' do
+      model = engine.create_model(label: 'stored')
+      expect(engine.model_coherence(model_id: model.id)).not_to be_nil
+    end
+  end
+
+  describe '#add_event_to_model' do
+    it 'returns the created event' do
+      model = engine.create_model(label: 'e')
+      event = engine.add_event_to_model(model_id: model.id, content: 'hi')
+      expect(event).to be_a(Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent)
+    end
+
+    it 'returns nil for unknown model_id' do
+      result = engine.add_event_to_model(model_id: 'nonexistent', content: 'x')
+      expect(result).to be_nil
+    end
+
+    it 'grows the model event count' do
+      model = engine.create_model(label: 'growing')
+      engine.add_event_to_model(model_id: model.id, content: 'first')
+      engine.add_event_to_model(model_id: model.id, content: 'second')
+      expect(model.events.size).to eq(2)
+    end
+
+    it 'passes dimension values to the event' do
+      model = engine.create_model(label: 'dims')
+      engine.add_event_to_model(model_id: model.id, content: 'test',
+                                dimension_values: { space: 0.9, time: 0.1, causation: 0.5,
+                                                    intentionality: 0.5, protagonist: 0.5 })
+      expect(model.events.last.dimension_values[:space]).to be_within(0.001).of(0.9)
+    end
+  end
+
+  describe '#model_coherence' do
+    it 'returns nil for unknown model' do
+      expect(engine.model_coherence(model_id: 'bad')).to be_nil
+    end
+
+    it 'returns 1.0 for empty model' do
+      model = engine.create_model(label: 'empty')
+      expect(engine.model_coherence(model_id: model.id)).to eq(1.0)
+    end
+
+    it 'returns coherence value for model with events' do
+      model = engine.create_model(label: 'coh')
+      add_coherent_events(model.id, 3)
+      expect(engine.model_coherence(model_id: model.id)).to be > 0.8
+    end
+  end
+
+  describe '#find_boundaries' do
+    it 'returns nil for unknown model' do
+      expect(engine.find_boundaries(model_id: 'bad')).to be_nil
+    end
+
+    it 'returns empty array for highly coherent model' do
+      model = engine.create_model(label: 'coherent')
+      add_coherent_events(model.id, 3)
+      expect(engine.find_boundaries(model_id: model.id, threshold: 0.5)).to be_empty
+    end
+
+    it 'detects discontinuities' do
+      model = engine.create_model(label: 'jump')
+      engine.add_event_to_model(model_id: model.id, content: 'high',
+                                dimension_values: { space: 0.9, time: 0.9, causation: 0.9, intentionality: 0.9, protagonist: 0.9 })
+      engine.add_event_to_model(model_id: model.id, content: 'low',
+                                dimension_values: { space: 0.0, time: 0.0, causation: 0.0, intentionality: 0.0, protagonist: 0.0 })
+      boundaries = engine.find_boundaries(model_id: model.id, threshold: 0.3)
+      expect(boundaries).to include(1)
+    end
+  end
+
+  describe '#dimension_trajectory' do
+    it 'returns nil for unknown model' do
+      expect(engine.dimension_trajectory(model_id: 'bad', dimension: :space)).to be_nil
+    end
+
+    it 'returns array of values for known dimension' do
+      model = engine.create_model(label: 'traj')
+      engine.add_event_to_model(model_id: model.id, content: 'a',
+                                dimension_values: { space: 0.3, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      engine.add_event_to_model(model_id: model.id, content: 'b',
+                                dimension_values: { space: 0.7, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      traj = engine.dimension_trajectory(model_id: model.id, dimension: :space)
+      expect(traj).to eq([0.3, 0.7])
+    end
+  end
+
+  describe '#most_coherent' do
+    it 'returns models sorted by coherence desc' do
+      m1 = engine.create_model(label: 'low')
+      engine.add_event_to_model(model_id: m1.id, content: 'a',
+                                dimension_values: { space: 0.9, time: 0.9, causation: 0.9, intentionality: 0.9, protagonist: 0.9 })
+      engine.add_event_to_model(model_id: m1.id, content: 'b',
+                                dimension_values: { space: 0.0, time: 0.0, causation: 0.0, intentionality: 0.0, protagonist: 0.0 })
+
+      m2 = engine.create_model(label: 'high')
+      add_coherent_events(m2.id, 3)
+
+      results = engine.most_coherent(limit: 2)
+      expect(results.first.id).to eq(m2.id)
+    end
+
+    it 'respects limit' do
+      3.times { |i| engine.create_model(label: "m#{i}") }
+      expect(engine.most_coherent(limit: 2).size).to eq(2)
+    end
+  end
+
+  describe '#models_by_label' do
+    it 'returns models matching label' do
+      engine.create_model(label: 'alpha')
+      engine.create_model(label: 'alpha')
+      engine.create_model(label: 'beta')
+      result = engine.models_by_label(label: 'alpha')
+      expect(result.size).to eq(2)
+      expect(result.all? { |m| m.label == 'alpha' }).to be(true)
+    end
+
+    it 'returns empty array for unknown label' do
+      expect(engine.models_by_label(label: 'nope')).to be_empty
+    end
+  end
+
+  describe '#decay_all' do
+    it 'decays all models' do
+      m1 = engine.create_model(label: 'a')
+      m2 = engine.create_model(label: 'b')
+      engine.add_event_to_model(model_id: m1.id, content: 'e1',
+                                dimension_values: { space: 0.8, time: 0.8, causation: 0.8, intentionality: 0.8, protagonist: 0.8 })
+      engine.add_event_to_model(model_id: m2.id, content: 'e2',
+                                dimension_values: { space: 0.6, time: 0.6, causation: 0.6, intentionality: 0.6, protagonist: 0.6 })
+
+      before_m1 = m1.current_state[:space]
+      before_m2 = m2.current_state[:space]
+      engine.decay_all
+      expect(m1.current_state[:space]).to be < before_m1
+      expect(m2.current_state[:space]).to be < before_m2
+    end
+  end
+
+  describe '#prune_collapsed' do
+    it 'removes models with coherence <= 0.1' do
+      model = engine.create_model(label: 'collapse')
+      # Add maximally discontinuous events repeatedly to drive coherence very low
+      5.times do |i|
+        engine.add_event_to_model(
+          model_id:         model.id,
+          content:          "e#{i}",
+          dimension_values: if i.even?
+                              { space: 0.0, time: 0.0, causation: 0.0, intentionality: 0.0, protagonist: 0.0 }
+                            else
+                              { space: 1.0, time: 1.0, causation: 1.0, intentionality: 1.0, protagonist: 1.0 }
+                            end
+        )
+      end
+
+      coherent_model = engine.create_model(label: 'coherent')
+      add_coherent_events(coherent_model.id, 3)
+
+      engine.prune_collapsed
+      # coherent model should survive
+      expect(engine.model_coherence(model_id: coherent_model.id)).not_to be_nil
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes model_count and models' do
+      engine.create_model(label: 'x')
+      h = engine.to_h
+      expect(h[:model_count]).to eq(1)
+      expect(h[:models]).to be_an(Array)
+      expect(h[:models].size).to eq(1)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/situation_model/helpers/situation_event_spec.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent do
+  let(:default_dims) { { space: 0.5, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 } }
+  let(:event_a)      { described_class.new(content: 'hero walks into room', dimension_values: default_dims) }
+  let(:event_b)      { described_class.new(content: 'hero walks forward', dimension_values: default_dims) }
+
+  describe '#initialize' do
+    it 'stores content' do
+      expect(event_a.content).to eq('hero walks into room')
+    end
+
+    it 'stores all 5 dimension values' do
+      expect(event_a.dimension_values.keys).to contain_exactly(*Legion::Extensions::Agentic::Integration::SituationModel::Helpers::Constants::DIMENSIONS)
+    end
+
+    it 'defaults missing dimensions to 0.5' do
+      event = described_class.new(content: 'test')
+      expect(event.dimension_values[:space]).to eq(0.5)
+    end
+
+    it 'clamps dimension values to [0, 1]' do
+      event = described_class.new(content: 'test', dimension_values: { space: 1.5, time: -0.3 })
+      expect(event.dimension_values[:space]).to eq(1.0)
+      expect(event.dimension_values[:time]).to eq(0.0)
+    end
+
+    it 'records created_at timestamp' do
+      expect(event_a.created_at).to be_a(Time)
+    end
+  end
+
+  describe '#continuity_with' do
+    it 'returns 1.0 for identical events' do
+      expect(event_a.continuity_with(event_b)).to be_within(0.001).of(1.0)
+    end
+
+    it 'returns 0.0 when all dimensions are maximally different' do
+      e1 = described_class.new(content: 'a', dimension_values: { space: 0.0, time: 0.0, causation: 0.0, intentionality: 0.0, protagonist: 0.0 })
+      e2 = described_class.new(content: 'b', dimension_values: { space: 1.0, time: 1.0, causation: 1.0, intentionality: 1.0, protagonist: 1.0 })
+      expect(e1.continuity_with(e2)).to be_within(0.001).of(0.0)
+    end
+
+    it 'returns intermediate value for partial differences' do
+      e1 = described_class.new(content: 'a', dimension_values: { space: 0.0, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      e2 = described_class.new(content: 'b', dimension_values: { space: 1.0, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      # Only space differs by 1.0, avg diff = 1.0/5 = 0.2, continuity = 0.8
+      expect(e1.continuity_with(e2)).to be_within(0.001).of(0.8)
+    end
+
+    it 'is symmetric' do
+      e1 = described_class.new(content: 'x', dimension_values: { space: 0.2, time: 0.8, causation: 0.5, intentionality: 0.3, protagonist: 0.7 })
+      e2 = described_class.new(content: 'y', dimension_values: { space: 0.6, time: 0.4, causation: 0.9, intentionality: 0.1, protagonist: 0.5 })
+      expect(e1.continuity_with(e2)).to be_within(0.001).of(e2.continuity_with(e1))
+    end
+  end
+
+  describe '#discontinuous_dimensions' do
+    it 'returns empty for identical events' do
+      expect(event_a.discontinuous_dimensions(event_b)).to be_empty
+    end
+
+    it 'returns dimensions that exceed threshold' do
+      e1 = described_class.new(content: 'a', dimension_values: { space: 0.0, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      e2 = described_class.new(content: 'b', dimension_values: { space: 0.8, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      result = e1.discontinuous_dimensions(e2, threshold: 0.3)
+      expect(result).to include(:space)
+      expect(result).not_to include(:time, :causation, :intentionality, :protagonist)
+    end
+
+    it 'uses threshold 0.3 by default' do
+      e1 = described_class.new(content: 'a', dimension_values: { space: 0.0, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      e2 = described_class.new(content: 'b', dimension_values: { space: 0.5, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      # space differs by 0.5 > 0.3
+      expect(e1.discontinuous_dimensions(e2)).to include(:space)
+    end
+
+    it 'respects custom threshold' do
+      e1 = described_class.new(content: 'a', dimension_values: { space: 0.0, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      e2 = described_class.new(content: 'b', dimension_values: { space: 0.4, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 })
+      # space diff = 0.4, with threshold 0.5 should NOT be discontinuous
+      expect(e1.discontinuous_dimensions(e2, threshold: 0.5)).not_to include(:space)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes content, dimension_values, and created_at' do
+      h = event_a.to_h
+      expect(h[:content]).to eq('hero walks into room')
+      expect(h[:dimension_values]).to be_a(Hash)
+      expect(h[:created_at]).to be_a(String)
+    end
+  end
+end

data/spec/legion/extensions/agentic/integration/situation_model/helpers/situation_model_spec.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationModel do
+  let(:model) { described_class.new(label: 'test_narrative') }
+
+  let(:event_a) do
+    Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent.new(
+      content:          'opening scene',
+      dimension_values: { space: 0.8, time: 0.8, causation: 0.8, intentionality: 0.8, protagonist: 0.8 }
+    )
+  end
+
+  let(:event_b) do
+    Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent.new(
+      content:          'continuing scene',
+      dimension_values: { space: 0.8, time: 0.9, causation: 0.8, intentionality: 0.7, protagonist: 0.8 }
+    )
+  end
+
+  let(:event_distant) do
+    Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent.new(
+      content:          'teleport scene',
+      dimension_values: { space: 0.0, time: 0.0, causation: 0.0, intentionality: 0.0, protagonist: 0.0 }
+    )
+  end
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(model.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'stores label' do
+      expect(model.label).to eq('test_narrative')
+    end
+
+    it 'starts with empty events' do
+      expect(model.events).to be_empty
+    end
+
+    it 'initializes current_state with default values' do
+      Legion::Extensions::Agentic::Integration::SituationModel::Helpers::Constants::DIMENSIONS.each do |dim|
+        expect(model.current_state[dim]).to eq(0.5)
+      end
+    end
+  end
+
+  describe '#add_event' do
+    it 'appends event to events array' do
+      model.add_event(event_a)
+      expect(model.events.size).to eq(1)
+    end
+
+    it 'returns 1.0 for first event (no previous)' do
+      result = model.add_event(event_a)
+      expect(result).to eq(1.0)
+    end
+
+    it 'returns continuity score for subsequent events' do
+      model.add_event(event_a)
+      result = model.add_event(event_b)
+      expect(result).to be_a(Float)
+      expect(result).to be_between(0.0, 1.0)
+    end
+
+    it 'updates current_state to the new event dimension values' do
+      model.add_event(event_a)
+      expect(model.current_state[:space]).to be_within(0.001).of(0.8)
+    end
+
+    it 'updates last_updated_at' do
+      original = model.last_updated_at
+      sleep(0.01)
+      model.add_event(event_a)
+      expect(model.last_updated_at).to be >= original
+    end
+  end
+
+  describe '#coherence' do
+    it 'returns 1.0 for empty model' do
+      expect(model.coherence).to eq(1.0)
+    end
+
+    it 'returns 1.0 for single event' do
+      model.add_event(event_a)
+      expect(model.coherence).to eq(1.0)
+    end
+
+    it 'returns high coherence for similar events' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      expect(model.coherence).to be > 0.8
+    end
+
+    it 'returns lower coherence for dissimilar events' do
+      model.add_event(event_a)
+      model.add_event(event_distant)
+      expect(model.coherence).to be < 0.5
+    end
+
+    it 'is between 0 and 1' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      model.add_event(event_distant)
+      expect(model.coherence).to be_between(0.0, 1.0)
+    end
+  end
+
+  describe '#health_label' do
+    it 'returns :vivid for fresh model with coherent events' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      expect(model.health_label).to eq(:vivid)
+    end
+
+    it 'returns a known health symbol' do
+      labels = %i[vivid clear hazy fading collapsed]
+      expect(labels).to include(model.health_label)
+    end
+  end
+
+  describe '#dominant_dimension' do
+    it 'returns the dimension with highest current_state value' do
+      model.add_event(
+        Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent.new(
+          content:          'high space',
+          dimension_values: { space: 0.9, time: 0.3, causation: 0.4, intentionality: 0.2, protagonist: 0.1 }
+        )
+      )
+      expect(model.dominant_dimension).to eq(:space)
+    end
+  end
+
+  describe '#weakest_dimension' do
+    it 'returns the dimension with lowest current_state value' do
+      model.add_event(
+        Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent.new(
+          content:          'weak protagonist',
+          dimension_values: { space: 0.9, time: 0.8, causation: 0.7, intentionality: 0.6, protagonist: 0.1 }
+        )
+      )
+      expect(model.weakest_dimension).to eq(:protagonist)
+    end
+  end
+
+  describe '#event_boundaries' do
+    it 'returns empty array when no boundaries' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      # Events are similar - expect no or minimal boundaries
+      result = model.event_boundaries(threshold: 0.5)
+      expect(result).to be_an(Array)
+    end
+
+    it 'detects boundaries on large dimension shifts' do
+      model.add_event(event_a)
+      model.add_event(event_distant)
+      # event_distant is all zeros vs event_a all 0.8 - should produce boundary
+      boundaries = model.event_boundaries(threshold: 0.3)
+      expect(boundaries).to include(1)
+    end
+
+    it 'uses threshold 0.3 by default' do
+      model.add_event(event_a)
+      model.add_event(event_distant)
+      boundaries_default = model.event_boundaries
+      boundaries_strict  = model.event_boundaries(threshold: 0.9)
+      # strict threshold should catch fewer boundaries
+      expect(boundaries_default.size).to be >= boundaries_strict.size
+    end
+  end
+
+  describe '#dimension_trajectory' do
+    it 'returns an array of values for each event' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      trajectory = model.dimension_trajectory(:space)
+      expect(trajectory.size).to eq(2)
+    end
+
+    it 'contains the correct values in order' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      trajectory = model.dimension_trajectory(:space)
+      expect(trajectory[0]).to be_within(0.001).of(0.8)
+      expect(trajectory[1]).to be_within(0.001).of(0.8)
+    end
+
+    it 'returns empty for model with no events' do
+      expect(model.dimension_trajectory(:time)).to be_empty
+    end
+  end
+
+  describe '#decay!' do
+    it 'reduces all current_state values by DECAY_RATE' do
+      model.add_event(event_a)
+      before = model.current_state[:space]
+      model.decay!
+      expect(model.current_state[:space]).to be_within(0.001).of(before - 0.01)
+    end
+
+    it 'clamps at 0.0' do
+      low_event = Legion::Extensions::Agentic::Integration::SituationModel::Helpers::SituationEvent.new(
+        content:          'near zero',
+        dimension_values: { space: 0.005, time: 0.5, causation: 0.5, intentionality: 0.5, protagonist: 0.5 }
+      )
+      model.add_event(low_event)
+      model.decay!
+      expect(model.current_state[:space]).to be >= 0.0
+    end
+
+    it 'applies decay to all 5 dimensions' do
+      model.add_event(event_a)
+      before = model.current_state.dup
+      model.decay!
+      Legion::Extensions::Agentic::Integration::SituationModel::Helpers::Constants::DIMENSIONS.each do |dim|
+        expect(model.current_state[dim]).to be < before[dim]
+      end
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes all expected keys' do
+      h = model.to_h
+      %i[id label event_count current_state coherence health_label created_at last_updated_at].each do |k|
+        expect(h).to have_key(k)
+      end
+    end
+
+    it 'reflects event count' do
+      model.add_event(event_a)
+      model.add_event(event_b)
+      expect(model.to_h[:event_count]).to eq(2)
+    end
+  end
+end