lex-agentic-inference 0.1.0

data/spec/legion/extensions/agentic/inference/horizon/helpers/constants_spec.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Horizon::Helpers::Constants do
+  describe 'numeric constants' do
+    it 'MAX_PROJECTIONS is 200' do
+      expect(described_module::MAX_PROJECTIONS).to eq(200)
+    end
+
+    it 'DEFAULT_HORIZON is 0.5' do
+      expect(described_module::DEFAULT_HORIZON).to eq(0.5)
+    end
+
+    it 'HORIZON_EXPAND is 0.08' do
+      expect(described_module::HORIZON_EXPAND).to eq(0.08)
+    end
+
+    it 'HORIZON_CONTRACT is 0.1' do
+      expect(described_module::HORIZON_CONTRACT).to eq(0.1)
+    end
+
+    it 'MIN_HORIZON is 0.1' do
+      expect(described_module::MIN_HORIZON).to eq(0.1)
+    end
+
+    it 'MAX_HORIZON is 1.0' do
+      expect(described_module::MAX_HORIZON).to eq(1.0)
+    end
+
+    it 'STRESS_CONTRACTION is 0.15' do
+      expect(described_module::STRESS_CONTRACTION).to eq(0.15)
+    end
+
+    it 'CONFIDENCE_DECAY_PER_STEP is 0.1' do
+      expect(described_module::CONFIDENCE_DECAY_PER_STEP).to eq(0.1)
+    end
+  end
+
+  describe 'HORIZON_LEVELS' do
+    it 'has 5 levels' do
+      expect(described_module::HORIZON_LEVELS.size).to eq(5)
+    end
+
+    it 'starts with :immediate' do
+      expect(described_module::HORIZON_LEVELS.first).to eq(:immediate)
+    end
+
+    it 'ends with :strategic' do
+      expect(described_module::HORIZON_LEVELS.last).to eq(:strategic)
+    end
+
+    it 'contains :near_term, :medium_term, :long_term' do
+      expect(described_module::HORIZON_LEVELS).to include(:near_term, :medium_term, :long_term)
+    end
+
+    it 'is frozen' do
+      expect(described_module::HORIZON_LEVELS).to be_frozen
+    end
+  end
+
+  describe 'CONSTRUAL_LABELS' do
+    it 'has 5 entries' do
+      expect(described_module::CONSTRUAL_LABELS.size).to eq(5)
+    end
+
+    it 'maps low distances to :concrete' do
+      entry = described_module::CONSTRUAL_LABELS.find { |e| e[:range].cover?(0.1) }
+      expect(entry[:label]).to eq(:concrete)
+    end
+
+    it 'maps mid distances to :balanced' do
+      entry = described_module::CONSTRUAL_LABELS.find { |e| e[:range].cover?(0.5) }
+      expect(entry[:label]).to eq(:balanced)
+    end
+
+    it 'maps high distances to :abstract' do
+      entry = described_module::CONSTRUAL_LABELS.find { |e| e[:range].cover?(0.9) }
+      expect(entry[:label]).to eq(:abstract)
+    end
+
+    it 'maps 0.3 to :detailed' do
+      entry = described_module::CONSTRUAL_LABELS.find { |e| e[:range].cover?(0.3) }
+      expect(entry[:label]).to eq(:detailed)
+    end
+
+    it 'maps 0.7 to :schematic' do
+      entry = described_module::CONSTRUAL_LABELS.find { |e| e[:range].cover?(0.7) }
+      expect(entry[:label]).to eq(:schematic)
+    end
+
+    it 'is frozen' do
+      expect(described_module::CONSTRUAL_LABELS).to be_frozen
+    end
+  end
+
+  def described_module
+    Legion::Extensions::Agentic::Inference::Horizon::Helpers::Constants
+  end
+end

data/spec/legion/extensions/agentic/inference/horizon/helpers/horizon_engine_spec.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Horizon::Helpers::HorizonEngine do
+  subject(:engine) { described_class.new }
+
+  let(:constants) { Legion::Extensions::Agentic::Inference::Horizon::Helpers::Constants }
+
+  describe '#initialize' do
+    it 'starts with empty projections' do
+      expect(engine.projections).to be_empty
+    end
+
+    it 'starts with DEFAULT_HORIZON' do
+      expect(engine.current_horizon).to eq(constants::DEFAULT_HORIZON)
+    end
+
+    it 'starts with zero stress' do
+      expect(engine.stress_level).to eq(0.0)
+    end
+
+    it 'accepts custom initial_horizon' do
+      e = described_class.new(initial_horizon: 0.8)
+      expect(e.current_horizon).to eq(0.8)
+    end
+
+    it 'clamps initial_horizon to MIN_HORIZON' do
+      e = described_class.new(initial_horizon: 0.0)
+      expect(e.current_horizon).to eq(constants::MIN_HORIZON)
+    end
+
+    it 'clamps initial_horizon to MAX_HORIZON' do
+      e = described_class.new(initial_horizon: 1.5)
+      expect(e.current_horizon).to eq(constants::MAX_HORIZON)
+    end
+  end
+
+  describe '#add_projection' do
+    it 'adds a projection to the list' do
+      engine.add_projection(description: 'test')
+      expect(engine.projections.size).to eq(1)
+    end
+
+    it 'returns a Projection object' do
+      proj = engine.add_projection(description: 'test')
+      expect(proj).to be_a(Legion::Extensions::Agentic::Inference::Horizon::Helpers::Projection)
+    end
+
+    it 'uses current_horizon as default distance' do
+      proj = engine.add_projection(description: 'test')
+      expect(proj.horizon_distance).to eq(engine.current_horizon)
+    end
+
+    it 'accepts explicit horizon_distance' do
+      proj = engine.add_projection(description: 'test', horizon_distance: 0.9)
+      expect(proj.horizon_distance).to eq(0.9)
+    end
+
+    it 'caps projections at MAX_PROJECTIONS' do
+      (constants::MAX_PROJECTIONS + 10).times { |i| engine.add_projection(description: "proj #{i}") }
+      expect(engine.projections.size).to eq(constants::MAX_PROJECTIONS)
+    end
+
+    it 'keeps the most recent projections when capping' do
+      (constants::MAX_PROJECTIONS + 5).times { |i| engine.add_projection(description: "proj #{i}") }
+      expect(engine.projections.last.description).to eq("proj #{constants::MAX_PROJECTIONS + 4}")
+    end
+  end
+
+  describe '#expand_horizon!' do
+    it 'increases current_horizon' do
+      before = engine.current_horizon
+      engine.expand_horizon!
+      expect(engine.current_horizon).to be > before
+    end
+
+    it 'increases by HORIZON_EXPAND by default' do
+      before = engine.current_horizon
+      engine.expand_horizon!
+      expect(engine.current_horizon).to eq((before + constants::HORIZON_EXPAND).clamp(constants::MIN_HORIZON, constants::MAX_HORIZON))
+    end
+
+    it 'accepts a custom amount' do
+      before = engine.current_horizon
+      engine.expand_horizon!(amount: 0.2)
+      expect(engine.current_horizon).to eq((before + 0.2).clamp(constants::MIN_HORIZON, constants::MAX_HORIZON))
+    end
+
+    it 'does not exceed MAX_HORIZON' do
+      engine = described_class.new(initial_horizon: 0.99)
+      engine.expand_horizon!(amount: 0.5)
+      expect(engine.current_horizon).to eq(constants::MAX_HORIZON)
+    end
+
+    it 'returns the new horizon value' do
+      result = engine.expand_horizon!
+      expect(result).to eq(engine.current_horizon)
+    end
+  end
+
+  describe '#contract_horizon!' do
+    it 'decreases current_horizon' do
+      before = engine.current_horizon
+      engine.contract_horizon!
+      expect(engine.current_horizon).to be < before
+    end
+
+    it 'decreases by HORIZON_CONTRACT by default' do
+      before = engine.current_horizon
+      engine.contract_horizon!
+      expect(engine.current_horizon).to eq((before - constants::HORIZON_CONTRACT).clamp(constants::MIN_HORIZON, constants::MAX_HORIZON))
+    end
+
+    it 'does not go below MIN_HORIZON' do
+      e = described_class.new(initial_horizon: constants::MIN_HORIZON)
+      e.contract_horizon!(amount: 0.5)
+      expect(e.current_horizon).to eq(constants::MIN_HORIZON)
+    end
+
+    it 'returns the new horizon value' do
+      result = engine.contract_horizon!
+      expect(result).to eq(engine.current_horizon)
+    end
+  end
+
+  describe '#apply_stress!' do
+    it 'sets stress_level' do
+      engine.apply_stress!(0.5)
+      expect(engine.stress_level).to eq(0.5)
+    end
+
+    it 'reduces current_horizon proportionally' do
+      before = engine.current_horizon
+      engine.apply_stress!(1.0)
+      expect(engine.current_horizon).to be <= before
+    end
+
+    it 'clamps stress to 0..1' do
+      engine.apply_stress!(2.0)
+      expect(engine.stress_level).to eq(1.0)
+    end
+
+    it 'clamps stress below 0.0 to 0.0' do
+      engine.apply_stress!(-0.5)
+      expect(engine.stress_level).to eq(0.0)
+    end
+
+    it 'ensures horizon does not go below MIN_HORIZON under max stress' do
+      engine.apply_stress!(1.0)
+      expect(engine.current_horizon).to be >= constants::MIN_HORIZON
+    end
+
+    it 'returns the new horizon value' do
+      result = engine.apply_stress!(0.3)
+      expect(result).to be_a(Float)
+    end
+  end
+
+  describe '#relieve_stress!' do
+    before { engine.apply_stress!(0.6) }
+
+    it 'reduces stress_level' do
+      before = engine.stress_level
+      engine.relieve_stress!
+      expect(engine.stress_level).to be < before
+    end
+
+    it 'accepts custom amount' do
+      engine.relieve_stress!(amount: 0.3)
+      expect(engine.stress_level).to be_within(0.001).of(0.3)
+    end
+
+    it 'does not go below 0.0' do
+      engine.relieve_stress!(amount: 10.0)
+      expect(engine.stress_level).to eq(0.0)
+    end
+  end
+
+  describe '#effective_horizon' do
+    it 'equals current_horizon when stress is zero' do
+      expect(engine.effective_horizon).to eq(engine.current_horizon)
+    end
+
+    it 'is less than current_horizon when stressed' do
+      engine.apply_stress!(0.5)
+      # after apply_stress! current_horizon already contracted;
+      # effective_horizon contracts further based on residual stress
+      expect(engine.effective_horizon).to be <= engine.current_horizon
+    end
+
+    it 'never goes below MIN_HORIZON' do
+      engine.apply_stress!(1.0)
+      expect(engine.effective_horizon).to be >= constants::MIN_HORIZON
+    end
+  end
+
+  describe '#projections_within_horizon' do
+    before do
+      engine.add_projection(description: 'near', horizon_distance: 0.2)
+      engine.add_projection(description: 'at horizon', horizon_distance: engine.effective_horizon)
+      engine.add_projection(description: 'far', horizon_distance: 0.99)
+    end
+
+    it 'returns projections at or within effective_horizon' do
+      within = engine.projections_within_horizon
+      within.each { |p| expect(p.horizon_distance).to be <= engine.effective_horizon }
+    end
+
+    it 'excludes projections beyond effective_horizon' do
+      within = engine.projections_within_horizon
+      descriptions = within.map(&:description)
+      expect(descriptions).not_to include('far')
+    end
+  end
+
+  describe '#beyond_horizon_projections' do
+    before do
+      engine.add_projection(description: 'near', horizon_distance: 0.1)
+      engine.add_projection(description: 'far', horizon_distance: 0.99)
+    end
+
+    it 'returns projections beyond effective_horizon' do
+      beyond = engine.beyond_horizon_projections
+      beyond.each { |p| expect(p.horizon_distance).to be > engine.effective_horizon }
+    end
+  end
+
+  describe '#nearest_projections' do
+    before do
+      [0.9, 0.1, 0.5, 0.3, 0.7].each { |d| engine.add_projection(description: "p#{d}", horizon_distance: d) }
+    end
+
+    it 'returns num nearest by horizon_distance' do
+      result = engine.nearest_projections(num: 3)
+      expect(result.size).to eq(3)
+      expect(result.map(&:horizon_distance)).to eq([0.1, 0.3, 0.5])
+    end
+
+    it 'defaults to 5' do
+      result = engine.nearest_projections
+      expect(result.size).to eq(5)
+    end
+  end
+
+  describe '#farthest_projections' do
+    before do
+      [0.9, 0.1, 0.5, 0.3, 0.7].each { |d| engine.add_projection(description: "p#{d}", horizon_distance: d) }
+    end
+
+    it 'returns num farthest in descending order' do
+      result = engine.farthest_projections(num: 2)
+      expect(result.map(&:horizon_distance)).to eq([0.9, 0.7])
+    end
+  end
+
+  describe '#construal_label' do
+    it 'returns a symbol' do
+      expect(engine.construal_label).to be_a(Symbol)
+    end
+
+    it 'returns :concrete for low effective horizon' do
+      e = described_class.new(initial_horizon: 0.15)
+      expect(e.construal_label).to eq(:concrete)
+    end
+
+    it 'returns :abstract for high effective horizon' do
+      e = described_class.new(initial_horizon: 0.95)
+      expect(e.construal_label).to eq(:abstract)
+    end
+  end
+
+  describe '#horizon_report' do
+    let(:report) { engine.horizon_report }
+
+    it 'includes current_horizon' do
+      expect(report).to have_key(:current_horizon)
+    end
+
+    it 'includes stress_level' do
+      expect(report).to have_key(:stress_level)
+    end
+
+    it 'includes effective_horizon' do
+      expect(report).to have_key(:effective_horizon)
+    end
+
+    it 'includes construal_label' do
+      expect(report).to have_key(:construal_label)
+    end
+
+    it 'includes horizon_level' do
+      expect(report).to have_key(:horizon_level)
+    end
+
+    it 'includes total_projections' do
+      expect(report).to have_key(:total_projections)
+    end
+
+    it 'includes within_horizon count' do
+      expect(report).to have_key(:within_horizon)
+    end
+
+    it 'includes beyond_horizon count' do
+      expect(report).to have_key(:beyond_horizon)
+    end
+
+    it 'rounds values to 10 places' do
+      expect(report[:current_horizon]).to be_a(Float)
+    end
+  end
+
+  describe '#to_h' do
+    it 'includes projections array' do
+      engine.add_projection(description: 'test')
+      h = engine.to_h
+      expect(h[:projections]).to be_an(Array)
+      expect(h[:projections].size).to eq(1)
+    end
+
+    it 'includes report fields' do
+      h = engine.to_h
+      expect(h).to have_key(:current_horizon)
+      expect(h).to have_key(:construal_label)
+    end
+  end
+end

data/spec/legion/extensions/agentic/inference/horizon/helpers/projection_spec.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+RSpec.describe Legion::Extensions::Agentic::Inference::Horizon::Helpers::Projection do
+  let(:proj) { described_class.new(description: 'Deploy new feature', domain: :code, horizon_distance: 0.4) }
+
+  describe '#initialize' do
+    it 'assigns a UUID id' do
+      expect(proj.id).to match(/\A[0-9a-f-]{36}\z/)
+    end
+
+    it 'sets description' do
+      expect(proj.description).to eq('Deploy new feature')
+    end
+
+    it 'sets domain' do
+      expect(proj.domain).to eq(:code)
+    end
+
+    it 'sets horizon_distance' do
+      expect(proj.horizon_distance).to eq(0.4)
+    end
+
+    it 'defaults confidence to 1.0' do
+      expect(proj.confidence).to eq(1.0)
+    end
+
+    it 'sets created_at' do
+      expect(proj.created_at).to be_a(Time)
+    end
+
+    it 'clamps horizon_distance above 1.0 to 1.0' do
+      p = described_class.new(description: 'x', horizon_distance: 1.5)
+      expect(p.horizon_distance).to eq(1.0)
+    end
+
+    it 'clamps horizon_distance below 0.0 to 0.0' do
+      p = described_class.new(description: 'x', horizon_distance: -0.5)
+      expect(p.horizon_distance).to eq(0.0)
+    end
+
+    it 'clamps confidence above 1.0 to 1.0' do
+      p = described_class.new(description: 'x', confidence: 2.0)
+      expect(p.confidence).to eq(1.0)
+    end
+
+    it 'clamps confidence below 0.0 to 0.0' do
+      p = described_class.new(description: 'x', confidence: -0.1)
+      expect(p.confidence).to eq(0.0)
+    end
+
+    it 'accepts explicit construal_level' do
+      p = described_class.new(description: 'x', construal_level: :abstract)
+      expect(p.construal_level).to eq(:abstract)
+    end
+  end
+
+  describe '#concrete?' do
+    it 'returns true for distance <= 0.3' do
+      p = described_class.new(description: 'x', horizon_distance: 0.2)
+      expect(p.concrete?).to be true
+    end
+
+    it 'returns true at exactly 0.3' do
+      p = described_class.new(description: 'x', horizon_distance: 0.3)
+      expect(p.concrete?).to be true
+    end
+
+    it 'returns false for distance > 0.3' do
+      p = described_class.new(description: 'x', horizon_distance: 0.5)
+      expect(p.concrete?).to be false
+    end
+  end
+
+  describe '#abstract?' do
+    it 'returns true for distance >= 0.7' do
+      p = described_class.new(description: 'x', horizon_distance: 0.8)
+      expect(p.abstract?).to be true
+    end
+
+    it 'returns true at exactly 0.7' do
+      p = described_class.new(description: 'x', horizon_distance: 0.7)
+      expect(p.abstract?).to be true
+    end
+
+    it 'returns false for distance < 0.7' do
+      p = described_class.new(description: 'x', horizon_distance: 0.5)
+      expect(p.abstract?).to be false
+    end
+  end
+
+  describe '#construal_level derived' do
+    it 'derives :concrete for distance 0.1' do
+      p = described_class.new(description: 'x', horizon_distance: 0.1)
+      expect(p.construal_level).to eq(:concrete)
+    end
+
+    it 'derives :balanced for distance 0.5' do
+      p = described_class.new(description: 'x', horizon_distance: 0.5)
+      expect(p.construal_level).to eq(:balanced)
+    end
+
+    it 'derives :abstract for distance 0.9' do
+      p = described_class.new(description: 'x', horizon_distance: 0.9)
+      expect(p.construal_level).to eq(:abstract)
+    end
+  end
+
+  describe '#to_h' do
+    let(:h) { proj.to_h }
+
+    it 'includes id' do
+      expect(h[:id]).to eq(proj.id)
+    end
+
+    it 'includes description' do
+      expect(h[:description]).to eq('Deploy new feature')
+    end
+
+    it 'includes domain' do
+      expect(h[:domain]).to eq(:code)
+    end
+
+    it 'includes horizon_distance rounded to 10 places' do
+      expect(h[:horizon_distance]).to eq(proj.horizon_distance.round(10))
+    end
+
+    it 'includes confidence rounded to 10 places' do
+      expect(h[:confidence]).to eq(proj.confidence.round(10))
+    end
+
+    it 'includes construal_level' do
+      expect(h[:construal_level]).to be_a(Symbol)
+    end
+
+    it 'includes concrete flag' do
+      expect(h).to have_key(:concrete)
+    end
+
+    it 'includes abstract flag' do
+      expect(h).to have_key(:abstract)
+    end
+
+    it 'includes created_at' do
+      expect(h[:created_at]).to be_a(Time)
+    end
+  end
+
+  describe 'unique IDs' do
+    it 'generates different IDs for different projections' do
+      p1 = described_class.new(description: 'a')
+      p2 = described_class.new(description: 'b')
+      expect(p1.id).not_to eq(p2.id)
+    end
+  end
+end