lex-llm 0.5.3 → 0.6.2

data/spec/legion/extensions/llm/capability_policy_spec.rb

@@ -14,7 +14,7 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
         policy = described_class.resolve(**empty_sources)
 
         expect(policy[:capabilities]).to eq([])
-        expect(policy[:sources][:embeddings]).to eq(value: false, source: :default_false)
+        expect(policy[:sources][:embedding]).to eq(value: false, source: :default_false)
         expect(policy[:sources][:thinking]).to eq(value: false, source: :default_false)
         expect(policy[:sources][:streaming]).to eq(value: false, source: :default_false)
         expect(policy[:sources][:tools]).to eq(value: false, source: :default_false)
@@ -42,7 +42,7 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
 
         expect(policy[:capabilities]).to contain_exactly(:streaming, :tools, :thinking)
         expect(policy[:sources][:thinking]).to eq(value: true, source: :instance_override)
-        expect(policy[:sources][:embeddings]).to eq(value: false, source: :provider_override)
+        expect(policy[:sources][:embedding]).to eq(value: false, source: :provider_override)
         expect(policy[:sources][:tools]).to eq(value: true, source: :instance_override)
       end
     end
@@ -65,7 +65,7 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
 
         expect(policy[:capabilities]).to contain_exactly(:streaming, :thinking)
         expect(policy[:sources][:streaming]).to eq(value: true, source: :provider_override)
-        expect(policy[:sources][:embeddings]).to eq(value: false, source: :provider_override)
+        expect(policy[:sources][:embedding]).to eq(value: false, source: :provider_override)
         expect(policy[:sources][:thinking]).to eq(value: true, source: :provider_override)
       end
     end
@@ -82,11 +82,11 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
           model_config: { capabilities: { tools: true } }
         )
 
-        expect(policy[:capabilities]).to include(:tools, :embeddings, :streaming, :structured_output)
+        expect(policy[:capabilities]).to include(:tools, :embedding, :streaming, :structured_output)
         expect(policy[:capabilities]).not_to include(:vision)
         expect(policy[:sources][:tools]).to eq(value: true, source: :model_override)
         expect(policy[:sources][:vision]).to eq(value: false, source: :provider_override)
-        expect(policy[:sources][:embeddings]).to eq(value: true, source: :probe)
+        expect(policy[:sources][:embedding]).to eq(value: true, source: :probe)
         expect(policy[:sources][:structured_output]).to eq(value: true, source: :provider_catalog)
         expect(policy[:sources][:streaming]).to eq(value: true, source: :provider_envelope)
       end
@@ -109,6 +109,29 @@ RSpec.describe Legion::Extensions::Llm::CapabilityPolicy do
         expect(policy[:sources][:streaming]).to eq(value: true, source: :instance_override)
         expect(policy[:sources][:tools]).to eq(value: false, source: :instance_override)
       end
+
+      it 'canonicalizes reasoning, embedding, and image-generation aliases' do
+        policy = described_class.resolve(
+          real: {},
+          provider_catalog: {},
+          probe: {},
+          provider_envelope: {},
+          provider_config: {},
+          instance_config: {
+            enable_reasoning: true,
+            embeddings_flag: true,
+            image_generation_flag: true,
+            completion_flag: true
+          },
+          model_config: {}
+        )
+
+        expect(policy[:capabilities]).to include(:thinking, :embedding, :image, :completion)
+        expect(policy[:sources][:thinking]).to eq(value: true, source: :instance_override)
+        expect(policy[:sources][:embedding]).to eq(value: true, source: :instance_override)
+        expect(policy[:sources][:image]).to eq(value: true, source: :instance_override)
+        expect(policy[:sources][:completion]).to eq(value: true, source: :instance_override)
+      end
     end
 
     context 'when capabilities hash wins over alias at same level' do

data/spec/legion/extensions/llm/inventory/capabilities_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::Capabilities do
+  describe '.normalize' do
+    it 'returns symbols for raw capability names' do
+      expect(described_class.normalize(%i[tools streaming])).to contain_exactly(:tools, :streaming)
+    end
+
+    it 'collapses provider aliases into the canonical vocabulary' do
+      expect(described_class.normalize([:function_calling])).to include(:tools)
+      expect(described_class.normalize([:tool_use])).to include(:tools)
+      expect(described_class.normalize([:stream])).to include(:streaming)
+    end
+
+    it 'returns an empty array for nil/empty input' do
+      expect(described_class.normalize(nil)).to eq([])
+      expect(described_class.normalize([])).to eq([])
+    end
+
+    it 'is the same vocabulary as Legion::Extensions::Llm::Capabilities' do
+      expect(described_class::ALIASES).to equal(Legion::Extensions::Llm::Capabilities::ALIASES)
+    end
+  end
+
+  describe '.merge' do
+    it 'unions multiple capability sets' do
+      result = described_class.merge([:tools], %i[streaming tools])
+      expect(result).to contain_exactly(:tools, :streaming)
+    end
+  end
+
+  describe '.include_all?' do
+    it 'returns true when required is a subset of available' do
+      expect(described_class.include_all?(%i[tools streaming], [:tools])).to be(true)
+    end
+
+    it 'returns false when required is missing from available' do
+      expect(described_class.include_all?([:streaming], [:tools])).to be(false)
+    end
+  end
+end

data/spec/legion/extensions/llm/inventory/scoped_refresher_spec.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/inventory/scoped_refresher'
+
+RSpec.describe Legion::Extensions::Llm::Inventory::ScopedRefresher do
+  describe '.compose_id' do
+    it 'builds a 5-part colon-separated id (G22)' do
+      id = described_class.compose_id(
+        tier: :direct, provider_family: :vllm, instance_id: :apollo,
+        type: :inference, model: 'gemma-12b'
+      )
+      expect(id).to eq('direct:vllm:apollo:inference:gemma-12b')
+      expect(id.split(':').size).to eq(5)
+    end
+  end
+
+  describe '#tick write-then-delete-orphans (G7)' do
+    let(:inventory_writes)  { [] }
+    let(:inventory_deletes) { [] }
+
+    before do
+      stub_const('Legion::LLM::Inventory', Module.new)
+      allow(Legion::LLM::Inventory).to receive(:write_lane) { |lane:, **| inventory_writes << lane[:id] }
+      allow(Legion::LLM::Inventory).to receive(:delete_lane) { |id:, **| inventory_deletes << id }
+    end
+
+    def make_actor(models)
+      klass = Class.new do
+        include Legion::Extensions::Llm::Inventory::ScopedRefresher
+
+        def self.every_seconds = 60
+        def scope_key = { provider: :test }
+        def credential_hash = 'testhash'
+
+        attr_accessor :models
+
+        def compute_lanes_for_scope
+          @models.map do |m|
+            {
+              id: Legion::Extensions::Llm::Inventory::ScopedRefresher.compose_id(
+                tier: :direct, provider_family: :test, instance_id: :default,
+                type: :inference, model: m
+              ),
+              tier: :direct, provider_family: :test, instance_id: :default,
+              model: m, type: :inference
+            }
+          end
+        end
+
+        def log = Logger.new(File::NULL)
+        def handle_exception(_err, **) = nil
+      end
+      actor = klass.new
+      actor.models = models
+      actor
+    end
+
+    it 'writes new lanes before deleting orphans (zero-results race window eliminated)' do
+      actor = make_actor(%w[gemma-12b])
+      actor.tick
+      expect(inventory_writes).to include('direct:test:default:inference:gemma-12b')
+    end
+
+    it 'deletes orphaned lanes (present on previous tick, absent on current)' do
+      actor = make_actor(%w[gemma-12b gemma-31b])
+      actor.tick
+      actor.models = %w[gemma-31b]
+      actor.tick
+      expect(inventory_deletes).to include('direct:test:default:inference:gemma-12b')
+      expect(inventory_writes.last).to eq('direct:test:default:inference:gemma-31b')
+    end
+
+    it 'writes nothing when compute raises, leaving previous lanes in place' do
+      actor = make_actor(%w[gemma-12b])
+      actor.tick
+      allow(actor).to receive(:compute_lanes_for_scope).and_raise(StandardError, 'net error')
+      actor.tick
+      expect(inventory_writes.count('direct:test:default:inference:gemma-12b')).to eq(1)
+      expect(inventory_deletes).to be_empty
+    end
+  end
+
+  describe 'auth-failure cooldown circuit (P2 commit 3)' do
+    let(:cache_store) { {} }
+    let(:cooldown_key) { 'llm_auth_failed:testhash' }
+
+    before do
+      stub_const('Legion::LLM::Inventory', Module.new)
+      allow(Legion::LLM::Inventory).to receive(:write_lane)
+      allow(Legion::LLM::Inventory).to receive(:delete_lane)
+
+      stub_const('Legion::Cache::Local', Module.new)
+      allow(Legion::Cache::Local).to receive(:get) { |k| cache_store[k] }
+      allow(Legion::Cache::Local).to receive(:set) do |k, v, **|
+        cache_store[k] = v
+      end
+    end
+
+    def make_auth_fail_actor(**)
+      klass = Class.new do
+        include Legion::Extensions::Llm::Inventory::ScopedRefresher
+
+        def self.every_seconds = 60
+        def scope_key = { provider: :test }
+        def credential_hash = 'testhash'
+
+        attr_accessor :should_raise, :raise_error
+
+        def compute_lanes_for_scope
+          raise @raise_error if @should_raise
+
+          []
+        end
+
+        def log
+          @log ||= begin
+            l = Object.new
+            def l.warn(_msg) = nil
+            def l.info(_msg) = nil
+            def l.debug(_msg) = nil
+            l
+          end
+        end
+
+        def handle_exception(_err, **) = nil
+      end
+      actor = klass.new
+      actor.should_raise = false
+      actor.raise_error = nil
+      actor
+    end
+
+    it 'writes auth cooldown key when compute raises with HTTP 401 status' do
+      actor = make_auth_fail_actor
+      err = StandardError.new('Unauthorized')
+      err.define_singleton_method(:status_code) { 401 }
+      actor.raise_error = err
+      actor.should_raise = true
+
+      actor.tick
+
+      expect(cache_store).to have_key(cooldown_key)
+    end
+
+    it 'writes auth cooldown key when compute raises with HTTP 403 status' do
+      actor = make_auth_fail_actor
+      err = StandardError.new('Forbidden')
+      err.define_singleton_method(:http_status) { 403 }
+      actor.raise_error = err
+      actor.should_raise = true
+
+      actor.tick
+
+      expect(cache_store).to have_key(cooldown_key)
+    end
+
+    it 'writes auth cooldown key when compute raises with unauthorized message' do
+      actor = make_auth_fail_actor
+      actor.raise_error = StandardError.new('invalid_api_key: bad credentials')
+      actor.should_raise = true
+
+      actor.tick
+
+      expect(cache_store).to have_key(cooldown_key)
+    end
+
+    it 'skips compute_lanes_for_scope when cooldown key is present' do
+      actor = make_auth_fail_actor
+      actor.should_raise = false
+      cache_store[cooldown_key] = 1 # simulate active cooldown
+
+      compute_called = false
+      actor.define_singleton_method(:compute_lanes_for_scope) do
+        compute_called = true
+        []
+      end
+
+      actor.tick
+      expect(compute_called).to be false
+    end
+
+    it 'calls compute_lanes_for_scope after cooldown TTL expires' do
+      actor = make_auth_fail_actor
+      actor.should_raise = false
+      # Cooldown expired — key absent
+      cache_store.delete(cooldown_key)
+
+      compute_called = false
+      actor.define_singleton_method(:compute_lanes_for_scope) do
+        compute_called = true
+        []
+      end
+
+      actor.tick
+      expect(compute_called).to be true
+    end
+
+    it 'does NOT write cooldown key for non-auth errors' do
+      actor = make_auth_fail_actor
+      actor.raise_error = StandardError.new('connection timeout: net unreachable')
+      actor.should_raise = true
+
+      actor.tick
+
+      expect(cache_store).not_to have_key(cooldown_key)
+    end
+  end
+end

data/spec/legion/extensions/llm/provider/open_ai_compatible_spec.rb

@@ -131,7 +131,7 @@ RSpec.describe Legion::Extensions::Llm::Provider::OpenAICompatible do
     models = provider.send(:parse_list_models_response, fake_response(models_body), :compatible,
                            provider_class.capabilities)
 
-    expect(models.map(&:capabilities)).to eq([%i[streaming function_calling tools], %i[embeddings]])
+    expect(models.map(&:capabilities)).to eq([%i[streaming function_calling tools], %i[embeddings embedding]])
     expect(models.map { |model| model.modalities.to_h }).to eq([
                                                                  { input: %w[text image], output: %w[text] },
                                                                  { input: %w[text], output: %w[embeddings] }

data/spec/legion/extensions/llm/provider_spec.rb

@@ -175,6 +175,26 @@ RSpec.describe Legion::Extensions::Llm::Provider do
       expect(offering.context_window).to eq(8192)
     end
 
+    it 'publishes every discovered model before policy filtering removes blocked models' do
+      blocked_model = Legion::Extensions::Llm::Model::Info.new(
+        id: 'blocked-model',
+        provider: :contract,
+        instance: :primary,
+        capabilities: %i[completion],
+        context_length: 4096
+      )
+      registry_publisher = instance_double(Legion::Extensions::Llm::RegistryPublisher)
+      allow(registry_publisher).to receive(:publish_models_async)
+      allow(provider_class).to receive(:registry_publisher).and_return(registry_publisher)
+      allow(provider).to receive_messages(list_models: [model, blocked_model], settings: { model_blacklist: ['blocked'] })
+
+      offerings = provider.discover_offerings(live: true)
+
+      expect(offerings.map(&:model)).to eq(['test-model'])
+      expect(registry_publisher).to have_received(:publish_models_async).with([model], anything)
+      expect(registry_publisher).to have_received(:publish_models_async).with([blocked_model], anything)
+    end
+
     it 'passes live discovery filters through to list_models' do
       provider.discover_offerings(live: true, capability: :tools, instance: :primary)
 
@@ -357,6 +377,62 @@ RSpec.describe Legion::Extensions::Llm::Provider do
     end
   end
 
+  describe '#enforce_model_allowed! (dispatch compliance guard)' do
+    let(:provider_class) do
+      Class.new(described_class) do
+        attr_writer :settings
+
+        def api_base = 'https://test.invalid'
+        def settings = @settings || {}
+        def slug = :test
+        def provider_instance_id = :default
+      end
+    end
+
+    let(:provider) { provider_class.new(Legion::Extensions::Llm.config) }
+
+    context 'when a model is excluded by the whitelist' do
+      before { provider.settings = { model_whitelist: %w[haiku] } }
+
+      it 'raises ModelNotAllowedError carrying the model and provider' do
+        expect { provider.send(:enforce_model_allowed!, 'gpt-5') }
+          .to raise_error(Legion::Extensions::Llm::ModelNotAllowedError) do |error|
+            expect(error.model).to eq('gpt-5')
+            expect(error.provider).to eq(:test)
+          end
+      end
+
+      it 'permits a whitelisted model' do
+        expect { provider.send(:enforce_model_allowed!, 'claude-haiku-4-5-20251001') }.not_to raise_error
+      end
+
+      it 'fails closed in #complete before any provider call' do
+        expect { provider.complete([], tools: [], temperature: nil, model: 'gpt-5') }
+          .to raise_error(Legion::Extensions::Llm::ModelNotAllowedError)
+      end
+
+      it 'fails closed in #embed before any provider call' do
+        expect { provider.embed(text: 'hello', model: 'text-embedding-3-large') }
+          .to raise_error(Legion::Extensions::Llm::ModelNotAllowedError)
+      end
+    end
+
+    context 'when a model is excluded by the blacklist' do
+      before { provider.settings = { model_blacklist: %w[sonnet] } }
+
+      it 'fails closed in #complete for a blacklisted model' do
+        expect { provider.complete([], tools: [], temperature: nil, model: 'claude-sonnet-4-6') }
+          .to raise_error(Legion::Extensions::Llm::ModelNotAllowedError)
+      end
+    end
+
+    context 'with no policy configured' do
+      it 'does not raise for any model' do
+        expect { provider.send(:enforce_model_allowed!, 'anything-goes') }.not_to raise_error
+      end
+    end
+  end
+
   describe 'multi-host URL resolution' do
     let(:provider_class) do
       Class.new(described_class) do

data/spec/legion/extensions/llm/routing/model_offering_spec.rb

@@ -96,7 +96,8 @@ RSpec.describe Legion::Extensions::Llm::Routing::ModelOffering do
       capabilities: %i[chat function_calling]
     )
 
-    expect(legacy_tools.capabilities).to include(:function_calling, :tools)
+    expect(legacy_tools.capabilities).to include(:tools)
+    expect(legacy_tools.capabilities).not_to include(:function_calling)
     expect(legacy_tools.eligible_for?(required_capabilities: [:tools])).to be true
   end
 
@@ -236,7 +237,7 @@ RSpec.describe Legion::Extensions::Llm::Routing::ModelOffering do
 
       expect(sourced.capabilities).to include(:streaming, :tools)
       expect(sourced.capability_sources[:tools]).to eq(value: true, source: :instance_override)
-      expect(sourced.capability_sources[:embeddings]).to eq(value: false, source: :default_false)
+      expect(sourced.capability_sources[:embedding]).to eq(value: false, source: :default_false)
     end
 
     it 'includes capability_sources in to_h' do

data/spec/legion/extensions/llm/taxonomies_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/llm/taxonomies'
+
+RSpec.describe Legion::Extensions::Llm::Taxonomies do
+  it 'TIERS includes :fleet as a first-class tier' do
+    expect(described_class::TIERS).to include(:fleet)
+  end
+
+  it 'TIERS contains exactly the documented values' do
+    expect(described_class::TIERS).to contain_exactly(:direct, :local, :fleet, :cloud, :frontier)
+  end
+
+  it 'TYPES contains documented inference types' do
+    expect(described_class::TYPES).to include(:inference, :embedding)
+  end
+
+  it 'CIRCUIT_STATES contains three states' do
+    expect(described_class::CIRCUIT_STATES).to contain_exactly(:closed, :half_open, :open)
+  end
+
+  it 'all constants are frozen' do
+    expect(described_class::TIERS).to be_frozen
+    expect(described_class::TYPES).to be_frozen
+    expect(described_class::CIRCUIT_STATES).to be_frozen
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.2
 platform: ruby
 authors:
 - LegionIO
@@ -272,6 +272,7 @@ files:
 - lib/legion/extensions/llm/canonical/tool_definition.rb
 - lib/legion/extensions/llm/canonical/tool_schema.rb
 - lib/legion/extensions/llm/canonical/usage.rb
+- lib/legion/extensions/llm/capabilities.rb
 - lib/legion/extensions/llm/capability_policy.rb
 - lib/legion/extensions/llm/chat.rb
 - lib/legion/extensions/llm/chunk.rb
@@ -293,6 +294,8 @@ files:
 - lib/legion/extensions/llm/fleet/token_validator.rb
 - lib/legion/extensions/llm/fleet/worker_execution.rb
 - lib/legion/extensions/llm/image.rb
+- lib/legion/extensions/llm/inventory/capabilities.rb
+- lib/legion/extensions/llm/inventory/scoped_refresher.rb
 - lib/legion/extensions/llm/message.rb
 - lib/legion/extensions/llm/mime_type.rb
 - lib/legion/extensions/llm/model.rb
@@ -322,6 +325,7 @@ files:
 - lib/legion/extensions/llm/routing/registry_event.rb
 - lib/legion/extensions/llm/stream_accumulator.rb
 - lib/legion/extensions/llm/streaming.rb
+- lib/legion/extensions/llm/taxonomies.rb
 - lib/legion/extensions/llm/thinking.rb
 - lib/legion/extensions/llm/tokens.rb
 - lib/legion/extensions/llm/tool.rb
@@ -357,6 +361,7 @@ files:
 - spec/legion/extensions/llm/canonical/tool_definition_spec.rb
 - spec/legion/extensions/llm/canonical/tool_schema_spec.rb
 - spec/legion/extensions/llm/canonical/usage_spec.rb
+- spec/legion/extensions/llm/capabilities_spec.rb
 - spec/legion/extensions/llm/capability_policy_spec.rb
 - spec/legion/extensions/llm/configuration_spec.rb
 - spec/legion/extensions/llm/conformance/client_translator_examples.rb
@@ -398,6 +403,8 @@ files:
 - spec/legion/extensions/llm/fleet/worker_execution_spec.rb
 - spec/legion/extensions/llm/fleet_messages_spec.rb
 - spec/legion/extensions/llm/gemspec_spec.rb
+- spec/legion/extensions/llm/inventory/capabilities_spec.rb
+- spec/legion/extensions/llm/inventory/scoped_refresher_spec.rb
 - spec/legion/extensions/llm/message_spec.rb
 - spec/legion/extensions/llm/model/info_spec.rb
 - spec/legion/extensions/llm/models_spec.rb
@@ -415,6 +422,7 @@ files:
 - spec/legion/extensions/llm/routing/registry_event_spec.rb
 - spec/legion/extensions/llm/stream_accumulator_spec.rb
 - spec/legion/extensions/llm/streaming_spec.rb
+- spec/legion/extensions/llm/taxonomies_spec.rb
 - spec/legion/extensions/llm/tool_spec.rb
 - spec/legion/extensions/llm/transport/fleet_lane_spec.rb
 - spec/legion/extensions/llm/utils_spec.rb